Skip to content

Docs: lock Jim causal roadmap - #135

Merged
flyingrobots merged 8 commits into
mainfrom
design/causal-roadmap-signposts
Jun 13, 2026
Merged

flyingrobots merged 8 commits into
mainfrom
design/causal-roadmap-signposts

Conversation

@flyingrobots

Copy link
Copy Markdown
Owner

Summary

Refs #131
Refs #132
Refs #133
Refs #134

Validation

  • npx --yes markdownlint-cli2 CHANGELOG.md README.md VISION.md docs/BEARING.md docs/design/0105-vim-power-moves-causal-parity.md docs/design/0108-causal-command-provenance-surface.md
  • git diff --check
  • npm run --silent quality
  • node --test --test-concurrency=1 spec/design-cycle-policy.spec.mjs spec/vim-power-parity-matrix.spec.mjs spec/vim-power-target-usability-fixtures.spec.mjs

@flyingrobots flyingrobots added the work-in-progress Cycle or PR is intentionally in progress and not ready to merge label Jun 13, 2026
@coderabbitai

coderabbitai Bot commented Jun 13, 2026 •

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@flyingrobots, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 28 minutes and 46 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 424f972d-b3b9-4130-80d5-941718cd63d1

📥 Commits

Reviewing files that changed from the base of the PR and between 28b19eb and 877e7e0.

📒 Files selected for processing (4)
  • VISION.md
  • docs/design/0107-geordi-raytraced-title-render-pipeline.md
  • docs/design/0108-causal-command-provenance-surface.md
  • spec/causal-roadmap-signpost.spec.mjs

Walkthrough

Documentation-only PR that synchronizes Jim's product promise and causal loop messaging across README, VISION, and BEARING; advances WF-0105 to active status and positions WF-0108 as the next pinned design cycle; adds comprehensive WF-0108 design document specifying :why command surface, provenance contract, system objects, implementation slices, and acceptance criteria.

Changes

Product Roadmap and Vision Coherence

Layer / File(s) Summary
Product promise and causal loop messaging
README.md, VISION.md, docs/BEARING.md
Added the product promise ("explainable, recoverable, reviewable editing") and the signature causal loop (explain → preview → admit → recover) as unified framing across README, VISION, and BEARING.
Execution sequence and product constraints
VISION.md, docs/BEARING.md
Defined 7 ordered near-term execution goalposts, added runtime work checklist, and extended non-goals to explicitly exclude routing around Wesley, premature Continuum, and collaboration before local causal file history.
WF-0105 to active and WF-0108 as next pinned cycle
docs/design/0105-vim-power-moves-causal-parity.md, docs/BEARING.md, CHANGELOG.md
Promoted WF-0105 from draft to active status, updated narrative to identify WF-0108 as next pinned product cycle, introduced Next Cycle Anchors table (WF-0108–WF-0111), and updated CHANGELOG.
Echo History feature and implementation readiness
README.md, docs/BEARING.md
Added Echo History drawer feature description, reworked "Next implementation start" checklist with WF design doc references, refined Deferred Full Rewrite proof gates separating causal command provenance from previewable broad edits.

WF-0108 Causal Command Provenance Design Document

Layer / File(s) Summary
WF-0108 design goal, problem scope, and user experience
docs/design/0108-causal-command-provenance-surface.md (lines 1–279)
Introduced WF-0108 design goal for :why command, framed trust question after edits, and specified wide/narrow UX mockups with keyboard-first accessibility, non-color accessibility posture, and model-backed explanations.
Command event contract and runtime API specification
docs/design/0108-causal-command-provenance-surface.md (lines 280–378)
Specified JeditCommandEvent core provenance contract with phase model (raw keys → parsed syntax → resolved target → mutation vs obstruction), required JSON witness content, semantic accessibility, and localization/directionality handling.
Roadmap system objects, invariants, and design decisions
docs/design/0108-causal-command-provenance-surface.md (lines 394–545)
Defined four roadmap system objects (JeditCommandEvent, JeditBasisView, result/proposal strands, retained text material), listed linked invariants, recorded design alternatives, and selected decision to deliver :why first with trust preflight.
Implementation slices, tests, and acceptance criteria
docs/design/0108-causal-command-provenance-surface.md (lines 546–598)
Enumerated implementation Slices 0–6 with required behavior tests (provenance, rendering, dispatch, witness, obstruction), listed command assertions, and defined acceptance criteria covering trust gates, stable emission, lower-mode summary, witness parity, and validation.
Validation plan, known risks, and follow-on debt
docs/design/0108-causal-command-provenance-surface.md (lines 599–687)
Provided validation commands, playback/witness targets (jim demo.txt and jedit-command-provenance-witness.mjs), outlined known risks and mitigations, enumerated follow-on debt, and included retrospective/PR link placeholders.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

  • WF-0108: Jim Command Provenance And :why #131: This PR directly adds and references WF-0108 as a new design milestone with comprehensive specification of the Jim command provenance and :why surface, matching the design scope and objectives outlined in that issue.

