cfsa-antigravity 2.19.0 → 2.19.2

package/template/.claude/skills/prd-templates/references/operational-templates.md

@@ -0,0 +1,116 @@
+# Operational Templates
+
+Templates for operational artifacts produced during planning, assessment, and provisioning workflows.
+
+---
+
+## Slice Acceptance Criteria
+
+Use when writing slice entries during `/plan-phase` Step 4:
+
+```markdown
+### Slice N: [Name]
+**Size**: S/M/L
+**Surfaces**: Contract, API, DB, UI
+
+#### Tasks
+- [ ] Contract: {{CONTRACT_LIBRARY}} schema for [entity] ← no tag (orchestrator handles sequentially)
+- [ ] `BE` API endpoints for [entity] ← backend agent
+- [ ] `FE` [entity] page and components ← frontend agent
+- [ ] `QA` Integration tests for [entity] ← QA agent (runs FIRST to write failing tests, AND after BE+FE to verify)
+
+#### Acceptance Criteria
+- [ ] Given [context], when [action], then [result]
+- [ ] Given [context], when [error condition], then [error response]
+- [ ] [Performance/security criteria if applicable]
+
+#### Dependencies
+- Requires: Slice M
+- Enables: Slice P
+```
+
+---
+
+## Remediation State
+
+Use when writing `docs/audits/remediation-state.md` during `/remediate-pipeline-assess`:
+
+```markdown
+# Remediation State
+
+> Generated: [ISO 8601 date]
+
+## Layer Status
+
+- vision: [confirmed-clean | unverified-clean | needs-audit | no-content]
+- architecture: [confirmed-clean | unverified-clean | needs-audit | no-content]
+- ia: [confirmed-clean | unverified-clean | needs-audit | no-content]
+- be: [confirmed-clean | unverified-clean | needs-audit | no-content]
+- fe: [confirmed-clean | unverified-clean | needs-audit | no-content]
+
+## Current Layer
+
+[layer — the layer to process next]
+
+## Layers Confirmed Clean This Session
+
+(none yet)
+
+## Notes
+
+[Any relevant context]
+```
+
+---
+
+## Installed Skills List
+
+Use when updating `{{INSTALLED_SKILLS}}` during `/bootstrap-agents-provision` Step 8:
+
+```markdown
+### Default Skills
+- fix-bug — TDD bug fix workflow
+- refactor — Safe refactoring with test verification
+- add-feature — Add feature to existing architecture
+- deploy — Full deployment pipeline
+- pr-review — Structured PR review
+- security-audit — Security review across all layers
+- main-workflow — General development workflow
+- iterate-plan — Tech stack gap analysis
+- setup-session — Session initialization
+- using-git-worktrees — Isolated workspace management
+- github-workflow-automation — GitHub CI/CD patterns
+- audit-context-building — Deep code analysis
+- context7-auto-research — Auto documentation lookup
+- self-improving-agent — Learning from experiences
+
+### Stack Skills
+- [skill-name] — [description] (installed for [STACK_KEY]=[value])
+- ...
+
+### Surface Skills
+- [skill-name] — [description] (installed for [surface] surface)
+- ...
+```
+
+---
+
+## Sync Integration Inventory
+
+Use when building the integration inventory during `/sync-kit` Step 5a:
+
+```markdown
+## New Kit Content Since Last Sync
+
+### New Rules
+- [list new rules, e.g. boundary-not-placeholder]
+
+### New Skills
+- [list new skills, e.g. parallel-agents, parallel-debugging]
+
+### Changed Rules/Instructions
+- [list what changed, e.g. tdd-always now references BOUNDARY stubs]
+
+### New Concepts
+- [list new concepts, e.g. boundary stubs, file ownership, synthesis protocol]
+```

package/template/.claude/skills/prd-templates/references/persona-completeness-gate.md

@@ -0,0 +1,20 @@
+# Persona Completeness Gate
+
+Applies to every persona in `meta/personas.md` during ideation.
+
+## Required Fields (6)
+
+Every persona must have all 6 fields populated before proceeding past persona exploration:
+
+1. **Name + specific role** — not generic ("Shop Owner" not "User")
+2. **Specific pain point** — the problem this product solves for them
+3. **Current workaround** — how they solve it today without this product
+4. **Success criteria** — what "solved" looks like for them (measurable)
+5. **Switching trigger** — what event would make them adopt this product
+6. **Edge case or constraint** — at least one thing unique to this persona (regulatory, workflow, scale)
+
+## Enforcement
+
+If any field is absent for any persona → probe the user before proceeding.
+
+Reference: `.agent/skills/pipeline-rubrics/references/ideation-rubric.md` Dimension 2.

package/template/.claude/skills/prd-templates/references/placeholder-guard-template.md

@@ -0,0 +1,21 @@
+# Placeholder Guard — Hard Stop Template
+
+Use this template in any workflow `## 0. Placeholder guard` step to emit a hard stop when required placeholders are unfilled.
+
+## Hard Stop Message Format
+
+Emit one block per unfilled placeholder:
+
+> ❌ **Bootstrap incomplete — cannot proceed.**
+>
+> **Unfilled placeholder:** `{{PLACEHOLDER_NAME}}`
+>
+> **Recovery:** If `docs/plans/*-architecture-design.md` exists, read it and extract the confirmed [tech decision] value, then run `/bootstrap-agents` with `KEY=<confirmed-value>`. If no architecture design document exists, run `/create-prd-stack` first to confirm tech stack decisions.
+>
+> **Why this matters:** [specific step] cannot produce correct output without this skill — [concrete consequence of proceeding without it].
+
+## Guard Procedure
+
+1. For each placeholder listed in the workflow's `requires_placeholders` frontmatter, check whether the literal characters `{{` still appear in the value.
+2. If **any** are unfilled, emit the hard stop message above (one block per unfilled placeholder) and **do not proceed** to the next step.
+3. Only proceed when **all** required placeholders report no literal `{{` characters.

