@tianhai/pi-workflow-kit 2.8.0 → 2.11.0

package/skills/pwk-executing-tasks/scripts/progress.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * The progress file's structural slots, written in one place.
+ *
+ * Every command validates the whole table before touching the file and writes atomically
+ * (a temp file plus a rename), so a refusal leaves the file byte-identical. There is no
+ * bypass flag: the point of the helper is that a hand edit is no longer needed.
+ *
+ * Usage:
+ *   node progress.mjs set --file <progress.md> --phase <value>
+ *   node progress.mjs set-setup --file <progress.md> --value <pending|done|n/a>
+ *   node progress.mjs set-row --file <progress.md> --requirement <n> [--done <glyph>] [--commit <hash>]
+ *   node progress.mjs append-summary --file <progress.md> --requirement <n> --built <text> [--deviated <text>] [--evidence <text>]
+ */
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+
+const DONE_GLYPHS = ["⬜", "🔄", "✅", "❌", "⏭"];
+const SETUP_VALUES = ["pending", "done", "n/a"];
+const PHASE = /^(e2e-written|reviewing|ship-paused|done|implementing \((\d+)\/(\d+)\))$/;
+
+const REQUIREMENT_HEADER = "| # | Done | Requirement | Per-req ceremony | Commit |";
+const SUMMARY_HEADER = "| R# | Requirement | How it was built | Deviated? | Evidence |";
+
+/** Every row of a markdown table, with its line index and its trimmed cells. */
+function tableRows(lines, header) {
+  const start = lines.indexOf(header);
+  if (start === -1) return null;
+  const rows = [];
+  for (let i = start + 2; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (!line.startsWith("|")) break;
+    rows.push({
+      index: i,
+      // Split on unescaped pipes only, so prose the helper escaped as \| survives a reparse.
+      cells: line
+        .split(/(?<!\\)\|/)
+        .slice(1, -1)
+        .map((cell) => cell.trim()),
+    });
+  }
+  return rows;
+}
+
+function fail(message) {
+  console.error(`progress.mjs: ${message}`);
+  process.exit(1);
+}
+
+/** Parse and validate the whole file before any command runs. */
+function load(filePath) {
+  let text;
+  try {
+    text = readFileSync(filePath, "utf8");
+  } catch (error) {
+    fail(`cannot read ${filePath}: ${error.message}`);
+  }
+  const lines = text.split("\n");
+  const phaseIndex = lines.findIndex((line) => line.startsWith("Feature phase:"));
+  if (phaseIndex === -1) fail(`${filePath}: no Feature phase line`);
+  const setupIndex = lines.findIndex((line) => line.startsWith("Setup:"));
+  if (setupIndex === -1) fail(`${filePath}: no Setup line`);
+  const lastUpdatedIndex = lines.findIndex((line) => line.startsWith("Last updated:"));
+  if (lastUpdatedIndex === -1) fail(`${filePath}: no Last updated line`);
+  const requirements = tableRows(lines, REQUIREMENT_HEADER);
+  if (!requirements) fail(`${filePath}: no Requirements table with its header row`);
+  const summary = tableRows(lines, SUMMARY_HEADER);
+  if (!summary) fail(`${filePath}: no Execution summary table with its header row`);
+  for (const row of requirements) {
+    if (row.cells.length !== 5) {
+      fail(`${filePath}: line ${row.index + 1} is not a five-cell requirement row`);
+    }
+  }
+  for (const row of summary) {
+    if (row.cells.length !== 5) {
+      fail(`${filePath}: line ${row.index + 1} is not a five-cell summary row`);
+    }
+  }
+  return { filePath, lines, phaseIndex, setupIndex, lastUpdatedIndex, requirements, summary };
+}
+
+const findRow = (rows, requirement, filePath, label) => {
+  const row = rows.find((candidate) => candidate.cells[0] === String(requirement));
+  if (!row) fail(`${filePath}: no ${label} row for requirement ${requirement}`);
+  return row;
+};
+
+const requirementRow = (cells) => `| ${cells.join(" | ")} |`;
+const stamp = () => new Date().toISOString();
+
+function save(state) {
+  state.lines[state.lastUpdatedIndex] = `Last updated: ${stamp()}`;
+  const temporary = `${state.filePath}.tmp`;
+  writeFileSync(temporary, state.lines.join("\n"));
+  renameSync(temporary, state.filePath);
+}
+
+const { values, positionals } = (() => {
+  try {
+    return parseArgs({
+      args: process.argv.slice(2),
+      allowPositionals: true,
+      options: {
+        file: { type: "string" },
+        phase: { type: "string" },
+        value: { type: "string" },
+        requirement: { type: "string" },
+        done: { type: "string" },
+        commit: { type: "string" },
+        built: { type: "string" },
+        deviated: { type: "string" },
+        evidence: { type: "string" },
+      },
+    });
+  } catch (error) {
+    fail(error.message);
+  }
+})();
+
+const command = positionals[0];
+if (!command || !values.file) {
+  fail("usage: progress.mjs <set|set-setup|set-row|append-summary> --file <progress.md> …");
+}
+const state = load(values.file);
+
+if (command === "set") {
+  const phase = values.phase ?? "";
+  const match = PHASE.exec(phase);
+  if (!match) {
+    fail(
+      `${values.file}: phase "${phase}" is not one of e2e-written, implementing (k/N), reviewing, ship-paused, done`,
+    );
+  }
+  if (match[2] !== undefined && Number(match[2]) > Number(match[3])) {
+    fail(
+      `${values.file}: phase "implementing (${match[2]}/${match[3]})" requires k <= N — accepted: e2e-written, implementing (k/N), reviewing, ship-paused, done`,
+    );
+  }
+  state.lines[state.phaseIndex] = `Feature phase: ${phase}`;
+} else if (command === "set-setup") {
+  const value = values.value ?? "";
+  if (!SETUP_VALUES.includes(value)) {
+    fail(`${values.file}: setup "${value}" is not one of ${SETUP_VALUES.join(", ")}`);
+  }
+  state.lines[state.setupIndex] = `Setup: ${value}`;
+} else if (command === "set-row") {
+  const row = findRow(state.requirements, values.requirement, values.file, "requirement");
+  const cells = [...row.cells];
+  if (values.done !== undefined) {
+    if (!DONE_GLYPHS.includes(values.done)) {
+      fail(`${values.file}: done "${values.done}" is not one of ${DONE_GLYPHS.join(" ")}`);
+    }
+    cells[1] = values.done;
+  }
+  if (values.commit !== undefined) {
+    const existing = cells[4] === "—" ? "" : cells[4];
+    const recorded = existing.split(/\s+/).filter(Boolean);
+    if (recorded.includes(values.commit)) fail(`${values.file}: commit ${values.commit} is already recorded`);
+    cells[4] = [...recorded, values.commit].join(" ");
+  }
+  state.lines[row.index] = requirementRow(cells);
+} else if (command === "append-summary") {
+  const row = findRow(state.summary, values.requirement, values.file, "execution summary");
+  const [, , built, deviated, evidence] = row.cells;
+  if (built || deviated || evidence) {
+    fail(`${values.file}: requirement ${values.requirement} already has an execution summary`);
+  }
+  const cellText = (text) => String(text ?? "—").replace(/\|/g, "\\|");
+  state.lines[row.index] = requirementRow([
+    row.cells[0],
+    row.cells[1],
+    cellText(values.built),
+    cellText(values.deviated),
+    cellText(values.evidence),
+  ]);
+} else {
+  fail(`unknown command "${command}"`);
+}
+
+save(state);