Poem

The causal loop ascends through dusty pages—
explain, preview, admit, then recover once more.
WF-0105 sleeps as WF-0108 awakens,
bearing witness to commands, honest and transparent,
as Jim learns to answer: ✨ Why? ✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title 'Docs: lock Jim causal roadmap' directly reflects the primary change: pinning the Jim product roadmap and locking the causal loop documentation across multiple files.
Description check ✅ Passed The description comprehensively covers the changeset scope, detailing the product promise pinning, roadmap loop locking, WF-0108 addition, follow-on issue anchors, and documentation updates across all modified files.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 28b19eb495

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/design/0108-causal-command-provenance-surface.md
Comment thread docs/design/0108-causal-command-provenance-surface.md
Comment thread docs/design/0108-causal-command-provenance-surface.md Outdated
Comment thread docs/design/0108-causal-command-provenance-surface.md Outdated
Comment thread docs/design/0108-causal-command-provenance-surface.md

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/design/0108-causal-command-provenance-surface.md`:
- Around line 337-357: The spec lists two invalid states ("Command event claims
a mutation without a receipt posture" and "Command event claims a range without
a basis") but doesn't mandate enforcement—add explicit validation in the model
layer: implement sealed/validated constructors or factory functions for the
CommandEvent and Range types (the entities driving the Parsed→Resolved→Applied
state machine) that throw or return typed errors when a mutation lacks a
receiptPosture or when a Range lacks a basis, and add runtime guards/schema
checks (e.g., in CommandEvent.fromPayload or Range.validate) so the Slice 1
model code deterministically rejects these cases and surfaces diagnostics rather
than silently tolerating them; update the spec text to name those
constructors/validators and the error types so Slice 0 preflight can confirm
detection is possible.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: a7858819-608e-4f3b-9577-4fcbf4a4b183

📥 Commits

Reviewing files that changed from the base of the PR and between c511e2a and 28b19eb.

📒 Files selected for processing (6)
  • CHANGELOG.md
  • README.md
  • VISION.md
  • docs/BEARING.md
  • docs/design/0105-vim-power-moves-causal-parity.md
  • docs/design/0108-causal-command-provenance-surface.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)
  • GitHub Check: test / cycle-proofs
  • GitHub Check: test / misc-fast
  • GitHub Check: test / workspace-ui
  • GitHub Check: test / contract-api
  • GitHub Check: test / title-rendering
  • GitHub Check: test / echo-authority
  • GitHub Check: test / docs-release
  • GitHub Check: release-gate / jedit-echo
🧰 Additional context used
📓 Path-based instructions (3)
**

⚙️ CodeRabbit configuration file

**: # jedit Agent Contract

Git Safety

  • Never amend commits. Make a new commit.
  • Never rebase unless the user explicitly approves it after a concrete explanation.
  • Never force git operations.
  • Draft pull requests are allowed only for design-cycle kickoff or active cycle
    work. Convert them to ready before merge. If draft PRs are unavailable, use a
    normal PR with the work-in-progress label.

Quality Doctrine

These are hard repo rules, not suggestions:

  1. No any.
  2. No unknown.
  3. Hexagonal architecture, strict.
  4. Encoding and decoding happen only at the boundary, inside a port/adapter.
  5. One file equals one runtime truth.
  6. Runtime truth beats compile-time theater.
  7. No ad hoc string comparison in core logic. Prefer instanceof, numeric tags, symbols, or explicit runtime objects.
  8. No magic strings.
  9. No magic numbers.
  10. SOLID.
  11. DRY.
  12. DI.
  13. Red to green.
  14. Tests are spec.
  15. Agent-first.
  16. No file over 500 lines of code.

Structure

  • ARCHITECTURE.md is the canonical repo architecture doctrine.
  • docs/BEARING.md records the current execution gravity.
  • docs/method/process.md is the canonical cycle workflow.
  • docs/method/roadmap-planning.md defines release-gate, roadmap, slice, and
    proof policy for multi-cycle planning.
  • docs/design/TEMPLATE.md is the required template for full cycle designs.
  • docs/design/0034-design-cycle-template-and-lifecycle.md records the policy
    decision that made executable design docs official.
  • docs/design/0024-jedit-powered-by-echo-release-gate.md is the completed
    baseline plan for the first thirty slices proving jedit has an installed
    package/evidence path while Echo remains generic.
  • docs/design/0025-echo-application-hosting-pattern.md is the completed
    post-release-pressure ten-slice plan for proving the reusable Echo
    application-hosting pattern before applying it to Graft, Think, or other apps.
  • docs/design/0026-echo-hosting-hardening-first-twenty.md is th...

Files:

  • CHANGELOG.md
  • VISION.md
  • docs/design/0105-vim-power-moves-causal-parity.md
  • README.md
  • docs/design/0108-causal-command-provenance-surface.md
  • docs/BEARING.md
docs/design/*.md

📄 CodeRabbit inference engine (AGENTS.md)

Use the template from docs/design/TEMPLATE.md for all full cycle designs

Files:

  • docs/design/0105-vim-power-moves-causal-parity.md
  • docs/design/0108-causal-command-provenance-surface.md
docs/BEARING.md

📄 CodeRabbit inference engine (AGENTS.md)

Record current execution gravity in docs/BEARING.md

Files:

  • docs/BEARING.md
🪛 LanguageTool
VISION.md

[style] ~249-~249: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...t make Echo know jedit product nouns. - Do not make jedit know Echo substrate coor...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[style] ~250-~250: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...edit know Echo substrate coordinates. - Do not publish packages just because the w...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[style] ~251-~251: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ust because the witness ritual works. - Do not prepare a public editor release unt...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

docs/design/0108-causal-command-provenance-surface.md

[style] ~190-~190: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... Full Vim parity. - Full visual mode. - Full macro replay. - Full causal undo. - Dur...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[style] ~191-~191: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ull visual mode. - Full macro replay. - Full causal undo. - Durable replay completio...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[grammar] ~282-~282: Ensure spelling is correct
Context: .... ## Runtime / API Contract Contract: JeditCommandEvent. Initial event shape: ```text JeditComma...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)


