task-pipeline-skill 1.14.0 → 1.15.0

package/CHANGELOG.md

@@ -1,5 +1,144 @@
 # Changelog
 
+## v1.15.0 — 2026-08-06
+
+### Added — the ten canons: what makes a document evidence
+
+The doctrine carried the mechanisms and never stated the standard they serve.
+`references/documentation.md` now opens with ten laws — a claim carries its address,
+numbers are computed rather than restated, one home per fact, a reference resolves from
+where the document is *read*, green nobody watched turn red is not evidence, a check
+proves its scope and nothing beyond it, silence is not a pass, an estimate is never
+announced as a measurement, what was not checked is printed beside what was, and the
+document ships in the change that made it true.
+
+Each canon **names where it is enforced** instead of restating the mechanism, and the
+boundary against `learned.md` is written down: the canons are epistemic (what makes a
+claim documentation), `learned.md` is operational (what to do at a trigger). Two
+undifferentiated rule lists would be the duplication canon 3 forbids.
+
+Guarded four ways: the list exists, all ten laws are present, every canon names an
+enforcement, and the boundary is stated. The enforcement check counts **per canon**
+rather than in total — a total threshold only fires once most of them are gone, which
+is a check proving less than it claims, canon 6 applied to itself.
+
+**Found while writing them, by this repository's own guard:** canon 9 cited
+`audit.md → Ratchets`, a section that lives in `gates.md`. The file resolved and the
+section did not — the shape a link checker cannot catch and a reader believes.
+
+### Added — a build date is the graph's reply about itself, not a measurement of it
+
+Stage 0 reads the code graph before it reads anything else, and until now it recorded
+that graph's freshness as `built YYYY-MM-DD`. That is true, self-reported, and silent
+about the only thing the harvest needs to know: whether the graph describes the tree
+this run is about to change. Twelve commits later the row still reads `built
+2026-08-05` — and still reads *fresh*, because a date with nothing subtracted from it
+is a fact with no scale. It is the class `references/gates.md` named one release ago:
+an actor's own reply, standing in for evidence about the world.
+
+The occasion was this repository's own. `docs/superpowers/specs/` holds a brief, a
+carry-over ledger and an acceptance document for v1.11.0, v1.12.0 and v1.13.0 — and
+none for v1.14.0 or v1.14.1. Those two releases never opened stage 9, so nothing
+refreshed the graph, and the next harvest would have read a two-release-old index
+behind a date that looked current.
+
+- **`references/knowledge-graph.md` gains *Measure the lag***: three commands
+  (`git rev-parse --verify`, `git rev-list --count`, `git log -1 --format=%ct`) so
+  the number comes from git rather than from judgement, and **three states** —
+  `built_at_commit` exact, file `mtime` approximate, and `unresolvable` — because
+  `graph.json` carries the commit stamp **only when the caller passed it** and
+  `graphify update` from the CLI does not. With one state, "could not measure" would
+  print like "fresh", which is the failure the section cites `gates.md` for. Zero is
+  stated out loud for the same reason.
+- **No threshold, deliberately.** `continuity.md` refused a context-budget number on
+  the same grounds: an unmeasurable threshold becomes unconditional doctrine, not
+  config. One commit that moved the function this task is about outweighs fifty that
+  touched a README, so anything but `current` carries `⚠ not trusted for reach until
+  refreshed` — a marker, not a block. The graph is recommended everywhere else in this
+  bundle; a blocking staleness check would make *no graph* cheaper than a week-old one.
+- **The cadence is untouched.** Stage 9 already required the refresh unconditionally,
+  and an `always | major | manual` mode was rejected rather than deferred: `major`
+  schedules exactly the state the doctrine warns about — a graph confidently wrong
+  between releases, read first by the next run.
+
+### Added — hygiene check 7: a blank line inside a table
+
+A GFM table ends at the first blank line, so a blank line left mid-table silently
+demotes every row below it to pipe-delimited prose. The file stays well-formed, every
+row is still present, and a diff showing only added lines shows nothing wrong. It
+happened **twice inside this run** — a carry-over ledger and the brief's decision
+table — which is `audit.md`'s threshold for a mechanism rather than a third ledger
+row. On its first armed pass the check found **three more** in the carry-over ledgers
+of v1.12.0 and v1.13.0, which had been rendering broken since the day they were
+written. All three are fixed rather than baselined behind a floor.
+
+The check shipped with `HYGIENE_FLOOR_7` undeclared, so `judge()` compared against an
+empty string and printed `ok: check 7 … 3 (floor )` over three real hits — the gate
+reporting a pass it never computed, on the release about exactly that. An undeclared
+floor is now a failure, not a zero, and the reason is written beside it.
+
+### Guards — 95 → 104, by extending a sibling rather than copying it
+
+`test/validate.py` already enforced that the code-graph doctrine be named in **both**
+halves of stage 9 — the config gate the orchestrator verifies and the section an agent
+reads — because a file that "reads as law while the run never does it" is an inert
+gate. Standing instruction R-003 requires running a fixed defect's definition against
+its siblings, and stage 0 is the sibling: same doctrine file, one duty reading the
+graph where the other refreshes it. So the existing guard was **extended**, not
+duplicated.
+
+At stage 0 the word *graph* is not the test — it was already there. The guard requires
+the **measured lag**, and three more checks keep the cited section honest: the commands
+must survive, all three states must survive, and `templates/brief.md` may not ship the
+superseded bare-date row to every project scaffolded from it.
+
+The repository's own drift guard caught the release mid-flight **three times**:
+`SKILL-CARD.md` and `evals/RESULTS.md` said *95*, then *100*, then *102*. Its message
+has always offered two fixes — *derive the number or delete it* — and three
+hand-corrections in one run is the answer to which one was right. **The prose no
+longer states a count at all**; it names the command that prints one. The guard's own
+negative self-test was rewritten in the same move: its plant used to edit the
+restated number in place, so it broke the moment the number went away — a test
+coupled to the defect it was written against rather than to the rule. It now
+*introduces* a count into a document that has none, which is what the guard actually
+forbids.
+
+### Fixed — one marker, one spelling
+
+The distrust marker this release introduces was written **four different ways inside
+the release that introduced it**: the doctrine's own three-state table omitted it
+entirely, its `unresolvable` row invented *"treat as stale until refreshed"*, and the
+Cursor rule and the config both dropped the sigil. Review caught the first; standing
+instruction R-003 — run a fixed defect's definition against its siblings — found the
+other three. `audit.md` says a class seen twice becomes a mechanism rather than a
+third ledger row, so a guard now requires the canonical string and rejects the second
+spelling. Greppability is the marker's only property: a ledger row is prose, and the
+marker is the one string a later reader can search for.
+
+That guard shipped green for the wrong reason and was caught by probing it rather
+than by reading it. It compared **per line**, and this doctrine wraps at ~80 columns —
+so in `README.md` and `stages.md`, where the marker is split across two lines, it
+matched nothing and reported a pass. It now normalises whitespace before counting.
+Two releases running, the defect found inside the release was an instance of the
+class the release was about.
+
+## v1.14.1 — 2026-08-05
+
+### Fixed — a guard below the verdict block is dead code shaped like a guard
+
+The fourteen guards v1.14.0 added were first appended to the *end* of
+`test/validate.py`, below `if errors: … sys.exit(1)`. On a clean run they executed
+after `PASS` was printed; on a corrupted one `sys.exit()` fired first and they never
+executed at all. Every one was green for the single reason that cannot be argued
+with: it never ran. The negatives runner caught it because it requires positive
+evidence (`OK:` in stdout) rather than a non-zero exit — this release's own subject,
+committed by the release that names it.
+
+A guard now reads the validator's own source and rejects any `fail(` after the
+verdict. It shipped with the same defect it checks for — `find()` matched the literal
+inside the guard's own body — and its negative self-test caught that within one run;
+`rfind`, with the reason written beside it. Guards 94 → 95.
+
 ## v1.14.0 — 2026-08-05
 
 ### Added — false success: the failure mode that removes the reason to look

