task-pipeline-skill 1.7.2 → 1.8.1

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,166 @@
+{
+  "_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."
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.7.2",
+  "version": "1.8.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"
@@ -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.7.2",
+  "version": "1.8.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: "Use when running a substantial task through the full end-to-end delivery pipeline — an up-front intake grill that expands the request into a complete brief, then docs study, brainstorm, spec, plan, subagent-driven build, tests, lint/deploy, post-deploy log check, docs/wiki sync and acceptance — as gated stages whose doctrine is built entirely into this skill (no required companion skills). Triggers - 'run this through the pipeline' / 'прогони по конвейеру', 'the full cycle' / 'полный цикл', /task-pipeline, or any substantial feature, fix, or build that should follow the disciplined cycle rather than ad-hoc coding. The intake grill is mandatory - it front-loads every decision, including the per-stage autonomy sweep, so stages 1→10 run without mid-flight questions; recommends super-ux for user-facing work; confirms one model up front (most capable available, never a hardcoded id); reads host-project conventions for deploy/docs/wiki 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 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."
 license: MIT
 ---
 

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

@@ -7,6 +7,19 @@ None of them asks *"does this still contain everything that was asked for?"*
 That is this stage's only job: **go back to the brief and account for every
 requirement.** It is what turns the pipeline from a funnel into a circle.
 
+## Contents
+
+- Why a stage and not a gate
+- First, the ladder walk — what the list itself is missing
+- Inputs
+- Output — the coverage table
+- Evidence, not assertion
+- Several repositories — a submodule is finished when its parent says so
+- The closing question
+- The retrospective — the run's last act
+- GATE (manual)
+- When the answer is "something's missing"
+
 ## Why a stage and not a gate
 
 The loss this catches doesn't happen inside a stage — it happens **on the seams**.

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

@@ -5,6 +5,12 @@ a resumed or handed-off run always knows where to look. This is the recommended
 structure; a host project may relocate roots via its `CLAUDE.md`, but keep the
 shape.
 
+## Contents
+
+- In the host project
+- Stage → artifact map
+- This repo (task-pipeline itself), for reference
+
 ## In the host project
 
 ```

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

@@ -14,6 +14,17 @@ This file is the method that finds those. It is **cross-cutting**: stage 10 runs
 before writing the coverage table, the program loop runs it per module, and a task
 whose whole job is "audit X" runs nothing else.
 
+## Contents
+
+- Three things that are easy to confuse
+- Why "look again, more carefully" stops working
+- The ladder
+- How one audit pass runs
+- Exit criterion — the part usually skipped
+- The three rules that stop this becoming another loop
+- When this runs
+- Rationalizations
+
 ## Three things that are easy to confuse
 
 | File | Runs when | Answers |

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

@@ -12,6 +12,18 @@ approved design — not at code.
 > the UI verdict is a required output, and the spec write-up moved to stage 3
 > ([`spec.md`](spec.md)).
 
+## Contents
+
+- The hard gate
+- Input: the brief, not a blank page
+- The loop
+- Design for isolation and clarity
+- Working in an existing codebase
+- UI detection — a required output
+- The approved design is a set of decisions — record them
+- GATE (manual)
+- Rationalizations
+
 ## The hard gate
 
 **No implementation action before the operator approves a design.** No code, no

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

@@ -29,6 +29,17 @@ the work; the gates, the artifacts and the review discipline do not. Say plainly
 that the run is inline, since a self-review is weaker evidence than a fresh
 reviewer's.
 
+## Contents
+
+- 1. Isolation
+- 2. Workspace and ledger
+- 3. Models
+- 4. The task loop
+- 5. Final whole-branch review
+- 6. Integrate, then finish
+- GATE (auto)
+- Rationalizations
+
 ## 1. Isolation
 
 Work never starts on `main`/`master` without the operator's explicit consent
@@ -341,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

@@ -8,6 +8,15 @@ something isn't installed.
 What remains is a short list of **optional** companions that make individual stages
 better, plus one that is required only for user-facing work.
 
+## Contents
+
+- Built in — nothing to install
+- The matrix
+- Optional bridge — substituting an external skill set
+- Preflight (emit before stage 0)
+- Credit
+- Hand-off the other direction
+
 ## Built in — nothing to install
 
 | Stage | Doctrine |
@@ -34,7 +43,7 @@ better, plus one that is required only for user-facing work.
 | Skill / tool | Needed for | Required? | Install |
 |---|---|---|---|
 | **super-ux** (`ux-foundation`, `ux-flows`, `ux-scenarios`, `ux-audit`, `/ux`, `/ux-lint`) | stage 3 UX track | **Required for any user-facing task** | `/plugin marketplace add ssheleg/super-ux` → `/plugin install super-ux@super-ux` (or `npx skills add ssheleg/super-ux`) |
-| **context7** (MCP) | stage 1 docs study | Recommended (web-search fallback) | connect the context7 MCP server |
+| **context7** (MCP — call tools fully qualified: `context7:resolve-library-id`, `context7:query-docs`) | stage 1 docs study | Recommended (web-search fallback) | connect the context7 MCP server |
 | **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 .` |

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

@@ -8,6 +8,15 @@ a time, each brick carrying its own documentation, spec, plan, build and gates.
 This runs at the end of **stage 2**, on the approved design, before any spec is
 written. It is skipped — explicitly, in writing — when the work is a single module.
 
+## Contents
+
+- When it applies
+- How to cut
+- The module map — the artifact
+- GATE (part of stage 2, manual)
+- The program loop — one brick at a time
+- Program done
+
 ## When it applies
 
 Decompose when any of these is true:

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

@@ -16,6 +16,20 @@ being written twice; write it once, here.
 
 ---
 
+## Contents
+
+- The inventory — four questions, answered before the first line of work
+- Registers and ids
+- Single source of truth
+- The Doc Loop
+- Changing your mind
+- The propagation matrix
+- Navigation
+- Intent and as-built
+- Registers are shared state
+- Where this binds in the pipeline
+- Rationalizations
+
 ## The inventory — four questions, answered before the first line of work
 
 Stage 0 answers these before the interview, and writes the answers to
@@ -36,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*).
 
 ---
 

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

