ctx-cc 4.0.0 → 4.1.1

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
 
@@ -115,6 +115,7 @@ Or use commands directly:
 | `/ctx plan [goal]` | Force research + planning |
 | `/ctx verify` | Force three-level verification |
 | `/ctx quick "task"` | Quick task bypass |
+| `/ctx cross-review [range] [--focus=area]` | On-demand Codex cross-model review (any project) |
 
 ### Debug
 | Command | Purpose |
@@ -269,7 +270,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 +355,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>

package/commands/monitor.md

@@ -4,7 +4,7 @@ description: Self-healing deployments - connect to error tracking (Sentry/LogRoc
 ---
 
 <objective>
-CTX 3.5 Self-Healing Deployments - Monitor production errors and automatically create fix stories or even auto-fix with PR creation.
+CTX 4.0 Self-Healing Deployments - Monitor production errors and automatically create fix stories or even auto-fix with PR creation.
 </objective>
 
 <usage>

package/commands/voice.md

@@ -4,7 +4,7 @@ description: Voice control for CTX - speak your requirements and commands using
 ---
 
 <objective>
-CTX 3.5 Voice Control - Speak your requirements instead of typing. Natural language processing converts speech to CTX commands and story descriptions.
+CTX 4.0 Voice Control - Speak your requirements instead of typing. Natural language processing converts speech to CTX commands and story descriptions.
 </objective>
 
 <usage>

package/hooks/pre-tool-use.js

@@ -63,7 +63,8 @@ if (agentName && agentName.startsWith('ctx-')) {
     if (fs.existsSync(manifestPath)) {
       const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
       for (const [category, cfg] of Object.entries(manifest)) {
-        if (cfg.agents.includes(agentName + '.md') && cfg.denied.includes(toolName)) {
+        if (category.startsWith('_')) continue; // skip metadata keys like _version
+        if (cfg?.agents?.includes(agentName + '.md') && cfg.denied.includes(toolName)) {
           process.stderr.write(`CTX: Tool "${toolName}" blocked for ${category} agent "${agentName}".\n`);
           fs.appendFileSync(
             path.join(ctxDir, 'violations.log'),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ctx-cc",
-  "version": "4.0.0",
-  "description": "CTX 4.0 — Intelligent workflow orchestration for Claude Code. 21 subagents, 3 skills, deterministic hooks. Phase-based lifecycle with autonomous execution.",
+  "version": "4.1.1",
+  "description": "CTX 4.0 — Intelligent workflow orchestration for Claude Code. 26 subagents, 7 skills, deterministic hooks. Phase-based lifecycle with autonomous execution.",
   "keywords": [
     "claude",
     "claude-code",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ctx",
   "version": "4.0.0",
-  "description": "CTX — Intelligent workflow orchestration for Claude Code. 21 specialized agents, phase-based lifecycle, two-stage review gate, autonomous execution.",
+  "description": "CTX — Intelligent workflow orchestration for Claude Code. Specialized agents, phase-based lifecycle, three-stage review gate with OpenAI Codex cross-model review, autonomous execution.",
   "author": "jufjuf",
   "license": "MIT",
   "homepage": "https://github.com/jufjuf/CTX",
@@ -38,6 +38,7 @@
   },
   "settings": {
     "reviewGate": true,
+    "codexReview": true,
     "tddMode": "off",
     "maxReviewCycles": 3,
     "maxAutoIterations": 5

package/skills/ctx-review-gate/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: ctx-review-gate
 description: |
-  WHEN: Code has been implemented and needs quality verification before marking a story complete. Runs two-stage review: spec compliance then code quality.
+  WHEN: Code has been implemented and needs quality verification before marking a story complete. Runs three-stage review: spec compliance, code quality, and optional cross-model adversarial review via OpenAI Codex.
   WHEN NOT: During planning, research, or when review gate is disabled in config.
 ---
 
-# CTX Two-Stage Review Gate
+# CTX Three-Stage Review Gate
 
 Automated quality gate that runs after execution and before verification.
 
-## Two Stages
+## Three Stages
 
 ### Stage 1: Spec Compliance (ctx-reviewer)
 Checks whether the code satisfies the story's acceptance criteria.
@@ -23,18 +23,39 @@ Agent({
 })
 ```
 
-### Stage 2: Code Quality (ctx-auditor)
-Checks security, performance, and code quality. **Only runs if Stage 1 passes.**
+### Stage 2: Code Quality (ctx-reviewer)
+Reuses ctx-reviewer with a quality-focused prompt: security, performance, error handling, style. **Only runs if Stage 1 passes.**
+
+(Note: earlier versions of this skill called `ctx-auditor` here. That was a miscast — `ctx-auditor` is an audit-trail/compliance agent, not a code-quality reviewer. `ctx-reviewer` already covers type checks, imports, security scans, and best-practice enforcement, so it handles both stages with different framings.)
 
 Spawn:
 ```
 Agent({
-  subagent_type: "ctx-auditor",
+  subagent_type: "ctx-reviewer",
   prompt: "Review recent changes for CODE QUALITY. Check: security vulnerabilities, performance, error handling, style. Output VERDICT: PASS or FAIL with ISSUES list.",
-  description: "Code quality audit"
+  description: "Code quality review"
 })
 ```
 
+### Stage 3: Cross-Model Review (ctx-codex-reviewer) — optional
+Sends the diff to OpenAI Codex via MCP for a second-pair-of-eyes review with different model priors. **Only runs if Stage 2 passes AND `config.codexReview !== false`.**
+
+Short-circuits on docs-only, test-only, or trivial (<20 LOC) diffs. Fails soft — if the Codex MCP is unavailable, rate-limited, or unauthenticated, returns `SKIP` rather than `FAIL` so infrastructure problems never block the gate.
+
+Spawn:
+```
+Agent({
+  subagent_type: "ctx-codex-reviewer",
+  prompt: "Cross-model review story <ID>. Dispatch the current diff to Codex via mcp__codex__codex with sandbox=read-only. Acceptance criteria: <list>. Output VERDICT: PASS, FAIL, or SKIP.",
+  description: "Codex adversarial review"
+})
+```
+
+Prerequisites (user-side, not automated by CTX):
+- Codex CLI installed (`npm i -g @openai/codex`)
+- Signed in via ChatGPT subscription (`codex login` — no `--api-key` flag)
+- MCP registered (`claude mcp add codex -- codex mcp-server`)
+
 ## Flow
 
 ```
@@ -51,6 +72,12 @@ Stage 2: ctx-auditor (code quality)
     ├── FAIL → Feed issues back to executor, increment cycle
     │
     ▼ PASS
+Stage 3: ctx-codex-reviewer (cross-model, if enabled)
+    │
+    ├── FAIL → Feed issues back to executor, increment cycle
+    ├── SKIP → Treat as pass (infra problem, not code problem)
+    │
+    ▼ PASS
 Mark story for verification
 ```
 
@@ -85,27 +112,36 @@ Update `.ctx/STATE.json`:
   "reviewGate": {
     "cycle": 2,
     "history": [
-      { "cycle": 1, "timestamp": "ISO", "stage1": { "passed": true }, "stage2": { "passed": false, "issues": "..." }, "result": "fail" },
-      { "cycle": 2, "timestamp": "ISO", "stage1": { "passed": true }, "stage2": { "passed": true }, "result": "pass" }
+      { "cycle": 1, "timestamp": "ISO", "stage1": { "passed": true }, "stage2": { "passed": false, "issues": "..." }, "stage3": null, "result": "fail" },
+      { "cycle": 2, "timestamp": "ISO", "stage1": { "passed": true }, "stage2": { "passed": true }, "stage3": { "passed": true, "threadId": "thr_...", "skipped": false }, "result": "pass" }
     ]
   }
 }
 ```
 
+`stage3` is `null` when Stage 2 fails (not reached) or when `codexReview` is disabled. When Stage 3 runs, record `threadId` so follow-ups reuse the same Codex session.
+
 ## Save Review Artifacts
 
 Write review results to `.ctx/reviews/<story-id>-<timestamp>.json`.
 
 ## Configuration
 
-Review gate can be disabled:
+Review gate can be disabled entirely:
 - Check `.ctx/config.json` for `"reviewGate": false`
 - If disabled, skip directly to verification
 
+Stage 3 (Codex cross-review) can be disabled independently:
+- Check `.ctx/config.json` for `"codexReview": false`
+- Useful when offline, when the ChatGPT rate-limit budget is depleted, or when the change is trivial
+- Stages 1 and 2 continue to run normally
+
 ## Rules
 
-- ALWAYS run Stage 1 before Stage 2
-- NEVER run Stage 2 if Stage 1 fails (fail-fast)
+- ALWAYS run Stage 1 before Stage 2, Stage 2 before Stage 3 (fail-fast ordering)
+- NEVER run Stage 2 if Stage 1 fails
+- NEVER run Stage 3 if Stage 2 fails, or if `codexReview === false`
+- Stage 3 SKIP (infrastructure failure) is NOT a gate failure — treat as pass
 - ALWAYS feed review issues back to executor as context on retry
 - Max 3 cycles — then escalate to human
-- Record every cycle in state
+- Record every cycle in state, including `stage3: null` when not reached

package/src/capabilities.js

@@ -1,9 +1,26 @@
 import fs from 'fs';
 import path from 'path';
 
+/**
+ * Schema version for the on-disk capability manifest.
+ * Bump when adding categories, renaming fields, or changing policy semantics
+ * so stale project manifests can be detected and regenerated.
+ */
+export const MANIFEST_VERSION = 1;
+
 /**
  * Default capability manifests per agent category.
- * Defines which tools each agent type is allowed to use.
+ * Defines which tools each ctx-* agent category is allowed to use.
+ *
+ * The runtime enforcement point is `hooks/pre-tool-use.js`, which reads
+ * `.ctx/capability-manifest.json` (written at project init from this table)
+ * and blocks tool calls whose name appears in the agent's `denied` list.
+ *
+ * `allowed` is the declared whitelist and is used for documentation and tests;
+ * the hook itself is denylist-driven so unknown tools default to permissive.
+ *
+ * Iterators over a loaded manifest MUST skip keys starting with `_`
+ * (reserved for metadata like `_version`).
  */
 const DEFAULT_CAPABILITIES = {
   // Planning agents — read-only + write plans
@@ -22,14 +39,22 @@ const DEFAULT_CAPABILITIES = {
     reason: 'Execution agents should not spawn other agents.',
   },
 
-  // Review agents — read + run tests, no modifications
+  // Review agents — read + run tests + Codex cross-review, no modifications
   review: {
-    agents: ['ctx-reviewer.md', 'ctx-auditor.md', 'ctx-verifier.md'],
-    allowed: ['Read', 'Glob', 'Grep', 'Bash'],
+    agents: ['ctx-reviewer.md', 'ctx-verifier.md', 'ctx-codex-reviewer.md', 'ctx-ml-reviewer.md'],
+    allowed: ['Read', 'Glob', 'Grep', 'Bash', 'mcp__codex__codex'],
     denied: ['Write', 'Edit', 'NotebookEdit'],
     reason: 'Review agents should not modify code.',
   },
 
+  // Audit agents — write audit trails, but never modify source
+  audit: {
+    agents: ['ctx-auditor.md'],
+    allowed: ['Read', 'Write', 'Bash', 'Glob', 'Grep'],
+    denied: ['Edit', 'Agent', 'NotebookEdit'],
+    reason: 'Audit agents record trails but should not modify source or spawn agents.',
+  },
+
   // Mapper agents — read-only analysis
   mapping: {
     agents: ['ctx-mapper.md', 'ctx-arch-mapper.md', 'ctx-tech-mapper.md', 'ctx-quality-mapper.md', 'ctx-concerns-mapper.md'],
@@ -69,25 +94,23 @@ const DEFAULT_CAPABILITIES = {
     denied: ['Edit'],
     reason: 'QA agents test but should not fix code.',
   },
-};
 
-/**
- * Load capability manifest from file, or return defaults.
- */
-export function loadCapabilityManifest(ctxDir) {
-  const manifestPath = path.join(ctxDir, 'capability-manifest.json');
-  try {
-    return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-  } catch {
-    return DEFAULT_CAPABILITIES;
-  }
-}
+  // ML agents — implement and analyze ML pipelines
+  ml: {
+    agents: ['ctx-ml-scientist.md', 'ctx-ml-engineer.md', 'ctx-ml-analyst.md'],
+    allowed: ['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep'],
+    denied: ['Agent', 'NotebookEdit'],
+    reason: 'ML agents implement and analyze pipelines but should not orchestrate.',
+  },
+};
 
 /**
  * Find the category for a given agent file.
+ * Skips metadata keys (prefix `_`) so a versioned on-disk manifest still works.
  */
 export function findAgentCategory(agentFile, manifest = DEFAULT_CAPABILITIES) {
   for (const [category, config] of Object.entries(manifest)) {
+    if (category.startsWith('_')) continue;
     if (config.agents.includes(agentFile)) {
       return { category, ...config };
     }
@@ -97,12 +120,14 @@ export function findAgentCategory(agentFile, manifest = DEFAULT_CAPABILITIES) {
 
 /**
  * Check if a tool is allowed for an agent.
+ * Denylist-driven (matches the runtime hook in hooks/pre-tool-use.js).
+ * Unknown agents are permissive by default.
+ *
  * Returns { allowed: boolean, reason: string|null }.
  */
 export function checkToolAllowed(agentFile, toolName, manifest = DEFAULT_CAPABILITIES) {
   const category = findAgentCategory(agentFile, manifest);
   if (!category) {
-    // Unknown agent — allow everything (permissive for custom agents)
     return { allowed: true, reason: null };
   }
 
@@ -117,37 +142,66 @@ export function checkToolAllowed(agentFile, toolName, manifest = DEFAULT_CAPABIL
 }
 
 /**
- * Generate a PreToolUse hook command that enforces capability restrictions.
- * Returns the hook command string.
+ * Save the capability manifest to `<ctxDir>/capability-manifest.json`.
+ * Called from the install flow to seed the template and from the project
+ * init command to materialize the manifest that the PreToolUse hook reads.
  */
-export function generateCapabilityHookCommand(ctxDir) {
-  return `node -e "
-    const fs=require('fs'),p=require('path');
-    const tool=process.env.TOOL_NAME||'';
-    const agent=process.env.CURRENT_AGENT||'';
-    if(!agent||!tool)process.exit(0);
-    const mPath=p.join('${ctxDir}','capability-manifest.json');
-    let manifest;
-    try{manifest=JSON.parse(fs.readFileSync(mPath,'utf-8'));}catch{process.exit(0);}
-    for(const[cat,cfg]of Object.entries(manifest)){
-      if(cfg.agents.includes(agent)&&cfg.denied.includes(tool)){
-        console.error('CTX: Tool '+tool+' blocked for '+cat+' agent '+agent);
-        const logDir=p.join('${ctxDir}','violations.log');
-        fs.appendFileSync(logDir,new Date().toISOString()+' | '+agent+' | '+tool+' | BLOCKED\\n');
-        process.exit(2);
-      }
-    }
-  "`.replace(/\n\s*/g, ' ').trim();
+export function saveCapabilityManifest(ctxDir) {
+  const manifestPath = path.join(ctxDir, 'capability-manifest.json');
+  if (!fs.existsSync(ctxDir)) fs.mkdirSync(ctxDir, { recursive: true });
+  const payload = { _version: MANIFEST_VERSION, ...DEFAULT_CAPABILITIES };
+  fs.writeFileSync(manifestPath, JSON.stringify(payload, null, 2) + '\n');
+  return manifestPath;
 }
 
 /**
- * Save default capability manifest to .ctx/ for customization.
+ * Read the `_version` field from an on-disk manifest.
+ * Returns 0 for pre-versioned manifests, null if file missing/invalid.
+ * Callers compare against MANIFEST_VERSION to decide whether to regenerate.
  */
-export function saveCapabilityManifest(ctxDir) {
+export function readManifestVersion(ctxDir) {
   const manifestPath = path.join(ctxDir, 'capability-manifest.json');
-  if (!fs.existsSync(ctxDir)) fs.mkdirSync(ctxDir, { recursive: true });
-  fs.writeFileSync(manifestPath, JSON.stringify(DEFAULT_CAPABILITIES, null, 2) + '\n');
-  return manifestPath;
+  try {
+    const data = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    return typeof data._version === 'number' ? data._version : 0;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Migrate an existing project's capability manifest to the current version.
+ * - Missing:  writes a fresh manifest, returns { action: 'created' }.
+ * - Current:  no-op, returns { action: 'current' }.
+ * - Stale:    backs up old manifest as `capability-manifest.v<N>.backup.json`
+ *             and regenerates, returns { action: 'migrated', backup }.
+ *
+ * Used by the `ctx-cc update-manifest` CLI subcommand so projects that
+ * predate MANIFEST_VERSION can pick up policy changes without re-initting.
+ */
+export function updateProjectManifest(ctxDir) {
+  const manifestPath = path.join(ctxDir, 'capability-manifest.json');
+  const current = readManifestVersion(ctxDir);
+
+  if (current === null) {
+    saveCapabilityManifest(ctxDir);
+    return { action: 'created', from: null, to: MANIFEST_VERSION, path: manifestPath };
+  }
+
+  if (current === MANIFEST_VERSION) {
+    return { action: 'current', from: current, to: current, path: manifestPath };
+  }
+
+  const backupPath = path.join(ctxDir, `capability-manifest.v${current}.backup.json`);
+  fs.copyFileSync(manifestPath, backupPath);
+  saveCapabilityManifest(ctxDir);
+  return {
+    action: 'migrated',
+    from: current,
+    to: MANIFEST_VERSION,
+    path: manifestPath,
+    backup: backupPath,
+  };
 }
 
 /**
@@ -156,6 +210,7 @@ export function saveCapabilityManifest(ctxDir) {
 export function formatCapabilities(manifest = DEFAULT_CAPABILITIES) {
   const lines = [];
   for (const [category, config] of Object.entries(manifest)) {
+    if (category.startsWith('_')) continue;
     lines.push(`  ${category}:`);
     lines.push(`    Agents:  ${config.agents.map(a => a.replace('ctx-', '').replace('.md', '')).join(', ')}`);
     lines.push(`    Allowed: ${config.allowed.join(', ')}`);

package/src/install.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { saveCapabilityManifest } from './capabilities.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -28,7 +29,7 @@ function printBanner() {
 `));
   console.log(`  ${bold('CTX 4.0')} ${dim(`v${VERSION}`)}`);
   console.log('  Intelligent workflow orchestration for Claude Code.');
-  console.log('  21 agents. Skills. Hooks. Phase-based lifecycle.\n');
+  console.log('  26 agents. 7 skills. Hooks. Phase-based lifecycle.\n');
 }
 
 function copyDir(src, dest) {
@@ -170,6 +171,12 @@ export async function install(options) {
     console.log(green(`  ✓`) + ` Installed templates (${count} files)`);
   }
 
+  // Generate capability-manifest.json template from DEFAULT_CAPABILITIES.
+  // /ctx:init copies this into each project's .ctx/ so the PreToolUse hook
+  // (hooks/pre-tool-use.js) has a manifest to enforce against.
+  saveCapabilityManifest(destTemplates);
+  console.log(green(`  ✓`) + ` Generated capability-manifest.json template`);
+
   // Write VERSION file
   fs.writeFileSync(path.join(ctxDir, 'VERSION'), VERSION);
   console.log(green(`  ✓`) + ` Wrote VERSION (${VERSION})`);
@@ -178,8 +185,8 @@ export async function install(options) {
   console.log(`\n  ${green('Done!')} Launch Claude Code and run ${cyan('/ctx:help')}.`);
   console.log(`
   ${bold('What was installed:')}
-    ${dim('Agents:')}   ~/.claude/agents/ctx-*.md     (21 subagents)
-    ${dim('Skills:')}   ~/.claude/skills/ctx-*/        (3 skills)
+    ${dim('Agents:')}   ~/.claude/agents/ctx-*.md     (26 subagents)
+    ${dim('Skills:')}   ~/.claude/skills/ctx-*/        (7 skills)
     ${dim('Commands:')} ~/.claude/commands/ctx/         (slash commands)
     ${dim('Hooks:')}    ~/.claude/hooks/ctx-*.js        (3 hook scripts)
     ${dim('Config:')}   ~/.claude/settings.json         (hooks registered)