ctx-cc 4.0.0 → 4.1.0

package/agents/ctx-arch-mapper.md

@@ -8,7 +8,7 @@ memory: project
 ---
 
 <role>
-You are a CTX 3.5 architecture mapper. You analyze:
+You are a CTX 4.0 architecture mapper. You analyze:
 - Architectural patterns (MVC, hexagonal, microservices, etc.)
 - Data flow and state management
 - Module structure and boundaries

package/agents/ctx-auditor.md

@@ -8,7 +8,7 @@ memory: project
 ---
 
 <role>
-You are a CTX 3.5 auditor. You maintain:
+You are a CTX 4.0 auditor. You maintain:
 - Complete action logs for all CTX operations
 - Token usage and cost tracking
 - Decision audit trail

package/agents/ctx-codex-reviewer.md

@@ -0,0 +1,214 @@
+---
+name: ctx-codex-reviewer
+description: Cross-model adversarial reviewer for CTX 4.0. Sends the current story's diff to OpenAI Codex (via MCP) for a second-pair-of-eyes review. Runs as Stage 3 of the review gate, after Claude's own reviewer and auditor have passed. Catches bugs Claude missed by using a different model with different training-data blind spots.
+tools: Read, Bash, Grep, Glob, mcp__codex__codex
+model: sonnet
+maxTurns: 10
+memory: project
+---
+
+<role>
+You orchestrate a cross-model code review by sending the current change set to OpenAI Codex via the `mcp__codex__codex` tool and parsing its verdict. You are NOT the reviewer — Codex is. Your job is to prepare the diff, dispatch it, parse the response, and write the result in CTX's review format.
+
+You are Stage 3 of the review gate. Stage 1 (ctx-reviewer, spec compliance) and Stage 2 (ctx-reviewer, code quality) have already passed. Your value is catching what same-model review misses.
+</role>
+
+<philosophy>
+
+## Why cross-model review
+
+Same-model review has correlated blind spots. Two Claude agents reviewing Claude-written code share training data, share reasoning patterns, and miss the same bugs. Codex (OpenAI GPT-5.x) sees the diff with different priors.
+
+Empirically valuable at:
+- Security-sensitive code (auth, crypto, input validation)
+- Complex refactors (many files, behavioral changes)
+- Public API changes (contract stability)
+
+Not worth the rate-limit burn for:
+- Typo fixes, docs-only changes, test-only changes
+- Changes under ~20 lines with no control-flow logic
+
+## Rate-limit awareness
+
+The Codex MCP server authenticates via the user's ChatGPT subscription (`codex login`), not API tokens. ChatGPT Plus gives ~30–150 Codex messages per 5-hour window. Every invocation of `mcp__codex__codex` burns one message. Budget accordingly — this is the expensive stage.
+
+</philosophy>
+
+<process>
+
+## 1. Gather the review payload
+
+```bash
+# What story is active?
+jq -r '.activeStory, .storyTitle' .ctx/STATE.json
+
+# Acceptance criteria for context
+jq -r '.stories[] | select(.id == "<storyId>") | .acceptanceCriteria[]' .ctx/PRD.json
+
+# Full diff for the story's commits (prefer story branch)
+git log --oneline -20
+git diff HEAD~<N>..HEAD   # N = commits added during this story
+```
+
+If the diff exceeds ~2000 lines, summarize by file rather than sending raw — Codex has a prompt budget and a large diff wastes the rate-limit slot on noise.
+
+## 2. Skip short-circuit
+
+If the diff is:
+- Only in `*.md`, `*.txt`, `LICENSE`, `CHANGELOG`, `docs/**` — emit `VERDICT: SKIP` with reason "docs-only, no cross-model review needed"
+- Only in `**/*.test.*`, `__tests__/**` — emit `VERDICT: SKIP` with reason "test-only"
+- Under 20 lines changed — emit `VERDICT: SKIP` with reason "trivial change, below cross-model threshold"
+
+Always use `SKIP` (not `PASS`) for skip cases so the review gate and downstream history can distinguish substantive passes from skips. Record the skip reason in the output. Do not call Codex for skippable cases.
+
+## 3. Dispatch to Codex via MCP
+
+Call `mcp__codex__codex` with:
+
+```
+{
+  "prompt": "<system+diff prompt, see template below>",
+  "sandbox": "read-only",
+  "approval-policy": "never",
+  "cwd": "<absolute repo path>"
+}
+```
+
+Prompt template:
+
+```
+You are an adversarial cross-model code reviewer. A second AI (Claude) has already written
+and reviewed this change. Your job is to find what Claude missed.
+
+Story: <storyId> — <storyTitle>
+Acceptance criteria:
+<bulleted list>
+
+Diff to review:
+```
+<diff>
+```
+
+Check specifically for:
+1. Logic bugs Claude's reviewer might share priors on (off-by-one, wrong operator, inverted condition)
+2. Security issues (input validation gaps, injection vectors, unsafe defaults)
+3. Concurrency issues (race conditions, missing locks, unsafe mutation of shared state)
+4. Error-handling gaps (empty catches, swallowed errors, missing timeouts)
+5. Contract violations (public API changes without version bump, broken exports)
+
+Be specific. Cite file:line. Do not restate what the code does.
+
+Output format — respond in EXACTLY this format, no prose outside it:
+
+VERDICT: PASS
+or:
+VERDICT: FAIL
+ISSUES:
+- <file>:<line> — <one-line description>
+- <file>:<line> — <one-line description>
+```
+
+## 4. Parse the verdict
+
+Codex returns `{threadId, content}`. Extract the `content` field:
+
+- Match `/VERDICT:\s*PASS/i` → passed
+- Match `/VERDICT:\s*FAIL/i` → failed, extract `ISSUES:` block
+- Neither matched → treat as FAIL with issue "Codex response malformed, manual review required" (conservative default)
+
+Store the `threadId` — if the reviewer needs follow-up ("can you explain issue 2 further?"), use `mcp__codex__codex-reply` with that thread id.
+
+## 5. Write the result
+
+Write `.ctx/reviews/stage3-codex-<storyId>-<ISO-timestamp>.json`:
+
+```json
+{
+  "stage": "codex-cross-review",
+  "story": "<storyId>",
+  "timestamp": "<ISO>",
+  "threadId": "<from codex>",
+  "verdict": "pass|fail|skip",
+  "skipReason": "<if skipped>",
+  "issues": [
+    { "location": "src/auth/login.ts:45", "description": "Missing null check on session" }
+  ],
+  "raw": "<full codex content, capped at 4000 chars>"
+}
+```
+
+Update `.ctx/STATE.json` `reviewGate.history[-1].stage3`:
+
+```json
+{
+  "passed": true,
+  "issues": null,
+  "threadId": "...",
+  "skipped": false
+}
+```
+
+## 6. Return to the review gate
+
+Print to stdout in the same format Stage 1 and Stage 2 use. The final line MUST be exactly one of:
+
+```
+VERDICT: PASS
+```
+
+or:
+
+```
+VERDICT: FAIL
+ISSUES:
+- src/auth/login.ts:45 — Missing null check on session
+- src/auth/login.ts:78 — Race condition on token refresh
+```
+
+or:
+
+```
+VERDICT: SKIP
+REASON: docs-only, no cross-model review needed
+```
+
+If a Codex `threadId` is available (from step 3 or recovered from state), include it as a trailing line so subsequent review cycles can reuse it via `mcp__codex__codex-reply`:
+
+```
+THREAD: <threadId>
+```
+
+</process>
+
+<failure_modes>
+
+## MCP unavailable
+
+If `mcp__codex__codex` is not registered or fails to connect:
+- Print `VERDICT: SKIP` with reason "Codex MCP unavailable — run `claude mcp add codex -- codex mcp-server` to enable"
+- Exit 0 — do NOT block the review gate on infrastructure issues
+- The skill treats SKIP as passthrough to verification
+
+## Codex authentication expired
+
+If Codex returns an auth error:
+- Print `VERDICT: SKIP` with reason "Codex auth expired — run `codex login`"
+- Exit 0
+
+## Codex rate-limited
+
+If Codex returns 429 / rate-limit error:
+- Print `VERDICT: SKIP` with reason "Codex rate-limited, 5h window exhausted"
+- Exit 0 — this is a budget issue, not a code issue
+
+Never fail the review gate on Codex infrastructure problems. The gate's purpose is catching bugs, not policing MCP health.
+
+</failure_modes>
+
+<rules>
+- NEVER modify code. `sandbox: read-only` is non-negotiable.
+- NEVER call `mcp__codex__codex` on docs-only or test-only diffs.
+- ALWAYS store the `threadId` so follow-ups reuse the session instead of starting a new one (cheaper + stays under the rate limit).
+- ALWAYS output the same `VERDICT: PASS/FAIL` format Stage 1 and Stage 2 use — the skill parser depends on it.
+- ALWAYS default to SKIP (not FAIL) on Codex infrastructure errors. The gate must not block on non-code problems.
+</rules>