@@ -19,6 +19,22 @@ elsewhere and is not restated here:
 
 ---
 
+## Contents
+
+- Axis A — the stage gate type
+- Axis B — the enforcement mechanism
+- Axis C — degrees of freedom
+- Progressive arming
+- Before you run a check
+- Anatomy of a project gate
+- Writing the check itself
+- Probing — plant, run, restore
+- The false-positive budget
+- Ratchets
+- Where a gate runs
+- Adding a check to an existing gate
+- Rationalizations
+
 ## Axis A — the stage gate type
 
 From [`../pipeline.schema.json`](../pipeline.schema.json), one per stage:
@@ -56,6 +72,53 @@ disprove. Left unwritten, it is indistinguishable from an omission.
 
 ---
 
+## Axis C — degrees of freedom
+
+Axis B says how hard a rule bites. This one says how much latitude the *instruction*
+leaves, and it is a separate choice: a low-freedom instruction guarded by nothing is
+a wish, and a high-freedom instruction behind a blocking hook is a bottleneck.
+
+Match the level to how **fragile** the step is, not to how important it feels:
+
+| Level | Shape | Use when | Example here |
+|---|---|---|---|
+| **high** | prose direction, no prescribed sequence | many routes reach a good answer and context decides | stage 2 — the design conversation |
+| **medium** | a named order with room inside each step | the sequence is fixed, the content is judgement | stage 0 — two phases, adaptive questions |
+| **low** | run exactly this, in this order, no variation | the operation is fragile, irreversible, or must be identical every time | stage 5's TDD order · stage 7's deploy · stage 9's matrix walk |
+
+The picture worth keeping is an **open field versus a narrow bridge**. In the field,
+say where to go and let the agent find the route. On the bridge there is one safe way
+across, and the guardrails are the instruction.
+
+**Over-constraining costs as much as under-constraining and is harder to see.** A
+high-freedom step written as low freedom produces an agent that follows the letter
+past the point where the letter stopped fitting — and reports success, because it did
+what it was told. Where a step is genuinely open, say so out loud; that sentence is
+what stops the next reader from hardening it.
+
+Every stage in [`stages.md`](stages.md) declares its level and its reason, on the
+line under its heading.
+
+## Progressive arming
+
+A gate seeded into a young project has almost nothing to check yet, and a gate that
+starts red teaches everyone on day one that it is noise ([`learned.md`](learned.md)
+rule 9). So each section reports one of four states and only one of them fails:
+
+| State | Means | Fails? |
+|---|---|---|
+| `ok` | the check ran and passed | no |
+| `dormant: … — no <artefact> yet` | the input does not exist yet | no |
+| `skip: … — <why>` | the input exists, the check could not run here | no |
+| `ERR` | the check ran and found something | **yes** |
+
+`dormant` and `skip` are **printed, never silent** — that is the whole reason they do
+not quietly become permanent.
+
+They also force one more obligation on the verdict line: it must report **what the
+run actually looked at**. Every section dormant is indistinguishable from a gate
+blind to the shape in front of it, and exit 0 alone cannot tell those two apart.
+
 ## Before you run a check
 
 Four preconditions. Skipping any of them turns a run into a claim.

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

@@ -12,6 +12,16 @@ coming back to the operator.
 > half — glossary challenges, `CONTEXT.md`, ADR discipline — comes from there; the
 > autonomy sweep and the brief are this pipeline's.
 
+## Contents
+
+- Phase 1 — harvest before you ask
+- Phase 2 — the loop
+- Domain awareness
+- The autonomy sweep
+- The design destination — one file, decided here, never invented later
+- The REQ spine — the grill's other hard output
+- Output
+
 ## Phase 1 — harvest before you ask
 
 **Do not open the interview cold.** Stage 0 begins by finding what the project

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

@@ -4,6 +4,22 @@
 have.** A hook is rung 5 of [`gates.md`](gates.md)'s ladder — the only mechanism
 that acts *while the agent is working* rather than after the commit.
 
+## Contents
+
+- The limit, before the capability
+- The events
+- The `PreToolUse` contract
+- What the hook receives
+- Where it lives
+- Matchers
+- Performance
+- What belongs in a hook, and what does not
+- A worked example
+- Debugging
+- Removing them
+- Leases are not reimplemented here
+- Rationalizations
+
 ## The limit, before the capability
 
 **Hooks exist only in Claude Code.** On Cursor, Codex and the other agents a skill

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

@@ -15,6 +15,14 @@ It is **recommended, never required**. No stage blocks on a missing graph; the
 harvest simply runs on the sources it has
 ([`knowledge-sources.md`](knowledge-sources.md)).
 
+## Contents
+
+- Detect it, and install it once
+- Stage 0 — query the graph before you ask the person
+- Stage 9 — the close-out has three artifacts, not two
+- The divergence check — the graph against the docs
+- Rationalizations
+
 ## Detect it, and install it once
 
 Detect, in this order: