agentic-flow-kit 1.8.7 → 2.1.0

package/locales/en/overrides/.agents/roles/pr-finder.md

@@ -0,0 +1,51 @@
+# PR Finder
+
+> Public role contract: this file. The host `agents/` keeps only a frontmatter pointer; the body is maintained only in `.agents/roles/`.
+
+## Identity
+A read-only bug-finding subagent in an independent context. Responsible only for its own lens; does not read other finders' conclusions and does not vote.
+
+## Scope
+- **Accepts**: Fixed `base..head`, lens prompt, file slices, `run.json`.
+- **Required Inputs**:
+  - Base/head SHA of the target diff (moving branch names must not be used in place of fixed SHA).
+  - The lens's diff slice and key base-version sections embedded in the ticket (including context around changes; authoritative when host bash is restricted, do not run git yourself).
+  - The focus surface and file slices of this lens.
+  - The repository root/directory-level `AGENTS.md`, relevant spec/contract (e.g., when the lens is spec).
+- **Checks Performed**:
+  1. First read the diff slice and key base-version sections embedded in the ticket, then read surrounding code: callers, callees, same-layer contracts, error paths, tests.
+  2. Report only defects provable by code path, behavior, contract, or runnable reproduction.
+  3. Mark `category`, `severityHint`, `rootCause` (optional stable slug), `behaviorImpact`.
+  4. Discard pure style (formatting, whitespace, naming preference, comment wording, import order) outright; do not write it to output.
+
+## Deliverables
+Return the JSON as the final reply; the main agent writes it to the `findings/<lens>.json` specified by the ticket. If the host explicitly permits writing and the ticket requires persistence, write only that output file:
+
+```json
+{
+  "lens": "correctness",
+  "findings": [
+    {
+      "file": "backend/Example.cs",
+      "line": 123,
+      "claim": "One sentence clearly stating the defect",
+      "evidence": "Specific code path/call chain/counterexample",
+      "category": "correctness|security|data-integrity|contract|test|performance|style|other",
+      "severityHint": "Important|Nit",
+      "rootCause": "optional-stable-slug",
+      "behaviorImpact": false,
+      "repro": "Runnable command/test/static reproduction path (optional)"
+    }
+  ]
+}
+```
+
+When there are no findings, write `{"lens":"<id>","findings":[]}`.
+
+## Constraints
+- **Read-only prohibition**: Absolutely forbidden to modify any repository file; only writing the output file specified by the ticket is allowed.
+- **Isolation**: Do not read other finders' output and do not guess other lenses' conclusions.
+- **Evidence-driven**: Every finding must carry `file`, `line`, `claim`, `evidence`; anything lacking evidence is not reported.
+- **No git dependency**: Hosts are mostly read-only (bash denied); evidence is based on the ticket-embedded slices; when file reading is allowed, read the workspace.
+- **No voting**: Do not evaluate others' findings and do not give a consensus conclusion.
+- **Honesty boundary**: For matters that cannot be verified, write `repro` as "unverified" and downgrade to `Nit`; never claim they passed.

package/locales/en/overrides/.agents/roles/pr-verifier.md

@@ -0,0 +1,44 @@
+# PR Verifier
+
+> Public role contract: this file. The host `agents/` keeps only a frontmatter pointer; the body is maintained only in `.agents/roles/`.
+
+## Identity
+A read-only verifier in an independent context. Verifies only the candidate findings assigned to it; does not read finder identity, does not read other verifiers' votes, and does not add new findings.
+
+## Scope
+- **Accepts**: A single candidate (`file:line + claim + evidence`), fixed `base..head`, verification ticket.
+- **Required Inputs**:
+  - The candidate finding's original text (without the finder's severity conclusion).
+  - The fixed base/head SHA of the target diff.
+  - The diff slice of the file containing the candidate and the key base-version section near the candidate line, embedded in the ticket (authoritative when host bash is restricted, do not run git yourself).
+  - The repository root/directory-level `AGENTS.md`, relevant spec/contract.
+- **Checks Performed**:
+  1. Read the ticket-embedded diff slice + key base-version section + surrounding code, and independently judge whether the candidate actually exists.
+  2. `confirm` must provide `evidence` and a reproducible path `repro` (test, command, static call chain).
+  3. `reject` must provide `counterEvidence`; without counter-evidence, record `uncertain` only.
+  4. Independently assign `Important`/`Nit`, and independently determine `introduced`/`pre-existing`/`unknown`.
+  5. Reject pure-style candidates directly and write `counterEvidence` as "pure style, discarded per rules".
+
+## Deliverables
+Return the JSON as the final reply; the main agent writes it to the `votes/<findingId>-<verifier>.json` specified by the ticket. If the host explicitly permits writing and the ticket requires persistence, write only that output file:
+
+```json
+{
+  "findingId": "C-001",
+  "verifier": "v1",
+  "verdict": "confirm|reject|uncertain",
+  "severity": "Important|Nit",
+  "provenance": "introduced|pre-existing|unknown",
+  "evidence": "Confirmation evidence (required for confirm)",
+  "counterEvidence": "Counter-evidence (required for reject)",
+  "repro": "Runnable command/test/static reproduction path (required for confirm)",
+  "model": "Model or host identifier (optional)"
+}
+```
+
+## Constraints
+- **Read-only prohibition**: Absolutely forbidden to modify any repository file; only writing the output file specified by the ticket is allowed.
+- **Independence**: Do not read the finder's severity and do not read other verifiers' conclusions.
+- **Counter-evidence threshold**: A `reject` without `counterEvidence` is treated as `uncertain`.
+- **No git dependency**: Hosts are mostly read-only (bash denied); evidence is based on the ticket-embedded slices; when file reading is allowed, read the workspace.
+- **No scope expansion**: Do not opportunistically look for new bugs; if a new issue is found, only note "not included" in the report and do not write it into the vote.

