@hone-ai/cli 1.4.0

package/hone-cli.js

@@ -0,0 +1,4006 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * @hone-ai/cli — Hone AI Command Line Interface
+ *
+ * Bridges the gap between setup-ai-pipeline.sh v3.1 and the Hone server.
+ * The key insight: setup-ai-pipeline.sh needs ENTERPRISE_SOURCE = enterprise-github/.github
+ * The CLI downloads this from the Hone server into a temp directory,
+ * then runs the script with --source pointing to that temp dir.
+ *
+ * Commands:
+ *   hone setup    — Download + run setup-ai-pipeline.sh v3.1
+ *   hone derive   — Bundle repo + POST /derive
+ *   hone refresh  — POST /derive/refresh (diff mode)
+ *   hone verify   — Health check against Hone server
+ *   hone sync     — Pull latest skills from server to local .github/skills/
+ */
+
+const { Command } = require('commander');
+const axios        = require('axios');
+const fs           = require('fs');
+const path         = require('path');
+const os           = require('os');
+const crypto       = require('crypto');
+const { execSync } = require('child_process');
+
+const pkg     = require('./package.json');
+const program = new Command();
+
+// ── Config resolution ─────────────────────────────────────────────────────────
+const RC_PATH = path.join(os.homedir(), '.honerc');
+
+function readRc() {
+  try {
+    if (fs.existsSync(RC_PATH)) return JSON.parse(fs.readFileSync(RC_PATH, 'utf8'));
+  } catch {}
+  return {};
+}
+
+function getConfig() {
+  // Priority: env var → ~/.honerc → error
+  const rc     = readRc();
+  const token  = process.env.HONE_TOKEN  || rc.token;
+  const apiUrl = process.env.HONE_API     || rc.api || 'https://api.hone.ai';
+
+  if (!token) {
+    console.error('Error: Hone token not found.');
+    console.error('Run "hone init --token <token>" to configure,');
+    console.error('or set the HONE_TOKEN environment variable.');
+    process.exit(1);
+  }
+
+  return { token, apiUrl };
+}
+
+function api(config) {
+  return axios.create({
+    baseURL: config.apiUrl,
+    headers: {
+      Authorization: `Bearer ${config.token}`,
+      'User-Agent':  `@hone-ai/cli/${pkg.version}`,
+    },
+    timeout: 30_000,
+  });
+}
+
+// ── SETUP command ─────────────────────────────────────────────────────────────
+program
+  .command('setup')
+  .description('Run setup-ai-pipeline.sh v3.1 — detects stack, scaffolds agents + skills')
+  .option('--dry-run',         'Preview what would be created without writing files')
+  .option('--non-interactive', 'Use detected defaults without prompting')
+  .option('--stack <stack>',   'Override stack detection (node|java|python|dotnet|salesforce)')
+  .option('--install-tests',   'Install unit test framework (vitest/jest/pytest) + create config')
+  .option('--e2e',             'Also install Playwright E2E framework (use with --install-tests)')
+  .option('--no-e2e',          'Skip Playwright even when --install-tests is set')
+  .option('--no-branch-protection', 'Skip installing GitHub branch protection on the default branch (H-001)')
+  .option('--refresh',           'Re-scan platform metadata without re-running full setup (HC-013c)')
+  .action(async (opts) => {
+    const config = getConfig();
+    const client = api(config);
+
+    // ── --refresh mode: re-ground platform config only ──────────────
+    if (opts.refresh) {
+      console.log('Hone AI — Platform Refresh');
+      console.log('==============================');
+      console.log('');
+
+      const repoRoot = process.cwd();
+      const configPath = path.join(repoRoot, '.github', '.pipeline-config.yml');
+
+      if (!fs.existsSync(configPath)) {
+        console.error('No .pipeline-config.yml found. Run `hone setup` first.');
+        process.exit(1);
+      }
+
+      const yaml = require('js-yaml');
+      const configText = fs.readFileSync(configPath, 'utf8');
+      const parsedConfig = yaml.load(configText);
+
+      const { groundPlatformConfig } = require('./lib/setup-grounding');
+      const result = groundPlatformConfig({
+        repoRoot,
+        configText,
+        parsedConfig,
+        refresh: true,
+        readFile: (rel) => {
+          try { return fs.readFileSync(path.join(repoRoot, rel), 'utf8'); }
+          catch { return null; }
+        },
+        listDir: (rel) => {
+          try { return fs.readdirSync(path.join(repoRoot, rel)); }
+          catch { return []; }
+        },
+        exec: (cmd) => {
+          try {
+            const stdout = require('child_process').execSync(cmd, {
+              encoding: 'utf8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            return { stdout: stdout.trim(), exitCode: 0 };
+          } catch (e) {
+            return { stdout: e.stdout || '', exitCode: e.status || 1 };
+          }
+        },
+        loadRegistry: (platform) => {
+          const rp = path.join(__dirname, '..', 'server', 'seeds', 'platform-docs', `${platform}.yml`);
+          try {
+            if (fs.existsSync(rp)) return yaml.load(fs.readFileSync(rp, 'utf8'));
+          } catch { /* no registry */ }
+          return null;
+        },
+      });
+
+      if (!result.skipped) {
+        fs.writeFileSync(configPath, result.augmentedConfig);
+        const platforms = Object.keys(result.platforms);
+        console.log(`✓ Platform grounding refreshed: ${platforms.join(', ')}`);
+        for (const [p, data] of Object.entries(result.platforms)) {
+          const mc = data.discovery.metadata_types;
+          const total = mc.code.length + mc.config.length + mc.test.length;
+          console.log(`  ${p}: ${total} metadata types, ${data.selectedDocs.length} doc URLs, MCP: ${data.mcp.available ? 'available' : 'not detected'}`);
+        }
+        for (const w of (result.warnings || [])) console.log(`  ⚠ ${w}`);
+      } else {
+        console.log(`ℹ Refresh skipped: ${result.reason}`);
+      }
+      return;
+    }
+
+    console.log('Hone AI — Pipeline Setup');
+    console.log('==============================');
+    console.log('');
+
+    // 1. Fetch org config to confirm connectivity and tier
+    let orgConfig;
+    try {
+      const r = await client.get('/scripts/config');
+      orgConfig = r.data;
+      console.log(`Org: ${orgConfig.org} | Tier: ${orgConfig.tier}`);
+    } catch (e) {
+      console.error(`Cannot connect to Hone server: ${e.message}`);
+      process.exit(1);
+    }
+
+    // 2. Create temp enterprise-github/.github directory
+    //    This is the ENTERPRISE_SOURCE that setup-ai-pipeline.sh needs
+    const tmpDir       = fs.mkdtempSync(path.join(os.tmpdir(), 'hone-'));
+    const enterpriseGH = path.join(tmpDir, 'enterprise-github', '.github');
+    const agentsDir    = path.join(enterpriseGH, 'agents');
+    const skillsDir    = path.join(enterpriseGH, 'skills');
+
+    fs.mkdirSync(agentsDir, { recursive: true });
+    fs.mkdirSync(skillsDir, { recursive: true });
+
+    console.log('');
+    console.log('Downloading enterprise assets from Hone server...');
+
+    // 3–5b. Download ALL enterprise assets in parallel (agents, skills, copilot-instructions, workflows, reviewer)
+    //        Previous: 21 sequential HTTP calls (~3s). Now: 1 parallel batch (~0.5s).
+    const agents = [
+      'story-groomer', 'implementation-planner', 'unit-test-case-writer',
+      'e2e-qa-planner', 'e2e-test-spec-writer', 'e2e-qa-spec-healer',
+      'code-builder', 'code-reviewer', 'delivery-architect',
+    ];
+    const skills = [
+      'architecture-patterns', 'api-standards', 'auth-service',
+      'error-handling', 'test-patterns', 'pr-review-standards',
+      'reliability', 'webapp-testing',
+    ];
+
+    const workflowsDir = path.join(enterpriseGH, 'workflows');
+    const scriptsEntDir = path.join(enterpriseGH, 'scripts');
+    fs.mkdirSync(workflowsDir, { recursive: true });
+    fs.mkdirSync(scriptsEntDir, { recursive: true });
+
+    // Build parallel fetch list
+    const fetches = [
+      // Agent stubs
+      ...agents.map(agent => ({
+        key: `${agent}.agent.md`,
+        promise: client.get(`/scripts/agent-stub/${agent}`).then(r => r.data),
+        write: (data) => fs.writeFileSync(path.join(agentsDir, `${agent}.agent.md`), data),
+      })),
+      // Skill files
+      ...skills.map(skill => ({
+        key: `skills/${skill}/SKILL.md`,
+        promise: client.get(`/skills/${skill}`).then(r => r.data),
+        write: (data) => {
+          const skillDir = path.join(skillsDir, skill);
+          fs.mkdirSync(skillDir, { recursive: true });
+          fs.writeFileSync(path.join(skillDir, 'SKILL.md'), data);
+        },
+      })),
+      // Copilot instructions
+      {
+        key: 'copilot-instructions.md',
+        promise: client.get('/scripts/copilot-instructions').then(r => r.data),
+        write: (data) => fs.writeFileSync(path.join(enterpriseGH, 'copilot-instructions.md'), data),
+      },
+      // AI review workflow template
+      {
+        key: 'workflows/ai-review.yml',
+        promise: client.get('/scripts/workflow-template', { responseType: 'text', headers: { Accept: 'text/yaml' } }).then(r => r.data),
+        write: (data) => fs.writeFileSync(path.join(workflowsDir, 'ai-review.yml'), data),
+      },
+      // AI reviewer script
+      {
+        key: 'scripts/ai-reviewer.js',
+        promise: client.get('/scripts/reviewer-script', { responseType: 'text', headers: { Accept: 'text/javascript' } }).then(r => r.data),
+        write: (data) => fs.writeFileSync(path.join(scriptsEntDir, 'ai-reviewer.js'), data),
+      },
+      // H-007: Learnings gate helper (imported by ai-reviewer at CI time).
+      // Both files are ESM. The .github/scripts/package.json (next entry below)
+      // declares ESM scope for this directory so node treats both .js files as
+      // ES modules regardless of the adopter's root package.json (see #16).
+      {
+        key: 'scripts/check-learnings-gate.js',
+        promise: client.get('/scripts/learnings-gate-script', { responseType: 'text', headers: { Accept: 'text/javascript' } }).then(r => r.data),
+        write: (data) => fs.writeFileSync(path.join(scriptsEntDir, 'check-learnings-gate.js'), data),
+      },
+      // H-007: Subdir package.json declares ESM scope for .github/scripts/.
+      // Both ai-reviewer.js and check-learnings-gate.js use `import` syntax;
+      // without this file, node treats them as CommonJS (the npm-init default)
+      // and the workflow fails with `Cannot use import statement outside a
+      // module`. Subdir package.json scope OVERRIDES the adopter's root —
+      // adopter's main project module semantics are unaffected. See #16.
+      {
+        key: 'scripts/package.json',
+        promise: Promise.resolve('{"type": "module"}\n'),
+        write: (data) => fs.writeFileSync(path.join(scriptsEntDir, 'package.json'), data),
+      },
+      // H-004: Auto-promote workflow template (installed at setup time;
+      // adopters customize {{BRANCHES}} via .pipeline-config.yml's
+      // ci.trigger_branches setting via setup-ai-pipeline.sh substitution).
+      // Goes to .github/workflows/learnings-promote.yml in the adopter repo.
+      {
+        key: 'workflows/learnings-promote.yml',
+        promise: client.get('/scripts/learnings-promote-template', { responseType: 'text', headers: { Accept: 'text/yaml' } }).then(r => r.data),
+        write: (data) => fs.writeFileSync(path.join(workflowsDir, 'learnings-promote.yml'), data),
+      },
+      // Metrics README (schema doc — needed by agents on ALL tiers to write per-story scorecards)
+      {
+        key: 'metrics/README.md',
+        promise: client.get('/scripts/metrics/readme', { responseType: 'text' }).then(r => r.data),
+        write: (data) => {
+          const metricsDir = path.join(enterpriseGH, 'metrics');
+          fs.mkdirSync(metricsDir, { recursive: true });
+          fs.writeFileSync(path.join(metricsDir, 'README.md'), data);
+        },
+      },
+      // Docs README (pipeline asset index + freshness rules — all tiers)
+      {
+        key: 'docs/sdlc/README.md',
+        promise: client.get('/scripts/docs/readme', { responseType: 'text' }).then(r => r.data),
+        write: (data) => {
+          const docsDir = path.join(tmpDir, 'enterprise-github', 'docs', 'sdlc');
+          fs.mkdirSync(docsDir, { recursive: true });
+          fs.writeFileSync(path.join(docsDir, 'README.md'), data);
+        },
+      },
+      // CLAUDE.md template for Claude Code integration (installed at repo root)
+      {
+        key: 'CLAUDE.md (Claude Code)',
+        promise: client.get('/scripts/claude-md', { responseType: 'text' }).then(r => r.data),
+        write: (data) => {
+          // H-002b: Substitute stack-aware test/lint commands at install time.
+          // Stack derived from detected primary; falls back to node defaults
+          // gracefully (E5). Unknown {{TOKEN}}s left intact (E4).
+          const { substituteClaudeMdTokens, getClaudeMdVarsForStack } = require('./lib/claude-md-tokens');
+          const detected = detectExistingTestFramework(process.cwd());
+          const stack = detected.stack === 'unknown' ? 'node' : detected.stack;
+          const vars = getClaudeMdVarsForStack(stack);
+          const substituted = substituteClaudeMdTokens(data, vars);
+          // Write substituted output to temp dir — copied to repo root after bash script runs
+          fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), substituted);
+        },
+      },
+    ];
+
+    // Execute all in parallel
+    const results = await Promise.allSettled(fetches.map(f => f.promise));
+    results.forEach((result, i) => {
+      const { key, write } = fetches[i];
+      if (result.status === 'fulfilled') {
+        write(result.value);
+        process.stdout.write(`  ✓ ${key}\n`);
+      } else {
+        process.stdout.write(`  ⚠ ${key} — ${result.reason?.message || 'failed'}\n`);
+      }
+    });
+
+    // 6. Download setup-ai-pipeline.sh, verify HMAC, write to tmp
+    let scriptContent;
+    try {
+      const r = await client.get('/scripts/setup', {
+        headers: { Accept: 'text/plain' },
+        responseType: 'text',
+      });
+      scriptContent = r.data;
+      const hmacHeader = r.headers['x-hone-hmac'];
+
+      // Verify HMAC if secret is known (optional — server enforces auth anyway)
+      if (process.env.HONE_HMAC_SECRET && hmacHeader) {
+        const computed = crypto
+          .createHmac('sha256', process.env.HONE_HMAC_SECRET)
+          .update(scriptContent)
+          .digest('hex');
+        if (computed !== hmacHeader) {
+          console.error('HMAC verification failed — script may have been tampered with');
+          process.exit(1);
+        }
+        console.log('  ✓ Script HMAC verified');
+      }
+    } catch (e) {
+      console.error(`Failed to download setup script: ${e.message}`);
+      process.exit(1);
+    }
+
+    // 7. Write script to tmp, make executable
+    const scriptPath = path.join(tmpDir, 'setup-ai-pipeline.sh');
+    fs.writeFileSync(scriptPath, scriptContent, { mode: 0o755 });
+
+    // 7b. Stage cli/lib/stack-detect.js inside <tmpDir>/enterprise-github/cli/lib/
+    //     so the bash rebalance helper at setup-ai-pipeline.sh can resolve it
+    //     via `${ENTERPRISE_SOURCE}/../cli/lib/stack-detect.js`. H-002a (#11).
+    //     The helper is required by the rebalance_node_python() function
+    //     when both Node and Python manifests are present.
+    try {
+      const stackDetectSrc = path.join(__dirname, 'lib', 'stack-detect.js');
+      if (fs.existsSync(stackDetectSrc)) {
+        const stackDetectDstDir = path.join(tmpDir, 'enterprise-github', 'cli', 'lib');
+        fs.mkdirSync(stackDetectDstDir, { recursive: true });
+        fs.copyFileSync(stackDetectSrc, path.join(stackDetectDstDir, 'stack-detect.js'));
+      }
+    } catch (e) {
+      // Non-fatal: bash script falls back to greedy default when helper missing.
+      console.log(`  ⚠ Could not stage stack-detect.js: ${e.message} (rebalance will skip)`);
+    }
+
+    // 8. Run setup-ai-pipeline.sh with --source pointing to our temp enterprise-github dir
+    console.log('');
+    console.log('Running setup-ai-pipeline.sh v3.1...');
+    console.log('');
+
+    const flags = [
+      `--source "${path.join(tmpDir, 'enterprise-github')}"`,
+      opts.dryRun        ? '--dry-run'         : '',
+      opts.nonInteractive? '--non-interactive'  : '',
+    ].filter(Boolean).join(' ');
+
+    try {
+      execSync(`bash "${scriptPath}" ${flags}`, {
+        stdio: 'inherit',
+        cwd: process.cwd(),
+        env: { ...process.env },
+      });
+    } catch (e) {
+      console.error('Setup script failed:', e.message);
+      process.exit(1);
+    }
+
+    // ── Phase 1b: Install Claude Code files (CLAUDE.md + .claude/agents/) ────
+    const repoRoot = process.cwd();
+    const claudeMdSrc = path.join(tmpDir, 'CLAUDE.md');
+    const claudeMdDst = path.join(repoRoot, 'CLAUDE.md');
+
+    // Install CLAUDE.md (only if it doesn't already exist — don't overwrite custom project context)
+    if (fs.existsSync(claudeMdSrc)) {
+      if (!fs.existsSync(claudeMdDst)) {
+        fs.copyFileSync(claudeMdSrc, claudeMdDst);
+        console.log('  ✓ CLAUDE.md installed (Claude Code pipeline context)');
+      } else {
+        console.log('  CLAUDE.md already exists — skipping (manual merge recommended)');
+      }
+    }
+
+    // Create .claude/agents/ with symlinks or copies of .github/agents/
+    const ghAgentsDir = path.join(repoRoot, '.github', 'agents');
+    const claudeAgentsDir = path.join(repoRoot, '.claude', 'agents');
+    if (fs.existsSync(ghAgentsDir)) {
+      fs.mkdirSync(claudeAgentsDir, { recursive: true });
+      const agentFiles = fs.readdirSync(ghAgentsDir).filter(f => f.endsWith('.agent.md'));
+      for (const file of agentFiles) {
+        const src = path.join(ghAgentsDir, file);
+        const dst = path.join(claudeAgentsDir, file);
+        fs.copyFileSync(src, dst);
+      }
+      console.log(`  ✓ .claude/agents/ created (${agentFiles.length} agents mirrored from .github/agents/)`);
+    }
+
+    // ── Phase 1c: Platform grounding (HC-013b-setup) ──────────────────────
+    //    Runs AFTER bash script writes .pipeline-config.yml.
+    //    Discovers metadata types, detects MCP, selects doc registry URLs,
+    //    augments config with platform.metadata_types + config_paths + mcp.
+    try {
+      const configPath = path.join(repoRoot, '.github', '.pipeline-config.yml');
+      if (fs.existsSync(configPath)) {
+        const yaml = require('js-yaml');
+        const configText = fs.readFileSync(configPath, 'utf8');
+        const parsedConfig = yaml.load(configText);
+
+        const { groundPlatformConfig } = require('./lib/setup-grounding');
+        const groundResult = groundPlatformConfig({
+          repoRoot,
+          configText,
+          parsedConfig,
+          readFile: (rel) => {
+            try { return fs.readFileSync(path.join(repoRoot, rel), 'utf8'); }
+            catch { return null; }
+          },
+          listDir: (rel) => {
+            try { return fs.readdirSync(path.join(repoRoot, rel)); }
+            catch { return []; }
+          },
+          exec: (cmd) => {
+            try {
+              const stdout = require('child_process').execSync(cmd, {
+                encoding: 'utf8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'],
+              });
+              return { stdout: stdout.trim(), exitCode: 0 };
+            } catch (e) {
+              return { stdout: e.stdout || '', exitCode: e.status || 1 };
+            }
+          },
+          loadRegistry: (platform) => {
+            // Load from server seeds (available in dev) or from tmp download
+            const registryPaths = [
+              path.join(__dirname, '..', 'server', 'seeds', 'platform-docs', `${platform}.yml`),
+              path.join(tmpDir, 'enterprise-github', 'platform-docs', `${platform}.yml`),
+            ];
+            for (const rp of registryPaths) {
+              try {
+                if (fs.existsSync(rp)) return yaml.load(fs.readFileSync(rp, 'utf8'));
+              } catch { /* continue to next path */ }
+            }
+            return null;
+          },
+        });
+
+        if (!groundResult.skipped) {
+          fs.writeFileSync(configPath, groundResult.augmentedConfig);
+          const platformNames = Object.keys(groundResult.platforms);
+          console.log(`  ✓ Platform grounding: ${platformNames.join(', ')} (metadata discovered + config augmented)`);
+          for (const w of (groundResult.warnings || [])) {
+            console.log(`    ⚠ ${w}`);
+          }
+        } else {
+          console.log(`  ℹ Platform grounding skipped: ${groundResult.reason}`);
+        }
+      }
+    } catch (e) {
+      // Non-fatal: setup continues without platform grounding
+      console.log(`  ⚠ Platform grounding failed: ${e.message} (setup continues)`);
+    }
+
+    // 9. Clean up temp directory
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+
+    // ── Phase 2: Test framework installation (opt-in via --install-tests) ────
+    if (opts.installTests) {
+      await installTestFramework(process.cwd(), opts);
+    } else {
+      // Show recommendation if no test framework detected
+      recommendTestFramework(process.cwd());
+    }
+
+    // ── Phase 3: Branch protection (H-001) ───────────────────────────────────
+    //
+    // Install GitHub branch protection on the default branch so the
+    // AI Code Review gate we just scaffolded actually blocks merges —
+    // admin-merge cannot silently bypass it. Skips gracefully on
+    // non-GitHub remotes, missing gh CLI, no admin rights, plan
+    // restrictions, or org-level rulesets. Never fails the setup.
+    const skipBranchProtection =
+      opts.branchProtection === false ||
+      /^(1|true|yes)$/i.test(process.env.HONE_SKIP_BRANCH_PROTECTION || '');
+
+    const { installBranchProtection } = require('./lib/branch-protection');
+    const protResult = await installBranchProtection({
+      log: console.log,
+      opts: {
+        skip: skipBranchProtection,
+        requiredChecks: ['ai-code-review'],
+      },
+    });
+    console.log('');
+    if (protResult.status === 'installed') {
+      console.log(`  ✓ Branch protection installed on '${protResult.branch}'`);
+    } else if (protResult.status === 'skipped') {
+      console.log(`  ⚠ Branch protection skipped: ${protResult.reason}`);
+      if (protResult.manualCommand) {
+        console.log('');
+        console.log('  To install manually, run:');
+        console.log(protResult.manualCommand.split('\n').map(l => '    ' + l).join('\n'));
+      }
+    } else if (protResult.status === 'failed') {
+      console.log(`  ⚠ Branch protection failed: ${protResult.reason}`);
+      if (protResult.manualCommand) {
+        console.log('');
+        console.log('  To install manually, run:');
+        console.log(protResult.manualCommand.split('\n').map(l => '    ' + l).join('\n'));
+      }
+    }
+  });
+
+// ── Test framework installation helpers ────────────────────────────────────────
+
+function detectExistingTestFramework(repoRoot) {
+  const pkgPath = path.join(repoRoot, 'package.json');
+  if (!fs.existsSync(pkgPath)) return { stack: 'unknown', testFw: null, pkgMgr: null };
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+  // Detect stack
+  let stack = 'node';
+  if (allDeps['react']) stack = allDeps['vite'] ? 'react-vite' : 'react';
+  if (allDeps['next']) stack = 'nextjs';
+  if (allDeps['@nestjs/core']) stack = 'nestjs';
+
+  // Detect existing test framework
+  let testFw = null;
+  if (allDeps['vitest']) testFw = 'vitest';
+  else if (allDeps['jest']) testFw = 'jest';
+  else if (allDeps['mocha']) testFw = 'mocha';
+
+  // Detect Playwright
+  const hasPlaywright = !!allDeps['@playwright/test'];
+
+  // Detect package manager
+  let pkgMgr = 'npm';
+  if (fs.existsSync(path.join(repoRoot, 'yarn.lock'))) pkgMgr = 'yarn';
+  if (fs.existsSync(path.join(repoRoot, 'pnpm-lock.yaml'))) pkgMgr = 'pnpm';
+
+  // Detect existing configs
+  const hasTestConfig = ['vitest.config.js', 'vitest.config.ts', 'jest.config.js', 'jest.config.ts', 'jest.config.cjs']
+    .some(f => fs.existsSync(path.join(repoRoot, f)));
+  const hasPlaywrightConfig = fs.existsSync(path.join(repoRoot, 'playwright.config.js'))
+    || fs.existsSync(path.join(repoRoot, 'playwright.config.ts'));
+
+  // Detect existing test script
+  const hasTestScript = !!pkg.scripts?.test && pkg.scripts.test !== 'echo "Error: no test specified" && exit 1';
+
+  return { stack, testFw, hasPlaywright, pkgMgr, hasTestConfig, hasPlaywrightConfig, hasTestScript, pkg };
+}
+
+function getInstallPackages(stack) {
+  const packages = {
+    'react-vite': {
+      unit: ['vitest', '@testing-library/react', '@testing-library/jest-dom', 'jsdom'],
+      e2e: ['@playwright/test'],
+      testCmd: 'vitest run',
+      testWatchCmd: 'vitest',
+      e2eCmd: 'playwright test',
+      configFile: 'vitest.config.js',
+    },
+    'react': {
+      unit: ['vitest', '@testing-library/react', '@testing-library/jest-dom', 'jsdom'],
+      e2e: ['@playwright/test'],
+      testCmd: 'vitest run',
+      testWatchCmd: 'vitest',
+      e2eCmd: 'playwright test',
+      configFile: 'vitest.config.js',
+    },
+    'nextjs': {
+      unit: ['jest', '@testing-library/react', '@testing-library/jest-dom', 'jest-environment-jsdom'],
+      e2e: ['@playwright/test'],
+      testCmd: 'jest',
+      testWatchCmd: 'jest --watch',
+      e2eCmd: 'playwright test',
+      configFile: 'jest.config.js',
+    },
+    'node': {
+      unit: ['vitest'],
+      e2e: ['@playwright/test'],
+      testCmd: 'vitest run',
+      testWatchCmd: 'vitest',
+      e2eCmd: 'playwright test',
+      configFile: 'vitest.config.js',
+    },
+    'nestjs': {
+      unit: ['jest', '@nestjs/testing', 'ts-jest'],
+      e2e: ['@playwright/test'],
+      testCmd: 'jest',
+      testWatchCmd: 'jest --watch',
+      e2eCmd: 'playwright test',
+      configFile: 'jest.config.js',
+    },
+    // H-002b: Python entry. Branches off via `pkgManagerKind: 'python'`.
+    'python': require('./lib/python-install').PYTHON_INSTALL_CONFIG,
+  };
+  return packages[stack] || packages['node'];
+}
+
+// H-002b: Python install path — pip/poetry/pipenv branches.
+// pyproject.toml gets [tool.pytest.ini_options] section (NOT package.json).
+async function installPythonTestFramework(repoRoot, detected, pkgs, opts) {
+  const py = require('./lib/python-install');
+  const pyMgr = py.detectPythonPackageManager(repoRoot, (p) => fs.existsSync(p));
+  const cmd = py.getPythonInstallCommand(pyMgr);
+
+  console.log(`  Stack: python (pkgMgr: ${pyMgr}) → ${cmd}`);
+  try {
+    execSync(cmd, { stdio: 'inherit', cwd: repoRoot });
+    console.log(`  ✓ pytest installed`);
+  } catch (e) {
+    console.error(`  ✗ Install failed: ${e.message}`);
+    return;
+  }
+
+  // Write [tool.pytest.ini_options] to pyproject.toml (create file if missing)
+  const tomlPath = path.join(repoRoot, 'pyproject.toml');
+  const sectionText = py.buildPyprojectTomlSection();
+  if (fs.existsSync(tomlPath)) {
+    const existing = fs.readFileSync(tomlPath, 'utf8');
+    if (/\[tool\.pytest\.ini_options\]/.test(existing)) {
+      console.log(`  pyproject.toml already has [tool.pytest.ini_options] ✓ (skipping)`);
+    } else {
+      fs.writeFileSync(tomlPath, existing + (existing.endsWith('\n') ? '' : '\n') + '\n' + sectionText);
+      console.log(`  ✓ [tool.pytest.ini_options] appended to pyproject.toml`);
+    }
+  } else {
+    fs.writeFileSync(tomlPath, sectionText);
+    console.log(`  ✓ pyproject.toml created with [tool.pytest.ini_options]`);
+  }
+
+  // Sample test file
+  const testDir = path.join(repoRoot, 'tests');
+  const sampleTest = path.join(testDir, 'test_pipeline.py');
+  if (!fs.existsSync(sampleTest)) {
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.writeFileSync(sampleTest, [
+      `def test_pipeline_setup():`,
+      `    """Smoke test — H-002b scaffold confirms pytest discovers tests."""`,
+      `    assert 1 + 1 == 2`,
+      ``,
+      `def test_environment_configured():`,
+      `    import sys`,
+      `    assert sys.version_info.major >= 3`,
+    ].join('\n'));
+    console.log(`  ✓ tests/test_pipeline.py created`);
+  }
+
+  // E2E (Playwright Python) — opt-in via opts.e2e
+  const installE2e = opts && opts.e2e !== false && opts.noE2e !== true;
+  if (installE2e) {
+    console.log('');
+    console.log(`  Skipping Playwright (Python) e2e auto-install — adopters opt in via \`pip install pytest-playwright\` separately.`);
+    console.log(`  See pytest-playwright docs for details.`);
+  }
+}
+
+async function installTestFramework(repoRoot, opts) {
+  console.log('');
+  console.log('── Test Framework Setup ────────────────────────────────');
+  console.log('');
+
+  const detected = detectExistingTestFramework(repoRoot);
+  const pkgs = getInstallPackages(detected.stack);
+
+  // H-002b: Python branch — different install commands + pyproject.toml (not package.json)
+  if (pkgs.pkgManagerKind === 'python') {
+    return installPythonTestFramework(repoRoot, detected, pkgs, opts);
+  }
+
+  const installCmd = detected.pkgMgr === 'yarn' ? 'yarn add -D' : detected.pkgMgr === 'pnpm' ? 'pnpm add -D' : 'npm install -D';
+
+  // ── Unit test framework ────────────────────────────────
+  if (detected.testFw) {
+    console.log(`  Test framework detected: ${detected.testFw} ✓ (skipping install)`);
+  } else {
+    console.log(`  Stack: ${detected.stack} → Installing: ${pkgs.unit.join(', ')}`);
+    try {
+      execSync(`${installCmd} ${pkgs.unit.join(' ')}`, { stdio: 'inherit', cwd: repoRoot });
+      console.log(`  ✓ Unit test framework installed`);
+    } catch (e) {
+      console.error(`  ✗ Install failed: ${e.message}`);
+      return;
+    }
+  }
+
+  // ── Test config file ───────────────────────────────────
+  if (detected.hasTestConfig) {
+    console.log(`  Test config exists ✓ (skipping creation)`);
+  } else {
+    const configSrc = path.join(__dirname, '..', 'server', 'scripts', 'test-configs', pkgs.configFile + '.template');
+    if (fs.existsSync(configSrc)) {
+      fs.copyFileSync(configSrc, path.join(repoRoot, pkgs.configFile));
+      console.log(`  ✓ ${pkgs.configFile} created`);
+    } else {
+      // Inline fallback config for vitest
+      if (pkgs.configFile === 'vitest.config.js') {
+        fs.writeFileSync(path.join(repoRoot, pkgs.configFile), [
+          `import { defineConfig } from 'vitest/config';`,
+          ``,
+          `export default defineConfig({`,
+          `  test: {`,
+          `    environment: 'jsdom',`,
+          `    globals: true,`,
+          `    setupFiles: [],`,
+          `    include: ['src/**/*.{test,spec}.{js,jsx,ts,tsx}', 'test/**/*.{test,spec}.{js,jsx,ts,tsx}'],`,
+          `  },`,
+          `  resolve: {`,
+          `    alias: { '@': new URL('./src', import.meta.url).pathname },`,
+          `  },`,
+          `});`,
+        ].join('\n'));
+        console.log(`  ✓ ${pkgs.configFile} created (inline)`);
+      }
+    }
+  }
+
+  // ── npm test script ────────────────────────────────────
+  if (!detected.hasTestScript) {
+    const pkgPath = path.join(repoRoot, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    pkg.scripts = pkg.scripts || {};
+    pkg.scripts.test = pkgs.testCmd;
+    pkg.scripts['test:watch'] = pkgs.testWatchCmd;
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    console.log(`  ✓ "test": "${pkgs.testCmd}" added to package.json`);
+  } else {
+    console.log(`  Test script exists ✓ (skipping)`);
+  }
+
+  // ── Sample test file ───────────────────────────────────
+  const testDir = path.join(repoRoot, 'src', '__tests__');
+  const sampleTest = path.join(testDir, 'example.test.jsx');
+  if (!fs.existsSync(sampleTest)) {
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.writeFileSync(sampleTest, [
+      `import { describe, it, expect } from 'vitest';`,
+      ``,
+      `describe('Pipeline setup', () => {`,
+      `  it('test framework is working', () => {`,
+      `    expect(1 + 1).toBe(2);`,
+      `  });`,
+      ``,
+      `  it('environment is configured', () => {`,
+      `    expect(typeof window).toBe('object');`,
+      `  });`,
+      `});`,
+    ].join('\n'));
+    console.log(`  ✓ src/__tests__/example.test.jsx created`);
+  }
+
+  // ── E2E framework (Playwright) ─────────────────────────
+  const installE2e = opts.e2e !== false && opts.noE2e !== true;
+  if (installE2e) {
+    console.log('');
+    if (detected.hasPlaywright) {
+      console.log(`  Playwright detected ✓ (skipping install)`);
+    } else {
+      console.log(`  Installing Playwright...`);
+      try {
+        execSync(`${installCmd} @playwright/test`, { stdio: 'inherit', cwd: repoRoot });
+        console.log(`  ✓ @playwright/test installed`);
+        console.log(`  Installing Chromium browser...`);
+        execSync('npx playwright install chromium', { stdio: 'inherit', cwd: repoRoot });
+        console.log(`  ✓ Chromium installed`);
+      } catch (e) {
+        console.error(`  ✗ Playwright install failed: ${e.message}`);
+      }
+    }
+
+    // Playwright config
+    if (!detected.hasPlaywrightConfig) {
+      fs.writeFileSync(path.join(repoRoot, 'playwright.config.js'), [
+        `import { defineConfig } from '@playwright/test';`,
+        ``,
+        `export default defineConfig({`,
+        `  testDir: './e2e',`,
+        `  timeout: 30_000,`,
+        `  retries: process.env.CI ? 2 : 0,`,
+        `  use: {`,
+        `    baseURL: process.env.TEST_BASE_URL || 'http://localhost:5173',`,
+        `    headless: true,`,
+        `    screenshot: 'only-on-failure',`,
+        `  },`,
+        `  projects: [`,
+        `    { name: 'chromium', use: { browserName: 'chromium' } },`,
+        `  ],`,
+        `});`,
+      ].join('\n'));
+      console.log(`  ✓ playwright.config.js created`);
+    }
+
+    // E2E npm script
+    const pkgPath = path.join(repoRoot, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    if (!pkg.scripts?.['test:e2e']) {
+      pkg.scripts = pkg.scripts || {};
+      pkg.scripts['test:e2e'] = pkgs.e2eCmd;
+      fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+      console.log(`  ✓ "test:e2e": "${pkgs.e2eCmd}" added to package.json`);
+    }
+
+    // Sample E2E spec
+    const e2eDir = path.join(repoRoot, 'e2e');
+    const sampleSpec = path.join(e2eDir, 'example.spec.js');
+    if (!fs.existsSync(sampleSpec)) {
+      fs.mkdirSync(e2eDir, { recursive: true });
+      fs.writeFileSync(sampleSpec, [
+        `import { test, expect } from '@playwright/test';`,
+        ``,
+        `test('app loads without errors', async ({ page }) => {`,
+        `  await page.goto('/');`,
+        `  // Verify the page loaded (no crash, no blank screen)`,
+        `  await expect(page).not.toHaveTitle('');`,
+        `});`,
+      ].join('\n'));
+      console.log(`  ✓ e2e/example.spec.js created`);
+    }
+  }
+
+  // ── Interactive test context (.env.test) ───────────────
+  console.log('');
+  await createTestEnv(repoRoot, opts);
+
+  // ── Verify ─────────────────────────────────────────────
+  if (!detected.testFw) {
+    console.log('');
+    console.log('── Verification ────────────────────────────────────────');
+    try {
+      execSync('npm test 2>&1', { cwd: repoRoot, stdio: 'inherit', timeout: 30_000 });
+      console.log('  ✓ npm test passed');
+    } catch {
+      console.log('  ⚠ npm test had issues — review test output above');
+    }
+  }
+
+  console.log('');
+  console.log('────────────────────────────────────────────────────────');
+  console.log('  Test framework ready. Write tests using the Unit Test Writer agent (Step 2).');
+}
+
+async function createTestEnv(repoRoot, opts) {
+  const envTestPath = path.join(repoRoot, 'env.test');
+  const envExamplePath = path.join(repoRoot, '.env.test.example');
+
+  // .env.test.example (always created — committed as team template)
+  const template = [
+    '# Test environment template — copy to .env.test and fill in values',
+    '# Created by: hone setup --install-tests',
+    '# Documentation: docs/sdlc/README.md',
+    '',
+    '# Required for E2E tests (Playwright baseURL)',
+    'TEST_BASE_URL=http://localhost:5173',
+    '',
+    '# Required for authenticated E2E flows',
+    'TEST_USER_EMAIL=',
+    'TEST_USER_PASSWORD=',
+    '',
+    '# Optional — API URL if different from app URL',
+    '# TEST_API_URL=',
+    '',
+    '# Optional — test database',
+    '# TEST_DATABASE_URL=',
+  ].join('\n');
+
+  if (!fs.existsSync(envExamplePath)) {
+    fs.writeFileSync(envExamplePath, template);
+    console.log('  ✓ .env.test.example created (commit this — team template)');
+  }
+
+  // .env.test (interactive prompts — gitignored)
+  if (opts.nonInteractive) {
+    console.log('  Non-interactive: skipping .env.test creation. Copy .env.test.example to .env.test and fill in values.');
+    return;
+  }
+
+  if (fs.existsSync(path.join(repoRoot, '.env.test'))) {
+    console.log('  .env.test exists ✓ (skipping)');
+    return;
+  }
+
+  // Interactive prompts via readline
+  const readline = await import('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise(resolve => rl.question(q, resolve));
+
+  console.log('  E2E tests need runtime context. Answer these prompts (or press Enter for defaults):');
+  console.log('');
+
+  const baseUrl = await ask('  ? App URL for E2E tests (http://localhost:5173): ') || 'http://localhost:5173';
+  const email = await ask('  ? Test user email (skip if none): ') || '';
+  const password = email ? await ask('  ? Test user password: ') || '' : '';
+  const apiUrl = await ask('  ? API base URL (skip if same as app): ') || '';
+
+  rl.close();
+
+  const envContent = [
+    '# Test environment — created by hone setup --install-tests',
+    '# This file is gitignored. See .env.test.example for documentation.',
+    '',
+    `TEST_BASE_URL=${baseUrl}`,
+    '',
+    email ? `TEST_USER_EMAIL=${email}` : '# TEST_USER_EMAIL=',
+    password ? `TEST_USER_PASSWORD=${password}` : '# TEST_USER_PASSWORD=',
+    '',
+    apiUrl ? `TEST_API_URL=${apiUrl}` : '# TEST_API_URL=',
+  ].join('\n');
+
+  fs.writeFileSync(path.join(repoRoot, '.env.test'), envContent);
+  console.log('');
+  console.log('  ✓ .env.test created (gitignored — contains your test credentials)');
+
+  // Ensure .env.test is in .gitignore
+  const gitignorePath = path.join(repoRoot, '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    const gitignore = fs.readFileSync(gitignorePath, 'utf8');
+    if (!gitignore.includes('.env.test')) {
+      fs.appendFileSync(gitignorePath, '\n# Test environment (contains credentials)\n.env.test\n');
+      console.log('  ✓ .env.test added to .gitignore');
+    }
+  }
+}
+
+function recommendTestFramework(repoRoot) {
+  const detected = detectExistingTestFramework(repoRoot);
+  if (detected.testFw) return; // Already has tests — no recommendation needed
+
+  const pkgs = getInstallPackages(detected.stack);
+  const installCmd = detected.pkgMgr === 'yarn' ? 'yarn add -D' : detected.pkgMgr === 'pnpm' ? 'pnpm add -D' : 'npm install -D';
+
+  console.log('');
+  console.log('── Test Framework Recommendation ───────────────────────');
+  console.log('');
+  console.log(`  Detected: No test framework installed.`);
+  console.log(`  Recommended for ${detected.stack}:`);
+  console.log(`    Unit: ${pkgs.unit.join(', ')}`);
+  console.log(`    E2E:  @playwright/test (chromium only)`);
+  console.log('');
+  console.log(`  To install now:`);
+  console.log(`    hone setup --install-tests --e2e`);
+  console.log('');
+  console.log(`  Or manually:`);
+  console.log(`    ${installCmd} ${pkgs.unit.join(' ')}`);
+  console.log(`    ${installCmd} @playwright/test && npx playwright install chromium`);
+  console.log('');
+  console.log('────────────────────────────────────────────────────────');
+}
+
+// ── DERIVE command ────────────────────────────────────────────────────────────
+program
+  .command('derive')
+  .description('Derive domain skills from this repository\'s codebase')
+  .option('--refresh',         'Run in refresh mode (diff-based, human approval required)')
+  .option('--repo <name>',     'Repository name override')
+  .option('--max-files <n>',   'Max source files to send (default: 30)', '30')
+  .option('--poll-interval <s>','Poll interval in seconds (default: 5)', '5')
+  .action(async (opts) => {
+    const config     = getConfig();
+    const client     = api(config);
+    const repoRoot   = process.cwd();
+    const configPath = path.join(repoRoot, '.github', '.pipeline-config.yml');
+    const isRefresh  = opts.refresh;
+
+    console.log(`Hone AI — ${isRefresh ? 'Skill Refresh' : 'Domain Skill Derivation'}`);
+    console.log('='.repeat(50));
+
+    // 1. Read .pipeline-config.yml
+    if (!fs.existsSync(configPath)) {
+      console.error('Error: .github/.pipeline-config.yml not found.');
+      console.error('Run "hone setup" first to generate this file.');
+      process.exit(1);
+    }
+
+    const yaml         = require('js-yaml');
+    const pipelineConfig = yaml.load(fs.readFileSync(configPath, 'utf8'));
+    const stack        = pipelineConfig?.stack?.primary || 'unknown';
+    const repoName     = opts.repo || path.basename(repoRoot);
+
+    console.log(`Stack: ${stack} | Repo: ${repoName}`);
+
+    // 2. Bundle source files
+    const sourceDirs = pipelineConfig?.source_dirs || ['src/'];
+    const files      = {};
+    const maxFiles   = parseInt(opts.maxFiles);
+    let fileCount    = 0;
+
+    for (const dir of sourceDirs) {
+      const dirPath = path.join(repoRoot, dir.replace(/"/g, ''));
+      if (!fs.existsSync(dirPath)) continue;
+      bundleDirectory(dirPath, repoRoot, files, maxFiles, fileCount);
+      fileCount = Object.keys(files).length;
+      if (fileCount >= maxFiles) break;
+    }
+
+    console.log(`Bundling ${Object.keys(files).length} source files...`);
+
+    // 3. Bundle existing skills if refresh mode
+    let existingSkills = {};
+    if (isRefresh) {
+      const skillsDir = path.join(repoRoot, '.github', 'skills');
+      if (fs.existsSync(skillsDir)) {
+        bundleDirectory(skillsDir, repoRoot, existingSkills, 50, 0);
+        console.log(`Bundling ${Object.keys(existingSkills).length} existing skill files...`);
+      }
+    }
+
+    // 4. Collect doc URLs
+    const docUrls = (pipelineConfig?.documentation?.external_urls || [])
+      .filter(u => u && !u.includes('confluence.example.com'));
+
+    // 5. POST /derive or /derive/refresh
+    const endpoint = isRefresh ? '/derive/refresh' : '/derive';
+    console.log(`\nSubmitting to Hone server (${endpoint})...`);
+
+    let jobId;
+    try {
+      const r = await client.post(endpoint, {
+        files,
+        pipelineConfig,
+        repoName,
+        docUrls,
+        isRefresh,
+        existingSkills,
+      });
+      jobId = r.data.jobId;
+      console.log(`Job queued: ${jobId}`);
+      console.log(`Estimated: ~${r.data.estimatedSeconds}s`);
+    } catch (e) {
+      console.error(`Submit failed: ${e.response?.data?.error || e.message}`);
+      process.exit(1);
+    }
+
+    // 6. Poll for completion
+    const pollMs = parseInt(opts.pollInterval) * 1000;
+    process.stdout.write('Processing');
+    let result;
+
+    while (true) {
+      await sleep(pollMs);
+      process.stdout.write('.');
+      try {
+        const r = await client.get(`/derive/${jobId}`);
+        if (r.data.status === 'complete') {
+          result = r.data;
+          break;
+        }
+        if (r.data.status === 'failed') {
+          console.error(`\nJob failed: ${r.data.error}`);
+          process.exit(1);
+        }
+      } catch (e) {
+        console.warn(`\nPoll error: ${e.message}`);
+      }
+    }
+
+    console.log('\n');
+
+    if (isRefresh) {
+      // Show change report and wait for approval
+      console.log('═'.repeat(60));
+      console.log('SKILL REFRESH REPORT');
+      console.log('═'.repeat(60));
+      console.log(result.changeReport || '[No change report generated]');
+      console.log('');
+      console.log(`To apply changes: hone approve --job ${jobId}`);
+      console.log(`To skip: hone derive --refresh (run again later)`);
+
+      // Save change report to file
+      const reportPath = path.join(repoRoot, '.github', 'skill-refresh-report.md');
+      fs.writeFileSync(reportPath, result.changeReport || '');
+      console.log(`\nChange report saved to: .github/skill-refresh-report.md`);
+    } else {
+      // Write generated skills to disk
+      console.log('Writing generated skills...');
+      if (result.skills) {
+        for (const [skillName, content] of Object.entries(result.skills)) {
+          if (!content || content.length < 50) continue;
+          const skillDir  = path.join(repoRoot, '.github', 'skills', skillName);
+          const skillFile = path.join(skillDir, 'SKILL.md');
+          fs.mkdirSync(skillDir, { recursive: true });
+          fs.writeFileSync(skillFile, content);
+          console.log(`  ✓ .github/skills/${skillName}/SKILL.md`);
+        }
+      }
+
+      // H-022: surface parser warnings so silent drops become VISIBLE failures.
+      // The parser already emits warnings (H-016 fix added the array); the CLI
+      // had been ignoring them, which caused the H-022 regression where
+      // python-architect silently disappeared. Adopters now see exactly which
+      // skills failed to extract and which patterns were tried.
+      if (Array.isArray(result.warnings) && result.warnings.length > 0) {
+        console.warn('');
+        console.warn(`⚠ Parser warnings (${result.warnings.length}):`);
+        for (const w of result.warnings) {
+          console.warn(`  - ${w}`);
+        }
+        console.warn(
+          '\n  These skills were not written. If a heading shape was missed, ' +
+          'open an issue at https://github.com/subbareddyvani/hone-server/issues ' +
+          'with the heading text — we extend the pattern list there.'
+        );
+      }
+
+      // Write living architecture doc if generated
+      if (result.architectureSummary) {
+        const archDir = path.join(repoRoot, 'docs', 'sdlc');
+        fs.mkdirSync(archDir, { recursive: true });
+        fs.writeFileSync(path.join(archDir, 'ARCHITECTURE.md'), result.architectureSummary);
+        console.log('  ✓ docs/sdlc/ARCHITECTURE.md (living architecture — regenerated from codebase scan)');
+      }
+
+      // Update .pipeline-config.yml with discovered URLs
+      if (result.updatedConfig) {
+        const yaml = require('js-yaml');
+        fs.writeFileSync(configPath, yaml.dump(result.updatedConfig));
+        console.log('  ✓ .github/.pipeline-config.yml (updated with platform URLs)');
+      }
+
+      // H-021: Stamp skill_refresh.last_derived with the current ISO timestamp.
+      // The .pipeline-config.yml schema docs say it's "updated each time
+      // derive-domain-skills runs" but the CLI never wrote it (issue #31).
+      // Surgical regex preserves all comments + other fields. Graceful no-op
+      // if `last_derived:` line is absent.
+      // H-015: Also stamp skill_refresh.last_derived_src_files for the
+      // growth-based refresh trigger (issue #24).
+      try {
+        const { stampLastDerived, stampLastDerivedSrcFiles } = require('./lib/config-update');
+        let currentText = fs.readFileSync(configPath, 'utf8');
+        const stamped = stampLastDerived(currentText, new Date().toISOString());
+        if (stamped.updated) {
+          currentText = stamped.text;
+          console.log(`  ✓ .github/.pipeline-config.yml — skill_refresh.last_derived stamped`);
+        }
+        // H-015: src-file count for growth trigger
+        const stampedCount = stampLastDerivedSrcFiles(currentText, Object.keys(files).length);
+        if (stampedCount.updated) {
+          currentText = stampedCount.text;
+          console.log(`  ✓ skill_refresh.last_derived_src_files = ${Object.keys(files).length}`);
+        }
+        if (stamped.updated || stampedCount.updated) {
+          fs.writeFileSync(configPath, currentText);
+        }
+      } catch (e) {
+        console.warn(`  (skipped last_derived stamp: ${e.message})`);
+      }
+
+      // Show health scorecard
+      if (result.scorecard) {
+        console.log('');
+        console.log('Health Scorecard:');
+        console.log(result.scorecard.raw || `Grade: ${result.scorecard.grade} (${result.scorecard.score}/${result.scorecard.max})`);
+      }
+
+      console.log('');
+      console.log('Next step: Review generated skills, then commit:');
+      console.log('  git add .github/skills/ .github/.pipeline-config.yml');
+      console.log('  git commit -m "feat: derive domain skills"');
+    }
+  });
+
+// ── INIT command ──────────────────────────────────────────────────────────────
+program
+  .command('init')
+  .description('Save HONE_TOKEN and API URL to ~/.honerc')
+  .option('--token <token>', 'Hone API token')
+  .option('--api <url>',     'Hone API base URL (default: https://api.hone.ai)')
+  .action(async (opts) => {
+    const token  = opts.token || process.env.HONE_TOKEN;
+    const apiUrl = opts.api   || process.env.HONE_API || 'https://api.hone.ai';
+
+    if (!token) {
+      console.error('Error: --token is required (or set HONE_TOKEN env var).');
+      console.error('Get your token from your Hone admin.');
+      process.exit(1);
+    }
+
+    console.log('Hone — Initialising...');
+
+    // Verify token before saving
+    try {
+      const client = axios.create({
+        baseURL: apiUrl,
+        headers: { Authorization: `Bearer ${token}`, 'User-Agent': `@hone-ai/cli/${pkg.version}` },
+        timeout: 10_000,
+      });
+      const r = await client.get('/scripts/config');
+      console.log(`✓ Token valid — org: ${r.data.org}, tier: ${r.data.tier}`);
+    } catch (e) {
+      console.error(`✗ Token verification failed: ${e.response?.data?.error || e.message}`);
+      process.exit(1);
+    }
+
+    // Save to ~/.honerc (mode 0600 — owner-read-only)
+    const rc = { token, api: apiUrl, savedAt: new Date().toISOString() };
+    fs.writeFileSync(RC_PATH, JSON.stringify(rc, null, 2), { mode: 0o600 });
+
+    console.log(`✓ Config saved to ${RC_PATH}`);
+    console.log(`  API: ${apiUrl}`);
+    console.log('');
+    console.log('You can now run "hone setup" in any repository.');
+  });
+
+// ── APPROVE command ────────────────────────────────────────────────────────────
+program
+  .command('approve')
+  .description('Approve a skill refresh to apply the change report')
+  .requiredOption('--job <jobId>', 'Job ID returned by "hone derive --refresh"')
+  .option('--changes <mode>',     'Which changes to apply: all (default)', 'all')
+  .action(async (opts) => {
+    const config = getConfig();
+    const client = api(config);
+
+    console.log(`Hone AI — Approving refresh job: ${opts.job}`);
+
+    // Verify job is ready
+    let jobData;
+    try {
+      const r = await client.get(`/derive/${opts.job}`);
+      jobData  = r.data;
+    } catch (e) {
+      console.error(`Failed to fetch job: ${e.response?.data?.error || e.message}`);
+      process.exit(1);
+    }
+
+    if (jobData.status !== 'complete') {
+      console.error(`Job is not ready (status: ${jobData.status}). Wait for it to finish.`);
+      process.exit(1);
+    }
+    if (!jobData.changeReport) {
+      console.error('No change report found — this may not be a refresh job.');
+      process.exit(1);
+    }
+
+    // Apply changes
+    try {
+      const r = await client.post(`/derive/${opts.job}/approve`, {
+        approvedChanges: opts.changes,
+      });
+      console.log('✓ Changes approved and applied');
+      if (r.data.skillsUpdated) console.log(`  Skills updated: ${r.data.skillsUpdated}`);
+      console.log('');
+      console.log('Run "hone sync" to pull updated skills to your local .github/skills/');
+    } catch (e) {
+      console.error(`Approval failed: ${e.response?.data?.error || e.message}`);
+      process.exit(1);
+    }
+  });
+
+// ── VERIFY command ────────────────────────────────────────────────────────────
+program
+  .command('verify')
+  .description('Verify Hone server connectivity and configuration')
+  .action(async () => {
+    const config = getConfig();
+    const client = api(config);
+
+    console.log('Hone — Server Verification');
+    console.log('================================');
+
+    try {
+      const health = await axios.get(`${config.apiUrl}/health`);
+      console.log(`✓ API health: ${health.data.status} (v${health.data.version})`);
+    } catch (e) {
+      console.error(`✗ API health: ${e.message}`);
+    }
+
+    try {
+      const cfg = await client.get('/scripts/config');
+      console.log(`✓ Auth valid: org=${cfg.data.org}, tier=${cfg.data.tier}`);
+      console.log(`  Features: ${JSON.stringify(cfg.data.features)}`);
+      console.log(`  Pipeline: v${cfg.data.pipeline.version} (${cfg.data.pipeline.stages} stages)`);
+    } catch (e) {
+      console.error(`✗ Auth check: ${e.message}`);
+    }
+
+    try {
+      await client.get('/skills/pr-review-standards');
+      console.log('✓ Enterprise skills: pr-review-standards accessible');
+    } catch (e) {
+      console.error(`✗ Enterprise skills: ${e.message}`);
+    }
+
+    console.log('');
+    console.log('Verification complete.');
+  });
+
+// ── SYNC command ──────────────────────────────────────────────────────────────
+program
+  .command('sync')
+  .description('Pull latest derived skills and agent prompts from Hone server')
+  .option('--repo <name>',     'Repository name (defaults to current directory name)')
+  .option('--skills-only',     'Only sync derived skills, skip agent prompts')
+  .option('--agents-only',     'Only sync agent prompts, skip derived skills')
+  .option('--with-learnings-report', 'Also fetch promoted-learnings report + update local YAML status (H-013)')
+  .option('--force',           'Overwrite local edits (default: skip files with local changes — H-024)')
+  .action(async (opts) => {
+    const config   = getConfig();
+    const client   = api(config);
+    const repoName = opts.repo || path.basename(process.cwd());
+    const { detectLocalEdits, formatSkipMessage } = require('./lib/sync-overwrite');
+
+    console.log(`Hone — Sync for ${repoName}`);
+
+    // H-024: collect skipped files so we can summarize at the end with the
+    // corrective action. Better one summary block than 15 separate warnings
+    // scrolling off the user's terminal.
+    const skipped = [];
+
+    /**
+     * Write a file unless local edits would be silently destroyed.
+     * Returns: 'wrote' | 'skipped' | 'created'
+     */
+    function safeWrite(absPath, relPath, serverContent) {
+      const localContent = fs.existsSync(absPath)
+        ? fs.readFileSync(absPath, 'utf8')
+        : null;
+      const { kind } = detectLocalEdits(serverContent, localContent);
+
+      if (kind === 'modified' && !opts.force) {
+        skipped.push(relPath);
+        console.log(formatSkipMessage(relPath));
+        return 'skipped';
+      }
+      // 'new' | 'identical' | 'modified'+force → write
+      fs.writeFileSync(absPath, serverContent);
+      return kind === 'new' ? 'created' : 'wrote';
+    }
+
+    // ── 1. Sync derived skills ──────────────────────────────────────────────
+    if (!opts.agentsOnly) {
+      try {
+        const r = await client.get(`/skills/${repoName}/derived`);
+        const { skills } = r.data;
+        if (!skills.length) {
+          console.log('No derived skills found. Run "hone derive" first.');
+        } else {
+          console.log(`\nSyncing ${skills.length} derived skills...`);
+          for (const skill of skills) {
+            const skillDir = path.join(process.cwd(), '.github', 'skills', skill.skill_name);
+            fs.mkdirSync(skillDir, { recursive: true });
+            const dest = path.join(skillDir, 'SKILL.md');
+            const rel = `skills/${skill.skill_name}/SKILL.md`;
+            const result = safeWrite(dest, rel, skill.content);
+            if (result !== 'skipped') console.log(`  ✓ ${rel}`);
+          }
+        }
+      } catch (e) {
+        console.error(`Skills sync failed: ${e.message}`);
+      }
+    }
+
+    // ── 2. Sync agent prompts into .github/agents/*.agent.md ───────────────
+    if (!opts.skillsOnly) {
+      const agents = [
+        'story-groomer',
+        'implementation-planner',
+        'unit-test-case-writer',
+        'e2e-qa-planner',
+        'e2e-test-spec-writer',
+        'e2e-qa-spec-healer',
+        'code-builder',
+        'code-reviewer',
+        'delivery-architect',
+      ];
+
+      console.log('\nSyncing agent prompts...');
+      const agentsDir = path.join(process.cwd(), '.github', 'agents');
+      fs.mkdirSync(agentsDir, { recursive: true });
+
+      let synced = 0;
+      for (const agent of agents) {
+        try {
+          const r = await client.get(`/prompts/${agent}`, {
+            responseType: 'text',
+            headers: { Accept: 'text/markdown' },
+          });
+          const dest = path.join(agentsDir, `${agent}.agent.md`);
+          const rel = `agents/${agent}.agent.md`;
+          const result = safeWrite(dest, rel, r.data);
+          if (result !== 'skipped') {
+            console.log(`  ✓ ${rel}`);
+            synced++;
+          }
+        } catch (e) {
+          if (e.response?.status === 404) {
+            console.log(`  ⚠ agents/${agent}.agent.md — prompt not seeded yet (run seed-agent-prompts.js)`);
+          } else {
+            console.log(`  ⚠ agents/${agent}.agent.md — ${e.message}`);
+          }
+        }
+      }
+      if (synced > 0) console.log(`\nSynced ${synced} agent prompts.`);
+
+      // Mirror to .claude/agents/ for Claude Code. This mirror is a derived
+      // copy of .github/agents/, so it's safe to overwrite — local edits
+      // belong in the source-of-truth dir. We still respect skipped files:
+      // if the source was skipped, don't overwrite the mirror either.
+      const claudeAgentsDir = path.join(process.cwd(), '.claude', 'agents');
+      const ghAgentsDir = path.join(process.cwd(), '.github', 'agents');
+      if (fs.existsSync(ghAgentsDir)) {
+        fs.mkdirSync(claudeAgentsDir, { recursive: true });
+        const files = fs.readdirSync(ghAgentsDir).filter(f => f.endsWith('.agent.md'));
+        for (const f of files) {
+          fs.copyFileSync(path.join(ghAgentsDir, f), path.join(claudeAgentsDir, f));
+        }
+        console.log(`  ✓ .claude/agents/ mirrored (${files.length} agents)`);
+      }
+    }
+
+    // ── 3. Sync copilot-instructions.md from server ──────────────────────
+    try {
+      const r = await client.get('/scripts/copilot-instructions', {
+        responseType: 'text',
+        headers: { Accept: 'text/markdown' },
+      });
+      const instrPath = path.join(process.cwd(), '.github', 'copilot-instructions.md');
+      const result = safeWrite(instrPath, 'copilot-instructions.md', r.data);
+      if (result !== 'skipped') {
+        console.log('\n  ✓ copilot-instructions.md synced from server');
+      }
+    } catch (e) {
+      console.log(`\n  ⚠ copilot-instructions.md — ${e.message}`);
+    }
+
+    // ── H-024 summary: tell the user what was skipped + how to fix ──────
+    // (placed before the CLAUDE.md block so the recap is the first thing
+    // the user sees if they scroll up after the command finishes)
+    if (skipped.length > 0) {
+      console.log('');
+      console.log(`⚠ ${skipped.length} file(s) skipped to preserve local edits:`);
+      for (const f of skipped) console.log(`    ${f}`);
+      console.log('');
+      console.log('  To upstream local additions:  hone promote');
+      console.log('  To overwrite anyway:           hone sync --force');
+    }
+
+    // ── 4. Sync CLAUDE.md from server ────────────────────────────────────
+    try {
+      const r = await client.get('/scripts/claude-md', {
+        responseType: 'text',
+        headers: { Accept: 'text/markdown' },
+      });
+      const claudePath = path.join(process.cwd(), 'CLAUDE.md');
+      if (!fs.existsSync(claudePath)) {
+        fs.writeFileSync(claudePath, r.data);
+        console.log('  ✓ CLAUDE.md synced from server');
+      } else {
+        console.log('  CLAUDE.md exists — skipping (manual merge if needed)');
+      }
+    } catch (e) {
+      console.log(`  ⚠ CLAUDE.md — ${e.message}`);
+    }
+
+    // ── 5. Promoted-learnings report (H-013, --with-learnings-report) ──
+    if (opts.withLearningsReport) {
+      try {
+        const r = await client.get(`/promoted-learnings-report?repo=${encodeURIComponent(repoName)}`);
+        const { markdown = '', entries = [] } = r.data || {};
+        const learningsRoot = path.join(process.cwd(), '.github', 'learnings');
+        fs.mkdirSync(learningsRoot, { recursive: true });
+        const reportPath = path.join(learningsRoot, 'promoted-report.md');
+        fs.writeFileSync(reportPath, markdown);
+        console.log(`\n  ✓ ${path.relative(process.cwd(), reportPath)} written`);
+
+        const { updateTopLevelStatus } = require('./lib/learnings-sync');
+        let updatedCount = 0, skippedCount = 0;
+        for (const e of entries) {
+          if (!e || !e.id || !e.status) continue;
+          // Map E13-A-L1 → E13-A (story id strips trailing -L<n>)
+          const storyId = String(e.id).replace(/-L\d+$/i, '');
+          const yamlPath = path.join(learningsRoot, `${storyId}.yml`);
+          if (!fs.existsSync(yamlPath)) {
+            console.log(`  ⚠ no local learnings file for ${storyId} — skip`);
+            skippedCount++;
+            continue;
+          }
+          const text = fs.readFileSync(yamlPath, 'utf8');
+          const result = updateTopLevelStatus(text, e.status);
+          if (result.updated) {
+            fs.writeFileSync(yamlPath, result.text);
+            console.log(`  ✓ ${storyId}.yml status → ${e.status}`);
+            updatedCount++;
+          } else {
+            console.log(`  ⚠ ${storyId}.yml — no top-level status to update`);
+            skippedCount++;
+          }
+        }
+        console.log(`  Promoted-report: ${updatedCount} updated, ${skippedCount} skipped`);
+      } catch (e) {
+        const status = e.response?.status;
+        if (status === 404 || status === 501) {
+          console.log(`\n  ⚠ Server doesn't yet support promoted-learnings-report. Skipping.`);
+        } else {
+          console.log(`\n  ⚠ promoted-learnings report fetch failed: ${e.message}`);
+        }
+      }
+    }
+  });
+
+// ── PROMOTE command ──────────────────────────────────────────────────────────
+program
+  .command('promote')
+  .description('Promote enterprise-candidate learnings from this repo to the Hone server')
+  .option('--dry-run', 'Show what would be promoted without sending')
+  .option('--auto-confirm', 'Skip the y/N prompt — for CI use only (H-004)')
+  .option('-y, --yes', 'Alias for --auto-confirm (matches hone retract syntax)')
+  .action(async (opts) => {
+    const config   = getConfig();
+    const client   = api(config);
+    const repoRoot = process.cwd();
+    const repoName = path.basename(repoRoot);
+
+    console.log('Hone AI — Learning Promotion');
+    console.log('================================');
+
+    // 1. Check consent: learnings.share_enterprise in .pipeline-config.yml
+    const configPath = path.join(repoRoot, '.github', '.pipeline-config.yml');
+    if (fs.existsSync(configPath)) {
+      const yaml = require('js-yaml');
+      const pipelineConfig = yaml.load(fs.readFileSync(configPath, 'utf8'));
+      const shareEnabled = pipelineConfig?.learnings?.share_enterprise;
+      if (!shareEnabled) {
+        console.log('');
+        console.log('  Learning sharing is not enabled for this repo.');
+        console.log('  To enable, add to .github/.pipeline-config.yml:');
+        console.log('');
+        console.log('    learnings:');
+        console.log('      share_enterprise: true');
+        console.log('');
+        return;
+      }
+    } else {
+      console.log('No .pipeline-config.yml found. Run "hone setup" first.');
+      return;
+    }
+
+    // 2. Scan .github/learnings/*.yml for eligible learnings
+    const learningsDir = path.join(repoRoot, '.github', 'learnings');
+    if (!fs.existsSync(learningsDir)) {
+      console.log('No .github/learnings/ directory found. No learnings to promote.');
+      return;
+    }
+
+    // H-035: schema-aware parser (3 active YAML schemas).
+    // See cli/lib/learnings-parse.js + .github/pipeline/H-035/.
+    const { parseLearningsFile, writeBackPromoted } = require('./lib/learnings-parse');
+    const files = fs.readdirSync(learningsDir).filter(f => f.endsWith('.yml'));
+    const eligible = [];
+    const fileSchemas = {};   // _filePath → schema (used by write-back below)
+
+    for (const file of files) {
+      try {
+        const filePath = path.join(learningsDir, file);
+        const content  = fs.readFileSync(filePath, 'utf8');
+        const result   = parseLearningsFile(content, { fileLabel: file });
+
+        if (result.parseError) {
+          console.warn(`  ⚠ ${file}: parse error — ${result.parseError.message}`);
+          continue;
+        }
+        if (result.warning) console.log(`  ⚠ ${result.warning}`);
+
+        fileSchemas[filePath] = result.schema;
+        for (const e of result.eligible) {
+          eligible.push({ ...e, _file: file, _filePath: filePath, repo_name: repoName });
+        }
+      } catch (e) {
+        console.warn(`  ⚠ ${file}: read error — ${e.message}`);
+      }
+    }
+
+    if (eligible.length === 0) {
+      console.log('No pending enterprise-candidate learnings found.');
+      console.log('Learnings need: enterprise_candidate: true + status: pending');
+      return;
+    }
+
+    // 3. Display each eligible learning
+    console.log(`\n${eligible.length} learning(s) eligible for promotion:\n`);
+    for (const l of eligible) {
+      console.log(`  ${l.id || l._file}`);
+      console.log(`    Type: ${l.type || 'unknown'} | Agent: ${l.agent || 'unknown'}`);
+      console.log(`    Enterprise summary: ${(l.enterprise_summary || '').slice(0, 120)}...`);
+      console.log('');
+    }
+
+    // 4. Confirm (or dry-run)
+    if (opts.dryRun) {
+      console.log('Dry run — no data sent. Remove --dry-run to promote.');
+      return;
+    }
+
+    // H-004: --auto-confirm (or -y/--yes alias) bypasses the y/N prompt for CI use.
+    // The consent gate at line ~1183 (share_enterprise: true) is a SEPARATE check
+    // that --auto-confirm does NOT bypass — operators must explicitly opt in.
+    const skipConfirm = opts.autoConfirm || opts.yes;
+    if (!skipConfirm) {
+      const readline = await import('readline');
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await new Promise(resolve => rl.question(`Send ${eligible.length} learning(s) to Hone server? (y/N): `, resolve));
+      rl.close();
+
+      if (!answer.match(/^[Yy]/)) {
+        console.log('Cancelled.');
+        return;
+      }
+    } else {
+      console.log(`Auto-confirm: sending ${eligible.length} learning(s) without prompt (H-004).`);
+    }
+
+    // 5. POST to /learnings/promote (enterprise_summary only — never local_summary)
+    const payload = eligible.map(l => ({
+      id: l.id || l._file,
+      repo_name: l.repo_name,
+      type: l.type,
+      agent: l.agent,
+      target_skill: l.target_skill,
+      enterprise_summary: l.enterprise_summary,
+      proposed_fix: l.proposed_fix || l.absorbed_into,
+    }));
+
+    try {
+      const r = await client.post('/learnings/promote', { learnings: payload });
+      console.log(`\n✓ ${r.data.promoted} learning(s) promoted to Hone server`);
+      console.log('  They will be reviewed by the Hone team and absorbed into enterprise skills.');
+    } catch (e) {
+      console.error(`\nPromotion failed: ${e.response?.data?.error || e.message}`);
+      console.error('Local files unchanged — safe to retry.');
+      return;
+    }
+
+    // 6. Update local YAML: status → promoted (per-schema, idempotent).
+    // Group by file so each file is read + written exactly once. H-035.
+    const promotedByFile = new Map();   // _filePath → ids[]
+    for (const l of eligible) {
+      if (!promotedByFile.has(l._filePath)) promotedByFile.set(l._filePath, []);
+      promotedByFile.get(l._filePath).push(l.id);
+    }
+    for (const [filePath, ids] of promotedByFile) {
+      try {
+        const schema = fileSchemas[filePath];
+        let content = fs.readFileSync(filePath, 'utf8');
+        content = writeBackPromoted(content, schema, ids);
+        fs.writeFileSync(filePath, content);
+        const fileName = path.basename(filePath);
+        console.log(`  ✓ ${fileName}: ${ids.length} learning(s) → promoted`);
+      } catch (e) {
+        console.warn(`  ⚠ ${path.basename(filePath)}: failed to update local file — ${e.message}`);
+      }
+    }
+
+    console.log('\nDone. Commit the updated learnings files:');
+    console.log('  git add .github/learnings/ && git commit -m "chore: promote learnings to enterprise"');
+  });
+
+// ── RETRACT command (H-023) ──────────────────────────────────────────────────
+// Two modes:
+//   1. Single retract: `hone retract <LEARNING-ID> --reason "..."`
+//   2. Batch from YAML: `hone retract --from-yaml`
+//        Scans .github/learnings/*.yml for entries with status: retracted
+//        and syncs each to the server.
+program
+  .command('retract [learningId]')
+  .description('Retract previously-promoted learnings on the Hone server')
+  .option('--reason <reason>', 'Retraction reason (required when retracting a single ID)')
+  .option('--from-yaml', 'Read all status: retracted entries from .github/learnings/*.yml')
+  .option('--dry-run', 'Show what would be retracted without sending')
+  .option('-y, --yes', 'Skip confirmation prompt')
+  .action(async (learningId, opts) => {
+    const config   = getConfig();
+    const client   = api(config);
+    const repoRoot = process.cwd();
+    const repoName = path.basename(repoRoot);
+
+    console.log('Hone AI — Learning Retraction');
+    console.log('================================');
+
+    const payload = [];
+
+    if (opts.fromYaml) {
+      // Batch mode: scan .github/learnings/*.yml for retracted entries
+      const learningsDir = path.join(repoRoot, '.github', 'learnings');
+      if (!fs.existsSync(learningsDir)) {
+        console.log('No .github/learnings/ directory found — nothing to retract.');
+        return;
+      }
+      const yaml = require('js-yaml');
+      const files = fs.readdirSync(learningsDir).filter(f => f.endsWith('.yml'));
+      for (const file of files) {
+        try {
+          const parsed = yaml.load(fs.readFileSync(path.join(learningsDir, file), 'utf8'));
+          const entries = Array.isArray(parsed) ? parsed : [parsed];
+          for (const entry of entries) {
+            if (entry?.status === 'retracted' && entry.id) {
+              payload.push({
+                id: entry.id,
+                repo_name: repoName,
+                reason: entry.retraction_reason || 'Retracted (no reason provided in YAML)',
+              });
+            }
+          }
+        } catch (e) {
+          console.warn(`  ⚠ ${file}: parse error — ${e.message}`);
+        }
+      }
+      if (payload.length === 0) {
+        console.log('No retracted entries found in .github/learnings/*.yml.');
+        console.log('To retract a learning, set status: retracted + retraction_reason in its YAML entry.');
+        return;
+      }
+    } else if (learningId) {
+      // Single mode: command-line ID + --reason
+      if (!opts.reason) {
+        console.error('Error: --reason "..." is required when retracting a single learning.');
+        process.exit(1);
+      }
+      payload.push({
+        id: learningId,
+        repo_name: repoName,
+        reason: opts.reason,
+      });
+    } else {
+      console.error('Error: provide either a <LEARNING-ID> with --reason, or --from-yaml.');
+      console.error('Examples:');
+      console.error('  hone retract E18-A-L2 --reason "dup-of E20-A-L1 (canonical)"');
+      console.error('  hone retract --from-yaml');
+      process.exit(1);
+    }
+
+    // Display
+    console.log(`\n${payload.length} learning(s) to retract:\n`);
+    for (const p of payload) {
+      console.log(`  ${p.id}`);
+      console.log(`    Reason: ${p.reason.slice(0, 120)}${p.reason.length > 120 ? '...' : ''}`);
+    }
+    console.log('');
+
+    if (opts.dryRun) {
+      console.log('Dry run — no data sent. Remove --dry-run to retract.');
+      return;
+    }
+
+    // Confirm unless --yes
+    if (!opts.yes) {
+      const readline = await import('readline');
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await new Promise(resolve =>
+        rl.question(`Retract ${payload.length} learning(s) on Hone server? (y/N): `, resolve)
+      );
+      rl.close();
+      if (!answer.match(/^[Yy]/)) {
+        console.log('Cancelled.');
+        return;
+      }
+    }
+
+    // POST to /learnings/retract
+    try {
+      const r = await client.post('/learnings/retract', { learnings: payload });
+      console.log(`\n✓ ${r.data.retracted} learning(s) retracted on Hone server.`);
+      if (r.data.skipped && r.data.skipped.length) {
+        console.log(`\n⚠ ${r.data.skipped.length} skipped:`);
+        for (const s of r.data.skipped) {
+          console.log(`  - ${s.id || '<no id>'}: ${s.why}`);
+        }
+      }
+      console.log('  Retracted entries will be excluded from the next enterprise skill rebuild.');
+    } catch (e) {
+      console.error(`\nRetraction failed: ${e.response?.data?.error || e.message}`);
+      console.error('Local files unchanged — safe to retry.');
+      process.exit(1);
+    }
+  });
+
+// ── ADOPT command (all-in-one: setup + derive + sync) ────────────────────────
+program
+  .command('adopt')
+  .description('Full pipeline adoption: setup + derive + sync in one command')
+  .option('--install-tests',   'Install unit test framework')
+  .option('--e2e',             'Install Playwright E2E framework')
+  .option('--no-e2e',          'Skip Playwright')
+  .option('--non-interactive', 'Use defaults without prompting')
+  .option('--max-files <n>',   'Max source files for derive (default: 15)', '15')
+  .option('--skip-derive',     'Skip the derive step (setup + sync only)')
+  .action(async (opts) => {
+    const startTime = Date.now();
+
+    console.log('');
+    console.log('╔══════════════════════════════════════════════╗');
+    console.log('║     Hone AI — Full Pipeline Adoption         ║');
+    console.log('║     setup → derive → sync                    ║');
+    console.log('╚══════════════════════════════════════════════╝');
+    console.log('');
+
+    // ── Step 1: Setup ─────────────────────────────────────────
+    console.log('━━━ Step 1/3: Pipeline Setup ━━━━━━━━━━━━━━━━━━');
+    console.log('');
+    try {
+      // Execute setup command programmatically
+      const setupArgs = ['setup'];
+      if (opts.nonInteractive) setupArgs.push('--non-interactive');
+      if (opts.installTests)   setupArgs.push('--install-tests');
+      if (opts.e2e !== false)  setupArgs.push('--e2e');
+      if (opts.noE2e)          setupArgs.push('--no-e2e');
+
+      const { execSync: ex } = require('child_process');
+      const cliPath = __filename;
+      const setupCmd = `node "${cliPath}" ${setupArgs.join(' ')}`;
+      ex(setupCmd, { stdio: 'inherit', cwd: process.cwd(), env: process.env });
+    } catch (e) {
+      console.error('Setup failed:', e.message);
+      process.exit(1);
+    }
+
+    // ── Step 2: Derive domain skills ──────────────────────────
+    if (!opts.skipDerive) {
+      console.log('');
+      console.log('━━━ Step 2/3: Derive Domain Skills ━━━━━━━━━━━━');
+      console.log('');
+      try {
+        const { execSync: ex } = require('child_process');
+        const cliPath = __filename;
+        const deriveCmd = `node "${cliPath}" derive --max-files ${opts.maxFiles}`;
+        ex(deriveCmd, { stdio: 'inherit', cwd: process.cwd(), env: process.env, timeout: 600_000 });
+      } catch (e) {
+        console.warn('');
+        console.warn('⚠ Derive failed (non-fatal):', e.message?.slice(0, 100));
+        console.warn('  You can run "hone derive" later to generate domain skills.');
+        console.warn('  The pipeline works with enterprise baseline skills.');
+      }
+    } else {
+      console.log('');
+      console.log('━━━ Step 2/3: Derive — skipped (--skip-derive) ━━');
+    }
+
+    // ── Step 3: Sync agent prompts + copilot-instructions ─────
+    console.log('');
+    console.log('━━━ Step 3/3: Sync Prompts ━━━━━━━━━━━━━━━━━━━━');
+    console.log('');
+    try {
+      const { execSync: ex } = require('child_process');
+      const cliPath = __filename;
+      ex(`node "${cliPath}" sync`, { stdio: 'inherit', cwd: process.cwd(), env: process.env });
+    } catch (e) {
+      console.warn('⚠ Sync failed:', e.message);
+    }
+
+    // ── H-018: Post-adopt pattern detection summary ───────────
+    // Tells the adopter what we detected vs what was written, so
+    // mismatches surface immediately instead of silently breaking
+    // Gate 3 / Pizza Tracker on the first PR.
+    try {
+      const { execSync: ex } = require('child_process');
+      const cliPath = __filename;
+      console.log('');
+      console.log('━━━ Pattern detection (H-018) ━━━━━━━━━━━━━━━━━━');
+      console.log('');
+      ex(`node "${cliPath}" check-patterns`, { stdio: 'inherit', cwd: process.cwd(), env: process.env });
+    } catch (e) {
+      // Exit 1 from check-patterns means drift detected — the user
+      // already saw the table, so just note that adoption succeeded
+      // but config needs review. Don't fail adoption itself.
+      console.warn('');
+      console.warn('  ↑ Patterns above drift from detected conventions — review .pipeline-config.yml.');
+    }
+
+    // ── Summary ───────────────────────────────────────────────
+    const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+    console.log('');
+    console.log('╔══════════════════════════════════════════════╗');
+    console.log('║     ✅ Pipeline Adoption Complete             ║');
+    console.log(`║     Time: ${elapsed}s                              ║`);
+    console.log('╚══════════════════════════════════════════════╝');
+    console.log('');
+    console.log('  Your repo now has:');
+    console.log('    • 9 agents (.github/agents/ + .claude/agents/)');
+    console.log('    • 11 enterprise skills + domain skills');
+    console.log('    • CI workflow (ai-review.yml)');
+    console.log('    • CLAUDE.md + copilot-instructions.md');
+    console.log('    • Metrics + learnings + docs infrastructure');
+    console.log('');
+    console.log('  Next steps:');
+    console.log('    1. git add -A && git commit -m "feat: adopt Hone AI pipeline"');
+    console.log('    2. Open Claude Code or VS Code Copilot');
+    console.log('    3. Say: "Run the SDLC pipeline for: [feature description]"');
+    console.log('');
+    // H-012 (#21): surface `hone tests organize` so teams actually run it.
+    // Discovery-only — the command itself has existed since H-020 era.
+    console.log('  (Recommended) Curate your regression suite:');
+    console.log('    hone tests organize     # group test files by story-id; flag orphans');
+    console.log('');
+  });
+
+// ── AUDIT command (H-020) ────────────────────────────────────────────────────
+program
+  .command('audit')
+  .description('Score every story under .github/pipeline/ for SDLC compliance')
+  .option('--fail-if-incomplete', 'Exit 1 if any story is INCOMPLETE or EMPTY (use in CI)')
+  .option('--format <fmt>', 'Output format: table | json', 'table')
+  .option('--story <id>', 'Audit a single story (e.g. E20-A) instead of all')
+  .action((opts) => {
+    const { auditPipeline, renderTable } = require('./lib/audit');
+    const repoRoot = process.cwd();
+    const pipelineDir = path.join(repoRoot, '.github', 'pipeline');
+
+    if (!fs.existsSync(pipelineDir)) {
+      console.error('No .github/pipeline/ directory found. Run `hone adopt` first.');
+      process.exit(1);
+    }
+
+    const stories = [];
+    for (const entry of fs.readdirSync(pipelineDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const storyDir = path.join(pipelineDir, entry.name);
+      const files = fs
+        .readdirSync(storyDir, { withFileTypes: true })
+        .filter((f) => f.isFile())
+        .map((f) => f.name);
+      stories.push({ storyId: entry.name, files });
+    }
+    stories.sort((a, b) => a.storyId.localeCompare(b.storyId));
+
+    // Optional override of required steps via .pipeline-config.yml.
+    let requiredSteps;
+    const cfgPath = path.join(repoRoot, '.github', '.pipeline-config.yml');
+    if (fs.existsSync(cfgPath)) {
+      try {
+        const yaml = require('js-yaml');
+        const cfg = yaml.load(fs.readFileSync(cfgPath, 'utf8')) || {};
+        if (Array.isArray(cfg.pipeline?.required_steps)) {
+          requiredSteps = cfg.pipeline.required_steps;
+        }
+      } catch {
+        // Bad config — fall back to defaults silently.
+      }
+    }
+
+    const audit = auditPipeline(stories, { story: opts.story, requiredSteps });
+
+    if (opts.format === 'json') {
+      console.log(JSON.stringify(audit, null, 2));
+    } else {
+      console.log(renderTable(audit));
+    }
+
+    const hasFailures = audit.summary.incomplete > 0 || audit.summary.empty > 0;
+    if (opts.failIfIncomplete && hasFailures) {
+      process.exit(1);
+    }
+    process.exit(0);
+  });
+
+// ── CHECK-PATTERNS command (H-018) ───────────────────────────────────────────
+// Detects whether the inlined story-ID + E2E-spec regexes in
+// .pipeline-config.yml match the conventions this repo actually uses.
+// Catches the silent-Gate-3 failure mode for non-TS-Playwright stacks.
+program
+  .command('check-patterns')
+  .description('Verify .pipeline-config.yml regexes match the repo\'s actual story-ID + E2E conventions (H-018)')
+  .option('--json', 'Emit machine-readable JSON instead of pretty output')
+  .action((opts) => {
+    const { detectStoryIdShape, detectE2EConvention, checkPatternDrift } = require('./lib/auto-detect');
+    const repoRoot = process.cwd();
+
+    // ── Collect filesystem signals ───────────────────────────────
+    const branchSamples = [];
+    try {
+      const out = execSync('git for-each-ref --sort=-committerdate --count=30 --format=%(refname:short) refs/heads/ refs/remotes/', {
+        cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      branchSamples.push(...out.split('\n').filter(Boolean));
+    } catch { /* not a git repo — skip */ }
+
+    const pipelineDir = path.join(repoRoot, '.github', 'pipeline');
+    if (fs.existsSync(pipelineDir)) {
+      try {
+        for (const e of fs.readdirSync(pipelineDir, { withFileTypes: true })) {
+          if (e.isDirectory()) branchSamples.push(e.name);
+        }
+      } catch { /* ignore */ }
+    }
+
+    const hasPyproject = fs.existsSync(path.join(repoRoot, 'pyproject.toml'));
+    const hasRequirements = fs.existsSync(path.join(repoRoot, 'requirements.txt'));
+    let hasPlaywrightDep = false;
+    const pkgJsonPath = path.join(repoRoot, 'package.json');
+    if (fs.existsSync(pkgJsonPath)) {
+      try {
+        const pj = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+        const deps = { ...(pj.dependencies || {}), ...(pj.devDependencies || {}) };
+        hasPlaywrightDep = '@playwright/test' in deps || 'playwright' in deps;
+      } catch { /* ignore */ }
+    }
+    const testsDir = fs.existsSync(path.join(repoRoot, 'tests'));
+    const testDir = fs.existsSync(path.join(repoRoot, 'test'));
+
+    const sampleE2EFiles = [];
+    for (const d of ['tests/e2e', 'test/e2e']) {
+      const full = path.join(repoRoot, d);
+      if (fs.existsSync(full)) {
+        try {
+          for (const f of fs.readdirSync(full, { withFileTypes: true })) {
+            if (f.isFile()) sampleE2EFiles.push(f.name);
+          }
+        } catch { /* ignore */ }
+      }
+    }
+
+    // ── Run detection ────────────────────────────────────────────
+    const story = detectStoryIdShape(branchSamples);
+    const e2e = detectE2EConvention({
+      hasPyproject, hasRequirements, hasPlaywrightDep, testsDir, testDir, sampleE2EFiles,
+    });
+    const recommended = { story, e2e };
+
+    // ── Read configured patterns ─────────────────────────────────
+    const cfgPath = path.join(repoRoot, '.github', '.pipeline-config.yml');
+    let configured = null;
+    if (fs.existsSync(cfgPath)) {
+      try {
+        const yaml = require('js-yaml');
+        const cfg = yaml.load(fs.readFileSync(cfgPath, 'utf8')) || {};
+        configured = {
+          story_id_pattern: cfg.ci?.story_id_pattern,
+          e2e_spec_pattern: cfg.ci?.e2e_spec_pattern,
+        };
+      } catch { /* malformed — leave configured null */ }
+    }
+
+    const drift = checkPatternDrift({ configured, recommended });
+    const result = { configured, recommended, drift };
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log('Pattern detection:');
+      console.log(`  Story ID:  ${story.shape} (${story.confidence} confidence) → ${story.pattern}`);
+      if (story.samples.length) console.log(`             samples: ${story.samples.join(', ')}`);
+      console.log(`  E2E spec:  ${e2e.framework} under ${e2e.dir}/e2e/ (${e2e.confidence} confidence) → ${e2e.pattern}`);
+      console.log('');
+      if (!configured) {
+        console.log('No .github/.pipeline-config.yml found — run `hone setup` first.');
+        process.exit(2);
+      }
+      console.log('Configured (.pipeline-config.yml):');
+      console.log(`  story_id_pattern: ${configured.story_id_pattern || '(unset)'}`);
+      console.log(`  e2e_spec_pattern: ${configured.e2e_spec_pattern || '(unset)'}`);
+      console.log('');
+      if (drift.status === 'ok') {
+        console.log('✓ Patterns match detected conventions.');
+      } else {
+        console.log(`✗ Drift: ${drift.reason}`);
+        for (const f of drift.findings) {
+          console.log(`  • ${f.key}`);
+          console.log(`      configured:  ${f.configured}`);
+          console.log(`      recommended: ${f.recommended}`);
+          console.log(`      reason:      ${f.reason}`);
+        }
+        console.log('');
+        console.log(`  Suggested fix: ${drift.suggestedFix}`);
+      }
+    }
+    process.exit(drift.status === 'drift' ? 1 : 0);
+  });
+
+// ── DOCTOR command (H-017) ───────────────────────────────────────────────────
+// Health checks for the adopter repo. First subcheck: docs freshness (catches
+// drifted README test-count badges). Future subchecks (H-018, H-021) plug into
+// the same `--check <name>` switch.
+program
+  .command('doctor')
+  .description('Run health checks on this repo (docs freshness, etc.)')
+  .option('--check <name>', 'Run only one named check (default: all)', 'all')
+  .option('--json', 'Emit machine-readable JSON instead of pretty output')
+  .option('--lookback <n>', 'commits to scan for admin-merge check (HC-005-A; default: 50)', '50')
+  .action(async (opts) => {
+    const repoRoot = process.cwd();
+    const results = [];
+
+    // Read .pipeline-config.yml to learn the stack
+    let stack = 'unknown';
+    try {
+      const yaml = require('js-yaml');
+      const cfgPath = path.join(repoRoot, '.github', '.pipeline-config.yml');
+      if (fs.existsSync(cfgPath)) {
+        const cfg = yaml.load(fs.readFileSync(cfgPath, 'utf8'));
+        stack = cfg?.stack?.primary || cfg?.stack?.language || 'unknown';
+      }
+    } catch {}
+
+    if (opts.check === 'all' || opts.check === 'docs') {
+      const {
+        checkDocsFreshness,
+        testCounterCommand,
+        parseTestCount,
+      } = require('./lib/doctor-docs');
+
+      const readmePath = path.join(repoRoot, 'README.md');
+      const readmeText = fs.existsSync(readmePath)
+        ? fs.readFileSync(readmePath, 'utf8')
+        : null;
+
+      // Try to count tests for this stack
+      let actualTestCount = null;
+      const counterCmd = testCounterCommand(stack);
+      if (counterCmd) {
+        try {
+          const stdout = execSync(counterCmd, {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            timeout: 60_000,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          });
+          actualTestCount = parseTestCount(stack, stdout);
+        } catch {
+          // Test runner failed — leave actualTestCount null; helper returns 'skip'
+        }
+      }
+
+      const result = checkDocsFreshness({ readmeText, actualTestCount });
+      results.push({ name: 'docs', stack, ...result });
+    }
+
+    // HC-002: admin-merge anti-pattern check (per E13-A-L3)
+    // HC-005-A: --lookback CLI plumbing with explicit validation
+    if (opts.check === 'all' || opts.check === 'admin-merge') {
+      const { checkAdminMerge } = require('./lib/doctor-admin-merge');
+      const parsedLookback = parseInt(opts.lookback, 10);
+      if (!Number.isFinite(parsedLookback) || parsedLookback <= 0) {
+        console.error(`✗ --lookback must be a positive integer; got "${opts.lookback}"`);
+        process.exit(2);
+      }
+      results.push(checkAdminMerge({ repoRoot, lookback: parsedLookback }));
+    }
+
+    // HC-002: bind-default check (per E13-A-L1; security-flagged per SC-006-L1)
+    if (opts.check === 'all' || opts.check === 'bind-default') {
+      const { checkBindDefault } = require('./lib/doctor-bind-default');
+      results.push(checkBindDefault({ repoRoot }));
+    }
+
+    // HC-002: unsubstituted placeholder check (per E21-A-L1)
+    if (opts.check === 'all' || opts.check === 'placeholders') {
+      const { checkPlaceholders } = require('./lib/doctor-placeholders');
+      results.push(checkPlaceholders({ repoRoot }));
+    }
+
+    // HC-002: skill staleness check (per E16-A-L4; mirrors hone check-refresh)
+    if (opts.check === 'all' || opts.check === 'skill-staleness') {
+      const { checkSkillStaleness } = require('./lib/doctor-skill-staleness');
+      results.push(checkSkillStaleness({ repoRoot }));
+    }
+
+    // Render
+    if (opts.json) {
+      console.log(JSON.stringify({ checks: results }, null, 2));
+    } else {
+      console.log('Hone Doctor — Repo Health');
+      console.log('==========================');
+      for (const r of results) {
+        // HC-005-A: distinguish info (ℹ) from warn/skip (⚠)
+        const icon = r.status === 'ok' ? '✓'
+          : r.status === 'drift' ? '✗'
+          : r.status === 'info' ? 'ℹ'
+          : '⚠';
+        const label = r.name === 'docs' ? 'Docs freshness' : r.name;
+        console.log(`${icon} ${label} — ${r.reason}`);
+        if (r.suggestedFix) {
+          console.log(`  Fix: ${r.suggestedFix}`);
+        }
+      }
+    }
+
+    // Exit non-zero if any check is in 'drift' state — useful in CI.
+    const failed = results.some((r) => r.status === 'drift');
+    process.exit(failed ? 1 : 0);
+  });
+
+// ── TESTS ORGANIZE command ───────────────────────────────────────────────────
+// ── TESTS ORGANIZE command ───────────────────────────────────────────────────
+program
+  .command('tests')
+  .argument('<action>', 'Action: organize')
+  .description('Organize existing test files into the regression suite structure')
+  .option('--dry-run', 'Show what would be moved without moving')
+  .action(async (action, opts) => {
+    if (action !== 'organize') {
+      console.error(`Unknown action: ${action}. Available: organize`);
+      process.exit(1);
+    }
+
+    const repoRoot = process.cwd();
+    console.log('Hone AI — Test Suite Organizer');
+    console.log('================================');
+    console.log('');
+
+    // 1. Ensure regression dirs exist
+    const e2eRoot = path.join(repoRoot, 'e2e');
+    for (const dir of ['smoke', 'regression', 'api', 'story']) {
+      fs.mkdirSync(path.join(e2eRoot, dir), { recursive: true });
+    }
+
+    // 2. Scan for existing spec files across common locations
+    const specFiles = [];
+    const scanDirs = [
+      'e2e', 'test/e2e', 'tests/e2e', 'test', 'tests',
+      'src/__tests__/e2e', 'src/__tests__/integration',
+    ];
+
+    for (const dir of scanDirs) {
+      const fullDir = path.join(repoRoot, dir);
+      if (!fs.existsSync(fullDir)) continue;
+      scanForSpecs(fullDir, repoRoot, specFiles);
+    }
+
+    // Filter out files already in organized dirs
+    const organized = specFiles.filter(f =>
+      !f.relPath.startsWith('e2e/smoke/') &&
+      !f.relPath.startsWith('e2e/regression/') &&
+      !f.relPath.startsWith('e2e/api/') &&
+      !f.relPath.startsWith('e2e/story/')
+    );
+
+    if (organized.length === 0) {
+      console.log('No unorganized spec files found.');
+      console.log('Spec files already in e2e/smoke/, e2e/regression/, e2e/api/, or e2e/story/ are considered organized.');
+      return;
+    }
+
+    // 3. Classify each file
+    const classified = organized.map(f => classifySpec(f, repoRoot));
+
+    // 4. Display plan
+    const browser = classified.filter(c => c.type === 'BROWSER');
+    const apiTests = classified.filter(c => c.type === 'API');
+    const hybrid = classified.filter(c => c.type === 'HYBRID');
+    const unknown = classified.filter(c => c.type === 'UNKNOWN');
+
+    console.log(`Found ${classified.length} spec files to organize:\n`);
+
+    if (browser.length > 0) {
+      console.log(`  BROWSER tests (${browser.length}):`);
+      for (const c of browser) {
+        console.log(`    ${c.relPath}`);
+        console.log(`      → ${c.destination}${c.smoke ? ' (+ @smoke)' : ''}`);
+      }
+      console.log('');
+    }
+
+    if (apiTests.length > 0) {
+      console.log(`  API tests (${apiTests.length}):`);
+      for (const c of apiTests) {
+        console.log(`    ${c.relPath}`);
+        console.log(`      → ${c.destination}`);
+      }
+      console.log('');
+    }
+
+    if (hybrid.length > 0) {
+      console.log(`  HYBRID tests (${hybrid.length}):`);
+      for (const c of hybrid) {
+        console.log(`    ${c.relPath}`);
+        console.log(`      → ${c.destination}`);
+      }
+      console.log('');
+    }
+
+    if (unknown.length > 0) {
+      console.log(`  UNCLASSIFIED (${unknown.length}) — needs manual review:`);
+      for (const c of unknown) {
+        console.log(`    ${c.relPath}`);
+        console.log(`      → ${c.destination} (best guess)`);
+      }
+      console.log('');
+    }
+
+    if (opts.dryRun) {
+      console.log('Dry run — no files moved. Remove --dry-run to organize.');
+      return;
+    }
+
+    // 5. Confirm
+    const readline = await import('readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise(resolve =>
+      rl.question(`Move ${classified.length} file(s) to regression structure? (y/N): `, resolve)
+    );
+    rl.close();
+
+    if (!answer.match(/^[Yy]/)) {
+      console.log('Cancelled.');
+      return;
+    }
+
+    // 6. Move files
+    let moved = 0;
+    const smokeSpecs = [];
+    for (const c of classified) {
+      const src = path.join(repoRoot, c.relPath);
+      const dst = path.join(repoRoot, c.destination);
+      fs.mkdirSync(path.dirname(dst), { recursive: true });
+      fs.renameSync(src, dst);
+      console.log(`  ✓ ${c.relPath} → ${c.destination}`);
+      moved++;
+      if (c.smoke) smokeSpecs.push(c.destination);
+    }
+
+    // 7. Copy smoke candidates
+    for (const spec of smokeSpecs) {
+      const src = path.join(repoRoot, spec);
+      const smokeDst = path.join(e2eRoot, 'smoke', path.basename(spec));
+      if (!fs.existsSync(smokeDst)) {
+        fs.copyFileSync(src, smokeDst);
+        console.log(`  ✓ ${path.basename(spec)} → e2e/smoke/ (@smoke)`);
+      }
+    }
+
+    // 8. Update regression manifest
+    const manifestPath = path.join(e2eRoot, 'regression-manifest.yml');
+    if (fs.existsSync(manifestPath)) {
+      try {
+        const yaml = require('js-yaml');
+        const manifest = yaml.load(fs.readFileSync(manifestPath, 'utf8'));
+        manifest.last_updated = new Date().toISOString();
+        manifest.total_specs = (manifest.total_specs || 0) + moved;
+        manifest.smoke_count = (manifest.smoke_count || 0) + smokeSpecs.length;
+        if (!manifest.promotion_history) manifest.promotion_history = [];
+        manifest.promotion_history.push({
+          action: 'organize',
+          files_moved: moved,
+          smoke_added: smokeSpecs.length,
+          organized_at: new Date().toISOString(),
+        });
+        fs.writeFileSync(manifestPath, yaml.dump(manifest, { flowLevel: 3, sortKeys: false }));
+        console.log(`  ✓ regression-manifest.yml updated (${moved} specs, ${smokeSpecs.length} smoke)`);
+      } catch (e) {
+        console.warn(`  ⚠ manifest update failed: ${e.message}`);
+      }
+    }
+
+    console.log(`\nDone: ${moved} files organized.`);
+    console.log('  git add e2e/ && git commit -m "chore: organize test suite into regression structure"');
+  });
+
+// ── Test organizer helpers ───────────────────────────────────────────────────
+
+function scanForSpecs(dir, repoRoot, results) {
+  const SPEC_PATTERN = /\.(spec|test)\.(js|jsx|ts|tsx)$/;
+  const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'coverage']);
+
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (SKIP.has(entry.name)) continue;
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        scanForSpecs(fullPath, repoRoot, results);
+      } else if (SPEC_PATTERN.test(entry.name)) {
+        results.push({
+          fullPath,
+          relPath: path.relative(repoRoot, fullPath),
+          name: entry.name,
+        });
+      }
+    }
+  } catch {}
+}
+
+function classifySpec(file, repoRoot) {
+  let content = '';
+  try { content = fs.readFileSync(file.fullPath, 'utf8'); } catch { }
+
+  const hasPage = /page\.(goto|click|locator|fill|waitFor|getBy)/.test(content);
+  const hasRequest = /request\.(get|post|put|delete|patch)\(/.test(content);
+  const hasExpectResponse = /response\.(status|json|ok|body)/.test(content) ||
+                            /expect\(resp/.test(content);
+
+  // Detect type
+  let type = 'UNKNOWN';
+  if (hasPage && (hasRequest || hasExpectResponse)) type = 'HYBRID';
+  else if (hasPage) type = 'BROWSER';
+  else if (hasRequest || hasExpectResponse) type = 'API';
+  else if (/import.*playwright|from.*@playwright/.test(content)) type = 'BROWSER';
+  else if (/import.*supertest|from.*supertest/.test(content)) type = 'API';
+
+  // Detect module from filename or content
+  // Detect module — filename takes priority over content, most specific first
+  let module = 'general';
+  const name = file.name.toLowerCase();
+  const contentLower = content.toLowerCase();
+
+  // Pass 1: check filename (strongest signal)
+  if (/auth|login|signup|oauth|session/.test(name)) module = 'auth';
+  else if (/trade|order|execution/.test(name)) module = 'trading';
+  else if (/position|portfolio|pnl|p&l/.test(name)) module = 'portfolio';
+  else if (/alert|notification/.test(name)) module = 'alerts';
+  else if (/dashboard|widget|overview/.test(name)) module = 'dashboard';
+  else if (/scanner|scan|market/.test(name)) module = 'market';
+  else if (/setting|config|preference/.test(name)) module = 'settings';
+
+  // Pass 2: fallback to content (if filename didn't match)
+  if (module === 'general') {
+    if (/login|authenticate|sign.?in/.test(contentLower)) module = 'auth';
+    else if (/trading|order|execute/.test(contentLower)) module = 'trading';
+    else if (/portfolio/.test(contentLower)) module = 'portfolio';
+    else if (/alert|notification/.test(contentLower)) module = 'alerts';
+    else if (/dashboard/.test(contentLower)) module = 'dashboard';
+    else if (/market|scanner/.test(contentLower)) module = 'market';
+  }
+
+  // Determine destination
+  let destination;
+  if (type === 'API') {
+    destination = `e2e/api/${file.name}`;
+  } else {
+    destination = `e2e/regression/${module}/${file.name}`;
+  }
+
+  // Smoke candidate: login, auth, critical navigation, app loads
+  const smoke = /login|auth|app.load|critical|smoke|health/.test(name) ||
+                /login|authenticate/.test(contentLower);
+
+  return { ...file, type, module, destination, smoke };
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function bundleDirectory(dir, root, files, maxFiles, currentCount) {
+  if (currentCount >= maxFiles) return;
+  const EXTENSIONS = /\.(js|ts|jsx|tsx|java|py|cs|cls|trigger|lwc|html|css|yml|yaml|json|xml|md)$/;
+  const SKIP_DIRS  = new Set(['node_modules', '.git', '.github', 'dist', 'build', 'coverage', '__pycache__', '.venv', 'target']);
+
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (Object.keys(files).length >= maxFiles) break;
+      if (SKIP_DIRS.has(entry.name)) continue;
+      const fullPath = path.join(dir, entry.name);
+      const relPath  = path.relative(root, fullPath);
+
+      if (entry.isDirectory()) {
+        bundleDirectory(fullPath, root, files, maxFiles, Object.keys(files).length);
+      } else if (EXTENSIONS.test(entry.name)) {
+        try {
+          const content = fs.readFileSync(fullPath, 'utf8');
+          if (content.length < 50_000) { // skip very large files
+            files[relPath] = content;
+          }
+        } catch {} // skip unreadable files
+      }
+    }
+  } catch {} // skip unreadable directories
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+// ── STATUS command (H-009) ────────────────────────────────────────────────────
+// Show pipeline state for a story (or use --all for every in-flight story).
+// Reads .github/pipeline/<STORY-ID>/metadata.yml + filesystem; uses
+// filesystem as source of truth on metadata-vs-reality disagreement (AC-5).
+// Pure helpers in cli/lib/pipeline-status.js — this command is the I/O shell.
+program
+  .command('status [storyId]')
+  .description('Show pipeline state for a story (or use --all for every in-flight story)')
+  .option('--all', 'List every in-flight story under .github/pipeline/')
+  .action(async (storyIdArg, opts) => {
+    const ps = require('./lib/pipeline-status');
+    const repoRoot = process.cwd();
+    const pipelineRoot = path.join(repoRoot, '.github', 'pipeline');
+
+    if (!fs.existsSync(pipelineRoot)) {
+      console.log('No pipeline state — run `hone setup` first.');
+      process.exit(0);
+    }
+
+    if (opts.all) {
+      const dirs = fs.readdirSync(pipelineRoot, { withFileTypes: true })
+        .filter(d => d.isDirectory()).map(d => d.name);
+      if (dirs.length === 0) {
+        console.log('No in-flight stories under .github/pipeline/');
+        process.exit(0);
+      }
+      const rows = [];
+      for (const sid of dirs) {
+        const metaPath = path.join(pipelineRoot, sid, 'metadata.yml');
+        if (!fs.existsSync(metaPath)) {
+          rows.push({ storyId: sid, branch: '(no metadata.yml)', summary: 'no metadata' });
+          continue;
+        }
+        const parsed = ps.parseMetadata(fs.readFileSync(metaPath, 'utf8'));
+        if (parsed.error) {
+          rows.push({ storyId: sid, branch: '?', summary: 'metadata.yml malformed' });
+          continue;
+        }
+        const presence = {};
+        for (const [k, fname] of Object.entries(ps.STEP_FILE_MAP)) {
+          presence[k] = fs.existsSync(path.join(pipelineRoot, sid, fname));
+        }
+        rows.push(ps.summarizeForAll(parsed, presence));
+      }
+      console.log('');
+      console.log(`${rows.length} pipeline ${rows.length === 1 ? 'story' : 'stories'}:`);
+      console.log('');
+      for (const r of rows) {
+        console.log(`  ${(r.storyId || '?').padEnd(8)} ${(r.summary || '').padEnd(45)} ${r.branch || ''}`);
+      }
+      console.log('');
+      process.exit(0);
+    }
+
+    // Single-story mode — derive STORY-ID if not passed
+    let storyId = storyIdArg;
+    if (!storyId) {
+      try {
+        const branch = execSync('git symbolic-ref --short HEAD', { encoding: 'utf8' }).trim();
+        storyId = ps.extractStoryIdFromBranch(branch);
+        if (!storyId) {
+          console.error(`Could not derive STORY-ID from branch '${branch}'.`);
+          console.error('Pass STORY-ID explicitly or use `hone status --all`.');
+          process.exit(1);
+        }
+      } catch (e) {
+        console.error('Not a git repo or git unavailable. Pass STORY-ID explicitly.');
+        process.exit(1);
+      }
+    }
+
+    const storyDir = path.join(pipelineRoot, storyId);
+    if (!fs.existsSync(storyDir)) {
+      console.error(`No story ${storyId} — checked ${storyDir}`);
+      console.error('Start with Step 0 (Story Groomer) or check the STORY-ID.');
+      process.exit(1);
+    }
+
+    const metaPath = path.join(storyDir, 'metadata.yml');
+    if (!fs.existsSync(metaPath)) {
+      console.error(`No metadata.yml in ${storyDir} — run Step 0 (Story Groomer).`);
+      process.exit(1);
+    }
+
+    const parsed = ps.parseMetadata(fs.readFileSync(metaPath, 'utf8'));
+    if (parsed.error) {
+      console.error(`metadata.yml is malformed (${parsed.error}): ${parsed.message || ''}`);
+      console.error('Fix the YAML and re-run.');
+      process.exit(1);
+    }
+
+    const presence = {};
+    for (const [k, fname] of Object.entries(ps.STEP_FILE_MAP)) {
+      presence[k] = fs.existsSync(path.join(storyDir, fname));
+    }
+
+    const states = ps.computeStepStates(parsed, presence);
+    const next = ps.findNextIncompleteStep(states);
+
+    console.log('');
+    console.log(`Story:  ${parsed.storyId} — ${parsed.title || '(no title)'}`);
+    console.log(`Branch: ${parsed.branch || '(unknown)'}`);
+    console.log(`Current step: ${next ? next.displayName : 'pipeline complete 🎉'}`);
+    console.log('');
+    console.log('Pipeline artifacts:');
+    for (const s of states) {
+      const pathStr = `(${path.join('.github/pipeline', storyId, s.artifactPath)})`;
+      console.log(`  ${s.icon} ${s.displayName.padEnd(28)} ${pathStr}`);
+    }
+
+    // Optional sidecar files
+    const learningsRel = path.join('.github/learnings', `${storyId}.yml`);
+    const metricsRel = path.join('.github/metrics', `${storyId}.yml`);
+    console.log('');
+    console.log(`Learnings: ${fs.existsSync(path.join(repoRoot, learningsRel)) ? '✓' : '⬜'} (${learningsRel})`);
+    console.log(`Metrics:   ${fs.existsSync(path.join(repoRoot, metricsRel)) ? '✓' : '⬜'} (${metricsRel})`);
+
+    if (next) {
+      console.log('');
+      console.log(`Next action: write ${path.join('.github/pipeline', storyId, next.artifactPath)}`);
+      console.log(`Suggested agent: ${next.agent}`);
+      process.exit(1); // rsync-style: 1 = work remaining
+    }
+    console.log('');
+    console.log('🎉 Pipeline complete. Run `hone status --all` for team sync.');
+    process.exit(0);
+  });
+
+// ── NEXT command (H-009) ──────────────────────────────────────────────────────
+// Find current story's next incomplete step + suggested agent name.
+// Uses git branch to auto-derive STORY-ID; rsync-style exit codes.
+program
+  .command('next')
+  .description('Find current story\'s next incomplete step + suggested agent')
+  .action(async () => {
+    const ps = require('./lib/pipeline-status');
+    const repoRoot = process.cwd();
+    const pipelineRoot = path.join(repoRoot, '.github', 'pipeline');
+
+    let branch;
+    try {
+      branch = execSync('git symbolic-ref --short HEAD', { encoding: 'utf8' }).trim();
+    } catch {
+      console.error('Not a git repo. `hone next` requires a git branch.');
+      process.exit(1);
+    }
+    const storyId = ps.extractStoryIdFromBranch(branch);
+    if (!storyId) {
+      console.error(`Could not derive STORY-ID from branch '${branch}'.`);
+      process.exit(1);
+    }
+    const storyDir = path.join(pipelineRoot, storyId);
+    const metaPath = path.join(storyDir, 'metadata.yml');
+    if (!fs.existsSync(metaPath)) {
+      console.error(`No metadata.yml at ${metaPath}. Start with Step 0 (Story Groomer).`);
+      process.exit(1);
+    }
+    const parsed = ps.parseMetadata(fs.readFileSync(metaPath, 'utf8'));
+    if (parsed.error) {
+      console.error(`metadata.yml malformed: ${parsed.message || ''}`);
+      process.exit(1);
+    }
+    const presence = {};
+    for (const [k, fname] of Object.entries(ps.STEP_FILE_MAP)) {
+      presence[k] = fs.existsSync(path.join(storyDir, fname));
+    }
+    const states = ps.computeStepStates(parsed, presence);
+    const next = ps.findNextIncompleteStep(states);
+    if (!next) {
+      console.log(`🎉 Pipeline complete for ${storyId}. Open a PR or run \`hone status\`.`);
+      process.exit(0);
+    }
+    console.log(`Story: ${parsed.storyId} — ${parsed.title || ''}`);
+    console.log(`Branch: ${branch}`);
+    console.log(`Next step: ${next.displayName}`);
+    console.log(`Next action: write ${path.join('.github/pipeline', storyId, next.artifactPath)}`);
+    console.log(`Suggested agent: ${next.agent}`);
+    process.exit(1); // rsync-style
+  });
+
+// ── METRICS command group (H-008) ─────────────────────────────────────────────
+// `hone metrics collect [STORY-ID]` — bootstrap .github/metrics/<STORY-ID>.yml
+// from pipeline metadata + git + gh data. Pure transformer; no re-collection.
+// Sub-task (a) of issue #17. Sub-tasks (b) Code Reviewer wiring + (c) CI gate
+// are deferred to Phase 3.7+. Helper module: cli/lib/metrics-collect.js
+const metricsCmd = program.command('metrics').description('Pipeline metrics scorecards');
+metricsCmd
+  .command('collect [storyId]')
+  .description('Bootstrap .github/metrics/<STORY-ID>.yml from pipeline metadata + git + gh')
+  .option('--force', 'Overwrite an existing scorecard (default: preserve)')
+  .action(async (storyIdArg, opts) => {
+    const ps = require('./lib/pipeline-status');
+    const mc = require('./lib/metrics-collect');
+    const repoRoot = process.cwd();
+    const pipelineRoot = path.join(repoRoot, '.github', 'pipeline');
+    const metricsRoot  = path.join(repoRoot, '.github', 'metrics');
+
+    // Derive STORY-ID
+    let storyId = storyIdArg;
+    if (!storyId) {
+      try {
+        const branch = execSync('git symbolic-ref --short HEAD', { encoding: 'utf8' }).trim();
+        storyId = ps.extractStoryIdFromBranch(branch);
+        if (!storyId) {
+          console.error(`Could not derive STORY-ID from branch '${branch}'.`);
+          console.error('Pass STORY-ID explicitly.');
+          process.exit(1);
+        }
+      } catch {
+        console.error('Not a git repo or git unavailable. Pass STORY-ID explicitly.');
+        process.exit(1);
+      }
+    }
+
+    const storyDir = path.join(pipelineRoot, storyId);
+    const metaPath = path.join(storyDir, 'metadata.yml');
+    if (!fs.existsSync(metaPath)) {
+      console.error(`No pipeline metadata for ${storyId} — checked ${metaPath}`);
+      console.error('Run `hone setup` and Step 0 (Story Groomer) first.');
+      process.exit(1);
+    }
+
+    const parsed = ps.parseMetadata(fs.readFileSync(metaPath, 'utf8'));
+    if (parsed.error) {
+      console.error(`metadata.yml malformed (${parsed.error}): ${parsed.message || ''}`);
+      console.error('Fix the YAML and re-run.');
+      process.exit(1);
+    }
+
+    // Filesystem presence check
+    const artifactPresence = {};
+    for (const [k, fname] of Object.entries(ps.STEP_FILE_MAP)) {
+      artifactPresence[k] = fs.existsSync(path.join(storyDir, fname));
+    }
+
+    // Idempotency: preserve existing scorecard unless --force
+    fs.mkdirSync(metricsRoot, { recursive: true });
+    const outPath = path.join(metricsRoot, `${storyId}.yml`);
+    if (fs.existsSync(outPath) && !opts.force) {
+      console.error(`${outPath} already exists. Re-run with --force to overwrite.`);
+      console.error('(Default behavior: preserve any hand-written or agent-appended fields.)');
+      process.exit(1);
+    }
+
+    // Git info — best-effort, non-fatal on failure
+    let author;
+    try {
+      author = execSync(`git log -1 --format=%an HEAD`, { encoding: 'utf8' }).trim();
+    } catch { /* leave undefined */ }
+
+    // Files changed — best-effort
+    let filesChanged = [];
+    try {
+      const diff = execSync(`git diff --name-only ${parsed.base || 'develop'}...HEAD`, { encoding: 'utf8' });
+      filesChanged = diff.split('\n').map(s => s.trim()).filter(Boolean);
+    } catch { /* leave empty */ }
+
+    // PR info — best-effort, gh may be missing or no PR yet (E4/E5 graceful)
+    let prInfo = {};
+    try {
+      const branch = execSync('git symbolic-ref --short HEAD', { encoding: 'utf8' }).trim();
+      const pr = execSync(`gh pr list --head ${branch} --json number --jq '.[0].number' 2>/dev/null`, { encoding: 'utf8' }).trim();
+      if (pr && /^\d+$/.test(pr)) prInfo = { pr_number: parseInt(pr, 10) };
+    } catch { /* leave empty — graceful */ }
+
+    // Learnings count — files matching `${storyId}.yml` or `${storyId}-*.yml`
+    let learningsCount = 0;
+    try {
+      const learningsRoot = path.join(repoRoot, '.github', 'learnings');
+      if (fs.existsSync(learningsRoot)) {
+        const re = new RegExp(`^${storyId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:-.*)?\\.ya?ml$`);
+        learningsCount = fs.readdirSync(learningsRoot).filter(f => re.test(f)).length;
+      }
+    } catch { /* leave 0 */ }
+
+    const today = new Date().toISOString().slice(0, 10);
+    const scorecard = mc.buildScorecard({
+      parsedPipelineMetadata: parsed,
+      artifactPresence,
+      gitInfo: author ? { author } : {},
+      prInfo,
+      learningsCount,
+      filesChanged,
+      today,
+    });
+    const yamlText = mc.renderScorecardYaml(scorecard);
+    fs.writeFileSync(outPath, yamlText);
+    console.log(`✓ Wrote ${outPath}`);
+    console.log(`  steps_completed: ${scorecard.totals.steps_completed}`);
+    console.log(`  pipeline_result: ${scorecard.totals.pipeline_result}`);
+    process.exit(0);
+  });
+
+// ── CLASSIFY-CI command (H-061 — Phase 4.1) ───────────────────────────────────
+// Classify CI failure logs into named categories with severity ranking.
+// Reads stdin or --log-file. Outputs JSON list of classifications.
+// Categories form a stable contract for downstream tools (#19 CI→skills,
+// #60 CI auto-fix). CLI exits 0 — downstream tools decide on severity.
+program
+  .command('classify-ci')
+  .description('Classify CI failure logs into named categories (security, lint, e2e_flake, ...)')
+  .option('--log-file <path>', 'Read log from file (default: stdin)')
+  .action((opts) => {
+    const { classifyLogText } = require('./lib/ci-classifier');
+    let text = '';
+    try {
+      if (opts.logFile) {
+        text = fs.readFileSync(opts.logFile, 'utf8');
+      } else {
+        // Read all of stdin
+        text = fs.readFileSync(0, 'utf8');
+      }
+    } catch (e) {
+      console.error(`Failed to read log: ${e.message}`);
+      process.exit(1);
+    }
+    const result = classifyLogText(text);
+    console.log(JSON.stringify(result, null, 2));
+    // CLI exits 0 — downstream tools decide on severity (per issue #61 spec).
+    process.exit(0);
+  });
+
+// ── CI-FAILURES command group (H-010 — Phase 4.2) ─────────────────────────────
+// CI failures feedback loop. Append-only NDJSON at .github/learnings/
+// ci-failures.jsonl. Subcommands: record / record-from-classify / summary.
+// Closes #19 parts 1+2; auto-derive (part 3) and server round-trip (part 4)
+// are deferred. Helper module: cli/lib/ci-failures.js
+const ciFailuresCmd = program.command('ci-failures').description('CI failure feedback loop (H-010)');
+
+function _ciFailuresPath() {
+  return path.join(process.cwd(), '.github', 'learnings', 'ci-failures.jsonl');
+}
+
+function _deriveStoryIdFromBranch() {
+  try {
+    const ps = require('./lib/pipeline-status');
+    const branch = execSync('git symbolic-ref --short HEAD', { encoding: 'utf8' }).trim();
+    return ps.extractStoryIdFromBranch(branch);
+  } catch { return null; }
+}
+
+ciFailuresCmd
+  .command('record')
+  .description('Append a CI failure entry to .github/learnings/ci-failures.jsonl')
+  .requiredOption('--tool <name>', 'Tool name (e.g. bandit, eslint)')
+  .requiredOption('--rule <id>', 'Rule ID (e.g. B104, no-unused-vars)')
+  .option('--file <path>', 'Source file with the finding')
+  .option('--line <n>', 'Line number')
+  .option('--message <msg>', 'Finding message')
+  .option('--story-id <id>', 'Override story ID (default: derived from branch)')
+  .option('--severity <s>', 'Severity (HIGH|MEDIUM|LOW)')
+  .option('--category <c>', 'Category from classifier (security|lint|...)')
+  .action((opts) => {
+    const cf = require('./lib/ci-failures');
+    const jsonlPath = _ciFailuresPath();
+    fs.mkdirSync(path.dirname(jsonlPath), { recursive: true });
+    const existing = fs.existsSync(jsonlPath) ? fs.readFileSync(jsonlPath, 'utf8') : '';
+    const entry = {
+      story_id: opts.storyId || _deriveStoryIdFromBranch() || 'unknown',
+      tool: opts.tool,
+      rule: opts.rule,
+    };
+    if (opts.file) entry.file = opts.file;
+    if (opts.line) entry.line = Number.parseInt(opts.line, 10);
+    if (opts.message) entry.message = opts.message;
+    if (opts.severity) entry.severity = opts.severity;
+    if (opts.category) entry.category = opts.category;
+    fs.writeFileSync(jsonlPath, cf.appendFailure(existing, entry));
+    console.log(`✓ Recorded ${entry.tool}:${entry.rule} → ${jsonlPath}`);
+    process.exit(0);
+  });
+
+ciFailuresCmd
+  .command('record-from-classify')
+  .description('Pipe `hone classify-ci` JSON output into the failures log')
+  .option('--story-id <id>', 'Override story ID (default: derived from branch)')
+  .action((opts) => {
+    const cf = require('./lib/ci-failures');
+    let stdin = '';
+    try { stdin = fs.readFileSync(0, 'utf8'); }
+    catch (e) {
+      console.error(`Failed to read stdin: ${e.message}`);
+      process.exit(1);
+    }
+    let matches;
+    try {
+      matches = JSON.parse(stdin);
+      if (!Array.isArray(matches)) throw new Error('expected array of classifications');
+    } catch (e) {
+      console.error(`Invalid JSON input from classify-ci: ${e.message}`);
+      process.exit(1);
+    }
+    const storyId = opts.storyId || _deriveStoryIdFromBranch() || 'unknown';
+    const jsonlPath = _ciFailuresPath();
+    fs.mkdirSync(path.dirname(jsonlPath), { recursive: true });
+    let text = fs.existsSync(jsonlPath) ? fs.readFileSync(jsonlPath, 'utf8') : '';
+    let added = 0;
+    for (const m of matches) {
+      // Skip 'unknown' classifications — they're noise in the recurring data
+      if (m.category === 'unknown') continue;
+      const entry = {
+        story_id: storyId,
+        tool: 'classifier',
+        rule: m.category,
+        category: m.category,
+        severity: typeof m.severity === 'number' ? String(m.severity) : m.severity,
+        message: m.evidence ? String(m.evidence).slice(0, 200) : undefined,
+      };
+      text = cf.appendFailure(text, entry);
+      added++;
+    }
+    fs.writeFileSync(jsonlPath, text);
+    console.log(`✓ Recorded ${added} classification(s) → ${jsonlPath}`);
+    process.exit(0);
+  });
+
+ciFailuresCmd
+  .command('summary')
+  .description('Print grouped counts + recurring patterns')
+  .option('--threshold <n>', 'Recurring threshold (default 3)', '3')
+  .option('--since-days <n>', 'Lookback window (default 30)', '30')
+  .action((opts) => {
+    const cf = require('./lib/ci-failures');
+    const jsonlPath = _ciFailuresPath();
+    if (!fs.existsSync(jsonlPath)) {
+      console.log(`No CI failures recorded yet. Path: ${jsonlPath}`);
+      process.exit(0);
+    }
+    const text = fs.readFileSync(jsonlPath, 'utf8');
+    const { failures, malformedCount } = cf.loadFailures(text);
+    if (malformedCount > 0) {
+      console.warn(`⚠ ${malformedCount} malformed line(s) skipped.`);
+    }
+    console.log(cf.summarize(failures, {
+      threshold: Number.parseInt(opts.threshold, 10) || 3,
+      sinceDays: Number.parseInt(opts.sinceDays, 10) || 30,
+    }));
+    process.exit(0);
+  });
+
+// ── CHECK-REFRESH command (H-015 — Phase 4.3) ─────────────────────────────────
+// Evaluate skill freshness against time-based + growth-based triggers.
+// Reads .pipeline-config.yml + walks source_dirs to count files.
+// Exit 0 if fresh, exit 1 if stale (with reasons printed).
+program
+  .command('check-refresh')
+  .description('Check if skill files are stale (time-based + growth-based triggers)')
+  .option('--growth-pct <n>', 'Growth threshold percent (default 50)', '50')
+  .action((opts) => {
+    const yaml = require('js-yaml');
+    const { evaluateRefresh } = require('./lib/refresh-check');
+    const repoRoot = process.cwd();
+    const configPath = path.join(repoRoot, '.github', '.pipeline-config.yml');
+
+    if (!fs.existsSync(configPath)) {
+      console.error(`No .pipeline-config.yml at ${configPath}`);
+      console.error('Run `hone setup` first.');
+      process.exit(1);
+    }
+
+    const config = yaml.load(fs.readFileSync(configPath, 'utf8')) || {};
+    const sr = config.skill_refresh || {};
+    const sourceDirs = config.source_dirs || ['src/'];
+
+    // Count source files in configured source_dirs (re-uses bundleDirectory
+    // semantics from `hone derive`)
+    let currentSrcFiles = 0;
+    for (const dir of sourceDirs) {
+      const dirPath = path.join(repoRoot, dir.replace(/"/g, ''));
+      if (!fs.existsSync(dirPath)) continue;
+      const stack = [dirPath];
+      while (stack.length > 0) {
+        const cur = stack.pop();
+        let entries;
+        try { entries = fs.readdirSync(cur, { withFileTypes: true }); }
+        catch { continue; }
+        for (const ent of entries) {
+          const full = path.join(cur, ent.name);
+          if (ent.isDirectory()) {
+            if (ent.name === 'node_modules' || ent.name.startsWith('.')) continue;
+            stack.push(full);
+          } else if (ent.isFile()) {
+            currentSrcFiles++;
+          }
+        }
+      }
+    }
+
+    const result = evaluateRefresh({
+      now: new Date(),
+      lastDerived: sr.last_derived || null,
+      lastDerivedSrcFiles: sr.last_derived_src_files == null ? null : Number(sr.last_derived_src_files),
+      currentSrcFiles,
+      refreshIntervalDays: typeof sr.refresh_interval_days === 'number' ? sr.refresh_interval_days : 90,
+      growthPct: Number.parseFloat(opts.growthPct) || 50,
+    });
+
+    console.log('');
+    console.log(`Skill freshness check`);
+    console.log(`=====================`);
+    console.log(`Last derived:        ${sr.last_derived || '(never)'}`);
+    console.log(`Last derived count:  ${sr.last_derived_src_files == null ? '(unknown)' : sr.last_derived_src_files}`);
+    console.log(`Current src files:   ${currentSrcFiles}`);
+    console.log(`Refresh interval:    ${sr.refresh_interval_days || 90} days`);
+    console.log(`Growth threshold:    ${result.reasons.length === 0 ? 'fresh' : '...'} ${Number.parseFloat(opts.growthPct) || 50}%`);
+    console.log('');
+    if (result.stale) {
+      console.log(`⚠ Skills are STALE. Reasons: ${result.reasons.join(', ')}`);
+      console.log(`Run \`hone derive\` to refresh.`);
+      process.exit(1);
+    }
+    console.log(`✓ Skills are fresh.`);
+    process.exit(0);
+  });
+
+// ── RATIFY command (H-027 — fast-track ratification at epic level) ────────────
+// Reads .github/EXECUTION_PLAN.yml; classifies fast_track:true stories
+// via isHighTouch; high-touch stories are auto-excluded from epic
+// ratification. Prompts user for accept/decline/per-story.
+// Sub-tasks (e) agent prompt wiring + (f) doc updates deferred to follow-up.
+program
+  .command('ratify')
+  .description('Ratify fast-track approvals at the epic level (H-027)')
+  .option('--status', 'Print current ratification status + exit')
+  .option('--per-story', 'Skip prompt; force per-story mode')
+  .option('--auto-confirm', 'Accept without prompting (CI use)')
+  .option('-y, --yes', 'Alias for --auto-confirm')
+  .action(async (opts) => {
+    const ratify = require('./lib/fast-track-ratify');
+    const repoRoot = process.cwd();
+    const planPath = path.join(repoRoot, '.github', 'EXECUTION_PLAN.yml');
+
+    if (!fs.existsSync(planPath)) {
+      console.error(`No execution plan at ${planPath}`);
+      console.error('Run the Delivery Architect agent first.');
+      process.exit(1);
+    }
+
+    const text = fs.readFileSync(planPath, 'utf8');
+
+    // --status: read + print + exit
+    if (opts.status) {
+      const status = ratify.getRatificationStatus(text);
+      if (!status.ratified) {
+        console.log('Fast-track ratification: NOT RATIFIED');
+        console.log('Run `hone ratify` to ratify.');
+        process.exit(0);
+      }
+      console.log('Fast-track ratification: RATIFIED');
+      console.log(`  By:                  ${status.by}`);
+      console.log(`  At:                  ${status.at}`);
+      console.log(`  Mode:                ${status.mode}`);
+      console.log(`  High-touch excluded: ${status.highTouchExcluded.length > 0 ? status.highTouchExcluded.join(', ') : '(none)'}`);
+      process.exit(0);
+    }
+
+    // Else: classify candidates + prompt
+    const parsed = ratify.parseExecutionPlan(text);
+    if (parsed.error) {
+      console.error(`EXECUTION_PLAN.yml ${parsed.error}: ${parsed.message || ''}`);
+      process.exit(1);
+    }
+    const stories = Array.isArray(parsed.stories) ? parsed.stories : [];
+    const candidates = stories.filter(s => s && s.fast_track === true);
+    if (candidates.length === 0) {
+      console.log('No fast_track candidates in EXECUTION_PLAN.yml. Nothing to ratify.');
+      process.exit(0);
+    }
+
+    // Classify
+    const eligible = [];
+    const highTouchExcluded = [];
+    for (const s of candidates) {
+      if (ratify.isHighTouch(s)) highTouchExcluded.push(s.id);
+      else eligible.push(s.id);
+    }
+
+    console.log('');
+    console.log(`Delivery Architect proposed fast-track for ${candidates.length} stories:`);
+    for (const s of candidates) {
+      const tag = ratify.isHighTouch(s) ? '[HIGH-TOUCH — will prompt per-story]' : '[eligible]';
+      const est = typeof s.estimate === 'number' ? `(${s.estimate}pt)` : '';
+      console.log(`  • ${s.id} — ${s.title || ''} ${est} ${tag}`);
+    }
+    console.log('');
+    console.log(`  Eligible:           ${eligible.length}`);
+    console.log(`  High-touch excluded: ${highTouchExcluded.length}`);
+    console.log('');
+
+    // Decide mode
+    let mode = 'epic';
+    let accept = false;
+    if (opts.perStory) {
+      mode = 'per-story';
+      accept = true;
+      console.log('Mode: per-story (--per-story flag)');
+    } else if (opts.autoConfirm || opts.yes) {
+      accept = true;
+      console.log('Auto-confirmed (CI mode)');
+    } else {
+      // Interactive prompt via readline
+      const readline = require('readline');
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const ask = (q) => new Promise(res => rl.question(q, res));
+      const answer = (await ask('Ratify all eligible? [y / n / per-story]: ')).trim().toLowerCase();
+      rl.close();
+      if (answer === 'y' || answer === 'yes') {
+        accept = true;
+      } else if (answer === 'p' || answer === 'per-story') {
+        accept = true;
+        mode = 'per-story';
+      }
+    }
+
+    if (!accept) {
+      console.log('Declined. No changes written.');
+      process.exit(1);
+    }
+
+    // Write the block
+    const author = process.env.USER || process.env.LOGNAME || 'unknown';
+    const result = ratify.addRatifiedBlock(text, {
+      by: author,
+      at: new Date().toISOString(),
+      mode,
+      highTouchExcluded,
+    });
+    fs.writeFileSync(planPath, result.text);
+    console.log('');
+    console.log(`✓ ${path.relative(repoRoot, planPath)} updated — fast_track_ratified block added`);
+    console.log(`  Mode: ${mode}`);
+    if (highTouchExcluded.length > 0) {
+      console.log(`  High-touch excluded (will prompt per-story): ${highTouchExcluded.join(', ')}`);
+    }
+    process.exit(0);
+  });
+
+// ── CHECK-COMPLIANCE command (H-011 — pre-commit pipeline compliance) ────────
+// Pre-commit-friendly check: ensures the current feature branch has a
+// step-0-grooming.md artifact for its derived STORY-ID. Off-pattern
+// branches and fresh repos pass gracefully (exit 0). Missing grooming
+// on a STORY-ID branch fails with exit 1.
+//
+// Wire as a pre-commit hook (see docs/sdlc/pre-commit-hook.md):
+//   - id: hone-pipeline-compliance
+//     entry: hone check-compliance
+//     language: system
+//     stages: [pre-push]
+program
+  .command('check-compliance')
+  .description('Verify pipeline artifacts exist for current branch (pre-commit-friendly)')
+  .action(() => {
+    const { evaluateCompliance } = require('./lib/compliance-check');
+    const repoRoot = process.cwd();
+    const pipelineRoot = path.join(repoRoot, '.github', 'pipeline');
+
+    let branch = '';
+    try {
+      branch = execSync('git symbolic-ref --short HEAD', { encoding: 'utf8' }).trim();
+    } catch {
+      // Detached HEAD or not a git repo — graceful pass
+      console.log('Not a git repo or detached HEAD — skipping pipeline compliance check.');
+      process.exit(0);
+    }
+
+    const result = evaluateCompliance({
+      branch,
+      pipelineRoot,
+      fileExists: (p) => fs.existsSync(p),
+    });
+
+    if (result.compliant) {
+      switch (result.reason) {
+        case 'no-story-id':
+          console.log(`✓ Branch '${branch}' has no story-ID pattern — pipeline compliance not applicable`);
+          break;
+        case 'no-pipeline-dir':
+          console.log(`✓ No .github/pipeline/ — pipeline compliance not yet applicable (run \`hone setup\`)`);
+          break;
+        case 'ok':
+          console.log(`✓ Pipeline compliance OK: ${result.storyId}/step-0-grooming.md`);
+          break;
+      }
+      process.exit(0);
+    }
+
+    // missing-grooming
+    console.error(`✗ Pipeline compliance: ${result.storyId} has no step-0-grooming.md`);
+    console.error(`  Expected: ${path.relative(repoRoot, result.expected)}`);
+    console.error(`  Run the Story Groomer agent before committing.`);
+    process.exit(1);
+  });
+
+// H-086: synthetic SDLC pipeline run — generate fixture or verify captured output.
+program
+  .command('synthetic-pipeline-run')
+  .description('Generate synthetic story fixture or verify captured pipeline output against expected rule-applied markers. M scope: fixture lib + verifier; per-editor runtime drivers deferred.')
+  .option('--fixture <name>', 'Print synthetic fixture by name (see SYNTHETIC_FIXTURES)')
+  .option('--list', 'List available synthetic fixtures')
+  .option('--verify <story-dir>', 'Verify captured outputs in story dir against fixture markers')
+  .option('--scenario <name>', 'Scenario name to use with --verify (default: fix-with-regression-policy)')
+  .action(async (opts) => {
+    const sp = require('./lib/synthetic-pipeline');
+
+    if (opts.list) {
+      console.log(JSON.stringify(Object.keys(sp.SYNTHETIC_FIXTURES), null, 2));
+      return;
+    }
+
+    if (opts.fixture) {
+      const f = sp.generateFixture(opts.fixture);
+      if (!f) {
+        console.error(`Unknown fixture: ${opts.fixture}`);
+        process.exit(1);
+      }
+      console.log(JSON.stringify(f, null, 2));
+      return;
+    }
+
+    if (opts.verify) {
+      const scenarioName = opts.scenario || 'fix-with-regression-policy';
+      const fixture = sp.generateFixture(scenarioName);
+      if (!fixture) {
+        console.error(`Unknown scenario: ${scenarioName}`);
+        process.exit(1);
+      }
+      const storyDir = path.resolve(opts.verify);
+      const capturedOutputs = {};
+      const stepFileMap = {
+        'step-1-plan': 'step-1-plan.md',
+        'step-3-e2e-plan': 'step-3-e2e-plan.md',
+        'step-5-review': 'step-5-review.md',
+        'step-5c-ci': 'step-5c-ci.md',  // HS-004: Step 5c artifact lives in its own file
+      };
+      for (const [stepName, fileName] of Object.entries(stepFileMap)) {
+        const fp = path.join(storyDir, fileName);
+        if (fs.existsSync(fp)) capturedOutputs[stepName] = fs.readFileSync(fp, 'utf8');
+      }
+      const result = sp.verifyMarkers({
+        capturedOutputs,
+        expectedMarkers: fixture.expectedMarkers,
+      });
+      console.log(JSON.stringify(result, null, 2));
+      if (!result.passed) process.exit(1);
+      return;
+    }
+
+    console.error('Specify one of: --list, --fixture <name>, or --verify <story-dir>');
+    process.exit(1);
+  });
+
+// H-084: merge adopter-side rule overlays onto canonical defaults.
+program
+  .command('merge-overlays <step>')
+  .description('Merge .hone-local/rule-overlays/<step>.*.md onto .hone/agents/<step>.agent.md. Prints merged result to stdout; diagnostics to stderr.')
+  .option('--default <path>', 'Override default file path (default: .hone/agents/<step>.agent.md)')
+  .option('--overlays-dir <path>', 'Override overlays directory (default: .hone-local/rule-overlays)')
+  .action(async (step, opts) => {
+    const { mergeOverlays, verifyOverlayMarkers } = require('./lib/overlay-merge');
+    const repoRoot = process.cwd();
+    const defaultPath = opts.default || path.join(repoRoot, '.hone/agents', `${step}.agent.md`);
+    const overlaysDir = opts.overlaysDir || path.join(repoRoot, '.hone-local/rule-overlays');
+
+    if (!fs.existsSync(defaultPath)) {
+      console.error(`Default file not found: ${defaultPath}`);
+      process.exit(1);
+    }
+
+    const defaultText = fs.readFileSync(defaultPath, 'utf8');
+
+    const overlays = [];
+    if (fs.existsSync(overlaysDir)) {
+      for (const f of fs.readdirSync(overlaysDir).sort()) {
+        if (f.startsWith(`${step}.`) && f.endsWith('.md')) {
+          overlays.push({
+            path: path.join(overlaysDir, f),
+            content: fs.readFileSync(path.join(overlaysDir, f), 'utf8'),
+          });
+        }
+      }
+    }
+
+    const result = mergeOverlays(defaultText, overlays);
+    const verify = verifyOverlayMarkers(result.merged, result.applied);
+
+    process.stdout.write(result.merged);
+    process.stderr.write(`\n[merge-overlays] ${result.applied.length} overlays applied, ${result.errors.length} errors\n`);
+    for (const a of result.applied) {
+      process.stderr.write(`  ${a.ok ? '✓' : '✗'} ${a.ruleId} (${a.insertSpec})\n`);
+    }
+    for (const e of result.errors) {
+      process.stderr.write(`  ERROR: ${e}\n`);
+    }
+    if (!verify.allPresent) {
+      process.stderr.write(`  WARN: missing markers: ${verify.missing.join(', ')}\n`);
+    }
+    if (result.errors.length > 0 || !verify.allPresent) process.exit(1);
+  });
+
+// H-081: validate editor-aware SDLC pipeline scaffolding.
+program
+  .command('validate-pipeline')
+  .description('Validate editor-aware SDLC pipeline: detect editors, check discovery + rule presence + cross-editor drift. Prints JSON. Exits 1 on ERROR findings (use --strict for CI).')
+  .option('--strict', 'Exit non-zero on any WARN finding too (CI grade)')
+  .action(async (opts) => {
+    const { detectEditors, EDITOR_PROJECTIONS } = require('./lib/editor-detect');
+    const { validatePipeline } = require('./lib/pipeline-validate');
+    const repoRoot = process.cwd();
+    const fileExists = (p) => fs.existsSync(path.join(repoRoot, p));
+    const readFile = (p) => fs.existsSync(path.join(repoRoot, p))
+      ? fs.readFileSync(path.join(repoRoot, p), 'utf8')
+      : null;
+
+    const editors = detectEditors({
+      fileExists,
+      envVar: process.env.HONE_EDITOR,
+      readFile,
+    });
+
+    const surfaceContents = new Map();
+    for (const editor of editors) {
+      const proj = EDITOR_PROJECTIONS[editor];
+      if (proj?.project_doc) {
+        const content = readFile(proj.project_doc);
+        if (content) surfaceContents.set(proj.project_doc, content);
+      }
+    }
+
+    const skillNames = [];
+    for (const skillsDir of [path.join(repoRoot, '.github/skills'), path.join(repoRoot, 'server/seeds/skills')]) {
+      if (fs.existsSync(skillsDir)) {
+        for (const e of fs.readdirSync(skillsDir)) {
+          if (fs.existsSync(path.join(skillsDir, e, 'SKILL.md')) && !skillNames.includes(e)) {
+            skillNames.push(e);
+          }
+        }
+        break;
+      }
+    }
+
+    const result = validatePipeline({ editors, surfaceContents, fileExists, skillNames });
+    console.log(JSON.stringify({
+      detected_editors: editors,
+      ...result,
+    }, null, 2));
+
+    const exitCode = result.summary.error_count > 0
+      || (opts.strict && result.summary.warn_count > 0)
+      ? 1 : 0;
+    if (exitCode > 0) process.exit(exitCode);
+  });
+
+// H-085: audit skills against codebase + learnings — detect drift.
+program
+  .command('audit-skills')
+  .description('Audit .github/skills/ for path drift, cross-ref drift, and new-skill candidates from learnings. Prints JSON.')
+  .action(async () => {
+    const { auditSkills } = require('./lib/skill-audit');
+    const repoRoot = process.cwd();
+
+    // Collect skill files: prefer .github/skills/, fall back to server/seeds/skills/
+    function collectSkillFiles(skillsDir) {
+      const out = { names: [], contents: [] };
+      if (!fs.existsSync(skillsDir)) return out;
+      const entries = fs.readdirSync(skillsDir);
+      for (const e of entries) {
+        const skillPath = path.join(skillsDir, e, 'SKILL.md');
+        if (fs.existsSync(skillPath)) {
+          out.names.push(e);
+          out.contents.push(fs.readFileSync(skillPath, 'utf8'));
+        }
+      }
+      return out;
+    }
+
+    let skills = collectSkillFiles(path.join(repoRoot, '.github/skills'));
+    if (skills.names.length === 0) {
+      skills = collectSkillFiles(path.join(repoRoot, 'server/seeds/skills'));
+    }
+
+    // Collect learnings files
+    const learningsDir = path.join(repoRoot, '.github/learnings');
+    const learningsFiles = [];
+    if (fs.existsSync(learningsDir)) {
+      for (const f of fs.readdirSync(learningsDir).filter((f) => f.endsWith('.yml'))) {
+        learningsFiles.push(fs.readFileSync(path.join(learningsDir, f), 'utf8'));
+      }
+    }
+
+    // AU-001 (#159): optional adopter-supplied allow-list at
+    // .hone/audit-skills.ignore.yml. When present, paths in the
+    // `ignore` array are never reported as PATH_BROKEN even if
+    // other heuristics would have flagged them. Glob support: entries
+    // containing * or ? are treated as globs.
+    let ignoreList = [];
+    const ignorePath = path.join(repoRoot, '.hone/audit-skills.ignore.yml');
+    if (fs.existsSync(ignorePath)) {
+      try {
+        const yamlMod = require('js-yaml');
+        const parsed = yamlMod.load(fs.readFileSync(ignorePath, 'utf8'));
+        if (parsed && Array.isArray(parsed.ignore)) {
+          ignoreList = parsed.ignore.filter(x => typeof x === 'string');
+        }
+      } catch (e) {
+        console.error(`audit-skills: warning — could not parse ${ignorePath}: ${e.message}`);
+      }
+    }
+
+    const result = auditSkills({
+      skillFiles: skills.contents,
+      skillNames: skills.names,
+      learningsFiles,
+      fileExists: (p) => fs.existsSync(path.join(repoRoot, p)),
+      ignoreList,
+    });
+
+    console.log(JSON.stringify(result, null, 2));
+    if (result.summary.error_count > 0) process.exit(1);
+  });
+
+// LC-003 (#58 G2 partial 3/3): retrospective audit of the learnings corpus.
+// Read-only — classifies each learning entry by freshness/incorporation/
+// contradiction status. Prints JSON.
+program
+  .command('audit-learnings')
+  .description('Retrospective audit of .github/learnings/. Classifies each entry by freshness, incorporation, and contradiction. Prints JSON.')
+  .option('--filter <status>', 'show only entries with this status (fresh|aging|stale|incorporated|contradicted|unknown)')
+  .action(async (cmdOpts) => {
+    const { auditLearnings, STATUS } = require('./lib/learnings-audit');
+    const { execSync } = require('node:child_process');
+    const repoRoot = process.cwd();
+
+    // Collect learnings files
+    const learningsDir = path.join(repoRoot, '.github/learnings');
+    const learningsFiles = [];
+    if (fs.existsSync(learningsDir)) {
+      for (const f of fs.readdirSync(learningsDir).filter((f) => f.endsWith('.yml'))) {
+        learningsFiles.push({
+          fileLabel: f,
+          content: fs.readFileSync(path.join(learningsDir, f), 'utf8'),
+        });
+      }
+    }
+
+    // Collect skill names
+    const skillsDir = path.join(repoRoot, '.github/skills');
+    const skillNames = [];
+    if (fs.existsSync(skillsDir)) {
+      for (const e of fs.readdirSync(skillsDir)) {
+        if (fs.existsSync(path.join(skillsDir, e, 'SKILL.md'))) skillNames.push(e);
+      }
+    }
+
+    // LC-004: shared git helpers (was inline; now cli/lib/git-helpers.js).
+    const { getLastModifiedDays, getFirstCommitDateMs } = require('./lib/git-helpers');
+    const todayMs = Date.now();
+
+    function getSkillLastModifiedDays(name) {
+      return getLastModifiedDays(repoRoot, '.github/skills/' + name + '/SKILL.md', todayMs);
+    }
+    // LC-004 (#143): captured_at fallback for entries missing the field.
+    // Query git for the file's first-commit timestamp.
+    function getCapturedAtFromGit(fileLabel) {
+      return getFirstCommitDateMs(repoRoot, '.github/learnings/' + fileLabel);
+    }
+
+    const result = auditLearnings({
+      learningsFiles,
+      skillNames,
+      getSkillLastModifiedDays,
+      getCapturedAtFromGit,
+    });
+
+    if (cmdOpts.filter) {
+      const valid = Object.values(STATUS);
+      if (!valid.includes(cmdOpts.filter)) {
+        console.error(`error: --filter must be one of [${valid.join(', ')}], got "${cmdOpts.filter}"`);
+        process.exit(2);
+      }
+      result.entries = result.entries.filter((e) => e.status === cmdOpts.filter);
+    }
+
+    console.log(JSON.stringify(result, null, 2));
+    // Exit 0 — this is read-only retrospective; non-zero only on parse errors
+    if (result.summary.parse_errors > 0) process.exit(1);
+  });
+
+// SA-002 / #137 (architect plan, story 2/2): Step 5b runtime skill-application
+// SC-002 (Phase 2 of SC family): classify a story's recommended SDLC
+// track + agent invocation per `cli/lib/story-classifier.js`. CLI reads
+// GitHub issue via `gh issue view`, extracts 4 reliable inputs heuristically,
+// accepts the other 5 via --input-file or interactive prompt, prints the
+// full classifier result. Adopters use this for ad-hoc backlog triage.
+program
+  .command('classify-story [issueId]')
+  .description('Classify a GitHub issue by SDLC track. Extracts inputs from issue body/labels heuristically; reads other inputs from --input-file or interactive prompt. Outputs JSON.')
+  .option('--input-file <path>', 'YAML file with all 9 classifyStory inputs (skips GitHub fetch + interactive)')
+  .option('--interactive', 'prompt for the 5 judgment fields not heuristically extractable')
+  .option('--pretty', 'human-readable output (default: --json)')
+  .option('--repo-root <path>', 'repo root (default: process.cwd())')
+  .option('--window-days <n>', 'recently-modified window in days (overrides .pipeline-config.yml; default 14)')
+  .option('--threshold-estimate-full-sdlc <s>', 'override estimate threshold (XS|S|M|L|XL)')
+  .action(async (issueId, cmdOpts) => {
+    const { classifyStory } = require('./lib/story-classifier');
+    const { readStoryClassifierConfig } = require('./lib/pipeline-config');
+    const repoRoot = cmdOpts.repoRoot || process.cwd();
+
+    // SC-003 + SC-004: read adopter-set thresholds once, up front.
+    // Used both for the extractor (window-days) and for classifyStory (estimate threshold).
+    // Precedence for any given knob: framework default < config default < CLI flag.
+    const configThresholds = readStoryClassifierConfig(repoRoot);
+    const effectiveWindowDays = parseInt(
+      cmdOpts.windowDays || configThresholds.recently_modified_window_days,
+      10,
+    ) || 14;
+
+    let inputs = null;
+    let issueMeta = null;
+
+    // Path A: --input-file (CI use, no GitHub fetch)
+    if (cmdOpts.inputFile) {
+      if (!fs.existsSync(cmdOpts.inputFile)) {
+        console.error(`error: input file not found: ${cmdOpts.inputFile}`);
+        process.exit(2);
+      }
+      try {
+        const yamlMod = require('js-yaml');
+        inputs = yamlMod.load(fs.readFileSync(cmdOpts.inputFile, 'utf8'));
+        if (!inputs || typeof inputs !== 'object') {
+          console.error(`error: input file is empty or not an object`);
+          process.exit(2);
+        }
+      } catch (e) {
+        console.error(`error: failed to parse ${cmdOpts.inputFile}: ${e.message}`);
+        process.exit(2);
+      }
+    }
+    // Path B: GitHub issue fetch via gh
+    else if (issueId) {
+      try {
+        const out = execSync(
+          `gh issue view ${issueId} --json title,body,labels,url`,
+          { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }
+        );
+        issueMeta = JSON.parse(out);
+        const labels = (issueMeta.labels || []).map(l => l.name);
+        const {
+          extractType, extractSecurityImplications,
+          extractCrossRepoDependency, extractRecentlyModifiedOverlap,
+        } = require('./lib/story-classifier-extract');
+        inputs = {
+          type: extractType(labels, issueMeta.body, issueMeta.title),
+          has_security_implications: extractSecurityImplications(labels, issueMeta.body),
+          cross_repo_dependency: extractCrossRepoDependency(issueMeta.body),
+          recently_modified_overlap: extractRecentlyModifiedOverlap(repoRoot, [], effectiveWindowDays),
+          // 5 fields below default to safe values; user supplies via --input-file or --interactive
+          adopter_blast_radius: 'medium',
+          surface_area: 'single-module',
+          estimate: 'M',
+          design_options: '1',
+          has_test_matrix: 'simple',
+          is_first_of_its_kind: false,
+        };
+      } catch (e) {
+        console.error(`error: gh issue view ${issueId} failed: ${(e.stderr || '').toString().trim() || e.message}`);
+        console.error(`hint: install GitHub CLI (cli.github.com), run \`gh auth login\`, or pass --input-file <path>`);
+        process.exit(2);
+      }
+    } else {
+      console.error('error: provide either an <issueId> argument or --input-file <path>');
+      console.error('usage: hone classify-story 142');
+      console.error('       hone classify-story --input-file inputs.yml');
+      process.exit(2);
+    }
+
+    // SC-003 + SC-004: build thresholds — config defaults UNDER explicit CLI flags.
+    // Adopter sets defaults in .pipeline-config.yml; CLI flags win when both supplied.
+    // Safety-critical rules (R1/R2/R3) ignore both — framework-fixed.
+    // (configThresholds was read up front so the extractor could also use it.)
+    const thresholds = { ...configThresholds };
+    if (cmdOpts.thresholdEstimateFullSdlc) {
+      thresholds.estimate_full_sdlc = cmdOpts.thresholdEstimateFullSdlc;
+    }
+
+    const classification = classifyStory(inputs, thresholds);
+    const result = {
+      ...(issueMeta && { issue_id: issueMeta.url ? issueId : null, title: issueMeta.title, url: issueMeta.url }),
+      inputs,
+      classification,
+    };
+
+    if (cmdOpts.pretty) {
+      console.log(`Track:           ${classification.track}`);
+      console.log(`Architect:       ${classification.architect.engage ? 'YES — ' + classification.architect.axes.join(', ') : 'no'}`);
+      console.log(`Agents:          ${classification.agents.join(', ')}`);
+      console.log(`Artifacts:       ${classification.artifacts.join(', ')}`);
+      console.log(`Rationale:       ${classification.rationale}`);
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+  });
+
+// SC-005 (Phase 5 of SC family): publish a framework-canonical learning
+// from `.github/learnings/<ID>.yml` to `server/seeds/learnings/<ID>.yml`,
+// flipping its status from `pending` → `promoted` and stamping a
+// `promoted_at` timestamp. The seed copy is what adopters receive at
+// install time. Eligibility: share_enterprise=true + enterprise_candidate=true.
+program
+  .command('publish-learning <learningId>')
+  .description('Publish an enterprise-candidate learning to server/seeds/learnings/ + flip status to promoted')
+  .option('--force', 're-publish even if status is already promoted')
+  .option('--repo-root <path>', 'repo root (default: process.cwd())')
+  .action((learningId, opts) => {
+    const { publishLearning } = require('./lib/publish-learning');
+    const repoRoot = opts.repoRoot || process.cwd();
+    const result = publishLearning({ repoRoot, learningId, force: opts.force });
+
+    switch (result.status) {
+      case 'published':
+        console.log(`✓ Published ${learningId} → ${result.copiedTo}`);
+        console.log(`  Source updated: status: promoted + promoted_at stamped.`);
+        break;
+      case 'already-promoted':
+        console.log(`• ${learningId} is already promoted (idempotent no-op). Pass --force to re-publish.`);
+        break;
+      case 'not-eligible':
+        console.error(`error: ${learningId} not eligible: ${result.error}`);
+        process.exit(2);
+        break;
+      case 'not-found':
+        console.error(`error: ${result.error}`);
+        process.exit(2);
+        break;
+      case 'error':
+      default:
+        console.error(`error: ${result.error || 'unknown failure'}`);
+        process.exit(1);
+    }
+  });
+
+// HC-003: multi-channel orchestration wrapper for `hone sync` + `hone derive`
+// with backup-before-write + section-aware restore + halt-and-restore-on-failure.
+// First multi-channel wrapper the framework ships. Implements OptionsFlow
+// E22-E-L3 (deferred during SC-008 absorption). See pipeline-integrity §17.
+program
+  .command('refresh-knowledge')
+  .description('Multi-channel wrapper for sync + derive with backup, section-aware restore, and halt-on-failure (HC-003).')
+  .option('--channels <list>', 'comma-separated channels to run (default: sync,derive)', 'sync,derive')
+  .option('--no-preserve', 'Skip section-aware restore (alias for --force; HC-005-B)')
+  .option('--backup-dir <path>', 'backup directory (default: .hone/backups)', '.hone/backups')
+  .option('--dry-run', 'print plan; do not run channels or create backup')
+  .option('--force', 'Skip section-aware restore (DANGEROUS — clobbers adopter customizations; alias for --no-preserve; HC-005-B)')
+  .option('--repo-root <path>', 'repo root (default: process.cwd())')
+  .option('--json', 'emit findings as JSON')
+  .action((opts) => {
+    const { refreshKnowledge } = require('./lib/refresh-knowledge');
+    const repoRoot = opts.repoRoot || process.cwd();
+    const channels = (opts.channels || 'sync,derive').split(',').map(s => s.trim()).filter(Boolean);
+    const result = refreshKnowledge({
+      repoRoot,
+      channels,
+      preserveUserSections: opts.preserve !== false,
+      backupDir: opts.backupDir,
+      dryRun: opts.dryRun,
+      force: opts.force,
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(result.summary.errors > 0 ? 1 : 0);
+      return;
+    }
+
+    console.log(`Hone refresh-knowledge (HC-003) — channels: ${channels.join(', ')}`);
+    if (result.dryRun) {
+      console.log('Dry-run plan (no side effects):');
+      for (const f of result.findings) {
+        console.log(`  • [${f.code}] ${f.message}`);
+      }
+      console.log(`Would run channels in order: ${channels.join(' → ')}`);
+      console.log(`Would back up to: ${path.join(repoRoot, opts.backupDir)}`);
+      process.exit(0);
+      return;
+    }
+
+    if (result.backupPath) {
+      console.log(`✓ Backup created: ${result.backupPath}`);
+    }
+    for (const cr of result.channelResults) {
+      const icon = cr.ok ? '✓' : '✗';
+      console.log(`${icon} channel ${cr.name}: exit ${cr.exitCode}`);
+    }
+    if (result.restored && result.restored.length > 0) {
+      console.log(`✓ Restored user sections in ${result.restored.length} file(s):`);
+      for (const f of result.restored) console.log(`    - ${f}`);
+    }
+    if (result.summary.errors > 0) {
+      console.error(`\n✗ ${result.summary.errors} error(s):`);
+      for (const f of result.findings.filter(x => x.severity === 'ERROR')) {
+        console.error(`  [${f.code}] ${f.message}`);
+      }
+      // HC-005-B: distinguish restore-failed via exit(3); generic errors stay exit(1)
+      const restoreFailed = result.findings.some(f => f.code === 'restore-failed');
+      process.exit(restoreFailed ? 3 : 1);
+    }
+    if (result.summary.warnings > 0) {
+      console.log(`\n⚠ ${result.summary.warnings} warning(s):`);
+      for (const f of result.findings.filter(x => x.severity === 'WARN')) {
+        console.log(`  [${f.code}] ${f.message}`);
+      }
+    }
+  });
+
+// HC-004: scaffold a per-adopter <name>-domain/SKILL.md from the 7-section
+// template documented in pipeline-integrity §13 (per OptionsFlow E26-A-L1).
+// First per-adopter skill scaffolder. Marker discipline per HC-001-L1.
+program
+  .command('derive-domain <name>')
+  .description('Scaffold a per-adopter <name>-domain/SKILL.md from the 7-section template (HC-004). Idempotent on managed files; refuses to overwrite unmanaged unless --force.')
+  .option('--force', 'overwrite unmanaged existing file (DANGEROUS — clobbers adopter customizations)')
+  .option('--repo-root <path>', 'repo root (default: process.cwd())')
+  .option('--json', 'emit findings as JSON')
+  .action((name, opts) => {
+    const { deriveDomain } = require('./lib/derive-domain');
+    const repoRoot = opts.repoRoot || process.cwd();
+    const result = deriveDomain({ repoRoot, domainName: name, force: opts.force });
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(result.summary.errors > 0 ? 1 : 0);
+      return;
+    }
+
+    console.log(`Hone derive-domain (HC-004) — domain: ${name}`);
+    if (result.created.length > 0) {
+      console.log(`✓ Created: ${result.created[0]}`);
+      console.log(`  Edit the 7 sections (Vocabulary / Architectural Contracts / Review Rules /`);
+      console.log(`  Anti-Hallucination / Calibration / Asymmetries / References) with your`);
+      console.log(`  domain's content. Set autoLoad: true in frontmatter when ready.`);
+    }
+    for (const s of result.skipped || []) {
+      console.log(`  • ${s.path}: ${s.reason}`);
+      if (s.userAction) console.log(`    → ${s.userAction}`);
+    }
+    if (result.summary.errors > 0) {
+      console.error(`\n✗ ${result.summary.errors} error(s):`);
+      for (const f of result.findings.filter(x => x.severity === 'ERROR')) {
+        console.error(`  [${f.code}] ${f.message}`);
+      }
+      process.exit(1);
+    }
+  });
+
+// HC-001: install adopter-side git hooks (pre-commit + pre-push) that
+// validate metadata.yml against the schema (SC-011) and enforce step-
+// artifact existence per metadata.yml status. First git hook the framework
+// ships. See pipeline-integrity §17 for the convention.
+program
+  .command('install-hooks')
+  .description('Install pre-commit + pre-push git hooks (per HC-001). Idempotent; refuses to overwrite unmanaged hooks unless --force.')
+  .option('--uninstall', 'remove managed hooks (only removes hooks carrying the managed-by:hone marker)')
+  .option('--mode <mode>', 'install mode: auto (default) | native | skip-husky', 'auto')
+  .option('--force', 'overwrite unmanaged existing hooks (DANGEROUS — clobbers adopter customizations)')
+  .option('--repo-root <path>', 'repo root (default: process.cwd())')
+  .option('--json', 'emit findings as JSON')
+  .action((opts) => {
+    const { installHooks, uninstallHooks } = require('./lib/install-hooks');
+    const repoRoot = opts.repoRoot || process.cwd();
+
+    const result = opts.uninstall
+      ? uninstallHooks({ repoRoot })
+      : installHooks({ repoRoot, mode: opts.mode, force: opts.force });
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(result.summary.errors > 0 ? 1 : 0);
+      return;
+    }
+
+    if (opts.uninstall) {
+      const removed = result.removed || [];
+      console.log(`Hone install-hooks --uninstall (HC-001)`);
+      if (removed.length > 0) {
+        console.log(`✓ Removed ${removed.length} managed hook(s): ${removed.join(', ')}`);
+      } else {
+        console.log(`• No managed hooks to remove (none found with managed-by:hone marker)`);
+      }
+      for (const s of result.skipped || []) {
+        console.log(`  • ${s.hook}: ${s.reason}`);
+      }
+    } else {
+      console.log(`Hone install-hooks (HC-001)`);
+      const installed = result.installed || [];
+      const skipped = result.skipped || [];
+      if (installed.length > 0) {
+        console.log(`✓ Installed ${installed.length} hook(s): ${installed.join(', ')}`);
+      }
+      for (const s of skipped) {
+        console.log(`  • ${s.hook}: ${s.reason}`);
+        if (s.userAction) console.log(`    → ${s.userAction}`);
+      }
+      if (installed.length === 0 && skipped.length === 0) {
+        console.log(`• No hooks installed (check --help for options)`);
+      }
+    }
+
+    if (result.summary.errors > 0) {
+      console.error(`\n✗ ${result.summary.errors} error(s):`);
+      for (const f of result.findings.filter(x => x.severity === 'ERROR')) {
+        console.error(`  [${f.code}] ${f.message}`);
+      }
+      process.exit(1);
+    }
+  });
+
+// SC-011 (Phase 11 of SC family): validate a story's metadata.yml against
+// the framework JSON schema. Implements what SC-010 §10 documented
+// (metadata.yml as wire protocol). Exit codes: 0 = pass, 1 = ERROR
+// findings, 2 = file or schema not found.
+program
+  .command('validate-metadata [storyId]')
+  .description('Validate .github/pipeline/<STORY-ID>/metadata.yml against the framework JSON schema. Implements SC-010 §10 (metadata.yml as wire protocol).')
+  .option('--all', 'validate every metadata.yml in .github/pipeline/')
+  .option('--repo-root <path>', 'repo root (default: process.cwd())')
+  .option('--schema <path>', 'override schema path (default: enterprise-assets/.github/schema/metadata.schema.json)')
+  .option('--json', 'emit findings as JSON')
+  .action((storyId, opts) => {
+    const { validateMetadata, validateAllMetadata } = require('./lib/validate-metadata');
+    const repoRoot = opts.repoRoot || process.cwd();
+    const schemaPath = opts.schema || require('node:path').join(repoRoot, 'enterprise-assets/.github/schema/metadata.schema.json');
+
+    if (opts.all) {
+      const result = validateAllMetadata({ repoRoot, schemaPath });
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`Hone validate-metadata — ${result.summary.fileCount} files validated`);
+        if (result.summary.errors === 0) {
+          console.log(`✓ All ${result.summary.fileCount} files validated. No errors.`);
+        } else {
+          console.log(`✗ ${result.summary.errorFileCount} of ${result.summary.fileCount} files failed validation.`);
+          for (const f of result.files) {
+            if (f.summary.errors === 0) continue;
+            console.log(`\n  ${f.filePath}:`);
+            for (const finding of f.findings.filter(x => x.severity === 'ERROR')) {
+              console.log(`    [${finding.code}] ${finding.message}`);
+            }
+          }
+        }
+      }
+      process.exit(result.summary.errors > 0 ? 1 : 0);
+    } else {
+      if (!storyId) {
+        console.error('error: provide a <STORY-ID> argument or pass --all');
+        process.exit(2);
+      }
+      const filePath = require('node:path').join(repoRoot, '.github/pipeline', storyId, 'metadata.yml');
+      const result = validateMetadata({ path: filePath, schemaPath });
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else if (result.summary.errors === 0) {
+        console.log(`✓ ${storyId}: metadata.yml passes validation. No findings.`);
+      } else {
+        console.log(`✗ ${storyId}: ${result.summary.errors} validation error(s):`);
+        for (const f of result.findings.filter(x => x.severity === 'ERROR')) {
+          console.log(`  [${f.code}] ${f.message}`);
+        }
+      }
+      // Exit code 2 if file/schema missing; 1 if validation errors; 0 if pass.
+      const hasMissingFile = result.findings.some(f => f.code === 'file-not-found' || f.code === 'schema-not-found');
+      process.exit(hasMissingFile ? 2 : (result.summary.errors > 0 ? 1 : 0));
+    }
+  });
+
+// audit runner. Shells out to `git diff origin/<base>...HEAD`, walks
+// `.github/skills/`, calls SA-001's `runAssertions()`, writes
+// `.github/pipeline/<STORY-ID>/step-5b-skill-audit.md`. Always exits 0;
+// gating deferred to OptionsFlow E29-G.
+program
+  .command('step-5b')
+  .description('Step 5b: runtime skill-application audit. Reads the story\'s referenced_skill cross-refs (LC-001), runs SA-001 assertion engine against PR diff, writes step-5b-skill-audit.md. Always exits 0 (informational; gating deferred to E29-G).')
+  .option('--base <branch>', 'base branch to diff against', 'develop')
+  .option('--story-id <id>', 'override story id (defaults to extraction from current branch name)')
+  .action(async (cmdOpts) => {
+    const { runAssertions } = require('./lib/skill-assertions');
+    const { renderStep5bArtifact } = require('./lib/skill-audit-render');
+    const { extractStoryIdFromBranch } = require('./lib/pipeline-status');
+    const { parseLearningsFile } = require('./lib/learnings-parse');
+    const { execSync } = require('node:child_process');
+    const repoRoot = process.cwd();
+
+    // 1. Resolve story id (CLI flag wins; else parse branch name)
+    let branchName = '';
+    try {
+      branchName = execSync('git rev-parse --abbrev-ref HEAD',
+        { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    } catch { /* defensive */ }
+    const storyId = cmdOpts.storyId || extractStoryIdFromBranch(branchName);
+    if (!storyId) {
+      console.error(`step-5b: cannot determine story id from branch "${branchName}". Pass --story-id explicitly. Skipping audit.`);
+      process.exit(0);  // exit 0 — informational
+    }
+
+    // 2. Capture PR diff (defensive — empty diff → no findings)
+    const baseBranch = cmdOpts.base || 'develop';
+    let diff = '';
+    try {
+      diff = execSync(`git diff origin/${baseBranch}...HEAD`,
+        { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 32 * 1024 * 1024 });
+    } catch {
+      // Fallback: no remote tracking — try local base
+      try {
+        diff = execSync(`git diff ${baseBranch}...HEAD`,
+          { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 32 * 1024 * 1024 });
+      } catch { /* leave empty */ }
+    }
+
+    // 3. Walk skills. Adopters live at .github/skills/; the hone-server
+    //    framework dogfoods against server/seeds/skills/ (same fallback as
+    //    `hone audit-skills`).
+    function collectSkillsFrom(dir) {
+      const out = [];
+      if (!fs.existsSync(dir)) return out;
+      for (const name of fs.readdirSync(dir)) {
+        const skillPath = path.join(dir, name, 'SKILL.md');
+        if (fs.existsSync(skillPath)) {
+          out.push({ id: name, content: fs.readFileSync(skillPath, 'utf8') });
+        }
+      }
+      return out;
+    }
+    let skills = collectSkillsFrom(path.join(repoRoot, '.github/skills'));
+    if (skills.length === 0) {
+      skills = collectSkillsFrom(path.join(repoRoot, 'server/seeds/skills'));
+    }
+
+    // 4. LC-001 cross-ref scoping: read story's learning file (if exists)
+    //    and pull every `referenced_skill` it declares.
+    const referencedSkills = [];
+    const learningPath = path.join(repoRoot, '.github/learnings', `${storyId}.yml`);
+    if (fs.existsSync(learningPath)) {
+      try {
+        const parsed = parseLearningsFile(fs.readFileSync(learningPath, 'utf8'),
+          { fileLabel: `${storyId}.yml` });
+        for (const e of parsed.eligible || []) {
+          if (e.referenced_skill) referencedSkills.push(e.referenced_skill);
+        }
+      } catch { /* defensive — empty referencedSkills means: evaluate all */ }
+    }
+
+    // 5. Run engine
+    const result = runAssertions({
+      diff,
+      skills,
+      referencedSkills: referencedSkills.length > 0 ? referencedSkills : undefined,
+    });
+
+    // 6. Render + write artifact
+    const artifact = renderStep5bArtifact({
+      result,
+      storyId,
+      branchName,
+      baseBranch,
+      referencedSkills,
+    });
+    const outDir = path.join(repoRoot, '.github/pipeline', storyId);
+    fs.mkdirSync(outDir, { recursive: true });
+    const outPath = path.join(outDir, 'step-5b-skill-audit.md');
+    fs.writeFileSync(outPath, artifact);
+
+    // 7. Print compact JSON summary to stdout (artifact path is the substantive output)
+    console.log(JSON.stringify({
+      story_id: storyId,
+      artifact: path.relative(repoRoot, outPath),
+      base_branch: baseBranch,
+      summary: {
+        skills_scanned: result.scannedSkills.length,
+        skills_skipped: result.skipped.length,
+        findings: result.findings.length,
+        warnings: (result.warnings || []).length,
+      },
+      // Convenience: per-severity counts
+      severity_counts: result.findings.reduce((acc, f) => {
+        const s = f.severity || 'INFO';
+        acc[s] = (acc[s] || 0) + 1;
+        return acc;
+      }, { BLOCKER: 0, WARN: 0, INFO: 0 }),
+    }, null, 2));
+
+    // Always exit 0 — Step 5b is informational. E29-G owns severity-to-gate mapping.
+    process.exit(0);
+  });
+
+// H-028g: detect platform from fingerprints + adopter config_paths.
+// Exposes cli/lib/platform-detect.js + classifyPathsForRepo readback at
+// the CLI for adopters who want to verify what the framework sees.
+program
+  .command('detect-platform')
+  .description('Detect installed platforms from fingerprint files + read platform.config_paths from .pipeline-config.yml. Prints JSON.')
+  .action(async () => {
+    const { detectPlatforms, PLATFORM_FINGERPRINTS } = require('./lib/platform-detect');
+    const { parsePlatformConfigPaths } = require('./lib/stack-paths');
+    const repoRoot = process.cwd();
+    const fileExists = (p) => fs.existsSync(path.join(repoRoot, p));
+    const detected = detectPlatforms({ repoRoot, fileExists });
+
+    let configPaths = [];
+    const cfgPath = path.join(repoRoot, '.pipeline-config.yml');
+    if (fs.existsSync(cfgPath)) {
+      try {
+        configPaths = parsePlatformConfigPaths(fs.readFileSync(cfgPath, 'utf8'));
+      } catch { /* defensive */ }
+    }
+
+    const fingerprintsByPlatform = {};
+    for (const [p, defn] of Object.entries(PLATFORM_FINGERPRINTS)) {
+      fingerprintsByPlatform[p] = defn.files.filter(fileExists);
+    }
+
+    console.log(JSON.stringify({
+      detected,
+      config_paths: configPaths,
+      fingerprints_found: fingerprintsByPlatform,
+      repo_root: repoRoot,
+    }, null, 2));
+  });
+
+// ── CLI setup ─────────────────────────────────────────────────────────────────
+program
+  .name('hone')
+  .description('Hone AI — Enterprise SDLC Pipeline CLI')
+  .version(pkg.version);
+
+program.parse(process.argv);