@jaybeeuu/agent-cortex 2.8.0 → 2.9.0

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

@@ -12,16 +12,23 @@ be counted, compared and trended across tasks instead of re-read one at a time.
 
 Apply exactly one class from this table. Never invent one.
 
-| Class | The defect | Evidence the rejection must show |
-|---|---|---|
-| `test-unproven` | A test's name claims a requirement its assertions never check. | The named clause, and the assertion that is missing. |
-| `test-cannot-fail` | An assertion passes against a broken implementation. | The case that should fail and does not. |
-| `criteria-unmet` | A criterion from the bead is not delivered. | The criterion, quoted, and what is absent. |
-| `scope-creep` | The change does more than the criteria ask. | The touched behaviour that no criterion names. |
-| `style-violation` | A `style-*` rule is broken. | The rule, quoted, and the line that breaks it. |
-| `missing-proof` | A report claims success with no evidence. | The claim, and the command output that is absent. |
-| `regression` | Behaviour that worked before now breaks. | The old behaviour, and the check that now fails. |
-| `docs-drift` | Shipped text no longer matches what ships. | The text, and the behaviour that contradicts it. |
+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.
@@ -59,17 +66,39 @@ 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.
 
-## An unknown class is itself a defect
+## No class fits: the escape hatch
 
-A class that is not on the list above is not a label. Applying one is a review defect in itself:
-state it in the rejection text, use the nearest real class for the finding, and raise the gap with
-the owner. Do not extend the list inside a review — a vocabulary that grows per rejection counts
-nothing.
+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
 ```
 
@@ -87,5 +116,6 @@ class that keeps appearing is a gap in the stage before this one.
 ## 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`.