cfsa-antigravity 2.7.0 → 2.9.0

package/template/.agent/workflows/decompose-architecture-validate.md

@@ -19,118 +19,67 @@ pipeline:
 
 Identify deep dive candidates, annotate shard document types, validate the dependency graph, generate the spec pipeline tracker, and request review.
 
-**Prerequisite**: Directory structure, shard skeletons, and layer indexes must exist (from `/decompose-architecture-structure` or equivalent). The IA index at `docs/plans/ia/index.md` and shard files must be in place.
+**Prerequisite**: Directory structure, shard skeletons, and layer indexes must exist (from `/decompose-architecture-structure`).
 
 ---
 
 ## 9.5. Proactive shard load pre-check (ideation signal)
 
-Before identifying deep dives, read the ideation domain folders that fed each shard. The sub-area count from ideation is a **leading indicator** of shard complexity.
+Read `.agent/skills/prd-templates/references/shard-boundary-analysis.md` → **Shard Load Thresholds** table.
 
 For each shard skeleton:
-1. Read the corresponding ideation domain folder (use the path from `ideation-index.md` Structure Map — may be under `domains/` or `surfaces/{name}/`). Read the folder's `*-index.md` for the children table.
-2. Count the child feature files and sub-domain folders listed in the domain index
-3. Compare against the shard load thresholds:
-
-| Ideation Sub-Areas | Pre-Check Action |
-|---|---|
-| ≤6 | ✅ No concern — proceed to skeleton validation |
-| 7–9 | ⚠️ **Pre-flag for split review** — note in the shard skeleton: `> ⚠️ Ideation source has [N] sub-areas — likely split candidate. Review at calibration gate.` |
-| ≥10 | 🚩 **Proactive split proposal** — present a split proposal to the user NOW, before the calibration gate. Use the same split format as Step 12. If the user approves, create the split shards immediately and update the decomposition plan. |
-
-> **Why proactive?** The reactive calibration gate (Step 12) catches overloaded shards, but only after skeletons are fully seeded. By reading ideation sub-area counts first, we avoid creating a massive skeleton only to immediately split it. For multi-product projects where a single surface domain (e.g., "Operations" in a desktop shop app) might have 15+ sub-areas, this saves significant rework.
+1. Read the corresponding ideation domain folder via `ideation-index.md` Structure Map
+2. Count child feature files and sub-domain folders in the domain index
+3. Compare against the load thresholds table and take the specified action
 
 ## 10. Identify deep dive candidates
 
-Read .agent/skills/architecture-mapping/SKILL.md and follow its methodology.
+Read `.agent/skills/architecture-mapping/SKILL.md` and follow its methodology.
 
 For each shard marked "Needs Deep Dive" in the domain boundary table:
-
-1. Create an empty deep dive skeleton at `docs/plans/ia/deep-dives/[feature-name].md`
-   - **Naming convention**: Use kebab-case derived from the feature name (e.g., `chat-orchestration.md`, `age-verification-flow.md`, `order-state-machine.md`)
-2. Add a reference to it in the parent shard's "Deep Dives Needed" section
-3. Add it to the IA index deep dives column
+1. Create empty deep dive skeleton at `docs/plans/ia/deep-dives/[feature-name].md`
+2. Add reference in parent shard's "Deep Dives Needed" section
+3. Add to IA index deep dives column
 
 ## 11. Annotate expected shard types
 
-Based on domain boundary analysis, add a **preliminary** `Document Type`
-annotation to each shard skeleton. `/write-architecture-spec` confirms or reclassifies.
-
-| Classification | Expected BE Specs |
-|---------------|-------------------|
-| **Feature domain** | 1 |
-| **Multi-domain** | N (split along sub-feature boundaries) |
-| **Cross-cutting** | 1 (`00-*`) |
-| **Structural reference** | 0 |
-
-```markdown
-> **Document Type** (preliminary): Feature domain | Multi-domain | Cross-cutting | Structural reference
-```
-
-> **Note**: Classification is based on domain analysis, not shard content (which doesn't
-> exist yet). `/write-be-spec` uses the confirmed type to determine spec count.
+Read `.agent/skills/prd-templates/references/shard-boundary-analysis.md` → **Shard Document Type Classification** table. Add preliminary Document Type annotation to each shard skeleton.
 
 ## 12. Dependency graph validation
 
