cfsa-antigravity 2.10.1 → 2.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cfsa-antigravity",
-  "version": "2.10.1",
+  "version": "2.12.0",
   "description": "CFSA Pipeline — Constraint-First Specification Architecture for AI agents. Production-grade from line one.",
   "scripts": {
     "changeset": "changeset",

package/template/.agent/kit-sync.md

@@ -1,6 +1,6 @@
 # Kit Sync State
 
 upstream: https://github.com/RepairYourTech/cfsa-antigravity
-last_synced_commit: 7d0a1d62ec69d9d1a673d8481777c730ce56f675
-last_synced_at: 2026-03-19T16:12:01Z
-kit_version: 2.10.1
+last_synced_commit: bf1e196564da7c037996f8e3422994f36dbc014e
+last_synced_at: 2026-03-20T00:52:40Z
+kit_version: 2.12.0

package/template/.agent/rules/completion-checklist.md

@@ -37,10 +37,11 @@ A unit of work is only DONE when:
    - Phase progress fractions updated (e.g., `3/10` → `4/10`)
    - Overall progress fractions updated
 4. **The Locks**: All task claims (`[!]` flags and `files:` blocks) are removed.
-5. **The Memory**: Blockers and patterns are logged to `.agent/progress/memory/`.
-   - Follow `.agent/skills/session-continuity/protocols/04-pattern-extraction.md` — reflect on what worked, what didn't, classify, and write to `memory/patterns.md`
-   - Log any new blockers or resolutions to `memory/blockers.md`
-   - If decisions were made using Protocol 6 (Decision Effect Analysis), verify they're recorded in `memory/decisions.md`
+5. **The Memory**: All three memory files in `.agent/progress/memory/` are checked:
+   - `patterns.md` — Any patterns observed (what worked, what failed) logged per Protocol 04. **User corrections are logged as anti-patterns.**
+   - `decisions.md` — Any non-trivial decisions logged per Protocol 06
+   - `blockers.md` — Any blockers hit logged with status and impact
+   - See rule: `memory-capture` for triggers and format
 6. **The Session Log**: A session close log exists in `.agent/progress/sessions/`.
    - Follow `.agent/skills/session-continuity/protocols/05-session-close.md` — write what was accomplished, deferred, and where the next session should start
 

package/template/.agent/rules/debug-by-test.md

@@ -0,0 +1,49 @@
+---
+description: Failing test before any fix — reproduce the bug first, then fix it
+trigger: always_on
+---
+
+# Debug-by-Test
+
+> Reproduce first. Fix second. Never touch production code until you have a failing test that proves the bug exists.
+
+## The Rule
+
+**When a bug, error, or unexpected behavior is encountered:**
+
+1. **STOP.** Do not touch the source code.
+2. **Write a failing test** that reproduces the exact bug.
+3. **Run it.** Confirm it fails for the right reason.
+4. **Now fix the code.** Make the failing test pass.
+5. **Run all tests.** Confirm nothing else broke.
+
+This is non-negotiable. No "I can see the problem, let me just fix it."
+
+## Why
+
+| Without this rule | With this rule |
+|---|---|
+| You guess at the fix, change code, hope it works | You prove the bug exists before touching anything |
+| "Fixed" bugs silently reappear | The test catches regressions forever |
+| You fix the symptom, not the cause | The test forces you to understand the actual behavior |
+| No proof the fix works | Green test IS the proof |
+
+## Applies To
+
+| Scenario | What To Do |
+|----------|-----------|
+| User reports a bug | Write a test reproducing it → fix → green |
+| Test failure during development | Isolate with a minimal test → fix → green |
+| Unexpected runtime error | Write a test triggering the error → fix → green |
+| "This isn't working right" | Write a test showing the wrong behavior → fix → green |
+| Spec/workflow bug (non-code) | Document the expected vs actual behavior before changing the spec |
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| Changing source code before writing a failing test | ❌ Rejected. Write the test first. |
+| "I can see the issue, let me fix it quickly" | ❌ Rejected. Quick fixes skip understanding. |
+| Writing a test AFTER the fix to prove it works | ❌ Rejected. That's backwards — you don't know what you actually fixed. |
+| Failing test → source fix → all tests green | ✅ Correct. |
+| Non-code bug → document expected vs actual → then fix | ✅ Correct. |

package/template/.agent/rules/decision-classification.md

@@ -101,3 +101,13 @@ questions than it answers. The ratio should feel like an interview, not a lectur
 - "How should we implement X?" → defer to `/create-prd` → note it and move on
 - "What technology for X?" → defer to `/create-prd` → note it and move on
 - Don't burden the user with implementation or architecture during ideation unless they bring it up
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| Choosing a database without presenting options | ❌ Rejected. Architecture decision — present 2-3 options. |
+| Asking user what to name a variable | ❌ Rejected. Implementation decision — just decide. |
+| Deciding product pricing without asking user | ❌ Rejected. Product decision — user decides. |
+| Unsure if product or architecture? → treating as product | ✅ Correct. Escalate upward. |
+| Making file-naming call, stating choice briefly | ✅ Correct. Implementation decision. |

package/template/.agent/rules/extensibility.md

@@ -13,10 +13,10 @@ trigger: always_on
 
 | File Type | Max Lines | Reasoning |
 |-----------|-----------|-----------|
-| Components (`.tsx`) | 200 | Extract sub-components if larger |
-| Utilities / lib (`.ts`) | 300 | Split into focused modules |
-| Schema files (`.schema.ts`) | 150 | One domain per schema file |
-| Test files (`.test.ts`) | 400 | Group by feature, split if needed |
+| Components | 200 | Extract sub-components if larger |
+| Utilities / lib | 300 | Split into focused modules |
+| Schema files | 150 | One domain per schema file |
+| Test files | 400 | Group by feature, split if needed |
 | Config files | 100 | Keep flat and readable |
 
 ## Directory Documentation
@@ -30,13 +30,7 @@ trigger: always_on
 
 ## Naming Conventions
 
-| Element | Convention | Example |
-|---------|-----------|---------|
-| Schema files | `[feature].schema.ts` | `model-config.schema.ts` |
-| Components | PascalCase directory + `index.tsx` | `ModelSelector/index.tsx` |
-| Utilities | `[feature].ts` in `lib/` | `lib/rate-limiter.ts` |
-| API routes | `[resource]/[action].ts` | `api/models/list.ts` |
-| Test files | `[source-file].test.ts(x)` | `ModelSelector.test.tsx` |
+Follow the project's established conventions in `.agent/instructions/patterns.md`. When no convention exists yet, use the stack's community standard.
 
 ## Anti-Spaghetti Rules
 
@@ -45,3 +39,14 @@ trigger: always_on
 - No business logic in components — components render, lib/ computes
 - No copy-paste patterns — if you wrote it twice, extract it
 - Same pattern everywhere — if existing code does X one way, new code does X the same way
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| Component file over 200 lines | ❌ Rejected. Extract sub-components. |
+| Directory with 3+ files and no README.md | ❌ Rejected. Add one. |
+| Circular import detected | ❌ Rejected. Restructure dependencies. |
+| Copy-pasted logic in two files | ❌ Rejected. Extract to shared module. |
+| New code uses different pattern than existing code for same thing | ❌ Rejected. Match existing conventions. |
+| Clean, focused modules with README documentation | ✅ Correct. |

package/template/.agent/rules/memory-capture.md

@@ -0,0 +1,71 @@
+---
+description: Patterns, decisions, and blockers written to memory every conversation — empty memory files mean the pipeline never learns
+trigger: always_on
+---
+
+# Memory Capture
+
+> Every conversation that involves a decision, correction, surprise, or blocker MUST record it before the conversation ends. Empty memory files mean the pipeline never learns.
+
+## The Problem
+
+The pipeline has three memory files (`memory/patterns.md`, `memory/decisions.md`, `memory/blockers.md`) — all empty. `workflow.md` Step 5 says "Learn (MANDATORY)" but no enforcement exists. This rule IS the enforcement.
+
+## When to Write
+
+| Trigger | What Happened | Target File | Format |
+|---------|---------------|-------------|--------|
+| User corrects me | "No, that's wrong" / "Don't do that" / "I told you to..." | `memory/patterns.md` | Anti-pattern (PAT-NNN) |
+| User says "remember this" | Explicit instruction to retain information | `memory/decisions.md` | Decision (DEC-NNN) |
+| Non-trivial decision made | Choice with ripple effects (see Protocol 06 triage) | `memory/decisions.md` | Decision (DEC-NNN) |
+| Something blocks progress | External dependency, missing spec, tooling failure | `memory/blockers.md` | Blocker (BLOCKER-NNN) |
+| Pattern emerges | Something works well or fails repeatedly | `memory/patterns.md` | Pattern (PAT-NNN) |
+
+## How to Write
+
+### Patterns (`memory/patterns.md`)
+
+```markdown
+### PAT-NNN: [Short description] (YYYY-MM-DD)
+- **Type**: best-practice | anti-pattern
+- **Confidence**: 0.5 (first occurrence) — increment by 0.1 on reuse, max 0.95
+- **Context**: When/where this applies
+- **Pattern**: What to do (or avoid)
+- **Source**: What triggered this entry
+```
+
+### Decisions (`memory/decisions.md`)
+
+```markdown
+### DEC-NNN: [Decision summary] (YYYY-MM-DD)
+- **Problem**: What needed deciding
+- **Options considered**: At least 2
+- **Decision**: What was chosen and why
+- **Downstream**: What this affects
+- **Reversibility**: High | Medium | Low
+```
+
+### Blockers (`memory/blockers.md`)
+
+```markdown
+### BLOCKER-NNN: [Description] (YYYY-MM-DD)
+- **Status**: active | resolved
+- **Impact**: What this blocks
+- **Resolution**: How it was resolved (if resolved)
+```
+
+## When NOT to Write
+
+- Routine/trivial tasks with nothing new learned — skip
+- Isolated implementation decisions (variable names, file paths) — skip
+- Repeating an existing pattern already logged — update confidence instead
+
+## Pre-Completion Check
+
+Before calling `notify_user` to report completion of ANY workflow or substantial task:
+
+1. **Scan this conversation** for triggers in the table above
+2. **If triggers found** → write entries to the appropriate memory files
+3. **If no triggers** → explicitly confirm: "No new patterns, decisions, or blockers to log"
+
+This check is **not skippable**. It applies to every pipeline stage, every conversation, every session.

package/template/.agent/rules/question-vs-command.md

@@ -79,3 +79,13 @@ interesting", hedging language ("maybe", "possibly", "sort of")
 
 5. **Never mistake frustration for instruction.** "This API is a mess" is not an
    instruction to refactor the API. It might be — but ask first.
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| Editing code because user asked "is this right?" | ❌ Rejected. That's a question — discuss. |
+| Refactoring because user said "this is messy" | ❌ Rejected. Frustration ≠ instruction — ask first. |
+| Switching approach because user asked "what about X?" | ❌ Rejected. They're exploring — discuss trade-offs. |
+| Question → discussion → user commands → action | ✅ Correct. |
+| Ambiguous input → clarification request | ✅ Correct. |

package/template/.agent/rules/security-first.md

@@ -41,3 +41,14 @@ Every response includes:
 - `X-Content-Type-Options: nosniff`
 - `X-Frame-Options: DENY`
 - `Strict-Transport-Security` — HSTS with long max-age
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| PII field in AI model request payload | ❌ Rejected. Strip before sending. |
+| API key hardcoded in source file | ❌ Rejected. Use environment variable. |
+| User input rendered as raw HTML | ❌ Rejected. Always escape. |
+| Public endpoint without rate limiting | ❌ Rejected. Add rate limiter. |
+| API endpoint without input validation | ❌ Rejected. Add {{CONTRACT_LIBRARY}} schema. |
+| Encrypted PII, parameterized queries, server-side secrets | ✅ Correct. |

package/template/.agent/rules/single-question.md

@@ -0,0 +1,59 @@
+---
+description: One question at a time with options, pros and cons, and a recommendation — never batch questions
+trigger: always_on
+---
+
+# Single-Question Flow
+
+> Never batch questions. One question at a time. Options, pros and cons, recommendation.
+
+## The Rule
+
+**Every question — to the user OR to yourself — follows the same structure:**
+
+1. **One question only.** Never ask multiple questions in a single message. If you have 5 things to ask, ask the first one. Wait for the answer. Then ask the second.
+
+2. **Present options.** List 2–4 concrete options (not open-ended "what do you want?").
+
+3. **Pros and cons.** Each option gets specific trade-offs — not vague qualities.
+
+4. **Recommend one.** State which option you'd choose and why. The user can override.
+
+## Applies to EVERYTHING
+
+This is not just for user-facing questions. It applies to:
+
+| Scenario | What This Means |
+|----------|----------------|
+| Asking the user a product decision | One decision at a time, options + recommendation |
+| Asking the user a preference | One preference at a time, options + recommendation |
+| Internal reasoning ("how should I structure this?") | Enumerate options, weigh trade-offs, pick one |
+| Ideation interviews | One domain/feature question at a time |
+| PRD stack decisions | One technology choice at a time |
+| Ambiguity resolution | One gap at a time |
+
+## Format
+
+```
+**[Question in plain language]**
+
+| Option | Pros | Cons |
+|--------|------|------|
+| A      | ...  | ...  |
+| B      | ...  | ...  |
+| C      | ...  | ...  |
+
+**Recommendation:** Option B — [specific reason why].
+```
+
+For internal reasoning, use the same structure but don't present it to the user — just apply the discipline internally and state your decision with brief reasoning.
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| "Here are 5 questions for you:" | ❌ Rejected. Ask one. |
+| "What do you think?" (open-ended, no options) | ❌ Rejected. Provide options. |
+| "Should we use X?" (no alternatives shown) | ❌ Rejected. Show at least 2 options with trade-offs. |
+| One question + 3 options + pros/cons + recommendation | ✅ Correct. |
+| "I chose X because [reason]" (internal, stated briefly) | ✅ Correct. |

package/template/.agent/rules/skill-mcp-first.md

@@ -0,0 +1,45 @@
+---
+description: Check skills and MCPs before reasoning on your own — leverage existing knowledge first
+trigger: always_on
+---
+
+# Skill and MCP First
+
+> Before doing anything yourself, check if a skill or MCP already knows how to do it.
+
+## The Rule
+
+**When you receive any task, BEFORE reasoning about how to do it:**
+
+1. **Scan skills.** Read through the skill names and descriptions already loaded in your context. If a skill matches the task or a sub-task, read its `SKILL.md` and follow it.
+
+2. **Scan MCPs.** Check if any connected MCP server provides tools relevant to the task. If so, use the MCP tool instead of inventing your own approach.
+
+3. **Only then think.** If no skill or MCP covers the task, proceed with your own reasoning.
+
+## Why
+
+| Without this rule | With this rule |
+|---|---|
+| You reinvent patterns already documented in skills | You leverage tested, refined procedures |
+| You ignore MCP tools and use workarounds | You use the right tool for the job |
+| Every session starts from scratch | Skills accumulate institutional knowledge |
+| Quality varies by conversation | Skills enforce consistent quality |
+
+## What Counts as a Match
+
+- **Exact match**: Skill name/description directly describes the task → read and follow it
+- **Partial match**: Skill covers a sub-task or related concern → read it for relevant sections
+- **MCP match**: An MCP server has tools that handle part of the task → use them
+- **No match**: No skill or MCP is relevant → proceed with your own reasoning and note it
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| Writing a test strategy without checking `Testing Strategist` skill | ❌ Rejected. |
+| Debugging without checking `systematic-debugging` skill | ❌ Rejected. |
+| Designing an API without checking `api-design-principles` skill | ❌ Rejected. |
+| Reading skill → following its methodology → executing | ✅ Correct. |
+| No relevant skill found → proceeding with own reasoning | ✅ Correct. |
+| Using MCP tool instead of manual workaround | ✅ Correct. |

package/template/.agent/rules/specificity-standards.md

@@ -52,3 +52,13 @@ Specs must go **deep enough** that an implementer needs zero clarification.
 3. Every API call has loading, success, and error UI states
 4. Every responsive breakpoint has layout behavior specified
 5. Every interaction has keyboard, mouse, and touch behavior defined
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| "Fast response times" in a spec | ❌ Rejected. Specify P95 latency threshold. |
+| "Handle errors gracefully" | ❌ Rejected. Specify error codes and response shapes. |
+| Endpoint without typed request/response schema | ❌ Rejected. Add full schema. |
+| Form spec without per-field validation rules | ❌ Rejected. Specify each field. |
+| "P95 < 200ms", "returns 409 with `{error, code}`" | ✅ Correct. Testable and specific. |

package/template/.agent/rules/tdd-contract-first.md

@@ -55,3 +55,13 @@ Red → Green → Refactor
 - Test file lives next to source: `foo.ts` → `foo.test.ts`
 - No `any` in test files — type your mocks
 - Coverage minimum: 80% lines, 90% branches on critical paths
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| Implementation code written before schema | ❌ Rejected. Schema first. |
+| Tests written after implementation | ❌ Rejected. Red → Green → Refactor. |
+| `any` type in test file | ❌ Rejected. Type your mocks. |
+| Endpoint without contract validation test | ❌ Rejected. Add contract test. |
+| Schema → failing test → implementation → green | ✅ Correct. |

package/template/.agent/rules/vertical-slices.md

@@ -33,10 +33,13 @@ A feature slice is complete when:
 - [ ] Auth gates: every route that requires auth has the auth gate implemented (not stubbed)
 - [ ] The feature is reachable from the app's entry point via normal user navigation
 
-## Anti-Patterns
-
-| Don't | Do |
-|-------|-----|
-| "I'll add the admin panel later" | Include admin CRUD in the slice |
-| "The API works, frontend next sprint" | Ship them together or not at all |
-| "Database is set up, just need endpoints" | That's not a slice, that's a layer |
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| "I'll add the admin panel later" | ❌ Rejected. Include admin CRUD in the slice. |
+| "The API works, frontend next sprint" | ❌ Rejected. Ship them together or not at all. |
+| "Database is set up, just need endpoints" | ❌ Rejected. That's a layer, not a slice. |
+| Route without navigation link from existing UI | ❌ Rejected. Must be reachable. |
+| Auth-required route without auth gate | ❌ Rejected. Implement the gate. |
+| All 4 layers + tests + navigation + auth gates | ✅ Correct. |

package/template/.agent/skills/idea-extraction/SKILL.md

@@ -555,6 +555,38 @@ When a cross-cut is identified, log it to the appropriate CX file:
 | During breadth sweep | Domain CX file | Medium |
 | During drilling | Sub-domain CX file or feature's cross-cut notes | High |
 
+### CX Decision Gate (Mandatory — NOT skippable)
+
+> **This is the enforcement mechanism for the Cross-Cut Watch Protocol.**
+> "Always-on" means there is a hard gate, not a suggestion.
+
+**After ANY of these trigger events, STOP and run this gate before moving to the next item:**
+
+| Trigger Event | Example |
+|---------------|---------|
+| Open question (OQ) resolved | User decides hiring fee model = shop pays |
+| Deep Think hypothesis confirmed | Agent proposed AI parts ordering, user confirmed |
+| User makes any product decision | User chooses freemium over paid-only |
+| Feature deepened reveals dependency | Certification tracking needs data from Training domain |
+| Edge case identified with cross-domain impact | Payment failure in domain A must notify domain B |
+
+**Gate questions** (answer all three):
+
+1. **New dependency?** — Does this decision create a dependency on another domain?
+2. **Modified cross-cut?** — Does it change an existing CX entry?
+3. **Cross-domain state/permissions/triggers?** — Does it affect state, permissions, or trigger chains in another domain?
+
+**If YES to any** → update the relevant CX file(s) **immediately**, before moving to the next item. Write the CX entry with:
+- Source domain and feature
+- Target domain(s) affected
+- Nature of the cross-cut (data dependency, trigger chain, permission, state)
+- Confidence level based on discovery context
+
+**If NO to all** → proceed. No logging needed for clean passes.
+
+> [!CAUTION]
+> **The gate is the point.** The most common failure mode is resolving an OQ, writing the decision to the feature file, and moving on without checking CX. The hiring fee model affects Payments, Supplier Integration, Analytics, and Consumer Platform visibility — 6 cross-domain connections that would be silently lost without this gate.
+
 ### Cross-Cut Synthesis Questions
 
 For each confirmed cross-cut (CX entry with High confidence), answer all five synthesis questions per the `fractal-cx-template.md`:

package/template/.agent/workflows/create-prd.md

@@ -111,3 +111,12 @@ Use `notify_user` to present both documents with self-check results.
 **STOP** — do NOT propose `/decompose-architecture` or any other pipeline workflow. The only valid next step is:
 
 - `/audit-ambiguity architecture` — unconditionally mandatory. The self-check above cannot replace an independent audit. After the audit passes, the next step is `/decompose-architecture`.
+
+## Completion Gate (MANDATORY)
+
+Before reporting completion to the user:
+
+1. **Memory check** — Apply rule `memory-capture`. Write any patterns, decisions, or blockers from this workflow to `.agent/progress/memory/`. If nothing to write, confirm: "No new patterns/decisions/blockers."
+2. **Progress update** — Update `.agent/progress/` tracking files if they exist.
+3. **Session log** — Write session entry to `.agent/progress/sessions/`.
+

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

@@ -91,3 +91,12 @@ Present the proposed domain decomposition to the user for validation.
 
 ### Step A — Run `.agent/workflows/decompose-architecture-structure.md`
 ### Step B — Run `.agent/workflows/decompose-architecture-validate.md`
+
+## Completion Gate (MANDATORY)
+
+Before reporting completion to the user:
+
+1. **Memory check** — Apply rule `memory-capture`. Write any patterns, decisions, or blockers from this workflow to `.agent/progress/memory/`. If nothing to write, confirm: "No new patterns/decisions/blockers."
+2. **Progress update** — Update `.agent/progress/` tracking files if they exist.
+3. **Session log** — Write session entry to `.agent/progress/sessions/`.
+

package/template/.agent/workflows/ideate-discover.md

@@ -46,7 +46,10 @@ Read `.agent/skills/prd-templates/references/engagement-tier-protocol.md` — ap
 
 ## 3. Domain Exploration — Recursive Model
 
-Read `.agent/skills/idea-extraction/SKILL.md` — follow the **Recursive Domain Exhaustion Protocol**, **Deep Think Protocol**, **Node Classification Gate**, and **Reactive Depth Protocol**.
+Read `.agent/skills/idea-extraction/SKILL.md` — follow the **Recursive Domain Exhaustion Protocol**, **Deep Think Protocol**, **Node Classification Gate**, **Reactive Depth Protocol**, and **CX Decision Gate**.
+
+> [!IMPORTANT]
+> **CX Decision Gate is mandatory at every level.** After resolving ANY open question, confirming ANY Deep Think hypothesis, or receiving ANY product decision from the user → STOP and run the CX Decision Gate from `idea-extraction/SKILL.md` before proceeding. This is the #1 enforcement gap — decisions silently drop cross-domain connections without this gate.
 
 Read `## Expansion Mode` and `## Structural Classification` from `docs/plans/ideation/ideation-index.md`.
 
@@ -117,9 +120,9 @@ For rejected features: note in `ideation-index.md` under a `## Considered & Reje
 For each Must Have feature, use the recursive model from `idea-extraction/SKILL.md`:
 1. **Level 1**: Sub-features. Run Classification Gate — sub-domain or feature?
 2. **Level 2**: Edge cases and failure modes. Fill feature file sections per `fractal-feature-template.md`.
-3. **Level 3** (complex features): Cross-cuts with evidence → parent CX file.
+3. **Level 3** (complex features): Full cross-cut synthesis per `fractal-cx-template.md`.
 
-**Deep Think at each level.** Write results to feature files.
+**At EVERY level**: Deep Think + **CX Decision Gate**. After each decision, OQ resolution, or confirmed hypothesis → run CX Decision Gate → write CX entries immediately → then proceed.
 
 ### 5c. Feature deepening — Should Haves (lighter touch)
 

package/template/.agent/workflows/ideate.md

@@ -126,3 +126,12 @@ Explores constraints, success metrics, and competitive positioning. Runs leaf-no
 - `/audit-ambiguity ideation` — mandatory coverage verification before `/create-prd` can begin.
 
 > If the user wants to pause, save progress and note where to resume. When resuming, the next step remains `/audit-ambiguity ideation`.
+
+## Completion Gate (MANDATORY)
+
+Before reporting completion to the user:
+
+1. **Memory check** — Apply rule `memory-capture`. Write any patterns, decisions, or blockers from this workflow to `.agent/progress/memory/`. If nothing to write, confirm: "No new patterns/decisions/blockers."
+2. **Progress update** — Update `.agent/progress/` tracking files if they exist.
+3. **Session log** — Write session entry to `.agent/progress/sessions/`.
+

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

@@ -50,3 +50,11 @@ Executes the TDD cycle (RED: write failing tests → GREEN: implement → REFACT
 - [ ] 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
+
+## Completion Gate (MANDATORY)
+
+Before reporting completion to the user:
+
+1. **Memory check** — Apply rule `memory-capture`. Write any patterns, decisions, or blockers from this workflow to `.agent/progress/memory/`. If nothing to write, confirm: "No new patterns/decisions/blockers."
+2. **Progress update** — Update `.agent/progress/` tracking files if they exist.
+3. **Session log** — Write session entry to `.agent/progress/sessions/`.

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

@@ -43,3 +43,12 @@ Run `.agent/workflows/plan-phase-preflight.md`.
 Slice identification, dependency ordering, acceptance criteria, progress file generation, and bootstrap completeness gate.
 
 Run `.agent/workflows/plan-phase-write.md`.
+
+## Completion Gate (MANDATORY)
+
+Before reporting completion to the user:
+
+1. **Memory check** — Apply rule `memory-capture`. Write any patterns, decisions, or blockers from this workflow to `.agent/progress/memory/`. If nothing to write, confirm: "No new patterns/decisions/blockers."
+2. **Progress update** — Update `.agent/progress/` tracking files if they exist.
+3. **Session log** — Write session entry to `.agent/progress/sessions/`.
+

package/template/.agent/workflows/sync-kit.md

@@ -214,7 +214,12 @@ Scan these files for any literal `{{` characters:
 6. `.agent/instructions/patterns.md`
 7. `.agent/instructions/tech-stack.md`
 
-**If unfilled patterns found** — list each with remediation:
+**If unfilled patterns found** — check the current pipeline phase before recommending remediation:
+
+1. **Detect phase**: Check filesystem markers per `GEMINI.md` → Pipeline Phase Detection table.
+2. **If phase is Pre-PRD** (no `architecture-design.md` exists) → report:
+   > "Placeholders remain unfilled — this is **expected** at the current pipeline phase (`<detected_phase>`). They will be filled when `/create-prd` → `/bootstrap-agents-fill` runs after ideation completes."
+3. **If phase is Post-PRD** (`architecture-design.md` exists) → show remediation table:
 
 | File(s) | Remediation |
 |---------|-------------|

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

@@ -50,3 +50,12 @@ Runs production readiness checks: API documentation sync, accessibility audit, p
 - [ ] All production readiness checks pass (Shard 2)
 - [ ] Validation report written to `docs/audits/phase-N-validation.md`
 - [ ] Pass/fail verdict determined
+
+## Completion Gate (MANDATORY)
+
+Before reporting completion to the user:
+
+1. **Memory check** — Apply rule `memory-capture`. Write any patterns, decisions, or blockers from this workflow to `.agent/progress/memory/`. If nothing to write, confirm: "No new patterns/decisions/blockers."
+2. **Progress update** — Update `.agent/progress/` tracking files if they exist.
+3. **Session log** — Write session entry to `.agent/progress/sessions/`.
+

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

@@ -68,3 +68,12 @@ Read .agent/skills/code-review-pro/SKILL.md and apply its adversarial review dis
 
 > [!CAUTION]
 > After completing all IA shards, the **only** valid next step is `/write-be-spec`. Do NOT propose `/plan-phase` or `/implement-slice` — those require completed BE and FE specs. This applies to ALL project types: web apps, CLI tools, bash scripts, APIs, desktop apps. No project skips the BE/FE spec layers.
+
+## Completion Gate (MANDATORY)
+
+Before reporting completion to the user:
+
+1. **Memory check** — Apply rule `memory-capture`. Write any patterns, decisions, or blockers from this workflow to `.agent/progress/memory/`. If nothing to write, confirm: "No new patterns/decisions/blockers."
+2. **Progress update** — Update `.agent/progress/` tracking files if they exist.
+3. **Session log** — Write session entry to `.agent/progress/sessions/`.
+

package/template/.agent/workflows/write-be-spec.md

@@ -74,3 +74,12 @@ Read .agent/skills/code-review-pro/SKILL.md and apply its adversarial review dis
 - [ ] Every deep dive key decision is reflected in the spec
 - [ ] Every cross-shard reference has been resolved
 - [ ] IA Source Map is complete — no BE spec section lacks a traceable IA source
+
+## Completion Gate (MANDATORY)
+
+Before reporting completion to the user:
+
+1. **Memory check** — Apply rule `memory-capture`. Write any patterns, decisions, or blockers from this workflow to `.agent/progress/memory/`. If nothing to write, confirm: "No new patterns/decisions/blockers."
+2. **Progress update** — Update `.agent/progress/` tracking files if they exist.
+3. **Session log** — Write session entry to `.agent/progress/sessions/`.
+

package/template/.agent/workflows/write-fe-spec.md

@@ -71,3 +71,12 @@ Read .agent/skills/code-review-pro/SKILL.md and apply its adversarial review dis
 - [ ] Responsive behavior specified for all breakpoints
 - [ ] IA shard's accessibility section fully consumed (not re-derived from BE spec)
 - [ ] Source Map is complete — no FE spec section lacks a traceable source
+
+## Completion Gate (MANDATORY)
+
+Before reporting completion to the user:
+
+1. **Memory check** — Apply rule `memory-capture`. Write any patterns, decisions, or blockers from this workflow to `.agent/progress/memory/`. If nothing to write, confirm: "No new patterns/decisions/blockers."
+2. **Progress update** — Update `.agent/progress/` tracking files if they exist.
+3. **Session log** — Write session entry to `.agent/progress/sessions/`.
+

package/template/GEMINI.md

@@ -1,35 +1,23 @@
 # CFSA Antigravity — Constraint-First Specification Architecture
 
-This is a **Constraint-First Specification Architecture (CFSA)** pipeline. It turns a raw idea into exhaustively specified, test-driven, production-quality code through a series of progressive gates. Stack-agnostic. Agent-agnostic. Cross-platform. Every line of code, every spec, every test is production-grade from the moment it's written. Phases control scope, never quality. There is no "fix it later."
+**CFSA pipeline** — raw idea → exhaustive specs → test-driven production code. Stack/agent-agnostic. Phases control scope, never quality. No "fix it later."
 
 ### Entry Point
 
-Start the pipeline with:
-
 ```
 /ideate                              # From scratch — deep interview
 /ideate @path/to/your-idea.md        # From existing document
 ```
 
-The `@file` pattern is natively supported by `/ideate` (with full multi-mode input classification) and as a simple document-read input by `/evolve-feature`, `/resolve-ambiguity`, and `/propagate-decision`. Other pipeline commands accept direct invocation; `@file` can be passed to them but no automatic input classification is applied — the workflow reads the file and treats it as inline context.
+`@file` is natively supported by `/ideate` (with multi-mode input classification) and as simple document-read by `/evolve-feature`, `/resolve-ambiguity`, `/propagate-decision`.
 
 ### Progressive Decision Lock
 
-Decisions in this pipeline are **progressively locked**. Each pipeline stage builds on the locked decisions of previous stages:
-
-1. `/ideate` locks the **vision** — problem, personas, features, constraints
-2. `/create-prd` locks the **architecture** — tech stack, system design, security model
-3. `/decompose-architecture` locks the **domain boundaries** — shard structure, dependencies
-4. `/write-architecture-spec` locks the **interaction specs** — per-shard contracts, data models
-5. `/write-be-spec` locks the **backend contracts** — API endpoints, schemas, middleware
-6. `/write-fe-spec` locks the **frontend specs** — components, state, interactions
-7. `/plan-phase` locks the **implementation order** — dependency-ordered TDD slices
-7.5. `/verify-infrastructure` locks the **operational foundation** — CI/CD green, staging live, migrations clean, auth working
-8. `/implement-slice` locks the **code** — tests → implementation → validation
+Decisions are **progressively locked**: `/ideate` → vision, `/create-prd` → architecture, `/decompose-architecture` → domain boundaries, `/write-architecture-spec` → interaction specs, `/write-be-spec` → backend contracts, `/write-fe-spec` → frontend specs, `/plan-phase` → implementation order, `/verify-infrastructure` → operational foundation, `/implement-slice` → code.
 
-Once a stage is locked, downstream stages may not contradict it. To change a locked decision, re-run the originating stage and cascade changes downstream.
+Once locked, downstream stages may not contradict. To change a locked decision, re-run the originating stage and cascade.
 
-<!-- Pipeline table maintained by: (1) bootstrap-agents-fill.md Step 4 for project-config sections, (2) kit maintainer checklist for workflow rows — see docs/kit-architecture.md Kit Maintenance Checklist -->
+<!-- Maintained by bootstrap-agents-fill.md Step 4 + kit maintainer checklist -->
 ### Pipeline Workflow Table
 
 | # | Command | Input | Output | Stage |
@@ -40,16 +28,12 @@ Once a stage is locked, downstream stages may not contradict it. To change a loc
 | ↳ | `/ideate-validate` | Domains + features | `docs/plans/vision.md` (human summary compiled from ideation folder) | Discovery |
 | 2 | `/create-prd` | `ideation-index.md` | `architecture-design.md` + `ENGINEERING-STANDARDS.md` + `data-placement-strategy.md` | Design |
 
-> **Persistent intermediary**: `docs/plans/ideation/` folder — kept permanently as the pipeline's source of truth for the ideation phase.
-
 | ↳ | `/create-prd-stack` | `ideation/meta/constraints.md` | Tech stack decisions | Design |
 | ↳ | `/create-prd-design-system` | Tech stack + brand-guidelines | `docs/plans/design-system.md` | Design |
 | ↳ | `/create-prd-architecture` | Tech stack | System architecture + data strategy | Design |
 | ↳ | `/create-prd-security` | Architecture | Security model + integrations | Design |
 | ↳ | `/create-prd-compile` | All prior steps | `architecture-design.md` + `ENGINEERING-STANDARDS.md` | Design |
 
-> **Progressive working artifact**: `docs/plans/architecture-draft.md` — written incrementally by shards 1–3, read by shard 4 to compile the final `architecture-design.md`.
-
 | 3 | `/decompose-architecture` | `architecture-design.md` | IA shards + layer indexes | Design |
 | ↳ | `/decompose-architecture-structure` | Approved domains | Directory structure + shard skeletons + indexes | Design |
 | ↳ | `/decompose-architecture-validate` | Skeletons | Deep dives + type annotations + validation | Design |
@@ -88,17 +72,13 @@ Once a stage is locked, downstream stages may not contradict it. To change a loc
 | 11 | `/evolve-contract` | Changed `{{CONTRACT_LIBRARY}}` schema | Safe schema migration | Maintenance |
 
 
-> **Note**: Rows marked with ↳ are independently-invocable sub-workflows (shards)
-> of their parent command. The parent orchestrates them in sequence, but each shard
-> can also be run standalone with its own prerequisites. `/bootstrap-agents` is also
-> sharded into `/bootstrap-agents-fill` and `/bootstrap-agents-provision`.
-> `/resolve-ambiguity`, `/remediate-pipeline`, `/propagate-decision`, and `/evolve-feature` are utility commands callable from any stage — they are not sequential pipeline steps.
+> **Note**: ↳ rows are independently-invocable shards. Utility commands (`/resolve-ambiguity`, `/remediate-pipeline`, `/propagate-decision`, `/evolve-feature`) are callable from any stage.
 
 > [!WARNING]
 > If `docs/plans/ideation/ideation-index.md` does not exist, the pipeline has not started — run `/ideate` before any other workflow.
 
 > [!WARNING]
-> If `{{PLACEHOLDER}}` values appear anywhere in this file, bootstrap has not run — do not attempt implementation work.
+> If `{{PLACEHOLDER}}` values appear in this file: check the current pipeline phase (see below). Pre-PRD → placeholders are expected, they fill at `/create-prd`. Post-PRD → run `/bootstrap-agents-fill`.
 
 ---
 
@@ -122,11 +102,11 @@ Once a stage is locked, downstream stages may not contradict it. To change a loc
 
 | Guide | Description |
 |-------|-------------|
-| 🛠️ [Workflow](.agent/instructions/workflow.md) | Execution sequence & principles |
-| 💻 [Tech Stack](.agent/instructions/tech-stack.md) | Technology decisions & skill mappings |
-| 📐 [Patterns](.agent/instructions/patterns.md) | Code conventions & architecture patterns |
-| 📁 [Structure](.agent/instructions/structure.md) | Directory layout & protected files |
-| ⌨️ [Commands](.agent/instructions/commands.md) | Dev, test, lint, build commands |
+| 🛠️ [Workflow](.agent/instructions/workflow.md) | Execution sequence |
+| 💻 [Tech Stack](.agent/instructions/tech-stack.md) | Technology decisions |
+| 📐 [Patterns](.agent/instructions/patterns.md) | Code conventions |
+| 📁 [Structure](.agent/instructions/structure.md) | Directory layout |
+| ⌨️ [Commands](.agent/instructions/commands.md) | Dev, test, lint, build |
 
 ### Agent Rules
 
@@ -143,6 +123,10 @@ Rules in `.agent/rules/` are **always active** — they apply to every task, eve
 | 🗣️ [question-vs-command](.agent/rules/question-vs-command.md) | Questions = discuss, Commands = act, Ambiguous = ask |
 | 🎯 [decision-classification](.agent/rules/decision-classification.md) | Product = user, Architecture = options, Implementation = agent |
 | ✅ [completion-checklist](.agent/rules/completion-checklist.md) | Code ≠ done. Code + tests + tracking = done |
+| 🧠 [memory-capture](.agent/rules/memory-capture.md) | Patterns, decisions, blockers written every conversation |
+| 🔢 [single-question](.agent/rules/single-question.md) | One question at a time, options + pros/cons + recommendation |
+| 🐛 [debug-by-test](.agent/rules/debug-by-test.md) | Failing test before any fix — reproduce first, fix second |
+| 🔍 [skill-mcp-first](.agent/rules/skill-mcp-first.md) | Check skills and MCPs before reasoning on your own |
 
 ### Installed Skills
 
@@ -156,27 +140,43 @@ Rules in `.agent/rules/` are **always active** — they apply to every task, eve
 4. **TDD: failing test before code** — Red → Green → Refactor, every slice, every surface
 5. **Security-first** — PII never leaks, inputs validated, secrets server-side only
 6. **Write decisions to disk immediately** — Every confirmed decision is written to its output file the moment the user confirms it. Never batch decisions in-memory across a long conversation. If the conversation truncates, all confirmed work must survive on disk.
+7. **Write to memory every conversation** — Before ending any workflow or conversation, write patterns to `memory/patterns.md`, decisions to `memory/decisions.md`, blockers to `memory/blockers.md`. See rule: `memory-capture`.
+
+### Pipeline Phase Detection
+
+Before acting on any task, detect the current pipeline phase from filesystem markers:
+
+| Phase | Marker | Valid Actions |
+|-------|--------|---------------|
+| Pre-ideation | No `docs/plans/ideation/ideation-index.md` | Only `/ideate` |
+| Ideating | `ideation/` has content, no `vision.md` | Ideation workflows only |
+| Ideation complete | `ideation-index.md` + `vision.md` exist | `/audit-ambiguity` → `/create-prd` |
+| PRD in progress | `architecture-draft.md` exists | PRD workflows only |
+| PRD complete | `architecture-design.md` + `ENGINEERING-STANDARDS.md` | `/decompose-architecture` |
+| Decomposition done | IA shards in `docs/plans/ia/` | `/write-architecture-spec` |
+| Spec writing | BE/FE specs exist | `/write-be-spec`, `/write-fe-spec` |
+| Planning | Phase plan in `docs/plans/phases/` | `/plan-phase` |
+| Implementation | `.agent/progress/` has content | `/implement-slice` |
+
+**Use this table to gate every action.** If a user runs a command that doesn't match their current phase, explain what phase they're in and what to run instead.
 
 ### Decision Tree
 
 ```mermaid
 graph TD
-    A[Task Received] --> B{Pipeline complete?}
-    B -->|No - ideation-index.md missing| C[Run /ideate first]
-    B -->|No - placeholders unfilled| D[Run /create-prd first]
-    B -->|Yes| E[Read Rules]
-    E --> F[Read Instructions]
-    F --> G{Scan Skills}
+    A[Task Received] --> P{Detect Phase}
+    P --> B{Task matches phase?}
+    B -->|No| F[STOP: explain phase + valid actions]
+    B -->|Yes| E[Read Rules + Instructions]
+    E --> G{Scan Skills}
     G -->|Found| H[Load Skill]
-    G -->|None| I{Scan MCP}
-    I -->|Found| J[Use MCP Tools]
-    I -->|None| K[Plan: Contract → Test → Implement]
-    K --> L[Execute]
-    L --> M[MANDATORY: Run Validation]
+    G -->|None| K[Execute Task]
+    K --> L[MANDATORY: Run Validation]
+    L --> M[MANDATORY: Write Memory]
     M --> N[Update Progress Tracking]
     N --> O[Complete]
 ```
 
 ### Mandatory Validation
 
-**CRITICAL:** Run the Validation Cmd from `.agent/instructions/commands.md` after **EVERY** code change. Do not finish a task until all pass.
+Run the Validation Cmd from `.agent/instructions/commands.md` after **EVERY** code change. Do not finish a task until all pass.

package/template/docs/kit-architecture.md

@@ -23,7 +23,7 @@ The intelligence of the kit lives entirely within the `.agent/` directory.
 ### Core Components
 
 *   **Instructions:** (`workflow.md`, `tech-stack.md`, `structure.md`, `patterns.md`, `commands.md`) Baseline knowledge the agent needs to operate in the specific environment. These files ship as templates with `{{PLACEHOLDER}}` markers — they are not static files. The bootstrap system fills them progressively as tech decisions are confirmed during `/create-prd`. An instruction file with unfilled placeholders is a broken agent context. `workflow.md` enforces the mandatory execution sequence: Understand Context -> Check Skills -> Execute -> Validate.
-*   **Rules:** Preemptively loaded constraints that apply to *every* task. Includes security best practices (`security-first.md`), TDD mandates (`tdd-contract-first.md`), and vertical-slice enforcement (`vertical-slices.md`).
+*   **Rules:** Preemptively loaded constraints that apply to *every* task. Covers security, TDD, vertical slices, debugging discipline, memory capture, questioning style, and more. See `GEMINI.md` → Agent Rules table for the full list.
 *   **Skill Library:** (`.agent/skill-library/`) Installable skill packages organized by category (e.g., `stack/databases/`, `stack/frontend-frameworks/`). Skills are provisioned from here into `.agent/skills/` by the bootstrap system when tech decisions are confirmed. Contains `MANIFEST.md` with the full taxonomy.
 *   **Skills:** Modular capabilities (e.g., `technical-writer`, `brainstorming`). Agents load these explicitly when a task requires them, preventing context bloat.
 *   **Workflows:** Step-by-step markdown checklists invoked via `/slash-commands` (e.g., `/create-prd`, `/implement-slice`). They chain skills together to achieve complex, multi-stage goals.
@@ -367,6 +367,11 @@ Workflows are designed to end with explicit NEXT STEPS. An agent shouldn't guess
 - [ ] If the workflow uses new prd-template reference files, add them to `prd-templates/SKILL.md`
 - [ ] If the workflow introduces a new skill, add it to `.agent/skill-library/MANIFEST.md`
 
+**When a new rule is added to `.agent/rules/`:**
+
+- [ ] Add a row to the `GEMINI.md` Agent Rules table
+- [ ] If the rule uses `{{PLACEHOLDER}}` values, follow the placeholder checklist below
+
 **When adding a `{{PLACEHOLDER}}` to any `.agent/rules/*.md`**
 
 - [ ] Add the placeholder name and the rule file it lives in to the "Currently applicable" note in `bootstrap-agents-fill.md` Step 3 (the rules scan step)