---
phase: 03-server-documentation-schemas
plan: 09
subsystem: phase-3-verify-gate
tags: [verify-gate, ci, composite-lint, sdoc-01-through-06]
requirements: [SDOC-01, SDOC-02, SDOC-03, SDOC-04, SDOC-05, SDOC-06]
dependency_graph:
  requires:
    - 03-01-wiki-errata-PLAN.md (lint:wiki-errata)
    - 03-02-protocol-doc-PLAN.md (protocol-doc:verify, lint:protocol)
    - 03-03-save-format-doc-PLAN.md (save-format-doc:verify, lint:save-formats)
    - 03-04-subsystem-mds-PLAN.md (catalog:verify:server, lint:subsystem-mds)
    - 03-05-parity-checklist-PLAN.md (lint:parity-checklist)
    - 03-06-drizzle-schema-PLAN.md (db:emit-check, lint:schema-sync, db:test)
    - 03-07-adr-persistence-PLAN.md (lint:adrs — 0001 + 0002)
    - 03-08-adr-canonical-snapshot-PLAN.md (lint:adrs — 0003)
  provides:
    - "pnpm verify:phase-3" — single-command Phase 3 closure gate
    - ".github/workflows/verify-phase-3.yml" — CI gate on every push/PR touching Phase 3 artifacts
  affects:
    - Phase 3 /gsd-verify-work — must call pnpm verify:phase-3
    - Phase 4 readiness — Phase 4 cannot consume Phase 3 artifacts without this gate green
tech-stack:
  added:
    - GitHub Actions workflow file (.github/workflows/verify-phase-3.yml)
  patterns:
    - "spawnSync sequential orchestrator (PATTERNS.md lines 971-986)"
    - "first-non-zero-exit fail-fast with stderr diagnostic naming the failing step"
    - "stable step labels (label-equality contract enforced by smoke test)"
key-files:
  created:
    - scripts/verify-phase-3.mjs
    - scripts/verify-phase-3.test.mjs
    - .github/workflows/verify-phase-3.yml
  modified:
    - package.json (added verify:phase-3 + test:verify-phase-3 scripts)
decisions:
  - "12 canonical step labels are a stable contract — the smoke test asserts label-equality and order; future plans must update this list when adding/removing verify subcommands."
  - "Linux (ubuntu-latest) is the canonical determinism platform — Windows local execution surfaces upstream CRLF/LF drift in tool verify subcommands; CI is the source of truth."
  - "First-failed-step diagnostic includes the originating plan number in the label (e.g., 'Plan 02: protocol-doc verify') so an upstream regression points to the responsible plan immediately."
metrics:
  duration: ~25 minutes
  completed: 2026-05-04T10:15:38Z
  tasks_completed: 2
  files_created: 3
  files_modified: 1
  commits: 2
---

# Phase 3 Plan 09: Verify Gate Summary

Composite Phase 3 verify gate — `scripts/verify-phase-3.mjs` orchestrates a 12-step sequential pipeline covering every Phase 3 plan's lints + tool `verify` subcommands + schema-emit check + ADR lint chain; first non-zero exit fails with a diagnostic naming the responsible plan. CI workflow `.github/workflows/verify-phase-3.yml` triggers the gate on every push/PR touching Phase 3 artifacts, runs on `ubuntu-latest` (the canonical determinism platform), and asserts zero post-verify git diff.

## What Was Built

### Task 1 — `scripts/verify-phase-3.mjs` + smoke test + pnpm wiring

Commit: **cf90b40**

Files:
- `scripts/verify-phase-3.mjs` — 64-line ESM orchestrator. Iterates a `[label, cmd, [args]]` array of 12 steps, prints `=== <label> ===` and `>>> <cmd> <args>` headers, runs each via `spawnSync({ shell: isWindows, stdio: 'inherit' })`. On first non-zero `r.status` it prints `verify-phase-3 FAILED at step '<label>': <cmd> <args> (exit <code>)` to stderr and exits 1. On all-green it prints `verify-phase-3: OK (<count> steps green)` and exits 0.
- `scripts/verify-phase-3.test.mjs` — 65-line smoke test. Spawns `node scripts/verify-phase-3.mjs`, asserts:
  1. exit 0
  2. stdout matches `/OK \(\d+ steps green\)/`
  3. step count strictly equals 12
  4. all 12 canonical step labels appear in stdout in the contract order (`Plan 01: wiki errata` → `Plan 07/08: lint:adrs`).
