@mrciphersmith/keryx 0.2.73 → 0.2.74

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.73",
+  "version": "0.2.74",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {

package/src/gdskills/bundled/skills/core/reviewer-skill-creator/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: reviewer-skill-creator
+model_tier: standard
+description: |
+  Use when asked to create a project-local reviewer for review-orchestrator, usually
+  from an existing source: a rules file, a review profile, a conventions doc, a
+  team's written review standard. Scaffolds the package under
+  .metaproject/project-skills/review/<name>/, records where the source came from
+  so drift is detectable later, writes the reviewer against the orchestrated review
+  contract, and confirms the orchestrator can see it.
+  NOT for: editing a bundled reviewer keryx ships (those live in the source tree and
+  change through a PR), and NOT for creating an ordinary entity project-skill
+  (entity-skill-creator).
+triggers:
+  - "create a reviewer"
+  - "new reviewer for review-orchestrator"
+  - "make a reviewer from this profile"
+  - "создай ревьюера"
+  - "создай нового ревьюера на основании"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "core"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
+license: "MIT"
+---
+
+# Reviewer Skill Creator
+
+Turn a written review standard into a reviewer the orchestrator will dispatch.
+
+The request usually arrives as one sentence — *"create a reviewer for
+review-orchestrator based on `<path>/rules/core/some-profile.mdc`"* — and it names two
+things: a **destination** (the review lane) and a **source** (a file someone
+else maintains). Both matter, and the second is the one that is usually
+mishandled.
+
+---
+
+## Where it goes, and why there
+
+```
+.metaproject/skills/gdskills/review/<name>/     <- reviewers keryx ships
+.metaproject/project-skills/review/<name>/      <- reviewers this project defines
+```
+
+The parallel is the whole convention. A project reviewer is a project-skill whose
+**module is `review`**; nothing else marks it, and `keryx review reviewers`
+finds it by that alone. Anyone who knows where bundled reviewers live knows where
+these go.
+
+---
+
+## Workflow
+
+```
+reviewer-skill-creator Progress:
+- [ ] Step 1: Read the source in full, and say what it is
+- [ ] Step 2: Scaffold the package, recording the source
+- [ ] Step 3: Write the reviewer against the orchestrated contract
+- [ ] Step 4: De-personalise
+- [ ] Step 5: Verify, and confirm the orchestrator sees it
+```
+
+### Step 1 — read the source in full, and say what it is
+
+Read the whole file before writing anything. A review profile is usually not
+organised as a reviewer: it is a list of rules, or a transcript of preferences,
+or a checklist mixed with examples from one specific repository.
+
+Sort what you find into three piles, out loud, in your reply:
+
+- **Method** — a way of establishing something. *Delete the gate and see whether
+  the suite stays green. Measure the rendered width. Read the producer at a
+  pinned SHA.* This is the valuable pile and it transfers.
+- **Convention** — a rule true of the source's own codebase. *Stores go in
+  `src/*/store.ts`.* Keep it only if it is true of THIS project; verify, do not
+  assume.
+- **Persona** — one person's voice, catchphrases, verdict vocabulary, and habits
+  of address. This pile is dropped whole. See Step 4.
+
+If the source is mostly the third pile, say so and stop. A reviewer distilled
+from someone's tone reviews tone.
+
+### Step 2 — scaffold the package, recording the source
+
+```bash
+keryx skills create "<short target>" \
+  --module review \
+  --name <reviewer-name> \
+  --note "<one line: what this reviewer is for>" \
+  --origin <path to the source file>
+```
+
+Three fields, three different jobs, and mixing them is the recorded failure mode:
+
+- `<short target>` is a **routing key** — a path, a symbol, or a short concept.
+  `keryx skills route` matches queries against it. Never a sentence.
+- `--note` is the prose. It renders under Purpose and touches nothing that routes.
+- `--origin` is the source file's path, stored verbatim and hashed. This is what
+  makes the next question answerable.
+
+**Always pass `--origin` when a source file exists.** The source is maintained
+somewhere else and will move on; without the hash, a reviewer built from last
+month's version reads as current forever, and nobody finds out until its findings
+disagree with the standard it claims to encode. With it,
+`keryx review reviewers` reports `drift: changed` the moment the file differs.
+
+Quote the path if it starts with `~` and you want it stored that way; an
+unquoted `~` is expanded by the shell before keryx sees it. Either is fine —
+both resolve — but the stored form is what a human reads later.
+
+### Step 3 — write the reviewer against the orchestrated contract
+
+The scaffold is a generic entity-skill template. Replace its body. A reviewer
+that does not conform is handled by the Sub-Agent Report Quality Gate exactly as
+a bundled one would be — local authorship is not evidence.
+
+Required, all of it in `SKILL.md`:
+
+- **Scope** — what this reviewer owns, and explicitly what it does not. Name the
+  neighbouring reviewers that own the excluded parts. A lane that does not say
+  where it stops duplicates three others.
+- **Checklist** — the method pile from Step 1, as checks that can be performed.
+- **Severity** — do **not** write a rubric. Point at
+  `review-orchestrator/SKILL.md` → **Severity (canonical)** and add one table
+  saying where this reviewer's recurring conditions land under it. Ten private
+  rubrics feeding one sort produce a ranking that means ten things at once.
+- **Shared laws** — copy the three verbatim from the orchestrator: no
+  unreproducible harm claim above `info`, never flag the theoretical, one finding
+  per class.
+- **Class scope** — `blocker` and `major` carry every site holding the shape and
+  the enumeration method that found them.
+- **Orchestrated Review Contract** — return `REVIEW_RESULT` per
+  `reviewer-finding.schema.json`, with a finding-id prefix of your own.
+
+If the source's method needs a command to be worth anything — a mutation, a
+measurement, a probe — say so as an iron law, and say what the finding is worth
+without it. A method nobody runs is a preference.
+
+### Step 4 — de-personalise
+
+Keep the method. Drop the person.
+
+Strip names and handles, catchphrases, verdict vocabulary, forms of address, and
+anything whose meaning depends on knowing the author. A rule that reads as one
+person's taste will be followed as taste; the same rule stated as a procedure
+with a stated reason will be followed as a procedure.
+
+This is not politeness, it is transferability, and keryx enforces the same line
+on its shipped tree: `bundled-eval.ts` fails a bundled skill that names the
+reviewer it was learned from or reuses their phrases. Project-skills are not
+scanned by that check — which makes this step your responsibility rather than
+the gate's.
+
+For every rule you keep, write the **reason** beside it. A reason survives being
+transplanted into a codebase the author never saw; an assertion does not.
+
+### Step 5 — verify, and confirm the orchestrator sees it
+
+```bash
+keryx skills verify review/<reviewer-name>
+keryx review reviewers
+```
+
+The second is the one that matters: it is the same call
+`review-orchestrator` makes, so its output is proof the reviewer will be
+dispatched rather than a hope. Check the row shows your reviewer with
+`drift: clean`.
+
+Then say, in your reply, which of the three piles from Step 1 you kept, which you
+dropped, and what you could not verify against this project.
+
+---
+
+## Iron Laws
+
+1. **`--origin` whenever a source file exists.** A reviewer built from a file
+   nobody can trace back is a reviewer nobody can update.
+2. **The target is a routing key, the note is the prose.** A sentence in the
+   target produces a skill that matches no query and verifies as permanently
+   stale. This is a recorded failure, not a hypothetical.
+3. **No private severity rubric.** Point at the canonical one.
+4. **Drop the persona, keep the method, state the reason.**
+5. **Do not claim the reviewer is wired until `keryx review reviewers` shows
+   it.** Creating files is not registration, and registration is not discovery.
+
+---
+
+## Refreshing a reviewer whose source moved on
+
+`keryx review reviewers` reporting `drift: changed` means the source file differs
+from what was imported. It does **not** mean the reviewer is wrong.
+
+Re-read the source, diff it against what the skill encodes, and then decide per
+change: fold it in, or record in the skill why this project deliberately differs.
+Re-run Step 2's command with the same `--name` to re-record the hash once the
+skill matches the source again.
+
+A deliberate divergence that is written down is a decision. The same divergence
+undocumented is drift that will be silently "fixed" by whoever refreshes next.
+
+---
+
+## Scope Boundaries
+
+| Concern | This skill | Use instead |
+|---|---|---|
+| Create a project-local reviewer | YES | — |
+| Refresh one whose origin drifted | YES | — |
+| Create an entity/module project-skill | NO | `entity-skill-creator` |
+| Change a reviewer keryx ships | NO | edit `src/gdskills/bundled/skills/review/` and open a PR |
+| Update a skill from review findings | NO | `entity-skill-learner`, `keryx skills learn` |
+| Decide which reviewers a round dispatches | NO | `review-orchestrator` |

package/src/gdskills/bundled/skills/orchestration/flow-orchestrator/SKILL.md

@@ -12,7 +12,7 @@ triggers:
   - "managed implementation"
 metadata:
   author: "MrCipherSmith"
-  version: "1.3.0"
+  version: "1.4.0"
   category: "orchestration"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
@@ -418,12 +418,59 @@ How should this flow end?
   Preserve the base branch recorded during initialization. Do not mark the
   flow implemented or complete before the PR is merged into that branch.
 
+### A dispatched run answers the question from its input
+
+The choice above is the USER's, and a subagent has no user to ask. When this
+skill is dispatched by another skill the answer arrives in the input, and asking
+anyway is how a dispatched run stalls forever on a prompt nobody will read.
+
+Read it from the **typed fields**, and validate them first:
+
+```bash
+keryx skills contracts validate <dispatch.json> --schema flow-orchestrator-input
+```
+
+`base_branch`, `completion_outcome` and `operator_confirmed` are properties of
+that contract, not constraint strings. The distinction is the whole point:
+nothing parses `constraints[]`, so a load-bearing value misspelled there is
+dropped in silence and the run merges wherever it resolved a base on its own.
+`constraints[]` carries advisory scope and policy — never a merge target.
+
+`completion_outcome` is **required** by the contract, so an absent one is a
+refused dispatch rather than a question. That is deliberate: the previous rule
+here said "ask", prescribed fourteen lines after this section says asking is how
+a dispatched run stalls on a prompt nobody reads — and it left the
+`create-pr-and-merge` conditional reachable-around by simply omitting the field.
+A dispatched run that cannot name its outcome returns **BLOCKED** naming the
+missing field. Only an interactive run asks. Record in `journal.md` which field
+answered it and who is behind it.
+
+| Input | Obey it as |
+|---|---|
+| `base_branch` | Cut the flow branch from **that** branch and merge back into it. Never substitute the repository default: a fix aimed at a pull request's own branch has to land inside that pull request, and the default branch is a different review. Absent, resolve the base yourself and record what you resolved. |
+| `completion_outcome: create-pr-and-merge` | Skip the Completion Choice question, run the PR review/fix loop, merge into `base_branch`, complete the flow. |
+| `operator_confirmed` | The human decision behind an outward-facing completion. See the row below for when its absence is a refusal. |
+| `review: the caller owns the reply on #<n>` | Pass it through to every `review-orchestrator` dispatch. Reviews of **this flow's own** PR reply as normal — that is a separate conversation. What the round must not do is answer `#<n>`, which the caller is already answering. |
+| `attempt budget: at most <n> attempts` | A numeric ceiling BELOW your own bound is obeyed. One at or above it is not — the bound is yours, and the paragraph under this table says why. |
+| `completion: <anything>` as a constraint STRING | **Not an outcome. Refuse it and ask for the typed field.** `constraints[]` is parsed by nothing, so a completion arriving there is never read at all. Such a dispatch is now refused for the missing `completion_outcome` rather than silently accepted — but the refusal is the contract's, not this row's, and a row telling you to honour the string would be a documented bypass of the fence in the file that owns it. |
+
+A constraint that would raise this skill's own attempt budget is **not** obeyed.
+The three-attempt bound and the `keryx review loop` repetition check are this
+skill's, they are evidence-backed, and a caller asking for "loop until clean" gets
+the bound plus an escalation — never an unbounded loop.
+
 ### PR review/fix loop
 
 1. Run the relevant `review-orchestrator` checks against the PR and current
    branch state.
 2. If findings or required check failures remain, create or update a flow fix
    task, dispatch `task-implementer`, push the fix, and run review again.
+
+   **The threshold is `minor`.** The loop exits when the round reports zero
+   findings at `blocker`, `major` or `minor`; `info` does not hold it. State the
+   remaining `info` findings in the completion report rather than fixing them
+   under a loop that was not opened for them. A caller may lower the threshold in
+   `constraints`; it cannot raise it to merge over a `minor`.
 3. Allow at most **three** review/fix attempts for the current approach. Count
    an attempt when review/check results are available, including a clean result,
    and record it with `keryx flow task attempt <id> <Tn> --outcome ...` so the

package/src/gdskills/bundled/skills/orchestration/flow-orchestrator/input-contract.schema.json

@@ -4,7 +4,10 @@
   "title": "FlowOrchestratorInput",
   "type": "object",
   "additionalProperties": false,
-  "required": ["request"],
+  "required": [
+    "request",
+    "completion_outcome"
+  ],
   "properties": {
     "request": {
       "type": "string",
@@ -21,13 +24,76 @@
     },
     "mode": {
       "type": "string",
-      "enum": ["init", "execute", "complete", "resume", "auto"],
+      "enum": [
+        "init",
+        "execute",
+        "complete",
+        "resume",
+        "auto"
+      ],
       "default": "auto"
     },
     "constraints": {
       "type": "array",
-      "items": { "type": "string" },
-      "default": []
+      "items": {
+        "type": "string"
+      },
+      "default": [],
+      "description": "Advisory scope and policy for this run, one per string. Anything that decides where the work LANDS belongs in a typed property above, not here: nothing parses this array, so a misspelled constraint is silently dropped."
+    },
+    "base_branch": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The branch the flow branch is cut from and merged back into. Typed rather than left to a constraint string because this is the field that decides WHERE the work lands: a fix aimed at a pull request's own head branch that merges to the repository default instead is a change nobody reviewed, reported as success. Absent, the orchestrator resolves the base itself and records it."
+    },
+    "completion_outcome": {
+      "type": "string",
+      "enum": [
+        "create-pr-and-merge",
+        "verified-handoff",
+        "keep-open"
+      ],
+      "description": "Answers the Phase 4 Completion Choice for a dispatched run, which has no user to ask. REQUIRED: an absent outcome used to mean 'ask', prescribed by the same section that says asking is how a dispatched run stalls on a prompt nobody reads \u2014 and it left the create-pr-and-merge conditional below unreachable by simply omitting the field. A dispatch that cannot name its outcome is BLOCKED, not questioned."
+    },
+    "operator_confirmed": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "confirmed_by",
+        "confirmed_at",
+        "plan_digest"
+      ],
+      "description": "The human decision behind an outward-facing completion. Required by callers whose work merges third-party content \u2014 see review-pr-feedback --fix. What `plan_digest` is worth is stated on the field itself; do not infer a replay defence from its presence here.",
+      "properties": {
+        "confirmed_by": {
+          "type": "string",
+          "minLength": 1
+        },
+        "confirmed_at": {
+          "type": "string",
+          "minLength": 1
+        },
+        "plan_digest": {
+          "type": "string",
+          "minLength": 1,
+          "description": "A record of WHICH plan the human said they read \u2014 not a control. Nothing in this tree computes or verifies a digest, and the schema constrains it only to a non-empty string, so an agent composing the dispatch chooses the value and a plan mutated after approval carries the same one. `operator_confirmed`'s PRESENCE is enforced; this field's VALUE is not. Making it a control means hashing the rendered plan and having the receiver recompute over what it got."
+        }
+      }
+    }
+  },
+  "if": {
+    "required": [
+      "completion_outcome"
+    ],
+    "properties": {
+      "completion_outcome": {
+        "const": "create-pr-and-merge"
+      }
     }
+  },
+  "then": {
+    "required": [
+      "operator_confirmed"
+    ]
   }
 }

