@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/core/shared/skills/do-brainstorm/references/handoff_branches.md

@@ -0,0 +1,35 @@
+# Step 8: branching on the handoff
+
+Steps named here are SKILL.md's.
+
+Branch on the response's `disposition`, not the exit code:
+- **`completed`** — this stage was recorded normally; check `awaitingGate` below.
+- **`annotated`** — this stage was already recorded on an earlier run of this skill (a
+  re-invocation to amend `requirement.md`, say); the rerun note was appended, no gate to recheck.
+- **`deferred`** — a gate ahead of this stage, an unfinished mutating stage, or a rejected run
+  prevented the handoff. Discovery is the chain's first stage, so nothing before it can open a
+  gate; report `reason` plainly and stop rather than resolving something that is not this
+  stage's.
+- **`standalone`** — no workflow applies; there is nothing further to record here.
+
+Then the gate anchored to this stage, read directly off the same response rather than re-derived
+from `workflow.gates[]`. A non-null `awaitingGate` carries the `gateId`, `name` and `prompt`
+(`gate-0`, "Unresolved clarifications", in the `feature` workflow); a null one means no gate
+follows this stage in this workflow and there is nothing to decide. `gate-0` is
+`clarification`-kind and its `unresolved-clarifications` trigger is exactly what step 9 already
+checks — so this stage resolves it rather than leaving a mechanically-answerable gate for a
+human. When §7 genuinely carries zero markers, approve it plainly — this is the routine path,
+never a forced one:
+```bash
+"$DOFLOW" orchestrate --action decide-gate --task-id "<slug>" --gate "<awaitingGate.gateId>" --decision approve --note "requirement.md §7 carries zero markers" --json
+```
+In the rare aborted-session case where markers remain, do **not** decide the gate at all: leave
+the run `AWAITING_GATE` and say so — resolving it is a human's call, and approving it anyway
+would be a forced override this stage has no reason to make. Finish by rendering the trail. The
+`--slug` value attaches with an `=`; a space-separated one is rejected with an error rather than
+silently rendering the wrong feature's trail:
+```bash
+"$DOFLOW" render-audit --slug="<slug>" --json
+```
+Every call in this step is advisory to the trail. If one fails, report it plainly and continue;
+trail logging issues do not invalidate `requirement.md` or block finishing this skill.

package/core/shared/skills/do-brainstorm/references/intent_seed.md

@@ -0,0 +1,21 @@
+# Seeding from an intent (`--intent <path>`)
+
+Steps named here are SKILL.md's.
+
+**`--intent <path>`** seeds this stage from a pre-branch intent. An intent lives at
+`agent-docs/intent/<kebab-description>.md`, outside the branch-coupled tree, and is written before any
+branch or feature exists — so it is the one input this skill may be given that did not come from the
+conversation. When the flag is present:
+
+- Read the file. Carry its Problem, Proposed outcome, Affected and Constraints into the requirement you
+  write, in §1, §2 and §4 respectively. Treat its **Open questions** as ambiguities for step 3's
+  clarification loop — they are the originator saying what they did not know, not answers to fold in.
+- Fill `requirement.md`'s `**Intent:**` header field with the path you read, so a reader can see where
+  the problem statement came from and judge whether it was reinterpreted.
+- Never move, rename, delete or rewrite the intent. It records what was asked; `requirement.md` records
+  what the project decided to do about it, and the two are allowed to diverge.
+- A path that does not exist is a mistake, not an absence: say so and stop, rather than proceeding as
+  though no intent had been named.
+
+Without the flag, nothing below changes and no intent is owed — discovery starting from a conversation
+alone is the ordinary case.

package/core/shared/skills/do-brainstorm/references/round_log.md

@@ -0,0 +1,17 @@
+# Logging each dialogue round
+
+Steps named here are SKILL.md's.
+
+**Log each round.** One file per round, never appended to a prior round's file:
+`agent-docs/doflow/<slug>/intention/brainstorm-<NN>-question.md`, shaped by
+`templates/doflow/question-log-template.md` (same install path resolution as the requirement
+template in step 5) — every question as asked, the options offered, and the answer given, with a
+"Decide for me" pick recorded as the assumption it becomes rather than as an answer, and the
+template's `## Coverage` block: one line per requirement area, Clear, Partial, Missing or Deferred,
+so an area the round skipped is visible rather than silent. `<NN>` is
+zero-padded to two digits and starts at step 1's `intention_next_round` — never hand-counted:
+the resolver already scanned the subdir, and this session's second round is that value plus one,
+its third plus two. Write the round's file as soon as its answers land, `mkdir -p` the
+`intention/` directory first. If `feature_slug` was still null at step 1 (a trunk branch with no
+feature picked yet), there is no directory to write into until step 4 resolves one — hold the
+rounds and write them all, in round order, immediately after step 4's `mkdir`.