package/CONTRIBUTING.md

@@ -225,7 +225,17 @@ side; `references/review.md` rates an effect asserted without one as **Important
 not Minor. A finding that never blocks is a finding the fix loop never sees.
 *(guard: `the report no longer requires verified-by lines`)*
 
-**30. Every invariant above names the guard that enforces it, and that guard exists.**
+**30. The code graph's ledger row states a measured lag, never a build date.**
+Stage 0 reads the graph first, so its freshness is the one claim a whole run rests
+on — and `built 2026-08-05` is the graph's own reply about itself, true and silent
+about whether it describes the tree the run is about to change. `stages.md`'s stage-0
+section and the config's stage-0 gate must both require the measurement, exactly as
+they do for the stage-9 refresh, and `references/knowledge-graph.md` must keep the
+commands and all three signal states — with a state missing, a graph that could not
+be measured prints like a fresh one.
+*(guard: `never requires it — a run passes intake quoting a`)*
+
+**31. Every invariant above names the guard that enforces it, and that guard exists.**
 This list claims to be *what the validator enforces*; it was eight guards behind when
 an audit measured it. A claim of enforcement is now checked like any other claim.
 *(guard: `whose message does not appear in`)* — and a cited literal must lie inside

package/README.md

@@ -238,8 +238,12 @@ then, in the project root:
 
 **Stage 0 asks it what grep can't** — `graphify query "how does session reach the
 API layer"`, `graphify affected "AuthModule"`, `graphify god-nodes` — and records it
-in the source ledger **with its build date**, because a graph goes stale exactly like
-a doc. It points; the code decides.
+in the source ledger **with its measured lag**, because a graph goes stale exactly
+like a doc. Not a build date: `built 2026-08-05` is the graph's own reply about
+itself, true and self-reported and silent about whether it describes the tree you
+are about to change. The row carries `N commits / M days behind HEAD`, the signal
+that measured it — and, on anything but `current`, `⚠ not trusted for reach until
+refreshed`. It points; the code decides.
 
 **Stage 9 closes three artifacts, not two.** Docs, wiki, **and the graph** — in the
 agent, so the documents this stage just edited are re-extracted too:

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.14.0 |
+| **Version** | 1.15.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. 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 (15 evals, 5 categories). **Never executed** — see [`evals/RESULTS.md`](evals/RESULTS.md) |
@@ -38,7 +38,7 @@ apply.
    instruction surface, and every one is linked directly from `SKILL.md`.
 2. Read `templates/docgate.sh` before seeding it; it is the only shipped script a
    host project will run on its own repository.
-3. Run `npm run test:all` — 94 guards, each with a negative self-test that plants a
+3. Run `npm run test:all` — every guard has a negative self-test that plants a
    defect and requires rejection.
 4. Run `python3 evals/run.py` for the behavioural protocol, and read
    `evals/RESULTS.md` for what has actually been observed.
@@ -54,7 +54,7 @@ apply.
 - **Versions are pinned by git tag** and mirrored into `sshlg-skills`'s catalogue.
   Rollback is `git checkout v<previous>` or pinning the previous plugin version;
   the previous version is never deleted.
-- **Behavioural evidence is missing, not merely thin.** 94 structural guards prove
+- **Behavioural evidence is missing, not merely thin.** The structural guards prove
   the skill is well-formed. Until `evals/RESULTS.md` carries a dated run, nothing in
   this repository proves it *behaves* — triggers correctly, stays quiet on a
   question, or performs the steps it documents.

package/cursor/rules/task-pipeline.mdc

@@ -86,8 +86,16 @@ you invented — it counts because the project names it). Query each by *this ta
 nouns; it is retrieval, not a full read; stop when the terms return nothing new.
 Write a short **source ledger** into the brief — source, what it says about this
 task, how fresh, and whether this run makes it stale. `none found` is a valid row;
-the graph's row carries its build date, because a graph goes stale like any other
-source, and it **points while the code decides** — never the tiebreaker.
+the graph's row carries its **measured lag**, not a build date — run
+`git rev-list --count <built_at_commit>..HEAD` and record `N commits / M days behind
+HEAD` plus the signal it came from (`built_at_commit` exact, file `mtime`
+approximate when the graph carries no stamp, or `unresolvable` when the stamp does
+not resolve here), ending in `⚠ not trusted for reach until refreshed` on anything
+but `current` — that exact string, so one marker is greppable across every
+ledger. A date is the graph's own reply about itself; the lag is the only part
+that says whether it describes the tree you are about to change. A graph goes stale
+like any other source, and it **points while the code decides** — never the
+tiebreaker.
 **Read `docs/superpowers/retro.md` in full if it exists** — its *standing
 instructions* are what previous runs of this pipeline got wrong in this project, and
 they bind this run (they are capped at ten, so reading them all is cheap). Stamp

package/evals/RESULTS.md

@@ -37,7 +37,8 @@ or it belongs in a check.
 | Dated runs recorded | **0** | 2026-08-03 |
 
 The bottom two numbers are the honest state of this skill's behavioural evidence.
-Everything else in this repository is proven by 94 structural guards that check the
+Everything else in this repository is proven by structural guards — the count is
+whatever `npm run test:all` prints, deliberately not restated here — that check the
 *form*; these are the only checks that would speak to the *behaviour*, and they have
 not been run yet. Printed here so "63 of 63 green" is never read as "the skill is
 known to work".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.14.0",
+  "version": "1.15.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

@@ -2,7 +2,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/manual gates, a frozen requirement spine that must close with evidence, a loop guard that breaks churn, one provider-agnostic model confirmed up front, and an optional super-ux UX track for user-facing work.",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/task-pipeline/skills/task-pipeline/pipeline.example.json

