cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/README.md

@@ -0,0 +1,99 @@
+# CFSA Pipeline for Codex
+
+This directory contains the CFSA (Constraint-First Specification Architecture) pipeline adapted for Codex.
+
+## Directory Structure
+
+```text
+.codex/
+├── skills/              # Pipeline workflow skills and utilities
+│   ├── workflows/       # Main pipeline workflows (ideate, create-prd, etc.)
+│   ├── setup/           # Setup and bootstrap skills
+│   └── utilities/       # Helper skills (resolution, templates, etc.)
+├── rules/               # Always-active rules that apply to every task
+├── instructions/        # Core directives (workflow, tech-stack, patterns)
+├── skill-library/       # Codex-owned skill library
+```
+
+Project root canonical memory / Obsidian vault:
+
+```text
+.memory/
+├── .obsidian/           # Vault config stored inside the project
+├── raw/                 # Append-only session and event captures
+├── wiki/                # Compiled patterns, decisions, blockers, and knowledge
+├── schema/              # Machine-readable retrieval artifacts
+├── mcp-server/          # Shared memory MCP server
+├── hooks/               # Optional hook entrypoints
+└── migrate/             # Legacy memory import helpers
+```
+
+The `.memory/` directory is the canonical project memory layer and is designed to function as an Obsidian-friendly vault inside the project.
+
+A Codex install also gets the shared `.memory/` runtime scaffold, including:
+- the `cfsa-memory` server under `.memory/mcp-server/`
+- daemon startup helpers under `.memory/mcp-server/start.mjs`
+- compile/runtime helpers under `.memory/pipeline/` and `.memory/hooks/`
+
+Tool-specific MCP client config is user-managed. If you want Codex to talk to the shared memory daemon, add the appropriate MCP client config yourself and then run the initial compile before opening Obsidian at `.memory/`.
+
+Codex should point at `.memory/mcp-server/client.mjs`. That client now resolves the daemon from the current workspace's `.memory/runtime/cfsa-memory-daemon.json` and validates the daemon's `projectRoot` from `/health`, so a Codex session in one repo will not silently proxy into another repo's daemon.
+
+All runtimes should read and write shared project memory through `.memory/` and the MCP bridge.
+
+```text
+Shared memory access path
+Codex / Antigravity / Claude / Factory
+        -> runtime MCP client config
+        -> .mcp.json -> cfsa-memory -> .memory/mcp-server/client.mjs
+        -> shared daemon at .memory/mcp-server/daemon.mjs
+        -> .memory/wiki/* and .memory/schema/*
+```
+
+## Parallel Structure
+
+This directory is the standalone Codex runtime for the CFSA pipeline. It sits alongside the other runtimes in this repository, but `.codex/` owns its Codex execution assets locally.
+
+## Key Differences from Antigravity Version
+
+1. **Skills vs Workflows**: Codex uses skills instead of passive workflow markdown files
+2. **Task System**: Uses Codex's task and progress conventions for tracking
+3. **Progress + Shared Memory**: Uses `.memory/pipeline/progress/` for Codex pipeline state and project-level `.memory/` for canonical cross-runtime memory
+4. **Invocation**: Workflows are invoked as skills rather than slash commands in markdown
+5. **MCP**: Codex can connect to the shared `cfsa-memory` MCP bridge when configured by the user
+
+## Installation
+
+To install the Codex version:
+
+```bash
+npx cfsa-antigravity init --agent codex
+```
+
+For the Antigravity version (default):
+
+```bash
+npx cfsa-antigravity init
+# or
+npx cfsa-antigravity init --agent antigravity
+```
+
+## Pipeline Stages
+
+The CFSA pipeline follows these stages regardless of the agent system:
+
+1. **Discovery** (`/ideate`) — Raw idea → structured ideation
+2. **Design** (`/create-prd`) → Architecture, tech stack, security model
+3. **Specification** (`/write-*-spec`) → Detailed specs per layer
+4. **Planning** (`/plan-phase`) → Dependency-ordered TDD slices
+5. **Setup** (`/setup-workspace`) → Project scaffold, CI/CD, infrastructure
+6. **Implementation** (`/implement-slice`) → TDD vertical slices
+7. **Validation** (`/validate-phase`) → Quality gates and readiness checks
+
+## Getting Started
+
+After installation, start the pipeline with the ideate workflow to begin your project.
+
+## Documentation
+
+See the main project documentation in `docs/` for complete pipeline guides.

