cfsa-antigravity 2.0.0 → 2.2.0

package/template/.agent/skills/migration-management/references/relational.md

@@ -0,0 +1,214 @@
+# Relational Database Migration Patterns
+
+Paradigm-specific patterns for the `migration-management` skill. Read `SKILL.md` first for universal methodology.
+
+Covers: **PostgreSQL**, **MySQL**
+
+---
+
+## Migration Tracking Tables
+
+### PostgreSQL
+
+```sql
+CREATE TABLE schema_migrations (
+  version BIGINT PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  duration_ms INTEGER,
+  checksum VARCHAR(64)
+);
+
+CREATE TABLE migration_logs (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  version BIGINT NOT NULL,
+  status VARCHAR(20) NOT NULL,
+  error_message TEXT,
+  rolled_back_at TIMESTAMP,
+  executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE OR REPLACE FUNCTION record_migration(
+  p_version BIGINT, p_name VARCHAR, p_duration_ms INTEGER
+) RETURNS void AS $$
+BEGIN
+  INSERT INTO schema_migrations (version, name, duration_ms)
+  VALUES (p_version, p_name, p_duration_ms)
+  ON CONFLICT (version) DO UPDATE SET executed_at = CURRENT_TIMESTAMP;
+END;
+$$ LANGUAGE plpgsql;
+```
+
+### MySQL
+
+```sql
+CREATE TABLE schema_migrations (
+  version BIGINT PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  duration_ms INT,
+  checksum VARCHAR(64)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+CREATE TABLE migration_status (
+  id INT AUTO_INCREMENT PRIMARY KEY,
+  version BIGINT NOT NULL,
+  status ENUM('pending', 'completed', 'failed', 'rolled_back'),
+  error_message TEXT,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+---
+
+## Adding Columns
+
+### PostgreSQL
+
+```sql
+-- Non-blocking column addition
+ALTER TABLE users ADD COLUMN phone VARCHAR(20) DEFAULT '';
+ALTER TABLE users ADD CONSTRAINT phone_format
+  CHECK (phone = '' OR phone ~ '^\+?[0-9\-\(\)]{10,}$');
+CREATE INDEX CONCURRENTLY idx_users_phone ON users(phone);
+
+-- Rollback:
+-- DROP INDEX CONCURRENTLY idx_users_phone;
+-- ALTER TABLE users DROP COLUMN phone;
+```
+
+### MySQL
+
+```sql
+ALTER TABLE users
+ADD COLUMN phone VARCHAR(20) DEFAULT '',
+ADD INDEX idx_phone (phone);
+
+-- Rollback:
+-- ALTER TABLE users DROP COLUMN phone;
+```
+
+---
+
+## Renaming Columns
+
+```sql
+-- PostgreSQL
+ALTER TABLE users RENAME COLUMN user_name TO full_name;
+REINDEX TABLE users;
+
+-- Rollback:
+-- ALTER TABLE users RENAME COLUMN full_name TO user_name;
+```
+
+---
+
+## Creating Indexes Non-Blocking
+
+### PostgreSQL (CONCURRENTLY)
+
+```sql
+CREATE INDEX CONCURRENTLY idx_orders_user_created
+ON orders(user_id, created_at DESC);
+
+CREATE INDEX CONCURRENTLY idx_products_category_active
+ON products(category_id) WHERE active = true;
+
+-- Verify
+SELECT schemaname, tablename, indexname, idx_scan
+FROM pg_stat_user_indexes WHERE indexname LIKE 'idx_%';
+```
+
+### MySQL (INPLACE)
+
+```sql
+ALTER TABLE orders
+ADD INDEX idx_user_created (user_id, created_at),
+ALGORITHM=INPLACE, LOCK=NONE;
+```
+
+---
+
+## Data Transformations
+
+### PostgreSQL
+
+```sql
+-- Normalize emails
+UPDATE users SET email = LOWER(TRIM(email))
+WHERE email != LOWER(TRIM(email));
+
+-- Deduplicate (keep latest)
+DELETE FROM users WHERE id NOT IN (
+  SELECT DISTINCT ON (LOWER(email)) id
+  FROM users ORDER BY LOWER(email), created_at DESC
+);
+```
+
+### MySQL
+
+```sql
+UPDATE products p
+JOIN category_mapping cm ON p.old_category = cm.old_name
+SET p.category_id = cm.new_category_id
+WHERE p.old_category IS NOT NULL;
+```
+
+---
+
+## Testing in Transaction
+
+```sql
+BEGIN;
+ALTER TABLE users ADD COLUMN test_column VARCHAR(255);
+SELECT COUNT(*) FROM users;
+-- ROLLBACK if issues, COMMIT if good
+ROLLBACK;
+```
+
+---
+
+## Bidirectional Migration Example
+
+```sql
+-- ===== UP =====
+CREATE TYPE user_status AS ENUM ('active', 'suspended', 'deleted');
+ALTER TABLE users ADD COLUMN status user_status DEFAULT 'active';
+
+-- ===== DOWN =====
+-- ALTER TABLE users DROP COLUMN status;
+-- DROP TYPE user_status;
+```
+
+---
+
+## Production Safety
+
+```sql
+-- PostgreSQL: Prevent hanging migrations
+SET statement_timeout = '30min';
+SET lock_timeout = '5min';
+```
+
+---
+
+## Combined Migration Example
+
+```sql
+BEGIN;
+ALTER TABLE users ADD COLUMN full_name VARCHAR(255);
+UPDATE users SET full_name = first_name || ' ' || last_name;
+CREATE INDEX idx_users_full_name ON users(full_name);
+ALTER TABLE users ADD CONSTRAINT email_unique UNIQUE(email);
+COMMIT;
+```
+
+---
+
+## Tools
+
+- [PostgreSQL ALTER TABLE](https://www.postgresql.org/docs/current/sql-altertable.html)
+- [MySQL ALTER TABLE](https://dev.mysql.com/doc/refman/8.0/en/alter-table.html)
+- [Flyway](https://flywaydb.org/) — Java
+- [Alembic](https://alembic.sqlalchemy.org/) — Python
+- [Knex.js](https://knexjs.org/) — Node.js

package/template/.agent/skills/parallel-feature-development/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: parallel-feature-development
-description: Prevent tool call conflicts when making concurrent edits across a codebase. Establishes strict file ownership, interface contracts, and merge strategies. Use with parallel-agents when executing concurrent `replace_file_content` calls.
+description: Prevent tool call conflicts when making concurrent edits across a codebase. Establishes strict file ownership, interface contracts, and merge strategies. Use with parallel-agents when executing concurrent code changes.
 ---
 
 # Concurrent Feature Development
 
 ## Overview
 
-When making concurrent code edits (e.g. implementing the frontend and backend of a slice simultaneously), the #1 risk is **file hash conflicts** — trying to execute multiple `replace_file_content` calls on the same file, which causes the operation to fail. This skill prevents that with strict file ownership, typed interface contracts, and batched execution.
+When making concurrent code edits (e.g. implementing the frontend and backend of a slice simultaneously), the #1 risk is **file conflicts** — trying to modify the same file from multiple streams, which causes the operation to fail. This skill prevents that with strict file ownership, typed interface contracts, and batched execution.
 
 **Core principle:** One concurrent stream per file, always. No exceptions. If two streams need the same file, they're not independent — restructure the decomposition.
 
@@ -36,58 +36,51 @@ If Stream A owns `src/auth/login.ts`, no other stream may modify that file — n
 
 ### 1. Ownership Declaration
 
-Before writing code concurrently, create an explicit mental or written ownership manifest:
+Before writing code concurrently, create an explicit ownership manifest:
 
 ```markdown
 ## File Ownership Manifest
 
 | Stream | Owned Files | Interface Files |
 |--------|-------------|-----------------|
