@jaybeeuu/agent-cortex 2.7.0 → 2.9.0

package/skills/review/review-defects/EXAMPLES.md

@@ -0,0 +1,198 @@
+# Review defects — worked examples
+
+One case per class. Each shows what was observed, the label, and the rejection text to write. Eleven
+were observed in real review rounds; `scope-creep` is described as a situation, because no recorded
+case exists, so you can match its shape without guessing at history.
+
+## `test-unproven` — the name claims a settle-time cleanup
+
+**Observed.** A test named "… removes it when the watch settles" called `stop()` and asserted the
+entry was gone. It never settled the watch, so the settle path had no assertion. The cleanup on
+settle could have been deleted and the test would still pass.
+
+**Label.** `defect:test-unproven`
+
+**Rejection text.** "Test `…removes it when the watch settles` claims removal at the settle step,
+but the body stops the watch and asserts removal once. Add the settle trigger and assert the entry
+is gone after it. Either the name or the assertion must change."
+
+**Why this class.** Not `test-cannot-fail`: the assertion is genuine and would fail for the bug it
+covers. The defect is narrower — the name promises a path the body never takes.
+
+## `test-cannot-fail` — the concurrent case is never exercised
+
+**Observed.** A note appended "a double fire appends nothing twice". The test fired twice in
+sequence and asserted one entry. Two concurrent fires were never run, so the claim could not fail.
+
+**Label.** `defect:test-cannot-fail`
+
+**Rejection text.** "The claim is about concurrent double fires, but the test fires sequentially.
+Await both fires against the same target and assert one entry, or rename the claim. As written no
+implementation can fail it."
+
+**Why this class.** Not `test-unproven`: the name and the assertion agree on "two fires produce one
+entry". The gap is that the case the claim is about is never constructed.
+
+## `missing-proof` — a report of a demonstration that was stubbed
+
+**Observed.** A stage report stated "end-to-end run verified: the check writes the record and the
+follow-up reads it". The command in the evidence block substituted a stub for the check, so no
+end-to-end path ran.
+
+**Label.** `defect:missing-proof`
+
+**Rejection text.** "`SUMMARY` claims an end-to-end demonstration; the evidence command replaces the
+check with a stub, so the record is written by the test, not by the code under review. Paste the
+real invocation and its output."
+
+**Why this class.** Nothing is missing from the code. The gap is between the claim and the evidence
+for it, which is exactly what this class names.
+
+## `docs-drift` — shipped text that shipped past its change
+
+**Observed.** Two shipped text defects in one round: a token map named an exact harness version, so
+the mapping broke on the next release; and a peer-channel section still said one harness only, after
+the fork had made it both.
+
+**Label.** `defect:docs-drift`
+
+**Rejection text.** "The token map names an exact harness version — it must read the running one or
+a documented default. The peer-channel section says one harness only, but the mapping now covers
+both; update the prose to what ships."
+
+**Why this class.** The shipped artefact and the text describing it disagree. A reviewer reading the
+text would predict behaviour the install does not have.
+
+## `criteria-unmet` — the change breaks the criterion it must satisfy
+
+**Observed.** A criterion said an install leaves one directory free of the tool's own files. The
+change wrote its state record into that very directory, so the reviewer could not affirm the
+criterion at all.
+
+**Label.** `defect:criteria-unmet`
+
+**Rejection text.** "The criterion says that directory holds no file of ours; the new record is
+written into it, so the criterion fails. Move the record under the tool's own state directory,
+keyed by the directory it describes, or amend the criterion in the bead and say why."
+
+**Why this class.** The work is real and the scope is honest — part of what was asked is absent.
+
+## `scope-creep` — unrelated tidying rides along
+
+**Situation.** A change that adds one label also renames three unrelated helpers and reformats a
+neighbouring module.
+
+**Label.** `defect:scope-creep`
+
+**Rejection text.** "The rename and the reformat are outside the criteria. Split them into their own
+change so this one can be reviewed and reverted on its own."
+
+**Why this class.** Every line is defensible in isolation. The defect is that the change is wider
+than its reason, which hides the real diff.
+
+## `style-violation` — a written rule is broken
+
+**Observed.** A change added a new skill and declared a `patch` bump in its changeset. The
+versioning rule says a new skill is a `minor` bump and lists "wrong bump type" as a red flag. The
+reviewer rejected the change citing that rule.
+
+**Label.** `defect:style-violation`
+
+**Rejection text.** "The changeset declares `patch`, but this change adds a skill. The versioning
+rule makes an addition `minor` and calls a wrong bump type a red flag. Bump it to `minor`."
+
+**Why this class.** Cite the rule, not a preference. A reviewer who cannot quote a written rule has
+a preference, and preferences are not rejections.
+
+## `regression` — an existing behaviour breaks
+
+**Observed.** A code stage added a manifest write that assumed its target directory existed. An
+install from a source holding no agents and no skills had worked before; after the change it threw
+`ENOENT` on that write. The stage found it in its own check of the change, reproduced it, added a
+test that failed, then fixed it.
+
+**Label.** `defect:regression`
+
+**Rejection text.** "The manifest write assumes its directory exists, so an install from a source
+with no agents and no skills now throws `ENOENT` where it used to succeed. Create the directory
+before writing, and cover the empty-source case with a test."
+
+**Why this class.** The change may satisfy its own criteria fully. It also breaks behaviour nobody
+asked to change, which is a separate fact from `criteria-unmet`.
+
+## `unsafe-instruction` — a documented command that ran the reader's text
+
+**Observed.** A shipped skill documented `bd note <bead> "<entry>"` and told the reader to embed a
+free-text entry, including text the user had typed. Following it with an entry containing `$(…)`
+ran the substitution when the line was pasted, and an entry containing a `"` ended the quoted
+argument early and corrupted the note. The sentence had shipped for many releases and still
+described the command correctly: the command does record a note.
+
+**Label.** `defect:unsafe-instruction`
+
+**Rejection text.** "The note command takes free text through a double-quoted shell argument, so a
+`$(…)` in the entry executes and a `"` truncates the note. Write the entry with `--out` and pass it
+with `bd note --file`, and say why. A reader on an arbitrary machine pastes this line as written."
+
+**Why this class.** Not `docs-drift`: the text matches the command's behaviour. Not
+`style-violation`: no convention was broken. The defect is the consequence of following the text —
+data loss and code execution on a machine the author never sees.
+
+## `ambiguous-rule` — two plausible readings of one rule
+
+**Observed.** Two in one round. A bead described a runtime that supplies "mail, rigs and pane
+conventions" and said the persona behaves the same in every scope, so a reader could take "rigs" as
+true of personal work too; the real rule is that rigs are code-project containers and personal work
+is a town-level scope with no rig. Separately, a shipped doc printed a live substitution token of
+the `TOOL` kind — a full token, colon and key included — to illustrate the token grammar, and the
+token guard necessarily rejects a literal token in a shipped doc: the line read both as an example
+and as a token that must resolve.
+
+**Label.** `defect:ambiguous-rule`
+
+**Rejection text.** "Two readings are possible and the text picks neither. 'Mail, rigs and pane
+conventions' reads as true of personal work; state that rigs are code-project containers and that
+personal work is a town-level scope with no rig. The doc prints a literal substitution token of the
+`TOOL` kind, which the guard reads as unresolved; show the grammar without a literal token, or mark
+the line as an example the guard must skip."
+
+**Why this class.** Not `docs-drift`: nothing was stale — each statement was true of the code
+projects it described. The text can be read two ways, and the reader who takes the wrong one cannot
+tell from the words.
+
+## `silent-degradation` — a guard that reported success on the tree it never read
+
+**Observed.** A materialiser check walked one harness's generated tree for leftover substitution
+tokens and reported success, while the other harness's tree shipped a literal token to readers. The
+guard was real and its assertion genuine; it never looked at half the surface, so it reported "no
+offenders" for a tree it had not read. A second instance in the same area: a token row whose
+second-harness column was empty dropped the token silently, leaving a sentence with a hole in it
+and no warning.
+
+**Label.** `defect:silent-degradation`
+
+**Rejection text.** "The guard reads one harness's tree only; the other tree ships an unsubstituted
+token and the check passes. Walk every generated tree, and fail on an empty token row rather than
+dropping the token. A skipped check must not report success."
+
+**Why this class.** Not `test-cannot-fail`: the assertion would fail for a token in the tree it
+reads. The defect is the unread surface, plus a mapping that degrades to prose with no warning — a
+path that fails quietly, which is wider than one test.
+
+## `unclassified` — the escape hatch, before the class existed
+
+**Observed.** The unsafe instruction above was rejected before `unsafe-instruction` existed. No
+class fit, so the reviewer forced the nearest one and the finding went out as `defect:docs-drift`.
+Nothing in the text was stale, the fix had nothing to do with documentation, and the aggregate
+counted a documentation defect where the risk was a destructive command. That mislabel is the case
+this section exists to correct.
+
+**Label.** `defect:unclassified`
+
+**Rejection text.** "No class fits: this is an instruction that can destroy data or run a command,
+not stale text. Applied `defect:unclassified` alone and proposed an `unsafe-instruction` class in a
+bead. Do not read this as a documentation defect."
+
+**Why this class.** It is the escape hatch, and the obligation is the point: it was applied with a
+gap bead proposing the missing class. Without that bead it is a miscount with a nicer name, and the
+class is not a pass on the review.

