task-pipeline-skill 1.81.1 → 1.84.0

package/CHANGELOG.md

@@ -1,3 +1,274 @@
+## v1.84.0 — fifteen filed findings, and the two rules they mostly refine
+
+Every one of the fifteen `ssheleg/sshlg-skills` issues this repository owned, closed in one
+release because they are one subject: **what a check is allowed to conclude.**
+
+**Ten new rules in `references/learned.md` (22 → 32), and two existing ones strengthened
+rather than duplicated** — the distinction matters, because a table that grows a row for
+every refinement stops being readable at exactly the point it starts being complete.
+
+- rule **4** (probe the detector) now demands the plant assert it **changed the file**, and
+  that the expected verdict be stated before the run — a green suite and an unlanded plant
+  are the same output (`#94`);
+- rule **8** (compute, never restate) now demands the matched items be printed classified
+  beside the count — *eighteen lines containing these three digits* and *eighteen throttle
+  events* are different claims, and only one was true (`#79`).
+
+The ten new ones, each carrying the incident it came from: a commit reference is a
+prediction until the object resolves (`#80`); a guard outliving the name it guards goes
+vacuous rather than red (`#81`); an item leaving a ranked list is not evidence about that
+item (`#87`); a model too small to reproduce cannot certify (`#89`); a sweep states its
+denominator before it starts (`#90`); guard capability, not incompleteness (`#91`); a
+census over a localised corpus reports per locale (`#92`); a gate scoped by exclusion
+judges every newcomer silently (`#93`); a gate needs a third verdict — *could not measure*
+(`#95`); a test whose assertion is implied by compilation is not a test (`#97`).
+
+**Three sub-canons in `evidence-docs`**, placed under the canons they refine rather than as
+an eleventh: **1a** a token that looks like evidence is not evidence until resolved; **2a**
+a number out of the shell is not a measurement until you look at what matched; **5a** a
+model too small to reproduce the defect is too small to prove the fix.
+
+**`prioritisation.md`** gains the half the existing rule was silent about (`#82`): the
+finder still may not rank by effort, the **fixer** weighs cost against *measured* harm, a
+zero-harm row is priced latent rather than deleted, and where the path is irreversible cost
+loses.
+
+**`retrospective.md`** gains two (`#85`, `#88`): what the prune does when it **cannot**
+run — an undefined case is where the spread between a careful run and a careless one lives
+— and that a fix to one call site closes a call site, not a class, with the sibling census
+taken by behaviour rather than from a list of names.
+
+**The high-water mark is derived now**, not typed: the validator caught `Numbers issued so
+far: 22` against a table reaching 32, which is the same defect these rules are about.
+
+Guards: 424 → **424** — doctrine, no mechanism.
+
+## v1.83.1 — the tag that could not be moved, and why that is right
+
+**No change to the skill.** `v1.83.0`'s tree carried a run stamp with `—` where its
+commit belongs, so the release gate refused it on the tag's own tree — correctly, and in
+the only place that can see it, because `validate.yml` ignores tag pushes.
+
+The stamp names `48544ac` now. **The tag was not moved**: a repository rule refuses to
+delete or re-point one, and that rule is right. A tag is a promise about a tree, the tree
+at `v1.83.0` genuinely lacked the stamp, and quietly re-cutting the same version over a
+different tree would make every future reader of that tag wrong about what it contained.
+So the repair is a version, not a rewrite.
+
+This is `ssheleg/sshlg-skills#80` met from the inside on the run that closed its
+neighbours: **a commit reference is written after the commit exists.** The record ships
+in a following commit rather than claiming a sha that did not exist when it was written.
+
+Guards: 424 → **424** — no mechanism changed.
+
+## v1.83.0 — an audit report is asked for, and four findings that had already cost something
+
+`project-audit`, closing `ssheleg/sshlg-skills#77`, `#78`, `#83`, `#84`.
+
+**A report is written when somebody wants a report.** The run wrote
+`docs/audit/<date>-audit.html` and opened it every time; it now writes the page only
+with **`--report`** (`--no-open` beside it to write without opening). The split is not
+symmetry: the **sidecar stays unconditional**, because `carry_forward` reads the previous
+one and skipping it would silently turn every future run into a first run. The page is
+different — a report outlives the conversation, and one nobody asked for is untracked
+HTML under `docs/`, one `git add -A` from the product's history.
+
+**`#83` — the telemetry probe read manifests and asserted about the product.** A project
+with a working home-grown error channel and no SDK dependency was reported as *"no error
+reporting found"*. The evidence is ordered and cheapest-first now, stopping at the first
+hit: a manifest dependency, a module named for the capability, a table or migration named
+for it, a mention in a documentation entry point. **And the KIND of evidence decides the
+verdict** — code or schema is `clean` with the channel named; a document alone is
+`blind`, because it establishes neither that the channel works nor that it is absent.
+The remedy sentence survives, which was the valuable half.
+
+**`#77` — a finding carries its consequence, or it is a hypothesis.** One audit had
+**eight consecutive rows** rewritten by measuring against production, two of which would
+have destroyed inventory if remedied as written, because both read an absence of sales as
+an absence of demand. A row now states how often the mechanism fires, or that it never
+has — in which case it is priced as **latent** and the remedy weighed against zero — or
+that the measurement is impossible, which is a `blind` on the consequence and not a
+finding.
+
+**`#78` — already decided is not a finding, and not nothing either.** Five of eight rows
+in one run reported decisions the project had already made, in the project's own words,
+because the decision sits a few lines from the cited code. The call site is read before a
+row is written, every row states which of three it is (undecided / decided here / decided
+elsewhere and not propagated), and where it is the third the remedy is **a mechanical
+check rather than an edit** — a written rule nobody verifies reaches exactly as far as
+the place it was written.
+
+**`#84` — an ordered preflight before any datastore read.** Resolve the store from the
+platform's own attachment rather than from a script or a document; prove liveness with a
+freshest-write aggregate and put that timestamp beside every figure it underwrites; name
+every attached store with its freshness; and treat the repository's connect helper as
+evidence about the repository, which is a finding of its own when the two disagree.
+
+Guards: 424 → **424** — this release adds no planted-defect guard. The three new checks
+live in `test/project_audit_test.py`, which `validate.yml` runs as an ordinary step
+rather than as one of its 429 `Negative self-test` steps, and the floor
+(`negatives.MIN_EXPECTED`) is unchanged. The new checks were still each watched failing
+against the un-fixed code, which is the property the count exists to protect and not the
+count itself.
+
+**One defect of my own, caught before it shipped:** the widened probe's first draft
+guarded with `hasattr(ctx, "excluded")` against a method that does not exist, producing a
+filter that was permanently false and silently did nothing. It reads `ctx.out_rel`, which
+is the real field.
+
+## v1.82.4 — the plant the harness could not see
+
+`v1.82.3` is a dead tag, and its cause is the **fourth distinct one**. Its stamp was
+correct and in the right order: the payload merged as `9e2ab3e`, the stamp cited it and
+landed as `e4e0eb4`, the tag was cut there, and the gate had accepted that tree.
+
+What failed was a negative self-test added in the same programme. `test/negatives.py`
+locates a plant's scratch directory by searching its script for a literal
+`cp -R . <dir>`, then diffs that copy against the repository to tell a real defect from a
+no-op. The duplicate-id plant copied **one file** and mutated the live tree, restoring it
+afterwards — correct as a workflow step, invisible to the harness. With no scratch
+directory it could not confirm the plant had landed, and reported the guard as one that
+**did not fire**. Correctly, by its own rule.
+
+The plant now follows the convention every other one uses: copy the tree, mutate the
+copy, run the validator from the copy, leave it mutated. Verified with the harness itself
+before shipping — `PASS: a board id naming two rows must fail`, the step that had never
+been run locally across four attempts.
+
+**`npm test` cannot see this**, because `negatives.py` is a CI step and not part of the
+suite. Four dead tags, four different mechanisms — a stamp in the wrong shape, a tag cut
+before the stamp existed twice, and now a plant the harness cannot verify — and one
+shared shape behind all of them: a green local gate that does not cover what the release
+runs. `B-134` carries it, and now asks for a preflight that runs the plant harness too.
+
+Guards: 424 → **424** — the plant is repaired, not added.
+
+**Landed 2026-09-02, and the release-gap check refused this tree first.** The repair above
+was green on every branch check and still declared no stamp for the release it was
+creating — a fifth instance of the same shape, caught because the tag was cut locally and
+`npm run test:all` was run against the tag's own tree before anything was pushed. The
+preflight `B-134` asks for is therefore not a new check: it is `test:all` on that tree,
+which is the only tree where four of the five failures can be seen at all. `npm test` runs
+three of its thirteen.
+
+## v1.82.3 — the release protocol is two merges, and their order is written down now
+
+**`v1.82.2` is a dead tag for the same reason `v1.82.1` was, and the run that burned it
+had just written the rule into this file.** A release here needs a stamp on the tag's own
+tree; the declaration v1.82.2 carried was for v1.82.1, the tag already dead. The payload
+merged as `9195590`, the tag was cut there, and nothing in that tree stamped the run.
+
+**The mechanism, stated so nobody pays for it a fourth time.** A stamp must cite a commit
+inside the NEW tag's own range, and that commit does not exist until the payload merges —
+the ruleset rebase-merges and mints every SHA at merge time. So a release is **two merges
+and their order is load-bearing**: the payload lands as `X`, a second change stamps the
+run citing `X` and lands as `Y`, and the tag is cut on `Y`.
+
+**Nothing refuses the wrong order before the tag exists.** `validate.yml` ignores tag
+pushes; `release.yml` is the first thing to run on the tag's own tree. So the branch is
+green either way and the cost is always a burned version, because the ruleset forbids
+deleting a tag. Three in one day: `v1.82.0` (stamp written in the sibling repository's
+bullet shape into a section this gate reads as a table), `v1.82.1` and `v1.82.2` (tag cut
+on the payload commit). That gap is now `B-134`, which asks for a preflight that resolves
+the range the tag would create and asserts a stamp falls inside it — a check that can run
+*before* anything is spent.
+
+Guards: 424 → **424** — this release records a protocol and adds no mechanism; the
+mechanism it asks for is the board row.
+
+## v1.82.2 — one id, one finding, and a status read from the wrong place
+
+**A board id identified two findings for the whole of v1.82.x.** `B-114` and `B-115`
+each named two rows: the pair filed on 2026-08-31 from the harness-engineering
+articles, and the pair this programme appended on 2026-09-01 without reading what was
+already there. Four rows, two ids — so a run stamp saying *"B-115 filed"*, a CHANGELOG
+naming the range `B-114…B-117`, and a sibling board citing either one all pointed at
+two different findings at once. The newer pair is renumbered `B-119` and `B-120`, and
+the stamp that cited them is repointed in the same change.
+
+**The guard, because renumbering fixes the case and not the class.** `test/validate.py`
+collected board ids into a **set**, where a repeat collapses leaving no trace — which
+is precisely why this shipped and stayed invisible. The new check reads row-leading ids
+only (`| B-NNN |`, first cell), so a prose citation of another row stays a citation
+rather than becoming a second definition, and it names both line numbers in its
+refusal. Watched failing before it shipped: a planted collision returns
+*"docs/evidence/backlog.md:110: id B-119 identifies a second row (the first is line
+109)"*. The umbrella has carried this guard for its own board; this repository is where
+the defect actually landed, and it had none. Guards: 423 → **424**.
+
+**Shipped as 1.82.2 because `v1.82.1` is a dead tag.** Its tree carried no stamp for its
+own run, so the release suite — which runs on the tag's own tree, where `validate.yml`
+never looks — refused it. The round was not lost to skipping the check: the gate **was**
+run against the merge commit, and its exit status was read from a trailing `echo` in the
+same command rather than from the suite, so a zero belonging to the `echo` was taken for
+the suite's verdict. An explicit re-run returned 1 seconds later. The rule from v1.82.0
+therefore gains its second half: verify with the gate rather than a grep of your own
+prose, **read the gate's own exit status**, and cut the tag locally, run the suite on the
+tag's tree, and push only then — a local tag can be moved, a pushed one cannot.
+
+## v1.82.1 — the second axis of blindness, and the scope the two-severity rule never had
+
+**This release is 1.82.0 and not 1.81.0, and the reason is worth recording.** 1.81.0 was
+already in flight in a concurrent session — the anchors-are-derived release — and this run
+picked the same number by reading `package.json` at branch time without asking whether
+anyone else held it. Worse, the tag was pushed **immediately after a `gh pr merge` that had
+printed a conflict and not merged**, so `v1.81.0` landed on the other session's commit and
+started its release before its run stamp was written. That release failed on exactly the
+guard that exists for it — *a release named nowhere in `Releases that carry no stamp`* — and
+published nothing. The tag cannot be deleted (a repository rule refuses it), so 1.81.0 stays
+spent and this work moves up. Standing instruction #8 in the umbrella's retro covers the
+mechanism: a wrapper's exit status is not the verdict, and it was not read.
+
+**Shipped as 1.82.1 because `v1.82.0` is a dead tag, and the reason is a check that read the
+wrong thing.** The run stamp for this release was written as a **list item** — the shape the
+sibling `sshlg-skills` uses — into a section this repository keeps as a **table**. The release
+suite therefore found no stamp covering the tag, refused it, and published nothing. Worse than
+the format slip: the verification run before tagging grepped for the stamp's own title and
+reported it present. **That confirmed the text existed, not that the gate could read it.** The
+tag cannot be deleted, so it is declared in `retro.md`'s no-stamp section and the payload moves
+one patch up.
+
+Guards: 423 → **423** — this release adds doctrine and no mechanism. Both findings argue
+against a rule rather than against a missing check, and the vertical blindness rule is
+explicitly one `certify` cannot verify from a report.
+
+**`certification.md` decoupled the three readers from each other and never decoupled the
+fixer from the grader.** Tier blindness is horizontal — no tier reads another's report, and
+`certify` refuses a report whose prose cites another tier. Nothing said the *vertical* half:
+the agent that produced a change may not be the agent that certifies it.
+
+That gap matters because the optimisation which closes it is attractive. The fixer already
+holds the context; a fresh reader has to re-derive it. Taking that saving converts
+certification into self-assessment **while every report it writes stays sincere** — an
+optimiser that grades itself learns to game the metric rather than improve the work, and
+`certify` cannot detect the collapse from a report. It is now a dispatch rule beside the
+one it belongs with.
+
+**And the two-severity rule shipped without its scope.** *There are two severities and no
+third, because a certification that admits a maybe admits everything* is correct — for a
+**finding**, which is a claim a reader makes about a diff and either blocks or does not.
+It is the wrong shape for the **verdict of a check** whose subject is non-deterministic,
+where binary pass/fail has been measured at **0% detection** of regressions and trace
+fingerprinting at **86%**. A third value there is not laxity: `INCONCLUSIVE`, grounded in
+hypothesis testing, is how a run says *this sample cannot decide* instead of flipping a coin
+and reporting the result as a severity. Sequential testing cuts the trials it needs by
+**78%**.
+
+So the rule now carries its boundary: **two severities for a finding, three verdicts for a
+stochastic check**, with the second axis pointed at `agent-stack`'s `agent-evals` —
+`references/statistics.md` for how many runs make a difference real — and at the skill's
+`references/gates.md` → *Axis A* for where such a gate belongs.
+
+**A fourth invisible class, with a measurement.** *Why one verifier is not enough* listed
+three defects a diff-reader cannot see; the fourth is the one a blended score cannot see
+either: **the internal state is right and the message about it is stale.** The value was
+stored correctly and the final sentence to the user echoed the old one — passing on state,
+failing on truth, so any grader that averages the two calls it mostly fine. It was caught by
+a rubric with categorical outcomes rather than a number, and closing it moved the violation
+rate from **21% to 4%**. Its general form is this pipeline's own worst case: work that
+**looks like it is working** while quietly missing what was asked — which is the product
+tier's whole job, and why the tier that reads no code is not the soft one.
+
 # Changelog
 
 ## v1.81.1 — the anchors are derived, and a dormant plant stops reading as a pass