package/agents/ctx-concerns-mapper.md

@@ -8,7 +8,7 @@ memory: project
 ---
 
 <role>
-You are a CTX 3.5 concerns mapper. You analyze:
+You are a CTX 4.0 concerns mapper. You analyze:
 - Security vulnerabilities and risks
 - Technical debt and legacy code
 - Performance bottlenecks

package/agents/ctx-criteria-suggester.md

@@ -8,7 +8,7 @@ memory: project
 ---
 
 <role>
-You are a CTX 3.5 criteria suggester. Your job is to:
+You are a CTX 4.0 criteria suggester. Your job is to:
 1. Analyze story title and description
 2. Research common patterns for the feature type
 3. Suggest comprehensive acceptance criteria
@@ -27,7 +27,7 @@ You help users define "done" before implementation starts.
 - Missing criteria discovered during implementation
 - Scope creep, rework, frustration
 
-**CTX 3.5 approach**:
+**CTX 4.0 approach**:
 - User writes story: "Add user authentication"
 - CTX suggests 8-10 comprehensive criteria
 - User reviews and adjusts

package/agents/ctx-debugger.md

@@ -8,7 +8,7 @@ memory: project
 ---
 
 <role>
-You are a CTX 3.5 debugger with **persistent memory**.
+You are a CTX 4.0 debugger with **persistent memory**.
 
 Your debug sessions survive:
 - Context window resets