package/skills/pwk-executing-tasks/scripts/ref.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Print one anchored section of a reference file, so a step loads the section it needs
+ * instead of the whole document.
+ *
+ * The anchor is the heading slug: lowercased, spaces to dashes, punctuation dropped.
+ * The section runs from its heading to the next heading of the same or higher level.
+ *
+ * Usage: node ref.mjs <reference-path>#<anchor>
+ */
+import { readFileSync } from "node:fs";
+
+const HEADING = /^(#{1,6})\s+(.+?)\s*$/;
+
+/** The heading slug a markdown link anchor is written against. */
+export function slug(heading) {
+  return heading
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s-]/gu, "")
+    .trim()
+    .replace(/\s+/g, "-");
+}
+
+/** Every heading in a document, with its level, slug, and line index. */
+export function headings(lines) {
+  const found = [];
+  for (const [index, line] of lines.entries()) {
+    const match = HEADING.exec(line);
+    if (match) found.push({ index, level: match[1].length, slug: slug(match[2]), text: match[2] });
+  }
+  return found;
+}
+
+export function section(lines, anchor) {
+  const all = headings(lines);
+  const start = all.find((heading) => heading.slug === anchor);
+  if (!start) return null;
+  const next = all.find((heading) => heading.index > start.index && heading.level <= start.level);
+  const body = lines.slice(start.index, next ? next.index : lines.length);
+  while (body.length && body[body.length - 1].trim() === "") body.pop();
+  return { text: body.join("\n"), available: all.map((heading) => heading.slug) };
+}
+
+function fail(message) {
+  console.error(`ref.mjs: ${message}`);
+  process.exit(1);
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+  const target = process.argv[2];
+  if (!target) fail("usage: ref.mjs <reference-path>#<anchor>");
+  const hash = target.lastIndexOf("#");
+  if (hash === -1 || hash === target.length - 1) fail(`${target}: pass an anchor, as <reference-path>#<anchor>`);
+  const path = target.slice(0, hash);
+  const anchor = target.slice(hash + 1);
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (error) {
+    fail(`cannot read ${path}: ${error.message}`);
+  }
+  const found = section(text.split("\n"), anchor);
+  if (!found) {
+    const available =
+      headings(text.split("\n"))
+        .map((heading) => heading.slug)
+        .join(", ") || "(none)";
+    fail(`${path}: no heading matches "#${anchor}" — available: ${available}`);
+  }
+  console.log(found.text);
+}

package/skills/pwk-executing-tasks/scripts/stage-check.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Fail when the working tree holds changes outside the plan folder.
+ *
+ * The reviewed diff is a commit range, so anything uncommitted outside docs/plans/ is
+ * invisible to the review and can ship unreviewed. The plan folder is exempt: the design,
+ * the progress file, and the generated packet are legitimately dirty while a step is in
+ * flight. A root that cannot be verified is a failure, never a silent pass.
+ *
+ * Usage: node stage-check.mjs [root]
+ */
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+
+const ALLOWED = "docs/plans/";
+const root = resolve(process.argv[2] ?? process.cwd());
+
+const probe = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: root, encoding: "utf8" });
+if (probe.status !== 0 || probe.stdout.trim() !== "true") {
+  console.error(`stage-check.mjs: ${root} is not a git worktree — nothing can be verified`);
+  process.exit(1);
+}
+
+// -uall: git otherwise collapses an untracked directory to "dir/", and the point of the
+// failure is to name the file that would miss the reviewed diff.
+const status = spawnSync("git", ["status", "--porcelain", "--untracked-files=all"], { cwd: root, encoding: "utf8" });
+if (status.status !== 0) {
+  console.error(`stage-check.mjs: git status failed in ${root}: ${status.stderr.trim()}`);
+  process.exit(1);
+}
+
+const unquote = (path) => path.replace(/^"(.*)"$/, "$1");
+const offenders = [];
+for (const line of status.stdout.split("\n")) {
+  if (!line.trim()) continue;
+  const entry = unquote(line.slice(3).trim());
+  const path = entry.includes(" -> ") ? entry.split(" -> ").at(-1).trim() : entry;
+  if (!path.startsWith(ALLOWED)) offenders.push(path);
+}
+
+if (offenders.length) {
+  for (const path of offenders) console.error(`stage-check.mjs: uncommitted outside ${ALLOWED} — ${path}`);
+  console.error(
+    `stage-check.mjs: ${offenders.length} path(s) would be missing from the reviewed diff; commit or remove them first`,
+  );
+  process.exit(1);
+}
+console.log(`stage-check.mjs: nothing uncommitted outside ${ALLOWED}`);

package/skills/pwk-finalizing/SKILL.md

@@ -7,35 +7,44 @@ description: "Use after all requirements are complete to archive or delete consu
 
 Ship the completed work.
 
