@jamie-tam/forge 6.0.0

package/templates/manifests/v5/SCHEMA.md

@@ -0,0 +1,327 @@
+# v5 manifest schema
+
+Source of truth for v5 manifest validation rules. The v5 reader and verifier
+in `src/work-manifest.ts` implement against this document. v4 manifests continue
+to parse (single-slice synthesis, see §6).
+
+---
+
+## 1. Top-level fields
+
+Required:
+
+| Field | Type | Notes |
+|---|---|---|
+| `schema_version` | string | `"5"` for v5 manifests |
+| `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` |
+| `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 |
+
+Optional:
+
+| Field | Type | Notes |
+|---|---|---|
+| `complexity` | enum | `trivial` \| `standard` \| `major` |
+| `escalated_from` | string \| null | upstream manifest path on escalation |
+| `successor_path` | string \| null | downstream manifest path on escalation |
+| `slice_graph` | object | v5 NEW (§3); absent for v4-shaped manifests |
+| `artifacts` | object | free-form artifact registry (e.g. brainstorm-approved.md) |
+
+`phases.build` is **intentionally absent** in v5 manifests. v4 manifests
+that contain `phases.build.tasks: []` still parse (see §6).
+
+---
+
+## 2. Phase gates (unchanged from v4)
+
+Each gate inside `phases.{discover,plan,quality}.{gate-name}` has shape:
+
+```yaml
+{ status: <enum>, gate-passed: <bool> }
+```
+
+`status` ∈ `pending` \| `in-progress` \| `complete` \| `skipped` \| `not-applicable`.
+
+`phases.deliver` and `phases.support` use plain booleans (not gate objects)
+for v4 compatibility — these are not enforced by `gate-enforcer.sh`.
+
+Gate names are flat strings. `gate-enforcer.sh` looks up requirements by
+exact gate name in `hooks/config/gate-requirements.json`.
+
+---
+
+## 3. Slice graph (v5 NEW)
+
+```yaml
+slice_graph:
+  current_slice: <slice-id>     # which slice is active
+  slices:
+    <slice-id>:
+      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
+      gates:
+        <gate-name>: { status: <enum>, gate-passed: <bool> }
+```
+
+### 3.1 Slice IDs
+
+- Kebab-case strings, unique within the manifest.
+- Must match `^[a-z][a-z0-9-]*$`.
+- `current_slice` MUST refer to an existing slice ID.
+
+### 3.2 DAG invariants (verifier MUST reject)
+
+1. **Unresolved dependency** — every entry in `depends_on` resolves to an existing slice ID in the same manifest.
+2. **Self-dependency** — slice ID may not appear in its own `depends_on`.
+3. **Cycle** — the directed graph induced by `depends_on` must be acyclic. Verifier runs Kahn's algorithm; any node remaining after the pass = cycle.
+4. **Skeleton uniqueness** — at most one slice has `type: skeleton`.
+5. **Skeleton root** — if a skeleton slice exists, its `depends_on` MUST be empty.
+6. **Skeleton ancestry** — if a skeleton slice exists, every non-skeleton slice MUST transitively depend on it. Verifier walks reverse-BFS from the skeleton; any unreached non-skeleton slice = error.
+7. **Variant required for skeleton** — if `type: skeleton`, `variant` MUST be a non-empty string.
+8. **Variant forbidden for non-skeleton** — if `type` ≠ `skeleton`, `variant` MUST be absent or null.
+
+### 3.3 Sibling ordering
+
+When two slices have the same depth in the DAG (siblings), execution order
+is **insertion order in the `slices:` map**. This is deterministic but
+explicit — agents adding new slices MUST insert them at the position they
+should execute. This avoids hidden dependencies on hash-map iteration.
+
+**Implementation contract.** The verifier uses `js-yaml` with default
+schema; js-yaml preserves YAML map insertion order on `load()` and `dump()`.
+If the implementer discovers round-trip order loss in any code path
+(library upgrade, alternate serializer, etc.), they MUST add an
+explicit `order: <int>` field per slice as a follow-up before Phase 2.
+Detect by writing a unit test that dumps then re-parses a 5-slice manifest
+and asserts identical key order.
+
+### 3.4 Gate name collisions (verifier MUST reject)
+
+A slice gate name MUST NOT collide with any manifest-level gate name in
+`phases.{discover,plan,quality}`. Reason: `gate-enforcer.sh` matches by
+unscoped name. Reusing a name would silently apply the wrong requirement.
+
+Reserved manifest-level gate names (v4 + v5): `codebase-analysis`,
+`brainstorm`, `design-system`, `architecture`, `task-decompose`,
+`code-review-final`, `test-plan`, `test-execution`, `uiux-review`.
+
+Allowed slice gate names: `skeleton-runs`, `build-tdd`, `wiki-lint`,
+`runtime-reach`, `code-review`. These differ from the manifest-level set
+by design (per Codex round 1, §3).
+
+### 3.5 Slice status lifecycle (convention, not enforced)
+
+> **By convention, this section describes a *lifecycle convention* that
+> skills follow voluntarily. The verifier does NOT block transitions.
+> Observed usage has not shown agents bypassing this discipline silently;
+> if it ever does, restore `verifyTransition` from git history
+> (commit `be5ab93`'s parent).**
+
+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
+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.
+
+### 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
+`phases.quality.code-review-final` gate check this convention before
+proceeding.
+
+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.
+
+`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
+alongside skills-first interruptibility. v5.0 does NOT enforce
+manifest-write serialization at the file level — single-session
+discipline + git review catches this in practice. Restore `flock(2)`
+write serialization if real usage shows concurrent-write corruption.
+
+---
+
+## 4. Slice gate semantics
+
+| Gate | Skill | Agent | When |
+|---|---|---|---|
+| `build-tdd` | `build-tdd` | `builder` | Per slice |
+| `wiki-lint` | `support-wiki-lint` | — | Per slice (validates the slice's wiki contributions) |
+| `runtime-reach` | `support-runtime-reachability` | — | Per slice |
+| `code-review` | `quality-code-review` | `craft-reviewer` | Per slice (lighter than `code-review-final`) |
+
+Per-slice `code-review` is **distinct** from manifest-level `code-review-final`.
+The slice version checks pattern conformance + stub detection for that
+slice's diff. The final version reviews the cross-slice integration.
+
+**Phase-close wiki lint is a hook, not a gate.** The phase-close gate
+hook ALSO invokes `support-wiki-lint`, but against the CUMULATIVE
+`aiwiki/` state at phase close — not against a slice. It does not
+correspond to any manifest gate slot (the per-slice `wiki-lint` already
+gates each slice's contributions). The phase-close invocation is a
+defense-in-depth check that catches drift across the whole wiki between
+when a slice's lint passed and when the phase closes (e.g. another slice
+edited the same file). The hook fails phase-close if lint fails; no
+manifest field tracks it (the failure is its own evidence).
+
+---
+
+## 5. Verifier interface
+
+`src/work-manifest.ts` exports two layers — structural (stateless) and
+transitional (stateful):
+
+```ts
+type ManifestParseResult =
+  | { ok: true; manifest: Manifest; schema: 'v4' | 'v5' }
+  | { ok: false; errors: ManifestError[] };
+
+// Structural: validates a single manifest snapshot. Stateless.
+// Implements §1, §3.1-3.4, §3.6, §6.
+function parseManifest(yaml: string): ManifestParseResult;
+function readManifest(path: string): ManifestParseResult;
+
+// NOTE: verifyTransition() and the transitional ErrorCode entries
+// (E_BAD_STATUS_TRANSITION, E_DEPENDENCY_NOT_COMPLETE,
+// E_TERMINAL_SLICE_MUTATED) were removed; slice status transitions
+// remain a documented convention, not enforced by the verifier.
+
+type ManifestError = {
+  code: ErrorCode;     // see enum below
+  message: string;     // human-readable, includes the offending value
+  path: string;        // YAML path, e.g. "slice_graph.slices.auth-login.depends_on[1]"
+};
+
+type ErrorCode =
+  | 'E_UNRESOLVED_DEP' | 'E_SELF_DEP' | 'E_CYCLE'
+  | 'E_MULTIPLE_SKELETONS' | 'E_SKELETON_NOT_ROOT' | 'E_ORPHAN_SLICE'
+  | 'E_VARIANT_REQUIRED' | 'E_VARIANT_FORBIDDEN'
+  | '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)
+  | 'E_YAML_PARSE' | 'E_FILE_NOT_FOUND';
+```
+
+`parseManifest` returns ALL errors (not first-fail) so users fix the
+manifest in one pass.
+
+### 5.1 Error message format
+
+```
+<E_CODE>  <YAML path>
+  <human message; one sentence; quotes the offending value>
+  Fix: <one-sentence remediation>
+```
+
+Example:
+
+```
+E_CYCLE  slice_graph.slices
+  Cycle detected: auth-login → profile-page → auth-login.
+  Fix: remove one edge from depends_on, or restructure into a single fan-in slice.
+```
+
+### 5.2 CLI surface
+
+The verifier ships as a dedicated sub-command:
+
+```
+$ npx @jamie-tam/forge verify-manifest [path]
+  --json                   Machine-readable output
+
+Exit codes:
+  0  No errors
+  1  Verification errors (errors written to stdout in human or JSON format)
+  2  Internal error (file not found, bad YAML syntax, etc.)
+```
+
+---
+
+## 6. v4 → v5 migration mapping
+
+A v4 manifest (no `slice_graph`, has `phases.build.tasks: []`) is
+synthesized into a v5-shaped in-memory structure:
+
+```yaml
+slice_graph:
+  current_slice: legacy-build
+  slices:
+    legacy-build:
+      type: feature-slice
+      depends_on: []
+      status: <derived from phases.build state>
+      gates:
+        build-tdd: { status: <derived>, gate-passed: <derived> }
+```
+
+Derivation rules (evaluated in order; first match wins):
+
+1. v4 `tasks: []` is empty (no build work yet planned) → `status: pending`, `gate-passed: false`. Treats vacuous "all complete / all pending" as not-yet-started.
+2. all tasks `complete` (with at least one task) → `status: complete`, `gate-passed: true`.
+3. any task `in-progress` and none failed → `status: in-progress`, `gate-passed: false`.
+4. all tasks `pending` (with at least one task) → `status: pending`, `gate-passed: false`.
+5. otherwise (mixed states without rule 3) → `status: in-progress`, `gate-passed: false`.
+
+The v4 `phases.quality.*` gates are kept AS-IS at manifest level (NOT
+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
+true v5 `slice_graph` block.
+
+### 6.1 Migration semantic limitation (acknowledged)
+
+The "all v4 tasks complete = `build-tdd` passed" inference is
+**pragmatic, not semantic**. v4 task names were arbitrary (e.g.
+"core-rule", "discover-codebase-analysis", "readme-update") and many
+weren't TDD work. The synthesis treats the migrated slice as a
+black-box "build phase that finished", not as evidence that TDD was
+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
+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
+and asks: "Accept this synthesis (treat as legacy build), or rewrite as
+v5 slice graph (re-run gates per slice)?". The default is "accept".
+
+---
+
+## 7. Reserved evolutions
+
+Out of scope for v5.0; slots reserved in the schema so we don't have
+to break it again:
+
+- **Conditional edges** (`depends_on: [{slice: X, when: <cond>}]`) — deferred to v5.2.
+- **Slice retry policy** (`retry: { max, backoff }`) — deferred; rework via `gated → in-progress` is the v5.0 mechanism.
+- **Per-worker `current_slice`** for parallel terminal tabs — deferred to v6.0 with skills-first interruptibility.

package/templates/manifests/v5/feature.yaml

@@ -0,0 +1,77 @@
+# v5 manifest template for /feature command.
+# Spec: ../SCHEMA.md (validation rules, DAG invariants, migration mapping).
+# Additive over v4 — v4 manifests still parse and are treated as single-slice
+# by the v5 reader (see src/manifest.ts).
+#
+# Placeholders: {name}, {description}, {date}, {skeleton_variant}
+# Written to: .forge/work/feature/{name}/manifest.yaml
+
+schema_version: "5"
+name: {name}
+type: feature
+description: "{description}"
+status: in-progress           # in-progress | paused | completed | escalated
+created: "{date}"
+command: feature
+complexity: standard          # trivial | standard | major
+escalated_from: null
+successor_path: null
+
+# Pre-build phases (unchanged from v4)
+phases:
+  discover:
+    codebase-analysis: { status: pending, gate-passed: false }
+  plan:
+    brainstorm:        { status: pending, gate-passed: false }
+    design-system:     { status: pending, gate-passed: false }
+    architecture:      { status: pending, gate-passed: false }
+    task-decompose:    { status: pending, gate-passed: false }
+  # NOTE: v4's `phases.build.tasks: []` is replaced by `slice_graph` below.
+  # `phases.build` is intentionally absent in v5; the v5 reader treats v4
+  # manifests (with `phases.build.tasks`) as a single-slice graph.
+  quality:
+    code-review-final: { status: pending, gate-passed: false }
+    test-plan:         { status: pending, gate-passed: false }
+    test-execution:    { status: pending, gate-passed: false }
+    uiux-review:       { status: pending, gate-passed: false }
+  deliver:
+    pr-created: false
+    deployed:   false
+    onboarding: false
+  support:
+    gotchas-recorded: false
+
+# v5 NEW — slice graph replaces flat task list.
+# DAG: each slice declares its dependencies. No edges list (per-node
+# depends_on is the source of truth). Verifier (see SCHEMA.md) rejects:
+# unresolved deps, self-deps, cycles, gate-name collisions with manifest-level
+# gates, and non-skeleton slices that don't transitively depend on the
+# skeleton (when a skeleton slice is present).
+#
+# Skeleton is OPTIONAL. /greenfield and /feature use a skeleton slice;
+# /bugfix and /hotfix omit it (small touches don't earn fake structure).
+# At most one slice may have type: skeleton. If present, it is the root.
+slice_graph:
+  current_slice: skeleton     # which slice the agent is working on now
+  slices:
+    skeleton:
+      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
+      gates:
+        skeleton-runs:    { status: pending, gate-passed: false }
+        wiki-lint:        { status: pending, gate-passed: false }
+        runtime-reach:    { status: pending, gate-passed: false }
+
+    # Example slice — replace/extend during /feature flow.
+    # Slices are added by plan-task-decompose and confirmed by user.
+    example-slice:
+      type: feature-slice
+      depends_on: [skeleton]
+      status: pending
+      gates:
+        build-tdd:        { status: pending, gate-passed: false }
+        wiki-lint:        { status: pending, gate-passed: false }
+        runtime-reach:    { status: pending, gate-passed: false }
+        code-review:      { status: pending, gate-passed: false }

package/templates/manifests/v6/SCHEMA.md

@@ -0,0 +1,199 @@
+# v6 manifest schema
+
+Source of truth for v6 manifest validation rules. The v6 reader and verifier in `src/work-manifest.ts` implement against this document.
+
+v6 layers a `phase_plan:` block on top of v5. Everything else (slice graph, gate state, escalation links) is inherited from v5 unchanged — see `templates/manifests/v5/SCHEMA.md` for the unchanged parts. This document describes the v6 delta and the parsing contract.
+
+---
+
+## 1. Why phase_plan
+
+v5 modeled a single canonical workflow: every gate was either `pending`, `complete`, or `skipped` based on what the skill recorded. There was no place to declare *up front* "this whole feature collapses to commit-only delivery, no PR" or "test-plan runs in light mode for this prototype-iteration feature."
+
+v6 separates planning from execution:
+
+- **`phase_plan:`** — the **plan** for which phases run and at what rigor. Set during preflight (Step 1 of `/feature`, `/bugfix`, etc). Stable through execution.
+- **`phases:`** — the **gate state** as execution proceeds. Mutated by skills; gate-passed booleans recorded after the matching skill runs.
+
+The two blocks are complementary, not redundant. A phase with `phase_plan.X: active-light` still has `phases.X.gate-passed: true` once its (lighter) skill invocation completes.
+
+---
+
+## 2. Top-level changes from v5
+
+| Field | v5 | v6 |
+|---|---|---|
+| `schema_version` | `"5"` | `"6"` |
+| `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).
+
+v6 is a purely additive change. Existing v5 fields keep their shape and semantics. `phase_plan` is the only new top-level field, and it is required.
+
+The two blocks coexist by design — `phase_plan` captures intent at preflight, `phases` records what skills actually accomplished. A manifest with `phase_plan.X: skipped` keeps the corresponding `phases.X.{gate}.gate-passed: false`; status fields document the discrepancy.
+
+---
+
+## 3. phase_plan structure
+
+`phase_plan:` is a map. Keys are workflow milestone identifiers (phase names, gate names, or any string the workflow recognizes). Values are either:
+
+- **Scalar form** — one of the allowed plan-status values
+- **Object form** — `{ status: <value>, reason: <string> }` when a reason needs to be attached
+
+```yaml
+phase_plan:
+  concept: skipped                                # scalar form
+  wireframe: skipped
+  prototype: skipped
+  codify: skipped
+  production-build: active
+  test-plan:                                      # object form
+    status: active-light
+    reason: "typecheck + browser verify only — no test runner installed"
+  uiux-review: active
+  code-review-final: active
+  deliver: active-commit-only
+  onboarding: skipped
+  gotchas: as-discovered
+```
+
+### 3.1 Allowed plan-status values
+
+| Value | Meaning | Gate-passed expected? |
+|---|---|---|
+| `active` | Runs at full rigor | yes (skill invocation required) |
+| `active-light` | Runs with reduced rigor (e.g. typecheck-only test phase, no test-runner suite) | yes (skill invocation required) |
+| `active-commit-only` | Runs but truncated to a partial deliverable (e.g. commit on existing branch instead of opening a PR) | yes (skill invocation required) |
+| `skipped` | Does not run; downstream consumers MUST handle absence | no — stays `false` |
+| `as-discovered` | Runs opportunistically when triggered; not scheduled | when triggered |
+| `complete-inline` | Was done inline (often before the manifest existed) without skill invocation | no — stays `false`; status field documents the work |
+
+The verifier rejects any other value with `E_BAD_PHASE_PLAN_STATUS`.
+
+### 3.2 Key naming convention
+
+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.
+
+**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.
+
+#### Recommended keys per work type
+
+Commands should use these keys (kebab-case, match the templates verbatim):
+
+| Work type | Recommended `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` |
+| `bugfix` | `debug-root-cause`, `production-build`, `code-review`, `deliver`, `gotchas` |
+| `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`.
+
+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.
+
+### 3.3 gate-passed discipline
+
+A manifest with `phase_plan.X: active` MUST still earn `phases.X.gate-passed: true` through skill invocation — the `gate-enforcer.sh` hook enforces this. Plan-status `active` does NOT pre-authorize gate passage.
+
+Conversely, `phase_plan.X: skipped` / `complete-inline` SHOULD keep `phases.X.gate-passed: false`. The plan-status documents intent; the gate field documents whether the rigor was applied. Setting `gate-passed: true` on a skipped phase trains the manifest to lie about gate state.
+
+This convention is enforced by skills (they read phase_plan and choose not to set gate-passed on skipped phases). The verifier does NOT cross-validate plan-status against gate-passed — that's a hot path for false positives and the convention is well-understood.
+
+---
+
+## 4. Migration from v5
+
+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.
+
+---
+
+## 5. Verifier interface delta
+
+Added `ErrorCode`:
+
+```ts
+type ErrorCode = 
+  | ...v5 codes...
+  | 'E_BAD_PHASE_PLAN_STATUS'    // phase_plan value not in §3.1 enum
+  | 'E_BAD_PHASE_PLAN_SHAPE';    // phase_plan not a map; or object-form value missing status
+```
+
+Added `Manifest` field:
+
+```ts
+export type PhasePlanStatus = 
+  | "active" | "active-light" | "active-commit-only" 
+  | "skipped" | "as-discovered" | "complete-inline";
+
+export interface PhasePlanEntry {
+  status: PhasePlanStatus;
+  reason?: string;
+}
+
+export interface Manifest {
+  // ...v5 fields...
+  phase_plan?: Record<string, PhasePlanEntry>;   // normalized at parse time
+}
+```
+
+At parse time, scalar-form values are normalized to object-form `{ status: <value> }` so downstream code reads a uniform shape.
+
+`schema` in the return value gains a third value: `'v4' | 'v5' | 'v6'`.
+
+---
+
+## 6. Artifacts convention
+
+The Manifest interface includes an optional top-level `artifacts:` map. v6 standardizes a convention for tracking phase outputs (paths + lock timestamps):
+
+```yaml
+artifacts:
+  concept:
+    deck_path: decks/{name}/slides.md
+    locked_at: "2026-05-12T10:00:00Z"
+  wireframe:
+    html_path: pocs/{name}-wireframe/index.html
+    locked_at: "2026-05-12T11:00:00Z"
+  prototype:
+    path: pocs/{name}-prototype/
+    locked_at: "2026-05-12T12:00:00Z"
+  codify:
+    locked_at: "2026-05-12T13:00:00Z"   # no path — slice_graph is the artifact
+  production-build:
+    locked_at: "2026-05-12T16:00:00Z"   # no path — slice terminal state is the artifact
+```
+
+**Lock signal.** Presence of `artifacts.{phase}.locked_at` is the canonical "phase locked" signal. Skills that gate on a prior phase being locked (e.g. `harden` requires prototype locked, `build-prototype` requires wireframe locked) check this field rather than a separate status enum.
+
+**Path fields are phase-specific:**
+
+| Phase | Field | Notes |
+|---|---|---|
+| concept | `deck_path` | Path to the slide deck |
+| wireframe | `html_path` | Path to the single-HTML wireframe |
+| prototype | `path` | Path to the prototype directory |
+| codify | (no path) | The slice_graph + aiwiki/architecture/ files ARE the artifacts |
+| production-build | (no path) | Slice terminal state + the production code ARE the artifacts |
+| deliver | `pr_urls` | Array of PR URLs created |
+
+The parser does not validate the artifacts shape — this is a documentation convention. Skills follow it; the verifier ignores it.
+
+---
+
+## 7. Reserved evolutions
+
+Out of scope for v6.0; slots reserved so we don't break the schema again:
+
+- **Plan-status `deferred`** (run later as a follow-up work item) — the current `escalated_from` / `successor_path` fields cover the multi-manifest case; `deferred` is a single-manifest variant we may need.
+- **Phase ordering hints** — currently implicit (insertion order in YAML map). Add an explicit `order:` field if real usage shows fragility.
+- **Strict artifact validation** — per-phase required fields could be enforced if real usage shows skills writing inconsistent shapes.