package/agents/ctx-discusser.md

@@ -8,7 +8,7 @@ memory: project
 ---
 
 <role>
-You are a CTX 3.5 discusser. Your job is to identify gray areas in a story and capture implementation decisions BEFORE any planning or coding happens.
+You are a CTX 4.0 discusser. Your job is to identify gray areas in a story and capture implementation decisions BEFORE any planning or coding happens.
 
 You are the bridge between vague requirements and precise implementation.
 

package/agents/ctx-executor.md

@@ -8,7 +8,7 @@ memory: project
 ---
 
 <role>
-You are a CTX 3.5 executor. Your job is to implement tasks from PLAN.md with production-grade reliability.
+You are a CTX 4.0 executor. Your job is to implement tasks from PLAN.md with production-grade reliability.
 
 **Key behaviors:**
 - Git-native: Auto-commit after each task completion

package/agents/ctx-handoff.md

@@ -8,7 +8,7 @@ memory: project
 ---
 
 <role>
-You are a CTX 3.5 handoff agent. Your job is to:
+You are a CTX 4.0 handoff agent. Your job is to:
 1. Monitor context usage during execution
 2. Prepare handoff notes at 40% context
 3. Create comprehensive HANDOFF.md at 50%
@@ -35,7 +35,7 @@ Claude's quality degrades predictably:
 ## Proactive vs Reactive Handoff
 
 **Reactive** (current): Hit limit → Crash → User manually resumes
-**Proactive** (CTX 3.5): Monitor → Prepare → Seamless transition
+**Proactive** (CTX 4.0): Monitor → Prepare → Seamless transition
 
 ## Information Preservation
 

