cfsa-antigravity 2.0.0 → 2.2.0

package/template/.agent/workflows/implement-slice-tdd.md

@@ -17,7 +17,7 @@ pipeline:
 
 Execute the TDD cycle (Red → Green → Refactor), run validation, handle synthesis, and update all progress tracking files.
 
-**Prerequisite**: Contract (Zod schema) must be written (from `/implement-slice-setup` or equivalent). If in parallel mode, QA-RED and BE/FE/QA-GREEN dispatch should be completed during setup.
+**Prerequisite**: Contract ({{CONTRACT_LIBRARY}} schema) must be written (from `/implement-slice-setup` or equivalent). If in parallel mode, QA-RED and BE/FE/QA-GREEN dispatch should be completed during setup.
 
 ---
 
@@ -26,153 +26,137 @@ Execute the TDD cycle (Red → Green → Refactor), run validation, handle synth
 Read .agent/skills/tdd-workflow/SKILL.md and follow its methodology.
 Read .agent/skills/clean-code/SKILL.md and follow its methodology.
 Read .agent/skills/systematic-debugging/SKILL.md and follow its methodology.
-Read .agent/skills/{{LANGUAGE_SKILL}}/SKILL.md and follow its language conventions.
-Read .agent/skills/{{UNIT_TESTING_SKILL}}/SKILL.md and follow its test writing conventions.
-Read .agent/skills/{{E2E_TESTING_SKILL}}/SKILL.md and follow its E2E test conventions.
+Determine which surface this slice belongs to from the phase plan or slice path. Read the surface stack map from `.agent/instructions/tech-stack.md`.
 
-Cross-reference **all three** sources — acceptance criteria from the phase plan, the Zod contract from step 2, AND IA edge cases traced through the BE Source Map:
+Load the Languages, Unit Tests, and E2E Tests skill(s) from this slice's surface row per the skill loading protocol (`.agent/skills/prd-templates/references/skill-loading-protocol.md`).
+
+Cross-reference **all three** sources — acceptance criteria from the phase plan, the {{CONTRACT_LIBRARY}} contract from step 2, AND IA edge cases traced through the BE Source Map:
 1. Write a test for each acceptance criterion
 2. Write a test for each contract field, error type, and validation rule not already covered by criteria
-3. For each endpoint in this slice, read the IA shard section(s) cited in that endpoint's BE spec `## Source Map`. Extract every item from the IA shard's `## Edge Cases` section that is relevant to the endpoint(s) under test. Write a failing test for each uncovered edge case. Tag these tests with `// IA-EDGE: [IA §X.Y — description]` so QA-GREEN can audit traceability.
+3. For each endpoint, read the IA shard section(s) cited in the BE spec `## Source Map`. Extract every relevant `## Edge Cases` item. Write a failing test for each, tagged `// IA-EDGE: [IA §X.Y — description]`
 4. Run all tests — they MUST fail
 5. Commit the failing tests
 
-**Test order**: Unit → Integration → E2E (if applicable)
+Read `.agent/skills/prd-templates/references/tdd-testing-policy.md` and apply its **Assertion Depth Rule** and **Anti-Mock-Abuse Rules** to all tests written above.
 
 > **In parallel mode**, this step is handled by the `QA` agent dispatch in step 1.5.
-> In sequential mode, the orchestrator handles it directly.
 
-Run `{{TEST_COMMAND}}` to verify tests fail.
+Run the Test Cmd from this slice's surface row in the surface stack map to verify tests fail.
 
 ## 4. Implement (GREEN)
 
-Read .agent/skills/{{LANGUAGE_SKILL}}/SKILL.md and follow its language conventions.
+Load the Languages skill(s) from this slice's surface row per the skill loading protocol.
 
-Write the minimum code to make all tests pass:
+Write the simplest *correct* implementation to make all tests pass. "Minimal" means no unnecessary abstractions — it does **NOT** mean skipping error handling, input validation, logging, or edge cases that the spec defines:
 1. Database schema/migration
 2. API endpoint handler
 3. Business logic
 4. UI component
 
