task-pipeline-skill 1.52.0 → 1.53.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## v1.53.0 — the artifact root stops carrying another pack's name
+
+The paperwork directory was called `docs/superpowers/`. The name came from an unrelated
+pack — one whose own tests walk the same path — and `references/artifacts.md` had called
+it "historical convention" since v0.1.0, promising that a host project *may relocate the
+root*. Nothing kept that promise: the path was hardcoded in 24 places in the validator,
+in the gate prose of `pipeline.json`, and in 26 CI plants.
+
+### Added
+
+- **`paths.artifacts` in `pipeline.schema.json`.** Any relative path, and it outranks
+  both discovered names. This is what turns the v0.1.0 sentence into a mechanism.
+- **The artifact-root rule, resolved rather than spelled.** `paths.artifacts` →
+  an existing `docs/evidence/` → an existing `docs/superpowers/` → `docs/evidence/` for
+  a project that has neither. A directory is adopted only when it **carries a register**
+  (`retro.md`, `backlog.md`, `verification.md`, or a `specs/plans/briefs/retro`
+  directory): a project may keep an unrelated `docs/evidence/`, and adopting it on a
+  name match would write a run's paperwork into somebody else's folder. The answer is a
+  record — `{root, reason, legacy, leftover, collision}` — because a bare string cannot
+  say *this is the legacy name*, *records also sit over there*, or *the default landed on
+  an occupied directory*.
+- **Two implementations, one table, compared to each other.**
+  `bin/lib/artifact-root.js` ships; `test/artifact_root.py` serves the validator;
+  `test/artifact_root_test.py` builds all seven cases as real trees and fails when the
+  two disagree. Checking each against the table alone would let them drift into two
+  readings that are both "right".
+- **`npx task-pipeline migrate-artifacts [--dry-run]`.** Optional, always: the legacy
+  name is supported and **no run warns about it**. It moves the directory, refuses when
+  `paths.artifacts` is set rather than overriding the operator, never overwrites a
+  collision, backs up before writing — and **lists every file elsewhere that names the
+  old path without editing one of them.** Rewriting arbitrary documents in somebody's
+  repository would mean deciding for them which mentions are a path in use and which are
+  a sentence about the old name; this release got that distinction wrong in its own
+  sweep before the command was written, which is the argument for not automating it.
+- **`/task-pipeline setup` now opens with the resolved root and why**, with all four
+  outcomes spelled out — including the one where the default lands on a directory that
+  exists and carries no register, which is a stop-and-ask rather than a write.
+
+### Changed
+
+- **The default is `docs/evidence/`**, matching the `evidence-docs` skill this plugin
+  already ships. **Nothing migrates on its own.** A project on `docs/superpowers/` keeps
+  it, forever, with no warning on any run — an upgrade is a no-op for everyone already
+  running.
+- 24 sites in `test/validate.py` and 105 occurrences across 34 files now go through the
+  rule: doctrine writes `<artifacts>/`, templates and this repository's own statements
+  write the resolved name. **Frozen records were not touched** — a brief from March
+  describes where things were in March, and rewriting it would falsify the record.
+
+### Fixed
+
+- **A guard that had lost its subject.** The prose sweep rewrote
+  `` `docs/superpowers/…` `` to `` `<artifacts>/…` `` — and the guard comparing
+  `artifacts.md`'s tables against its layout tree searched for the resolved literal, so
+  it found nothing and passed by having nothing to check. Reported by the negative
+  self-test as *does not actually fire*, not by the validator, which was green. That is
+  standing instruction #6's corollary landing in this repository's own validator one
+  release after the instruction was written; the guard is now anchored on the symbol the
+  doctrine writes, and it has been watched failing against a planted defect.
+- **A plant that no longer landed.** The CI plant removing the layout tree anchored on a
+  bare `superpowers/` — a spelling the path sweep never matched — and said so, loudly,
+  because it asserts its own effect. Repointing the other 26 plants recovered 24 broken
+  negative self-tests.
+- **A backup taken when nothing moved.** `migrate-artifacts` copied the legacy tree
+  before every run, so a second run against a still-colliding tree changed the tree it
+  claimed to leave alone. Found by the three-run fixture rather than by reading: the pure
+  planner was right and the command that repeats was not, which is standing instruction
+  #2 arriving in the release that cites it.
+
+Guards: 312 → **313**. Property checks: 9 → 9. The new one reverses the precedence in
+one of the two resolver implementations: the table still describes the correct order, so
+a suite that merely ran both would stay green while they drifted apart on a case the
+table never named. Two new suites join CI — the artifact-root rule (7 cases, both
+implementations compared) and `migrate-artifacts` (7 cases, three real runs with hashes
+compared). 26 CI plants were repointed at the new root and 24 broken negative self-tests
+recovered; two remain unable to fire in a submodule checkout for a reason that predates
+this release (the harness copies to `/tmp` without a resolving `.git`, and both guards
+read git history — CI clones normally and is green).
+
 ## v1.52.0 — the three moments the run's own record could not show
 
 ### Added