package/skills/review/review-defects/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: review-defects
+description: The closed vocabulary of `defect:<class>` labels a reviewer applies to a rejected bead, so rejections become countable data. Use when rejecting a change, when deciding which class names a finding, or when querying which defects recur.
+---
+
+# Review defects
+
+A rejection says what is wrong. The class says *which kind* of wrong, in one word, so rejections can
+be counted, compared and trended across tasks instead of re-read one at a time.
+
+## One closed list, one label per rejection
+
+Apply exactly one class from this table. Never invent one.
+
+The **Distinct from** column is part of the definition: two classes that sound alike are separated
+there, and a finding that matches the neighbour belongs to the neighbour.
+
+| Class | The defect | Distinct from | Evidence the rejection must show |
+|---|---|---|---|
+| `test-unproven` | A test's name claims a requirement its assertions never check. | `test-cannot-fail`: there the assertion is genuine and the case is absent. | The named clause, and the assertion that is missing. |
+| `test-cannot-fail` | An assertion passes against a broken implementation. | `test-unproven`: a name that outruns its body, not an assertion that cannot bite. | The case that should fail and does not. |
+| `criteria-unmet` | A criterion from the bead is not delivered. | `scope-creep`: too little work, not more than was asked. | The criterion, quoted, and what is absent. |
+| `scope-creep` | The change does more than the criteria ask. | `criteria-unmet`: the change is wider than its reason. | The touched behaviour that no criterion names. |
+| `style-violation` | A `style-*` rule is broken. | `unsafe-instruction`: a convention broken, not a machine put at risk. | The rule, quoted, and the line that breaks it. |
+| `missing-proof` | A report claims success with no evidence. | `silent-degradation`: evidence absent, not evidence that cannot be wrong. | The claim, and the command output that is absent. |
+| `regression` | Behaviour that worked before now breaks. | `criteria-unmet`: it breaks something nobody asked to change. | The old behaviour, and the check that now fails. |
+| `docs-drift` | Shipped text no longer matches what ships. | `ambiguous-rule`: drift is **stale**; ambiguity is **readable two ways**. | The text, and the behaviour that contradicts it. |
+| `unsafe-instruction` | Shipped text that, followed on an arbitrary machine, could destroy data or run something dangerous — destructive commands, force-pushes, credential handling, overwriting user config. | `docs-drift`: the text is still true, and the hazard is the point. `style-violation`: a convention, not a consequence. | The text, quoted, the state it endangers, and a safe form to use instead. |
+| `ambiguous-rule` | Wording a reasonable agent reads two ways, especially a phrase true of one context that reads as true of another. | `docs-drift`: true yesterday, false today. `criteria-unmet`: behaviour delivered, not wording. | Both readings, quoted, and the one the author intended. |
+| `silent-degradation` | A path that fails quietly or passes vacuously: a skipped check reported as success, a null mapping silently dropping a token, a guard that cannot fail. | `test-cannot-fail`: one assertion that cannot bite; this is any path that cannot report. | The quiet path, what it should have reported, and the run that shows it. |
+| `unclassified` | The defect matches no class. It exists so a reviewer never force-fits. | Everything: it is the honest answer when none of the others is true. | The finding, the classes considered and why each fails, and the gap bead filed for the missing class. |
+
+Two findings of different kinds are two entries in the rejection text and one label: the class of
+the finding that must be fixed first.
+
+## A class is a classification, not a state
+
+The bead's own status still answers "where is this work?". The label answers "what kind of defect
+was this?" — so never use it to mean blocked, in progress or done, and never add a parallel state
+label.
+
+## Apply it
+
+1. Name the class in the rejection text, next to the specific reason.
+2. Apply it to the bead whose work you reject:
+
+   ```bash
+   bd update <id> --add-label defect:test-unproven
+   ```
+
+   That bead is normally already closed — a pipeline closes the chore whose work is rejected before
+   the review runs — and the label attaches to it anyway. So the queries below pass `--all`.
+
+3. Write the specific reason — the file, the line, the missing assertion — in the rejection text.
+   The label is queryable; it is never the whole message.
+
+## Remove it when the fix closes
+
+The review that confirms the fix removes the label, so the vocabulary describes only defects whose
+fix is unconfirmed:
+
+```bash
+bd update <id> --remove-label defect:test-unproven
+```
+
+Record the removal in that review's trail entry ("`defect:test-unproven` cleared"), not as a label.
+A closed defect is a fact in the trail, not a second class.
+
+## No class fits: the escape hatch
+
+Apply `defect:unclassified` when none of the classes above describes the finding. It exists so you
+never force-fit, because a forced label corrupts the aggregate the feedback loop reads: the classes
+are counted, so a `docs-drift` label on a dangerous instruction reports a text problem where the
+risk was a machine at risk.
+
+Applying it carries an obligation. The class is not a pass:
+
+1. Say in the rejection text that no class fits, and name the classes you considered.
+2. File a bead proposing the class that should have covered the finding, with this finding as its
+   case.
+3. Name that bead in the rejection text.
+
+Without step 2 the label records a defect and teaches nothing — silent degradation of the aggregate,
+which is the exact failure the class exists to prevent. An escape hatch without the bead is a
+miscount with a nicer name.
+
+## A label off this list is not a class
+
+Any other `defect:*` label is not a class: the report prints it as vocabulary drift and counts it as
+nothing. Inventing one is a review defect, and the escape hatch is the only honest way to say "no
+class fits".
+
+The vocabulary stays closed. A class is added by changing this file with the owner, never invented
+inside a review, and adding one does not licence the next reviewer to add another. Applying a class
+that does not fit is a review defect in itself, whatever the class: a label is never a near-miss.
+
+## Query it
+
+```bash
+bd list -l defect:test-unproven --all        # one class, any status
+bd list -l defect:unclassified --all        # the escape hatch: each names the gap bead filed
+bd list --label-pattern 'defect:*' --all     # every defect, any class
+```
+
+`--all` is not optional. `bd list` hides closed beads by default, defects are historical data, and
+the bead carrying one is usually closed: drop the flag and the query reports "No issues found" on
+a label that is set.
+
+Count the pattern output per class to see what recurs, and fix the process that produces it — a
+class that keeps appearing is a gap in the stage before this one.
+
+## Worked examples
+
+`EXAMPLES.md` carries one real case per class, with the rejection text a reviewer should write.
+
+## See Also
+
+- [review-security](../review-security/SKILL.md) — the security verdict that precedes any rejection.
+- [review-report](../review-report/SKILL.md) — counts these classes across a project and files the recurring ones upstream.
+- [run-pipeline-stage](../../workflow/run-pipeline-stage/SKILL.md) — the stage that applies these labels.
+- [bd-tool](../../productivity/bd-tool/SKILL.md) — labels, notes and statuses.

