@jamie-tam/forge 6.0.0 → 6.1.0

package/rules/common/forge-system.md

@@ -1,5 +1,5 @@
 ---
-description: Forge system structure — skills (prefix-grouped), commands (orchestrate skills), .forge/ directory layout, context recovery. Auto-loaded every session so agents know the system they're operating in.
+description: Forge system structure — skills (prefix-grouped), commands (orchestrate skills), .forge/ directory layout, aiwiki/ knowledge layer, context recovery. Auto-loaded every session so agents know the system they're operating in.
 ---
 
 # Forge System
@@ -23,14 +23,15 @@ v6 also adds phase skills: concept-slides, build-wireframe, build-prototype, ite
 
 | Command | When to use |
 |---------|------------|
-| `/forge` | One-screen discovery — installed capabilities, active work, suggested next |
+| `/discover` | One-screen discovery — installed capabilities, active work, suggested next |
 | `/setup` | Detect stack, install matching language rules, and fill the project profile |
 | `/feature` | Full feature development |
 | `/greenfield` | New project from zero |
 | `/bugfix` | Fix a bug |
 | `/refactor` | Improve existing code |
 | `/hotfix` | Emergency production fix |
-| `/evolve` | Improve the forge system itself |
+| `/note <text>` | Capture an ad-hoc research note or brainstorm to `aiwiki/raw/{date}.md` |
+| `/forge-evolve` | Improve the forge system itself |
 | `/validate` | Check skill consistency |
 
 ## .forge/ Directory
