cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skills/prd-templates/references/decision-confirmation-protocol.md

@@ -0,0 +1,68 @@
+# Decision Confirmation Protocol
+
+**Purpose**: Every decision that gets written to a spec or instruction file MUST be explicitly confirmed before writing. This protocol replaces all "refine based on discussion" patterns.
+
+---
+
+## Procedure
+
+### 1. Present
+
+Present the decision to the user with:
+- The specific question or choice
+- Your recommendation and reasoning
+- The options (if applicable)
+- Where the decision will be written (file + section)
+
+### 2. Wait for Confirmation
+
+**HARD GATE** — Do NOT write anything until the user explicitly confirms.
+
+Acceptable confirmations: explicit "yes", "approved", "confirmed", "go ahead", "looks good", selection of an option, or equivalent affirmative.
+
+NOT acceptable: silence, moving on to other topics, ambiguous responses. If ambiguous → ask again.
+
+### 3. Handle Requests for Changes
+
+If the user requests changes:
+1. Apply the requested changes to your proposed content
+2. Re-present the updated version
+3. Return to Step 2 — wait for confirmation again
+
+Do NOT write a partially-confirmed version. The full content must be confirmed before writing.
+
+### 4. Write
+
+After confirmation, write the decision to the target file + section.
+
+### 5. Verify Write
+
+Follow the write verification protocol (`.codex/skills/prd-templates/references/write-verification-protocol.md`):
+- Read back the target file
+- Verify the section header exists and content matches what was confirmed
+- If missing or mismatched → write failed, retry
+
+---
+
+## Tier-Aware Variant (for /create-prd workflows)
+
+When the current engagement tier is known:
+
+| Tier | Behavior |
+|------|----------|
+| **Interactive** | Full present → wait → confirm → write cycle per decision |
+| **Hybrid** | Group related decisions, present batch, confirm batch, write batch |
+| **Auto** | Use Deep Think reasoning, write with `[AUTO-CONFIRMED]` tag, present all auto-confirmed decisions for batch review at end of shard |
+
+**Even in Auto mode**, the user reviews and can reject auto-confirmed decisions at the batch review step. Rejection triggers re-presentation at Interactive tier for that decision.
+
+---
+
+## What This Replaces
+
+This protocol replaces all instances of:
+
+> ~~"Refine based on discussion before proceeding"~~
+> ~~"Adjust based on feedback"~~
+
+Those patterns allow agents to skip refinement and write unconfirmed content. This protocol requires explicit confirmation before any write.

package/template/.codex/skills/prd-templates/references/decision-propagation.md

