@hecer/yoke 0.2.0 → 0.8.0

package/docs/superpowers/specs/2026-06-29-baustein-h-loop-robustness-design.md

@@ -0,0 +1,113 @@
+# Baustein H — Loop Robustness (verify-as-truth + flaky-tolerant verify)
+
+**Status:** Design approved 2026-06-29
+**Component:** Yoke (🐂)
+**Relates to:** [[harness-build-progress]], [[harness-loop-technique]]
+
+## Problem & Goal
+
+Evidence from a real autonomous run (NewMarket, 52/57 stories): the loop blocked and needed
+human intervention on a handful of stories. Two of those block causes are **harness defects**,
+not project defects, and both are cheap to fix:
+
+1. **Runner exit-code is treated as ground truth (SE5).** The story was implemented and the full
+   suite was green (769/769), but the `claude` `.cmd` wrapper on Windows exited **127**. The loop
+   checks `result.success` *before* running verify, so it **blocked a successful story** on a
+   spurious exit code and didn't auto-commit. This contradicts the loop's own stated philosophy
+   (Baustein C2): *"independent verification is the source of truth, not the agent's exit code."*
+
+2. **No flaky-test tolerance (T4).** Under autonomous load, a heavy background task caused an
+   async test to time out — a **false** red, not a real defect. The single-shot verify gate
+   blocked the story. The user had to manually add `retry: 2` to the project's `vitest.config`.
+   That resilience belongs in the harness.
+
+**Goal:** make the loop trust **verify**, not the agent's exit code, and tolerate transient
+flakes — closing two real block causes without weakening the gate.
+
+**Out of scope (deferred):** cross-story regression repair (S5/S6 — a later story breaking an
+earlier story's tests). That needs its own design; this spec does not address it.
+
+## Key Decisions (locked)
+
+| Decision | Choice |
+|---|---|
+| Verify authority | The **implementer** runner's `success` flag is advisory; **verify decides**. Run verify regardless of runner exit, block only on verify failure. |
+| Runner-fail + verify-pass | Proceed (commit) — the exit code was a ghost. Note it via the reporter / summary. |
+| Runner-fail + verify-fail | Block, with a reason naming both signals. |
+| Reviewer runner | **Unchanged** — its non-zero exit *is* the reject verdict (there is no separate verify for the review). |
+| Flaky tolerance | `retryingVerifier(inner, retries)` re-runs a failing verify up to `retries` times; first pass wins. |
+| Retry default | `config.verify.retries` default **1** (one retry). `0` = strict/no-retry. A real failure still fails (twice). |
+| Out of scope | Cross-story regression repair; changing the reviewer's exit-code semantics. |
+
+## Architecture
+
+### 1. `src/loop/verify.ts` — `retryingVerifier`
+```ts
+export function retryingVerifier(inner: Verifier, retries: number): Verifier {
+  return (targetDir) => {
+    let last = inner(targetDir)
+    let attempt = 0
+    while (!last.passed && attempt < retries) {
+      attempt++
+      last = inner(targetDir)
+    }
+    if (last.passed && attempt > 0) {
+      return { passed: true, summary: `${last.summary} (passed on retry ${attempt})` }
+    }
+    return attempt > 0 && !last.passed
+      ? { passed: false, summary: `${last.summary} (still failing after ${attempt} retr${attempt === 1 ? 'y' : 'ies'})` }
+      : last
+  }
+}
+```
+Pure, injectable `inner` for tests (no real command needed).
+
+### 2. `src/loop/loop.ts` — verify is the gate
+In **both** the isolate and non-isolate paths, restructure the implementer step so verify always
+runs:
+
+- Run the implementer runner (keep `result` for its summary).
+- `reporter.phase('verifying')`; run `opts.verify(dir)`.
+- If verify **fails**: block. Reason = verify summary, and if the runner *also* reported failure,
+  prepend that (`runner reported failure (<summary>); verify also red: <verify summary>`).
+- If verify **passes**: proceed to review/commit even if `result.success` was false. When the
+  runner had reported failure, the committed decision/summary notes
+  `(runner exited non-zero but verify is green)` so the ghost is auditable.
+
+The reviewer step is untouched: `if (!reviewResult.success) → block` stays (exit = verdict).
+
+The Baustein-E invariant (no `passes:true` without a commit; decision rollback on commit failure)
+and the leftover-hint are preserved exactly — only the implementer-failure gate moves from
+"before verify" to "verify decides".
+
+### 3. `src/retrofit/config.ts` — `verify.retries`
+Extend the `verify` config object: `verify: { command: string; retries?: number }`.
+Backwards-compatible (optional).
+
+### 4. `src/loop/run-command.ts` — wire the retry
+When building the verifier from config, wrap it:
+`verify = retryingVerifier(commandVerifier(command), config.verify?.retries ?? 1)`.
+The injected-verifier test path (`opts.verify`) is unchanged.
+
+### 5. README + loop-spec
+Document: verify is the source of truth (a spurious agent exit code can't block a green story),
+and `verify.retries` (default 1) for flaky suites. Update `canon/loop/loop-spec.md` step 5.
+
+## Testing (subagent-driven TDD)
+- **verify.ts:** `retryingVerifier` passes immediately when inner passes (no retry); passes on
+  retry N when inner fails then passes; fails after exhausting retries; `retries: 0` = single
+  shot; summary notes the retry/exhaustion. Inner is a stub Verifier.
+- **loop.ts:** runner-fail + verify-pass → story is committed + `passes:true` (the SE5 case);
+  runner-fail + verify-fail → blocked with a combined reason; runner-pass + verify-fail →
+  blocked (unchanged); the reviewer still blocks on its own failure; existing invariant tests
+  (commit-failure revert, leftover hint) stay green; applies to both isolate and non-isolate.
+- **config.ts:** `verify.retries` accepted + optional.
+- **run-command.ts:** the built verifier is wrapped with the resolved retry count (assert via a
+  small seam or by config round-trip).
+- Full suite green; `tsc` clean.
+
+## What this would have done for the run
+- **SE5:** runner exits 127 but suite is 769/769 green → verify passes → story auto-commits. No
+  manual finalize.
+- **T4:** the load-flake fails once, the retry passes → story proceeds. No manual `vitest.config`
+  patch, no false block.

package/docs/superpowers/specs/2026-06-30-baustein-i-visual-design-verification-design.md

@@ -0,0 +1,98 @@
+# Baustein I — Visual & Design Verification
+
+**Status:** Design approved 2026-06-30 (autonomous)
+**Component:** Yoke (🐂)
+**Relates to:** [[harness-build-progress]], [[readme-always-update]]
+**Inspired by:** [vibecoded-design-tells](https://github.com/JCarterJohnson/vibecoded-design-tells) (MIT © 2026 Carter Johnson) — a data-ranked study of the visual "tells" of AI-generated UIs. Yoke implements the *idea* natively in TypeScript and credits the research; no code or data is copied.
+
+## Problem & Goal
+
+Yoke's verify gate is **code-only** (`tsc` + unit/component tests). It does not check that the UI is **visually sound** (free of generic AI-slop design) or that **user flows actually work end-to-end**. Evidence: in the real NewMarket run, integration/visual bugs (unwired auth pages, a seed id-collision, an old "purple #6c5ce7 dark theme" — itself a classic AI-slop tell) slipped past the unit-test gate and were only caught by a later manual QA sweep.
+
+**Goal:** add a **visual & design verification layer** that plugs into the existing verify model (so it's gated, not advisory) and is honest about cost:
+1. **Mechanical:** a static **design-slop scanner** (`yoke design-scan`) that flags the high-signal AI-slop tells and gates on exit code.
+2. **Methodology:** two canon skills — `unslop-ui` (the design rubric) and `visual-verification` (compose a verify pipeline: types + unit + design-scan + a Playwright flow-smoke; capture video only on failure).
+
+Both integrate through one idea: **the project's `verify.command` becomes a pipeline**, and Baustein-H's verify-as-truth makes those gates authoritative.
+
+## Key Decisions (locked)
+
+| Decision | Choice |
+|---|---|
+| Design-slop detection | A **TS-native** scanner built into the `yoke` CLI (`yoke design-scan`), not a port of the upstream Python; high-precision static heuristics |
+| Gate model | Exit non-zero when the weighted tell-score exceeds `--max` (default **4**); `--report` lists without failing |
+| Flow / video | **Methodology, not CLI** — the agent drives the wired Playwright MCP per the `visual-verification` skill. Yoke gates + guides; it does not embed a browser. Video capture is **opt-in, on failure only** (token-aware). |
+| Skills | `unslop-ui` (rubric) + `visual-verification` (pipeline + flow-smoke + video-on-failure) → all 3 agents |
+| Attribution | Credit vibecoded-design-tells (MIT) in `ATTRIBUTION.md` + README + the skill |
+| Canon count | 24 → **26** skills |
+| Out of scope (YAGNI) | Embedding Playwright/a browser in the Yoke CLI; structural-layout detection ("centered hero + 3 cards") — left to the rubric + agent eye; auto-fixing slop (the agent fixes, guided by the skill) |
+
+## Architecture
+
+### 1. `src/scan/design.ts` (new) — the static scanner
+Pure + unit-testable. Walks the project's source and scores AI-slop tells.
+
+```ts
+export interface Tell { name: string; weight: number; test: (line: string) => boolean; hint: string }
+export interface Finding { file: string; line: number; tell: string; hint: string; text: string }
+export interface ScanResult { findings: Finding[]; score: number }
+
+export const TELLS: Tell[]            // the curated tell set (below)
+export function scanText(text: string, tells?: Tell[]): { line: number; tell: Tell; text: string }[]
+export function scanDir(dir: string, tells?: Tell[]): ScanResult   // walks files, aggregates
+```
+
+**Curated high-precision tells** (each match adds `weight` to the score):
+
+| Tell | weight | matches (case-insensitive) | hint |
+|---|---|---|---|
+| `ai-purple` | 2 | hex `#6c5ce7\|#7c3aed\|#8b5cf6\|#a855f7\|#9333ea`, or Tailwind `(from\|via\|to)-(purple\|violet\|fuchsia)-(4\|5\|6\|7)00` | AI-purple is the #1 vibecoded tell — choose a real brand color |
+| `gradient-clip-text` | 2 | a line containing both `bg-clip-text` and `text-transparent`, or CSS `-webkit-background-clip:\s*text` near a gradient | gradient hero text reads as AI-slop — solid color + weight instead |
+| `neon-glow` | 2 | Tailwind `(shadow\|drop-shadow)-\[0_0_`, or CSS `box-shadow:[^;]*0\s+0\s+\d{2,}px` with a color | neon glow is a tell — use subtle, neutral elevation |
+| `gradient-overload` | 1 | `bg-gradient-to-` or CSS `linear-gradient(` | gradients everywhere flatten hierarchy — use them sparingly |
+| `emoji-icon` | 1 | an emoji (unicode pictographic) inside a `.tsx/.jsx` line that also contains `<button`, `<a `, `aria-hidden`, or a JSX `>…<` icon slot | emoji-as-icons is a tell — use a real icon set |
+
+File walk: extensions `.css .scss .tsx .jsx .ts .js .html .vue .svelte .astro`; skip `node_modules`, `dist`, `.next`, `build`, `.yoke`, `coverage`, `.git`. The tell set is the default but injectable (for tests). Heuristic by design — documented as high-signal, not exhaustive.
+
+### 2. `src/cli.ts` — `yoke design-scan [dir] [--max=N] [--report]`
+- Runs `scanDir(dir)`, prints findings grouped by tell as `file:line  <tell>  — <hint>`.
+- `--report`: print + summary, **always exit 0** (advisory).
+- default (gate): print + summary; **exit 1 if `score > max`** (default `max=4`), else 0. So a couple incidental matches pass; pervasive slop fails. Designed to sit in a verify pipeline.
+- A small body extracted to `runDesignScan(dir, { max, report }): number` for testability.
+
+### 3. `canon/skills/unslop-ui/SKILL.md` (new) — the rubric
+Agent-facing. Lists the ranked tells (AI-purple gradients, gradient hero text, neon glow, emoji-as-icons, shadcn defaults left unchanged, "centered hero + three cards", homogeneous spacing) and how to fix each. Instructs: before finishing UI work, run `yoke design-scan .` and resolve findings; also apply the structural items the scanner can't see. Credits the research.
+
+### 4. `canon/skills/visual-verification/SKILL.md` (new) — ties it together
+Methodology for UI projects:
+- **Compose the verify pipeline** so the loop gate covers more than units: `verify.command` chains types → unit tests → `yoke design-scan .` → a Playwright flow-smoke. (Baustein-H makes these authoritative.)
+- **Flow-smoke via the wired Playwright MCP:** load the key routes against the dev server, assert they render and the console has **no errors**, screenshot each. This catches the "unwired page / runtime crash" bugs unit tests miss.
+- **Video only when necessary:** capture a video of a flow **only on failure** (or when explicitly debugging a UX issue), then analyse it — keeps tokens down. Never record every run.
+
+### 5. Wiring
+- `canon/manifest.yaml`: add `unslop-ui` + `visual-verification` (kind: methodology).
+- `canon/skills/ATTRIBUTION.md`: credit vibecoded-design-tells (MIT © Carter Johnson).
+- `README.md` (**mandatory**): a "Visual & design verification" section (the scanner + the two skills + the pipeline idea), the catalog updated (24 → 26, methodology group +2), and the test-count badge synced.
+
+## Data flow (gate)
+```
+verify.command =  tsc --noEmit  &&  vitest run  &&  yoke design-scan .  &&  <playwright flow-smoke>
+                                                     │ exit 1 if slop-score > max
+   loop verify (Baustein H: verify is the source of truth) ──► block on any red step
+```
+
+## Testing (subagent-driven TDD)
+- **design.ts:** `scanText` flags each tell with correct line + weight; clean text → no findings; `scanDir` walks + skips ignored dirs + aggregates score; injected tell-set works; emoji/purple/clip/glow/gradient cases each covered; a known-clean snippet scores 0.
+- **cli:** `runDesignScan` exits 1 when score > max, 0 when ≤ max, 0 always in `--report`; `--max` parsed; bad `--max` rejected.
+- **canon:** `unslop-ui` + `visual-verification` registered; `validateCanon` stays zero-error; real-canon asserts both present.
+- Full suite green; `tsc` clean.
+
+## What this would have caught
+- NewMarket's old **purple `#6c5ce7` dark theme** → `ai-purple` tell, scored, flagged before it shipped.
+- **Unwired auth pages / runtime crashes** → the flow-smoke (render + no console errors) gate, not the unit tests.
+
+## Non-goals (YAGNI)
+- No browser embedded in the Yoke CLI (Playwright MCP is the agent's tool).
+- No always-on video (opt-in, on failure).
+- No auto-rewrite of slop (the agent fixes via the rubric).
+- No structural-layout static detection (rubric + agent eye).

package/docs/superpowers/specs/2026-07-02-baustein-j-cross-model-review-gstack-compose-design.md

@@ -0,0 +1,137 @@
+# Baustein J — Cross-Model Review + gstack Compose
+
+**Date:** 2026-07-02
+**Status:** Approved (design), pending implementation plan
+
+## Motivation
+
+A comparison of Yoke against gstack (garrytan/gstack) and superpowers (obra/superpowers)
+surfaced two capabilities worth adopting, each in a way that preserves Yoke's identity
+(cross-agent portability + reproducible retrofit + safe autonomy):
+
+1. **On-demand cross-model review.** gstack's `/codex` lets a *second* model review the
+   current diff interactively with a pass/fail gate. Yoke already does cross-model review
+   *inside the loop* (`yoke loop run --review --reviewer=codex`, see `src/loop/runner.ts`
+   `makeReviewRunner` + `src/loop/loop.ts`), but there is **no standalone command** for a
+   human working interactively to get a second-model review before committing/pushing.
+
+2. **Composing with gstack instead of bundling it.** gstack is Claude-Code- and Bun-bound,
+   auto-updates hourly, and owns its own skill namespace. Bundling it would break Yoke's
+   cross-agent uniformity (Codex/Gemini users would get nothing) and create two masters over
+   `~/.claude/skills`. The sound integration is **detect-and-compose**: if gstack is present,
+   route Claude to it for capabilities Yoke deliberately does not ship — without depending on
+   it, and without ever touching Codex/Gemini artifacts.
+
+Explicitly rejected: bundling gstack at install time; copying its browser/iOS/design-shotgun
+breadth (that is gstack's Claude-Code + Bun identity, and copying it would dilute Yoke's
+cross-agent promise).
+
+## Part 1 — `yoke review` (standalone cross-model gate)
+
+### Command
+
+```
+yoke review [targetDir] [--reviewer=<claude|codex|gemini>] [--base=<ref>] [--focus="..."]
+```
+
+### Behavior
+
+- **Diff scope:**
+  - Default: the **uncommitted working-tree changes** (working tree + staged). Matches the
+    loop's per-story review semantics and the common "review before I commit/push" case.
+  - `--base=<ref>`: review the committed range `<ref>..HEAD` (pre-PR review of a whole branch).
+- **Reviewer resolution:**
+  - `--reviewer=<agent>` overrides (validated against `claude|codex|gemini`).
+  - Without the flag, resolve to the first **available** (CLI on PATH) agent in the order
+    **`[codex, gemini, claude]`** — preferring a *second* model so the review is genuinely
+    cross-model.
+  - If resolution lands on `claude` (only Claude on PATH), proceed but print a note that this
+    is a **self-review, not cross-model**.
+  - If no agent CLI is on PATH, exit non-zero with an install hint (same diagnostics style as
+    `runLoopCommand`).
+- **Prompt:** a new story-less builder `buildStandaloneReviewPrompt(scope, focus?)` added to
+  `src/loop/runner.ts` next to the existing `buildReviewPrompt`. It instructs the reviewer to inspect
+  the diff (it runs `git diff` itself — it has repo access) for correctness, unmet intent,
+  missing tests, and obvious bug/security risks. `--focus` injects an emphasis line.
+  Approve by exiting 0; reject (any blocking issue) by exiting non-zero. Do not modify files.
+- **Gate semantics:** the reviewer's stdout inherits to the console (like the loop). Approve →
+  `yoke review` exits **0**; findings → exits **1**. This makes it chainable as a gate:
+  `... && yoke review`, inside `verify.command`, or as a pre-push hook. Consistent with the
+  Baustein-H gate model.
+- **Watchdog:** wrap the invocation with the existing `buildWatchdogInvocation` using the
+  default idle timeout (reuse `resolveIdleMs` / `DEFAULT_IDLE_MINUTES`), overridable via a
+  `--timeout=<minutes>` flag, so a silent hang is killed. Minor but keeps parity with the loop.
+
+### Module shape
+
+- Export a thin `runAgent(inv: Invocation): AgentResult` from `src/loop/runner.ts` (wraps the
+  existing private `runCli`) so a standalone caller can reuse invocation + watchdog plumbing
+  without duplicating the win32/exec logic.
+- Add `src/review/command.ts` with `runReview(targetDir, opts): number` (mirrors
+  `src/context/command.ts`). It resolves the reviewer, builds the scope description + prompt,
+  invokes via `agentInvocation` + `buildWatchdogInvocation` + `runAgent`, and maps the result
+  to an exit code.
+- Wire a `case 'review':` into `src/cli.ts` `main()` with flag parsing mirroring the existing
+  `loop run` parsing (validate `--reviewer`, `--timeout`; accept `--base`, `--focus`).
+
+### Out of scope (YAGNI)
+
+- No loop wiring (the loop already has `--review`/`--reviewer`).
+- No multi-reviewer quorum.
+- No diff parsing in Node — the agent reads the diff itself.
+
+## Part 2 — gstack compose (interop bridge)
+
+### Detection
+
+`retrofit` checks, best-effort and non-fatal, for a gstack install:
+
+- repo-local: `<targetDir>/.claude/skills/gstack`
+- global: `<os.homedir()>/.claude/skills/gstack`
+
+Detection returns a boolean; a filesystem error is treated as "not detected".
+
+### Effect (Claude artifact only)
+
+When gstack is detected **and** `claude` is a target agent, `planClaude` appends a short
+**"Composed tools"** section to the generated `CLAUDE.md` (`src/retrofit/planners/claude.ts`,
+`claudeMd(...)`). The section routes Claude to gstack for the capabilities Yoke deliberately
+does not ship:
+
+- Live-browser QA → gstack `/qa`
+- Security audit → gstack `/cso`
+- Ship / deploy → gstack `/ship`, `/land-and-deploy`
+
+The note is **never** added to Codex or Gemini artifacts (gstack is Claude-only). If gstack is
+absent, nothing is written — the feature degrades cleanly to nothing, preserving cross-agent
+uniformity.
+
+### Non-goals
+
+- No bundling, no install of gstack, no dependency, no interaction with gstack's auto-update.
+- Yoke does not own gstack; it composes with it only when the user has installed it.
+
+## Part 3 — Tests, docs, attribution
+
+- **Tests:**
+  - `yoke review`: diff-scope resolution (default vs `--base`), reviewer resolution order
+    (codex→gemini→claude) including the self-review fallback note and the no-agent error,
+    exit-code gate (approve=0 / reject=1), using an injected fake runner (no real CLI call,
+    mirroring the loop tests' seam).
+  - gstack detection: repo-local present, global present, absent; and that `planClaude` adds
+    the "Composed tools" section to CLAUDE.md only when detected + claude targeted, and never
+    to Codex/Gemini artifacts.
+- **Docs:** README gets a `yoke review` section + a "composes with gstack" note; the canon
+  `review` skill mentions `yoke review` as the interactive counterpart to the loop's
+  `--review`. Bump the test-count badge.
+- **Attribution:** credit the `/codex` idea to gstack (MIT © Garry Tan) in
+  `canon/skills/ATTRIBUTION.md` — natively re-implemented, cross-agent, no code copied.
+
+## Testability & isolation
+
+- `runReview` takes an injectable runner (default = real `runAgent`) and an injectable
+  `isAvailable` probe, exactly like `runLoopCommand`, so tests never spawn a real agent CLI.
+- gstack detection takes the two candidate paths (or a `homedir` injection) so tests can point
+  at a temp dir.
+- Each unit has one purpose: prompt building, reviewer resolution, detection, and CLI wiring
+  are separable and independently testable.

package/docs/superpowers/specs/2026-07-02-baustein-k-zero-to-100-bootstrap-design.md

@@ -0,0 +1,200 @@
+# Baustein K — Zero-to-100 Bootstrap: `yoke new`, PRD draft/check, loop cleanup, loop lock
+
+Date: 2026-07-02
+Status: approved (design delegated by user; scope approved in conversation: "ok setze es um wie du es geplant hast, gleich nach K")
+
+## Problem
+
+Yoke's core claim is "zero to 100% autonomous development", but today the zero side is missing:
+the loop requires a hand-written `.yoke/prd.yaml` in an already-existing git repo. Greenfield
+start is undocumented agent work. Two robustness gaps compound this: a crashed loop leaves
+orphaned worktrees behind (manual `git worktree remove`), and two concurrent `yoke loop run`
+invocations race on the PRD and status files.
+
+## Goal
+
+One command from idea to loop-ready project, plus loop robustness:
+
+```
+yoke new my-app --idea="CLI tool that ..."   # scaffold + retrofit + context + drafted PRD, committed
+yoke loop on my-app && yoke loop run my-app --isolate
+```
+
+## Part 1: `yoke new <dir> [--idea="..."] [--agent=...] [--runner=<agent>] [--loop]`
+
+Module: `src/new/command.ts`, export `runNew(dir: string, opts: RunNewOptions): number`.
+
+Behavior, in order:
+
+1. `<dir>` is required (usage + exit 1 if missing). If the directory exists **and is non-empty**,
+   refuse with exit 1 (`yoke new` is greenfield-only; retrofit exists for brownfield). An existing
+   empty directory is fine.
+2. Create the directory (recursive) and `git init` it.
+3. Minimal scaffold (language-agnostic — the PRD's first story scaffolds the real project):
+   - `README.md`: `# <basename>` plus the idea text as a paragraph when `--idea` is given.
+   - `.gitignore`: `node_modules/`, `dist/`, `.env` (one per line).
+4. Run the existing retrofit (`runRetrofit(dir, { loop: opts.loop, agents })`). Agents resolve like
+   the `retrofit` CLI case: `--agent=` list or default; in an empty dir detection finds nothing, so
+   the default is `['claude']`.
+5. Run `runContextInit(dir)`. When `--idea` is given, append `\n## Idea\n\n<idea>\n` to
+   `.yoke/context/PROJECT.md` so every loop iteration sees the north star.
+6. Write the PRD **template** to `.yoke/prd.yaml` (see Part 2a below): an empty story array `[]`
+   preceded by comment lines showing a fully-formed example story. Comments survive because we
+   write the file verbatim; `loadPrd` still parses it (empty array is schema-valid).
+7. Initial commit: `git add -A` + commit `chore: bootstrap <basename> with yoke`
+   (`-c commit.gpgsign=false`, same as `realGitOps.commitAll`). This makes `--isolate` work from
+   iteration 1 (worktrees check out committed HEAD).
+8. When `--idea` is given: run the PRD draft (Part 2) with `--runner` resolution, then commit the
+   drafted PRD as a second commit `docs: draft PRD from idea`. If the draft fails (agent error or
+   invalid YAML), keep the template, print
+   `PRD draft failed (<reason>). Project is ready; retry with: yoke prd draft <dir> --idea="..."`
+   and return **1** (the scaffold succeeded, but the user's idea→PRD ask did not — signal it).
+9. Print next steps: edit/inspect `.yoke/prd.yaml`, set `verify.command` in `.yoke/config.yaml`,
+   `yoke loop on <dir>`, `yoke loop run <dir> --isolate`.
+
+Exit codes: 0 success; 1 usage / non-empty dir / draft failure; 2 requested draft agent unavailable.
+
+Injectable seams for tests: `git?: (args: string[], cwd: string) => void` (default execFileSync
+wrapper) and the Part-2 seams passed through (`isAvailable`, `run`).
+
+## Part 2: `yoke prd draft [dir] --idea="..." [--runner=<agent>] [--force] [--timeout=<minutes>]`
+
+Module: `src/prd/command.ts`, export `runPrdDraft(targetDir: string, opts: PrdDraftOptions): number`.
+
+- `--idea` is required (exit 1 with usage if missing/empty).
+- Overwrite guard: if `.yoke/prd.yaml` exists and parses to **> 0 stories**, refuse with exit 1
+  (`PRD already has N stories — use --force to overwrite`) unless `--force`. The Part-1 template
+  (0 stories) never triggers the guard.
+- Agent resolution mirrors the loop: `--runner` ?? `config.agents[0]` ?? `'claude'`; must pass
+  `isAgentAvailable`, else exit 2 with install hint. (No cross-model preference here — drafting is
+  not adversarial review.)
+- Prompt builder `buildPrdDraftPrompt(idea: string): string` in `src/prd/command.ts`:
+  - You are drafting a PRD for the Yoke loop.
+  - Break the idea into 5–12 small, independently shippable stories; each must fit one loop
+    iteration.
+  - Each story: `id` (STORY-1…), `title` (imperative), `priority` (dense from 1, lower = first),
+    `acceptance` (2–5 testable, behavioral criteria — outcomes, not implementation), `passes: false`.
+  - If the project has no source code yet, STORY-1 must scaffold the project skeleton including a
+    runnable test suite, and its acceptance must include that the verify command
+    (`.yoke/config.yaml` → `verify.command`) runs green.
+  - Write ONLY the file `.yoke/prd.yaml` as a YAML array matching this schema (schema inlined).
+    Do not modify other files. Do not commit.
+- Execution reuses the Baustein-J plumbing: `agentInvocation` → default runner
+  `runAgent(buildWatchdogInvocation(inv, idleMs))` with `resolveIdleMs(opts.timeoutMinutes, undefined)`;
+  injectable `isAvailable` / `run` seams exactly like `src/review/command.ts`.
+- Post-validation: `loadPrd(prdPath)` — on parse/schema failure exit 1 with the zod message; on
+  success print `Drafted N stories → .yoke/prd.yaml` and exit 0. 0 drafted stories is a failure
+  (exit 1, `agent produced an empty PRD`).
+
+### Part 2a: PRD template
+
+Exported const `PRD_TEMPLATE` (in `src/prd/command.ts`), written by `yoke new`:
+
+```yaml
+# Yoke PRD — the loop picks the lowest-priority open story each iteration.
+# Story format (see canon/loop/prd.schema.md):
+# - id: STORY-1
+#   title: scaffold the project with a runnable test suite
+#   priority: 1
+#   acceptance:
+#     - "the verify command exits 0"
+#     - "a placeholder test exists and passes"
+#   passes: false
+[]
+```
+
+## Part 3: `yoke prd check [dir]`
+
+Same module, export `runPrdCheck(targetDir: string): number`.
+
+- Missing file → exit 1 (`No PRD at .yoke/prd.yaml — run yoke prd draft or yoke new`).
+- Schema violation (zod) → print message, exit 1.
+- Lints beyond the schema, each an error (exit 1): duplicate story ids; any story with an **empty
+  `acceptance` array** (the schema allows `[]`, but the loop's stop-the-line gate will block it —
+  fail fast here); zero stories (`PRD has no stories`).
+- Success: print `✓ PRD valid — N stories, M pass` and exit 0. Chainable pre-loop gate.
+
+## Part 4: `yoke loop cleanup [dir]`
+
+Module: `src/loop/cleanup.ts`, export `runLoopCleanup(targetDir: string, opts?): number`.
+
+- Scans `.yoke/worktrees/` only (yoke-created paths; never touches user worktrees). Missing/empty
+  → `Nothing to clean.`, exit 0.
+- For each entry: `git worktree remove --force <path>` from the repo root; collect failures and
+  fall through. Afterwards run `git worktree prune`.
+- Also removes a **stale** `.yoke/loop.lock` (holder pid not alive — see Part 5). A live lock is
+  reported and left alone.
+- Report `Removed N worktree(s).` (+ failures). Exit 0 when everything cleaned, 1 if any removal
+  failed.
+- Injectable seam: `git?: (args: string[], cwd: string) => void`.
+- Registered under the existing `loop` CLI case as sub-command `cleanup`.
+
+## Part 5: Loop lock (single-flight guard)
+
+Module: `src/loop/lock.ts`:
+
+- `lockPath(targetDir)` → `.yoke/loop.lock`; contents JSON `{ "pid": number, "startedAt": ISO }`.
+- `isPidAlive(pid: number): boolean` — `process.kill(pid, 0)` in try/catch (works on Windows);
+  `EPERM` counts as alive.
+- `acquireLock(targetDir, pid?): { acquired: boolean; holderPid?: number }` — no file or unreadable/
+  corrupt file → take it (mkdir `.yoke` if needed); holder alive → `{ acquired: false, holderPid }`;
+  holder dead → warn-and-take (caller prints the warning; the function returns
+  `{ acquired: true, stalePid }` — include `stalePid?: number` in the result).
+- `releaseLock(targetDir)` — best-effort unlink, never throws.
+
+Wiring in `runLoopCommand` (src/loop/run-command.ts): after the existing pre-checks (loop enabled,
+PRD exists, verify resolved, agent available) and before `runLoop`, acquire the lock; on
+`acquired: false` print
+`Another loop is already running (pid <holderPid>). If that is wrong, run: yoke loop cleanup` and
+return 2. On stale takeover print a warning. Release in `finally`.
+
+Gitignore: add `.yoke/loop.lock` to `YOKE_IGNORE_LINES` (src/retrofit/gitignore.ts) so the
+pre-dispatch clean-tree gate is not broken by the lock file itself. Note: `ensureGitignore` is
+idempotent and appends only missing lines, so existing retrofitted projects pick the new line up
+on their next retrofit.
+
+## Part 6: Canon skill `authoring-prd`
+
+`canon/skills/authoring-prd/SKILL.md` (kind: methodology), registered in `canon/manifest.yaml`.
+Content: how to slice a product idea into loop-ready stories — small and independently shippable
+(one loop iteration each); acceptance criteria are testable behavioral outcomes, never
+implementation steps; dense priorities; greenfield STORY-1 scaffolds project + test runner and
+wires `verify.command`; full `prd.yaml` example. This gives interactive sessions (all three
+agents, via retrofit) the same discipline `yoke prd draft` encodes.
+
+Canon count moves 26 → 27; the real-canon test that asserts the skill count must be updated.
+
+## CLI usage line
+
+`yoke new <dir> [--idea="..."] [--agent=...] [--runner=<agent>] [--loop] | prd <draft|check> [dir] [--idea="..."] [--runner=<agent>] [--force] | loop <on|off|status|run|cleanup> | ...`
+
+## Testing
+
+- `tests/prd/command.test.ts`: draft — runner receives resolved agent invocation (seam), `--runner`
+  honored, unavailable → 2, overwrite guard (>0 stories blocks, `--force` passes, template `[]`
+  passes), post-validation failure → 1, empty result → 1, success prints count; prompt builder —
+  contains idea, schema, story-count band, STORY-1 scaffold rule, "Write ONLY"; check — valid PRD
+  0, duplicate ids 1, empty acceptance 1, no stories 1, missing file 1.
+- `tests/new/command.test.ts`: non-empty dir refused; scaffold files + git init + initial commit
+  (seam-recorded git calls); retrofit artifacts present (real canon); PROJECT.md gets idea section;
+  template PRD written and schema-parses to `[]`; `--idea` triggers draft via injected run seam and
+  second commit; draft failure → exit 1 + template intact.
+- `tests/loop/cleanup.test.ts`: removes listed worktrees via git seam + prune called; nothing to
+  clean; failure → exit 1; stale lock removed, live lock kept.
+- `tests/loop/lock.test.ts`: acquire on empty; blocked by live pid (use `process.pid`); stale
+  takeover (dead pid, e.g. a just-exited child or an absurd pid); corrupt file → take; release
+  best-effort; `runLoopCommand` returns 2 when locked (existing run-command tests gain one case,
+  using the real lock with `process.pid`).
+- `tests/retrofit/gitignore.test.ts`: extend for `.yoke/loop.lock`.
+- Real-canon tests: 27 skills, `authoring-prd` frontmatter valid.
+
+## Non-goals
+
+- No language/framework project templates (STORY-1 scaffolds; keeps `yoke new` universal).
+- No parallel loop, no CI triggers, no PRD estimation/dependencies.
+- No cross-model preference for drafting (that's review's job).
+
+## Attribution
+
+PRD-driven Ralph loop: Geoffrey Huntley's Ralph technique; story-slicing discipline informed by
+superpowers `writing-plans`. No external code.