package/CONTRIBUTING.md

@@ -371,11 +371,11 @@ seven files where thirteen state the condition, the disclosure check named five
 rule and the command. Every miss was found by a reader or a sweep, never by the guard —
 **nobody notices a corpus that is too small, because everything inside it passes.**
 Exclusions are allowed and must each carry a reason in the code: a changelog narrates
-old formats, `docs/superpowers/specs/` are point-in-time records.
+old formats, `docs/evidence/specs/` are point-in-time records.
 *(guard: `a worked GATE verdict omits ` and `states the cold-retirement condition as` — both now run over corpora walked from disk, so a new surface joins by existing)*
 
 **44. A carry-over row still `open` names a board id, and the board row names it back.**
-`docs/superpowers/backlog.md` is the project's queue between runs; the ledger's `open`
+`docs/evidence/backlog.md` is the project's queue between runs; the ledger's `open`
 was a home that pointed nowhere, and rows across eight ledgers sat in it — sixteen by the first, positional count, twenty-four once the check stopped reading by column. Both
 directions are checked because they are different failures — an id nobody issued, and a
 row traceable to nothing. The test is **position-free**: a row is open if any of its cells
@@ -387,7 +387,7 @@ design and it was wrong for the same reason.
 *(guard: `with no board id` and `names no Source`)*
 
 **45. Every shipped REQ has a verification row, and `Human` is a date or `never`.**
-`docs/superpowers/verification.md` records the one thing no check can decide — whether a
+`docs/evidence/verification.md` records the one thing no check can decide — whether a
 person looked after it shipped. Both directions: a shipped REQ with no row, and a row
 whose REQ is in no brief. It keys to the brief because eight of nine briefs carry
 machine-readable REQ rows while ten acceptance files carry their coverage table in nearly

package/HOW-IT-WORKS.md

@@ -380,5 +380,5 @@ exclusion clause as their reason to refuse.
 | change it | [`CONTRIBUTING.md`](CONTRIBUTING.md) — the invariants live there |
 | why a release happened | [`CHANGELOG.md`](CHANGELOG.md) |
 | the stage doctrine itself | `plugins/task-pipeline/skills/task-pipeline/references/` |
-| what is open | [`docs/superpowers/backlog.md`](docs/superpowers/backlog.md) |
+| what is open | [`docs/evidence/backlog.md`](docs/evidence/backlog.md) |
 | what is genuinely unresolved | [`docs/OPEN_QUESTIONS.md`](docs/OPEN_QUESTIONS.md) |

package/README.md

@@ -584,7 +584,7 @@ class of failure gets caught, fixed and forgotten five times, and nothing in the
 pipeline notices it is the same one.
 
 The last act of stage 10 is therefore a **retrospective**, written to