[style] ~385-~385: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...mmand keys ran? - What syntax parsed? - What mode was active? - What basis or readin...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[style] ~386-~386: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...yntax parsed? - What mode was active? - What basis or reading was used? - What targe...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[style] ~387-~387: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ve? - What basis or reading was used? - What target resolved? - What range or range ...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[style] ~388-~388: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ing was used? - What target resolved? - What range or range set changed? - What regi...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[style] ~389-~389: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...d? - What range or range set changed? - What register changed? - What receipt/result...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[style] ~390-~390: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...set changed? - What register changed? - What receipt/result reading was available? -...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[style] ~391-~391: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...receipt/result reading was available? - What obstruction occurred? - What short huma...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[style] ~392-~392: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ailable? - What obstruction occurred? - What short human explanation did Jim show? ...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🔇 Additional comments (19)
VISION.md (1)

245-255: 💤 Low value

Non-goals list style: governance doctrine or prose repetition?

Lines 248–255 establish constraints as a "Do not X" governance list, which is valid doctrine style. However, LanguageTool flagged lines 249–251 for three successive identical sentence structures:

  • "Do not make Echo know jedit product nouns."
  • "Do not make jedit know Echo substrate coordinates."
  • "Do not publish packages just because the witness ritual works."

This repetition is intentional if the list is pure governance constraints (all negations). If this is design prose meant to flow, the three-in-a-row structure becomes awkward.

Recommendation: Keep this list as-is if it's intended as a non-negotiable constraint checklist (analogous to the "Non-Negotiables" section at the bottom of BEARING.md). If it's meant as flowing prose, consider restructuring one or two items to break the repetition while preserving the "Do not" constraint signal.

