task-pipeline-skill 1.8.1 → 1.9.1

package/CHANGELOG.md

@@ -1,5 +1,104 @@
 # Changelog
 
+## v1.9.1 — 2026-08-03
+
+### Added — the direction of the artifact map that was missing
+
+`references/artifacts.md` mapped **stage → what it writes → who consumes it** and
+nothing the other way. What an agent actually needs at runtime is **what each stage
+reads, and from where** — and that direction had been absent since the file was
+written. It is `references/learned.md` rule 2 (*compute the mapping in both
+directions*) left unapplied to this file itself: the direction that feels redundant
+is the one that finds things.
+
+Two tables now sit above the old one:
+
+- **Stage → input map** — per stage, the exact inputs and their origin. Stage 9's row
+  is the one worth reading twice: it takes **two different lists**, the stage-0 source
+  ledger (what the run *read*) and the doc map's propagation matrix (what the run
+  *owes*), and the gap between them is where documentation rots.
+- **Project-saved rules, and where each one binds** — the eight files a host project
+  owns that change how a run behaves, each with where it is read and where it is
+  enforced: `CLAUDE.md`/`AGENTS.md`, `docs/DOCMAP.md`, the retro's standing
+  instructions, the brief's autonomy section, the carry-over ledger,
+  `docs/ux/scenarios.md`, `.claude/agent-sync.json`, and the operator's global config
+  that decides whether a task routes here at all. Plus the precedence rule: for *what
+  is*, code wins; for *what should be*, the register wins, and the gap is a finding
+  rather than a tie-break.
+
+A guard holds all three maps present, with a negative self-test watched failing.
+
+## v1.9.0 — 2026-08-03
+
+### Added — the adoption track, and default-on inside a stated boundary
+
+Built by running this skill through itself: brief, spec, plan, gated stages,
+acceptance. The stage-0 harvest found two things that changed the shape of the work,
+and one of them is why this release exists at all.
+
+**`references/adoption.md` — the first run in a project.** The pipeline assumed a
+documentation system either exists or gets seeded, and said almost nothing about the
+repository you actually have. Greenfield is mechanical: stage 0 seeds the map, the
+registers and the gate, and the gate is green on day one because unarmed sections
+print `dormant`. Brownfield is a different problem and now has seven steps, of which
+**step 3 decides whether adoption survives**: baseline the ratchets at today —
+`PROP_FLOOR` to the next free id, `RESIDUE_FLOOR` to the measured count — so the gate
+is green on the history it inherited and red only on what happens next. On the
+project this practice comes from, the first run of that check reported **162 missing
+propagations across 73 decisions**; that is a printed number, not a to-do list, and a
+gate that is red on adoption day is switched off on day two.
+
+It also states the rule that keeps a register honest: **history is not back-filled.**
+An old decision enters the register the day somebody is about to contradict it —
+when the reason is being discussed anyway and the person holding the context is in
+the room. A reconstructed rationale is indistinguishable from a real one forever.
+
+**Default-on routing, inside a boundary.** The description now widens to work that
+**changes the repository** — feature, fix, refactor, migration, integration, rewrite,
+adoption, hardening, with Russian verbs beside the English — and carries an explicit
+`Not for:` clause for questions, explanations, typos and one-line edits, plus the
+opt-out phrases *"без пайплайна"* / *"quick"*. Two evals follow it: a plain Russian
+refactor that must trigger, and the same request with the opt-out that must not. A
+guard ties the two together, because an escape hatch nobody tests is a trap rather
+than a default.
+
+**The lever that actually binds is not in this repository**, and the brief says so:
+a `description` raises the odds a skill is selected and cannot make selection
+mandatory. Default-on is enforced by an instruction in the operator's `CLAUDE.md`;
+the description makes it reachable.
+
+### Fixed
+
+- **The ratchet floors were documented as the same kind and are not.** `PROP_FLOOR`
+  is an **id threshold**, `RESIDUE_FLOOR` is a **count**; the comment called both
+  counts. Adoption turns on that distinction, so it is now spelled out where the
+  floors are declared.
+- **The frontmatter guard wore the platform's number.** It capped the whole block at
+  1024 — the limit Anthropic puts on `description` alone — silently making the
+  usable description ~975 and reading as if it were the real rule. The platform's
+  limit stays on `description`; ours becomes a stated budget of 1200.
+- **agent-sync's binding to this skill** (patched in that repository): its
+  `pipeline.json` example claimed this schema permitted it while carrying a string
+  `id`, a `title` where the schema says `name`, and no `state` at all — required. Its
+  gate texts stated only agent-sync's half, so a host that copied them silently
+  dropped the stage's real gate. Stage 9 pointed at the artifact-layout reference
+  instead of that stage's doctrine. And `guardedFiles` did not cover `docs/DOCMAP.md`
+  or `docs/superpowers/retro.md`, both of which this pipeline now creates and both of
+  which lose data under a concurrent write. `companion-skills.md` states the
+  **≥ 1.3.0** floor `finish` needs.
+
+### Dogfooded
+
+This repository ran its own brownfield walkthrough and wrote `docs/DOCMAP.md`. Step 1
+— *inventory what is already there* — changed the plan: `npm test` already resolves
+links, checks citations and computes counts over the same markdown, so **no second
+gate was seeded**. The map records the gate that exists and why no other is created,
+which is the walkthrough's step 2 read correctly: seed what is *missing*, and here
+that was the map. The changed check went to the carry-over ledger for the operator's
+agreement rather than being swapped silently.
+
+Two new guards, each with a negative self-test watched failing.
+
 ## v1.8.1 — 2026-08-03
 
 ### Fixed — eight findings from a code-and-contradiction audit of 1.8.0