package/template/.codex/instructions/commands.md

@@ -0,0 +1,24 @@
+# Development Commands
+
+<!-- 
+  THIS FILE IS A TEMPLATE.
+  The /bootstrap-agents workflow fills per-surface command sections below.
+  For single-surface projects, one flat section is written.
+  For multi-surface projects, one section per surface.
+-->
+
+<!-- Bootstrap writes command sections here. Each surface from the map gets its own section. -->
+<!-- Single-surface projects get a flat layout (no surface header). -->
+
+{{COMMAND_SECTIONS}}
+
+## Validation (run after every code change)
+
+The validation command runs all checks for the primary surface. For multi-surface projects, run each surface's validation command.
+
+// turbo
+```bash
+{{VALIDATION_COMMAND}}
+```
+
+All checks must pass before marking any task complete.

package/template/.codex/instructions/example.md

@@ -0,0 +1,21 @@
+ideation/
+├── surfaces/
+│   ├── web/
+│   │   ├── webdomain-01/ (top domain)
+│   │   │  ├── 01.01-consumer-web/ (sub domain)
+│   │   │  │   └── 01.01.01-consumer-web-{{feat01}}.md 
+│   │   │  │   └── 01.01.02-consumer-web-{{feat02}}.md
+│   │   │  │   └── cunsumer-web-crosscut.md (sub domain CX)
+│   │   │  │   └── consumer-web-index.md (sub domain index)
+│   │   └── webdomain-02/ (top domain)
+│   │   │  ├── 01.02-education-hub/ (sub domain)
+│   │   │  │   └── 01.02.01-education-hub-{{feat01}}.md
+│   │   │  │   └── 01.02.02-education-hub-{{feat02}}.md
+│   │   │  │   └── education-hub-crosscut.md (sub domain CX)
+│   │   │  │   └── education-hub-index.md (sub domain index)
+│   │   ├── webdomain-cx.md (top domain cx)
+│   │   ├── webdomain-index.md (top domain index)
+│   ├── desktop/
+│   │   ├── desktopdomain-01/ (top domain)
+│   └── mobile/
+│       ├── mobiledomain-01/ (top domain)

package/template/.codex/instructions/patterns.md