-| Stream 1 (Auth) | `src/auth/*`, `src/middleware/auth.ts` | `src/types/auth.ts` |
-| Stream 2 (API) | `src/api/*`, `src/middleware/api.ts` | `src/types/api.ts` |
-| Stream 3 (UI) | `src/components/*`, `src/pages/*` | `src/types/ui.ts` |
+| Stream 1 (Auth) | `src/auth/*`, `src/middleware/auth.*` | `src/types/auth.*` |
+| Stream 2 (API) | `src/api/*`, `src/middleware/api.*` | `src/types/api.*` |
+| Stream 3 (UI) | `src/components/*`, `src/pages/*` | `src/types/ui.*` |
 
 ### Shared Files (Frozen)
-- `src/types/shared.ts` — modify only in synthesis step
-- `src/config.ts` — frozen during parallel work
-- `package.json` — frozen during parallel work
+- `src/types/shared.*` — modify only in synthesis step
+- `src/config.*` — frozen during parallel work
+- Package manifest — frozen during parallel work
 ```
 
 **Rules:**
-- Every source file to be edited appears in exactly ONE workstream
-- Shared files are **frozen** — do not mutate them concurrently
+- Every source file appears in exactly ONE workstream
+- Shared files are **frozen** — do not mutate concurrently
 - If a stream needs a change to a shared file, document it as a `// BOUNDARY:` stub
 - Interface files define the contract between streams
 
 ### 2. Interface Contracts
 