@@ -46,10 +47,47 @@ v6 also adds phase skills: concept-slides, build-wireframe, build-prototype, ite
   state/                       # Runtime state (notepad.md, telemetry, dream history)
 ```
 
-Project knowledge (ADRs, gotchas) lives under `aiwiki/` — see `aiwiki/decisions/` and `aiwiki/gotchas/`. The `.forge/` directory retains operational state only (manifests, telemetry, dream history).
+The `.forge/` directory retains operational state only (manifests, telemetry, dream history). Project knowledge lives in `aiwiki/` (next section).
 
 Work items are identified by `{type}/{name}` — names may collide across types.
 
+## aiwiki/ (knowledge layer)
+
+`aiwiki/` accumulates lasting project knowledge — separate from `.forge/` which is operational state. Subagents read these pages to inform their work, so the typed pages have schemas enforced by `wiki-lint`.
+
+| Page type | Purpose | Written by |
+|---|---|---|
+| `decisions/` | ADRs — architecture decisions + rationale | `plan-brainstorm`, `harden`, manual |
+| `gotchas/` | Recurring failure modes with reproducible fixes | `iterate-prototype`, `quality-code-review`, manual |
+| `conventions/` | Established patterns in this codebase | `iterate-prototype`, `harden`, manual |
+| `architecture/` | Component maps, sequence diagrams | `harden`, manual |
+| `sessions/` | Per-session work notes (index-of-links) | manual or `harden` at codify; session-checkpoint hooks deferred |
+| `oracle/` | Trusted external references (RFCs, vendor docs) | manual |
+| `raw/` | Append-only research/brainstorm capture (no schema) | `/note <text>`, manual |
+
+**Auto-capture during phases.** `iterate-prototype` (Phase 4) writes gotchas and conventions surfaced during prototype iteration. Phases 1 (concept) and 2 (wireframe) have **no auto-capture** — use `/note <text>` to land research/brainstorm in `aiwiki/raw/{date}.md`.
+
+**Lint** (`wiki-lint` PostToolUse hook). Fires on every `aiwiki/**.md` write (Edit/Write/MultiEdit). Validates frontmatter, required H2 sections, line caps, citation hash drift, and possible-secret patterns in cited content against the page's schema. Skips `aiwiki/raw/` (no schema) and `aiwiki/proposed/` (lint runs there separately at dream-complete). Findings surface on stderr — non-blocking, but the next edit should address them.
+
+**Dream** (`support-dream` skill). Async consolidation:
+- **PreCompact** (~85% context): consolidates `aiwiki/raw/` + recently-touched typed pages before lossy compaction. (Session-file refinement deferred until session-checkpoint hooks ship — see `aiwiki/sessions/` row above.)
+- **Phase-close** (Phase 4/5/6/7 lock): promotes phase outputs into curated wiki state. The next phase **blocks** until the user reviews the proposed dream.
+- **Manual `/dream`**: user-driven cleanup.
+
+Dream outputs to `aiwiki/proposed/{dream_id}/` — input store is never modified. User atomically accepts (swap) or rejects (discard) via `forge wiki accept` / `reject`.
+
+### When the AI should write to aiwiki
+
+The default is **don't**. The user-customizable `aiwiki/CLAUDE.md` (auto-loaded when `aiwiki/` is scaffolded by `/setup`) carries the per-page-type writing rules; respect them. Three reminders that override any temptation to over-capture:
+
+1. **Never write speculation, conversation history, or "we might want to revisit this" notes.** This is the strongest rule in `aiwiki/CLAUDE.md`. Wiki pages answer recurring questions; conversational asides do not.
+2. **Typed pages need durable, reusable knowledge.** Decisions go to `aiwiki/decisions/` only after the decision is finalized (architectural, public-surface, security, schema, or other hard-to-reverse choice). Gotchas to `aiwiki/gotchas/` only when the failure mode is reproducible with a concrete fix. Conventions to `aiwiki/conventions/` only when the pattern is established across multiple sites. If the knowledge isn't yet durable, it doesn't belong in a typed page.
+3. **Ad-hoc research, half-formed thoughts, deferred decisions, comparison notes — these go to `aiwiki/raw/` ONLY when the user explicitly invokes `/note <text>`.** The AI does not autonomously decide to write conversational content to raw. The user is the gate.
+
+If a typed-page-worthy insight emerges mid-conversation (e.g., "this is a real gotcha"), you MAY write it to the correct typed page — but only if it meets that page's durability test. When in doubt, ask the user.
+
+**Session-end handoff.** Forge has no automated session-end capture mechanism. If a session produced durable knowledge that warrants persisting, the AI should OFFER to write the appropriate typed pages before ending the session — never silently. The user accepts or declines.
+
 ## Context Recovery
 
 If `.forge/state/notepad.md` exists, read it FIRST before doing anything else.

package/skills/build-prototype/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: build-prototype
-description: "Use to scaffold a working POC from a locked wireframe. Produces a runnable Vite + React + TS app at pocs/{name}-prototype/ with seed data, in-memory state, and screens that mirror the wireframe states. The prototype is the verification surface for concept + UX before any production code is written."
+description: "Use to scaffold a working POC from a locked wireframe — triggered by phrases like 'build the prototype', 'scaffold the POC', 'wireframe is locked, start the prototype', 'turn the wireframe into something I can run', 'make it interactive', or by the wireframe-lock event in /feature and /greenfield (Phase 2 → Phase 3 transition). Produces a runnable Vite + React + TS + Tailwind + Zustand app at pocs/{name}-prototype/ with seed data, in-memory state, and screens mirroring the wireframe's locked states. The prototype is the verification surface for concept + UX before any production code is written. Skip if the wireframe is not locked (run build-wireframe first), if a prototype already exists at the target path (use iterate-prototype for changes), or if the work is production code under TDD (use build-tdd at Phase 6)."
 ---
 
 # Build Prototype
@@ -15,7 +15,7 @@ Once a wireframe is locked, the prototype turns it into something the user can r
 
 ## When to Use
 
-- Phase 4 of a prototype-driven flow (after wireframe is locked, before Phase 5 codification)
+- Phase 3 of a prototype-driven flow (after wireframe is locked, before Phase 4 iteration and Phase 5 codification)
 - For `/feature` on existing apps: scaffold a `pocs/{feature-name}-prototype/` mini-prototype branch of the existing app's tech stack — same skill, smaller scope
 - Ad-hoc when a wireframe is mature enough to validate via running code
 
@@ -176,7 +176,7 @@ Capture findings in `pocs/{name}-prototype/.forge/feedback.md` if there's any dr
 
 ### Step 5: side-effect capture during iteration
 
-Phase 4 is also when real gotchas + conventions emerge. During iteration:
+Phase 3 (prototype build) and Phase 4 (iteration) are when real gotchas + conventions emerge. During the build and iteration cycles:
 
 - **Gotchas**: every time prototype-builder hits a state-management surprise, library quirk, framework mounting issue, or type-system pothole, write to `aiwiki/gotchas/{date}-{slug}.md` per the gotcha schema. The wiki-lint hook validates on save.
 - **Conventions**: when patterns settle (file naming, import order, state-shape conventions, design-token usage), write to `aiwiki/conventions/{slug}.md`. The `prototype-reviewer` flags new conventions emerging across iteration cycles.
@@ -249,7 +249,7 @@ Document the choice in `pocs/{name}-prototype/README.md` so Phase 5 codification
 
 | Caller | When |
 |---|---|
-| Wireframe-lock event in `/feature` and `/greenfield` | Phase 3 → Phase 4 transition |
+| Wireframe-lock event in `/feature` and `/greenfield` | Phase 2 → Phase 3 transition |
 | Manual invocation | When a wireframe is mature enough to verify via running code |
 
 | Dispatches | For |

package/skills/build-tdd/SKILL.md

@@ -67,6 +67,20 @@ Do not ask the user. The decision was persisted at task decompose handoff.
 
 When architecture artifacts exist (from `plan-architecture` or `harden`), use them to set unit-test expectations for shapes, constraints, and error behavior. Treat those contracts as the source of truth for assertions at the unit boundary. Integration tests at boundaries identified by `harden`'s slice graph are required per the Wiring Coverage subsection above — they are not optional even when the task description omits them.
 
+## Oracle Satisfaction
+
+When `harden` (Phase 5) ran, it captured prototype behavior as integration-test oracles at `aiwiki/oracles/{slug}.md` — one per slice or subsystem. These are the load-bearing contract: production code must reproduce the oracle's `Setup → Trigger → Assertions`. They close the wiring gap that mock-heavy unit tests miss (the Flux/REACH dogfood signal that drove v6).
+
+**Before writing the first RED test for a slice:**
+
+1. Read every oracle whose `slug` or `prototype_path` matches the slice being built (the slice graph entry produced by harden references its oracles).
+2. For each oracle, design at least one test that exercises its `Setup → Trigger → Assertions`. That test counts as the boundary integration test for Wiring Coverage above — so the oracle test and the wiring test are usually the same test.
+3. If the slice crosses a wiring boundary (CLI ↔ filesystem, process exec, manifest I/O, external services) and **no oracle exists for that boundary**, halt and surface to the user. Do NOT invent oracles inline; do NOT proceed against an empty oracle directory. Missing oracles mean harden has not closed — re-run harden to capture them, or surface to the user that the slice is being built without a verified prototype contract.
+
+When this skill dispatches the **builder** subagent (manifest's `execution.mode: subagent`), the agent enforces the same discipline (see [agents/builder.md](../../agents/builder.md) "Oracles Are Load-Bearing"). When running inline, the orchestrator (this skill) is responsible — load the oracles before the first RED.
+
+If `phase_plan.codify: skipped` for this work item (typical for trivial bugfixes that bypass harden), no oracles are expected — note the skip in the work-item notes and proceed.
+
 ## Codex Integration
 
 **Mode:** Delegate | **Protocol:** `protocols/codex.md`

package/skills/concept-slides/SKILL.md

@@ -15,7 +15,7 @@ A concept deck is the cheapest artifact in the pipeline. It exists to verify the
 
 ## When to Use
 
-- Phase 2 of a prototype-driven flow (after discovery, before wireframing)
+- Phase 1 of a prototype-driven flow (after discovery, before wireframing)
 - For `/feature` on existing apps: a 1-3 slide mini-deck — what the feature is, where it sits, the visual sketch. Often a single slide.
 - Ad-hoc when a user wants to put a concept on paper before building anything
 
@@ -46,8 +46,8 @@ The deck is rendered with `marp` and previewed in HTML so the user can click thr
 
 ## What concept-slides does NOT produce
 
-- A wireframe (Phase 3 deliverable; uses `build-wireframe` skill)
-- A prototype (Phase 4 deliverable; uses `build-prototype` skill)
+- A wireframe (Phase 2 deliverable; uses `build-wireframe` skill)
+- A prototype (Phase 3 deliverable; uses `build-prototype` skill)
 - An architecture doc (Phase 5 deliverable; uses `harden`)
 - A finalized pitch deck (use `marp-slides` directly for finalized presentations)
 
@@ -58,7 +58,7 @@ If the user asks for "a real deck for the leadership pitch," use `marp-slides` w
 | Source | Required | Purpose |
 |---|---|---|
 | Rough concept brief from the user | yes | One-sentence to one-paragraph description of what's being built |
-| Discovery output (if existing repo) | if Phase 1 ran | Codebase conventions, existing UX patterns to align with |
+| Discovery output (if existing repo) | if discovery ran | Codebase conventions, existing UX patterns to align with |
 | Reference decks the user likes | optional | Style/composition reference (links or paths) |
 
 ## Process
@@ -119,13 +119,13 @@ Re-dispatch the subagent with the feedback as part of the prompt; rewrite the de
 
 ### Step 5: lock
 
-When the user emits "concept locked" (or equivalent), the phase closes. The locked deck is the input to Phase 3 (`build-wireframe`).
+When the user emits "concept locked" (or equivalent), the phase closes. The locked deck is the input to Phase 2 (`build-wireframe`).
 
 Update the manifest at `.forge/work/{type}/{name}/manifest.yaml`:
 - `artifacts.concept.deck_path: decks/{name}/slides.md`
 - `artifacts.concept.locked_at: <ISO-8601 timestamp>`
 
-Presence of `artifacts.concept.locked_at` is the lock signal that Phase 3 (`build-wireframe`) reads to confirm the concept is locked before proceeding.
+Presence of `artifacts.concept.locked_at` is the lock signal that Phase 2 (`build-wireframe`) reads to confirm the concept is locked before proceeding.
 
 ## Visual sketch guidance
 
@@ -146,7 +146,7 @@ Avoid:
 | Mistake | Fix |
 |---|---|
 | Treating the deck as a finalized pitch | It's a draft; lower the polish bar to "sketch-grade" |
-| Embedding real UI mockups | Move that to Phase 3 wireframe; sketches in the deck are boxes-and-arrows |
+| Embedding real UI mockups | Move that to Phase 2 wireframe; sketches in the deck are boxes-and-arrows |
 | Producing a 30-slide deck | Cap at 15 for full products, 3 for features. Cut or split. |
 | Skipping the "out of scope" slide | The deferral list IS the spec — what NOT to build is as important as what to build |
 | Iterating with the user before the first render | Render first, get feedback against something concrete; don't iterate against imagined slides |
@@ -158,7 +158,7 @@ Avoid:
 - Build a polished marketing deck under this skill (different intent — use `marp-slides` directly)
 - Skip the "out of scope" slide — defining what's NOT built is half the value
 - Iterate without rendering — text-only edits invite imaginary feedback
-- Carry a draft to Phase 3 without an explicit user lock
+- Carry a draft to Phase 2 without an explicit user lock
 
 **Always:**
 - Render to HTML and let the user click through — that's the iteration surface
@@ -172,13 +172,13 @@ Avoid:
 | **Requires** | User brief, target output path, optional discovery output |
 | **Produces** | `decks/{name}/slides.md` (marp source) + `decks/{name}/slides.html` (rendered preview) |
 | **Updates manifest** | `artifacts.concept.{deck_path, locked_at}` |
-| **Feeds into** | `build-wireframe` (Phase 3 — wireframe extends the visual sketches into clickable HTML) |
+| **Feeds into** | `build-wireframe` (Phase 2 — wireframe extends the visual sketches into clickable HTML) |
 
 ## Integration
 
 | Caller | When |
 |---|---|
-| Phase 2 of `/feature` and `/greenfield` | Default flow entry point for prototype-driven work |
+| Phase 1 of `/feature` and `/greenfield` | Default flow entry point for prototype-driven work |
 | Manual invocation | When a concept needs sketching outside a workflow |
 
 | Dispatches | For |
@@ -188,5 +188,5 @@ Avoid:
 | Pairs with | For |
 |---|---|
 | `marp-slides` (user-level skill) | Underlying rendering engine — concept-slides specializes the format |
-| `build-wireframe` | Phase 3 successor — wireframer reads the locked deck as input |
+| `build-wireframe` | Phase 2 successor — wireframer reads the locked deck as input |
 | `discover-codebase-analysis` | If existing repo, supplies UX/convention context |

package/skills/deliver-deploy/SKILL.md

@@ -298,7 +298,7 @@ VERDICT: Ready to deploy
 3. **Trigger Post-Deploy Skills**
    - If documentation needs updating, flag for `deliver-onboarding`
    - If any issues were encountered during deploy, invoke `support-gotcha`
-   - If deployment revealed process improvements, note for `/evolve`
+   - If deployment revealed process improvements, note for `/forge-evolve`
 
 ## Rollback Procedures
 

package/skills/harden/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+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 — re-iterate or restart instead."
 ---
 
 # Harden
@@ -48,7 +48,7 @@ The expected total is short: ~200-400 lines across all architecture files combin
 - 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`)
+- Does NOT skip the adversarial-review step on ADRs — every production ADR is reviewed inline at Step 2: harden runs the review pass and records reviewer, objections, resolutions, and verdict in the ADR `review:` block before promoting to `accepted`. If Codex is configured (`protocols/codex.md`), the review pass may dispatch Codex in verify mode; otherwise Claude performs the pass directly.
 
 ## Inputs
 
@@ -102,7 +102,7 @@ The subagent does NOT write the files itself — it returns the proposals. The m
 
 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).
+For each proposed ADR, run an adversarial review pass and write a structured `review:` block (reviewers, objections, resolutions, verdict) into the draft. The review is performed 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. If Codex is configured (`protocols/codex.md`), dispatch it in verify mode to perform the review pass and merge its findings; otherwise Claude runs the pass directly.
 
 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.
 
@@ -153,7 +153,7 @@ The user reviews ALL outputs as a unit, not piecemeal. The codified plan is shor
 
 ## 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.
+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 review pass runs inline within harden Step 2 and writes the verdict directly into the ADR. When Codex is configured (`protocols/codex.md`), the pass may be dispatched to Codex in verify mode; otherwise Claude performs it directly.
 
 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.
 
@@ -164,7 +164,7 @@ Decisions that don't make the trigger list (variable naming, inline-vs-extract,
 | 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) |
+| 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 (performed inline at Step 2, optionally via Codex verify mode) |
 | 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. |
@@ -203,7 +203,7 @@ Decisions that don't make the trigger list (variable naming, inline-vs-extract,
 | 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 |
+| Codex (verify mode, via `protocols/codex.md`) | Optional adversarial review on each proposed ADR — if Codex is not configured, harden runs the review pass inline at Step 2 |
 | `support-dream` | Focused dream over touched subfolders after writes |
 | `support-wiki-lint` | Synchronous validation on every wiki write |
 

package/skills/quality-test-execution/SKILL.md

@@ -63,6 +63,31 @@ Now that the test plan is parsed and files are verified, run the Codex consent f
 - **Takeover:** Dispatch Codex with the test plan to execute tests and produce the results report. Claude reviews test quality and coverage.
 - **Verify** or **Skip / Codex unavailable:** Proceed with the steps below. The Codex Verify note in Step 9 will dispatch Codex to review test quality (Verify only).
 
+### Step 1.6: Oracle Coverage Check
+
+Before any test runs, verify that every oracle in `aiwiki/oracles/` for this work item is mapped to a test in the plan. Oracles are the Phase 5 (harden) contract — production code must reproduce the prototype's verified behavior. This is the load-bearing closure of the mock-pass / real-break wiring gap; running tests without checking oracle coverage re-creates the gap.
+
+1. Enumerate `aiwiki/oracles/*.md`. Filter to oracles whose `prototype_path` is within this work item's scope (typically `pocs/{name}-prototype/`).
+2. For each in-scope oracle, find the matching test ID(s) in the test plan's "Map Oracles to Tests" table (produced by `quality-test-plan` Step 2.3).
+3. **If any in-scope oracle is unmapped, halt:**
+
+```
+ORACLE COVERAGE FAILURE:
+Unmapped oracle: aiwiki/oracles/auth-login-success.md
+  Type: interaction
+  prototype_path: pocs/myapp-prototype/src/auth/Login.tsx
+  No test in test-plan.md cites this oracle.
+
+Cannot execute the test plan. Mock-heavy tests pass while real integration
+breaks (the wiring gap) — the chain closes only when every oracle has a
+test. Resolve by:
+  (a) Returning to quality-test-plan and adding a test that satisfies the
+      oracle, OR
+  (b) Re-running harden if the oracle is stale or out of scope.
+```
+
+4. **Skip condition:** If no oracles exist for this work item (the test plan recorded "No oracles in scope" in Step 2.3, or `aiwiki/oracles/` is empty for the scope), record "No oracles in scope" in the results and proceed. The check is non-blocking when oracle capture wasn't part of the lifecycle.
+
 ### Step 2: External Service Availability Check
 
 Before executing any tests, determine which external services are available for real testing.
@@ -393,7 +418,7 @@ Do not execute only unit tests and declare success. All test types from the plan
 
 | Field | Value |
 |---|---|
-| **Requires** | Test plan (`.forge/work/{type}/{name}/test-plan.md`) + implementation code (from `build-tdd`) + architecture artifacts (`.forge/work/{type}/{name}/architecture/api-contract.md` for external service verification) |
+| **Requires** | Test plan (`.forge/work/{type}/{name}/test-plan.md`) + implementation code (from `build-tdd`) + architecture artifacts (`.forge/work/{type}/{name}/architecture/api-contract.md` for external service verification) + oracle pages (`aiwiki/oracles/*.md` from harden Step 2.5) when codify ran |
 | **Produces** | `.forge/work/{type}/{name}/test-results.md` |
 | **Feeds into** | `deliver-deploy` (via quality gate -- zero failures required) |
 | **Updates manifest** | `artifacts.test-results: test-results.md`, `phases.quality.test-execution: { status: complete, gate-passed: true }` |

package/skills/quality-test-plan/SKILL.md

@@ -96,6 +96,26 @@ Create a traceability matrix:
 
 **Rule:** Every acceptance criterion MUST have at least one test. If a criterion has no test, the plan is incomplete.
 
+### Step 2.3: Map Oracles to Tests
+
+If `aiwiki/oracles/` contains oracle pages for slices in this work item, every in-scope oracle MUST appear in the traceability matrix with at least one mapped test. Oracles are the prototype-derived behavioral contract from Phase 5 (harden); production code is not "tested" if oracles are unverified. This is the load-bearing closure of the mock-pass / real-break wiring gap (Flux/REACH dogfood signal).
+
+For each `aiwiki/oracles/{slug}.md` whose `prototype_path` is within this work item's scope (typically `pocs/{name}-prototype/`):
+
+```markdown
+| Oracle | Type | Setup → Trigger → Assertions cite | Mapped tests |
+|---|---|---|---|
+| `auth-login-success` | interaction | `pocs/myapp-prototype/src/auth/Login.tsx:42` | IT-003, E2E-001 |
+| `dashboard-renders-empty-state` | render | `pocs/myapp-prototype/src/Dashboard.tsx:18` | IT-005 |
+| `checkout-applies-discount-code` | golden-trace | `pocs/myapp-prototype/src/checkout/apply.ts:67` | IT-012, CONTRACT-004 |
+```
+
+**Rule:** Every in-scope oracle MUST have at least one test that exercises its `Setup → Trigger → Assertions`. Unmapped oracles fail this step — either add tests to cover them, or surface to the user that harden's oracle capture missed a slice.
+
+The mapped test SHOULD be an integration or E2E test (oracles describe boundary behavior; unit tests with mocks at the boundary don't satisfy them). A pure-unit test mapping is acceptable only when the oracle is itself a unit-level invariant (rare).
+
+**Skip condition:** If `phase_plan.codify: skipped` for this work item or `aiwiki/oracles/` is empty for the work scope, record "No oracles in scope" in the plan and proceed. The check is non-blocking when oracle capture wasn't part of the lifecycle (e.g. trivial bugfix routed past harden).
+
 ### Step 2.5: Map User Journeys to E2E Scenarios
 
 If the requirements document includes a User Journeys section, create a business flow traceability table. Every journey MUST map to an E2E test scenario. Gaps are flagged before test execution.
@@ -237,7 +257,7 @@ If the critic identifies coverage gaps or missing scenarios, address them before
 
 | Field | Value |
 |---|---|
-| **Requires** | Implementation code (from `build-tdd`), architecture artifacts (`.forge/work/{type}/{name}/architecture/`), requirements (`.forge/work/{type}/{name}/requirements.md`) |
+| **Requires** | Implementation code (from `build-tdd`), architecture artifacts (`.forge/work/{type}/{name}/architecture/`), requirements (`.forge/work/{type}/{name}/requirements.md`), oracle pages (`aiwiki/oracles/*.md` from harden Step 2.5) when codify ran |
 | **Produces** | `.forge/work/{type}/{name}/test-plan.md` |
 | **Feeds into** | `quality-test-execution` (test plan drives execution) |
 | **Updates manifest** | `artifacts.test-plan: test-plan.md` |

package/skills/support-debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: support-debug
-description: "Use when encountering any bug, test failure, error, crash, or unexpected behavior — enforces systematic root cause investigation."
+description: "Use when a bug, test failure, error, crash, or unexpected behavior needs systematic investigation — triggered by phrases like 'debug this', 'why is X failing', 'trace this error', 'figure out what's wrong', 'investigate the failure', 'this is broken', 'help me debug'. Enforces a four-phase process (fact-check → root-cause investigation → hypothesis testing → implementation) with a 3-fix threshold that stops the random-fix spiral. Skip when the user is asking a design or architecture question (not a failure to investigate), when the failure is a known limitation already documented, or when the work is prototype iteration where the lightweight feedback loop in iterate-prototype is the right shape."
 ---
 
 # Support: Debug

package/skills/support-dream/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: support-dream
-description: "Use when the user asks to 'consolidate the wiki', 'clean up aiwiki', 'merge duplicate notes', 'prune stale gotchas', or when /evolve runs maintenance. Also auto-fires on phase-close or when context approaches compaction (~85%). Merges aiwiki duplicates, resolves contradictions, refreshes the session index. Output goes to aiwiki/proposed/ for user review — input is never modified."
+description: "Use when the user asks to 'consolidate the wiki', 'clean up aiwiki', 'merge duplicate notes', 'prune stale gotchas', or when /forge-evolve runs maintenance. Also auto-fires on phase-close or when context approaches compaction (~85%). Merges aiwiki duplicates, resolves contradictions, refreshes the session index. Output goes to aiwiki/proposed/ for user review — input is never modified."
 ---
 
 # Support: Dream (Wiki Consolidation)
@@ -22,7 +22,7 @@ Three triggers, distinct intents:
 | Trigger | Intent | Scope |
 |---|---|---|
 | **Phase close** (Phase 4 (iterate) lock, Phase 5 (codify) lock, Phase 6 (production-build) per-slice close, Phase 7 (deliver) retrospective) | Promote phase outputs into curated wiki state | Subfolders touched by the phase |
-| **PreCompact hook fire** (~85% context utilization) | Consolidate session signal into durable form before lossy compaction | `aiwiki/sessions/{current}` + `aiwiki/raw/` + recently-touched typed pages |
+| **PreCompact hook fire** (~85% context utilization) | Consolidate signal into durable form before lossy compaction | `aiwiki/raw/` + recently-touched typed pages. If `aiwiki/sessions/{current}.md` exists, refine it too; if not, skip (session-checkpoint hooks deferred — see `templates/aiwiki/schemas/session.md`). |
 | **Manual `/dream`** | User-driven cleanup (after major refactor, branch merge, accumulated noise) | User-specified |
 
 **Do NOT skip when:**
@@ -57,12 +57,12 @@ Fired by phase-close hooks (after user emits the phase-lock signal):
 
 Fired by forge's existing pre-compact hook (~85% context):
 
-1. Hook calls skill with scope `[aiwiki/sessions/{current}, aiwiki/raw/, recently-touched-typed-pages]`
-2. **Sync prerequisite** — session checkpoint hook has already updated `aiwiki/sessions/{current}.md` with all events. Dream IMPROVES this file; does not produce its existence.
+1. Hook calls skill with scope `[aiwiki/raw/, recently-touched-typed-pages]`. If `aiwiki/sessions/{current}.md` exists, ALSO include it in scope.
+2. **Conditional session prerequisite** — if `aiwiki/sessions/{current}.md` exists (session-checkpoint hooks shipped and active), dream IMPROVES it; does not produce its existence. If it does NOT exist (current state — session-checkpoint hooks deferred), dream SKIPS session-file refinement and consolidates raw/typed pages only. No `SESSION_FILE_MISSING` failure.
 3. Dispatches `dreamer` subagent
 4. Output to `aiwiki/proposed/{dream_id}/`
 5. LINT runs on proposed output
-6. Native compaction proceeds (does not wait for user review — the consolidated session file is already on disk)
+6. Native compaction proceeds (does not wait for user review — the consolidated raw/typed pages are already on disk)
 
 ### Manual /dream trigger
 

package/skills/support-gotcha/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: support-gotcha
-description: "Use when a subtle bug, surprising behavior, or hard-won lesson is uncovered that could recur — records it as a typed wiki page for future prevention."
+description: "Use when a reproducible failure mode, hard-won lesson, or surprising behavior with a concrete trigger emerges and is worth preventing next time — triggered by phrases like 'record this gotcha', 'save this lesson', 'capture this finding', 'we should remember this', 'this is a gotcha', 'log this for future', or automatically after support-debug closes a non-trivial bug. Writes a typed page to aiwiki/gotchas/{date}-{slug}.md with reproduction steps, root cause, and concrete fix; promotes to a rule when the same pattern recurs (N=3). Skip for speculation or half-formed thoughts (use /note for those); skip if the failure mode is not reproducible — a gotcha needs a concrete trigger, not a vibe."
 ---
 
 # Support: Gotcha
@@ -43,7 +43,7 @@ Every bug fixed, every failed approach, every "I wish I'd known that earlier" mo
 | **Requires** | Concrete lesson: what broke, why, how to prevent |
 | **Produces** | Gotcha page in `aiwiki/gotchas/{YYYY-MM-DD}-{slug}.md` (project) or `~/.claude/gotchas/{YYYY-MM-DD}-{slug}.md` (global) |
 | **Schema** | `aiwiki/schemas/gotcha.md` — LINT validates frontmatter + sections on write |
-| **Feeds into** | Future sessions (prevention), `gotcha-hunter` agent (surfaces relevant entries to reviewers), `/evolve` (skill improvement) |
+| **Feeds into** | Future sessions (prevention), `gotcha-hunter` agent (surfaces relevant entries to reviewers), `/forge-evolve` (skill improvement) |
 
 ### Storage tiers
 
@@ -234,7 +234,7 @@ When no pending promotions exist, `gotcha-hunter` (separate agent) reads `aiwiki
 | `gotcha-hunter` (agent) | Reads `aiwiki/gotchas/` and surfaces diff-relevant entries to reviewers; never writes |
 | `support-wiki-lint` | Validates frontmatter + sections on every write |
 | `support-dream` | At phase-close / PreCompact: consolidates raw entries, may merge similar gotchas, prunes retired entries (writes proposals to `aiwiki/proposed/{dream_id}/` for user review) |
-| `/evolve` command | Reads gotchas to identify skill improvement opportunities |
+| `/forge-evolve` command | Reads gotchas to identify skill improvement opportunities |
 
 ## Quick reference
 

package/skills/{support-task-force → support-parallel}/SKILL.md

@@ -1,28 +1,28 @@
 ---
-name: support-task-force
-description: "Use when the user prompts a punch list of independent tasks (numbered or bulleted, ≥3 items) OR explicitly invokes /task-force. Classifies each task by type, assembles the right specialist team per task, dispatches all in parallel, aggregates results. Phase-aware: light teams during prototype phases (fast iteration), full crew during harden/production (no shortcuts). Optional Codex adversarial pairing when consent is on. REFUSES command-shaped work — routes feature/bugfix/refactor items to their owning commands instead."
+name: support-parallel
+description: "Use when the user prompts a punch list of independent tasks (numbered or bulleted, ≥3 items) OR explicitly invokes /parallel. Classifies each task by type, assembles the right specialist team per task, dispatches all in parallel, aggregates results. Phase-aware: light teams during prototype phases (fast iteration), full crew during harden/production (no shortcuts). Optional Codex adversarial pairing when consent is on. REFUSES command-shaped work — routes feature/bugfix/refactor items to their owning commands instead."
 ---
 
-# Task Force
+# Parallel
 
 ## Overview
 
 Users don't always invoke `/feature` or `/bugfix`. The daily reality is a paste-in punch list: "do these 10 things: 1. update README; 2. explore option X; 3. add a test for Y; 4. ...". Doing those in series in one context window is slow, conflict-prone, and skips the Codex second-opinion that catches real bugs.
 
-This skill assembles a **task-force per item** — a specialist team sized for the task's type and the project's current phase — and dispatches them in parallel. Each task-force has a Claude reviewer/builder paired with a Codex sibling (when the task is non-trivial). The skill REFUSES to swallow command-shaped work; items that look like features/bugfixes/refactors get routed to their owning commands.
+This skill assembles a **team per item** — sized for the task's type and the project's current phase — and dispatches them in parallel. Each team has a Claude reviewer/builder paired with a Codex sibling (when the task is non-trivial). The skill REFUSES to swallow command-shaped work; items that look like features/bugfixes/refactors get routed to their owning commands.
 
 **Core principle:** match team size to task complexity AND to the project's current phase. Prototype phases iterate fast with light teams. Production phases demand the full crew.
 
-**Announce at start:** "I'm using support-task-force to dispatch N task-forces in parallel — M routed to commands, K running in light mode, L running in full mode." If `!max` / `--full-power` detected: "...running in `!max` mode — production teams enforced regardless of phase."
+**Announce at start:** "I'm using support-parallel to dispatch N teams in parallel — M routed to commands, K running in light mode, L running in full mode." If `!max` / `--full-power` detected: "...running in `!max` mode — production teams enforced regardless of phase."
 
 ## When to Use
 
 Fire when **any** of:
-- User types `/task-force` explicitly
+- User types `/parallel` explicitly
 - User prompt contains a numbered list (`1. xxx 2. xxx 3. xxx`) with ≥3 items
 - User prompt contains a bulleted list (`- xxx / - xxx / - xxx`) with ≥3 items AND items look like work-tasks (not casual mentions)
 
-Confirm with user before dispatching if auto-detected (one-line: "Detected a 5-item task list; dispatching task-forces — say 'no' to cancel").
+Confirm with user before dispatching if auto-detected (one-line: "Detected a 5-item task list; dispatching teams — say 'no' to cancel").
 
 Do NOT use for:
 - A single task (use the appropriate command or skill directly)
@@ -33,7 +33,7 @@ Do NOT use for:
 
 ### Step 0: Codex consent (per `protocols/codex.md`)
 
-Run the Codex consent flow ONCE for the whole task-force run. The choice (Verify / Takeover / Skip / Never) propagates to every per-task dispatch. Record in `.forge/task-force/{run-id}/codex.yaml`.
+Run the Codex consent flow ONCE for the whole parallel run. The choice (Verify / Takeover / Skip / Never) propagates to every per-task dispatch. Record in `.forge/parallel/{run-id}/codex.yaml`.
 
 ### Step 1: Detect repo phase (or honor full-power override)
 
@@ -100,7 +100,7 @@ For each task, apply this classifier in order — first match wins:
 | ≥4 subsystems touched OR ≥3 verbs combined | **complex** |
 | Anything else | **ambiguous** (ask user) |
 
-Command-shaped items get **routed out** — they do NOT get a task-force. Surface them to the user with: "Item X looks like a `/feature` — running it as a forge command instead. The remaining items continue as task-forces." User can override.
+Command-shaped items get **routed out** — they do NOT get a team. Surface them to the user with: "Item X looks like a `/feature` — running it as a forge command instead. The remaining items continue as teams." User can override.
 
 ### Step 4: Assemble team per task
 
@@ -136,20 +136,20 @@ Apply both the **task type** AND the **phase mode**:
 
 Ask the user: "Is this a prototype or production task list?" Then proceed with the matching template.
 
-### Step 5: Dispatch all task-forces in parallel
+### Step 5: Dispatch all teams in parallel
 
 For each non-routed task:
 1. Compose the prompt: include the task text, the detected type, phase mode, the team composition.
 2. Fire each agent in the team as a background subagent (`run_in_background: true`).
 3. For tasks whose team includes "dispatch X skill", spawn ONE agent that invokes that skill (the skill handles its own internal multi-agent chain).
-4. Tag each agent with `task-force/{run-id}/{task-n}/{role}` for telemetry.
+4. Tag each agent with `parallel/{run-id}/{task-n}/{role}` for telemetry.
 
 Batched dispatch ceiling: 20-25 agents per `<function_calls>` block. For 10 tasks × 4 agents = 40 agents, plan 2 dispatch rounds.
 
 ### Step 6: Accumulate
 
 Background notifications arrive asynchronously:
-- Save each agent's result to `.forge/task-force/{run-id}/task-{n}/{role}.md`
+- Save each agent's result to `.forge/parallel/{run-id}/task-{n}/{role}.md`
 - Maintain a per-task status line: `Task 3 of 10: 2 of 3 agents complete (1 pending)`
 - DO NOT narrate every individual agent completion to the user — batch updates every ≥3 returns
 
@@ -161,14 +161,14 @@ When all agents for a task return, synthesize:
 - If only one returned (other failed/timeout) → mark `complete-single-source`, flag for user attention
 - If both failed → mark `failed`, recommend retry or single-task fallback
 
-Per-task output goes to `.forge/task-force/{run-id}/task-{n}/verdict.md`.
+Per-task output goes to `.forge/parallel/{run-id}/task-{n}/verdict.md`.
 
 ### Step 8: Run summary
 
 After all tasks finish (or hit batch limit), produce one consolidated report:
 
 ```
-Task-Force Run {run-id} — {N} tasks, {M} routed to commands
+Parallel Run {run-id} — {N} tasks, {M} routed to commands
 
 | # | Task | Type | Team size | Status | Conflicts |
 |---|------|------|-----------|--------|-----------|
@@ -186,7 +186,7 @@ Followups:
 - Run /feature for item 4 when ready
 ```
 
-Write the summary to `.forge/task-force/{run-id}/run-summary.md` and surface to user.
+Write the summary to `.forge/parallel/{run-id}/run-summary.md` and surface to user.
 
 ### Step 9: Stop
 
@@ -197,8 +197,8 @@ This skill does ONE run per invocation. If the user wants to iterate on findings
 | Field | Value |
 |---|---|
 | Requires | A user-provided task list (parsed in Step 2); optionally an active manifest for phase detection |
-| Produces | `.forge/task-force/{run-id}/codex.yaml`, `.forge/task-force/{run-id}/tasks.yaml` (classification), `.forge/task-force/{run-id}/task-{n}/{role}.md` per agent, `.forge/task-force/{run-id}/task-{n}/verdict.md` per task, `.forge/task-force/{run-id}/run-summary.md` |
-| Updates manifest | If a feature/bugfix manifest is active, append `phases.{phase}.task-force-runs: [{run-id}]`. Otherwise no manifest update — task-force runs are not phase-gated. |
+| Produces | `.forge/parallel/{run-id}/codex.yaml`, `.forge/parallel/{run-id}/tasks.yaml` (classification), `.forge/parallel/{run-id}/task-{n}/{role}.md` per agent, `.forge/parallel/{run-id}/task-{n}/verdict.md` per task, `.forge/parallel/{run-id}/run-summary.md` |
+| Updates manifest | If a feature/bugfix manifest is active, append `phases.{phase}.parallel-runs: [{run-id}]`. Otherwise no manifest update — parallel runs are not phase-gated. |
 | Feeds into | `/feature`, `/bugfix`, `/refactor` (for routed items); `support-gotcha` (for recurring patterns surfaced across tasks) |
 
 ## Agent Dispatch
@@ -224,11 +224,11 @@ Raw agents it dispatches directly:
 | Step | Skill / Command | Why |
 |---|---|---|
 | Pre-dispatch consent | `protocols/codex.md` | Codex pairing requires consent ONCE per run |
-| Task routing-out | `/feature`, `/bugfix`, `/refactor`, `/greenfield`, `/hotfix` | Command-shaped items must use commands, not task-forces |
+| Task routing-out | `/feature`, `/bugfix`, `/refactor`, `/greenfield`, `/hotfix` | Command-shaped items must use commands, not teams |
 | Per-task dev | `quality-code-review` skill | Production dev tasks get the full review chain |
 | Per-task debug | `support-debug` skill | Debug tasks get tracer + gotcha-hunter |
 | Per-task security | `quality-security-audit` skill | Security tasks get the OWASP-aware audit chain |
-| Post-run gotcha | `support-gotcha` | Patterns surfaced across multiple task-forces deserve a recorded lesson |
+| Post-run gotcha | `support-gotcha` | Patterns surfaced across multiple teams deserve a recorded lesson |
 
 ## Red Flags
 
@@ -239,12 +239,12 @@ Raw agents it dispatches directly:
 | Codex consent skipped silently | Means no second-opinion across the whole run — for production-mode tasks this is a regression |
 | 0 conflicts across all tasks | Either every task was trivial OR Claude+Codex are echoing each other; sample-check |
 | Complex tasks in prototype mode | Probably should be a /feature; warn user before proceeding |
-| Run-id directories never get cleaned | Add a periodic prune; aiwiki/dream or /evolve should handle it |
+| Run-id directories never get cleaned | Add a periodic prune; aiwiki/dream or /forge-evolve should handle it |
 | Soft cap warning ignored repeatedly | User has misframed work — recommend splitting into milestones |
 
 ## Anti-Patterns
 
-**Swallowing command-shaped work.** If the user types "add a payment feature, then audit security, then ship", DO NOT run a task-force — that's three workflows pretending to be three tasks. Route them: `/feature` → `quality-security-audit` → `/feature` deploy phase. Task-force is for items that DON'T fit a workflow.
+**Swallowing command-shaped work.** If the user types "add a payment feature, then audit security, then ship", DO NOT dispatch a parallel run — that's three workflows pretending to be three tasks. Route them: `/feature` → `quality-security-audit` → `/feature` deploy phase. `/parallel` is for items that DON'T fit a workflow.
 
 **Phase-blind sizing.** Spawning the full crew on a Phase-4 prototype task wastes tokens AND violates the prototype-throwaway principle. Always read phase first.
 
@@ -252,7 +252,7 @@ Raw agents it dispatches directly:
 
 **Ignoring divergent verdicts.** Claude+Codex disagreement is a SIGNAL, not noise. Surface it. Let the user adjudicate.
 
-**Letting `.forge/task-force/` grow forever.** Each run leaves a directory. Add to `support-dream` consolidation scope, or document a cleanup pattern.
+**Letting `.forge/parallel/` grow forever.** Each run leaves a directory. Add to `support-dream` consolidation scope, or document a cleanup pattern.
 
 **Auto-dispatching without confirmation when auto-detected.** Numbered lists in user prose aren't always task lists (could be a survey of options, a sequence diagram, etc.). Confirm before firing 40 agents.