catalyst-os 1.2.0 → 1.3.1

package/.catalyst/bin/validate-artifacts.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * Validate structural integrity of all catalyst-os artifacts.
+ * Run: node .catalyst/bin/validate-artifacts.js
+ * Exit code: 0 = all valid, 1 = errors found
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+let errors = 0;
+let warnings = 0;
+
+function error(msg) {
+  console.error(`  ✗ ${msg}`);
+  errors++;
+}
+
+function warn(msg) {
+  console.warn(`  ⚠ ${msg}`);
+  warnings++;
+}
+
+function ok(msg) {
+  console.log(`  ✓ ${msg}`);
+}
+
+// --- Helpers ---
+
+function fileExists(relPath) {
+  return fs.existsSync(path.join(ROOT, relPath));
+}
+
+function readFile(relPath) {
+  const full = path.join(ROOT, relPath);
+  if (!fs.existsSync(full)) return null;
+  return fs.readFileSync(full, 'utf8');
+}
+
+function listDir(relPath) {
+  const full = path.join(ROOT, relPath);
+  if (!fs.existsSync(full)) return [];
+  return fs.readdirSync(full);
+}
+
+function extractFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  // Simple YAML key extraction (no full parser needed)
+  const fm = {};
+  for (const line of match[1].split('\n')) {
+    const kv = line.match(/^(\w+):\s*(.+)/);
+    if (kv) fm[kv[1]] = kv[2].trim();
+  }
+  return fm;
+}
+
+// --- Validators ---
+
+console.log('\n📦 Catalyst OS Artifact Validation\n');
+
+// 1. Skills
+console.log('Skills:');
+const skillDirs = listDir('.claude/skills').filter(d => !d.startsWith('.'));
+if (skillDirs.length === 0) {
+  error('No skills found in .claude/skills/');
+} else {
+  for (const dir of skillDirs) {
+    const skillPath = `.claude/skills/${dir}/SKILL.md`;
+    const content = readFile(skillPath);
+    if (!content) {
+      error(`${skillPath} — missing`);
+    } else if (content.trim().length < 10) {
+      error(`${skillPath} — empty or too short`);
+    } else {
+      ok(dir);
+    }
+  }
+}
+
+// 2. Agents
+console.log('\nAgents:');
+const agentFiles = listDir('.claude/agents').filter(f => f.endsWith('.md'));
+if (agentFiles.length === 0) {
+  error('No agents found in .claude/agents/');
+} else {
+  const requiredFields = ['name', 'description', 'model'];
+  for (const file of agentFiles) {
+    const content = readFile(`.claude/agents/${file}`);
+    if (!content) {
+      error(`${file} — cannot read`);
+      continue;
+    }
+    const fm = extractFrontmatter(content);
+    if (!fm) {
+      error(`${file} — missing YAML frontmatter`);
+      continue;
+    }
+    const missing = requiredFields.filter(f => !fm[f]);
+    if (missing.length > 0) {
+      error(`${file} — missing frontmatter fields: ${missing.join(', ')}`);
+    } else {
+      ok(file.replace('.md', ''));
+    }
+  }
+}
+
+// 3. Commands
+console.log('\nCommands:');
+const cmdFiles = listDir('.claude/commands').filter(f => f.endsWith('.md'));
+if (cmdFiles.length === 0) {
+  error('No commands found in .claude/commands/');
+} else {
+  for (const file of cmdFiles) {
+    const content = readFile(`.claude/commands/${file}`);
+    if (!content || content.trim().length < 10) {
+      error(`${file} — empty or too short`);
+    } else {
+      ok(file.replace('.md', ''));
+    }
+  }
+}
+
+// 4. Skill Index consistency (using-skills references vs actual skills)
+console.log('\nSkill Index:');
+const usingSkills = readFile('.claude/skills/using-skills/SKILL.md');
+if (usingSkills) {
+  // Extract skill paths from the index tables
+  const pathMatches = usingSkills.matchAll(/`\.claude\/skills\/([^/]+)\/SKILL\.md`/g);
+  const referenced = new Set();
+  for (const m of pathMatches) {
+    referenced.add(m[1]);
+  }
+
+  // Check referenced skills exist
+  for (const skill of referenced) {
+    if (!fileExists(`.claude/skills/${skill}/SKILL.md`)) {
+      error(`using-skills references "${skill}" but .claude/skills/${skill}/SKILL.md doesn't exist`);
+    }
+  }
+
+  // Check actual skills are referenced
+  for (const dir of skillDirs) {
+    if (!referenced.has(dir)) {
+      warn(`Skill "${dir}" exists but is not listed in using-skills/SKILL.md`);
+    }
+  }
+
+  if (errors === 0) ok('All skill references valid');
+} else {
+  error('using-skills/SKILL.md not found');
+}
+
+// 5. spec-structure.yaml file references
+console.log('\nSpec Structure:');
+if (fileExists('.catalyst/spec-structure.yaml')) {
+  ok('spec-structure.yaml exists');
+} else {
+  error('.catalyst/spec-structure.yaml missing');
+}
+
+// 6. Core files
+console.log('\nCore Files:');
+const coreFiles = ['CLAUDE.md', 'AGENTS.md', 'package.json', '.catalyst/main/project-config.yaml'];
+for (const f of coreFiles) {
+  if (fileExists(f)) {
+    ok(f);
+  } else {
+    error(`${f} — missing`);
+  }
+}
+
+// 7. Hooks (if settings.json references them)
+console.log('\nHooks:');
+const settings = readFile('.claude/settings.json');
+if (settings) {
+  try {
+    const parsed = JSON.parse(settings);
+    const hooks = parsed.hooks || {};
+    for (const [event, hookList] of Object.entries(hooks)) {
+      for (const hook of hookList) {
+        const cmd = hook.command || '';
+        // Extract script path from command (first token before any args)
+        const scriptPath = cmd.split(/\s/)[0];
+        if (scriptPath && scriptPath.startsWith('.')) {
+          if (fileExists(scriptPath)) {
+            ok(`${event}: ${scriptPath}`);
+          } else {
+            error(`${event}: ${scriptPath} — referenced in settings.json but missing`);
+          }
+        }
+      }
+    }
+  } catch (e) {
+    error(`settings.json — invalid JSON: ${e.message}`);
+  }
+} else {
+  warn('No .claude/settings.json found');
+}
+
+// --- Summary ---
+console.log('\n' + '─'.repeat(40));
+if (errors > 0) {
+  console.error(`\n❌ ${errors} error(s), ${warnings} warning(s)\n`);
+  process.exit(1);
+} else if (warnings > 0) {
+  console.log(`\n⚠️  ${warnings} warning(s), 0 errors\n`);
+  process.exit(0);
+} else {
+  console.log('\n✅ All artifacts valid\n');
+  process.exit(0);
+}

