task-pipeline-skill 1.74.0 → 1.76.0

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

@@ -200,10 +200,18 @@ plugins/task-pipeline/
     templates/                                # skeletons seeded into a host project
       hygiene.sh docgate.sh                 # -> scripts/check-hygiene.sh, check-docs.sh
       README.md                             # the index — and it is the list, not a copy of it
+    scripts/graph.py                          # the work graph, walked so the model never reads it
+  skills/evidence-docs/SKILL.md               # the ten canons, as a navigator
+  skills/project-audit/                       # a whole project as the subject
+    SKILL.md                                  #   the six phases, cold start
+    references/probes.md                      #   the probe catalogue, by stack and shape
+    scripts/audit.py                          #   discovery, registry, HTML + JSON sidecar
+  commands/project-audit.md                   # /project-audit
 cursor/rules/task-pipeline.mdc                # Cursor channel (self-contained rule)
 bin/task-pipeline.js                          # npx installer (package task-pipeline-skill)
 install.sh                                    # POSIX installer
 test/validate.py                              # structural validator (npm test)
+test/graph_test.py  test/project_audit_test.py  # the other two halves of `npm test`
 .github/workflows/{validate,release}.yml      # CI + toggleable release automation
 .github/ISSUE_TEMPLATE/  .github/PULL_REQUEST_TEMPLATE.md
 package.json  .gitignore

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

@@ -34,6 +34,14 @@ whose whole job is "audit X" runs nothing else.
 | [`acceptance.md`](acceptance.md) | stage 10 | did everything **on the list** ship, with evidence? |
 | [`loop-guard.md`](loop-guard.md) | any **editing** loop churns | is this pass undoing the last one? |
 | **this file** | any **audit** pass | what is broken or missing that nobody has compared? |
+| the `project-audit` skill | a **whole project** is the subject | what is true of this repository today — from a cold start, with no brief |
+
+**`project-audit` is the cold-start caller of this file, not a second copy of
+it.** This ladder needs a REQ row and a module map to walk; most repositories
+have neither, and *"your spine is missing"* is a true first finding and a useless
+audit. That skill discovers what the project is, probes it, reads the production
+evidence a repository cannot hold, and hands phase 4 back here — so the method
+below stays the one place it is written.
 
 `loop-guard.md` governs loops that *change* things — the fix loop, a re-entered
 stage. Its trip means a decision is being re-litigated at the wrong altitude. This

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

@@ -49,9 +49,23 @@ the same run and a description of the behaviour is not the behaviour. → the re
 SHA-resolution guard; the finding shape in [`setup.md`](setup.md); [`tdd.md`](tdd.md) →
 *When the thing under test is an agent*.
 
-**2. Numbers are computed, never restated.** A count in prose is a number that was true
-once. Derive it at check time and compare the stated one against the computed one as the
-same object. → [`learned.md`](learned.md) rule 8.
+**2. Numbers are computed, never restated — and an example that instantiates a number
+IS one.** A count in prose is a number that was true once. Derive it at check time and
+compare the stated one against the computed one as the same object. → [`learned.md`](learned.md)
+rule 8.
+
+The half that costs more, because it is written by the person who understands the rule:
+**a document quoting a form as an example is indistinguishable from the form.** A release
+note explaining *"the count was written wrongly as `Guards: 412 → 412`"* has just placed a
+second readable count in a section whose count a gate reads — so when the probe removes the
+real one, the narrative still matches and the guard reports green over a section that states
+nothing. Measured three times in one hour on 2026-08-22, each time inside prose *about* this
+very failure: the release note, the board row filed against it, and the repair to the probe.
+
+The rule the umbrella already states for commands — **name a dead command, never claim it**
+— holds for a number, a version and a shape. Describe the wrong form; do not write it.
+*"the bold sat around the whole phrase instead of around the second number"* is checkable by
+a reader and invisible to a pattern; the same sentence with the digits in it is a live claim.
 
 **3. Every fact has exactly one home.** Other documents link to it; they never restate
 it. Two homes do not disagree on the day they are written — they disagree on the day one

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

@@ -31,6 +31,9 @@ elsewhere and is not restated here:
 - Anatomy of a project gate
 - Writing the check itself
 - Probing — plant, run, restore
+- A probe rots, and every way it rots reports green
+- A ratchet prices the rule, not the exception
+- Run the whole suite locally before you push the tag
 - The neighbour probe — plant the evidence outside the subject
 - A ratchet's matcher is itself a check, and it needs a near-miss
 - A green probe is evidence only if the mutation is known to have landed
@@ -385,6 +388,95 @@ Otherwise the next reader has to redo it to know whether it was ever done.
 
 ---
 