@@ -0,0 +1,61 @@
+# Code Patterns & Conventions
+
+<!-- 
+  THIS FILE IS A TEMPLATE. 
+  The /bootstrap-agents workflow will fill in your project-specific patterns.
+  Sections marked with {{PLACEHOLDER}} will be replaced.
+-->
+
+## TypeScript → skills: `clean-code`, `typescript-advanced-patterns`
+- **Strict mode** everywhere — `strict: true` in tsconfig
+- **Explicit types** — No `any`, no implicit returns
+- **{{CONTRACT_LIBRARY}} validation** — All API inputs validated with {{CONTRACT_LIBRARY}} schemas
+- **Self-documenting** — Clear naming over comments
+- **{{CONTRACT_LIBRARY}} inference** — Derive types from {{CONTRACT_LIBRARY}} schemas (e.g., `z.infer<typeof schema>` for Zod, type inference for Pydantic)
+
+## File Organization → skill: `clean-code`
+- **File size limits** — Per-type limits (enforced by extensibility rule): 200 lines for components (.tsx), 300 for utilities (.ts), 150 for schemas (.schema.ts), 400 for tests (.test.ts), 100 for config files
+- **Single responsibility** — One component/module per file
+- **Named exports** — No default exports for utilities
+- **Direct imports** — Import from specific files, avoid barrel files
+
+## Components
+<!-- {{FRAMEWORK_PATTERNS}} — Filled by /bootstrap-agents based on chosen frontend framework -->
+> ⚠️ **Framework component patterns not yet configured.** Run /bootstrap-agents with FRAMEWORK_PATTERNS to fill this section. Until then, follow the framework's official documentation for component conventions and apply the naming and file organisation rules above.
+
+## API & Data → skill: `rest-api-design`
+- **Input validation** — {{CONTRACT_LIBRARY}} schemas on every endpoint
+- **Error format** — Consistent: `{ success: boolean, data?: T, error?: { code, message } }`
+- **No magic strings** — Constants and enums for repeated values
+- **Rate limiting** — On all public-facing endpoints
+
+## Security → skill: `security-scanning-security-hardening`
+- **No secrets in client code** — Server-side only, environment variables
+- **CSP headers** — Content Security Policy on all responses
+- **Input sanitization** — Prevent XSS, injection attacks
+- **CORS configured** — Explicit allowed origins, no wildcards in production
+
+## Naming
+- **Files:** kebab-case (`user-profile.tsx`)
+- **Components:** PascalCase (`UserProfile`)
+- **Functions:** camelCase (`getUserById`)
+- **Constants:** SCREAMING_SNAKE (`MAX_RETRY_COUNT`)
+- **Types/Interfaces:** PascalCase (`UserSession`)
+
+## What NOT to Do
+- No `console.log` in committed code — Use a structured logging utility
+- No `// TODO` — Lazy placeholders are banned. If the information you need genuinely doesn't exist yet, use a `// BOUNDARY:` stub (see rule: `boundary-not-placeholder`)
+- No `any` type — Ever
+- No inline styles — Use CSS classes or scoped styles
+- No hardcoded URLs — Use environment config
+- No barrel files (`index.ts`) — Import directly from source files
+
+<!-- 
+  Add project-specific sections below as your stack evolves:
+  ## State & Data
+  ## Caching
+  ## Observability
+  ## Payments
+  ## Email
+  ## Images
+-->

package/template/.codex/instructions/structure.md

@@ -0,0 +1,29 @@
+# Project Structure
+
+<!-- 
+  THIS FILE IS A TEMPLATE.
+  The /bootstrap-agents workflow will fill in your project-specific structure.
+-->
+
+## Current Layout
+
+```
+{{PROJECT_STRUCTURE}}
+```
+
+## Architecture Separation
+
+| Concern | Location | Runtime |
+|---------|----------|---------|
+| {{ARCHITECTURE_TABLE}} |
+
+## Protected Files (Do Not Modify Without Approval)
+- `AGENTS.md` — Project agent config
+- `.memory/wiki/specs/ENGINEERING-STANDARDS.md` — Quality bar
+- `.codex/instructions/*` — Agent rules
+- `package.json` — Dependencies (add carefully)
+- `tsconfig.json` — TypeScript config
+
+## Notes
+- Codex agent config lives in `.codex/`
+- Frontend and API may be separately deployed depending on architecture

package/template/.codex/instructions/tech-stack.md

