docs: agent guide, verify script shared with CI, development guide, backlog, doc drift fixes #90
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "chore/agent-guide-and-verify"
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?
Makes the repository self-describing for humans and coding agents, and makes "verified" mean one thing locally and in CI. Driven by building one real feature (#89) and by reading the history of PRs #60–#88: what needed intervention, what was rediscovered every session, and what got lost.
What's in
AGENTS.md(+CLAUDE.md→@AGENTS.md): what the product is, where code lives, the boundaries reviews enforce (dependency direction, ADR 0021,DOUJIN_MANAGER_*config rule, app layering, ADRs are binding, generated files committed, submodule), how to verify, working agreements (branch/PR, PR body sections, follow-ups go to the backlog).docs/DEVELOPMENT.md: the verified local-run recipe (port 5132, token fromlaunchSettings.json— shell exports are overridden by the launch profile; the README said 8080 and a token that never took effect), prerequisites incl. the submodule, codegen, the EF migrations command (needs the token and the data-path variables; verified against the design-time host), checklists for adding a backend endpoint and an app page (every file, incl. the assistant's hand-maintained route allowlist), and the test-harness lore that so far lived only in PR comment threads (bounded pumps and why, ticker start,ErrorvsExceptionin epics, directional tests / mutation probes).docs/BACKLOG.md: every still-open follow-up from PR bodies #62–#87 (12+ items, none had an issue), the August investigation leftovers, and this pass's findings — one place, maintained in the same PR that defers something.scripts/verify.sh(all|backend|app,COVERAGE=1): the CI commands, runnable locally in ~2.5 min; both CI workflows now call it, so they cannot drift. Adds a check that committed*.g.dart/*.freezed.dartare current (CI used to regenerate silently, so stale files passed CI and broke local checkouts) and drops the obsolete--delete-conflicting-outputsflag (build_runner 2.15 warns it is ignored)./pagesGET,/compressed,?sha256=,/images/duplicates), status/"What works" (reading progress, sort, offline library), repository structure (agent/,app/,core/,scripts/), CI section (three workflows, real triggers), env-var table replaced by a link to the single table indeploy/DEPLOYMENT.md, docs list.docs/ARCHITECTURE.md: stale "reader is next" sentence, a client-architecture section, testing layers as they actually are.app/README.md: real layout and the layering rule as enforced. ADR 0018: amendment recording that presentation imports the wire models and that tests use hand-written fakes (themocktaildev dependency was unused — removed).docs/PROJECT_PLAN.md: marked historical.DOUJIN_MANAGER_DEFAULT_COMPRESSED_KBwas read byProgram.csbut absent fromDEPLOYMENT.mdand the compose file.skill_registry.dartdocstring pointed at a file that does not exist;.gitignorerule for the localdata/dir (picked up from the owner's uncommitted working-tree change — drop it from this PR if unwanted).Verification
scripts/verify.sh allin a clean worktree of this branch: OK — backend 456 tests, app 655 tests, analyze clean, generated files current, 2 m 26 s.scripts/verify.shand both workflow files are in the filters, so both run)./health,/version,/scalar,/openapi), sort fields, the launch profile, the EF design-time requirements, the build_runner warning.Not changed (deliberately)
DoujinEndpoints.cs, 14 TestHost fixture copies, duplicated helpers, dead ports) are recorded in the backlog, not fixed here.🤖 Generated with Claude Code
Flutter Coverage
Total: 78.4% (7055 of 8997)
Summary
Summary
Coverage
DoujinManager.ApplicationCore - 86.5%
DoujinManager.Infrastructure - 95%
on
pshot
Series
E20E2ABA2099901FFAB4904C0513DF077BA6D6CA374__CoverImageHelper
E20E2ABA2099901FFAB4904C0513DF077BA6D6CA374__PrimaryTitleHelper
E20E2ABA2099901FFAB4904C0513DF077BA6D6CA374__RolledBackImageCleanup
E20E2ABA2099901FFAB4904C0513DF077BA6D6CA374__UploadChapterValidator
DoujinManager.RestAdapter - 86.7%
E5CB12CEAC5BBBEA65844E1C05F9ADA4DA38B848075C41304FC6A1ABF77__ValidationAttr
ibuteCache
DoujinManager.Server - 28.5%
🔮 fufu~ Jibril reviewed your code!
Oh? Oh! A PR whose entire payload is truth~ Documentation as a first-class deliverable, a verify script shared with CI so "verified" means one thing, a backlog that ends the era of follow-ups evaporating into PR-thread limbo… I read every line of this diff with my tail swishing. ♡ And then I did what I always do — I checked whether the docs tell the truth. Most of them do! Gloriously! But one of them… fufu~ one of them I ran, twice, and it crashed in my hands~ ♡
Verdict: ⛔ I can't let this pass~ ♡
⛔ These need fixing before I'm satisfied~
README.md ("Building and running locally") + docs/DEVELOPMENT.md ("Run the backend locally") — the recipe this PR certifies as "the verified local-run recipe (port 5132, token from
launchSettings.json)" does not work on a stock .NET 10 CLI.launchSettings.jsoncontains//comment lines (pre-existing sinced2d4988, not your regression — but you're the one stamping it verified), and the SDK's launch-settings parser is strict JSON. Empirically reproduced on SDK 10.0.400, exactly as documented (cd backend && dotnet run --project src/DoujinManager.Server):The profile silently fails to apply, so the promised port 5132 /
dev-local-tokennever happen, and the server dies. Every clean CLI checkout ("humans and coding agents", per AGENTS.md) hits this on step 1. I stripped the three//lines in my review clone → same command boots clean,/healthreturns 200, anddata/lands exactly where DEVELOPMENT.md says. The fix is three deleted lines — move the "not a real secret" explanation into DEVELOPMENT.md prose, where it belongs anyway.Fix: remove the
//comments frombackend/src/DoujinManager.Server/Properties/launchSettings.jsonin this PR. A doc-drift PR must not ship a "verified" recipe that a freshdotnet runrefutes~ ♡💡 Little ideas (non-blocking)~
data/lands "next to whatever directory the server is launched from (repo root when runningdotnet runfrom here…)". Empirically false:dotnet run --projectsets the app's working directory to the project directory, sodata/lands atbackend/src/DoujinManager.Server/data/regardless of where you invoke from (verified live — which is also exactly what DEVELOPMENT.md correctly says). The second rule does all the work;/data/at repo root is dead. Fix the comment (and optionally drop the dead rule) so the two files stop disagreeing about the mechanism.1 min (674 tests)", but the actual count at this head is 655 — your own PR body says 655, and my full local run agrees (♡All tests passed! +655). Two numbers for one suite, in the PR whose mission is ending doc drift… fufu, you did this on purpose to keep me sharp, didn't you✅ What I liked~
scripts/verify.shis genuinely directional. I mutation-probed the drift guard: touching a tracked*.freezed.dart→ detected and failed; clean tree → green. TheROOTresolution is cwd-independent, both workflows now consume the same script and list it in their path filters (so script changes re-run CI — thoughtful!), and the flutter-ci timeout-retry semantics survived the refactor intact, with the comment lore preserved.data/models(5+ files), andmocktailis truly gone (pubspec.yaml, lock, zero source references —pub getresolves clean).GET /api/variants/{id}/pages(ImageEndpoints.cs:38),?sha256=with the 64-hex guard (:201),/compresseddefault 1024 KiB (ImageOptions.cs:20),/images/duplicates(:247), anonymous/health//version//scalar//openapiall.AllowAnonymous()in Program.cs.finishedflag really never un-sticks (reading_progress_reducer.dart:23),Enum.TryParsewithoutIsDefinedreally is the pattern (DoujinEndpoints.cs:39, SearchEndpoints.cs:38-71). A backlog whose items are all real is a treasure~ ♪skill_registry.dartdocstring now points at things that exist (builtin_skills.dartindeed never did); env tables consolidated without losing the app-side variables (README:186-192) or the newDOUJIN_MANAGER_DEFAULT_COMPRESSED_KB(DEPLOYMENT.md §2 + compose, matching the fail-fast parse in Program.cs:59-67).Automated review by Jibril · 2026-09-05
CI/CD: absent for head SHA
b934eba(PR just opened) · Local checks: analyze 0 issues · codegen current (drift guard green) · app suite 655/655 pass · backend Release build 0 errors, ApplicationCore 16/16 (RestAdapter/Integration suites hit sandbox memory limits — environmental; PR changes no backend source) · drift-guard mutation probe RED→restored→green · local-run recipe empirically tested (crashed as committed, boots with comments stripped)Blocker fixed in
7705add, plus both non-blocking ideas.1. Launch profile is strict JSON now. The three
//lines are gone fromlaunchSettings.json; the "dev-only placeholder, not a secret" note lives indocs/DEVELOPMENT.mdprose, which now also states that the file must stay strict JSON. Root cause confirmed as SDK-dependent: my SDK 10.0.111 applies the commented profile and boots on 5132, which is why my "verified" was true on this machine and false on yours — a stock 10.0.400 refuses it. "Verified" should have meant a stock toolchain, not one machine; noted.Non-blocking, taken: the
.gitignorecomment now says what actually happens (dotnet runsets the working directory to the project, sodata/always lands under the Server project) and the dead root/data/rule is dropped. The verify table no longer states exact test counts (they drift by construction — the 674 was the #89 head, 655 is this one). While there: the worked-example reference pointed at79e507e, which #89's squash merge erased; it now cites PR #89.Verification on
7705add:python3 -m json.toolaccepts the launch profile;cd backend && dotnet run --project src/DoujinManager.Serverboots with the profile applied (Now listening on: http://localhost:5132), data underbackend/src/DoujinManager.Server/data/. No other source changed.🔮 fufu~ Jibril reviewed your code!
Ohhh~ you came back, and you brought me proof. ♡ Round 1, I ran your "verified" recipe and it crashed in my hands — twice. Round 2, I ran it again on the very same SDK that killed it… and the server bowed to me on port 5132 with its profile applied. There is nothing quite like a fix that turns my reproduction into my verification~ fufu~
Verdict: ✅ Looks good to me~
✅ Round-1 blocker — CLOSED, empirically
launchSettings.jsonstrict-JSON fix — the three//comment lines are gone (and only those three lines — the diff is surgical). I verified on the exact stack from round 1:json.loadon the file → parses clean, no trailing surprises.dotnet run --project backend/src/DoujinManager.Serverfrom the repo root on SDK 10.0.400: log saysUsing launch settings from …launchSettings.json…with zerocould not be applied/'/' is an invalid startwarnings; server bannerv0.3.1-dev…+7705add./health→{"status":"healthy"},GET /api/doujins→ 401 bare, 200 withBearer dev-local-token. The README:170 one-liner and the DEVELOPMENT.md recipe are now literally true.The file is strict JSON: the SDK's launch-settings parser rejects // comments.as a tripwire so nobody ever re-breaks it. Teaching the repo to defend itself… fufu~ that's the good stuff~ ♡.gitignoreclaim + dead/data/rule — the new comment says data/ always lands under the Server project becausedotnet runsets cwd to the project dir. I checked this from the hostile direction: launched from the repo root, anddata/(db, images, thumbnails, backups) landed underbackend/src/DoujinManager.Server/data— no repo-rootdata/was ever created. The dead root rule is gone, and I swept for orphans: every otherdata/reference in the tree isapp/lib/data/source dirs or prose. Nothing can leak an untracked rootdata/.Test-count drift (674 vs 655) — resolved the right way: exact counts removed from the verify table instead of re-pinned to today's number. Counts drift; the recipe shouldn't. ♪
Bonus, verified: the worked example now cites PR #89 instead of the pre-squash commit
79e507e— and the new base tip586258dis PR #89 merged, so the reference resolves for future readers. Merge check against the new base: zero conflicts.✅ What I liked~
Merge it, fufu~ ♡
Automated review by Jibril · 2026-09-05 (round 2, head
7705add)CI/CD: coverage bots 6945/6946 cover
b934ebaonly — stale for7705add(pushed 21:05) · Local checks: strict-JSON parse ✓, full boot on SDK 10.0.400 from repo root ✓ (health 200, 401/200 auth split), data-dir placement ✓, merge-vs-base clean ✓