package/SKILL-CARD.md

@@ -12,7 +12,7 @@ harmless.
 |---|---|
 | **Purpose** | Runs a substantial task through ten gated delivery stages — intake grill, docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs+registers, acceptance — refusing to advance until each gate passes |
 | **Owner** | ssheleg ([github.com/ssheleg/task-pipeline](https://github.com/ssheleg/task-pipeline)) |
-| **Version** | 1.81.1 |
+| **Version** | 1.84.0 |
 | **Surface** | Claude Code (filesystem skill + plugin) and the vercel `skills` CLI. **Not** uploaded to the Skills API; custom Skills do not sync across surfaces |
 | **Dependencies** | None required. Optional: `context7` (MCP), `figma` (MCP), super-ux, agent-sync, graphify, obsidian-wiki, and **one of two browser channels** — `playwright` (CLI or MCP) or `chrome-devtools` (MCP); either satisfies the browser step and neither is required. Every stage's doctrine ships in-repo; the one conditional requirement is super-ux for the stage-3 UX track on a user-facing task |
 | **Evaluation status** | Suite authored, 5 categories. One recorded run, **self-observed by the author**; **zero blind runs on zero of three models** — the split, and the numbers, live in [`evals/RESULTS.md`](evals/RESULTS.md) and are computed by `evals/run.py` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.81.1",
+  "version": "1.84.0",
   "description": "Full-cycle delivery pipeline for coding agents: a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine ships inside the skill — no companion plugin required. This package is the installer CLI.",
   "bin": {
     "task-pipeline": "bin/task-pipeline.js"

package/plugins/task-pipeline/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "task-pipeline",
   "displayName": "Task Pipeline",
   "description": "Runs a substantial task through a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine is built into the skill — no companion plugin required — with typed auto/judgment/manual gates, a frozen requirement spine that closes with evidence, a work board and a verification ledger that outlive a run, an exposure line naming what shipped unconfirmed, a progress rail computed from the project's own config, a loop guard whose review ceiling measures rather than stops, and stage-3 tracks for what a product does, how it sounds and how it looks. Two modes need no task: `checkup` (what is unverified) and `setup` (audit existing docs). Retro insights can publish upstream as issues, opt-in and redacted.",
-  "version": "1.81.1",
+  "version": "1.84.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/task-pipeline/skills/evidence-docs/SKILL.md

@@ -16,10 +16,13 @@ The full statement of each canon, its rationale and its enforcement live in
 ## The ten canons
 
 1. **A claim carries its address** — `file:line`, a command with its output, a test name; a lesson names its commit.
+   - **1a. A token that looks like evidence is not evidence until it has been resolved.** A sha, a line number, a path, a flag, a test name: every one can be plausible and absent, and each is trusted at exactly the moment nobody re-reads it. A commit reference is filled **after** the commit exists and checked with a command.
 2. **Numbers are computed, never restated.**
+   - **2a. A number out of the shell is not a measurement until you have looked at what matched.** Print the matched items classified beside the count whenever the token can occur inside something else, and never pipe a command whose exit status governs what happens next — the shell then answers about the pager. *Eighteen lines containing these three digits* and *eighteen throttle events* are different claims.
 3. **Every fact has exactly one home** — others link, never restate.
 4. **A reference resolves from where the document is read** — not from where it lives.
 5. **Green nobody watched turn red is not evidence.**
+   - **5a. A model too small to reproduce the defect is too small to prove the fix.** Reproduce first, fix second: a harness that goes green on the unfixed input is not a harness. Where the model is smaller than the subject, the gap is stated as a list of what it omits, with numbers.
 6. **A check proves its scope and nothing beyond it.**
 7. **Silence is not a pass** — ask what a mechanism prints when it did not look.
 8. **An estimate is never announced as a measurement** — a rule states its evidence condition.

package/plugins/task-pipeline/skills/project-audit/SKILL.md

@@ -84,6 +84,21 @@ cannot admit about itself:
   blind. Read aggregates and pointers, never raw bodies (see *The two
   artefacts*).
 
+**Before ANY datastore read, in this order** — a figure from the wrong database is
+worse than no figure, because it is quoted with the authority of a measurement:
+
+1. **resolve the datastore from the platform's own attachment**, not from a script
+   in the repository and not from a name in the documentation;
+2. **prove liveness with a freshest-write aggregate** against a table the product
+   writes constantly, and put that timestamp in the report beside every figure it
+   underwrites;
+3. where **more than one** datastore is attached, name them all with their
+   freshness — an audit that reads one and does not mention the other cannot be
+   reproduced by its reader;
+4. the repository's connect helper is **evidence about the repository**, never about
+   the platform. Where the two disagree that is a finding of its own, and it is the
+   one this rule was written from.
+
 ### 4. Seams — hand off to the ladder
 
 Now, and only now, walk `audit.md`'s ladder over the capabilities the discovery
@@ -91,9 +106,10 @@ found. Bottom-up, seam-ordered. Absences found here are findings like any other.
 
 ### 5. Report — two files, one command
 
-`python3 scripts/audit.py --root <path>` writes both and opens the page. It is
-the same script the probes live in, so what the report claims and what ran are
-the same object.
+`python3 scripts/audit.py --root <path>` writes the sidecar and prints a summary.
+Add `--report` for the HTML page, and `--no-open` beside it to write without
+opening. It is the same script the probes live in, so what the report claims and
+what ran are the same object.
 
 ### 6. Propose — rows, not edits
 
@@ -105,6 +121,51 @@ audit: what a fix costs is the fixer's decision, not the finder's
 (`references/prioritisation.md`). An audit
 that edits while it reads cannot be re-run to check itself.
 
+## A finding carries its consequence, or it is a hypothesis
+
+**A mechanism is derived from the code; the consequence lives in production.** A row
+written from the mechanism alone is indistinguishable from a real finding until
+somebody measures it — and one audit had **eight consecutive rows** rewritten by that
+measurement, two of which would have destroyed inventory if remedied as written,
+because both read an absence of sales as an absence of demand.
+
+So before a row may be written as a `finding` rather than as a hypothesis:
+
+1. **how often does the mechanism fire?** A query, a log count, a telemetry read — or
+   an explicit statement that it has never been observed to fire;
+2. **where the answer is *never*, the row is still worth keeping**, priced as
+   **latent**: the remedy is weighed against zero rather than against the mechanism's
+   severity;
+3. **where the measurement is impossible, that is a `blind` on the consequence** and
+   the row says so. A blind consequence is not a finding.
+
+Two rules follow from the same place:
+
+- **Check a remedy against the population it would touch before proposing it.** Two
+  rows prescribed releasing an asset class; the measurement showed the asset class was
+  the product's own inventory, deliberately held.
+- **An absence is not evidence until the path that would produce the presence has been
+  walked.** Zero sales means no demand *or* no working path, and those two want
+  opposite remedies.
+
+## Already decided is not a finding, and it is not nothing either
+
+An audit that reads a module and not the places the module is used reports, as
+defects, the things the project has already decided — **in the project's own words**,
+because the decision is usually written a few lines from the code the finding cites.
+Five of eight rows in one run were that.
+
+- **Read the call site, not only the definition.** A finding about a module is not
+  written until the places that use it have been read.
+- **Every row states which of three it is:** *(a)* undecided, *(b)* decided and
+  documented right here, *(c)* decided elsewhere and not propagated. Only **(a)** and
+  **(c)** are work. **(b)** is the audit being wrong, and recording that is worth more
+  than deleting the row.
+- **Where the verdict is (c), the remedy is a mechanical check, not an edit.** A
+  written rule nobody verifies reaches exactly as far as the place it was written; the
+  durable fix in all five cases was a guard that asks the project's own instruction of
+  every copy, not a patch to the copy that happened to be found.
+
 ## Three verdicts, and why the third one exists
 
 `clean` · `finding` · `blind`. The vocabulary is closed; a fourth value is
@@ -145,9 +206,17 @@ Two more traps, both of which shipped in the first draft and are now fixtures:
 - **Compare only when both sides claim the same version.** A branch already
   bumped past its tag makes no common claim, and is `blind`, not `clean`.
 
-## The two artefacts
+## The artefacts — the sidecar always, the page on request
+
+`docs/audit/<date>-audit.json` is written on every run. **The HTML page is written
+only with `--report`.**
 
-`docs/audit/<date>-audit.html` and `docs/audit/<date>-audit.json`.
+The split is not symmetry. The sidecar is what makes this a ratchet rather than a
+snapshot, and the next run reads it — skipping it would silently turn every future run
+into a first run. The page is a **report**, and a report is an artefact that outlives
+the conversation: one nobody asked for is a document nobody ordered and nobody
+maintains, sitting untracked under `docs/` one `git add -A` from the product's
+history. Answer in the conversation; write the page when somebody wants a page.
 
 **The page carries aggregates and pointers, never raw bodies.** Counts, top
 classes, trends, and a link to the issue in its own system — never a stack
@@ -170,7 +239,7 @@ picks up is a decision nobody wrote down.
 
 | The script | You |
 |---|---|
-| discovery, the registry, mechanical probes, both artefacts, the diff | the seam walk, MCP evidence, judgement about what a finding means |
+| discovery, the registry, mechanical probes, the sidecar, the page on `--report`, the diff | the seam walk, MCP evidence, judgement about what a finding means |
 | refuses a fourth verdict, redacts secrets, excludes its own output | deciding severity and effort, writing the remedy that fits this project |
 
 The split is not tidiness. **A judgement encoded in a script becomes a gate

package/plugins/task-pipeline/skills/project-audit/scripts/audit.py

@@ -940,6 +940,47 @@ def _p_worktree(ctx):
                            % len(state["paths"]))
 
 
+# A capability can be present without a dependency declaring it, and the words a
+# home-grown one is named after are predictable. Ordered cheapest-first; the probe
+# stops at the first hit.
+HOMEGROWN_TELEMETRY = re.compile(
+    r"(?:error|exception|crash)[-_]?(?:report|track|log|handler|monitor)"
+    r"|(?:report|track|capture)[-_]?(?:error|exception|crash)"
+    r"|error[-_]?(?:events?|feed)", re.I)
+
+
+def _telemetry_evidence(ctx):
+    """Everything short of a manifest dependency that says this capability exists.
+
+    The probe concluded from manifests alone, so a project with a working
+    home-grown error channel was reported as having none — and the finding read
+    `no error reporting found`, which is an assertion about the product rather than
+    about the manifest the probe actually read. Ordered cheapest-first, stopping at
+    the first hit, and the KIND of evidence is returned because it decides the
+    verdict: code or schema is `clean`, documentary alone is not a finding either.
+    """
+    # `out_rel` is where THIS run writes; a probe that reads it takes the audit's
+    # own artefacts for project state. There is no `ctx.excluded()` — the first draft
+    # guarded with `hasattr` and produced a branch that was permanently false, which
+    # is a filter that silently does nothing.
+    out = (ctx.out_rel or "").rstrip("/") + "/"
+    files = [f for f in (tracked_files(ctx.root) or []) if not f.startswith(out)]
+    for rel in files:
+        base = os.path.basename(rel)
+        if HOMEGROWN_TELEMETRY.search(base):
+            return ("module", rel)
+    for rel in files:
+        low = rel.lower()
+        if ("migration" in low or "schema" in low or low.endswith(".sql")) \
+                and HOMEGROWN_TELEMETRY.search(_read(os.path.join(ctx.root, rel), 40000)):
+            return ("schema", rel)
+    for marker in ("README.md", "CLAUDE.md", "AGENTS.md", "ARCHITECTURE.md"):
+        path = os.path.join(ctx.root, marker)
+        if os.path.exists(path) and HOMEGROWN_TELEMETRY.search(_read(path, 60000)):
+            return ("documented", marker)
+    return (None, None)
+
+
 @probe("telemetry", "prod", needs=())
 def _p_telemetry(ctx):
     found = ctx.profile.get("telemetry") or []
@@ -950,16 +991,29 @@ def _p_telemetry(ctx):
     if not deploy:
         return Result("clean", "no deploy target declared — a library or tool, "
                                "for which absent telemetry is a design, not a gap")
+    kind, where = _telemetry_evidence(ctx)
+    if kind in ("module", "schema"):
+        return Result("clean", "no telemetry dependency, but a home-grown channel "
+                               "is present (%s: %s) — the manifest was the wrong "
+                               "place to look" % (kind, where))
+    if kind == "documented":
+        # Documentary evidence cannot establish that the channel WORKS, and it
+        # cannot establish that it is absent either. Asserting absence over a
+        # document that describes the opposite is the defect this branch exists for.
+        return Result("blind", "no telemetry dependency and no module named for "
+                               "one, but %s describes an error channel — whether it "
+                               "works is not answerable from the tree" % where)
     return Result("finding", "no error reporting found", findings=[_finding(
         "telemetry", "manifests",
         "A deployed surface reports no errors anywhere its maintainer can see",
         "medium", 2, 2,
         "add an error reporter, or record the decision not to — the gap worth "
         "closing is that nobody wrote down which it is",
-        detail="Deploy targets declared (%s) with no telemetry dependency in "
-               "any manifest. A failure on a user's machine is invisible."
-               % (", ".join(deploy) or "none"),
-        evidence="languages=%s deploy=%s telemetry=[]"
+        detail="Deploy targets declared (%s) with no telemetry dependency in any "
+               "manifest, no module named for an error channel, and no mention in "
+               "the documentation entry points. A failure on a user's machine is "
+               "invisible." % (", ".join(deploy) or "none"),
+        evidence="languages=%s deploy=%s telemetry=[] homegrown=none"
                  % (",".join(langs), ",".join(deploy)))])
 
 
@@ -1207,8 +1261,11 @@ def main(argv=None):
     ap.add_argument("--root", default=".", help="project root (default: .)")
     ap.add_argument("--out", default=None,
                     help="output directory (default: <root>/docs/audit)")
+    ap.add_argument("--report", action="store_true",
+                    help="also write the HTML page and open it (default: the JSON "
+                         "sidecar and a stdout summary only)")
     ap.add_argument("--no-open", action="store_true",
-                    help="do not open the report in a browser")
+                    help="with --report, write the page but do not open it")
     ap.add_argument("--offline", action="store_true",
                     help="skip every probe that needs the network")
     ap.add_argument("--json", action="store_true",
@@ -1234,11 +1291,20 @@ def main(argv=None):
 
     json_path = os.path.join(out_dir, base + ".json")
     html_path = os.path.join(out_dir, base + ".html")
+    # The sidecar is unconditional: it is what makes this a ratchet rather than a
+    # snapshot, and `carry_forward` above has already read the previous one. Skipping
+    # it would silently turn every future run into a first run.
+    #
+    # The PAGE is a report, and a report is an artefact that outlives the
+    # conversation. Writing one nobody asked for leaves a document in the tree that
+    # nobody ordered and nobody maintains — and, being untracked HTML under `docs/`,
+    # it is one `git add -A` from the product's history. So it is opt-in.
     with open(json_path, "w", encoding="utf-8") as fh:
         json.dump(payload, fh, indent=1, ensure_ascii=False, sort_keys=True)
         fh.write("\n")
-    with open(html_path, "w", encoding="utf-8") as fh:
-        fh.write(render_html(payload))
+    if args.report:
+        with open(html_path, "w", encoding="utf-8") as fh:
+            fh.write(render_html(payload))
 
     if args.json:
         print(json.dumps(payload, indent=1, ensure_ascii=False))
@@ -1254,9 +1320,13 @@ def main(argv=None):
         else:
             print("  closed %d · new %d · still open %d"
                   % (len(r["closed"]), len(r["new"]), len(r["carried"])))
-        print("  %s\n  %s" % (html_path, json_path))
+        if args.report:
+            print("  %s\n  %s" % (html_path, json_path))
+        else:
+            print("  %s" % json_path)
+            print("  no page written — pass `--report` for the HTML view")
 
-    if not args.no_open:
+    if args.report and not args.no_open:
         ok, note = open_in_browser(html_path)
         if not ok:
             sys.stderr.write("could not open the report: %s\n" % note)

package/plugins/task-pipeline/skills/task-pipeline/references/certification.md

@@ -33,11 +33,23 @@ to it by construction:
 - a **second implementation of the same rule** did not get the fix
 - a **documented behaviour** is now false, and the document still reads as true
 - **another feature** reaches the same path and nobody considered the interaction
+- the **internal state is right and the message about it is stale** — the value was
+  stored correctly and the final sentence to the user echoed the old one
 
 None of these is a bug in the changed lines. All of them ship. Each is found by
 looking one level further out than the change — which is a different reading, not a
 longer one, because the context that finds it is the context that excludes the diff.
 
+**The last one is worth its own sentence, because it is the shape a blended score cannot
+see.** A run that stores the right value and then reports the stale one passes on state
+and fails on truth, so any grader that averages the two calls it mostly fine. It was
+caught by a purpose-built rubric with categorical outcomes — *honoured / ignored /
+partial / none* — rather than a number, and closing it moved the violation rate from
+**21% to 4%**. The general form is the dangerous one for this pipeline: work that **looks
+like it is working** — confident answers, a plan that reads fine — while quietly missing
+what was actually asked. That is the product tier's whole job, and it is why the tier
+that reads no code is not the soft one.
+
 ## The three tiers
 
 | Tier | Subject | Characteristic finding |
@@ -62,6 +74,16 @@ tier's verdict.
 Dispatch all three in one message so they run concurrently. Give each the node id,
 its `serves`, and the diff — nothing else, and never another tier's output.
 
+**The second axis, and it is the one an optimisation removes first: whoever produced
+the fix never grades it.** Tier blindness is horizontal — no tier reads another's
+report. This one is vertical: the agent that wrote the change, and the agent that
+certifies it, are different agents. The reason is not tidiness — *an optimizer that
+grades itself learns to game the metric instead of improving the work*, and it does so
+while every report it writes stays sincere. The saving on offer is real (the fixer
+already holds the context, a fresh reader must re-derive it) and it is the saving that
+converts certification into self-assessment. `certify` cannot detect the collapse from
+a report, so it is stated here as a dispatch rule.
+
 ## A pass has to mean something, so two rules have teeth
 
 **A tier cannot pass on an empty `scope`.** `scope` is what the tier actually
@@ -81,6 +103,24 @@ and no third, because a certification that admits a maybe admits everything:
   closing verdict as a blocker with `can_continue_around: true`, which is exactly
   what a named survivable finding is.
 
+**And the scope of that rule, because it is not universal.** These are severities of a
+**finding**, and a finding is a claim a reader makes about a diff — it either blocks or
+it does not. That is a different object from the **verdict of a check**, and where the
+check's subject is non-deterministic the two-valued form is not strictness, it is
+blindness: binary pass/fail has been measured at **0% detection** of regressions in a
+non-deterministic workflow, where mapping execution traces to compact vectors and
+testing them multivariately reaches **86%**. A third value there — `INCONCLUSIVE`,
+grounded in hypothesis testing rather than in a reader's judgement — is what lets a
+run say *this sample cannot decide* instead of flipping a coin and reporting it as a
+severity. Sequential testing cuts the trials such a verdict needs by **78%**.
+
+So: **two severities for a finding, three verdicts for a stochastic check.** A
+deterministic command exits 0 or it does not, and admitting a maybe there does admit
+everything. The instrument for the other case is `agent-stack`'s `agent-evals` —
+`references/statistics.md` for how many runs make a difference real — and a gate whose
+subject is non-deterministic belongs on that axis rather than this one
+([`gates.md`](gates.md) → *Axis A*).
+
 ## The report, and where each field lands
 
 Eight keys, all required, `[]` a valid answer and silence not one. On a pass

package/plugins/task-pipeline/skills/task-pipeline/references/learned.md

@@ -29,11 +29,11 @@ to be enforced and is not is the same failure as a gate that prints `FAIL` and e
 | 1 | **Change the axis when it stops paying** | any second review or audit pass | count new findings and self-inflicted ones separately | self-inflicted exceeds new → change the axis, do not "look again more carefully" |
 | 2 | **Absence needs its own check** | any two-layer model — entity/table, screen/frame, task/module, requirement/test | compute the mapping in **both** directions | zero orphans each way, printed |
 | 3 | **Verify closure against the artefact** | closing anything that names a design, a build or a file | open the artefact, not the document describing it | the artefact carries a marker naming what it was last verified against |
-| 4 | **Probe the detector** | every new check, lint rule or assertion | plant the defect → run → assert non-zero; restore → assert zero | both directions observed once, and recorded |
+| 4 | **Probe the detector** | every new check, lint rule or assertion | plant the defect → run → assert non-zero; restore → assert zero. **The plant asserts it CHANGED the file** — `assert text.count(old) == 1` before substituting — and the expected verdict is stated before the run, because a green suite and an unlanded plant are the same output | both directions observed once, and recorded; the plant's own effect asserted, and restored from a copy taken before it rather than by `git checkout`, which discards whatever else was uncommitted |
 | 5 | **Doubt the probe first** | a check that stays silent when it should fire | prove the planted defect exists in the text the check actually parses | the probe is shown to have changed what the check reads |
 | 6 | **Sweep the class, not the finding** | any correction | grep the whole corpus for the same shape before closing | the class is gated, or named in the note so the next reader can finish it |
 | 7 | **Ratchet, never TODO** | anything that cannot be fixed now | a named, counted set printed on every run | the number may only fall, and `OK` prints it beside itself |
-| 8 | **Compute, never restate** | any count or cross-reference stated in prose | derive it from the source at check time | the stated number and the computed one are the same object |
+| 8 | **Compute, never restate** | any count or cross-reference stated in prose | derive it from the source at check time. **Where the token could occur inside something else, print the matched items classified beside the number** — `grep -oE '<token>' \| sort \| uniq -c`, never a bare `grep -c` — because *eighteen lines containing these three digits* and *eighteen throttle events* are different claims and only one of them was true | the stated number and the computed one are the same object, and the run has looked at WHAT matched, not only how many |
 | 9 | **A generator seeds green** | any scaffold, template or code generator | run the generated project's own checks inside the generator's tests | fresh output exits zero |
 | 10 | **Measure a detector before trusting it** | a new heuristic check | run it over the real corpus and count false positives | zero false positives, or the heuristic is replaced by a deterministic rule |
 | 11 | **A gate's exit code is part of its output** | any gate or CI step | run it against a planted defect and assert on `$?` | non-zero, not merely a `FAIL` line on stdout |
@@ -48,6 +48,16 @@ to be enforced and is not is the same failure as a gate that prints `FAIL` and e
 | 20 | **When a thing exists twice, ask which one is used — not whether they agree** | any artifact with a second copy: two build files, a vendored library, a schema and its mirror, doctrine in two documents | find the **consumer** and read what it names; the copies cannot answer this about themselves | the run names the file the build/test/deploy actually reads, quoted from the consumer |
 | 21 | **A step that consumes what a later step produces is a deadlock, not an ordering** | any sequence where a check reads state another step writes — a prune reading stamps, a gate reading a ledger, a report reading counts | trace each input to the step that writes it; if that step is downstream, the check has never run on real data | every check names the step that produces its input, and that step is upstream of it |
 | 22 | **An operation that changes nothing reports the same as one that changed everything** | a substitution whose needle is absent · a command whose output is suppressed at a decision point · an edit issued against a shape the file does not have | assert the effect, not the call: a replacement must report how many times it matched, and a command whose exit code governs the next step is never piped or silenced | four incidents in two programmes, each invisible until something downstream failed — an import that never landed, a doctrine phrase worded differently, a `gh` call refused behind `>/dev/null`, and a test piped to `head` so that `$?` belonged to `head` |
+| 23 | **A commit reference is a prediction until the commit exists** | any record naming a sha, and by extension any token that looks like evidence — a line number, a file path, a flag name, a test name | fill the field AFTER the object exists and resolve it (`git cat-file -e <sha>`); where the record must ship inside the commit it names, name the commit that carried the CHANGE and let the record follow | every reference in the record resolves, checked by a command, not by its shape |
+| 24 | **A guard that outlives the name it guards goes vacuous, not red** | renaming or replacing any construct other files name | search the test suite for the old name in the same pass; and derive a guard's subject list from a **runtime declaration**, never a literal maintained by hand | the guard names its subjects by reading what the code says about itself, so a new member is covered by construction |
+| 25 | **An item leaving a ranked list is not evidence about that item** | any fix verified against a top-N report, a truncated list, or "it no longer appears" | re-run the SAME measurement of the SAME subject; and make every truncating report say what it dropped — `showing 5 of 12` | the closing evidence names the subject and its measured value, not its absence from a window |
+| 26 | **A model too small to reproduce the defect cannot certify the fix** | any reduced case, minimal repro, fixture or scratch tree standing in for the real subject | reproduce the defect in the model FIRST; if it goes green on the unfixed input it is not a harness | the fidelity gap is stated as a list of what the model omits, with numbers, not as prose that invites reasoning past it |
+| 27 | **A sweep states its denominator before it starts** | any pass over an enumerable corpus — locales, call sites, files, tools | name the size of the corpus up front and the number converted at close; and derive the guard from the set the project already enumerates, never from a list typed into the test | the closing evidence is a re-run of the finding census, not the diff — the diff shows what was touched, the census shows what is left |
+| 28 | **Guard capability, not incompleteness** | any completeness metric, coverage score or "N of M" axis | assert that an input exists for which the axis answers *no*; a count that only ever rises cannot tell a finished axis from one that lost the ability to fail | the probe finds its own subject rather than naming a fixture, and an axis that cannot say no is labelled WHERE THE NUMBER IS PUBLISHED |
+| 29 | **A census over a localised corpus reports per locale** | any pattern matched across translations, regions or notations | print subjects examined and subjects matched **per locale**; check the notation for numbers, units and signs in each target first | a locale reporting zero where its neighbours report several is raised as a question by the report's own shape — and where the subject is one fact in N dictionaries, compare the dictionaries to EACH OTHER, which needs no notation knowledge at all |
+| 30 | **A gate scoped by exclusion judges every newcomer silently** | any lint, format or check configured with an ignore list rather than an include list | scope by what it COVERS; where the tool has no such switch, assert the covered set and fail on additions, deriving the allowlist by measuring the tool's own reach | the failure message names the intruder and the remedy, because the operator meets it mid-release |
+| 31 | **A gate needs a third verdict — could not measure** | any check that can time out, lose a dependency, or run on a contended machine | distinguish *failed* from *could not measure* with different exit codes, and say which; neither is a verdict about the code | the refusal names its remedy, and a test that waits for a DURATION rather than an event is treated as a defect in the test |
+| 32 | **A test whose assertion is implied by compilation is not a test** | any test whose name promises a behaviour | delete the subject: if that is a type or import error rather than a red test, the test is decoration | removing one asks what the name PROMISED and whether anything checks it — four of five such cases here were covered elsewhere and the fifth was a real gap only visible because the name was read as a claim |
 
 ---
 
@@ -266,7 +276,7 @@ evidence that something left, and the log below says what.
 
 ### Retired
 
-**Numbers issued so far: 22.** This is the high-water mark, and it is the only number
+**Numbers issued so far: 32.** This is the high-water mark, and it is the only number
 this file states about itself — deliberately, because the gap that proves a rule left
 cannot be computed from the table alone: **deleting the highest-numbered rule shrinks
 the maximum with it, and no gap ever opens.** That false negative shipped in the first

package/plugins/task-pipeline/skills/task-pipeline/references/prioritisation.md

@@ -14,6 +14,7 @@ the **order** the rows come off it.
 - 2. Confidence and Ease
 - 3. The order, and why it is not a product
 - 4. Research before scoring, not after
+- Effort does not rank a finding, but the fixer needs a cost rule
 - 5. Where the human goes
 - 6. Two models in one family, and why both are right
 
@@ -128,6 +129,27 @@ four fields are the contract; anything else is a subagent that spent context to
 
 **Do not fan out to score two rows.** The dispatch costs more than reading them.
 
+## Effort does not rank a finding, but the fixer needs a cost rule
+
+The existing rule — **the finder may not rank by effort** — is about the finder, and it
+holds. It says nothing about the moment somebody decides what to do with the row, and the
+silence there was read as *cost never enters*, which is not what anyone means.
+
+So the split, stated rather than inferred:
+
+- **The finder** still may not rank by effort. What a fix costs is not a property of the
+  defect.
+- **The fixer**, at the point of deciding, weighs remedy cost against **measured harm** —
+  not against the finding's stated severity. Severity is the finder's estimate of what
+  could happen; harm is what did.
+- **Where the harm measures zero the row is not deleted.** It is priced as *latent* and
+  carries its measurement, so the next reader inherits the number rather than the alarm.
+  A row deleted for measuring zero takes the measurement with it and the next audit
+  re-derives the same alarm from the same mechanism.
+- **Where the path is irreversible, cost loses.** A cheap guard on something that cannot
+  be undone ships whether or not the failure has been observed — the asymmetry is the
+  whole reason to have a rule instead of a judgement.
+
 ## 5. Where the human goes
 
 The operator is a **scarce, high-value input**, and the failure mode is spending them one

package/plugins/task-pipeline/skills/task-pipeline/references/retrospective.md

@@ -39,6 +39,8 @@ file exists to stop.
 - Three grades of fix — take the highest one that can work
 - Stamp first, then prune, then write
 - The prune — mandatory, and it runs after the stamp
+- When the prune cannot run, say so — it is not the same as nothing to prune
+- A fix to one call site closes a call site, not a class
 - The loop closes at stage 0
 - Where a lesson goes when it is not about this project
 - Publishing the insight — the skill learns from every project that runs it
@@ -300,6 +302,33 @@ GATE 10 acceptance: PASS — 14/14 REQ verified
 
 A pruned list that nobody prints is a list that quietly grows back.
 
+## When the prune cannot run, say so — it is not the same as nothing to prune
+
+The prune retires a standing instruction against its triggers, and the cold trigger counts
+run stamps. Meeting a list whose rows carry **no id and no retirement condition**, the
+honest behaviour was undefined — so a careful run printed counts and stopped while a
+careless one could delete nine rules, and both looked like *the prune ran*.
+
+- **Backfill first, once.** On meeting rows with no id, the prune's first act is to mint
+  ids and propose a retirement condition per row **from the row's own text**, printed for
+  the operator to accept. One pass, and the trigger works forever after.
+- **`blocked` is a named outcome**, printed like any other: what could not be evaluated
+  and why. An undefined case is where the spread between two runs lives.
+- **A hard cap plus an unrunnable retirement condition is a deadlock.** Either the cap
+  yields until the backfill is done, or the backfill is a precondition of enforcing it —
+  but not both, and the file says which.
+
+## A fix to one call site closes a call site, not a class
+
+- **A fix other call sites will need is exported before it is used.** The test is
+  mechanical: if the same defect could exist in a second file, the fix does not stay
+  private to the first.
+- **Closing a defect includes a census of its siblings, by BEHAVIOUR rather than by a list
+  of names** — *every script that spawns a browser*, found by searching for the spawn, not
+  by remembering the five. A list of names is how the previous pass missed four of them.
+- **The entry states how many call sites the class had and how many were fixed.** *Fixed*
+  and *fixed in one of five* currently read identically, and only one of them closes a row.
+
 ## The loop closes at stage 0
 
 The standing instructions are an **instruction source**, not background reading: