task-pipeline-skill 1.82.4 → 1.84.1

package/CHANGELOG.md

@@ -1,3 +1,159 @@
+## v1.84.1 — the conformance sentence is computed, and two of its five figures were wrong
+
+**A sentence of five measured figures, and nothing derived any of them.** The README's
+*Held to Anthropic's own Skill authoring guidance* paragraph states `name` length,
+`description` length, `SKILL.md` lines, the reference count and the bundle size. Measured
+2026-09-05:
+
+| stated | measured |
+|---|---|
+| `name` 13/64 | 13 ✓ |
+| `description` inside 1024 | 899 ✓ |
+| `SKILL.md` **334**/500 lines | **262** |
+| all **38** references | 38 ✓ |
+| **436 KB** against 30 MB | **1128 KB** |
+
+**The line figure was wrong when it was written.** At commit `297a0cb`, which added the
+sentence, the file was **339** lines — not 334. It was never a measurement, and a reader
+had no way to tell which of the five to trust.
+
+**The size figure changed SHAPE rather than value, and that is the decision worth
+recording.** It moved on four of the eight commits before this one — 950 → 970 → 980 →
+1128 KB — so an exact figure in prose goes stale by construction, and a check over it
+would fire on nearly every edit. *A check that fires constantly is one somebody turns
+off.* It is a bound now — **far under the 30 MB ceiling** — which stays true across three
+orders of magnitude and still says what the sentence exists to say.
+
+The other four are derived and compared on every run. The parser **asserts it found all
+four**: a sentence reworded past it fails here saying so rather than passing quietly,
+which is the shape that has twice made a healthy guard in this family report itself
+broken. Line count is `splitlines()`, stated in the failure message because `wc -l` over
+a file without a trailing newline gives a different number.
+
+Both directions watched failing, each plant asserting it landed first: a wrong figure
+gives *states lines = 999 and the tree gives 262*; deleting the reference clause gives
+*no longer states references in a shape this check can read*.
+
+Guards: 424 → **424** — the new check is an ordinary step, not a planted-defect guard.
+
+## 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

package/README.md

@@ -587,9 +587,9 @@ must say so.
 ### Held to Anthropic's own Skill authoring guidance
 
 Audited against the four Agent Skills pages. Most of it already held — `name`
-13/64 chars, `description` inside 1024, `SKILL.md` 334/500 lines, all 38 references
-linked **directly** from `SKILL.md`, 436 KB against a 30 MB ceiling. What did not,
-now does:
+13/64 chars, `description` 899/1024 chars, `SKILL.md` 262/500 lines, all 38 references
+linked **directly** from `SKILL.md`, and the bundle far under the 30 MB ceiling. What
+did not, now does:
 
 - **Every reference over 100 lines carries a `## Contents` list**, and the list is
   *compared against the file's own headings* rather than trusted. The guidance is

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.82.4 |
+| **Version** | 1.84.1 |
 | **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.82.4",
+  "version": "1.84.1",
   "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.82.4",
+  "version": "1.84.1",
   "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/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: