archondev 3.0.1 → 3.1.0

package/README.md

@@ -1,6 +1,8 @@
 # ArchonDev
 
-**AI Development Governance — Stop Babysitting Your AI Agent**
+**Govern AI code with local-first quality gates.**
+
+Development governance for code written by AI coding assistants. Reads your architecture file before any change, runs quality gates on every diff, tracks file dependencies so refactors don't silently break callers. Free, local-first, BYOK. Works as a CLI or as drop-in files for Cursor, Claude Code, Windsurf, VS Code + Copilot, Gemini, and the OpenAI Codex CLI.
 
 ## Two Ways to Use ArchonDev
 
@@ -23,7 +25,7 @@ npm install -g archondev; archon
 - Learning persistence — mistakes are remembered and avoided
 - **Dependency tracking** — prevent regressions with "what-breaks-what" map
 - Bug reporting with root cause analysis
-- AI-powered code review for any codebase
+- Reviews any codebase against the architecture file you supply, with severity-graded findings
 - Multi-provider key support with adversarial features
 - **Risk scoring** — 0-100 risk assessment before every execution
 - **Ship pipeline** — `archon ship`: review → test → version → changelog → PR
@@ -50,12 +52,12 @@ Context-aware intelligence for your existing AI tools: **Cursor, Claude Code, Wi
 
 **Governance Foundation:**
 - .archon/active/architecture.md template with best practices
-- **Quality Level / Posture** — prototype/production/enterprise-grade behavior
+- **Quality Level / Posture** — prototype, production, and enterprise postures each gate behavior differently
 - **DEPENDENCIES.md** — File-level dependency tracking to prevent regressions
 - IDE-specific rule files (.cursorrules, CLAUDE.md, GEMINI.md, etc.)
-- **24 on-demand AI skills** — Design review, debugging, ship readiness, scope review, accessibility, SEO/GEO, color scheme picker, expert review, features dashboard, and more — loaded only when triggered, keeping context lean
+- **27 on-demand AI skills** — Design review, debugging, ship readiness, truth layer, human memory map, AI-washing audit, scope review, accessibility, SEO/GEO, color scheme picker, expert review, features dashboard, and more — loaded only when triggered, keeping context lean
 - **Skills-based architecture** — 80% smaller context footprint (8.6 KB core vs 42 KB monolithic). Skills load on-demand with progressive disclosure
-- **Claude Code: 16 native slash commands** — `/debug`, `/design-review`, `/ship-readiness`, `/code-review`, `/scope-check`, `/expert-review`, `/geo-optimize`, `/seo-check`, `/accessibility`, `/reflect`, `/handoff`, `/plan-tasks`, `/color-scheme`, `/rollback`, `/dashboard`, `/constitution`
+- **Claude Code: 19 native slash commands** — `/debug`, `/design-review`, `/ship-readiness`, `/code-review`, `/scope-check`, `/expert-review`, `/geo-optimize`, `/seo-check`, `/accessibility`, `/reflect`, `/handoff`, `/plan-tasks`, `/color-scheme`, `/rollback`, `/dashboard`, `/constitution`, `/memory-map`, `/washing-audit`, `/truth-layer`
 - **GEO Optimization** — 7-phase protocol for AI search citation: identity phrases, atomic claims, JSON-LD schemas, and audit ([free tools](https://archondev.io/geo))
 - **Task Extraction** — AI confirms all items before starting, nothing gets forgotten
 - **Context Handoff** — Memory management for long sessions
@@ -80,14 +82,14 @@ pnpm exec tsx scripts/init-governance-db.ts
 | `archon init` | Initialize in your project |
 | `archon mode` | Choose local governance mode or BYOK AI mode |
 | `archon config ai` | Guided BYOK provider-key setup |
-| `archon status` | Show local mode, auth, and project status |
+| `archon status` | Show local mode and any old local legacy-session tokens |
 | `archon plan <description>` | Create a work item with AI planning (extracts and confirms multi-item requests) |
 | `archon execute <atom-id>` | Execute with quality gates |
 | `archon list` | List all work items |
 | `archon show <atom-id>` | Show details |
 | `archon watch` | Live TUI dashboard with status |
 | `archon bug report <title>` | Bug report with root cause analysis |
-| `archon review init` | Initialize AI-powered code review |
+| `archon review init` | Initialize the local code review database |
 | `archon review analyze` | Scan project and populate review tasks |
 | `archon review run` | Run AI review on pending tasks |
 | `archon usage` | Usage by period and model |
@@ -105,8 +107,15 @@ pnpm exec tsx scripts/init-governance-db.ts
 | `archon a11y pre-deploy` | Interactive pre-deployment check |
 | `archon seo check` | Run SEO meta tag audit |
 | `archon seo fix` | Apply recommended SEO fixes |
-| `archon geo identity` | Generate brand identity phrases for AI citation |
-| `archon geo schema` | Generate JSON-LD schemas |
+| `archon geo identity` | Generate 7-word phrase + 50-word description + businessContext/audienceContext artifacts |
+| `archon geo schema` | Generate Organization + Service + WebSite JSON-LD |
+| `archon geo faq` | Generate FAQPage JSON-LD (sentence-budget validated) |
+| `archon geo claims` | Generate atomic claims (≤18 tokens each) for agent citation |
+| `archon geo audit` | Agent Clarity Audit — multi-surface walk (homepage, pricing, docs, comparison, etc.) |
+| `archon geo washing-audit` | AI-Washing Risk Register — find unsupported claims, defensible rewrites |
+| `archon truth-layer init` | Create `.archon/truth-layer.md` — the living claims-and-evidence artifact |
+| `archon truth-layer audit` | Compare truth layer to public surfaces; flag gaps |
+| `archon brand memory-map` | Human Memory Map — pressure-test what humans actually remember |
 | `archon governance status` | Show governance status (AGD) |
 | `archon governance architecture update` | Update architecture with change reason |
 | `archon governance task update` | Update governance tasks |
@@ -173,7 +182,7 @@ No Archon token markup. You pay your LLM provider directly at their published ra
 ```bash
 $ archon
 
-ArchonDev - AI-Powered Development Governance
+ArchonDev — Development Governance for AI-Assisted Code
 ────────────────────────────────────────────────
 
 AI mode: Local governance only
@@ -195,38 +204,24 @@ Type these anytime during interactive prompts:
 | Command | Description |
 |---------|-------------|
 | `config ai` | Open BYOK key setup |
-| `status` | Show local mode and optional auth info |
+| `status` | Show local mode and old legacy-session token status |
 | `keys` | List configured API keys |
 | `help` | Show available commands |
 | `quit` | Exit ArchonDev |
 
-## Cloud Execution (Legacy)
-
-These commands are preserved only for backward compatibility and are hidden from the normal CLI surface.
-They are not part of the current local-first product path.
+## Retired Remote Paths
 
-```bash
-# 1. Authenticate
-archon login
+Platform login, GitHub OAuth, cloud execution, cloud sessions, Supabase usage tracking, Stripe credits, and remote model-registry sync are retired for the current product. Hidden compatibility commands now print a retirement message instead of calling Supabase or Fly.
 
-# 2. Connect GitHub (one-time setup)
-archon github connect       # Opens browser for authorization
-archon github status        # Verify connection
+Use local execution with BYOK keys:
 
-# 3. Plan locally, execute in cloud
+```bash
+archon config ai
 archon plan "add user settings page"
-archon execute ATOM-001 --cloud
-
-# 3b. Queue multiple atoms in parallel (legacy command; disabled in free/BYOK mode)
-archon parallel cloud ATOM-001 ATOM-002
-
-# 4. Check progress
-archon cloud status         # List all cloud executions
-archon cloud logs <id>      # View execution logs
+archon execute ATOM-001
+archon usage
 ```
 
-Cloud execution is currently disabled in the free/BYOK model. Use local execution with BYOK keys.
-
 ## Working with Existing Projects
 
 Have a project created by another AI agent? ArchonDev can review it first, then govern future changes.

package/dist/auth-ZMBA5HYH.js

@@ -0,0 +1,13 @@
+import {
+  login,
+  logout,
+  status
+} from "./chunk-RAM67KA6.js";
+import "./chunk-EV5QU5KG.js";
+import "./chunk-NQBS7L2F.js";
+import "./chunk-4VNS5WPM.js";
+export {
+  login,
+  logout,
+  status
+};

package/dist/{bug-TFICZ4OP.js → bug-MOMNYU5J.js}

@@ -1,11 +1,11 @@
 import {
   bugReport
-} from "./chunk-4TZOCXAI.js";
+} from "./chunk-ECEWULAA.js";
 import "./chunk-IYZN6FPJ.js";
 import "./chunk-D3TVDCJA.js";
 import "./chunk-NIIFUBOE.js";
+import "./chunk-NQBS7L2F.js";
 import "./chunk-7C6JELBL.js";
-import "./chunk-GGRW4NTA.js";
 import "./chunk-4VNS5WPM.js";
 export {
   bugReport

package/dist/{chunk-43IIEFB2.js → chunk-7ELR6RW6.js}

@@ -1,6 +1,6 @@
 import {
   listLocalAtoms
-} from "./chunk-7RXZTPXY.js";
+} from "./chunk-BSG5XY3C.js";
 
 // src/cli/list.ts
 import chalk from "chalk";

package/dist/{chunk-IG3H7C7R.js → chunk-ARHCVLQW.js}

@@ -1,13 +1,13 @@
+import {
+  loadConfig,
+  saveConfig
+} from "./chunk-NQBS7L2F.js";
 import {
   KeyValidator
 } from "./chunk-TFSHS7EN.js";
 import {
   keyManager
 } from "./chunk-RDG5BUED.js";
-import {
-  loadConfig,
-  saveConfig
-} from "./chunk-GGRW4NTA.js";
 
 // src/cli/keys.ts
 import chalk from "chalk";

package/dist/chunk-AWHINKO2.js

@@ -0,0 +1,244 @@
+import {
+  BANNED_WORDS_AI_WASHING,
+  BANNED_WORDS_GENERIC,
+  detectSurfaces
+} from "./chunk-EF66S6ZQ.js";
+import {
+  ArchitectAgent
+} from "./chunk-D3TVDCJA.js";
+
+// src/cli/truth-layer.ts
+import { Command } from "commander";
+import chalk from "chalk";
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { existsSync } from "fs";
+import { join } from "path";
+var TRUTH_LAYER_PATH = ".archon/truth-layer.md";
+var TRUTH_LAYER_TEMPLATE = `# Truth Layer
+
+Living infrastructure. Sales, product, marketing, and AI agents all read from this. Update it as reality changes.
+
+> Edit freely. This file is the source of truth for every content-touching command. If a claim is not in here, do not publish it.
+
+## Identity
+
+- **7-word phrase:** _(pulled from .archon/config.yaml after \`archon geo identity\`)_
+- **50-word description:** _(same)_
+- **businessContext:** _(see .archon/geo/context.md)_
+- **audienceContext:** _(see .archon/geo/context.md)_
+
+## Claims and Evidence
+
+Every claim made on a public surface must appear in this table with at least one piece of evidence. If you cannot fill the Evidence column, the claim is AI-washing and must be rewritten or removed.
+
+| Claim | Where it appears | Evidence | Owner | Last verified |
+|-------|------------------|----------|-------|---------------|
+| _example: "Cuts onboarding time 60% for healthcare teams"_ | homepage hero, pricing | Customer case study X (link, date) | _name_ | YYYY-MM-DD |
+
+## Customer Language Library
+
+Phrases that came from real customers \u2014 interviews, calls, reviews. Do not paraphrase.
+
+- _example: "I stopped having to babysit the agent" \u2014 Sarah, healthcare ops, 2026-03-12_
+
+## Proof Library
+
+Numbers, named outcomes, named integrations, named customers, named references.
+
+- _example: 12,000 active developers as of 2026-04-01_
+- _example: integrates with Stripe, Cursor, GitHub_
+
+## Competitive Positioning
+
+Three direct comparisons. What we beat, what beats us, what is genuinely a tie.
+
+| Competitor | We beat them on | They beat us on |
+|------------|-----------------|-----------------|
+| _example: CompetitorX_ | local-first, no-cloud, BYOK | enterprise SSO |
+
+## Constraints (What we do NOT do)
+
+- _example: We do not host customer data._
+- _example: We do not run AI without a user-supplied key._
+
+Stating what the product does NOT do is high-leverage for agent legibility. Agents reading vague capability claims often invent capabilities; constraints anchor reality.
+
+## Pricing Logic
+
+Why it costs what it costs. What each tier actually gates. If pricing is intentionally hidden, document why.
+
+- _example: Free is the full product. The CLI is BYOK. We make money on Pro for teams >5._
+
+## Objection Bank
+
+Top 10 objections + the honest response.
+
+| Objection | Honest response |
+|-----------|-----------------|
+| _example: "Doesn't the AI just write whatever it wants?"_ | _example: No \u2014 quality gates block changes that violate architecture invariants. See \`archon governance\`._ |
+
+## Category Beliefs
+
+The 2\u20133 things this company believes about its market that competitors do not. These are NOT taglines. These are the underlying convictions that produce the strategy.
+
+- _example: "AI quality cannot be a layer you add. It has to be where the code-writing happens."_
+
+## Memorability Test
+
+What is the ONE thing you want a human to carry into an agent prompt six months from now? Pass the competitor test \u2014 could any competitor honestly write the same line?
+
+- _intended memory:_ _(fill in)_
+- _competitor test:_ _(could any direct competitor say this? if yes, sharpen.)_
+
+---
+
+_Generated by \`archon truth-layer init\`. Re-generate with \`archon truth-layer audit\`._
+`;
+async function truthLayerInit() {
+  const cwd = process.cwd();
+  const fullPath = join(cwd, TRUTH_LAYER_PATH);
+  if (existsSync(fullPath)) {
+    console.log(chalk.yellow(`Truth Layer already exists at ${TRUTH_LAYER_PATH}.`));
+    console.log(chalk.dim(`Edit it directly, or run 'archon truth-layer audit' to scan it for gaps.`));
+    return;
+  }
+  const archonDir = join(cwd, ".archon");
+  if (!existsSync(archonDir)) await mkdir(archonDir, { recursive: true });
+  await writeFile(fullPath, TRUTH_LAYER_TEMPLATE, "utf-8");
+  console.log(chalk.green(`\u2705 Truth Layer initialized at ${TRUTH_LAYER_PATH}`));
+  console.log();
+  console.log(chalk.bold("Next steps:"));
+  console.log(chalk.dim(`  1. Open ${TRUTH_LAYER_PATH} and fill in the sections marked _example_.`));
+  console.log(chalk.dim(`  2. Run 'archon geo identity' to populate the Identity section.`));
+  console.log(chalk.dim(`  3. Run 'archon truth-layer audit' to find unsupported claims in your copy.`));
+}
+var TRUTH_LAYER_AUDIT_PROMPT = `You audit a company's truth layer against its public surfaces. Your job is to find:
+  1. Claims that appear publicly but are NOT in the truth layer's claims-and-evidence table.
+  2. Constraints implied by the product but not declared in the constraints section.
+  3. Customer language used publicly that was synthesized rather than sourced.
+  4. Inconsistencies between the truth layer and what surfaces actually say.
+
+Be direct. Do not soften findings.
+
+Output strict JSON.`;
+async function truthLayerAudit() {
+  const cwd = process.cwd();
+  const truthPath = join(cwd, TRUTH_LAYER_PATH);
+  console.log(chalk.blue("\n\u{1F4D0} Truth Layer Audit\n"));
+  if (!existsSync(truthPath)) {
+    console.log(chalk.yellow(`No truth-layer.md found.`));
+    console.log(chalk.dim(`Run 'archon truth-layer init' first.
+`));
+    return [];
+  }
+  const truthLayer = await readFile(truthPath, "utf-8");
+  const surfaces = await detectSurfaces(cwd);
+  if (surfaces.length === 0) {
+    console.log(chalk.yellow("No public surfaces detected to audit against."));
+    return [];
+  }
+  const corpus = surfaces.map((s) => `--- ${s.label} ---
+${s.content.slice(0, 4e3)}`).join("\n\n");
+  console.log(chalk.dim(`Comparing truth layer against ${surfaces.length} surface(s)...
+`));
+  const agent = new ArchitectAgent({ temperature: 0.3 });
+  const prompt = `Truth Layer:
+
+${truthLayer}
+
+Public surfaces:
+
+${corpus}
+
+Audit. Output JSON:
+{
+  "gaps": [
+    {
+      "type": "unbacked-claim|missing-constraint|synthetic-language|inconsistency",
+      "description": "what is the problem",
+      "surface": "which surface this came from",
+      "recommendation": "what to do \u2014 add to truth layer OR remove from copy"
+    }
+  ]
+}`;
+  const response = await agent.client.chat(
+    TRUTH_LAYER_AUDIT_PROMPT,
+    prompt,
+    { temperature: 0.3, maxTokens: 3e3 }
+  );
+  const jsonMatch = response.content.match(/\{[\s\S]*\}/);
+  if (!jsonMatch) {
+    console.log(chalk.red("Failed to parse audit response."));
+    return [];
+  }
+  const parsed = JSON.parse(jsonMatch[0]);
+  const gaps = parsed.gaps ?? [];
+  const lower = truthLayer.toLowerCase();
+  for (const banned of [...BANNED_WORDS_GENERIC, ...BANNED_WORDS_AI_WASHING]) {
+    if (lower.includes(banned.toLowerCase())) {
+      gaps.push({
+        type: "synthetic-language",
+        description: `Banned filler word "${banned}" appears in the truth layer itself.`,
+        surface: "truth-layer.md",
+        recommendation: "Replace with specific, defensible language."
+      });
+    }
+  }
+  if (gaps.length === 0) {
+    console.log(chalk.green("\u2705 No gaps found between truth layer and public surfaces."));
+    return [];
+  }
+  console.log(chalk.bold(`Found ${gaps.length} gap(s):
+`));
+  const byType = {
+    "unbacked-claim": [],
+    "missing-constraint": [],
+    "synthetic-language": [],
+    inconsistency: []
+  };
+  for (const g of gaps) byType[g.type]?.push(g);
+  for (const t of ["unbacked-claim", "inconsistency", "missing-constraint", "synthetic-language"]) {
+    const list = byType[t] ?? [];
+    if (list.length === 0) continue;
+    console.log(chalk.yellow.bold(`  ${t.toUpperCase()} (${list.length})`));
+    list.forEach((g, i) => {
+      console.log(chalk.yellow(`    ${i + 1}. ${g.description}`));
+      console.log(chalk.dim(`       Surface: ${g.surface}`));
+      console.log(chalk.dim(`       Recommendation: ${g.recommendation}`));
+    });
+    console.log();
+  }
+  return gaps;
+}
+function createTruthLayerCommand() {
+  const cmd = new Command("truth-layer").description("Truth Layer \u2014 living infrastructure for claims, evidence, customer language, proof").addHelpText(
+    "after",
+    `
+Examples:
+  archon truth-layer init       Create .archon/truth-layer.md from template
+  archon truth-layer audit      Audit truth layer against detected public surfaces
+`
+  );
+  cmd.command("init").description("Create .archon/truth-layer.md from template").action(async () => {
+    await truthLayerInit();
+  });
+  cmd.command("audit").description("Find gaps between truth layer and public surfaces").action(async () => {
+    await truthLayerAudit();
+  });
+  cmd.action(async () => {
+    const cwd = process.cwd();
+    if (!existsSync(join(cwd, TRUTH_LAYER_PATH))) {
+      await truthLayerInit();
+    } else {
+      await truthLayerAudit();
+    }
+  });
+  return cmd;
+}
+
+export {
+  TRUTH_LAYER_TEMPLATE,
+  truthLayerInit,
+  truthLayerAudit,
+  createTruthLayerCommand
+};

package/dist/{chunk-7RXZTPXY.js → chunk-BSG5XY3C.js}

@@ -2,9 +2,6 @@ import {
   appendLocalUsageEntry,
   debugLog
 } from "./chunk-I3BBA7MB.js";
-import {
-  ArchitectureParser
-} from "./chunk-5EVHUDQX.js";
 import {
   createAtom,
   validateAtom
@@ -15,15 +12,18 @@ import {
 import {
   createAIClient
 } from "./chunk-NIIFUBOE.js";
+import {
+  isAuthenticated
+} from "./chunk-NQBS7L2F.js";
+import {
+  ArchitectureParser
+} from "./chunk-5EVHUDQX.js";
 import {
   getModelProvider
 } from "./chunk-7C6JELBL.js";
 import {
   KeyManager
 } from "./chunk-RDG5BUED.js";
-import {
-  isAuthenticated
-} from "./chunk-GGRW4NTA.js";
 
 // src/cli/plan.ts
 import chalk from "chalk";

package/dist/{chunk-AJNKSFHL.js → chunk-CI5E4EX3.js}

@@ -1,5 +1,7 @@
 // src/cli/ship.ts
 import chalk from "chalk";
+import { existsSync as existsSync2 } from "fs";
+import { join as join3 } from "path";
 
 // src/core/ship/pipeline.ts
 import { execSync } from "child_process";
@@ -54,17 +56,21 @@ function parseCommitMessages(commitLines) {
   return commitLines.map((line) => {
     const trimmed = line.trim();
     const match = trimmed.match(/^([a-z]+)(?:\([^)]*\))?[!]?:\s*(.+)/);
-    if (match) {
-      const type = match[1];
+    const commitType = match?.[1];
+    const message = match?.[2];
+    if (commitType && message) {
+      const type = commitType;
       const validTypes = ["feat", "fix", "refactor", "docs", "chore"];
       return {
         type: validTypes.includes(type) ? type : "other",
-        message: match[2]
+        message
       };
     }
     const hashMatch = trimmed.match(/^([0-9a-f]{7,40})\s+(.+)/);
-    if (hashMatch) {
-      return { type: "other", message: hashMatch[2], hash: hashMatch[1] };
+    const hash = hashMatch?.[1];
+    const hashMessage = hashMatch?.[2];
+    if (hash && hashMessage) {
+      return { type: "other", message: hashMessage, hash };
     }
     return { type: "other", message: trimmed };
   }).filter((e) => e.message.length > 0);
@@ -400,6 +406,61 @@ async function runPostShipDocCheck(cwd, changedFiles) {
 // src/cli/ship.ts
 import { createInterface } from "readline";
 import { execSync as execSync2 } from "child_process";
+var PUBLIC_COPY_PATTERNS = [
+  /^README\.md$/i,
+  /(^|\/)CHANGELOG\.md$/i,
+  /(^|\/)pricing\./i,
+  /(^|\/)index\.(html|astro|tsx|jsx|svelte|vue)$/i,
+  /(^|\/)src\/pages\//i,
+  /(^|\/)docs\.(html|astro|tsx|jsx|md|mdx)$/i,
+  /(^|\/)compare\./i,
+  /(^|\/)integrations\./i,
+  /(^|\/)customers\./i,
+  /(^|\/)case-studies\//i
+];
+function changeTouchesPublicCopy(files) {
+  return files.some((f) => PUBLIC_COPY_PATTERNS.some((p) => p.test(f)));
+}
+async function runCoherenceGate(cwd, options) {
+  const truthPath = join3(cwd, ".archon", "truth-layer.md");
+  if (!existsSync2(truthPath)) {
+    return { blocking: false, message: "No truth-layer.md found \u2014 skipping coherence gate. Consider `archon truth-layer init`." };
+  }
+  let changedFiles = [];
+  try {
+    const baseRef = options.baseBranch ?? "main";
+    const out = execSync2(`git diff --name-only ${baseRef}...HEAD`, { cwd, encoding: "utf-8" });
+    changedFiles = out.split("\n").map((s) => s.trim()).filter(Boolean);
+  } catch {
+    return { blocking: false, message: "Could not compute changeset \u2014 coherence gate skipped." };
+  }
+  if (!changeTouchesPublicCopy(changedFiles)) {
+    return { blocking: false, message: "No public-facing copy in changeset \u2014 coherence gate not required." };
+  }
+  console.log(chalk.bold("\nTruth-Layer Coherence Gate"));
+  console.log(chalk.dim(`  Public-facing copy changed in ${changedFiles.filter((f) => PUBLIC_COPY_PATTERNS.some((p) => p.test(f))).length} file(s).`));
+  console.log(chalk.dim("  Running truth-layer audit against detected public surfaces..."));
+  try {
+    const { truthLayerAudit } = await import("./truth-layer-7N32HKCE.js");
+    const gaps = await truthLayerAudit();
+    const critical = gaps.filter((g) => g.type === "unbacked-claim" || g.type === "inconsistency");
+    if (critical.length > 0) {
+      return {
+        blocking: true,
+        message: `Coherence gate BLOCKED: ${critical.length} unbacked claim(s) or inconsistency(ies) between truth layer and public surfaces.`
+      };
+    }
+    if (gaps.length > 0) {
+      return {
+        blocking: false,
+        message: `Coherence gate: ${gaps.length} non-critical gap(s) (constraints / synthetic language). Review .archon/truth-layer.md after ship.`
+      };
+    }
+    return { blocking: false, message: "Coherence gate: PASSED." };
+  } catch (err) {
+    return { blocking: false, message: `Coherence gate could not run: ${err.message}` };
+  }
+}
 function createPrompt() {
   const rl = createInterface({
     input: process.stdin,
@@ -440,11 +501,25 @@ async function ship(options = {}) {
       console.log(chalk.dim("  (dry run \u2014 no changes will be made)"));
     }
     console.log();
+    const gate = await runCoherenceGate(cwd, options);
+    if (gate.blocking) {
+      console.log(chalk.red(gate.message));
+      console.log(chalk.dim("Fix the truth layer or rewrite the offending public copy before shipping."));
+      console.log(chalk.dim("Override (not recommended): set ARCHON_SKIP_COHERENCE_GATE=1"));
+      if (process.env.ARCHON_SKIP_COHERENCE_GATE !== "1") {
+        return;
+      }
+      console.log(chalk.yellow("  Override applied \u2014 continuing despite coherence gate failure."));
+    } else if (gate.message) {
+      console.log(chalk.dim(gate.message));
+    }
+    console.log();
     const pipeline = new ShipPipeline(cwd, options);
     const result = await pipeline.run();
     const totalSteps = result.steps.length;
     for (let i = 0; i < result.steps.length; i++) {
       const step = result.steps[i];
+      if (!step) continue;
       const stepNum = `[${i + 1}/${totalSteps}]`;
       const detail = step.detail ? chalk.dim(` ${step.detail}`) : "";
       const error = step.error ? chalk.red(` \u2014 ${step.error}`) : "";

package/dist/{chunk-4TZOCXAI.js → chunk-ECEWULAA.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-D3TVDCJA.js";
 import {
   loadConfig
-} from "./chunk-GGRW4NTA.js";
+} from "./chunk-NQBS7L2F.js";
 
 // src/cli/bug.ts
 import chalk from "chalk";