-`docs/superpowers/retro.md` — **one file per project, not per run**
+`docs/evidence/retro.md` — **one file per project, not per run**
 ([`retrospective.md`](plugins/task-pipeline/skills/task-pipeline/references/retrospective.md)).
 Every run **stamps and prunes** — in that order, because one retirement trigger
 counts firings across the last five run stamps **or sixty days**, whichever comes
@@ -784,6 +784,20 @@ npx task-pipeline-skill                   # from the npm registry
 on npm; installs the same skill + `/task-pipeline` command into `~/.claude`,
 idempotent, `--force` to overwrite)
 
+**Moving the paperwork off the legacy directory name — optional, always:**
+```bash
+npx task-pipeline-skill migrate-artifacts --dry-run   # the plan, nothing written
+npx task-pipeline-skill migrate-artifacts             # do it
+```
+The artifact root was `docs/superpowers/` until v1.53.0 and the default is now
+`docs/evidence/`. **A project on the old name keeps it and no run warns about it** —
+the root is resolved (`paths.artifacts` in `pipeline.json`, else an existing
+`docs/evidence/`, else an existing `docs/superpowers/`, else the new default), so an
+upgrade changes nothing for a project already running. The command moves the directory,
+never overwrites a collision, refuses when `paths.artifacts` is set rather than
+overriding you, and **lists every other file that names the old path without editing
+one of them** — only you can tell a path in use from a sentence about the old name.
+
 **Cursor:** the skills CLI above with `--agent cursor`, or per project copy
 [`cursor/rules/task-pipeline.mdc`](cursor/rules/task-pipeline.mdc) into the repo's
 `.cursor/rules/`. Cursor has no global rules directory — use the skills CLI for a

package/SKILL-CARD.md

@@ -12,7 +12,7 @@ harmless.
 |---|---|
 | **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.52.0 |
+| **Version** | 1.53.0 |
 | **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, 5 categories. One recorded run, **self-observed by the author**; **zero blind runs on zero of three models** — the split, and the numbers, live in [`evals/RESULTS.md`](evals/RESULTS.md) and are computed by `evals/run.py` |

