cfsa-antigravity 2.19.0 → 2.19.2

package/template/.claude/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 `docs/plans/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 `docs/plans/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 `docs/plans/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 `docs/plans/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 `docs/plans/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/.claude/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 `docs/plans/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 |

package/template/.claude/skills/prd-templates/references/design-system-decisions.md

@@ -0,0 +1,198 @@
+# Design System Decision Options & Output Template
+
+Reference material for the `/create-prd-design-system` workflow. Contains option menus for all seven decisions and the canonical output template for `docs/plans/design-system.md`.
+
+---
+
+## Navigation Paradigm Options
+
+### Web surfaces
+
+- **Sidebar + topnav** — Collapsible sidebar for section nav, top bar for global actions. Good for complex apps with deep IA; competes with content width on small screens.
+- **Tab bar (app-style)** — Horizontal tab bar, web app feels like a native app. Limited to 5–7 top-level destinations; unfamiliar on traditional websites.
+- **Full-page transitions** — Each section is a full-page view with navigation between pages. Poor for frequent cross-section navigation; high cognitive load for data-heavy apps.
+- **Command palette primary** — Keyboard-first navigation with minimal visible chrome. High power-user efficiency; steep learning curve, requires discoverability affordances.
+- **Minimal/none** — No persistent navigation; content-first with contextual links. Clean and focused; users may feel lost without orientation cues.
+
+### Mobile surfaces
+
+- **Bottom tab bar** — iOS/Android standard, 3–5 tabs at screen bottom. Limited to 5 top-level destinations; thumb-friendly.
+- **Drawer + top header** — Slide-out drawer with a persistent top header bar. Supports many sections; discoverability issues — out of sight, out of mind.
+- **Stack navigation only** — Linear forward/back navigation with no persistent tabs. No quick access to unrelated sections; relies on back button.
+- **Tab bar + stack hybrid** — Bottom tabs for top-level sections, stack navigation within each tab. Combines discoverability with depth; tab count still limited.
+
+### Desktop (native) surfaces
+
+- **Menu bar + sidebar** — OS-native menu bar with sidebar panel. Platform-specific conventions differ (macOS vs Windows vs Linux).
+- **Ribbon (Office-style)** — Grouped toolbar with tabbed ribbon. Heavy initial learning curve; takes vertical space.
+- **Panel system** — Draggable/dockable panels with customizable layout. Window management complexity; steep learning curve.
+- **Sidebar only** — Vertical sidebar as sole navigation element. No menu bar discoverability for infrequent actions.
+
+---
+
+## Page Archetype Options
+
+| Archetype | Description | Typical Layout Zones |
+|-----------|-------------|---------------------|
+| **Dashboard** | Data overview with cards/charts | Nav zone · Summary strip · Grid/card zone · Detail panel |
+| **List → Detail** | Browse items, select to view/edit | Nav zone · Filter bar · List zone · Detail zone |
+| **Form** | Multi-step or single-page data entry | Nav zone · Form zone · Action bar |
+| **Content/Article** | Long-form reading with optional sidebar | Nav zone · Content zone · Sidebar/TOC zone |
+| **Settings** | Tabbed or sectioned preference panels | Nav zone · Section nav · Settings zone |
+| **Empty/Onboarding** | First-run or zero-data state | Nav zone · Illustration zone · CTA zone |
+| **Auth** | Login/signup/password-reset | Centered card zone · Background zone |
+| **Error** | 404/500/offline states | Nav zone · Error illustration zone · Recovery CTA |
+
+### Example wireframe (Dashboard archetype)
+
+```
+┌─────────────────────────────────────┐
+│              Nav Zone               │
+├────────┬────────────────────────────┤
+│        │       Summary Strip        │
+│  Side  ├────────────────────────────┤
+│  bar   │                            │
+│  Zone  │       Content Zone         │
+│        │                            │
+├────────┴────────────────────────────┤
+│            Action Bar               │
+└─────────────────────────────────────┘
+```
+
+---
+
+## Global Component Categories
+
+- **Navigation components** — derived from the navigation paradigm (e.g., TopNav, Sidebar, BottomTabBar, Breadcrumb)
+- **Layout components** — derived from archetypes (e.g., PageShell, ContentArea, Sidebar, ActionBar)
+- **Feedback components** — Loading skeleton, Toast, ErrorBoundary, EmptyState
+- **Form primitives** — Input, Select, Checkbox, Radio, TextArea, DatePicker, FileUpload
+- **Data display** — Table, Card, Badge, Avatar, Stat, Chart container
+- **Overlay components** — Modal, Drawer, Popover, Tooltip, ContextMenu
+- **Action components** — Button, IconButton, Link, Dropdown menu
+
+---
+
+## Motion Language Options
+
+| Level | Description | Typical Durations | Use When |
+|-------|-------------|-------------------|----------|
+| **Instant** | No transitions — all state changes are immediate | 0ms | Performance-critical tools, terminal UIs, accessibility-first products |
+| **Subtle** | Micro-transitions only — fades and opacity shifts | 100–150ms ease-out | Productivity tools, data-dense dashboards, professional/enterprise apps |
+| **Balanced** | Purposeful transitions for navigation and state changes | 150–300ms ease-in-out | Most consumer apps, SaaS products, general-purpose UIs |
+| **Rich** | Expressive animations — page transitions, element choreography, spring physics | 200–500ms spring/cubic-bezier | Marketing sites, creative tools, consumer apps where delight matters |
+
+> **Mandatory regardless of level**: All motion must respect `prefers-reduced-motion: reduce`. When reduced motion is active, all animations collapse to instant (0ms) or opacity-only transitions (≤100ms).
+
+---
+
+## Data Density Options
+
+| Philosophy | Description | Best For | Characteristics |
+|------------|-------------|----------|-----------------|
+| **Compact** | Maximum information per viewport — tight spacing, smaller text, dense tables | Data-heavy dashboards, admin panels, developer tools | 12–14px body text, 4–8px element spacing, minimal whitespace |
+| **Spacious** | Generous whitespace, larger text, breathing room between elements | Consumer apps, marketing, content-focused products | 16–18px body text, 16–24px element spacing, generous padding |
+| **Hybrid** | Context-dependent — compact for data tables/lists, spacious for forms/content | Apps mixing data overview with detail editing | Defined rules for when each density applies |
+
+If **Hybrid** is selected, ask the user to define the density rules:
+- Which archetypes get compact density?
+- Which archetypes get spacious density?
+- What is the transition behavior between densities?
+
+---
+
+## Global State Design Language Options
+
+### Loading states
+
+| Option | Description | Best For |
+|--------|-------------|----------|
+| **Skeleton screens** | Grey placeholder shapes matching the expected layout | Content-heavy pages where layout stability matters |
+| **Spinner/shimmer** | Centered spinner or shimmer overlay | Simple actions, modals, inline operations |
+| **Progressive** | Skeleton for page-level, spinner for component-level operations | Complex apps with mixed loading contexts |
+
+### Error states
+
+- **Inline** — Error message appears near the failed element (forms, field validation)
+- **Toast** — Transient notification for non-blocking errors (network retry, background sync)
+- **Full-page** — Dedicated error page (404, 500, offline)
+- **Error boundary** — Component-level fallback UI (prevents cascade, isolates failure)
+
+### Empty states
+
+- **Illustration + copy** — Custom illustration with descriptive text and CTA
+- **Minimal** — Text-only with action link
+- **Contextual** — Different empty states per archetype (empty dashboard vs. empty list)
+
+**Copy tone**: Helpful / Playful / Neutral — must align with the confirmed design direction.
+
+---
+
+## design-system.md Output Template
+
+The final `docs/plans/design-system.md` must have this exact structure:
+
+```markdown
+# Design System
+
+> **Confirmed Design Direction**: [confirmed direction from brand-guidelines]
+> **Date**: [YYYY-MM-DD]
+> **Status**: Locked
+
+## Navigation Paradigm
+[Confirmed paradigm with rationale]
+[Surface-specific notes if multi-surface project]
+
+## Layout Grid
+
+| Breakpoint | Columns | Gutter | Max Width |
+|------------|---------|--------|-----------|
+| Mobile (≤768px) | [confirmed] | [confirmed] | [confirmed] |
+| Tablet (769–1024px) | [confirmed] | [confirmed] | [confirmed] |
+| Desktop (≥1025px) | [confirmed] | [confirmed] | [confirmed] |
+
+**Grid type**: [confirmed]
+
+## Page Archetypes
+
+### [Archetype Name]
+**Layout zones**: [nav] | [content] | [sidebar] | [action]
+[Optional: ASCII wireframe for additional clarity]
+
+[repeat for each confirmed archetype]
+
+## Global Component Inventory
+- `<ComponentName>` — [what it does / what it renders]
+- `<ComponentName>` — [what it does / what it renders]
+[repeat for each confirmed global component]
+
+## Motion Language
+**Style**: [confirmed style — Instant / Subtle / Balanced / Rich]
+**Default duration**: [confirmed duration range]
+**Default easing**: [confirmed easing function]
+**Interaction transitions**: [confirmed interaction transition behavior]
+**Reduced-motion policy**: All animations disabled when `prefers-reduced-motion: reduce` is active.
+
+## Data Density Philosophy
+**Default density**: [confirmed density — Compact / Spacious / Hybrid]
+**Rules**: [when each density applies — per archetype if hybrid]
+
+## Global State Design Language
+
+### Loading States
+- **Skeleton screens**: use when [confirmed rule]
+- **Spinner/shimmer**: use when [confirmed rule]
+- **Progressive**: use when [confirmed rule]
+
+### Error States
+- **Inline errors**: use when [confirmed rule — e.g., form field validation]
+- **Toast errors**: use when [confirmed rule — e.g., non-blocking network errors]
+- **Full-page errors**: use when [confirmed rule — e.g., 404, 500, offline]
+- **Error boundaries**: use when [confirmed rule — e.g., component-level isolation]
+
+### Empty States
+**Illustration style**: [confirmed style]
+**Copy tone**: [confirmed tone — must align with confirmed design direction]
+**CTA**: Every empty state MUST include a primary call-to-action that guides the user toward populating the view.
+[Per-archetype empty state rules if contextual]
+```