package/src/gdskills/bundled/skills/planning/consistency-checker/SKILL.codex.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-consistency-checker
+name: consistency-checker
 description: >
   Validates PRD/Implementation Plan against decisions registry, architecture doc,
   and best practices constraints. Catches contradictions, gaps, and violations.

package/src/gdskills/bundled/skills/planning/consistency-checker/SKILL.cursor.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-consistency-checker
+name: consistency-checker
 description: >
   Validates PRD/Implementation Plan against decisions registry, architecture doc,
   and best practices constraints. Catches contradictions, gaps, and violations.

package/src/gdskills/bundled/skills/planning/consistency-checker/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-consistency-checker
+name: consistency-checker
 description: >
   Validates PRD/Implementation Plan against decisions registry, architecture doc,
   and best practices constraints. Catches contradictions, gaps, and violations.

package/src/gdskills/bundled/skills/planning/patterns-researcher/SKILL.codex.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-patterns-researcher
+name: patterns-researcher
 description: >
   Researches best practices per technology in the chosen stack and defines
   application architecture patterns. Produces constraints that PRD must follow.

package/src/gdskills/bundled/skills/planning/patterns-researcher/SKILL.cursor.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-patterns-researcher
+name: patterns-researcher
 description: >
   Researches best practices per technology in the chosen stack and defines
   application architecture patterns. Produces constraints that PRD must follow.