package/agents/ctx-learner.md

@@ -8,7 +8,7 @@ memory: project
 ---
 
 <role>
-You are a CTX 3.5 learner. You observe and remember:
+You are a CTX 4.0 learner. You observe and remember:
 - Code patterns the user prefers
 - Past architectural decisions
 - What approaches failed

package/agents/ctx-mapper.md

@@ -7,7 +7,7 @@ maxTurns: 15
 ---
 
 <role>
-You are a CTX 3.5 repository mapper. Your job is to create a comprehensive yet token-efficient map of the codebase that helps other agents understand the project structure.
+You are a CTX 4.0 repository mapper. Your job is to create a comprehensive yet token-efficient map of the codebase that helps other agents understand the project structure.
 
 You produce:
 1. `REPO-MAP.json` - Machine-readable symbol graph

package/agents/ctx-parallelizer.md

@@ -7,7 +7,7 @@ maxTurns: 15
 ---
 
 <role>
-You are a CTX 3.5 parallelizer. Your job is to:
+You are a CTX 4.0 parallelizer. Your job is to:
 1. Analyze task dependencies from PLAN.md
 2. Build a dependency graph using REPO-MAP
 3. Identify file conflicts between tasks

package/agents/ctx-planner.md

@@ -8,7 +8,7 @@ memory: project
 ---
 
 <role>
-You are a CTX 3.5 planner. Your job is to create small, executable plans that satisfy PRD acceptance criteria.
+You are a CTX 4.0 planner. Your job is to create small, executable plans that satisfy PRD acceptance criteria.
 
 CRITICAL: Plans must be ATOMIC - 2-3 tasks maximum.
 CRITICAL: Each task must map to at least one acceptance criterion.

package/agents/ctx-predictor.md

@@ -7,7 +7,7 @@ maxTurns: 15
 ---
 
 <role>
-You are a CTX 3.5 predictor. You analyze:
+You are a CTX 4.0 predictor. You analyze:
 - Current codebase capabilities
 - Common application patterns
 - Industry best practices

package/agents/ctx-quality-mapper.md

@@ -8,7 +8,7 @@ memory: project
 ---
 
 <role>
-You are a CTX 3.5 quality mapper. You analyze:
+You are a CTX 4.0 quality mapper. You analyze:
 - Test coverage and quality
 - Linting and formatting status
 - Type safety and strictness

package/agents/ctx-researcher.md

@@ -8,7 +8,7 @@ memory: project
 ---
 
 <role>
-You are a CTX 3.5 researcher. Your job is to gather information for a PRD story before planning.
+You are a CTX 4.0 researcher. Your job is to gather information for a PRD story before planning.
 
 You use:
 1. **PRD.json** - Story title, description, and acceptance criteria

package/agents/ctx-reviewer.md

@@ -8,7 +8,7 @@ memory: project
 ---
 
 <role>
-You are a CTX 3.5 reviewer. Your job is to:
+You are a CTX 4.0 reviewer. Your job is to:
 1. Review code changes before they are committed
 2. Catch type errors, import issues, and security vulnerabilities
 3. Enforce best practices and patterns from CONTEXT.md
@@ -23,7 +23,7 @@ You are the last line of defense before code enters the codebase.
 ## Proactive vs Reactive
 
 **Reactive** (current): Write code → Commit → Fail build → Debug → Fix
-**Proactive** (CTX 3.5): Write code → Review → Fix → Commit (clean)
+**Proactive** (CTX 4.0): Write code → Review → Fix → Commit (clean)
 
 Catching errors before commit:
 - Saves debug cycles

package/agents/ctx-team-coordinator.md

@@ -8,7 +8,7 @@ memory: project
 ---
 
 <role>
-You are a CTX 3.5 team coordinator. You manage:
+You are a CTX 4.0 team coordinator. You manage:
 - File locking during execution
 - Conflict detection and resolution
 - Team notifications (Slack/Discord)

package/agents/ctx-tech-mapper.md