package/template/.claude/skills/prd-templates/references/design-system-prerequisite-check.md

@@ -0,0 +1,18 @@
+# Design System Prerequisite Check
+
+Run this check before writing any FE spec.
+
+## Procedure
+
+1. Check whether `docs/plans/design-system.md` exists.
+2. If it does not exist → **stop** and tell the user: _"The design system has not been established yet. Run `/create-prd-design-system` to lock navigation paradigm, layout grid, page archetypes, and global state design language before writing FE specs."_
+3. If it exists → read and extract all seven decision areas: Navigation Paradigm, Layout Grid, Page Archetypes, Global Component Inventory, Motion Language, Data Density Philosophy, and Global State Design Language.
+4. The extracted decisions are **requirements** for this FE spec — any violation is a rubric failure under Dimension 11 (Design System Consistency).
+
+## Fail-Fast Validation Checks
+
+Verify the following before proceeding. If any check fails, classification must **stop** and instruct the user to run `/create-prd-design-system` to resolve drift before continuing:
+
+- **Page archetype match**: At least one page archetype from `design-system.md` applies to the feature being classified. If no archetype matches, the design system is incomplete for this feature.
+- **Global component / navigation compliance**: The navigation paradigm and Global Component Inventory sections are populated (not empty or placeholder). Every navigation element the FE spec will use must exist in the inventory — re-inventing global components is a rubric failure.
+- **Global state design language compliance**: The Loading States, Error States, and Empty States sub-sections are populated with confirmed approaches. The FE spec must use these confirmed patterns — inventing loading/error/empty state patterns outside the design language is a rubric failure.