package/src/gdskills/bundled/skills/planning/patterns-researcher/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-patterns-researcher
+name: patterns-researcher
 description: >
   Researches best practices per technology in the chosen stack and defines
   application architecture patterns. Produces constraints that PRD must follow.

package/src/gdskills/bundled/skills/planning/planner/SKILL.codex.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-planner
+name: planner
 description: >
   Generates roadmap, milestones, task breakdown, and dependency graph from PRD.
   Use when: dispatched by gproject-orchestrator Phase 6.

package/src/gdskills/bundled/skills/planning/planner/SKILL.cursor.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-planner
+name: planner
 description: >
   Generates roadmap, milestones, task breakdown, and dependency graph from PRD.
   Use when: dispatched by gproject-orchestrator Phase 6.

package/src/gdskills/bundled/skills/planning/planner/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-planner
+name: planner
 description: >
   Generates roadmap, milestones, task breakdown, and dependency graph from PRD.
   Use when: dispatched by gproject-orchestrator Phase 6.

package/src/gdskills/bundled/skills/planning/problem-definer/SKILL.codex.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-problem-definer
+name: problem-definer
 description: >
   Defines core problems, goals, non-goals, and success metrics from discovery data.
   Use when: dispatched by gproject-orchestrator Phase 1.

package/src/gdskills/bundled/skills/planning/problem-definer/SKILL.cursor.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-problem-definer
+name: problem-definer
 description: >
   Defines core problems, goals, non-goals, and success metrics from discovery data.
   Use when: dispatched by gproject-orchestrator Phase 1.