package/bin/lib/artifact-root.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * Where this project's run artifacts live — the shipped answer.
+ *
+ * The same ordered rule as `test/artifact_root.py`, which serves the validator.
+ * `test/artifact_root_test.py` runs both against
+ * `test/fixtures/artifact-root-cases.json` and fails when they disagree, which is
+ * what makes two implementations of one rule affordable at all.
+ *
+ *   1. `paths.artifacts` in `pipeline.json` wins outright. Any relative path.
+ *   2. otherwise the first KNOWN name that exists AND CARRIES A REGISTER.
+ *      `docs/evidence/` before `docs/superpowers/`, so a partial migration
+ *      resolves forward and moving one file at a time never splits a project.
+ *   3. otherwise `docs/evidence/`, the default for a project that has none.
+ *
+ * **Carrying a register is the whole difference between a root and a directory.**
+ * A project may keep an unrelated `docs/evidence/`; adopting it on bare existence
+ * would write a run's paperwork into somebody else's folder.
+ *
+ * **The answer is a record, not a string.** A bare path cannot say *this is the
+ * legacy name*, *records also sit over there*, or *the default landed on an
+ * occupied directory* — and a caller that cannot know those things writes blind.
+ *
+ * This file lives under `bin/` because that is what the package ships
+ * (`package.json` → `files`), and `bin/task-pipeline.js` is its only caller.
+ * Run directly it prints the record as JSON, which is how the Python test asks it.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** Ordered. The new name first, so a partial migration resolves forward. */
+const KNOWN = ['docs/evidence', 'docs/superpowers'];
+
+/** The name this pipeline used until 2026-08-13. Supported, not deprecated. */
+const LEGACY = 'docs/superpowers';
+
+/** What makes a directory a root rather than a directory. Any ONE of these. */
+const REGISTERS = ['retro.md', 'backlog.md', 'verification.md',
+                   'specs', 'plans', 'briefs', 'retro'];
+
+/** Does this directory hold any artifact this pipeline recognises? */
+function carriesRegister(dir) {
+  let st;
+  try { st = fs.statSync(dir); } catch (e) { return false; }
+  if (!st.isDirectory()) return false;
+  return REGISTERS.some((name) => fs.existsSync(path.join(dir, name)));
+}
+
+/**
+ * `paths.artifacts` from `pipeline.json`, or `null`.
+ *
+ * An unreadable or malformed config yields `null` rather than throwing: the
+ * resolver's job is to answer, and a project with a broken config still has a
+ * directory layout. The config's own validity is the schema check's business.
+ */
+function configured(project) {
+  let cfg;
+  try {
+    cfg = JSON.parse(fs.readFileSync(path.join(project, 'pipeline.json'), 'utf8'));
+  } catch (e) {
+    return null;
+  }
+  const value = cfg && cfg.paths && cfg.paths.artifacts;
+  if (typeof value === 'string' && value.trim()) {
+    return value.trim().replace(/\/+$/, '');
+  }
+  return null;
+}
+
+/**
+ * `{root, reason, legacy, leftover, collision}` for a project directory.
+ * `root` is relative to `project` and posix-separated.
+ */
+function resolve(project) {
+  if (typeof project !== 'string' || !project) {
+    // A resolver handed nothing must not answer as though it were handed a
+    // project: standing instruction #1, in the one line where it is cheapest.
+    throw new TypeError('resolve() needs a project directory');
+  }
+
+  let root = configured(project);
+  let reason = root ? 'configured' : null;
+
+  if (!root) {
+    for (const name of KNOWN) {
+      if (carriesRegister(path.join(project, name))) {
+        root = name;
+        reason = name === LEGACY ? 'legacy' : 'found';
+        break;
+      }
+    }
+  }
+
+  if (!root) {
+    root = KNOWN[0];
+    reason = 'default';
+  }
+
+  // `leftover` answers "what else carries records here", a different question
+  // from "which root won" — so it is computed the same way whatever chose the root.
+  const leftover = KNOWN.find(
+    (n) => n !== root && carriesRegister(path.join(project, n))
+  ) || null;
+
+  // The default landing on a directory that exists but is not a root: answer,
+  // and say so, so the caller asks instead of writing into it.
+  let collision = false;
+  if (reason === 'default') {
+    const dir = path.join(project, root);
+    collision = fs.existsSync(dir) && !carriesRegister(dir);
+  }
+
+  return { root, reason, legacy: reason === 'legacy', leftover, collision };
+}
+
+module.exports = { resolve, carriesRegister, configured, KNOWN, LEGACY, REGISTERS };
+
+if (require.main === module) {
+  const target = process.argv[2] || process.cwd();
+  process.stdout.write(JSON.stringify(resolve(target)) + '\n');
+}

package/bin/lib/migrate-artifacts.js

