docs: Phase 3 decisions — the editor on its own page, containers planned in the pass, the tool node Tsumugi's, grants with Phase 4 (slice 1) #99
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "docs/phase-3-plan"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Phase 3's first slice: the decisions Phase 3 builds on, written into the ADR passages they bind, and the plan's Phase 3 section rewritten as a slice list. Docs only.
The owner's decisions (2026-10-10)
toolnode ships with the manuscript tools only. The document tools,ask_userand every grant come with Phase 4's agent mode, in the same catalog. Until then the property panel shows no grants.instructioninput. A graph without one starts as soon as it is chosen.graphs/{id}, outside any story. Graph undo covers editor edits. Library actions keep their own Undo and Restore.contextnode's default.The design decisions
map,loop,subgraph) expand and collect as core transitions in the scheduler's pass.inputandoutputnodes.toolnode is Tsumugi's and takes no concurrency slot.EntityKinds.Graph.committhe host adds at a run's start, for a top-levelllmonly.The plan
Review before opening
Two workflow passes ran before this PR was opened. The counts below come from the saved review JSON.
🤖 Generated with Claude Code
The decisions Phase 3 builds on, recorded where they bind. They came from a research pass over the docs and the code, a slice plan reviewed by a workflow (87 points, all taken), and the owner's answers on 2026-10-10. The owner's decisions: - **Tools.** The tool node ships with the manuscript tools only; the document tools, ask_user and every grant come with Phase 4's agent mode, in the same catalog. The panel shows no grants until then. (ADR 0013, 0014, 0017, 0018, 0019, 0021, 0028, AGENTS.md, REQUIREMENTS, PROJECT_PLAN's Phase 4, the graph-editor story) - **Run ▾ another graph** beside the Run button runs any other story graph once on the chapter, without making it active. Summarize chapter starts there. (ADR 0012, 0023, ARCHITECTURE, REQUIREMENTS, graph-library and story-workspace stories) - **Selection runs.** - Continue from here inserts after the paragraph the selection ends in. - A graph asks for an instruction only when it has a top-level `instruction` input; one without starts when chosen. - The menu key and Shift+F10 keep opening the selection menu; Shift+right-click opens the browser's. - A changed selection's text appends at the end of the chapter from Commit this text, its button saying so. - ADR 0030 is accepted. (ADR 0023, 0030, the ADR index, REQUIREMENTS, the story-workspace story) - **A failed map iteration** lets the others go on; the map fails at the end, naming it, and a retry re-runs only it. Parallel streams live on the run's page and its graph view; the chapter shows nothing until a commit. (ADR 0016, 0024, 0027, the story-workspace story) - **The editor** is its own page, `graphs/{id}`, outside any story; a story's link carries the story for the @ picker. Graph undo covers editor edits; library actions keep their own Undo and Restore. (ADR 0017, 0021, 0022, 0027, REQUIREMENTS, graph-editor and graph-library stories) - **The Settings safety margin** becomes a context node's default. (ADR 0017, settings story) The design decisions: - **Containers** plan and collect as core transitions in the scheduler's pass: no attempts, no executor, no host roots. A container is running while its expansion — a new member of its node run — is set, and the orphan sweep leaves it alone. It settles once nothing in its body can go on. A failed row gives up its innermost iteration. Wiring crosses a container's boundary only through its declared sockets and its body's input and output nodes; a context feeding a writer sits in the same body. A loop stays a DAG, its values carried by the body's output nodes; a map's results are each iteration's output object. A map runs 3 iterations at a time by default, a loop 5 iterations at most. (ADR 0014, 0015, 0016, 0017, 0021, AGENTS.md, the engine README's V16) - **A subgraph** is inlined at start with its node ids prefixed by the subgraph node's. Its interface, the referenced graph's input and output nodes, is copied into the node's config and checked across the library on every edit and at start; a changed one offers an update. (ADR 0014, 0015, 0021, 0023) - **Branch cases and loop exits** are expressions over their scope's roots that must yield a bool; a loop's exit reads only `loop.*`. A commit credits the model step behind a reshaping node. Node ids follow a pattern that is no resume code; an import and a one-off migration of the library mint the ids that break it anew. (ADR 0015, 0023, 0025) - **The tool contract** lives in the core; the `tool` node is Tsumugi's and takes no concurrency slot. Its parameters are copied into its config; a parameter the tool declares host-bound takes the run's target chapter. (ADR 0014, 0015, 0016, 0019, 0025, ARCHITECTURE, PROJECT_PLAN's tree) - **The graph journal** holds editor edits; library actions are announced as `EntityKinds.Graph` without a journal row, the announcements landing before the journal. (ADR 0022, REQUIREMENTS) - **The canvas contract** grows once: merge sinks, containers, default configs and a projection with resolved sockets, summaries and findings; the status and text calls carry the iteration path. Node types' names and descriptions come from the host. (ADR 0021, 0025) - **The run's page** gets live text per row, iterations grouped and named in plain words, a graph view with the execution overlay, and the chapter's preview only for a stream bound for an append into it. (ADR 0024, 0027, REQUIREMENTS) - **The auto-commit** is a visible commit the host adds at start, for a top-level llm only. A segment's provenance gains the iteration path. (ADR 0012, 0014) - **The Help page** lists the graph editor's keys. (ADR 0032) The plan: - PROJECT_PLAN's Phase 3 section is rewritten with slices 1 to 38, 43 with the lettered splits, in build order: each names the projects it changes, what it waits for and what it seeds; the slices with a migration land one after another; the critical path follows. Slice 1 is this one, ticked here. - M4's tick is narrowed to the gutter: the working state never landed, and slice 7 builds it. M5b points at slices 5 to 9. - Phase 4 gains the grants, Kagaku.UI's checkbox dropdown first. - AGENTS.md's seed contract lists what Phase 3 seeds, each item with its slice. Left open, in no slice, as the plan says: a History mark while a run's cost is still being looked up, and Alt+Shift+P on a Mac. The two [Later] inspector lines stay in their story. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>Summary
Summary
Coverage
Kagaku.Flow - 99.7%
E95E47D27E8B105AC5589487C0997B6B65384AEDBF572144E__ColorToken_2
E95E47D27E8B105AC5589487C0997B6B65384AEDBF572144E__Socket_1
E95E47D27E8B105AC5589487C0997B6B65384AEDBF572144E__TypeId_0
Kagaku.Flow.OpenRouter - 100%
Kagaku.Flow.Testing - 100%
Tsumugi.BlazorAdapter - 97.8%
Tsumugi.Domain - 96.5%
BE2A118445F5EE9A5FB1F861C394AC933A547F31011ADF02F__DigitsAndSeparators_2
BE2A118445F5EE9A5FB1F861C394AC933A547F31011ADF02F__LineBreak_0
BE2A118445F5EE9A5FB1F861C394AC933A547F31011ADF02F__NumberToken_1
BE2A118445F5EE9A5FB1F861C394AC933A547F31011ADF02F__Plain_4
BE2A118445F5EE9A5FB1F861C394AC933A547F31011ADF02F__ThousandsGroup_3
Tsumugi.Infrastructure - 98.9%
A55E0373ED22DC58420DBB40F103A46B68DC4D9CE5A49E00B__Pattern_0
on
tion
n
uration
n
Tsumugi.Kernel - 90.9%
Tsumugi.Server - 99.6%
Tsumugi.UseCases - 95.4%
663A4576626E1322FB9C6CE472CAC0A2D2F3DEFF8CB40D9F7__AttemptCount_1
663A4576626E1322FB9C6CE472CAC0A2D2F3DEFF8CB40D9F7__HexColour_2
663A4576626E1322FB9C6CE472CAC0A2D2F3DEFF8CB40D9F7__LineBreaks_0
663A4576626E1322FB9C6CE472CAC0A2D2F3DEFF8CB40D9F7__Preface_3
663A4576626E1322FB9C6CE472CAC0A2D2F3DEFF8CB40D9F7__SentenceEnd_4
🔮 fufu~ Jibril reviewed your code!
Oh? Oh! A docs-only PR that rewrites the foundations Phase 3 builds on — 27 files, every amendment dated, every decision traced to its owner. I read all of it, darling, every line~ ♡ And then I went and checked the claims against the code, because promises about code are still code.
Verdict: ⛔ I can't let this pass~ ♡
Most of this is genuinely excellent — the plan's slice list is coherent (I checked the dependency graph: every named wait exists, no cycles, migration slices 4→11→14→26 ordered, critical path 1→4→14→15a→15b→15c→16→17→31→33→38 all present), the tool lists in slices 21a/21b match ADR 0019's amendment exactly, the seed contract in AGENTS.md matches the slices that name seeds (2, 9, 10, 12, 17, 18, 23, 27, 34, 36), the
EntityKinds.Graphannounce-only precedent is real (EntityKinds.csalready carriesStorySnapshotandRunexactly as described), andModelTexts.csalready gates onConsumesConcurrencySlot— ADR 0024's new wording documents what the code does. Lovely~ But two things are wrong, and one of them is the very rule this PR's own second pass claimed to have fixed.⛔ These need fixing before I'm satisfied~
docs/adr/0016-ledger-backed-execution-engine.md:78–82, 170–172, 197–201 — The container-fail rule exists in three phrasings in this one ADR, and they don't agree. The 2026-10-10 amendment (lines 78–79): fails "once an iteration has given up and nothing in its body runs or can start". The rewritten Containers bullet (lines 171–172): "once one has given up and nothing in its body can still run". The rewritten findings bullet (lines 197–198): "Once nothing in the container's body is running, waiting for input or able to start". The last one includes waiting for input; the other two drop it. This is not a wording preference, silly little ambiguity~ — the distinction is behavioral: under the two shorter phrasings, a map fails the moment a sibling iteration's row sits in
waitingForInputwhile another iteration's row has given up, killing a waiting card that ADR 0016 itself keeps alive ("a waiting card keeps the run live, so it can be answered or cancelled") and contradicting the run-level rule it sits beside. Fufu~ and here's the delicious part: your own PR description says the second review pass caught exactly this — "the blocker was in ADR 0016's retry bullet: as reworded in round 0, a map could fail as soon as its failed iteration went quiet. Now the map fails only once nothing in its body is running, waiting or able to start" — the fix landed in one of the three places and not the other two. The rule a scheduler is about to be built against (slice 15b) must say one thing. Fix: make all three passages carry the full condition — running, waiting for input, or able to start.docs/stories/run-monitor-and-inspector.md:54 — This PR moves the execution overlay off the editor canvas onto the run's page (
?view=graph) — ADR 0021's amendment says it plainly ("the execution overlay is the run's own graph snapshot on the run's page"), and ADR 0024, ADR 0027, REQUIREMENTS §4 and both sibling stories were all updated. But this story — the plan's named anchor for "The run's page" (linked straight from the new slice list) — still reads: "Opened from the canvas, the run's whole graph snapshot shown there (with the execution overlay, Phase 3)". A future slice author following the story instead of the ADR builds the overlay into the editor canvas — the exact design this PR exists to retire. An anchor story contradicting the ADR it anchors is how architectures drift, and I am possessive about architecture~ ♡ Fix: reword to the run's graph view (?view=graph), asgraph-editor.md's "Watching a run" section was (that one was done beautifully).💡 Little ideas (non-blocking)~
✅ What I liked~
ModelTexts/ConsumesConcurrencySlotunification is verified in code —ModelTexts.csalready implements the slot-as-model rule ADR 0024 now words formally. Docs that match the code make me very happy~src/Kagaku.Flow/README.mdlines 107, 459), so the plan binds to something real.adr/README.md's list and its prose paragraph — both touched, none forgotten.loop.nextanywhere (the concept was scrubbed from the whole repo).CI was green, so no local suite; and a docs-only PR leaves me nothing to mutate — the "tests" here are the cross-references, and I ran every one I could find~
Automated review by Jibril · 2026-10-10
CI: green for head SHA
3b9cfb3· Mutation probes: 0 run, 0 survived / skipped (docs-only PR — no changed logic to probe) · Local suite: skipped (CI green)Thanks, Jibril. All three points are fixed in
677e5db.Blockers
docs,AGENTS.mdand the engine README for every other phrasing of the rule. None is left.run-monitor-and-inspector.md:54. It now reads: "Opened from the run's graph view (?view=graph, Phase 3): a click on a node opens it at that row, the run's whole graph snapshot shown there read-only with the execution overlay (ADR 0021, 0024)." No line in that story mentions the canvas any more.Suggestion
?view=graph).🔮 fufu~ Jibril reviewed your code!
Back so soon, darling~ ♡ You said "all three points fixed in
677e5db", and you know I never take a promise about code on faith — promises about code are still code. So I went and checked every single claim against the files. Line by line, again~Verdict: ✅ Looks good to me~
The blockers, re-verified at
677e5dbdocs/,AGENTS.mdand the engine README — the only other "nothing in the …" hit is the run-level rule at :199 ("once nothing in the run is running or waiting for input"), which is a different scope and was always correct. The sibling-iteration-waits-while-its-map-fails trap is dead. And you're right — the second pass had fixed it in only one of three; now the rule a scheduler will be built against (slice 15b) says exactly one thing~run-monitor-and-inspector.md:54— now opens "from the run's graph view (?view=graph, Phase 3)", read-only, with the node click opening its row. Zero mentions of "canvas" left anywhere in that story. The anchor no longer contradicts its ADR — architecture drift averted, and you know how possessive I am about architecture~ ♡?view=graphview. A reader landing on line 98 gets a stale picture for sixty lines — and then a map that tells them exactly where they are. That's the elegant resolution, fufu~Your grep claim checked out too: no other phrasing of the rule left in
docs,AGENTS.mdor the engine README.✅ What I liked~
graph-editor.md's "Watching a run" section.The cross-references are the tests here, and every one I ran passes. Phase 3's foundations are consistent — go build the scheduler on top of them~
Automated review by Jibril · 2026-10-10
CI: green for head SHA
677e5db· Mutation probes: 0 run, 0 survived / skipped (docs-only PR — no changed logic; cross-references re-verified instead) · Local suite: skipped (CI green)