package/src/gdskills/bundled/skills/planning/problem-definer/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-problem-definer
+name: problem-definer
 description: >
   Defines core problems, goals, non-goals, and success metrics from discovery data.
   Use when: dispatched by gproject-orchestrator Phase 1.

package/src/gdskills/bundled/skills/planning/project-discovery/SKILL.codex.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-discovery
+name: project-discovery
 description: >
   Collects and structures initial project information from multiple sources.
   Use when: dispatched by gproject-orchestrator Phase 0.

package/src/gdskills/bundled/skills/planning/project-discovery/SKILL.cursor.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-discovery
+name: project-discovery
 description: >
   Collects and structures initial project information from multiple sources.
   Use when: dispatched by gproject-orchestrator Phase 0.

package/src/gdskills/bundled/skills/planning/project-discovery/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-discovery
+name: project-discovery
 description: >
   Collects and structures initial project information from multiple sources.
   Use when: dispatched by gproject-orchestrator Phase 0.

package/src/gdskills/bundled/skills/planning/spec-writer/SKILL.codex.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-spec-writer
+name: spec-writer
 description: >
   Generates PRD or Implementation Plan constrained by decisions registry,
   architecture doc, and best practices. Does NOT invent new architectural decisions.

package/src/gdskills/bundled/skills/planning/spec-writer/SKILL.cursor.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-spec-writer
+name: spec-writer
 description: >
   Generates PRD or Implementation Plan constrained by decisions registry,
   architecture doc, and best practices. Does NOT invent new architectural decisions.

