task-pipeline-skill 1.8.0 → 1.8.1

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## v1.8.1 — 2026-08-03
+
+### Fixed — eight findings from a code-and-contradiction audit of 1.8.0
+
+A third pass, on a third axis: the first read for contradictions, the second measured
+against Anthropic's guidance, this one went after the **code** and the **invariants
+between files**. Everything below was proven before the fix and again after.
+
+**Fifteen broken cross-references, eleven of them pointing at a section about
+something else.** Every per-stage freedom label cited `gates.md → Axis B` — which is
+the *enforcement ladder* and contains no mention of degrees of freedom. Two more
+cited sections that do not exist at all (`gates.md → progressive arming`,
+`review.md → Final review`). This is the failure `references/learned.md` keeps as a
+review question rather than a rule: *"a stale reference was replaced with a FALSE
+one — the new target existed and said nothing about the subject."* The link checker
+proved every file resolved and could not see it.
+
+It is a rule now. `gates.md` gained the two sections the citations were reaching for
+— **Axis C — degrees of freedom** and **Progressive arming** — and a guard checks
+every ``file.md → *Section*`` pointer against the target's actual headings. Measured
+before shipping: whitespace is normalised first, because a citation wrapped across
+two lines is not a defect and six were reported as such.
+
+**Both installers created the shadow copy this family exists to prune.**
+`install.sh` and `bin/task-pipeline.js` write a plain copy to
+`~/.claude/skills/task-pipeline`; the launcher (`sshlg-skills`) deletes exactly those
+because while the plugin channel is active a plain copy **shadows it and keeps
+serving the version it was copied from**. `CLAUDE.md` documented the shadow-creating
+form (`--force`) as the local install path. Both installers now **refuse when a
+plugin install is detected**, name the plugin commands instead, and take `--force`
+only as a deliberate override.
+
+**The npm package did not contain what the README points at.** `SKILL-CARD.md` and
+the whole `evals/` directory were outside `files[]` while the shipped README linked
+both — and `CONTRIBUTING.md`, `SECURITY.md` and `CODE_OF_CONDUCT.md` had been
+dangling for npm consumers far longer. Rule 14 — *a document may not send a reader
+to something absent* — applied to the artefact that is actually published. All are
+packaged now, and a guard holds every relative README link to `files[]`.
+
+**Living documents restated a guard count that had moved.** `SKILL-CARD.md` and
+`evals/RESULTS.md` claimed 46 after the suite reached 50. Rule 8 — *compute, never
+restate* — had never been applied to this repository's own prose. It is now: the
+count is compared against the negative self-tests the workflow defines, and the
+guard caught its own author within the minute, when adding three tests made the
+freshly-corrected numbers stale again. CHANGELOG entries are exempt; they record
+what a past release shipped.
+
+**The contributor invariants were numbered 1,2,3,4,5,6,10,7,8,9 — and number 8
+documented the opposite of what is enforced**, still requiring the description to
+*open* with `Use when` after v1.8.0 made that a failure. Rewritten: sixteen
+invariants, in order, each matching a guard that exists.
+
+**Smaller:** the seeded gate's empty-project failure named only `docs/` while it also
+scans the repository root, and offered no remedy — it now names both and says what to
+do; `CLAUDE.md` gained the `evals/run.py` row it never had.
+
+Three new guards, each with a negative self-test watched failing.
+
 ## v1.8.0 — 2026-08-03
 
 ### Added — the skill now meets Anthropic's own authoring guidance, measurably

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,38 @@
+# Code of conduct
+
+## The short version
+
+Be decent. Argue with the idea, never with the person. Assume the other side read
+the docs and still disagrees for a reason.
+
+## Expected
+
+- **Technical criticism is welcome and wanted** — this repo is opinionated prose,
+  and the opinions get better under pressure. Bring the failure case, the file and
+  the line.
+- Accept that a maintainer may decline a change and say why. "Out of scope" is a
+  legitimate answer.
+- Respect that contributors work in different languages, time zones and
+  experience levels. English is the working language here; imperfect English is
+  never a reason to dismiss a point.
+
+## Not accepted
+
+Personal attacks, harassment of any kind, demeaning or discriminatory comments,
+sexualized language or imagery, publishing someone's private information, and
+sustained disruption of discussions.
+
+## Scope
+
+Applies to issues, pull requests, discussions, commit messages and any other
+project space, and to public spaces when someone is representing the project.
+
+## Enforcement
+
+Report anything that crosses the line to **[@sshlg on Telegram](https://t.me/sshlg)**
+or via [GitHub's report abuse](https://github.com/contact/report-abuse) flow. Reports
+are handled privately. Depending on severity the response is a warning, removal of
+the offending content, or a block from the project.
+
+Maintainers hold themselves to the same standard; a maintainer who breaks it should
+expect to hear about it publicly.

package/CONTRIBUTING.md

@@ -0,0 +1,215 @@
+# Contributing to task-pipeline
+
+Thanks for taking the time. This repo ships a **skill**, not a program: almost
+everything in it is prose that an agent reads and acts on. That makes two things
+unusually important — the doctrine must not contradict itself across surfaces, and
+the structural validator must stay able to fail.
+
+## Getting set up
+
+No build step, no dependencies. You need `python3` (validator), `node` ≥ 16 (npm
+installer), and `bash`.
+
+```bash
+git clone https://github.com/ssheleg/task-pipeline
+cd task-pipeline
+npm test          # == python3 test/validate.py
+```
+
+`npm test` must print `PASS: task-pipeline structure valid` before you open a PR.
+
+That proves the repo is well-formed. It does **not** prove the validator is
+anything more than a decoration — for that, every guard has to be watched
+rejecting a planted defect:
+
+```bash
+npm run test:negatives    # python3 test/negatives.py
+npm run test:all          # both, in order
+```
+
+The corruptions live in [`.github/workflows/validate.yml`](.github/workflows/validate.yml)
+and `test/negatives.py` reads them from there — never duplicated, because a second
+copy of a corruption is a second thing to drift. The runner also tells a **broken
+test** from a **guard that didn't fire**: if a planted defect changed nothing, the
+validator passing means the test proved nothing, and it is reported as `BROKEN`
+rather than as a failure of the guard.
+
+**Corrupt files in python, never with `sed -i`.** BSD sed needs an argument GNU sed
+refuses, and `0,/re/` does not exist on BSD at all — there it edits nothing
+silently, and the test reads as a guard that failed. The validator rejects `sed -i`
+in the workflow for exactly this reason: a self-test that only runs on CI cannot be
+used while you are writing the guard, which is the moment it is worth most.
+
+To try your change in a real agent:
+
+```bash
+./install.sh --force            # ~/.claude/skills/task-pipeline + the command
+node bin/task-pipeline.js --force   # the same, through the npm installer
+```
+
+## Repository layout
+
+| Path | What it is |
+|---|---|
+| `plugins/task-pipeline/skills/task-pipeline/SKILL.md` | the orchestrator — the entry point every agent reads first |
+| `…/references/*.md` | the built-in stage doctrine (one file per stage or concern) |
+| `…/templates/*.md` | skeletons seeded into a host project (brief, carry-over, `CONTEXT.md`, ADR) |
+| `…/pipeline.schema.json` | the universal pipeline-config contract |
+| `…/pipeline.example.json` | this plugin's own flow expressed against that contract |
+| `plugins/task-pipeline/commands/task-pipeline.md` | the `/task-pipeline` slash command |
+| `cursor/rules/task-pipeline.mdc` | the Cursor channel — **self-contained**, no relative links |
+| `bin/task-pipeline.js`, `install.sh` | the two installers |
+| `test/validate.py` | the structural validator |
+
+## The invariants
+
+These are what the validator enforces. Breaking one is not a style disagreement —
+it ships a wrong pipeline to every install. Numbered in reading order; the numbers
+are labels, not priorities.
+
+**1. Four-way version sync.** `package.json`, `.claude-plugin/marketplace.json`
+(`plugins[0].version`), `plugins/task-pipeline/.claude-plugin/plugin.json` and the
+top `## vX.Y.Z` heading in `CHANGELOG.md` must all carry the same version.
+`SKILL-CARD.md`'s Version row is held to it too.
+
+**2. The stage list lives on three surfaces and may not drift.** `SKILL.md`'s
+table, `references/stages.md`'s per-stage sections, and `pipeline.example.json`.
+Stage ids, names and **gate types** are compared across all three. Each stage's own
+doctrine file states its gate type too and must agree with the config.
+
+**3. Every human-facing description must name the flow's final stage, last.** The
+package, marketplace, plugin, skill, command, Cursor-rule and README blurbs are the
+only thing most people ever read. The validator derives the last stage from
+`pipeline.example.json` and holds every blurb to it.
+
+**4. No hardcoded vendor model ids.** Anywhere in the shipped skill, the README, the
+command or the Cursor rule. Name the **tier**, never a string; stage configs use the
+provider-agnostic tokens `default` / `inherit`.
+
+**5. Every `references/*.md` must be reachable from `SKILL.md`**, directly or
+transitively. An unreferenced file is dead context that ships and is never read.
+
+**6. No external provider may substitute for built-in stage doctrine.**
+`pipeline.example.json`'s `skills[]` may not name one for the stages whose doctrine
+ships here (2, 3-spec, 4, 5, 6, 10). The optional tools — `context7`, `figma`,
+`graphify`, `wiki-query` / `wiki-update` — and the UI-required `super-ux:*` track are
+the enumerated exceptions, named deliberately.
+
+**7. Stage 0 is mandatory and manual; stage 10 is manual and demands evidence; the
+stage-4 gate is a set comparison.** These three are the spine, asserted in the
+shipped config.
+
+**8. `SKILL.md` frontmatter stays under 1024 characters, and the description says
+WHAT before WHEN.** Anthropic's authoring guidance requires both halves — a
+capability statement in third person, then the `Use when …` trigger — and Russian
+trigger aliases ride beside the English ones. *(Before v1.8.0 this invariant demanded
+the description **open** with `Use when`, which enforced the trigger half and left
+the capability optional. The validator now rejects that shape.)*
+
+**9. Relative links resolve.** Every relative markdown link in every file outside a
+fenced code block must point at a path that exists.
+
+**10. A seeded template must keep the seeded gate green — in both register shapes.**
+`templates/docgate.sh` is run by `npm test` over two scratch projects: one seeded
+from `docmap.md` / `decisions.md` / `open-questions.md` / `retro.md`, and one built
+from `adr.md`'s own fenced example. Each must exit `0`, **report the shape it
+found**, and run a minimum of live checks — because every section can go `dormant`,
+and a gate blind to a shape passes exactly like one that reads it. Change a template
+→ run `npm test`, not just your eyes.
+
+**11. Every reference over 100 lines carries a `## Contents` list**, and the list is
+compared against that file's own `##` headings. The guidance asks for it because a
+long file gets previewed with a partial read; the comparison is because a hand-kept
+list is a second source that goes stale on the next heading.
+
+**12. A section-qualified citation must name a section that exists.**
+A citation of the form `file.md → *Section*` is checked against the target's headings. The
+link checker proves the file resolves; only this proves the pointer is not false.
+
+**13. Numbers stated in living documents are computed, not restated.** The guard
+count in `README.md`, `SKILL-CARD.md` and `evals/RESULTS.md` is compared against the
+negative self-tests the workflow defines. CHANGELOG entries are exempt — they record
+what a past release shipped.
+
+**14. Every relative link in `README.md` resolves inside the published package.**
+`package.json` → `files[]` must ship whatever the README points at, or the link
+dangles for every npm consumer.
+
+**15. `SKILL-CARD.md` answers every risk indicator** and carries the current
+version. It is the registry entry a consumer reviews before deploying, and an
+omitted row reads as "does not apply".
+
+**16. The evaluation suite covers all five dimensions** and `evals/run.py` accepts
+it. Running it is a human step; the suite existing is not.
+
+## Adding or changing doctrine
+
+- **Change one idea per PR.** These files are read by agents under load; a PR that
+  edits eight references for three unrelated reasons is unreviewable.
+- **Update every surface in the same change.** If you touch the stage list, the
+  gate types or the review verdict count, walk `SKILL.md`, `references/stages.md`,
+  `pipeline.example.json`, the command, the Cursor rule and the README before you
+  commit. The validator catches much of this — do not rely on it to think for you.
+- **A new guard needs a negative self-test.** If you teach `test/validate.py` a new
+  rule, add a step to `.github/workflows/validate.yml` that corrupts a copy and
+  asserts the validator fails, then watch it with `npm run test:negatives`. A guard
+  nobody proved can fail is decoration. **Check the base is green first** — if the
+  repo already fails your new rule, the self-test passes for the wrong reason and
+  proves nothing.
+- **Keep the Cursor rule self-contained.** It gets copied into foreign projects;
+  relative links break there. Restate, don't link.
+- **Prose style:** state the rule, then the failure it prevents. Every doctrine
+  file ends with a *Rationalizations* table for a reason — the excuse an agent will
+  reach for is more useful to write down than the rule itself.
+
+## Commits and pull requests
+
+- **Conventional commits:** `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`.
+  Append the version when the change ships one: `feat: … ; v0.19.0`.
+- Fill in the PR template: what changed, which surfaces you updated, validator
+  output.
+- CI must be green. It is fast and dependency-light on purpose.
+
+## Releasing (maintainers)
+
+1. Bump the version in **all four** places (see invariant 1) and write the
+   `CHANGELOG.md` section — what changed and *why it mattered*, not a diff summary.
+2. `npm test` green, commit, push.
+3. Tag `vX.Y.Z` and push the tag. With the repo variable `RELEASE_ENABLED=true`,
+   [`.github/workflows/release.yml`](.github/workflows/release.yml) re-runs the
+   validator, checks the tag against the manifests, cuts a GitHub release from that
+   CHANGELOG section, and smoke-tests `npx` from a clean checkout.
+4. **`npm publish` runs in the same workflow**, in a second job armed by the repo
+   variable `PUBLISH_NPMJS=true` — it was the one human step in every release, and
+   the registry drifted behind the tags because of it. Auth is either the
+   `NPM_TOKEN` secret (a **granular automation** token; a classic one is still
+   refused by 2FA) or npm trusted publishing via OIDC, which needs no long-lived
+   credential. With `PUBLISH_NPMJS` unset or false it stays manual, and 2FA makes
+   that a human step.
+5. Refresh the local installs: `claude plugin marketplace update task-pipeline` →
+   `claude plugin update task-pipeline@task-pipeline` →
+   `npx skills update task-pipeline --global --yes`, then restart the agent.
+
+
+### The family catalogue moves with the release
+
+`sshlg-skills` — the launcher that installs and updates the whole ssheleg family — pins every
+member's version in its own `skills.json`. **A release that does not bump that pin is invisible.**
+`npx sshlg-skills list` keeps reporting the previous version, `update` keeps installing it, and
+anyone comparing their install against `list` is told the wrong number with nothing to reveal it.
+
+So a release is not finished at `npm publish`:
+
+```bash
+# in ssheleg/sshlg-skills
+#   1. bump this member's "version" in skills.json
+#   2. bump the launcher's own version, changelog, tag
+npm publish --access public
+npx --yes sshlg-skills@latest list   # the new number must appear here
+```
+
+## License
+
+By contributing you agree that your contributions are licensed under the
+[MIT License](LICENSE), and that any third-party material you bring in is
+compatible and gets its notice added to `LICENSE` → *Third-party*.

package/README.md

@@ -630,7 +630,7 @@ framework bakes in no fixed stage count and no opinion on which gates are manual
 A pipeline config may declare an optional `release` block: a master `enabled`
 toggle, a `trigger`, project-defined `steps`, and `verify` smoke-checks. It's **off
 unless a project turns it on**, and every project configures its own. This repo's
-own instance is [`.github/workflows/release.yml`](.github/workflows/release.yml) —
+own instance is [`.github/workflows/release.yml`](https://github.com/ssheleg/task-pipeline/blob/main/.github/workflows/release.yml) —
 armed per repo by the `RELEASE_ENABLED` variable (unset = off), it validates the tag
 against the manifests, cuts a GitHub release from the CHANGELOG, and smoke-tests
 `npx` from a clean checkout. Copy and adapt it; nothing is hardcoded.

package/SECURITY.md

@@ -0,0 +1,67 @@
+# Security policy
+
+## What this project is
+
+`task-pipeline` ships **markdown doctrine plus two small installers**. There is no
+server, no network client and no runtime service. The executable surface is:
+
+| Surface | What it does |
+|---|---|
+| `bin/task-pipeline.js` | copies the skill directory into `~/.claude/` (zero dependencies) |
+| `install.sh` | the same, in POSIX shell |
+| `test/validate.py` | reads repo files and exits 0/1; run in CI |
+| `.github/workflows/*.yml` | CI and the toggleable release job |
+
+The skill's doctrine, however, is **instructions an agent will act on** inside your
+repository — including running your test and lint commands and, at stage 7, your
+deploy. Treat a change to `references/*.md` with the same care as a change to a
+deploy script.
+
+## Supported versions
+
+The latest released version is supported. Fixes ship in a new release rather than
+as patches to older tags.
+
+## Reporting a vulnerability
+
+**Do not open a public issue for a security problem.**
+
+- Preferred: [GitHub private vulnerability reporting](https://github.com/ssheleg/task-pipeline/security/advisories/new)
+  (Security → Report a vulnerability).
+- Alternative: Telegram [@sshlg](https://t.me/sshlg).
+
+Please include what you found, how to reproduce it, and the impact you see. You'll
+get an acknowledgement within **72 hours** and a fix or a decision with reasoning
+within **14 days** for anything confirmed. Coordinated disclosure is welcome — tell
+me the timeline you'd like and I'll work to it.
+
+## In scope
+
+- The installers writing outside `~/.claude/skills/task-pipeline` and
+  `~/.claude/commands/task-pipeline.md`, or overwriting files without `--force`.
+- Anything in the shipped doctrine that would lead an agent to exfiltrate secrets,
+  push to a repository the task never named, deploy without the operator's go, or
+  bypass a gate that exists to require one.
+- Command injection or path traversal through the validator or the workflows.
+- A CI workflow that could be made to leak repository secrets.
+
+## Out of scope
+
+- The behavior of the AI agent that reads the skill. Agents are non-deterministic;
+  a model ignoring an instruction is a doctrine-quality bug — please file it as a
+  normal issue.
+- Third-party companions (`super-ux`, `context7`, `obsidian-wiki`). Report those to
+  their own maintainers.
+- Anything requiring an attacker who already controls the operator's machine or
+  their agent's configuration.
+
+## Hardening notes for operators
+
+- **Deploy authorization has a floor by design.** The pipeline treats deploy,
+  publish and PR-opening as outward actions that need an explicit go, or a standing
+  authorization that names the target *and* the preconditions. Do not record a
+  blanket "do everything" in a brief — it is specifically rejected.
+- **Writes to another repository are always proposal + PR**, never a direct push.
+- The build stage keeps its scratch state in a git-ignored `.task-pipeline/`
+  directory; confirm that directory is ignored before you run it in a repo with
+  strict commit hooks.

package/SKILL-CARD.md

@@ -0,0 +1,60 @@
+# Skill card — task-pipeline
+
+**What a reviewer needs before deploying this skill, in one page.** The fields are
+the registry entry Anthropic's [Skills for enterprise](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise)
+guidance asks every organisation to keep, plus an honest pass over its risk-tier
+table. Written so somebody who did not build this can decide, not so it looks
+harmless.
+
+## Registry entry
+
+| Field | Value |
+|---|---|
+| **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 |
+| **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) |
+
+## Risk-tier disclosure
+
+Every indicator from the enterprise risk table, answered — including the ones that
+apply.
+
+| Indicator | Applies? | What exactly |
+|---|---|---|
+| **Code execution** | **Yes — High** | Ships `templates/docgate.sh` (seeded into the host project as its documentation gate), `bin/task-pipeline.js` and `install.sh` (installers), `test/*.py` and `evals/run.py` (repo checks). None run automatically; the gate is seeded and run by the host project |
+| **MCP server references** | **Yes — High** | Instructions name `context7`, `figma`, `graphify`, `wiki-query`, `wiki-update`. All optional; absence degrades a stage, never blocks one, except super-ux on a UI task |
+| **Tool invocations** | **Yes — Medium** | Instructs bash (git, test runners, the host's lint/deploy commands), file reads and writes, and a `PreToolUse` hook example that runs the docs gate before a commit |
+| **Filesystem access scope** | **Yes — Medium** | Reads and writes inside the host project: `docs/`, `scripts/check-docs.sh`, `.task-pipeline/` scratch, `CONTEXT.md`. Stage 5 creates and removes git worktrees. Writing to **another repository** is treated as outward and requires an explicit go |
+| **Instruction manipulation** | No | Nothing instructs Claude to bypass safety rules, hide actions, or behave conditionally on hidden inputs. Outward and irreversible actions (deploy, publish, PR, editing a shared design file) explicitly require operator authorization |
+| **Network access patterns** | Minimal | No `curl`/`fetch`/`requests` in shipped code. The doctrine tells the agent to fetch **library documentation** at stage 1 and to re-fetch the hook contract; both are reads of vendor docs, named in the text |
+| **Hardcoded credentials** | No | None. Release automation uses repository secrets in CI, never files in the skill |
+
+## What to check before you trust it
+
+1. Read `SKILL.md` and the 23 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
+   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.
+
+## Posture, stated rather than implied
+
+- **Separation of duties is not in place.** The author and the reviewer are the same
+  person. The enterprise guidance asks for separation; a consumer should treat this
+  repository's own review as an author's self-review and do their own.
+- **Commits are unsigned**, so provenance rests on GitHub account control rather than
+  cryptographic signature. Integrity verification by checksum is possible today
+  (`npm pack` / tag archives) and is not automated.
+- **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
+  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/bin/task-pipeline.js

@@ -78,6 +78,29 @@ function main(argv) {
   }
 
   const home = os.homedir(); // respects $HOME on POSIX — tests override via env
+
+  // One channel per agent. This installer writes a PLAIN copy to
+  // ~/.claude/skills/<id>, and while the Claude Code PLUGIN channel is active that
+  // copy SHADOWS the plugin — silently serving whatever version was copied, forever.
+  // The family launcher (sshlg-skills) prunes exactly these copies for that reason,
+  // so creating one without saying so undoes the thing it is paired with.
+  const pluginDirs = [
+    path.join(home, '.claude', 'plugins', 'marketplaces', 'task-pipeline'),
+    path.join(home, '.claude', 'plugins', 'cache', 'task-pipeline'),
+  ];
+  if (!force && pluginDirs.some((d) => fs.existsSync(d))) {
+    console.error(`refusing: task-pipeline is already installed as a Claude Code PLUGIN.
+
+A plain copy in ~/.claude/skills/ shadows the plugin and keeps serving the version
+it was copied from — the failure this family prunes for. Prefer the plugin:
+
+  claude plugin marketplace update task-pipeline
+  claude plugin update task-pipeline@task-pipeline
+
+Rerun with --force if you deliberately want the plain copy instead.`);
+    return 3;
+  }
+
   installOne(
     'task-pipeline skill  ',
     skillSrc,

package/evals/RESULTS.md

@@ -0,0 +1,47 @@
+# Evaluation results — task-pipeline
+
+**Status: the suite is authored and has not been executed.** Recorded here rather
+than left blank, because an empty results file and an unrun suite look identical,
+and this repository's own doctrine calls that the failure — a skip is not a pass.
+
+Running these needs a fresh session per query, per model. That is a human or agent
+step; `evals/run.py` prints the protocol and deliberately never reports a pass it
+did not observe.
+
+## How to record a run
+
+One table per date + model. Verdict is `pass` / `fail` / `partial`, and a `fail`
+carries what actually happened, not a shrug.
+
+```markdown
+## 2026-08-10 · sonnet
+
+| id | verdict | what happened |
+|---|---|---|
+| TRIG-01 | pass | harvest ran first, ledger written, no code before the brief |
+| NOTRIG-02 | fail | invoked the skill for a one-character README fix |
+```
+
+Then act on the result the way the enterprise guidance says: declining trigger
+accuracy → change the description; coexistence conflicts → narrow it or consolidate;
+persistent instruction-following failures → the instruction is not prominent enough,
+or it belongs in a check.
+
+## Ratchet
+
+| Metric | Value | As of |
+|---|---|---|
+| Evals authored | 13 | 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
+*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
+known to work".
+
+## Runs
+
+_(none yet)_

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

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

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

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

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

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

@@ -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