cfsa-antigravity 2.1.0 → 2.2.0

package/template/.agent/workflows/validate-phase-readiness.md

@@ -0,0 +1,167 @@
+---
+description: Production readiness gates — API docs, accessibility, performance, security, dependency audit, results for the validate-phase workflow
+parent: validate-phase
+shard: readiness
+standalone: true
+position: 2
+pipeline:
+  position: 8.2
+  stage: verification
+  predecessors: [validate-phase-quality]
+  successors: [update-architecture-map]
+  skills: [adversarial-review, security-scanning-security-hardening, verification-before-completion]
+  calls-bootstrap: false
+---
+
+// turbo-all
+
+# Validate Phase — Production Readiness Gates
+
+Run all production readiness checks for a completed implementation phase.
+
+**Prerequisite**: Code quality gates (from `/validate-phase-quality` or equivalent) must pass first.
+
+---
+
+## 5.9. API documentation sync (surfaces with API endpoints)
+
+Read the surface stack map from `.agent/instructions/tech-stack.md`. **Skip this step** if the project has no API surface and no BE endpoints exposed to external consumers.
+
+1. Read `docs/plans/ENGINEERING-STANDARDS.md` → `## Code Quality` → `Required documentation` field
+2. If API documentation is required or the project exposes public API endpoints:
+   - Verify an OpenAPI spec file exists (e.g., `openapi.yaml`, `openapi.json`, or a generated equivalent)
+   - If the project uses a schema-first or code-first generation approach (documented in architecture-design.md), verify the generation tool produces output matching the implemented endpoints
+   - For each new endpoint in this phase, verify it appears in the OpenAPI spec with:
+     - Request body schema matching the {{CONTRACT_LIBRARY}} contract
+     - Response schema matching the contract
+     - All error codes documented
+   - Run OpenAPI linter if configured (e.g., the tool named in ENGINEERING-STANDARDS.md or the project's `lint` scripts)
+3. If API documentation is not required and no public API surface exists → skip
+
+**Pass criteria**: OpenAPI spec exists and is in sync with implemented contracts for this phase's endpoints, or API documentation is not applicable.
+
+---
+
+## 6. Accessibility audit (if UI changes)
+
+Audit all new UI components in this phase for WCAG 2.1 AA compliance using the Accessibility skill(s) from the cross-cutting section.
+
+## 7. Performance check
+
+### 7a. Performance budget verification (mandatory when budgets are defined)
+
+Read `docs/plans/ENGINEERING-STANDARDS.md` section `## Performance Budgets`.
+
+**If the section does not exist or contains only unfilled template placeholders** → Log: "No performance budgets defined in ENGINEERING-STANDARDS.md — skipping budget verification." Proceed to 7b.
+
+**If budgets are defined**, read the `### CI Enforcement` table. For each row where the enforcement tool is named:
+
+1. Check if the named enforcement tool is installed/available in the project
+2. **If tool is available** → run it against the staging deployment (from Step 5.6) using the thresholds in the corresponding budget table:
+   - **Web Vitals** (LCP, INP, CLS) → run against staging URLs, one per page type defined in the budget
+   - **JS Bundle Size** → measure build output against per-page-type caps
+   - **API Response Time** → run the named load test tool with a baseline scenario against staging endpoints
+   - **DB Query Time** → run EXPLAIN ANALYZE (or equivalent) on critical queries and verify against tier thresholds
+   - **Desktop/Mobile/CLI metrics** → run the named platform profiler against the built artifact
+3. **If tool is not available** → log which tool is missing and recommend installation, but do not block
+
+**Verdict per budget row**:
+- `Fail` classification in CI Enforcement table AND threshold exceeded → **STOP.** Mark step 7a as `❌`. The phase cannot pass until budgets are met.
+- `Warn` classification AND threshold exceeded → Log as a finding, do not block.
+- Tool not available → Log as a finding, do not block, recommend installation.
+
+**Pass criteria**: All `Fail`-classified budgets pass their thresholds. All `Warn`-classified findings are logged.
+
+### 7b. Deep performance audit (optional)
+
+Check if the `performance-optimization` skill is installed (look for `.agent/skills/performance-optimization/SKILL.md`).
+
+**If installed**:
+1. Read `.agent/skills/performance-optimization/SKILL.md`
+2. Run the skill's audit protocol against the phase's changed pages/routes/endpoints
+3. Compare results to the targets in `docs/plans/ENGINEERING-STANDARDS.md` (response time budgets, bundle sizes, memory limits, or other surface-appropriate metrics)
+4. Report any metrics that exceed the defined thresholds
+
+**If not installed**:
+- Manually verify that no obviously expensive operations were added (large synchronous imports, unoptimized assets, missing lazy loading, N+1 queries, unbounded loops)
+- If performance is critical for this project, recommend installing the skill via `find-skills`
+
+## 8. Security review
+
+Read .agent/skills/adversarial-review/SKILL.md and follow its structured methodology for generating attack scenarios, abuse cases, and race conditions against the phase's changes. Produce spec-level gap items for any identified risks. Feed these into the defense-in-depth audit below.
+
+Read .agent/skills/security-scanning-security-hardening/SKILL.md and run its full defense-in-depth audit protocol against the phase's changes (new endpoints, new data flows, new auth checks). Report findings with severity levels. Block the phase if any Critical or High severity issues are found.
+
+**Supplemental security checks (conditional)**: After the core audit completes, read the Security skill(s) from the cross-cutting section of the surface stack map. For each listed skill directory name, read `.agent/skills/[skill]/SKILL.md` and run its audit protocol as a supplement to the core audit.
+
+Report any additional findings from supplemental audits with the same severity classification.
+
+**Surface-conditional DAST scan (if applicable)**: Read `docs/plans/ENGINEERING-STANDARDS.md` → `## Security` → `Security testing tool` field. If a DAST or security scanning tool is defined:
+1. Run it against the staging deployment from Step 5.6
+2. Report findings with severity levels consistent with the core audit
+3. Block the phase if any Critical or High severity findings are discovered
+
+If no security testing tool is defined in ENGINEERING-STANDARDS → skip and log: "No DAST/security testing tool configured."
+
+## 8.5. Dependency audit
+
+### Core audit (mandatory — no skill required)
+
+Run the package manager's built-in vulnerability audit tool. Use the appropriate command for the project's language/package manager:
+
+| Package Manager | Audit Command |
+|----------------|---------------|
+| npm | `npm audit --audit-level=high` |
+| pnpm | `pnpm audit --audit-level=high` |
+| yarn | `yarn npm audit --severity high` |
+| pip | `pip-audit` or `safety check` |
+| cargo | `cargo audit` |
+| go | `govulncheck ./...` |
+| bundler | `bundle audit check` |
+| composer | `composer audit` |
+
+If the project uses a package manager not listed above, check its documentation for a built-in vulnerability audit command.
+
+**If any HIGH or CRITICAL vulnerabilities are found in production dependencies** → **STOP.** Mark step 8.5 as `❌`. List affected packages and recommended fixes (upgrade version, patch, or replace).
+
+**If only LOW or MODERATE vulnerabilities are found** → Log as findings, do not block.
+
+**If the audit tool is not available** (e.g., language has no built-in audit) → Log: "No built-in dependency audit available for [language]. Recommend installing a dependency auditing tool." Do not block.
+
+### Supplemental audit (conditional)
+
+If the `dependency-auditing` skill is installed (`.agent/skills/dependency-auditing/SKILL.md`):
+1. Read the skill and run its full audit protocol (Snyk, Socket.dev, SBOM generation, lockfile integrity)
+2. Report any additional findings with severity levels
+
+**Pass criteria**: Zero HIGH/CRITICAL vulnerabilities in production dependencies.
+
+## 9. Document results
+
+**Note on report file**: `docs/audits/phase-N-validation.md` is written progressively. Step 5.8 creates the file and appends the `## Spec Coverage` section. Step 9 appends all remaining sections. Do not recreate or overwrite the file in Step 9 — append only.
+
+- Test results and coverage
+- Lint and type-check status
+- Build status
+- Accessibility findings
+- Performance budget results (7a) and deep audit findings (7b)
+- Security review findings (including DAST results if applicable)
+- Dependency audit results
+- API documentation sync status (if applicable)
+- Deployment strategy compliance (if applicable)
+- CI/CD pipeline status
+- Staging deployment result
+- Migration verification status
+- Pass/fail verdict
+
+## 10. Present results and next steps
+
+Read .agent/skills/verification-before-completion/SKILL.md and follow its methodology.
+
+Use `notify_user` to present the validation report.
+
+### Proposed next steps
+
+- **If all checks pass**: "Phase N validation complete. Next: Run `/update-architecture-map` to ensure the project's living architecture document is up-to-date."
+- **If any checks fail**: "Fix the failures listed in the validation report and re-run `/validate-phase` for Phase N."
+- **If new requirements were discovered during validation** (scope gaps, missing features, behavioral corrections): Use `/evolve-feature` to add them at the correct entry point layer. Do not attempt to add them directly to specs — evolution must go through the classify → cascade flow to maintain layer consistency.

package/template/.agent/workflows/validate-phase.md

@@ -8,6 +8,7 @@ pipeline:
   loop: true # one validate per phase
   skills: [adversarial-review, code-review-pro, deployment-procedures, security-scanning-security-hardening, testing-strategist, verification-before-completion]
   calls-bootstrap: false
+shards: [validate-phase-quality, validate-phase-readiness]
 ---
 
 // turbo-all
@@ -16,172 +17,36 @@ pipeline:
 
 Comprehensive validation of a completed implementation phase.
 
----
-
-## 0. Load validation skills
-
-Read these skills before running checks:
-1. `.agent/skills/testing-strategist/SKILL.md` — Coverage strategy and test quality
-2. `.agent/skills/code-review-pro/SKILL.md` — Review checklist for self-audit
-3. `.agent/skills/deployment-procedures/SKILL.md` — Build and release readiness
+**Input**: A completed phase with all slices implemented
+**Output**: Validation report with pass/fail verdict
 
 ---
 
-## 0.5. Parallel dispatch option
-
-If the phase contains independent slices that don't share files, validation can run in parallel:
-
-1. **Identify independent slices** — slices that don't import from or export to each other
-2. **Dispatch parallel validation** — run Steps 1–5 concurrently for independent slices using the `parallel-agents` skill
-3. **Sequential for shared** — slices that share contracts or utilities must validate sequentially
-
-This is an optimization, not a requirement. Sequential validation is always correct.
-
-## 1. Run test suite
-
-Run the Test Cmd from `.agent/instructions/commands.md`. All tests must pass. Zero tolerance.
-
-## 2. Check coverage
-
-Run the Test Coverage Cmd from `.agent/instructions/commands.md`.
-
-Read `docs/plans/ENGINEERING-STANDARDS.md` and use the coverage thresholds defined in the "Test Coverage" section. If the file doesn't exist or thresholds aren't defined, fall back to these defaults:
-- Statements: 80%
-- Branches: 90% (critical paths: auth, payments, data mutations, permission checks), 75% (non-critical paths)
-- Functions: 80%
-- Lines: 80%
-
-Critical paths are defined as: auth flows, payment processing, data mutations, and permission/authorization checks.
-
-## 2.5. Mutation testing (critical paths)
-
-**Optional but recommended.** If the project's test tooling supports mutation testing (e.g., Stryker for JS/TS, mutmut for Python, cargo-mutants for Rust):
+## Shard Overview
 
-1. Run the mutation testing tool against critical path modules only (auth, payments, data mutations, permission checks)
-2. **Required**: Mutation score ≥ 70% on critical paths — if below, the tests are passing but not actually catching bugs
-3. **Recommended**: Mutation score ≥ 50% on non-critical paths — log as a finding but don't block
-
-If mutation testing is not available in the project's tooling, skip and note in the validation report that mutation testing was not run.
-
-## 3. Lint
-
-Run the Lint Cmd from the surface stack map.
-
-Zero lint errors. Warnings should be reviewed and addressed.
-
-## 4. Type check
-
-Run the Type Check Cmd from the surface stack map.
-
-Zero type errors. Strict mode must be enabled.
-
-## 5. Build
-
-Run the Build Cmd from the surface stack map.
-
-Build must succeed with no errors.
+| # | Shard | What It Does |
+|---|-------|-------------|
+| 1 | [`validate-phase-quality`](.agent/workflows/validate-phase-quality.md) | Code quality gates: tests, coverage, mutation testing, lint, type-check, build, CI/CD, staging deploy, deployment strategy, migrations, spec coverage |
+| 2 | [`validate-phase-readiness`](.agent/workflows/validate-phase-readiness.md) | Production readiness gates: API doc sync, accessibility, performance budgets, security review, DAST, dependency audit, results documentation, next steps |
 
 ---
 
-## 5.5. CI/CD pipeline verification
+## Orchestration
 
-Verify the CI/CD pipeline is green for this phase's changes:
+### Step A — Run `.agent/workflows/validate-phase-quality.md`
 
-1. Check that a CI/CD configuration file exists (e.g., `.github/workflows/`, `.gitlab-ci.yml`)
-2. Verify the pipeline has run for the latest commit in this phase
-3. Verify ALL CI/CD jobs are passing (not just the test job — include lint, type-check, build, and any deployment jobs)
+Loads validation skills, runs all code quality checks (tests, coverage, mutation testing, lint, type-check, build), verifies CI/CD pipeline, deploys to staging, verifies deployment strategy compliance, checks migrations, and runs the spec coverage sweep.
 
-**If CI/CD is red** → red path: **STOP immediately.** Do not mark this phase as complete. List the failing jobs and their error output. Fix them and re-run `/validate-phase` after fixes.
+### Step B — Run `.agent/workflows/validate-phase-readiness.md`
 
-**Pass criteria**: CI/CD pipeline is green for the latest commit in this phase.
+Runs production readiness checks: API documentation sync, accessibility audit, performance budget enforcement, deep performance audit, security review (including surface-conditional DAST), dependency supply chain audit. Documents all results and presents the validation report with next steps.
 
 ---
 
-## 5.6. Staging deployment gate
-
-1. Deploy to staging using `.agent/skills/deployment-procedures/SKILL.md`
-2. Verify deployment succeeded (no rollback triggered, no error logs in the deployment output)
-3. Run smoke tests against the staging environment:
-   - Health check endpoint returns 200
-   - At least one authenticated route works with a valid token
-   - At least one protected route returns 401/403 for unauthenticated requests
-4. **If smoke tests fail** → red path: Capture the failing test output, rollback the staging deployment, and fix the issue before re-running `/validate-phase`
-5. **If deployment fails** → red path: Do not mark this phase as complete — diagnose the deployment failure, fix it, and re-run `/validate-phase`
-
-**Pass criteria**: Staging deployment succeeds and all smoke tests pass.
-
----
-
-## 5.7. Migration verification
-
-1. Run the migration status command (e.g., `prisma migrate status`, `drizzle-kit status`, or equivalent)
-2. Verify there are no pending migrations and no failed migrations
-3. Verify the CI/CD pipeline ran migrations successfully as part of this phase's deployment
-4. Check that rollback scripts exist for each migration in this phase
-5. If migrations are pending or failed → red path: do not mark this phase as complete — run the pending migrations, verify they succeed, and re-run `/validate-phase`
-
-**Pass criteria**: Migration status is clean. All migrations from this phase ran successfully in the CI/CD environment. Rollback scripts are present.
-
----
-
-## 5.8. Spec coverage sweep
-
-Read `.agent/skills/prd-templates/references/spec-coverage-sweep.md` and follow its full procedure for FE spec, BE spec, and IA shard coverage. Apply its hard-stop rule for any uncovered items.
-
----
-
-## 6. Accessibility audit (if UI changes)
-
-Audit all new UI components in this phase for WCAG 2.1 AA compliance using the Accessibility skill(s) from the cross-cutting section.
-
-## 7. Performance check
-
-Check if the `performance-optimization` skill is installed (look for `.agent/skills/performance-optimization/SKILL.md`).
-
-**If installed**:
-1. Read `.agent/skills/performance-optimization/SKILL.md`
-2. Run the skill's audit protocol against the phase's changed pages/routes/endpoints
-3. Compare results to the targets in `docs/plans/ENGINEERING-STANDARDS.md` (response time budgets, bundle sizes, memory limits, or other surface-appropriate metrics)
-4. Report any metrics that exceed the defined thresholds
-
-**If not installed**:
-- Note: "No performance optimization skill installed. Skipping automated performance audit."
-- Manually verify that no obviously expensive operations were added (large synchronous imports, unoptimized assets, missing lazy loading, N+1 queries, unbounded loops)
-- If performance is critical for this project, recommend installing the skill via `find-skills`
-
-## 8. Security review
-
-Read .agent/skills/adversarial-review/SKILL.md and follow its structured methodology for generating attack scenarios, abuse cases, and race conditions against the phase's changes. Produce spec-level gap items for any identified risks. Feed these into the defense-in-depth audit below.
-
-Read .agent/skills/security-scanning-security-hardening/SKILL.md and run its full defense-in-depth audit protocol against the phase's changes (new endpoints, new data flows, new auth checks). Report findings with severity levels. Block the phase if any Critical or High severity issues are found.
-
-**Supplemental security checks (conditional)**: After the core audit completes, read the Security skill(s) from the cross-cutting section of the surface stack map. For each listed skill directory name, read `.agent/skills/[skill]/SKILL.md` and run its audit protocol as a supplement to the core audit.
-
-Report any additional findings from supplemental audits with the same severity classification.
-
-## 9. Document results
-
-**Note on report file**: `docs/audits/phase-N-validation.md` is written progressively. Step 5.8 creates the file and appends the `## Spec Coverage` section. Step 9 appends all remaining sections. Do not recreate or overwrite the file in Step 9 — append only.
-
-- Test results and coverage
-- Lint and type-check status
-- Build status
-- Accessibility findings
-- Performance findings
-- Security review findings
-- CI/CD pipeline status
-- Staging deployment result
-- Migration verification status
-- Pass/fail verdict
-
-## 10. Present results and next steps
-
-Read .agent/skills/verification-before-completion/SKILL.md and follow its methodology.
-
-Use `notify_user` to present the validation report.
-
-### Proposed next steps
+## Quality Gate
 
-- **If all checks pass**: "Phase N validation complete. Next: Run `/update-architecture-map` to ensure the project's living architecture document is up-to-date."
-- **If any checks fail**: "Fix the failures listed in the validation report and re-run `/validate-phase` for Phase N."
-- **If new requirements were discovered during validation** (scope gaps, missing features, behavioral corrections): Use `/evolve-feature` to add them at the correct entry point layer. Do not attempt to add them directly to specs — evolution must go through the classify → cascade flow to maintain layer consistency.
+You may not call `notify_user` until:
+- [ ] All code quality checks pass (Shard 1)
+- [ ] All production readiness checks pass (Shard 2)
+- [ ] Validation report written to `docs/audits/phase-N-validation.md`
+- [ ] Pass/fail verdict determined

package/template/.agent/workflows/write-architecture-spec-design.md

@@ -46,9 +46,13 @@ Before loading skills, check whether the shard file at `docs/plans/ia/[shard-nam
 
 ### 1a. Read the authoritative sources
 
-Read the following files and build a **reconciliation table** comparing what each source says about this shard's features. Use the `ideation-index.md` Domain Documents table to find the correct domain file path (may be in `domains/` or `surfaces/{name}/` for multi-product projects). The ideation domain file is the **primary source of truth** for sub-features — the architecture design is secondary context.
+Read the following files and build a **reconciliation table** comparing what each source says about this shard's features. Use the `ideation-index.md` Structure Map to find the correct domain folder path (may be under `domains/` or `surfaces/{name}/` for multi-product projects). The ideation domain's feature files are the **primary source of truth** for sub-features — the architecture design is secondary context.
 
-1. The relevant ideation domain file for this shard (path from `ideation-index.md` Domain Documents table)
+1. The relevant ideation domain folder for this shard (path from `ideation-index.md` Structure Map):
+   - Read the domain's `*-index.md` for the children table and Role Matrix
+   - Read each child **feature `.md` file** for sub-feature details (Role Lens, behavior, edge cases)
+   - Read the domain's `*-cx.md` for cross-domain interactions relevant to this shard
+   - If the domain has sub-domain folders, recurse into them and aggregate all descendant feature files
 2. The shard's `## Features` section (from `/decompose-architecture-structure`)
 3. `docs/plans/ideation/ideation-index.md` — Must Have features for this domain
 
@@ -61,8 +65,8 @@ Present the reconciled `## Features` list to the user, including a count of newl
 > **Reconciled features for [Shard NN — Domain Name]:**
 > [bullet list of all sub-features, with `[Architecture-only]` markers]
 > 
-> **[N] sub-features added from ideation domain file** that were missing from the shard skeleton.
-> **[M] sub-features marked `[Architecture-only]`** — not found in ideation domain file, added during decomposition.
+> **[N] sub-features added from ideation domain tree** that were missing from the shard skeleton.
+> **[M] sub-features marked `[Architecture-only]`** — not found in ideation domain tree, added during decomposition.
 > 
 > "Does this feature list match your intent for this domain? Any sub-features to add, remove, or re-scope?"
 

package/template/AGENTS.md

@@ -76,12 +76,16 @@ Once a stage is locked, downstream stages may not contradict it. To change a loc
 | ↳ | `/evolve-feature-classify` | Feature description | Classified change + new content at entry point | Evolution |
 | ↳ | `/evolve-feature-cascade` | Classified change + entry point | Layer-by-layer additions + implementation impact | Evolution |
 | 8 | `/plan-phase` | Architecture + specs | Dependency-ordered TDD slices | Planning |
+| ↳ | `/plan-phase-preflight` | Approved specs | Phase gate + completeness audit + consistency check | Planning |
+| ↳ | `/plan-phase-write` | Preflight pass | Slices + acceptance criteria + progress files | Planning |
 | 9 | `/implement-slice` | Slice acceptance criteria | Working code via Red→Green→Refactor | Implementation |
 | ↳ | `/implement-slice-setup` | Slice from phase plan | Progress check + skills + contracts + parallel mode | Implementation |
 | ↳ | `/implement-slice-tdd` | Contract + tests | Red→Green→Refactor + validation + progress tracking | Implementation |
 | 9.5 | `/verify-infrastructure` | Implemented infra or auth slice | Operational verification report | Verification |
 | 10 | `/validate-phase` | Completed phase | Full validation gate | Verification |
-| 11 | `/evolve-contract` | Changed Zod schema | Safe schema migration | Maintenance |
+| ↳ | `/validate-phase-quality` | Completed phase | Code quality gates — tests, coverage, lint, type-check, build, CI/CD, staging, migrations, spec coverage | Verification |
+| ↳ | `/validate-phase-readiness` | Quality gates passed | Production readiness gates — API docs, accessibility, performance, security, dependency audit, results | Verification |
+| 11 | `/evolve-contract` | Changed `{{CONTRACT_LIBRARY}}` schema | Safe schema migration | Maintenance |
 
 > **Note**: Rows marked with ↳ are independently-invocable sub-workflows (shards)
 > of their parent command. The parent orchestrates them in sequence, but each shard

package/template/GEMINI.md

@@ -83,6 +83,8 @@ Once a stage is locked, downstream stages may not contradict it. To change a loc
 | ↳ | `/implement-slice-tdd` | Contract + tests | Red→Green→Refactor + validation + progress tracking | Implementation |
 | 7.5 | `/verify-infrastructure` | Implemented infra or auth slice | Operational verification report | Verification |
 | 10 | `/validate-phase` | Completed phase | Full validation gate | Verification |
+| ↳ | `/validate-phase-quality` | Completed phase | Code quality gates — tests, coverage, lint, type-check, build, CI/CD, staging, migrations, spec coverage | Verification |
+| ↳ | `/validate-phase-readiness` | Quality gates passed | Production readiness gates — API docs, accessibility, performance, security, dependency audit, results | Verification |
 | 11 | `/evolve-contract` | Changed `{{CONTRACT_LIBRARY}}` schema | Safe schema migration | Maintenance |
 
 

package/template/docs/README.md

@@ -35,19 +35,19 @@ The pipeline is a linear sequence of commands. Each step tells you what to run n
       You describe your idea (or point to a document with @file).
       The pipeline explores your idea using recursive breadth-before-depth:
         - Level 0: Maps all domains in your product
-        - Level 1: Sweeps sub-areas within each domain
+        - Level 1: Sweeps each domain for sub-areas (Classification Gate: sub-domain folder or feature file?)
         - Level 2+: Drills vertically until each domain is exhausted
       At every level, a Deep Think protocol generates hypotheses based on
       domain knowledge — "Based on this industry, I'd expect X. Is that relevant?"
-      Cross-cutting concerns are tracked continuously in a dedicated ledger.
-      Each domain gets its own file the moment it's discovered (shard-as-you-go).
-
-      Output: docs/plans/ideation/ folder:
-                ideation-index.md   ← pipeline key file (domain map, MoSCoW, coverage)
-                domains/*.md        ← one file per domain
-                meta/*.md           ← problem, personas, constraints, competitive landscape
-                cross-cuts/         ← cross-cut ledger
-              docs/plans/vision.md  ← human-readable executive summary (not a pipeline input)
+      Cross-cutting concerns are tracked at the level where they occur (CX files).
+      Each domain gets its own folder the moment it's discovered (fractal-as-you-go).
+
+      Output: docs/plans/ideation/ folder (fractal tree):
+                ideation-index.md      ← pipeline key file (structure map, MoSCoW, coverage)
+                ideation-cx.md         ← global cross-cuts
+                domains/*/             ← domain folders (index + CX + feature files)
+                meta/*.md              ← problem, personas, constraints, competitive landscape
+              docs/plans/vision.md     ← human-readable executive summary (not a pipeline input)
 
     Step 2: /audit-ambiguity ideation  ── MANDATORY ──
       Scores the ideation folder against a 12-dimension rubric.

package/template/docs/kit-architecture.md

@@ -32,36 +32,87 @@ The intelligence of the kit lives entirely within the `.agent/` directory.
 
 ## 2. Ideation Architecture
 
-The ideation layer is the pipeline's first output and the source of truth for all downstream specification work. It replaces the former monolithic `vision.md` approach with a sharded folder structure that scales with project complexity.
+The ideation layer is the pipeline's first output and the source of truth for all downstream specification work. It uses a **fractal folder structure** — every node (surface, domain, sub-domain) is a folder containing an index file, a cross-cut (CX) file, and its children. Leaf nodes are `.md` feature files. This pattern is universal regardless of project complexity.
 
 ### Pipeline Key File
 
-`docs/plans/ideation/ideation-index.md` is the **pipeline key file** — the primary entry point for all downstream workflows. When `/create-prd`, `/decompose-architecture`, or any specification workflow needs to understand the product, it reads `ideation-index.md` first, then follows links to relevant domain files for detail.
+`docs/plans/ideation/ideation-index.md` is the **pipeline key file** — the primary entry point for all downstream workflows. When `/create-prd`, `/decompose-architecture`, or any specification workflow needs to understand the product, it reads `ideation-index.md` first, then follows links into the fractal tree.
 
 `docs/plans/vision.md` still exists but is a **human-readable executive summary** only — a sales pitch compiled from the ideation folder. No downstream workflow reads it as a data source.
 
-### Folder Structure
+### Structural Classification (4 Project Shapes)
+
+During `/ideate-extract`, every project is classified into one of four shapes that governs folder layout:
+
+| Shape | When | Folder Pattern |
+|-------|------|----------------|
+| `single-surface` | One surface (e.g., web app only) | Flat `domains/` at top level |
+| `multi-surface-shared` | Multiple surfaces sharing the same backend (e.g., web + mobile) | Flat `domains/` with surface annotations in feature files |
+| `multi-product-hub` | One primary surface owns most logic; others consume it | Primary surface's folder owns shared domains; others reference them |
+| `multi-product-peer` | Independent products with shared infrastructure | `shared/` folder for shared domains; surface folders for exclusive domains |
+
+### Fractal Folder Structure
 
 ```text
 docs/plans/ideation/
-├── ideation-index.md          # Pipeline key file — domain map, MoSCoW summary, coverage
-├── domains/                   # One file per product domain
-│   ├── user-management.md
-│   ├── billing.md
-│   └── ...
+├── ideation-index.md          # Super-index — shape, structure map, MoSCoW, progress
+├── ideation-cx.md             # Global CX — cross-surface interactions (if multi-product)
+├── domains/                   # Top-level domains (single/multi-surface-shared)
+│   ├── 01-user-management/    # Each domain is a FOLDER, not a file
+│   │   ├── user-management-index.md   # Children table, Role Matrix, decisions
+│   │   ├── user-management-cx.md      # Cross-cuts between this domain's children
+│   │   ├── 01-registration.md         # Leaf feature file (Role Lens, behavior, edge cases)
+│   │   ├── 02-authentication/         # Sub-domain (promoted from feature if complex)
+│   │   │   ├── authentication-index.md
+│   │   │   ├── authentication-cx.md
+│   │   │   ├── 01-login.md
+│   │   │   └── 02-password-reset.md
+│   │   └── 03-roles.md
+│   └── 02-billing/
+│       ├── billing-index.md
+│       ├── billing-cx.md
+│       └── ...
 ├── meta/                      # Structured metadata
 │   ├── problem-statement.md
 │   ├── personas.md
 │   ├── constraints.md
 │   └── competitive-landscape.md
-└── cross-cuts/                # Cross-cutting concern tracking
-    └── cross-cut-ledger.md
+└── [surfaces/]                # Only for multi-product-hub or multi-product-peer
+    ├── web/
+    │   ├── web-index.md
+    │   ├── web-cx.md
+    │   └── 01-dashboard/...
+    └── mobile/
+        ├── mobile-index.md
+        ├── mobile-cx.md
+        └── 01-notifications/...
 ```
 
 **Key properties:**
-- **Shard-as-you-go**: Domain files are created the moment a domain is identified during exploration, not batched after all exploration is complete
-- **Living documents**: Domain files and the index are updated in place as exploration deepens — they are never dated (see Dated File Convention below)
-- **Downstream consumers**: `/create-prd` reads `ideation-index.md` + `meta/constraints.md`; `/decompose-architecture` reads `ideation-index.md` + domain files; specification workflows reference domain files for sub-feature detail
+- **Fractal pattern**: Every folder has an index + CX file. Every leaf is a feature `.md` file. This is universal — no exceptions.
+- **Reactive depth**: Folders are created during exploration when complexity is discovered, not pre-scaffolded. A feature file can be promoted to a sub-domain folder if it reveals internal complexity.
+- **Numbering**: Children are numbered `{NN}-{slug}` within their parent. Paths are expressed as dot-separated (e.g., `01.02.03` = domain 01, sub-domain 02, feature 03).
+- **Soft depth limit**: 4 levels recommended. Level 5 triggers a user prompt to confirm structured complexity isn't runaway nesting.
+
+### Role Integration
+
+Roles (personas) are defined once in `meta/personas.md` and then referenced at every level of the tree:
+
+| Location | What | Purpose |
+|----------|------|---------|
+| `meta/personas.md` | Full persona definitions (6 fields each) | Single source of truth |
+| Node index files | **Role Matrix** — which personas access which children | Structural overview of role coverage |
+| Feature files | **Role Lens** — per-persona behavior details | Downstream input for IA/BE/FE multitenancy specs |
+
+### Node Classification Gate
+
+Before creating any new node (domain, sub-domain, or feature), the agent runs a classification gate:
+
+1. **What is it?** — Domain (top-level concept), sub-domain (2+ interacting capabilities), or feature (single capability)
+2. **Where does it go?** — Surface-exclusive, hub-owned, shared, or top-level (depends on project shape)
+3. **Does it already exist?** — Check for duplicates before creating
+
+This prevents incorrect domain placement — the primary failure mode of the old flat structure.
 
 ### Exploration Model
 
@@ -69,20 +120,20 @@ The `/ideate` workflow uses **recursive breadth-before-depth exploration**:
 
 | Level | Scope | What happens |
 |---|---|---|
-| **Level 0** | Global domain map | Identify all top-level domains in the product. Each gets a file in `domains/`. |
-| **Level 1** | Sub-area sweep per domain | For each domain, identify all sub-areas. Mark each with a depth status marker. |
-| **Level 2+** | Vertical drilling | Drill into each sub-area until no new information emerges. Recursion: new domains discovered during drilling loop back to Level 0. |
+| **Level 0** | Global domain map | Identify all top-level domains. Run Classification Gate for each. Create domain folders. |
+| **Level 1** | Domain breadth sweep | For each domain, identify sub-areas. Classification Gate: sub-domain folder or feature file? Update Role Matrix. |
+| **Level 2+** | Vertical drilling | Drill each child. Fill feature files (Role Lens, behavior, edge cases). Promote features to sub-domains if complex. |
 
-Each domain file tracks its sub-areas with status markers:
+Each node tracks its status:
 
 | Marker | Meaning |
 |---|---|
 | `[SURFACE]` | Identified but unexplored |
-| `[BREADTH]` | Sub-areas listed, not detailed |
+| `[BREADTH]` | Children listed, not detailed |
 | `[DEEP]` | Core logic, edge cases, interactions documented |
 | `[EXHAUSTED]` | Deep Think yielded nothing new — domain complete |
 
-A domain reaches `[EXHAUSTED]` only when the Deep Think protocol generates no new hypotheses.
+Status propagates upward: a node is `[EXHAUSTED]` only when ALL its children are `[EXHAUSTED]`.
 
 ### Deep Think Protocol
 
@@ -90,14 +141,30 @@ At every exploration level, the agent actively generates hypotheses:
 
 > *"Based on [industry knowledge / domain patterns / cross-domain interaction], I'd expect [feature/concern/edge case]. Is that relevant to your product?"*
 
-Hypotheses are tracked in domain files with resolution status (confirmed/rejected/deferred). This prevents shallow exploration — the agent doesn't just record what the user says, it actively probes for what the user hasn't mentioned yet.
+Hypotheses are tracked in feature files with resolution status (confirmed/rejected/deferred). This prevents shallow exploration — the agent doesn't just record what the user says, it actively probes for what the user hasn't mentioned yet.
+
+### Hierarchical Cross-Cuts
+
+Cross-cutting concerns are tracked **at the level where they occur**, not in a single flat ledger:
+
+| CX File Location | What It Tracks |
+|-----------------|----------------|
+| `ideation-cx.md` (global) | Cross-surface interactions (multi-product only) |
+| `{surface}-cx.md` | Cross-domain interactions within a surface |
+| `{domain}-cx.md` | Cross-sub-domain interactions within a domain |
+| `{sub-domain}-cx.md` | Cross-feature interactions within a sub-domain |
+
+Each CX entry includes which nodes interact, confidence level, 5 synthesis questions (trigger, data, flow, failure, scope), role scoping, and rejected pairs with reasoning.
+
+### Downstream Consumption
 
-### Cross-Cut Ledger
+| Consumer | What It Reads |
+|----------|--------------|
+| `/create-prd` | `ideation-index.md` + `meta/constraints.md` |
+| `/decompose-architecture` | `ideation-index.md` + domain indexes (walks fractal tree for shard boundary signals: depth, child count, CX density, Role Matrix) |
+| Spec workflows | Domain indexes + feature files for sub-feature detail |
 
-Cross-cutting concerns (security, notifications, analytics, error handling, etc.) are tracked continuously in `cross-cuts/cross-cut-ledger.md` as they're discovered at any level, not batched into a separate pass. Each entry includes:
-- Which domains are involved
-- Confidence level (increases as exploration deepens)
-- Resolution status
+> **Important**: Ideation does NOT prescribe shard boundaries. `/decompose-architecture` reads the fractal tree and makes architectural decisions about where to draw shard lines.
 
 ---