-Before generating concurrent edits, define the typed interfaces they'll communicate through:
-
-```typescript
-// src/types/auth.ts — Stream 1 PRODUCES this, Stream 2 CONSUMES it
-export interface AuthResult {
-  userId: string;
-  roles: string[];
-  token: string;
-}
-
-// src/types/api.ts — Stream 2 PRODUCES this, Stream 3 CONSUMES it
-export interface UserResponse {
-  id: string;
-  name: string;
-  email: string;
-}
+Before generating concurrent edits, define the typed interfaces they'll communicate through.
+
+**Example (pseudocode — adapt to your language):**
+```
+// src/types/auth — Stream 1 PRODUCES, Stream 2 CONSUMES
+AuthResult { userId: string, roles: string[], token: string }
+
+// src/types/api — Stream 2 PRODUCES, Stream 3 CONSUMES
+UserResponse { id: string, name: string, email: string }
 ```
 
 **Contract rules:**
-- Interfaces are strictly defined BEFORE generating logic
-- Do NOT change interface files during the concurrent implementation phase
+- Interfaces defined BEFORE generating logic
+- Do NOT change interface files during the concurrent phase
 - Each interface has exactly one PRODUCER and one or more CONSUMERS
 - Develop against the interface, not assumptions
 
 ### 3. Batched Tool Execution
 
-When generating concurrent tool calls in the same turn:
+When generating concurrent tool calls:
 
 ```markdown
 ## Stream: [Role]
@@ -110,7 +103,7 @@ If you need something from another stream's domain:
 
 ### 4. Merge Protocol
 
-Always execute edits that don't overlap in a single batched `multi_replace_file_content` call, but conceptually process dependencies:
+Process dependencies in order:
 
 ```
 1. Interface files (already defined, verify no changes)
@@ -127,19 +120,17 @@ Always execute edits that don't overlap in a single batched `multi_replace_file_
 
 ### 5. Conflict Resolution
 
-If despite everything, a conflict is detected:
-
 | Conflict Type | Resolution |
 |---------------|-----------|
-| **Same file modified** | `replace_file_content` block. Separate edits into sequential tool calls. |
+| **Same file modified** | Separate edits into sequential tool calls |
 | **Interface mismatch** | Producer's implementation doesn't match contract → fix producer |
 | **Missing dependency** | Assumed something exists that doesn't → add BOUNDARY stub |
-| **Mutual dependency** | A needs B's output AND B needs A's output → can't go concurrent, code sequentially |
+| **Mutual dependency** | A needs B's output AND B needs A's → can't go concurrent, code sequentially |
 
 ## Integration with Kit
 
-- **With `session-continuity` Protocol 9 (Parallel Claim):** When tasks in progress files have surface tags (`BE`, `FE`, `QA`) and claim markers (`[!]`), the `files:` blocks under claimed tasks serve as your live ownership manifest. By analyzing these blocks, you can safely batch `replace_file_content` calls for both `FE` and `BE` tasks simultaneously.
-- **With `boundary-not-placeholder`:** Use `// BOUNDARY:` stubs for cross-stream dependencies you can't resolve concurrently. Resolve them sequentially afterward.
+- **With `session-continuity` Protocol 9 (Parallel Claim):** Surface tags (`BE`, `FE`, `QA`) and claim markers (`[!]`) in progress files serve as your live ownership manifest.
+- **With `boundary-not-placeholder`:** Use `// BOUNDARY:` stubs for cross-stream dependencies. Resolve them sequentially afterward.
 - **With `implement-slice`:** When a slice enters parallel mode (step 1.5), claim all tags concurrently. The synthesis step (6.5) resolves BOUNDARY stubs on frozen files.
 
 ## Example: Concurrent Vertical Slice
@@ -148,19 +139,19 @@ If despite everything, a conflict is detected:
 
 | Stream | Surface | Owned Files | Produces | Consumes |
 |--------|---------|-------------|----------|----------|
-| DB Stream | Schema | `migrations/003-profile.sql`, `src/db/profile.ts` | `ProfileRecord` type | — |
-| API Stream | Endpoint | `src/api/profile.ts`, `src/api/profile.test.ts` | `GET /api/profile` | `ProfileRecord` |
-| UI Stream | Component | `src/components/Profile.tsx`, `src/pages/profile.astro` | Rendered page | `GET /api/profile` |
+| DB | Schema | `migrations/003-profile.*`, `src/db/profile.*` | `ProfileRecord` type | — |
+| API | Endpoint | `src/api/profile.*`, `src/api/profile.test.*` | `GET /api/profile` | `ProfileRecord` |
+| UI | Component | `src/components/Profile.*`, `src/pages/profile.*` | Rendered page | `GET /api/profile` |
 
 **Merge order:** DB → API → UI (dependency chain)
 
-**Frozen files:** `src/types/shared.ts`, `astro.config.mjs`, `package.json`
+**Frozen files:** `src/types/shared.*`, config, package manifest
 
 ## Common Mistakes
 
 | Mistake | Consequence | Fix |
 |---------|-------------|-----|
-| Two sub-tasks mutate the same file | Tool call conflict, lost edits | ONE STREAM PER FILE. NO EXCEPTIONS. |
+| Two streams mutate the same file | Tool call conflict, lost edits | ONE STREAM PER FILE |
 | No interface contracts | Mismatched assumptions | Define types BEFORE editing |
 | Skipping integration tests | Interfaces match but behavior doesn't | Full suite after batch edits |
-| Parallelizing tightly coupled code | Constant blocking, BOUNDARY stubs everywhere | Code sequentially |
+| Parallelizing tightly coupled code | Constant blocking, stubs everywhere | Code sequentially |

package/template/.agent/skills/pipeline-rubrics/references/be-rubric.md

@@ -3,7 +3,7 @@
 | # | Dimension | ✅ (must meet ALL criteria) | ⚠️ | ❌ |
 |---|---|---|---|---|
 | 1 | Upstream Traceability | (a) Every endpoint cites its IA source shard + section. (b) Every schema field traces to an IA data model field. No endpoint is "inferred" from context. (c) Every sub-feature listed in the IA shard's `## Features` is represented by at least one endpoint in the BE spec — a sub-feature with zero endpoints and no explicit `[Deferred to Phase N]` note is a gap. | Some endpoints or fields missing IA citations, or ≤20% of sub-features lack endpoint representation | Orphan endpoints with no IA source, or >20% of sub-features have no endpoint and no deferral note |
-| 2 | Contract Completeness | Every endpoint has: Zod request schema (all fields typed) + Zod response schema (all fields typed) + error schema. No field uses `any`, `unknown`, or untyped `string` where a more specific type exists. | Some schemas present but fields untyped or missing | Major schemas absent |
+| 2 | Contract Completeness | Every endpoint has: {{CONTRACT_LIBRARY}} request schema (all fields typed) + {{CONTRACT_LIBRARY}} response schema (all fields typed) + error schema. No field uses `any`, `unknown`, or untyped `string` where a more specific type exists. | Some schemas present but fields untyped or missing | Major schemas absent |
 | 3 | Error Exhaustiveness | Every endpoint has: HTTP status code + application error code (not just HTTP) + error message format + retry guidance. No endpoint uses "standard error handling" without defining it. | Some endpoints missing error codes or retry guidance | Generic 500s or no error section |
 | 4 | Schema Completeness | Every database table has: all fields with types + constraints (nullable, unique, indexed) + relationships with foreign keys + indexes for every query pattern. No field uses "standard" constraints without defining them. | Constraints or indexes missing | Sketched only |
 | 5 | Middleware Explicitness | Every endpoint has an explicit middleware matrix: auth required (yes/no) + rate limit (number/window) + input validation (where it runs) + CORS policy. No endpoint inherits "default middleware" without defining it. | Some endpoints missing middleware entries | No matrix |