@@ -0,0 +1,93 @@
+# Tech Stack
+
+<!--
+  THIS FILE IS A TEMPLATE.
+  The setup-cfsa skill fills the Surface Stack Map and Global Settings below.
+  Empty cells are marked with — (not applicable) or ⚠️ (not yet resolved).
+-->
+
+## Surface Stack Map
+
+The surface stack map is the **single source of truth** for all per-surface stack decisions and cross-cutting project-wide skills. Every workflow that needs to load skills or run commands resolves them from this map — NOT from scattered placeholders.
+
+### How Codex Workflows Use This Map
+
+**Surface-aware workflows** (spec-writing, implementation):
+1. Determine the shard/slice's surface from its directory path or surface tag
+2. Look up the row for that surface in the Per-Surface table below
+3. Load all skills listed in the required column(s) — cells are comma-separated lists
+4. Resolve each skill through the 4-tier resolution chain (see `.codex/skills/utilities/resolve-skill.md`)
+5. Skip cells marked `—` (not applicable for this surface)
+
+**Cross-cutting workflows** (validation, infrastructure verification):
+1. Read the Cross-Cutting Skills table below
+2. Load all skills listed in the required category
+3. Resolve through 4-tier chain if not already present
+
+**Single-surface projects**: The Per-Surface table has exactly one row. All lookups resolve identically to a flat scalar model. No conditional logic needed.
+
+### Per-Surface Skills
+
+Each cell is a comma-separated list of skill directory names from `.codex/skills/`. Use `—` for "not applicable."
+
+<!-- Bootstrap fills this table. One row per confirmed surface + a `shared` row for cross-surface backend. -->
+
+| Surface | Languages | BE Frameworks | FE Frameworks | FE Design | ORMs | State Mgmt | Databases | Unit Tests | E2E Tests | Test Cmd | Validation Cmd | Lint Cmd | Build Cmd | Dev Cmd | Package Mgr |
+|---------|-----------|---------------|---------------|-----------|------|------------|-----------|------------|-----------|----------|----------------|----------|-----------|---------|-------------|
+| {{SURFACE_ROW}} |
+
+> **Multi-value cells**: A surface can list multiple skills per column (e.g., `tailwind, vanilla-css` or `supabase, surrealdb, pglite`). Workflows iterate and load ALL listed skills.
+
+> **Shared row**: The `shared` surface represents cross-surface backend infrastructure (API layer, shared database, etc.). Shards in `.memory/wiki/specs/shared/` resolve against this row.
+
+### Cross-Cutting Skills
+
+Project-wide skills that don't vary per surface. Each value column is also comma-separated.
+
+<!-- Bootstrap fills this table from project-wide tech stack decisions. -->
+
+| Category | Skills |
+|----------|--------|
+| Auth | {{AUTH}} |
+| CI/CD | {{CI_CD}} |
+| Hosting | {{HOSTING}} |
+| Security | {{SECURITY}} |
+| API Design | {{API_DESIGN}} |
+| Accessibility | {{ACCESSIBILITY}} |
+| Contract Library | {{CONTRACT_LIBRARY}} |
+
+### Map Verification
+
+A valid surface stack map must satisfy:
+1. **At least one row** in the Per-Surface table (even single-surface projects)
+2. **Languages column is never empty** — every surface has at least one language
+3. **Test Cmd column is never empty** — every surface must be testable
+4. **No `⚠️` cells** — all skill resolution must be complete before implementation begins
+
+Verification gates in `workflow-plan-phase` and `workflow-implement-slice` check these conditions. See `.codex/skills/setup/setup-verify.md` for the full verification procedure.
+
+---
+
+## Global Settings
+
+<!-- These are project-wide values, not per-surface. Bootstrap fills them. -->
+
+| Setting | Value |
+|---------|-------|
+| Project Name | {{PROJECT_NAME}} |
+| Description | {{DESCRIPTION}} |
+| Stack Summary | {{TECH_STACK_SUMMARY}} |
+| Surfaces | {{SURFACES}} |
+| Architecture Doc | {{ARCHITECTURE_DOC}} |
+
+---
+
+## Installed Skills
+
+<!-- Updated by setup-provision-skills after skill discovery and provisioning -->
+{{INSTALLED_SKILLS}}
+
+## Reference
+
+- [Architecture Design](../../{{ARCHITECTURE_DOC}}) — full system design with rationale
+- [Engineering Standards](../../.memory/wiki/specs/ENGINEERING-STANDARDS.md) — Quality thresholds

package/template/.codex/instructions/workflow.md