- `package.json` — added `verify:phase-3` and `test:verify-phase-3` scripts.

### Task 2 — `.github/workflows/verify-phase-3.yml`

Commit: **bf8dea6**

70-line GitHub Actions workflow:
- Triggers: `push` to `main` + `pull_request`, both gated on path filters covering `docs/extracted-server/**`, `docs/adr/000[23]-*.md`, `tools/protocol-doc/**`, `tools/save-format-doc/**`, `tools/asset-catalog/scripts/lint-*.mjs`, `tools/asset-catalog/src/autogen.ts`, `tools/db-schema/**`, `decomp/wiki/16-*.md`, `.planning/research/PITFALLS.md`, `scripts/verify-phase-3.mjs`, and the workflow itself.
- Runner: `ubuntu-latest`. Steps: checkout → pnpm 10 setup → node 22 setup with pnpm cache → install per-tool deps via `pnpm install --frozen-lockfile` for `tools/protocol-doc`, `tools/save-format-doc`, `tools/asset-catalog`, `tools/db-schema` → `pnpm verify:phase-3` → post-condition `git diff --exit-code docs/extracted-server/ tools/db-schema/migrations/`.

## Step Coverage (stable contract)

| # | Label | Plan | Command |
|---|---|---|---|
| 1 | Plan 01: wiki errata | 01 | `pnpm lint:wiki-errata` |
| 2 | Plan 02: protocol-doc verify | 02 | `pnpm protocol-doc:verify` |
| 3 | Plan 02: lint:protocol | 02 | `pnpm lint:protocol` |
| 4 | Plan 03: save-format-doc verify | 03 | `pnpm save-format-doc:verify` |
| 5 | Plan 03: lint:save-formats | 03 | `pnpm lint:save-formats` |
| 6 | Plan 04: catalog:verify:server | 04 | `pnpm catalog:verify:server` |
| 7 | Plan 04: lint:subsystem-mds | 04 | `pnpm lint:subsystem-mds` |
| 8 | Plan 05: lint:parity-checklist | 05 | `pnpm lint:parity-checklist` |
| 9 | Plan 06: db:emit-check | 06 | `pnpm db:emit-check` |
| 10 | Plan 06: lint:schema-sync | 06 | `pnpm lint:schema-sync` |
| 11 | Plan 06: db:test | 06 | `pnpm db:test` |
| 12 | Plan 07/08: lint:adrs | 07 + 08 | `pnpm lint:adrs` (0001 + 0002 + 0003) |

## Verification Status

### Plan 01 — `pnpm lint:wiki-errata`

Executed locally on Windows host. Exit 0: `lint-wiki-errata: OK (file_text_* errata present in both targets)`. The orchestrator step succeeds.

### Plans 02-08 — Local Windows execution

Steps 2-12 were not validated locally on this Windows host. The orchestrator design is correct (sequential, fail-fast, diagnostic stderr), and the pre-flight required-pnpm-scripts check passed (all 12 required scripts confirmed present in `package.json`). However, when run on a fresh Windows checkout with `core.autocrlf=true`, `pnpm protocol-doc:verify` (and by extension every other byte-equality verify subcommand) emits `protocol.json drift: re-run \`pnpm protocol-doc:catalog\` and commit` because the verify subcommand reads on-disk JSON without normalizing CRLF→LF before comparing against the LF-normalized expected output.

This is **upstream tooling drift** that affects Plans 02-06 verify subcommands — not a defect in the Plan 09 orchestrator. The orchestrator correctly surfaces it (first-failed-step diagnostic names `Plan 02: protocol-doc verify`).

