task-pipeline-skill 1.7.2 → 1.8.1

package/CHANGELOG.md

@@ -1,5 +1,123 @@
 # 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
+
+Audited against the four Agent Skills pages (overview, best practices, enterprise,
+API guide). Most of the spec already held — `name` 13/64 chars, `description` inside
+1024, `SKILL.md` 334/500 lines, all 23 references linked **directly** from SKILL.md,
+forward slashes only, 436 KB against a 30 MB ceiling, and the plan-validate-execute
+pattern the guidance describes is exactly the stage 3→4 set-equality check. Five
+things did not.
+
+**Every reference over 100 lines now carries a `## Contents` list — 21 files, from
+zero.** The guidance is explicit about why: *"This ensures Claude can see the full
+scope of available information even when previewing with partial reads."* That
+preview is real, and `references/stages.md` is 500 lines — an agent that previewed
+it saw stages 0 and 1 and could not learn stage 9 existed. The list is **compared
+against the file's own headings**, not merely required to be present, because a
+hand-maintained contents list is a second source that goes stale on the next
+heading.
+
+**A behavioural evaluation suite, where there was none.** 46 structural guards prove
+the skill is well-*formed*; nothing proved it *behaves*. `evals/` now carries 13
+evaluations across the five dimensions the enterprise page names — should-trigger,
+should-not-trigger, ambiguous, coexistence with super-ux, and instruction-following
+(does phase 1 really run before the first question; does stage 9 walk the matrix and
+print ratchets; does a stage-5 subagent refuse to write the register; does stage 10
+run the ladder walk before the table).
+
+`evals/run.py` validates the suite and prints the protocol. **It never reports a
+pass**, because Anthropic ships no runner and a script claiming to have executed a
+model would be the exact failure this repository is written against.
+`evals/RESULTS.md` records the honest state — *authored, zero models exercised, zero
+runs* — as a ratchet, so "46 of 46 green" is never read as "the skill is known to
+work".
+
+**A copyable run checklist and a stated degree of freedom per stage.** The guidance
+recommends a checklist Claude copies into its response for complex workflows, and
+matching specificity to fragility — high freedom in the open field, low on the
+narrow bridge. Every stage now declares which it is and why: stage 2 is high (many
+designs are valid), stages 5, 7 and 9 are low (TDD order, an irreversible deploy, a
+mechanical matrix walk).
+
+**`SKILL-CARD.md`** — the registry entry the enterprise guidance asks for (purpose,
+owner, version, dependencies, evaluation status) plus an honest pass over its
+risk-tier table. This skill scores **three High indicators** — shipped scripts, MCP
+references, tool invocations — and says so, along with the three things a consumer
+should know rather than discover: author and reviewer are the same person, commits
+are unsigned, and behavioural evidence is missing rather than thin.
+
+### Changed
+
+- **The description leads with what the skill does, then the trigger** — the shape
+  Anthropic's own examples use. The validator used to *require* the string start with
+  "Use when", which enforced the WHEN half and left the WHAT half optional; it now
+  checks for both, plus the third-person voice the guidance requires.
+- MCP tools are named fully qualified (`context7:resolve-library-id`), because
+  without the server prefix Claude may fail to locate the tool.
+
+Four new guards, each with a negative self-test watched failing.
+
 ## v1.7.2 — 2026-08-03
 
 ### Fixed — nine findings from a post-release investigation of v1.7.1

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

@@ -464,6 +464,32 @@ Code, and **any exit code other than 2 is non-blocking, so a crashing guard fail
 open** and stops guarding without announcing it. Elsewhere the run is `ungated` and
 must say so.
 
+### Held to Anthropic's own Skill authoring guidance
+
+Audited against the four Agent Skills pages. Most of it already held — `name`
+13/64 chars, `description` inside 1024, `SKILL.md` 334/500 lines, all 23 references
+linked **directly** from `SKILL.md`, 436 KB against a 30 MB ceiling. What did not,
+now does:
+
+- **Every reference over 100 lines carries a `## Contents` list**, and the list is
+  *compared against the file's own headings* rather than trusted. The guidance is
+  explicit about why: a long file gets previewed with a partial read, and
+  `stages.md` is 500 lines.
+- **A behavioural evaluation suite** (`evals/`) — 13 evaluations across the five
+  dimensions the enterprise guidance names: should-trigger, should-not-trigger,
+  ambiguous, coexistence, instruction-following. `evals/run.py` validates the suite
+  and prints the protocol; it **never reports a pass**, because no runner exists
+  upstream and a script claiming to have run a model would be the exact failure this
+  skill is written against. `evals/RESULTS.md` carries the honest state.
+- **A copyable run checklist** and a **stated degree of freedom per stage** — high
+  in the open field (brainstorm), low on the narrow bridge (TDD order, deploy, the
+  matrix walk).
+- **[`SKILL-CARD.md`](SKILL-CARD.md)** — the registry entry an enterprise reviewer
+  needs, with an honest pass over the risk-tier table. This skill scores three
+  *High* indicators and says so, along with what a consumer should know rather than
+  discover: author and reviewer are the same person, commits are unsigned, and the
+  eval suite has not been executed.
+
 ### The retrospective — the run teaches the next run, and the list stays short
 
 Every gate in this flow is good at *this* run and blind across runs. So the same
@@ -604,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.
@@ -717,6 +743,8 @@ recommendation, so you arm the whole run in one exchange. Detail:
 | [`references/retrospective.md`](plugins/task-pipeline/skills/task-pipeline/references/retrospective.md) | the project retro: the three grades of fix, the mandatory prune, the cap of ten |
 | [`references/model-tiering.md`](plugins/task-pipeline/skills/task-pipeline/references/model-tiering.md) | model policy, the `/model` reminder, overrides |
 | [`templates/`](plugins/task-pipeline/skills/task-pipeline/templates/README.md) | brief, carry-over ledger, `CONTEXT.md` and ADR skeletons, the doc map, both registers, the retro and its archive, the seeded `docgate.sh`, a worked hook |
+| [`SKILL-CARD.md`](SKILL-CARD.md) | the registry entry and risk-tier disclosure a reviewer needs before deploying it |
+| [`evals/`](evals/RESULTS.md) | the behavioural evaluation suite, its protocol, and what has actually been observed |
 | [`CHANGELOG.md`](CHANGELOG.md) | every release, with the reasoning behind it |
 | [`CONTRIBUTING.md`](CONTRIBUTING.md) | dev setup, the validator, the version-sync rule, release flow |
 

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)_