benwu95 · benwu95 · Jul 14, 2026 · Jul 14, 2026 · Jul 14, 2026
diff --git a/.agents/skills/prospec-archive/SKILL.md b/.agents/skills/prospec-archive/SKILL.md
@@ -77,7 +77,7 @@ For each confirmed change:
 1. Create `.prospec/archive/{YYYY-MM-DD}-{change-name}/`
 2. Move all artifacts (proposal.md, plan.md, delta-spec.md, tasks.md, metadata.yaml, and design-spec.md + interaction-spec.md if present)
 3. Place generated summary.md in archive directory
-4. Update `metadata.yaml` to `status: archived`
+4. Update `metadata.yaml` to `status: archived` (edit in place; keep the `metadata-format` serialization intact — do not reorder or reformat fields)
 5. Copy `summary.md` → `prospec/specs/_archived-history/{YYYY-MM-DD}-{change-name}.md` (date prefix = the archive date, same as the `.prospec/archive/{YYYY-MM-DD}-{change-name}/` folder) — the **committed** spec-history audit trail (`.prospec/archive/` is gitignored, so this copy is the only per-change record in version control). It lands in `_archived-history/` (drift-excluded via `ARCHIVED_EXCLUDES`), never flat under `prospec/specs/`. Non-fatal — a copy failure never blocks archiving. Format: `references/archive-format.md` §Spec Archiving.
 
 > **Phase 3 Gate** — proceed when:

diff --git a/.agents/skills/prospec-ff/SKILL.md b/.agents/skills/prospec-ff/SKILL.md
@@ -21,7 +21,7 @@ Write generated documents in the language defined by the Constitution's Language
 1. [STABLE] Read `prospec/CONSTITUTION.md` — prepare Constitution check
 2. [DYNAMIC] Read `prospec/index.md` — identify related modules
 
-> Format references are read **per phase on demand**, NOT as Startup Loading items (keeps the stable prefix lean): [`references/proposal-format.md`](references/proposal-format.md) at Phase 2, [`references/plan-format.md`](references/plan-format.md) + [`references/delta-spec-format.md`](references/delta-spec-format.md) at Phase 3, [`references/tasks-format.md`](references/tasks-format.md) at Phase 4. Read each when entering its phase; do not preload them into the stable prefix.
+> Format references are read **per phase on demand**, NOT as Startup Loading items (keeps the stable prefix lean): [`references/proposal-format.md`](references/proposal-format.md) + [`references/metadata-format.md`](references/metadata-format.md) at Phase 2, [`references/plan-format.md`](references/plan-format.md) + [`references/delta-spec-format.md`](references/delta-spec-format.md) at Phase 3, [`references/tasks-format.md`](references/tasks-format.md) at Phase 4. Read each when entering its phase; do not preload them into the stable prefix.
 
 ## What Makes FF Unique
 
@@ -56,7 +56,7 @@ Derive kebab-case change name, confirm before proceeding.
 
 | Step | Action |
 |------|--------|