package/src/gdskills/bundled/skills/planning/spec-writer/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-spec-writer
+name: spec-writer
 description: >
   Generates PRD or Implementation Plan constrained by decisions registry,
   architecture doc, and best practices. Does NOT invent new architectural decisions.

package/src/gdskills/bundled/skills/planning/stack-advisor/SKILL.codex.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-stack-advisor
+name: stack-advisor
 description: >
   Determines project level (MVP/pet/startup/production) and recommends optimal
   technology stack with trade-off analysis.

package/src/gdskills/bundled/skills/planning/stack-advisor/SKILL.cursor.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-stack-advisor
+name: stack-advisor
 description: >
   Determines project level (MVP/pet/startup/production) and recommends optimal
   technology stack with trade-off analysis.

package/src/gdskills/bundled/skills/planning/stack-advisor/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-stack-advisor
+name: stack-advisor
 description: >
   Determines project level (MVP/pet/startup/production) and recommends optimal
   technology stack with trade-off analysis.

package/src/gdskills/bundled/skills/review/review-clean-code/SKILL.md

@@ -211,9 +211,41 @@ Flags:
 
 Flags:
 - Redundant comment restating the code — **minor**
-- Stale comment contradicting the code — **major** (actively misleads readers)
+- Stale comment contradicting the code — **minor** (misleads the next reader; it
+  names no runtime trigger, so the canonical rubric puts it here. It was
+  **major** in this file until that was reconciled against
+  `review-orchestrator/SKILL.md` → **Severity (canonical)**, which reviewers may
+  not override. If the comment's inaccuracy *causes* a defect — someone relied on
+  it and the code does otherwise — that defect is the finding, at its own severity)
 - Commented-out code block — **minor** (use git history, not comments, to preserve old code)
 