-**If in parallel mode**: Each agent claims its task via the **Parallel Claim Protocol** (`.agent/skills/session-continuity/protocols/09-parallel-claim.md`) — marking `[!]`, writing `files:` list, and working through subtasks. Agents release claims on completion.
-
-**Before using any stub or placeholder**, apply the three-part test from the
-`boundary-not-placeholder` rule:
-- Does the spec exist? → Implement it. No stub.
-- Could you write the spec now? → Write the spec first, then implement.
-- Information genuinely doesn't exist? → `BOUNDARY:` stub with typed interface, tracking issue, and sentinel test.
+**If in parallel mode**: Each agent claims its task via the **Parallel Claim Protocol** (`.agent/skills/session-continuity/protocols/09-parallel-claim.md`).
 
-> **"This is a lot of work" is not a valid boundary.** Amount of work, task
-> scope, and complexity are never reasons to stub. Only missing information is.
+**Before using any stub or placeholder**, apply the three-part test from the `boundary-not-placeholder` rule. Only missing information is a valid boundary — amount of work, scope, and complexity are never reasons to stub.
 
-**Spec traceability**: if you make any implementation decision not explicitly covered by the spec or contract (e.g., choosing enum values, default behaviors, retry counts, timeout durations, error messages), annotate it with `// DECISION: [what was decided and why]`. QA will audit these.
+**Spec traceability**: Annotate any implementation decision not covered by the spec with `// DECISION: [what was decided and why]`. QA will audit these.
 
-Run `{{TEST_COMMAND}}` to verify tests pass.
+> **Decision recording**: For decisions with ripple effects (touching other components, changing contracts, setting precedent), read `.agent/skills/session-continuity/protocols/06-decision-analysis.md` and follow the **Decision Effect Analysis Protocol**. Isolated decisions don't need this — only decisions where changing it later requires editing more than the current file.
 
-## 4.1. Debug cycle (if tests fail after initial implementation)
+Run the Test Cmd to verify tests pass.
 
-If `{{TEST_COMMAND}}` shows failures after completing Step 4:
+## 4.1. Debug cycle (if tests fail)
 
-Read .agent/skills/systematic-debugging/SKILL.md and follow its ACH methodology.
-Read .agent/skills/parallel-debugging/SKILL.md if failures span multiple subsystems.
+Read `.agent/skills/systematic-debugging/SKILL.md` and follow its ACH methodology. Read `.agent/skills/parallel-debugging/SKILL.md` if failures span multiple subsystems.
 
-1. Classify failures: contract mismatch vs logic error vs integration issue
-2. For contract mismatches: re-read the BE spec — is the contract wrong or the implementation?
-3. For logic errors: apply ACH (Analysis of Competing Hypotheses) per the debugging skill
-4. For integration issues: check cross-surface wiring, env vars, service connectivity
-5. Maximum 3 debug iterations before escalating to user with findings
+1. Classify: contract mismatch vs logic error vs integration issue
+2. Contract mismatch → re-read BE spec — contract wrong or implementation?
+3. Logic error → ACH per debugging skill
+4. Integration issue → check cross-surface wiring, env vars, service connectivity
+5. Maximum 3 iterations before escalating to user
 
-Run `{{TEST_COMMAND}}` after each debug iteration to verify progress.
+Run the Test Cmd after each iteration.
 
 ## 4.5. New dependency check
 
-After making all tests pass (GREEN), scan the new imports introduced in the implementation files.
+After GREEN, scan new imports. If any package lacks a corresponding skill directory in `.agent/skills/`:
+1. Identify the stack category (e.g., `QUEUE`, `CACHE`, `SEARCH`)
+2. Read `.agent/workflows/bootstrap-agents.md` and fire bootstrap with `PIPELINE_STAGE=implement-slice` + the key-value pair
+3. Confirm skill installed before proceeding to REFACTOR
 
-If any package or module was introduced that does **not** have a corresponding skill directory in `.agent/skills/`:
-1. Identify the stack category (e.g., `QUEUE`, `CACHE`, `SEARCH`, `STORAGE`, `REALTIME`)
-2. Read `.agent/workflows/bootstrap-agents.md` and fire bootstrap with `PIPELINE_STAGE=implement-slice` + the key-value pair (e.g., `NEW_DEPENDENCY=[package-name]`)
-3. Confirm the matching skill is installed before proceeding to REFACTOR
-
-If no new unregistered dependencies were introduced, skip and proceed to Step 5.
+No new unregistered dependencies → skip to Step 5.
 
 ## 5. Refactor
 
