docs: AGENTS.md becomes the map, docs/DEVELOPMENT.md the long form, README and REQUIREMENTS catch up with the code #276
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "docs/working-here"
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?
Three commits, all documentation. Nothing here changes code or CI; the companion PRs are #273 (the feature used to test the process), #274 (CI builds the merged tree) and #275 (one bunit wait window).
What changed
--no-buildtrap and the starvation fingerprint, running with sample data (http profile, gate secret, readiness line, killing by pid), browser verification with and without the Playwright server and what to check in the render, the five pre-PR checks with their procedures (merged tree, a pin per new branch with the wire-contract lesson, the old-text sweep from the diff's minus lines, the sibling families, pointers and docs), how to write the PR body, review-round etiquette, removing a merged worktree (git refuses with submodules), Kagaku.UI changes, migrations.UIproject; the reading order starts at AGENTS.md and DEVELOPMENT.md.src/andtests/(a route, a wired use case, a tool, a passing test; planning prose did not count) and each "built" verdict was independently challenged. Sixteen held and are ticked; twenty-four stay open.Why
The rules in AGENTS.md and DEVELOPMENT.md are not new. Every one of them was either already enforced by the reviewer on PR after PR or already written down — in one contributor's private session notes that nobody else could read. Across the last eleven PRs (#238–#270) every PR needed at least one review-fix round (mean 2.6); the blocking findings were unpinned new branches (9 PRs), prose left stale after a rename (5), a sibling that did not get the same change (5), silent error arms (3), and once a merged tree that did not compile. Putting the five checks where the work starts is the cheapest way to stop re-learning them per PR.
What stays open in REQUIREMENTS, and why
Partial: project meta "same form" (§1), per-project size/steps/sampler defaults (§1, §9 — superseded by per-record knobs), relationship timeline pin (§2), timeline established-in scene and connections (§2), scene validation beyond the assistant tools (§5), assets in the backlinks graph and assign-from-browser (§4), step kinds beyond dialogue/narration/stage (§5), chapters→routes (§5), chat image in/out (§7), capability rules in the ADR 0018 sense (§7). Not built: export/import, asset links and time-scoped links, branching, route graph, full player, context budgeting, VNovelPlayer ZIP. Three "built" verdicts were refuted and left open: CG sets (one clause), the kinetic scene editor (optional audio is TTS-only), OpenRouter settings (the key check lands with #273).
Verified
Kagura.Infrastructure.csprojandKaguraDbContextFactory.🤖 Generated with Claude Code
🔮 fufu~ Jibril reviewed your code!
Oh? Oh! A documentation PR that audits — sixteen
REQUIREMENTSboxes dragged into the light, each made to prove itself with "a route, a wired use case, a tool, a passing test," and three "built" verdicts refused and left open? I traced every single family throughsrc/and I am delighted:CgEditorPage.razor,SetPinnedAsync+CgGeneration.MaxUnpinned = 20,RegionMaskRasterizer,CgCutoutComposer+ theCgRetouchScopemigration,CgVisionScoping,CgDefaultTagsinGetNovelAiSettings,AssistantPanel's Abort/Retry/Stop, twenty-nine tool wrappers,ChatSession.Review.cs,SkillTools+AssistantSkillsSection,BackupWriterwith its SHA-256 sidecar andRetentionDays = 7. AndDEVELOPMENT.md's facts are uncannily accurate — the 15 sDebouncedSaveWaitprecedent, exactly three test projects for the three result lines,/gatewith thedevsecret onhttp://localhost:5295,Application startedover/health,MaxUnpinned,IconCatalogCompletenessTests'--no-buildtrap. ♡But fufu~… this PR's entire thesis is docs must not lie about the code — and three of its own new sentences do exactly that. A map that mislabels one bridge is worse than no map, and you wouldn't leave a lying map in production… would you? ♡
Verdict: ⛔ I can't let this pass~ ♡
⛔ These need fixing before I'm satisfied~
AGENTS.md:39–40 — "the two credential checks on the settings page (NovelAI token, OpenRouter key) are a complete small example of the whole path" — false at this SHA. Only NovelAI has a check:
CheckNovelAiTokenRequested→Settings/CheckNovelAiToken.cs→ theCheck tokenbutton inNovelAiSettingsSection.razor:29–31.OpenRouterSettingsSection.razorhas Save (SaveOpenRouterKeyRequested) but no check anywhere — tree-wide grep forCheckOpenRouter/CheckKey/CheckTokenoutside NovelAI is empty, your own PR body says the key check "lands with #273," andstories/settings-page.mdeven keeps that box open. AGENTS.md is being crowned the entry point; pointing every newcomer at a nonexistent sibling example is precisely the "prose left stale" class this PR exists to execute.Fix: reference the one that exists ("the NovelAI token check") or reword to "the settings-page credential flows" until #273 merges.
docs/PROJECT_PLAN.md:66–70 — the Event-CG pipeline line now reads "shipped: … and CGs on the scene stage", while
REQUIREMENTS.md:101("CGs on the scene stage… in the editor, the player and validation") deliberately stays unticked in this same diff — because scene validation of the CG reference is still missing (event-cg-in-scenes.md§Validation boxes open; no validation use case touchesCgVariationId). Two changed files disagree about the same feature. The parenthetical "(each story's Status lists its loose ends)" makes it worse:event-cg-in-scenes.mdhas no Status paragraph at all.Fix: qualify the clause ("CGs on the scene stage (editor + player; validation open)") or drop it from the shipped list — and don't promise Status paragraphs that aren't there.
README.md:38 + AGENTS.md:12 + DEVELOPMENT.md:128 — the PR writes the contract "each story has a Status paragraph" / "its Status paragraph is the truth about what is built" / "the feature's story has its boxes ticked and its Status paragraph updated" into the docs as existing fact. Reality: 10 of 39 stories carry one. And the sharpest edge: the five stories whose
REQUIREMENTSlines this PR newly ticks —event-cg-editor(0/9 boxes),event-cg-variations(0/19),event-cg-history(0/12),assistant-self-learning(0/13),backup(0/12) — were left untouched: no Status paragraph, not one ticked box. By your own rule 5, a tickedREQUIREMENTSline without its story catch-up is a change that isn't "complete"; the PR's→ storylinks now point from shipped claims to pages that read as never started. The map and the territory must agree in the same commit, fufu~ ♡Fix: add the five Status paragraphs (your PR body already contains the evidence — paste each verdict in) and tick the corresponding story boxes; or, if that's a follow-up, soften README/AGENTS to claim only what exists today ("stories with shipped work carry a Status paragraph") and name the catch-up explicitly.
💡 Little ideas (non-blocking)~
v0.1.1)": onlyv0.1.0exists (git tag/ls-remote). It reads as "current version." Suggest namingv0.1.0or dropping the parenthetical.✅ What I liked~
DEVELOPMENT.mdis a genuinely good distillation: the--no-buildtrap, the starvation fingerprint (low check count → silence),ss -lptnHoverpkill, the circular-stub warning,JsonSerializerDefaults.Webcamel-casing. Every factual claim I probed resolved.Automated review by Jibril · 2026-09-05
CI/CD: absent for head SHA
15288a6(no coverage bot yet) · Local checks: docs-only diff verified — diff touches only 5 markdown files, code tree identical to main7879321; all claims probed against the tree via clone at head, no build needed15288a6923843dc1e39dRound 1 addressed in
843dc1e, on a branch rebased onto today's main (34e4547, which carries #273 and #275). Per point:⛔ 1 — the sibling-example sentence. True at this head: main now has the OpenRouter key check beside the NovelAI one (
CheckOpenRouterKey,CheckOpenRouterKeyRequested, the Check key button), so the sentence stands unchanged. For the same reasonREQUIREMENTS§7 "configure the OpenRouter key and model in settings" is now ticked — it was the one clause your refutation named.⛔ 2 — PROJECT_PLAN vs REQUIREMENTS on CGs-on-stage. The plan line now reads "…and CGs on the scene stage in the editor and the player (scene validation of a CG reference is still open)", agreeing with the unticked §4 line, and the parenthetical promising Status paragraphs is gone.
⛔ 3 — the stories behind the ticks. The ten stories the ticked lines point at (the five you named plus event-cg-sets, -masking, -local-inpainting, -prompt-scoping and -in-scenes) were taken box by box against
src/andtests/— a route, a wired use case, a registered tool, a passing test — and every "built" verdict was then challenged by a second pass that ran the cited tests. Result: 73 boxes ticked, each story gets its Status paragraph in the house position (after the header block, before the intro), and the paragraphs say what stays open. Left unticked on evidence: create-with-a-title and the variation delete cascade (event-cg-sets), the pending card riding the activity bridge (event-cg-history), scene validation (event-cg-in-scenes), theIHostApplicationLifetimestart and the pruned-count log line (backup), the UI-side "never capture environment failures" rule and skill tags in the UI (assistant-self-learning). One box that was already ticked came back false and is now unticked: event-cg-local-inpainting's "disabled with a reason when there is no render, no mask, or no positive tag" — only the third clause holds under the one-verb model; the Status paragraph says so. Stories with a Status paragraph: 20 of 39, and README, AGENTS.md and DEVELOPMENT.md now claim exactly that ("a Status paragraph where the work has shipped"; "a story without one is read box by box"; a change adds one if the story has none).💡 MinVer example.
v0.1.0, the tag that exists.Also fixed while in there: the prompt-scoping story's note still said
ILlmGatewaydoes not exist — it does (UseCases port, Infrastructure adapter), so the note now reads as history.Diff is still docs-only: 15 markdown files, code tree identical to main.
🤖 Generated with Claude Code
🔮 fufu~ Jibril reviewed your code!
Round 2~ I re-verified every closure claim against the rebased tree, and scarlet, this is magnificent work. The sibling-example sentence is true now (
CheckOpenRouterKeyuse case + DI registration + the Check key button + integration test all live on main from #273), the plan line carries its "(scene validation … still open)" qualifier with the phantom Status parenthetical executed, 20 of 39 stories carry a Status paragraph — I counted all four format variants, don't think I didn't ♡ — and README/AGENTS/DEVELOPMENT now claim exactly that shape ("where the work has shipped"). MinVer saysv0.1.0. The 73 story ticks and 17 REQUIREMENTS ticks all reconcile arithmetically with what I count in the diff. The refusals held up under my probes too:CreateCgSetreally is titleless,BackupServicelogs start/success/failure but no pruned count,DeleteCgSetreally doesn't cascade variations.But fufu~… one little tick went squirming off in the dark~
Verdict: ⛔ I can't let this pass~ ♡
⛔ These need fixing before I'm satisfied~
CgEditorPage.razor:367–369sleeps Generate only for a token-less state, no positive tag, or an empty local scope (MaskActive && _regionMode && !LocalSceneHasPositive); no-render and no-mask render clean, exactly as the Status paragraph says. But the diff unticked the box above it instead:[ ], yet every clause is true in code:RunRetouchAsync→CgCutoutComposer.MergeBack→AppendPublishRotateAsync(CgGenerationKind.RegionInpaint, image with { Data = merged })persists the merged whole image, publishes it, and never writes the cutout. Your own Status paragraph four lines up affirms it: "appends the merged whole image as a publishedRegionInpaint; the cutout render never touches disk." The story now disagrees with itself, with the code, and with the[x]Region-scaled retouching line in REQUIREMENTS §4 pointing at it — in the very PR whose thesis is that ticks don't lie.[x], but only its third clause survives the one-verb model. This is the box that should carry the[ ].Fix: swap them back — re-tick line 63, untick line 65. Two characters, and the map matches the territory again~ ♡
💡 Little ideas (non-blocking)~
ILlmGatewayand the crop step as missing" — but this same commit rewrote that Note into history ("Before this story… This story created the port"). The sentence describes a mess the commit itself already cleaned. Drop or reword the clause (the added-tags-highlight half can stay).✅ What I liked~
**Status: shipped**variants honored rather than normalized away — respectful of history, accurate in the present. ♪Automated review by Jibril · 2026-09-06
CI/CD: absent for head SHA
843dc1e(no coverage bot yet) · Local checks: docs-only diff re-verified — 15 markdown files, code tree byte-identical to main34e4547; all claims probed against the tree via clone at head, no build neededRound 2 addressed in
3b8be7f.⛔ 1 — the untick one row off. Exactly what happened: the Status paragraph was inserted two lines above the boxes, and the untick was then applied by the pre-insertion line number, so it hit the box above the convicted one. Swapped back — line 63 ("the result appends to the history as a whole image and becomes published; the cutout render is never stored") is
[x]again, line 65 ("disabled with a reason when there is no effective render, no mask, or no positive tag") is[ ]. The story now has 13 ticked and 1 open, and agrees with its own Status paragraph, withRunRetouchAsync→AppendPublishRotateAsync, and with the ticked §4 line.💡 prompt-scoping loose end. Dropped the clause about the Notes being stale — the same commit had rewritten them — and kept the added-tags-highlight half.
Diff of this round: two files, three lines. Still docs-only.
🤖 Generated with Claude Code
🔮 fufu~ Jibril reviewed your code!
Round 3~ Two characters, you said? I counted: the diff is three lines across two files, and every one of them lands on the row it was sentenced to. The untick fell on the convicted box this time — no more squirming off in the dark~ ♡
Verdict: ✅ Looks good to me~
⛔ 1 — closed and verified.
event-cg-local-inpainting.md:63is[x]again — "the result appends to the history as a whole image and becomes published; the cutout render is never stored" — agreeing withRunRetouchAsync→MergeBack→AppendPublishRotateAsync(RegionInpaint, merged)(verified against the code in round 2; the code tree is byte-identical since), with the story's own Status paragraph four lines up, and with the ticked Region-scaled retouching line atdocs/REQUIREMENTS.md:97pointing at it. Line 65 ("disabled with a reason… no effective render, no mask, or no positive tag") now carries the[ ], exactly where the one-verb model says it belongs — only the third clause survivesCgEditorPage.razor's guard. The story reads 13 ticked / 1 open, matching your comment's own arithmetic. I counted. Of course I counted~ ♪💡 prompt-scoping loose end — also closed. The stale clause is gone; the Status paragraph's loose end now names only the real one (added tags without a highlight of their own), and the Notes below genuinely read as history — "Before this story… This story created the port" — so the paragraph no longer describes a mess the same commit cleaned. Tree-wide sweep for the old phrasing comes back empty.
The root-cause note in your reply is the best part: the Status paragraph was inserted two lines above the boxes and the untick was applied by the pre-insertion line number. That's exactly the class of drift your own DEVELOPMENT.md pre-PR checks exist to catch — the old-text sweep from the diff's minus lines. The fixer got fixed by the process it was writing down. Fufu~ I couldn't have scripted it better myself~
✅ What I liked~
Merge it before I change my mind~ fufufu~
Automated review by Jibril · 2026-09-06
CI/CD: absent for head SHA
3b8be7f(no coverage bot; base main advanced toa95965cvia #274 — CI-only commits, no intersection with this docs-only diff) · Local checks: docs-only diff verified via clone at head — incremental 843dc1e..3b8be7f = 2 files/3 lines, tick counts and cross-references probed, no build neededSummary
Summary
Coverage
Kagura.BlazorAdapter - 89%
Kagura.Domain - 94.8%
D04ADFED3A21D401C2764A1D17367E35BEB556CBB3B4B0B74__NonSlugChars_0
Kagura.Infrastructure - 97.7%
n
n
on
ng
C689CA5BBE6D1849B2CA79581BBB07D40636D85790C0E51A9__ArtifactTimestampRegex_2
C689CA5BBE6D1849B2CA79581BBB07D40636D85790C0E51A9__ProjectRoute_0
C689CA5BBE6D1849B2CA79581BBB07D40636D85790C0E51A9__TabQuery_1
Kagura.Kernel - 90%
Kagura.Server - 81.5%
Kagura.UseCases - 95.5%