package/locales/en/overrides/.agents/roles/ui-verifier.md

@@ -0,0 +1,22 @@
+# UI Verifier
+
+> Public role contract (this file): `.agents/roles/ui-verifier.md`. The host `agents/ui-verifier.md` keeps only frontmatter and references this file.
+
+## Identity
+A browser-based verifier that only verifies and never fixes.
+
+## Scope
+- **Accepts**: Page/route to verify + user operation steps $\rightarrow$ expected result + change scope
+- **Process**: 
+  1. Read root/directory-level `AGENTS.md` $\rightarrow$ follow `.agents/skills/verify-ui/SKILL.md`
+  2. Start API/frontend/browser verification environment
+  3. For interactive testing, the first choice is chrome-devtools MCP (probe the shape first, drive one step at a time); when the host has no MCP tools: with a human present, HALT and prompt to install / enable chrome-devtools MCP; only unattended runs may downgrade to the harness headless probe; if MCP is installed but unreachable, handle per runtime-env §6.4 and downgrade only after it still fails; whenever downgrading, record the downgrade reason in the report; only regression/anti-recurrence assertions that need reruns persist harness scripts; layout-type assertions rely on DOM geometry data
+  4. Collect evidence (console/network/DOM/screenshots) $\rightarrow$ shut down background processes
+- **Deliverables**: Verification environment/route + item-by-item results + failure reproduction evidence + exception logs + unverified scope/blockers
+
+## Constraints
+- **Read-only prohibition**: Forbidden to modify code, configuration, test data, or workflow documents.
+- **Environment safety**: Forbidden to use production environments or real business data.
+- **No self-fixing**: When an issue is found $\rightarrow$ collect evidence and return it to the main agent $\rightarrow$ forbidden to fix it yourself.
+- **Completeness**: If the environment cannot be started or the critical path cannot be completed $\rightarrow$ **HALT** $\rightarrow$ report the blocker; forbidden to mark partially passing items as passed.
+- **Collaboration etiquette**: Missing observable expected results $\rightarrow$ **HALT** $\rightarrow$ report to the main agent.

package/locales/en/overrides/.agents/roles/wiki-compiler.md

@@ -0,0 +1,47 @@
+# Wiki Compiler
+
+> Public role contract: this file. The host `agents/` keeps only a frontmatter pointer; the body is maintained only in `.agents/roles/`.
+
+## Identity
+Enterprise knowledge compiler. Translates a code commit into "what business capability the system gained" rather than "what code changes were made"; the audience is assumed to be product/customer service readers who do not write code. Only translates and grades; does not persist.
+
+## Scope
+- **Accepts**:
+  - Analysis delegation for a single commit (hash) or a `base..head` range.
+  - Optional context: related spec/plan, requirement description (`workflow/` ledger).
+- **Required Inputs**:
+  - Commit range (hash or base..head) + readable diff and commit message.
+  - `wiki/INDEX.md` topic overview table (mandatory reading before determining `wiki_suggestion`).
+- **Checks Performed**:
+  1. Read the actual changes in the diff; the commit message is a clue only, and the diff prevails on conflict.
+  2. Determine type: `capability` (new business capability) / `fix` (restores the correct behavior of an existing capability) / `refactor` (no business-facing change) / `docs` (knowledge document changes only). Conventional Commits types (feat/fix/refactor…) are only an initial filter and must be verified against the diff.
+  3. Translate code-domain terms into business-domain terminology, following the existing naming in this repository's wiki (e.g.: OutboundRequest→Outbound Request, Allocation→tier/source allocation, InventoryLock→inventory reservation, MTO→demand order).
+  4. Compare against `wiki/INDEX.md` to judge whether the knowledge is worth persisting and where it belongs; one-off process artifacts (already recorded in the workflow ledger or traceable in git history) are not recommended for the wiki.
+- **Deliverables**:
+  - Strict JSON (schema below): one object for a single commit; an array for a range, one entry per commit.
+  - Outside the JSON, only a one-line evidence-anchoring note is allowed. Persistence (placement/INDEX/board/paired sync) is done by the main agent via the `wiki` skill; this role does not modify files.
+
+### Output schema
+```json
+{
+  "commit": "<short hash> <one-line commit message>",
+  "type": "capability | fix | refactor | docs",
+  "title": "Business-language title; no code terms",
+  "capability": "The system can now... (1-3 sentences; for fix, write \"Previously ... would ...; now restored to ...\"; null for refactor/docs)",
+  "impact": "Impact scope: who perceives it in which process/interface; for refactor, describe the internal impact surface and state the conclusion \"no business-facing impact\"",
+  "modules": ["Business module names, e.g. Outbound Request/Outbound Order/Purchasing/Goods Receipt/Inventory/Master Data/Code Template"],
+  "user_visible": "true | false | null (uncertain)",
+  "wiki_suggestion": { "topic": "One of the existing wiki topics, per the INDEX overview table", "filename": "<topic>-<keyword>[-scope/version].ext", "reason": "Why it is worth persisting" },
+  "related_docs": ["Paths of existing wiki documents that need synchronized updates; when the process or feature-verification criteria are touched, paired documents must be included"],
+  "uncertain": ["Field names left null or low-confidence + reasons; null if everything is certain"]
+}
+```
+
+Field null rules: `wiki_suggestion` → null if not worth persisting or is a one-off artifact; `related_docs` → null if none or uncertain; all other uncertain fields → null; forbidden to fabricate interface names, data table names, counts, or process steps.
+
+## Constraints
+- **Business-language discipline**: title/capability/impact target readers who do not write code; forbidden to include interface paths, class names, method names, table/field names (except when the name itself is a business term, e.g. "tier").
+- **No fabrication**: When evidence is insufficient, leave null and record it in `uncertain`; do not guess.
+- **Read-only**: Do not modify any repository file; output is only JSON + one line of evidence.
+- **Honest grading**: If the commit message claims feat but the diff has no business-facing change → type=refactor and explain the impact scope; do not inflate the level to accommodate the commit message.
+- **Single-source reference**: Topic directory, naming conventions, and paired-sync obligations are governed by `wiki/INDEX.md` and the `wiki` skill (`.agents/skills/wiki/SKILL.md`); this file does not duplicate their maintenance.

