task-pipeline-skill 1.7.2 → 1.8.1

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

@@ -8,6 +8,19 @@ The same source list closes the loop at **stage 9**: what was read at the start
 what gets updated at the end. A source good enough to answer a question is a source
 that goes stale when the answer changes.
 
+## Contents
+
+- Why this is a phase and not "explore a bit first"
+- The sources, in the order to try them
+- The retro's standing instructions — an instruction source, not background
+- The code graph — recommended
+- The knowledge wiki — recommended
+- How to harvest — retrieval, not reading
+- Record it — the source ledger
+- Phase 2 — validate the answers against the harvest
+- Close the loop — stage 9 updates what stage 0 read
+- Rationalizations
+
 ## Why this is a phase and not "explore a bit first"
 
 An agent that starts asking without harvesting spends the operator's turns on

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

@@ -13,6 +13,14 @@ to be enforced and is not is the same failure as a gate that prints `FAIL` and e
 
 ---
 
+## Contents
+
+- The table — trigger · check · exit criterion
+- The incidents, so the rules are not abstract
+- The two that are not in the table, and why
+- The one instruction that would have prevented the most
+- Where these bind in the pipeline
+
 ## The table — trigger · check · exit criterion
 
 | # | Rule | Trigger | The check | Exit criterion |

package/plugins/task-pipeline/skills/task-pipeline/references/loop-guard.md

@@ -18,6 +18,14 @@ axis, don't push harder): [`audit.md`](audit.md) → *Every pass changes the axi
 Both can bind one run. Use this file's trips for edits, that file's crossover for
 searches.
 
+## Contents
+
+- Bookkeeping — the thing that makes detection mechanical
+- Detection — any one of these trips the guard
+- The break protocol
+- When to stop and hand back
+- Rationalizations
+
 ## Bookkeeping — the thing that makes detection mechanical
 
 You cannot detect churn from memory, especially after compaction. Every repeating

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

@@ -9,6 +9,18 @@ Built into this skill; nothing to install.
 > *Third-party*), extended with the dependency graph, parallel groups and
 > file-ownership rules this pipeline's stage-5 subagent build depends on.
 
+## Contents
+
+- Audience
+- Before writing tasks
+- Task right-sizing
+- Plan header — required
+- Task structure — required
+- No placeholders
+- Self-review — before handing off
+- This stage settles nothing — and that is a rule, not an omission
+- GATE (auto)
+
 ## Audience
 
 Assume a skilled developer who knows nothing about this codebase, this domain or

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

@@ -20,6 +20,17 @@ Every run writes a **stamp** and runs the **prune**. Only a run that *diverged*
 writes an entry. A retro that is empty after a messy run is the exact failure this
 file exists to stop.
 
+## Contents
+
+- Write the entry only for a divergence — and name the layer that owned it
+- Every lesson carries its commit
+- Rotation — the archive is how pruning stops losing things
+- Three grades of fix — take the highest one that can work
+- The prune — mandatory, and it runs BEFORE the new entry is written
+- The loop closes at stage 0
+- Where a lesson goes when it is not about this project
+- Rationalizations
+
 ## Write the entry only for a divergence — and name the layer that owned it
 
 An entry is owed when the run did not go as planned: a gate reopened, a stage was
@@ -114,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

@@ -10,6 +10,16 @@ install.
 > external helper scripts replaced by plain git commands so the doctrine works on
 > any agent.
 
+## Contents
+
+- The diff package
+- Reviewer inputs
+- Controller rules
+- The rubric
+- Prompt — task review
+- Prompt — scoped re-review
+- Prompt — final whole-branch review
+
 ## The diff package
 
 A reviewer never re-derives the diff with a dozen git calls, and the diff never
@@ -172,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/spec.md

@@ -9,6 +9,16 @@ Writing the approved design down so a zero-context implementer — human or suba
 > *Third-party*), extended here with the UX track and the Global Constraints block
 > that stages 4–5 depend on.
 