package/README.md

@@ -490,6 +490,24 @@ now does:
   discover: author and reviewer are the same person, commits are unsigned, and the
   eval suite has not been executed.
 
+### Adopting it — a new project, and the one you actually have
+
+Greenfield is mechanical: stage 0 seeds `docs/DOCMAP.md`, the registers and the gate
+before the first interview question, and the gate is green on day one because
+sections with nothing to check yet print `dormant`.
+
+Brownfield is a different problem, and [`references/adoption.md`](plugins/task-pipeline/skills/task-pipeline/references/adoption.md)
+gives it seven steps. The third one decides whether adoption survives: **baseline the
+ratchets at today** — the propagation floor to the next free id, the residue floor to
+the measured count — so the gate is green on the history it inherited and red only on
+what happens next. On the project this practice comes from, that check's first run
+reported 162 missing propagations across 73 decisions. That is a printed number, not
+a to-do list; a gate that is red on adoption day is switched off on day two.
+
+And history is **not** back-filled. An old decision enters the register the day
+somebody is about to contradict it — when the reason is being discussed anyway and
+the person who holds the context is in the room.
+
 ### The retrospective — the run teaches the next run, and the list stays short
 
 Every gate in this flow is good at *this* run and blind across runs. So the same
@@ -743,6 +761,7 @@ recommendation, so you arm the whole run in one exchange. Detail:
 | [`references/retrospective.md`](plugins/task-pipeline/skills/task-pipeline/references/retrospective.md) | the project retro: the three grades of fix, the mandatory prune, the cap of ten |
 | [`references/model-tiering.md`](plugins/task-pipeline/skills/task-pipeline/references/model-tiering.md) | model policy, the `/model` reminder, overrides |
 | [`templates/`](plugins/task-pipeline/skills/task-pipeline/templates/README.md) | brief, carry-over ledger, `CONTEXT.md` and ADR skeletons, the doc map, both registers, the retro and its archive, the seeded `docgate.sh`, a worked hook |
+| [`references/adoption.md`](plugins/task-pipeline/skills/task-pipeline/references/adoption.md) | the first run in a project: greenfield seeding, and the brownfield walkthrough |
 | [`SKILL-CARD.md`](SKILL-CARD.md) | the registry entry and risk-tier disclosure a reviewer needs before deploying it |
 | [`evals/`](evals/RESULTS.md) | the behavioural evaluation suite, its protocol, and what has actually been observed |
 | [`CHANGELOG.md`](CHANGELOG.md) | every release, with the reasoning behind it |

package/SKILL-CARD.md

@@ -12,10 +12,10 @@ 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.8.1 |
+| **Version** | 1.9.1 |
 | **Surface** | Claude Code (filesystem skill + plugin) and the vercel `skills` CLI. **Not** uploaded to the Skills API; custom Skills do not sync across surfaces |
 | **Dependencies** | None required. Optional: `context7` (MCP), `figma` (MCP), super-ux, agent-sync, graphify, obsidian-wiki. 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 (13 evals, 5 categories). **Never executed** — see [`evals/RESULTS.md`](evals/RESULTS.md) |