@@ -0,0 +1,64 @@
+# Mandatory Execution Sequence
+
+Before taking any action on a task:
+
+## 1. Understand Context
+- Read the agent config file at project root (`AGENTS.md` for Antigravity, `GEMINI.md` for Gemini CLI, or equivalent for your agent)
+- Read relevant `.codex/instructions/` files for the task type
+- Check [Engineering Standards](../../.memory/wiki/specs/ENGINEERING-STANDARDS.md) for quality bar — if this file doesn't exist yet, the pipeline hasn't reached /create-prd; run /ideate then /create-prd first
+- **Session Resumption**: If `.memory/pipeline/progress/index.md` exists, read `.codex/skills/session-continuity/protocols/01-session-resumption.md` and follow the **Session Resumption Protocol** to load cross-session context and identify the resumption point
+
+## 2. Check Skills
+- Scan `.codex/skills/` for applicable skills
+- Load relevant skill SKILL.md before proceeding
+- Key skills: `brainstorming` (before creative work), `tdd-workflow` (before features), `clean-code` (during review)
+
+## 3. Execute
+
+> **Non-negotiable:** This project does not ship MVPs. Every line you write is
+> production code. There is no "rough draft" phase.
+
+- Follow the task requirements
+- Write production-grade code from the start — no exceptions, no "clean up later"
+- No placeholder implementations or `// TODO` comments — if the information you need genuinely doesn't exist yet, use a `// BOUNDARY:` stub with typed interface, tracking issue, and sentinel test (see rule: `boundary-not-placeholder`)
+- No deferred quality — if it's not ready for production, it's not ready to commit
+- **Cost-blind execution** — The cost of API calls, tokens, or compute to complete your work is NEVER your concern. Do not estimate, report, or factor operational AI costs into any decision. The only cost constraints that matter are user-defined project constraints (e.g., "keep hosting costs low," "prefer client-side compute"). If the user hasn't defined a cost constraint, cost is not a factor.
+- **Proactive effort mindset** — When you estimate a task will take significant effort, that is a signal to commit harder, not to defer. Small task? Get it done immediately. Large task? Buckle in, communicate progress, and work through it systematically. Time estimates drive commitment, never avoidance.
+
+## 4. Validate (MANDATORY)
+After **every** code change, run:
+```bash
+See `.codex/instructions/commands.md` for the validation command.
+```
+
+Do NOT mark a task complete until all validations pass.
+
+## 5. Learn (MANDATORY)
+
+After completing a workflow or substantial task:
+
+- **Pattern Extraction**: Read `.codex/skills/session-continuity/protocols/04-pattern-extraction.md` and follow the **Pattern Extraction Protocol**. Reflect on what worked, what didn't, and log reusable patterns to `memory/patterns.md`. Skip only if the task was trivial (routine, nothing new learned).
+- **Session Close**: Read `.codex/skills/session-continuity/protocols/05-session-close.md` and follow the **Session Close Protocol**. Write a session log to `.memory/pipeline/progress/sessions/` so the next session can resume cleanly.
+
+> These steps are **not optional**. They are what differentiate a pipeline that gets
+> smarter over time from one that repeats the same mistakes.
+
+## 6. Recommend Next Step (MANDATORY)
+
+Before reporting completion via `notify_user`:
+- Check the pipeline progress state (`.memory/pipeline/progress/spec-pipeline.md` or equivalent)
+- Propose the next valid pipeline command to the user
+- If multiple valid next steps exist, list them with brief context
+- Never end a conversation without telling the user what to do next
+
+> This closes the gap where individual workflow files include "next step" sections,
+> but agents don't read those files at session start. This step ensures the
+> recommendation happens regardless.
+
+## Principles
+
+- **Ask before assuming** — Clarify ambiguous requirements
+- **Small changes** — Commit frequently, keep diffs reviewable
+- **Test first** — Write failing tests before implementation — no exceptions
+- **Security always** — Validate inputs, sanitize outputs, never expose secrets
+- **Work is the job** — Never use the size, complexity, or duration of a task as a reason to reduce quality or scope. Large tasks get more effort, not less quality.

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

@@ -0,0 +1,6 @@
+# Kit Sync State
+
+upstream: https://github.com/RepairYourTech/cfsa-antigravity
+last_synced_commit: 41065b8165f7ea05b56a48f029eabcca52aa3049
+last_synced_at: 2026-05-03T19:45:21Z
+kit_version: 3.1.0

package/template/.codex/rules/boundary-not-placeholder.md