package/template/.claude/skills/prd-templates/references/domain-exhaustion-criteria.md

@@ -0,0 +1,37 @@
+# Domain Exhaustion Criteria
+
+Final validation gate before vision compilation. All criteria must pass.
+
+| Check | Criteria | Action if Fail |
+|-------|----------|----------------|
+| All leaf nodes ≥ `[DEEP]` | Every feature file in the tree is `[DEEP]` or `[EXHAUSTED]` | Drill remaining feature files |
+| Status propagation correct | Parent nodes reflect their children's status | Update parent indexes |
+| All Must Have features ≥ Level 2 | Every Must Have has sub-features AND edge cases AND Role Lens | Deep Think + drill |
+| Deep Think zero hypotheses | Final Deep Think pass across ALL leaf nodes yields no new hypotheses | Present any new hypotheses, drill if confirmed |
+| All CX files clean | No Medium/Low confidence entries remain at any level — all are High or rejected | Run synthesis questions on pending pairs |
+| Role Lens complete | Every feature file has a populated Role Lens table | Fill missing Role Lens entries |
+| User confirmation | User explicitly confirms "nothing else" for each domain | Ask for each under-explored domain |
+
+## Execution Procedure
+
+1. Walk the fractal tree. For each leaf node below `[DEEP]`:
+   - "Feature [X] in [domain] is still at [status]. Drill deeper or intentionally minimal?"
+   - If "drill" → return to `/ideate-discover`
+   - If "intentionally minimal" → note in feature file and proceed
+
+2. Run **final Deep Think pass**: For each `[DEEP]` leaf node, apply the four Deep Think questions. Present any new hypotheses.
+   - If confirmed → drill, update feature files
+   - If zero hypotheses → mark `[EXHAUSTED]`, propagate status upward
+
+3. Walk ALL CX files at every level. Resolve any Medium/Low confidence entries.
+
+4. Verify all feature files have populated Role Lens tables.
+
+5. Update `ideation-index.md` progress summary with final counts (total leaf nodes, exhausted count, CX entries confirmed).
+
+## Proportionality Check
+
+- **Rich inputs**: Total domain file content (all files combined) should be at least 30% of the original source document's line count. If short, identify what was lost.
+- **All inputs**: Each domain with `[DEEP]` or `[EXHAUSTED]` status should have at least 3 sub-areas drilled with edge cases.
+
+If proportionality fails, return to `/ideate-discover` for the under-explored areas.