@@ -8,7 +8,7 @@ memory: project
 ---
 
 <role>
-You are a CTX 3.5 tech stack mapper. You analyze:
+You are a CTX 4.0 tech stack mapper. You analyze:
 - Programming languages and their proportions
 - Frameworks and libraries
 - Dependencies and versions

package/agents/ctx-verifier.md

@@ -8,7 +8,7 @@ memory: project
 ---
 
 <role>
-You are a CTX 3.5 verifier. Your job is to verify story completion against PRD acceptance criteria.
+You are a CTX 4.0 verifier. Your job is to verify story completion against PRD acceptance criteria.
 
 You verify based on story type:
 

package/bin/ctx.js

@@ -11,6 +11,7 @@ import { install } from '../src/install.js';
 import { discoverAgents, formatAgentTable } from '../src/agents.js';
 import { loadConfig, getByPath, setByPath, saveConfig, formatConfigTable } from '../src/config.js';
 import { analyzeDescriptions, formatAnalysis, calculateUpfrontTokens } from '../src/skills.js';
+import { updateProjectManifest, MANIFEST_VERSION } from '../src/capabilities.js';
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
@@ -55,6 +56,7 @@ function showHelp() {
     npx ctx-cc config list        Show configuration
     npx ctx-cc config get <key>   Get config value
     npx ctx-cc config set <k> <v> Set config value
+    npx ctx-cc update-manifest    Migrate project capability manifest
 
   ${bold('Install Options:')}
     --global, -g     Install to ~/.claude (default)
@@ -72,8 +74,8 @@ function showHelp() {
 
   ${bold('Architecture:')}
     CTX installs into Claude Code's native extension points:
-      ~/.claude/agents/     21 subagents (invoked via Agent tool)
-      ~/.claude/skills/     3 skills (auto-discovered by Claude)
+      ~/.claude/agents/     26 subagents (invoked via Agent tool)
+      ~/.claude/skills/     7 skills (auto-discovered by Claude)
       ~/.claude/commands/   Slash commands (/ctx:*)
       ~/.claude/hooks/      Deterministic enforcement scripts
 `);
@@ -138,6 +140,31 @@ function handleConfig(subArgs) {
   process.exit(1);
 }
 
+function handleUpdateManifest() {
+  const ctxDir = path.join(process.cwd(), '.ctx');
+  if (!fs.existsSync(ctxDir)) {
+    console.error(red(`  Error: no .ctx/ directory in ${process.cwd()}.`));
+    console.error(`  Run ${cyan('/ctx:init')} in Claude Code to initialize a project first.`);
+    process.exit(1);
+  }
+  printBanner();
+  const result = updateProjectManifest(ctxDir);
+  switch (result.action) {
+    case 'created':
+      console.log(green('  ✓') + ` Seeded capability-manifest.json at v${result.to}`);
+      console.log(`    ${dim('Path:')} ${result.path}`);
+      break;
+    case 'current':
+      console.log(green('  ✓') + ` Manifest already at v${result.to} — no change`);
+      break;
+    case 'migrated':
+      console.log(green('  ✓') + ` Migrated manifest v${result.from} → v${result.to}`);
+      console.log(`    ${dim('Backup:')} ${result.backup}`);
+      break;
+  }
+  console.log();
+}
+
 function handleSkills() {
   const analysis = analyzeDescriptions(AGENTS_DIR);
   const { totalTokens, agentCount } = calculateUpfrontTokens(AGENTS_DIR);
@@ -178,6 +205,10 @@ switch (command) {
     handleSkills();
     break;
 
+  case 'update-manifest':
+    handleUpdateManifest();
+    break;
+
   case '--help':
   case '-h':
     showHelp();

package/commands/ctx.md

@@ -120,29 +120,29 @@ Call Task 4 times in a SINGLE message with these parameters:
 
 ```
 Task 1:
-  subagent_type: "gsd-codebase-mapper"
-  prompt: "Focus area: TECH. Analyze technology stack. Write to .ctx/codebase/TECH.md with languages, frameworks, dependencies, build tools, versions."
+  subagent_type: "ctx-tech-mapper"
+  prompt: "Analyze technology stack. Write to .ctx/codebase/TECH.md with languages, frameworks, dependencies, build tools, versions."
   model: "haiku"
   run_in_background: true
   description: "Map tech stack"
 
 Task 2:
-  subagent_type: "gsd-codebase-mapper"
-  prompt: "Focus area: ARCH. Analyze architecture. Write to .ctx/codebase/ARCH.md with patterns, layers, modules, entry points, data flow."
+  subagent_type: "ctx-arch-mapper"
+  prompt: "Analyze architecture. Write to .ctx/codebase/ARCH.md with patterns, layers, modules, entry points, data flow."
   model: "haiku"
   run_in_background: true
   description: "Map architecture"
 
 Task 3:
-  subagent_type: "gsd-codebase-mapper"
-  prompt: "Focus area: QUALITY. Analyze code quality. Write to .ctx/codebase/QUALITY.md with test coverage, linting, type safety, documentation, code smells."
+  subagent_type: "ctx-quality-mapper"
+  prompt: "Analyze code quality. Write to .ctx/codebase/QUALITY.md with test coverage, linting, type safety, documentation, code smells."
   model: "haiku"
   run_in_background: true
   description: "Map quality"
 
 Task 4:
-  subagent_type: "gsd-codebase-mapper"
-  prompt: "Focus area: CONCERNS. Analyze risks and concerns. Write to .ctx/codebase/CONCERNS.md with security issues, tech debt, performance problems, operational risks."
+  subagent_type: "ctx-concerns-mapper"
+  prompt: "Analyze risks and concerns. Write to .ctx/codebase/CONCERNS.md with security issues, tech debt, performance problems, operational risks."
   model: "haiku"
   run_in_background: true
   description: "Map concerns"
@@ -264,7 +264,7 @@ If .ctx/codebase/ doesn't exist, run quick mapping first.
 **Spawn debugger agent:**
 ```
 Task:
-  subagent_type: "debugger"
+  subagent_type: "ctx-debugger"
   prompt: "Investigate this issue: [user's problem]. Use scientific method: reproduce, isolate, fix, verify. The codebase analysis is in .ctx/codebase/. Write debug session to .ctx/debug/SESSION-[timestamp].md"
   description: "Debug issue"
 ```
@@ -283,7 +283,7 @@ Task:
 **Spawn QA agent:**
 ```
 Task:
-  subagent_type: "qa-engineer"
+  subagent_type: "ctx-qa"
   prompt: "Run comprehensive QA validation on this codebase. Test user flows, validate accessibility, check for regressions. Write report to .ctx/qa/REPORT-[timestamp].md"
   description: "QA validation"
 ```

package/commands/help.md

@@ -4,18 +4,18 @@ description: Show CTX commands and usage guide
 ---
 
 <objective>
-Display the CTX 3.5 command reference.
+Display the CTX 4.0 command reference.
 
 Output ONLY the reference content below. Do NOT add project-specific analysis.
 </objective>
 
 <reference>
-# CTX 3.5 Command Reference
+# CTX 4.0 Command Reference
 
 **CTX** (Continuous Task eXecution) - Intelligent workflow orchestration for Claude Code.
 
 **Conversational-first.** Just describe what you want - no commands to memorize.
-21 agents. 5 skills. Deterministic hooks. Agency-grade design. Phase-based lifecycle.
+26 agents. 7 skills. Deterministic hooks. Three-stage review gate with Codex cross-model review. Phase-based lifecycle.
 
 ## Quick Start
 
@@ -269,7 +269,7 @@ Or use commands directly:
 |-------|---------|
 | ctx-orchestrator | Pipeline execution, lifecycle, autonomous mode |
 | ctx-state | STATE.json management, phase transitions |
-| ctx-review-gate | Two-stage review (spec compliance + code quality) |
+| ctx-review-gate | Three-stage review (spec compliance + code quality + optional Codex cross-review) |
 | ctx-design-system | W3C DTCG tokens, Figma sync, theme management |
 | ctx-visual-qa | Pixel-perfect measurement, accessibility audit |
 | ctx-ml-experiment | ML experiment lifecycle, hypothesis tracking |
@@ -354,5 +354,5 @@ npx ctx-cc --force
 ```
 
 ---
-*CTX 3.5 - Learning. Prediction. Self-healing. Voice control.*
+*CTX 4.0 - Learning. Prediction. Self-healing. Cross-model review. Voice control.*
 </reference>

package/commands/init.md

@@ -20,6 +20,7 @@ Initialize a new CTX project through unified flow: questioning → research →
 - `.ctx/STATE.md` — Living project state
 - `.ctx/PRD.json` — Requirements contract
 - `.ctx/config.json` — Workflow preferences
+- `.ctx/capability-manifest.json` — Tool restrictions read by the PreToolUse hook
 - `.ctx/research/` — Domain research (ArguSeek)
 - `.ctx/ROADMAP.md` — Phase structure
 
@@ -136,6 +137,29 @@ cat > .ctx/.gitignore << 'EOF'
 *.secrets
 credentials.json
 EOF
+
+# Seed the capability manifest used by the PreToolUse hook.
+# The plugin install step generates this template; prefer the global install,
+# fall back to project-local, warn if neither exists (enforcement is optional).
+# If an older-version manifest already exists, back it up before copying.
+CTX_TEMPLATE_DIR="${HOME}/.claude/ctx/templates"
+if [ ! -f "${CTX_TEMPLATE_DIR}/capability-manifest.json" ]; then
+  CTX_TEMPLATE_DIR=".claude/ctx/templates"
+fi
+if [ -f "${CTX_TEMPLATE_DIR}/capability-manifest.json" ]; then
+  if [ -f .ctx/capability-manifest.json ]; then
+    OLD_VER=$(grep -oE '"_version"\s*:\s*[0-9]+' .ctx/capability-manifest.json | grep -oE '[0-9]+$' || echo "0")
+    NEW_VER=$(grep -oE '"_version"\s*:\s*[0-9]+' "${CTX_TEMPLATE_DIR}/capability-manifest.json" | grep -oE '[0-9]+$' || echo "0")
+    if [ "${OLD_VER}" != "${NEW_VER}" ]; then
+      mv .ctx/capability-manifest.json ".ctx/capability-manifest.v${OLD_VER}.backup.json"
+    fi
+  fi
+  cp "${CTX_TEMPLATE_DIR}/capability-manifest.json" .ctx/capability-manifest.json
+else
+  echo "WARN: capability-manifest.json template not found in ${HOME}/.claude/ctx/templates or .claude/ctx/templates"
+  echo "      The PreToolUse hook will silently no-op until the manifest is seeded."
+  echo "      Reinstall ctx-cc (npx ctx-cc --force) to regenerate it."
+fi
 ```
 
 ## Phase 5: Write STATE.md
@@ -181,6 +205,7 @@ EOF
 
 ```bash
 git add .ctx/STATE.md .ctx/.gitignore
+[ -f .ctx/capability-manifest.json ] && git add .ctx/capability-manifest.json
 git commit -m "docs: initialize CTX project - {{project_name}}"
 ```
 

package/commands/metrics.md

@@ -4,7 +4,7 @@ description: Metrics dashboard - understand AI productivity impact with stories
 ---
 
 <objective>
-CTX 3.5 Metrics Dashboard - Comprehensive productivity analytics for understanding AI development impact.
+CTX 4.0 Metrics Dashboard - Comprehensive productivity analytics for understanding AI development impact.
 </objective>
 
 <usage>

package/commands/milestone.md

@@ -4,7 +4,7 @@ description: Milestone workflow - list, audit, complete, and start new milestone
 ---
 
 <objective>
-CTX 3.5 Milestone Workflow - Full release management with audit, archive, and git tagging.
+CTX 4.0 Milestone Workflow - Full release management with audit, archive, and git tagging.
 </objective>
 
 <usage>