package/template/.agent/skills/pipeline-rubrics/references/ia-rubric.md

@@ -2,7 +2,7 @@
 
 | # | Dimension | ✅ (must meet ALL criteria) | ⚠️ | ❌ |
 |---|---|---|---|---|
-| 1 | Feature Enumeration | (a) Every feature from the ideation index's Must Have list appears in at least one shard. (b) Every feature has a clear scope boundary (what's in, what's out). (c) Every shard's `## Features` section contains Level-1 sub-features from the ideation domain files — not architecture headlines — and every sub-feature is represented in at least one section body (User Interactions, Data Model, Access Control, or Edge Cases). | Some features vague, scope unclear, or sub-features listed in `## Features` but not represented in any section body | Major Must Have features missing, or `## Features` contains only architecture headlines with no sub-feature detail |
+| 1 | Feature Enumeration | (a) Every feature from the ideation index's Must Have list appears in at least one shard. (b) Every feature has a clear scope boundary (what's in, what's out). (c) Every shard's `## Features` section contains Level-1 sub-features from the ideation domain tree (folder index + feature files) — not architecture headlines — and every sub-feature is represented in at least one section body (User Interactions, Data Model, Access Control, or Edge Cases). | Some features vague, scope unclear, or sub-features listed in `## Features` but not represented in any section body | Major Must Have features missing, or `## Features` contains only architecture headlines with no sub-feature detail |
 | 2 | Access Model | Every role has: a named role + an exhaustive list of what it CAN do + an exhaustive list of what it CANNOT do + escalation path. No role uses "standard access" without defining it. | Some roles defined but missing permission or restriction lists | No access model |
 | 3 | Data Model | Every entity has: named fields + field types + constraints + relationships with cardinality. No field uses "standard" or "typical" without defining it. | Structure present but field types or constraints missing | Absent |
 | 4 | User Flows | Every user flow has: trigger + step-by-step actions + system responses + error paths. No flow ends at "success" without defining what success looks like. | Happy path only, or flows missing error paths | None |
@@ -14,6 +14,6 @@
 > **Deep Dive audit note**: When auditing dimension 7, read each deep dive file directly — do not infer its completeness from the parent shard's reference to it. A parent shard that links to a deep dive scores ⚠️ (not ✅) if the deep dive file itself is still a skeleton. Score ✅ only when the deep dive file contains exhaustive subsystem detail that an implementer could work from without asking questions.
 
 > **Dimension 1 audit procedure**:
-> 1. Read `docs/plans/ideation/ideation-index.md` and the relevant domain files in `docs/plans/ideation/domains/` to extract the authoritative list of Level-1 sub-features per domain.
+> 1. Read `docs/plans/ideation/ideation-index.md` and the relevant ideation domain folders (use Structure Map for correct paths — folders are under `domains/` or `surfaces/{name}/`). For each domain, read the folder's `*-index.md` for the children table, then each child feature file to extract the authoritative list of Level-1 sub-features per domain.
 > 2. For each shard, open `docs/plans/ia/[NN-domain-name].md` and confirm every sub-feature from step 1 appears in the `## Features` section. Score ❌ if Must Have sub-features are missing entirely.
 > 3. For each sub-feature listed in `## Features`, verify it is represented in at least one section body (User Interactions, Data Model, Access Control, or Edge Cases). A sub-feature that appears only as a headline in `## Features` but has no corresponding detail in any section body scores ⚠️ — headline only = warning, not pass.

package/template/.agent/skills/pipeline-rubrics/references/scoring.md

@@ -21,7 +21,7 @@ Write all cross-layer findings to a `## Cross-Layer Consistency` section in the
 
 | Layer | Documents to load |
 |-------|-------------------|
-| Ideation | `docs/plans/ideation/ideation-index.md` + domain files |
+| Ideation | `docs/plans/ideation/ideation-index.md` + `ideation-cx.md` + all `*-index.md`, `*-cx.md`, and feature `.md` files recursively under `domains/` (and `surfaces/` for multi-product projects) |
 | Architecture | `docs/plans/*-architecture-design.md`, `docs/plans/ENGINEERING-STANDARDS.md` |
 | IA | `docs/plans/ia/index.md` + each shard listed + `docs/plans/ia/deep-dives/*.md` (list directory; include all files present) |
 | BE | `docs/plans/be/index.md` + each spec listed |

package/template/.agent/skills/pipeline-rubrics/references/vision-rubric.md

@@ -1,4 +1,4 @@
-# Vision Rubric (7 dimensions)
+# Vision Rubric (8 dimensions)
 
 | # | Dimension | ✅ (must meet ALL criteria) | ⚠️ | ❌ |
 |---|---|---|---|---|
@@ -9,3 +9,4 @@
 | 5 | Success Measurability | Every metric is a number with a unit and a timeframe (e.g., "p95 < 500ms at launch"). No metric uses "fast", "good", or "acceptable". | Directional only | Missing |
 | 6 | Competitive Positioning | ≥3 named competitors. Differentiation is a specific capability gap. Moat is a defensible mechanism. | Vague positioning or <3 competitors | Not addressed |
 | 7 | Open Question Resolution | Every open question has: owner + deadline + what decision it blocks. No question is listed without an owner. | Questions listed, no owners or deadlines | No questions section |
+| 8 | Structural Compliance | Every domain folder has `*-index.md` + `*-cx.md`. Role Matrix populated in every domain index. Feature files have Role Lens. Structure Map in `ideation-index.md` matches actual folder tree. No Classification Gate violations (no folders with 1 child, no flat features with ≥3 sub-features). | Structure exists but some folders missing CX or Role Matrix is partially empty | No fractal structure, or flat files used instead of folders |

package/template/.agent/skills/prd-templates/SKILL.md

@@ -52,7 +52,12 @@ Run this procedure when filling the `## Features` section of each shard skeleton
 
 ### Source
 
-Read `docs/plans/ideation/ideation-index.md` and locate the relevant domain file in `docs/plans/ideation/domains/` for each shard's domain.
+Read `docs/plans/ideation/ideation-index.md` — specifically the `## Structural Classification` and `## Structure Map` sections.
+
+- **All project shapes**: Use the Structure Map to find the correct domain **folder** path. Each domain is a folder containing `*-index.md` (children table + Role Matrix), `*-cx.md` (cross-cuts), and child feature `.md` files.
+- **Multi-product projects**: Domain folders may be under `docs/plans/ideation/surfaces/{surface-name}/` (surface-exclusive) or `docs/plans/ideation/domains/` (shared).
+
+Match each shard to its ideation domain by name. Walk the domain's fractal tree: read the domain index for the children list, then read each child feature file to extract sub-features. If the domain has sub-domain folders, recurse into them.
 
 ### Actor + Goal Format Rule
 
@@ -68,21 +73,33 @@ List sub-features as bullet points in the `## Features` section. Group by functi
 
 ### `[THIN — review with user]` Fallback Rule
 
-If a shard's domain has no corresponding file in `docs/plans/ideation/domains/` (the domain was introduced during architecture design, not ideation), mark the skeleton with `[THIN — review with user]` at the top of `## Features` and seed from the architecture design description instead.
+If a shard's domain has no corresponding ideation domain folder (the domain was introduced during architecture design, not ideation — check the `ideation-index.md` Structure Map for paths under `domains/` and `surfaces/`), mark the skeleton with `[THIN — review with user]` at the top of `## Features` and seed from the architecture design description instead.
 
 At the validation step, the user must confirm whether to:
 - Keep the shard separate
 - Merge it into an adjacent shard
-- Add missing sub-features from ideation
+- Add missing sub-features from ideation (create a domain folder if needed)
 
 ### Directory Example
 
-Seeded skeletons live in the `docs/plans/ia/` directory:
+Seeded skeletons live in the `docs/plans/ia/` directory (or per-surface directories for multi-product):
 
