task-pipeline-skill 1.8.0 → 1.9.0

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

@@ -23,6 +23,8 @@ elsewhere and is not restated here:
 
 - 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
@@ -70,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/retrospective.md

@@ -125,7 +125,7 @@ and the commit. Silent deletion is forbidden: the record is what survives, the
 instruction is what leaves.
 
 **Print the counts beside the gate verdict**, the same way the carry-over ledger
-does ([`audit.md`](audit.md) → *ratchet, never TODO*):
+does ([`audit.md`](audit.md) → *What can't be fixed now becomes a ratchet, never a TODO*):
 
 ```
 GATE 10 acceptance: PASS — 14/14 REQ verified

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

@@ -182,7 +182,7 @@ exactly the sentence a future reader will hit in the code and re-litigate, so a
 ruling that outlives the run goes through the **Doc Loop**
 ([`documentation.md`](documentation.md)) — via the report and the ledger, written by
 the orchestrator after integration, never by a subagent
-([`build.md`](build.md) → *§4.1a*).
+([`build.md`](build.md) → *4.1a Decisions settled inside a task*).
 
 Run the final review on the **run's confirmed model** like everything else
 ([`model-tiering.md`](model-tiering.md)). It is the one review that sees the whole

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

@@ -53,7 +53,7 @@ never that the work was skipped quietly.
 - Cross-cutting — the audit
 
 ## 0 — Intake grill — MANDATORY
-- **Freedom: medium** — the interview adapts to the answers; its two phases and their order do not ([`gates.md`](gates.md) → *Axis B*).
+- **Freedom: medium** — the interview adapts to the answers; its two phases and their order do not ([`gates.md`](gates.md) → *Axis C*).
 - **Stage 0 is not optional and not skippable.** There is no "small enough task"
   exemption, no "the request was already clear" exemption, no starting stage 1
   "while the operator thinks". The only sanctioned bypass is the
@@ -154,7 +154,7 @@ never that the work was skipped quietly.
   reversible calls can be deferred with a note). Only then start stage 1.
 
 ## 1 — Docs study
-- **Freedom: medium** — which sources to fetch is judgement; grounding contracts on fetched docs is not ([`gates.md`](gates.md) → *Axis B*).
+- **Freedom: medium** — which sources to fetch is judgement; grounding contracts on fetched docs is not ([`gates.md`](gates.md) → *Axis C*).
 - **What:** ground every external library / API / SDK the task touches on the
   *current* docs, before locking any contract.
 - **Invoke:** the `context7` MCP — `context7:resolve-library-id` → `context7:query-docs`,
@@ -164,7 +164,7 @@ never that the work was skipped quietly.
   not recall. Unresolvable libraries are flagged in the spec.
 
 ## 2 — Brainstorm + decompose
-- **Freedom: high** — many designs are valid — this is the open field, and the only fixed thing is the gate ([`gates.md`](gates.md) → *Axis B*).
+- **Freedom: high** — many designs are valid — this is the open field, and the only fixed thing is the gate ([`gates.md`](gates.md) → *Axis C*).
 - **How it runs: [`brainstorm.md`](brainstorm.md)** — built into this skill. Read
   the brief first (stage 0 already answered scope/constraints/done-criteria), then
   explore the codebase, scope-check for decomposition, one question at a time, 2–3
@@ -194,7 +194,7 @@ never that the work was skipped quietly.
   contracts named with their owner.
 
 ## 3 — Spec — with UX track for user-facing tasks
-- **Freedom: medium** — what the contract says is judgement; which contracts must be locked is a list ([`gates.md`](gates.md) → *Axis B*).
+- **Freedom: medium** — what the contract says is judgement; which contracts must be locked is a list ([`gates.md`](gates.md) → *Axis C*).
 - **How it runs: [`spec.md`](spec.md)** — built into this skill: the UX-track order,
   what the spec must lock (types, schemas, signatures, file layout, the **Global
   Constraints** block stages 4–5 depend on), the self-review pass and the operator
@@ -250,7 +250,7 @@ never that the work was skipped quietly.
   starts before this — the chain comes BEFORE interface.
 
 ## 4 — Plan
-- **Freedom: low** — the task format is prescribed and the REQ set-comparison is mechanical ([`gates.md`](gates.md) → *Axis B*).
+- **Freedom: low** — the task format is prescribed and the REQ set-comparison is mechanical ([`gates.md`](gates.md) → *Axis C*).
 - **How it runs: [`planning.md`](planning.md)** — built into this skill →
   `docs/superpowers/plans/YYYY-MM-DD-<topic>.md` (same slug as the brief and the
   spec). Zero-context tasks, exact
@@ -269,7 +269,7 @@ never that the work was skipped quietly.
   same change (super-ux *same-change* rule).
 
 ## 5 — Dev
-- **Freedom: low** — TDD order, worktree isolation and 'a subagent never writes the register' are the narrow bridge ([`gates.md`](gates.md) → *Axis B*).
+- **Freedom: low** — TDD order, worktree isolation and 'a subagent never writes the register' are the narrow bridge ([`gates.md`](gates.md) → *Axis C*).
 - **How it runs: [`build.md`](build.md)** — built into this skill: isolate the
   workspace (native worktree tool first, git fallback, baseline tests), keep a
   ledger under `.task-pipeline/build/<plan>/` so a compacted context can resume,
@@ -291,7 +291,7 @@ never that the work was skipped quietly.
   "leave it" recorded).
 
 ## 6 — Tests
-- **Freedom: low** — green means the full suite, and no skip smuggles a red one past ([`gates.md`](gates.md) → *Axis B*).
+- **Freedom: low** — green means the full suite, and no skip smuggles a red one past ([`gates.md`](gates.md) → *Axis C*).
 - **What:** consolidate test coverage for the change: confirm new functionality
   has tests (written test-first in stage 5), update/repair existing tests the
   change touched, and add edge-case + failure-path tests per DoD.
@@ -305,7 +305,7 @@ never that the work was skipped quietly.
   ([`audit.md`](audit.md)).
 
 ## 7 — Lint + deploy
-- **Freedom: low** — outward and irreversible — the authorization floor is exact or the stage stops ([`gates.md`](gates.md) → *Axis B*).
+- **Freedom: low** — outward and irreversible — the authorization floor is exact or the stage stops ([`gates.md`](gates.md) → *Axis C*).
 - Read host conventions (`conventions.md`): run the linter; fix failures. The suite
   is already green from stage 6 — re-run it if code changed since. For UI projects,
   the **super-ux linter** (`python3 docs/ux/lint.py` / `/ux-lint`) is part of lint —
@@ -320,14 +320,14 @@ never that the work was skipped quietly.
   operator go. Respect deploy-from-main rules if the project mandates them.
 
 ## 8 — Post-deploy
-- **Freedom: medium** — where the logs live varies; 'clean boot or an honest degradation report' does not ([`gates.md`](gates.md) → *Axis B*).
+- **Freedom: medium** — where the logs live varies; 'clean boot or an honest degradation report' does not ([`gates.md`](gates.md) → *Axis C*).
 - Tail deploy logs / health-check per conventions. Confirm clean boot, no error
   spike, live subsystems healthy.
 - **GATE (auto):** clean boot confirmed, or an **honest degradation report** with next
   steps — never silent success.
 
 ## 9 — Docs + wiki
-- **Freedom: low** — the matrix walk and the gate are mechanical; what a doc says is not this stage's call ([`gates.md`](gates.md) → *Axis B*).
+- **Freedom: low** — the matrix walk and the gate are mechanical; what a doc says is not this stage's call ([`gates.md`](gates.md) → *Axis C*).
 - **The propagation sweep runs first** ([`documentation.md`](documentation.md)).
   The ledger below names the documents you **read**; the matrix in `docs/DOCMAP.md`
   names the documents you **owe**. They are not the same list, and the gap between
@@ -381,7 +381,7 @@ never that the work was skipped quietly.
   carry-over count printed beside this verdict**.
 
 ## 10 — Acceptance
-- **Freedom: medium** — the walk and the evidence rule are fixed; whether it is what was asked for is the operator's ([`gates.md`](gates.md) → *Axis B*).
+- **Freedom: medium** — the walk and the evidence rule are fixed; whether it is what was asked for is the operator's ([`gates.md`](gates.md) → *Axis C*).
 - **What:** the closing stage — go back to the brief and account for **every**
   requirement. Doctrine: [`acceptance.md`](acceptance.md). Every earlier gate asks
   "is this artifact good?"; none asks "does this still contain everything that was

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
@@ -82,7 +93,9 @@ find . -maxdepth 1 -type f -name '*.md' 2>/dev/null | sort >> "$TMP/files" || tr
 FILE_COUNT=$(wc -l < "$TMP/files" | tr -d ' ')
 
 if [ "$FILE_COUNT" = "0" ]; then
-  echo "FAIL: documentation gate — no markdown found under $DOCS_DIR"
+  echo "FAIL: documentation gate — no markdown found in $DOCS_DIR/ or the repository root."
+  echo "      Seed the doc map and the registers first (task-pipeline stage 0, phase 1b),"
+  echo "      or point DOCS_DIR at wherever this project keeps its documentation."
   exit 1
 fi