-Any command or tool recipe in this skill is an example, not the requirement — when your host grants a better tool for an operation (a sandboxed batch executor, a structured file API), use the better tool and treat the recipe as a fallback; the only exact exceptions are this kit's `scripts/` helpers and plain `git` invocations, whose deterministic output is the point.
+Any command or tool recipe in this skill is an example, not the requirement — when your host grants a better tool for an operation (a sandboxed batch executor — e.g. `codemode` on pi ≥ 1.0.0 — a structured file API), use the better tool and treat the recipe as a fallback; the only exact exceptions are this kit's `scripts/` helpers and plain `git` invocations, whose deterministic output is the point.
 
 ## Pre-finalization checks
 
 1. **Verify the repo root** — run `pwd` (or your shell's equivalent) and `git rev-parse --show-toplevel`; mismatch → report both paths and stop; never `cd` (a worktree root counts).
-2. **Run the FULL test suite** — every test must pass, and only a green suite ships. Resume spans sessions; re-run the suite yourself rather than trust the previous session's ending state. Anything failing → send the user back to `/skill:pwk-executing-tasks`.
-3. Read **every** relevant progress file — for a multi-leaf topic that's each leaf's progress file — discovered by listing `docs/plans` recursively, excluding docs/plans/completed/, for `*-progress.md` (topic docs live in `docs/plans/<date>-<topic>/` folders — archived work is not in flight). Use whatever recurses in your harness; one example: `find docs/plans -name '<suffix>' -not -path '*/completed/*'`. More than one topic in flight? Ask which one this finalize ships — finalizing touches only its own topic, and another topic still being designed or executed never blocks this run. Then match, in the chosen topic's file(s), the `Feature phase:` line (e.g. `grep -m1 '^Feature phase:' <file>`) and read only the matching ❌/⏭ verdict rows in the Requirements table (e.g. `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep '^| [0-9].*❌'` / `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep '^| [0-9].*⏭'` — scoped to Requirements-table rows because the Execution summary rows share the same row shape, with reasons); the sections after the tables carry nothing the gate needs. Apply the gates below to the chosen topic's file(s) and no others:
-   - **Any `❌ failed`** (in any leaf of the topic) → **block**. Present counts and reasons; continue only when the user sends the task back to executing-tasks, or explicitly types `--force-failed` to acknowledge shipping with incomplete requirements.
+2. **Run the FULL test suite** — only a green suite ships; re-run it yourself rather than trusting the previous session's ending state. Anything failing → send the user back to `/skill:pwk-executing-tasks`.
+3. Read **every** relevant progress file — for a multi-leaf topic that's each leaf's progress file — discovered by listing `docs/plans` recursively, excluding docs/plans/completed/, for `*-progress.md` (topic docs live in `docs/plans/<date>-<topic>/` folders — archived work is not in flight). Use whatever recurses in your harness; one example: `find docs/plans -name '<suffix>' -not -path '*/completed/*'`. With a sandboxed batch executor (e.g. `codemode` on pi ≥ 1.0.0) the listing and every topic’s `Feature phase:` extraction are one call, returning only the summary lines (adapt the paths to the verified root when your cwd differs):
+
+   ```javascript
+   const designs = (await tools.bash({ command: "find docs/plans -name '*-design.md' -not -path '*/completed/*' | sort", timeout: 15 })).output.trim();
+   const files = designs ? designs.split('\n') : [];
+   const shellq = (s) => "'" + s.replace(/'/g, "'\\''") + "'";
+   const heads = await Promise.all(files.map(d =>
+     tools.bash({ command: "grep -m1 '^Feature phase:' " + shellq(d.replace('-design.md', '-progress.md')), timeout: 15 }).then(r => r.output.trim() || 'design')));
+   return text(files.map((d, i) => d + ' — ' + heads[i]).join('\n') || 'no in-flight topics');
+   ```
+
+   More than one topic in flight? Ask which one this finalize ships — finalizing touches only its own topic, and another topic being designed or executed never blocks this run. Then match the chosen topic's `Feature phase:` line (e.g. `grep -m1 '^Feature phase:' <file>`) and read only its ❌/⏭ verdict rows in the Requirements table (e.g. `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep '^| [0-9].*❌'` / `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep '^| [0-9].*⏭'` — scoped to Requirements-table rows because the Execution summary rows share the same row shape); the sections after the tables carry nothing the gate needs. Apply the gates below to the chosen topic's file(s) and no others:
+   - **Any `❌ failed`** (in any leaf of the topic) → **block**. Present counts and reasons; continue only when the user sends the task back to executing-tasks, or explicitly types `--force-failed`.
    - **Only `⏭ skipped`** → warn and confirm ("Requirement N was skipped. Continue, or go back?").
-   - **`Feature phase` must be `done`** in every progress file of the topic — any other value (`e2e-written`, `implementing (k/N)`, `reviewing`, `ship-paused`) means that topic is still in flight: its ship checkpoint has not been approved. Send the user back to `/skill:pwk-executing-tasks` instead of finalizing.
-4. **Cross-check the roster — fail closed on unstarted work.** Find the topic folder locally: the progress file's `Design:` ref names the design doc, and that directory is the topic folder. An `overview.md` **beside the design doc** (same folder — never a repo-wide `docs/plans/**/overview.md`, or a sibling topic's overview would route this finalize) means a multi-leaf topic. Read that overview's `## Parts (build order)` roster and require one `<leaf>-progress.md` per leaf. A roster leaf with no progress file is **unstarted** — **block**, naming the leaf, and send the user back to `/skill:pwk-executing-tasks` to build it; never dispose an unstarted design unread. (A leaf with a progress file that is not `done` is already stopped by the gate above.)
+   - **`Feature phase` must be `done`** in every progress file of the topic — any other value (`e2e-written`, `implementing (k/N)`, `reviewing`, `ship-paused`) means its ship checkpoint has not been approved: send the user back to `/skill:pwk-executing-tasks` instead of finalizing.
+4. **Cross-check the roster — fail closed on unstarted work.** The progress file's `Design:` ref names the design doc, and that directory is the topic folder. An `overview.md` **beside the design doc** (same folder — never a repo-wide `docs/plans/**/overview.md`) means a multi-leaf topic: read that overview's `## Parts (build order)` roster and require one `<leaf>-progress.md` per leaf. A roster leaf with no progress file is **unstarted** — **block**, naming the leaf, and send the user back to `/skill:pwk-executing-tasks` to build it; never dispose an unstarted design unread. (A leaf whose progress file is not `done` is already stopped by the gate above.)
 
 ## Process
 
 1. **Derive the topic set** —
