cfsa-antigravity 3.0.2 → 3.1.0

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

@@ -0,0 +1,90 @@
+# FE Spec Template
+
+Use this template when writing FE specs to `.memory/wiki/specs/fe/[NN-feature-name].md`.
+
+```markdown
+# [Feature] — Frontend Specification
+
+> **BE Source**: [link to BE spec(s), or N/A for cross-cutting]
+> **IA Source**: [link to IA shard, or N/A for cross-cutting]
+> **Status**: Draft | Review | Complete
+
+## Split Group _(include only if this spec resulted from a split)_
+
+> **Split origin**: [IA shard that was split, e.g., `09-messaging`]
+> **Companion specs**: [sibling FE spec files, e.g., `09b-agent-flow-ui.md`]
+> **Shared entities**: [data models shared across companions, e.g., `Message`, `Thread`]
+
+## Source Map
+
+| FE Spec Section | Source | Section/Lines |
+|-----------------|--------|---------------|
+| Component Inventory | [be-spec.md or conventions] | § Response Contracts |
+| Page/Route Definitions | [ia-shard.md or conventions] | § User Flows |
+| Interactions | [ia-shard.md or conventions] | § User Flows + § Edge Cases |
+| Accessibility | [ia-shard.md or conventions] | § Accessibility (lines N–M) |
+| Responsive Behavior | [ia-shard.md or conventions] | § Device Strategy |
+| Data Mapping | [be-spec.md or conventions] | § Request/Response Contracts |
+
+## Design Requirements
+**Direction**: [from brand-guidelines — confirmed direction]
+**Typography**: [font/size/weight per text element]
+**Colors**: [primary/secondary/accent for default, hover, active, disabled, error states]
+**Motion**: [animation/transition behavior, or "none"]
+**Anti-patterns**: [what AI slop looks like for this component and how to avoid it]
+
+## Design System Compliance
+**Page archetype(s)**: [name the archetype(s) from design-system.md]
+**Navigation**: [confirm which nav elements this spec uses from the global component inventory]
+**Loading states**: [confirm skeleton vs. spinner — cite design-system.md rule]
+**Error states**: [confirm inline/toast/full-page/boundary — cite design-system.md rule for each context]
+**Empty states**: [confirm illustration style and copy tone from design-system.md]
+
+## Component Inventory
+[Tree with props interfaces]
+
+## Page/Route Definitions
+[URL patterns, guards, redirects]
+
+## State Management
+[Server state, client state, URL state, loading/error/empty]
+
+## Interaction Specification
+[Click, hover, keyboard, form validation matching {{CONTRACT_LIBRARY}}]
+
+## Responsive Behavior
+[Breakpoints, component behavior per breakpoint]
+
+## Accessibility
+[ARIA roles, keyboard nav, screen reader, WCAG compliance]
+
+## Data Mapping
+[Which BE response fields map to which component props]
+
+## Open Questions
+
+## Changelog
+
+| Date | Change | Workflow | Sections Affected |
+|------|--------|----------|-------------------|
+| [date] | Initial creation | /write-fe-spec | All |
+```
+
+## Quality Gates Checklist
+
+Apply after writing every FE spec:
+
+- [ ] Every component has a props interface
+- [ ] Every interactive element has defined behavior
+- [ ] Every data field maps to a BE response field (if applicable)
+- [ ] Loading, error, and empty states defined for every data-fetching view
+- [ ] Accessibility requirements meet WCAG 2.1 AA
+- [ ] Responsive behavior specified for all breakpoints
+- [ ] IA shard's accessibility section fully consumed (not re-derived from BE spec)
+- [ ] IA shard's user flows reflected in interaction specification
+- [ ] Account-tier conditional rendering rules from IA access model included
+- [ ] Source Map is complete — no FE spec section lacks a traceable source
+- [ ] Design Requirements section filled from brand-guidelines (not placeholders)
+- [ ] Page archetype named and matches design-system.md
+- [ ] All loading/error/empty states use the confirmed design language from design-system.md
+- [ ] No global component re-invented (consuming from global inventory, not re-implementing)