@@ -0,0 +1,121 @@
+# Decision Propagation Reference
+
+Templates, formats, and scan procedures for `/propagate-decision` workflows.
+
+## Decision Type Sources
+
+| Decision Type | Source Document | Downstream Scope |
+|--------------|-----------------|-------------------|
+| **structure** | `.codex/instructions/structure.md` | All IA shards, BE specs, FE specs |
+| **tech-stack** | `.codex/instructions/tech-stack.md` + architecture doc | All IA shards, BE specs, FE specs |
+| **auth-model** | Architecture doc (auth/security section) | All BE specs with middleware, all FE specs with auth flows |
+| **data-placement** | `.memory/wiki/specs/data-placement-strategy.md` | All IA shards with data models, all BE specs with storage |
+| **patterns** | `.codex/instructions/patterns.md` | All IA shards, BE specs with implementation patterns, FE specs with component patterns |
+| **error-architecture** | Architecture doc `## Error Architecture` (5 sub-sections) | All BE specs, all FE specs |
+
+## Selection Menu Format
+
+```
+Decision propagation pre-scan:
+
+[1] structure — structure.md — inconsistencies detected in X documents
+[2] tech-stack — tech-stack.md — inconsistencies detected in X documents
+[3] auth-model — architecture doc — inconsistencies detected in X documents
+[4] data-placement — data-placement-strategy.md — inconsistencies detected in X documents
+[5] patterns — patterns.md — inconsistencies detected in X documents
+[6] error-architecture — architecture doc ## Error Architecture — inconsistencies detected in X documents
+
+[A] All with inconsistencies
+[Q] Quit — no propagation needed
+```
+
+## Error-Architecture Scan Procedure
+
+**Source extraction:**
+- Locate `.memory/wiki/specs/*-architecture-design.md` using glob
+- Read `## Error Architecture` and extract locked decisions from: `### Global Error Envelope`, `### Error Propagation Chain`, `### Unhandled Exception Strategy`, `### Client Fallback Contract`, `### Error Boundary Strategy`
+
+**BE spec conformance** (scan `.memory/wiki/specs/be/`):
+- Check error envelope by locked name and canonical field names
+- Check propagation chain rules
+- Classify: explicit contradiction / implicit assumption / consistent
+
+**FE spec conformance** (scan `.memory/wiki/specs/fe/`):
+- Check client fallback contract for surface type
+- Check error boundary placement
+- Same classification
+
+## Contradiction Display Format
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Contradiction N of X
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Document: [path]
+Section:  [section name]
+Current:  [current text]
+Locked:   [locked value]
+Fix to:   [proposed fix]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[Y] Apply fix and move to next
+[n] Skip this item
+[skip] Skip entire document
+[stop-and-save] Save progress and stop
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Assumption Display Format
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Assumption N of X
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Document: [path]
+Section:  [section name]
+Current:  [current text]
+Issue:    [ambiguity description]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[Y] Flag for /resolve-ambiguity
+[n] Ignore
+[skip] Skip entire document
+[stop-and-save] Save progress and stop
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Impact Report Format
+
+### Explicit Contradictions
+
+| Document | Line | Current Text | Locked Value | Decision Type |
+|----------|------|--------------|--------------|---------------|
+| [path] | [N] | [text] | [value] | [type] |
+
+### Implicit Assumptions
+
+| Document | Line | Current Text | Concern | Decision Type |
+|----------|------|--------------|---------|---------------|
+| [path] | [N] | [text] | [concern] | [type] |
+
+### Summary
+
+- **Explicit contradictions**: X items across Y documents
+- **Implicit assumptions**: X items across Y documents
+- **Consistent references**: X items (no action needed)
+
+## Completion Summary Format
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Propagation Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Fixed:   X contradictions across Y documents
+Flagged: X implicit assumptions for /resolve-ambiguity
+Skipped: X items
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Recommended next steps:
+1. Run `/resolve-ambiguity` to address the X flagged assumptions
+   (see .memory/wiki/specs/audits/propagation-ambiguity-[date].md)
+2. Run `/remediate-pipeline` to audit all layers with the corrected specs
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```

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

@@ -0,0 +1,226 @@
+# Decomposition Templates
+
+Templates for shard skeletons and layer indexes created during `/decompose-architecture-structure`.
+
+---
+
+## Shard Skeleton
+
+For each shard, create at `.memory/wiki/specs/ia/[NN-domain-name].md`:
+
+```markdown
+# [Shard ##] — [Domain Name]
+
+> **Architecture Source**: [link to architecture-design.md]
+> **Status**: Skeleton | Draft | Review | Complete
+
+## Overview
+[1-2 sentence description of this domain's scope]
+
+## Features
+[Level-1 sub-features from the relevant ideation domain folder for this domain. Check `ideation-index.md` Structure Map for the correct folder path — folders are under `domains/` or `surfaces/{name}/`. Read the folder's `*-index.md` for the children table, then each child feature file. NOT architecture-level headlines. See /decompose-architecture-structure Step 5 for seeding instructions.]
+
+## User Interactions
+[To be filled during /write-architecture-spec]
+
+## Data Model
+[To be filled during /write-architecture-spec]
+
+## Access Control
+[To be filled during /write-architecture-spec]
+
+## Accessibility
+
+<!-- Filled by /write-architecture-spec-design Step 5.5 -->
+<!-- For web/mobile/desktop surfaces: WCAG 2.1 AA requirements per interaction -->
+<!-- For api/cli/extension only: "Not applicable — no visual surfaces" -->
+
+## Edge Cases
+[To be filled during /write-architecture-spec]
+
+## Surface Applicability
+<!-- Populated during decomposition from architecture design's Project Surfaces -->
+| Surface | Applicable | Notes |
+|---------|-----------|-------|
+| [populated from architecture design] | | |
+
+> `all` shorthand: If the shard applies to every surface, write `Surfaces: all` instead of the table.
+
+## Cross-Shard Dependencies
+[List which other shards this one depends on or is depended upon by]
+
+## Deep Dives Needed
+[List any features complex enough to warrant a separate deep dive document]
+
+## Changelog
+
+| Date | Change | Workflow | Sections Affected |
+|------|--------|----------|-------------------|
+| [date] | Initial creation | /decompose-architecture-structure | All |
+```
+
+---
+
+## IA Index
+
+Create at `.memory/wiki/specs/ia/index.md`:
+
+```markdown
+# IA Layer — Information Architecture
+
+> **Architecture Source**: [link to architecture-design.md]
+
+## Reading Order
+
+Read cross-cutting shards first, then feature shards in numerical order.
+
+## Shards
+
+| # | Shard | Surfaces | Status | Deep Dives |
+|---|-------|----------|--------|------------|
+| 00 | [00-shard-name.md](00-shard-name.md) | all | 🔲 | — |
+| 01 | [01-shard-name.md](01-shard-name.md) | web, mobile | 🔲 | — |
+| ... | ... | ... | ... | ... |
+
+## Conventions
+
+- Every shard must define: features, user interactions, data model, access control, accessibility, edge cases
+- Cross-shard dependencies must be bidirectional (if A references B, B must reference A)
+- Complex features get a separate deep dive in `deep-dives/`
+- Status: 🔲 Skeleton → 📝 Draft → 👀 Review → ✅ Complete
+```
+
+---
+
+## BE Index Skeleton
+
+Create at `.memory/wiki/specs/be/index.md`:
+
+```markdown
+# BE Layer — Backend Specifications
+
+> **IA Source**: [link to ia/index.md]
+
+## Reading Order
+
+Read cross-cutting specs first, then feature specs in numerical order.
+
+## Conventions Template
+
+Every BE spec MUST include:
+- API Endpoints (method, path, description)
+- Request/Response Contracts ({{CONTRACT_LIBRARY}} schemas)
+- Database Schema (tables, fields, indexes, permissions)
+- Middleware & Policies (auth, rate limits, validation)
+- Data Flow (request lifecycle)
+- Error Handling (specific error codes, not generic 500s)
+- IA Source Map (which IA shard sections and deep dives inform each part)
+
+## Shard-to-Spec Mapping
+
+Populated by `/write-be-spec`. Mapping depends on shard document type
+(classified during `/write-architecture-spec`):
+
+| IA Shard | Type | BE Spec(s) | Status |
+|----------|------|-----------|--------|
+| *(populated by /write-be-spec)* | | | |
+```
+
+---
+
+## FE Index Skeleton
+
+Create at `.memory/wiki/specs/fe/index.md`:
+
+```markdown
+# FE Layer — Frontend Specifications
+
+> **BE Source**: [link to be/index.md]
+
+## Reading Order
+
+Read cross-cutting specs first, then feature specs in numerical order.
+
+## Conventions Template
+
+Every FE spec MUST include:
+- Component Inventory (tree with props interfaces)
+- Page/Route Definitions (URL patterns, guards, redirects)
+- State Management (server state, client state, URL state)
+- Interaction Specification (click, hover, keyboard, form validation)
+- Responsive Behavior (breakpoints, component behavior)
+- Accessibility (ARIA roles, keyboard navigation, screen reader)
+- Loading/Error/Empty States
+- Source Map (traceability to BE spec and IA shard sections)
+
+## Spec-to-Source Mapping
+
+Populated by `/write-fe-spec`. FE specs are organized by UI surface, not backend boundary:
+
+| # | FE Spec | BE Source(s) | IA Source | Status |
+|---|---------|-------------|-----------|--------|
+| *(populated by /write-fe-spec)* | | | | |
+```
+
+---
+
+## Master Index — Single-Surface
+
+Create or update `.memory/wiki/specs/index.md`:
+
+```markdown
+# [Project Name] — Specification Index
+
+## Documents
+
+| Document | Description | Status |
+|----------|-------------|--------|
+| [Ideation](ideation/ideation-index.md) | Problem, personas, features, constraints, domain map | ✅ |
+| [Architecture Design](YYYY-MM-DD-architecture-design.md) | Tech stack, system design, security | ✅ |
+
+## Specification Layers
+
+| Layer | Index | Purpose | Specs |
+|-------|-------|---------|-------|
+| **IA** | [ia/index.md](ia/index.md) | Features, interactions, data models, access control | N shards |
+| **BE** | [be/index.md](be/index.md) | API endpoints, contracts, database schemas, middleware | N specs |
+| **FE** | [fe/index.md](fe/index.md) | Components, routing, state, interactions, a11y | N specs |
+```
+
+## Master Index — Multi-Surface
+
+```markdown
+# [Project Name] — Specification Index
+
+## Documents
+
+| Document | Description | Status |
+|----------|-------------|--------|
+| [Ideation](ideation/ideation-index.md) | Problem, personas, features, constraints, domain map | ✅ |
+| [Architecture Design](YYYY-MM-DD-architecture-design.md) | Tech stack, system design, security | ✅ |
+
+## IA Layer (shared across all surfaces)
+
+| Layer | Index | Purpose | Shards |
+|-------|-------|---------|--------|
+| **IA** | [ia/index.md](ia/index.md) | Features, interactions, data models, access control | N shards |
+
+> IA shards are domain-based, not surface-based. Each shard declares its surface applicability.
+
+## Per-Surface Layers
+
+| Surface | BE Index | FE Index | Description |
+|---------|----------|----------|-------------|
+| **Shared** | [be/index.md](be/index.md) | [fe/index.md](fe/index.md) | Cross-surface contracts (pre-scaffolded dirs) |
+| **[Surface 1]** | [be/surface-1/index.md](be/surface-1/index.md) | [fe/surface-1/index.md](fe/surface-1/index.md) | [description] |
+| **[Surface 2]** | [be/surface-2/index.md](be/surface-2/index.md) | [fe/surface-2/index.md](fe/surface-2/index.md) | [description] |
+
+## Pipeline
+
+IA shards (shared) → per-surface BE specs → per-surface FE specs → audit → plan → implement → validate
+
+Shared BE specs must be completed first — surface-specific specs depend on them.
+```
+
+Each surface's own `index.md` contains BE/FE tables scoped to that surface.
+IA shards are referenced from the shared `ia/index.md` — filtered by the shard's Surface Applicability.

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

@@ -0,0 +1,114 @@
+# Deep Ideation Loading Protocol
+
+> **Purpose**: When ideation output is large (many domains, many features), the single `ideation-index.md` summary is insufficient for downstream architecture decisions. This protocol reads domain-level index files to build a structured **Domain Digest Table** that captures every feature, role assignment, and decision without requiring the agent to hold hundreds of leaf-level files in context.
+
+## When to Invoke
+
+**Always invoke** this protocol when ANY of these thresholds are met (read from the `## Progress Summary` table in `ideation-index.md`):
+
+| Metric | Threshold |
+|--------|-----------|
+| Total domains | ≥ 6 |
+| Total leaf features | ≥ 50 |
+| Total surfaces | ≥ 2 (multi-product projects) |
+
+If none of these thresholds are met, the standard `ideation-index.md` read is sufficient — skip this protocol.
+
+## Procedure
+
+### Step 1 — Enumerate domain folders
+
+Read the `## Structure Map` in `ideation-index.md`. For each row in the domain tables, record:
+- Domain number and name
+- Path to the domain folder
+- Status (`[SURFACE]`, `[BREADTH]`, `[DEEP]`, `[EXHAUSTED]`)
+- Child count (from the "Children" column)
+- Surface (for multi-product projects)
+
+This produces a **domain enumeration list** — typically 6-20 entries.
+
+### Step 2 — Read each domain index
+
+For each domain in the enumeration list, read `{domain-folder}/{domain}-index.md`. Extract:
+
+1. **Children table** — every sub-domain and feature with: number, name, type, status, depth
+2. **Role Matrix** — which personas have access to which children, and at what level (Full / Config / Read-only / Reports / None)
+3. **Decision Log** — any product decisions made during ideation for this domain
+4. **Open Questions** — deferred questions tagged for downstream stages
+
+> **Context management**: Read domain indexes one at a time. Extract the structured data, then move to the next. Do not attempt to hold all domain indexes simultaneously.
+
+### Step 3 — Read CX files for cross-domain dependencies
+
+Read `ideation-cx.md` (global cross-cuts) and each domain-level `{domain}-cx.md`. Extract:
+- Cross-domain data dependencies (which entities are shared)
+- Trigger chains (domain A event → domain B action)
+- Shared entity ownership
+
+### Step 4 — Build the Domain Digest Table
+
+Compile the extracted data into a structured table:
+
+```markdown
+## Ideation Digest
+
+> Auto-generated by the Deep Ideation Loading Protocol. Source: domain-level index files.
+> This section is the primary source for entity identification, data strategy, and phasing decisions.
+
+### Domain Summary
+
+| # | Domain | Surface | Features | Sub-domains | Depth | Must Have | Roles | Key Entities |
+|---|--------|---------|----------|-------------|-------|----------|-------|-------------|
+| 01 | {name} | {surface} | {N} | {N} | {status} | {N} | {list} | {entity hints} |
+
+### Cross-Domain Dependencies
+
+| Source Domain | Target Domain | Type | Shared Entities |
+|--------------|--------------|------|----------------|
+| {source} | {target} | data / trigger / permission | {entities} |
+
+### Ideation Decisions (from domain logs)
+
+| # | Domain | Decision | Impact |
+|---|--------|----------|--------|
+| D-{NN} | {domain} | {decision} | {what this affects downstream} |
+
+### Deferred Questions (tagged for /create-prd)
+
+| # | Domain | Question | Owner |
+|---|--------|----------|-------|
+| Q-{NN} | {domain} | {question} | /create-prd |
+```
+
+### Step 5 — Derive Key Entities column
+
+For each domain, scan the Children table for entity hints:
+- Feature names that imply data objects (e.g., "Device History" → `Device`, `RepairRecord`)
+- Role Matrix intersections that imply access-controlled resources
+- Cross-cut shared entities from CX files
+
+List the implied entities in the "Key Entities" column. These are **hints**, not schema — they inform data strategy without prescribing it.
+
+### Step 6 — Write to architecture-draft.md
+
+Write the completed Domain Digest Table to `.memory/wiki/specs/architecture-draft.md` as the first section (`## Ideation Digest`). If the file doesn't exist yet, create it with this section.
+
+> **Write immediately.** Do not hold the digest in memory — write it to disk as soon as it's compiled. All subsequent create-prd shards read from `architecture-draft.md`.
+
+## Downstream Consumption
+
+| Consumer | What It Uses |
+|----------|-------------|
+| `create-prd-architecture` (Step 5: Data strategy) | Key Entities column → entity identification; Cross-Domain Dependencies → data ownership and sync |
+| `create-prd-compile` (Step 9: Phasing) | Features + Must Have counts → phase complexity sizing; Sub-domain counts → dependency ordering |
+| `create-prd-security` | Roles column → access control scope; Cross-Domain Dependencies → trust boundaries |
+
+## Anti-Patterns
+
+| ❌ Wrong | ✅ Right |
+|---------|---------|
+| Reading all 295 leaf-level feature files | Reading 8-20 domain index files |
+| Skipping this protocol because "ideation-index.md has a summary" | Invoking when thresholds are met — summaries lose detail |
+| Deriving entities from the MoSCoW bullet list | Deriving entities from the Children tables + CX dependencies |
+| Holding all domain indexes in context simultaneously | Reading one at a time, extracting structured data, moving on |
+| Writing the digest at the end of create-prd | Writing it to architecture-draft.md immediately in Step 1.5 |