+#### C1a. Documentation drift — the shapes worth searching for
+
+Stale comments are not found by reading comments; they are found by reading each
+comment **against the statement it sits above**. Three shapes recur, and they are
+the cheapest real findings in a multi-round review:
+
+- **A doc describing the rule a later round replaced.** A prop's JSDoc says the
+  tooltip drops the split "unless both are known"; the live rule is that both must
+  be greater than zero. The behaviour changed, the sentence did not. Check every
+  doc comment on every symbol the diff touched, not only the ones the diff edited.
+- **A comment detached from its statement.** A `const` gets inserted between a
+  comment and the expression it explained, so the comment now reads as an
+  explanation of the insertion. The text is unchanged and is now wrong. Look for
+  this wherever the diff adds a line inside an existing block.
+- **Two files documenting one field oppositely.** One says a cell is the valid
+  percentage, another computes `100 - cell` and calls it the invalid percentage.
+  Only one is right, and the diff just made the field load-bearing.
+
+Where an issue or PR is cited, check that it is the right one and still says what
+the comment claims — a closed *issue* cited in place of the *PR* that shipped the
+work sends the next reader to the wrong page.
+
+A comment that describes a behaviour with **no code path at all** — including one
+left behind by a review finding that was later withdrawn — is the same class: it
+should state the defensiveness it actually provides, not assert a path that does
+not exist.
+
 #### C2. Comments That Compensate for Bad Names
 
 A comment whose entire purpose is to explain a poorly-named identifier is a sign to improve the name, not add a comment.