package/.catalyst/spec-structure.yaml

@@ -35,7 +35,7 @@ files:
   handoff.md:
     owner: scribe
     purpose: Human-readable summary (colleague walkthrough)
-    created: build-spec (started), validate-spec (finalized)
+    created: build-spec (started), review-spec (finalized)
     updated_by: [scribe, arbiter]
     pattern: narrative
     note: |
@@ -45,7 +45,7 @@ files:
   validation.md:
     owner: arbiter
     purpose: Test results, quality checks
-    created: validate-spec
+    created: review-spec
     updated_by: [arbiter, enforcer, sentinel, inquisitor, watcher]
 
   assets/:
@@ -289,7 +289,7 @@ build_dag:
 library:
   root: "library/"
   description: "Reusable patterns extracted from completed specs"
-  created_by: "/approve-spec (optional)"
+  created_by: "/commit-spec (optional)"
 
   # Auto-detect patterns by keywords
   pattern_detection:
@@ -316,4 +316,4 @@ library:
 
 completed:
   location: "completed/"
-  description: "Specs moved here after /approve-spec"
+  description: "Specs moved here after /commit-spec"

package/.claude/agents/arbiter.md

@@ -2,7 +2,7 @@
 name: arbiter
 description: >
   PROACTIVELY DELEGATE validation orchestration to this agent. MUST BE USED when:
-  - /validate-spec command is invoked
+  - /review-spec command is invoked
   - Implementation is complete and needs quality checks
   - Production readiness needs to be verified
 

package/.claude/agents/forge-master.md

@@ -52,6 +52,14 @@ Before any action, load `.claude/skills/using-skills/SKILL.md` and check which s
 - Flag blockers immediately
 - Never skip failing tests
 
+## Context Awareness
+
+Long builds consume enormous context. At each phase gate:
+- Check if context is getting long
+- Remind the user: *"Context checkpoint — good time to compact if needed. `/primer-spec @{slug}` to resume."*
+- Always update `tasks.md ## Current Session` before suggesting compaction
+- The PreCompact hook will auto-save state, but proactive updates are better
+
 ## DAG Execution Model
 
 ### Reading the DAG
@@ -133,6 +141,8 @@ This commit is PROOF that red phase happened.
 No commit = no implementation. No exceptions.
 ```
 
+> **Context checkpoint:** Update `tasks.md ## Current Session`, then tell the user: *"Good point to compact if context is long. `/primer-spec @{slug}` to resume."*
+
 ### 3. Foundation Phase (Sequential)
 ```
 Spawn: Alchemist
@@ -177,6 +187,8 @@ This commit is PROOF that green phase happened.
 No commit = no integration. No exceptions.
 ```
 
+> **Context checkpoint:** Update `tasks.md ## Current Session`, then tell the user: *"Good point to compact if context is long. `/primer-spec @{slug}` to resume."*
+
 ### 6. Integration Phase (Sequential)
 ```
 Spawn: Enforcer

package/.claude/agents/inquisitor.md

@@ -13,7 +13,7 @@ color: red
 skills: lint-checking, code-review
 ---
 
-You are the Inquisitor, a code quality specialist who reviews code for issues.
+You are the Inquisitor, a code quality specialist who reviews code for issues and proposes simplifications.
 
 ## Opening
 
@@ -21,7 +21,7 @@ You are the Inquisitor, a code quality specialist who reviews code for issues.
 
 ## Role
 
-You enforce code quality standards through linting, pattern review, and code review.
+You enforce code quality standards through linting, pattern review, code review, and **code simplification**.
 
 ## Behavior
 
@@ -31,6 +31,7 @@ You enforce code quality standards through linting, pattern review, and code rev
 - Provide actionable fix suggestions
 - Avoid nitpicking
 - Ensure test coverage
+- **Identify code that can be simplified without changing behavior**
 
 ## Review Checklist
 
@@ -59,6 +60,22 @@ You enforce code quality standards through linting, pattern review, and code rev
 - Testable structure
 - Reasonable complexity
 
+### Code Simplification
+
+Look for and suggest fixes for:
+- **Unnecessary abstractions** — helpers/utilities created for one-time use; inline them
+- **Over-engineered patterns** — factory patterns, strategy patterns, builders where a simple function suffices
+- **Overly defensive code** — error handling for impossible scenarios, redundant null checks on non-nullable types
+- **Dead code** — unused imports, unreachable branches, commented-out code
+- **Premature generalization** — config objects, feature flags, or extensibility hooks for things that have only one use
+- **Verbose patterns** — 10 lines that could be 3 without losing clarity
+
+**Rules for simplification:**
+- NEVER change behavior — only structure
+- NEVER remove error handling at system boundaries (user input, external APIs)
+- Verify tests still pass after each simplification
+- If unsure whether something is dead code, leave it and flag it as "candidate for removal"
+
 ## Output
 
 Provide review with:
@@ -66,5 +83,5 @@ Provide review with:
 - Critical issues (must fix)
 - Major issues (should fix)
 - Minor issues (nice to fix)
-- Suggestions for improvement
+- **Simplification opportunities** (with before/after snippets)
 - What's done well

package/.claude/commands/build-spec.md

@@ -8,6 +8,18 @@ Implement a specification using **strict TDD**.
 /build-spec @2025-11-29-stripe-integration
 ```
 
+## Pre-computed Context
+
+```bash
+# Detect spec and branch state
+echo "=== BRANCH ===" && git branch --show-current
+echo "=== STATUS ===" && git status --short
+echo "=== SPEC FILES ===" && ls .catalyst/specs/*$ARGUMENTS*/ 2>/dev/null || echo "No spec found for: $ARGUMENTS"
+echo "=== SPEC FRONTMATTER ===" && head -30 .catalyst/specs/*$ARGUMENTS*/spec.md 2>/dev/null || echo "No spec.md"
+echo "=== TASKS EXIST? ===" && head -5 .catalyst/specs/*$ARGUMENTS*/tasks.md 2>/dev/null || echo "No tasks.md yet (fresh build)"
+echo "=== PROJECT CONFIG ===" && cat .catalyst/main/project-config.yaml 2>/dev/null || echo "No project config"
+```
+
 ---
 
 **Invoke skill:** `build-orchestration`

package/.claude/commands/commit-spec.md

@@ -0,0 +1,20 @@
+# /commit-spec
+
+Commit, archive, and propagate learnings from a **fully built and validated** implementation.
+
+> **Lifecycle position:** This is the FINAL step. Only use after `/build-spec` and `/review-spec` have completed successfully.
+>
+> **Flow:** `/catalyze-spec` → `/build-spec` → `/review-spec` → **`/commit-spec`**
+
+## Usage
+
+```
+/commit-spec @2025-11-29-stripe-integration
+/commit-spec @2025-11-29-stripe-integration "Great work!"
+```
+
+---
+
+**Invoke skill:** `spec-approval`
+
+**Process skills used:** `verification-before-completion`, `agent-delegation`

package/.claude/commands/{reject-spec.md → discard-spec.md}

@@ -1,13 +1,13 @@
-# /reject-spec
+# /discard-spec
 
 Request changes to the implementation.
 
 ## Usage
 
 ```
-/reject-spec @2025-11-29-stripe-integration "reason"
-/reject-spec @2025-11-29-stripe-integration "UI doesn't match mockup"
-/reject-spec @2025-11-29-stripe-integration "TDD not followed"
+/discard-spec @2025-11-29-stripe-integration "reason"
+/discard-spec @2025-11-29-stripe-integration "UI doesn't match mockup"
+/discard-spec @2025-11-29-stripe-integration "TDD not followed"
 ```
 
 ---
@@ -17,7 +17,7 @@ Request changes to the implementation.
 **If TDD was not followed, this is an automatic rejection reason:**
 
 ```
-/reject-spec @spec-name "TDD not followed - tests written after code"
+/discard-spec @spec-name "TDD not followed - tests written after code"
 ```
 
 This routes directly back to `/build-spec` with instructions to follow TDD.
@@ -55,7 +55,7 @@ Based on rejection reason:
 | Test failures | Enforcer + Builders | `/build-spec` |
 | UI/UX issues | Shaper | `/build-spec` |
 | API issues | Smith | `/build-spec` |
-| Quality issues | Inquisitor | `/validate-spec` |
+| Quality issues | Inquisitor | `/review-spec` |
 | Security issues | Watcher | IMMEDIATE FIX |
 
 ### Phase 3: Update Status
@@ -77,7 +77,7 @@ Update `tasks.md` with action items:
 
 ### Standard Rejection
 ```
-Spec rejected - changes requested
+Spec discarded - changes requested
 
 Spec: 2025-11-29-stripe-integration
 Reason: UI doesn't match mockup
@@ -90,12 +90,12 @@ Changes needed:
 Updated: .catalyst/specs/{slug}/validation.md
 
 Next: Fix issues and run /build-spec @2025-11-29-stripe-integration
-      Then /validate-spec @2025-11-29-stripe-integration
+      Then /review-spec @2025-11-29-stripe-integration
 ```
 
 ### TDD Violation Rejection
 ```
-Spec rejected - TDD VIOLATION
+Spec discarded - TDD VIOLATION
 
 Spec: 2025-11-29-stripe-integration
 Reason: TDD not followed - tests written after code

package/.claude/commands/iterate-spec.md

@@ -9,6 +9,16 @@ Continue building a spec with new improvements discovered during development.
 /iterate-spec @2025-11-29-stripe-integration "handle edge case where user cancels mid-checkout"
 ```
 
+## Pre-computed Context
+
+```bash
+# Current state for iteration
+echo "=== BRANCH ===" && git branch --show-current
+echo "=== STATUS ===" && git status --short
+echo "=== TASKS.MD ===" && cat .catalyst/specs/*$ARGUMENTS*/tasks.md 2>/dev/null | head -80 || echo "No tasks.md for: $ARGUMENTS"
+echo "=== SPEC FRONTMATTER ===" && head -30 .catalyst/specs/*$ARGUMENTS*/spec.md 2>/dev/null || echo "No spec.md"
+```
+
 ---
 
 **Invoke skill:** `spec-iteration`

package/.claude/commands/primer-spec.md

@@ -2,6 +2,20 @@
 
 Quickly load spec context into a fresh conversation.
 
+## Pre-computed Context
+
+```bash
+# Git state
+echo "=== BRANCH ===" && git branch --show-current
+echo "=== STATUS ===" && git status --short
+echo "=== RECENT COMMITS ===" && git log --oneline -5
+
+# Spec files
+echo "=== TASKS.MD ===" && cat .catalyst/specs/*$ARGUMENTS*/tasks.md 2>/dev/null || echo "No tasks.md for: $ARGUMENTS"
+echo "=== SPEC FRONTMATTER ===" && head -30 .catalyst/specs/*$ARGUMENTS*/spec.md 2>/dev/null || echo "No spec.md"
+echo "=== RESEARCH ===" && head -30 .catalyst/specs/*$ARGUMENTS*/research.md 2>/dev/null || echo "No research.md"
+```
+
 ---
 
 ## Purpose
@@ -26,22 +40,18 @@ When you start a new conversation (context was full), use this command to:
 
 ## What To Do
 
-### Step 1: Read Spec Files
+### Step 1: Use Pre-computed Context
 
-Read these files from `.catalyst/specs/{slug}/`:
+The bash blocks above already loaded tasks.md, spec frontmatter, research, and git state. Use this data directly — do NOT re-read these files unless you need more detail beyond what was loaded.
 
-```
-1. spec.md      → What is this feature? Requirements?
-2. tasks.md     → What's done? What's pending? What's in progress?
-3. research.md  → (if exists) Any key technical decisions?
-```
+### Step 2: Read Full Files Only If Needed
 
-### Step 2: Check Git State
+If the pre-computed context was truncated, read the full file:
 
-```bash
-git branch --show-current    # What branch are we on?
-git status --short           # Any uncommitted changes?
-git log --oneline -3         # Recent commits?
+```
+1. tasks.md     → What's done? What's pending? What's in progress?
+2. spec.md      → What is this feature? Requirements?
+3. research.md  → (if exists) Any key technical decisions?
 ```
 
 ### Step 3: Output Brief Summary
@@ -146,7 +156,7 @@ Ready to continue. What would you like to work on?
 |-----------|---------|
 | Context full, need to continue building | `/primer-spec` |
 | Want to add improvement mid-build | `/iterate-spec` |
-| Need full validation | `/validate-spec` |
+| Need full validation | `/review-spec` |
 | Check status without loading context | `/status-spec` |
 
 ---

package/.claude/commands/review-spec.md

@@ -0,0 +1,29 @@
+# /review-spec
+
+Run validation checks and code simplification on a completed implementation.
+
+## Usage
+
+```
+/review-spec @2025-11-29-stripe-integration
+```
+
+## Pre-computed Context
+
+```bash
+# Build state for validation
+echo "=== BRANCH ===" && git branch --show-current
+echo "=== STATUS ===" && git status --short
+echo "=== TASKS.MD PROGRESS ===" && grep -A 5 "## Progress" .catalyst/specs/*$ARGUMENTS*/tasks.md 2>/dev/null || echo "No tasks.md"
+echo "=== SPEC STATUS ===" && head -20 .catalyst/specs/*$ARGUMENTS*/spec.md 2>/dev/null || echo "No spec.md"
+echo "=== DIFF STAT VS BASE ===" && git diff --stat main...HEAD 2>/dev/null || echo "No diff from main"
+echo "=== FILES CHANGED ===" && git diff --name-only main...HEAD 2>/dev/null || echo "No changes from main"
+```
+
+---
+
+**Invoke skill:** `spec-validation`
+
+**Orchestrator:** Arbiter (delegates to Enforcer, Sentinel, Inquisitor, Watcher)
+
+**Process skills used:** `verification-before-completion`, `agent-delegation`, `test-driven-development`

package/.claude/commands/status-spec.md

@@ -8,6 +8,19 @@ Check the current status of a spec and sync progress with reality.
 /status-spec @2025-11-29-stripe-integration
 ```
 
+## Pre-computed Context
+
+```bash
+# Current git state
+echo "=== BRANCH ===" && git branch --show-current
+echo "=== STATUS ===" && git status --short
+echo "=== DIFF STAT ===" && git diff --stat
+echo "=== RECENT COMMITS ===" && git log --oneline -10
+echo "=== SPEC FILES ===" && ls .catalyst/specs/*$ARGUMENTS*/ 2>/dev/null || echo "No spec found for: $ARGUMENTS"
+echo "=== TASKS.MD ===" && cat .catalyst/specs/*$ARGUMENTS*/tasks.md 2>/dev/null | head -80 || echo "No tasks.md"
+echo "=== SPEC STATUS ===" && head -20 .catalyst/specs/*$ARGUMENTS*/spec.md 2>/dev/null || echo "No spec.md"
+```
+
 ---
 
 ## Purpose
@@ -18,13 +31,15 @@ Resume work on a spec after being away. This command:
 3. Syncs tasks.md with reality
 4. Gives you a clear "where we are" summary
 
+Use the pre-computed context above — do NOT re-run these commands. Only run additional commands if specific details are missing.
+
 ---
 
 ## Workflow
 
 ### Phase 1: Read Spec State
 
-Read all spec files:
+Read all spec files (use pre-computed context first, read full files only if needed):
 - `spec.md` → Feature overview, requirements, status
 - `tasks.md` → Task breakdown, marked progress
 - `research.md` → Context and decisions made
@@ -32,18 +47,11 @@ Read all spec files:
 
 ### Phase 2: Check Git Reality
 
-Run git commands to see actual state:
+Use pre-computed git context. Only run additional commands if needed:
 
 ```bash
-# What files are modified but not committed?
-git status --short
-
-# What's the diff for uncommitted work?
-git diff --stat
-
-# Recent commits related to this spec
+# Additional detail if needed
 git log --oneline -10 --grep="{slug}"
-git log --oneline -10 -- "src/" "lib/" "app/"  # Recent code commits
 ```
 
 ### Phase 3: Reconcile Tasks