+## Contents
+
+- Order of operations
+- UX track (user-facing tasks only)
+- Write the spec
+- Module dossier — when the run is one brick of a platform
+- Self-review — before showing it
+- Locked contracts are decisions — the register, not only the spec
+- GATE (manual)
+
 ## Order of operations
 
 For a **user-facing task** (stage-2 UI verdict = yes) the UX chain runs **first** —

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

@@ -8,7 +8,52 @@ operator's explicit go). These stages (0 intake + 1→10) are the plugin's
 `pipeline.schema.json`; a host project replaces it with its own
 stages/agents/types (see SKILL.md → *Bring your own skills*).
 
+## The run checklist — copy it, tick it
+
+Complex workflows lose steps silently. Copy this into your response at the start of
+a run and check items off as they close; it is the cheapest guard against the one
+failure this pipeline keeps paying for — a stage that *looks* done because nothing
+printed.
+
+```
+Pipeline progress
+- [ ]  0  Intake — harvest + doc inventory + reconcile, grill, REQ table, brief locked
+- [ ]  1  Docs study — every contract grounded on fetched docs, not recall
+- [ ]  2  Brainstorm — design approved, UI verdict recorded, every REQ answered
+- [ ]  3  Spec — committed, reviewed, every section covers: REQ-…
+- [ ]  4  Plan — REQ set equality holds, no placeholders, groups share no files
+- [ ]  5  Dev — tasks DONE, three verdicts each, suite green, branch integrated
+- [ ]  6  Tests — full suite green, new checks probed both ways
+- [ ]  7  Lint + deploy — clean, and the deploy authorization is specific
+- [ ]  8  Post-deploy — clean boot, or an honest degradation report
+- [ ]  9  Docs — matrix walked, registers written, docs gate green with ratchets printed
+- [ ] 10  Acceptance — ladder walk first, every REQ with evidence, retro written last
+```
+
+Each line is a **gate**, not a task: an unchecked box means the gate did not pass,
+never that the work was skipped quietly.
+
+## Contents
+
+- The run checklist — copy it, tick it
+- 0 — Intake grill — MANDATORY
+- 1 — Docs study
+- 2 — Brainstorm + decompose
+- 3 — Spec — with UX track for user-facing tasks
+- 4 — Plan
+- 5 — Dev
+- 6 — Tests
+- 7 — Lint + deploy
+- 8 — Post-deploy
+- 9 — Docs + wiki
+- 10 — Acceptance
+- The program loop — a platform, one brick at a time
+- Cross-cutting — the Doc Loop
+- Cross-cutting — the loop guard
+- 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 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
@@ -109,15 +154,17 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   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 C*).
 - **What:** ground every external library / API / SDK the task touches on the
   *current* docs, before locking any contract.
-- **Invoke:** `context7` MCP (`resolve-library-id` → `get-library-docs`, scope by
-  `topic`) or the `context7-docs` skill. Web-search fallback for libs context7
+- **Invoke:** the `context7` MCP — `context7:resolve-library-id` → `context7:query-docs`,
+  scoped by topic or the `context7-docs` skill. Web-search fallback for libs context7
   can't resolve.
 - **GATE (auto):** every contract the design will lock is grounded in fetched docs,
   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 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
@@ -147,6 +194,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   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 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
@@ -202,6 +250,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   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 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
@@ -220,6 +269,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   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 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,
@@ -241,6 +291,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   "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 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.
@@ -254,6 +305,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   ([`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 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 —
@@ -268,12 +320,14 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   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 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 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
@@ -327,6 +381,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   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 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/references/tdd.md

@@ -7,6 +7,16 @@ into this skill; nothing to install.
 > [obra/superpowers](https://github.com/obra/superpowers) (MIT — see `LICENSE` →
 > *Third-party*), with the stage-6 suite gate added.
 
+## Contents
+
+- The iron law
+- Red → green → refactor
+- Tests that stay honest
+- Stage 6 — consolidation and the suite gate
+- When stuck
+- Rationalizations
+- Red flags — stop and start over
+
 ## The iron law
 
 ```

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

@@ -82,7 +82,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