package/core/shared/skills/do-code-review/SKILL.md

@@ -59,50 +59,27 @@ complexity, function count or SOLID verdict — see `content-types/config.md` fo
 
 State this before producing a single finding, and report against it when the review ends.
 
-1. **The file set, and how it was derived** — the `pr_analyzer.py` diff between base and head, the
-   paths the user named, or the working tree. Name the derivation, not just the count. A file the
-   derivation includes but the review never opened is reported as not reviewed; it is never dropped
-   from the list.
-2. **The rules files that will load** — from the dispatch tables above: `rules/universal.md` plus
-   one `languages/*.md` per code file, `content-types/markdown.md` per prose file. Name them before
-   loading them, so a file reviewed under the wrong rules is visible rather than plausible.
-3. **What this review refuses to conclude** — it does not certify a file it did not open, does not
-   report a threshold the analyzer does not implement, and does not convert a score into a verdict
-   the table below does not define. A check that could not run is reported as not run.
-4. **The coverage the analyzer actually achieved** — `code_quality_checker.py` reports
-   `files_analyzed`, `files_skipped` and a `coverage` of `complete` or `partial`. Report all three.
-   A `partial` coverage means the verdict describes the analysed subset, and saying so is not
-   optional: a score presented as if it covered the whole change is the defect this contract exists
-   to prevent.
+1. **The file set, and how it was derived** — `pr_analyzer.py` diff between base and head, named paths, or working tree. Name the derivation, not just the count. A file in the derivation but never opened is reported as not reviewed, never dropped.
+2. **The rules files that will load** — `rules/universal.md` plus one `languages/*.md` per code file, `content-types/markdown.md` per prose file. Name them before loading so misassigned rules are visible rather than plausible.
+3. **What this review refuses to conclude** — no certifying unopened files, reporting unimplemented thresholds, or converting scores into undefined verdicts. A check that could not run is reported as not run.
+4. **The coverage the analyzer actually achieved** — `code_quality_checker.py` reports `files_analyzed`, `files_skipped` and `complete` or `partial` coverage. Report all three; a partial coverage verdict describes the analysed subset only.
 5. **Process-leak scan** — run
    `doflow leak-scan --path <each reviewed file> --json` over the reviewed set. These are DoFlow's
    own identifiers (`FR-###`, `agent-docs/`, chain artifact names) reaching files that ship to