+| **Evaluation status** | Suite authored (15 evals, 5 categories). **Never executed** — see [`evals/RESULTS.md`](evals/RESULTS.md) |
 
 ## Risk-tier disclosure
 
@@ -34,11 +34,11 @@ apply.
 
 ## What to check before you trust it
 
-1. Read `SKILL.md` and the 23 files under `references/` — that is the whole
+1. Read `SKILL.md` and the 24 files under `references/` — that is the whole
    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` — 53 guards, each with a negative self-test that plants a
+3. Run `npm run test:all` — 56 guards, each with 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.** 53 structural guards prove
+- **Behavioural evidence is missing, not merely thin.** 56 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/evals/RESULTS.md

@@ -31,17 +31,38 @@ or it belongs in a check.
 
 | Metric | Value | As of |
 |---|---|---|
-| Evals authored | 13 | 2026-08-03 |
+| Evals authored | 15 | 2026-08-03 |
 | Categories covered | 5 of 5 | 2026-08-03 |
 | Models exercised | **0 of 3** | 2026-08-03 |
 | 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 53 structural guards that check the
+Everything else in this repository is proven by 56 structural guards 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 "53 of 53 green" is never read as "the skill is
+not been run yet. Printed here so "56 of 56 green" is never read as "the skill is
 known to work".
 
 ## Runs
 
-_(none yet)_
+## 2026-08-03 · opus · self-observed, not a blind run
+
+**Scope of this evidence.** The author ran the skill on a real task
+(`default-routing-adoption`) and watched it follow its own doctrine. That is a
+legitimate observation of instruction-following and **not** an independent
+evaluation: the operator knew the expected behaviour and the same person wrote both
+sides. It closes none of the trigger-accuracy or coexistence rows, which need fresh
+sessions and a reader who is not the author.
+
+| id | verdict | what happened |
+|---|---|---|
+| INSTR-01 | pass | harvest ran before the first question; source ledger written into the brief; doc inventory answered (`DOCMAP.md` absent → seeded this run); intent reconciled against as-built (clean, in sync) |
+| INSTR-04 | partial | the ladder walk and the evidence rule ran at stage 10, but a stage-10 self-audit by the author is the weakest form of the check |
+| others | not run | require fresh sessions per model |
+
+**One divergence worth recording:** at stage 5 the work contradicted the spec —
+inventory showed this repository already had a gate over the same corpus, so seeding
+a second one would have violated the SSOT rule the doc map publishes. The finding
+went back to stage 3, the spec was revised, and the changed check was raised in the
+carry-over ledger for the operator rather than swapped silently. The loop behaved as
+designed.
+

package/evals/task-pipeline.evals.json

@@ -1,12 +1,18 @@
 {
   "_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"],
+  "models": [
+    "haiku",
+    "sonnet",
+    "opus"
+  ],
   "evals": [
     {
       "id": "TRIG-01",
       "category": "should_trigger",
-      "skills": ["task-pipeline"],
+      "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",
@@ -19,7 +25,9 @@
     {
       "id": "TRIG-02",
       "category": "should_trigger",
-      "skills": ["task-pipeline"],
+      "skills": [
+        "task-pipeline"
+      ],
       "query": "полный цикл: перенести биллинг на нового провайдера",
       "expected_behavior": [
         "Invokes the task-pipeline skill from the Russian trigger alias",
@@ -31,7 +39,9 @@
     {
       "id": "TRIG-03",
       "category": "should_trigger",
-      "skills": ["task-pipeline"],
+      "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",
@@ -43,7 +53,9 @@
     {
       "id": "NOTRIG-01",
       "category": "should_not_trigger",
-      "skills": ["task-pipeline"],
+      "skills": [
+        "task-pipeline"
+      ],
       "query": "what does this regex do: ^(?!.*--)[a-z0-9-]{1,63}$",
       "expected_behavior": [
         "Answers the question directly",
@@ -55,7 +67,9 @@
     {
       "id": "NOTRIG-02",
       "category": "should_not_trigger",
-      "skills": ["task-pipeline"],
+      "skills": [
+        "task-pipeline"
+      ],
       "query": "fix the typo in the README heading: 'Instalation' -> 'Installation'",
       "expected_behavior": [
         "Makes the edit directly",
@@ -67,7 +81,9 @@
     {
       "id": "NOTRIG-03",
       "category": "should_not_trigger",
-      "skills": ["task-pipeline"],
+      "skills": [
+        "task-pipeline"
+      ],
       "query": "explain how our auth middleware decides which routes are public",
       "expected_behavior": [
         "Reads the code and explains it",
@@ -78,7 +94,9 @@
     {
       "id": "AMB-01",
       "category": "ambiguous",
-      "skills": ["task-pipeline"],
+      "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",
@@ -90,7 +108,9 @@
     {
       "id": "AMB-02",
       "category": "ambiguous",
-      "skills": ["task-pipeline"],
+      "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",
@@ -102,7 +122,10 @@
     {
       "id": "COEX-01",
       "category": "coexistence",
-      "skills": ["task-pipeline", "super-ux"],
+      "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",
@@ -114,7 +137,9 @@
     {
       "id": "INSTR-01",
       "category": "instruction_following",
-      "skills": ["task-pipeline"],
+      "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'",
@@ -127,7 +152,9 @@
     {
       "id": "INSTR-02",
       "category": "instruction_following",
-      "skills": ["task-pipeline"],
+      "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",
@@ -140,7 +167,9 @@
     {
       "id": "INSTR-03",
       "category": "instruction_following",
-      "skills": ["task-pipeline"],
+      "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",
@@ -152,7 +181,9 @@
     {
       "id": "INSTR-04",
       "category": "instruction_following",
-      "skills": ["task-pipeline"],
+      "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",
@@ -161,6 +192,34 @@
         "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.1",
+  "version": "1.9.1",
   "description": "Full-cycle delivery pipeline for coding agents: a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine ships inside the skill — no companion plugin required. This package is the installer CLI.",
   "bin": {
     "task-pipeline": "bin/task-pipeline.js"

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

@@ -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.1",
+  "version": "1.9.1",
   "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/artifacts.md

@@ -8,6 +8,7 @@ shape.
 ## Contents
 
 - In the host project
+- Stage → input map — where each stage's information comes from
 - Stage → artifact map
 - This repo (task-pipeline itself), for reference
 
@@ -65,6 +66,52 @@ Stage 5 also creates a **git-ignored** scratch workspace per plan at
 review packages. It is deleted when the final review is clean; git history is the
 record (see `build.md`).
 
+## Stage → input map — where each stage's information comes from
+
+The map below this one answers *what a stage writes*. This one answers *what it
+reads, and from where* — the direction that was missing, which is
+[`learned.md`](learned.md) rule 2 (*compute the mapping in both directions*) applied
+to this file itself. A stage whose inputs are unnamed is a stage that will read
+whatever the context happens to hold.
+
+| Stage | Reads | From where |
+|---|---|---|
+| **0 Harvest** | the project's own knowledge about this task | code · the code graph (`graphify-out/`) · `CLAUDE.md`/`AGENTS.md` · `CONTEXT.md`/`docs/adr/` · `docs/` + `docs/ux/` · past briefs and carry-over ledgers · the retro's standing instructions **in full** · the wiki · any doc repo or hosted system the project names |
+| **0 Inventory (1b)** | the documentation regime | `docs/DOCMAP.md` — registers, single homes, propagation matrix, gate commands, ratchet floors. Absent ⇒ seeded ([`adoption.md`](adoption.md)) |
+| **0 Reconcile (1c)** | intent vs as-built | git (how it *should* be) against the run record (how it *turned out*) |
+| **0 Grill** | the operator | the interview — every answer checked against the harvest, which is what makes it checkable rather than confident |
+| **1 Docs study** | external library/API contracts | `context7:resolve-library-id` → `context7:query-docs`; web search where it cannot resolve. **Never from recall** |
+| **2 Brainstorm** | what is already settled | the brief (scope, constraints, done-criteria) + the codebase. Re-asking what the grill answered is this stage's most common waste |
+| **3 Spec** | the approved design + the UX chain | stage-2 design · `docs/ux/{foundation,flows,screens,scenarios}.md` (UI only) · the Figma canonical record in `docs/ux/foundation.md` → *Design tooling* · `DOCMAP.md` for where a settled contract is recorded |
+| **4 Plan** | the spec and the frozen list | the spec's locked contracts and **Global Constraints** · the brief's REQ ids (the gate is a set comparison against them) |
+| **5 Dev** | one task at a time | the plan task · the spec's Global Constraints, copied verbatim · host test/lint commands · the brief's branch policy. **A subagent reads only its own file-based brief** — that is the whole of its context |
+| **6 Tests** | the host's runner | `CLAUDE.md`/`AGENTS.md` → *Lint + test*, else detection ([`conventions.md`](conventions.md)) |
+| **7 Lint + deploy** | the host's lint and deploy path, and the authorization | host conventions · the brief's autonomy sweep, where a standing go must name target **and** preconditions |
+| **8 Post-deploy** | where health lives | the brief's autonomy sweep (app name, endpoint, workflow) |
+| **9 Docs + registers** | two different lists | the stage-0 **source ledger** (what this run *read*) **and** `DOCMAP.md`'s **propagation matrix** (what this run *owes*). They are not the same list, and the gap between them is where documentation rots |
+| **10 Acceptance** | everything the run produced | the brief's REQ table · the carry-over ledger **in full** · plan task statuses · `git log` · the final suite output · stage-8 notes · stage-9 changes · `docs/ux/scenarios.md` + `/ux-lint` for UI |
+
+### Project-saved rules, and where each one binds
+
+These are the files a **host project** owns that change how a run behaves. An agent
+that has not read them is running the pipeline's defaults, not this project's.
+
+| Rule file | What it binds | Read at | Enforced at |
+|---|---|---|---|
+| `CLAUDE.md` / `AGENTS.md` | commands, deploy path, house rules, which docs exist and where | 0 | 6–10 |
+| `docs/DOCMAP.md` | the decision home, each fact's single home, the propagation matrix, the gate and its ratchet floors | 0 (1b) | 9 |
+| `docs/superpowers/retro.md` | standing instructions — the rules no check can decide. Capped at ten, **read in full**, stamped the moment one fires | 0 | pruned at 10 |
+| `specs/<topic>-brief.md` → *Autonomy* | every pre-resolved decision; stages 1→10 **answer from it instead of asking** | 0 | 1–10 |
+| `specs/<topic>-carryover.md` | everything deferred, parked or half-done; appended the moment it is said | all | read in full at 10 |
+| `docs/ux/scenarios.md` | the source of truth for user-facing behaviour (super-ux) | 3 | 3, 7, 9, 10 |
+| `.claude/agent-sync.json` | which registers are guarded, and by whose lease | 0 | every guarded write |
+| the operator's global `CLAUDE.md` | whether a task routes here at all, and the opt-out phrase | before stage 0 | — |
+
+**Precedence when two of them disagree.** For *what is*: code, then host docs and
+ADRs, then the wiki, then memory. For *what should be*: the register outranks the
+code, because a decision not yet built is still the decision — and the gap between
+them is a finding, not a tie-break ([`knowledge-sources.md`](knowledge-sources.md)).
+
 ## Stage → artifact map
 
 | Stage | Writes | Consumed by |

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/templates/docgate.sh

@@ -37,8 +37,19 @@ MAP_FILE=${MAP_FILE:-$DOCS_DIR/DOCMAP.md}
 RETRO_GLOB=${RETRO_GLOB:-$DOCS_DIR/superpowers}
 
 # ---------- ratchets: a floor may only fall. Raising one is a decision. ----------
-PROP_FLOOR=${PROP_FLOOR:-0}        # allowed missing propagation citations
-RESIDUE_FLOOR=${RESIDUE_FLOOR:-0}  # allowed unmarked citations of retired ids
+# THE TWO FLOORS ARE DIFFERENT KINDS. Mixing them up is why this is spelled out.
+#
+# PROP_FLOOR is an ID THRESHOLD, not a count. An entry whose number is >= the floor
+#   must have propagated; everything older is a counted backlog that may only shrink.
+#   ADOPTING THIS GATE IN AN EXISTING REPOSITORY MEANS SETTING IT TO THE NEXT FREE
+#   ID: from today the rule binds, and the history becomes one printed number instead
+#   of a thousand failures nobody will fix. Lower it as tranches are cleared.
+PROP_FLOOR=${PROP_FLOOR:-0}        # id threshold — entries >= this must propagate
+#
+# RESIDUE_FLOOR is a COUNT: how many unmarked citations of retired decisions are
+#   tolerated. On adoption set it to what the repository measurably has today, then
+#   only ever lower it.
+RESIDUE_FLOOR=${RESIDUE_FLOOR:-0}  # count — tolerated unmarked citations, today's number
 
 TMP=$(mktemp -d 2>/dev/null || mktemp -d -t docgate)
 trap 'rm -rf "$TMP"' EXIT