package/template/.codex/skills/prd-templates/references/feature-ledger-protocol.md

@@ -0,0 +1,149 @@
+# Feature Tracking Ledger Protocol
+
+> **Purpose**: Track every ideation feature through the entire pipeline — from birth in ideation to final slice assignment. Catches dropped features that per-stage reconciliation tables miss.
+
+## Ledger Location
+
+`.memory/wiki/specs/feature-ledger.md`
+
+## Ledger Format
+
+```markdown
+# Feature Tracking Ledger
+
+> Auto-generated by `/ideate-validate`. Updated by each pipeline stage.
+> Each column is populated by the stage that owns it (see Column Ownership below).
+
+| Feature ID | Feature Name | Domain | MoSCoW | IA Shard | IA Status | BE Spec | BE Status | FE Spec | FE Status | Phase | Slice |
+|-----------|-------------|--------|--------|----------|-----------|---------|-----------|---------|-----------|-------|-------|
+```
+
+## Column Ownership
+
+| Column(s) | Populated By | Stage |
+|-----------|-------------|-------|
+| Feature ID, Feature Name, Domain, MoSCoW | `/ideate-validate` Step 11.5 | Discovery |
+| IA Shard, IA Status | `/decompose-architecture-validate` | Design |
+| BE Spec, BE Status | `/write-be-spec-write` | Specification |
+| FE Spec, FE Status | `/write-fe-spec-write` | Specification |
+| Phase, Slice | `/plan-phase-write` Step 2.5 | Planning |
+
+## Status Values
+
+| Status | Meaning |
+|--------|---------|
+| ✅ | Covered — spec exists and includes this feature |
+| ⚠️ deferred | Explicitly deferred with documented reason |
+| ❌ missing | Not covered — no spec addresses this feature |
+| — | Column not yet populated (upstream stage hasn't run) |
+
+## Step 1 — Ledger Creation (`/ideate-validate`)
+
+**When**: After Step 11 (compile vision), before Step 12 (request review).
+
+**Procedure**:
+
+1. Read `ideation-index.md` → Structure Map → get all domain paths
+2. For each domain, read `{domain}-index.md` → Children table
+3. For each leaf-level child (type = `feature`), create one ledger row:
+   - **Feature ID**: `{domain-name}/{feature-file-basename}` (e.g., `inventory/01-categories`)
+   - **Feature Name**: from the Children table Name column
+   - **Domain**: domain name
+   - **MoSCoW**: from `ideation-index.md` MoSCoW Summary (match by feature name), or from the feature's own priority field if available
+4. All other columns → `—` (not yet populated)
+5. Write to `.memory/wiki/specs/feature-ledger.md`
+
+> **Context management**: Read domain indexes one at a time, extract features, move on. Same pattern as the deep-ideation-loading protocol.
+
+## Step 2 — IA Assignment (`/decompose-architecture-validate`)
+
+**When**: After shard boundaries are approved and shard skeletons exist.
+
+**Procedure**:
+
+1. Read `.memory/wiki/specs/feature-ledger.md`
+2. For each IA shard skeleton in `.memory/wiki/specs/ia/`:
+   - Read the shard's `## Sub-features` or features list
+   - For each feature, find the matching row in the ledger (match by Feature ID or Feature Name)
+   - Set **IA Shard** = shard name (e.g., `02-inventory`)
+   - Set **IA Status** = `✅`
+3. **Orphan check**: Any row where IA Shard is still `—` after processing all shards → set IA Status = `❌ missing`
+4. Write updated ledger
+
+**If orphans are found**:
+> ⚠️ **Feature ledger orphan check**: [N] features from ideation have no IA shard assignment:
+> - `{Feature ID}`: {Feature Name}
+>
+> Options:
+> 1. Add to an existing shard
+> 2. Create a new shard
+> 3. Mark as explicitly deferred (with reason)
+
+**STOP** — wait for user decision on each orphan.
+
+## Step 3 — BE Coverage (`/write-be-spec-write`)
+
+**When**: After each BE spec is written.
+
+**Procedure**:
+
+1. Read `.memory/wiki/specs/feature-ledger.md`
+2. Read the newly written BE spec's endpoint list
+3. For each endpoint, identify which Feature ID(s) it serves (from the IA shard → feature mapping)
+4. For each matched Feature ID, set **BE Spec** = spec file name, **BE Status** = `✅`
+5. Write updated ledger
+
+> **Note**: Not all features produce BE endpoints (e.g., purely client-side UI features). These should have BE Status = `⚠️ deferred` with reason "client-only".
+
+## Step 4 — FE Coverage (`/write-fe-spec-write`)
+
+**When**: After each FE spec is written.
+
+**Procedure**:
+
+1. Read `.memory/wiki/specs/feature-ledger.md`
+2. Read the newly written FE spec's component list
+3. For each component, identify which Feature ID(s) it serves
+4. For each matched Feature ID, set **FE Spec** = spec file name, **FE Status** = `✅`
+5. Write updated ledger
+
+## Step 5 — Slice Assignment (`/plan-phase-write`)
+
+**When**: After Step 2.5 (spec coverage verification).
+
+**Procedure**:
+
+1. Read `.memory/wiki/specs/feature-ledger.md`
+2. For each slice, identify which Feature ID(s) it covers (from its spec source map)
+3. For each matched Feature ID, set **Phase** = phase number, **Slice** = slice ID
+4. Write updated ledger
+
+## Verification Gate (`/plan-phase-preflight`)
+
+**When**: During the cross-layer consistency check.
+
+**Procedure**:
+
+1. Read `.memory/wiki/specs/feature-ledger.md`
+2. Count features by completeness:
+   - **✅ Complete**: All columns through FE Status are ✅ or ⚠️ deferred
+   - **⚠️ Partial**: Some columns filled, some still `—`
+   - **❌ Orphaned**: IA Status or BE Status or FE Status = `❌ missing`
+3. Report:
+
+> **Feature Ledger Verification**:
+> - ✅ Complete: [N] features
+> - ⚠️ Partial: [N] features (columns not yet populated by upstream stages)
+> - ❌ Orphaned: [N] features (dropped between stages)
+
+4. **If any ❌ orphans** → **BLOCKING GATE**: "Feature ledger shows [N] orphaned features. Resolve before planning."
+5. **If any ⚠️ partial** → **WARNING**: "Feature ledger shows [N] features with incomplete coverage. These may be from stages not yet run."
+
+## Anti-Patterns
+
+| ❌ Wrong | ✅ Right |
+|---------|---------|
+| Skipping ledger updates "because it's just bookkeeping" | Every stage updates its columns — it's the only global tracking |
+| Marking orphaned features as ⚠️ deferred without a reason | Orphans are ❌ missing until explicitly deferred with documented reasoning |
+| Regenerating the ledger from scratch at each stage | Updating existing rows — the ledger is cumulative |
+| Ignoring the orphan check at plan-phase-preflight | Blocking on orphans — they represent dropped features |

package/template/.codex/skills/prd-templates/references/folder-seeding-protocol.md

@@ -0,0 +1,77 @@
+# Folder Seeding Protocol
+
+Rules for creating the `.memory/wiki/specs/ideation/` folder structure during `/ideate-extract`.
+
+## Additive-Only Rule
+
+The `.memory/wiki/specs/ideation/` directory already exists in the kit with `.gitkeep` and `README.md`. You are ADDING files into this existing directory.
+
+- Do NOT delete, overwrite, or replace the directory itself
+- Do NOT remove any existing files (`.gitkeep`, `README.md`)
+- Create new files alongside what already exists
+
+## Base Structure (All Project Shapes)
+
+After seeding, the folder should contain kit-shipped files PLUS new pipeline files:
+
+```
+.memory/wiki/specs/ideation/
+├── .gitkeep                ← KIT-SHIPPED — do not touch
+├── README.md               ← KIT-SHIPPED — do not touch
+├── ideation-index.md       ← NEW: super-index (from ideation-index-template)
+├── ideation-cx.md          ← NEW: global cross-cuts (from ideation-crosscut-template)
+└── meta/                   ← NEW: created by this step
+    ├── problem-statement.md
+    ├── personas.md
+    ├── competitive-landscape.md
+    └── constraints.md
+```
+
+For multi-product projects, additionally create `surfaces/` with sub-folders per surface.
+
+## Templates
+
+Read these templates when creating files:
+
+- `.codex/skills/prd-templates/references/ideation-index-template.md` (super-index)
+- `.codex/skills/prd-templates/references/ideation-crosscut-template.md` (global CX)
+- `.codex/skills/prd-templates/references/fractal-node-index-template.md` (node index)
+- `.codex/skills/prd-templates/references/fractal-cx-template.md` (node CX)
+- `.codex/skills/prd-templates/references/fractal-feature-template.md` (feature file)
+
+## Domain Seeding Rules
+
+Domains come from the **confirmed classification table** (Step 1.4.5), NOT from source headings.
+
+### Placement by Structural Classification
+
+| Classification | Placement |
+|---|---|
+| Single-surface | `.memory/wiki/specs/ideation/{NN}-{slug}/` |
+| Hub-and-spoke | Surface-exclusive in `surfaces/{surface}/{NN}-{slug}/`, shared in hub surface |
+| Peer | Surface-exclusive in `surfaces/{surface}/{NN}-{slug}/`, shared in `shared/{NN}-{slug}/` |
+
+### Node Type → Action
+
+| Gate Result | Action |
+|---|---|
+| **Domain** | Create domain folder with `{slug}-index.md` + `{slug}-cx.md` |
+| **Sub-domain** | Create sub-domain folder nested inside parent domain |
+| **Feature** | Create feature file inside parent domain or sub-domain |
+| **Cross-cut** | Add entries to appropriate CX files (domain-level or global) |
+| **Not-a-product-domain** | Add notes to `meta/constraints.md` for `/create-prd` |
+
+After all nodes are created, update `ideation-index.md` structure map with paths.
+
+## Content Seeding by Input Type
+
+| Input Type | Content Strategy |
+|---|---|
+| **Rich document** | Seed each node with content from source using classification table citations. Run fidelity check: every major concept in source must map to SOMETHING in the output. Add `> Source: path/to/original.md` to index. |
+| **Chat transcript** | Noise filter → extract signal → seed domain folders with structured output |
+| **Thin document** | Create domain folders with depth markers on feature files |
+| **Verbal / one-liner** | Create domain folders with scaffolding. Feature files are `[SURFACE]`. |
+
+## Post-Seeding Verification Gate
+
+After creating all files, verify that `.memory/wiki/specs/ideation/.gitkeep` and `.memory/wiki/specs/ideation/README.md` still exist. If EITHER file is missing → **STOP**: "Kit-shipped files were destroyed during seeding. Restore `.gitkeep` and/or `README.md` to `.memory/wiki/specs/ideation/` before continuing."

package/template/.codex/skills/prd-templates/references/fractal-cx-template.md

@@ -0,0 +1,58 @@
+# {Node Name} — Cross-Cuts
+
+> **Level**: {surface | domain | sub-domain}
+> **Scope**: Connections between children of [{parent}](../{parent}-index.md)
+
+## Cross-Cut Map
+
+| # | Source | Target | Relationship | Roles Affected | Confidence | Evidence |
+|---|--------|--------|--------------|----------------|------------|----------|
+| CX-01 | [child-A](./path) | [child-B](./path) | _what the interaction is_ | Tech, Owner | High | _specific evidence from exploration_ |
+| CX-02 | [child-C](./path) | [{external-node}](../../path) | _cross-level interaction_ | Tech | Medium | _evidence_ |
+
+> **Confidence levels:** High (confirmed with evidence), Medium (strong signal, needs validation), Low (hypothesis)
+>
+> **Cross-level references:** When a cross-cut spans levels (e.g., a feature in one surface touches a domain in another), record it here at the HIGHER level with a link path to the specific lower-level item. The detail of HOW they interact lives in the LOWER-level CX file.
+>
+> **Cross-references:** When referencing a CX entry from another file, use format `{filename}#CX-NN` (e.g., `ai-assistant-cx.md#CX-03`)
+
+---
+
+## Cross-Cut Details
+
+### CX-01: {Source} ↔ {Target}
+
+**Relationship**: _Detailed description of how these two children interact. What data flows between them? What triggers what?_
+
+**Role scoping**:
+- **{Role 1}**: _what this role experiences at this intersection_
+- **{Role 2}**: _what this role experiences_
+- **{Role 3}**: _not affected / no visibility_
+
+**Synthesis questions answered**:
+1. **Shared state conflict**: _Who owns the entity? What's the merge strategy if both sides modify it?_
+2. **Trigger chain**: _Does A trigger B? What happens if B fails — rollback? Compensating action? Is it sync or async?_
+3. **Permission intersection**: _Does a permission in A affect what you can do in B?_
+4. **Notification fan-out**: _Does an event in A notify actors in B?_
+5. **State transition conflict**: _Can A and B race? What's the consistency impact?_
+
+---
+
+_Repeat the Cross-Cut Details section for each CX entry in the map._
+
+---
+
+## Rejected Pairs
+
+| # | Source | Target | Reason for Rejection |
+|---|--------|--------|---------------------|
+| R-01 | _{child-A}_ | _{child-B}_ | _No shared state, no trigger dependency, independent lifecycles_ |
+
+> **Notes for agents:**
+> - This template is used at EVERY folder level in the fractal structure
+> - CX files ONLY connect children at their own level — a surface CX connects domains, a domain CX connects sub-domains, a sub-domain CX connects features
+> - CX entries use sequential `CX-NN` numbering within each file, starting at CX-01
+> - Always include role scoping — every cross-cut affects specific roles, not all roles equally
+> - Rejected pairs are valuable — they show the agent considered the interaction and dismissed it with reasoning
+> - The 5 synthesis questions should be answered for EVERY confirmed cross-cut (CX entries with High confidence)
+> - For Medium/Low confidence entries, the synthesis questions can be deferred to later drilling passes

package/template/.codex/skills/prd-templates/references/fractal-feature-template.md

@@ -0,0 +1,93 @@
+# Feature: {Feature Name}
+
+> **Number**: {NN.NN.NN}
+> **Parent**: [{sub-domain-name}](./{sub-domain}-index.md)
+> **Status**: [SURFACE] / [PARTIAL] / [DEEP] / [EXHAUSTED]
+> **Last updated**: {timestamp}
+
+## Overview
+
+_What this feature is, why it exists, what user problem it solves. 2-3 sentences._
+
+## Role Lens
+
+| Role | Access | What They See/Do |
+|------|--------|-------------------|
+| {Persona 1} | Full | _specific behavior for this role — actions, views, capabilities_ |
+| {Persona 2} | Config | _specific behavior — what they configure, what they see_ |
+| {Persona 3} | Read-only | _specific behavior — what they can view, what's hidden_ |
+| {Persona 4} | None | _not visible — brief note on why or what they see instead_ |
+
+> **Access levels**: Full · Config · Read-only · Reports · None
+>
+> **Rules:**
+> - Every feature file MUST have a Role Lens table — no exceptions
+> - Use persona names from `meta/personas.md`
+> - "What They See/Do" must be SPECIFIC to this feature, not generic role descriptions
+> - If a persona has "None" access, still list them — the explicit absence is valuable for downstream spec writers
+> - This is the implementation-ready detail that IA/BE/FE spec writers consume directly
+
+## Behavior
+
+_Detailed description of the feature's behavior._
+
+### Happy Path
+
+_Step-by-step user interaction for the normal/expected case. Number each step._
+
+1. _User does X_
+2. _System responds with Y_
+3. _User confirms Z_
+4. _System completes action, shows confirmation_
+
+### Edge Cases / Failure Modes
+
+| Scenario | What Happens | User Sees |
+|----------|-------------|-----------|
+| _edge case 1_ | _system behavior_ | _error message or fallback UI_ |
+| _edge case 2_ | _system behavior_ | _error message or fallback UI_ |
+
+### States
+
+| State | Trigger | What User Sees |
+|-------|---------|---------------|
+| Loading | _action initiated_ | _spinner, skeleton, progress bar_ |
+| Empty | _no data exists yet_ | _empty state with CTA_ |
+| Populated | _data loaded_ | _populated view_ |
+| Error | _request failed_ | _error message with retry option_ |
+| Partial | _incomplete data_ | _partial view with missing-data indicator_ |
+
+## Deep Think Annotations
+
+| # | Hypothesis | Source | Outcome |
+|---|-----------|--------|---------|
+| DT-01 | _hypothesis about what this feature needs_ | _reasoning or industry precedent_ | ✅ CONFIRMED / ❌ REJECTED: _reason_ |
+
+> Log every Deep Think hypothesis — both confirmed and rejected. This is the audit trail showing the agent explored beyond the obvious.
+
+## Cross-Cut Notes
+
+_Quick references to how this feature interacts with features in other domains/sub-domains. These are pointers — detailed cross-cut analysis lives in the parent's CX file._
+
+- Touches **{Domain/Sub-domain/Feature}** ([path](../../../path)) — _why: shared entity, trigger dependency, permission, etc._
+- Consumed by **{Surface/Domain}** via API — _why: spoke surface reads this data through platform API_
+
+> For detailed cross-cut analysis (synthesis questions, role scoping), see the CX file at the appropriate level.
+
+## Decisions
+
+| # | Decision | Context |
+|---|----------|---------|
+| D-01 | _what was decided_ | _why this was the right call_ |
+
+## Open Questions
+
+| # | Question | Owner | Deferred To |
+|---|----------|-------|-------------|
+| Q-01 | _question_ | User / Agent / /create-prd | _pipeline stage_ |
+
+> **Notes for agents:**
+> - Feature files are LEAF NODES — they are `.md` files, never folders
+> - If a feature reveals 2+ interacting capabilities during drilling, it should be PROMOTED to a sub-domain (see Reactive Depth Protocol in `idea-extraction/SKILL.md`)
+> - Status markers: `[SURFACE]` = identified only, `[PARTIAL]` = some depth, `[DEEP]` = all sections filled with edge cases, `[EXHAUSTED]` = Deep Think yields zero hypotheses + user confirms nothing missing
+> - The Role Lens is the PRIMARY output consumed by `/write-fe-spec` and `/write-be-spec` — make it thorough

package/template/.codex/skills/prd-templates/references/fractal-node-index-template.md

@@ -0,0 +1,55 @@
+# {Node Name} — Index
+
+> **Level**: {surface | domain | sub-domain}
+> **Parent**: [{parent-name}](../{parent}-index.md)
+> **Status**: [SURFACE] / [BREADTH] / [DEEP] / [EXHAUSTED]
+> **Last updated**: {timestamp}
+
+## Overview
+
+_What this node contains and why it exists. 2-3 sentences describing the domain or sub-domain's purpose and scope._
+
+## Children
+
+| # | Name | Type | Path | Status | Deep Think |
+|---|------|------|------|--------|------------|
+| 01 | _{child-name}_ | domain / sub-domain / feature | [01-slug](./01-slug/) or [01.01-slug.md](./01.01-slug.md) | [SURFACE] | _N hypotheses_ |
+| 02 | ... | ... | ... | ... | ... |
+
+> **Type column values:**
+> - `domain` — a top-level grouping within a surface (folder with index + CX)
+> - `sub-domain` — a grouping within a domain that has 2+ interacting capabilities (folder with index + CX)
+> - `feature` — a leaf node describing a single capability (.md file)
+
+## Role Matrix
+
+| Child | {Persona 1} | {Persona 2} | {Persona 3} | {Persona 4} |
+|-------|-------------|-------------|-------------|-------------|
+| 01-child | ✅ Full | ⚙️ Config | 👁️ View | ❌ None |
+| 02-child | ✅ Full | ✅ Full | ❌ None | ❌ None |
+
+> **Legend**: ✅ Full access · ⚙️ Configuration only · 👁️ Read-only · 📊 Reports only · ❌ No access
+>
+> **Rules:**
+> - Persona names come from `meta/personas.md` — use short names (e.g., "Tech", "Owner", "CSR", "Consumer")
+> - NEVER redefine a persona here — reference only
+> - Only list children that exist — the matrix grows as children are added
+> - Access icons are shorthand; detailed per-role behavior lives in each feature file's **Role Lens**
+
+## Decision Log
+
+| # | Decision | Context | Source |
+|---|----------|---------|--------|
+| D-01 | _what was decided_ | _why this was the right call_ | _conversation / document / user directive_ |
+
+## Open Questions
+
+| # | Question | Owner | Deferred To |
+|---|----------|-------|-------------|
+| Q-01 | _question_ | User / Agent / /create-prd | _pipeline stage_ |
+
+> **Notes for agents:**
+> - This template is used at EVERY folder level in the fractal structure (surface, domain, sub-domain)
+> - The content differs by level — a surface index lists domains, a domain index lists sub-domains/features
+> - Status propagates upward: all children `[EXHAUSTED]` → node is `[EXHAUSTED]`; all `[DEEP]`+ → node is `[DEEP]`
+> - When adding a new child, update BOTH the Children table AND the Role Matrix

package/template/.codex/skills/prd-templates/references/gate-applicability.md

@@ -0,0 +1,92 @@
+# Gate Applicability Reference
+
+Reference for `/validate-phase-readiness` Step 5.85. Defines which readiness gates apply based on phase content.
+
+## Content Classification Table
+
+Read the phase plan and completed slices. Determine which content categories are present:
+
+| Content Category | How to Detect | Gates It Triggers |
+|-----------------|---------------|-------------------|
+| **New/modified API endpoints** | BE spec slices, new route files, new controllers | 5.9 (API docs), 8 (Security — full) |
+| **New/modified UI components** | FE spec slices, new component files, new pages/routes | 6 (Accessibility), 7a (Performance — Web Vitals/Bundle) |
+| **New/modified data models** | Schema changes, new migrations, new DB queries | 7a (Performance — DB Query Time), 8 (Security — data flow) |
+| **Infrastructure-only changes** | CI/CD config, hosting config, env vars, no app code | Skip 5.9, 6; apply 8 (infra security only) |
+| **Auth/security changes** | Auth middleware, RBAC, token handling, secrets | 8 (Security — mandatory, elevated priority) |
+
+## Gate Applicability Table Template
+
+Build this table for each phase:
+
+```markdown
+| Gate | Applies? | Reason |
+|------|----------|--------|
+| 5.9 API Documentation | Yes/No/Deferred | [why] |
+| 6 Accessibility | Yes/No/Deferred | [why] |
+| 7a Performance Budget | Yes/No/Deferred | [why] |
+| 7b Deep Performance | Yes/No/Deferred | [why] |
+| 8 Security Review | Always Yes | Core audit always runs |
+| 8.5 Dependency Audit | Always Yes | Always runs |
+| 8.7 Feature Ledger | Always Yes | Always runs (if ledger exists) |
+| 8.8 Boundary Stub Audit | Always Yes | Always runs |
+```
+
+## Always-On Gates (never skippable)
+
+- **8 Security Review** — Core adversarial review + defense-in-depth always runs. DAST scan is conditional on having a staging deployment with endpoints.
+- **8.5 Dependency Audit** — Always runs.
+- **8.7 Feature Ledger Reconciliation** — Always runs (if ledger exists).
+- **8.8 Boundary Stub Audit** — Always runs.
+
+## Content-Triggered Gates (skip when content category is absent)
+
+- **5.9 API Documentation** — Skip if no new/modified API endpoints in this phase.
+- **6 Accessibility** — Skip if no new/modified UI components in this phase.
+- **7a Performance Budget (Web Vitals/Bundle)** — Skip if no UI changes. DB Query Time sub-gate skips if no new queries/models.
+- **7b Deep Performance** — Skip if no performance-critical changes.
+
+## Deferred Gate Rules
+
+A gate may be **deferred** (not skipped) when:
+- The gate applies but a prerequisite is not yet available (e.g., staging deployment not configured yet for DAST)
+- The phase is early infrastructure and the gate will apply to the next phase that adds the relevant content
+
+**Hard deadline required**: Specify which phase or milestone must run the deferred gate. Log deferred gates in `.memory/wiki/specs/audits/phase-N-validation.md` with the deadline.
+
+**Single-deferral limit**: A gate may NOT be deferred more than once. If a previously deferred gate's deadline arrives, it MUST run — no further deferral.
+
+## Validation Report Structure
+
+### Gate Applicability Summary
+
+Include the gate applicability table. For each gate, report one of:
+- **Applied** — gate ran, results follow
+- **Skipped** — gate did not apply to this phase (with reason)
+- **Deferred** — gate applies but prerequisite missing (with hard deadline)
+
+### Applied Gate Results
+
+Report only for gates that were applied:
+- Test results and coverage
+- Lint and type-check status
+- Build status
+- Accessibility findings (if gate applied)
+- Performance budget results 7a and deep audit findings 7b (if gate applied)
+- Security review findings (including DAST results if applicable)
+- Dependency audit results
+- API documentation sync status (if gate applied)
+- Deployment strategy compliance (if applicable)
+- CI/CD pipeline status, staging deployment result, migration verification status
+
+### Deferred Gates Section
+
+For each deferred gate:
+- Gate name and step number
+- Reason for deferral
+- Hard deadline (phase number or milestone)
+- Whether this is the first deferral (second deferral is forbidden)
+
+### Verdict
+
+- Pass/fail verdict
+- If any gates were deferred: "Phase N passes with deferred gates. Deferred gates MUST run by [deadline]."

package/template/.codex/skills/prd-templates/references/ideation-crosscut-template.md

@@ -0,0 +1,36 @@
+# Global Cross-Cuts — {{PROJECT_NAME}}
+
+> **Scope**: Cross-surface interactions for multi-product projects, or cross-domain interactions for single-surface projects.
+> **Format**: Index + one-line summary. Detailed synthesis lives in lower-level CX files.
+
+## Cross-Surface Interaction Map
+
+> Each row records that an interaction EXISTS between two surfaces or top-level domains. The Detail column links to the lower-level CX file where the full synthesis questions are answered.
+
+| # | Source Surface/Domain | Target Surface/Domain | Summary | Roles | Detail |
+|---|----------------------|----------------------|---------|-------|--------|
+| CX-01 | _Web / Consumer Platform_ | _Desktop / Shop Ops_ | _Desktop diagnostic workflow consumes web supplier data via API_ | Tech, Owner | [detail](surfaces/desktop/desktop-cx.md#CX-03) |
+| CX-02 | _Web / Device History_ | _Mobile / Device Guardian_ | _Mobile app syncs with web device history for owner verification_ | Consumer | [detail](surfaces/mobile/mobile-cx.md#CX-01) |
+
+> **Rules:**
+> - This file is an INDEX with one-line summaries — not the source of truth for cross-cut details
+> - Detailed synthesis (5 questions, role scoping) lives in the lower-level CX file linked in the Detail column
+> - For single-surface projects, this file covers cross-DOMAIN interactions (same content as would appear in a surface-level CX)
+> - For multi-product projects, this file covers cross-SURFACE interactions
+> - Use `CX-NN` numbering. This file's entries are distinct from CX entries in lower-level files.
+> - When referencing from other files, use `ideation-cx.md#CX-NN`
+
+## Shared Domain Consumption _(multi-product only)_
+
+> Which shared domains are consumed by which spoke surfaces, and through what mechanism.
+
+| Shared Domain | Owner | Consumed By | Mechanism | Detail |
+|--------------|-------|-------------|-----------|--------|
+| _Device History_ | Web (hub) | Desktop, Mobile | REST API | [web/02-device-history-cx.md](surfaces/web/02-device-history/device-history-cx.md) |
+| _Payments_ | Web (hub) | Desktop | REST API | [web/03-payments-cx.md](surfaces/web/03-payments/payments-cx.md) |
+
+## Rejected Cross-Surface Pairs
+
+| # | Surface A | Surface B | Reason for Rejection |
+|---|-----------|-----------|---------------------|
+| R-01 | _Desktop_ | _Mobile_ | _No direct interaction — both consume web API independently_ |