@tianhai/pi-workflow-kit 2.8.0 → 2.11.0

package/skills/pwk-executing-tasks/references/progress-format.md

@@ -2,7 +2,7 @@
 
 Read before creating or changing progress rows, or writing/re-presenting the code digest. This reference owns the unchanged progress artifact schema.
 
-2. **Create the progress file** `docs/plans/<date>-<topic>/<leaf>-progress.md`, beside the design doc it belongs to (`<leaf>` is `<topic>` for a single-part topic; an umbrella part uses its roster slug), so `pwk-finalizing` finds it inside the topic folder. Keep the blank lines between the header fields: the blank lines are load-bearing, because CommonMark merges consecutive plain lines into one paragraph, so without them every preview renders the whole header as a single run-on line.
+2. **Create the progress file** `docs/plans/<date>-<topic>/<leaf>-progress.md`, beside the design doc it belongs to (`<leaf>` is `<topic>` for a single-part topic; an umbrella part uses its roster slug). Keep the blank lines between the header fields: the blank lines are load-bearing, because CommonMark merges consecutive plain lines into one paragraph.
 
    ```markdown
    # Progress: <topic>
@@ -19,7 +19,7 @@ Read before creating or changing progress rows, or writing/re-presenting the cod
 
    Feature phase: e2e-written
 
-   <!-- a trivial design doc (no `## Feature acceptance`) starts at `implementing (0/N)` instead — there is no E2E to write -->
+   <!-- a trivial design doc (no `## Feature acceptance`) starts at `implementing (0/N)` -->
 
    ## Requirements
    | # | Done | Requirement | Per-req ceremony | Commit |
@@ -27,13 +27,13 @@ Read before creating or changing progress rows, or writing/re-presenting the cod
    | 1 | ⬜ | <requirement name> | — | — |
 
    ## Execution summary
-   | R# | Requirement | How it was built | Deviated? |
-   |----|-------------|------------------|-----------|
-   | 1 | <requirement name> | | |
+   | R# | Requirement | How it was built | Deviated? | Evidence |
+   |----|-------------|------------------|-----------|----------|
+   | 1 | <requirement name> | | | |
 
    ## Deviation records
 
-   <!-- One short paragraph per design-decision reversal (what changed, why, what was rejected), written at deviation time; leave this section empty when every Deviated? entry is mechanical. -->
+   <!-- One short paragraph per design-decision reversal -->
 
    ## Code digest
 
@@ -52,35 +52,34 @@ Read before creating or changing progress rows, or writing/re-presenting the cod
    - `<file>` — <what shifted inside it>
    ```
 
-   The `## Code digest` is filled once, at the write point in the ship checkpoint — never per requirement. Fill rules: plain language, R# anchors where natural, no test names (the execution-summary rule). `### Summary` is 2–3 sentences: what the code now does differently, and why. `### Flow` uses `A -> B -> C` arrow chains, one spine or branch per bullet line, so every renderer shows each hop chain on its own line — bare label lines would merge into one run-on paragraph. `### Gotchas` lifts real risks from the review findings, one bullet each — `[ALERT]` only for reviewer-confirmed issues, never invented; with no findings, write `none beyond review findings` and mean it. `### Key files` is capped at 5 pivotal files, one bullet each: what shifted inside them.
+## Code digest
 
-   **Flow shape** — this is the ship stop's navigable map, so it is the one digest section that carries structure, not just prose:
+   The `## Code digest` is filled once, at the write point in the ship checkpoint — never back-filled per requirement. Fill rules: plain language, R# anchors where natural, no test names. `### Summary` is 2–3 sentences: what the code now does differently, and why. `### Flow` uses `A -> B -> C` arrow chains, one spine or branch per bullet line. `### Gotchas` lifts real risks from the review findings, one real risk per bullet — `[ALERT]` only for reviewer-confirmed issues, never invented; with none, write `none beyond review findings`. `### Key files` is capped at 5 pivotal files, one bullet each.
 
-   - **Spine** — the happy path as `A -> B -> C` hops, each hop named by symbol or module, with no line numbers anywhere and no file paths: symbol names survive edits and stay greppable, so a stale anchor can never mislead. Tag each hop `[R<n>]` with the requirement it comes from — that is what lets the coverage table's verdict rows be traced into the code without opening the diff.
-   - **Branches** — every alternative and error path as `condition -> outcome` (a linear spine with no branches reads as "there are no edge cases", which is rarely true). Put ⚠️ on the genuinely surprising ones. Add a `was: <previous behavior>` clause for each requirement whose behavior changed; skip it for purely additive requirements — honest-empty, never invented.
-   - **Inline worked values** — where a mapping is non-obvious, show it concretely (`` `implementing (2/5)` -> `execute 2/5` ``), so a reader can falsify it without running anything.
-   - **Side effects** — a bullet naming what is read and written, only when the feature performs I/O, network, or migrations; omit it entirely otherwise rather than filling a placeholder.
-   - **Cap: roughly 15 lines.** If the change genuinely needs more, the ship checkpoint **offers `/skill:pwk-walkthrough`** as the deep read (it regenerates a `file:line`-anchored walkthrough on demand) instead of growing the digest — the digest is what the human reads at the one remaining stop, and an unbounded Flow recreates the digging it exists to prevent.
+   **Flow shape** — the ship stop's navigable map, the one digest section carrying structure:
+   - **Spine** — the happy path, each hop named by symbol — no line numbers, no file paths (those go stale). Tag each hop `[R<n>]`, so coverage verdicts trace into the code.
+   - **Branches** — every alternative and error path as `condition -> outcome`; a bare spine reads as "no edge cases". Put ⚠️ on the surprising ones, and a `was: <previous behavior>` clause on each requirement whose behavior changed — skip it for purely additive ones.
+   - **Inline worked values** — a non-obvious mapping shown concretely (`` `implementing (2/5)` -> `execute 2/5` ``).
+   - **Side effects** — what is read and written, only for I/O, network, or migrations; otherwise omit the bullet.
+   - **Cap: roughly 15 lines.** A longer Flow gets the ship checkpoint's `/skill:pwk-walkthrough` offer instead.
 
    `Feature phase` is one of: `e2e-written`, `implementing (k/N)`, `reviewing`, `ship-paused`, `done`.
 
