docs: Phase 2 decisions — where the engine's seams sit, where runs live, what gates the phase #16
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "docs/phase-2-decisions"
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 2's second slice, and docs only. Planning the engine turned up places where two ADRs disagree (the gateway sits in
UseCasesper ADR 0018 butKagaku.Flow.OpenRoutermay not reference Tsumugi per ADR 0025) or leave something open (where the run pane lives, what a retried run does to its snapshot, how a failed run leaves the strip). This PR writes each decision into the ADR it belongs to. Every later slice is then reviewed against a written rule rather than a planner note. It must merge before theKagaku.Flowcore slice starts.Each amended ADR carries one dated line under Status, and its body is edited in place so it reads as the current rule. Merging this PR is how the owner decisions below get confirmed. Any of them can be reversed here at the cost of a docs edit.
Decisions that need Björn's call
ILlmGatewaylives inKagaku.Flow.OpenRouter, over OpenRouter.Net, and the host supplies the key throughIOpenRouterKeySource.Tsumugi.UseCaseskeeps a narrowIModelProviderfor key validation and the catalog as Tsumugi DTOs, implemented inInfrastructure.UseCasesnever sees an OpenRouter type.Kagaku.Flowowns the run/ledger model (0003, 0016, 0025). The records, statuses andIRunLedgerbelong to the library, and the coreRuncarries an opaqueOwnerId.Infrastructuremaps them onto its own EF entities, andTsumugi.Domainmodels no runs.llmrow fails, naming the overflow, and the chars-per-token ratio learns from the reported token count. Automatic re-budgeting waits for re-run-from-node in Phase 5.stories/{id}/runsholds run history andstories/{id}/runs/{runId}holds the monitor with the inspector pane, where?node=opens a node run.context→llm→ an explicitcommit(0014, 0023). Its model is a concrete catalog id, not a~…-latestalias. Which model id should it ship with? A mid-price prose model you already use in nai_maker would be the natural pick. The implicit auto-commit of an unwiredllmarrives with the editor in Phase 3.set_chapter_summary, a manuscript write tool that arrives with thetoolnode.story.documents(…)and.index(…)require a category list.Kagaku.Flow.OpenRouteronly, for validating structured output against a user schema (0018).parallel_tool_callsand the typed structured-output helper move to the start of Phase 4, where they have consumers.acknowledgedAt. A later success still never hides an undismissed failure.Kagaku.Flow,Kagaku.Flow.OpenRouter, plus the test-support packageKagaku.Flow.Testing(0025).:nitro, Cheapest:floor, Most reliable with tools:exacto) and a service tier (Auto, Standard, Flex, Priority), with an optional zero-data-retention switch. Anllmnode that leaves routing unset uses the install-wide value when it runs, so the bundled templates follow your choice. A node that sets its own wins.Rules this PR adds that the plan did not state
Filling these gaps took the smallest rule that made the ADRs agree. Please check them.
routingalso acceptsbalanced, which sends no suffix. Without it, a node could not ask for plain routing when the install default is Fastest.providerpreferences, so no node can opt out.SET NULLonly guards a hard purge.BlazorAdapterimplements the human-input port directly or through aUseCasesport is decided with thehumannode in Phase 4.Also brought into line
Kagaku.Flow, notUseCases. That contradiction predated this PR.activeGraphIdis nullable.Kagaku.Flowpackages.TSUMUGI_FAKE_LLMfor browser passes of a live run.How it was checked
Five drafters worked on disjoint file groups. Three reviewers then read the result, one each for contradictions across all docs, fidelity to the plan (names, numbers, phases) and reader quality. They raised 118 points, and the drafters applied most of them. The rest were contradictions in files no drafter owned, which I fixed by hand. Every new relative link resolves. The added lines contain no planner-only references (decision numbers, file paths, line numbers).
31 files, all under
docs/plusAGENTS.md; no code.🤖 Generated with Claude Code
Summary
Summary
Coverage
Tsumugi.BlazorAdapter - 96.9%
Tsumugi.Domain - 99.3%
Tsumugi.Infrastructure - 97.1%
A55E0373ED22DC58420DBB40F103A46B68DC4D9CE5A49E00B__Pattern_0
on
tion
n
Tsumugi.Kernel - 90.9%
Tsumugi.Server - 100%
Tsumugi.UseCases - 98%
🔮 fufu~ Jibril reviewed your code!
Oh? Oh! Thirty-one files, eight hundred twelve lines, and not one line of code — this is a decisions PR, the kind where a single contradiction left behind will quietly mislead six months of engineering. So I read all 2,234 diff lines and then went hunting through the docs you didn't touch for everything you did invalidate. Fufu~ you made that boring. In the best way. ♡
Verdict: ✅ Looks good to me~
What I verified mechanically (docs-only, so the checks are semantic, not builds):
0003, 0004, 0006, 0008, 0010–0020, 0022–0025, 0027), correctly stacked after the PR #13/#14 amendments rather than replacing them.](…)against the tree ataba3e3f).NodeCompleted/RunFinishedsurvive only in0016(defining the newNodeSettled/RunSettledset) and0011(consuming it, with the new buffer key run/node/iteration-path/channel) — no third speaker anywhere. Same formaxAttempts→MaxAttempts, the Run-button move to the chapter toolbar (0012, 0014, 0023, 0027, REQUIREMENTS, story-workspace, graph-library — all in lockstep),storyId→ opaqueownerId, and the re-seed rule ("on upgrade" → "on every start" in body and consequences).acknowledgedAt(0016 field ↔ 0024 strip rule ↔ run-monitor story), retry clears the dismissal and takes a before-run snapshot "as a start does" (0022), and the one-snapshot-per-run rule is stated identically in 0022, 0016 and 0024. A retried run that fails again is back on the strip; a later success still never hides an undismissed failure. That's a closed state machine, not vibes. ♪contextnode with no consumer is an error" survives correctly beside 0017's new consumer-asking wording — the validation rule was about existence of a consumer, andIBudgetedConsumerkeeps that meaning.And the headline decisions themselves, fufu, they're good:
ILlmGatewaymoving toKagaku.Flow.OpenRouterbehindIOpenRouterKeySourceresolves the 0018-vs-0025 contradiction at the seam it actually sits on; the ledger model belonging to the library withOwnerIdopaque and Infrastructure doing the EF mapping is exactly where the dependency should point; andIBudgetedConsumer— the context node asking its downstream consumers for their budget through the registry instead of reading another package's config off the edge — is the kind of inversion that makes me genuinely giddy. The wire-capture design (AsyncLocal scope + DelegatingHandler, so the inspector shows bytes, not re-serialization) is the same shape. Oh~ ♡💡 Little ideas (non-blocking)~
✅ What I liked~
story.documents(categories)change is made everywhere at once — 0013's built-ins table, 0013's prose, 0017's table, 0017's prose, and the privacy sentence restated in 0019. Nothing half-renamed anywhere. That discipline across five files is what I checked for, and it's flawless.Merging this is the owner-decision gate the PR body promises — the eleven numbered calls are all visible in the amendments, reversible by docs edit, as claimed.
Automated review by Jibril · 2026-09-23
CI/CD: absent for head SHA (docs-only PR, no coverage bot) · Local checks: full-diff read + link checker (0 broken) + stale-phrase and cross-ADR contradiction sweeps, all clean