-   - **Multi-leaf topic** (an `overview.md` sits beside the design doc, inside the same `docs/plans/<date>-<topic>/` folder — never a repo-wide `docs/plans/**/overview.md`, and always excluding docs/plans/completed/, so an archived or sibling topic never routes): read its roster; the set is the topic folder itself, disposed as one unit.
+   - **Multi-leaf topic** (an `overview.md` beside the design doc, inside the same `docs/plans/<date>-<topic>/` folder — never a repo-wide `docs/plans/**/overview.md`, and always excluding docs/plans/completed/, so an archived or sibling topic never routes): the set is the topic folder itself, disposed as one unit.
    - **Single-leaf topic**: progress file → `Design:` ref → that design doc's own folder → `<topic>`, which **is the folder slug** — the topic directory's name, and the same value `pwk-executing-tasks` uses for the branch and worktree (never a leaf filename). One folder.
 
    Ambiguous with several designs in flight? Ask.
-2. **Run the learning sweep — before any disposal command.** The planning docs are about to be destroyed; extract the durable knowledge first, while its container still exists. Read each design doc's At-a-glance key-decision bullets **and its `Approaches considered` section** (the full forks with their reasoning — every leaf's, for an umbrella), each progress file's `Deviated?` entries (including any deviation decision-records), and each Code digest's `[ALERT]` entries. (A trivial doc has no `## At a glance` and no `Approaches considered` — a trivial slice's sweep is expected to come up honest-empty.) Then:
-   - **Offer an ADR** (in `docs/adr/`) for each item that passes the three gates — **hard to reverse**, **surprising without context**, **a real trade-off** — informed by how the decision actually played out during execution, not just how it looked at design time.
+2. **Run the learning sweep — before any disposal command.** The planning docs are about to be destroyed, so extract the durable knowledge first, while its container still exists: each design doc's At-a-glance key-decision bullets **and its `Approaches considered` section** (every leaf's, for an umbrella), each progress file's `Deviated?` entries, and each Code digest's `[ALERT]` entries. (A trivial doc has no `## At a glance` and no `Approaches considered` — expect an honest-empty sweep.) Then:
+   - **Offer an ADR** (in `docs/adr/`) for each item that passes the three gates — **hard to reverse**, **surprising without context**, **a real trade-off**.
    - **Append generic rules** to `docs/lessons.md` (strip domain specifics).
-   - Both outputs are **honest-empty**: most features qualify for nothing — say so and move on; never manufacture. When an item passes the gates but the recorded material is too thin to draft a credible ADR, **ask the human rather than fabricating** context — the human was there.
-   - The sweep is file-based by necessity: executing and finalizing usually run in fresh sessions with no memory of the brainstorm conversation — everything the sweep needs must already be on disk.
-3. **Dispose of consumed plan docs — ask archive or delete** — for **every topic** in the set, dispose its topic folder `docs/plans/<date>-<topic>/` **as one unit**: every leaf's `-design.md`, `-progress.md`, and `-review-packet*.md`, plus `overview.md` for an umbrella. The digest sections (`## At a glance`, `## Execution summary`) live inside their host docs and ride the folder — no separate disposal. The folder path is taken verbatim from discovery, and the `????-??-??-` dated shape is the topic's identity — a bare `*<topic>*` pattern would over-match unrelated topics. Present both options and let the human choose:
+   - Both outputs are **honest-empty**: most features qualify for nothing — say so and move on; never manufacture. When an item passes the gates but the recorded material is too thin for a credible ADR, **ask the human rather than fabricating**.
+   - The sweep is file-based by necessity: executing and finalizing usually run in fresh sessions with no memory of the brainstorm, so everything the sweep needs must already be on disk.
+3. **Dispose of consumed plan docs — ask archive or delete** — for **every topic** in the set, dispose its topic folder `docs/plans/<date>-<topic>/` **as one unit**: every leaf's `-design.md`, `-progress.md`, and `-review-packet*.md`, plus `overview.md` for an umbrella. The digest sections and the Evidence cells live inside their host docs and ride the folder. The folder path is taken verbatim from discovery, and the `????-??-??-` dated shape is the topic's identity — a bare `*<topic>*` pattern would over-match unrelated topics. Present both options and let the human choose:
 
-   - **Delete (default)** — code + tests are the source of truth; removing the scaffold prevents stale plan docs from misleading future sessions:
-
-     The invariant: the topic folder `docs/plans/<date>-<topic>/` is the disposal unit — delete it entirely, nothing more and nothing less; any single operation achieving exactly this is correct, and the bash below is one canonical example.
+   - **Delete (default)** — code + tests are the source of truth; removing the scaffold prevents stale plan docs from misleading future sessions. The invariant: the topic folder is the disposal unit — delete it entirely, nothing more and nothing less; any single operation achieving exactly this is correct, and the bash below is one canonical example.
 
      ```bash
      # the topic folder goes as one unit (every leaf, plus overview.md if it has one).
@@ -47,9 +56,7 @@ Any command or tool recipe in this skill is an example, not the requirement —
      # uncommitted drafts never ride the disposal commit.
      ```
 