Source: Linters/SAST tools

docs/BEARING.md (2)

173-174: ⚡ Quick win

Deferred rewrite bullets now explicitly separate command-provenance from broad-edit proof gates.

Splitting the single "causal or transactional edit operations" bullet into two:

  • "causal command provenance beyond the landed core operators"
  • "previewable broad edits"

…clarifies that WF-0108 (command provenance) and WF-0110 (search/substitute strand preview) are distinct proof requirements for the full rewrite decision. This reduces ambiguity about what proof is needed before the rewrite starts.


141-148: Next Cycle Anchors table: link consistency is solid; issue URL liveness still needs GitHub check.

  • docs/BEARING.md’s Next Cycle Anchors URLs use #131/#132/#133/#134, and those same issue links also appear in docs/design/0108-causal-command-provenance-surface.md for the corresponding WF cycles.
  • Public web lookup doesn’t show these issue numbers indexed for flyingrobots/jedit, so the “URL resolves to an actual issue” part can’t be trusted without checking GitHub directly (private/unindexed issues are plausible).

WIP: docs/BEARING.md issue URL liveness check

  • Confirm each linked GitHub issue exists/resolves in the repo’s tracker at merge time
  • If issues are intentionally private/internal, switch links to the agreed internal reference format

0% (0/0 slices)
WIP: docs/BEARING.md issue URL liveness check

  • Next Cycle Anchors link liveness

🙈 OFF-ROADMAP

docs/design/0105-vim-power-moves-causal-parity.md (1)

34-40: ⚡ Quick win

Clean status transition and narrative reframing: WF-0105 from sole signpost to substrate roadmap.