-With tests green, improve code quality:
-- Extract shared logic
-- Improve naming
-- Remove duplication
-- Add documentation
+With tests green, improve code quality: extract shared logic, improve naming, remove duplication, add documentation.
 
-Read `.agent/skills/code-review-pro/SKILL.md` and apply its adversarial review: "How would a senior engineer reject this in a PR review?" Fix issues before running tests.
+Read `.agent/skills/code-review-pro/SKILL.md` and apply its adversarial review: "How would a senior engineer reject this in a PR review?"
 
-**Spec traceability check**: Re-read the BE spec and IA shard sections for this slice. Verify every Zod contract field maps to a BE spec field. Verify every `// IA-EDGE:` tagged test's edge case is covered by the implementation, not just tested. Fix any spec drift before proceeding.
+**Spec traceability check**: Re-read the BE spec and IA shard for this slice. Verify every contract field maps to a BE spec field and every `// IA-EDGE:` test's edge case is covered by the implementation. Fix spec drift before proceeding.
 
-Run `{{TEST_COMMAND}}` to verify tests still pass after refactor.
+Run the Test Cmd to verify tests still pass.
 
-## 6. Validate
+### 5.5. Query optimization check
 
-Read .agent/skills/verification-before-completion/SKILL.md and apply its evidence-before-claims discipline.
+For each database query introduced or modified in this slice:
 
-Run the full validation suite: `{{VALIDATION_COMMAND}}`.
+1. **N+1 detection**: Review all data-fetching code for loop-based queries. If a query inside a loop fetches related data that could be eagerly loaded or batched, flag as an N+1 pattern and fix using the installed ORM/DB skill's recommended approach (e.g., `include` for Prisma, `with` for Drizzle, JOIN for raw SQL, graph traversal for SurrealDB)
+2. **Index coverage**: For each new WHERE clause, ORDER BY, or JOIN condition, verify a supporting index exists in the migration/schema. If no index exists and the table is expected to exceed 10,000 rows, add one
+3. **Query plan verification** (if test DB is available): Run EXPLAIN ANALYZE (or equivalent) on queries targeting tables with >1,000 rows in seed data. Flag any sequential scan on a table expected to grow beyond 10,000 rows
 
-All must pass before the slice is complete.
+If `docs/plans/ENGINEERING-STANDARDS.md` defines `### DB Query Time` budgets, annotate each new query with its expected tier in a code comment: `// DB-TIER-2: uncached read, p95 target < 50ms`
 
-## 6.5. Synthesis (parallel mode only)
+### 5.6. Resource cleanup verification
 
-**Skip this step if not in parallel mode.**
+Review all new code in this slice for resource acquisition patterns. For each resource acquired, verify matching cleanup exists:
 
-Read `.agent/skills/session-continuity/protocols/11-parallel-synthesis.md` and follow its full procedure — write synthesis plan, resolve stubs, wire integrations, run `{{VALIDATION_COMMAND}}`.
+| Resource Type | Required Cleanup | Example |
+|--------------|-----------------|---------|
+| DB connection/client | `disconnect()`/`close()` in `finally` | Prisma `$disconnect()`, pg `pool.end()` |
+| Event listener | `removeEventListener()` or equivalent on unmount/destroy | React `useEffect` cleanup return |
+| Subscription | `unsubscribe()`/`kill()` on unmount/destroy | RxJS, SurrealDB live queries, WebSocket |
+| Timer (interval/timeout) | `clearInterval()`/`clearTimeout()` | Polling loops, debounce timers |
+| File handle/stream | `close()`/`destroy()` | fs reads, HTTP response streams |
+| Worker thread | `terminate()` | Web Workers, Node Worker Threads |
 
-## 7. Update progress (Mandatory)
+If any cleanup is missing, add it before proceeding. Run the Test Cmd after adding cleanup to verify tests still pass.
 