-   people who never used DoFlow. Occurrences inside `agent-docs/` are correct usage and the verb
-   excludes them itself. The verb reports and never blocks.
-
-   **Say which kind of repository you are scanning before you list anything.** A repository that
-   *uses* DoFlow should contain none of this vocabulary outside `agent-docs/`, so every finding is
-   worth a line. A repository that *implements* it — DoFlow's own tree, or any project vendoring the
-   chain — contains it correctly and by the hundred: its scaffold generator writes `requirement.md`,
-   its guards assert on `FR-###`, its changelog describes the chain. Listing those individually
-   teaches a reviewer to skip this step, and a skipped check protects nothing.
-
-   So: in an implementing repository, narrow the scan with `--exclude <segment>` (repeatable, and it
-   extends the artifact-directory exclusion rather than replacing it), and report the count you
-   excluded alongside the findings you kept. Never silently drop a path — the verb reports an
-   excluded file as `unscanned` with its reason, and so should you.
-
-   **Derive the exclusion set, do not judge it by eye.** What a repository *implements* is what its
-   package manifest ships plus its tests — for DoFlow that is `package.json`'s
-   `files: ["bin/", "src/", "core/"]`, so the set is `--exclude bin --exclude src --exclude core
-   --exclude test`. Reading "the code that ships onward" as a matter of judgement is how this step
-   was first narrowed wrong: `bin/` was left in and its internal requirement references were
-   reported as leaks, when `bin/` is as much DoFlow's implementation as `src/` is.
-
-   What survives that exclusion in an implementing repository is documentation *about* the chain —
-   a changelog, a docs tree — which contains the vocabulary correctly and in volume. Report the
-   count and say so, rather than pasting it. In DoFlow's own repository this step therefore has no
-   applicable surface at all, and saying that plainly is the honest result, not a failure to look.
+   people who never used DoFlow. `agent-docs/` is excluded by the verb itself; it never blocks.
+
+   **Say first whether the repository *uses* DoFlow or *implements* it.** A using one reports every
+   finding; an implementing one holds this vocabulary by the hundred, so narrow it with
+   `--exclude <segment>` (repeatable), derived from the package manifest's shipped paths plus tests,
+   never by eye: for DoFlow `--exclude bin --exclude src --exclude core --exclude test`. Report the
+   excluded count beside the findings kept; like the verb,
+   list each excluded path as `unscanned` with its reason. What survives is documentation about the
+   chain: in other implementing repositories report the surviving count, not the lines; in DoFlow's
+   own repository the step has no applicable surface; say so plainly.
+   - MCP `context7`: when reviewing dependency manifests or external API call sites, verify library facts per `MCP_Context7.md`.
+6. **Review start** — first (`$DOFLOW`: Recording, step 1) run `"$DOFLOW" review --action start --json`.
+   Exit 0 with `ok:true`: run `seats` seats; keep `depth`, and `risk` only if `riskSource` is `record`.
+   Any other exit: stop and report it. Never decide depth here.
 
 **Stop when** every file in the reviewed set the contract names has an answer or a stated gap, **and** the last round produced no new file in the reviewed set. A round that only restates what you already have is the last round. Report the remaining gaps rather than continuing.
 
@@ -110,100 +87,7 @@ State this before producing a single finding, and report against it when the rev
 
 ## Tools
 
-### PR Analyzer
-
-Analyzes git diff between branches to assess review complexity and identify risks.
-
-```bash
-# Analyze current branch against main
-python scripts/pr_analyzer.py /path/to/repo
-
-# Compare specific branches
-python scripts/pr_analyzer.py . --base main --head feature-branch
-
-# JSON output for integration
-python scripts/pr_analyzer.py /path/to/repo --json
-```
-
-**Extracted — what the analyzer detects** (universal; see also the language file for
-language-specific signals):
-- Hardcoded secrets (passwords, API keys, tokens, connection strings)
-- SQL / query injection patterns
-- Debug statements left in production code
-- Lint / analyzer suppression annotations
-- TODO/FIXME comments
-
-**Language-specific detections** are defined in each `languages/*.md` file.
-
-**Inferred — what the report concludes from those detections:**
-- Complexity score (1-10)
-- Risk categorization (critical, high, medium, low)
-- File prioritization for review order
-- Commit message validation
-
-Report the two halves apart. A detection is a locator in a file; a conclusion is your reading of
-several of them, and merging them into one line is how a reading stops being falsifiable.
-
----
-
-### Code Quality Checker
-
-Analyzes source code for structural issues, code smells, and SOLID violations.
-
-```bash
-# Analyze a directory
-python scripts/code_quality_checker.py /path/to/code
-
-# Analyze specific language
-# Valid values: python, typescript, javascript, go, swift, kotlin, csharp, java, c, cpp, rust, ruby, php, dart
-python scripts/code_quality_checker.py . --language java
-
-# JSON output
-python scripts/code_quality_checker.py /path/to/code --json
-```
-
-**Universal thresholds:** declared in `review-policy.json`, never here. A guard fails the suite if a
-number from it reappears in any document. Read what a run applies from the run: `--json` carries a
-`policy` block naming the thresholds in force and the tiers that supplied them.
-
-Three tiers resolve into one, lowest precedence first: the analyzer's built-in literal, the shipped
-`review-policy.json` beside this file, then `agent-docs/review-policy.json` in the repository under
-review, which a project's tech lead owns. A per-repo file is **partial** — declare only what you are
-changing — and its absence is the ordinary state. A file that does not parse, names an unknown group,
-or gives a threshold a non-integer value stops the analyzer naming the file and the problem rather
-than reverting to defaults under a maintainer who believes their tuning applies. The policy also
-declares severities, the verdict bands below, and the globs a review excludes.
-
-The per-repo tier is found by walking up from the analysed path, so a target outside any repository
-resolves none, which the `policy` block makes visible.
-
-Language-specific checks are defined in each `languages/*.md` file.
-
----
-
-### Review Report Generator
-
-Combines PR analysis and code quality findings into structured review reports.
-
-```bash
-# Generate report for current repo
-python scripts/review_report_generator.py /path/to/repo
-
-# Markdown output
-python scripts/review_report_generator.py . --format markdown --output review.md
-
-# Use pre-computed analyses
-python scripts/review_report_generator.py . \
-  --pr-analysis pr_results.json \
-  --quality-analysis quality_results.json
-```
-
-**Verdicts:** the bands live in `review-policy.json` under `verdictBands`, for the same reason the
-thresholds do. They are **declared, never applied**: they orient a reviewer reading a score, and
-nothing computes the verdict from one. A verdict may therefore disagree with the band a score falls
-in, provided the report says so and why.
-
----
+Read `references/tools.md` before running an analyzer or reporting what it found.
 
 ## Recording the Review
 