+**Single-surface:**
 ```
 docs/plans/ia/
 ├── 00-infrastructure.md
-├── 01-user-accounts.md      ← ## Features seeded from ideation/domains/user-accounts.md
-├── 02-content-library.md    ← ## Features seeded from ideation/domains/content-library.md
+├── 01-user-accounts.md      ← ## Features seeded from ideation/domains/01-user-accounts/ (index + feature files)
+├── 02-content-library.md    ← ## Features seeded from ideation/domains/02-content-library/ (index + feature files)
 ├── ...
 ```
+
+**Multi-product:**
+```
+docs/plans/desktop/ia/
+├── 00-infrastructure.md
+├── 01-operations.md         ← ## Features seeded from ideation/surfaces/desktop/01-operations/ (index + feature files)
+├── 02-inventory.md          ← ## Features seeded from ideation/surfaces/desktop/02-inventory/ (index + feature files)
+
+docs/plans/shared/ia/
+├── 01-device-history.md     ← ## Features seeded from ideation/domains/01-device-history/ (index + feature files)
+```

package/template/.agent/skills/prd-templates/references/be-spec-template.md

@@ -24,7 +24,7 @@ that lets a reviewer verify nothing was missed or invented.]
 | [specific subsystem] | [deep-dive.md] | § Key Decisions |
 
 ## API Endpoints
-## Request/Response Contracts (Zod schemas)
+## Request/Response Contracts ({{CONTRACT_LIBRARY}} schemas)
 ## Database Schema
 ## Middleware & Policies
 ## Data Flow
@@ -42,7 +42,7 @@ that lets a reviewer verify nothing was missed or invented.]
 
 Apply after writing every BE spec:
 
-- [ ] Every endpoint has a Zod request AND response schema
+- [ ] Every endpoint has a {{CONTRACT_LIBRARY}} request AND response schema
 - [ ] Every database table has defined fields, indexes, and permissions
 - [ ] Security constraints from IA shard reflected in middleware section
 - [ ] Error codes are specific (not generic 500s)

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

@@ -18,7 +18,7 @@ For each shard, create at `docs/plans/ia/[NN-domain-name].md`:
 [1-2 sentence description of this domain's scope]
 
 ## Features
-[Level-1 sub-features from the relevant domain file in `docs/plans/ideation/domains/` for this domain. NOT architecture-level headlines. See /decompose-architecture-structure Step 5 for seeding instructions.]
+[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]
@@ -101,7 +101,7 @@ Read cross-cutting specs first, then feature specs in numerical order.
 
 Every BE spec MUST include:
 - API Endpoints (method, path, description)
-- Request/Response Contracts (Zod schemas)
+- Request/Response Contracts ({{CONTRACT_LIBRARY}} schemas)
 - Database Schema (tables, fields, indexes, permissions)
 - Middleware & Policies (auth, rate limits, validation)
 - Data Flow (request lifecycle)

package/template/.agent/skills/prd-templates/references/engineering-standards-template.md

@@ -102,9 +102,11 @@ Use this template when creating `docs/plans/ENGINEERING-STANDARDS.md`. Fill in c
 
 ## Security
 - Dependency audit: [e.g., npm audit on every CI run]
+- Dependency audit enforcement: [e.g., Fail on HIGH/CRITICAL, Warn on MODERATE]
 - Secret scanning: [tool/approach]
 - CSP policy: [strict/relaxed + details] (web surfaces)
 - Code signing: [signing certificate strategy] (desktop/mobile surfaces)
+- Security testing tool: [e.g., OWASP ZAP for web, MobSF for mobile, or none] (surface-specific dynamic security scan)
 
 ## Code Quality
 - Max file length: [e.g., 300 lines]

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

@@ -44,7 +44,7 @@ Use this template when writing FE specs to `docs/plans/fe/[NN-feature-name].md`.
 [Server state, client state, URL state, loading/error/empty]
 
 ## Interaction Specification
-[Click, hover, keyboard, form validation matching Zod]
+[Click, hover, keyboard, form validation matching {{CONTRACT_LIBRARY}}]
 
 ## Responsive Behavior
 [Breakpoints, component behavior per breakpoint]

package/template/.agent/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