cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skills/prd-templates/references/shard-boundary-analysis.md

@@ -0,0 +1,103 @@
+# Shard Boundary Analysis
+
+Reference data for the decompose-architecture workflow — shard boundary heuristics, load thresholds, classification types, and split proposal format.
+
+## Fractal Tree Signals for Shard Boundaries
+
+| Signal | What It Means for Sharding |
+|--------|---------------------------|
+| Deep fractal tree (3+ levels) | Domain is complex enough for its own shard |
+| Many children (5+ features) | Consider splitting into multiple shards |
+| Dense CX file (5+ cross-cuts) | High coupling — keep together in one shard, or isolate carefully |
+| Rich Role Matrix (3+ roles with access) | Shard needs multi-role IA spec coverage |
+| Hub-and-spoke shared domains | Shared domains often become `00-*` cross-cutting shards |
+| Leaf features marked `[EXHAUSTED]` | Most confident for shard scoping — behavior is fully defined |
+
+## Standard Boundary Heuristics
+
+- Features that share the same data models belong together
+- Features that can be developed/deployed independently are candidates for separation
+- Features that share the same access control model may belong together
+- Cross-cutting concerns (auth, API conventions, error handling) become `00-*` shards
+
+## Shard Load Thresholds (Pre-check from Ideation)
+
+| Ideation Sub-Areas | Pre-Check Action |
+|---|---|
+| ≤6 | ✅ No concern — proceed |
+| 7–9 | ⚠️ **Pre-flag for split review** — note in the shard skeleton |
+| ≥10 | 🚩 **Proactive split proposal** — present to user NOW before calibration gate |
+
+## Sub-feature Count Thresholds (Calibration Gate)
+
+Count sub-features using the **bullet/named-item rule**: count every bullet or named item under `## Features`, excluding group headers that introduce a group but are not themselves a concrete capability. Sub-bullets count independently. Test: "Would a product manager list this as a separate line item in a release note?"
+
+| Sub-feature Count | Action |
+|-------------------|--------|
+| **≤6** | ✅ OK — proceed |
+| **7–9** | ⚠️ Flag for user review — present sub-feature list and ask: "Keep as-is, or split?" |
+| **≥10** | 🛑 **Hard stop** — present mandatory split proposal. No shard may exit with ≥10 sub-features. |
+
+## Shard Document Type Classification
+
+| Classification | Expected BE Specs |
+|---------------|-------------------|
+| **Feature domain** | 1 |
+| **Multi-domain** | N (split along sub-feature boundaries) |
+| **Cross-cutting** | 1 (`00-*`) |
+| **Structural reference** | 0 |
+
+Annotation format for shard skeletons:
+```markdown
+> **Document Type** (preliminary): Feature domain | Multi-domain | Cross-cutting | Structural reference
+```
+
+## Split Proposal Format
+
+When a shard exceeds the ≥10 threshold:
+
+```
+Shard [NN] — [domain name] has [N] sub-features (threshold: ≥10 → mandatory split)
+
+Current sub-features:
+  1. [sub-feature]
+  2. [sub-feature]
+  ...
+
+Proposed split:
+  [NN]a — [new domain name] → file: .memory/wiki/specs/ia/[NN]a-[domain].md
+    Sub-features: 1, 3, 5
+  [NN]b — [new domain name] → file: .memory/wiki/specs/ia/[NN]b-[domain].md
+    Sub-features: 2, 4, 6
+
+Split rationale: [why these groups are independent]
+```
+
+**After any split**: Update `.memory/wiki/specs/ia/decomposition-plan.md` with the revised table, re-run the Must Have coverage gate, **then run `/remediate-shard-split` to update all downstream cross-references. Do NOT proceed until zero stale parent references remain.** See `.codex/skills/prd-templates/references/shard-split-remediation.md` for scan patterns and matching heuristics.
+
+**Companion spec tracking**: When writing BE or FE specs for split shards, populate the `## Split Group` section in each spec file (see `be-spec-template.md` / `fe-spec-template.md`). This enables downstream discovery of sibling specs during implementation.
+
+## Total Shard Count Guidance
+
+The decomposition should produce a shard count proportional to the ideation depth. Too few shards compress complex domains and lose detail. Too many create coordination overhead that exceeds agent context capacity.
+
+### Expected Range by Ideation Scale
+
+| Ideation Scale | Domains | Expected Shards (incl. `00-infrastructure`) | Notes |
+|----------------|---------|---------------------------------------------|-------|
+| **Small** | 3–5 | 4–8 | Most domains map 1:1 to shards |
+| **Medium** | 6–8 | 7–14 | Some multi-domain splits expected |
+| **Large** | 9–12 | 12–20 | Cross-cutting shards multiply; enforce sub-feature limits aggressively |
+| **Deep** | 13+ | 16–25 | Maximum recommended. Beyond 25 → consider surface-level decomposition or domain grouping |
+
+### Total Count Thresholds (Post-Skeleton Check)
+
+After all shard skeletons are created in Step 5, count the total:
+
+| Total Shards | Action |
+|--------------|--------|
+| **≤ 20** | ✅ Proceed |
+| **21–25** | ⚠️ Warning — "Decomposition produced [N] shards. This will require [N × 3] spec documents (IA + BE + FE) and proportional phase planning. Confirm this is the intended scope or consider grouping related domains." |
+| **> 25** | 🛑 **Hard stop** — "Decomposition produced [N] shards. This exceeds the recommended maximum for sequential agent processing. Present a domain grouping proposal that reduces shard count to ≤ 25." |
+
+> **Why 25 max**: Each shard produces ~3 spec documents (IA + BE + FE). At 25 shards, that's 75 spec documents. Beyond this, cross-layer consistency checks become unreliable and phase planning produces impractical slice counts.

