@tianhai/pi-workflow-kit 2.2.0 → 2.5.0

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

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+"""Build review evidence from explicit, immutable Git bounds. Python 3.9+, stdlib only."""
+
+import argparse
+import os
+from pathlib import Path
+import re
+import subprocess
+import sys
+import tempfile
+
+
+class PacketError(Exception):
+    pass
+
+
+class Document:
+    """Keep original lines for evidence; inspect headings only outside fenced examples."""
+
+    def __init__(self, path):
+        with path.open(encoding='utf-8', newline='') as source:
+            self.lines = source.readlines()
+        self.headings = []
+        self.visible = set()
+        fence = None
+        for index, line in enumerate(self.lines):
+            marker = re.match(r'^ {0,3}(`{3,}|~{3,})(.*)$', line.rstrip('\r\n'))
+            if fence:
+                if marker and marker[1][0] == fence[0] and len(marker[1]) >= len(fence) and not marker[2].strip():
+                    fence = None
+                continue
+            if marker:
+                fence = marker[1]
+                continue
+            self.visible.add(index)
+            heading = re.match(r'^ {0,3}(#{1,6})\s+(.+?)\s*#*\s*$', line.rstrip('\r\n'))
+            if heading:
+                self.headings.append((index, len(heading[1]), heading[2]))
+        if fence:
+            raise PacketError(f'{path.name}: unclosed code fence')
+
+    def section(self, title, level=2, required=False):
+        matches = [h for h in self.headings if h[1:] == (level, title)]
+        if len(matches) > 1 or (required and not matches):
+            raise PacketError(f'expected one {title} section; found {len(matches)}')
+        if not matches:
+            return None
+        start = matches[0][0]
+        end = next((i for i, depth, _ in self.headings if i > start and depth <= level), len(self.lines))
+        return start, end
+
+    def text(self, start, end):
+        return ''.join(self.lines[start:end])
+
+
+def git(project, *args):
+    result = subprocess.run(
+        ['git', '-C', str(project), *args], stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+        env={**os.environ, 'GIT_OPTIONAL_LOCKS': '0', 'GIT_TERMINAL_PROMPT': '0'},
+    )
+    if result.returncode:
+        invocation = ' '.join(['git', *args])
+        raise PacketError(f'{invocation} failed: {result.stderr.decode("utf-8", errors="replace").strip()}')
+    return result.stdout.decode('utf-8', errors='replace')
+
+
+def resolve_input(project, value):
+    path = Path(value)
+    return (path if path.is_absolute() else project / path).resolve(strict=True)
+
+
+def paths(args):
+    project = Path(args.project).resolve(strict=True)
+    if Path(git(project, 'rev-parse', '--show-toplevel').strip()).resolve() != project:
+        raise PacketError('--project must be the Git worktree root')
+    for value in (args.design, args.progress):
+        supplied = Path(value)
+        supplied = Path(os.path.abspath(supplied if supplied.is_absolute() else project / supplied))
+        lexical_project = Path(os.path.abspath(args.project))
+        try:
+            relative_input = supplied.relative_to(lexical_project)
+        except ValueError:
+            relative_input = supplied.relative_to(project)
+        current = project
+        for part in relative_input.parts:
+            current = current / part
+            if current.is_symlink():
+                raise PacketError('design/progress paths must not traverse symlinks')
+    design = resolve_input(project, args.design)
+    progress = resolve_input(project, args.progress)
+    relative = design.relative_to(project / 'docs' / 'plans')
+    if len(relative.parts) != 2 or relative.parts[0] == 'completed' or not design.name.endswith('-design.md'):
+        raise PacketError('design must be docs/plans/<topic>/<leaf>-design.md in an active topic')
+    leaf = design.name[:-len('-design.md')]
+    if not leaf or progress != design.with_name(f'{leaf}-progress.md'):
+        raise PacketError('progress must be the matching <leaf>-progress.md beside the design')
+    # Resolving inputs must not route a packet write through symlinked topic directories.
+    lexical_topic = project / 'docs' / 'plans' / relative.parts[0]
+    for directory in (project / 'docs', project / 'docs' / 'plans', lexical_topic):
+        if directory.is_symlink():
+            raise PacketError('symlink topic directories are not writable packet destinations')
+    suffix = '' if args.scope == 'feature' else f'-r{args.requirement}'
+    destination = design.with_name(f'{leaf}-review-packet{suffix}.md')
+    validate_destination(destination)
+    return project, design, progress, destination
+
+
+def validate_destination(path):
+    if path.is_symlink() or (path.exists() and not path.is_file()):
+        raise PacketError('packet destination must be a regular file, not a symlink or directory')
+
+
+def requirements(document):
+    region = document.section('Requirements', required=True)
+    headings = []
+    for index, depth, title in document.headings:
+        match = re.match(r'^R([1-9][0-9]*):\s*\S', title)
+        if depth == 3 and re.match(r'^R[0-9]', title) and not match:
+            raise PacketError('malformed requirement heading')
+        if depth == 3 and match:
+            if not region[0] < index < region[1]:
+                raise PacketError('requirement heading outside Requirements section')
+            headings.append((int(match[1]), index))
+    numbers = [number for number, _ in headings]
+    if not numbers or len(set(numbers)) != len(numbers):
+        raise PacketError('missing or duplicate requirement headings')
+    return headings, region
+
+
+def progress_rows(document, project, design):
+    first_heading = next((i for i, depth, _ in document.headings if depth == 2), len(document.lines))
+    pointers = [document.lines[i].strip()[8:] for i in document.visible
+                if i < first_heading and document.lines[i].startswith('Design: ')]
+    if len(pointers) != 1 or resolve_input(project, pointers[0]) != design:
+        raise PacketError('progress Design header must identify the selected design exactly once')
+    start, end = document.section('Requirements', required=True)
+    lines = [document.lines[i].strip() for i in range(start + 1, end)
+             if i in document.visible and document.lines[i].strip()]
+    if len(lines) < 3:
+        raise PacketError('missing Requirements table')
+
+    def cells(line):
+        if not line.startswith('|') or not line.endswith('|'):
+            raise PacketError('malformed Requirements table row')
+        return [cell.strip() for cell in re.split(r'(?<!\\)\|', line)[1:-1]]
+
+    header = cells(lines[0])
+    if header != ['#', 'Done', 'Requirement', 'Per-req ceremony', 'Commit']:
+        raise PacketError('Requirements table must have #, Done, Requirement, Per-req ceremony, Commit columns')
+    separator = cells(lines[1])
+    if len(separator) != 5 or not all(re.fullmatch(r':?-+:?', cell) for cell in separator):
+        raise PacketError('malformed Requirements table separator')
+    rows = {}
+    for line in lines[2:]:
+        row = cells(line)
+        if len(row) != 5 or not re.fullmatch(r'[1-9][0-9]*', row[0]):
+            raise PacketError('malformed Requirements table row')
+        number = int(row[0])
+        if number in rows:
+            raise PacketError(f'duplicate R{number} progress row')
+        if row[1] not in ('', '⬜', '🔄', '✅', '❌', '⏭'):
+            raise PacketError(f'R{number}: invalid Done cell')
+        rows[number] = row
+    return rows
+
+
+def bounds(project, rows, headings, args):
+    numbers = [number for number, _ in headings]
+    position = numbers.index(args.requirement) if args.scope == 'requirement' else None
+    relevant = numbers if position is None else numbers[max(0, position - 1):position + 1]
+    if set(rows) - set(numbers):
+        raise PacketError('progress contains requirements absent from the design')
+    recorded = {}
+    previous = None
+    current_head = git(project, 'rev-parse', '--verify', 'HEAD^{commit}').strip()
+    for number in relevant:
+        if number not in rows:
+            raise PacketError(f'R{number}: missing progress row')
+        row = rows[number]
+        value = row[4]
+        if value in ('', '—', '-'):
+            if row[1] not in ('❌', '⏭'):
+                raise PacketError(f'R{number}: missing Commit entry')
+            recorded[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.
+        entries = value.split()
+        if not all(re.fullmatch(r'[0-9a-fA-F]{7,64}', entry) for entry in entries):
+            raise PacketError(f'R{number}: Commit must contain only ordered hexadecimal commit IDs')
+        commits = []
+        for entry in entries:
+            commit = git(project, 'rev-parse', '--verify', f'{entry}^{{commit}}').strip()
+            if previous:
+                if previous == commit:
+                    raise PacketError('duplicate or overlapping recorded commits')
+                git(project, 'merge-base', '--is-ancestor', previous, commit)
+            git(project, 'merge-base', '--is-ancestor', commit, current_head)
+            commits.append(commit)
+            previous = commit
+        recorded[number] = commits
+    if args.scope == 'feature':
+        first = next((commits[0] for commits in recorded.values() if commits), None)
+        if not first:
+            raise PacketError('no recorded commits; cannot infer a feature base')
+        return git(project, 'rev-parse', '--verify', f'{first}^').strip(), current_head
+    selected = recorded[args.requirement]
+    if not selected:
+        raise PacketError('selected requirement has no recorded bound')
+    if position == 0:
+        base = git(project, 'rev-parse', '--verify', f'{selected[0]}^').strip()
+    else:
+        prior = recorded[numbers[position - 1]]
+        if not prior:
+            raise PacketError('previous requirement has no recorded bound; cannot guess a range')
+        base = prior[-1]
+    return base, selected[-1]
+
+
+def evidence(document, headings, region, args):
+    feature = document.section('Feature acceptance')
+    if feature and feature[0] < region[1]:
+        raise PacketError('Feature acceptance must follow Requirements')
+    if args.scope == 'feature':
+        start = headings[0][1]
+        end = feature[0] if feature else len(document.lines)
+    else:
+        position = next(i for i, (number, _) in enumerate(headings) if number == args.requirement)
+        start = headings[position][1]
+        end = headings[position + 1][1] if position + 1 < len(headings) else region[1]
+    criteria = document.text(start, end)
+    acceptance = ''
+    if feature:
+        stop = next((i for i, depth, title in document.headings
+                     if feature[0] < i < feature[1] and depth == 3 and title.startswith('Feature review:')), feature[1])
+        acceptance = document.text(feature[0], stop)
+    notes = []
+    for index, depth, title in document.headings:
+        if depth == 3 and title == 'Production-risk notes' and start <= index < end:
+            stop = next((i for i, d, t in document.headings if i > index and
+                         (d <= 2 or (d == 3 and re.match(r'^R[0-9]+:', t)))), len(document.lines))
+            notes.append(document.text(index, min(stop, end)))
+    risk = document.section('Production-risk areas')
+    if risk:
+        notes.append(document.text(*risk))
+    return criteria, acceptance, ''.join(notes)
+
+
+def build(args):
+    project, design_path, progress_path, destination = paths(args)
+    design = Document(design_path)
+    headings, region = requirements(design)
+    if args.scope == 'requirement' and args.requirement not in [n for n, _ in headings]:
+        raise PacketError('selected requirement is absent from the design')
+    rows = progress_rows(Document(progress_path), project, design_path)
+    base, head = bounds(project, rows, headings, args)
+    criteria, acceptance, notes = evidence(design, headings, region, args)
+    span = f'{base}..{head}'
+    pathspec = ['--', '.', ':(glob,exclude)**/*-review-packet*.md']
+    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)),
+    ]
+    label = 'feature review' if args.scope == 'feature' else f'requirement R{args.requirement} review'
+    packet = f'# Review packet: {design_path.parent.name} — {label}\n\nBase: {base}\nHead: {head}\n\n'
+    for title, content in sections:
+        packet += f'## {title}\n\n{content}\n'
+    # All parsing and Git reads finish before a temporary file exists. A failure in
+    # assembly leaves an earlier complete packet intact. Replacement is same-directory.
+    temporary = None
+    try:
+        validate_destination(destination)
+        with tempfile.NamedTemporaryFile(mode='w', encoding='utf-8', newline='', dir=destination.parent,
+                                         prefix=f'.{destination.name}.', delete=False) as output:
+            temporary = Path(output.name)
+            output.write(packet)
+            output.flush()
+            os.fsync(output.fileno())
+        validate_destination(destination)
+        os.replace(temporary, destination)
+        temporary = None
+    finally:
+        if temporary is not None:
+            temporary.unlink()
+    print(f'Wrote {destination}\nRange: {base}..{head}')
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__, epilog=(
+        '--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.'
+    ))
+    parser.add_argument('--project', required=True)
+    parser.add_argument('--design', required=True)
+    parser.add_argument('--progress', required=True)
+    parser.add_argument('--scope', choices=['feature', 'requirement'], required=True)
+    parser.add_argument('--requirement', type=int)
+    args = parser.parse_args()
+    if (args.scope == 'requirement') != (args.requirement is not None):
+        parser.error('--requirement N is required only for --scope requirement')
+    try:
+        if sys.version_info < (3, 9):
+            raise PacketError('Python 3.9 or newer is required; install it explicitly before retrying')
+        build(args)
+    except (PacketError, OSError, ValueError) as error:
+        print(f'error: {error}', file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/skills/pwk-finalizing/SKILL.md

@@ -9,58 +9,56 @@ Ship the completed work.
 
 ## Pre-finalization checks
 
-1. **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. **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:
-3. Read **every** relevant progress file — for an umbrella that's each part's progress file — discovered by listing `docs/plans` recursively for `*-progress.md`, excluding docs/plans/completed/ (umbrella docs live in `docs/plans/<date>-<umbrella>/` folders — archived parts are already shipped). Use whatever recurses in your harness; one example: `find docs/plans -name '*-progress.md' -not -path '*/completed/*'`. Match the `Feature phase:` line (e.g. `grep -m1 '^Feature phase:' <file>`) and read only the matching ❌/⏭ verdict rows in the Requirements table (e.g. `grep '❌' <file>` / `grep '⏭' <file>` — rows with reasons); the sections after the tables carry nothing the gate needs. For a standalone design doc, the one:
-   - **Any `❌ failed`** (in any part) → **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.
+1. **Verify the repo root** — run `pwd` (or your shell's equivalent) and `git rev-parse --show-toplevel`; mismatch → report both paths and stop; never `cd` (a worktree root counts).
+2. **Run the FULL test suite** — every test must pass, and only a green suite ships. Resume spans sessions; re-run the suite yourself rather than trust the previous session's ending state. Anything failing → send the user back to `/skill:pwk-executing-tasks`.
+3. Read **every** relevant progress file — for a multi-leaf topic that's each leaf's progress file — discovered by listing `docs/plans` recursively, excluding docs/plans/completed/, for `*-progress.md` (topic docs live in `docs/plans/<date>-<topic>/` folders — archived work is not in flight). Use whatever recurses in your harness; one example: `find docs/plans -name '<suffix>' -not -path '*/completed/*'`. More than one topic in flight? Ask which one this finalize ships — finalizing touches only its own topic, and another topic still being designed or executed never blocks this run. Then match, in the chosen topic's file(s), the `Feature phase:` line (e.g. `grep -m1 '^Feature phase:' <file>`) and read only the matching ❌/⏭ verdict rows in the Requirements table (e.g. `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep '^| [0-9].*❌'` / `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep '^| [0-9].*⏭'` — scoped to Requirements-table rows because the Execution summary rows share the same row shape, with reasons); the sections after the tables carry nothing the gate needs. Apply the gates below to the chosen topic's file(s) and no others:
+   - **Any `❌ failed`** (in any leaf of the topic) → **block**. Present counts and reasons; continue only when the user sends the task back to executing-tasks, or explicitly types `--force-failed` to acknowledge shipping with incomplete requirements.
    - **Only `⏭ skipped`** → warn and confirm ("Requirement N was skipped. Continue, or go back?").
-   - **`Feature phase` must be `done`** in every progress file — any other value (`e2e-written`, `feature-spec-paused`, `implementing (k/N)`, `reviewing`, `ship-paused`, or a legacy `feature-complete-paused` from before the ship gate) means the feature is still in flight: the ship checkpoint has not been approved. Send the user back to `/skill:pwk-executing-tasks` instead of finalizing.
+   - **`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.)
 
 ## Process
 
 1. **Derive the topic set** —
-   - **Umbrella** (a `docs/plans/**/overview.md` exists — excluding docs/plans/completed/, so an archived umbrella is never the one being finalized): read its roster; the set is every part's `<topic>`. The umbrella folder is disposed too.
-   - **Standalone**: progress file → `Design:` ref → design-doc filename → `<topic>`. One topic. (Legacy progress file: `Plan:` ref → the implementation doc's `Design:` ref → design doc.)
+   - **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.
+   - **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 the design doc's At-a-glance key-decision bullets **and its `Approaches considered` section** (the full forks with their reasoning), the progress file's `Deviated?` entries (including any deviation decision-records), and the Code digest's `[ALERT]` entries. Then:
+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.
    - **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 `-design.md`, `-implementation.md` (legacy — a 2.0 feature has none; the glob harmlessly no-ops), `-progress.md` (matched by the exact dated topic slug so similarly-named plans for other topics survive); for an umbrella, dispose the whole `docs/plans/<date>-<umbrella>/` folder — overview + every part — as one unit. Standalone topics keep the per-file paths. The digest sections (`## At a glance`, `## Execution summary`) live inside their host docs and ride the same globs — no separate disposal. Each path is matched with the `????-??-??-` prefix. Present both options and let the human choose:
+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:
 
    - **Delete (default)** — code + tests are the source of truth; removing the scaffold prevents stale plan docs from misleading future sessions:
 
      ```bash
-     # for each <topic> in the set:
-     rm -f docs/plans/????-??-??-<topic>-design.md docs/plans/????-??-??-<topic>-implementation.md docs/plans/????-??-??-<topic>-progress.md docs/plans/????-??-??-<topic>-review-packet*.md
-     # umbrella only — the whole folder goes as one unit (overview + every part).
-     # The folder path is taken verbatim from the discovered docs/plans/**/overview.md
-     # result — never typed or reconstructed (rm -rf has no dated-glob guard):
-     rm -rf docs/plans/<date>-<umbrella>/
-     git add -A docs/plans/ && git commit -m "chore: delete planning docs for <topic-or-umbrella>"
+     # the topic folder goes as one unit (every leaf, plus overview.md if it has one).
+     # The folder path is taken verbatim from discovery — never typed or
+     # reconstructed (rm -rf has no glob guard):
+     rm -rf docs/plans/<date>-<topic>/
+     git add -A docs/plans/<date>-<topic>/ && git commit -m "chore: delete planning docs for <topic>"
+     # the add is scoped to the topic pathspec, so another in-flight topic's
+     # 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/`:
 
      ```bash
      mkdir -p docs/plans/completed
-     # for each <topic> in the set:
-     mv docs/plans/????-??-??-<topic>-design.md          docs/plans/completed/ 2>/dev/null || true
-     mv docs/plans/????-??-??-<topic>-implementation.md  docs/plans/completed/ 2>/dev/null || true
-     mv docs/plans/????-??-??-<topic>-progress.md        docs/plans/completed/ 2>/dev/null || true
-     mv docs/plans/????-??-??-<topic>-review-packet*.md   docs/plans/completed/ 2>/dev/null || true
-     # umbrella only — the whole folder goes as one unit (overview + every part).
+     # the topic folder goes as one unit (every leaf, plus overview.md if it has one).
      # No error suppression on the folder move: verify the archive landed before
      # committing, or a silently failed move would commit the deletion and destroy
      # the history the human chose to keep:
-     mv docs/plans/<date>-<umbrella>/ docs/plans/completed/
-     ls docs/plans/completed/<date>-<umbrella>/ >/dev/null
-     git add docs/plans/ && git commit -m "chore: archive planning docs for <topic-or-umbrella>"
+     mv docs/plans/<date>-<topic>/ docs/plans/completed/
+     ls docs/plans/completed/<date>-<topic>/ >/dev/null
+     # both sides of the move, and nothing else — another in-flight topic's
+     # uncommitted drafts never ride the archive commit:
+     git add -A docs/plans/<date>-<topic>/ docs/plans/completed/ && git commit -m "chore: archive planning docs for <topic>"
      ```
 
-   The `????-??-??-` glob enforces the dated filename; a bare `*<topic>*` would over-match unrelated docs (e.g. topic `auth` would also hit `feature-auth-redesign-design.md`). Verify with `ls docs/plans/` before and after. `rm -f` and each `mv … || true` handle missing files. 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.
+   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.)
 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:
@@ -70,13 +68,13 @@ Ship the completed work.
    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.
-7. **Clean up** — remove the worktree if one was used: `git worktree remove ../<repo>-<topic>`.
+   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.
 
 ## 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) — for a standalone design doc its three docs; for an umbrella its overview plus every part's docs. Unrelated topics stay in `docs/plans/`.
+- 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).