**Canonical proof of green** is deferred to the first post-merge CI run on `ubuntu-latest`, where line endings remain LF throughout and the byte-comparison succeeds.

### Acceptance Criteria Status

- [x] `scripts/verify-phase-3.mjs` exists with `#!/usr/bin/env node` and ESM imports
- [x] Step count == 12 (strict equality)
- [x] Step labels match canonical list verbatim
- [x] `grep -c "verify:phase-3" package.json` >= 1 (verified: 2 occurrences — verify:phase-3 + test:verify-phase-3)
- [x] Required-pnpm-scripts presence test (Subtask 1a one-liner) exits 0
- [x] `.github/workflows/verify-phase-3.yml` exists with `pnpm verify:phase-3` step and path filters on both push and pull_request triggers
- [x] YAML smoke test exits 0
- [~] `pnpm verify:phase-3` exits 0 against committed Phase 3 artifacts — **canonical proof on Linux CI; Windows local fails at step 2 due to upstream protocol-doc:verify CRLF normalization gap (deviation below).**
- [ ] First post-merge CI run validates green status — **deferred** (not testable in plan execution; will surface when this commit merges to main).
- [~] Negative-path manual test (mutate artifact → exit 1 with descriptive stderr) — **partially validated**: Plan 02 step 2 reproducibly exits 1 with stderr identifying the failing step on Windows host (not by intentional mutation, but the diagnostic path is exercised).

## Deviations from Plan

### Out-of-scope upstream drift (NOT auto-fixed — flagged for downstream resolution)

**1. [Out-of-scope] protocol-doc:verify and save-format-doc:verify have one-sided CRLF normalization**