package/template/.claude/skills/prd-templates/references/placeholder-workflow-mapping.md

@@ -0,0 +1,50 @@
+# Map Column Reference
+
+Maps surface stack map columns and cross-cutting categories to the workflows that consume them.
+
+> **How workflows use the map**: See `.agent/instructions/tech-stack.md` for the surface stack map format and resolution rules. Workflows determine their surface context (from shard directory or slice surface tag), then look up the corresponding row and column.
+
+## Per-Surface Columns
+
+| Column | Workflows That Consume It |
+|--------|--------------------------|
+| **Languages** | write-be-spec-classify, write-fe-spec-classify, implement-slice-setup, implement-slice-tdd, evolve-contract |
+| **BE Frameworks** | write-be-spec-classify |
+| **FE Frameworks** | write-fe-spec-classify |
+| **FE Design** | write-fe-spec-classify |
+| **ORMs** | create-prd-architecture, write-be-spec-classify, implement-slice-setup, verify-infrastructure, validate-phase |
+| **State Mgmt** | write-fe-spec-classify, implement-slice-setup |
+| **Databases** | create-prd-architecture, write-architecture-spec-design, write-be-spec-classify |
+| **Unit Tests** | create-prd-compile, write-be-spec-classify, implement-slice-setup, implement-slice-tdd, evolve-contract |
+| **E2E Tests** | create-prd-compile, implement-slice-tdd, validate-phase |
+| **Test Cmd** | implement-slice-tdd, validate-phase, evolve-contract |
+| **Validation Cmd** | implement-slice-tdd, validate-phase, evolve-contract |
+| **Lint Cmd** | validate-phase |
+| **Build Cmd** | validate-phase |
+| **Dev Cmd** | verify-infrastructure |
+| **Package Mgr** | bootstrap-agents-fill |
+
+## Cross-Cutting Categories
+
+| Category | Workflows That Consume It |
+|----------|--------------------------|
+| **Auth** | create-prd-security, write-be-spec-classify |
+| **CI/CD** | create-prd-compile, decompose-architecture-structure, plan-phase-write, verify-infrastructure, validate-phase |
+| **Hosting** | create-prd-architecture, decompose-architecture-structure, plan-phase-write, verify-infrastructure, validate-phase |
+| **Security** | create-prd-security, write-architecture-spec-design, validate-phase |
+| **API Design** | create-prd-architecture, write-architecture-spec-design, write-be-spec-classify |
+| **Accessibility** | write-fe-spec-classify, write-fe-spec-write, write-architecture-spec-design, validate-phase |
+| **Contract Library** | tdd-contract-first rule, implement-slice-setup |
+
+## Surface Context Resolution
+
+How each workflow determines which surface's row to read:
+
+| Workflow Type | Resolution Method |
+|--------------|-------------------|
+| Spec-writing (`write-be-spec`, `write-fe-spec`) | Shard directory path: `docs/plans/be/desktop/` → surface `desktop`; flat `docs/plans/be/` → surface `shared` |
+| Implementation (`implement-slice`) | Slice's `surface:` tag from the phase plan |
+| Planning (`plan-phase`) | Iterates ALL surfaces in the map |
+| Validation (`validate-phase`) | Runs per-surface commands for all surfaces |
+| Cross-cutting (`verify-infrastructure`) | Uses cross-cutting table + primary surface for commands |
+| Architecture (`create-prd-*`) | Map may be incomplete during these workflows — falls back to inline conversation context |

package/template/.claude/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: docs/plans/ia/[NN]a-[domain].md
+    Sub-features: 1, 3, 5
+  [NN]b — [new domain name] → file: docs/plans/ia/[NN]b-[domain].md
+    Sub-features: 2, 4, 6
+
+Split rationale: [why these groups are independent]
+```
+
+**After any split**: Update `docs/plans/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 `.agent/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/.claude/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 `docs/plans/` 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 |
+|-----------|----------|
+| `docs/plans/ia/` | Always |
+| `docs/plans/be/` | If exists |
+| `docs/plans/fe/` | If exists |
+| `docs/plans/be/web/` | If exists |
+| `docs/plans/fe/web/` | If exists |
+| `docs/plans/be/desktop/` | If exists |
+| `docs/plans/fe/desktop/` | If exists |
+| `docs/plans/be/mobile/` | If exists |
+| `docs/plans/fe/mobile/` | If exists |
+
+### Exclusions
+
+- The parent stub file itself (already marked SPLIT)
+- `docs/audits/` (audit records, not active specs)
+- `docs/plans/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/.claude/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., `docs/plans/be/web/` → surface `web`; flat `docs/plans/be/` → surface `shared`).
+
+2. **Read the surface stack map**: Open `.agent/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 `.agent/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 `.agent/skills/` and is not in `.agent/skill-library/MANIFEST.md`, read `.agent/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/.claude/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/.claude/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 (`docs/plans/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 `.agent/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 (`docs/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/.claude/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