-   The `Setup:` header slot takes one of `Setup: pending | done | n/a` — the header starts `Setup: pending` when the design doc has a `## Setup` section, else `Setup: n/a`; the main skill's setup checkpoint flips it to `done` on approval. The phase line stays `e2e-written` through the setup stop — the Setup slot, not the phase, is what flags the not-yet-approved window, and the E2E is written after setup.
-
+   The `Setup:` header slot takes one of `Setup: pending | done | n/a` — the header starts `Setup: pending` when the design doc has a `## Setup` section, else `Setup: n/a`; the setup checkpoint flips it to `done` on approval. The phase line stays `e2e-written` through the setup stop, and the E2E is written after setup.
 
 ## Progress file
 
-Update the matching requirement row directly (not via pattern matching that could corrupt the table). Update `Last updated` and `Feature phase` on every change.
+Update the matching row directly, never via pattern matching (which corrupts the table). Update `Last updated` and `Feature phase` on every change.
 
 **Row vocabulary (canonical — this file owns it):**
 
-- **Done cell:** `⬜` not started · `🔄` in progress · `✅` done · `❌` failed · `⏭` skipped. A row is **terminal** when its Done cell is `✅`, `❌`, or `⏭` — resolved, not necessarily passed. A `❌`/`⏭` row carries its reason as a suffix in the Requirement cell (finalizing's verdict greps read it), and its test coverage is reconciled in the same step — assertions removed or skipped with the reason; the suite must stay green. This skill sets all five values. A requirement under review stays `🔄`: `pwk-code-review` reports findings and never edits the Done cell — the loop only ever flips `🔄`→`✅` when the review returns clean, and findings leave the row `🔄` for another pass.
+- **Done cell:** `⬜` not started · `🔄` in progress · `✅` done · `❌` failed · `⏭` skipped. A row is **terminal** when its Done cell is `✅`, `❌`, or `⏭` — resolved, not necessarily passed. A `❌`/`⏭` row carries its reason as a suffix in the Requirement cell, and its test coverage is reconciled in the same step — assertions removed or skipped with the reason, leaving the suite green. A requirement under review stays `🔄`: `pwk-code-review` never edits the Done cell — the loop only ever flips `🔄`→`✅` when the review returns clean; findings leave the row `🔄` for another pass.
 - **Per-req ceremony cell** echoes the design doc's tag, not progress: `—` (default `none`/`skip`) · `⏸ full` (fires two stops — after the slice's tests and after it is complete) · `🔎 inline` · `🔎 parallel`.
 
-**Execution summary rows are written in the same step as marking a requirement ✅** — never retrofitted at the end. "How it was built" = one or two plain sentences: what it does now + the approach actually taken; file names sparingly; **no test names, no code** (the human reads this at the ship checkpoint — big picture only). If the implementation departs from the design, fill the Deviated? column **at deviation time** (when the departure happens), with a one-line why — it is a log, not a stop. A departure that **reverses or alters a design decision** gets a **deviation decision-record**: a short paragraph (what changed, why, what was rejected) written into the progress file while the knowledge is fresh — mechanical deviations keep the one-liner. `pwk-finalizing`'s learning sweep harvests these records for ADRs before the docs are disposed.
-
+**Execution summary rows are written in the same step as marking a requirement ✅** — never retrofitted. "How it was built" = one or two plain sentences: what it does now plus the approach taken, file names sparingly, **no test-name lists, no code**. The `Evidence` cell pairs **what it proves in plain words** with a pointer — a commit, a `file:line`, a command with its output line, or one probe test — single-line. No requirement is marked ✅ with an empty `Evidence` cell: either the pointer exists or the requirement is not done. A deviating implementation fills the Deviated? column **at deviation time** (when the departure happens), with a one-line why — it is a log, not a stop. A departure that **reverses or alters a design decision** gets a **deviation decision-record**: a short paragraph (what changed, why, what was rejected) written while the knowledge is fresh; mechanical deviations keep the one-liner. `pwk-finalizing`'s learning sweep harvests these records for ADRs before the docs are disposed.
 
 ## Commit entries for packet assembly
 