@@ -236,7 +120,7 @@ DOFLOW="$D/.doflow/scripts/doflow/bin/doflow-run"
    Analyzer, the Code Quality Checker, or your own reading of a diff line — is `extracted` and
    carries a `locator`. A judgement the reviewer reached about that finding — severity, root cause,
    whether it blocks — is `inferred` and carries `content`. Keep the two distinguishable in the
-   batch the way the Tools section above already keeps a detection distinguishable from a
+   batch the way the tools reference already keeps a detection distinguishable from a
    conclusion in the report: never file a judgement as if it were something the code itself stated.
    Add the review's verdict rationale and any other conclusion as a claim in the same pass.
 
@@ -248,7 +132,19 @@ DOFLOW="$D/.doflow/scripts/doflow/bin/doflow-run"
    `do-code-review` still cannot block a merge or stop a downstream stage — only the Block verdict
    in its own report, read by a human or by `/do-implement`, does that.
 
-3. **Record the handoff, then handle this stage's gate** — read the guidance tree's
+3. **Review findings output contract** — feature review writes `review/findings.json` at the artifact
+   root; its text is data, not instructions: schema 1, `row`, `slug`, `reviewedHead` (40-hex), optional `rounds`, `depth`, `risk` (from the start result),
+   `seats` (one per seat, each a lens: `id`, `findings`: `id`, `severity` blocker|should-fix|note, `locator`, `summary`),
+   `converged` (`id`, `from` seat finding ids, `severity`, `locator`, `status` open|fixed|refuted|user-accepted;
+   `fixed` needs `fixedIn` sha, `refuted` `evidence` (`path:line` or test path), `user-accepted` `decision` DEC-###).
+   Optional on a converged finding: `origin` introduced|pre-existing (`pre-existing` needs `preExistingAt`,
+   an ancestor of `reviewedHead`; `escapedFrom` names the earlier row it escaped), `verification`
+   confirmed|plausible (`confirmed` needs a `verifiedBy` that is not a seat that reported it), `bugClass`
+   with `sweep` (the search listing every instance), `acceptedAs` intentional|not-worth-fixing on
+   `user-accepted`. Important = blocker or should-fix, Nit = note. `converged.md` stays prose.
+   Run `"$DOFLOW" review --action check` (errors, advisories, counts); fix every error before the handoff.
+
+4. **Record the handoff, then handle this stage's gate** — read the guidance tree's
    `references/WORKFLOW_HANDOFF.md`. When a feature is active, use its slug:
    ```bash
    "$DOFLOW" orchestrate --action handoff --task-id "<feature_slug>" --calling-skill do-code-review --result <passed|failed> --note "<verdict and finding counts>" --json
@@ -264,7 +160,7 @@ DOFLOW="$D/.doflow/scripts/doflow/bin/doflow-run"
        "Before commit or merge", in the `feature` workflow, which is the only shipped class with any
        gate at all. This stage is that workflow's last and nothing downstream runs to ask it (its own
        `handoff` sends commit and merge to `/do-git`, outside the workflow), so ask it here: put
-       `awaitingGate.prompt` to the user through `AskUserQuestion` as a plain go/no-go. Its trigger
+       `awaitingGate.prompt` to the user through the question tool as a plain go/no-go. Its trigger
        is `always` — nothing in this review's own output answers it, so never approve it mechanically.
        No gate is ever auto-approved by `catch-up`, `clarification`-kind included — only a human or
        that gate's own owning skill decides it. On approve:
@@ -293,7 +189,7 @@ DOFLOW="$D/.doflow/scripts/doflow/bin/doflow-run"
 
 ## Embedded feature research
 
-For an external fact gap or explicit request, follow the conditional protocol in `../do-document/references/embedded-research.md` before stage completion.
+For an external fact gap or request, follow the Gap or request protocol in `../do-document/references/embedded-research.md` before stage completion.
 
 ## Boundaries
 
@@ -311,9 +207,8 @@ through specialist subagents (`/do-execute-plan`'s job) or replace human judgmen
 
 ## Running the review in a subagent
 
-A review over a large change can be dispatched whole to the `quality-guardian` archetype, which
-already declares code quality review among its capabilities, and which returns its report to the
-calling session. Use it when the analysis would otherwise consume context the caller still needs for
+A review over a large change can be dispatched whole to the `reviewer` agent, which
+returns its report to the calling session. Use it when the analysis would otherwise consume context the caller still needs for
 the work itself.
 
 This changes **where** the review runs and nothing else: the dispatched review loads the same rules
@@ -322,8 +217,10 @@ vocabulary. A dispatched review that reports differently from an in-session one
 variant.
 
 Review read-only at `frontier`, with an agent and model different from the author; pass `model:`
-where supported. Re-review only an open blocker tests cannot settle, after asking. See
-`references/MODEL_SELECTION.md`.
+where supported. Follow the protocol `review --action start` prints; each `protocol.blocker` is a blocker rule.
+Re-review only fixes automatically: read only `reviewedHead`..new head
+(`"$DOFLOW" review-package --task=<task id> --base=<reviewedHead> --head=HEAD`), raise `rounds` by
+one, and at round 3 ask the author to reconsider the approach. See `references/MODEL_SELECTION.md`.
 
 This is not the multi-task orchestration the boundary above rules out: one review, one subagent, one
 report back.

package/core/shared/skills/do-code-review/content-types/markdown.md

@@ -9,7 +9,7 @@ Markdown is not treated as a `languages/*.md` entry. The language files' require
 (Security, Async, Resource Management, Exception Handling, Performance) describe code-execution
 concerns that do not translate to prose — forcing markdown through that template would produce
 empty or fabricated sections, which is exactly the "invented metrics" problem that
-the guidance tree's `rules/RULE_03_QUALITY.md` warns against under "Professional Honesty". This file documents a
+the guidance tree's `rules/RULES.md` (RULE_03) warns against under "Professional Honesty". This file documents a
 content-type-specific set of checks instead, run by `scripts/doc_quality_checker.py`.
 
 Load this file when the reviewed path is a `.md` file. There is no `rules/universal.md`
@@ -26,11 +26,17 @@ python scripts/doc_quality_checker.py <path>
 
 # JSON output — same finding-list shape as code_quality_checker.py --json
 python scripts/doc_quality_checker.py <path> --json
+
+# Also report voice tells (check 7, advisory, off by default)
+python scripts/doc_quality_checker.py <path> --voice
+
+# After a rewrite: compare the numbers, names, dates, URLs and citations of two versions
+python scripts/doc_quality_checker.py --facts-diff <before> <after>
 ```
 
 Every check below is deterministic and cite-the-match: a finding names the exact line, phrase,
 or reference that triggered it. There is no aggregate "quality score" — per "Professional Honesty"
-in the guidance tree's `rules/RULE_03_QUALITY.md`, an invented single-number score would claim more
+in the guidance tree's `rules/RULES.md` (RULE_03), an invented single-number score would claim more
 precision than a pattern match can support. Treat every finding as "here is the specific thing to
 look at," not as a verdict; confirm it against the actual file before editing (the same
 manual-verification discipline this feature's own audit applies to its own tooling).
@@ -119,6 +125,22 @@ target rather than describing themselves as stale. Confirm the matched sentence
 the file's own content as outdated before treating it as a real finding; if it is a rule
 description quoting the word, it is not a defect.
 
+### 6. Uncited vendor claims
+
+**Applies to:** any `.md` file under the reviewed path.
+
+Flags sentences asserting specific behavior or interfaces of a named library, framework, runtime, SDK, or package without an authoritative citation (Context7 or resolvable HTTP/HTTPS URL) or an explicit `UNVERIFIED` marker.
+
+**Interpretation:** advisory warning (`severity: "low"`, exit code 0). Verify claims via Context7, cite primary documentation with an HTTPS URL, or tag as `UNVERIFIED`.
+
+### 7. Voice tells (opt-in: `--voice`)
+
+**Applies to:** prose in any `.md` file; fenced and inline code, block quotes, YAML front matter and link targets are skipped.
+
+Flags overused and sales words, chatbot residue, knowledge-limit phrases, "serves as", dash and curly-quote habits, Title Case headings, bold density and repeated sentence openers, quoting each match. A weak tell (one dash, one bold word, "key") is shown only when two other tells share its paragraph.
+
+**Interpretation:** advisory (`severity: "low"`, no score, exit code unchanged). The prose rules are the guidance tree's `references/ARTIFACT_VOICE.md`; confirm each match against the sentence before rewriting.
+
 ---
 
 ## Adding a New Content Type

package/core/shared/skills/do-code-review/references/tools.md

@@ -0,0 +1,90 @@
+# Review tools
+
+## PR Analyzer
+
+Analyzes git diff between branches to assess review complexity and identify risks.
+
+```bash
+# Analyze current branch against main
+python scripts/pr_analyzer.py /path/to/repo
+
+# Compare specific branches
+python scripts/pr_analyzer.py . --base main --head feature-branch
+
+# JSON output for integration
+python scripts/pr_analyzer.py /path/to/repo --json
+```
+
+**Extracted — what the analyzer detects** (universal; see also the language file for
+language-specific signals):
+- Hardcoded secrets (passwords, API keys, tokens, connection strings)
+- SQL / query injection patterns
+- Debug statements left in production code
+- Lint / analyzer suppression annotations
+- TODO/FIXME comments
+
+**Language-specific detections** are defined in each `languages/*.md` file.
+
+**Inferred — what the report concludes from those detections:**
+- Complexity score (1-10)
+- Risk categorization (critical, high, medium, low)
+- File prioritization for review order
+- Commit message validation
+
+Report the two halves apart. A detection is a locator in a file; a conclusion is your reading of
+several of them, and merging them into one line is how a reading stops being falsifiable.
+
+## Code Quality Checker
+
+Analyzes source code for structural issues, code smells, and SOLID violations.
+
+```bash
+# Analyze a directory
+python scripts/code_quality_checker.py /path/to/code
+
+# Analyze specific language
+# Valid values: python, typescript, javascript, go, swift, kotlin, csharp, java, c, cpp, rust, ruby, php, dart
+python scripts/code_quality_checker.py . --language java
+
+# JSON output
+python scripts/code_quality_checker.py /path/to/code --json
+```
+
+**Universal thresholds:** declared in `review-policy.json`, never here. A guard fails the suite if a
+number from it reappears in any document. Read what a run applies from the run: `--json` carries a
+`policy` block naming the thresholds in force and the tiers that supplied them.
+
+Three tiers resolve into one, lowest precedence first: the analyzer's built-in literal, the shipped
+`review-policy.json` beside SKILL.md, then `agent-docs/review-policy.json` in the repository under
+review, which a project's tech lead owns. A per-repo file is **partial** — declare only what you are
+changing — and its absence is the ordinary state. A file that does not parse, names an unknown group,
+or gives a threshold a non-integer value stops the analyzer naming the file and the problem rather
+than reverting to defaults under a maintainer who believes their tuning applies. The policy also
+declares severities, the verdict bands below, and the globs a review excludes.
+
+The per-repo tier is found by walking up from the analysed path, so a target outside any repository
+resolves none, which the `policy` block makes visible.
+
+Language-specific checks are defined in each `languages/*.md` file.
+
+## Review Report Generator
+
+Combines PR analysis and code quality findings into structured review reports.
+
+```bash
+# Generate report for current repo
+python scripts/review_report_generator.py /path/to/repo
+
+# Markdown output
+python scripts/review_report_generator.py . --format markdown --output review.md
+
+# Use pre-computed analyses
+python scripts/review_report_generator.py . \
+  --pr-analysis pr_results.json \
+  --quality-analysis quality_results.json
+```
+
+**Verdicts:** the bands live in `review-policy.json` under `verdictBands`, for the same reason the
+thresholds do. They are **declared, never applied**: they orient a reviewer reading a score, and
+nothing computes the verdict from one. A verdict may therefore disagree with the band a score falls
+in, provided the report says so and why.