- **Found during:** Task 1 verification (running `pnpm verify:phase-3` end-to-end).
- **Issue:** `tools/protocol-doc/src/emit/index.ts` `runVerify()` reads `onDiskJson = readFileSync(protoPath, 'utf-8')` without normalizing CRLF to LF, then compares against `expectedJsonLF = expected.replace(/\r\n/g, '\n')`. On Windows hosts with `core.autocrlf=true`, the on-disk file has CRLF after checkout; the comparison fails. Same pattern in save-format-doc verify and likely the asset-catalog server-tree verify. The committed `protocol.json` also embeds `\r\n` literals in the `inputManifestSha256` JSON-string value (read from `MANIFEST.sha256` on the original committer's Windows host without normalization), making the artifact platform-specific.
- **Why not auto-fixed here:** Per executor scope rule ("only auto-fix issues DIRECTLY caused by the current task's changes"), this is pre-existing tooling drift introduced in Plans 02/03/04. Fixing it would touch three tool packages (protocol-doc, save-format-doc, asset-catalog), require regen + recommit of `protocol.json`/`save-formats.json` from a normalized canonical source, and is architecturally an upstream determinism fix — Rule 4 territory. Hit the 3-attempt fix limit while exploring `.gitattributes` + renormalize-the-extracted-tree paths; reverted those attempts to keep this plan focused.
- **Files affected (upstream):** `tools/protocol-doc/src/emit/index.ts` (line 148, 159, 173), `tools/save-format-doc/src/.../verify-equivalent`, possibly `tools/asset-catalog/src/emit.ts` line 511.
- **Resolution path:** Either (a) Linux-canonical commit pass — checkout on Linux, run `pnpm regen:server`, commit the normalized artifacts; or (b) make every verify subcommand normalize `onDiskJson.replace(/\r\n/g, '\n')` before compare AND have catalog tools normalize `manifestSha256` before embedding it in the JSON. Recommended: do (a) once on Linux to establish canonical bytes, then layer (b) defensively. Both belong in a follow-up Phase 3 maintenance plan or a Phase 4 hardening pass — flagged for `/gsd-verify-work` to decide.

**2. [Out-of-scope] First post-merge CI run not testable in this plan execution**

- **Issue:** Acceptance criteria #5 of Task 2 ("First post-merge CI run triggers") cannot be exercised inside the worktree — the workflow only runs on GitHub once this commit lands on main.
- **Resolution:** Deferred to next merge. The workflow YAML structure is statically valid (smoke test confirms `pnpm verify:phase-3` step + `paths:` filter present); GitHub Actions parser is the canonical YAML validator at trigger time.

### Auto-fix attempts that were rolled back

**3. [Reverted - Out of scope] `.gitattributes` + extracted/-tree renormalization**

- **Found during:** Task 1 end-to-end verify (steps 2-3 failing on Windows).
- **Attempted:** Added a comprehensive `.gitattributes` (`* text=auto eol=lf` + per-glob `text eol=lf` + binary attributes for `*.gmd`, `*.bnu`, etc.) and ran `git rm --cached -r extracted/ docs/ tools/db-schema/migrations/ && git checkout HEAD -- ...` to force LF on disk for previously-CRLF text files.
- **Outcome:** LF normalization on disk fixed Plan 02 step 2 on Windows but broke the determinism of Plan 02 step 2's *committed* artifact comparison: the committed `protocol.json` was emitted from a CRLF-source environment (so its `inputManifestSha256` JSON-string contains literal `\r\n`), and renormalizing the source to LF makes regen produce literal `\n`-content instead — different bytes. Fixing this properly requires recommitting all Phase 3 emitted artifacts from a Linux canonical pass (see deviation 1).
- **Why reverted:** The renormalize had a wider blast radius than this plan's scope (touched hundreds of `extracted/server-5-4/scripts/*.gml` files committed by Phase 1) and didn't actually fix the root cause. Reverted to keep the working tree clean for Plan 09's deliverables. The orchestrator and CI workflow stand on their own merits.

## Threat Model Outcomes

- **T-3-09-01 (cross-plan invariant drift):** Mitigated as designed — the gate runs every lint + verify sequentially; first non-zero fails. Already validated locally: Plan 02 verify step correctly trips fail-fast and surfaces the originating plan in stderr.
- **T-3-09-02 (CI bypass via direct push to main):** Accepted per plan — branch-protection enforcement is repo-admin-level, out of scope.
- **T-3-09-03 (incomplete CI deps install):** Mitigated — `--frozen-lockfile` on every per-tool install + `setup-node cache: pnpm`.
- **T-3-09-04 (post-verify drift slipping past):** Mitigated — final `git diff --exit-code` step in workflow asserts artifact regen is committed.

## Threat Flags

None — Plan 09 introduces no new attack surface. The CI workflow is read-only against the repo (no secrets, no external network beyond pnpm registry, no deploy step).

## Known Stubs

None.

## Files

### Created
- `scripts/verify-phase-3.mjs` — composite gate orchestrator (64 lines)
- `scripts/verify-phase-3.test.mjs` — orchestrator smoke test (65 lines)
- `.github/workflows/verify-phase-3.yml` — CI gate (70 lines)

### Modified
- `package.json` — added `verify:phase-3` + `test:verify-phase-3` scripts (2 keys, 2 lines added)

## Commits

| Commit | Message |
|--------|---------|
| `cf90b40` | feat(03-09): add scripts/verify-phase-3.mjs composite gate orchestrator [SDOC-01..06] |
| `bf8dea6` | feat(03-09): add .github/workflows/verify-phase-3.yml CI gate [SDOC-01..06] |

## Self-Check

- [x] `scripts/verify-phase-3.mjs` exists at the worktree path (`ls scripts/` confirmed)
- [x] `scripts/verify-phase-3.test.mjs` exists
- [x] `.github/workflows/verify-phase-3.yml` exists
- [x] `package.json` contains `verify:phase-3` (and `test:verify-phase-3`)
- [x] Commit `cf90b40` reachable from HEAD: `git log --oneline | grep cf90b40` → present
- [x] Commit `bf8dea6` reachable from HEAD: `git log --oneline | grep bf8dea6` → present
- [x] No modifications to STATE.md / ROADMAP.md (orchestrator-owned per executor frontmatter)

## Self-Check: PASSED