refactor(spec): polish cluster — 4 follow-on beads#1032
Merged
Conversation
added 4 commits
May 14, 2026 15:26
…as (rf2-gffca) Spec-Schemas.md L280 referenced a single rejection key `:rf.error/flow-shape-invalid` that does not exist in the implementation or in 009. The 009 Error contract documents four distinct keys covering the failure modes (`flow-missing-id` / `flow-bad-inputs` / `flow-bad-output` / `flow-bad-path`). Replace the stale single-key reference with the four-key family and a direct pointer to 009 §Error contract (where the per-key recovery posture, tags, and reason are owned). The pointer to 013 §The registration shape is retained as a 'see also'.
…(rf2-fhg5l) Causa is the structural successor to re-frame-10x per `tools/causa/spec/DESIGN-RATIONALE.md` Lock #1 (the standalone 10x port was redirected into Causa per rf2-jt6t / #556). The Story spec text still referenced "re-frame-10x" as the live artefact name and shipped a canonical embed example whose `:render` symbol pointed at the never-published `:re-frame-10x.epoch-panel/view` keyword instead of Causa's actual `:day8.re-frame2-causa.panels.time-travel/time-travel-view`. Rename across `tools/story/spec/`: - Sweep "re-frame-10x" → "Causa" / "Causa's" in prose; keep the "structural successor to re-frame-10x" framing once per file so the rename lineage is discoverable. - Update the canonical embed example: the registration id moves from `:rf.story/10x-epoch` to `:rf.story/causa-epoch`, the panel title from "Epochs (10x)" to "Epochs (Causa)", and the late-bind `:render` keyword to the real `:day8.re-frame2-causa.panels.time-travel/time-travel-view` symbol Causa actually ships (per `tools/causa/spec/API.md` §Panel namespaces). - Rename anchors that named the rename target: `§10x-embed` → `§causa-embed`; `§10x-embed-inert-without-causa` → `§causa-embed-inert-without-causa`. No external links to the old anchors existed. - Update README index entry, file-tree comments, ship-list rows, and "deliberately doesn't ship" rejection entries in lockstep. Bring the corresponding Story canonical-embed test (`tools/story/test/re_frame/story_test.clj`) into lockstep with the new id and `:render` keyword so the test asserts the shape the spec actually documents. Findings/ docs (historical research artefacts) and `tools/README.md` already document the rename narratively — left untouched. mkdocs warning count unchanged (119 → 119); `check_doc_slugs.py` clean.
…jjw1) Stand up the per-tool spec scaffold for the agent face of Machines-Viz, closing the forward-reference from `tools/README.md` (line 206 — "likely separate MCP surface for machine viz, mirroring the causa / causa-mcp split. Confirmed separation pending the first cut") and the multiple cross-spec pointers in `tools/story-mcp/` and `tools/story/spec/` to `tools/machines-viz-mcp/` as a peer of `tools/machines-viz/`. The vision doc pins the direction-setting calls: - **Separate jar.** Machines-Viz-MCP ships as `day8/re-frame2-machines-viz-mcp` separate from `day8/re-frame2-machines-viz` — mirroring the causa / causa-mcp and story / story-mcp splits so the MCP server can be loaded without dragging the React / charting runtime into the agent's classpath. - **MCP-over-stdio for machines-viz queries.** Node-side stdio JSON-RPC server compiled via shadow-cljs; same `@modelcontextprotocol/sdk` + bencode-pinned nREPL + port- discovery walk + degraded-boot policy as pair2-mcp / causa-mcp. - **Share-URL encoding parity.** The MCP wraps the canonical `machines-viz/encode-share-url` codec rather than re- implementing it — single source of truth in `tools/machines-viz/spec/API.md`. - **Read-only posture.** No `edit-machine` tool; same observation-only stance Machines-Viz-the-component takes. - **No session export.** Inherits Causa Lock #4 via Machines-Viz — share-URL serialises topology + a single snapshot, never a trace stream / epoch buffer / app-db slice. The catalogue sketch (list + fetch + encode share-URL + export SVG/PNG + streaming subscribe + meta) is load-bearing for the separation decision and consumer planning, not the final tool catalogue — that lands in `003-Tool-Catalogue.md` when impl begins (per the four-file shape pair2-mcp / causa-mcp grow into). mkdocs warning count unchanged (119 → 119); `check_doc_slugs.py` clean.
…-0m7p9)
`tools/story/spec/004-Assertions.md` L23 and `API.md` L114 both
documented `:rf.assert/effect-emitted` with the parenthetical
"(optional pred)" annotation, but never pinned what shape `pred`
takes. The implementation at
`tools/story/src/re_frame/story/assertions.cljc:385`
(`evaluate-effect-emitted`) makes the contract concrete: `pred` is
a unary fn over the fx-id keyword, exception-safe (throws default to
false).
Lift that contract into the normative spec:
- Replace the bracket-with-parenthetical "`[fx-id]` (optional
`pred`)" annotation with two explicit legal shapes —
`[fx-id]` and `[fx-id pred]` — in both the 004-Assertions.md
table and the API.md table.
- Add a new `004-Assertions.md` §`:rf.assert/effect-emitted`
payload shape that pins:
- The two legal payload shapes and their pass conditions.
- The pred's arity (unary) and argument (the fx-id keyword that
matched, **not** the fx-args map).
- The exception-safe failure mode (exceptions count as false; the
assertion records as failing rather than propagating).
- The rationale for not threading fx-args — preserving arg-level
granularity would require a parallel accumulator on the trace
bus and was out of scope for v1.
- The recommended composition pattern for argument-level checks
(`:rf.assert/effect-emitted` for set membership +
`:rf.assert/path-equals` against the slot the fx writes
through).
- Cross-link API.md back to the new payload-shape subsection so
readers landing on the consolidated public-surface doc reach the
detailed contract in one click.
mkdocs warning count unchanged (119 → 119); `check_doc_slugs.py`
clean.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Batched four single-file spec-polish beads on disjoint surfaces, respecting the dispatch plan's hot-zone exclusions (spec/005, spec/API, spec/Conventions, spec/009, spec/010 untouched).
spec/Spec-Schemas.md: replace stale single-key:rf.error/flow-shape-invalidreference with the four-key family that 009 actually documents (flow-missing-id/flow-bad-inputs/flow-bad-output/flow-bad-path).tools/story/spec/*: retire stalere-frame-10xprose in favour of Causa (the structural successor per Causa Lock Rename public namespace re-frame-2.* -> re-frame.* (rf2-7j0q) #1). Renames the canonical embed example's id (:rf.story/10x-epoch→:rf.story/causa-epoch), points the:renderkeyword at the real:day8.re-frame2-causa.panels.time-travel/time-travel-viewsymbol Causa ships, renames§10x-embed/§10x-embed-inert-without-causaanchors, brings the test into lockstep.tools/machines-viz-mcp/spec/000-Vision.mdclosing the forward-references fromtools/README.mdand the story-mcp / story specs; pins the direction-setting calls (separate jar, MCP-over-stdio, share-URL parity, read-only, no session export).tools/story/spec/004-Assertions.md+API.md: pin the:rf.assert/effect-emittedpred slot — unary fn over the fx-id keyword (not fx-args), exception-safe (throws default to false). Adds the§:rf.assert/effect-emitted payload shapesubsection with the rationale and composition pattern for arg-level checks.Deferred (per dispatch rules):
rf2-lb0mx— touches spec/009 + spec/010 (shared-vocab batch territory).rf2-ocp7a,rf2-9mdst— spec/005-StateMachines.md (excluded; just batched in refactor(spec/005): polish cluster — 4 follow-on beads #1028).rf2-cl8me— spec/002-Frames.md (hot-zone); P4 v1.1-design-pass tracker; no urgent edit.rf2-fa19u— umbrella tracker awaiting fixtures landing.rf2-mdoqh— closed as superseded: Causa-MCP Lock test: schema integration coverage (rf2-dznb) #12 (rf2-3we2k, 2026-05-14) reconciled the count back to 18 withlist-subscriptionsas the eighteenth tool;tools/causa/spec/010-MCP-Server.mdis internally consistent.Hot files touched: none (deliberately disjoint from the documented hot-zone list).
LoC delta: +310 / -75 across 11 files (the +193 stub vision doc dominates; the four spec edits are surgical).
Test plan
python scripts/check_doc_slugs.pyexit 0python -m mkdocs buildwarnings unchanged from main (119 → 119):rendersymbol and id.