@@ -0,0 +1,146 @@
+---
+description: TODOs and placeholders are banned — boundary stubs are allowed ONLY when required information doesn't exist yet
+trigger: always_on
+---
+
+# Boundary Not Placeholder
+
+## The Rule
+
+**Lazy placeholders are banned. Boundary stubs are allowed under strict conditions.**
+
+The difference is not about effort, complexity, or scope — it is about
+**whether the information you need to do the work exists.**
+
+## What Is NEVER a Valid Reason for a Stub
+
+| Excuse | Why It's Not Valid |
+|--------|-------------------|
+| "This is a lot of work" | Amount of work is irrelevant. Do the work. |
+| "This spans outside the current task" | If the spec exists, you have the information. Do it. |
+| "This is complex" | Complexity is not an obstacle if the spec defines the behavior. |
+| "I'll come back to this" | No you won't. Do it now. |
+| "This should be a separate PR" | Code organization ≠ deferred implementation. |
+| "This needs refactoring first" | Refactor, then implement. Don't stub. |
+| "The test is passing without it" | Then your test is incomplete. Fix the test. |
+| "This is boilerplate" | Boilerplate is still production code. Write it. |
+| "This will cost X in API calls/tokens" | Your operational cost is never a factor. Do the work. |
+| "This will take a long time" | Time is a signal to commit harder, not to defer. |
+| "For efficiency, I'll skip this" | Efficiency means doing it right, not doing less. |
+
+## The ONLY Valid Reason for a Boundary Stub
+
+> **The spec, schema, or contract that defines the required behavior has not
+> been written yet.** You literally cannot implement it because the information
+> that tells you *what* to implement does not yet exist in any document,
+> schema file, or codebase artifact.
+
+Examples of genuinely valid boundaries:
+
+| Situation | Why It's Valid |
+|-----------|---------------|
+| Auth middleware spec is in a future shard that hasn't been written | No IA/BE spec exists for the auth behavior |
+| Payment webhook handler depends on a Stripe integration spec not yet created | No contract defines the webhook payload shape |
+| Component needs data from an API endpoint whose BE spec doesn't exist yet | No schema defines the response format |
+| Feature depends on a third-party SDK that hasn't been evaluated yet | No architecture decision has been made |
+
+## The Three-Part Test
+
+Before writing a boundary stub, answer ALL THREE questions:
+
+1. **Does a spec exist for this behavior?** (IA shard, BE spec, FE spec, contract)
+   - If YES → you have the information. Implement it. No stub allowed.
+   - If NO → proceed to question 2.
+
+2. **Could you write the spec right now?**
+   - If YES → write the spec first, then implement. No stub allowed.
+   - If NO (requires a user decision, external dependency, or upstream spec) → proceed to question 3.
+
+3. **Is this blocking the current slice from being testable and functional?**
+   - If YES → write a boundary stub (see requirements below).
+   - If NO → omit it entirely. Don't stub what you don't need yet.
+
+## Boundary Stub Requirements
+
+If — and ONLY if — all three tests pass, a boundary stub must include:
+
+### 1. Typed Interface
+```typescript
+// ✅ Boundary stub — typed interface for future auth middleware
+// BOUNDARY: Requires IA shard 04 (authentication) — not yet specified
+// TRACKING: #123
+export interface AuthMiddleware {
+  requireAuth: (roles: string[]) => RequestHandler;
+  validateToken: (token: string) => Promise<AuthResult>;
+}
+
+// Temporary: returns a no-op until auth spec is written
+export const authMiddleware: AuthMiddleware = {
+  requireAuth: (_roles) => (_req, _res, next) => next(),
+  validateToken: async (_token) => ({ valid: false, reason: 'auth-not-implemented' }),
+};
+```
+
+### 2. Tracking Issue
+Every boundary stub MUST have a linked GitHub issue that includes:
+- Which spec is missing (e.g., "IA shard 04: Authentication")
+- What the stub currently does (e.g., "no-op passthrough")
+- What it should do when the spec is written
+
+### 3. Sentinel Test
+
+The sentinel test must verify that calling the function returns a structured boundary response — not `undefined` or an error. Specific assertion syntax depends on your test framework:
+
+- **Jest / Vitest**: `expect(fn()).resolves.toEqual({ ... })`
+- **pytest**: `assert fn() == { ... }`
+- **Rust**: `assert_eq!(fn(), BoundaryResponse { ... })`
+
+The test exists to remind the team the stub is still active. When the real implementation replaces the stub, this test is replaced with full behavioral tests.
+
+### 4. BOUNDARY Comment Prefix
+All boundary stubs use the `BOUNDARY:` prefix (not `TODO:`):
+```typescript
+// BOUNDARY: Requires BE spec for payment-webhooks — not yet written
+// TRACKING: #456
+```
+
+This makes boundary stubs greppable and distinguishable from lazy TODOs:
+```bash
+grep -r "BOUNDARY:" src/    # Shows legitimate cross-cutting boundaries
+grep -r "TODO:" src/        # Should return ZERO results
+```
+
+## What Gets Flagged in Code Review
+
+| Pattern | Verdict |
+|---------|---------|
+| `// TODO: implement later` | ❌ **Rejected.** Lazy placeholder. |
+| `// TODO: add error handling` | ❌ **Rejected.** Error handling is part of the current work. |
+| `throw new Error('not implemented')` | ❌ **Rejected.** Empty implementation. |
+| `// BOUNDARY: Requires IA shard 04` + typed interface + issue + sentinel test | ✅ **Allowed.** Information genuinely doesn't exist. |
+| `test.skip('auth integration')` without linked issue | ❌ **Rejected.** Skipped tests need accountability. |
+| `test.skip('auth integration') // BOUNDARY: #123` | ✅ **Allowed.** Tracked and accountable. |
+
+## Summary
+
+```
+                    ┌─────────────────────────┐
+                    │ Can I implement this?    │
+                    └────────┬────────────────┘
+                             │
+                    ┌────────▼────────────────┐
+                    │ Does the spec exist?     │
+                    └────────┬────────────────┘
+                         YES │           NO
+                    ┌────────▼───┐  ┌────▼──────────────┐
+                    │ IMPLEMENT. │  │ Can I write the    │
+                    │ No excuses.│  │ spec right now?    │
+                    └────────────┘  └────┬──────────────┘
+                                     YES │           NO
+                               ┌─────────▼──┐  ┌────▼──────────────┐
+                               │ Write spec, │  │ Boundary stub:    │
+                               │ then impl.  │  │ typed interface + │
+                               └─────────────┘  │ tracking issue +  │
+                                                 │ sentinel test     │
+                                                 └──────────────────┘
+```

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