-   - **Archive** — keep the planning history for future readers (e.g. a complex design worth preserving) by moving the artifacts into `docs/plans/completed/`:
-
-     The invariant: the topic folder `docs/plans/<date>-<topic>/` moves whole into `docs/plans/completed/` and the destination is verified before committing; any single operation achieving exactly this is correct, and the bash below is one canonical example.
+   - **Archive** — keep the planning history for future readers by moving the artifacts into `docs/plans/completed/`. The invariant: the topic folder moves whole into `docs/plans/completed/` and the destination is verified before committing; any single operation achieving exactly this is correct, and the bash below is one canonical example.
 
      ```bash
      mkdir -p docs/plans/completed
@@ -64,23 +71,17 @@ Any command or tool recipe in this skill is an example, not the requirement —
      git add -A docs/plans/<date>-<topic>/ docs/plans/completed/ && git commit -m "chore: archive planning docs for <topic>"
      ```
 
-   Verify with `ls docs/plans/` before and after. Both paths commit the disposal so the shipped branch is clean. Neither path touches `docs/adr/`, `docs/lessons.md`, `CHANGELOG.md`, or `README.md` — those are permanent.
-4. **Curate lessons (Agile Scrum Master hat)** — if `docs/lessons.md` exists: add missed lessons, generalize domain-specific rules into generic patterns, de-duplicate, categorize, retire stale rules. None exists but lessons were learned? Create it. (The learning sweep above feeds this; curation then shapes the whole file.)
+   Verify with `ls docs/plans/` before and after. Both paths commit the disposal so the shipped branch is clean. Neither touches `docs/adr/`, `docs/lessons.md`, `CHANGELOG.md`, or `README.md` — those are permanent.
+4. **Curate lessons (Agile Scrum Master hat)** — if `docs/lessons.md` exists: add missed lessons, generalize domain-specific rules, de-duplicate, categorize, retire stale rules. None exists but lessons were learned? Create it. (The learning sweep feeds this; curation then shapes the whole file.)
 5. **Update documentation** — if the API or surface changed: `README.md`, `CHANGELOG.md`, any inline docs. Bump the package version (major for breaking changes).
-6. **Choose a merge strategy** — ask the human:
+6. **Choose a merge strategy** — ask the human: 1. **Create PR** (`git push origin <branch>` then `gh pr create`). 2. **Rebase & merge** *(recommended)* — rebase onto parent, `--ff-only` merge, push parent, delete branch. 3. **Squash & merge**. 4. **Merge commit** (`--no-ff`).
 
-   1. **Create PR** — `git push origin <branch>` then `gh pr create`.
-   2. **Rebase & merge** *(recommended)* — rebase onto parent, `--ff-only` merge, push parent, delete branch.
-   3. **Squash & merge** — squash onto parent, push, delete branch.
-   4. **Merge commit** — `--no-ff` merge, push parent, delete branch.
-
-   For 2–4, confirm the detected parent branch before proceeding. When a worktree was used, the parent-side commands (merge onto parent, push parent, branch deletion) run from the main working tree — the topic worktree holds the feature-branch checkout, so the parent cannot be checked out there (`git -C ../<repo> …` drives the main side without moving the session; the root check's never-cd rule still holds) — and step 7's worktree removal comes **first**: a branch checked out in a worktree cannot be deleted.
-7. **Clean up** — if a worktree was used, verify presence first (`git worktree list`): when the topic's worktree exists, remove it (`git worktree remove ../<repo>-<topic>`, where `<topic>` is the folder slug — the same one `pwk-executing-tasks` created the branch under, never a leaf slug). The `../` path is written from the main working tree, and the removal runs from there — `git -C ../<repo> worktree remove ../<repo>-<topic>` when the session stands inside the worktree, which git refuses to remove under itself. When absent, cleanup is a silent no-op — never a failure.
+   For 2–4, confirm the detected parent branch first. When a worktree was used, the parent-side commands (merge onto parent, push parent, branch deletion) run from the main working tree — the worktree holds the feature branch, so the parent cannot be checked out there (`git -C ../<repo> …`; the never-cd rule still holds) — and step 7's worktree removal comes **first**: a branch checked out in a worktree cannot be deleted.
+7. **Clean up** — if a worktree was used, check `git worktree list` first: when the topic's worktree exists, remove it (`git worktree remove ../<repo>-<topic>`, `<topic>` being the folder slug, never a leaf slug) from the main working tree — `git -C ../<repo> worktree remove ../<repo>-<topic>` when the session stands inside the worktree, which git refuses to remove under itself. Absent → a silent no-op, never a failure.
 
 ## Principles
 
 - The learning sweep runs before disposal and touches only `docs/adr/` and `docs/lessons.md` — the two permanent stores.
-
-- Dispose of the active work's artifacts only (archive or delete, the human's choice) — the unit is the topic folder `docs/plans/<date>-<topic>/`, one folder whether the topic has a single leaf or an umbrella's many. Unrelated topics stay in `docs/plans/`.
-- ADRs are permanent institutional memory — they stay out of archive/rotation forever.
-- Bump the package version if this is a published change (major for breaking changes).
+- Dispose of the active work's artifacts only, the human's choice — the unit is the topic folder `docs/plans/<date>-<topic>/`, one folder whether a single leaf or an umbrella's many. Unrelated topics stay in `docs/plans/`.
+- ADRs are permanent institutional memory — never archived or rotated.
+- Bump the package version if this is a published change (major for breaking changes).