package/skills/review/review-report/EXAMPLES.md

@@ -0,0 +1,114 @@
+# Review report — worked examples
+
+Five real runs. Each prints the same five sections; what changes is what the tracker held, and a
+section with nothing to measure says so instead of printing a zero. The project names and bead ids
+are fixtures, the output is verbatim.
+
+## No label at all
+
+Four beads, one change, one review chore, no `defect:` label anywhere:
+
+```
+Defect report — acme/nolabels
+Reported 2026-05-01T10:00:00Z. Read 4 beads from the tracker.
+
+Defects by class — `bd list --label-pattern 'defect:*' --all`
+  No defect label is set on any bead, closed beads included. There is nothing to count,
+  so no zero is printed as if it were a measurement.
+
+First-pass review rate
+  1 of 1 review cohorts passed with no fix round — 100%
+  A cohort is a parent holding at least one stage:review chore; a rejected review always
+  creates a fresh one, so a parent with exactly one passed first time.
+
+Fix rounds
+  No stage:fix chore is recorded in this tracker.
+
+Change since the previous report
+  None — no previous report was named. This is a snapshot, not a trend.
+  Pass --baseline <path> to compare against one, and --record to keep this one.
+
+A defect label is removed when the review that confirms its fix runs, so every count
+above is the unconfirmed defect set at this moment, not the history of defects.
+```
+
+The pipeline numbers are still real. Only the defect section degrades, and it degrades by saying
+so: `0 defects` would have read as a measurement.
+
+## One labelled defect
+
+The same tracker after a review rejected the change once:
+
+```
+Defects by class — `bd list --label-pattern 'defect:*' --all`
+  1. criteria-unmet  1 defect in 1 change · owners: implement-task/SKILL.md, create-task/SKILL.md
+     example: acme-2q.3
+  1 unconfirmed defect across 1 change.
+
+First-pass review rate
+  0 of 1 review cohorts passed with no fix round — 0%
+
+Fix rounds
+  1 in total across 1 change — review 1
+```
+
+The report names the owning skill for the class and the bead that carries the label. The trend
+section still reads "None — no previous report was named": one label is a snapshot, and a
+direction needs a second report to compare against.
+
+## No review stage chore yet
+
+A project that has fixed something once but never ran a review chore. Only the two affected sections
+are shown:
+
+```
+First-pass review rate
+  No review stage chore is recorded in this tracker, so no rate is reported — absent
+  is not zero.
+
+Fix rounds
+  1 in total across 1 change — code 1
+```
+
+The rate is absent because nothing measured it, not because it is zero. The fix round is still
+counted, because attribution reads the fresh chore's `blocks` dependency rather than the review
+chores.
+
+## The whole vocabulary
+
+Twelve labels, one per class, spread over four changes. The defect section prints the top three and
+summarises the rest:
+
+```
+Defects by class — `bd list --label-pattern 'defect:*' --all`
+  1. ambiguous-rule  1 defect in 1 change · owners: write-a-skill/SKILL.md
+     example: acme-5q.1
+  2. criteria-unmet  1 defect in 1 change · owners: implement-task/SKILL.md, create-task/SKILL.md
+     example: acme-5q.2
+  3. docs-drift      1 defect in 1 change · owners: maintain-agent-docs/SKILL.md, style-documentation/SKILL.md
+     example: acme-5q.3
+  12 unconfirmed defects across 4 changes. Top 3 of 12 classes.
+```
+
+This is the owning-skill mapping in use. Each class maps to at least one shipped skill, the report
+names the file to change rather than the symptom, and the suite fails if a mapped skill disappears
+or a vocabulary class has no owner.
+
+`--json` prints every class with its count, its changes and its bead ids, for a caller that needs
+the whole table rather than the top three.
+
+## With a previous report
+
+The same project, recorded as a baseline one month earlier and re-run after two more rejections:
+
+```
+Change since the previous report
+  Against /tmp/rr-example/trend/.agent-cortex-docs/defect-report.json, reported 2026-04-01T09:00:00Z
+  criteria-unmet 1 (+1), docs-drift 1 (+1), missing-proof 1 (+1), and 5 more
+  First-pass review rate 75% (from 75%, no change)
+```
+
+The comparison reads the report the script wrote at `--baseline`, so it compares like with like.
+A class that did not change is not listed; when no class changed, the section says so. A baseline
+file with an unrecognised schema is refused rather than read as zeros, because a baseline that
+cannot be read must not become an invented trend.