-Record immutable hexadecimal commit IDs (7–64 characters). A cell can hold one ID or an ordered, whitespace-separated list: initial implementation first, review-fix commits last. Preserve the first recorded commit when appending a fix; replacing it loses the feature base. Record a commit hash after committing, never amend a commit to include its own hash.
+Record immutable hexadecimal commit IDs (7–64 characters). A cell holds one ID or an ordered, whitespace-separated list: initial implementation first, review-fix commits last. Preserve the first recorded commit when appending a fix — replacing it loses the feature base. Record a hash after committing, never amend a commit to carry its own hash.
 
-The helper reads only the Requirements table Commit column. A done or in-review row needs a recorded commit. Terminal `❌`/`⏭` rows may have `—` when no commit remains; this does not supply a bound for a requirement packet. If the selected or immediately previous requirement lacks a bound, stop and correct the record from Git evidence; never invent one.
+The helper reads only the Requirements table Commit column. A done or in-review row needs a recorded commit; a terminal `❌`/`⏭` row may have `—`, which supplies no bound. If the selected or previous requirement lacks a bound, stop and correct the record from Git evidence; never invent one.

package/skills/pwk-executing-tasks/references/resume.md

@@ -1,14 +1,14 @@
 # Workspace and resume details
 
-Read before choosing or adopting a topic branch/worktree, and whenever a matching progress file exists.
+Read before adopting a topic branch/worktree, or when a matching progress file exists.
 
 ## Workspace
 
-3. **Workspace — create the feature branch** — if you're already on **this topic's** feature branch, **reuse** it: a later umbrella part continues on the same umbrella branch as part 1. If on `main` — or on a different topic's feature branch, which stays that topic's own and never hosts this topic's commits — create or switch to this topic's branch: `git checkout <topic>` when it exists, else `git checkout -b <topic>` — the topic's folder slug (the `docs/plans/<date>-<topic>/` directory name, shared by every leaf of an umbrella), never a leaf slug. **`<topic>` is the folder slug** everywhere it appears in this skill, including the `../<repo>-<topic>` worktree convention below, so a standalone topic and an umbrella part name the same branch and the same worktree. For larger work, first check `git worktree list`: if a worktree already checks out this branch (the same `../<repo>-<topic>` convention), adopt it — resume the session there instead of offering a new `git worktree add`. One worktree per branch, created once: git refuses two checkouts of one branch, so a later umbrella part reuses part 1's worktree and a standalone resume reuses its own. Otherwise offer a worktree (`git worktree add ../<repo>-<topic> <topic>`) and hand off to a new session there so `pwd` is the worktree. **Uncommitted planning docs do not cross a worktree boundary**, and the design doc is still uncommitted (brainstorm never commits): when the user takes the worktree, commit the topic folder on this branch first — the same scoped add as the main skill's First-run commit — then switch this tree back to the branch it came from (e.g. `git checkout main` when it started there; git refuses `worktree add` of a branch that is still checked out here) and only then `git worktree add ../<repo>-<topic> <topic>` and hand off (the new session's First-run commit then has only its progress file to record). The adopt path above is safe only when the docs are already committed on the branch; if this tree holds uncommitted topic docs while another worktree holds the branch checkout, git refuses to commit to the branch from here — copy the topic folder into that worktree's `docs/plans/`, verify with `ls`, and remove the source copy before handing off. Wait for the user's choice.
+3. **Workspace — create the feature branch** — already on **this topic's** feature branch → **reuse** it (a later umbrella part continues on part 1's branch). Else `git checkout <topic>`, or `git checkout -b <topic>` if new — **`<topic>` is the folder slug** everywhere in this skill: the `docs/plans/<date>-<topic>/` directory name, shared by every umbrella leaf, never a leaf slug — and it names the branch and the `../<repo>-<topic>` worktree. Check `git worktree list` first: adopt a worktree already on this branch rather than adding a second (one per branch); otherwise offer `git worktree add ../<repo>-<topic> <topic>` and hand off to a new session there, so the session's working directory is the worktree. **Uncommitted planning docs do not cross a worktree boundary** (brainstorm never commits the design doc): commit the topic folder with the main skill's scoped First-run add, switch this tree back to the branch it came from (git refuses `worktree add` of a branch still checked out here), then add the worktree. If this tree holds uncommitted topic docs while another worktree holds the branch, git refuses to commit from here — copy the topic folder into that worktree's `docs/plans/`, confirm the copy landed, and remove the source copy. Wait for the user's choice.
 
 ## Resume
 
-Read the progress file's `Feature phase` (match the line — e.g. `grep -m1 '^Feature phase:' <file>`), the Requirements table (the first row whose Done cell is not terminal routes the next requirement — `⬜`, `🔄`, and blank all mean not-done; `✅`/`❌`/`⏭` are resolved and are skipped past), and the Execution summary rows (how prior parts were built); read from the top through the end of `## Execution summary` and stop — the sections after it (deviation records, code digest) carry nothing the resume needs, with one exception: the `ship-paused` route re-presents the ship checkpoint, so it also reads the `## Code digest` written in the progress file. Before routing: if the header reads `Setup: pending` and the design doc has a `## Setup` section, the setup checkpoint was never approved — re-run the setup verification and wait at it:
+Read the progress file's `Feature phase` (match the line — e.g. `grep -m1 '^Feature phase:' <file>`), the Requirements table (the first row whose Done cell is not terminal routes the next requirement — `⬜`, `🔄`, and blank all mean not-done; `✅`/`❌`/`⏭` are resolved and are skipped past), and the Execution summary rows; stop after `## Execution summary` — later sections carry nothing the resume needs, with one exception: the `ship-paused` route re-presents the ship checkpoint, so it also reads the `## Code digest`. Before routing: a `Setup: pending` header on a design doc with a `## Setup` section means the setup checkpoint was never approved — re-run the setup verification and wait at it:
 - `e2e-written` → write the E2E if not yet present, post the notice, and continue into the implement phase (no stop). A trivial design doc has no `## Feature acceptance` — skip both and go straight into the implement phase.
 - `implementing (k/N)` → continue the next not-yet-terminal requirement.
 - `reviewing` → continue/finish the feature review, then assemble the **ship** checkpoint.