@@ -0,0 +1,60 @@
+---
+description: Code plus tests plus tracking equals done — never mark complete without updating progress files
+trigger: always_on
+---
+
+# Completion Checklist
+
+> Code complete ≠ done. Tests pass ≠ done.
+> Code complete + tests pass + tracking updated = DONE.
+
+## The Problem
+
+Working code is only half the job of a software engineer. The other half is communicating
+that work, updating shared state, releasing locks, and documenting decisions so the rest of
+the team (or your future self) can understand what happened.
+
+When an agent reports a task as "complete" without updating the progress tracking files,
+it breaks the pipeline. The next agent won't know what's done, dependencies get blocked,
+and the human operator loses visibility.
+
+## The Rule
+
+**You are never "done" just because the code works and the tests pass.**
+
+Before concluding any workflow, task, or slice — and especially before calling `notify_user`
+to report completion — you must verify you have completed the administrative checklist.
+
+## The Definition of Done
+
+A unit of work is only DONE when:
+
+1. **The Code**: Implementation meets the contract and acceptance criteria.
+2. **The Tests**: All tests pass (validation step is green).
+3. **The Tracking**: Progress markdown files in `.memory/pipeline/progress/` are updated.
+   - Acceptance criteria marked `[x]`
+   - Slice/Task marked `[x]`
+   - 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**: The unified project memory in `.memory/wiki/` is 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 `.memory/pipeline/progress/sessions/`.
+   - Follow `.codex/skills/session-continuity/protocols/05-session-close.md` — write what was accomplished, deferred, and where the next session should start
+7. **The Next Step**: The user is told what comes next in the pipeline.
+   - Read the pipeline progress file (`.memory/pipeline/progress/spec-pipeline.md` or equivalent)
+   - Propose the next valid pipeline command based on current state
+   - If multiple options exist, present them as a numbered list with brief context
+   - If the pipeline stage is complete, say so explicitly
+
+## Enforcement
+
+If you are following a workflow that includes a "Completion Gate" or a checklist for
+updating progress files, **you may not skip it**.
+
+If you skip the progress tracking steps, you have failed the task, regardless of how
+good the code is.
+

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