@@ -18,7 +18,7 @@
       ],
       "gate": {
         "type": "manual",
-        "check": "MANDATORY stage — never skipped (only sanctioned bypass: the entry-from-super-ux short-circuit). PHASE 1, before the first question: harvest the knowledge sources (references/knowledge-sources.md) — code, THE CODE GRAPH when one is built (references/knowledge-graph.md: graphify query/affected/god-nodes answer reach, which grep cannot; detect graphify-out/graph.json — recommended, never required), CLAUDE.md/AGENTS.md, CONTEXT.md + docs/adr, docs/ + docs/ux, past pipeline briefs and carry-over ledgers, THE RETRO'S STANDING INSTRUCTIONS (docs/superpowers/retro.md — read IN FULL, not queried: they are capped at ten and they BIND this run; stamp each one the moment it fires, since that date is the only evidence behind stage 10's cold-retirement rule — references/retrospective.md), the knowledge wiki when installed (obsidian-wiki — recommended, never required; detect ~/.obsidian-wiki/config), and any other repo or hosted doc system the project names as its docs — queried by this task's own terms, with the SOURCE LEDGER written into the brief (a row per source consulted, or an explicit 'none found'; the graph's row carries its build date, because a graph goes stale like any other source). PHASE 2, the grill, built into the skill (references/grill.md) — no companion to install. Per its contract: one question at a time, a recommended answer with each, explore the codebase/docs before asking, depth-first, contradictions reconciled; EVERY answer that touches a harvested source is validated against that source — the operator outranks any document, but only out loud, and the losing side is logged for the stage-9 doc update; domain awareness applied (terms challenged against CONTEXT.md, ADRs recorded for hard-to-reverse calls). The autonomy sweep is covered — every stage 1-10 has its blockers pre-resolved (docs sources, branch/tracker policy, test + lint commands, deploy target and authorization, log/health locations, docs+wiki targets, and for UI tasks the design surface: Figma on or text-only, is the Figma MCP connected, and if it is not — ship text-only or stop and connect it, since the UX chain degrades on its own and never blocks; plus, with Figma on, the DESIGN DESTINATION — which team/org by name and which file (the recorded one, a URL the operator gives, or creation in that named team with the creation explicitly authorized), written into the project's canonical record before the first frame, and never created while a recorded file resolves — an unreachable recorded file means stop and ask, never make a replacement) or is explicitly marked 'stop and ask here'. UI verdict recorded (arms super-ux); model decision recorded. All of it locked into a committed task brief the operator confirms before stage 1. The REQ table is written — one row per independently verifiable deliverable, each naming how it is verified — and frozen: adding later is free, removing or narrowing needs the operator's explicit agreement. The carry-over ledger is seeded. PHASE 1b, THE DOCUMENTATION INVENTORY (references/documentation.md): four questions answered into docs/DOCMAP.md before the interview — where settled things live (the DECISION HOME, and there is exactly one per project: an existing docs/adr/ IS the register and is recorded as such, never duplicated), what each fact's single home is, what a change of type X obliges (THE PROPAGATION MATRIX, non-empty, every row naming the check that enforces it or the word 'review' with a one-line reason), and what proves it (the gate command). A project with no answers gets them seeded — registers, matrix and scripts/check-docs.sh from the skill's templates — and the seeding is recorded as the register's first entry; the seeded gate must exit 0 on its own seeds, because a project that starts red teaches everyone on day one that the gate is noise. The regime is recorded. PHASE 1c, RECONCILE: git says how it should be, the run record says how it turned out — read both for the area about to be touched and resolve every divergence (the document is stale, the record is wrong, or they genuinely disagree and that is a decision), because starting on an unresolved divergence means building against a system that does not exist. The retro's in-force sections are read IN FULL and its archive is QUERIED by the task's nouns."
+        "check": "MANDATORY stage — never skipped (only sanctioned bypass: the entry-from-super-ux short-circuit). PHASE 1, before the first question: harvest the knowledge sources (references/knowledge-sources.md) — code, THE CODE GRAPH when one is built (references/knowledge-graph.md: graphify query/affected/god-nodes answer reach, which grep cannot; detect graphify-out/graph.json — recommended, never required), CLAUDE.md/AGENTS.md, CONTEXT.md + docs/adr, docs/ + docs/ux, past pipeline briefs and carry-over ledgers, THE RETRO'S STANDING INSTRUCTIONS (docs/superpowers/retro.md — read IN FULL, not queried: they are capped at ten and they BIND this run; stamp each one the moment it fires, since that date is the only evidence behind stage 10's cold-retirement rule — references/retrospective.md), the knowledge wiki when installed (obsidian-wiki — recommended, never required; detect ~/.obsidian-wiki/config), and any other repo or hosted doc system the project names as its docs — queried by this task's own terms, with the SOURCE LEDGER written into the brief (a row per source consulted, or an explicit 'none found'; THE GRAPH'S ROW CARRIES ITS MEASURED LAG — commits and days behind HEAD, the signal it was measured with (built_at_commit exact / mtime approximate / unresolvable), and the marker '⚠ not trusted for reach until refreshed' — that exact string, so one marker is greppable across every ledger — on anything but current. A bare build date does NOT satisfy this: it is the graph's own reply about itself, true and self-reported and silent about whether the graph describes the tree this run is about to change — references/knowledge-graph.md -> Measure the lag, and references/gates.md -> False success for the class). PHASE 2, the grill, built into the skill (references/grill.md) — no companion to install. Per its contract: one question at a time, a recommended answer with each, explore the codebase/docs before asking, depth-first, contradictions reconciled; EVERY answer that touches a harvested source is validated against that source — the operator outranks any document, but only out loud, and the losing side is logged for the stage-9 doc update; domain awareness applied (terms challenged against CONTEXT.md, ADRs recorded for hard-to-reverse calls). The autonomy sweep is covered — every stage 1-10 has its blockers pre-resolved (docs sources, branch/tracker policy, test + lint commands, deploy target and authorization, log/health locations, docs+wiki targets, and for UI tasks the design surface: Figma on or text-only, is the Figma MCP connected, and if it is not — ship text-only or stop and connect it, since the UX chain degrades on its own and never blocks; plus, with Figma on, the DESIGN DESTINATION — which team/org by name and which file (the recorded one, a URL the operator gives, or creation in that named team with the creation explicitly authorized), written into the project's canonical record before the first frame, and never created while a recorded file resolves — an unreachable recorded file means stop and ask, never make a replacement) or is explicitly marked 'stop and ask here'. UI verdict recorded (arms super-ux); model decision recorded. All of it locked into a committed task brief the operator confirms before stage 1. The REQ table is written — one row per independently verifiable deliverable, each naming how it is verified — and frozen: adding later is free, removing or narrowing needs the operator's explicit agreement. The carry-over ledger is seeded. PHASE 1b, THE DOCUMENTATION INVENTORY (references/documentation.md): four questions answered into docs/DOCMAP.md before the interview — where settled things live (the DECISION HOME, and there is exactly one per project: an existing docs/adr/ IS the register and is recorded as such, never duplicated), what each fact's single home is, what a change of type X obliges (THE PROPAGATION MATRIX, non-empty, every row naming the check that enforces it or the word 'review' with a one-line reason), and what proves it (the gate command). A project with no answers gets them seeded — registers, matrix and scripts/check-docs.sh from the skill's templates — and the seeding is recorded as the register's first entry; the seeded gate must exit 0 on its own seeds, because a project that starts red teaches everyone on day one that the gate is noise. The regime is recorded. PHASE 1c, RECONCILE: git says how it should be, the run record says how it turned out — read both for the area about to be touched and resolve every divergence (the document is stale, the record is wrong, or they genuinely disagree and that is a decision), because starting on an unresolved divergence means building against a system that does not exist. The retro's in-force sections are read IN FULL and its archive is QUERIED by the task's nouns."
       }
     },
     {

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

@@ -18,6 +18,7 @@ being written twice; write it once, here.
 
 ## Contents
 
+- The canons — what makes a document evidence
 - The inventory — four questions, answered before the first line of work
 - Registers and ids
 - Single source of truth
@@ -30,6 +31,71 @@ being written twice; write it once, here.
 - Where this binds in the pipeline
 - Rationalizations
 
+## The canons — what makes a document evidence
+
+Ten laws. Everything else in this file, and the mechanisms in [`gates.md`](gates.md),
+[`learned.md`](learned.md) and [`retrospective.md`](retrospective.md), exist to serve
+them. Where a canon is already enforced by something, the enforcement is **named, not
+restated** — a canon that repeats its own mechanism is the second home this system
+exists to prevent.
+
+**1. A claim carries its address.** Every fact that lands in a document names where it
+can be checked: `file:line`, a command with its output, a test name. A lesson names the
+commit that earned it. *"We verified it" is the sentence that passes every review and
+proves nothing.* → the retro's SHA-resolution guard; the finding shape in
+[`setup.md`](setup.md).
+
+**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.
+
+**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
+of them is updated. → *Single source of truth*, below.
+
+**4. A reference resolves from where the document is read.** Not from where it lives. A
+link correct in `templates/` and broken everywhere the template is seeded stays green
+under every link checker, because the checker resolves from the file's home. → invariant
+27; the seeded-template guard.
+
+**5. Green nobody watched turn red is not evidence.** A check must be seen rejecting a
+planted defect before its pass means anything — and the plant must be proven to have
+landed in the text the check actually parses. → [`gates.md`](gates.md) → *Probing*;
+[`learned.md`](learned.md) rules 4 and 5.
+
+**6. A check proves its scope and nothing beyond it.** Every gate carries what it does
+**not** cover, and quoting it wider is how "the gate is green" becomes a false statement
+made in good faith. "The docs are in sync" is a command with an exit code, never a
+sentence at the end of a report. → [`gates.md`](gates.md) → *Before you run a check*.
+
+**7. Silence is not a pass.** Ask of any mechanism: what does it print when it did not
+look? If that is indistinguishable from what it prints when it looked and found nothing
+wrong, it is not evidence. → [`gates.md`](gates.md) → *False success*.
+
+**8. An estimate is never announced as a measurement.** A rule that fires on a judgement
+states its **evidence condition** — the observable signal that licenses it. A false
+alarm does not cost one interruption; it costs the alarm. → [`continuity.md`](continuity.md)
+→ *The context budget*.
+
+**9. What was not checked is printed beside what was.** Absence is a finding with one
+side, so it never surfaces by comparison. Carry it as a named, counted set next to every
+verdict — a ratchet, never a TODO — so `PASS` reads as *"green, and here is what nobody
+looked at"*. → [`learned.md`](learned.md) rule 7; [`gates.md`](gates.md) → *Ratchets*.
+
+**10. The document ships in the change that made it true.** Not in the next ticket —
+documentation deferred is documentation that describes a system nobody is running. A
+correction is **appended**, never edited over: a register that is rewritten loses the
+fact that it was ever wrong, which is usually the useful part. → *The Doc Loop*, below.
+
+### What these are not
+
+They are **epistemic**, not operational: they say what makes a claim documentation, not
+what to do at a trigger. The operational layer is [`learned.md`](learned.md) — each rule
+there carries a trigger, a check and an exit criterion. When the two seem to say the same
+thing, the canon is the *why* and the rule is the *how*; edit the rule, cite the canon.
+
+---
+
 ## The inventory — four questions, answered before the first line of work
 
 Stage 0 answers these before the interview, and writes the answers to

package/plugins/task-pipeline/skills/task-pipeline/references/knowledge-graph.md

@@ -19,6 +19,7 @@ harvest simply runs on the sources it has
 
 - Detect it, and install it once
 - Stage 0 — query the graph before you ask the person
+- Measure the lag — a build date is a reply, not a measurement
 - Stage 9 — the close-out has three artifacts, not two
 - The divergence check — the graph against the docs
 - Rationalizations
@@ -78,10 +79,68 @@ Two rules keep it honest:
   belongs in the retrieval order right after the code, and never as the tiebreaker.
   Precedence, reflowed so it reads in one direction: code first, then host docs and
   ADRs, then the graph, then the wiki, then anyone's memory.
-- **Record it in the ledger with its build date** — source
-  `graphify-out/graph.json`, what it said about this task, how fresh, and therefore
-  whether stage 9 owes it a refresh. A source consulted but not recorded is a source
-  nobody will update.
+- **Record it in the ledger with its measured lag** — source
+  `graphify-out/graph.json`, what it said about this task, **how far behind `HEAD` it
+  actually is**, and therefore whether stage 9 owes it a refresh. A source consulted
+  but not recorded is a source nobody will update. How to measure it: next section.
+
+## Measure the lag — a build date is a reply, not a measurement
+
+[`gates.md`](gates.md) → *False success* gives the law — *an actor's own reply is not
+evidence about the world* — and the test: **what does it print when it did not look?**
+
+A build date is that kind of reply. `built 2026-08-05` is true, self-reported, and
+says nothing about whether the graph describes the tree this run is about to change.
+Twelve commits later it still reads `built 2026-08-05`, and it still reads *fresh* —
+a date with nothing subtracted from it is a fact with no scale. So the `Fresh?` cell
+of the graph's ledger row carries a **measured distance from `HEAD`**, the **signal it
+was measured with**, and — while that distance is not zero — a refusal to lean on it.
+
+**Compute it; never type it** ([`learned.md`](learned.md) rule 8). Three commands, and
+the first one's failure *is* a state rather than an error to handle:
+
+```bash
+git rev-parse --verify -q "<built_at_commit>^{commit}"   # which state applies
+git rev-list --count "<built_at_commit>..HEAD"           # commits behind
+git log -1 --format=%ct "<built_at_commit>"              # its timestamp → days behind
+```
+
+`<built_at_commit>` is read from the top level of `graph.json`. **It is written only
+when the caller passed it**, and `graphify update .` from the CLI does not — so the
+absence of a stamp is normal, not a defect, and it gets its own state instead of
+silence. Three states, each naming its signal — the same reason
+[`gates.md`](gates.md) → *Progressive arming* gives a dormant check a word of its own:
+
+| State | Condition | The `Fresh?` cell reads |
+|---|---|---|
+| **exact** | stamp present and resolves here | ``built `3944593` — 12 commits / 2d behind HEAD, signal: built_at_commit (exact) — ⚠ not trusted for reach until refreshed`` |
+| **approximate** | no stamp in `graph.json` | ``built ≤ 2026-08-05T22:47Z — signal: file mtime (approximate; no commit stamp, so this is a lower bound) — ⚠ not trusted for reach until refreshed`` |
+| **unresolvable** | stamp present, does not resolve here (rebase, squash, shallow clone) | ``built `3944593` — UNRESOLVABLE in this checkout, signal: none — ⚠ not trusted for reach until refreshed`` |
+
+Every row above is a **non-current** graph, so every row ends with the marker. The
+cell is quoted whole on purpose: a worked example is what gets copied, and an example
+that omits the thing it exists to demonstrate teaches the omission.
+
+**State zero out loud.** A current graph reads ``built `3944593` — current (0 commits
+behind), signal: built_at_commit (exact)``. Printing nothing when the graph is fresh
+is what makes freshness indistinguishable from a harvest that never looked, which is
+the failure this section cites `gates.md` for.
+
+**Anything but `current` ends the cell with `⚠ not trusted for reach until
+refreshed`.** The marker does not block — stage 0's gate is `manual` and this is a
+ledger row, not a gate. It tells the harvest what it may lean on; the run continues,
+it just stops quoting the graph as though it were current.
+
+**No threshold, deliberately.** [`continuity.md`](continuity.md) refused a
+context-budget number for the same reason: an unmeasurable threshold becomes
+unconditional doctrine, not config. "Ten commits is fine, eleven is not" is a number
+nobody can defend, and a number nobody can defend is one every run argues its way
+under — one commit that moved the function this task is about outweighs fifty that
+touched a README.
+
+**Promote it when it breaks, not before** ([`gates.md`](gates.md) → *Axis B*): this
+rule sits at rung 2, a criterion in stage 0's gate. Promote it to a script the first
+time a run is observed passing stage 0 with an unmeasured graph row.
 
 ## Stage 9 — the close-out has three artifacts, not two
 
@@ -160,7 +219,8 @@ sweep on every commit turns an audit axis into noise and it stops being read.
 | Excuse | Reality |
 |---|---|
 | "I'll just grep, it's faster" | Grep answers "where is this name". The questions that stop a run are "what reaches this" and "what breaks if it moves" — that is one query against a graph and an afternoon with grep. |
-| "The graph is probably stale" | Then it has a build date and you can say so. Stale-and-dated is a finding; stale-and-unknown is what you get by not building one. |
+| "The graph is probably stale" | Then measure it and say how stale — three commands, above. *Probably* is the word a run uses right before leaning on it anyway; `12 commits / 2d behind HEAD` is a finding, and `built 2026-08-05` on its own is only a date. |
+| "It says built today, that's fresh enough" | Today's date and today's `HEAD` are different claims. The date is the graph's own reply about itself; the lag is the one thing that says whether it describes the tree you are about to change. |
 | "Docs and wiki are updated, we're done" | The graph is the source the *next* harvest reads first. Leaving it behind is leaving a false premise where a machine will quote it back. |
 | "The divergence check found nothing, skip it next time" | It found nothing **on this axis, this pass**. Rotate the axis; that is the rule this check belongs to, not an exemption from it. |
 | "A hub with no doc is fine, everyone knows it" | Everyone currently on the team. The graph found it in one command; the person who joins next month will find it in a postmortem. |

package/plugins/task-pipeline/skills/task-pipeline/references/knowledge-sources.md

@@ -94,8 +94,11 @@ the directory doesn't (installed, not built).
 
 - **Built → query it** during the harvest: `graphify query "<the task, as a
   question>"`, `graphify affected "<the thing being changed>"`, `graphify god-nodes`.
-  Record the row **with the graph's build date**, because a graph is a source and
-  goes stale like one.
+  Record the row **with the graph's measured lag** — how far behind `HEAD` it is and
+  which signal said so — because a graph is a source and goes stale like one, and a
+  build date is the graph's own reply about itself rather than a measurement of it.
+  The three commands and the three states:
+  [`knowledge-graph.md`](knowledge-graph.md) → *Measure the lag*.
 - **Not installed → recommend it once**, in the preflight block, with the lines:
 
   ```bash

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

@@ -73,6 +73,7 @@ a row pointing outside the bundle is the defect this file exists to catch.
 | How the host project's own conventions are read | `references/conventions.md` |
 | Which companions exist, what is required, self-currency | `references/companion-skills.md` |
 | The code graph: queries, refresh, the graph↔docs divergence | `references/knowledge-graph.md` |
+| How the graph's staleness is measured and stated in the ledger | `references/knowledge-graph.md` |
 | Model policy — tier not id, ask once at preflight | `references/model-tiering.md` |
 | This boundary | `references/portability.md` |
 

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

@@ -93,7 +93,11 @@ never that the work was skipped quietly.
   ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki) — recommended,
   never required), and any **other repo or hosted doc system the project names as
   its docs**. Write the **source ledger** into the brief (a row per source, or an
-  explicit "none found"; the graph's row carries its build date). It is retrieval
+  explicit "none found"; **the graph's row carries its measured lag — commits and
+  days behind `HEAD`, the signal that measured it, and `⚠ not trusted for reach
+  until refreshed` on anything but `current`**
+  ([`knowledge-graph.md`](knowledge-graph.md) → *Measure the lag*; a build date is
+  the graph's own reply about itself, not a measurement of it). It is retrieval
   scoped by the task's own nouns, not a read of everything — and it is what makes
   phase 2's answers checkable instead of merely confident.
 - **Phase 1b — the documentation inventory**
@@ -152,7 +156,11 @@ never that the work was skipped quietly.
   an updated `CONTEXT.md` (terms written as they resolved) and any ADRs under
   `docs/adr/` — see `grill.md` → *Domain awareness*.
 - **GATE (manual):** shared understanding reached — **the source ledger is written
-  (every source consulted, or an explicit "none found")**, **the documentation
+  (every source consulted, or an explicit "none found")**, **where a code graph
+  exists its row carries the measured lag and the signal it was measured with — a
+  bare build date does not satisfy this, because it is the graph's own reply rather
+  than a measurement of it** ([`knowledge-graph.md`](knowledge-graph.md) →
+  *Measure the lag*), **the documentation
   inventory is answered into `docs/DOCMAP.md`** with its registers, single homes,
   a non-empty propagation matrix and the gate command, **the regime is recorded**,
   **intent and as-built are reconciled with every divergence resolved**, the retro's

package/plugins/task-pipeline/skills/task-pipeline/templates/brief.md

@@ -31,7 +31,7 @@ premise if the run leaves it wrong.
 | Source | What it says about this task | Fresh? | Authority | Stale after this run? |
 |---|---|---|---|---|
 | `docs/adr/NNNN-….md` | … | YYYY-MM | decision | no |
-| `graphify-out/graph.json` | reach: what calls it, what breaks if it moves | built YYYY-MM-DD | index | **yes — refresh at stage 9** |
+| `graphify-out/graph.json` | reach: what calls it, what breaks if it moves | built `<sha>` — N commits / M days behind HEAD, signal: built_at_commit (exact) — ⚠ not trusted for reach until refreshed | index | **yes — refresh at stage 9** |
 | wiki: `projects/…/concepts/…` | … | YYYY-MM | context | **yes — update at stage 9** |
 | `CLAUDE.md` | test/lint/deploy commands, house rules | current | convention | no |
 
@@ -66,7 +66,8 @@ source is a recorded decision, an unquoted one is an undetected divergence.
   what it returned: … (or `nothing`)
 - **Code graph:** built / installed-not-built / not installed
   ([graphify](https://github.com/Graphify-Labs/graphify); recommended, never a gate —
-  built → its row above carries the build date and stage 9 refreshes it)
+  built → its row above carries the **measured lag and the signal it was measured
+  with**, and stage 9 refreshes it)
 
 ## Scope
 

package/plugins/task-pipeline/skills/task-pipeline/templates/hygiene.sh

@@ -7,7 +7,8 @@
 # WHAT IT IS FOR: the defect class an AGENT produces and no other check looks for —
 #   a half-resolved merge, a stub that outlived its task, a generation cut off in the
 #   middle, a file "shortened" while being rewritten, a batch of edits where one
-#   applied twice, a section opened and abandoned.
+#   applied twice, a section opened and abandoned, a blank line left in a table so
+#   every row below it silently stops being one.
 #
 # SCOPE: walks tracked files. In diff mode it walks only what this run changed; in
 #   tree mode it walks everything, behind per-check floors.
@@ -26,9 +27,11 @@
 #     5 duplicated block   — a legitimately repeated stanza 3+ lines long
 #     6 empty section      — a heading used as a one-line record. If you have those,
 #                            they want to be list items: a heading promises a section.
+#     7 split table        — a document deliberately showing a broken table as an
+#                            example of the defect.
 #   Read this header before quoting a green from here as evidence.
 #
-# IT NEVER EDITS. It reports file:line and exits non-zero. None of the six is safely
+# IT NEVER EDITS. It reports file:line and exits non-zero. None of them is safely
 #   machine-fixable: deleting a "duplicated block" sometimes deletes a legitimate
 #   repetition, and deleting a TODO erases a reminder instead of discharging it.
 #   Fixing is the agent's job, and task-pipeline's references/build.md makes it one.
@@ -36,6 +39,8 @@
 # EXIT CODE IS THE OUTPUT: non-zero on any failure. Nothing may run after the
 #   VERDICT block at the bottom — a gate that appended a check after its verdict
 #   printed FAIL and returned 0, and CI was green over it for an unknown period.
+#   For the same reason, an UNDECLARED FLOOR is a failure, not a zero: check 7
+#   shipped without HYGIENE_FLOOR_7 and printed "ok … (floor )" over 3 real hits.
 #
 # PORTABLE to macOS bash 3.2: no grep -P, no sed -i, no readarray, no mapfile.
 #
@@ -62,6 +67,7 @@ HYGIENE_FLOOR_3=${HYGIENE_FLOOR_3:-0}
 HYGIENE_FLOOR_4=${HYGIENE_FLOOR_4:-0}
 HYGIENE_FLOOR_5=${HYGIENE_FLOOR_5:-0}
 HYGIENE_FLOOR_6=${HYGIENE_FLOOR_6:-0}
+HYGIENE_FLOOR_7=${HYGIENE_FLOOR_7:-0}
 
 TMP=${TMPDIR:-/tmp}/hygiene.$$
 mkdir -p "$TMP" || exit 2
@@ -117,6 +123,12 @@ floor_for() {
 
 judge() { # judge <n> <count> <label>
   _f=$(floor_for "$1")
+  # An undeclared floor made this print "ok … (floor )" while the count was 3 — the
+  # gate reporting a pass it never computed. Refuse rather than default to zero: a
+  # missing floor is a bug in the gate, and a bug in the gate is not a passing file.
+  case "$_f" in
+    ''|*[!0-9]*) err "check $1 — $3: no floor declared (HYGIENE_FLOOR_$1) — the gate cannot judge $2 finding(s)"; return ;;
+  esac
   if [ "$2" -gt "$_f" ]; then
     err "check $1 — $3: $2 finding(s), floor $_f"
     sed 's/^/         /' "$TMP/hits$1"
@@ -127,7 +139,7 @@ judge() { # judge <n> <count> <label>
 
 if [ "$NFILES" -eq 0 ]; then
   dormant "every check — no files in scope"
-  C1=0; C2=0; C3=0; C4=0; C5=0; C6=0
+  C1=0; C2=0; C3=0; C4=0; C5=0; C6=0; C7=0
 else
 
 # ---------- 1. conflict markers ----------
@@ -225,12 +237,41 @@ else
   judge 6 "$C6" "empty section"
 fi
 
+# ---------- 7. a blank line inside a table ----------
+# A GFM table ends at the first blank line. An agent appending rows to a ledger or a
+# decision register routinely leaves one behind, and the rows after it silently stop
+# being a table: they render as pipe-delimited prose with no header. Nothing else
+# here sees it — the file is well-formed markdown, every row is present, and the
+# defect is invisible in a diff that shows only the added lines.
+# Found twice in one run (a carry-over ledger and a brief's decision table), which is
+# what turns a finding into a check rather than a third ledger row.
+: > "$TMP/hits7"
+if [ "$NMD" -eq 0 ]; then
+  dormant "check 7 — blank line inside a table: no markdown in scope"
+  C7=0
+else
+  while read -r f; do
+    awk -v F="$f" '
+      /^[[:space:]]*(```|~~~)/ { fence = !fence; next }
+      fence { next }
+      { line[NR] = $0 }
+      END {
+        for (i = 2; i < NR; i++)
+          if (line[i] == "" && line[i-1] ~ /^\|/ && line[i+1] ~ /^\|/)
+            print F ":" i ": blank line inside a table — the rows below it stop being a table"
+      }
+    ' "$f" >> "$TMP/hits7" 2>/dev/null
+  done < "$TMP/md"
+  C7=$(wc -l < "$TMP/hits7" | tr -d ' ')
+  judge 7 "$C7" "blank line inside a table"
+fi
+
 fi
 
 # ---------- VERDICT — nothing may run after this block ----------
 if [ "$FAIL" -ne 0 ]; then
-  echo "FAIL: hygiene gate — mode $MODE · conflict ${C1} · placeholder ${C2} · fence ${C3} · truncation ${C4} · duplicate ${C5} · empty-section ${C6}"
+  echo "FAIL: hygiene gate — mode $MODE · conflict ${C1} · placeholder ${C2} · fence ${C3} · truncation ${C4} · duplicate ${C5} · empty-section ${C6} · split-table ${C7}"
   exit 1
 fi
-echo "OK: hygiene gate — mode $MODE · $NFILES file(s) · conflict ${C1} · placeholder ${C2} · fence ${C3} · truncation ${C4} · duplicate ${C5} · empty-section ${C6}"
+echo "OK: hygiene gate — mode $MODE · $NFILES file(s) · conflict ${C1} · placeholder ${C2} · fence ${C3} · truncation ${C4} · duplicate ${C5} · empty-section ${C6} · split-table ${C7}"
 exit 0