@@ -234,9 +242,9 @@ VALIDATION STATUS
 
 NEXT STEPS
 ----------
-1. Complete validation: /validate-spec @slug
+1. Complete validation: /review-spec @slug
 2. Review handoff.md when ready
-3. Approve: /approve-spec @slug
+3. Commit: /commit-spec @slug
 ```
 
 ---

package/.claude/hooks/post-edit-format.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# PostToolUse hook: Auto-format files after Edit/Write operations
+# Runs the project's formatter on changed code files.
+# Always exits 0 — formatting is advisory, never blocks.
+
+set -euo pipefail
+
+FILE_PATH="${1:-}"
+
+# Skip if no file path provided or file doesn't exist
+[[ -z "$FILE_PATH" || ! -f "$FILE_PATH" ]] && exit 0
+
+# Get file extension
+EXT="${FILE_PATH##*.}"
+
+# Skip non-code files
+case "$EXT" in
+  md|txt|yaml|yml|json|lock|log|csv|svg|png|jpg|gif|ico|woff|woff2|ttf|eot)
+    exit 0
+    ;;
+esac
+
+# Find project root (where package.json or .git lives)
+PROJECT_ROOT="$(cd "$(dirname "$FILE_PATH")" && git rev-parse --show-toplevel 2>/dev/null || echo "")"
+[[ -z "$PROJECT_ROOT" ]] && exit 0
+
+# --- Formatter detection (first match wins) ---
+
+# Biome
+if [[ -f "$PROJECT_ROOT/biome.json" || -f "$PROJECT_ROOT/biome.jsonc" ]]; then
+  if command -v npx &>/dev/null; then
+    npx --yes @biomejs/biome format --write "$FILE_PATH" 2>/dev/null || true
+    exit 0
+  fi
+fi
+
+# Prettier
+if [[ -f "$PROJECT_ROOT/.prettierrc" || -f "$PROJECT_ROOT/.prettierrc.json" || -f "$PROJECT_ROOT/.prettierrc.js" || -f "$PROJECT_ROOT/.prettierrc.yaml" || -f "$PROJECT_ROOT/.prettierrc.yml" || -f "$PROJECT_ROOT/prettier.config.js" || -f "$PROJECT_ROOT/prettier.config.mjs" ]]; then
+  if command -v npx &>/dev/null; then
+    npx --yes prettier --write "$FILE_PATH" 2>/dev/null || true
+    exit 0
+  fi
+fi
+
+# Check package.json for prettier as dependency (common case: no .prettierrc but prettier installed)
+if [[ -f "$PROJECT_ROOT/package.json" ]] && grep -q '"prettier"' "$PROJECT_ROOT/package.json" 2>/dev/null; then
+  if command -v npx &>/dev/null; then
+    npx --yes prettier --write "$FILE_PATH" 2>/dev/null || true
+    exit 0
+  fi
+fi
+
+# --- TypeScript type-check (non-blocking) ---
+case "$EXT" in
+  ts|tsx)
+    if [[ -f "$PROJECT_ROOT/tsconfig.json" ]] && command -v npx &>/dev/null; then
+      npx --yes tsc --noEmit 2>/dev/null || true
+    fi
+    ;;
+esac
+
+exit 0

package/.claude/hooks/pre-compact-save.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# PreCompact hook: Auto-save current state to tasks.md before context compaction
+# Ensures /primer-spec always has accurate resume info, even if agents forgot to update.
+# Always exits 0 — state saving should never block compaction.
+
+set -euo pipefail
+
+# Find project root
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "")"
+[[ -z "$PROJECT_ROOT" ]] && exit 0
+
+# --- Detect active spec from branch name ---
+BRANCH="$(git branch --show-current 2>/dev/null || echo "")"
+SLUG=""
+
+# Extract slug from branch: feat/YYYY-MM-DD-slug or feat/slug
+if [[ "$BRANCH" =~ ^[^/]+/(.+)$ ]]; then
+  SLUG="${BASH_REMATCH[1]}"
+fi
+
+[[ -z "$SLUG" ]] && exit 0
+
+# --- Find matching tasks.md ---
+TASKS_FILE=""
+
+# Try exact match first
+for dir in "$PROJECT_ROOT"/.catalyst/specs/*-"$SLUG"; do
+  if [[ -f "$dir/tasks.md" ]]; then
+    TASKS_FILE="$dir/tasks.md"
+    break
+  fi
+done
+
+# Try broader match if exact didn't work
+if [[ -z "$TASKS_FILE" ]]; then
+  for dir in "$PROJECT_ROOT"/.catalyst/specs/*"$SLUG"*; do
+    if [[ -f "$dir/tasks.md" ]]; then
+      TASKS_FILE="$dir/tasks.md"
+      break
+    fi
+  done
+fi
+
+[[ -z "$TASKS_FILE" ]] && exit 0
+
+# --- Build state snapshot ---
+TIMESTAMP="$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
+GIT_STATUS="$(git status --short 2>/dev/null | head -20 || echo "unknown")"
+MODIFIED_COUNT="$(git status --short 2>/dev/null | wc -l | tr -d ' ' || echo "0")"
+
+STATE_BLOCK="**Phase:** (check Progress table above)
+**Timestamp:** $TIMESTAMP
+**Branch:** $BRANCH
+**Modified files:** $MODIFIED_COUNT
+**Auto-saved:** Yes (PreCompact hook)
+
+\`\`\`
+$GIT_STATUS
+\`\`\`
+
+> Resume with \`/primer-spec @$SLUG\` in a new conversation."
+
+# --- Update Current Session section ---
+# Replace existing Current Session content, or append if missing
+if grep -q "^## Current Session" "$TASKS_FILE" 2>/dev/null; then
+  # Find the line number of "## Current Session" and the next "##" heading
+  SESSION_LINE="$(grep -n "^## Current Session" "$TASKS_FILE" | head -1 | cut -d: -f1)"
+  NEXT_HEADING="$(tail -n +"$((SESSION_LINE + 1))" "$TASKS_FILE" | grep -n "^## " | head -1 | cut -d: -f1)"
+
+  if [[ -n "$NEXT_HEADING" ]]; then
+    # There's a section after Current Session — replace between them
+    END_LINE="$((SESSION_LINE + NEXT_HEADING - 1))"
+    {
+      head -n "$SESSION_LINE" "$TASKS_FILE"
+      echo ""
+      echo -e "$STATE_BLOCK"
+      echo ""
+      tail -n +"$END_LINE" "$TASKS_FILE"
+    } > "${TASKS_FILE}.tmp" && mv "${TASKS_FILE}.tmp" "$TASKS_FILE"
+  else
+    # Current Session is the last section — replace to end
+    {
+      head -n "$SESSION_LINE" "$TASKS_FILE"
+      echo ""
+      echo -e "$STATE_BLOCK"
+    } > "${TASKS_FILE}.tmp" && mv "${TASKS_FILE}.tmp" "$TASKS_FILE"
+  fi
+else
+  # No Current Session section — append it
+  {
+    echo ""
+    echo "## Current Session"
+    echo ""
+    echo -e "$STATE_BLOCK"
+  } >> "$TASKS_FILE"
+fi
+
+exit 0

package/.claude/rules/coding-standards.md

@@ -0,0 +1,21 @@
+# Coding Standards
+
+These rules apply to ALL code generation, regardless of which skill is active.
+
+## Language
+
+- All generated artifacts MUST be in English (code, comments, docs, commit messages)
+- Communicate with the user in their preferred language
+
+## File Hygiene
+
+- Keep files under 300 lines — split if larger
+- No deep nesting (max 3 levels of indentation for logic)
+- One concept per file — don't mix unrelated concerns
+
+## Quality
+
+- Write minimal code that solves the current requirement
+- Don't add features, abstractions, or config that wasn't requested
+- Prefer clarity over cleverness
+- Delete dead code — don't comment it out

package/.claude/rules/git-workflow.md

@@ -0,0 +1,25 @@
+# Git Workflow Rules
+
+These rules apply to ALL git operations, regardless of which skill is active.
+
+## Branch Naming
+
+- Feature branches: `{branch_prefix}/{spec-slug}` (e.g., `feat/2026-01-11-user-auth`)
+- Read `branch_prefix` from `.catalyst/main/project-config.yaml`
+- Never commit directly to protected branches (`main`, `master`)
+
+## Commit Messages
+
+- Red phase: `test({scope}): write failing tests for {spec}`
+- Green phase: `feat({scope}): implement {spec}`
+- Bug fixes: `fix({scope}): description`
+- Refactors: `refactor({scope}): description`
+- Keep subject line under 72 characters
+- Use imperative mood ("add", not "added")
+
+## Operations
+
+- Always check `git status` before destructive operations
+- Never force-push to shared branches without user confirmation
+- Prefer creating new commits over amending published ones
+- Stage specific files — avoid `git add -A` which may catch secrets

package/.claude/rules/security.md

@@ -0,0 +1,23 @@
+# Security Rules
+
+These rules apply to ALL actions, regardless of which skill is active.
+
+## Secrets
+
+- **NEVER** commit `.env`, `.env.*`, credentials, API keys, or tokens
+- **NEVER** hardcode secrets in source code — use environment variables
+- Verify `.gitignore` includes `.env*` before any git operations
+- If a secret is accidentally staged, **unstage immediately** and rotate the key
+
+## Dependencies
+
+- Do not install packages with known critical CVEs
+- Prefer well-maintained packages with active security practices
+- Pin major versions in production dependencies
+
+## Code
+
+- Sanitize all user input at system boundaries
+- Use parameterized queries — never string-concatenate SQL
+- Escape output to prevent XSS
+- Validate file paths to prevent traversal attacks

package/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "command": ".claude/hooks/post-edit-format.sh $FILE_PATH"
+      }
+    ],
+    "PreCompact": [
+      {
+        "command": ".claude/hooks/pre-compact-save.sh"
+      }
+    ]
+  }
+}

package/.claude/skills/build-orchestration/SKILL.md

@@ -28,7 +28,7 @@ Orchestrate the full build workflow: task breakdown, test writing, foundation, c
 ├── spec.md           # Already exists from /catalyze-spec
 ├── research.md       # Already exists from /catalyze-spec
 ├── tasks.md          # Forger creates (this phase)
-├── validation.md     # Arbiter creates (in /validate-spec)
+├── validation.md     # Arbiter creates (in /review-spec)
 ├── handoff.md        # Updated throughout
 └── assets/
 ```