package/skills/pwk-status/SKILL.md

@@ -9,21 +9,18 @@ Report on in-flight pipelines in this working tree (a worktree has its own `docs
 
 ## Process
 
-0. **Verify the root** — run `pwd` (or your shell's equivalent) and `git rev-parse --show-toplevel`; if they differ, report both paths and stop — tell the user to restart the session at the repo root; never `cd` (a worktree root counts).
-1. **Discover** — List `docs/plans` recursively, excluding docs/plans/completed/, one list per suffix: `*-design.md`, `*-implementation.md` (legacy — a 2.0 feature has no implementation doc; discovery covers both suffixes), `*-progress.md`, `overview.md` (umbrella docs live in `docs/plans/<date>-<umbrella>/` folders — archived topics are not in flight) — this working tree only. Use whatever recurses in your harness; one example: `find docs/plans -name '<suffix>' -not -path '*/completed/*'`.
-2. **State per topic/part — extract, never ingest.** For each progress file take the `Feature phase:` line by matching it (e.g. `grep -m1 '^Feature phase:' <file>` — wherever the template puts it); the body (execution summary, review reports, code digest) carries nothing status needs, and neither do design docs. Map the line to the displayed state:
-   - `done` → **`done`** — terminal, never shown as in-flight; append the tally as `N/N` when wanted — the Requirements-table row count (e.g. `grep -c '^| [0-9]' <file>`); at `done` every row is complete
+0. **Verify the root** — run `pwd` (or your shell's equivalent) and `git rev-parse --show-toplevel`; mismatch → report both paths and stop; never `cd` (a worktree root counts).
+1. **Discover** — List `docs/plans` recursively, excluding docs/plans/completed/, for `*-design.md`, `*-progress.md`, and `overview.md` (topic docs live in `docs/plans/<date>-<topic>/` folders — archived work is not in flight) — this working tree only. Use whatever recurses in your harness; one example: `find docs/plans -name '<suffix>' -not -path '*/completed/*'`.
+2. **State per topic/part — extract, never ingest.** For each progress file take the `Feature phase:` line by matching it (e.g. `grep -m1 '^Feature phase:' <file>` — wherever the template puts it); the body (execution summary, review reports, code digest) carries nothing status needs, and neither do design docs. A header reading `Setup: pending` renders the topic as **`awaiting setup`** — the setup checkpoint was never approved (the slot is only ever written when the design doc has a `## Setup` section, so the header alone decides — no design-doc read) — ahead of any phase-derived state below. Map the line to the displayed state:
+   - `done` → **`done`** — terminal, never shown as in-flight; every row is resolved (`✅` passed, `❌` failed, `⏭` skipped — resolved, not necessarily passed). Append the tally as `N/N` when wanted — the Requirements-table row count, scoped to that table because the Execution summary rows share the same `| <n> |` row shape and a bare grep would double it (e.g. `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep -c '^| [0-9]'`) — and when that same scoped range finds any — `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep -c '^| [0-9].*❌'` / `sed -n '/^## Requirements/,/^## Execution summary/p' <file> | grep -c '^| [0-9].*⏭'` (the same scoping, so Execution-summary rows — which share the row shape — and prose mentions of the glyphs do not inflate the count) — render the counts, e.g. `done (1 ❌ · 1 ⏭)`, noting finalizing will require `--force-failed` while `❌` rows stand
    - `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)
-   - `feature-spec-paused` (legacy — a progress file from before the notice replaced the stop) → `execute 0/N`
-   - `reviewing`, legacy `feature-complete-paused` → `review`
-   - `ship-paused` → `ship-paused`
+   - `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.
    - 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).
