@tianhai/pi-workflow-kit 2.8.1 → 2.11.0

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

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

package/skills/pwk-finalizing/SKILL.md

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

package/skills/pwk-status/SKILL.md

@@ -5,7 +5,7 @@ description: "Show all active pipeline topics and their phase/progress. Use when
 
 # Status
 
-Report on in-flight pipelines in this working tree (a worktree has its own `docs/plans/`, so run status in each). Read-only. This skill **does not unlock the guard** — it needs no writes, so it runs fine inside the design read-only phase. If you want source edits after a status check, invoke the skill for the next phase yourself (the guard follows the skill).
+Report on in-flight pipelines in this working tree (a worktree has its own `docs/plans/`, so run status in each). Read-only: this skill **does not unlock the guard**, so it runs fine inside the design read-only phase — invoke the next phase's skill yourself if you want source edits (the guard follows the skill).
 
 Any command or tool recipe in this skill is an example, not the requirement — when your host grants a better tool for an operation (a sandboxed batch executor — 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.
 
@@ -24,15 +24,15 @@ Any command or tool recipe in this skill is an example, not the requirement —
    ```
 
 2. **State per topic/part — map the header.** The body (execution summary, review reports, code digest) carries nothing status needs, and neither do design docs. A header reading `Setup: pending` renders the topic as **`awaiting setup`** — the setup checkpoint was never approved (the slot is only ever written when the design doc has a `## Setup` section, so the header alone decides — no design-doc read) — ahead of any phase-derived state below. Map the line to the displayed state:
-   - `done` → **`done`** — terminal, never shown as in-flight; every row is resolved (`✅` passed, `❌` failed, `⏭` skipped — resolved, not necessarily passed). Append the tally as `N/N` when wanted — the Requirements-table row count, scoped to that table because the Execution summary rows share the same `| <n> |` row shape and a bare grep would double it (e.g. `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep -c '^| [0-9]'`) — and when that same scoped range finds any — `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep -c '^| [0-9].*❌'` / `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep -c '^| [0-9].*⏭'` (the same scoping, so Execution-summary rows — which share the row shape — and prose mentions of the glyphs do not inflate the count) — render the counts, e.g. `done (1 ❌ · 1 ⏭)`, noting finalizing will require `--force-failed` while `❌` rows stand
+   - `done` → **`done`** — terminal, never shown as in-flight; every row is resolved (`✅` passed, `❌` failed, `⏭` skipped — resolved, not necessarily passed). Append the tally as `N/N` when wanted — the Requirements-table row count, scoped to that table because the Execution summary rows share the same `| <n> |` row shape and a bare grep would double it (e.g. `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep -c '^| [0-9]'`). Counting `❌`/`⏭` rows over that same scoped range (`sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep -c '^| [0-9].*❌'` / `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep -c '^| [0-9].*⏭'` — the same scoping, so Execution-summary rows and prose mentions of the glyphs do not inflate the count) renders the counts, e.g. `done (1 ❌ · 1 ⏭)`, noting finalizing will require `--force-failed` while `❌` rows stand
    - `implementing (k/N)` → `execute k/N` (the tally rides on the line itself — no extra read)
    - `e2e-written` → `execute 0/N` (the E2E is written and the run continues into implementation — never shown as a paused state; N comes from the same Requirements-table-scoped row count as `done` — so no tally renders without a defined source)
    - `reviewing` → `review`
-   - `ship-paused` → `ship-paused` — next: `/skill:pwk-executing-tasks` (approve the ship checkpoint). Never hint finalizing: only `done` routes there.
+   - `ship-paused` → `ship-paused` — next: `/skill:pwk-executing-tasks` (approve the ship checkpoint); only `done` routes to finalizing.
    - no progress file, only `*-design.md` → `design` — next: `/skill:pwk-executing-tasks`
    - roster-only (named in the overview, no artifacts) → `not started`
    - no parseable `Feature phase` line → `execute` (with tally if parseable).
-3. **Group by umbrella** — for each `overview.md`, read its **`## Parts (build order)`** roster (the heading and the `N. <part> — <scope>` item shape are lint-pinned) and roll the parts up by state (the overview carries no status): done parts, in-flight parts (design, execute, review, ship-paused, awaiting setup), not-started parts. A part sitting at the feature-E2E notice (`e2e-written`) rolls up as execute — the notice is a routing moment, not a bucket of its own. Print one roll-up line — `<topic> (umbrella): n done · n in-flight · n not-started` — and when every part is `done` append `— all parts done, ready for /skill:pwk-finalizing`. A `done` single-leaf topic gets the same hint. Once the topic finalizes, its folder — overview included — is disposed, so it no longer appears here. Topics without an overview print flat.
+3. **Group by umbrella** — for each `overview.md`, read its **`## Parts (build order)`** roster (the heading and the `N. <part> — <scope>` item shape are lint-pinned) and roll the parts up by state (the overview carries no status): done, in-flight (design, execute, review, ship-paused, awaiting setup), not-started. A part at the feature-E2E notice (`e2e-written`) rolls up as execute — a routing moment, not a bucket of its own. Print one roll-up line — `<topic> (umbrella): n done · n in-flight · n not-started` — and when every part is `done` append `— all parts done, ready for /skill:pwk-finalizing`; a `done` single-leaf topic gets the same hint. Once the topic finalizes its folder — overview included — is disposed, so it no longer appears here. Topics without an overview print flat.
 4. Print a compact table, grouped under any umbrellas, e.g.:
 
    ```text

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

@@ -1,194 +0,0 @@
-#!/usr/bin/env python3
-"""Read-only validation of the workflow's Markdown design structure (Python 3.9+)."""
-
-import argparse
-from dataclasses import dataclass
-from pathlib import Path
-import re
-import sys
-from typing import List, Optional, Tuple
-
-
-TAG_VALUES = {
-    "Checkpoints": ("none", "full"),
-    "Review": ("skip", "parallel", "inline"),
-    "Feature review": ("auto", "parallel", "inline"),
-}
-HEADING = re.compile(r"^ {0,3}(#{1,6})[ \t]+(.+?)\s*#*\s*$")
-REQUIREMENT = re.compile(r"^R([1-9][0-9]*):\s*(.*)$")
-REQUIREMENT_LIKE = re.compile(r"^R(?:[0-9]|\s*:)")
-CRITERIA = re.compile(r"^\*\*Acceptance criteria\*\*(?:\s*(?:—|–|-|:).*)?$")
-
-
-@dataclass
-class Heading:
-    level: int
-    title: str
-    index: int
-
-
-def visible_lines(text: str) -> Tuple[List[str], List[str]]:
-    """Blank fenced examples, retaining indexes for diagnostics. Not a Markdown renderer."""
-    lines = []
-    errors = []
-    fence = ""
-    fence_line = 0
-    for number, line in enumerate(text.splitlines(), 1):
-        if fence:
-            if re.fullmatch(r" {0,3}" + re.escape(fence[0]) + "{" + str(len(fence)) + r",}[ \t]*", line):
-                fence = ""
-            lines.append("")
-            continue
-        opening = re.match(r"^ {0,3}(`{3,}|~{3,})(.*)$", line)
-        if opening and not (opening[1][0] == "`" and "`" in opening[2]):
-            fence = opening[1]
-            fence_line = number
-            lines.append("")
-        else:
-            lines.append(line)
-    if fence:
-        errors.append(f"line {fence_line}: unclosed code fence; close it before validating")
-    return lines, errors
-
-
-def has_content(lines: List[str]) -> bool:
-    # Check presence, not whether the assertion is true, testable, or sufficiently specific.
-    for line in lines:
-        text = re.sub(r"^\s*(?:[-+*]|[0-9]+[.)])\s*", "", line).strip()
-        if text and re.search(r"\w", text):
-            return True
-    return False
-
-
-def criteria_body(lines: List[str], start: int, end: int) -> List[str]:
-    """A heading or another bold section label terminates criteria, not just the next R ID."""
-    result = []
-    for line in lines[start:end]:
-        if HEADING.match(line) or re.match(r"^\s*\*\*[^*]+\*\*", line):
-            break
-        result.append(line)
-    return result
-
-
-def validate(text: str) -> Tuple[List[str], List[str]]:
-    lines, errors = visible_lines(text)
-    headings = []
-    for index, line in enumerate(lines):
-        match = HEADING.match(line)
-        if match:
-            headings.append(Heading(len(match[1]), match[2], index))
-    for heading in headings:
-        if REQUIREMENT_LIKE.match(heading.title) and heading.level != 3:
-            errors.append(f"line {heading.index + 1}: {heading.title} must use a ### requirement heading")
-    requirements = [h for h in headings if h.level == 3 and REQUIREMENT_LIKE.match(h.title)]
-    features = [h for h in headings if h.level == 2 and h.title == "Feature acceptance"]
-    summaries = []
-
-    if not requirements:
-        errors.append("required requirement block missing; add ### R1: <name> with Acceptance criteria")
-    seen = set()
-    for expected, heading in enumerate(requirements, 1):
-        match = REQUIREMENT.fullmatch(heading.title)
-        if not match:
-            errors.append(f"line {heading.index + 1}: malformed requirement '{heading.title}'; use ### R{expected}: <name>")
-            continue
-        number = int(match[1])
-        if number in seen:
-            errors.append(f"line {heading.index + 1}: duplicate requirement R{number}")
-        elif number != expected:
-            errors.append(f"line {heading.index + 1}: expected R{expected}, found R{number}; IDs must be sequential in document order")
-        seen.add(number)
-        if not match[2].strip():
-            errors.append(f"line {heading.index + 1}: R{number} requires a nonempty name")
-
-    intro_end = requirements[0].index if requirements else len(lines)
-    short = any(re.match(r"^In short:\s*\S.*$", line) for line in lines[:intro_end])
-    full_format = any(h.level == 2 and h.title in ("At a glance", "Requirements") for h in headings)
-    trivial = short and not full_format and len(requirements) == 1 and requirements[0].title.startswith("R1:") and not features
-    if not trivial and not features:
-        errors.append("## 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 len(features) > 1:
-        errors.append("duplicate ## Feature acceptance section; keep exactly one")
-
-    # Record ownership so a valid-looking tag cannot silently land outside its section.
-    owned_tags = set()
-
-    def tags(start: int, end: int, names: Tuple[str, ...], owner: str) -> dict:
-        values = {name: TAG_VALUES[name][0] for name in names}
-        found = set()
-        for heading in headings:
-            if not start <= heading.index < end:
-                continue
-            for name in names:
-                if heading.level != 3 or not re.match(re.escape(name) + r"\b", heading.title):
-                    continue
-                owned_tags.add(heading.index)
-                if name in found:
-                    errors.append(f"line {heading.index + 1}: duplicate {name} tag in {owner}")
-                found.add(name)
-                value = heading.title[len(name):].strip()
-                value = value[1:].strip() if value.startswith(":") else ""
-                if value not in TAG_VALUES[name]:
-                    allowed = " | ".join(TAG_VALUES[name])
-                    errors.append(f"line {heading.index + 1}: invalid {name} tag in {owner}; expected {allowed}")
-                else:
-                    values[name] = value
-        return values
-
-    for heading in requirements:
-        end = next((h.index for h in headings if h.index > heading.index and (h.level <= 2 or h in requirements)), len(lines))
-        criteria_end = next((h.index for h in headings if heading.index < h.index < end), end)
-        labels = [i for i in range(heading.index + 1, criteria_end) if CRITERIA.fullmatch(lines[i].strip())]
-        owner = heading.title.split(":", 1)[0]
-        if not labels:
-            errors.append(f"line {heading.index + 1}: {owner} needs a standalone **Acceptance criteria** section")
-        elif len(labels) > 1:
-            errors.append(f"line {labels[1] + 1}: {owner} has duplicate Acceptance criteria sections")
-        elif not has_content(criteria_body(lines, labels[0] + 1, end)):
-            errors.append(f"line {labels[0] + 1}: {owner} Acceptance criteria is empty; add a criterion before the next section")
-        values = tags(heading.index + 1, end, ("Checkpoints", "Review"), owner)
-        summaries.append(f"{owner}: Checkpoints={values['Checkpoints']}, Review={values['Review']}")
-
-    for heading in features:
-        end = next((h.index for h in headings if h.index > heading.index and h.level <= 2), len(lines))
-        if not has_content(criteria_body(lines, heading.index + 1, end)):
-            errors.append(f"line {heading.index + 1}: Feature acceptance is empty; add an end-to-end criterion before its review tag")
-        values = tags(heading.index + 1, end, ("Feature review",), "Feature acceptance")
-        summaries.append(f"Feature review={values['Feature review']}")
-
-    for heading in headings:
-        for name in TAG_VALUES:
-            if re.match(re.escape(name) + r"\b", heading.title) and heading.index not in owned_tags:
-                owner = "## Feature acceptance" if name == "Feature review" else "a ### R<n>: requirement block"
-                errors.append(f"line {heading.index + 1}: {name} must be a ### tag inside {owner}")
-    return errors, summaries
-
-
-def main(argv: Optional[List[str]] = None) -> int:
-    parser = argparse.ArgumentParser(
-        description="Read-only structural design validation. Requires Python 3.9+; standard library only. Semantic correctness is not verified.",
-        epilog="Pass an explicit design path. Absolute paths are used directly; relative paths resolve from the caller's working directory (cwd), not the installed skill directory.",
-    )
-    parser.add_argument("design", type=Path, help="UTF-8 Markdown design file (quote paths containing spaces)")
-    args = parser.parse_args(argv)
-    if sys.version_info < (3, 9):
-        print("Python 3.9+ is required; supply a compatible runtime before validation.", file=sys.stderr)
-        return 2
-    try:
-        text = args.design.read_text(encoding="utf-8")
-    except (OSError, UnicodeError, ValueError) as error:
-        print(f"{args.design}: cannot read UTF-8 design: {error}", file=sys.stderr)
-        return 2
-    errors, summaries = validate(text)
-    if errors:
-        for error in errors:
-            print(f"{args.design}: {error}", file=sys.stderr)
-        return 1
-    print(f"{args.design}: structural checks passed. Semantic correctness is not verified.")
-    for summary in summaries:
-        print(f"  {summary}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())