package/skills/pwk-executing-tasks/references/review.md

@@ -1,42 +1,35 @@
 # Review mechanics and packet helper
 
-Read before any feature or opt-in requirement review, before refreshing a packet, and before writing the code digest from review evidence.
+Read before any review, packet refresh, or digest write.
 
 ## Assemble evidence
 
-**Assemble the review packet first** — once, by script, so that no packet byte passes through model output (spawn arguments are model output; file reads are not). The Commit column is the packet's source of truth for both spans: the feature packet base is `git rev-parse <first Commit-column entry>^` (the parent of the first recorded commit); a per-requirement packet spans from the previous requirement's last commit (exclusive) to this requirement's last commit (inclusive), with R1's exclusive bound being its own parent. No `merge-base` guessing, no default-branch knowledge. If commits land while the review is in flight, re-run the recipe before spawning any replacement role so the packet matches HEAD:
+**Assemble the review packet first** — once, by script, so that no packet byte passes through model output. The Commit column fixes both spans: feature base = `git rev-parse <first Commit-column entry>^`, the parent of the first recorded commit; a requirement packet spans the previous requirement's last commit (exclusive) to this one's last commit (inclusive), R1's exclusive bound being its own parent. No `merge-base` guessing. Commits landing mid-review → re-run the recipe before spawning a replacement role, so the packet matches HEAD:
 
-Use the installed skill directory, not a repository checkout of the kit. First verify `python3 --version` reports Python 3.9 or newer and that the helper exists. Missing runtime/resource → report the dependency and stop this step. No runtime auto-install or alternate-language fallback.
+Use the installed skill directory, not a repository checkout; a missing runtime or helper (`node --version`) → report it and stop, with no auto-install or fallback.
 
 ```sh
-python3 "<executing-skill-dir>/scripts/build-review-packet.py" \
+node "<executing-skill-dir>/scripts/build-review-packet.mjs" \
   --project "<repo-root>" \
   --design "docs/plans/<date>-<topic>/<leaf>-design.md" \
   --progress "docs/plans/<date>-<topic>/<leaf>-progress.md" \
   --scope feature
 ```
 
-For an opt-in requirement review, use the same invocation with `--scope requirement --requirement 2` (substitute the selected number). The feature destination is `<design doc's directory>/<leaf>-review-packet.md`; the requirement destination is `<design doc's directory>/<leaf>-review-packet-r<N>.md`. Requirement-suffixed packets never overwrite each other or the feature packet.
+For an opt-in requirement review, the same invocation with `--scope requirement --requirement 2` (substitute the number): destination `<leaf>-review-packet-r<N>.md`, versus the feature packet's `<design doc's directory>/<leaf>-review-packet.md`. Requirement-suffixed packets never overwrite each other or the feature packet.
 
-`--project` resolves from the caller's cwd and must name the Git worktree root. Design/progress arguments are absolute or relative to that project, regardless of the current directory or installed skill location. Both must be matched leaf files inside one active `docs/plans/<topic>/` folder. The helper derives the destination; symlink destinations are refused. Use argument lists in programmatic invocations, never shell interpolation.
+`--project` resolves from the caller's cwd and must name the Git worktree root; design/progress paths are absolute or relative to it and must be matched leaf files in one active `docs/plans/<topic>/` folder. The helper derives the destination and refuses a symlink; to pass arguments programmatically, use a list, never shell interpolation.
 
-The packet retains these sections, in order:
-- `## Commits`
-- `## Changed files`
-- `## Acceptance criteria (verbatim from the design doc)`
-- `## Feature acceptance (verbatim)` (empty for a trivial design)
-- `## Production-risk notes (verbatim, if any)`
-- `## Diff`
+The packet retains, in order: `## Commits`, `## Changed files`, `## Acceptance criteria (verbatim from the design doc)`, `## Feature acceptance (verbatim)` (empty for a trivial design), `## Production-risk notes (verbatim, if any)`, `## Diff`.
 
-Criteria and production-risk content remain verbatim, including all lines in multiple risk blocks; fenced template headings do not route extraction. Feature criteria span from the first real requirement to Feature acceptance (or document end); requirement criteria include only the selected requirement block. Design-level production-risk areas are retained as review context. The packet header records fixed `Base:` and `Head:` IDs: feature uses the first recorded commit's parent through current HEAD; requirement uses the previous requirement's last recorded commit exclusively through the selected last recorded commit inclusively. The helper excludes generated `*-review-packet*.md` files from diff/stat, including committed packets.
+Criteria and production-risk content stay verbatim, including every line of multiple risk blocks; a fenced template heading never routes extraction. Feature criteria span from the first real requirement to Feature acceptance (or document end); a requirement packet covers only its own block, keeping design-level production-risk areas as context. The helper excludes generated `*-review-packet*.md` files from diff/stat, including committed packets.
 
