@jamie-tam/forge 6.0.0 → 6.2.0

package/templates/aiwiki/CLAUDE.md.template

@@ -16,22 +16,20 @@ The wiki is curated to answer recurring questions. **Use it before asking the us
 
 ## Writing
 
-When you make a decision that's hard to reverse — architectural choice, public-surface naming (APIs / schemas / file paths users import), security or data-handling tradeoff, schema design, or a contract that other parts of the codebase depend on:
-- Write an ADR in `aiwiki/decisions/`. Format per `aiwiki/schemas/decision.md`. Invoke `/second-opinion` to get adversarial review before marking `status: accepted`.
+AI writes typed pages directly when the content meets the durability test for that page type. The user can edit or delete any page after the fact. `wiki-lint` (PostToolUse hook) validates schema on every save.
 
-When you encounter a recurring failure:
-- Write a gotcha in `aiwiki/gotchas/`. Format per `aiwiki/schemas/gotcha.md`.
-- If the gotcha file's `occurrences` reaches 3+, the gotcha is auto-drafted as a `proposed_rule:` block; the next session-start hard-interrupts to require user approval before promoting the rule.
+| Page type | Trigger | Skill that typically writes it | Adversarial review |
+|---|---|---|---|
+| ADR (`aiwiki/decisions/`) | Hard-to-reverse choice: architectural, public-surface naming (APIs / schemas / file paths users import), security or data-handling tradeoff, schema design, contracts other code depends on | `harden` (Phase 5, with inline adversarial review in each ADR's `review:` block per `aiwiki/schemas/decision.md`), `plan-brainstorm`, manual | Inline in the ADR `review:` block. When Codex is configured (`protocols/codex.md`), `harden` may dispatch Codex in verify mode; otherwise Claude performs the pass directly. |
+| Gotcha (`aiwiki/gotchas/`) | Reproducible failure mode with a concrete fix | `support-gotcha`, `support-debug` (after closing a non-trivial bug) | None — gotchas are facts, not opinions. The `occurrences: 3+` auto-promotion path adds a `proposed_rule:` block and the next session-start hard-interrupts for user approval before the rule ships. |
+| Convention (`aiwiki/conventions/`) | Pattern established across 2+ sites in this codebase | `iterate-prototype` (during Phase 4), `harden` (codify-time), manual | None — wiki-lint enforces schema; user reviews on read. |
+| Architecture (`aiwiki/architecture/{topic}.md`) | System-shape change: new subsystem, new boundary, new contract between components. One file per topic — do NOT collapse multiple subsystems into a single mega-file. | `harden` (Phase 5), manual | None directly, but `harden` Step 2 runs adversarial review on any ADRs that drive the architecture write. |
+| Oracle (`aiwiki/oracles/{slug}.md`) | Prototype behavior snapshot (setup → trigger → assertions) that Phase 6 production code must reproduce | `harden` Step 2.5 | None — oracles are observation of the prototype, not opinion. Tests in Phase 6 are written against the oracle. |
+| Session (`aiwiki/sessions/{date}-{session_id_short}.md`) | First in-session writer creates the file lazily | `pre-compact.sh` (Checkpoints), `/wrap` (index sections), `harden` (codify-time session entry) | `/wrap` confirms content with user before setting `status: done`. |
 
-When you discover a codebase convention:
-- Write to `aiwiki/conventions/`. Format per `aiwiki/schemas/convention.md`.
+**Raw (`aiwiki/raw/`) is user-gated.** Half-formed thoughts, research notes, deferred decisions, comparison sketches — these go to raw ONLY via `/note <text>`. The AI does not autonomously decide to write conversational content to raw; the user is the gate.
 
-When you make a system-shape change:
-- Write to `aiwiki/architecture/{topic}.md`. Format per `aiwiki/schemas/architecture.md`.
-- One file per topic — do NOT collapse multiple subsystems into a single mega-file.
-
-When unsure where something belongs:
-- Write to `aiwiki/raw/{YYYY-MM-DD}-{slug}.md`. Phase-close dream consolidates raw entries into typed pages.
+When durability is uncertain (e.g. "is this a real gotcha or just a one-off?"), ask the user instead of speculating into a typed page. Speculation in `aiwiki/decisions/` poisons future retrieval more than the missing entry costs.
 
 ## Citations
 
@@ -46,12 +44,33 @@ When the cited code moves, LINT flags the citation as stale on the next wiki wri
 
 The wiki is consolidated periodically by **dream** (forge's wiki-consolidation mechanism — see `support-dream` skill). Dream output goes to `aiwiki/proposed/{dream_id}/` and is **never auto-applied** to `aiwiki/`.
 
+**Dream triggers:**
+- **Manual** — `/dream [scope]` slash command. User-driven cleanup.
+- **PreCompact (~85% context)** — `hooks/scripts/pre-compact.sh` appends a `**Dream directive (unconsumed)**` block to the active session file's `## Checkpoints` section (`aiwiki/sessions/{date}-{session_id_short}.md`, created lazily on first fire). The post-compact agent reads the session file, finds the directive, and invokes `support-dream`. Skipped when `aiwiki/` has no recent (last 24h) activity.
+- **Phase-close** — the phase-locking skills (`iterate-prototype` on prototype-lock, `harden` on codify-lock, `feature.md` Step 8.5 per-slice on slice gate-pass, `deliver-deploy` on deliver-lock) dispatch `support-dream` immediately after writing their `artifacts.{phase}.locked_at`.
+
 When pending dreams exist:
 - Run `forge wiki status` to see the queue
-- Run `forge wiki review [dream_id]` to review per-page diffs
+- Run `forge wiki ui` to open the local web review at 127.0.0.1:8765, OR
+- Run `forge wiki review [dream_id]` to step through per-page diffs in the terminal
 - Run `forge wiki accept [dream_id]` or `forge wiki reject [dream_id] --reason "..."` to resolve
 
-You will be notified at session start (soft) and at phase-close (hard interrupt if a phase-close dream is pending).
+**Phase-close dreams hard-block the next phase** (iterate→codify, codify→production-build, all-slices-pass→deliver close). Per-slice dreams do not block — they're reviewed in bulk before Phase 7. PreCompact dreams do not block compaction; the proposal is durable on disk and you review whenever convenient.
+
+## Session handoff (`aiwiki/sessions/`)
+
+Each Claude session can produce a handoff file at `aiwiki/sessions/{date}-{session_id_short}.md`. Two writers populate different parts:
+
+| Section | Writer | Style |
+|---|---|---|
+| `## Checkpoints` | `hooks/scripts/pre-compact.sh`, `support-dream` skill | Append-only event log. PreCompact events with recovery directives. |
+| `## Files touched` / `## Decisions made` / `## Gotchas surfaced` / `## Open questions` / `## Next steps` | `/wrap` command | Index of links. Curated by the agent, confirmed by the user. |
+
+**Lazy creation.** The file is NOT created at SessionStart (that would produce empty noise for trivial 30-second sessions). The first writer in the session creates it.
+
+**`/wrap` to finalize.** Run `/wrap` at the natural end of a working session to fill the index sections and set `status: done`. This is the single most useful thing for next-session continuity — the SessionStart hook surfaces the latest session's focus and any unconsumed checkpoints.
+
+**Active dream directives.** If a `## Checkpoints` entry has a header `**Dream directive (unconsumed):**`, it's an action item for the current agent (typically: invoke `support-dream`). After acting, change the entry's header from `**Dream directive (unconsumed):**` to `**Dream directive (consumed at {ISO-timestamp}):**`. The `session-start.sh` hook counts active directives by matching `(unconsumed):` literally — flipping the header is what makes the count accurate.
 
 ## Phase vocabulary
 
@@ -59,15 +78,22 @@ When a skill or agent states its phase context, the canonical numbering and name
 
 ## Rules and references — what applies when
 
-Forge tiers code-standards content by phase to match its prototype-driven SDLC. The thesis: prototype iteration should be fast and unconstrained by style/convention rules; production-grade standards take effect when the prototype is codified.
+Forge ships 8 common rules in `.claude/rules/common/`. Seven auto-load every session; one (`testing.md`) is paths-conditional via frontmatter `paths:` and loads only when an editor touches test files or source code in `src/`.
 
-| Tier | Files | Active during |
+| Rule | Loading | Purpose |
 |---|---|---|
-| Always-on (safety floor) | `.claude/rules/common/security.md`, `guardrails.md`, `verification.md` | Every phase. Prevents classes of issues that are expensive to retrofit (injection, missing input validation, unverified completion claims). |
-| Phase-conditional | `.claude/rules/common/testing.md`, `quality-gates.md`, `git-workflow.md` | Phase 5 (codify) onward. Headers in those files mark the transition explicitly. |
-| References (load on demand) | `.claude/references/common/coding-standards.md`, `.claude/references/{language}/standards.md` (typescript, react, python) | Loaded by the `harden` skill / `prototype-codifier` agent at codify time. Not active during prototype iteration. |
-
-**Implication for AI agents:** during Phases 1–4 (concept → wireframe → prototype → iterate), follow the safety floor only — do not preemptively apply style/convention/testing standards. During Phase 5 (codify/harden) onward, load the references and phase-conditional rules listed above.
+| `forge-system.md` | Always-on | This file. Forge directory layout, aiwiki layer, dream + session-handoff mechanics. |
+| `security.md` | Always-on | Injection, secret handling, auth/data-handling — safety floor. |
+| `guardrails.md` | Always-on | Destructive-action gates, force-push refusals, sandbox boundaries. |
+| `verification.md` | Always-on | Don't claim "done" without proof; verify completion before reporting. |
+| `skill-selection.md` | Always-on | Routing logic: which skill fits a request given phase/scope/manifest state. |
+| `quality-gates.md` | Always-on | Gate-state vocabulary + the per-gate pass criteria summary. |
+| `git-workflow.md` | Always-on | Conventional Commits, bisectable commits, branch naming, hook-respect. |
+| `testing.md` | Paths-conditional | TDD discipline (RED-GREEN-REFACTOR), coverage targets, mocking strategy. Loads only when editing test files or `src/` code. |
+
+**References load on demand**, not automatically. `.claude/references/common/coding-standards.md` and language-specific standards (`typescript/`, `python/`, `react/`) are read by the `harden` skill, the `prototype-codifier` agent, and `quality-code-review`'s craft pass — when those subagents/skills choose to consult them. During prototype iteration (Phases 1-4), references are unread by default.
+
+**The original v6 design** floated a phase-conditional loading tier (testing/quality-gates/git-workflow load only from Phase 5 onward). That was rejected after second-opinion review: the safety-floor + paths-conditional model above is what actually ships. Prototype iteration speed comes from skill-level discipline (e.g. `iterate-prototype` doesn't dispatch full code-review chains) rather than from suppressing always-on rules.
 
 ## Forbidden
 

package/templates/aiwiki/schemas/session.md

@@ -1,10 +1,10 @@
 ---
 schema_id: session
-schema_version: 1
+schema_version: 2
 applies_to: aiwiki/sessions/**/*.md
-filename_pattern: "{date}-{slug}.md"
-hard_cap_lines: 200
-soft_target_lines: [40, 100]
+filename_pattern: "{date}-{session_id_short}.md"
+hard_cap_lines: 400
+soft_target_lines: [40, 200]
 required_frontmatter:
   schema_id: { type: string, equals: session }
   schema_version: { type: integer }
@@ -12,80 +12,142 @@ required_frontmatter:
   date_start: { type: date }
   date_end: { type: date, optional: true }
   focus: { type: string }
+  session_id: { type: string, optional: true }
   last_commit: { type: string, optional: true }
-required_sections:
+required_sections: []
+optional_sections:
+  - "## Checkpoints"
   - "## Files touched"
   - "## Decisions made"
   - "## Gotchas surfaced"
   - "## Open questions"
   - "## Next steps"
 section_order: strict
-citation_rule: required-in-files-touched
-maintained_by: hooks-and-dream
+citation_rule: required-in-files-touched-when-present
+maintained_by: lazy-on-first-event
 ---
 
 # Schema: session (per-session handoff)
 
 ## Purpose
 
-A session file is an **index of links** for one work session — what files were touched, what decisions landed, what gotchas surfaced, what's still open, what comes next. The page answers "what happened in session X?" for a future session that needs to resume or audit.
+A session file is the **handoff artifact** for one Claude session — what events fired during the session (PreCompact, /dream, /wrap) and what knowledge the session produced (files touched, decisions, gotchas, open questions, next steps). The page answers two questions for a future session:
 
-**Index of links, not distilled summary.** No prose paragraphs. No narrative. No screenshots-from-the-moment. Future sessions follow the links to actual artifacts (ADRs, gotchas, raw notes); the session file is just the routing layer.
+1. **What is the immediate recovery state?** — read `## Checkpoints` for in-session events the post-compact agent (or next session) needs to act on.
+2. **What happened and where do I pick up?** — read the index-of-links sections (`## Files touched`, `## Decisions made`, etc.).
 
-## How it's maintained (NOT by hand)
+**Two patterns mixed in one file by design:**
 
-This page type is unusual: it's maintained by **hooks and dream**, not by humans typing.
+- `## Checkpoints` is **event-log style** (append-only, chronological). Pre-compact and other hook-driven events write here. Each entry is timestamped and may include a recovery directive that the next agent should act on.
+- The other sections are **index of links** (curated, written by `/wrap` or `harden`). No prose paragraphs, no narrative — just links to ADRs, gotchas, raw notes. Future sessions follow the links to the actual artifacts.
 
-- `SessionStart` hook creates the file from this schema's skeleton (frontmatter + empty sections)
-- `PostToolUse` hooks append event lines to the appropriate sections (commit / gotcha / decision / raw)
-- `PreCompact` dream consolidates the event log into the schema sections (deduplicates, summarises bullet sequences, prunes noise)
-- `SessionEnd` (manual `/handoff` or detected) marks `status: done`
+## How it's maintained
 
-Do NOT manually edit a session file unless correcting a hook misfire. Manual edits should be rare.
+**Lazy creation.** Session files are NOT created at SessionStart (that would produce empty noise for trivial 30-second sessions). Instead, the first writer creates the file:
+
+| Writer | Triggers create? | Section written |
+|---|---|---|
+| `hooks/scripts/pre-compact.sh` | yes | `## Checkpoints` (appends event with recovery directive) |
+| `/wrap` command | yes | `## Files touched`, `## Decisions made`, `## Gotchas surfaced`, `## Open questions`, `## Next steps` (filled by agent, user confirms) |
+| `support-dream` skill | yes | `## Checkpoints` (appends dream-fired event with `dream_id`) |
+| `harden` skill (Phase 5) | yes | All sections (codify-time session capture, similar to /wrap) |
+
+`SessionStart` does NOT create the file — it READS the latest existing session file and surfaces a one-line summary to the agent, plus any unconsumed `## Checkpoints` directives.
 
 ## File location and naming
 
-- Path: `aiwiki/sessions/{date}-{slug}.md`
-- Date: ISO format (`YYYY-MM-DD`)
-- Slug: kebab-case, ≤6 words, naming the focus
+- Path: `aiwiki/sessions/{date}-{session_id_short}.md`
+- Date: ISO format (`YYYY-MM-DD`) — date the session STARTED
+- `session_id_short`: first 7 hex chars of Claude Code's session UUID (read from the hook payload on stdin). Functions like a git sha7 — short enough for filenames, long enough to disambiguate.
 
-Examples: `2026-05-10-auth-refactor.md`, `2026-05-11-bugfix-session-race.md`.
+Examples: `2026-05-18-7e8a3f2.md`, `2026-05-19-a1b2c3d.md`.
 
-The companion file `aiwiki/sessions/INDEX.md` is a sortable table of all sessions; SessionStart appends a row.
+If multiple sessions start on the same date, the short-id keeps them distinct. If a session spans a date boundary (rare — sessions don't usually run >24h), the date_end frontmatter captures it.
+
+The companion file `aiwiki/sessions/INDEX.md` (if present) is a sortable table of sessions; dream's session-refinement step appends a row when consolidating.
 
 ## Required frontmatter
 
 | Field | Type | Notes |
 |---|---|---|
 | `schema_id` | string | Must equal `session` |
-| `schema_version` | integer | — |
-| `status` | enum | `active` (in progress) / `done` (handed off) / `abandoned` (orphaned) |
-| `date_start` | ISO date | When SessionStart fired |
-| `date_end` | ISO date (optional) | When SessionEnd fired; null while active |
-| `focus` | string | What this session is about (e.g. `feature/auth-refactor`, `bugfix/session-race`) |
+| `schema_version` | integer | `2` (was `1` in v6.1.0; v2 adds `session_id` field and `## Checkpoints` section) |
+| `status` | enum | `active` (in progress) / `done` (handed off via /wrap) / `abandoned` (orphaned — pruned by dream) |
+| `date_start` | ISO date | When the session began (first event triggered file creation) |
+| `date_end` | ISO date (optional) | When /wrap fired or SessionEnd hook closed the file; null while active |
+| `focus` | string | What this session is about — initially "unset" if file was created by pre-compact before /wrap fired; updated by /wrap |
+| `session_id` | string (optional) | Full Claude session UUID. Pre-compact writes the short form into the filename; the full ID lives here for traceability. |
 | `last_commit` | string (optional) | SHA of the last commit during this session |
 
-## Required sections
+## Optional sections
+
+All sections are optional individually; at least one must be present (an empty session file is meaningless).
 
-| Section | Purpose | Maintained by |
+| Section | Style | Writer |
 |---|---|---|
-| `## Files touched` | Bullet list of files modified, with citations | PostToolUse hooks (append-only) |
-| `## Decisions made` | Links to ADRs in `aiwiki/decisions/` written this session | PostToolUse hook on `aiwiki/decisions/` write |
-| `## Gotchas surfaced` | Links to gotchas captured this session | PostToolUse hook on `aiwiki/gotchas/` write |
-| `## Open questions` | Links to raw context in `aiwiki/raw/` for unresolved items | PostToolUse hook on `aiwiki/raw/` write |
-| `## Next steps` | What the next session should do | Dream at PreCompact / SessionEnd |
+| `## Checkpoints` | Event log (append-only) | `pre-compact.sh`, `support-dream` skill |
+| `## Files touched` | Index of links (with citations) | `/wrap`, `harden` |
+| `## Decisions made` | Index of links to ADRs | `/wrap`, `harden` |
+| `## Gotchas surfaced` | Index of links to gotchas | `/wrap`, `harden` |
+| `## Open questions` | Index of links to raw notes | `/wrap`, `harden` |
+| `## Next steps` | Bullet list | `/wrap`; dream refines |
 
-## Line caps
+If `## Checkpoints` is present, it MUST be first (before the index sections).
+
+## Section: ## Checkpoints (event log)
+
+Append-only chronological list of in-session events. Each entry is a `###` subsection.
+
+**Entry shape:**
+
+```markdown
+### PreCompact at 2026-05-18T14:23:00Z
+
+Active work: feature/wire-dream
+Manifest: .forge/work/feature/wire-dream/manifest.yaml
+
+Phase status (from manifest):
+```yaml
+status: in-progress
+artifacts.prototype.locked_at: 2026-05-17T11:00:00Z
+artifacts.codify.locked_at: ~
+```
+
+**Dream directive (unconsumed):**
+
+- Scope: `aiwiki/raw/`, recently-touched typed pages
+- Trigger: pre-compact, context ~85%
+- Action: invoke `support-dream` skill before resuming other work
+
+---
+```
 
-- Hard cap: 200 lines (LINT fails above; if hit, dream is overdue or session is unusually long)
-- Soft target: 40-100 lines
+**Marking consumed.** After the agent acts on a `Dream directive (unconsumed)` entry, it changes the entry's bold-header from `**Dream directive (unconsumed):**` to `**Dream directive (consumed at {ISO-timestamp}):**`. The `session-start.sh` hook counts active directives by matching the exact `(unconsumed):` header — flipping the header is what makes the count accurate. Appending a separate "Status: consumed" line is wrong because it leaves the unconsumed-marked header still grep-matchable; the next session-start will surface the directive as a HARD-INTERRUPT again (dogfood-validated 2026-05-18).
 
-A session file that grows past 100 lines without dream consolidation usually means PreCompact hasn't fired (short session) — that's fine; SessionEnd dream will compact it. If it grows past 200 with no compact, run `/dream` manually.
+## Section: ## Files touched (index of links)
+
+Bullet list. Each entry cites the file with `file:line@<sha7>` (or `path` if file-level). LINT auto-fills `@<sha7>` on first save.
+
+## Sections: ## Decisions made / ## Gotchas surfaced / ## Open questions
+
+Bullet lists. Each entry is a link to a typed wiki page (ADR, gotcha, raw note). No `@<sha7>` needed for wiki-internal links.
+
+## Section: ## Next steps
+
+Bullet list. What the next session should do. Dream's session-refinement step (if it runs) may rewrite this section as it learns more about the work's state.
+
+## Line caps
+
+- Hard cap: 400 lines (raised from 200 in v1; `## Checkpoints` event log grows over a long session)
+- Soft target: 40-200 lines
+- A session file >200 lines that hasn't been touched by /wrap is probably pre-compact-heavy and ready for /wrap consolidation
+- A session file >400 lines fails LINT — run `/wrap` to consolidate, OR `/dream` to refine the file
 
 ## Citation rules
 
-- `## Files touched` MUST cite each file with `file:line@<sha7>` (or `path` if file-level)
+- `## Files touched`: each line MUST cite `file:line@<sha7>` (or `path`)
 - Other sections link to typed wiki pages (no `@<sha7>` needed for wiki-internal links)
+- `## Checkpoints` entries don't require citations — they're event records, not knowledge claims
 - LINT auto-fills missing code citations on first save
 
 ## Skeleton
@@ -93,33 +155,56 @@ A session file that grows past 100 lines without dream consolidation usually mea
 ```markdown
 ---
 schema_id: session
-schema_version: 1
+schema_version: 2
 status: active
-date_start: 2026-05-10
-focus: feature/auth-refactor
+date_start: 2026-05-18
+session_id: 7e8a3f2-9a4b-4c8d-b1e2-f5a6c7d8e9f0
+focus: unset
 last_commit: ~
 ---
 
+## Checkpoints
+
+### PreCompact at 2026-05-18T14:23:00Z
+
+Active work: feature/wire-dream
+Manifest: .forge/work/feature/wire-dream/manifest.yaml
+
+Phase status (from manifest):
+```yaml
+status: in-progress
+artifacts.prototype.locked_at: 2026-05-17T11:00:00Z
+```
+
+**Dream directive (unconsumed):**
+- Scope: `aiwiki/raw/`, recently-touched typed pages
+- Trigger: pre-compact, context ~85%
+- Action: invoke `support-dream` skill before resuming other work
+- Status: unconsumed
+
+---
+
 ## Files touched
 
-- [src/auth/handler.ts](src/auth/handler.ts)
-- [src/auth/token.ts](src/auth/token.ts)
-- [src/auth/middleware.ts:1-42@a3f2bc1](src/auth/middleware.ts)
+(filled by /wrap)
 
 ## Decisions made
 
-- [aiwiki/decisions/0042-token-storage.md](aiwiki/decisions/0042-token-storage.md)
+(filled by /wrap)
 
 ## Gotchas surfaced
 
-- [aiwiki/gotchas/2026-05-10-cookie-samesite-defaults.md](aiwiki/gotchas/2026-05-10-cookie-samesite-defaults.md)
+(filled by /wrap)
 
 ## Open questions
 
-- Token rotation policy ([aiwiki/raw/2026-05-10-rotation-question.md](aiwiki/raw/2026-05-10-rotation-question.md))
+(filled by /wrap)
 
 ## Next steps
 
-- Implement refresh token rotation per the open question
-- Update [aiwiki/architecture/auth-flow.md](aiwiki/architecture/auth-flow.md) once rotation lands
+(filled by /wrap)
 ```
+
+## Migration from v1
+
+v1 session files (no `## Checkpoints`, no `session_id`) parse cleanly under v2 (all v2 sections are optional). LINT will surface "no `session_id`" as advisory, not blocking. Manual migration: add `session_id: ~` to frontmatter and bump `schema_version: 2`; or just leave v1 files and let dream consolidate them at next refinement pass.

package/templates/manifests/bugfix.yaml

@@ -11,7 +11,7 @@ schema_version: "6"
 name: {name}
 type: bugfix
 description: "{description}"
-status: in-progress  # in-progress | paused | completed | escalated | abandoned
+status: in-progress  # in-progress | paused | completed | escalated
 created: "{date}"
 command: bugfix
 escalated_from: null

package/templates/manifests/feature.yaml

@@ -18,7 +18,7 @@ schema_version: "6"
 name: {name}
 type: feature
 description: "{description}"
-status: in-progress  # in-progress | paused | completed | escalated | abandoned
+status: in-progress  # in-progress | paused | completed | escalated
 created: "{date}"
 command: feature
 complexity: standard  # trivial | standard | major

package/templates/manifests/greenfield.yaml

@@ -12,7 +12,7 @@ schema_version: "6"
 name: {name}
 type: greenfield
 description: "{description}"
-status: in-progress  # in-progress | paused | completed | escalated | abandoned
+status: in-progress  # in-progress | paused | completed | escalated
 created: "{date}"
 command: greenfield
 complexity: standard  # trivial | standard | major

package/templates/manifests/hotfix.yaml

@@ -11,7 +11,7 @@ schema_version: "6"
 name: {name}
 type: hotfix
 description: "{description}"
-status: in-progress  # in-progress | paused | completed | escalated | abandoned
+status: in-progress  # in-progress | paused | completed | escalated
 created: "{date}"
 command: hotfix
 escalated_from: null

package/templates/manifests/refactor.yaml

@@ -7,7 +7,7 @@ schema_version: "6"
 name: {name}
 type: refactor
 description: "{description}"
-status: in-progress  # in-progress | paused | completed | escalated | abandoned
+status: in-progress  # in-progress | paused | completed | escalated
 created: "{date}"
 command: refactor
 coverage-baseline: null  # recorded in Step 0

package/templates/manifests/v5/SCHEMA.md

@@ -16,7 +16,7 @@ Required:
 | `name` | string | kebab-case identifier; matches `.forge/work/{type}/{name}/` |
 | `type` | enum | `feature` \| `bugfix` \| `hotfix` \| `refactor` \| `greenfield` |
 | `description` | string | one-line human description |
-| `status` | enum | `in-progress` \| `paused` \| `completed` \| `escalated` \| `abandoned` |
+| `status` | enum | `in-progress` \| `paused` \| `completed` \| `escalated` |
 | `created` | ISO-8601 date | |
 | `command` | string | which slash command produced the manifest |
 | `phases` | object | pre-build (discover, plan) and post-build (quality, deliver, support) gates |
@@ -64,7 +64,7 @@ slice_graph:
       type: skeleton | feature-slice | refactor-slice
       variant: <string>          # only for type: skeleton; identifies stack
       depends_on: [<slice-id>...]
-      status: pending | in-progress | gated | complete | abandoned
+      status: pending | in-progress | gated | complete
       gates:
         <gate-name>: { status: <enum>, gate-passed: <bool> }
 ```
@@ -127,25 +127,23 @@ Lifecycle path (recommended; skills are written to follow this):
 
 ```
 pending → in-progress → gated → complete
-                       ↘ abandoned
 gated → in-progress       (gate failed; rework)
 ```
 
-`complete` and `abandoned` are conventionally terminal. If a downstream
-change invalidates a completed slice's work, the convention is to add a
-NEW slice that supersedes the old (preserving the audit trail) rather
-than mutate the completed slice's status. Skills enforce this in their
+`complete` is the conventional terminal state. If a downstream change
+invalidates a completed slice's work, the convention is to add a NEW
+slice that supersedes the old (preserving the audit trail) rather than
+mutate the completed slice's status. Skills enforce this in their
 prompts; the verifier does not.
 
 A slice should enter `in-progress` only when every slice in its
-`depends_on` is in `complete` status. `abandoned` does not satisfy a
-dependency — descendants of an abandoned slice block. Skills check this
-before advancing.
+`depends_on` is in `complete` status. Skills check this before
+advancing.
 
 ### 3.6 Fan-out / fan-in completion (planning convention)
 
 The slice graph is **terminally settled** when every slice is in
-`complete` or `abandoned` status. Skills running the post-build
+`complete` status. Skills running the post-build
 `phases.quality.code-review-final` gate check this convention before
 proceeding.
 
@@ -153,8 +151,7 @@ Fan-out: a slice with multiple non-dependent successors creates parallel
 branches. Each branch advances independently when its own gates pass.
 
 Fan-in: a slice with multiple `depends_on` entries waits for ALL of them
-to reach `complete` before entering `in-progress`. An `abandoned`
-dependency does NOT satisfy fan-in.
+to reach `complete` before entering `in-progress`.
 
 `current_slice` is a single global pointer in v5.0; multi-active-slice
 (per-worker pointer for parallel terminal tabs) is deferred to v6.0
@@ -223,7 +220,7 @@ type ErrorCode =
   | 'E_GATE_COLLISION' | 'E_BAD_SLICE_ID' | 'E_BAD_CURRENT_SLICE'
   | 'E_MISSING_REQUIRED_FIELD' | 'E_BAD_ENUM_VALUE'
   | 'E_PHASE_GATE_PREMATURE'   // §3.6: phases.quality.code-review-final.gate-passed = true
-                                //       while any slice is not in terminal state (complete/abandoned)
+                                //       while any slice is not in terminal state (complete)
   | 'E_YAML_PARSE' | 'E_FILE_NOT_FOUND';
 ```
 
@@ -292,7 +289,7 @@ duplicated into the synthesized slice). They run at v4-style "post-build"
 time — after `legacy-build` slice completes.
 
 The migration is a **read-time synthesis**, not an on-disk rewrite. v4
-manifests on disk stay v4-shaped until `/evolve` runs, which writes a
+manifests on disk stay v4-shaped until `/forge-evolve` runs, which writes a
 true v5 `slice_graph` block.
 
 ### 6.1 Migration semantic limitation (acknowledged)
@@ -307,11 +304,11 @@ followed.
 Consequence: a v4-migrated manifest read by v5 tooling will show
 `build-tdd: passed` even if no TDD occurred. This is acceptable because
 (a) the v4 work has already shipped — re-litigating the gate would
-block all in-flight v4 features, and (b) `/evolve` prompts the user to
+block all in-flight v4 features, and (b) `/forge-evolve` prompts the user to
 review the synthesis and rewrite the slice graph if they want true
 v5 gate semantics for ongoing work.
 
-`/evolve` shows the synthesized slice graph alongside the v4 task list
+`/forge-evolve` shows the synthesized slice graph alongside the v4 task list
 and asks: "Accept this synthesis (treat as legacy build), or rewrite as
 v5 slice graph (re-run gates per slice)?". The default is "accept".
 

package/templates/manifests/v5/feature.yaml

@@ -58,7 +58,7 @@ slice_graph:
       type: skeleton          # skeleton | feature-slice | refactor-slice
       variant: {skeleton_variant}   # backend-server | frontend-spa | cli-tool | library | mobile-app — set during stack selection
       depends_on: []
-      status: pending         # pending | in-progress | gated | complete | abandoned
+      status: pending         # pending | in-progress | gated | complete
       gates:
         skeleton-runs:    { status: pending, gate-passed: false }
         wiki-lint:        { status: pending, gate-passed: false }

package/templates/manifests/v6/SCHEMA.md

@@ -27,7 +27,6 @@ The two blocks are complementary, not redundant. A phase with `phase_plan.X: act
 | `phase_plan` | (absent) | **required** at top level |
 | `phases` | required | required (unchanged — still tracks gate state per phase/sub-phase) |
 | `slice_graph` | required by parser | optional (the v5 SCHEMA already documented this as optional; v6 aligns the parser) |
-| `status` enum | `in-progress` \| `paused` \| `completed` \| `escalated` | adds `abandoned` (terminal state recorded by `/abort`; preserves artifacts) |
 | Everything else | — | unchanged |
 
 The `slice_graph` change is a parser fix: v5's SCHEMA §1 listed `slice_graph` as optional but the verifier rejected its absence. v6 manifests can ship without a slice graph — it is populated at codify, not at preflight. v4 and v5 manifests continue to require it (v4 synthesizes one; v5 always shipped one in practice).
@@ -75,17 +74,17 @@ phase_plan:
 
 The verifier rejects any other value with `E_BAD_PHASE_PLAN_STATUS`.
 
-### 3.2 Key naming convention
+### 3.2 Key naming — strict enum per work type
 
-Keys are free-form strings — the verifier does NOT validate them against any canonical vocabulary. This is intentional: `/bugfix`, `/hotfix`, `/refactor` workflows have different shapes than `/feature` or `/greenfield`, and each command enumerates its own plannable steps.
+Keys are validated against a per-work-type allow-list. An unknown key produces `E_UNKNOWN_PHASE_PLAN_KEY` with a "did you mean?" suggestion when a near-match exists.
 
-**This means typos in keys are silent failures.** A misspelled `prototpe` produces no parse error but breaks any downstream routing that reads `phase_plan.prototype` — including the mode-detection signals in `rules/common/skill-selection.md` and command preflight redirects. Treat phase_plan keys as load-bearing identifiers: copy them from the templates exactly, do not invent variants.
+This was a convention through early v6 — the verifier accepted any string and a `W_UNKNOWN_PHASE_PLAN_KEY` warning surfaced typos. Dogfood signal (a misspelled `prototpe` parsed fine but broke `rules/common/skill-selection.md`'s mode-detection read of `phase_plan.prototype`) drove the 2026-05-17 promotion to a hard error.
 
-#### Recommended keys per work type
+#### Allowed keys per work type
 
-Commands should use these keys (kebab-case, match the templates verbatim):
+Commands MUST use these keys (kebab-case, match the templates verbatim). The list in `src/work-manifest.ts` (`ALLOWED_PHASE_PLAN_KEYS`) is the source of truth — this table must stay in sync.
 
-| Work type | Recommended `phase_plan` keys |
+| Work type | Allowed `phase_plan` keys |
 |---|---|
 | `feature` | `discover-codebase`, `concept`, `wireframe`, `plan-design-system`, `prototype`, `iterate`, `codify`, `worktree`, `production-build`, `test-plan`, `uiux-review`, `code-review-final`, `deliver`, `onboarding`, `gotchas` |
 | `greenfield` | `discover-requirements`, `concept`, `wireframe`, `plan-design-system`, `prototype`, `iterate`, `codify`, `scaffold`, `production-build`, `test-plan`, `uiux-review`, `code-review-final`, `deliver`, `onboarding`, `gotchas` |
@@ -93,11 +92,16 @@ Commands should use these keys (kebab-case, match the templates verbatim):
 | `hotfix` | `debug-root-cause`, `production-build`, `smoke-tests`, `code-review-critical`, `deliver`, `gotchas`, `followup-ticket` |
 | `refactor` | `discover-codebase`, `brainstorm`, `task-decompose`, `production-build`, `test-execution`, `assessment`, `deliver`, `gotchas` |
 
-`plan-design-system` is a workflow-specific gate that runs at Step 4.5 of `/feature` and `/greenfield` (post-wireframe-lock, pre-prototype). It is not in `references/common/phases.md` because it is a step within Phase 3-4 rather than its own canonical phase. Backend-only / CLI work skips it (`status: skipped` with a reason); frontend work uses `status: active`.
+`plan-design-system` is a workflow-specific gate that runs at Step 4.5 of `/feature` and `/greenfield` (post-wireframe-lock, pre-prototype). It is not in `references/common/phases.md` because it is a step within Phases 2-3 rather than its own canonical phase. Backend-only / CLI work skips it (`status: skipped` with a reason); frontend work uses `status: active`.
 
 The seven canonical phase names from `references/common/phases.md` (`concept`, `wireframe`, `prototype`, `iterate`, `codify`, `production-build`, `deliver`) MUST match the canonical spelling when used. Other keys are workflow-specific gates or sub-phases.
 
-If real usage shows typos causing failures, harden this from convention to per-type enum validation — the parser knows `manifest.type`, so a per-type allowed-keys map is a single Set lookup.
+#### Adding a new key
+
+To extend a workflow with a new phase_plan key:
+1. Add it to the appropriate `ManifestType` entry in `ALLOWED_PHASE_PLAN_KEYS` (`src/work-manifest.ts`).
+2. Add it to the table above.
+3. Update the relevant command's preflight planner so it emits the new key.
 
 ### 3.3 gate-passed discipline
 
@@ -113,7 +117,7 @@ This convention is enforced by skills (they read phase_plan and choose not to se
 
 A v5 manifest read by the v6 parser is accepted as-is. The parser returns `schema: 'v5'` and the synthesized in-memory manifest has `phase_plan: undefined`. Tools that need a phase_plan can synthesize a default: every phase in `phases.{block}.{gate}` becomes `phase_plan.{gate}: active`.
 
-`/evolve` (when it lands) will offer to rewrite v5 manifests on-disk into v6 shape, prompting for plan-status per phase. v5 manifests parse forever; no forced migration.
+`/forge-evolve` (when it lands) will offer to rewrite v5 manifests on-disk into v6 shape, prompting for plan-status per phase. v5 manifests parse forever; no forced migration.
 
 ---
 

package/commands/abort.md

@@ -1,25 +0,0 @@
----
-name: abort
-description: "Mark a .forge/work item abandoned without deleting files."
-argument-hint: "[type/name] [reason]"
----
-
-# /abort — Abandon Work Item
-
-Mark a work item abandoned while preserving every artifact for audit and future reference.
-
-## Scope
-
-Marks a `.forge/work/` item `status: abandoned` in its manifest. Preserves every artifact — work directory, branches, logs, prototypes, wiki entries — so the abandonment is auditable. Does NOT delete files, close branches, prune the wiki, or reset gate state. Invoke when work is being walked away from (replaced by a different approach, blocked indefinitely, or pivoted) and the user wants the trail kept for future reference.
-
-## Input
-
-Accept `type/name` and an optional reason. If no work item is provided, run `/status` first and ask the user which item to abandon.
-
-## Steps
-
-1. Read `.forge/work/{type}/{name}/manifest.yaml`.
-2. Confirm with the user before changing status.
-3. Set `status: abandoned`, `abandoned_at: <ISO-8601 UTC timestamp>` (executing agent fills this — e.g. `2026-05-12T15:42:00Z`; not a literal placeholder), and `abandon_reason: {reason}` in the manifest. Preserve all existing phase, gate, and artifact fields.
-4. Do not delete the work directory, branches, logs, prototypes, wiki entries, or any generated artifacts.
-5. Report the manifest path and the reason recorded.