@jamie-tam/forge 6.0.0

package/skills/discover-requirements/templates/user-stories.md

@@ -0,0 +1,76 @@
+# User Stories
+
+## Story: {Story Title}
+
+**ID**: US-{number}
+**Priority**: Must / Should / Could / Won't (MoSCoW)
+
+### Description
+As a **{role}**,
+I want **{action}**,
+so that **{benefit}**.
+
+### Acceptance Criteria
+
+- [ ] **Given** {precondition}, **when** {action}, **then** {expected result}
+- [ ] **Given** {precondition}, **when** {action}, **then** {expected result}
+- [ ] **Given** {precondition}, **when** {action}, **then** {expected result}
+
+### Dependencies
+
+- {Depends on US-{number} because...}
+- {Requires {external system/service} to be available}
+
+### Notes
+
+- {Additional context, constraints, or considerations}
+- {Link to mockup, design, or reference material}
+
+---
+
+## Story: {Next Story Title}
+
+**ID**: US-{number}
+**Priority**: Must / Should / Could / Won't
+
+### Description
+As a **{role}**,
+I want **{action}**,
+so that **{benefit}**.
+
+### Acceptance Criteria
+
+- [ ] **Given** {precondition}, **when** {action}, **then** {expected result}
+
+### Dependencies
+
+- {none / list dependencies}
+
+### Notes
+
+- {Additional context}
+
+---
+
+## User Journeys
+
+Chain user stories into end-to-end flows. Each journey represents a complete user goal. E2E tests are derived from these journeys.
+
+### Journey: {Journey Name}
+**Priority:** Must / Should / Could
+**Stories:** US-{x} → US-{y} → US-{z}
+
+| Step | User Does | System Response | Story |
+|---|---|---|---|
+| 1 | {user action} | {system response} | US-{x} |
+| 2 | {user action} | {system response} | US-{y} |
+| 3 | {user action} | {system response} | US-{z} |
+
+---
+
+## Summary
+
+| ID | Title | Priority | Dependencies | Status |
+|----|-------|----------|-------------|--------|
+| US-001 | {title} | Must | None | Draft |
+| US-002 | {title} | Should | US-001 | Draft |

package/skills/harden/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: harden
+description: "Use after a working prototype is locked and the user says 'codify', 'harden', 'ready to productionize', 'extract decisions', 'time to build for real', or runs /feature past the prototype phase. Extracts architecture, ADRs, design system, slice graph, and convention/gotcha promotions FROM the working prototype — does not invent them. Skip if prototype is still iterating or has been abandoned — re-iterate or restart instead."
+---
+
+# Harden
+
+## Overview
+
+A working prototype contains real decisions: what data shape works, which interactions feel right, where the seams are, what failures recur. Production code needs those decisions written down before it can be built. This skill codifies — it does not invent.
+
+**Core principle:** the prototype is the verification; this skill is the transcription. Every output cites the prototype file, wireframe state, or iteration gotcha it derives from. ADRs that can't cite a concrete prototype decision are flagged for review — they may be premature.
+
+**Announce at start:** "I'm using the harden skill to codify the prototype into production plans."
+
+## When to Use
+
+- Right after the user locks the prototype phase ("satisfied — go to production"). Triggered by the prototype-lock event or by an explicit invocation.
+- Ad-hoc when a feature's prototype is mature enough that production planning should begin while iteration continues at low intensity.
+
+**Do NOT skip when:**
+- The prototype "feels obvious" — obvious shape still needs an architecture document so the production build is testable against it
+- The team is in a hurry — skipping codification means the production build is improvising; the gates downstream rely on this skill's outputs as inputs
+
+**Do NOT use this skill for:**
+- Generating architecture from scratch with no prototype (use `plan-architecture` directly during a non-prototype-driven flow)
+- Reviewing existing architecture docs (that's `craft-reviewer` and `code-reviewer`'s job)
+- Building the production code itself (that's the production-build phase, after this skill closes)
+
+## What harden produces (multi-output)
+
+This is an orchestrator skill. A single invocation may produce all of the below:
+
+| Output | Where | Purpose |
+|---|---|---|
+| Architecture file(s) | `aiwiki/architecture/{topic}.md` (one per subsystem) | The system shape, components, boundaries, tradeoffs as observed in the prototype |
+| ADRs | `aiwiki/decisions/{nnnn}-{slug}.md` | Production-only decisions that the prototype implicitly made; needs explicit recording (with `review:` block per the adversarial-review trigger list) |
+| Convention additions | `aiwiki/conventions/{slug}.md` | Production-surface conventions the frontend prototype didn't cover (API route handler naming, error shapes, etc.) |
+| Gotcha addenda | `aiwiki/gotchas/{date}-{slug}.md` (existing files updated) | Re-evaluates Phase 4 gotchas under production scope; adds "still applies under server-rendered hydration" or similar production-only notes |
+| Production task graph | `.forge/work/{type}/{name}/tasks.md` + `slice_graph` field in manifest | What needs to be built to take the prototype to production |
+| Session entry | `aiwiki/sessions/{date}-{slug}.md` | Index linking everything produced this session |
+
+The expected total is short: ~200-400 lines across all architecture files combined, ~3-8 ADRs, a slice graph with explicit dependencies. Not 1000+ lines of monolithic plan.
+
+## What harden does NOT do
+
+- Does NOT write production code (Phase 6's job)
+- Does NOT run gates (LINT runs on the wiki output; reachability runs on production code later)
+- Does NOT modify the prototype (it's the source of truth — leave it alone)
+- Does NOT pre-promote raw entries from `aiwiki/raw/` to typed pages (dream's job at phase close)
+- Does NOT skip the adversarial-review step on ADRs — every production ADR is reviewed inline at Step 2 (the dedicated `/second-opinion` slash command + `support-second-opinion` skill are *planned, not yet implemented*; until they ship, harden inlines the review pass and records reviewer, objections, resolutions, verdict in the ADR `review:` block before promoting to `accepted`)
+
+## Inputs
+
+| Source | Required | Purpose |
+|---|---|---|
+| Locked prototype directory | yes | The codebase being codified |
+| Wireframe single-HTML | yes | Visual spec; design-system extraction source |
+| Concept slides | yes | High-level intent context |
+| `aiwiki/gotchas/` (Phase 4 entries) | if present | Prototype iteration gotchas to re-evaluate under production scope |
+| `aiwiki/conventions/` (Phase 4 entries) | if present | Conventions captured during prototype iteration |
+| Existing `aiwiki/architecture/` | if present | Prior architecture this work extends or supersedes |
+| Existing `aiwiki/decisions/` | if present | Prior ADRs to check for supersession |
+| `references/common/coding-standards.md` + `references/{lang}/standards.md` | yes | Production standards loaded as constraints on codified output |
+| `rules/common/{testing,quality-gates,git-workflow}.md` | yes | Phase-conditional rules that activate from this phase forward |
+| Manifest at `.forge/work/{type}/{name}/manifest.yaml` | yes | Target for slice graph + task list output |
+
+## Process
+
+### Step 0: locate inputs
+
+```
+Repo root: `git rev-parse --show-toplevel` or `${CLAUDE_PROJECT_DIR}`
+Manifest: the in-progress manifest under `.forge/work/*/*/manifest.yaml`. Multiple in flight = ask user.
+Prototype dir: from manifest's `prototype_path` field, or default `pocs/{name}-prototype/`
+Wireframe path: from manifest's `wireframe_path` field, or default `pocs/{name}-wireframe/index.html`
+```
+
+If the manifest does not yet have `artifacts.prototype.locked_at`, surface the gap and stop — this skill runs after prototype lock.
+
+### Step 1: dispatch the prototype-codifier subagent
+
+The bulk of the codification work happens in a separate context window so the main session stays lean.
+
+Dispatch `prototype-codifier` with:
+- Prototype directory path
+- Wireframe HTML path
+- Concept slides path
+- Path lists for existing `aiwiki/gotchas/`, `aiwiki/conventions/`, `aiwiki/architecture/`
+- Manifest path (writes target)
+
+The subagent returns a structured report listing:
+- Proposed architecture files (with topics + content)
+- Proposed ADRs (with subjects + draft content, marked `status: proposed`)
+- Convention additions
+- Gotcha addenda
+- Slice graph + task list
+
+The subagent does NOT write the files itself — it returns the proposals. The main session writes them after step 2.
+
+### Step 2: invoke adversarial review on each proposed ADR
+
+Each proposed ADR represents a decision that's hard to reverse — by definition, ADR-worthy. The `prototype-codifier` agent only proposes ADRs that match the adversarial-review trigger list (the canonical list lives in `agents/prototype-codifier.md` Phase 4); every proposal therefore arrives flagged for review.
+
+For each proposed ADR, run an adversarial review pass and write a structured `review:` block (reviewers, objections, resolutions, verdict) into the draft. The dedicated `/second-opinion` slash command + `support-second-opinion` skill that would package this work are *planned, not yet implemented* — until they ship, perform the review inline within harden (interrogate the decision against the trigger list's failure modes, surface objections explicitly, and either record resolutions or escalate to the user).
+
+Only ADRs with `verdict: approved` get written as `status: accepted`. ADRs with `verdict: escalate` are surfaced to the user for resolution before the phase closes. ADRs with `verdict: reject` are dropped from the proposal set.
+
+### Step 2.5: test-oracle capture
+
+Snapshot the prototype's behavior — route renders, key interactions, golden output traces — as integration-test oracles. Production code in Phase 6 must pass these.
+
+This is the SDLC's load-bearing wiring-test backbone — without it, mock-heavy unit tests pass while real integration breaks (Flux/REACH dogfood gap). Capture at least:
+
+- **Route/render oracles** for every page or HTTP endpoint the prototype exposes (status + body shape + critical DOM/JSON nodes)
+- **Interaction oracles** for the click-through paths the wireframe demos (sequence of state transitions and observable outputs)
+- **Golden output traces** for any pipeline, transform, or CLI command in the prototype (input fixture → expected output, byte- or structure-exact)
+
+Write the oracles to `aiwiki/oracles/{slug}.md` (one per slice or subsystem) with: source citation (prototype file + sha7), capture method (manual click-through, recorded fixture, snapshot diff), and the expected observable. Reference them in the slice graph so Phase 6 knows which oracle each task must satisfy.
+
+Oracles are not unit tests — they describe behavior at the same boundaries `build-tdd`'s Wiring Coverage subsection requires real-wiring tests for. They are the contract that says "the production rebuild meets the prototype's verified behavior," and they are what closes the mock-only gap.
+
+### Step 3: write the outputs
+
+In order:
+
+1. Architecture files → `aiwiki/architecture/{topic}.md` (one per topic; do NOT collapse into a monolith)
+2. Approved ADRs → `aiwiki/decisions/{nnnn}-{slug}.md` (numbering: continue from the highest existing number)
+3. Convention additions → `aiwiki/conventions/{slug}.md`
+4. Gotcha addenda → update existing `aiwiki/gotchas/{date}-{slug}.md` files with production scope notes
+5. Slice graph + tasks → manifest's `slice_graph` field + `.forge/work/{type}/{name}/tasks.md`
+6. Session entry → `aiwiki/sessions/{date}-{slug}.md` linking everything written this session
+
+Each write triggers wiki-lint synchronously; lint failures must be resolved before continuing.
+
+### Step 4: trigger a focused dream
+
+After the writes land, fire a phase-close dream over the touched subfolders. The dream is the consolidation pass that may merge new ADRs with existing ones, promote raw entries that became relevant during codification, and prune stale entries the new architecture supersedes.
+
+Dream output goes to `aiwiki/proposed/{dream_id}/` for user review. The phase does NOT close until the user accepts or rejects the dream output.
+
+### Step 5: gate
+
+User reviews:
+- The architecture files (do they accurately reflect the prototype?)
+- The ADRs (each `review:` block has a clear verdict; objections are addressed)
+- The slice graph (is the production task decomposition reasonable?)
+- The dream proposal (any consolidation conflicts to resolve?)
+
+User approves → Phase 6 (production-build) starts. User has objections → harden iterates: revise outputs, re-run dream, re-gate.
+
+The user reviews ALL outputs as a unit, not piecemeal. The codified plan is short by design (~200-400 lines architecture + ~3-8 ADRs + slice graph) — review should be a single sitting, not a series of sessions.
+
+## Adversarial review integration
+
+Every production-only decision is an ADR-worthy decision; the prototype-codifier subagent flags them all. Adversarial review runs on each proposed ADR before it's written as `accepted`. This is non-optional — production code that ships against an ADR with no recorded review is silent debt. The dedicated `/second-opinion` skill that will eventually own this work is *planned, not yet implemented* (see docs/V6-PLAN.md §11); today the review pass runs inline within harden Step 2 and writes the verdict directly into the ADR.
+
+Decisions that don't make the trigger list (variable naming, inline-vs-extract, choosing between known-good libraries with no real tradeoff) don't need ADRs at all and are NOT proposed by the subagent.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Generating architecture from imagination instead of citing the prototype | Every claim about a component cites `prototype-dir/path/to/file.ts:line@<sha7>` — if you can't cite, the claim is premature |
+| One giant `aiwiki/architecture.md` file | Split by subsystem: `data-layer.md`, `auth-flow.md`, `event-bus.md`. Each <400 lines. |
+| Writing ADRs for non-trigger-list decisions | Variable naming and inline-vs-extract are NOT ADRs. Use the trigger list strictly. |
+| Skipping adversarial review because "the decision is obvious" | If the decision is obvious it doesn't need an ADR; if it needs an ADR it needs review (today inline; `/second-opinion` dedicated surface planned) |
+| Pre-promoting raw entries during codification | Raw entries are dream's territory; harden writes to typed pages directly, raw stays raw until dream consolidates |
+| Modifying the prototype during codification | The prototype is the source of truth — leave it alone. Annotation goes in the architecture file, not in prototype source |
+| Treating the gate as advisory | Phase 6 reads these outputs; if codification is incomplete, the production build is improvising. Block until the user accepts. |
+
+## Red Flags
+
+**Never:**
+- Write production code in this phase (that's Phase 6)
+- Skip the adversarial review on any proposed ADR
+- Leave a proposed ADR with `verdict: escalate` unresolved at gate time
+- Commit to the slice graph without listing explicit dependencies between slices
+- Bypass wiki-lint on the outputs
+
+**Always:**
+- Cite the prototype file (or wireframe state) for every claim about how the system works
+- Run the focused dream after writes — it catches conflicts the codification step alone misses
+- Surface ALL outputs to the user for unified review
+- Keep the codified plan short — if it grows past ~500 lines combined, it's invented, not codified
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | Locked prototype, wireframe, concept slides, Phase 4 wiki entries, manifest |
+| **Produces** | `aiwiki/architecture/*.md`, `aiwiki/decisions/*.md` (ADRs), `aiwiki/conventions/*.md` (additions), `aiwiki/gotchas/*.md` (updates), manifest's `slice_graph` field, `.forge/work/{type}/{name}/tasks.md`, `aiwiki/sessions/*.md` |
+| **Updates manifest** | `slice_graph`, `artifacts.codify.locked_at` |
+| **Triggers** | wiki-lint on every write; phase-close dream after writes complete |
+
+## Integration
+
+| Caller | When |
+|---|---|
+| Prototype-lock event in `/feature` and `/greenfield` | Phase 4 → Phase 5 transition |
+| Manual invocation | When prototype is mature enough that production planning should begin |
+
+| Dispatches | For |
+|---|---|
+| `prototype-codifier` subagent | Bulk codification work in own context window |
+| `support-second-opinion` (`/second-opinion`) *(planned, not yet implemented)* | Adversarial review on each proposed ADR — until shipped, harden inlines this pass at Step 2 |
+| `support-dream` | Focused dream over touched subfolders after writes |
+| `support-wiki-lint` | Synchronous validation on every wiki write |
+
+| Pairs with | For |
+|---|---|
+| `iterate-prototype` | Phase 4 driver that hands off to harden at lock |
+| `build-tdd` | Phase 6 driver that reads harden's outputs as inputs |
+| `quality-code-review` | Phase 6 reviewer that checks production code against the codified architecture |

package/skills/iterate-prototype/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: iterate-prototype
+description: "Use to drive the polish loop on an in-progress prototype — read user feedback list, revise the relevant partitions, re-verify, repeat until the user emits 'satisfied' or 'LOCKED'. The polish loop after build-prototype's initial scaffold; runs sequentially (not parallel partitions). Captures gotchas + conventions discovered during iteration."
+---
+
+# Iterate Prototype
+
+## Overview
+
+After build-prototype scaffolds the initial Vite + React app from the wireframe, the user runs it locally and gives feedback: "this header is too tall", "the case detail needs a wrap-up modal", "the inbox filter is in the wrong place." This skill turns that feedback into focused revisions and verifies each one before the next.
+
+**Core principle:** the prototype iterates against the running app, not against imagined screens. Every revision cycle ends with `npm run dev` + click-through verification before the user gives the next round of feedback.
+
+**Announce at start:** "I'm using the iterate-prototype skill to apply the pending feedback to the prototype."
+
+## When to Use
+
+- After `build-prototype` finishes the initial scaffold and the user starts giving feedback
+- When the user says "polish", "iterate", "fix this", "tweak X", or names a specific feedback item
+- When the user adds entries to `pocs/{name}-prototype/.forge/feedback.md` and asks to apply them
+
+**Do NOT use this skill for:**
+- Initial scaffolding (use `build-prototype` instead)
+- Adding entirely new screens not in the wireframe (revise the wireframe first via `build-wireframe`)
+- Fixing actual bugs in production code (this is prototype-only; production bugs go through `/bugfix`)
+- Implementing real auth / real DB / production hardening (still Phase 6)
+
+## Loop modes
+
+Two modes, both opt-in:
+
+| Mode | When |
+|---|---|
+| **Manual** (default) | User adds feedback, invokes `/iterate-prototype`, reviews after revision, repeats. One cycle per invocation. |
+| **Autopilot** *(planned, not yet implemented)* | User invokes `/autopilot prototype` once. A stop-loop hook re-feeds the prompt until the user emits `LOCKED`. The skill reads feedback, applies, verifies, then yields back to the loop hook for the next cycle. See docs/V6-PLAN.md §11; until shipped, every cycle is manual. |
+
+Default to manual unless the user explicitly opts into autopilot. Autopilot's risk is iteration without human review at each step — useful for hands-off polish but easy to misuse on consequential design changes.
+
+## Inputs
+
+| Source | Required | Purpose |
+|---|---|---|
+| Running prototype at `pocs/{name}-prototype/` | yes | The codebase being iterated |
+| Locked wireframe HTML | yes | Still the spec — drift is checked against it |
+| `pocs/{name}-prototype/.forge/feedback.md` | yes | Running list of user feedback items, oldest first |
+| `pocs/{name}-prototype/.forge/partition-plan.md` | yes (from build-prototype) | Which partition each feedback item routes to |
+| Existing `aiwiki/gotchas/` and `aiwiki/conventions/` | optional | Phase 4 captures so far |
+| Manifest at `.forge/work/{type}/{name}/manifest.yaml` | yes | Phase state target |
+
+## Feedback file format
+
+`pocs/{name}-prototype/.forge/feedback.md` is a checklist:
+
+```markdown
+# Prototype Feedback
+
+## Pending
+
+- [ ] Case header is too tall on supervisor view — reduce vertical padding by 1 step
+- [ ] Inbox filter sticky-positioned at wrong y-offset on `/inbox`
+- [ ] Add an explicit "wrap up" CTA on case detail (currently only via menu)
+
+## Resolved
+
+- [x] (2026-05-09) Wireframe `s2` had a left rail; prototype was missing it — added
+- [x] (2026-05-09) Tutorial overlay click-target too small — bumped hit area
+```
+
+The skill reads the `## Pending` section, applies each item in order, then moves resolved items to `## Resolved` with the date.
+
+The user appends to `## Pending` between iterations. Manual mode runs one batch of pending items per invocation; autopilot mode keeps draining until pending is empty AND the user emits LOCKED.
+
+## Process
+
+### Step 0: locate inputs
+
+| Input | How to find |
+|---|---|
+| Repo root | `git rev-parse --show-toplevel` or `${CLAUDE_PROJECT_DIR}` |
+| Manifest | The single in-progress manifest under `.forge/work/*/*/manifest.yaml`. Multiple = ask user. |
+| Prototype path | Manifest's `artifacts.prototype.path`, or default `pocs/{name}-prototype/` |
+| Wireframe path | Manifest's `wireframe_path`, or default `pocs/{name}-wireframe/index.html` |
+| Feedback file | `<prototype-path>/.forge/feedback.md` |
+| Partition plan | `<prototype-path>/.forge/partition-plan.md` |
+
+If `artifacts.prototype.locked_at` is already present in the manifest, surface the gap and stop — iterate runs while the prototype phase is open, not after lock. Otherwise the prototype phase is open: proceed.
+
+### Step 1: read pending feedback
+
+Parse `## Pending` from the feedback file. Each line that begins with `- [ ]` is an unresolved item.
+
+If no pending items: report "No pending feedback to apply" and stop. The skill is a no-op when there's nothing to do.
+
+### Step 2: route feedback items to partitions
+
+For each pending item, identify which partition the change touches by reading the partition plan and the feedback content.
+
+Three routing patterns:
+
+| Feedback shape | Routing |
+|---|---|
+| Names a specific screen ("case detail header...") | Route to that screen's partition |
+| Names a system area ("tutorial overlay..., notifications...") | Route to that system's partition |
+| Cross-cutting (design tokens, shared component, global state) | Dispatch a single instance of `prototype-builder` covering the shared scaffold (NOT a partition) |
+
+If a feedback item is genuinely ambiguous (could touch multiple partitions), dispatch one builder per affected partition with the item scoped to "your-partition's expression of <feedback>".
+
+### Step 3: dispatch sequentially per partition
+
+Unlike build-prototype's parallel dispatch, iterate-prototype runs sequentially. Reasons:
+
+- Feedback items are usually small, individually scoped
+- Sequential application keeps the diff reviewable per item
+- Parallel revisions of the same partition would conflict
+
+For each pending item:
+
+1. Dispatch `prototype-builder` with the item scoped to the relevant partition (or shared scaffold)
+2. Subagent returns the diff (changed files, content)
+3. Apply the diff
+4. Mark the item resolved
+
+For cross-cutting items that touch multiple partitions, route to each in turn (still sequential).
+
+### Step 4: verify after each cycle (or after the batch in autopilot)
+
+In manual mode, after applying the batch:
+
+```bash
+cd pocs/{name}-prototype
+npm run dev          # smoke test
+# user clicks through; provides next round of feedback
+```
+
+In autopilot mode, after each individual item is applied:
+
+```bash
+cd pocs/{name}-prototype
+npm run dev &
+sleep 2  # give Vite time to compile
+npx playwright codegen http://localhost:5173 --output /tmp/codegen.spec.ts &
+# script kills after sanity check; the codegen output is for human review later
+```
+
+Verification doesn't replace user judgment — it just catches obvious breakage (compile errors, missing routes). The user is still the final reviewer.
+
+### Step 5: dispatch prototype-reviewer for drift check (optional, every 5 cycles or on demand)
+
+After ~5 iteration cycles, drift between prototype and wireframe accumulates silently. Dispatch `prototype-reviewer` to flag:
+
+- Wireframe states that no longer have a matching prototype screen
+- Prototype screens that aren't in the wireframe (undocumented features)
+- Interaction model deviations (e.g. wireframe shows modal, prototype now uses sheet)
+- Convention drift (file naming, import order, design token usage)
+
+The reviewer returns findings; the user decides whether to update the wireframe (codify the change) or revert the prototype (restore alignment). Either way, the next iteration starts from a known-aligned state.
+
+In autopilot, the reviewer runs every 5 cycles automatically. In manual, it runs on demand or when the user invokes `/check-prototype-drift`.
+
+### Step 6: capture side effects during iteration
+
+Each iteration may surface gotchas or conventions. The dispatched prototype-builder subagent will write these to `aiwiki/` per the gotcha and convention schemas. The wiki-lint hook validates on save.
+
+If the prototype-builder reports a gotcha that already exists (matched by root cause), bump the existing gotcha's `occurrences` field instead of creating a duplicate. If `occurrences` reaches 3+, the gotcha is auto-drafted as a `proposed_rule:` block — the next session-start will hard-interrupt to require user approval before promoting it.
+
+### Step 7: update the feedback file
+
+After each batch (manual) or each item (autopilot):
+
+- Move resolved items from `## Pending` to `## Resolved` with date
+- Keep pending items that weren't applied (e.g. user reordered priorities)
+
+### Step 8: detect convergence
+
+Two convergence signals:
+
+| Signal | Meaning |
+|---|---|
+| User emits "satisfied", "LOCKED", "done", or equivalent | Phase 4 is closing — set manifest's `artifacts.prototype.{path, locked_at}` and stop the loop |
+| Iteration count reaches 10 cycles since last alignment check | Run prototype-reviewer drift check before continuing; surface "are we converging?" if drift is high |
+
+In autopilot mode, the loop hook reads the LOCKED signal from the manifest and exits cleanly.
+
+## Anti-fatigue
+
+If pending feedback grows past 10 items without any being resolved, the loop is not iterating — it's accumulating. Surface this to the user explicitly: "Pending list has grown to N items without resolution; consider whether the wireframe needs an update before continuing prototype iteration." This is the prototype-equivalent of the wiki accept-fatigue safeguard.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Running parallel revisions of the same partition | Sequential only in iterate; parallel is build-prototype's territory |
+| Skipping drift check across many iteration cycles | Drift accumulates silently; run `prototype-reviewer` every 5 cycles or surface the gap |
+| Applying feedback that asks for new screens | New screens require wireframe revision first; surface the gap, do not extrapolate |
+| Hardening the prototype during iteration | Phase 4 is still the prototype; real auth / real DB / production-grade error handling stays out |
+| Letting feedback file grow unbounded without convergence signal | Anti-fatigue: surface explicit "pending growing without resolution" warning at >10 unresolved |
+| Forgetting to capture gotchas surfaced during iteration | Gotchas are Phase 5 inputs; they must land in `aiwiki/gotchas/` to feed harden |
+| Bypassing wiki-lint on captured gotchas/conventions | Hook fires automatically; if it's bypassed, lint manually after |
+
+## Red Flags
+
+**Never:**
+- Add screens not in the wireframe (revise the wireframe first)
+- Lock the prototype with known broken interactions (the lock signal means "production should match this")
+- Run autopilot mode on consequential design changes (e.g. layout overhaul) — autopilot is for polish, not redesign
+- Skip drift checks indefinitely (5-cycle cadence is the floor)
+
+**Always:**
+- Sequential dispatch (one prototype-builder at a time during iterate)
+- Update the feedback file as items resolve
+- Run `npm run dev` between cycles in manual mode
+- Capture gotchas + conventions to `aiwiki/` as they surface
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | Running prototype, locked wireframe, feedback file, partition plan, manifest |
+| **Produces** | Code changes in `pocs/{name}-prototype/`, updated `pocs/{name}-prototype/.forge/feedback.md`, gotchas + conventions in `aiwiki/` |
+| **Updates manifest** | `artifacts.prototype.{path, locked_at}` on convergence |
+| **Triggers** | wiki-lint on every `aiwiki/**` write; phase-close dream when prototype locks |
+
+## Integration
+
+| Caller | When |
+|---|---|
+| Manual `/iterate-prototype` | User-driven polish cycle |
+| `/autopilot prototype` *(planned, not yet implemented)* | Stop-loop hook re-feeds the prompt; this skill runs once per cycle |
+| `build-prototype` final step | After initial scaffold + first verification, hands off to iterate-prototype for refinement |
+
+| Dispatches | For |
+|---|---|
+| `prototype-builder` (sequential, per partition) | Code revisions for each feedback item |
+| `prototype-reviewer` (every 5 cycles or on demand) | Drift check between prototype and wireframe |
+
+| Pairs with | For |
+|---|---|
+| `build-prototype` | Initial scaffold predecessor |
+| `harden` | Phase 5 successor — runs once iterate-prototype emits the LOCKED signal |
+| `support-gotcha` | Captures gotchas during iteration |
+| `support-wiki-lint` | Validates gotcha + convention writes |