-**CRITICAL ANTI-HALLUCINATION RULE**: You MUST NOT skip the progress update. Agents routinely skip this step after validation passes.
+## 6. Validate
 
-Read `.agent/skills/session-continuity/protocols/03-progress-update.md` and follow **every step** in the protocol. You must physically open and edit each of the four file targets (slice file, phase file, index, memory) using your file editing tools.
+Read `.agent/skills/verification-before-completion/SKILL.md` and apply its evidence-before-claims discipline.
 
-The protocol covers:
-- **7a**: Slice file — status, criteria, implementation notes, files changed
-- **7b**: Phase file — slice entry, sub-tasks, progress fraction, claim releases
-- **7c**: Index — overall percentage, phase row
-- **7d**: Memory — patterns and blockers
+Run the Validation Cmd from this slice's surface row. At least one integration test per BE endpoint must hit a real test server + real test database and assert the full response body.
 
-## 8. Completion Gate
+All must pass before the slice is complete.
 
-Read .agent/skills/verification-before-completion/SKILL.md and apply its evidence-before-claims discipline.
+## 6.5. Synthesis (parallel mode only)
 
-### UI Completeness Check (FE slices only)
+**Skip if not in parallel mode.**
 
-- [ ] (FE slices only) Every acceptance criterion mentioning "user sees", "user can", "displays", or "shows" has a rendered implementation — not just a passing test
-- [ ] (FE slices only) Every new route in this slice is wired into the app's navigation (not just exported as a component)
-- [ ] (FE slices only) Loading, error, and empty states are rendered in the UI — not just covered by tests
-- [ ] (FE slices only) The feature is reachable from the app's entry point via normal user navigation
+Read `.agent/skills/session-continuity/protocols/11-parallel-synthesis.md` and follow its full procedure.
 
-These items apply only when the slice is tagged `FE`. Non-FE slices skip this block.
+## 7. Update progress (Mandatory)
 
-### Spec Traceability Gate (all slices)
+**CRITICAL**: You MUST NOT skip progress updates. Read `.agent/skills/session-continuity/protocols/03-progress-update.md` and follow **every step** — physically edit all four file targets (slice, phase, index, memory).
 
-Before calling `notify_user`, verify:
+## 8. Completion Gate
 
-- [ ] Re-read the BE spec section(s) for every endpoint in this slice — every response field, error code, and validation rule has a corresponding test tagged with the spec reference
-- [ ] Re-read the IA shard's `## Edge Cases` section for this slice's domain — every edge case relevant to this slice has a `// IA-EDGE:` tagged test
-- [ ] No `// DECISION:` annotations exist for behaviors that are actually specified in the BE spec or IA shard (i.e., no spec-defined behavior was treated as an undocumented implementation decision)
-- [ ] The Zod contract written in Step 2 matches the delivered implementation field-for-field — no fields added, removed, or renamed during implementation without a corresponding contract update
+Read `.agent/skills/verification-before-completion/SKILL.md` and apply its discipline.
 
-> ❌ STOP — Do not call `notify_user` if any of the above are unchecked. Fix the gap and re-run `{{TEST_COMMAND}}`.
+Read `.agent/skills/prd-templates/references/slice-completion-gates.md` and verify every applicable checklist passes:
+- **UI Completeness Check** — FE slices only
+- **Spec Traceability Gate** — all slices
 
-You may not call `notify_user` until you have edited all four file targets above (7a–7d).
+Read `.agent/skills/prd-templates/references/tdd-testing-policy.md` and run the **QA Anti-Cheat Audit** checklist.
 
-Verify your edits by reading each of the following files:
-- Read `.agent/progress/slices/phase-NN-slice-NN.md` — must show Status: complete and [x] criteria
-- Read `.agent/progress/phases/phase-NN.md` — search for "Progress" and verify it shows the incremented fraction
-- Read `.agent/progress/index.md` — search for "Overall" and verify it shows the new overall percentage
+You may not call `notify_user` until you have edited all four progress file targets (7a–7d).
 