+## A probe rots, and every way it rots reports green
+
+The three assertions above prove a probe works **today**. They say nothing about the
+day after, and a probe is uniquely exposed: the thing it guards is the thing that moves
+it. Four rotted in one release on 2026-08-22, and none of them failed loudly — two
+reported `caught`, two reported nothing at all.
+
+**1. The anchor is a literal the guarded thing moves.** A probe pinned to *"the bundle
+is N reference files"* stops landing the day a reference file is added — on the release
+that changes the very number it guards. Same for a version, a count word, a phrase a
+release rewrites. **Derive the anchor**: read whatever the text currently says and make
+*that* wrong. A probe that computes `wrong = stated - 1` never needs maintaining.
+
+**2. The precondition is inherited from the tree rather than created.** This is the
+subtle one, because it is triggered by the system working correctly. A probe that
+narrows a declared gap to expose *releases after the newest run stamp* has nothing to
+expose the moment a release writes an honest stamp — the newest release is now the
+newest stamp. A probe requiring an `## Unreleased` section has none the moment a release
+absorbs it. **Both landed. Both proved nothing.** A probe must construct the state it
+needs: remove the stamp, write the section, then plant the defect.
+
+**3. The document quotes the form the probe removes.** Covered as
+[`documentation.md`](documentation.md) canon 2's second half, and it belongs here too
+because the probe is where it surfaces: prose describing the wrong shape *with real
+values in it* is a second instance of the shape. The probe deletes the real one, the
+narrative still matches, the guard is silent.
+
+**How to see it before CI does.** Ask one question per probe: *what does this probe
+LOOK FOR, and who is allowed to change it?* Where the answer is "the thing it guards",
+it is rotting already. A repository-wide sweep is one grep — a two-digit literal inside
+a needle, an `assert` or a `replace` — and the triage is: the number a probe **writes**
+is correct, the number it **looks for** is the defect.
+
+## A ratchet prices the rule, not the exception
+
+A floor that counts assertions is a floor that can be lowered by improving the code, if
+the assertions are attached to the wrong things.
+
+Measured: a coverage check called `check()` once per *exception* — a silent value, a kept
+value, a promise — and simply `continue`d on the ordinary case. Collapsing four kept
+values, **the remediation the requirement names first**, therefore dropped the count by
+four against its floor and turned the suite red on the stricter answer. The only way
+through was lowering a ratchet whose own reason says a falling count is how a deleted
+requirement hides — so a legitimate lowering and the failure the floor exists to catch
+became indistinguishable.
+
+**One assertion per subject examined, whatever its verdict.** The ordinary case asserts
+too. Then the floor is a function of how large the corpus is, not of how many exceptions
+it happens to contain, and doing the right thing can never lower it.
+
+**And measure the floor after the last edit, not before it.** Read the count, keep
+editing, restate the count you read — every floor set that way sits below the true one,
+and a floor is a minimum, so nothing ever says so. Where the gate cannot enforce
+equality — it must not, or the ratchet stops allowing growth — it can still **print the
+gap**: `floor 4026, ran 4027: 1 check is not pinned` turns a silent difference into a
+visible one for the cost of one line.
+
+## Run the whole suite locally before you push the tag
+
+Not a preference: an arithmetic. A release workflow that runs the full suite takes
+twenty-five to forty minutes per round, and it reports one failure at a time. The same
+suite on the machine that wrote the change takes twelve and reports all of them at once.
+
+On 2026-08-22 one tag took **five CI rounds** — a stray key in a `run:` block, a missing
+run stamp, a stamp cap, and then four rotted probes — where a single local `test:all`
+before the first push would have found the last four together. Every refusal was correct.
+The cost was entirely in asking the wrong machine.
+
+**A green local suite is not evidence until you know which checks LOOKED.** This
+instruction failed on its own release: the local run was green, CI was not, and the
+difference was a precondition asking `os.path.isdir(".git")` — false in a submodule
+checkout, where `.git` is a *file* holding a gitdir pointer. One check switched itself
+off in the only checkout the family is developed in, silently, and had been doing so
+since it was written. The repository had recorded that class **twice** already, in two
+other files, and this instance was missed both times: knowing a class is not sweeping
+it. Two consequences, and the second is the general one:
+
+- ask `exists`, never `isdir`, of anything named `.git`;
+- **a precondition that fails must disclose, not skip.** Where a check cannot run, it
+  appends to the unlooked list and the run prints it. A check guarded by a bare `and`
+  evaporates without a line of output, which is the one thing this file's own canon
+  forbids — and it evaporates most reliably in the environment its authors use.
+
+The rule has a second half, and it is the one that makes it stick: **a tag is the only
+thing that runs some checks.** A branch push cannot see a tag that does not exist yet, so
+the tag-ancestry check, the version-sync check and the run-stamp check have no earlier
+opportunity to fire. Locally, run them the way the release does — against the tree you are
+about to tag, with the suite the release claims.
+
 ## The neighbour probe — plant the evidence outside the subject
 
 A probe proves a guard rejects **the phrasing its author had in mind**. That is less than