package/skills/pwk-status/SKILL.md

@@ -5,24 +5,34 @@ description: "Show all active pipeline topics and their phase/progress. Use when
 
 # Status
 
-Report on in-flight pipelines in this working tree (a worktree has its own `docs/plans/`, so run status in each). Read-only. This skill **does not unlock the guard** — it needs no writes, so it runs fine inside the design read-only phase. If you want source edits after a status check, invoke the skill for the next phase yourself (the guard follows the skill).
+Report on in-flight pipelines in this working tree (a worktree has its own `docs/plans/`, so run status in each). Read-only: this skill **does not unlock the guard**, so it runs fine inside the design read-only phase — invoke the next phase's skill yourself if you want source edits (the guard follows the skill).
 
-Any command or tool recipe in this skill is an example, not the requirement — when your host grants a better tool for an operation (a sandboxed batch executor, a structured file API), use the better tool and treat the recipe as a fallback; the only exact exceptions are this kit's `scripts/` helpers and plain `git` invocations, whose deterministic output is the point.
+Any command or tool recipe in this skill is an example, not the requirement — when your host grants a better tool for an operation (a sandboxed batch executor — e.g. `codemode` on pi ≥ 1.0.0 — a structured file API), use the better tool and treat the recipe as a fallback; the only exact exceptions are this kit's `scripts/` helpers and plain `git` invocations, whose deterministic output is the point.
 
 ## Process
 
 0. **Verify the root** — run `pwd` (or your shell's equivalent) and `git rev-parse --show-toplevel`; mismatch → report both paths and stop; never `cd` (a worktree root counts).
-1. **Discover** — List `docs/plans` recursively, excluding docs/plans/completed/, for `*-design.md`, `*-progress.md`, and `overview.md` (topic docs live in `docs/plans/<date>-<topic>/` folders — archived work is not in flight) — this working tree only. Use whatever recurses in your harness; one example: `find docs/plans -name '<suffix>' -not -path '*/completed/*'`.
-2. **State per topic/part — extract, never ingest.** For each progress file take the `Feature phase:` line by matching it (e.g. `grep -m1 '^Feature phase:' <file>` — wherever the template puts it); the body (execution summary, review reports, code digest) carries nothing status needs, and neither do design docs. A header reading `Setup: pending` renders the topic as **`awaiting setup`** — the setup checkpoint was never approved (the slot is only ever written when the design doc has a `## Setup` section, so the header alone decides — no design-doc read) — ahead of any phase-derived state below. Map the line to the displayed state:
-   - `done` → **`done`** — terminal, never shown as in-flight; every row is resolved (`✅` passed, `❌` failed, `⏭` skipped — resolved, not necessarily passed). Append the tally as `N/N` when wanted — the Requirements-table row count, scoped to that table because the Execution summary rows share the same `| <n> |` row shape and a bare grep would double it (e.g. `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep -c '^| [0-9]'`) — and when that same scoped range finds any — `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep -c '^| [0-9].*❌'` / `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep -c '^| [0-9].*⏭'` (the same scoping, so Execution-summary rows — which share the row shape — and prose mentions of the glyphs do not inflate the count) — render the counts, e.g. `done (1 ❌ · 1 ⏭)`, noting finalizing will require `--force-failed` while `❌` rows stand
+1. **Discover** — List `docs/plans` recursively, excluding docs/plans/completed/, for `*-design.md`, `*-progress.md`, and `overview.md` (topic docs live in `docs/plans/<date>-<topic>/` folders — archived work is not in flight) — this working tree only; take each topic’s `Feature phase:` line header-only (`grep -m1 '^Feature phase:' <file>`). Use whatever recurses in your harness; one example: `find docs/plans -name '<suffix>' -not -path '*/completed/*'`. With a sandboxed batch executor (e.g. `codemode` on pi ≥ 1.0.0) the listing and every phase extraction are one call, returning only the summary lines (adapt the paths to the verified root when your cwd differs):
+
+   ```javascript
+   const designs = (await tools.bash({ command: "find docs/plans -name '*-design.md' -not -path '*/completed/*' | sort", timeout: 15 })).output.trim();
+   const files = designs ? designs.split('\n') : [];
+   const shellq = (s) => "'" + s.replace(/'/g, "'\\''") + "'";
+   const heads = await Promise.all(files.map(d =>
+     tools.bash({ command: "grep -m1 '^Feature phase:' " + shellq(d.replace('-design.md', '-progress.md')), timeout: 15 }).then(r => r.output.trim() || 'design')));
+   return text(files.map((d, i) => d + ' — ' + heads[i]).join('\n') || 'no in-flight topics');
+   ```
+
+2. **State per topic/part — map the header.** The body (execution summary, review reports, code digest) carries nothing status needs, and neither do design docs. A header reading `Setup: pending` renders the topic as **`awaiting setup`** — the setup checkpoint was never approved (the slot is only ever written when the design doc has a `## Setup` section, so the header alone decides — no design-doc read) — ahead of any phase-derived state below. Map the line to the displayed state:
+   - `done` → **`done`** — terminal, never shown as in-flight; every row is resolved (`✅` passed, `❌` failed, `⏭` skipped — resolved, not necessarily passed). Append the tally as `N/N` when wanted — the Requirements-table row count, scoped to that table because the Execution summary rows share the same `| <n> |` row shape and a bare grep would double it (e.g. `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep -c '^| [0-9]'`). Counting `❌`/`⏭` rows over that same scoped range (`sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep -c '^| [0-9].*❌'` / `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep -c '^| [0-9].*⏭'` — the same scoping, so Execution-summary rows and prose mentions of the glyphs do not inflate the count) renders the counts, e.g. `done (1 ❌ · 1 ⏭)`, noting finalizing will require `--force-failed` while `❌` rows stand
    - `implementing (k/N)` → `execute k/N` (the tally rides on the line itself — no extra read)
    - `e2e-written` → `execute 0/N` (the E2E is written and the run continues into implementation — never shown as a paused state; N comes from the same Requirements-table-scoped row count as `done` — so no tally renders without a defined source)
    - `reviewing` → `review`
-   - `ship-paused` → `ship-paused` — next: `/skill:pwk-executing-tasks` (approve the ship checkpoint). Never hint finalizing: only `done` routes there.
+   - `ship-paused` → `ship-paused` — next: `/skill:pwk-executing-tasks` (approve the ship checkpoint); only `done` routes to finalizing.
    - no progress file, only `*-design.md` → `design` — next: `/skill:pwk-executing-tasks`
    - roster-only (named in the overview, no artifacts) → `not started`
    - no parseable `Feature phase` line → `execute` (with tally if parseable).
-3. **Group by umbrella** — for each `overview.md`, read its **`## Parts (build order)`** roster (the heading and the `N. <part> — <scope>` item shape are lint-pinned) and roll the parts up by state (the overview carries no status): done parts, in-flight parts (design, execute, review, ship-paused, awaiting setup), not-started parts. A part sitting at the feature-E2E notice (`e2e-written`) rolls up as execute — the notice is a routing moment, not a bucket of its own. Print one roll-up line — `<topic> (umbrella): n done · n in-flight · n not-started` — and when every part is `done` append `— all parts done, ready for /skill:pwk-finalizing`. A `done` single-leaf topic gets the same hint. Once the topic finalizes, its folder — overview included — is disposed, so it no longer appears here. Topics without an overview print flat.
+3. **Group by umbrella** — for each `overview.md`, read its **`## Parts (build order)`** roster (the heading and the `N. <part> — <scope>` item shape are lint-pinned) and roll the parts up by state (the overview carries no status): done, in-flight (design, execute, review, ship-paused, awaiting setup), not-started. A part at the feature-E2E notice (`e2e-written`) rolls up as execute — a routing moment, not a bucket of its own. Print one roll-up line — `<topic> (umbrella): n done · n in-flight · n not-started` — and when every part is `done` append `— all parts done, ready for /skill:pwk-finalizing`; a `done` single-leaf topic gets the same hint. Once the topic finalizes its folder — overview included — is disposed, so it no longer appears here. Topics without an overview print flat.
 4. Print a compact table, grouped under any umbrellas, e.g.:
 
    ```text

package/skills/pwk-walkthrough/SKILL.md

@@ -7,7 +7,7 @@ description: "Generate a detailed, file-referenced walkthrough of a shipped feat
 
 Explain a shipped feature in code-level detail, for a human reading with the files open.
 
-Any command or tool recipe in this skill is an example, not the requirement — when your host grants a better tool for an operation (a sandboxed batch executor, a structured file API), use the better tool and treat the recipe as a fallback; the only exact exceptions are this kit's `scripts/` helpers and plain `git` invocations, whose deterministic output is the point.
+Any command or tool recipe in this skill is an example, not the requirement — when your host grants a better tool for an operation (a sandboxed batch executor — e.g. `codemode` on pi ≥ 1.0.0 — a structured file API), use the better tool and treat the recipe as a fallback; the only exact exceptions are this kit's `scripts/` helpers and plain `git` invocations, whose deterministic output is the point.
 
 **Not a pipeline phase** — never auto-run, never blocks anything. The skill is generated on demand and invoking it exits any gated design phase (it writes outside `docs/plans/`).