-Replace `NN` with the actual phase and slice numbers you just completed.
+Verify your edits by reading:
+- `.agent/progress/slices/phase-NN-slice-NN.md` — Status: complete, [x] criteria
+- `.agent/progress/phases/phase-NN.md` — incremented progress fraction
+- `.agent/progress/index.md` — updated overall percentage
 
 Your `notify_user` payload **MUST** include:
-1. The raw output from the three commands above.
-2. The updated overall progress (e.g., "Overall progress is now 75% (24/32 slices)").
-3. The explicit next command: Run `/implement-slice` for [next slice name].
-
-If any command output shows unchecked criteria, a stale fraction, or a missing file, you have failed the workflow.
+1. Raw output from the three reads above
+2. Updated overall progress (e.g., "Overall progress is now 75% (24/32 slices)")
+3. Explicit next command: Run `/implement-slice` for [next slice name]
 
-**Infrastructure/Auth slice gate**: After completing progress tracking, check the slice name against the phase plan. If this was the `00-infrastructure` slice or the auth slice, the next command to run is `/verify-infrastructure`, not `/implement-slice`. Do not propose the next feature slice until `/verify-infrastructure` passes and produces a green report in `docs/audits/`.
+**Infrastructure/Auth slice gate**: If this was the `00-infrastructure` or auth slice, the next command is `/verify-infrastructure`, not `/implement-slice`.

package/template/.agent/workflows/implement-slice.md

@@ -6,7 +6,7 @@ pipeline:
   predecessors: [plan-phase]
   successors: [validate-phase]
   loop: true # repeats per slice within a phase
-  skills: [clean-code, code-review-pro, parallel-agents, parallel-debugging, parallel-feature-development, session-continuity, systematic-debugging, tdd-workflow, verification-before-completion]
+  skills: [clean-code, code-review-pro, minimalist-surgical-development, parallel-agents, parallel-debugging, parallel-feature-development, session-continuity, systematic-debugging, tdd-workflow, verification-before-completion]
   calls-bootstrap: true # may discover new dependencies during implementation
 shards: [implement-slice-setup, implement-slice-tdd]
 ---
@@ -35,7 +35,7 @@ Implement a single vertical slice using strict TDD: Red → Green → Refactor.
 
 ### Step A — Run `.agent/workflows/implement-slice-setup.md`
 
-Checks progress state and session continuity, loads all bundled skills, reads the slice acceptance criteria, determines if parallel mode applies, and writes the contract (Zod schema). If parallel mode is detected, dispatches agents for the TDD cycle.
+Checks progress state and session continuity, loads all bundled skills, reads the slice acceptance criteria, determines if parallel mode applies, and writes the contract ({{CONTRACT_LIBRARY}} schema). If parallel mode is detected, dispatches agents for the TDD cycle.
 
 ### Step B — Run `.agent/workflows/implement-slice-tdd.md`
 
@@ -46,7 +46,7 @@ Executes the TDD cycle (RED: write failing tests → GREEN: implement → REFACT
 ## Quality Gate
 
 You may not call `notify_user` until:
-- [ ] All tests pass (`{{TEST_COMMAND}}`)
-- [ ] Full validation passes (`{{VALIDATION_COMMAND}}`)
+- [ ] All tests pass (Test Cmd from surface stack map)
+- [ ] Full validation passes (Validation Cmd from surface stack map)
 - [ ] All 4 progress tracking files updated (slice, phase, index, memory)
 - [ ] Each tracking file verified by re-reading after edit

package/template/.agent/workflows/plan-phase-preflight.md

@@ -50,7 +50,7 @@ Read these skills for slice planning guidance:
 
 ## 0.5. Application Completeness Audit
 
-Read `{{SURFACES}}` from `.agent/instructions/tech-stack.md`. For each row below, only run the check if "Applies To" matches the project's confirmed surfaces. Skip inapplicable rows.
+Read the **Surfaces** list from the Global Settings section of `.agent/instructions/tech-stack.md`. For each row below, only run the check if "Applies To" matches the project's confirmed surfaces. Skip inapplicable rows.
 
 Read all FE specs in `docs/plans/fe/` and check the following table.
 
@@ -106,14 +106,18 @@ Do not proceed until the user confirms all uncovered specs are resolved.
 
 ### 0.6b. Cross-Layer Field and Contract Consistency
 
-Using the `cross-layer-consistency` skill's methodology, verify:
+Using the `cross-layer-consistency` skill's methodology as a guide, verify the following **minimum checks** regardless of skill depth:
 
 1. **Field mapping**: For every BE response field consumed by an FE component, verify the field name, type, and nullability match exactly between the BE spec and FE spec.
 2. **Error code propagation**: For every error code defined in a BE spec, verify the corresponding FE spec documents how that error is displayed to the user.
 3. **Access control consistency**: For every RBAC role referenced in a BE spec's access control, verify the FE spec's conditional rendering matrix includes that role.
+4. **Data contract drift**: For every IA shard entity, verify that the BE spec's request/response schemas contain all fields defined in the IA shard's data model — no fields silently dropped or renamed.
+5. **State management consistency**: For every FE component that manages optimistic updates, verify the corresponding BE endpoint's error response is specified well enough for the FE to roll back.
 
 Collect all mismatches into a consistency report. If any exist → **hard stop** and present them to the user for resolution before proceeding.
 
+> These 5 checks are **non-negotiable minimums**. The `cross-layer-consistency` skill may define additional checks — run those too, but never skip these 5 even if the skill doesn't mention them.
+
 ---
 
 ## 0.8. Draft continuity check

package/template/.agent/workflows/plan-phase-write.md

@@ -53,9 +53,9 @@ Read .agent/skills/concise-planning/SKILL.md and follow its methodology.
 Sort slices so each builds on the last:
 - Infrastructure slices first (DB schema, auth middleware)
 
-**Phase 1 special rule**: Before applying this rule, verify that `{{CI_CD_SKILL}}` and `{{HOSTING_SKILL}}` contain filled values (no literal `{{` characters). If unfilled, emit a **HARD STOP**: these placeholders are filled by `/create-prd-stack` — run it first.
+**Phase 1 special rule**: Before applying this rule, read the surface stack map from `.agent/instructions/tech-stack.md` and verify that the **CI/CD** and **Hosting** cross-cutting categories have filled values. If empty, emit a **HARD STOP**: these are filled by `/create-prd-stack` — run it first.
 
-The `00-infrastructure` shard is always the first slice. Verify it covers: (1) CI/CD pipeline setup — read `.agent/skills/{{CI_CD_SKILL}}/SKILL.md`, (2) environment configuration (`.env.example`), (3) deployment pipeline — read `.agent/skills/{{HOSTING_SKILL}}/SKILL.md`, (4) project scaffolding from `.agent/instructions/structure.md` (directories, `README.md` files, base configs), (5) database initialization. Add missing items before proceeding.
+The `00-infrastructure` shard is always the first slice. Verify it covers: (1) CI/CD pipeline setup — read the CI/CD skill(s) from the cross-cutting section of the surface stack map, (2) environment configuration (`.env.example`), (3) deployment pipeline — read the Hosting skill(s) from the cross-cutting section of the surface stack map, (4) project scaffolding from `.agent/instructions/structure.md` (directories, `README.md` files, base configs), (5) database initialization. Add missing items before proceeding.
 
 **Verification gates** (hard gates — add explicitly to the phase plan):
 - `/verify-infrastructure` MUST pass after the infrastructure slice, before any feature slice.
@@ -96,14 +96,12 @@ Read `.agent/skills/session-continuity/protocols/02-progress-generation.md` and
 ## 6.5. Bootstrap Completeness Gate
 
 Scan these four files for literal `{{` occurrences of `LANGUAGE_SKILL`, `HOSTING_SKILL`, `CI_CD_SKILL`, `ORM_SKILL`, `UNIT_TESTING_SKILL`, `E2E_TESTING_SKILL`:
-- `.agent/workflows/implement-slice-setup.md`
-- `.agent/workflows/implement-slice-tdd.md`
-- `.agent/workflows/verify-infrastructure.md`
-- `.agent/workflows/validate-phase.md`
 
-For each unfilled placeholder, read `docs/plans/*-architecture-design.md` to extract the confirmed value, then run `/bootstrap-agents` (see `.agent/workflows/bootstrap-agents.md`) with the corresponding key.
+> **Note**: As of v3, these files no longer contain literal `{{` placeholders — they reference the surface stack map. This gate now verifies that the surface stack map itself is fully populated for all surfaces involved in this phase.
 
-> ❌ STOP — Re-scan the four files. Only proceed to Step 7 when zero `{{` patterns remain. If any remain unfilled after bootstrap, tell the user which placeholders could not be provisioned.
+Read the surface stack map from `.agent/instructions/tech-stack.md`. Verify all per-surface and cross-cutting cells are filled. Verify `.agent/instructions/commands.md` has non-template values.
+
+> ❌ STOP — Only proceed to Step 7 when the map is fully populated. If any cells are empty after bootstrap, tell the user which cells could not be provisioned.
 
 ## 7. Request review and next steps
 

package/template/.agent/workflows/remediate-pipeline-assess.md

@@ -71,7 +71,7 @@ Check which layers have content by verifying the presence of key files:
 
 | Layer | Key Files to Check | Has Content If… |
 |-------|-------------------|-------------------|
-| Ideation | `docs/plans/ideation/ideation-index.md` | File exists and domains at `[DEEP]`+ |
+| Ideation | `docs/plans/ideation/ideation-index.md` | File exists, ≥1 domain folder under `domains/` (or `surfaces/`) with `*-index.md` + `*-cx.md`, and domains at `[DEEP]`+ in Structure Map |
 | Architecture | `docs/plans/*-architecture-design.md` | At least one dated file exists |
 | IA | `docs/plans/ia/index.md` | File exists with ≥1 shard listed |
 | BE | `docs/plans/be/index.md` | File exists with ≥1 spec listed |
@@ -80,6 +80,7 @@ Check which layers have content by verifying the presence of key files:
 For each layer with content, also note:
 - How many documents it contains (shards/specs count)
 - Whether any deep dive files exist (IA layer only)
+- For ideation: count of domain folders, total feature files, and CX files across the fractal tree
 
 ---
 

package/template/.agent/workflows/resolve-ambiguity.md

@@ -18,7 +18,7 @@ Targeted ambiguity resolution for any pipeline document or layer. Uses the `reso
 | Invocation | Behavior |
 |---|---|
 | `/resolve-ambiguity` | Interactive — asks which document or layer to resolve |
-| `/resolve-ambiguity ideation` | Targets `docs/plans/ideation/ideation-index.md` + domain files |
+| `/resolve-ambiguity ideation` | Targets `ideation-index.md` + `ideation-cx.md` + all fractal tree files |
 | `/resolve-ambiguity architecture` | Targets the architecture design documents |
 | `/resolve-ambiguity @path/to/spec.md` | Targets a specific file |
 
@@ -29,7 +29,7 @@ Targeted ambiguity resolution for any pipeline document or layer. Uses the `reso
 If no argument was provided, ask the user which document or layer to resolve. Accept a layer name (`vision`, `architecture`, `ia`, `be`, `fe`) or a direct `@file` path.
 
 For layer names, resolve to the canonical document(s):
-- `ideation` → `docs/plans/ideation/ideation-index.md` + all domain files in `docs/plans/ideation/domains/`
+- `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/YYYY-MM-DD-architecture-design.md` + `docs/plans/ENGINEERING-STANDARDS.md` + `docs/plans/data-placement-strategy.md`
 - `ia` → all files in `docs/plans/ia/` (excluding `index.md`)
 - `be` → all files in `docs/plans/be/` (excluding `index.md`)

package/template/.agent/workflows/update-architecture-map.md

@@ -39,7 +39,7 @@ Analyze the project structure using file exploration tools. Do not just stop at
 Read .agent/skills/architecture-mapping/SKILL.md and follow its component analysis methodology.
 
 Group files logically into components, but extract their exact contracts:
-- Use `grep_search` to find `z.object` or `interface` definitions.
+- Use `grep_search` to find contract/validation schema definitions. Search for patterns appropriate to the project's contract library (e.g., `z.object` for Zod, `BaseModel` for Pydantic, `Joi.object` for Joi, `schema(` for Yup, `struct` for Rust/Go, or `interface`/`type` definitions for TypeScript). Check `.agent/instructions/tech-stack.md` for the project's confirmed contract library if unsure.
 - Document exact schema names, required environment variables, and binding names (e.g., KV namespaces, R2 buckets).
 
 ## 3. Map Explicit Data Flow and Relationships
@@ -65,10 +65,27 @@ Create or update `docs/ARCHITECTURE.md`.
 
 Ensure the document is human-readable, well-structured, and focuses on high-level system interactions rather than low-level functional documentation.
 
-## 6. Present Results and Next Steps
+## 6. Phase completion gate
 
-Use `notify_user` to present a summary of the architecture map updates.
+Read `docs/plans/*-architecture-design.md` → **Phasing** section to determine the total number of planned phases.
+Read `.agent/progress/index.md` to determine the current phase number N and how many phases have `status: complete`.
 
-### Proposed next steps
+### If completed phases < total phases
 
-"Architecture map updated. Next: Run `/plan-phase` for the next phase, or if all phases are complete, the project is ready for deployment — refer to your CI/CD pipeline configuration and the deployment procedures documented in `docs/plans/ENGINEERING-STANDARDS.md`."
+The pipeline has more phases to implement. Present:
+
+> "Architecture map updated for Phase N. **Next**: Run `/plan-phase` for Phase [N+1]."
+
+### If completed phases = total phases
+
+All phases are complete. The pipeline has reached its terminal state. Present:
+
+> "✅ **All phases complete.** Architecture map updated. The project is ready for deployment.
+>
+> - Refer to `docs/plans/ENGINEERING-STANDARDS.md` for deployment procedures
+> - Refer to your CI/CD pipeline configuration for automated deployment
+> - Run `/validate-phase` for the final phase if not already done
+>
+> No further `/plan-phase` iterations are needed."
+
+**Do NOT propose `/plan-phase` after the final phase.** The loop terminates here.

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

@@ -0,0 +1,155 @@
+---
+description: Code quality gates — tests, coverage, lint, type-check, build, CI/CD, staging deploy, migrations, spec coverage for the validate-phase workflow
+parent: validate-phase
+shard: quality
+standalone: true
+position: 1
+pipeline:
+  position: 8.1
+  stage: verification
+  predecessors: [implement-slice]
+  successors: [validate-phase-readiness]
+  skills: [code-review-pro, deployment-procedures, testing-strategist, verification-before-completion]
+  calls-bootstrap: false
+---
+
+// turbo-all
+
+# Validate Phase — Code Quality Gates
+
+Run all code quality checks for 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
+
+---
+
+## 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):
+
+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.
+
+---
+
+## 5.5. CI/CD pipeline verification
+
+Verify the CI/CD pipeline is green for this phase's changes:
+
+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)
+
+**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.
+
+**Pass criteria**: CI/CD pipeline is green for the latest commit in this phase.
+
+---
+
+## 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.6.5. Deployment strategy verification
+
+Read the project's architecture design document (`docs/plans/*-architecture-design.md`) and look for a `## Deployment Strategy` section.
+
+**If no deployment strategy is defined** → Log: "No deployment strategy in architecture doc. Using direct deploy." Proceed.
+
+**If a deployment strategy is defined**:
+1. Verify the deployment in Step 5.6 followed the documented strategy (e.g., canary → verify traffic was gradually shifted; blue-green → verify old environment is still available for rollback; rolling → verify instances were replaced sequentially)
+2. If the architecture documents feature flags as the rollout mechanism → verify the new features in this phase are behind flags
+3. Verify the documented rollback trigger mechanism is configured (error rate monitoring, latency threshold alert, or manual switch — whatever the architecture specifies)
+
+**Pass criteria**: Deployment follows the architecture-documented strategy, or no strategy is documented.
+
+---
+
+## 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.
+
+---
+
+### Propose next step
+
+Code quality gates complete. Next: Run `.agent/workflows/validate-phase-readiness.md` for production readiness checks.
+
+> If this shard was invoked standalone (not from `/validate-phase`), surface this via `notify_user`.