@@ -0,0 +1,221 @@
+'use strict';
+/**
+ * `migrate-artifacts` — move a project's paperwork off the legacy root, on request.
+ *
+ * **Nothing calls this on its own.** The resolver supports `docs/superpowers/`
+ * indefinitely and no run warns about it, so a project that never runs this command is
+ * not behind. This exists because `task-pipeline` is published: without it, a project
+ * that WANTS the new name has to do the move by hand and guess what else to touch.
+ *
+ * What it does, and the line it does not cross:
+ *
+ * - **It moves the directory.** That part is mechanical and safe to automate.
+ * - **It does not rewrite your prose.** Files elsewhere in the project that name the
+ *   old path are LISTED, never edited. A command that rewrote arbitrary documents in
+ *   somebody's repository would be deciding, for them, which mentions were a path in
+ *   use and which were a path being discussed — the exact distinction a mechanical
+ *   replace cannot make, and one this pipeline got wrong in its own sweep before
+ *   shipping this file.
+ * - **A partial state is a state, not a fault.** Where both roots exist it moves what
+ *   does not collide and names what does. Nothing is ever overwritten.
+ * - **A configured root is refused, not overridden.** `paths.artifacts` is the
+ *   operator saying where the paperwork goes; moving it would contradict the config
+ *   the resolver is about to read.
+ *
+ * The backup is a mechanism, not a habit: a copy that cannot be taken CANCELS the
+ * move. Copies land under `.task-pipeline/backups/`, and a name already taken in the
+ * same second gets a suffix — two backups inside one second were one backup once, and
+ * the second overwrote the first.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const { resolve, LEGACY, KNOWN } = require('./artifact-root.js');
+
+const NEW = KNOWN[0];
+
+/** Every file under `dir`, repo-relative, posix-separated. */
+function walk(dir, base, out) {
+  out = out || [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) walk(full, base, out);
+    else out.push(path.relative(base, full).split(path.sep).join('/'));
+  }
+  return out;
+}
+
+/** Is this a git work tree? `git mv` keeps the history a rename would drop. */
+function inGitWorkTree(project) {
+  try {
+    execFileSync('git', ['-C', project, 'rev-parse', '--is-inside-work-tree'],
+                 { stdio: ['ignore', 'pipe', 'ignore'] });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Which files elsewhere in the project still name the old path.
+ *
+ * Reported, never rewritten. Skips the artifact roots themselves — a brief written in
+ * March describes where things were in March, and correcting it would falsify the
+ * record it exists to be.
+ */
+function mentionsElsewhere(project) {
+  const hits = [];
+  const skipDirs = new Set(['.git', 'node_modules', 'graphify-out', 'dist', 'build']);
+  const exts = ['.md', '.mdc', '.json', '.yml', '.yaml', '.sh', '.py', '.js', '.ts'];
+  const walkAll = (dir) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (e) { return; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      const rel = path.relative(project, full).split(path.sep).join('/');
+      if (e.isDirectory()) {
+        if (skipDirs.has(e.name)) continue;
+        if (rel === LEGACY || rel === NEW) continue;   // the records themselves
+        walkAll(full);
+      } else if (exts.includes(path.extname(e.name))) {
+        let text;
+        try { text = fs.readFileSync(full, 'utf8'); } catch (err) { continue; }
+        const n = text.split(`${LEGACY}/`).length - 1;
+        if (n) hits.push({ file: rel, count: n });
+      }
+    }
+  };
+  walkAll(project);
+  return hits.sort((a, b) => b.count - a.count);
+}
+
+/**
+ * What the move would do. Pure: reads the tree, writes nothing.
+ *
+ * `moves` are safe; `collisions` are files whose target already exists and which are
+ * therefore left where they are. `mentions` is the list this command refuses to edit.
+ */
+function plan(project) {
+  const info = resolve(project);
+  const legacyAbs = path.join(project, LEGACY);
+
+  if (info.reason === 'configured') {
+    return { action: 'refused', info,
+             why: `pipeline.json sets paths.artifacts to "${info.root}". Moving the `
+                  + 'directory would contradict the config the resolver reads first. '
+                  + 'Change or remove that key first if the move is what you want.' };
+  }
+  if (!fs.existsSync(legacyAbs)) {
+    return { action: 'nothing', info,
+             why: `no ${LEGACY}/ in this project — the root is already "${info.root}".` };
+  }
+
+  const files = walk(legacyAbs, legacyAbs);
+  const moves = [];
+  const collisions = [];
+  for (const rel of files) {
+    const target = path.join(project, NEW, rel);
+    if (fs.existsSync(target)) collisions.push(`${NEW}/${rel}`);
+    else moves.push({ from: `${LEGACY}/${rel}`, to: `${NEW}/${rel}` });
+  }
+  return { action: 'move', info, moves, collisions,
+           mentions: mentionsElsewhere(project) };
+}
+
+/** A preview that shows what LEAVES, not only what arrives. */
+function render(p) {
+  const L = [];
+  if (p.action === 'refused') { L.push(`refused: ${p.why}`); return L.join('\n'); }
+  if (p.action === 'nothing') { L.push(`nothing to do: ${p.why}`); return L.join('\n'); }
+
+  L.push(`artifact root: ${p.info.root}  (${p.info.reason})`);
+  L.push('');
+  L.push(`${p.moves.length} file(s) move:`);
+  for (const m of p.moves) {
+    L.push(`  - ${m.from}`);          // what leaves
+    L.push(`  + ${m.to}`);            // and where it arrives
+  }
+  if (p.collisions.length) {
+    L.push('');
+    L.push(`${p.collisions.length} file(s) NOT moved — the target already exists and `
+           + 'nothing here overwrites:');
+    for (const c of p.collisions) L.push(`  ! ${c}`);
+    L.push(`  ${LEGACY}/ stays in place for these.`);
+  }
+  if (p.mentions.length) {
+    L.push('');
+    L.push(`${p.mentions.length} file(s) elsewhere still name ${LEGACY}/ — `
+           + 'LISTED, NOT EDITED:');
+    for (const m of p.mentions) L.push(`  ? ${m.file}  (${m.count})`);
+    L.push('  Some of those are paths in use and some are sentences about the old');
+    L.push('  name. Only you can tell them apart, so this command will not try.');
+  }
+  return L.join('\n');
+}
+
+/** A copy that cannot be taken cancels the move. Returns the backup directory. */
+function backup(project, stamp) {
+  const dir = path.join(project, '.task-pipeline', 'backups');
+  fs.mkdirSync(dir, { recursive: true });
+  let target = path.join(dir, `artifacts-${stamp}`);
+  let n = 1;
+  // A stamp resolves to the second and an agent moves faster than that: a name
+  // already taken gets a suffix rather than the previous copy's contents.
+  while (fs.existsSync(target)) target = path.join(dir, `artifacts-${stamp}-${++n}`);
+  fs.cpSync(path.join(project, LEGACY), target, { recursive: true });
+  const copied = walk(target, target).length;
+  const wanted = walk(path.join(project, LEGACY), path.join(project, LEGACY)).length;
+  if (copied !== wanted) {
+    throw new Error(`backup incomplete (${copied}/${wanted} files) — move cancelled`);
+  }
+  return target;
+}
+
+/** Do it. Returns `{plan, backupDir, moved}`. */
+function apply(project, opts) {
+  const o = opts || {};
+  const p = plan(project);
+  if (p.action !== 'move') return { plan: p, backupDir: null, moved: 0 };
+
+  // Nothing movable is nothing to do — and a backup taken anyway would make every
+  // repeat run change the tree it claims to leave alone. Found by the three-run
+  // fixture, not by reading: the plan was right and the command that repeats was not,
+  // which is standing instruction #2 arriving in the file that cites it.
+  if (!p.moves.length) return { plan: p, backupDir: null, moved: 0 };
+
+  const backupDir = backup(project, o.stamp || 'unstamped');
+  const git = inGitWorkTree(project);
+  let moved = 0;
+  for (const m of p.moves) {
+    const from = path.join(project, m.from);
+    const to = path.join(project, m.to);
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    if (git) {
+      try {
+        execFileSync('git', ['-C', project, 'mv', m.from, m.to], { stdio: 'ignore' });
+      } catch (e) {
+        fs.renameSync(from, to);      // untracked files git mv refuses
+      }
+    } else {
+      fs.renameSync(from, to);
+    }
+    moved += 1;
+  }
+  // The legacy directory goes only when nothing is left in it — a collision means
+  // records still live there and removing it would delete them.
+  pruneEmpty(path.join(project, LEGACY));
+  return { plan: p, backupDir, moved };
+}
+
+/** Remove empty directories, deepest first. Never removes a directory with content. */
+function pruneEmpty(dir) {
+  if (!fs.existsSync(dir)) return;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.isDirectory()) pruneEmpty(path.join(dir, e.name));
+  }
+  if (!fs.readdirSync(dir).length) fs.rmdirSync(dir);
+}
+
+module.exports = { plan, render, apply, backup, mentionsElsewhere, NEW, LEGACY };