package/skills/review/review-report/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: review-report
+description: Reports the defect classes a project's reviews recorded, with the pipeline's first-pass review rate, fix rounds per stage and the change since the previous report, and files that report upstream. Use when you ask "what keeps failing", "defect report", "which skill should change", or "file this as package feedback".
+---
+
+# Review report
+
+`review-defects` gives every rejection one class, so rejections become countable. This skill counts
+them: one report naming which classes recur, the shipped skill that owns each failing rule, and the
+pipeline's own rate — then, as a separate step, files that report upstream.
+
+## When to use
+
+- "What keeps failing?" — which defect class recurs across this project's changes.
+- Deciding which shipped skill to change, because a class keeps appearing.
+- Filing package feedback against the tool the project runs on.
+- Checking whether the review gate is improving, without reading closed beads one at a time.
+
+## When NOT to use
+
+- Applying a class to a rejection — that is `review-defects`.
+- Reviewing one change — that is the `review` stage.
+- Reporting work progress — beads and `bd-tool` own that.
+
+## What it measures
+
+| Metric | Derived from the tracker |
+|---|---|
+| Defects by class | every `defect:<class>` label on any bead, closed beads included |
+| First-pass review rate | parents holding exactly one `stage:review` chore |
+| Fix rounds per stage | `stage:fix` chores, attributed to the stage the fresh chore re-runs |
+| Change since the previous report | this report against the report kept at `--baseline` |
+
+The class vocabulary is not defined here. `review-defects` owns the closed list of classes, and
+the script parses that table at run time, so the words a reviewer applies and the words this report
+counts cannot drift apart. A class that appears as a label but not in the table is printed as
+vocabulary drift and is never counted as a class of its own.
+
+A fix round is attributed by chore state, not by prose: a rejected stage always creates a `stage:fix`
+chore plus a fresh instance of that stage, and the fresh instance declares a `blocks` dependency on
+the fix. The stage label it carries is the stage the fix round repaired. A fix chore that no fresh
+chore depends on is printed as `unattributed`, and the trend compares the per-stage counts only —
+so a movement inside `unattributed` shows in the snapshot and never in the trend.
+
+The class-to-skill mapping is `DEFECT_OWNERS` in `scripts/report.mjs` — one table, so a mapping edit
+is one edit. The suite fails when a mapped skill does not exist on disk, or when a class in the
+vocabulary has no owner.
+
+## Honest by construction
+
+The report never dresses an absent measurement as a number. The four degradation cases are:
+
+- **No defect label.** It says no label is set and prints no zeros, because zero labels is an absence,
+  not a measurement of zero defects.
+- **One labelled defect.** It prints the snapshot and says there is a single data point, so there is no
+  trend yet.
+- **No review chore.** It says no rate is reported, because absent is not zero.
+- **No baseline.** It prints the snapshot and says there is no previous report to compare against.
+
+One further rule governs what a count means rather than what it measures. A label is removed when the
+review that confirms its fix runs, so every count describes the unconfirmed defect set at that
+moment, never the whole history. The trend compares snapshots, and the report says so.
+
+## Workflow
+
+1. Run the report against the project:
+
+   ```bash
+   node <review-report-scripts>/report.mjs
+   ```
+
+   It reads two tracker queries, both read-only and both carrying `--all` — the defect query
+   `bd list --label-pattern 'defect:*' --all` and the chore tree. Without `--all` a query for a label
+   on a closed bead returns nothing.
+
+2. Cross-check two numbers by hand before trusting the report: count one class with
+   `bd list -l defect:<class> --all`, and count one parent's review chores with
+   `bd children <id> --json`. The report is a summary of queries you can run yourself.
+
+3. Keep a baseline when you want a trend. `--baseline <path>` compares against a report the script
+   wrote earlier, and `--record` keeps this report there:
+
+   ```bash
+   node <review-report-scripts>/report.mjs --baseline docs/defect-report.json --record
+   ```
+
+   The path is yours to choose, and a committed one is the only kind that survives. `.agent-cortex/`
+   is an ignored directory in a consuming project, and the working-docs directory is per-bead and lost
+   with the worktree, so neither can hold a trend across branches or machines. Commit the file if you
+   want the comparison to travel; leave it out of version control and the comparison is local.
+
+4. Read the report before it leaves the machine. The default run writes nothing and calls nothing.
+
+5. File it, once you have read it:
+
+   ```bash
+   node <review-report-scripts>/report.mjs --file
+   ```
+
+   `--file` is the only networked step, and it runs `gh issue create` — no push, no pull request, no
+   merge, and nothing written to the repository it files against.
+
+   `--file` with `--json` prints the model and then appends the `Filed: <url>` line, so that stdout is
+   no longer parseable JSON. File from a text run, or read the URL from the last line and drop it.
+
+## Choosing the feedback repository
+
+The repository is configuration, resolved in this order:
+
+1. `--repo <owner/name>`.
+2. `AGENT_CORTEX_FEEDBACK_REPO` in the environment.
+3. The `repository` field of the manifest the running install ships — the `package.json` of the
+   package `install pi` stages, or the `.claude-plugin/plugin.json` of the plugin `install claude`
+   stages. A manifest is read only when its `name` is one of this package's three shipped identities
+   — `PACKAGE_NAME` and `STAGED_PACKAGE_NAME` for the pi manifest, `PLUGIN_NAME` for the claude one,
+   all in `scripts/report.mjs` — so a consuming project's own manifest is never filed against.
+
+No repository slug is hardcoded, so an install files feedback to the package it was installed from.
+Both installs declare that field, so `--file` needs no further configuration. A copy that carries
+no such manifest — vendored into a project by hand, for example — cannot resolve one: `--file` then
+fails with a message naming `--repo` and the environment variable, and the report is printed first,
+so the measurement is never lost.
+
+## Verification checklist
+
+- [ ] The report printed counts that you can reproduce with the same queries by hand.
+- [ ] Every top class named an owning skill, and one example bead id.
+- [ ] The report was read before `--file` ran, and `--file` ran only if filing was wanted.
+- [ ] With no labels or no baseline, the report said so instead of printing a trend.
+- [ ] Nothing was pushed and no pull request was opened against the feedback repository.
+
+## See Also
+
+- [review-defects](../review-defects/SKILL.md) — the closed class vocabulary this report counts.
+- [run-pipeline-stage](../../workflow/run-pipeline-stage/SKILL.md) — the stage that applies the labels and builds fix rounds.
+- [style-tests](../../style/style-tests/SKILL.md) — the rule behind the `test-*` classes this report points at.
+
+Reports for the four degradation cases are in `EXAMPLES.md`.