package/template/.codex/skills/prd-templates/references/shard-split-remediation.md

@@ -0,0 +1,157 @@
+# Shard Split Remediation Reference
+
+Templates, formats, and scan patterns for `/remediate-shard-split` workflow.
+
+## Sub-Shard Mapping Table Format
+
+```markdown
+| Parent | Sub-Shard | Domain Name | Keywords |
+|--------|-----------|-------------|----------|
+| 00 | 00a | Consumer Identity | auth, identity, login, registration, session, token, OAuth, password |
+| 00 | 00b | AI Gateway | AI, gateway, LLM, model, inference, prompt, embedding, agent |
+| 00 | 00c | File Storage | file, storage, upload, media, blob, asset, image, document |
+| 00 | 00d | Taxonomy | taxonomy, category, classification, tag, hierarchy, label |
+```
+
+### Keyword Extraction Rules
+
+1. Read each sub-shard's `## Features` section
+2. Extract nouns and domain terms from each feature bullet
+3. Include the sub-shard's domain name words as keywords
+4. Include obvious synonyms (e.g., "auth" → also "authentication", "login", "session")
+5. Aim for 5–10 keywords per sub-shard — enough for matching, not so many they overlap
+
+## Cross-Reference Scan Patterns
+
+Grep the entire `.memory/wiki/specs/` tree for the parent shard number using these patterns. The `NN` below represents the parent number (e.g., `00`, `01`, `02`).
+
+### Primary Patterns (always scan)
+
+| Pattern | Matches |
+|---------|---------|
+| `Depends on:.*NN` | Depends-on header lines |
+| `Consumed by:.*NN` | Consumed-by header lines |
+| `\| *NN *\|` | Dependency table cells containing the shard number |
+| `NN — ` or `NN —` | Shard references with em-dash (e.g., "00 — Infrastructure") |
+| `NN - ` or `NN -` | Shard references with hyphen |
+| `(NN` followed by space or `)` | Parenthetical shard references |
+| `shard NN` (case-insensitive) | Inline text references |
+| `NN-[a-z]*.md` parent filename refs | Links to the parent file (e.g., `00-infrastructure.md`) |
+
+### Scope
+
+| Directory | Required |
+|-----------|----------|
+| `.memory/wiki/specs/ia/` | Always |
+| `.memory/wiki/specs/be/` | If exists |
+| `.memory/wiki/specs/fe/` | If exists |
+| `.memory/wiki/specs/be/web/` | If exists |
+| `.memory/wiki/specs/fe/web/` | If exists |
+| `.memory/wiki/specs/be/desktop/` | If exists |
+| `.memory/wiki/specs/fe/desktop/` | If exists |
+| `.memory/wiki/specs/be/mobile/` | If exists |
+| `.memory/wiki/specs/fe/mobile/` | If exists |
+
+### Exclusions
+
+- The parent stub file itself (already marked SPLIT)
+- `.memory/wiki/specs/audits/` (audit records, not active specs)
+- `.memory/wiki/specs/ideation/` (upstream of decomposition — doesn't use shard numbers)
+
+## Context Matching Heuristics
+
+When a stale reference includes a parenthetical description, match it against sub-shard keywords:
+
+### Matching Algorithm
+
+1. **Exact keyword match**: If the parenthetical contains a word that appears in exactly one sub-shard's keyword list → **clear match**
+2. **Strongest keyword match**: If the parenthetical contains words that appear in multiple sub-shards' keyword lists, pick the sub-shard with the most keyword hits → **clear match** if gap ≥ 2 hits, **ambiguous** otherwise
+3. **Contextual read**: If keyword matching is inconclusive, read the surrounding 5 lines in the downstream file for additional context clues (e.g., what feature is being described in that section)
+4. **No match**: If the parenthetical is generic (e.g., just "Infrastructure" with no specifics) → **flag for user resolution**
+
+### Multiple Dependency Detection
+
+A downstream shard may legitimately depend on more than one sub-shard. Detect this when:
+
+- The `Depends on:` section lists the parent *and* the downstream shard's features span multiple sub-shard domains
+- The downstream shard's data model references entities owned by different sub-shards
+
+In this case, propose expanding the single reference into multiple references:
+```
+Before: Depends on: 00 (Infrastructure)
+After:  Depends on: 00a (Consumer Identity), 00c (File Storage)
+```
+
+## Remediation Display Format
+
+### Clear Match
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Reference N of X
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Document: [path]
+Line:     [line number]
+Current:  [current text with stale reference]
+Context:  [extracted context clue]
+Maps to:  [proposed sub-shard] — [confidence: clear]
+Fix to:   [proposed replacement text]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[Y] Apply fix and move to next
+[n] Skip this item
+[e] Edit — provide custom replacement
+[skip] Skip entire document
+[stop-and-save] Save progress and stop
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Ambiguous Match
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Reference N of X — AMBIGUOUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Document: [path]
+Line:     [line number]
+Current:  [current text with stale reference]
+Context:  [extracted context clue]
+Candidates:
+  [1] [sub-shard] — [domain] (keyword match: "[matched words]")
+  [2] [sub-shard] — [domain] (keyword match: "[matched words]")
+  [M] Multiple — expand to: [sub-shard1], [sub-shard2]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Which sub-shard? [1/2/M/skip/stop-and-save]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Remediation Record Template
+
+```markdown
+# Shard Split Remediation — [Parent NN] → [Sub-shards]
+
+**Date**: [YYYY-MM-DD]
+**Parent shard**: [NN] — [domain name]
+**Sub-shards**: [list with domain names]
+
+## Mapping Table Used
+
+[copy of the confirmed mapping table]
+
+## Changes Applied
+
+| # | Document | Line | Before | After | Confidence |
+|---|----------|------|--------|-------|------------|
+| 1 | [path] | [N] | [old text] | [new text] | clear/user-resolved |
+
+## Skipped References
+
+| # | Document | Line | Text | Reason |
+|---|----------|------|------|--------|
+| 1 | [path] | [N] | [text] | [reason] |
+
+## Verification
+
+- **Final grep result**: 0 stale references remaining ✅
+- **Documents scanned**: [N]
+- **Documents modified**: [N]
+```

package/template/.codex/skills/prd-templates/references/skill-loading-protocol.md

@@ -0,0 +1,36 @@
+# Skill Loading Protocol
+
+Standard procedure for loading skills from the surface stack map before beginning spec or implementation work.
+
+## How to Load Skills from the Surface Stack Map
+
+1. **Determine the surface**: Identify which surface this work belongs to from the directory path or phase plan (e.g., `.memory/wiki/specs/be/web/` → surface `web`; flat `.memory/wiki/specs/be/` → surface `shared`).
+
+2. **Read the surface stack map**: Open `.codex/instructions/tech-stack.md` and locate this surface's row.
+
+3. **For each skill category** relevant to your workflow (Languages, Databases, BE Frameworks, FE Frameworks, FE Design, ORMs, Auth, Unit Tests, E2E Tests, State Mgmt, Accessibility, CI/CD, Hosting, Security):
+   - Read the skill name(s) listed in that cell
+   - For each skill directory name, read `.codex/skills/[skill]/SKILL.md`
+   - Follow its conventions (language, testing, framework, design, etc.)
+
+4. **Cross-cutting skills**: Some categories (Auth, Security, CI/CD, Hosting, Accessibility) are in the cross-cutting section — not per-surface. Read those from the cross-cutting rows.
+
+5. **Missing skill fallback**: If any skill in the bundle is not installed in `.codex/skills/` and is not in `.codex/skill-library/MANIFEST.md`, read `.codex/skills/find-skills/SKILL.md` and follow its discovery methodology to search for a community equivalent before proceeding without it.
+
+## Which Categories to Load Per Workflow
+
+| Workflow | Required Categories |
+|----------|-------------------|
+| `write-be-spec-classify` | Languages, Databases, Auth, BE Frameworks, ORMs, Unit Tests |
+| `write-fe-spec-classify` | Languages, FE Frameworks, FE Design, Accessibility, State Mgmt |
+| `write-architecture-spec-design` | Databases, Security, API Design |
+| `setup-workspace-scaffold` | Languages, BE Frameworks, FE Frameworks |
+| `setup-workspace-cicd` | CI/CD, Languages |
+| `setup-workspace-hosting` | Hosting, CI/CD |
+| `setup-workspace-data` | Databases, ORMs |
+| `implement-slice-tdd` | Languages, Unit Tests, E2E Tests |
+| `validate-phase` | Unit Tests, E2E Tests, CI/CD, Hosting, Accessibility, Security |
+
+## Surface Stack Map Verification
+
+Before loading, verify the required cells have filled values. If any required cell is empty → **HARD STOP**: tell the user to run `/create-prd` first to make tech stack decisions.

package/template/.codex/skills/prd-templates/references/slice-completion-gates.md

@@ -0,0 +1,29 @@
+# Slice Completion Gates
+
+Checklists that must pass before a slice can be marked complete. Every unchecked item is a hard stop.
+
+## UI Completeness Check (FE slices only)
+
+- [ ] Every acceptance criterion mentioning "user sees", "user can", "displays", or "shows" has a rendered implementation — not just a passing test
+- [ ] Every new route in this slice is wired into the app's navigation (not just exported as a component)
+- [ ] Loading, error, and empty states are rendered in the UI — not just covered by tests
+- [ ] The feature is reachable from the app's entry point via normal user navigation
+
+Non-FE slices skip this block.
+
+## Spec Traceability Gate (all slices)
+
+- [ ] Re-read the BE spec section(s) for every endpoint in this slice — every response field, error code, and validation rule has a corresponding test tagged with the spec reference
+- [ ] Re-read the IA shard's `## Edge Cases` section for this slice's domain — every edge case relevant to this slice has a `// IA-EDGE:` tagged test
+- [ ] No `// DECISION:` annotations exist for behaviors that are actually specified in the BE spec or IA shard (i.e., no spec-defined behavior was treated as an undocumented implementation decision)
+- [ ] The {{CONTRACT_LIBRARY}} contract written in Step 2 matches the delivered implementation field-for-field — no fields added, removed, or renamed during implementation without a corresponding contract update
+
+## Resource Cleanup Gate (all slices)
+
+- [ ] Every database client or connection created in this slice has a corresponding cleanup call (`disconnect`, `close`, `end`, `dispose`) in a `finally` block or lifecycle hook
+- [ ] Every event listener or subscription registered in UI components has a corresponding cleanup in the component's unmount/destroy lifecycle
+- [ ] Every `setInterval` or `setTimeout` with a stored reference has a corresponding `clearInterval`/`clearTimeout` on cleanup
+- [ ] No file handles or streams are opened without corresponding `close`/`destroy` calls
+- [ ] If using connection pools — pool size is configured (not left at framework default) and documented via code comment: `// POOL: max=N, reason=...`
+
+> ❌ STOP — Do not call `notify_user` if any of the above are unchecked. Fix the gap and re-run the Test Cmd from the surface stack map.

package/template/.codex/skills/prd-templates/references/spec-coverage-sweep.md

@@ -0,0 +1,44 @@
+# Spec Coverage Sweep
+
+Verifies that a phase's implementation delivered what the specs required — not just that tests pass.
+
+## Procedure
+
+For each slice in the phase plan (`.memory/wiki/specs/phases/phase-N.md`):
+
+### FE Spec Coverage
+
+1. Read the slice's acceptance criteria
+2. Identify the FE spec(s) referenced by this slice (via the FE spec's `## Source Map`)
+3. For each named user flow in the relevant FE spec `## Interaction Specification` section that belongs to this slice:
+   - Verify a test exists in the test suite that covers this flow by name or by its acceptance criterion
+   - Verify the flow is implemented (not stubbed with `BOUNDARY:`) unless a valid boundary stub exists with a tracking issue
+
+### BE Spec Coverage
+
+4. Identify the BE spec section(s) for each endpoint in this slice
+5. For each endpoint:
+   - Verify every {{CONTRACT_LIBRARY}}-validated field in the BE spec has a corresponding test
+   - Verify every error code defined in the BE spec has a corresponding test that asserts the **full error response shape** (status + error code + message), not just the HTTP status
+   - Verify every auth rule (role, ownership check) defined in the BE spec has a corresponding permission test
+
+### IA Shard Coverage
+
+6. For each slice, identify which IA shard(s) the slice's features originate from (using either the phase plan's domain references or the FE spec's `## Source Map`). For each identified IA shard:
+   - Read the shard's `## Accessibility` section (surface-conditional: apply only for `web`, `mobile`, or `desktop` surfaces). For each accessibility requirement, verify a corresponding test exists (e.g., axe-core check, keyboard navigation test, screen reader label test).
+   - Read the shard's acceptance criteria or testability section (look for Given/When/Then format or numbered acceptance criteria). For each criterion, verify it maps to at least one named test in the test suite.
+   - Flag any IA criterion with no test coverage as an uncovered item — apply the hard-stop rule below.
+
+## Hard Stop Rule
+
+If any flow, field, error code, auth rule, IA acceptance criterion, or accessibility requirement has no corresponding test:
+
+> ❌ STOP — Do not mark this phase as complete. List the uncovered items. Either write the missing tests and re-run the Test Cmd from `.codex/instructions/commands.md`, or if the item was genuinely deferred (valid boundary stub + tracking issue), document the deferral explicitly in the phase validation report.
+
+## Pass Criteria
+
+Every named user flow, BE endpoint field, error code, auth rule, IA acceptance criterion, and accessibility requirement in the phase's scope has a corresponding passing test or a documented valid boundary stub.
+
+## Report Section
+
+Update report (`.memory/wiki/specs/audits/phase-N-validation.md`): Add a `## Spec Coverage` section listing the sweep results — covered items, uncovered items, boundary stubs, accessibility coverage, IA testability trace results, and the pass/fail verdict.

package/template/.codex/skills/prd-templates/references/surface-model.md

@@ -0,0 +1,61 @@
+# Surface Model Reference
+
+This document defines two distinct models used throughout the kit. Understanding the distinction prevents confusion between surface types (what kind of thing you're building) and implementation layers (what a complete feature requires).
+
+---
+
+## Surface Type Model
+
+Used by: stack decisions, bootstrap key `SURFACES`, decomposition, `/plan-phase` Step 0.5
+
+The surface type describes the *kind of deployment target* for the project.
+
+| Surface Type | Description | Examples |
+|---|---|---|
+| `web` | Browser-based application | SaaS dashboard, marketing site, web app |
+| `mobile` | Native or hybrid mobile app | iOS/Android app, React Native, Expo |
+| `desktop` | Native desktop application | Electron, Tauri, native macOS/Windows |
+| `cli` | Command-line interface | Developer tool, automation script, npm package |
+| `api` | Headless API without a user-facing interface | REST API, GraphQL service, microservice |
+| `extension` | Browser extension or plugin | Chrome extension, VS Code plugin |
+
+---
+
+## Implementation Layer Model
+
+Used by: `vertical-slices.md` completeness rule, phase planning, slice acceptance criteria
+
+The implementation layer describes *what a complete vertical feature slice requires* — regardless of surface type.
+
+| Layer | What It Is | Required For |
+|---|---|---|
+| **Data layer** | Schema, migrations, seed data, storage config | Every feature that persists state |
+| **API layer** | Endpoints, validation, middleware, business logic | Every feature with server-side behavior |
+| **User-facing layer** | The interface for the primary user of this feature | Every feature (form adapts to surface type) |
+| **Admin layer** | Management interface for operators or privileged users | Every feature that needs operator control |
+
+---
+
+## Reconciliation: Layers Are Always Present, Form Adapts
+
+Every surface type has all four implementation layers — but the *form* of each layer adapts to the surface type.
+
+| Surface Type | Data Layer | API Layer | User-Facing Layer | Admin Layer |
+|---|---|---|---|---|
+| `web` | DB schema + migrations | REST/GraphQL/tRPC endpoints | Browser UI (pages, components) | Admin dashboard or management UI |
+| `mobile` | Local storage + remote sync | Mobile API endpoints | Native screens | Admin API or web admin |
+| `desktop` | Local DB or file system | Internal IPC or local server | Native window UI | Settings/configuration panel |
+| `cli` | Config files, local state | Internal command router | Command output, prompts, `--help` | Privileged commands, admin mode |
+| `api` | DB schema | API endpoints | Response format (the interface for API consumers) | Admin endpoints or management API |
+| `extension` | Extension storage | Background service worker | Popup or sidebar UI | Extension settings page |
+
+**Key insight**: A CLI project has no "admin panel" in the web sense — but it has privileged commands and a management mode that fulfill the admin layer role. The layers are never absent; they just look different.
+
+---
+
+## Related Rules and Workflows
+
+- `vertical-slices.md` — uses the Implementation Layer Model to define feature completeness
+- `/plan-phase` Step 0.5 — uses the Surface Type Model to condition completeness checks
+- `bootstrap-agents-fill.md` — fills `{{SURFACES}}` with confirmed Surface Type values
+- `decompose-architecture.md` — uses surface types to determine which skills to load

package/template/.codex/skills/prd-templates/references/tdd-testing-policy.md

@@ -0,0 +1,39 @@
+# TDD Testing Policy
+
+## Assertion Depth Rule
+
+Every test must assert **at minimum**:
+- Response status code AND response body structure (not just status)
+- At least one specific field value from the response body
+- For error paths: the full error shape (code + message), not just the status code
+- Contract tests must assert both valid input accepted AND invalid input rejected with the correct error shape
+
+Tests that only assert `status == 200` without checking the response body are **insufficient** and will be flagged during QA anti-cheat audit.
+
+## Anti-Mock-Abuse Rules
+
+| Test Type | Mocking Policy |
+|-----------|---------------|
+| **Unit tests** | Mocking external dependencies allowed and expected |
+| **Integration tests** | At least one test per endpoint must hit a real test database — no mocked DB responses |
+| **E2E tests** | No mocks allowed — full stack or it doesn't count |
+
+**Banned patterns**:
+- Mocking the module under test (testing a mock of what you're building)
+- Mock chains (mocking a mock that mocks another dependency)
+- Tests where the mock returns exactly the expected value (circular, proves nothing)
+
+**Test order**: Unit → Integration → E2E (if applicable)
+
+## QA Anti-Cheat Audit
+
+Before marking tests as passing, verify:
+
+- [ ] No tests with zero assertions
+- [ ] No tautological tests (e.g., `expect(true).toBe(true)`, `expect(mock).toEqual(mock)`)
+- [ ] No `test.skip` without a `BOUNDARY:` reference and tracking issue
+- [ ] Every test that asserts a response also asserts the response body, not just the status code
+- [ ] No tests that mock the thing they're supposed to test (e.g., mocking the handler to test the handler)
+- [ ] Error path tests actually trigger the error condition — they don't just mock the error response
+
+In sequential mode, the agent self-audits against this checklist. In parallel mode, the QA-GREEN agent runs this explicitly.

package/template/.codex/skills/prd-templates/references/vision-template.md

@@ -0,0 +1,57 @@
+# Vision Document Template
+
+Use this template when compiling `.memory/wiki/specs/vision.md` as the human-readable executive summary.
+
+> **Important**: `vision.md` is a summary document for human consumption. The pipeline reads
+> `.memory/wiki/specs/ideation/ideation-index.md` directly — not this file. All the depth, domain
+> files, CX files, and structured data live in the `ideation/` folder's fractal tree.
+
+```markdown
+# [Project Name] — Vision
+
+> One-sentence pitch: [from Step 4]
+
+> **This is a human-readable project summary.** For pipeline-grade detail, see
+> [ideation-index.md](ideation/ideation-index.md) and the fractal domain tree it references.
+
+## Problem Statement
+[Condensed from `meta/problem-statement.md`]
+
+## Target Users
+[Condensed persona summaries from `meta/personas.md` — name + role + pain point + success criteria.
+Not the full 6-field exploration — that detail stays in the personas file.]
+
+## Solution Overview
+[2-3 paragraphs describing what the product does and why it matters.]
+
+## Domain Map
+[One paragraph per domain, condensed from the ideation domain folders (paths in `ideation-index.md` Structure Map).
+Each domain links to its folder's index file.]
+
+## Feature Inventory (MoSCoW)
+### Must Have (Phase 1)
+[Feature names + one-line description. Links to domain folder index files for drill-down detail.]
+### Should Have (Phase 2)
+[Feature names + one-line description.]
+### Could Have (Phase 3+)
+### Won't Have (explicitly excluded)
+
+## Key Cross-Cutting Interactions
+[Top confirmed interactions from `ideation-cx.md` (global) and domain-level `*-cx.md` files.
+Full synthesis detail stays in the CX files.]
+
+## Constraints Summary
+[Condensed from `meta/constraints.md` — budget, timeline, team, compliance, performance, surfaces.]
+
+## Success Metrics
+[Key metrics with concrete targets. Full details in relevant domain folder feature files.]
+
+## Competitive Landscape
+[Condensed from `meta/competitive-landscape.md` — competitors, differentiation, moat.]
+
+## Key Decisions
+[Numbered list of major product decisions made during ideation.]
+
+## Open Questions
+[Anything unresolved that needs answers before architecture — with owners and target stages.]
+```

package/template/.codex/skills/prd-templates/references/workflow-checkpoint-protocol.md

@@ -0,0 +1,112 @@
+# Workflow Checkpoint Protocol
+
+> Survive context truncation. When process memory is lost, this file tells the next context exactly where you are and what to do next.
+
+## When to use
+
+Every `/create-prd` shard workflow writes and reads this checkpoint. It lives at `.memory/wiki/specs/architecture/prd-working/workflow-state.md`.
+
+## Checkpoint file format
+
+The checkpoint is a markdown file with YAML-style key-value pairs. Agents must parse it on shard start and update it at every write trigger.
+
+```markdown
+# Workflow Checkpoint
+
+active_shard: .codex/skills/create-prd-stack/SKILL.md
+current_step: per-axis-flow
+current_item: Frontend Framework (STK-04)
+items_completed: [Hosting (STK-01), Database (STK-02), Auth (STK-03)]
+next_action: Read ideation files for Frontend Framework axis, write synthesis
+pending_reads:
+  - .memory/wiki/specs/ideation/domains/dashboard/dashboard-deep-dive.md
+  - .memory/wiki/specs/ideation/domains/diagnostics/diagnostics-deep-dive.md
+  - .memory/wiki/specs/ideation/ideation-cx.md
+synthesis_written: false
+last_user_output: Confirmed Auth Provider as Supabase Auth (STK-03)
+```
+
+### Field definitions
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `active_shard` | filepath | Which workflow file to `view_file` to recover process |
+| `current_step` | string | Step identifier within the shard |
+| `current_item` | string | Axis name, decision name, or section being worked on |
+| `items_completed` | list | Already-completed items (decisions, sections, axes) |
+| `next_action` | string | Exact next thing the agent should do |
+| `pending_reads` | list | Files that MUST be read before next user-facing output |
+| `synthesis_written` | bool | Whether synthesis was written for current item |
+| `last_user_output` | string | Summary of last thing shown to the user |
+
+## Write triggers
+
+Update the checkpoint file at these moments:
+
+1. **Shard start** — initialize with shard filepath, first step, empty completed list
+2. **After reading ideation files** — update `pending_reads` to empty, note files were read
+3. **After writing synthesis** — set `synthesis_written: true`
+4. **After each item completion** — move item to `items_completed`, set next item, reset `synthesis_written: false`, populate `pending_reads` for next item from the Ideation Relevance Index
+5. **Before user-facing output** — update `last_user_output` with summary of what was presented
+6. **Shard completion** — update `current_step: complete`, `next_action: proceed to [next shard]`
+
+## Read triggers — Resumption
+
+At the start of every shard, check if `.memory/wiki/specs/architecture/prd-working/workflow-state.md` exists.
+
+### If it exists and `active_shard` matches this shard:
+
+1. **Re-read the shard workflow**: `view_file` the path in `active_shard` — recover the full process
+2. **Load completed items**: Skip already-completed axes/decisions
+3. **Check `synthesis_written`**: If `false` → the agent was interrupted before writing synthesis. Read `pending_reads` files and write synthesis before doing anything else
+4. **Resume from `next_action`**: Execute exactly what the checkpoint says
+
+### If it exists and `active_shard` is a DIFFERENT shard:
+
+The previous shard finished or a different shard is running. Check `current_step`:
+- If `complete` → previous shard finished cleanly. Initialize fresh checkpoint for this shard
+- If not `complete` → previous shard was interrupted. **STOP**: "Previous shard `{active_shard}` was interrupted at `{current_item}`. Resume that shard first or confirm skip."
+
+### If it does not exist:
+
+Fresh start. Initialize the checkpoint.
+
+## Synthesis verification gate (HARD)
+
+> This gate enforces `source-before-ask`. It is not optional.
+
+**Before presenting ANY Tier 2 question, option table, or recommendation to the user:**
+
+1. Read the checkpoint file
+2. Check `synthesis_written` for the current item
+3. If `synthesis_written: false` → **STOP**. Do not present anything to the user. Read the files in `pending_reads`, write the synthesis to the appropriate synthesis file, update `synthesis_written: true` in the checkpoint, THEN proceed
+4. If `synthesis_written: true` → proceed with user-facing output
+
+This gate catches the exact failure mode: context truncation drops the synthesis step, the agent pattern-matches "STK-04 is next" from the summary, and jumps straight to asking the user generic questions.
+
+## Shard-specific checkpoint patterns
+
+### create-prd-stack
+
+- `current_item` format: `{Axis Name} (STK-{NN})`
+- `items_completed` tracks each axis
+- `pending_reads` populated from Ideation Relevance Index per-axis
+- Checkpoint updated at per-axis flow step 9 (move to next axis)
+
+### create-prd-design-system
+
+- `current_item` format: `{Decision Name} (DS-{NN})`
+- 7 decisions tracked: Navigation Paradigm, Layout Grid, Page Archetypes, Component Hierarchy, Motion System, Data Density, State Design Language
+- `pending_reads` populated from heavy domain files
+
+### create-prd-architecture / security / compile
+
+- `current_item` format: `{Section Name}`
+- Tracks major sections (e.g., "System Components", "Data Strategy", "Security Model")
+- `pending_reads` populated from relevant ideation domains per section
+
+## Cleanup
+
+The parent orchestrator (`create-prd.md`) deletes or archives the checkpoint file after Step E (quality gate) passes. The file is a process artifact — once the PRD is compiled, it has no further value.
+
+The synthesis files in `prd-working/` are kept as audit trail.