-A Commit cell is one immutable hexadecimal ID or an ordered whitespace-separated list. Preserve the first ID; append review-fix IDs in order. Feature assembly permits missing commits only for terminal failed/skipped rows. Requirement assembly needs an explicit selected and previous bound; it refuses to guess across a failed/skipped row without a commit. Missing relevant rows, malformed/ambiguous entries, invalid revisions, or non-ancestral order → correct the record from evidence and rerun. The helper never edits progress, commits, switches branches, or marks anything approved. It finishes all parse/Git work before atomically replacing a complete packet. A nonzero exit is failure, not review evidence: report stderr and stop delegation; an older packet remains intact but may be stale.
+A Commit cell is one immutable hexadecimal ID or an ordered whitespace-separated list — preserve the first ID, append review-fix IDs in order. Only terminal failed/skipped rows may lack a commit, and requirement assembly never guesses a bound across such a row. Anything missing, malformed, or non-ancestral → correct the record from evidence and rerun. The helper never edits progress, commits, or approves, replacing a packet only after all parse/Git work succeeds. A nonzero exit is failure, not evidence: report stderr and stop delegation.
 
-After late review fixes, commit them and append their IDs to the selected row before refreshing a requirement packet; feature packets refresh HEAD automatically. Re-run the helper before any replacement reviewer and before digest writing if stale or missing. Packet generation is evidence assembly, not review approval. Re-green the full suite + E2E after fixes, then complete review and the human checkpoint.
+After late fixes, commit, append the IDs to the selected row, and refresh the packet; feature packets refresh HEAD automatically. Re-run the helper before any replacement reviewer, and before digest writing if stale or missing. Then re-green the full suite + E2E and finish the checkpoint.
 
 ## Delegate or review inline
 
-- **`parallel`** (the `auto` resolution when risk content is present) — request the host’s `parallel-review` capability for four fresh-context, read-only logical roles: `pwk-spec-reviewer`, `pwk-tracing-reviewer`, `pwk-smell-reviewer`, and `pwk-hazard-reviewer`. Spawn each role with a **one-liner** — a pointer to the packet file with the role framing appended last: the checklist name of the role (`spec alignment`, `code tracing`, `code smells`, or `production hazards`). For example: `Read docs/plans/<date>-<topic>/<leaf>-review-packet.md. Your role: spec alignment.` The packet never appears in spawn arguments. Require independent execution and one collected outcome per role. The reviewer role contracts live in `agents/pwk-*-reviewer.md`; do not duplicate their checklists in the workflow instructions. Reviewers are read-only reporters; you apply smell fixes yourself (full suite + E2E must stay green, commit) and flag trace/spec/hazard findings as follow-ups for the human.
-
+- **`parallel`** (the `auto` resolution when risk content is present) — request the host's `parallel-review` capability for four fresh-context, read-only roles: `pwk-spec-reviewer`, `pwk-tracing-reviewer`, `pwk-smell-reviewer`, `pwk-hazard-reviewer`. Spawn each with a **one-liner** pointing at the packet file, role framing last — the checklist name (`spec alignment`, `code tracing`, `code smells`, `production hazards`), e.g. `Read docs/plans/<date>-<topic>/<leaf>-review-packet.md. Your role: spec alignment.` The packet never appears in spawn arguments. Require independent execution and one collected outcome per role; the contracts live in `agents/pwk-*-reviewer.md`. Reviewers only report — you apply smell fixes (full suite + E2E green, commit) and flag trace/spec/hazard findings for the human.
 - **`inline`** — perform `/skill:pwk-code-review` over the whole diff as a single pass.
-- **Fallback** — if the host has no compatible parallel-review capability, cannot prove the requested read-only/fresh-context/bounded constraints, or delegation fails, perform the missing review work inline. Retain successful delegated reports and do not mark the feature fully reviewed while a required role is missing.
+- **Fallback** — no compatible parallel-review capability, unprovable read-only/fresh-context/bounded constraints, or failed delegation → perform the missing review work inline. Retain successful delegated reports; never mark the feature fully reviewed while a required role is missing.

package/skills/pwk-executing-tasks/scripts/build-review-packet.mjs

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+/**
+ * Build review evidence from explicit, immutable Git bounds.
+ *
+ * Usage: node build-review-packet.mjs --project <root> --design <path> --progress <path> --scope feature|requirement [--requirement N]
+ */
+import { spawnSync } from "node:child_process";
+import { constants, lstatSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+
+class PacketError extends Error {}
+
+/** Keep original lines for evidence; inspect headings only outside fenced examples. */
+class Document {
+  constructor(path) {
+    // A strict decode, as Python's open(encoding="utf-8") is: reading as utf8 would replace
+    // invalid bytes and build a packet from damaged evidence.
+    this.lines = new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(path)).split(/(?<=\n)/);
+    this.headings = [];
+    this.visible = new Set();
+    let fence = null;
+    this.lines.forEach((line, index) => {
+      const stripped = line.replace(/\r?\n$/, "");
+      const marker = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(stripped);
+      if (fence) {
+        if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length && !marker[2].trim()) fence = null;
+        return;
+      }
+      if (marker) {
+        fence = marker[1];
+        return;
+      }
+      this.visible.add(index);
+      const heading = /^ {0,3}(#{1,6})\s+(.+?)\s*#*\s*$/.exec(stripped);
+      if (heading) this.headings.push([index, heading[1].length, heading[2]]);
+    });
+    if (fence) throw new PacketError(`${basename(path)}: unclosed code fence`);
+  }
+
+  section(title, level = 2, required = false) {
+    const matches = this.headings.filter(([, depth, text]) => depth === level && text === title);
+    if (matches.length > 1 || (required && matches.length === 0)) {
+      throw new PacketError(`expected one ${title} section; found ${matches.length}`);
+    }
+    if (matches.length === 0) return null;
+    const start = matches[0][0];
+    const end = this.headings.find(([index, depth]) => index > start && depth <= level)?.[0] ?? this.lines.length;
+    return [start, end];
+  }
+
+  text(start, end) {
+    return this.lines.slice(start, end).join("");
+  }
+}
+
+function git(project, ...args) {
+  const result = spawnSync("git", ["-C", String(project), ...args], {
+    env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" },
+    encoding: "utf8",
+  });
+  if (result.status !== 0) {
+    throw new PacketError(`git ${args.join(" ")} failed: ${(result.stderr ?? "").trim()}`);
+  }
+  return result.stdout;
+}
+
+const isSymlink = (path) => {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+};
+
+function resolveInput(project, value) {
+  const path = isAbsolute(value) ? value : join(project, value);
+  return realpathSync(path);
+}
+
+/** POSIX-style relative segments, or null when the child is outside the parent. */
+function relativeParts(child, parent) {
+  const rel = relative(parent, child);
+  if (!rel || rel === "" || rel.startsWith("..")) return null;
+  return rel.split(/[\\/]/);
+}
+
+function validateDestination(path) {
+  if (isSymlink(path)) throw new PacketError("packet destination must be a regular file, not a symlink or directory");
+  try {
+    if (!lstatSync(path).isFile()) {
+      throw new PacketError("packet destination must be a regular file, not a symlink or directory");
+    }
+  } catch (error) {
+    if (error instanceof PacketError) throw error;
+  }
+}
+
+function paths(args) {
+  const project = realpathSync(resolve(args.project));
+  if (resolve(git(project, "rev-parse", "--show-toplevel").trim()) !== project) {
+    throw new PacketError("--project must be the Git worktree root");
+  }
+  for (const value of [args.design, args.progress]) {
+    const supplied = resolve(isAbsolute(value) ? value : join(project, value));
+    const lexicalProject = resolve(args.project);
+    let rel = relativeParts(supplied, lexicalProject);
+    if (!rel) rel = relativeParts(supplied, project);
+    if (!rel) throw new PacketError(`${value} is outside the project`);
+    let current = project;
+    for (const part of rel) {
+      current = join(current, part);
+      if (isSymlink(current)) throw new PacketError("design/progress paths must not traverse symlinks");
+    }
+  }
+  const design = resolveInput(project, args.design);
+  const progress = resolveInput(project, args.progress);
+  const relativeTopic = relativeParts(design, join(project, "docs", "plans"));
+  if (
+    !relativeTopic ||
+    relativeTopic.length !== 2 ||
+    relativeTopic[0] === "completed" ||
+    !design.endsWith("-design.md")
+  ) {
+    throw new PacketError("design must be docs/plans/<topic>/<leaf>-design.md in an active topic");
+  }
+  const leaf = basename(design).slice(0, -"-design.md".length);
+  if (!leaf || progress !== join(dirname(design), `${leaf}-progress.md`)) {
+    throw new PacketError("progress must be the matching <leaf>-progress.md beside the design");
+  }
+  for (const directory of [
+    join(project, "docs"),
+    join(project, "docs", "plans"),
+    join(project, "docs", "plans", relativeTopic[0]),
+  ]) {
+    if (isSymlink(directory)) throw new PacketError("symlink topic directories are not writable packet destinations");
+  }
+  const suffix = args.scope === "feature" ? "" : `-r${args.requirement}`;
+  const destination = join(dirname(design), `${leaf}-review-packet${suffix}.md`);
+  validateDestination(destination);
+  return { project, design, progress, destination };
+}
+
+function requirements(document) {
+  const region = document.section("Requirements", 2, true);
+  const headings = [];
+  for (const [index, depth, title] of document.headings) {
+    const match = /^R([1-9][0-9]*):\s*\S/.exec(title);
+    if (depth === 3 && /^R[0-9]/.test(title) && !match) throw new PacketError("malformed requirement heading");
+    if (depth === 3 && match) {
+      if (!(region[0] < index && index < region[1])) {
+        throw new PacketError("requirement heading outside Requirements section");
+      }
+      headings.push([Number(match[1]), index]);
+    }
+  }
+  const numbers = headings.map(([number]) => number);
+  if (numbers.length === 0 || new Set(numbers).size !== numbers.length) {
+    throw new PacketError("missing or duplicate requirement headings");
+  }
+  return { headings, region };
+}
+
+function progressRows(document, project, design) {
+  const firstHeading = document.headings.find(([, depth]) => depth === 2)?.[0] ?? document.lines.length;
+  const pointers = [...document.visible]
+    .filter((index) => index < firstHeading && document.lines[index].startsWith("Design: "))
+    .map((index) => document.lines[index].trim().slice(8));
+  if (pointers.length !== 1 || resolveInput(project, pointers[0]) !== design) {
+    throw new PacketError("progress Design header must identify the selected design exactly once");
+  }
+  const [start, end] = document.section("Requirements", 2, true);
+  const lines = [];
+  for (let index = start + 1; index < end; index += 1) {
+    if (document.visible.has(index) && document.lines[index].trim()) lines.push(document.lines[index].trim());
+  }
+  if (lines.length < 3) throw new PacketError("missing Requirements table");
+
+  const cells = (line) => {
+    if (!line.startsWith("|") || !line.endsWith("|")) throw new PacketError("malformed Requirements table row");
+    return line
+      .split(/(?<!\\)\|/)
+      .slice(1, -1)
+      .map((cell) => cell.trim());
+  };
+
+  const header = cells(lines[0]);
+  if (header.join("|") !== ["#", "Done", "Requirement", "Per-req ceremony", "Commit"].join("|")) {
+    throw new PacketError("Requirements table must have #, Done, Requirement, Per-req ceremony, Commit columns");
+  }
+  const separator = cells(lines[1]);
+  if (separator.length !== 5 || !separator.every((cell) => /^:?-+:?$/.test(cell))) {
+    throw new PacketError("malformed Requirements table separator");
+  }
+  const rows = new Map();
+  for (const line of lines.slice(2)) {
+    const row = cells(line);
+    if (row.length !== 5 || !/^[1-9][0-9]*$/.test(row[0])) throw new PacketError("malformed Requirements table row");
+    const number = Number(row[0]);
+    if (rows.has(number)) throw new PacketError(`duplicate R${number} progress row`);
+    if (!["", "⬜", "🔄", "✅", "❌", "⏭"].includes(row[1])) throw new PacketError(`R${number}: invalid Done cell`);
+    rows.set(number, row);
+  }
+  return rows;
+}
+
+function bounds(project, rows, headings, args) {
+  const numbers = headings.map(([number]) => number);
+  const position = args.scope === "requirement" ? numbers.indexOf(args.requirement) : null;
+  const relevant = position === null ? numbers : numbers.slice(Math.max(0, position - 1), position + 1);
+  if ([...rows.keys()].some((number) => !numbers.includes(number))) {
+    throw new PacketError("progress contains requirements absent from the design");
+  }
+  const recorded = new Map();
+  let previous = null;
+  const currentHead = git(project, "rev-parse", "--verify", "HEAD^{commit}").trim();
+  for (const number of relevant) {
+    if (!rows.has(number)) throw new PacketError(`R${number}: missing progress row`);
+    const row = rows.get(number);
+    const value = row[4];
+    if (value === "" || value === "—" || value === "-") {
+      if (!["❌", "⏭"].includes(row[1])) throw new PacketError(`R${number}: missing Commit entry`);
+      recorded.set(number, []);
+      continue;
+    }
+    // An ordered whitespace-separated list supports review-fix commits without losing the
+    // first feature commit. Other formats are ambiguous, never mined for hashes.
+    const entries = value.split(/\s+/).filter(Boolean);
+    if (!entries.every((entry) => /^[0-9a-fA-F]{7,64}$/.test(entry))) {
+      throw new PacketError(`R${number}: Commit must contain only ordered hexadecimal commit IDs`);
+    }
+    const commits = [];
+    for (const entry of entries) {
+      const commit = git(project, "rev-parse", "--verify", `${entry}^{commit}`).trim();
+      if (previous) {
+        if (previous === commit) throw new PacketError("duplicate or overlapping recorded commits");
+        git(project, "merge-base", "--is-ancestor", previous, commit);
+      }
+      git(project, "merge-base", "--is-ancestor", commit, currentHead);
+      commits.push(commit);
+      previous = commit;
+    }
+    recorded.set(number, commits);
+  }
+  if (args.scope === "feature") {
+    const first = [...recorded.values()].find((commits) => commits.length > 0)?.[0] ?? null;
+    if (!first) throw new PacketError("no recorded commits; cannot infer a feature base");
+    return [git(project, "rev-parse", "--verify", `${first}^`).trim(), currentHead];
+  }
+  const selected = recorded.get(args.requirement);
+  if (!selected?.length) throw new PacketError("selected requirement has no recorded bound");
+  if (position === 0) return [git(project, "rev-parse", "--verify", `${selected[0]}^`).trim(), selected.at(-1)];
+  const prior = recorded.get(numbers[position - 1]);
+  if (!prior?.length) throw new PacketError("previous requirement has no recorded bound; cannot guess a range");
+  return [prior.at(-1), selected.at(-1)];
+}
+
+function evidence(document, headings, region, args) {
+  const feature = document.section("Feature acceptance");
+  if (feature && feature[0] < region[1]) throw new PacketError("Feature acceptance must follow Requirements");
+  let start;
+  let end;
+  if (args.scope === "feature") {
+    start = headings[0][1];
+    end = feature ? feature[0] : document.lines.length;
+  } else {
+    const position = headings.findIndex(([number]) => number === args.requirement);
+    start = headings[position][1];
+    end = position + 1 < headings.length ? headings[position + 1][1] : region[1];
+  }
+  const criteria = document.text(start, end);
+  let acceptance = "";
+  if (feature) {
+    const stop =
+      document.headings.find(
+        ([index, depth, title]) =>
+          feature[0] < index && index < feature[1] && depth === 3 && title.startsWith("Feature review:"),
+      )?.[0] ?? feature[1];
+    acceptance = document.text(feature[0], stop);
+  }
+  const notes = [];
+  for (const [index, depth, title] of document.headings) {
+    if (depth === 3 && title === "Production-risk notes" && start <= index && index < end) {
+      const stop =
+        document.headings.find(([i, d, t]) => i > index && (d <= 2 || (d === 3 && /^R[0-9]+:/.test(t))))?.[0] ??
+        document.lines.length;
+      notes.push(document.text(index, Math.min(stop, end)));
+    }
+  }
+  const risk = document.section("Production-risk areas");
+  if (risk) notes.push(document.text(risk[0], risk[1]));
+  return { criteria, acceptance, notes: notes.join("") };
+}
+
+function build(args) {
+  const { project, design: designPath, progress: progressPath, destination } = paths(args);
+  const design = new Document(designPath);
+  const { headings, region } = requirements(design);
+  if (args.scope === "requirement" && !headings.some(([number]) => number === args.requirement)) {
+    throw new PacketError("selected requirement is absent from the design");
+  }
+  const rows = progressRows(new Document(progressPath), project, designPath);
+  const [base, head] = bounds(project, rows, headings, args);
+  const { criteria, acceptance, notes } = evidence(design, headings, region, args);
+  const span = `${base}..${head}`;
+  const pathspec = ["--", ".", ":(glob,exclude)**/*-review-packet*.md"];
+  const sections = [
+    ["Commits", git(project, "log", "--oneline", "--no-decorate", span)],
+    ["Changed files", git(project, "diff", "--no-ext-diff", "--no-textconv", "--stat", span, ...pathspec)],
+    ["Acceptance criteria (verbatim from the design doc)", criteria],
+    ["Feature acceptance (verbatim)", acceptance],
+    ["Production-risk notes (verbatim, if any)", notes],
+    ["Diff", git(project, "diff", "--no-ext-diff", "--no-textconv", "--no-color", span, ...pathspec)],
+  ];
+  const label = args.scope === "feature" ? "feature review" : `requirement R${args.requirement} review`;
+  // The blank line between Base and Head is load-bearing: CommonMark merges consecutive
+  // plain lines into one paragraph in every preview.
+  let packet = `# Review packet: ${basename(dirname(designPath))} — ${label}\n\nBase: ${base}\n\nHead: ${head}\n\n`;
+  for (const [title, content] of sections) packet += `## ${title}\n\n${content}\n`;
+
+  // Every parse and Git read finishes before a temporary file exists, so a failure in
+  // assembly leaves an earlier complete packet intact. Replacement is same-directory.
+  let temporary = null;
+  try {
+    validateDestination(destination);
+    temporary = join(dirname(destination), `.${basename(destination)}.${process.pid}${Date.now()}`);
+    writeFileSync(temporary, packet, {
+      encoding: "utf8",
+      flag: constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY,
+    });
+    validateDestination(destination);
+    renameSync(temporary, destination);
+    temporary = null;
+  } finally {
+    if (temporary) {
+      try {
+        unlinkSync(temporary);
+      } catch {
+        // The temporary file is already gone.
+      }
+    }
+  }
+  console.log(`Wrote ${destination}\nRange: ${base}..${head}`);
+}
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  console.log(`usage: node build-review-packet.mjs --project <root> --design <path> --progress <path> --scope feature|requirement [--requirement N]
+
+Build review evidence from explicit, immutable Git bounds, with Node's standard library only.
+
+--project resolves from the caller cwd and must be a Git worktree root. --design and --progress are absolute or relative to --project, not the skill or cwd. Output is <leaf>-review-packet[-rN].md beside the matched docs in docs/plans/<topic>/. Commit cells contain ordered whitespace-separated hexadecimal commit IDs, not revision expressions.`);
+  process.exit(0);
+}
+
+const { values } = (() => {
+  try {
+    return parseArgs({
+      args: process.argv.slice(2),
+      allowPositionals: false,
+      options: {
+        project: { type: "string" },
+        design: { type: "string" },
+        progress: { type: "string" },
+        scope: { type: "string" },
+        requirement: { type: "string" },
+      },
+    });
+  } catch (error) {
+    console.error(`error: ${error.message}`);
+    process.exit(2);
+  }
+})();
+for (const required of ["project", "design", "progress", "scope"]) {
+  if (!values[required]) {
+    console.error(`error: --${required} is required`);
+    process.exit(2);
+  }
+}
+if (!["feature", "requirement"].includes(values.scope)) {
+  console.error("error: --scope must be feature or requirement");
+  process.exit(2);
+}
+const requirement = values.requirement === undefined ? undefined : Number(values.requirement);
+if ((values.scope === "requirement") !== (requirement !== undefined)) {
+  console.error("error: --requirement N is required only for --scope requirement");
+  process.exit(2);
+}
+try {
+  build({
+    project: values.project,
+    design: values.design,
+    progress: values.progress,
+    scope: values.scope,
+    requirement,
+  });
+} catch (error) {
+  console.error(`error: ${error.message}`);
+  process.exit(1);
+}