-| Scaffold | Create `.prospec/changes/[name]/` + `metadata.yaml`(status: story) + `proposal.md` |
+| Scaffold | Create `.prospec/changes/[name]/` + `metadata.yaml`(status: story, serialized per [`references/metadata-format.md`](references/metadata-format.md)) + `proposal.md` |
 | Scale | Run the complexity assessment from `/prospec-new-story` Phase 3.5 (criteria table + quick veto); user confirms; write `metadata.scale`. Quick → slim proposal form |
 | Populate | Read [`references/proposal-format.md`](references/proposal-format.md) on demand, then write User Story and ACs to that format |
 | Check | Site-specific Constitution check (this phase's rule: INVEST) → PASS continue / FAIL pause — the full every-principle audit is `/prospec-verify` only |

diff --git a/.agents/skills/prospec-ff/references/metadata-format.md b/.agents/skills/prospec-ff/references/metadata-format.md
@@ -0,0 +1,110 @@
+# Metadata (metadata.yaml) Format Reference
+
+This document defines the **serialization format** for a change's `metadata.yaml`
+(`.prospec/changes/{name}/metadata.yaml`). It exists so every skill that creates or
+appends to `metadata.yaml` emits byte-consistent YAML instead of inventing field order,
+quoting, or date format per invocation.
+
+> **Scope: format only.** Field *semantics*, types, and optionality are defined by the
+> `ChangeMetadataSchema` in `src/types/change.ts`; `status` values and their transitions
+> by `prospec/ai-knowledge/_status-lifecycle.md`; the required-field floor is enforced by
+> the `metadata-completeness` drift check (`prospec check`). This reference does **not**
+> restate any of them — it governs how the data is written to disk. When in doubt about a
+> value's meaning, read those sources; when in doubt about how to lay it out, read this.
+
+---
+
+## Serialization conventions
+
+- **Block style**, 2-space indent — never flow/inline maps or sequences for the top-level
+  fields. Arrays are block sequences (`- item` on their own lines).
+- **Key order is canonical and fixed** (see below) — write keys in this order; do not reorder
+  to match how you happened to gather the data.
+- **Minimal quoting** — quote a scalar only when YAML requires it (leading special char,
+  a value that would otherwise parse as a non-string, an embedded `:` + space). Do not
+  wrap plain prose or dates in quotes by habit; do not use `>-`/`|` block scalars for a
+  one-line `description`.
+- **No Markdown inside values** — `related_modules` entries are bare module names
+  (`- lib`), never `- "**lib**"`; descriptions are plain text.
+- **`created_at` is a full ISO 8601 timestamp** (`2026-07-13T09:51:00.000Z`), matching the
+  CLI path's `new Date().toISOString()` in `change-story.service.ts` — not a bare `YYYY-MM-DD`.
+- **No document markers** (`---`/`...`) and exactly one trailing newline.
+
+This is exactly what `stringifyYaml` (the `yaml` library, default options) emits, so the
+skill-authored file and the CLI-authored file (`prospec change story`) converge.
+
+## Canonical field order
+
+`name` → `created_at` → `status` → `scale` → `related_modules` → `description` →
+`quality_log` → `review_provenance` → `introduced_by`
+
+| Field | Required | Written by | Notes |
+|-------|----------|-----------|-------|
+| `name` | yes | new-story / ff (create) | change dir name (kebab-case) |
+| `created_at` | yes | new-story / ff (create) | full ISO 8601 |
+| `status` | yes | every stage that owns a transition | one of the lifecycle values (`_status-lifecycle.md`) |
+| `scale` | no (defaults `standard`) | new-story / ff, after user-confirmed assessment | one of the schema's `CHANGE_SCALES` values |
+| `related_modules` | no | new-story / ff | bare module names |
+| `description` | no | new-story / ff | one line, plain text |
+| `quality_log` | no | new-story, ff, plan, tasks, review, verify, learn (append) | gate trail — see below |
+| `review_provenance` | no | `prospec check --record-review` at review | machine-written baseline |
+| `introduced_by` | no | new-story (bug-fix changes only) | escaped-defect registration |
+
+## `quality_log` entry shape
+
+Each station appends one entry. Fixed keys `skill` / `date` / `result` / `warnings`, plus
+optional structured keys that only certain stations write:
+
+```yaml
+quality_log:
+  - skill: prospec-review          # the station name
+    date: 2026-07-13               # bare ISO 8601 date
+    result: WARN                   # gate three-state ONLY: PASS | WARN | FAIL
+    warnings:
+      - "one finding per array item"
+    criticals_found: 0             # review only (optional)
+    criticals_fixed: 0             # review only (optional)
+    majors: 1                      # review only (optional)
+  - skill: prospec-verify
+    date: 2026-07-13
+    result: PASS                   # still the gate three-state
+    warnings: []
+    grade: S                       # verify quality grade goes HERE, never in `result`
+    dimensions:                    # verify only (optional)
+      - name: task-completion
+        result: PASS
+      - name: tests
+        result: PASS
+```
+
+- **`result` is always the gate three-state `PASS` / `WARN` / `FAIL`.** The `/prospec-verify`
+  quality grade (`S`/`A`/`B`/`C`/`D`) is written to the separate `grade` key and is **never in
+  `result`** — `result: A` is malformed.
+- `warnings` is always present (use `[]` when none); each entry is one string.
+- Omit the optional keys entirely when they do not apply — do not write them as `null`/empty.
+
+## Canonical example (a standard change mid-lifecycle)
+
+```yaml
+name: add-widget-export
+created_at: 2026-07-13T09:51:00.000Z
+status: tasks
+scale: standard
+related_modules:
+  - services
+  - tests
+description: Add CSV export to the widget service
+quality_log:
+  - skill: prospec-ff
+    date: 2026-07-13
+    result: PASS
+    warnings: []
+```
+
+---
+
+## Reference Information
+
+- Project name: `prospec`
+- AI Knowledge path: `prospec/ai-knowledge`
+- Schema authority: `src/types/change.ts` · Status authority: `prospec/ai-knowledge/_status-lifecycle.md`
diff --git a/.agents/skills/prospec-implement/SKILL.md b/.agents/skills/prospec-implement/SKILL.md
@@ -117,7 +117,7 @@ code tasks are done, emit `Progress Y/Y (Complete)` and point to `/prospec-revie
 ### Phase 6: Move to Next Task
 
 Auto-locate next uncompleted task. If switching architecture layers, load new module knowledge.
-When all **code** tasks are complete (unchecked `[M]`/`[V]` tasks are surfaced as reminders, never blockers — kind schema: tasks-format reference), update `.prospec/changes/[name]/metadata.yaml` → `status: implemented`, then suggest `/prospec-review` (adversarial code review before verify). **Do not commit during implement** — the commit boundary is after `/prospec-verify` reaches S/A, so implement + review + verify fixes fold into one atomic-by-feature commit.
+When all **code** tasks are complete (unchecked `[M]`/`[V]` tasks are surfaced as reminders, never blockers — kind schema: tasks-format reference), update `.prospec/changes/[name]/metadata.yaml` → `status: implemented` (edit in place; keep the `metadata-format` serialization intact — do not reorder or reformat fields), then suggest `/prospec-review` (adversarial code review before verify). **Do not commit during implement** — the commit boundary is after `/prospec-verify` reaches S/A, so implement + review + verify fixes fold into one atomic-by-feature commit.
 
 ## Task Execution Rules
 

diff --git a/.agents/skills/prospec-new-story/SKILL.md b/.agents/skills/prospec-new-story/SKILL.md
@@ -20,8 +20,9 @@ Write generated documents in the language defined by the Constitution's Language
 
 1. [STABLE] Read `prospec/CONSTITUTION.md` — prepare Constitution check
 2. [STABLE] **MANDATORY** — Read [`references/proposal-format.md`](references/proposal-format.md) for proposal.md format specification
-3. [DYNAMIC] Read `prospec/index.md` — identify related modules by matching proposal keywords against module `keywords` field
-4. [DYNAMIC] Read `prospec/specs/features/` — check existing feature specs for context
+3. [STABLE] **MANDATORY** — Read [`references/metadata-format.md`](references/metadata-format.md) for the metadata.yaml serialization format (canonical field order, minimal quoting, `created_at` ISO 8601, `quality_log` entry shape) — the scaffolded metadata.yaml MUST follow it
+4. [DYNAMIC] Read `prospec/index.md` — identify related modules by matching proposal keywords against module `keywords` field
+5. [DYNAMIC] Read `prospec/specs/features/` — check existing feature specs for context
 
 ## Entry Gate
 
@@ -54,7 +55,7 @@ Derive a kebab-case name from interview results (verb-first, 2-4 words). Confirm
 
 | Scenario | Action |
 |----------|--------|
-| Directory doesn't exist | Create `.prospec/changes/[name]/` + `metadata.yaml`(status: story) + empty `proposal.md` |
+| Directory doesn't exist | Create `.prospec/changes/[name]/` + `metadata.yaml`(status: story, serialized per [`references/metadata-format.md`](references/metadata-format.md)) + empty `proposal.md` |
 | Already exists | Read existing files, proceed to populate |
 
 > **Phase 3 Gate** — proceed when:

diff --git a/.agents/skills/prospec-new-story/references/metadata-format.md b/.agents/skills/prospec-new-story/references/metadata-format.md
@@ -0,0 +1,110 @@
+# Metadata (metadata.yaml) Format Reference
+
+This document defines the **serialization format** for a change's `metadata.yaml`
+(`.prospec/changes/{name}/metadata.yaml`). It exists so every skill that creates or
+appends to `metadata.yaml` emits byte-consistent YAML instead of inventing field order,
+quoting, or date format per invocation.
+
+> **Scope: format only.** Field *semantics*, types, and optionality are defined by the
+> `ChangeMetadataSchema` in `src/types/change.ts`; `status` values and their transitions
+> by `prospec/ai-knowledge/_status-lifecycle.md`; the required-field floor is enforced by
+> the `metadata-completeness` drift check (`prospec check`). This reference does **not**
+> restate any of them — it governs how the data is written to disk. When in doubt about a
+> value's meaning, read those sources; when in doubt about how to lay it out, read this.
+
+---
+
+## Serialization conventions
+
+- **Block style**, 2-space indent — never flow/inline maps or sequences for the top-level
+  fields. Arrays are block sequences (`- item` on their own lines).
+- **Key order is canonical and fixed** (see below) — write keys in this order; do not reorder
+  to match how you happened to gather the data.
+- **Minimal quoting** — quote a scalar only when YAML requires it (leading special char,
+  a value that would otherwise parse as a non-string, an embedded `:` + space). Do not
+  wrap plain prose or dates in quotes by habit; do not use `>-`/`|` block scalars for a
+  one-line `description`.
+- **No Markdown inside values** — `related_modules` entries are bare module names
+  (`- lib`), never `- "**lib**"`; descriptions are plain text.
+- **`created_at` is a full ISO 8601 timestamp** (`2026-07-13T09:51:00.000Z`), matching the
+  CLI path's `new Date().toISOString()` in `change-story.service.ts` — not a bare `YYYY-MM-DD`.
+- **No document markers** (`---`/`...`) and exactly one trailing newline.
+
+This is exactly what `stringifyYaml` (the `yaml` library, default options) emits, so the
+skill-authored file and the CLI-authored file (`prospec change story`) converge.
+
+## Canonical field order
+
+`name` → `created_at` → `status` → `scale` → `related_modules` → `description` →
+`quality_log` → `review_provenance` → `introduced_by`
+
+| Field | Required | Written by | Notes |
+|-------|----------|-----------|-------|
+| `name` | yes | new-story / ff (create) | change dir name (kebab-case) |
+| `created_at` | yes | new-story / ff (create) | full ISO 8601 |
+| `status` | yes | every stage that owns a transition | one of the lifecycle values (`_status-lifecycle.md`) |
+| `scale` | no (defaults `standard`) | new-story / ff, after user-confirmed assessment | one of the schema's `CHANGE_SCALES` values |
+| `related_modules` | no | new-story / ff | bare module names |
+| `description` | no | new-story / ff | one line, plain text |
+| `quality_log` | no | new-story, ff, plan, tasks, review, verify, learn (append) | gate trail — see below |
+| `review_provenance` | no | `prospec check --record-review` at review | machine-written baseline |
+| `introduced_by` | no | new-story (bug-fix changes only) | escaped-defect registration |
+
+## `quality_log` entry shape
+
+Each station appends one entry. Fixed keys `skill` / `date` / `result` / `warnings`, plus
+optional structured keys that only certain stations write:
+
+```yaml
+quality_log:
+  - skill: prospec-review          # the station name
+    date: 2026-07-13               # bare ISO 8601 date
+    result: WARN                   # gate three-state ONLY: PASS | WARN | FAIL
+    warnings:
+      - "one finding per array item"
+    criticals_found: 0             # review only (optional)
+    criticals_fixed: 0             # review only (optional)
+    majors: 1                      # review only (optional)
+  - skill: prospec-verify
+    date: 2026-07-13
+    result: PASS                   # still the gate three-state
+    warnings: []
+    grade: S                       # verify quality grade goes HERE, never in `result`
+    dimensions:                    # verify only (optional)
+      - name: task-completion
+        result: PASS
+      - name: tests
+        result: PASS
+```
+
+- **`result` is always the gate three-state `PASS` / `WARN` / `FAIL`.** The `/prospec-verify`
+  quality grade (`S`/`A`/`B`/`C`/`D`) is written to the separate `grade` key and is **never in
+  `result`** — `result: A` is malformed.
+- `warnings` is always present (use `[]` when none); each entry is one string.
+- Omit the optional keys entirely when they do not apply — do not write them as `null`/empty.
+
+## Canonical example (a standard change mid-lifecycle)
+
+```yaml
+name: add-widget-export
+created_at: 2026-07-13T09:51:00.000Z
+status: tasks
+scale: standard
+related_modules:
+  - services
+  - tests
+description: Add CSV export to the widget service
+quality_log:
+  - skill: prospec-ff
+    date: 2026-07-13
+    result: PASS
+    warnings: []
+```
+
+---
+
+## Reference Information
+
+- Project name: `prospec`
+- AI Knowledge path: `prospec/ai-knowledge`
+- Schema authority: `src/types/change.ts` · Status authority: `prospec/ai-knowledge/_status-lifecycle.md`
diff --git a/.agents/skills/prospec-plan/SKILL.md b/.agents/skills/prospec-plan/SKILL.md
@@ -173,7 +173,7 @@ Emit one line: `Met N/M | Unmet: <items> | Overall: PASS|WARN|FAIL | Next: <one-
 
 ### Exit Gate (Constitution)
 
-Verify the output against this skill's **site-specific** Constitution rule (**dependency-direction/layering**) — not the full Constitution; the every-principle audit is `/prospec-verify` V3/5 only. When the rule carries RFC-2119 severity (BL-031), grade by weight — MUST→FAIL, SHOULD→WARN, MAY→informational (the grade vocabulary stays PASS/WARN/FAIL). A free-text Constitution falls back to judgment-based grading. Record each WARN/FAIL to `metadata.yaml` `quality_log` (`skill` / `date` / `result` / `warnings`). Advisory — surface issues, do not hard-block.
+Verify the output against this skill's **site-specific** Constitution rule (**dependency-direction/layering**) — not the full Constitution; the every-principle audit is `/prospec-verify` V3/5 only. When the rule carries RFC-2119 severity (BL-031), grade by weight — MUST→FAIL, SHOULD→WARN, MAY→informational (the grade vocabulary stays PASS/WARN/FAIL). A free-text Constitution falls back to judgment-based grading. Record each WARN/FAIL to `metadata.yaml` `quality_log` (`skill` / `date` / `result` / `warnings`) — entry shape per the `metadata-format` reference (bundled with `/prospec-new-story` · `/prospec-ff`); `result` stays the gate three-state, never a grade. Advisory — surface issues, do not hard-block.
 
 ## NEVER
 

diff --git a/.agents/skills/prospec-review/SKILL.md b/.agents/skills/prospec-review/SKILL.md
@@ -71,7 +71,7 @@ Write findings to `.prospec/changes/[name]/review.md`: a cumulative table (`loca
 
 Review must leave a machine-queryable record so `/prospec-verify`'s Entry Gate can prove it ran and is still current:
 
-1. **Every round** — including a **review-clean** round (0 critical / 0 major) — append a `skill: prospec-review` entry to `metadata.yaml` `quality_log` (result `PASS` when clean, `WARN` when unresolved majors/FAIL carry forward). A clean review that records nothing is indistinguishable from a review that never ran. Carry the round's counts as structured fields so quality trends are machine-aggregatable (not buried in `review.md` prose): `criticals_found`, `criticals_fixed`, and `majors` (integers ≥ 0). These are additive — `result`/`warnings` are unchanged; a round that finds nothing records the counts as `0`.
+1. **Every round** — including a **review-clean** round (0 critical / 0 major) — append a `skill: prospec-review` entry to `metadata.yaml` `quality_log` (result `PASS` when clean, `WARN` when unresolved majors/FAIL carry forward). A clean review that records nothing is indistinguishable from a review that never ran. Carry the round's counts as structured fields so quality trends are machine-aggregatable (not buried in `review.md` prose): `criticals_found`, `criticals_fixed`, and `majors` (integers ≥ 0). These are additive — `result`/`warnings` are unchanged; a round that finds nothing records the counts as `0`. Entry shape (these optional keys, and `result` staying the gate three-state) is defined by the `metadata-format` reference (bundled with `/prospec-new-story` · `/prospec-ff`).
 2. **At loop convergence** (review-clean or escalation), run `prospec check --record-review` — it code-computes the reviewed change's digest and writes `review_provenance` to `metadata.yaml`. This is the baseline the `review-provenance` drift check compares against. **Graceful**: if the CLI is unavailable, state so explicitly and record the review entry anyway — never silently skip.
 
 Because the digest is code-computed, editing the change's code after this point flips `review-provenance` to stale — `/prospec-verify` will then require a fresh review round before it runs.