package/template/.claude/skills/prd-templates/references/engagement-tier-protocol.md

@@ -0,0 +1,58 @@
+# Engagement Tier Protocol
+
+**Purpose**: Single source of truth for engagement tier definitions and behavior. Workflows reference this instead of inlining tier blocks.
+
+---
+
+## Tier Definitions
+
+| Tier | When | User Experience |
+|------|------|-----------------|
+| **Auto** | 6+ well-constrained axes, experienced user, clear preferences | Agent uses Deep Think reasoning per axis, presents all decisions for batch review at shard end |
+| **Hybrid** | 3-5 axes, some need discussion, some are obvious | Group related decisions, present key choices, auto-confirm obvious ones |
+| **Interactive** | ≤2 axes, novel/uncertain domain, user requests it | Full interview — one decision at a time with options and trade-offs |
+
+## Tier Selection
+
+Read the user's context:
+1. Count the number of decision axes in the current step
+2. Assess user's familiarity (prior conversations, explicit preferences, technical depth)
+3. Default to **Interactive** if uncertain
+
+Present the proposed tier: "I'll approach this as [tier] — [brief rationale]. Want a different level of involvement?"
+
+**HARD GATE**: Wait for user acknowledgment before proceeding. If the user requests a different tier, switch.
+
+## Behavior by Tier
+
+### Auto Tier
+1. For each decision: apply Deep Think reasoning (consider constraints, project goals, prior decisions)
+2. Write the decision with `[AUTO-CONFIRMED — reasoning: ...]` annotation
+3. At shard end: present ALL auto-confirmed decisions in a summary table
+4. User reviews batch — any rejection triggers Interactive re-presentation for that decision
+5. Remove `[AUTO-CONFIRMED]` annotations after batch approval
+
+### Hybrid Tier
+1. Group related decisions (e.g., all auth decisions together)
+2. For obvious decisions: present with recommendation, apply if user says "looks good"
+3. For debatable decisions: present options with trade-offs, wait for selection
+4. Follow the decision-confirmation-protocol for each group
+
+### Interactive Tier
+1. Present one decision at a time
+2. Include 2-3 options with trade-offs and your recommendation
+3. Wait for explicit selection
+4. Follow the decision-confirmation-protocol for each decision
+
+## Gate Classification
+
+Not all decisions follow the engagement tier. Some are always user-facing regardless of tier:
+
+| Gate Type | Always Interactive? | Examples |
+|-----------|-------------------|----------|
+| **Product** | Yes — user always decides | Feature scope, UX philosophy, pricing |
+| **Architecture** | Yes — present options | Database choice, framework, hosting |
+| **Structural** | No — tier-aware | File naming, directory organization |
+| **Implementation** | No — agent decides | Import ordering, variable naming |
+
+See `.agent/rules/decision-classification.md` for the full classification.