package/bin/task-pipeline.js

@@ -26,6 +26,14 @@ Usage:
                                       into ~/.claude (skip existing unless --force)
   npx task-pipeline-skill --help
 
+  npx task-pipeline-skill migrate-artifacts [--dry-run]
+                                      move this project's paperwork from the legacy
+                                      docs/superpowers/ to docs/evidence/. Optional:
+                                      the legacy name is supported forever and no run
+                                      warns about it. Moves the directory, LISTS every
+                                      other file that names the old path, and edits
+                                      none of them.
+
 Other install paths:
   Claude Code plugin:  /plugin marketplace add ${REPO}
                        /plugin install task-pipeline@task-pipeline
@@ -87,12 +95,62 @@ function offerRouters() {
   }
 }
 
+/**
+ * `migrate-artifacts` — the one verb this installer grew.
+ *
+ * Kept here rather than in a second binary because the package ships one `bin`, and a
+ * project that wants the move should not have to learn a second command name. The work
+ * itself is in `lib/migrate-artifacts.js`, which is pure up to the moment it copies.
+ */
+function migrateArtifacts(args) {
+  const mig = require('./lib/migrate-artifacts.js');
+  const project = process.cwd();
+  const dry = args.includes('--dry-run');
+  const unknown = args.filter((a) => a !== '--dry-run');
+  if (unknown.length) {
+    console.error(`unknown argument(s) for migrate-artifacts: ${unknown.join(' ')}`);
+    return 2;
+  }
+
+  const p = mig.plan(project);
+  console.log(mig.render(p));
+  if (p.action === 'refused') return 3;
+  if (p.action === 'nothing') return 0;
+  if (dry) {
+    console.log('\n--dry-run: nothing was written.');
+    return 0;
+  }
+
+  let r;
+  try {
+    r = mig.apply(project, { stamp: new Date().toISOString().replace(/[:.]/g, '-') });
+  } catch (e) {
+    // A copy that cannot be taken cancels the move, and says so instead of
+    // degrading to "moved anyway".
+    console.error(`\nmove cancelled: ${e.message}`);
+    return 1;
+  }
+  console.log(`\nbackup: ${r.backupDir}`);
+  console.log(`moved:  ${r.moved} file(s)`);
+  if (r.plan.collisions.length) {
+    console.log(`kept:   ${r.plan.collisions.length} file(s) left in `
+                + `${mig.LEGACY}/ — their targets already existed`);
+  }
+  if (r.plan.mentions.length) {
+    console.log(`review: ${r.plan.mentions.length} file(s) still name ${mig.LEGACY}/ `
+                + '— listed above, none edited');
+  }
+  return 0;
+}
+
 function main(argv) {
   const args = argv.slice(2);
   if (args.includes('--help') || args.includes('-h')) {
     usage();
     return 0;
   }
+  if (args[0] === 'migrate-artifacts') return migrateArtifacts(args.slice(1));
+
   const force = args.includes('--force');
   const unknown = args.filter((a) => a !== '--force');
   if (unknown.length) {

package/cursor/rules/task-pipeline.mdc

@@ -96,7 +96,7 @@ ledger. A date is the graph's own reply about itself; the lag is the only part
 that says whether it describes the tree you are about to change. A graph goes stale
 like any other source, and it **points while the code decides** — never the
 tiebreaker.
-**Read `docs/superpowers/retro.md` in full if it exists** — its *standing
+**Read `docs/evidence/retro.md` in full if it exists** — its *standing
 instructions* are what previous runs of this pipeline got wrong in this project, and
 they bind this run (they are capped at ten, so reading them all is cheap). Stamp
 each one the moment it fires: that date is the only evidence behind the
@@ -174,12 +174,12 @@ Seed a **carry-over ledger** next to the brief, append-only. Anything deferred,
 dropped, or left half-done goes in the moment it's said — including implementer
 concerns and non-blocking review findings. **Deferred out loud is forgotten.**
 
-Read **the verification ledger** — `docs/superpowers/verification.md` — and quote how
+Read **the verification ledger** — `docs/evidence/verification.md` — and quote how
 many rows sit at `never`: that is the project's standing exposure, and stage 0 is where
 it is cheapest to look. `never` is a fact, not a failure; the count has no floor and may
 never be given a target.
 
-Read **the board** — `docs/superpowers/backlog.md`, the project's work-list *between*
+Read **the board** — `docs/evidence/backlog.md`, the project's work-list *between*
 runs — and quote its open count in the brief; seed it from the template when absent. Its
 priority is **computed, never assigned**: `prio = sev × blast + age_bonus`, with the
 three inputs in the row so a ranking can be checked rather than trusted, and `age` moving
@@ -342,7 +342,7 @@ not authorize an outward, irreversible action — stage 7 stops and asks.
     `git -C <repo> status --porcelain`, `git -C <repo> log @{u}..HEAD --oneline`.
     The fix is two commands and the second is the one that gets forgotten:
     `git -C <submodule> push`, then `git add <submodule> && git commit`.
-    **The last act is the retrospective** — `docs/superpowers/retro.md`, **one file
+    **The last act is the retrospective** — `docs/evidence/retro.md`, **one file
     per project, not per run**. Every gate above is good at *this* run and blind
     across runs: the same class of failure gets caught, fixed and forgotten five
     times and nothing notices it is the same one. So, in this order —
@@ -352,7 +352,7 @@ not authorize an outward, irreversible action — stage 7 stops and asks.
 
     **0. Resolve the ledger onto the board first.** Every carry-over row still
     `open`, `unresolved`, or homed `backlog` leaves with a `B-NNN` id on
-    `docs/superpowers/backlog.md`, and the ledger row is updated to name it — both
+    `docs/evidence/backlog.md`, and the ledger row is updated to name it — both
     directions, because a pointer to an id nobody issued and a board row traceable to
     nothing are different failures. Then re-derive the board's priorities: `age` moved
     while the run was happening.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.52.0",
+  "version": "1.53.0",
   "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"
@@ -9,8 +9,9 @@
     "test": "python3 test/validate.py",
     "test:negatives": "python3 test/negatives.py",
     "test:probe": "python3 test/probe.py --self-test",
-    "test:all": "python3 test/validate.py && python3 test/negatives.py && npm run test:probe && npm run test:hooks",
-    "test:hooks": "python3 test/release_gate_test.py"
+    "test:all": "python3 test/validate.py && python3 test/negatives.py && npm run test:probe && npm run test:hooks && npm run test:artifacts",
+    "test:hooks": "python3 test/release_gate_test.py",
+    "test:artifacts": "python3 test/artifact_root_test.py && python3 test/migrate_artifacts_test.py"
   },
   "files": [
     "bin",

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 closes with evidence, a work board and a verification ledger that outlive a run, an exposure line naming what shipped unconfirmed, a progress rail computed from the project's own config, a loop guard whose review ceiling measures rather than stops, and stage-3 tracks for what a product does, how it sounds and how it looks. Two modes need no task: `checkup` (what is unverified) and `setup` (audit existing docs). Retro insights can publish upstream as issues, opt-in and redacted.",
-  "version": "1.52.0",
+  "version": "1.53.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"