-Verify the decomposition (structural checks only — content doesn't exist yet):
-
-Read .agent/skills/architecture-mapping/SKILL.md and follow its methodology for dependency graph validation.
+Read `.agent/skills/architecture-mapping/SKILL.md` and follow its dependency graph validation methodology.
 
-- **Must Have coverage gate**: Read `docs/plans/ideation/ideation-index.md` and extract every feature listed under "Must Have" in the MoSCoW Summary. For each Must Have feature, verify it appears in at least one shard's Features section. If any Must Have feature is not covered by any shard → **STOP**: "The following Must Have features from ideation-index.md are not covered by any shard: [list]. Add them to the appropriate shards before proceeding."
+Read `.agent/skills/prd-templates/references/shard-boundary-analysis.md` → **Sub-feature Count Thresholds** and **Split Proposal Format**.
 
-- **Shard load calibration gate**: After the Must Have coverage gate passes, count the sub-features in each shard's `## Features` section using the **bullet/named-item rule**: count every bullet point or named item under `## Features`, **excluding** group headers (lines that introduce a group of sub-features but are not themselves a concrete capability). If Step 9.5 pre-flagged any shards, they should be reviewed first. Compare against the following thresholds:
+- **Must Have coverage gate**: Read `ideation-index.md` MoSCoW Summary. Every Must Have feature must appear in at least one shard. If any missing → **STOP**.
 
-  | Sub-feature Count | Action |
-  |-------------------|--------|
-  | **≤6** | ✅ OK — proceed |
-  | **7–9** | ⚠️ Flag for user review — present the sub-feature list and ask: "This shard has [N] sub-features. Keep as-is, or split?" |
-  | **≥10** | 🛑 **Hard stop** — do NOT proceed. Present a mandatory split proposal and **wait for the user to approve the split** before continuing. No shard may exit this gate with ≥10 sub-features. |
+- **Shard load calibration gate**: Count sub-features in each shard using the bullet/named-item rule (defined in the analysis reference). If Step 9.5 pre-flagged shards, review first. Apply the thresholds. For ≥10, use the split proposal format from the reference.
 
-  > **What counts as a sub-feature**: Count each bullet or named item under `## Features`. Group headers (e.g., "Content Management:") that introduce a cluster of sub-features are **not** counted — only the items beneath them. If a bullet contains sub-bullets, count each sub-bullet independently. When in doubt, ask: "Would a product manager list this as a separate line item in a release note?"
+  **After any split**: Update `docs/plans/ia/decomposition-plan.md` and re-run Must Have coverage gate.
 
-  **Split proposal format:**
-  ```
-  Shard [NN] — [domain name] has [N] sub-features (threshold: ≥10 → mandatory split)
-  
-  Current sub-features:
-    1. [sub-feature]
-    2. [sub-feature]
-    ...
-  
-  Proposed split:
-    [NN]a — [new domain name] → file: docs/plans/ia/[NN]a-[domain].md
-      Sub-features: 1, 3, 5
-    [NN]b — [new domain name] → file: docs/plans/ia/[NN]b-[domain].md
-      Sub-features: 2, 4, 6
-  
-  Split rationale: [why these groups are independent]
-  ```
-
-  **After any split**: Update `docs/plans/ia/decomposition-plan.md` with the revised domain boundary table and re-run the Must Have coverage gate to confirm no features were lost in the split.
+  **Split loop guard**: Track how many times the same shard has been split.
+  - **1st split** → normal. Apply the split.
+  - **2nd split on the same shard** → warn: "Shard `[name]` has been split twice. This may indicate the domain boundary is wrong. Present to user: re-split, or merge back and redraw the domain boundary?"
+  - If the total number of shards exceeds 20 → warn: "Shard count is [N]. Projects with 20+ shards are unusually large. Verify this is correct with the user."
 
+Verify structural integrity:
 - [ ] No circular dependencies between shards
 - [ ] Cross-cutting shards (00-*) don't depend on feature shards
 - [ ] Every shard has a preliminary Document Type annotation
-- [ ] Deep dive candidates are referenced from their parent shards
-- [ ] BE/FE indexes exist with conventions templates (mapping tables will be populated later)
-- [ ] For multi-surface: shared surface shards have lower numbers than surface-specific shards that depend on them
-- [ ] For multi-surface: each surface has its own index.md with IA/BE/FE layer table
-- [ ] For multi-surface: cross-surface dependencies point to shared/ shards, not directly to another surface's shards
+- [ ] Deep dive candidates are referenced from parent shards
+- [ ] BE/FE indexes exist with conventions templates
+- [ ] Multi-surface: shared shards have lower numbers; cross-surface deps point to shared/
 
 ## 13. Generate spec pipeline tracker
 
-Read `.agent/skills/session-continuity/protocols/07-spec-pipeline-generation.md` and follow the **Spec Pipeline Generation Protocol**
-to create `.agent/progress/spec-pipeline.md` tracking IA/BE/FE completion per shard.
+Read `.agent/skills/session-continuity/protocols/07-spec-pipeline-generation.md` and follow the Spec Pipeline Generation Protocol.
 
 ## 14. Request review and propose next steps
 
-Use `notify_user` to present:
-- The full `docs/plans/ia/` directory (shard skeletons + index)
-- `docs/plans/be/index.md`
-- `docs/plans/fe/index.md`
-- `docs/plans/index.md`
-- `.agent/progress/spec-pipeline.md`
+Use `notify_user` to present: IA directory, BE index, FE index, master index, spec pipeline tracker.
+
+**STOP** — do NOT proceed until the user explicitly approves.
 
-The decomposition must be approved before filling in shards with `/write-architecture-spec`. Do NOT proceed to the next step until the user sends a message explicitly approving this output. Proposing next steps is not the same as receiving approval. Wait for explicit approval before continuing.
+### Next step
 
-**Proposed next step**: Once approved, run `/write-architecture-spec` starting with the lowest-numbered skeleton shard. Read `.agent/progress/spec-pipeline.md` to identify which shard to start with.
+**STOP** — do NOT proceed to any other workflow. The only valid next step is `/write-architecture-spec` starting with the lowest-numbered shard per `.agent/progress/spec-pipeline.md`.

package/template/.agent/workflows/decompose-architecture.md

@@ -17,7 +17,7 @@ shards: [decompose-architecture-structure, decompose-architecture-validate]
 Break the architecture design document into domain-bounded IA shards and create the full spec layer structure.
 
 **Input**: `docs/plans/YYYY-MM-DD-architecture-design.md` (must exist and be approved)
-**Output**: `docs/plans/ia/`, `docs/plans/be/`, `docs/plans/fe/` directories with indexes and shard skeletons (or per-surface subdirectories for multi-surface projects)
+**Output**: `docs/plans/ia/`, `docs/plans/be/`, `docs/plans/fe/` directories with indexes and shard skeletons
 
 ---
 
@@ -25,84 +25,56 @@ Break the architecture design document into domain-bounded IA shards and create
 
 Read the file at `docs/plans/*-architecture-design.md`.
 
-If no architecture design exists, tell the user to run `/create-prd` first. Do not proceed without an approved design.
+If no architecture design exists → **STOP**: tell the user to run `/create-prd` first.
 
-Also check the document's `**Status**:` field. If the status is `Draft` or `Review` → **STOP**: "The architecture design is not yet approved (current status: [status]). Get explicit approval from the user and update the status to `Approved` before decomposing."
+**Multi-file handling**: If the glob matches multiple files (e.g., multiple dated versions):
+- Use the file with the most recent date prefix
+- Warn: "Multiple architecture-design files found. Using `[filename]` (most recent). If this is wrong, specify the correct file."
 
-Also read `docs/plans/ideation/ideation-index.md` for the fractal domain map and structural classification. The ideation folder uses a fractal structure — read domain indexes (not flat files) to understand depth, child counts, and cross-cut density.
+Check the document's `**Status**:` field.
+- If `Draft` or `Review` → **STOP**: "Architecture design not yet approved. Get explicit approval first."
+- If the `**Status**:` field does not exist → **STOP**: "Architecture design document has no Status field. Add `**Status**: Approved` after explicit review, or run `/create-prd` to regenerate."
 
-> **Design system prerequisite (web/mobile/desktop projects)**: Read `.agent/instructions/tech-stack.md` and locate the `SURFACES` value. If surfaces include `web`, `mobile`, or `desktop`, verify that `docs/plans/design-system.md` exists and is not empty.
->
-> If it does not exist:
->
-> ⚠️ **Warning**: FE specs for this project require a design system (`docs/plans/design-system.md`). Run `/create-prd-design-system` before writing any FE specs. You may continue with architecture decomposition now, but the design system must be completed before the FE spec writing phase.
+Read `docs/plans/ideation/ideation-index.md` for the fractal domain map and structural classification.
+
+> **Design system prerequisite (web/mobile/desktop projects)**: Read `.agent/instructions/tech-stack.md` → `SURFACES`. If surfaces include `web`, `mobile`, or `desktop`, verify `docs/plans/design-system.md` exists.
 >
-> This is a warning, not a hard stop — architecture decomposition can proceed. API-only, CLI, and extension projects are not affected.
+> If not: ⚠️ **Warning** — run `/create-prd-design-system` before writing FE specs. Architecture decomposition can proceed. API-only/CLI/extension projects unaffected.
+
+Identify **Project Type** from the architecture design header:
+- **Single-surface** → standard flat structure
+- **Multi-surface** → per-surface subdirectories with shared layer
 
-Identify the **Project Type** from the architecture design header:
-- **Single-surface** (web, desktop, mobile, CLI, API) → standard flat structure
-- **Multi-surface** (desktop + web, mobile + web, etc.) → per-surface subdirectories with shared layer
+**Surface consistency check**: Compare the Project Type derived here with `## Structural Classification` in `ideation-index.md`. If they conflict (e.g., ideation says single-surface but architecture says multi-surface) → **STOP**: "Surface classification mismatch between ideation (`[ideation value]`) and architecture design (`[arch value]`). Resolve via `/propagate-decision` before decomposing."
 
 ## 2. Load brainstorming skill
 
-Read `.agent/skills/brainstorming/SKILL.md` — domain boundary decisions benefit from collaborative exploration.
+Read `.agent/skills/brainstorming/SKILL.md`.
 
 ## 3. Identify domain boundaries
 
-Read .agent/skills/architecture-mapping/SKILL.md and follow its methodology.
-
-Analyze the architecture design and identify natural domain boundaries. Each boundary becomes a numbered IA shard.
-
-**Fractal tree analysis for shard boundaries:**
-
-The ideation folder uses a fractal structure. Walk the tree to inform shard granularity:
+Read `.agent/skills/architecture-mapping/SKILL.md` and follow its Domain Boundary Protocol.
 
-| Signal | What It Means for Sharding |
-|--------|---------------------------|
-| Deep fractal tree (3+ levels) | Domain is complex enough for its own shard |
-| Many children (5+ features) | Consider splitting into multiple shards |
-| Dense CX file (5+ cross-cuts) | This domain has high coupling — keep it together in one shard, or isolate carefully |
-| Rich Role Matrix (3+ roles with access) | Shard needs multi-role IA spec coverage |
-| Hub-and-spoke shared domains | Shared domains often become `00-*` cross-cutting shards |
-| Leaf features marked `[EXHAUSTED]` | Most confident for shard scoping — behavior is fully defined |
+Read `.agent/skills/prd-templates/references/shard-boundary-analysis.md` for fractal tree signals and standard heuristics.
 
-**Standard heuristics also apply:**
-- Features that share the same data models belong together
-- Features that can be developed/deployed independently are candidates for separation
-- Features that share the same access control model may belong together
-- Cross-cutting concerns (auth, API conventions, error handling) become `00-*` shards
+Walk the ideation fractal tree to inform shard granularity. Build the domain inventory record, apply split trigger rules, produce the domain boundary table.
 
-Read `.agent/skills/architecture-mapping/SKILL.md` and follow its Domain Boundary Protocol. Build the domain inventory record, apply all three split trigger rules, and produce the domain boundary table. Present split candidates to the user before locking any boundary.
-
-> **Important**: Ideation does NOT prescribe shard boundaries. It provides the raw data (depth, features, cross-cuts, roles). This workflow makes the shard boundary decisions based on architectural analysis.
+> **Important**: Ideation does NOT prescribe shard boundaries. It provides raw data. This workflow makes boundary decisions based on architectural analysis.
 
 Present the proposed domain decomposition to the user for validation.
 
 ## 4. Assign shard numbers
 
-Follow the numbering convention:
-- `00-*` — Cross-cutting/foundation concerns (may have multiple: `00-api-conventions`, `00-auth-middleware`, etc.)
-- `01-*` through `NN-*` — Feature domains, ordered by dependency (dependencies first)
-
-Order rule: If shard B depends on shard A, then A gets a lower number than B.
+- `00-*` — Cross-cutting/foundation concerns
+- `01-*` through `NN-*` — Feature domains, dependency-ordered (lower = fewer deps)
 
 ## 4.5. Request approval of domain boundaries
 
-**STOP HERE** and present the domain boundary table and shard numbering to the user for explicit approval. Use `notify_user` to present:
-
-1. The complete domain boundary table from Step 3
-2. The proposed shard numbering from Step 4
-3. The dependency ordering rationale
-4. Any shards marked as needing deep dives
-
-Ask:
-- "Does this decomposition capture every feature from the architecture design?"
-- "Are the domain boundaries in the right places, or should any be split/merged?"
-- "Is the dependency ordering correct?"
+**STOP** — present domain boundary table, shard numbering, dependency ordering, and deep dive candidates to the user via `notify_user`.
 
-**Do not proceed** to shard skeleton creation until the user explicitly approves the domain boundaries. If the user requests changes, revise Steps 3-4 and re-present.
+**Do not proceed** until the user explicitly approves.
 
-**Write `docs/plans/ia/decomposition-plan.md` immediately after user approval of the domain list, before proceeding to skeleton creation. This is a single gate — write the plan once, then proceed to the Shard Overview.**
+**Write `docs/plans/ia/decomposition-plan.md` immediately after approval**, before proceeding to skeleton creation.
 
 ---
 
@@ -118,9 +90,4 @@ Ask:
 ## Orchestration
 
 ### Step A — Run `.agent/workflows/decompose-architecture-structure.md`
-
-Creates the directory structure (with multi-surface subdirectories if needed), writes shard skeleton files, and creates the IA, BE, FE, and master index files.
-
 ### Step B — Run `.agent/workflows/decompose-architecture-validate.md`
-
-Identifies deep dive candidates, annotates expected shard document types, validates the dependency graph, generates the spec pipeline tracker, and requests user review.

package/template/.agent/workflows/evolve-contract.md

@@ -61,6 +61,11 @@ Document all consumers:
 - Test files
 - Other contracts that reference this one
 
+**Zero-consumer path**: If no consumers are found (only the schema definition itself):
+- Confirm with user: "Contract [name] has zero consumers. It can be modified directly without migration safeguards. Proceed with simple edit?"
+- If confirmed → skip Steps 3-5, apply the schema change directly, run validation (Step 6), then proceed to Step 6.5.
+- If user declines → proceed normally (the contract may have planned but not-yet-implemented consumers).
+
 ### 2.5. API versioning check (conditional)
 
 If any consumer is a **public-facing API endpoint** (i.e., called by external clients, not just internal frontend):
@@ -96,9 +101,9 @@ Modify the {{CONTRACT_LIBRARY}} schema. For breaking changes:
 
 ## 4.5. New dependency check
 
-If the contract change introduces a dependency not currently in the skill set — for example, a new validation library plugin, a schema extension, a binary serialization library, or a new validation pattern — read `.agent/workflows/bootstrap-agents.md` and invoke `/bootstrap-agents NEW_DEPENDENCY=[package]` before updating consumers in Step 5.
+If the contract change introduces a dependency not currently in the skill set — for example, a new validation library plugin, a schema extension, a binary serialization library, or a new validation pattern — read `.agent/workflows/bootstrap-agents.md` and invoke `/bootstrap-agents NEW_DEPENDENCY=[package]` before updating consumers in Step 5. **HARD GATE**: Follow the bootstrap verification protocol (`.agent/skills/prd-templates/references/bootstrap-verification-protocol.md`).
 
-Confirm the matching skill is installed (or no new dependency was introduced) before proceeding to Step 5.
+If no new dependency was introduced, proceed directly to Step 5.
 
 ## 5. Update all consumers
 

package/template/.agent/workflows/evolve-feature-cascade.md

@@ -17,32 +17,32 @@ pipeline:
 
 Cascade the new content from the entry point through all downstream layers with existing content, assess implementation impact, run a consistency check, and write the evolution record.
 
-> **Prerequisite**: The entry point document must already contain the new content (written by `/evolve-feature-classify` Step 4). The cascade scope must be determined (Step 5 output).
+> **Prerequisite**: Entry point document must contain the new content (from `/evolve-feature-classify` Step 4). Cascade scope must be determined (Step 5 output).
+
+**Locked decision conflict check**: Before cascading, scan the new content against locked decisions in upstream layers:
+1. Read the architecture design document (`docs/plans/*-architecture-design.md`) for locked constraints
+2. Compare each element of the new feature against: tech stack decisions, data placement strategy, security model, performance budgets
+3. **If conflict detected** → **STOP**: "New feature '[name]' conflicts with locked decision: [decision]. Options: (1) Modify the feature to work within the constraint, (2) Use `/propagate-decision` to change the locked decision first, then re-run `/evolve-feature`."
+4. **If no conflicts** → proceed to Step 1.
 
 ---
 
 ## 1. Cascade through each downstream layer
 
-Read .agent/skills/technical-writer/SKILL.md and apply its writing standards to all spec additions and the evolution record.
-
-For each downstream layer with existing content (in order: architecture → IA → BE → FE → phase plan):
+Read `.agent/skills/technical-writer/SKILL.md` for writing standards.
 
-1. **Read existing documents** in the layer
-2. **Determine what the new feature means for this layer** — what sections need additions, what contracts change, what new components are needed
-3. **Write the additions** — new sections, new entries in existing tables, new acceptance criteria, new contracts. Write at the same depth and quality as the existing content in the layer.
-4. **Present additions to user** — show exactly what was added and where
+Read `.agent/skills/prd-templates/references/evolution-layer-guidance.md` → **Cascade Layer Guidance** table.
 
-**STOP at each layer** — do not cascade to the next layer until the user approves the current layer's additions.
+For each downstream layer with existing content (in order: architecture → IA → BE → FE → phase plan):
 
-Layer-specific guidance:
+1. Read existing documents in the layer
+2. Determine what the new feature means for this layer — consult the guidance table for what to add
+3. Write the additions at the same depth and quality as existing content
+4. Present additions to user
 
-- **Architecture layer**: Add new components, update system diagrams references, add NFRs, update integration points
-- **IA layer**: Add new domain interactions, update contracts, add data model changes, update access control
-- **BE layer**: Add new API endpoints, update schemas, add middleware requirements, update validation rules
-- **FE layer**: Add new components, update state management, add new routes, update accessibility requirements
-- **Phase plan**: Add new slices or update existing slice acceptance criteria (see Step 2)
+**STOP at each layer** — do not cascade to next until user approves.
 
-> After writing additions to any spec document in this step, append a row to that spec's `## Changelog` table recording: today's date, `'Evolution: [brief description of what was added]'`, this workflow (`/evolve-feature-cascade`), and the sections of the spec that were updated. If the spec does not yet have a `## Changelog` section, add one following the template in `.agent/skills/prd-templates/references/be-spec-template.md` (for BE specs) or the equivalent FE/IA template before appending the row.
+> After writing to any spec document, append a `## Changelog` row: date, `'Evolution: [description]'`, workflow, updated sections. If no `## Changelog` exists, add one from the template in `.agent/skills/prd-templates/references/be-spec-template.md`.
 
 ---
 
@@ -50,91 +50,47 @@ Layer-specific guidance:
 
 If `docs/plans/phases/` exists and contains phase plans:
 
-1. **Check in-progress slices** — do any currently in-progress slices need their acceptance criteria updated? List the affected criteria.
-2. **Check completed slices** — do any completed slices that may need revisiting? (This is a red flag — document it clearly with regression risk assessment)
-3. **Determine if new slices are needed** — does the new feature require new implementation slices in the current phase? If yes, draft the slice names and acceptance criteria.
-4. **Determine if phase plan update is required** — does the scope require changes to the phase plan structure?
-
-Present the impact assessment:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Implementation Impact
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-In-progress slices affected:              [list or "none"]
-Completed slices that may need revisiting: [list or "none"]
-New slices needed:                        [list or "none"]
-Phase plan update required:               [yes/no]
+1. Check in-progress slices for affected acceptance criteria
+2. Check completed slices that may need revisiting (flag regression risk)
+3. Determine if new slices are needed
+4. Determine if phase plan update is required
 
-Recommended action: [specific next step]
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
+Read `.agent/skills/prd-templates/references/evolution-layer-guidance.md` → **Impact Assessment Format** and use it to present.
 
-If no phase plans exist, skip this step and note: "No phase plans exist yet — implementation impact will be assessed during `/plan-phase`."
+If no phase plans exist: "No phase plans yet — impact assessed during `/plan-phase`."
 
 ---
 
 ## 3. Run consistency check
 
-Read .agent/skills/resolve-ambiguity/SKILL.md and follow its methodology.
+Read `.agent/skills/resolve-ambiguity/SKILL.md` and follow its methodology.
 
-For every document that received additions in Step 1:
+For every document that received additions:
+1. Re-read full document — verify additions integrate correctly
+2. Check for internal contradictions
+3. Check cross-references between changed documents
+4. Check against locked decisions
 
-1. **Re-read the full document** — verify the additions integrate correctly with existing content
-2. **Check for internal contradictions** — do the additions conflict with anything else in the same document?
-3. **Check cross-references between changed documents** — if multiple documents were updated, verify they are consistent with each other
-4. **Check against locked decisions** — do the additions contradict any locked architectural decisions?
-
-Report any issues found. **Do not auto-fix** — present them to the user for review.
+Report issues. **Do not auto-fix** — present to user.
 
 ---
 
 ## 4. Write evolution record
 
-Write `docs/audits/evolve-feature-[name]-[date].md` recording:
-
-- **Feature name** — short identifier for the evolution
-- **Change type** — classification from Step 2 of `/evolve-feature-classify`
-- **Entry point** — which document received the initial content
-- **New content written** — summary of what was added at the entry point
-- **Layers updated** — list of downstream layers that received additions
-- **Per-layer additions** — what was added at each layer (summary, not full content)
-- **Implementation impact** — assessment from Step 2 (if applicable)
-- **Consistency check results** — pass/fail with details
-- **Timestamp** of the evolution run
+Write `docs/audits/evolve-feature-[name]-[date].md` recording: feature name, change type, entry point, new content summary, layers updated, per-layer additions, implementation impact, consistency check results, timestamp.
 
 ---
 
 ## 4.5. Bootstrap gate — new dependency check
 
-Before closing the cascade, scan every document that was updated in Step 1 for any technology, library, or service referenced in the new content that does not have a corresponding installed skill directory in `.agent/skills/`.
-
-For each missing skill:
-1. Identify the technology (e.g., WebSocket, S3 storage, Stripe, Redis)
-2. Read `.agent/workflows/bootstrap-agents.md` and invoke `/bootstrap-agents NEW_DEPENDENCY=[technology]`
-3. Confirm the matching skill is installed before proceeding to Step 5
+Scan updated documents for technologies without corresponding skill directories.
 
-If no new unregistered technologies were introduced, skip and proceed to Step 5.
+For each missing skill: read `.agent/workflows/bootstrap-agents.md` and invoke. **HARD GATE**: follow bootstrap verification protocol (`.agent/skills/prd-templates/references/bootstrap-verification-protocol.md`).
 
 ---
 
 ## 5. Propose next steps
 
-Display the completion summary:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Feature Evolution Complete
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Entry point:       [document]
-Layers updated:    [list]
-New content:       [summary]
-Implementation:    [impact summary]
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-❗ **Mandatory next step — do not skip**: The evolution just added or modified content across [N] layers. Evolution bypasses the normal deepening phase — the audit is the quality gate that replaces it.
-
-Run `/audit-ambiguity` on the affected layers before any implementation work touches these documents. The affected layers are: [list the layers that were updated during the cascade — populated from Step 1's output].
+Read `.agent/skills/prd-templates/references/evolution-layer-guidance.md` → **Completion Summary Format** and present.
 
-This is not optional. Under-specified evolution content is the single most common source of spec drift. The audit catches what the inline micro check may have missed at a cross-document level.
-```
+❗ **Mandatory next step**: Run `/audit-ambiguity` on affected layers before any implementation work. List the layers updated during Step 1.

package/template/.agent/workflows/evolve-feature-classify.md

@@ -17,7 +17,7 @@ pipeline:
 
 Capture the user's new feature, requirement, or constraint. Classify it, identify the correct entry point document, write the new content at proper spec depth, and determine which downstream layers need updating.
 
-> **Prerequisite**: At least `docs/plans/ideation/ideation-index.md` must exist. If the pipeline hasn't started, run `/ideate` first — there's nothing to evolve yet.
+> **Prerequisite**: `docs/plans/ideation/ideation-index.md` must exist. If not → **STOP**: run `/ideate` first.
 
 ---
 
@@ -25,100 +25,66 @@ Capture the user's new feature, requirement, or constraint. Classify it, identif
 
 Ask the user to describe what they want to add. Accept free-form input or `@file`.
 
-If the user provides an `@file` reference, read the file and extract the key additions. If free-form, engage briefly to ensure the addition is clear — but this is NOT a full `/ideate` interview. The goal is to understand what's being added, not to explore the entire problem space.
+If `@file` → read and extract key additions. If free-form → brief clarifying questions only (NOT a full `/ideate` interview).
 
 ---
 
 ## 2. Classify the change
 
-Read .agent/skills/brainstorming/SKILL.md and follow its methodology.
+Read `.agent/skills/brainstorming/SKILL.md` and follow its methodology.
 
 Present the classification menu:
 
 ```
 What type of change is this?
 
-[1] New feature — an entirely new capability that doesn't exist in the current specs
-[2] New requirement on an existing feature — additional constraint, behavior, or acceptance criteria for something already specified
-[3] New technical constraint — a non-functional requirement that affects architecture (performance, compliance, infrastructure)
-[4] Scope correction — something was misunderstood or underspecified in existing specs and needs to be fixed
+[1] New feature — entirely new capability
+[2] New requirement on existing feature — additional constraint/behavior/criteria
+[3] New technical constraint — non-functional requirement affecting architecture
+[4] Scope correction — misunderstanding or underspecification that needs fixing
 ```
 
-**Do not proceed until the user selects.**
+**STOP** — do not proceed until the user selects.
 
 ---
 
 ## 3. Identify the entry point document
 
-Based on the classification, determine where the new content enters the pipeline:
-
-| Classification | Entry Point Document | Rationale |
-|---------------|---------------------|-----------|
-| **[1] New feature** | `docs/plans/ideation/ideation-index.md` + fractal tree placement (see Step 4) | New features start at the ideation layer — placed in the correct domain folder via Classification Gate |
-| **[2] New requirement** | The IA shard that owns the affected domain | Requirements on existing features enter at the domain interaction level |
-| **[3] New technical constraint** | `docs/plans/[dated]-architecture-design.md` | Technical constraints affect the architecture and everything below it |
-| **[4] Scope correction** | Ask the user which document contains the misunderstanding | Corrections enter wherever the original misunderstanding lives |
-
-For classification [2], identify which IA shard owns the affected domain by reading `docs/plans/ia/index.md` and matching the feature to a domain.
+| Classification | Entry Point Document |
+|---------------|---------------------|
+| **[1] New feature** | `docs/plans/ideation/ideation-index.md` + fractal tree placement (Step 4) |
+| **[2] New requirement** | The IA shard that owns the affected domain (read `docs/plans/ia/index.md` to find it) |
+| **[3] New technical constraint** | `docs/plans/[dated]-architecture-design.md` |
+| **[4] Scope correction** | Ask the user which document contains the misunderstanding |
 
 ---
 
 ## 4. Write new content at the entry point
 
-Read .agent/skills/technical-writer/SKILL.md and follow its clarity standards for all new spec content.
-
-This is a real spec-writing step — not a placeholder. Write the new content at the appropriate depth for the entry point layer:
-
-**If entry point is ideation layer** (`docs/plans/ideation/`):
+Read `.agent/skills/technical-writer/SKILL.md` for clarity standards.
 
-1. **Placement**: Read `ideation-index.md` Structure Map. Identify the domain folder where this feature belongs. If no suitable domain exists, create one.
-2. **Classification Gate**: Apply the Node Classification Gate from `.agent/skills/idea-extraction/SKILL.md` — determine if the feature is a leaf feature file or complex enough to warrant a sub-domain folder.
-3. **Write the feature**: Use `.agent/skills/prd-templates/references/fractal-feature-template.md` as the template. Include:
-   - Feature description (what it does, why it matters)
-   - Affected personas (who uses this)
-   - Success criteria (how we know it works)
-   - Constraints (what limits apply)
-   - **Role Lens** — which personas interact with this feature and how
-4. **Update parent index**: Add the new feature to the parent domain's `*-index.md` children table
-5. **Update CX files**: If the feature has cross-domain interactions, update the parent domain's `*-cx.md` and/or `ideation-cx.md` (global)
-6. **Update `ideation-index.md`**: Add the feature to the MoSCoW Summary at the appropriate priority level
+Read `.agent/skills/prd-templates/references/evolution-layer-guidance.md` → **Entry Point Writing Depth** section for the entry point layer. Follow its writing checklist for the identified layer.
 
-**If entry point is architecture layer** (`architecture-design.md`):
-- Technical constraint description
-- Affected components (which parts of the system this touches)
-- Non-functional requirements (performance, scalability, compliance)
-- Integration points (how this relates to existing architecture decisions)
-
-**If entry point is IA layer** (specific IA shard):
-- Domain interactions (new user flows or modifications to existing flows)
-- Contracts (new or modified API contracts)
-- Data models (new entities, fields, or relationships)
-- Access control (RBAC implications)
-
-**Inline ambiguity check**: Before presenting this content to the user for approval, apply the Micro Ambiguity Check from `.agent/skills/session-continuity/SKILL.md` (Ambiguity Gates section). Walk each individual element of the new content and ask: "Would an implementer need to guess about this?" For every element where the answer is yes — fix it now. Add the missing detail, type, behavior, or constraint. Only present the content to the user once it passes the micro check.
+**Inline ambiguity check**: Before presenting to user, apply Micro Ambiguity Check from `.agent/skills/session-continuity/SKILL.md` — walk each element, fix any gaps where an implementer would need to guess.
 
 Present the written content to the user.
 
-**STOP — do not proceed until the user approves the new content.**
+**STOP** — do not proceed until the user approves.
 
 ---
 
 ## 5. Determine cascade scope
 
-Based on the entry point, determine which downstream layers have existing content that needs updating:
-
 | Entry Point | Cascade Layers (in order) |
 |-------------|---------------------------|
 | Vision | Architecture → IA → BE → FE → Phase plan |
 | Architecture | IA → BE → FE → Phase plan |
-| IA shard | BE spec for that shard → FE spec for that shard → Phase plan |
+| IA shard | BE spec → FE spec → Phase plan |
 | BE spec | FE → Phase plan |
-| Scope correction | Depends on the document — all layers below the corrected document |
-
-**Important**: When the entry point is an IA shard, the downstream cascade remains scoped to the affected domain shard's corresponding BE and FE specs. Do not cascade into unrelated domain shards unless the user explicitly broadens scope.
+| Scope correction | All layers below the corrected document |
 
-For each downstream layer, check whether content exists (using the same file checks as `/remediate-pipeline-assess` Step 1). Only layers with existing content need updating — layers that haven't been started yet will naturally incorporate the new content when they are written.
+Check each downstream layer for existing content. Only layers with existing content need updating.
 
 Report: "These layers have existing content that will need updating: [list]."
 
-If no downstream layers have content, report: "No downstream layers have existing content — the new content will be incorporated when those layers are written. Evolution complete."
+If no downstream layers have content: "No downstream layers have existing content — incorporated when written. Evolution complete."