@@ -144,6 +144,9 @@ Only AFTER this commit exists may implementation begin.
 No commit = no implementation. No exceptions.
 ```
 
+> **Context checkpoint:** If context is getting long, compact now. All state is in `tasks.md`.
+> Run `/primer-spec @{slug}` in a new conversation to resume.
+
 - Every task has at least one test
 - All tests executed
 - All tests FAIL (for the right reasons — missing feature, not import errors)
@@ -151,6 +154,9 @@ No commit = no implementation. No exceptions.
 
 ### Phase 3-4: Foundation & Contracts
 
+> **Context checkpoint:** If context is getting long, compact now. All state is in `tasks.md`.
+> Run `/primer-spec @{slug}` in a new conversation to resume.
+
 Spawn Alchemist (foundation) → WAIT → Spawn Smith (contracts) → WAIT
 
 ### Phase 5: Parallel Implementation
@@ -178,8 +184,14 @@ COMMIT: "feat({scope}): implement {spec}"
 Only AFTER this commit exists may integration begin.
 ```
 
+> **Context checkpoint:** If context is getting long, compact now. All state is in `tasks.md`.
+> Run `/primer-spec @{slug}` in a new conversation to resume.
+
 ### Phase 6: Integration
 
+> **Context checkpoint:** If context is getting long, compact now. All state is in `tasks.md`.
+> Run `/primer-spec @{slug}` in a new conversation to resume.
+
 Spawn Enforcer for cross-boundary integration tests.
 
 ## Implementation Rules