The status change from draft to active (line 6, date 2026-06-13) combined with the narrative update explicitly repositions WF-0105:

  • No longer the only active product signpost
  • Remains the broad Vim/Jim power-move substrate
  • WF-0108 is now the next pinned cycle
  • Future WF-0105 slices chosen by provenance/preview/replay/trust criteria (aligned with Jim's product promise)

This is disciplined roadmap doctrine. The subordination is clear without erasing WF-0105's continued role.

CHANGELOG.md (1)

5-7: 💤 Low value

Changelog entry: concise and stakeholder-focused, but missing the product promise.

The Unreleased entry captures the roadmap repin (signature loop + WF-0108 + release-planning shift) but omits two important coordination facts:

  • The product promise ("explainable, recoverable, reviewable") is now the north star for all downstream decisions.
  • WF-0105 transitioned from draft to active (stakeholders may expect this to be called out).

Recommendation (low priority): Consider expanding the entry to include the product promise and WF-0105 status change, since this PR establishes both. Current wording focuses on roadmap structure (the loop and next cycle) rather than product doctrine (the promise and execution ladder). A two-sentence entry could cover both:

"Pinned Jim's product promise (explainable, recoverable, reviewable) and established the signature causal loop (explain -> preview -> admit -> recover) as the roadmap ordering mechanism. Promoted WF-0105 to active status and added WF-0108 for Jim Command Provenance And :why as the next pinned product cycle."

But current wording is acceptable as-is if the changelog prioritizes external roadmap visibility over internal promise doctrine.

README.md (1)

207-245: Product ladder names match VISION.md and docs/BEARING.md (items 1–7) with no cross-doc drift.

The 7 active product ladder goalpost titles appear in VISION.md “## Execution sequence” and docs/BEARING.md with the same names and ordering, and README’s “Next implementation start” aligns with BEARING’s immediate ordering and deferred-rewrite guidance.

docs/design/0108-causal-command-provenance-surface.md (13)

1-11: LGTM on front matter and issue linkage.

Front matter is complete and correct; issue #131 is properly cited. ✓


19-98: Product roadmap lock, decision summary, and version ladder are architecturally sound.

The product promise (explainable, recoverable, reviewable) and signature loop (explain → preview → admit → recover) are clear and grounded. The version ladder correctly disclaims advisory-only status (line 84), and the command grammar (:why, :preview, :admit, :history, :yankfrom, :explain) is well-motivated and free of magic strings. Goalpost ordering defers full Vim parity and agent autonomy until causality is proven. ✓


100-166: Sponsored human, sponsored agent, hill, and current truth are precisely scoped.

Sponsored human wants trust and repeatability (lines 100-105); sponsored agent wants structured JSON facts (107-112). The hill (line 114-118) is narrow: explain the last edit through :why and JSON witness, without terminal scraping. Current truth section anchors the design in existing substrate (Echo session flow, Vim runtime, search/motion facts, incomplete undo). References to prior design anchors (WF-0105, WF-0106, Echo History, causal event model, text-edit algebra) ground the work. ✓


168-181: Scope is laser-focused and non-goals are honest.

In scope: trust preflight, JeditCommandEvent model, provenance for five commands (ciw/dw/d%/gUap/n|N), lower-mode summary, :why dispatch, JSON witness, typed obstruction. Out of scope: public release, jim alias, full Vim parity, visual mode, macros, undo, replay, timeline, AI, plugins, Git, title rendering. This is disciplined boundary-setting. ✓


199-277: UX flow, mockups, and accessibility posture are well-articulated.

The user journey (lines 214-226) traces raw keys → parsed syntax → resolved target → mutation/obstruction → receipt/reading → summary → :why detail → JSON witness. This is honest to the phase model and event lifecycle. Wide and narrow terminal mockups (lines 228-268) show the principle: lower-mode summary names the last meaningful command; :why detail command expands it. Accessibility posture (lines 273-278) mandates model facts independent of color/layout/geometry; no visual-only explanations. Keyboard-first interaction required. ✓


280-336: Runtime/API contract and lower modes are grounded in existing codebase patterns.

The JeditCommandEvent core shape (lines 287-304) itemizes eventId, keys, command, mode, operator, motionOrTextObject, count, register, basisReadingId, targetKind, rangeSet, registerEffect, receiptId, resultReadingId, obstruction, summary. This is architecturally sound: command-owned fields (keys, command, mode, operator, motion, count, register) are joined with Echo-owned fields (basisReadingId, receiptId, resultReadingId) and obstruction facts. The three-phase model (lines 307-314: raw keys → parsed syntax → resolved target → mutation vs obstruction) aligns with existing applyResolvedMotion obstruction checks in vim-command-executor.ts (context snippet 1). Lower-mode requirements (lines 321-335) are explicit: JSON witness, no-color summary, narrow summary, honest posture when evidence is unavailable, keyboard access. ✓

Cross-codebase alignment: The proposed witness posture (JSON with command facts for agent assertion) mirrors the existing ProductionTextSessionWitnessReport pattern (context snippet 2: applied vs obstructed with status/stage/issue). Design correctly positions command provenance as a Jim-owned layer over Echo's witness layer. ✓


337-392: Data/state model and agent inspectability posture are rigorous.

The state machine (lines 348-357) traces Parsed → Resolved → Applied/Obstructed → Summarized → Explained. Invalid-state invariant is explicit (line 343): "Command event claims a mutation without a receipt posture, or claims a range without a basis." Source of truth is Echo readings/receipts plus jedit-owned syntax/resolution state; derived state is lower-mode summary and :why detail. Reset behavior: new meaningful command supersedes prior summary. Determinism is declared (line 346).

Agent inspectability checklist (lines 383-392) enumerates nine explicit facts: command keys, parsed syntax, mode, basis, resolved target, range/range-set, register change, receipt/result posture, obstruction reason. This is comprehensive and testable. ✓

Minor style note: LanguageTool flags the bulleted "What" question repetition (lines 383-392) as word-repeat. This is intentional parallelism for specification clarity and is acceptable. No action needed.


394-495: Roadmap system objects and linked invariants are well-stratified.

Four systems are cleanly separated:

  • System A (Command Provenance): Enables :why, :explain, register provenance, repeat explanation, evidence lens, agent edit explanation. Core: JeditCommandEvent. ✓
  • System B (Basis-Bound Views): Enables historical preview, time-travel yank, stale diagnostics, search results, panes. Core: JeditBasisView with basisId/currentHeadId/viewPosture/sourceEvidence/readBudget/returnCommand. Product rule (line 437-440) is critical: "Viewing a historical or proposal basis must never mutate current head unless an explicit admission command runs." ✓
  • System C (Result Sets / Proposal Strands): Enables search results, substitute preview, global preview, formatter preview, agent proposals, admit-selected, macro dry-run. Cores: JeditResultSet, JeditProposalStrand, JeditAdmissionSelection. ✓
  • System D (Retained Material Provenance): Enables time-travel yank, register provenance, undo fragments, historical paste, macro replay. Core: JeditRetainedTextMaterial with materialRef/digest/sourceBasis/sourceRange/producingEvent/retentionPosture. Constraint (line 483): "Missing retention is an obstruction, not a fallback invitation." ✓

Linked invariants (lines 485-495) are well-chosen: tests are spec, runtime truth > compile-time theater, design becomes repo truth, files/previews are projections, Echo authority is external, unsupported work is final, retry is explicit input, semantic distinction between buffers/panes/panels/lenses, main surface stays quiet. These are architectural guardrails. ✓


497-545: Design alternatives are candid; Option C decision is justified.

Option A (full timeline first): Rejected as too large, spectacle-risk, hard to keep honest before historical projection/durable replay. Option B (JSON-only): Rejected as invisible to users, leaves Jim's differentiator hidden. Option C (command provenance + :why first): Chosen as narrow enough to land, turns existing Vim/Echo/receipt work into product shape, shared facts through different projections, foundation for future systems. Acknowledged cons: discipline needed to avoid debug-spew, trust preflight required. This is thoughtful and honest risk-taking. ✓


546-577: Implementation slices are correct-order and tests-first discipline is present.

Slice 0 (preflight) comes first, blocking implementation if gaps are found (line 650-651 risk mitigation). Slices 1-6 then proceed: model definition (Slice 1), provenance emission (Slice 2), lower-mode rendering (Slice 3), :why dispatch (Slice 4), JSON witness (Slice 5), obstruction posture (Slice 6).

Tests-to-write-first section is explicit:

  • Behavior tests: trust preflight, command event model stability, runtime vs provenance parity, rendering at wide/narrow, :why detail, JSON witness, obstruction. ✓
  • Command assertions: ciw/dw/d%/gUap/n|N must report text-object/target/range/register/receipt/result facts. :why with no event reports calm obstruction. ✓

Documentation/process test (line 581) verifies roadmap/signpost docs link WF-0108 as active. ✓

Minor style note: LanguageTool flags "Full visual mode / Full macro replay / Full causal undo" repetition in non-goals as word-repeat. This is intentional parallelism in a bulleted list and is acceptable.


583-609: Acceptance criteria and validation plan are complete and executable.

Acceptance criteria (lines 585-597):

  • Preflight names blockers ✓
  • ≥5 commands emit stable facts ✓
  • Lower-mode summary is informative without overwhelming ✓
  • :why exposes structured facts ✓
  • JSON witness matches :why facts ✓
  • Obstruction/unavailable/stale cases return typed facts ✓
  • CI and local validation green ✓

Validation plan (lines 603-608) specifies exact commands:

npm run build
node --test --test-concurrency=1 spec/<focused-command-provenance>.spec.mjs
npm run quality
npx --yes markdownlint-cli2 docs/BEARING.md README.md VISION.md docs/design/0108-causal-command-provenance-surface.md
git diff --check

This is executable and matches the PR validation already run (per PR objectives). ✓


611-652: Playback/witness targets and risks/mitigations are grounded in current reality.

Playback targets (lines 613-634) correctly distinguish aspirational (:jim demo.txt once alias earned) from current (:npm run dev -- demo.txt). Witness script name jedit-command-provenance-witness.mjs is labeled "target, not current runtime truth" (line 634). ✓

Risks (lines 638-652):

  • Provenance noise violating quiet-editor invariant → mitigation: compact summaries, details behind explicit command. ✓
  • Event facts overclaiming Echo evidence → mitigation: separate receipt/result from syntax facts. ✓
  • First commands skip user-facing trust gaps → mitigation: run Slice 0 preflight first. ✓
  • Search/motion evidence may not cover / and ? → mitigation: move into trust gate if blocking demo. ✓

These are known, concrete risks with proportionate mitigations. No hand-waving.


654-688: Follow-on debt and retrospective placeholders are well-organized.

Follow-on issues anchor the roadmap:

  • WF-0109 Historical Basis Preview (#134) ✓
  • WF-0110 Search Sets And Substitute Strand Preview (#132) ✓
  • WF-0111 Historical Yank And Register Provenance (#133) ✓

Additional debt items: macro dry-run, causal marks, :explain range, register detail, dot-repeat explanation, stale diagnostics, agent proposals. All are credible follow-on work, not hidden in the cycle. ✓

Retrospective placeholder (lines 669-687) is correctly formatted for post-implementation fill-in. PR link placeholder awaits merge. ✓

Comment thread docs/design/0108-causal-command-provenance-surface.md
@flyingrobots

Copy link
Copy Markdown
Owner Author

Self-Code Review

@codex please sanity-check these findings before this PR is treated as clean.

Severity File:Line Type Issue Recommended mitigation prompt
P3 VISION.md:45 Documentation governance / source-of-truth drift The canonical product vision now makes current-market claims about Neovim, modern modal editors, and agentic editors owning specific lanes without citations or a dating/expiry posture. That is volatile strategy analysis living in a durable vision document, so it can become stale while still looking like repo truth. "Update VISION.md to remove or quarantine uncited competitor-market claims. Rephrase the passage as Jim-owned strategy without asserting current external market ownership, or move the market analysis into a dated design rationale with explicit citations and review cadence."
P5 docs/design/0108-causal-command-provenance-surface.md:239 Markdown style / fixed-width rendering The wide terminal mockup has inconsistent row widths: the border is 100 chars, most body rows are 100 chars, src/example.ts is 101 chars, and the :why row is 99 chars. In a plain terminal or monospaced review pane the box is visibly ragged. "Normalize the wide UI mockup to a single fixed width by padding or shortening rows 233-240, then rerun markdownlint and git diff --check."

Review Notes

  • Pre-review gate passed: git status --porcelain was clean before review, then git fetch origin completed.
  • Diff reviewed: origin/main...HEAD.
  • CI/check state observed after review: all GitHub checks passing, including CodeRabbit, quality, static/build, release-gate, and test suites.
  • Existing PR review state is still CHANGES_REQUESTED from CodeRabbit, so merge eligibility remains blocked until that review posture is resolved or superseded.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Swish!

Reviewed commit: 28b19eb495

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@flyingrobots flyingrobots removed the work-in-progress Cycle or PR is intentionally in progress and not ready to merge label Jun 13, 2026
@flyingrobots

Copy link
Copy Markdown
Owner Author

Code Lawyer Activity Summary

All discovered PR review threads were processed one issue at a time with a RED regression, GREEN fix, VERIFY pass, and one commit per issue. No additional self-discovered issues remained after the post-fix self-audit.

# Severity Source File Commit Outcome
1 P2 PR docs/design/0108-causal-command-provenance-surface.md 3f60385 Resolved WF-0108/WF-0109 collision by moving title-render reserved follow-up arcs to WF-0112/WF-0113 and adding a regression spec.
2 P2 PR docs/design/0108-causal-command-provenance-surface.md d1950d6 Added fully qualified merge-target evidence links for Current Truth claims and regression coverage.
3 P2 PR docs/design/0108-causal-command-provenance-surface.md 0eb3bb2 Replaced non-runnable focused-test placeholder with concrete shell commands and regression coverage.
4 P2 PR docs/design/0108-causal-command-provenance-surface.md 3e4d809 Created issue anchors for all remaining deferred debt and linked every debt bullet.
5 P2 PR docs/design/0108-causal-command-provenance-surface.md 1fed851 Added <Esc> before :why in target playback and regression coverage.
6 P5 PR docs/design/0108-causal-command-provenance-surface.md 877e7e0 Specified command-event factory validation and typed rejection posture for invalid event states.

Verification

  • npm run check passed: build, full Node suite, and quality gate.
  • Full Node suite: 934 tests, 925 passed, 9 skipped, 0 failed.
  • npx --yes markdownlint-cli2 CHANGELOG.md README.md VISION.md docs/BEARING.md docs/design/0105-vim-power-moves-causal-parity.md docs/design/0107-geordi-raytraced-title-render-pipeline.md docs/design/0108-causal-command-provenance-surface.md passed.
  • git diff --check passed.
  • Resolved all six discovered review threads via GraphQL.
  • Removed the work-in-progress label.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant