@tianhai/pi-workflow-kit 2.8.0 → 2.11.0

package/skills/pwk-brainstorming/scripts/validate-design.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * Read-only structural validation of a workflow design document.
+ *
+ * Structure only: it does not judge whether a criterion is true, testable, or specific.
+ *
+ * Usage: node validate-design.mjs <design-path>
+ */
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+
+const TAG_VALUES = {
+  Checkpoints: ["none", "full"],
+  Review: ["skip", "parallel", "inline"],
+  "Feature review": ["auto", "parallel", "inline"],
+};
+const HEADING = /^ {0,3}(#{1,6})[ \t]+(.+?)\s*#*\s*$/;
+const REQUIREMENT = /^R([1-9][0-9]*):\s*(.*)$/;
+const REQUIREMENT_LIKE = /^R(?:[0-9]|\s*:)/;
+const CRITERIA = /^\*\*Acceptance criteria\*\*(?:\s*(?:—|–|-|:).*)?$/;
+
+/** Blank fenced examples, keeping an unclosed-fence diagnostic. Not a Markdown renderer. */
+function visibleLines(text) {
+  const lines = [];
+  const errors = [];
+  let fence = "";
+  let fenceLine = 0;
+  // Python's splitlines: break on CRLF, CR, or LF, and never keep a trailing empty line.
+  const rawLines = text.split(/\r\n|\r|\n/);
+  if (/[\r\n]$/.test(text)) rawLines.pop();
+  for (const [offset, line] of rawLines.entries()) {
+    const number = offset + 1;
+    if (fence) {
+      const char = fence[0] === "`" ? "`" : "~";
+      if (new RegExp(`^ {0,3}${char}{${fence.length},}[ \\t]*$`).test(line)) fence = "";
+      lines.push("");
+      continue;
+    }
+    const opening = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+    if (opening && !(opening[1][0] === "`" && opening[2].includes("`"))) {
+      fence = opening[1];
+      fenceLine = number;
+      lines.push("");
+    } else {
+      lines.push(line);
+    }
+  }
+  if (fence) errors.push(`line ${fenceLine}: unclosed code fence; close it before validating`);
+  return { lines, errors };
+}
+
+/** Presence of content, not its quality. */
+function hasContent(lines) {
+  return lines.some((line) => {
+    const text = line.replace(/^\s*(?:[-+*]|[0-9]+[.)])\s*/, "").trim();
+    // Unicode word characters: a criteria section written in CJK is not empty.
+    return Boolean(text) && /[\p{L}\p{N}_]/u.test(text);
+  });
+}
+
+/** A heading or another bold label terminates a criteria section. */
+function criteriaBody(lines, start, end) {
+  const result = [];
+  for (const line of lines.slice(start, end)) {
+    if (HEADING.test(line) || /^\s*\*\*[^*]+\*\*/.test(line)) break;
+    result.push(line);
+  }
+  return result;
+}
+
+function validate(text) {
+  const { lines, errors } = visibleLines(text);
+  const headings = [];
+  for (const [index, line] of lines.entries()) {
+    const match = HEADING.exec(line);
+    if (match) headings.push({ level: match[1].length, title: match[2], index });
+  }
+  for (const heading of headings) {
+    if (REQUIREMENT_LIKE.test(heading.title) && heading.level !== 3) {
+      errors.push(`line ${heading.index + 1}: ${heading.title} must use a ### requirement heading`);
+    }
+  }
+  const requirements = headings.filter((h) => h.level === 3 && REQUIREMENT_LIKE.test(h.title));
+  const features = headings.filter((h) => h.level === 2 && h.title === "Feature acceptance");
+  const summaries = [];
+
+  if (requirements.length === 0) {
+    errors.push("required requirement block missing; add ### R1: <name> with Acceptance criteria");
+  }
+  const seen = new Set();
+  requirements.forEach((heading, position) => {
+    const expected = position + 1;
+    const match = REQUIREMENT.exec(heading.title);
+    if (!match) {
+      errors.push(`line ${heading.index + 1}: malformed requirement '${heading.title}'; use ### R${expected}: <name>`);
+      return;
+    }
+    const number = Number(match[1]);
+    if (seen.has(number)) errors.push(`line ${heading.index + 1}: duplicate requirement R${number}`);
+    else if (number !== expected) {
+      errors.push(
+        `line ${heading.index + 1}: expected R${expected}, found R${number}; IDs must be sequential in document order`,
+      );
+    }
+    seen.add(number);
+    if (!match[2].trim()) errors.push(`line ${heading.index + 1}: R${number} requires a nonempty name`);
+  });
+
+  const introEnd = requirements.length ? requirements[0].index : lines.length;
+  const short = lines.slice(0, introEnd).some((line) => /^In short:\s*\S.*$/.test(line));
+  const fullFormat = headings.some((h) => h.level === 2 && (h.title === "At a glance" || h.title === "Requirements"));
+  const trivial =
+    short &&
+    !fullFormat &&
+    requirements.length === 1 &&
+    requirements[0].title.startsWith("R1:") &&
+    features.length === 0;
+  if (!trivial && features.length === 0) {
+    errors.push(
+      "## Feature acceptance is required for non-trivial designs; the trivial exception needs an In short: one-liner and a single R1 block without full-format sections",
+    );
+  }
+  if (features.length > 1) errors.push("duplicate ## Feature acceptance section; keep exactly one");
+
+  const ownedTags = new Set();
+  const tags = (start, end, names, owner) => {
+    const values = Object.fromEntries(names.map((name) => [name, TAG_VALUES[name][0]]));
+    const found = new Set();
+    for (const heading of headings) {
+      if (heading.index < start || heading.index >= end) continue;
+      for (const name of names) {
+        if (
+          heading.level !== 3 ||
+          // Anchored, as Python's re.match is: a title that merely contains a tag word is not a tag.
+          !new RegExp(`^${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(heading.title)
+        ) {
+          continue;
+        }
+        ownedTags.add(heading.index);
+        if (found.has(name)) errors.push(`line ${heading.index + 1}: duplicate ${name} tag in ${owner}`);
+        found.add(name);
+        let value = heading.title.slice(name.length).trim();
+        value = value.startsWith(":") ? value.slice(1).trim() : "";
+        if (!TAG_VALUES[name].includes(value)) {
+          errors.push(
+            `line ${heading.index + 1}: invalid ${name} tag in ${owner}; expected ${TAG_VALUES[name].join(" | ")}`,
+          );
+        } else {
+          values[name] = value;
+        }
+      }
+    }
+    return values;
+  };
+
+  for (const heading of requirements) {
+    const end =
+      headings.find((h) => h.index > heading.index && (h.level <= 2 || requirements.includes(h)))?.index ??
+      lines.length;
+    const criteriaEnd = headings.find((h) => h.index > heading.index && h.index < end)?.index ?? end;
+    const labels = [];
+    for (let i = heading.index + 1; i < criteriaEnd; i += 1) if (CRITERIA.test(lines[i].trim())) labels.push(i);
+    const owner = heading.title.split(":")[0];
+    if (labels.length === 0) {
+      errors.push(`line ${heading.index + 1}: ${owner} needs a standalone **Acceptance criteria** section`);
+    } else if (labels.length > 1) {
+      errors.push(`line ${labels[1] + 1}: ${owner} has duplicate Acceptance criteria sections`);
+    } else if (!hasContent(criteriaBody(lines, labels[0] + 1, end))) {
+      errors.push(
+        `line ${labels[0] + 1}: ${owner} Acceptance criteria is empty; add a criterion before the next section`,
+      );
+    }
+    const values = tags(heading.index + 1, end, ["Checkpoints", "Review"], owner);
+    summaries.push(`${owner}: Checkpoints=${values.Checkpoints}, Review=${values.Review}`);
+  }
+
+  for (const heading of features) {
+    const end = headings.find((h) => h.index > heading.index && h.level <= 2)?.index ?? lines.length;
+    if (!hasContent(criteriaBody(lines, heading.index + 1, end))) {
+      errors.push(
+        `line ${heading.index + 1}: Feature acceptance is empty; add an end-to-end criterion before its review tag`,
+      );
+    }
+    const values = tags(heading.index + 1, end, ["Feature review"], "Feature acceptance");
+    summaries.push(`Feature review=${values["Feature review"]}`);
+  }
+
+  for (const heading of headings) {
+    for (const name of Object.keys(TAG_VALUES)) {
+      if (
+        new RegExp(`^${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(heading.title) &&
+        !ownedTags.has(heading.index)
+      ) {
+        const owner = name === "Feature review" ? "## Feature acceptance" : "a ### R<n>: requirement block";
+        errors.push(`line ${heading.index + 1}: ${name} must be a ### tag inside ${owner}`);
+      }
+    }
+  }
+  return { errors, summaries };
+}
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  console.log(`usage: node validate-design.mjs <design-path>
+
+Read-only structural design validation with Node's standard library only. Semantic correctness is not verified.
+
+Pass an explicit design path. Absolute paths are used directly; relative paths resolve from the caller's current working directory (cwd), not the installed skill directory.`);
+  process.exit(0);
+}
+
+const { positionals } = (() => {
+  try {
+    return parseArgs({ args: process.argv.slice(2), allowPositionals: true });
+  } catch (error) {
+    console.error(`validate-design.mjs: ${error.message}`);
+    process.exit(2);
+  }
+})();
+const design = positionals[0];
+if (!design) {
+  console.error("usage: node validate-design.mjs <design-path>");
+  process.exit(2);
+}
+let text;
+try {
+  // A strict decode: reading as utf8 would replace invalid bytes instead of refusing them.
+  text = new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(design));
+} catch (error) {
+  console.error(`${design}: cannot read UTF-8 design: ${error.message}`);
+  process.exit(2);
+}
+const { errors, summaries } = validate(text);
+if (errors.length) {
+  for (const error of errors) console.error(`${design}: ${error}`);
+  process.exit(1);
+}
+console.log(`${design}: structural checks passed. Semantic correctness is not verified.`);
+for (const summary of summaries) console.log(`  ${summary}`);
+process.exit(0);

package/skills/pwk-code-review/SKILL.md

@@ -7,11 +7,11 @@ description: "Review a completed requirement's code — trace the logic, check s
 
 Review the code just implemented — one tagged requirement, or the whole feature at the feature-level review. **Unlocked** — you may edit code to apply smell fixes; flag everything else as a follow-up.
 
-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
 
-1. **Identify the scope** — in the feature-gate flow (the default), you review the **whole feature diff** at the feature-level review (`git diff $FEATURE_BASE...HEAD` — the parent of the first Commit-column entry; see the executing skill's packet recipe); all acceptance criteria in the design doc and the `## Feature acceptance` E2E are in scope. When invoked per-requirement (`Review: inline` on a tagged requirement — or inline-completing a missing delegated role when the tag is `parallel`), scope is just that requirement — read its acceptance criteria from the design doc, run `git log --oneline -5` and `git diff` to see what changed for it. Invoked standalone — no invoking skill, no design doc, no packet — review the span the user names (the working-tree diff, or the branch's commits against its parent branch): tracing, smell fixes, and the hazard check run as usual, while spec alignment has no acceptance criteria to key on — say so and judge the diff against its stated intent instead of manufacturing a coverage table. When the invoking skill already assembled a review packet (the feature packet, or the requirement-scoped `<leaf>-review-packet-r<N>.md`), work from the packet — it is the scope of record; re-derive nothing the packet already states.
+1. **Identify the scope** — in the feature-gate flow (the default) you review the **whole feature diff** at the feature-level review (`git diff $FEATURE_BASE...HEAD`, `$FEATURE_BASE` being the parent of the first Commit-column entry; see the executing skill's packet recipe), with every design-doc acceptance criterion and the `## Feature acceptance` E2E in scope. Invoked per-requirement (`Review: inline` on a tagged requirement, or inline-completing a missing delegated role when the tag is `parallel`), the scope is that requirement alone — read its acceptance criteria from the design doc and use `git log --oneline -5` plus `git diff` to see what changed. Invoked standalone — no invoking skill, no design doc, no packet — review the span the user names (the working-tree diff, or the branch's commits against its parent): tracing, smell fixes, and the hazard check run as usual, while spec alignment has no criteria to key on — say so and judge the diff against its stated intent rather than manufacturing a coverage table. When the invoking skill already assembled a packet (the feature packet, or the requirement-scoped `<leaf>-review-packet-r<N>.md`), work from the packet — it is the scope of record; re-derive nothing it states.
 
 2. **🔍 Code tracing** — trace the new or changed code paths end-to-end against the acceptance criteria and the feature E2E (a trivial design doc has no feature E2E — its acceptance criteria alone are the spec). For each path, determine whether data flows correctly from entry to the asserted outcome. Note any branch the tests do not exercise, any dead branch, or any path where the trace breaks.
 
@@ -23,7 +23,7 @@ Any command or tool recipe in this skill is an example, not the requirement —
    |----|---------|----------|
    | 1 | <verdict> | file:line (code), file:line (test) |
 
-   Verdict per requirement: `covered | gap | scope-creep` — `covered` = every criterion has covering code and a test; `gap` = a criterion lacks code or a test; `scope-creep` = the code does more than the criteria specify. Findings elaborate on every non-`covered` row; an all-`covered` table needs no elaboration.
+   Verdict per requirement: `covered | gap | scope-creep` — `covered` = every criterion has covering code and a test; `gap` = a criterion lacks code or a test; `scope-creep` = the code does more than the criteria specify; findings elaborate on every non-`covered` row, and an all-`covered` table needs no elaboration.
 
 4. **🧹 Code smells — fix these directly:** review the changed code and affected files against the requirement and feature scope, then fix what you find.
    - Shallow modules (interface nearly as complex as implementation)
@@ -49,8 +49,8 @@ Any command or tool recipe in this skill is an example, not the requirement —
 
 - **Tracing and spec alignment are the core** — they catch what tests miss: untested branches, missing criteria, scope creep.
 - **Fix smells in place; flag everything else.** Keep the review scoped — the goal is polish on the requirement that just landed, not a redesign pass.
-- **Be proportional** — a one-function change doesn't need the depth of a batch pipeline. When this skill runs as the inline path because the design doc tagged the requirement `Review: inline`, that was a deliberate call at design approval — keep the review focused and don't second-guess the tag.
+- **Be proportional** — a one-function change doesn't need the depth of a batch pipeline; a `Review: inline` tag was a deliberate call at design approval — keep the review focused and don't second-guess it.
 
 ## After the review
 
-Return to `/skill:pwk-executing-tasks` — the next requirement, or the ship checkpoint when every requirement is done. Finalizing is proposed from the ship checkpoint, never from here. (The human tagged this requirement at design approval when its `### Review` tag was set — keep the review focused on the tag's scope.)
+Return to `/skill:pwk-executing-tasks` — the next requirement, or the ship checkpoint when every requirement is done. Finalizing is proposed from the ship checkpoint, never from here.

package/skills/pwk-executing-tasks/SKILL.md

@@ -5,66 +5,75 @@ description: "Implement a design doc via the feature-gate flow: write the featur
 
 # Executing Tasks
 
-Implement the design doc found under `docs/plans/` via the **feature-gate flow**. The design doc is the single buildable artifact — its `### R<n>` blocks carry each requirement's acceptance criteria and tags. The criteria define *what*, you decide *how*: structure, signatures, internals are yours.
+Implement the design doc under `docs/plans/` via the **feature-gate flow**; its `### R<n>` blocks carry each requirement's acceptance criteria and tags. The criteria define *what*, you decide *how*.
 
-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.
 
-The feature-acceptance E2E test is the primary enforced gate and the primary enforced spec for the feature. The flow is always on: write the E2E first (red), implement the requirements back-to-back, then run the feature review and pause at the **ship checkpoint** — one fully-informed stop where you present the execution summary and the reviewer coverage table, with the full diff on request. Per-requirement checkpoints and reviews are **opt-in** — they fire only for requirements the design doc tags (default off); the feature gate covers everything else. A trivial design doc (no `## Feature acceptance`, per brainstorming's proportionality rule) skips the E2E steps and ships on the full suite; the one whole-feature review still runs at its ship checkpoint, its missing `### Feature review` tag defaulting to `auto`.
+Reference pointers name the section a step needs: run the section helper `scripts/ref.mjs <reference-path>#<anchor>` instead of reading the whole reference file.
+
+The feature-acceptance E2E test is the primary enforced gate and the primary enforced spec. The flow is always on: E2E first (red), the requirements back-to-back, then the feature review and the **ship checkpoint**. Per-requirement checkpoints and reviews are **opt-in** — they fire only when the design doc tags them, and the feature gate covers the rest. A trivial design doc (no `## Feature acceptance`) skips the E2E and ships on the full suite.
 
 ## Before you start
 
-Resolve local references and scripts from this installed skill directory. If a required resource is missing, report the blocker and stop before the affected action; do not silently skip its instructions.
+Resolve local references and scripts from this skill directory; a missing required resource is a blocker to report, never to skip.
 
 1. **Git state** — `git status` + `git log --oneline -5`; note uncommitted changes.
-2. **Find the doc** — first 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). Then list `docs/plans` recursively, excluding docs/plans/completed/, for `*-design.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/*'`. If no doc at all, ask the user to run `/skill:pwk-brainstorming` first; if several, ask which. Report one line, e.g. `Found: design "auth" — feature-gate execute (E2E written, implementing 2/5)`. A matching `*-progress.md` means this is a **resume** (see [Resume and progress](#resume-and-progress)). An umbrella part whose prior leaves are not all at `done`: surface their `Feature phase:` lines (matched header-only from each `<leaf>-progress.md`) as advisory context in the pre-flight report — no refusal, no reorder; build order stays advisory.
-3. **Workspace — choose this topic’s branch/worktree.** Before creating, switching, or adopting one, read [Workspace and resume details](references/resume.md#workspace). Reuse this topic’s branch (one umbrella = one branch); a different topic’s branch never hosts these commits. Uncommitted planning docs do not cross a worktree boundary: commit this topic folder on its branch before a new worktree handoff; when adopting an existing checkout with uncommitted docs here, copy the topic folder there, verify it, then remove the source copy. Read the reference's command order before acting. Offer/adopt only after checking existing worktrees; wait for the user's choice.
+2. **Find the doc** — first 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). Then list `docs/plans` recursively, excluding docs/plans/completed/, for `*-design.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/*'`; take each topic’s `Feature phase:` line header-only (`grep -m1 '^Feature phase:' <file>`). 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):
 
-## First run
+   ```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');
+   ```
 
-1. **Parse the design doc** — read every `### R<n>:` heading and its `### Checkpoints` / `### Review` tags (defaults `none` / `skip`), plus the feature-level `### Feature review` tag in the `## Feature acceptance` section. Requirements run in **listed order** (build order); do not reorder. Read the `## Feature acceptance` section — it is the E2E you gate on first. A trivial design doc (no `## Feature acceptance`) skips steps 5–6 below and goes straight into the implement phase.
-2. **Create the progress file** beside the design at `docs/plans/<date>-<topic>/<leaf>-progress.md`. Before creating it, read [Progress format](references/progress-format.md) for the exact template, header slots, and row vocabulary. Start at `Feature phase: e2e-written` (trivial doc: `implementing (0/N)`); `Setup: pending` when the design has `## Setup`, otherwise `Setup: n/a`.
+   No doc → ask for `/skill:pwk-brainstorming`; several → ask which. A matching `*-progress.md` means a **resume** ([Resume and progress](#resume-and-progress)); an umbrella part whose prior leaves are not all `done` shows their `Feature phase:` lines as advisory context.
+3. **Workspace** — choose this topic’s branch or worktree: read [Workspace and resume details](references/resume.md#workspace) first; it owns the command order including worktree handoffs. Reuse this topic’s branch (one umbrella = one branch); a different topic’s branch never hosts these commits. Offer or adopt only after checking existing worktrees, then wait for the user.
 
-3. **Setup pre-flight** *(only if the design doc has a `## Setup` section)* — install dependencies, apply migrations, seed data, then run the existing test suite. **⏸ CHECKPOINT: setup** — present results and wait for approval, then set `Setup: done` in the progress-file header so a resume can confirm it rather than assume it.
+## First run
 
-4. **Commit the design docs** — `git add docs/plans/<date>-<topic>/ && git commit -m "docs: add design doc"`. The add is scoped to the topic folder so another in-flight topic's uncommitted drafts never ride this commit (docs/lessons.md hygiene: one commit per topic).
-5. **Write the feature-acceptance E2E test (red).** Read the design doc's `## Feature acceptance` section and encode it as a real test file; run it; confirm it **fails** (it must — little or none of the feature exists yet). If it passes immediately, probe why before proceeding: the behavior may already exist, or the test may be asserting too little. If it still passes and the expected behavior looks wrong, **stop and present** rather than implementing against a wrong spec. Iterate it to green as you implement — fixing the implementation is the default, and you **stop and present only when you are genuinely blocked** (nothing you can do makes it pass, or the E2E itself is wrong). That stop is the reserved failure case; it is not the flow's default pause.
-6. **Notice, not a stop — report the E2E and continue.** Post 1–2 plain-language lines stating **what the E2E proves** ("this test proves that …"), plus the E2E test and its failing output, then go straight into the implement phase **without waiting for approval** — the `## Feature acceptance` text was approved during brainstorm, so there is nothing new here for the human to sign off. The notice is the window to object *before* implementation starts: a human who sees the E2E asserting the wrong thing says so, and you revise, re-run, and re-notice. Keep `Feature phase: e2e-written`.
+1. **Parse the design doc** — read every `### R<n>:` heading with its `### Checkpoints` / `### Review` tags and the feature-level `### Feature review` tag. Requirements run in **listed order**. The `## Feature acceptance` section is the E2E you gate on first; a trivial doc skips steps 5–6.
+2. **Create the progress file** beside the design at `docs/plans/<date>-<topic>/<leaf>-progress.md`, writing it with `scripts/progress.mjs` (read [Progress format](references/progress-format.md#progress-file) first for the template). Start at `Feature phase: e2e-written` (trivial doc: `implementing (0/N)`); `Setup: pending` when the design has `## Setup`, otherwise `Setup: n/a`.
+3. **Setup pre-flight** *(only if the design doc has a `## Setup` section)* — install dependencies, apply migrations, seed data, then run the suite. **⏸ CHECKPOINT: setup** — present results and wait for approval, then set `Setup: done`.
+4. **Commit the design docs** — `git add docs/plans/<date>-<topic>/ && git commit -m "docs: add design doc"`, scoped to the topic folder so another topic’s drafts never ride it.
+5. **Write the feature-acceptance E2E test (red)** — encode the `## Feature acceptance` section as a real test, run it, confirm it **fails**. If it passes immediately, probe why before proceeding — the behavior may already exist, or the test may be asserting too little — and if the expected behavior looks wrong, **stop and present** rather than implementing against a wrong spec. Iterate to green; fixing the implementation is the default, and you **stop and present only when you are genuinely blocked** (nothing makes it pass, or the E2E itself is wrong).
+6. **Notice, not a stop — report the E2E and continue.** Post 1–2 plain-language lines stating **what the E2E proves** ("this test proves that …") plus its failing output, then go straight into the implement phase **without waiting for approval** — the `## Feature acceptance` text was approved during brainstorm.
 
 ## Resume and progress
 
 `Feature phase` is one of: `e2e-written`, `implementing (k/N)`, `reviewing`, `ship-paused`, `done`.
 
-**Done cell:** `⬜` not started · `🔄` in progress · `✅` done · `❌` failed · `⏭` skipped. A row is **terminal** when its Done cell is `✅`, `❌`, or `⏭` — resolved, not necessarily passed. Only executing changes Done cells; a requirement under review stays `🔄` until a clean pass permits `✅`.
+**Done cell:** `⬜` not started · `🔄` in progress · `✅` done · `❌` failed · `⏭` skipped. A row is **terminal** when its Done cell is `✅`, `❌`, or `⏭` — resolved, not necessarily passed. Only executing changes Done cells; a reviewed row stays `🔄` until a clean pass permits `✅`.
 
-When a matching progress file exists, read [Resume](references/resume.md#resume) before routing. Read the header, Requirements table, and Execution summary only; `ship-paused` also needs Code digest. A pending setup checkpoint must be re-verified and approved before proceeding. Resume the first nonterminal row (`⬜`, `🔄`, blank); `✅`/`❌`/`⏭` are terminal, resolved rather than necessarily passed. Match `grep -m1 '^Feature phase:' <file>` for the phase header; `reviewing` resumes review; `ship-paused` re-presents and waits, never approves itself. Missing reviewer reports require review again before showing coverage.
+When a matching progress file exists, read [Resume](references/resume.md#resume), then the header, Requirements table, and Execution summary only (`ship-paused` also needs the Code digest). Resume the first nonterminal row (`⬜`, `🔄`, blank). Match `grep -m1 '^Feature phase:' <file>`; `reviewing` resumes review; `ship-paused` re-presents and waits, never approving itself. Missing reviewer reports require review again before coverage.
 
-Before any progress-row update or code-digest write, read [Progress format](references/progress-format.md). Update the matching row directly, `Last updated`, and `Feature phase`; write execution-summary content at the same time as ✅, and deviations at deviation time. A failed/skipped row carries its reason in the Requirement cell and reconciles its test coverage so the suite stays green.
+Read [Progress format](references/progress-format.md#progress-file) before any progress-row or code-digest write, and drive every structural edit through `scripts/progress.mjs` — it updates the row, `Last updated`, and `Feature phase` together, so write execution-summary content with the ✅ and deviations at deviation time. A failed/skipped row carries its reason and reconciles its test coverage.
 
 ## Implement phase
 
-Bugs found mid-execution are mandatory execution-summary content: record the fix in the requirement's `How it was built` cell and fill its Deviated? column at fix time — the summary must show what the feature actually cost to land.
+Bugs found mid-execution are mandatory execution-summary content: record the fix in the requirement’s `How it was built` cell and fill its Deviated? column then.
 
 Set `Feature phase: implementing (0/N)` and work the requirements in listed order. For each:
 
-1. **Mark the requirement 🔄** (Done column), read its `### Checkpoints` / `### Review` tags, and check `docs/lessons.md` for a rule that applies to this slice.
-2. **Write a meaningful test (red), then implement (green)** — TDD discipline. Encode the requirement's acceptance criteria as a real test through the public interface; run it; confirm it fails; implement to green. Skip the per-slice test only when the slice has no independent observable behavior (the feature E2E covers it). Follow the meaningful-test rules: (1) **Test observable behavior** — assert on what the feature produces or changes (a return value, persisted/updated data, an emitted event, an HTTP response) through its public interface; these assertions keep passing as the implementation changes. (2) **Write a per-slice test when the slice has its own observable behavior** — when a slice is pure config or a trivial extraction, the feature E2E covers it and a per-slice test is unnecessary. (Mirrored in `pwk-brainstorming` and `docs/lessons.md`.)
-3. **⏸ per-requirement checkpoint** *(fires only when the tag says so — opt-in)* — if `### Checkpoints: full`, stop and present after the tests and again after the slice is complete — both before its commit (the checkpoint rule below forbids committing before approval). With the default `none`, show the red→green inline and proceed.
-4. **Regression check after each commit** — run the **full existing suite**. This is what catches cross-requirement regressions (a later requirement breaking an earlier one's test). The **feature E2E stays red until the last requirement lands**; you may run it to watch the failure point advance, but it is gated only at the ship checkpoint — never expect it green per-commit.
-5. **Learn.** Caught a repeat mistake? Append a **generic** rule to `docs/lessons.md` (strip domain specifics).
-6. **Commit** the requirement with a clear message; record the requirement's commit hash in the Commit column.
-7. **Per-requirement review** *(fires only when the requirement's `### Review` tag is `parallel` or `inline` — default `skip`)* — review the slice now (see [Per-requirement review](#per-requirement-review-opt-in)); the row stays 🔄 through the review.
-8. **Mark the requirement ✅** and write its execution-summary row in the same step; advance `Feature phase: implementing (k/N)`. For a reviewed requirement this fires only after the review returns clean.
+1. **Mark the requirement 🔄** (Done column), read its `### Checkpoints` / `### Review` tags, and check `docs/lessons.md` for an applicable rule.
+2. **Write a meaningful test (red), then implement (green)** — encode the acceptance criteria as a real test through the public interface: red, then green; a slice with no independent observable behavior is covered by the feature E2E. **Test observable behavior** — assert on what the feature produces or changes (a return value, persisted data, an emitted event, an HTTP response) through its public interface.
+3. **⏸ per-requirement checkpoint** *(fires only when the tag says so)* — with `### Checkpoints: full`, stop and present after the tests and again after the slice is complete, both before its commit; with the default `none`, show the red→green inline and proceed.
+4. **Regression check after each commit** — run the **full existing suite**, which catches a later requirement breaking an earlier one’s test. The **feature E2E stays red until the last requirement lands**; never expect it green per-commit.
+5. **Learn.** Caught a repeat mistake? Append a **generic** rule to `docs/lessons.md`.
+6. **Commit** the requirement; record its commit hash in the Commit column.
+7. **Per-requirement review** *(only when the `### Review` tag is `parallel` or `inline`)* — review the slice now (see [Per-requirement review](#per-requirement-review-opt-in)); the row stays 🔄.
+8. **Mark the requirement ✅** and write its execution-summary row in the same step — Evidence cell non-empty, plain words plus pointer; advance `Feature phase: implementing (k/N)`. A reviewed requirement fires only after a clean review.
 
 ### Per-requirement review (opt-in)
 
-If the requirement's `### Review` tag is `parallel` or `inline` (default `skip`), review that slice at step 7 — read [Review mechanics](references/review.md) first and use its helper with `--scope requirement --requirement N`, limited to the commits and criteria of that requirement, written to `<design doc's directory>/<leaf>-review-packet-r<N>.md` (requirement-suffixed, so per-requirement packets never overwrite the feature packet or each other). The row stays 🔄 through the review: the four delegated roles — or the one `pwk-code-review` pass on `inline` — report findings, you apply the smell fixes yourself and commit them (the roles are read-only reporters), and a clean pass returns to step 8, which marks the row ✅. With `skip`, no per-requirement review — step 8 fires directly, and the feature-level review covers it.
-
-With the default `none`, no per-requirement stop fires — the per-requirement test still runs red→green, and the feature review covers implementation quality.
+If the requirement’s `### Review` tag is `parallel` or `inline` (default `skip`), review that slice at step 7: run the [Review mechanics](references/review.md#assemble-evidence) helper with `--scope requirement --requirement N` over that requirement’s commits and criteria, written to `<design doc's directory>/<leaf>-review-packet-r<N>.md`. The four delegated roles — or the one `pwk-code-review` pass on `inline` — only report; you apply the smell fixes and commit them, then a clean pass returns to step 8. With `skip`, no per-requirement review — step 8 fires directly, and the feature-level review covers it.
 
 ### Checkpoint gates are mandatory (when the tag says so)
 
 When a per-requirement checkpoint fires it is a **hard stop**:
-- Stop immediately; never proceed without explicit human approval.
+- Stop immediately; never proceed without explicit approval.
 - **Never** `git add` or `git commit` before approval at a checkpoint.
 - Set the progress phase/status **before** pausing.
 
@@ -72,41 +81,36 @@ When a per-requirement checkpoint fires it is a **hard stop**:
 
 When every requirement's Done cell is terminal — `✅` (done), `❌` (failed, reason in row), or `⏭` (skipped, reason in row):
 
-1. **Run the FULL test suite** — a failure means one requirement regressed another; fix it now, in execute context.
-2. **Run the feature-acceptance E2E** — the test you wrote at the start. It must be **green** now that all requirements have landed. (A `❌`/`⏭` requirement's assertions were reconciled when its row went terminal, so a still-red E2E still means a requirement is missing or wrong.) If it is still red, a requirement is missing or wrong — fix it before proceeding. (A trivial design doc has no `## Feature acceptance` — the full suite staying green is its gate instead.)
-3. **Run the feature review** (below) per the design's `### Feature review` tag — set `Feature phase: reviewing` first, so a mid-review resume routes into this step instead of the implement loop. (A trivial design doc carries no `### Feature review` tag — the missing tag defaults to `auto`, which resolves on its risk content; a trivial diff is typically `inline`, one pass, and there is no E2E to re-green — the full suite is the gate.) The review runs **before** your final approval, so the pause is fully informed. Apply smell fixes yourself and re-green (full suite + E2E) before pausing.
-4. **Write the code digest** into the progress file — the review has succeeded, findings are fixed, and the code is final: read the packet's `## Commits`, `## Changed files`, and `## Diff` sections and fill the progress file's `## Code digest` using [Progress format](references/progress-format.md) and its fill rules. If the packet is stale or missing, read [Review mechanics](references/review.md) and re-run the helper before writing. A resumed `Feature phase: reviewing` that completes lands on this same write point before the checkpoint is assembled. Never a gate: it explains the change, it does not block shipping.
-
-   **Reconcile the Flow against reviewed reality before writing it.** The Flow is written from what was reviewed, not from recollection: in `parallel` mode every hop must correspond to a path the tracing reviewer's report names — no hop invented, no reported path dropped. In `inline` mode there is no separate tracing report — the inline pass itself performs code tracing — so check the Flow against that pass's tracing findings and spec-coverage result instead. A discrepancy you cannot resolve is **surfaced** to the human in the ship checkpoint's findings status, never smoothed over by writing a Flow that omits the path.
+1. **Run the FULL test suite** — a failure means one requirement regressed another; fix it here. Then run `scripts/stage-check.mjs` and stop on a non-zero exit: the reviewed diff is a commit range, so anything uncommitted outside `docs/plans/` is missing from it.
+2. **Run the feature-acceptance E2E** — it must be **green** now that all requirements have landed; still red means a requirement is wrong.
+3. **Run the feature review** (below) per the design’s `### Feature review` tag — set `Feature phase: reviewing` first, so a mid-review resume routes into this step instead of the implement loop. The review runs **before** your final approval, so the pause is fully informed; apply smell fixes and re-green first.
+4. **Write the code digest** into the progress file — the review has succeeded and the code is final: read the packet’s `## Commits`, `## Changed files`, and `## Diff` sections and fill the file’s `## Code digest` per [Progress format](references/progress-format.md#code-digest); if the packet is stale, re-run the helper first. Never a gate — it explains the change, it does not block shipping. A resumed `Feature phase: reviewing` that completes lands on this same write point. **Reconcile the Flow against reviewed reality**: every hop must match a path the tracing report names — in `inline` mode the inline pass itself performs code tracing, so check the Flow against that pass’s tracing findings and spec-coverage result — no hop invented and none dropped; an unresolvable discrepancy is **surfaced** in the findings status.
 5. **Set `Feature phase: ship-paused`** and **⏸ CHECKPOINT: ship** — present, in this order:
-   - a green-gates line: full suite green, feature E2E green (trivial doc: the suite line alone — there is no E2E);
-   - the **execution summary** — what each requirement became, deviations included;
-   - the **verdict rows** — list every `❌`/`⏭` row with its reason, so the approval is given knowing what failed;
-   - the **code digest** — the plain-language change explanation from the progress file (summary, flow, gotchas, key files);
-   - the **coverage table** (one verdict row per R#) — from the spec-reviewer report in `parallel` mode, from the inline pass's spec alignment in `inline` mode;
+   - a green-gates line: full suite green, feature E2E green (trivial doc: the suite line alone);
+   - the **execution summary** — what each requirement became, deviations included, Evidence cells quoted;
+   - the **verdict rows** — list every `❌`/`⏭` row with its reason, so approval is given knowing what failed;
+   - the **code digest** — the plain-language change explanation from the progress file;
+   - the **coverage table** (one verdict row per R#) — from the spec-reviewer report in `parallel` mode, from the inline pass’s spec-coverage result otherwise;
    - findings status: fixed / open for the human;
-   - "full diff on request" — the raw diff is one command away; show a hunk only where a verdict or finding makes the human ask.
-
-   Wait for approval. **request changes** → fix, re-run the gates (and the review if the change is substantive), re-present.
+   - "full diff on request" — show a hunk only where a finding makes the human ask.
 
-A spec-reviewer report without a per-requirement coverage table is invalid — retry the role or complete it inline before pausing; the ship checkpoint is never presented without coverage. (Only the spec role owes the table; the tracing/smell/hazard reports keep their own report shapes.)
+   Wait for approval. **request changes** → fix, re-run the gates (and the review if substantive), re-present.
 
-The old "integration gate" is gone — the feature E2E at the ship checkpoint *is* the gate; there is no separate end pass.
+A spec-reviewer report without a per-requirement coverage table is invalid — retry the role or complete it inline before pausing.
 
 ## Feature review
 
-This is step 3 of the [ship checkpoint](#ship-checkpoint-all-requirements-terminal--review-merged): it runs **before** the final human approval, so the pause is fully informed. Run **one** review over the **whole feature diff**, driven by the design doc's `### Feature review` tag — exactly one per part, never once per requirement. This is the single thorough review — per-requirement reviews, if any, only saw slices in isolation.
-
-**Assemble the review packet first** — read [Review mechanics](references/review.md), then invoke the installed skill’s `scripts/build-review-packet.py` with explicit `--project`, `--design`, `--progress`, and `--scope feature`. Check `python3 --version` for Python 3.9+ and helper availability before this step; if Python is missing or unavailable, report the blocker, request a suitable runtime, and stop. Do not auto-install a runtime, use a fallback implementation, or claim packet generation succeeded. No packet byte passes through model output. A failed helper is not usable evidence or approval; correct the inputs, never guess ranges. The helper writes `<leaf>-review-packet.md` beside the design; opt-in packets use `<leaf>-review-packet-r<N>.md`.
+Run **one** review over the **whole feature diff**, driven by the design doc’s `### Feature review` tag — exactly one per part, never once per requirement.
 
-- **Resolve the tag first.** `auto` (the default, and what a missing tag means) resolves on the design's own production-risk content: if the design carries a non-empty `## Production-risk areas` section, or any requirement carries a non-empty `### Production-risk notes`, resolve to `parallel`; otherwise resolve to `inline`. An explicit `parallel` or `inline` is used as written and always wins over `auto` — explicit tag wins in both directions, so a human who wants one pass on a risky design gets one pass.
+**Assemble the review packet first** — run `scripts/stage-check.mjs` and stop on a non-zero exit, then read [Review mechanics](references/review.md#assemble-evidence) and invoke `scripts/build-review-packet.mjs` with explicit `--project`, `--design`, `--progress`, and `--scope feature`. Check `node --version`; if missing, report the blocker, request a suitable runtime, and stop — never auto-install, use a fallback, or claim the packet succeeded. No packet byte passes through model output; a failed helper is never evidence or approval. It writes `<leaf>-review-packet.md` beside the design; opt-in packets use `<leaf>-review-packet-r<N>.md`.
 
-- **`parallel`** — use the host’s `parallel-review` capability for four independent, fresh-context, read-only roles: `pwk-spec-reviewer`, `pwk-tracing-reviewer`, `pwk-smell-reviewer`, `pwk-hazard-reviewer`. Follow [Review mechanics](references/review.md#delegate-or-review-inline): a one-liner packet-file pointer with role framing last; the packet never appears in spawn arguments. Collect one outcome per role. Reviewers only report; you apply smell fixes, commit, and re-green full suite + E2E. Surface trace/spec/hazard findings to the human.
+- **Resolve the tag first.** `auto` (the default, and what a missing tag means) resolves on the design’s production-risk content: a non-empty `## Production-risk areas` section or any `### Production-risk notes` → `parallel`; otherwise `inline`. An explicit tag wins over `auto` in both directions.
+- **`parallel`** — use the host’s `parallel-review` capability for four independent, fresh-context, read-only roles: `pwk-spec-reviewer`, `pwk-tracing-reviewer`, `pwk-smell-reviewer`, `pwk-hazard-reviewer`. Follow [Review mechanics](references/review.md#delegate-or-review-inline): a one-liner packet-file pointer with role framing last — the packet never appears in spawn arguments. Collect one outcome per role. Reviewers only report; you apply smell fixes, commit, and re-green. Surface trace/spec/hazard findings to the human.
 - **`inline`** — perform `/skill:pwk-code-review` over the whole diff as a single pass.
-- **Fallback** — if compatible capability is absent, required read-only/fresh-context/bounded constraints cannot be proved, or delegation fails, do the missing work inline. Retain successful reports; required missing roles mean review is incomplete.
-- **Refresh** — if commits land during review, use [Review mechanics](references/review.md) to refresh the packet before any replacement role or digest write. Append requirement-fix IDs before a requirement refresh; keep the initial ID. Packet creation never substitutes for review or approval.
+- **Fallback** — if compatible capability is absent, constraints cannot be proved, or delegation fails, do the missing work inline. Retain successful reports; a missing required role leaves the review incomplete.
+- **Refresh** — if commits land during review, refresh the packet before any replacement role or digest write, appending requirement-fix IDs and keeping the initial ID. Packet creation never substitutes for review or approval.
 
-On success, continue assembling the ship checkpoint; once the human approves it — knowing what failed — set `Feature phase: done`. (An umbrella part's gate is its own progress file; `pwk-finalizing` reads every part's file, and a `❌` in any part blocks the umbrella until the human sends the work back or explicitly types `--force-failed`.)
+On success, continue assembling the ship checkpoint; once the human approves it, set `Feature phase: done`. (An umbrella part’s gate is its own progress file; `pwk-finalizing` reads every part's file, and a `❌` in any part blocks the umbrella until the human types `--force-failed`.)
 
 ## Tags reference
 
@@ -118,7 +122,7 @@ The design doc tags each requirement and the feature level:
 | `### Review` | `skip \| parallel \| inline` | `skip` | per-requirement review — `parallel` = four delegated reviewers; `inline` = one `pwk-code-review` pass |
 | `### Feature review` | `auto \| parallel \| inline` | `auto` | the one whole-feature review — always run, never per requirement (a trivial doc carries no tag; the missing tag resolves to `auto`) |
 
-Nothing is tagged silently: **only the human tags** a slice, and the feature review covers everything else. How each tag resolves lives where its decision executes — the [per-requirement review](#per-requirement-review-opt-in) and the [feature review](#feature-review).
+Nothing is tagged silently: **only the human tags** a slice; each tag resolves where its decision executes.
 
 ## User override commands
 
@@ -131,14 +135,14 @@ Nothing is tagged silently: **only the human tags** a slice, and the feature rev
 
 ## Receiving feedback (outside a checkpoint)
 
-Verify the criticism against the code, evaluate the suggestion, then implement (with tests) or push back with evidence. Don't blindly apply.
+Verify the criticism against the code, then implement (with tests) or push back with evidence.
 
 ## After the feature review
 
-The feature is implemented, reviewed, and approved at the ship checkpoint. Determine the next step from the artifacts (the human drives every transition — this is a suggestion, not a gate; the overview check below is **folder-local** — read the `overview.md` beside this leaf, inside the same `docs/plans/<date>-<topic>/` directory, never a repo-wide `docs/plans/**/overview.md`, and always excluding docs/plans/completed/, so an archived or sibling umbrella never routes):
+Determine the next step from the artifacts — a suggestion, not a gate. The overview check is **folder-local** — the `overview.md` beside this leaf, inside the same `docs/plans/<date>-<topic>/` directory, never a repo-wide `docs/plans/**/overview.md`, and always excluding docs/plans/completed/:
 
 - **Standalone topic** (no `overview.md` in the topic folder) → suggest `/skill:pwk-finalizing`.
-- **Umbrella part** (an `overview.md` sits beside this leaf) → read the overview's `## Parts (build order)` roster. The umbrella is complete when every roster leaf has a `done` progress file → suggest `/skill:pwk-finalizing` (one PR for the whole umbrella). Otherwise look at the **next leaf** — the **first roster part with no `done` progress file**, not the next entry in build order: build order is advisory, so a part built out of order must not be skipped by the suggestion. That leaf with no progress file and no `<leaf>-design.md` is unstarted → suggest `/skill:pwk-brainstorming` for it; with a `<leaf>-design.md` but no progress file it is designed but never executed → suggest `/skill:pwk-executing-tasks` (its pre-flight picks the design doc up — the same state pwk-status renders as `design`); with a progress file that is not `done` it is mid-flight → suggest `/skill:pwk-executing-tasks` to resume that leaf instead.
+- **Umbrella part** (an `overview.md` sits beside this leaf) → read its `## Parts (build order)` roster; complete when every roster leaf has a `done` progress file → `/skill:pwk-finalizing` (one PR for the whole umbrella). Otherwise the **next leaf** is the first roster part with no `done` progress file — not the next entry in build order: a leaf with no progress file and no `<leaf>-design.md` → `/skill:pwk-brainstorming`; one with a `<leaf>-design.md` but no progress file → `/skill:pwk-executing-tasks`; one whose progress file is not `done` → `/skill:pwk-executing-tasks` to resume it.
 
 Present:
 
@@ -149,7 +153,6 @@ Feature phase: done
 | # | Done | Requirement |
 |---|------|-------------|
 | 1 | ✅ | <name> |
-| … | … | … |
 
    - Next part: /skill:pwk-brainstorming (unstarted leaf) or /skill:pwk-executing-tasks (designed or mid-flight) — per the routing above   ← umbrella, more parts remain
    - Ship: /skill:pwk-finalizing                          ← standalone, or last umbrella part
@@ -157,10 +160,10 @@ Feature phase: done
 
 ## If you're stuck
 
-1. Re-read the requirement's acceptance criteria — you may have drifted.
-2. Check `git log` for context. Ask the user — clarify beats guessing.
-3. Still stuck → discard uncommitted changes (`git restore .`); if already committed, also `git revert` the requirement's commit(s). **Never leave a failed requirement's partial work on the shipped branch.**
-4. Set its Done cell `❌` (with the reason as a suffix in the Requirement cell), reconcile its test coverage, and move on. Check `docs/lessons.md` — a prior lesson may apply.
+1. Re-read the requirement’s acceptance criteria — you may have drifted.
+2. Check `git log` for context; ask the user — clarify beats guessing.
+3. Still stuck → discard uncommitted changes (`git restore .`); if already committed, also `git revert` the requirement’s commit(s). **Never leave a failed requirement’s partial work on the shipped branch.**
+4. Set its Done cell `❌` (with the reason as a suffix in the Requirement cell), reconcile its test coverage, and move on; `docs/lessons.md` may hold an applicable rule.
 
 ## Contract index
 
@@ -189,7 +192,7 @@ Feature phase: e2e-written
 ## Requirements
 | # | Done | Requirement | Per-req ceremony | Commit |
 ## Execution summary
-| R# | Requirement | How it was built | Deviated? |
+| R# | Requirement | How it was built | Deviated? | Evidence |
 ## Code digest
 ### Summary
 ### Flow