task-pipeline-skill 1.8.0 → 1.9.0

package/evals/run.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""Validate the evaluation suite and print the run protocol.
+
+**This script does not run a model, and it never reports a pass.** Anthropic's
+guidance ships no runner for Skill evaluations ("There is not currently a built-in
+way to run these evaluations"), and a script that claimed to have executed one
+would be the exact failure this repository's own doctrine is written against — a
+tool describing a world it is not looking at.
+
+What it does:
+  * checks the suite is well-formed and covers every required category;
+  * prints each query with its expected behaviours, ready to run;
+  * checks RESULTS.md exists and says, honestly, when the suite last ran.
+
+    python3 evals/run.py           # validate + print the protocol
+    python3 evals/run.py --list    # ids and categories only
+
+Zero dependencies, same as the validator.
+"""
+import json
+import os
+import re
+import sys
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+SUITE = os.path.join(ROOT, "evals", "task-pipeline.evals.json")
+RESULTS = os.path.join(ROOT, "evals", "RESULTS.md")
+
+# The enterprise guidance requires coverage of triggering (both directions) and
+# ambiguity. The last two are ours: instruction following is where a ten-stage
+# skill actually fails, and coexistence is what a broad description breaks.
+REQUIRED = ("should_trigger", "should_not_trigger", "ambiguous",
+            "instruction_following", "coexistence")
+MIN_EVALS = 3          # Anthropic: "At least three evaluations created"
+
+
+def main(argv):
+    errors = []
+    if not os.path.isfile(SUITE):
+        print(f"FAIL: no suite at {os.path.relpath(SUITE, ROOT)}")
+        return 2
+    suite = json.load(open(SUITE, encoding="utf-8"))
+    evals = suite.get("evals") or []
+
+    seen = set()
+    for e in evals:
+        where = e.get("id", "<no id>")
+        if not e.get("id"):
+            errors.append("an eval has no id")
+        elif e["id"] in seen:
+            errors.append(f"duplicate eval id {e['id']}")
+        seen.add(e.get("id"))
+        if e.get("category") not in REQUIRED:
+            errors.append(f"{where}: category {e.get('category')!r} is not one of {list(REQUIRED)}")
+        if not (e.get("query") or "").strip():
+            errors.append(f"{where}: empty query")
+        beh = e.get("expected_behavior") or []
+        if len(beh) < 2:
+            errors.append(f"{where}: needs at least two expected behaviours — one is a hope, "
+                          "two is a rubric")
+        if not (e.get("why") or "").strip():
+            errors.append(f"{where}: no `why` — an eval whose failure mode is unstated "
+                          "cannot tell you what broke")
+
+    if len(evals) < MIN_EVALS:
+        errors.append(f"{len(evals)} eval(s); at least {MIN_EVALS} are required")
+    covered = {e.get("category") for e in evals}
+    for cat in REQUIRED:
+        if cat not in covered:
+            errors.append(f"no eval covers {cat!r}")
+
+    if errors:
+        print("FAIL: evaluation suite invalid")
+        for e in errors:
+            print("  - " + e)
+        return 1
+
+    by_cat = {}
+    for e in evals:
+        by_cat.setdefault(e["category"], []).append(e)
+
+    if "--list" in argv:
+        for cat in REQUIRED:
+            for e in by_cat.get(cat, []):
+                print(f"  {e['id']:<10} {cat:<22} {e['query'][:60]}")
+        print(f"\n{len(evals)} evals across {len(by_cat)} categories")
+        return 0
+
+    print("=" * 72)
+    print("task-pipeline evaluation protocol")
+    print("=" * 72)
+    print("Run each query in a FRESH session with the skill installed, once per")
+    print("model in", suite.get("models", []), "— effectiveness varies by model.")
+    print("Record every verdict in evals/RESULTS.md with the date and the model.")
+    print("A query you did not run is not a pass; leave it blank and say so.\n")
+    for cat in REQUIRED:
+        print(f"\n--- {cat} ---")
+        for e in by_cat.get(cat, []):
+            print(f"\n[{e['id']}] {e['query']}")
+            print(f"    why: {e['why']}")
+            for b in e["expected_behavior"]:
+                print(f"    [ ] {b}")
+
+    print("\n" + "=" * 72)
+    if not os.path.isfile(RESULTS):
+        print("NO RESULTS FILE — the suite has never been recorded as run.")
+        return 1
+    body = open(RESULTS, encoding="utf-8").read()
+    # Count RUN HEADINGS only, outside fenced blocks. Counting every date in the
+    # file swept up the ratchet table and the fenced example and reported five runs
+    # against zero — a reporting tool that overstates its own subject, which is the
+    # one thing this script exists not to do.
+    outside, infence = [], False
+    for ln in body.split("\n"):
+        if re.match(r"^\s*(```|~~~)", ln):
+            infence = not infence
+            continue
+        if not infence:
+            outside.append(ln)
+    runs = [l for l in outside if re.match(r"^## 20\d{2}-\d{2}-\d{2}\b", l)]
+    print(f"suite: {len(evals)} evals · recorded runs: {len(runs)}")
+    if not runs:
+        print("RESULTS.md carries no dated run — the suite is authored and unexecuted.")
+    print("OK: suite valid. Execution is a human/agent step; this script never")
+    print("    reports a pass it did not observe.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/evals/task-pipeline.evals.json

@@ -0,0 +1,225 @@
+{
+  "_note": "Behavioural evaluations for the task-pipeline skill. Format follows Anthropic's Skill authoring guidance (skills, query, expected_behavior), extended with `id`, `category` and `why` so a failure says which dimension broke. There is no built-in runner for these upstream; `run.py` validates the suite and prints the protocol, and results are recorded in RESULTS.md. Dimensions come from the enterprise guidance: triggering accuracy, isolation, coexistence, instruction following, output quality.",
+  "skill": "task-pipeline",
+  "models": [
+    "haiku",
+    "sonnet",
+    "opus"
+  ],
+  "evals": [
+    {
+      "id": "TRIG-01",
+      "category": "should_trigger",
+      "skills": [
+        "task-pipeline"
+      ],
+      "query": "run this through the pipeline: add per-tenant rate limiting to the public API",
+      "expected_behavior": [
+        "Invokes the task-pipeline skill rather than starting to design or code inline",
+        "Runs the stage-0 knowledge harvest BEFORE the first interview question, and writes a source ledger",
+        "Asks interview questions one at a time, each with a recommended answer",
+        "Writes no implementation code before a brief is committed and confirmed"
+      ],
+      "why": "The explicit invocation phrase is the primary trigger; the failure it guards is jumping to code."
+    },
+    {
+      "id": "TRIG-02",
+      "category": "should_trigger",
+      "skills": [
+        "task-pipeline"
+      ],
+      "query": "полный цикл: перенести биллинг на нового провайдера",
+      "expected_behavior": [
+        "Invokes the task-pipeline skill from the Russian trigger alias",
+        "Continues the conversation in Russian while keeping identifiers and commands untranslated",
+        "Reaches stage 0 and does not skip the grill because the request looks clear"
+      ],
+      "why": "The description carries Russian trigger aliases; if they do not fire, half the operator's phrasings miss the skill."
+    },
+    {
+      "id": "TRIG-03",
+      "category": "should_trigger",
+      "skills": [
+        "task-pipeline"
+      ],
+      "query": "build a support-agent dashboard with saved views and CSV export",
+      "expected_behavior": [
+        "Invokes the skill without an explicit pipeline phrase, because the request is a substantial build",
+        "Detects the user-facing surface and surfaces super-ux at intake",
+        "Records the UI verdict in the brief"
+      ],
+      "why": "Substantial work must trigger without the magic words, or the skill only helps people who already know it exists."
+    },
+    {
+      "id": "NOTRIG-01",
+      "category": "should_not_trigger",
+      "skills": [
+        "task-pipeline"
+      ],
+      "query": "what does this regex do: ^(?!.*--)[a-z0-9-]{1,63}$",
+      "expected_behavior": [
+        "Answers the question directly",
+        "Does NOT invoke the task-pipeline skill",
+        "Does NOT create a TaskList or propose an intake grill"
+      ],
+      "why": "A question is not a build. Triggering here is the 'description too broad' failure the enterprise guidance names."
+    },
+    {
+      "id": "NOTRIG-02",
+      "category": "should_not_trigger",
+      "skills": [
+        "task-pipeline"
+      ],
+      "query": "fix the typo in the README heading: 'Instalation' -> 'Installation'",
+      "expected_behavior": [
+        "Makes the edit directly",
+        "Does NOT invoke the task-pipeline skill",
+        "Does NOT run a ten-stage flow for a one-character change"
+      ],
+      "why": "A trivial mechanical edit run through ten gates teaches the operator to route around the skill."
+    },
+    {
+      "id": "NOTRIG-03",
+      "category": "should_not_trigger",
+      "skills": [
+        "task-pipeline"
+      ],
+      "query": "explain how our auth middleware decides which routes are public",
+      "expected_behavior": [
+        "Reads the code and explains it",
+        "Does NOT invoke the task-pipeline skill"
+      ],
+      "why": "Explanation is not delivery."
+    },
+    {
+      "id": "AMB-01",
+      "category": "ambiguous",
+      "skills": [
+        "task-pipeline"
+      ],
+      "query": "clean up the error handling in the payments module",
+      "expected_behavior": [
+        "Establishes scope before choosing a route — asks whether this is a bounded fix or a refactor worth the full cycle",
+        "Does NOT silently start the ten-stage flow, and does NOT silently start editing",
+        "States which route it is taking and why"
+      ],
+      "why": "The honest failure here is a silent pick in either direction; the skill should make the choice visible."
+    },
+    {
+      "id": "AMB-02",
+      "category": "ambiguous",
+      "skills": [
+        "task-pipeline"
+      ],
+      "query": "add an `is_archived` field to the user model",
+      "expected_behavior": [
+        "Recognises that a schema field touches contracts, migrations and documentation even though the change is small",
+        "Either runs the flow or states explicitly which parts it is skipping and why",
+        "Does not treat 'small diff' as 'no decision to record'"
+      ],
+      "why": "Small changes with wide blast radius are where the doc track earns its keep or gets skipped."
+    },
+    {
+      "id": "COEX-01",
+      "category": "coexistence",
+      "skills": [
+        "task-pipeline",
+        "super-ux"
+      ],
+      "query": "redesign the settings screen so the security options are easier to find",
+      "expected_behavior": [
+        "Does not steal the trigger from super-ux for what is a UX-chain task",
+        "If task-pipeline runs, it routes the UX chain to super-ux at stage 3 rather than improvising one",
+        "If super-ux runs, task-pipeline stays out of the way until there is something to build"
+      ],
+      "why": "The enterprise guidance calls this out directly: a broad description steals triggers from narrower skills."
+    },
+    {
+      "id": "INSTR-01",
+      "category": "instruction_following",
+      "skills": [
+        "task-pipeline"
+      ],
+      "query": "run this through the pipeline: add a webhook retry policy. When you reach stage 0, show me what you did before your first question.",
+      "expected_behavior": [
+        "The knowledge harvest ran first and produced a source ledger with a row per source consulted, or an explicit 'none found'",
+        "The documentation inventory ran and docs/DOCMAP.md exists or was seeded",
+        "Intent was reconciled against the as-built record, with divergences named",
+        "The first interview question came AFTER all of that"
+      ],
+      "why": "Phase-1 ordering is the single most skipped instruction; if it slips, every later answer is unchecked."
+    },
+    {
+      "id": "INSTR-02",
+      "category": "instruction_following",
+      "skills": [
+        "task-pipeline"
+      ],
+      "query": "you are at stage 9 of a pipeline run that changed a status enum and an API contract. Close the stage.",
+      "expected_behavior": [
+        "Walks the propagation matrix for every change type produced, not only the sources the harvest read",
+        "Records the settled decisions under ids and flips any answered questions",
+        "Runs the documentation gate and prints its ratchet counts beside the verdict",
+        "States any check that skipped, rather than passing silently"
+      ],
+      "why": "Stage 9 is where 'docs in sync' used to be unfalsifiable; this eval is what makes the replacement real."
+    },
+    {
+      "id": "INSTR-03",
+      "category": "instruction_following",
+      "skills": [
+        "task-pipeline"
+      ],
+      "query": "you are a stage-5 implementer subagent in a worktree. While building, you settled that retries use exponential backoff capped at 30s. Record it.",
+      "expected_behavior": [
+        "Does NOT write to the decision register from inside the worktree",
+        "Puts the decision in the implementer report, and in the carry-over ledger if it outlives the task",
+        "States that the orchestrator runs the Doc Loop after integration, as a single writer"
+      ],
+      "why": "Two worktrees appending to one append-only register is the collision the rule exists to prevent."
+    },
+    {
+      "id": "INSTR-04",
+      "category": "instruction_following",
+      "skills": [
+        "task-pipeline"
+      ],
+      "query": "you are at stage 10. Close the run. The REQ table looks complete.",
+      "expected_behavior": [
+        "Runs the ladder walk BEFORE writing the coverage table, and turns absences into new REQ rows first",
+        "Refuses to accept 'done' without evidence, downgrading to partial instead of upgrading the claim",
+        "Confirms every check it leans on — the documentation gate included — was seen failing once against a planted defect",
+        "Writes the retrospective last: prune, stamp with the run's commit, entry only on divergence"
+      ],
+      "why": "'The table looks complete' is the exact prompt under which the ladder walk gets skipped."
+    },
+    {
+      "id": "TRIG-04",
+      "category": "should_trigger",
+      "skills": [
+        "task-pipeline"
+      ],
+      "query": "перепиши модуль экспорта на потоковую выдачу, он не держит большие выгрузки",
+      "expected_behavior": [
+        "Invokes the skill from a plain Russian refactor request with no pipeline phrase — the work changes the repository, which is the boundary",
+        "Runs stage 0 before touching code",
+        "Does not treat 'it's just a refactor' as an exemption from the brief"
+      ],
+      "why": "Default-on is only real if it fires on ordinary work phrased ordinarily; a skill that needs magic words helps only people who already know it exists."
+    },
+    {
+      "id": "NOTRIG-04",
+      "category": "should_not_trigger",
+      "skills": [
+        "task-pipeline"
+      ],
+      "query": "перепиши модуль экспорта на потоковую выдачу, без пайплайна",
+      "expected_behavior": [
+        "Does NOT invoke the skill, despite the task being repo-changing and otherwise qualifying",
+        "Says out loud that the cycle was skipped because the operator opted out",
+        "Does the work directly"
+      ],
+      "why": "The opt-out phrase is the release valve that makes default-on acceptable. If it does not work, the boundary is a trap rather than a default."
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.8.0",
+  "version": "1.9.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"
@@ -14,9 +14,14 @@
     "bin",
     "plugins",
     "cursor",
+    "evals",
     "README.md",
+    "SKILL-CARD.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md"
   ],
   "repository": "github:ssheleg/task-pipeline",
   "homepage": "https://github.com/ssheleg/task-pipeline#readme",

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.8.0",
+  "version": "1.9.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -1,6 +1,6 @@
 ---
 name: task-pipeline
-description: "Runs a substantial task through a full delivery pipeline: an intake grill that expands the request into a locked brief, then docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy check, docs/wiki sync and acceptance — gated stages whose doctrine ships inside this skill (no required companions). Use when any substantial feature, fix or build should follow the disciplined cycle rather than ad-hoc coding, or on 'run this through the pipeline' / 'прогони по конвейеру', 'the full cycle' / 'полный цикл', /task-pipeline. The grill is mandatory and front-loads every decision, so stages 1→10 run without mid-flight questions; documentation is a deliverable with its own gate; recommends super-ux for user-facing work; confirms one model up front (most capable available, never a hardcoded id); reads host conventions so it stays project-agnostic."
+description: "Runs a substantial task through a full delivery pipeline: an intake grill that expands the request into a locked brief, then docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy check, docs/wiki sync and acceptance — gated stages whose doctrine ships inside this skill (no required companions). Use when work changes the repository — a feature, fix, refactor, migration, integration, rewrite, adoption or hardening; фича, фикс, рефактор, миграция, интеграция, доработать, починить, внедрить — or on 'run this through the pipeline' / 'прогони по конвейеру', 'the full cycle' / 'полный цикл', /task-pipeline. Not for: answering a question, explaining or reading code, a typo or a one-line edit — say 'без пайплайна' / 'quick' to opt out. The grill is mandatory and front-loads every decision, so stages 1→10 run without mid-flight questions; documentation is a deliverable with its own gate; recommends super-ux for user-facing work; confirms one model up front, never a hardcoded id."
 license: MIT
 ---
 
@@ -61,6 +61,7 @@ gate stops until it is installed.
 | 10 Acceptance (REQ close-out) | [`references/acceptance.md`](references/acceptance.md) |
 | 10 Retrospective (the run's last act) | [`references/retrospective.md`](references/retrospective.md) |
 | 10 + any audit (what's *missing*) | [`references/audit.md`](references/audit.md) |
+| **first run in a project** (new or existing) | [`references/adoption.md`](references/adoption.md) |
 | any repeating loop | [`references/loop-guard.md`](references/loop-guard.md) |
 
 **Optional bridge.** If the operator already runs an equivalent skill set (e.g.
@@ -331,6 +332,8 @@ automation is on — `pipeline.schema.json` is the only contract.
 - `references/tdd.md` — stages 5–6: the iron law, red/green/refactor, the suite gate
 - `references/stages.md` — per-stage detail + exact gate criteria + gate types
 - `references/model-tiering.md` — model map, ids, the `/model` reminder mechanic, override
+- `references/adoption.md` — the first run in a project: greenfield seeding, and the
+  brownfield walkthrough whose third step baselines the ratchets at today
 - `references/conventions.md` — how stages 6–10 read the host project's CLAUDE.md
 - `references/companion-skills.md` — companion skills, install lines, preflight recommendation
 - `references/artifacts.md` — the canonical document/artifact layout per stage

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

@@ -0,0 +1,210 @@
+# Adoption — bringing a project onto the pipeline
+
+**One job: get a repository to the state where stage 0 has something true to read.**
+The pipeline assumes a documentation system exists or gets seeded
+([`documentation.md`](documentation.md)). This file is what to do on the first run in
+a project — and the two entry conditions are not the same problem.
+
+## Contents
+
+- Two entry conditions
+- A new project — the seed is the whole of it
+- An existing project — the register starts today
+- Why history is not back-filled
+- What good looks like the day after
+- Rationalizations
+
+## Two entry conditions
+
+| | Greenfield | Brownfield |
+|---|---|---|
+| What exists | nothing, or a README | code, history, opinions, and docs that are partly true |
+| The hard part | none — seeding is mechanical | **the decisions already exist and none of them are written down** |
+| Failure if done wrong | a register nobody starts using | a gate that is red on day one, switched off on day two |
+| First run's deliverable | the feature, with the system seeded on the way | **the system itself** — adoption is its own run |
+
+**On a brownfield project, adoption is a run, not a preamble.** Give it a brief, a
+REQ table and an acceptance, exactly like a feature. A doc system introduced as a
+side effect of somebody else's task is a doc system with no owner.
+
+## A new project — the seed is the whole of it
+
+Stage 0 phase 1b already does it before the first interview question. Nothing to
+prepare:
+
+```
+docs/DOCMAP.md          the map: registers, single homes, propagation matrix, gates, ratchets
+docs/DECISIONS.md       the register — DEC-####, append-only
+docs/OPEN_QUESTIONS.md  OQ-####, closed status vocabulary
+scripts/check-docs.sh   the gate, ten sections
+```
+
+Three things are true on day one and worth knowing:
+
+- **The gate is green immediately.** Sections whose input does not exist yet print
+  `dormant`, which is visible and passing ([`gates.md`](gates.md) → *Progressive
+  arming*). The skill proves this mechanically: its own validator seeds a scratch
+  project from these templates and requires exit `0`.
+- **Both floors are `0`,** because there is no history to forgive.
+- **The register's first entry is the decision to document this way.** A register
+  that starts with a real entry is a register somebody has already used once.
+
+Then run the task. There is no separate adoption step.
+
+## An existing project — the register starts today
+
+Seven steps. Step 3 is the one that decides whether adoption survives contact with
+the repository.
+
+### Step 1 · Inventory — what is already here
+
+Answer the four questions of [`documentation.md`](documentation.md) against reality,
+not against the templates:
+
+```bash
+ls docs/DECISIONS.md docs/adr/ docs/OPEN_QUESTIONS.md docs/DOCMAP.md 2>/dev/null
+ls scripts/check-docs.sh .github/workflows/ 2>/dev/null
+grep -rl "ADR\|decision record\|DEC-" docs/ README.md CONTRIBUTING.md 2>/dev/null | head
+```
+
+**One decision home, and you are looking for the one that already exists.** A
+populated `docs/adr/` *is* the register — record it in the doc map and use it. Never
+seed a second one beside it; that is the fork the SSOT rule exists to prevent.
+
+A project whose decisions live in a CHANGELOG with reasons, or in commit messages
+nobody will migrate, has a decision home too. Write down which it is. The choice
+being *unrecorded* is the defect, not the choice.
+
+### Step 2 · Seed what is missing
+
+Usually the map and the gate; often the register already exists in some shape.
+
+```bash
+cp <skill>/templates/docmap.md   docs/DOCMAP.md          # only if absent
+cp <skill>/templates/docgate.sh  scripts/check-docs.sh   # only if absent
+chmod +x scripts/check-docs.sh
+```
+
+**Seeding never overwrites.** An existing brief, register or map is the project's
+memory; the template is a skeleton.
+
+### Step 3 · Baseline the ratchets — the step that decides adoption
+
+Run the gate **before** deciding anything, and read what it actually says:
+
+```bash
+bash scripts/check-docs.sh; echo "exit=$?"
+```
+
+On a repository with history this is red, often loudly — the practice this skill
+comes from measured **162 missing propagations across 73 decisions** on its first
+run. That number is not a to-do list. Fixing it blind would add 162 citations nobody
+verified, and failing on it every day makes the gate something people switch off,
+which costs more than the rows it would have caught.
+
+So set the floors to **today**, and only ever lower them:
+
+```bash
+# PROP_FLOOR is an ID THRESHOLD: entries numbered >= it must have propagated.
+# Set it to the next free id — from now on the rule binds, and the history
+# becomes one printed number.
+PROP_FLOOR=$(grep -o 'Next free ID:\**\s*`\?DEC-[0-9]*' docs/DECISIONS.md \
+             | grep -o '[0-9]*$' | sed 's/^0*//')
+
+# RESIDUE_FLOOR is a COUNT: unmarked citations of retired decisions, as measured
+# right now.
+RESIDUE_FLOOR=$(bash scripts/check-docs.sh 2>&1 \
+                | grep -o 'residue [0-9]*' | grep -o '[0-9]*' | head -1)
+```
+
+Write both into the top of `scripts/check-docs.sh` and into `docs/DOCMAP.md` →
+*Ratchets*, with the date. Re-run; the gate is now **green on today's state** and
+red only on what happens next.
+
+**Why this is not cheating.** A ratchet is a named, counted set that may only shrink,
+printed beside every verdict ([`audit.md`](audit.md) → *What can't be fixed now
+becomes a ratchet, never a TODO*). The backlog stays visible on every single run —
+it just stops blocking work it was never going to fix today. A gate that starts red
+teaches everyone on day one that it is noise
+(`references/learned.md` rules 9 and 10).
+
+### Step 4 · Build the propagation matrix
+
+Not from the template — from what this project actually has. The five steps are in
+[`documentation.md`](documentation.md) → *The propagation matrix*. Start with three
+rows you can name today; a matrix with three true rows beats one with twenty
+imported ones.
+
+The third column is not optional: name the check that would notice, or write
+`review` **with the one-line reason no check can decide it**.
+
+### Step 5 · Record the adoption itself
+
+The first entry in the register is the decision to adopt — regime, decision home,
+where the map lives, what the floors were set to and on what date. It costs two
+minutes and it is the cheapest possible demonstration that the register works, to
+the next person who wonders whether anyone actually uses it.
+
+### Step 6 · Arm the gate
+
+Local first, then the one that binds people who never run it locally:
+
+```bash
+echo 'bash scripts/check-docs.sh' >> .git/hooks/pre-commit   # local, skippable
+# CI: add the same line to the workflow that already runs the tests
+```
+
+Optionally at agent time, which is the only rung that can stop a bad edit *before*
+it lands — `templates/hooks.example.json`, and read
+[`hooks.md`](hooks.md) first for the fail-open hazard.
+
+### Step 7 · Several agents — add the leases
+
+Only when more than one agent works the repository. Then the registers become shared
+state ([`documentation.md`](documentation.md) → *Registers are shared state*) and a
+coordination tool arbitrates: `guardedFiles` must list every register **plus
+`docs/DOCMAP.md` and `docs/superpowers/retro.md`**, which are equally shared and
+equally lossy under a concurrent write.
+
+Without such a tool the run is **`ungated`** and must say so. The discipline still
+applies; only the arbitration is missing.
+
+## Why history is not back-filled
+
+The decisions already exist — in the git log, in the code, in somebody's memory. The
+temptation is to reconstruct them into the register so it looks complete.
+
+Don't. A reconstructed decision carries a *guess* about why it was made, in a
+register whose whole value is that entries are true. One invented rationale is worse
+than a hundred absent ones, because absent ones are visibly absent and an invented
+one is indistinguishable from a real one forever.
+
+**The rule: an old decision enters the register the day somebody is about to
+contradict it.** At that moment the reason is being discussed anyway, the person
+holding the context is in the room, and the entry writes itself honestly — with the
+new decision beside it.
+
+## What good looks like the day after
+
+- `bash scripts/check-docs.sh` exits `0`, prints its ratchet counts, and says which
+  sections were `dormant` or `skipped`.
+- `docs/DOCMAP.md` answers the four questions, and its propagation matrix has no
+  empty *Checked by* cell.
+- The register has at least one entry: the adoption.
+- The gate runs in CI, not only on the adopter's laptop.
+- The next task runs through the pipeline normally, and stage 9 has a matrix to walk
+  instead of a sentence to interpret.
+
+Anything not true yet is a carry-over row with a home, not a promise.
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "We'll adopt it properly when things calm down" | The backlog only grows, and the floors you would set today are the smallest numbers you will ever get to set. |
+| "The gate is red, this clearly doesn't fit our repo" | The gate is red because it is measuring history nobody promised to fix. That is what step 3 is for, and it takes one command. |
+| "Let's back-fill the last two years of decisions first" | Then the register's first hundred entries are guesses, and nobody can tell them from the real ones. Start today; back-fill exactly one entry at the moment it is contradicted. |
+| "We already have ADRs, so we need to migrate to DECISIONS.md" | You do not. An existing ADR set *is* the register. Migrating is its own decision with its own entry — never a side effect of adopting. |
+| "We'll set the floors to zero, it's more honest" | It is more honest for about a day, after which the gate is disabled and you have neither the floor nor the check. A printed backlog is the honest thing that survives. |
+| "The matrix needs to be complete before it's useful" | Three true rows catch three real classes. Twenty imported rows catch nothing and teach everyone that the matrix is decoration. |
+| "One agent works here, so leases are overkill" | Correct — skip step 7 and say so. Adopting coordination nobody needs is how a project learns to route around the parts it does need. |

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

@@ -352,7 +352,7 @@ findings are neither fixed nor parked-with-ruling at the cap.
 After the last task: build a package over `MERGE_BASE`..`HEAD`
 (`git merge-base "$BASE_BRANCH" HEAD`, where `$BASE_BRANCH` is the base recorded in
 the stage-0 brief — never a hardcoded `main`), dispatch the whole-branch review
-([`review.md`](review.md) → *Final review*; on the run's model, escalation offered
+([`review.md`](review.md) → *Prompt — final whole-branch review*; on the run's model, escalation offered
 out loud per *Models* above), and point it at the
 ledger's deferred-minor and parked lines so it can triage what must be fixed before
 merge.

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

@@ -47,7 +47,7 @@ better, plus one that is required only for user-facing work.
 | **Figma** (MCP) | stage 3 UX track, when the project designs visually — super-ux mirrors each `SCR-` screen/state into a frame | Optional, **UI + Figma-on only**. Absent → super-ux degrades to text-only *by itself and never blocks*, so shipping a UI feature with no mockups becomes a silent scope call — which is why the stage-0 sweep decides it | connect the Figma MCP server (`/mcp`, or your claude.ai connectors) |
 | **[obsidian-wiki](https://github.com/ar9av/obsidian-wiki)** (`wiki-query`, `wiki-update`) | **stage 0 harvest** (query what's already known) **+ stage 9 sync** | **Recommended** — never a gate; absent → harvest runs on repo docs alone | `pip install obsidian-wiki` → `obsidian-wiki setup --vault /path/to/your/vault` |
 | **[graphify](https://github.com/Graphify-Labs/graphify)** (`/graphify`, `graphify query\|affected\|god-nodes`) | **stage 0 harvest** (reach: what calls this, what breaks if it moves) **+ stage 9 refresh + the graph↔docs divergence check** ([`knowledge-graph.md`](knowledge-graph.md)) | **Recommended** — never a gate; absent → the harvest greps instead, and the divergence axis is unavailable | `uv tool install graphifyy` → `graphify install` → `/graphify .` |
-| **[agent-sync](https://github.com/ssheleg/agent-sync)** (`/agent-sync`) | **guarded registers** — a lease before writing one, `reserve` before minting an id, `reconcile`/`record` for intent vs as-built, and `finish` for the stage-10 multi-repository close-out ([`documentation.md`](documentation.md)) | **Recommended** — never a gate. Absent → the run is **`ungated`** and must say so out loud; the discipline still applies, only the arbitration is missing | `npx sshlg-skills install` |
+| **[agent-sync](https://github.com/ssheleg/agent-sync)** (`/agent-sync`, **≥ 1.3.0** — `finish` did not exist before it, so an older install turns the stage-10 close-out into a command that is not there) | **guarded registers** — a lease before writing one, `reserve` before minting an id, `reconcile`/`record` for intent vs as-built, and `finish` for the stage-10 multi-repository close-out ([`documentation.md`](documentation.md)) | **Recommended** — never a gate. Absent → the run is **`ungated`** and must say so out loud; the discipline still applies, only the arbitration is missing | `npx sshlg-skills install` |
 | ~~superpowers~~ | — | **Not a dependency.** Stages 2/4/5/6 run on the built-in doctrine above. See *Optional bridge* | — |
 | ~~grill-me / grilling~~ | — | **Not a dependency.** The stage-0 grill is built in (`references/grill.md`) | — |
 

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

@@ -50,7 +50,7 @@ repository — the smallest one still decides *somewhere* that a thing is true
 the only choice is whether that answer is written down or re-derived by each new
 reader. What scales down is **volume**, never the rules: a register with three
 entries is a register, and the seeded gate is green on exactly those three
-([`gates.md`](gates.md) → *progressive arming*).
+([`gates.md`](gates.md) → *Progressive arming*).
 
 ---