-
-   A legacy 1.x topic (`*-implementation.md` stem-matched) uses the same phase-line inference on its progress file.
-3. **Group by umbrella** — for each umbrella `overview.md` (read it — it is status-free and tiny), take its **parts** roster and roll the parts up by state (the overview carries no status): done parts, in-flight parts (design, execute, review, ship-paused), not-started parts. Print one roll-up line — `<umbrella> (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` standalone topic gets the same hint. Once the umbrella finalizes, its folder — overview included — is disposed, so it no longer appears here. Topics not part of 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 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.
 4. Print a compact table, grouped under any umbrellas, e.g.:
 
    ```text
@@ -32,7 +29,7 @@ Report on in-flight pipelines in this working tree (a worktree has its own `docs
      payments-ui        execute   1/2
      payments-review    review    —
      payments-webhooks  not started
-   auth                ship-paused   — ready for /skill:pwk-finalizing
+   auth                ship-paused   — ready for /skill:pwk-executing-tasks
    ```
 
    If nothing, suggest `/skill:pwk-brainstorming`.

package/skills/pwk-walkthrough/SKILL.md

@@ -13,7 +13,7 @@ Five sections, always: Summary / How it works / Key flows / Gotchas & invariants
 
 ## Contract
 
-- **On demand only.** Someone asks (or finalize suggests it as an optional follow-up); it never runs unprompted.
+- **On demand only.** Someone asks — or the ship checkpoint offers it when the code digest's Flow outgrows its cap (see `pwk-executing-tasks`); it never runs unprompted.
 - **Generated from code, not memory**: the branch diff (`<merge-base>...HEAD` — an unshipped branch is allowed, stamped at HEAD) plus the code as it exists now. Surviving artifacts (ADRs in `docs/adr/`, `docs/lessons.md`, an archived plan under `docs/plans/completed/`) are optional inputs — planning docs are usually gone by the time anyone asks, by design.
 - **Output**: `docs/walkthroughs/<topic>.md`, **stamped with the commit range** it describes.
 - **Regeneration overwrites wholesale.** The file is a generated cache of an explanation, never hand-edited; a re-run replaces it end to end. It is **never disposed** — finalize's globs do not touch `docs/walkthroughs/`.
@@ -28,7 +28,7 @@ Five sections, always: Summary / How it works / Key flows / Gotchas & invariants
    ```markdown
    # Walkthrough: <topic>
 