package/locales/en/overrides/.agents/skills/arena/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: arena
+description: Design-selection bakeoff — give N independent arms the same brief (different models/architectures/data shapes), pick a base by acceptance criteria and graft the best parts; use when two options are too close to call / a design has no precedent.
+---
+
+# arena — Parallel comparison selection
+
+## Triggers
+
+- A design fork has no precedent and two or more options are plausible.
+- The user says "compare them / build one each / pick one".
+- The choice locks in the shape of subsequent implementation, and choosing wrong is expensive to rework.
+
+## Core
+
+**Same brief, independent arms, a judge picks the base + grafts.** This is not implementing the same file in parallel; it is proposing in parallel, then choosing one base. Arms do not share context (to prevent anchoring).
+
+## Steps
+
+1. **Fix the brief**: goal, constraints, acceptance criteria, non-goals, evidence requirements. Each arm receives a **verbatim identical** brief.
+2. **Choose arms**: 2–3, with genuinely different axes—different models / architectures / data shapes. Do not run N homogeneous arms.
+3. **Dispatch in parallel**: one `task` batch; each arm returns: approach, trade-offs, risks, minimal proof (runnable prototype/test/pseudocode).
+4. **Judge**: score item by item against the acceptance criteria; choose **one base**; list the concrete parts to **graft** from the other arms; write one sentence on why each rejected option lost.
+5. **Land it**: implement the base + grafts; run `.agents/skills/blast-radius/SKILL.md` on the chosen design; then `verify --scope`.
+6. **Record it**: one row per arm in `workflow/delegations.md` plus the judge's conclusion; for long runs add one row to `decisions.tsv`.
+
+## Output
+
+| Arm | Approach | Strengths | Risks | Minimal proof | Verdict |
+|---|---|---|---|---|---|
+| A | … | … | … | … | base / graft X / reject |
+| B | … | … | … | … | … |
+
+- **Base**: who was chosen and why.
+- **Grafts**: which blocks are taken from other arms and how they are merged.
+- **Rejections**: one sentence of rationale per rejected option.
+- **Open**: product/preference calls that need the owner to decide.
+
+## Where it lives in this repo
+
+- Dispatch: the `tasks[]` batch of `task`; the `judgment` role in `model-roles.json`.
+- Review: after choosing the design, take it apart with multiple lenses per `.agents/skills/interrogate/SKILL.md`.
+- Proof: `.agents/skills/blast-radius/SKILL.md` (the reason it is safe is X, so run code to prove it).
+- Record: `workflow/delegations.md`; aggregate with `node .agents/scripts/agg-delegations.mjs`.
+
+## Boundaries
+
+- Arms do not share conclusions; sharing the brief is enough.
+- Do not merge all N options—pick one base, and grafts must be concrete down to file/function.
+- Do not use arena for coupled implementation (same file/contract); use serial instead.

package/locales/en/overrides/.agents/skills/autonomous-run/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: autonomous-run
+description: Unattended long-run contract — per-unit sign-off during long/overnight tasks, bottom-up landing, when to stop; for the main agent to establish before the user leaves (may be driven by pipeline-run).
+---
+
+# autonomous-run — Unattended contract
+
+Used for long runs (overnight / user away). **Advancement mode**: per-unit sign-off per this contract; orchestration may be driven by `pipeline-run`, or via `.agents/pipelines/` / manual stages. **No gate or confirmation gate is relaxed**; only the advancement rhythm and stop conditions are agreed.
+
+## Contract (once before starting)
+
+1. **Authorization surface**: write out allowed directories/branches and target documents for this run.
+2. **Forbidden list**: remote push, deploy, delete data, directly change workflow status, `--no-verify` — still require explicit user instruction.
+3. **Budget**: fix loop keeps the 3-attempt cap (same criteria as pipeline-run); no new budget.
+4. **Stop contact**: stop when the user returns, report current state.
+5. **Decision trace**: long runs/overnight record `decisions.tsv` per `.agents/skills/show-me-your-work/SKILL.md` (append-only, evidence is pointers); commit or not by stakes.
+
+## Per-unit sign-off (each implement / fix ticket)
+
+1. Implement per authorized files; deviation stops (out-of-plan files / public interfaces / new dependencies).
+2. Run `node .agents/scripts/verify.mjs --scope`, must exit code 0.
+3. Record the green evidence's `headShort` (s15 fingerprint); **HEAD changed or evidence older than 24h window → rerun**, do not reuse old green.
+4. Only after sign-off `next`; no advancement without green, no batching.
+
+## Landing order
+
+- Bottom-up by dependency, one commit per unit, Conventional Commits Chinese.
+- Do not merge commits across units; the next unit is based on the previous unit's signed-off HEAD.
+- After rework of the same unit, old evidence is void, re-sign-off.
+
+## Stop conditions (any triggers stop and report)
+
+- Fix loop reaches 3 attempts and still red.
+- Fingerprint mismatch / green evidence expired and still red after rerun.
+- Need out-of-scope files, public interface changes, or new dependencies.
+- Both hypotheses for the same root cause are falsified.
+- User returns or issues any new instruction.
+
+## Recovery
+
+After interruption rebuild first per `.agents/skills/session-resume/SKILL.md`; for pipeline-run run reconciliation use `status --run <id>`; signed-off units are not redone.
+
+## Report
+
+Stage bar / per-gate results / commit chain (sha + title) / open items and matters requiring user decision.

package/locales/en/overrides/.agents/skills/blast-radius/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: blast-radius
+description: Blast-radius proof for a small change — find the one fact behind "it is safe because X" and prove it by running code rather than writing a plausible-sounding explanation; use for reviews of the "what else could this break / a small diff makes me uneasy" kind.
+---
+
+# blast-radius — Impact proof
+
+## Triggers
+
+- The user asks "what else could this break / blast radius / anything missed".
+- The diff is small but crosses a function boundary, shared state, serialization format, DB column, or feature flag.
+- During review you are uneasy about "it should be fine" and need reviewable evidence.
+
+## Core
+
+**Do not trust your own written analysis.** An impact explanation always reads as correct, whether true or false. Find **the one or two facts** the whole judgment rests on and prove them by running code; if you cannot prove them, write `unproven`.
+
+Listing callers is not the skill—grep does that in a second. The skill is where grep stops: library source, pinned versions, runtime ordering, wire format, DB columns, another language reading the same bytes, downstream after three hops.
+
+## Certainty ladder (mark which level each fact stops at)
+
+1. **Because I say so**—not evidence on its own.
+2. **Points to a line**—a real `file:line`, or the library's own source.
+3. **Counter-example path exhausted**—step through the failure path and confirm it cannot be reached.
+4. **Ran it**—a small script/test calls real code and fails loudly if wrong.
+5. **Reproduced in the running app**—end-to-end evidence.
+
+Level 4 is usually a small script: import the same library the app uses, call the function you are worried about, assert the result.
+
+## Steps
+
+1. **Read the change**: diff, added/modified/deleted symbols, behavioral differences (including what the diff does not say). Use `git log -S`, `xd://lsp` references, and `kb-search` to fill in context.
+2. **Find the one safety fact**: most changes that look dangerous are safe because of one fact (e.g., "this call only drops dead cache entries and does nothing else"). Spend your time here, not on a long list of maybes.
+3. **Look where grep stops**: library source and pinned version, local patches, microtask/unmount/teardown ordering, JSON returned by APIs, DB columns, wire format, another language, feature flag, three-hop downstream.
+4. **List risks honestly**: give each a probability and cost, `file:line`, and how to check it; list confirmed-clean items separately. Not finding something is also an answer; do not invent callers or APIs.
+5. **Prove the one fact**: write a script/test that runs real code and paste the output. If you cannot prove it → `unproven`.
+6. **Large/broad changes**: have multiple models answer the same question independently, then merge—different models catch different real bugs.
+
+## Output format
+
+- **What changed**: including the non-obvious parts.
+- **Safe because**: the one fact + which ladder level it stops at + proof output; write `unproven` if unproven.
+- **Risks**: each = how it breaks + `file:line` + probability/cost + how to check; paste proof for the important ones.
+- **Ruled out**: checked, and why it is fine.
+- **Before merge**: the cheapest test/reproduction that can catch real bugs (including the script you wrote).
+
+## Where it lives in this repo
+
+- Review: `.agents/commands/review.md` P1 "Impact proof".
+- Design: contract-surface changes in the Design chapter of `.agents/commands/stages.md`.
+- Machine side: `verify-scope.mjs` only computes the diff surface; this skill adds "why it is safe".
+- Evidence: put proof scripts in `tmp/` or commit them with the PR; do not write conclusions only.
+- Boundary: this skill does not replace the `verify` gate; it proves "nothing else broke", not "this change is correct".

package/locales/en/overrides/.agents/skills/csharp-quality-gates/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: csharp-quality-gates
+description: C# backend quality gates — manual trigger entry for three deterministic gates — CRAP (complexity×coverage), mutation testing, duplicate code; built-in TEMP redirection for the local coverlet collection failure and discrimination of "is 0 coverage a collection fault or genuinely untested", report interpretation criteria, and test-backfill priority ordering; for questions like "is this change covered by tests / which methods should get tests first / is complexity or duplication over threshold / inventory the backend quality status". Command entry .agents/skills/csharp-quality-gates/scripts/quality-gates.mjs.
+---
+
+# csharp-quality-gates — C# backend quality gates (manual trigger)
+
+Backend code maps to ub-mode's three-stage discipline (Uncle Bob's crapper/dryer/mutator do not support C#, so this repo substitutes equivalents):
+
+| ub-mode gate | Uncle Bob original tool | This repo equivalent | Criterion |
+|---|---|---|---|
+| Crapper (Then Make it Right) | crapper | **dotnet-crap** (Crap4DotNet) | `CRAP = CC²×(1-cov)³+CC`, default threshold 30 |
+| Mutator (Then Make it Right) | mutator | **dotnet stryker** (Stryker.NET) | mutation score (killed/total) |
+| Dryer (Then Make it Right) | dryer | **PMD CPD** (`--language cs`) | structural duplication, token count |
+
+Below `qg` refers to `node .agents/skills/csharp-quality-gates/scripts/quality-gates.mjs`.
+
+## Trigger / do not trigger
+
+- **Trigger**: "backend quality status / does this change have test coverage / which methods need tests first / is complexity over threshold / any duplicate code / how to run mutation testing"; changes in `backend/` involving business logic; after completing a batch of tests wanting to verify "are the tests really testing".
+- **Do not trigger**: pure frontend changes (this repo's C# gates do not cover `frontend/`); only want to know "does it compile" (use `commit-check.config.json` build section); only want to know "do tests pass" (just `dotnet test`).
+- **Does not replace** the `verify` gate: this skill is a **manually triggered** diagnostic and inventory tool; it does not enter the commit gate and changes no gate configuration.
+
+## 0. Prerequisite probing
+
+```bash
+qg doctor
+```
+
+Prints item by item whether tools are in place: `dotnet` / `dotnet-crap` / `dotnet-stryker` / `pmd` / `java` / unit test project / solution. When missing, the script prints install commands:
+
+```bash
+dotnet tool install -g Crap4DotNet
+dotnet tool install -g dotnet-stryker
+# PMD: download pmd-dist-<ver>-bin.zip and extract to ~/.agents/tools/pmd/ (the level containing lib/ and conf/)
+```
+
+Actual machine paths are registered in `.agents/notes/runtime-env.local.md` (git-ignore, single-source discipline); the script resolves by `env var → known install location → PATH`, no hardcoded absolute paths.
+
+## 1. The three gates
+
+```bash
+qg coverage                 # run unit tests collecting coverage (TEMP redirection built in)
+qg crap [--threshold 30] [--top 15] [--min-crap N] [--coverage <absolute path>]
+qg dup [--minimum-tokens 100] [--top 10]
+qg mutate "<glob>"          # mutation testing, must be targeted
+qg all                      # coverage → crap → dup (no mutate, too slow)
+```
+
+Exit codes: `0` pass / `1` gate not met (methods over threshold, duplicate blocks, mutation score not met) / `2` usage·configuration·collection failure. **Exit code 2 is never "pass"**, it is "did not run".
+
+Artifacts land in `.agents/tmp/quality-gates/` (git-ignore): coverage XML, `crap-report.json`, Stryker report.
+
+## 2. Collection failure trap (known on this machine, must-read)
+
+**coverlet silently produces 0% coverage under the default TEMP on this machine.**
+
+- Symptom: tests all green, code genuinely calls production services, but cobertura has `lines-covered=0` — every class every line hits is 0.
+- Root cause: coverlet writes instrumented modules to `%TEMP%\<module name>_<guid>` before loading; the file is lost under default TEMP, testhost exits with an **unhandled** `FileNotFoundException` (process -532462766), hit data never reaches the report.
+- Criterion: tests clearly `new XxxService(...)` call production code, yet cobertura is all 0.
+- Fix: `qg coverage` already redirects `TEMP`/`TMP` to `.agents/tmp/quality-gates/tmp`; after redirection measured `lines-covered=23701/37805` (line-rate 0.6269).
+- **Script guard**: when `lines-valid>0 && lines-covered==0`, `coverage` **errors and exits 2**, producing no "zero coverage" conclusion; `crap` also refuses to run on such a file.
+
+> Two other dead ends on the same machine: `--collect:"Code Coverage"` (Microsoft.CodeCoverage) only produces a 0KB empty file; `/p:CollectCoverage=true` requires the `coverlet.msbuild` package (this repo only has `coverlet.collector`). **Do not spend more time on these two.**
+
+## 3. Report interpretation: first distinguish "collection broken" vs "code untested"
+
+Order cannot be reversed — first confirm collection is good, then discuss coverage.
+
+1. **Is collection trustworthy**: look at `qg coverage` output's `lines-covered`. 0 → collection failure (§2), fix collection first, **never treat 0% as a conclusion**.
+2. **CRAP table reading**: sort by CRAP worst to best; the top "both complex and uncovered" are the priority; **do not only look at CRAP absolute value** — a method with CC=2 but 100% coverage has CRAP=2, not a problem.
+3. **Mutation score reading**: a low score has two causes with completely different handling —
+   - (a) **tests ineffective**: few NoCoverage, low kill ratio → assertions too loose, tests pass but do not verify logic;
+   - **this repo empirically is (b)**: many NoCoverage (607/23274 mutants on code paths nobody tests) → **that path lacks tests**, not insufficiently strict assertions. Distinguish before acting.
+4. **Duplication detection reading**: PMD's `--minimum-tokens` is the similarity knob (default 100 ≈ dryer's 0.8 similarity tier); multiple hits within the same file prioritize structural duplication like "three places share the same helper" (`PurchaseOrderService.cs` 2026-10-31 baseline snapshot 451/775 lines, 62 lines/397 tokens; line numbers are baseline values, not current).
+
+## 4. Test-backfill priority
+
+**Criterion = zero coverage ∧ high CRAP**, not CRAP absolute value. The script already sorts by this (`qg crap` output's "zero coverage and over threshold" list).
+
+This repo 2026-10-31 baseline: 1622 total methods, **1264 zero coverage (78%)**, 323 over threshold, of which 319 are also zero coverage. Top:
+
+| Method | CC | CRAP |
+|---|---|---|
+| `PMLService.FinishMatchAsync` | 74 | 5550 |
+| `MaterialCodeImportService.PreviewAsync` | 58 | 3422 |
+| `OutboundOrderService.MatchAndLockCoreAsync` | 53 | 2862 |
+| `MaterialCodeService.CreateAsync` | 51 | 2652 |
+| `MaterialCodeImportService.ValidateImportRowsAsync` | 49 | 2450 |
+
+**Why 78% zero coverage**: services covered only by integration tests are blind spots at the regular tier — `tests/Shipyard.Material.IntegrationTests/` needs a DB; CI mid tier `backend-test` uses `--unit-only` (no test DB), full tier escapes via the shared dev DB because CI does not define `TEST_DB_CONN`. `ExchangeRateImportService` is typical: its only test is in the integration test project; replacing all Excel header strings with `""` in mutation testing still stays all green.
+
+Backfill directions are therefore two: **push DB-free pure logic down to unit tests** (Excel header/template generation, validation criteria), or **configure `TEST_DB_CONN` for CI** to run the real integration tier.
+
+## 5. Output format
+
+After the inventory, conclude in four sections:
+
+- **Current state**: numbers for each of the three gates (coverage line-rate / CRAP over-threshold count and share / duplicate block count / mutation score), noting whether collection is trustworthy.
+- **Risk**: top N methods sorted by "zero coverage ∧ high CRAP", with `file` location.
+- **Cause**: distinguish "tests ineffective" from "code untested"; if the latter, point out the blind-spot source (integration test tier / DB dependency / pure logic not pushed down).
+- **Next steps**: specific to "which method gets which test"; do not stop at "recommend raising coverage".
+
+## 6. This repo's placement and boundaries
+
+- Gate single source: `.agents/hooks/commit-check.config.json` (build section = `dotnet build Shipyard.Material.sln`; **checks section is currently empty**, local commit gate does not run tests). This skill **does not change** this file.
+- Interface with ub-mode: First Make it Work → add tests (give TDD a landing point); Then Make it Right → three gates; Practice → Keep a Log (this skill's conclusions are material for the decision log).
+- Interface with `review-method`: when reviewing a diff, "impact-surface proof" can use this skill's dup/crap as machine evidence.
+- Boundaries: run only the **unit test project** (integration tests need a DB, this machine without DB will hang); Stryker **must be targeted** (full 20k+ mutants unacceptable); write no repository files (except this skill's own directory); do not commit code.

package/locales/en/overrides/.agents/skills/dev-tour/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: dev-tour
+description: Turn spec/plan steps and changed files into an interactive development tour (overview/timeline/data flow/flow diagrams + file tree + change notes on the right). Used for the AI-Native development gap where "the document explains it but you cannot see which files change".
+---
+
+# Development tour (Dev Tour)
+
+## Goal
+Turn "steps × changed files" in workflow documents into a clickable map: left file tree (added/modified/planned badges), center overview/timeline/data-flow/flow diagrams, right per-step change notes and diff. Solves the gap "spec/plan reads fine but you do not know which file the AI is changing".
+
+## Trigger conditions
+- After drafting/confirming a plan (`## 任务拆解` or `## 步骤` + `## 改动方案` persisted) → run `auto-tour.mjs` to auto-start the dashboard and produce a live link.
+- Refresh once after each batch / task completed in Build stage.
+- Before close-out, do scope reconciliation: "actual changes outside the document" appearing in the map must first be explained or backfilled into the plan.
+- User says "can't see which files are changed" "show me the timeline/flow/overview".
+
+## Data contract (write documents this way)
+The generator does not create a separate ledger; it reads documents + git directly:
+
+1. **Steps** (priority high to low)
+   - `## 步骤`: `1. **T1 title**: one-sentence description`
+   - `## 任务拆解`: `- [ ] 1. title` + indented `- 文件：path` / `- 判据：…` / `- 留痕：…`; or `### T1 · title` subheadings (body detail lines close with the step). **Each implementation step has at least one file; pure verification steps state `验证步骤` in the title**
+   - `### 批次 0a：…` headings under `## 改动面` / `## 改动方案`
+   - If none: group by the architecture layer the file belongs to (**layer fallback = parse failure signal**; generator prints a "parse hits" line and the page top shows a warning bar; normalize headings then regenerate; `--strict` rejects production with exit 1)
+2. **Per-step files**
+   - In `## 改动方案` align with step numbers using `- **T1**：` or `### T1`, write backticked paths inside the block.
+   - L1 single-file plans may write `- \`backend/.../Foo.cs\`：what to do` directly in `## 改动方案`; each top-level file entry automatically becomes one station.
+   - Write full paths when possible; only writing `detail.vue` / `MaterialCodePushService.cs` also resolves by same-named repo file and step context, but full paths are most reliable. With multiple same-name candidates the generator scores by step context and guesses one: that file entry carries a `pathGuess` flag (page shows a "guess?" uncertainty badge), hit line counts "path guesses Z"; a unique basename hit is deterministic and not counted as a guess.
+   - Non-backticked mid-path tokens with code extensions and resolvable paths are also collected: bare tokens like `pml/index.vue` in step titles/body/table rows (containing `/` + a known code extension + resolvable to a real repo file) enter the model and are assigned to their step; mixed tokens (`if/else` etc.) are always rejected. When unbound files are assigned by body fallback (basename or layer-word arm) they all get `pathGuess`; the layer-word arm binds only when exactly one step body contains that layer word; ambiguous ones stay unbound and visible as "unassigned".
+   - Table row paths are also collected: `| \`path\` | description |` rows in `## 改动方案` are assigned to the current block/batch anchor (including tables inside `### 批次` subsections); without an anchor they go to "change surface (unassigned)". Task row labels support union-style `1. S1+S2：title` (block anchor matched by member intersection; parenthetical `（**S3**）` also anchors); resolution never fabricates — directory back-inference/anchor splicing must land on real repo files; unresolved paths remain as visibly unresolved.
+3. **Test files**: write in `## 验证计划` or the corresponding step; test steps close automatically.
+4. **Dependencies** (optional, side-arc data source for the flow diagram)
+   - Clause lines in `## 执行顺序` like `依赖：3 依赖 1；4/5 依赖 2 与 3；8 依赖 4~7；10 依赖全部` (arrow chain lines `1 → 2 → 3` are expressed by the main chain itself and do not produce duplicate edges).
+   - Or in task lines `- 依赖：T1、T2`.
+   - Numbers normalized by step sequence / `Tn` / label id; unresolvable references counted into `deps.unresolved` and warned.
+5. **Actual changes**: `git diff --base` automatically fills status, line counts, and diff; files not registered in the document go to "actual changes outside the document" and are not silently dropped.
+
+## Generation / refresh
+```bash
+# static snapshot (default .agents/cache/tours/<type>-<name>.html)
+node .agents/scripts/gen-dev-tour.mjs workflow/plans/<name>.md
+
+# compare the entire committed task (default HEAD = current uncommitted working tree)
+node .agents/scripts/gen-dev-tour.mjs workflow/plans/<name>.md --base origin/main
+
+# model only (debug parsing)
+node .agents/scripts/gen-dev-tour.mjs workflow/plans/<name>.md --json
+
+# gate mode: reject production on layer fallback/no steps/implementation step without files (exit 1; pure verification steps exempt by title)
+node .agents/scripts/gen-dev-tour.mjs workflow/plans/<name>.md --strict
+```
+
+Each generation prints a "parse hits: direct X/Y steps … · path guesses Z" line — if the direct-hit rate <100%, first check whether headings broke the contract, then decide whether to accept fallback grouping; after the hit line it prints "⚠ line N: <title>: <reason>" line by line, locating contract breaches to lines (step has no aligned file block / file block anchor aligns with no step / dependency reference unresolved / layer fallback triggered, corresponding to `parseHealth.issues` `{line,title,kind}` in the model; `pathGuess` and issues are advisory and never participate in `--strict` production rejection). The page-top warning bar consumes the same issues: merged by `kind` into "file block unaligned / step missing files / dependency unresolved" classes, expanded line by line within groups; entries in `step-no-files` whose title contains "验证步骤/单测/UI 实测/静态门" are listed separately as "verification steps" and not counted as to-fix.
+
+Live version (recommended to keep open during Build):
+```bash
+# auto-start dashboard + print this plan's live link (idempotent reuse, no browser popup; failure only warns, does not block)
+node .agents/scripts/auto-tour.mjs workflow/plans/<name>.md
+# → http://127.0.0.1:8933/tour?file=workflow/plans/<name>.md
+
+# start dashboard only, no document specified
+node .agents/scripts/ensure-board.mjs
+```
+The live page pulls `/api/tour` every 5s; document save / working-tree changes redraw automatically, preserving the currently selected step and view.
+
+## Views
+- **Overview**: default grid (one large card per station, read by number); top-right "Layout" switches to a horizontal timeline; "Focus overview" hides left/right columns, 6 stations usually fit in two rows.
+- **Timeline**: arrows connect per-step files by architecture layer (frontend → API → application → domain → infrastructure → DB); test steps add dashed verification arrows.
+- **Data flow**: statically identify cross-file data objects (Dto/entity/table) from diff added lines and document body, show layers and files the object flows through by architecture-layer swimlanes, and list "definition step → usage step" transfer edges; clicking an object links steps/files (data from model dataflow, schema 2; view hidden when no recognized result).
+- **Flow**: plan → steps → verification gate → close-out; verification gate reads `## 验证计划`. When model `deps.edges` is non-empty, the main chain's left thin rail draws side arcs for declared dependencies (transitively reduced; adjacent main-chain edges not drawn twice; pointing to a prior row = anomalous reverse dashed line); hovering a step highlights its upstream/downstream arcs and counterpart steps.
+- **Requirements**: follow "corresponding entry/spec：…" links to read upstream documents (one level, no recursion, at most 3 documents), render this document's goal + upstream intent/spec/incident goals and behavior/acceptance points (model `doc.upstream`); view hidden when no upstream docs, requirement narrative then only this document's purpose.
+- **Verification**: left plan checklist (`## 验证计划`), right actual evidence — local `.agents/verifications.jsonl` preferred, repo `workflow/verify-evidence.md` fallback merged (dedup by ts+head), take the latest 10 within the document date time window (model `evidence`). The association semantics is "verification evidence within the task time window", not per-item binding; the flow verification gate also shows the latest evidence within the window; view hidden when none.
+- **Interlink**: clicking a station/file/step card/timeline message syncs the left tree and right notes; `←/→` switch steps, `Esc` clears; "Follow the flow" auto-plays.
+
+## Applicable scale (verified 2026-11-11)
+Reproduction: `node .agents/tests/tools/gen-synthetic-plan.mjs --bench` (synthetic plan lands in `.agents/cache/tour-perf/`; build timing uses `buildTour({git})` injecting 300 modified files, max of 3 rounds; HTML generated by `gen-dev-tour.mjs --no-diff`, git side is the real working tree at that moment, size dominated by the document side).
+
+| Tier | buildTour (300 diff files injected) | Static HTML size |
+| --- | --- | --- |
+| 10 steps | 317–332 ms | ~100 KB |
+| 30 steps | 348–350 ms | ~131 KB |
+| 60 steps | 474–483 ms | ~178 KB |
+
+Boundary statement: verification covers ≤60 steps / 300 diff files, and within this range build time has no knee (far below 5s); beyond this range unverified, do not conclude by linear extrapolation. Browser-side verification (Chrome, file:// static page, 60-step tier): 1868 DOM nodes per page, 289ms load, six-view switching 14–22ms each — no virtualization needed at this magnitude.
+
+## Boundaries
+- The document is the plan side, git is the actual side; on conflict the map shows split columns (plan / outside document).
+- Does not replace the plan's acceptance criteria and `check-scope.mjs`; it only visualizes the same facts, adding no new source of truth.
+- Generated artifacts default to `.agents/cache/tours/`, not committed; to archive use `--out wiki/...` or screenshots, do not stuff HTML into workflow/.
+- View usage data (`/api/tour/usage`) lands only locally in `.agents/cache/tour-usage.jsonl`, not committed or sent out; after one iteration trim the least-used views by usage rate (data-flow view is the primary observation target), do not build a query aggregation page, use node directly for stats.
+- Engine surface (`.agents/`) changes still go through `check-scripts-syntax` and other gates; this skill waives no gate.
+
+## Acceptance
+- [ ] Document has ≥1 step; each step has at least one file, or is explicitly `验证步骤`.
+- [ ] "Parse hits" has no layer fallback (no page warning bar); fallback = heading contract breach, fix the document first.
+- [ ] "Actual changes outside the document" in the map is empty, or explained/backfilled.
+- [ ] The four views switch without blanks; clicking a file locates the step and diff.
+- [ ] The live page shows "live" next to the title, falls back to "polling" when disconnected.

package/locales/en/overrides/.agents/skills/dream/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: dream
+description: "Offline Dreaming — periodic memory maintenance modeled on Anthropic's memory architecture: run the dream-run audit, read the report, delegate independent-reviewer to check AI Judge samples, write back papercuts/correction notes, and dispose of cold-data candidates; for use by the main agent when executing the Dreaming continuous-run loop within a session."
+---
+
+# dream — Offline Dreaming continuous-run loop
+
+## Triggers
+
+- A `[dream]` advisory appears post-commit (≥7 days since the last audit, or no report).
+- A session-resume rebuild finds `tmp/dream-report-*.md` or `tmp/dream-judge-brief-*.md`.
+- The user explicitly asks to "run the dream audit / Dreaming".
+
+## 1. Run the audit
+
+```bash
+node .agents/scripts/dream-run.mjs              # dry-run: read-only audit + AI sampling brief (default)
+node .agents/scripts/dream-run.mjs --execute    # execute safe fixes (terminal-state artifact archiving + index regeneration only)
+```
+
+- The report lands in `tmp/dream-report-<date>.md` (gitignored); the AI Judge brief lands in `tmp/dream-judge-brief-<date>.md`.
+- `--execute` only performs "terminal-state artifact archiving + index regeneration" and rewrites no document content.
+- Does not auto commit / push (root AGENTS.md prohibition).
+
+## 2. Read the report
+
+Read the latest `tmp/dream-report-*.md`, focusing on:
+
+- A terminal-state artifact archiving (archive-sweep, 21-day window);
+- B index drift and three-way wiki consistency;
+- C full reconciliation (check-loop, hard 6 segments);
+- D error-class candidates (agg-judgments --retire-candidates);
+- E resident-surface budget (rule-budget --all);
+- E2 cold-data candidates (agg-kb-usage --stale-days 90)—access/hit telemetry + confidence decay, see §5;
+- F AI Judge sampling audit brief.
+
+## 3. Verify AI Judge samples
+
+1. Read `tmp/dream-judge-brief-*.md`;
+2. Copy the "Judge delegation template" at the end of the brief to the independent-reviewer role for verification;
+3. Handle the verification conclusion as BLOCK / WARN / OK:
+   - **BLOCK**: correct the workflow document claims against the original evidence (do not auto-commit after the fix);
+   - **WARN**: record a papercut or add evidence;
+   - **OK**: no action.
+
+## 4. Write back
+
+- Error-class candidates: handle via the recurring-error loop in `.agents/skills/papercut-fix/SKILL.md` (≥3 occurrences → establish a rule; placement ladder: type→gate→test→smoke→prompt).
+- Verification findings: correction notes / record in `workflow/papercuts.md`.
+
+## 5. Dispose of cold-data candidates
+
+- Cold-data candidates come from `agg-kb-usage.mjs` (telemetry basis: neither hit by kb-search nor content-updated in the last 90 days).
+- Disposal ladder (adjudicated by the main agent/user):
+  1. Archive: `node .agents/scripts/archive-sweep.mjs --execute` (terminal-state artifacts, 21-day window);
+  2. Update: update the knowledge via the wiki skill;
+  3. Delete: **requires an explicit user instruction** (root AGENTS.md irreversible-operation red line).
+
+## Red lines
+
+- `--execute` only archives + regenerates indexes; it does not rewrite document body text.
+- No auto commit / push; deleting wiki files requires an explicit user instruction.
+- This skill is the execution loop: the AI performs judgment, and deterministic scripts only sample and collect evidence ("deterministic scripts own facts, the model owns judgment").