package/.claude/skills/spec-approval/SKILL.md

@@ -1,7 +1,7 @@
 # Spec Approval
 
 > **When to invoke:** When accepting an implementation and archiving the spec.
-> **Invoked by:** `/approve-spec` command.
+> **Invoked by:** `/commit-spec` command.
 
 ## Purpose
 
@@ -15,10 +15,10 @@ Final verification, git commit, spec archival, self-documentation (propagate lea
 ## Prerequisites — HARD GATES
 
 > **This skill is the FINAL step in the spec lifecycle.** It runs ONLY after build and validation are complete.
-> **Flow:** `/catalyze-spec` → `/build-spec` → `/validate-spec` → **`/approve-spec`** (you are here)
+> **Flow:** `/catalyze-spec` → `/build-spec` → `/review-spec` → **`/commit-spec`** (you are here)
 >
 > If the spec has not been built yet, STOP and tell the user to run `/build-spec` first.
-> If the spec has not been validated yet, STOP and tell the user to run `/validate-spec` first.
+> If the spec has not been validated yet, STOP and tell the user to run `/review-spec` first.
 
 - `/build-spec` must have been completed (tasks.md exists with completed tasks)
 - Validation must be complete (`validation.md` must show all checks passed)

package/.claude/skills/spec-shaping/SKILL.md

@@ -178,4 +178,4 @@ Next steps:
 - Or /iterate-spec if you want changes first
 ```
 
-**IMPORTANT: Do NOT suggest `/approve-spec` after spec shaping.** `/approve-spec` is only for accepting a fully built and validated implementation — it is the FINAL step, not a plan-approval step. The correct flow is: `/catalyze-spec` → `/build-spec` → `/validate-spec` → `/approve-spec`.
+**IMPORTANT: Do NOT suggest `/commit-spec` after spec shaping.** `/commit-spec` is only for committing a fully built and validated implementation — it is the FINAL step, not a plan-approval step. The correct flow is: `/catalyze-spec` → `/build-spec` → `/review-spec` → `/commit-spec`.

package/.claude/skills/spec-validation/SKILL.md

@@ -1,7 +1,7 @@
 # Spec Validation
 
 > **When to invoke:** When running validation checks on a completed implementation.
-> **Invoked by:** `/validate-spec` command.
+> **Invoked by:** `/review-spec` command.
 > **Orchestrator:** Arbiter agent.
 
 ## Purpose
@@ -76,10 +76,13 @@ Spawn all Guardians in parallel:
 - Test user flows
 - Capture screenshots on failure
 
-**Inquisitor** (Code Quality):
+**Inquisitor** (Code Quality + Simplification):
 - Run linters
 - Code review checks
 - Documentation gaps
+- **Code simplification suggestions** (unnecessary abstractions, over-engineering, dead code, verbose patterns)
+- Simplifications must NOT change behavior — only structure
+- Provide before/after snippets for each suggestion
 
 **Watcher** (Security):
 - Dependency audit
@@ -126,8 +129,9 @@ If all validation passes, create handoff.md with:
 - Total: N, Passing: N
 
 ## Quality Checks
-### Lint (Inquisitor)
-- Status: PASS/FAIL, Errors: N, Warnings: N
+### Lint & Simplification (Inquisitor)
+- Lint Status: PASS/FAIL, Errors: N, Warnings: N
+- Simplification Opportunities: N found
 
 ### Security (Watcher)
 - Dependencies: status
@@ -153,7 +157,7 @@ If all validation passes, create handoff.md with:
 ```
 Validation complete!
 Status: READY FOR APPROVAL
-Next: /approve-spec @slug
+Next: /commit-spec @slug
 ```
 
 ### TDD Failure
@@ -167,5 +171,5 @@ Action: Return to /build-spec and follow TDD process
 ```
 Validation failed!
 Failed Checks: [details]
-Action: Fix issues and re-run /validate-spec
+Action: Fix issues and re-run /review-spec
 ```

package/.claude/skills/using-skills/SKILL.md

@@ -44,8 +44,8 @@ Skills tell you HOW. User instructions tell you WHAT.
 | **spec-shaping** | `.claude/skills/spec-shaping/SKILL.md` | `/catalyze-spec` — shaping a new specification |
 | **build-orchestration** | `.claude/skills/build-orchestration/SKILL.md` | `/build-spec` — implementing a specification |
 | **spec-iteration** | `.claude/skills/spec-iteration/SKILL.md` | `/iterate-spec` — updating and continuing a build |
-| **spec-validation** | `.claude/skills/spec-validation/SKILL.md` | `/validate-spec` — quality checks on implementation |
-| **spec-approval** | `.claude/skills/spec-approval/SKILL.md` | `/approve-spec` — final approval and archival |
+| **spec-validation** | `.claude/skills/spec-validation/SKILL.md` | `/review-spec` — quality checks on implementation |
+| **spec-approval** | `.claude/skills/spec-approval/SKILL.md` | `/commit-spec` — final commit and archival |
 | **project-initialization** | `.claude/skills/project-initialization/SKILL.md` | `/catalyze-project` — setting up a new project |
 | **task-building** | `.claude/skills/task-building/SKILL.md` | `/build-task` — building a single task (brownfield) |
 | **spec-update** | `.claude/skills/spec-update/SKILL.md` | `/update-spec` — modifying an existing spec |

package/README.md

@@ -12,8 +12,8 @@ npx catalyst-os                        # Install to your project
 /catalyze-spec "description"           # Shape a feature specification
 /build-spec @spec-name                 # Implement with TDD
 /iterate-spec @spec-name "improvement" # Add improvements mid-build
-/validate-spec @spec-name              # Run quality checks
-/approve-spec @spec-name               # Accept and archive
+/review-spec @spec-name              # Run quality checks
+/commit-spec @spec-name               # Accept and archive
 ```
 
 ---
@@ -105,8 +105,8 @@ Without this, skills are optional documentation. With it, they're mandatory proc
 | `spec-shaping` | `/catalyze-spec` | Shape feature requests into specifications |
 | `build-orchestration` | `/build-spec` | DAG-based TDD implementation |
 | `spec-iteration` | `/iterate-spec` | Update and continue mid-build |
-| `spec-validation` | `/validate-spec` | Quality checks via Guardian agents |
-| `spec-approval` | `/approve-spec` | Final verification and archival |
+| `spec-validation` | `/review-spec` | Quality checks via Guardian agents |
+| `spec-approval` | `/commit-spec` | Final verification and archival |
 | `project-initialization` | `/catalyze-project` | Workspace detection + foundation docs |
 | `task-building` | `/build-task` | Single task (brownfield) |
 | `spec-update` | `/update-spec` | Modify spec during planning phase |
@@ -173,10 +173,10 @@ Guardians (Quality)
 ```
   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
   │              │     │              │     │              │     │              │
-  │   CATALYZE   │────>│    BUILD     │────>│   VALIDATE   │────>│   APPROVE    │
+  │   CATALYZE   │────>│    BUILD     │────>│    REVIEW    │────>│    COMMIT    │
   │              │     │              │     │              │     │              │
-  │ /catalyze-   │     │ /build-spec  │     │ /validate-   │     │ /approve-    │
-  │    spec      │     │              │     │    spec      │     │    spec      │
+  │ /catalyze-   │     │ /build-spec  │     │ /review-spec │     │ /commit-spec │
+  │    spec      │     │              │     │              │     │              │
   └──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘
          │                    │                    │                    │
          v                    v                    v                    v
@@ -209,9 +209,9 @@ Guardians (Quality)
 | `/iterate-spec @slug "idea"` | Add improvements mid-build | Updated spec + tasks, continues building |
 | `/primer-spec @slug` | Restore context (new conversation) | Brief status summary |
 | `/build-task "description"` | Modify existing code | task.md in .catalyst/tasks/ |
-| `/validate-spec @slug` | Quality checks | validation.md, handoff.md |
-| `/approve-spec @slug` | Finalize | Commit + Archive |
-| `/reject-spec @slug "reason"` | Reject implementation | Status: REJECTED |
+| `/review-spec @slug` | Quality checks | validation.md, handoff.md |
+| `/commit-spec @slug` | Finalize | Commit + Archive |
+| `/discard-spec @slug "reason"` | Discard implementation | Status: REJECTED |
 | `/status-spec @slug` | Check progress | Current status |
 | `/update-spec @slug "change"` | Modify spec (planning phase) | Updated spec.md |
 | `/mission` | Create/update mission.md | mission.md |
@@ -296,7 +296,7 @@ Enforcer   -> Builders      │ TDD: tests before code
 
 ## Pattern Library
 
-Reusable implementation patterns extracted from completed specs via `/approve-spec`.
+Reusable implementation patterns extracted from completed specs via `/commit-spec`.
 
 **Location:** `.catalyst/library/`
 

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "catalyst-os",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "scripts": {
-    "postinstall": "node .catalyst/bin/install.js"
+    "postinstall": "node .catalyst/bin/install.js",
+    "validate": "node .catalyst/bin/validate-artifacts.js"
   },
   "description": "AI-native spec-driven development framework for Claude Code",
   "bin": {

package/.claude/commands/approve-spec.md

@@ -1,22 +0,0 @@
-# /approve-spec
-
-Accept a **fully built and validated** implementation — commit, archive, and propagate learnings.
-
-> **Lifecycle position:** This is the FINAL step. Only use after `/build-spec` and `/validate-spec` have completed successfully.
->
-> **Flow:** `/catalyze-spec` → `/build-spec` → `/validate-spec` → **`/approve-spec`**
->
-> **This is NOT for approving a spec/plan before building.** There is no "approve plan" step — after catalyzing, you go straight to `/build-spec`.
-
-## Usage
-
-```
-/approve-spec @2025-11-29-stripe-integration
-/approve-spec @2025-11-29-stripe-integration "Great work!"
-```
-
----
-
-**Invoke skill:** `spec-approval`
-
-**Process skills used:** `verification-before-completion`, `agent-delegation`

package/.claude/commands/validate-spec.md

@@ -1,17 +0,0 @@
-# /validate-spec
-
-Run validation checks on a completed implementation.
-
-## Usage
-
-```
-/validate-spec @2025-11-29-stripe-integration
-```
-
----
-
-**Invoke skill:** `spec-validation`
-
-**Orchestrator:** Arbiter (delegates to Enforcer, Sentinel, Inquisitor, Watcher)
-
-**Process skills used:** `verification-before-completion`, `agent-delegation`, `test-driven-development`