-   Generated from <merge-base>..<HEAD> — file references are valid at that range.
+   Generated from <merge-base>...<HEAD> — file references are valid at that range.
 
    ## Summary
    2–4 sentences: what this feature does and what changed.

package/skills/pwk-diagnose/SKILL.md

@@ -1,59 +0,0 @@
----
-name: pwk-diagnose
-description: "Disciplined debugging loop for hard bugs and performance regressions. Use when a test fails unexpectedly, a bug is found during execution, or something is broken. Use this skill whenever the user reports a bug, says 'this doesn't work', 'something's wrong', 'help me debug', or when tests fail for unclear reasons. Works at any point in the workflow — brainstorm, execute, or standalone."
----
-
-# Diagnose
-
-A 6-phase debugging discipline. Phase 1 is the skill — spend disproportionate effort here.
-
-Invoking `/skill:pwk-diagnose` **exits the gated design phase** (the workflow guard unlocks) — diagnosis needs to write failing tests and `[DEBUG-…]` instrumentation. If you only wanted read-only investigation, use `/skill:pwk-status` (stays gated) or reinstate the lock with `/pwk-guard on`.
-
-## Phase 1 — Build a feedback loop
-
-Create a fast, deterministic, agent-runnable pass/fail signal for the bug before doing anything else. Try in this order: failing test, curl script, CLI invocation, headless browser script.
-
-Other strategies when the basics don't work:
-- **Bisection** — bug appeared between two known states? Automate "boot at state X, check, repeat" to bisect
-- **Replay** — save a real network request or event log to disk, replay it through the code path in isolation
-
-The loop must produce the failure mode the **user** described — not a nearby but different failure. Iterate on the loop itself: can you make it faster? Sharper? More deterministic?
-
-If you genuinely cannot build a loop, stop and say so. List what you tried. Ask for access to a reproducing environment or a captured artifact.
-
-Hold at Phase 1 until you have a loop you believe in. Everything downstream — hypotheses, instrumentation, the fix — depends on that loop actually reproducing the user's symptom.
-
-## Phase 2 — Reproduce
-
-Run the loop. Confirm:
-- The failure matches the user's reported symptom
-- The failure is reproducible across multiple runs
-- You've captured the exact symptom (error message, wrong output, slow timing)
-
-Then **minimize the repro** — strip it down to the smallest input, shortest path, or fewest steps that still triggers the bug. A minimized repro dramatically narrows the hypothesis space.
-
-## Phase 3 — Hypothesise
-
-Generate 3-5 ranked hypotheses. Each must be falsifiable:
-
-> "If `<X>` is the cause, then `<changing Y>` will make the bug disappear / `<changing Z>` will make it worse."
-
-Show the ranked list to the user before testing. They often have domain knowledge that re-ranks instantly.
-
-## Phase 4 — Instrument
-
-Each probe must map to a specific hypothesis. Change one variable at a time. Tag every debug log with a unique prefix (e.g. `[DEBUG-a4f2]`) for easy cleanup later. Prefer a debugger breakpoint over logs when available.
-
-## Phase 5 — Fix + regression test
-
-Write the regression test **before** the fix — but only if there's a correct seam (one that exercises the real bug pattern at the call site). If no correct seam exists, note it — the codebase architecture is preventing the bug from being locked down.
-
-## Phase 6 — Cleanup
-
-Required before declaring done:
-- Original repro no longer triggers
-- Regression test passes (or absence of seam is documented)
-- All `[DEBUG-...]` instrumentation removed
-- Ask: what would have prevented this bug?
-- If the answer is a repeatable pattern, append a **generic** rule to `docs/lessons.md` (strip domain specifics) so future sessions catch it early.
-- If the bug was caused by an architectural problem (no good test seam, tangled callers, hidden coupling), suggest writing an ADR to `docs/adr/` capturing that insight