@davesheffer/hunch 1.7.0 → 1.7.1

package/dist/cli/index.js

@@ -17,6 +17,7 @@ import "./preflight.js"; // MUST stay the first import — Node-version gate bef
 import { existsSync, readFileSync, writeFileSync, mkdirSync, realpathSync } from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
 import { join, relative, dirname, basename, resolve, isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { hunchPaths, hunchPathsForDir, findRoot, toPosixTarget } from "../core/paths.js";
 import { writeFileAtomic } from "../core/io.js";
@@ -29,7 +30,7 @@ import { indexRepo } from "../extractors/indexer.js";
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
 import { parseTestReport } from "../extractors/testreport.js";
 import { readSynthesisPreference, resolveSynthesisProvider, selectProvider, SYNTH_PREFERENCES, writeSynthesisPreference, } from "../synthesis/provider.js";
-import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, workingFiles, commitFiles, asOfDate, stagedDiff, workingDiff, commitDiff, rangeFiles, rangeDiff, rangeSubjects, revExists, commitAndPushHunch, pullHunch, gitUntrackCached, gitCommonDir, isLinkedWorktree, mainWorktreeRoot } from "../extractors/git.js";
+import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, workingFiles, commitFiles, asOfDate, stagedDiff, workingDiff, commitDiff, rangeFiles, rangeDiff, rangeSubjects, revExists, revParse, commitAndPushHunch, pullHunch, gitUntrackCached, gitCommonDir, isLinkedWorktree, mainWorktreeRoot } from "../extractors/git.js";
 import { writeTeamConfig, ensureTeamOverlay, readTeamConfig } from "../integrations/team.js";
 import { runbookId, decisionId } from "../core/ids.js";
 import { deriveForbids, effectiveForbids } from "../core/constraintmatch.js";
@@ -44,25 +45,34 @@ import { ensureGitignore, ignoreHunchMemory, HUNCH_MEMORY_DIRS } from "../integr
 import { writeCiWorkflow } from "../integrations/ciAction.js";
 import { updateClaudeMd } from "../integrations/claudemd.js";
 import { writeMcpJson, writeSlashCommands, installClaudeHooks } from "../integrations/scaffold.js";
-import { scaffoldProviders, regenerateGrounding, refreshExistingGrounding } from "../integrations/providers.js";
+import { scaffoldProviders, regenerateGrounding, refreshExistingGrounding, refreshCommittableGrounding } from "../integrations/providers.js";
 import { healClaudeConfigCaseSplit } from "../integrations/claudeConfig.js";
 import { formatContext, formatStructure } from "../core/format.js";
 import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness } from "../core/config.js";
 import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpolicy.js";
+import { appendEvent, readEvents } from "../core/events.js";
+import { computeStats, formatStats } from "../core/stats.js";
 import { injectionMode } from "../core/hookcache.js";
 import { contextHookOutput, denyHookOutput, hookProvider, normalizeHookEvent, stopHookOutput } from "../core/agenthook.js";
 import { PIPELINE_LOOP, UNVERIFIED_NAG, loadPipelineState, onCommand, onEdit, onPrompt, onSkill, pipelineEnabled, savePipelineState, stopVerdict, } from "../core/pipeline.js";
-import { draftDuplicateOf } from "../core/dupdetect.js";
+import { draftDuplicateOf, isAcceptedDuplicateAnchor } from "../core/dupdetect.js";
 import { planAutoReview, planMutations } from "../core/autoreview.js";
 import { loadGoldenSet, evaluateGraphLift } from "../eval/harness.js";
 import { loadGuardCases, evalGuards, generateGuardCases } from "../eval/guards.js";
 import { computeDrift } from "../core/drift.js";
+import { renderCompilerScorecard, scoreCompilerCaseBank } from "../constitution/scorecard.js";
 import { generateWiki, wikiStatus, wikiPrompt, publicHome, privateHome, readWikiManifestAt, nowData } from "../wiki/wiki.js";
 import { adoptProsePrompt } from "../wiki/adopt.js";
 import { topicCollisions, renderGrounding } from "../core/topics.js";
 import { parseDocAnchors, renderDocGrounding } from "../core/docanchors.js";
 import { compareCandidates } from "../core/compare.js";
 import { checkConformance } from "../core/conformance.js";
+import { ConstitutionService } from "../constitution/service.js";
+import { renderProofCard } from "../constitution/card.js";
+import { movePolicyArtifactsToPrivate } from "../constitution/repository.js";
+import { HistoryDispositionClassificationSchema } from "../constitution/schema.js";
+import { G2_RUNBOOK_CATEGORIES } from "../constitution/g2.js";
+import { subscriptionCliVersion } from "../constitution/experimentRunner.js";
 import { draftTripwires, knownRepoDeps } from "../synthesis/tripwires.js";
 import { constraintId } from "../core/ids.js";
 import { readManifest, writeManifest, SCHEMA_VERSION } from "../core/migrate.js";
@@ -333,15 +343,20 @@ program
         verify: opts.verify,
         samples: parseSamples(opts.samples),
     });
+    const doCommit = opts.commit ?? store.autoCommit;
     if (r.status === "written") {
         store.reindex();
-        // Don't rewrite grounding from the hook — it would dirty the working tree on
-        // every commit. Off the hook (manual `hunch sync`), self-heal ALL existing
-        // grounding docs (param-name fixes + fresh counts), not just CLAUDE.md.
+        // Refresh grounding so committed counts track the store. Git-CLEAN docs are
+        // refreshed and folded into the capture commit below (kills the refresh-counts
+        // treadmill: every capture bumped the count and re-staled the docs for the
+        // release gate's clean-tree check). A user-dirty doc is never touched from the
+        // hook; manual `hunch sync` still self-heals ALL existing grounding docs.
+        const groundingToStage = toOverlay ? [] : refreshCommittableGrounding(root, store);
         if (!opts.fromHook) {
             const healed = refreshExistingGrounding(root, store);
-            if (healed.length && !opts.quiet)
-                console.log(`  ↳ grounding refreshed: ${healed.join(", ")}`);
+            const refreshed = [...new Set([...groundingToStage.map((file) => relative(root, file)), ...healed])];
+            if (refreshed.length && !opts.quiet)
+                console.log(`  ↳ grounding refreshed: ${refreshed.join(", ")}`);
         }
         // Persist the captured decision in the repo it landed in (private store under
         // --private, else this repo). ON by default (follows auto-commit; --no-commit or
@@ -351,10 +366,9 @@ program
         // hook (no recursion). The overlay is pushed; the public .hunch/ is committed
         // WITHOUT pushing — auto-pushing the user's code branch would publish their
         // unpushed commits (bug_overlay_clobber lineage).
-        const doCommit = opts.commit ?? store.autoCommit;
         const commitTarget = doCommit ? (toOverlay ? store.privateDir : hunchPaths(root).hunch) : undefined;
         if (commitTarget) {
-            commitAndPushHunch(commitTarget, `hunch: capture ${r.decision?.id ?? "decision"}`, { push: toOverlay });
+            commitAndPushHunch(commitTarget, `hunch: capture ${r.decision?.id ?? "decision"}`, { push: toOverlay, alsoStage: groundingToStage });
             if (!opts.quiet)
                 console.log(`  ↳ committed ${toOverlay ? "+ pushed " : ""}${r.decision?.id} (${commitTarget}${toOverlay ? "" : " — rides your next push"})`);
         }
@@ -364,6 +378,26 @@ program
     else if (!opts.quiet) {
         console.log(`· skipped: ${r.reason}`);
     }
+    try {
+        const constitution = new ConstitutionService(store, root);
+        if (constitution.g2Repository.currentPlan()) {
+            indexRepo(store, root, { churn: false });
+            store.reindex();
+            const sweep = constitution.g2ShadowSweep();
+            if (sweep.recorded.length && doCommit && store.privateDir) {
+                commitAndPushHunch(store.privateDir, `hunch: record ${sweep.recorded.length} G2 shadow observation(s)`);
+            }
+            if (!opts.quiet) {
+                console.log(`  ↳ G2 shadow: ${sweep.recorded.length} recorded · ${sweep.existing.length} existing · ${sweep.failures.length} failed; authority none`);
+            }
+        }
+    }
+    catch (e) {
+        // Post-commit learning is background/best-effort. Shadow operation must
+        // never make a source commit, decision capture, warning, or block fail.
+        if (!opts.quiet)
+            console.log(`  ↳ G2 shadow skipped safely: ${e.message}`);
+    }
     store.close();
 });
 function configureOverlay(dir, opts, mode) {
@@ -491,6 +525,7 @@ function configureOverlay(dir, opts, mode) {
         const pub = new JsonStore(paths);
         const priv = new JsonStore(hunchPathsForDir(hunchDir));
         const res = movePublicMemoryToPrivate(pub, priv);
+        const constitutionMoved = movePolicyArtifactsToPrivate(paths.hunch, hunchDir);
         for (const kind of ENTITY_KINDS)
             pub.dropAll(kind); // public store now empty on disk
         if (isGitRepo(root))
@@ -500,7 +535,22 @@ function configureOverlay(dir, opts, mode) {
         const grounding = regenerateGrounding(root, gstore);
         gstore.close();
         commitAndPushHunch(hunchDir, "hunch: absorb public memory into private overlay"); // durable
-        const breakdown = Object.entries(res.moved).map(([k, n]) => `${n} ${k}`).join(", ") || "0 records";
+        const breakdownParts = Object.entries(res.moved).map(([k, n]) => `${n} ${k}`);
+        if (constitutionMoved.policies)
+            breakdownParts.push(`${constitutionMoved.policies} policies`);
+        if (constitutionMoved.proofs)
+            breakdownParts.push(`${constitutionMoved.proofs} proofs`);
+        if (constitutionMoved.plans)
+            breakdownParts.push(`${constitutionMoved.plans} proof plans`);
+        if (constitutionMoved.evidence)
+            breakdownParts.push(`${constitutionMoved.evidence} evidence events`);
+        if (constitutionMoved.corpora)
+            breakdownParts.push(`${constitutionMoved.corpora} proof corpora`);
+        if (constitutionMoved.dispositions)
+            breakdownParts.push(`${constitutionMoved.dispositions} history dispositions`);
+        if (constitutionMoved.shadow)
+            breakdownParts.push(`${constitutionMoved.shadow} shadow records`);
+        const breakdown = breakdownParts.join(", ") || "0 records";
         migrateNote =
             `  ✓ migrated public memory → overlay (${breakdown}); public store emptied\n` +
                 `  ✓ untracked + gitignored the .hunch memory tree — this repo is now CODE-ONLY\n` +
@@ -935,6 +985,1007 @@ program
     }
     store.close();
 });
+// ---- policy (Hunch Constitution — versioned policy/proof lifecycle) -------
+const policyCmd = program
+    .command("policy")
+    .description("Hunch Constitution: compile, prove, inspect, activate, and evaluate deterministic engineering policy.");
+policyCmd
+    .command("list")
+    .description("List Policy IR records from the public store plus the local private overlay.")
+    .option("--state <state>", "filter by lifecycle state")
+    .option("--public-only", "exclude private-overlay policy records")
+    .action((opts) => {
+    const { store, root } = storeFor();
+    try {
+        const policies = new ConstitutionService(store, root).list({ state: opts.state, publicOnly: opts.publicOnly });
+        if (!policies.length) {
+            console.log("No Constitution policies found.");
+            return;
+        }
+        for (const p of policies) {
+            console.log(`${p.id}  [${p.state}] [${p.severity}] ${p.statement}${p.data_class === "public" ? "" : ` [${p.data_class}]`}`);
+        }
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+policyCmd
+    .command("show")
+    .description("Show canonical Policy IR and, optionally, its proof artifact.")
+    .argument("<id>", "policy id")
+    .option("--proof", "include the linked proof artifact")
+    .option("--public-only", "exclude private-overlay policy records")
+    .action((id, opts) => {
+    const { store, root } = storeFor();
+    try {
+        const service = new ConstitutionService(store, root);
+        const policy = service.get(id, { publicOnly: opts.publicOnly });
+        const output = { policy };
+        if (opts.proof && policy.proof)
+            output.proof = service.proof(policy.proof, { publicOnly: opts.publicOnly });
+        console.log(JSON.stringify(output, null, 2));
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+policyCmd
+    .command("corpus")
+    .description("Import or inspect a policy-bound known-good/known-bad commit corpus. Known-good fixtures may carry a human attestation; imported refs resolve to immutable SHAs.")
+    .argument("<id>", "policy id")
+    .option("--import <file>", "JSON file with known_bad/known_good ref and label arrays; known_good may include attestation { actor, reason }")
+    .option("--public-only", "exclude private-overlay policy/corpus records when inspecting")
+    .action((id, opts) => {
+    const { store, root } = storeFor();
+    try {
+        const service = new ConstitutionService(store, root);
+        if (opts.import) {
+            if (opts.publicOnly)
+                throw new Error("--public-only cannot be combined with --import");
+            const file = resolve(root, opts.import);
+            const corpus = service.importCorpus(id, JSON.parse(readFileSync(file, "utf8")));
+            const attestedGood = corpus.known_good.filter((fixture) => !!fixture.attestation).length;
+            console.log(`✓ imported ${corpus.id} for ${corpus.policy_id}: ${corpus.known_bad.length} known bad, ${corpus.known_good.length} known good (${attestedGood} human-attested)`);
+            console.log(`  hash: ${corpus.content_hash} · home follows policy data class (${corpus.data_class})`);
+        }
+        else {
+            console.log(JSON.stringify(service.corpus(id, { publicOnly: opts.publicOnly }), null, 2));
+        }
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+policyCmd
+    .command("card")
+    .description("Render the deterministic proof card: exact policy, evidence vector, uncertainty, authority, and next actions.")
+    .argument("<id>", "policy id")
+    .option("--json", "emit the canonical proof-card object")
+    .option("--public-only", "exclude private-overlay policy/proof records")
+    .action((id, opts) => {
+    const { store, root } = storeFor();
+    try {
+        const card = new ConstitutionService(store, root).card(id, { publicOnly: opts.publicOnly });
+        console.log(opts.json ? JSON.stringify(card, null, 2) : renderProofCard(card));
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+policyCmd
+    .command("compile")
+    .description("Compile one structured Decision.conformance predicate into a non-active Policy IR candidate.")
+    .argument("<decision-id>", "source decision id")
+    .option("--through <selector>", "compile a negative boundary as must-pass-through via this symbol selector")
+    .option("--private", "write the policy/proof only to the configured private overlay")
+    .action((decisionId, opts) => {
+    const { store, root } = storeFor();
+    try {
+        const policy = new ConstitutionService(store, root).compile(decisionId, opts);
+        console.log(`✓ compiled ${policy.id} [${policy.state}] — ${policy.statement}`);
+        console.log(`  ${policy.assertion.kind}: ${JSON.stringify(policy.assertion)}`);
+        console.log("  authority: none; this candidate cannot block until proved and explicitly accepted by a human.");
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+policyCmd
+    .command("plan")
+    .description("Generate or inspect the canonical, non-executing ProofPlan for a Policy IR candidate.")
+    .argument("<id>", "policy id")
+    .option("--history <n>", "maximum accepted-history commits", "20")
+    .option("--mutations <n>", "maximum deterministic mutations", "3")
+    .option("--minutes <n>", "total future replay budget in minutes", "5")
+    .option("--public-only", "exclude private-overlay policy/evidence records")
+    .action((id, opts) => {
+    const { store, root } = storeFor();
+    try {
+        const values = [opts.history, opts.mutations, opts.minutes].map(Number);
+        if (values.slice(0, 2).some((n) => !Number.isFinite(n) || n < 0) || !Number.isFinite(values[2]) || values[2] <= 0) {
+            throw new Error("history/mutation budgets must be non-negative and minutes must be positive");
+        }
+        const plan = new ConstitutionService(store, root).plan(id, {
+            maxCommits: values[0],
+            maxMutations: values[1],
+            maxMinutes: values[2],
+            publicOnly: opts.publicOnly,
+        });
+        console.log(JSON.stringify(plan, null, 2));
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+policyCmd
+    .command("prove")
+    .description("Execute the canonical ProofPlan: isolated current/history/control replay plus deterministic mutation; grants no authority.")
+    .argument("<id>", "policy id")
+    .action((id) => {
+    const { store, root } = storeFor();
+    try {
+        indexRepo(store, root, { churn: false });
+        store.reindex();
+        const { policy, proof } = new ConstitutionService(store, root).prove(id);
+        console.log(`POLICY PROOF  ${policy.id}`);
+        console.log(`  state: ${policy.state} · class: ${proof.proof_class} · proof: ${proof.id}`);
+        console.log(`  current: ${proof.current.satisfied} satisfied · ${proof.current.violated} violated · ${proof.current.unknown} unknown · ${proof.current.error} error`);
+        console.log(`  known bad: ${proof.known_bad.violated}/${proof.known_bad.total} caught · known good: ${proof.known_good.satisfied}/${proof.known_good.total} satisfied`);
+        console.log(`  accepted history: ${proof.accepted_history.total} evaluated · ${proof.accepted_history.violated} unclassified hit · ${proof.accepted_history.unknown} unknown · ${proof.accepted_history.error} error`);
+        console.log(`  mutations: ${proof.mutations.violated}/${proof.mutations.total} caught · ${Object.keys(proof.mutations.operator_coverage).join(", ") || "none"}`);
+        for (const limitation of proof.limitations)
+            console.log(`  limitation: ${limitation}`);
+        console.log("  next: hunch policy accept " + policy.id + " --advisory|--blocking --actor human:<identity>");
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+policyCmd
+    .command("history")
+    .description("Inspect or human-classify exact violated accepted-history receipts. Classifications are append-only and grant no activation authority.")
+    .argument("<id>", "policy id")
+    .option("--commit <sha>", "full 40-character accepted-history commit SHA")
+    .option("--classify <kind>", "true_positive_actionable | true_positive_accepted_exception | false_positive_selector | false_positive_semantics | false_positive_stale | unknown_insufficient_parser")
+    .option("--actor <identity>", "explicit human identity: human:, github:, or git:")
+    .option("--reason <reason>", "bounded audited reason for the classification")
+    .option("--supersedes <id>", "current disposition id when appending a corrected classification")
+    .option("--public-only", "exclude private-overlay policy/disposition records when inspecting")
+    .action((id, opts) => {
+    const { store, root } = storeFor();
+    try {
+        const service = new ConstitutionService(store, root);
+        const writing = !!opts.commit || !!opts.classify || !!opts.actor || !!opts.reason || !!opts.supersedes;
+        if (writing) {
+            if (opts.publicOnly)
+                throw new Error("--public-only cannot be combined with history classification");
+            if (!opts.commit || !opts.classify || !opts.actor || !opts.reason) {
+                throw new Error("history classification requires --commit, --classify, --actor, and --reason");
+            }
+            const classification = HistoryDispositionClassificationSchema.parse(opts.classify);
+            const disposition = service.classifyHistory(id, opts.commit, classification, opts.actor, opts.reason, { supersedes: opts.supersedes });
+            console.log(`✓ recorded ${disposition.id}: ${disposition.classification} for ${disposition.commit}`);
+            console.log(`  proof: ${disposition.proof_id} · actor: ${disposition.actor} · home follows policy data class (${disposition.data_class})`);
+            console.log("  classification grants no activation authority; blocking still requires an explicit human policy acceptance.");
+        }
+        else {
+            console.log(JSON.stringify(service.historyDispositions(id, { publicOnly: opts.publicOnly }), null, 2));
+        }
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+policyCmd
+    .command("shadow")
+    .description("Record or inspect non-blocking shadow evaluations, append human dispositions, and derive raw precision/P4-readiness measurements. Never activates policy.")
+    .argument("<id>", "policy id")
+    .option("--record", "record the current deterministic evaluation once for this exact graph receipt")
+    .option("--event <id>", "shadow evaluation id to classify")
+    .option("--classify <kind>", "true_positive_actionable | true_positive_accepted_exception | false_positive_selector | false_positive_semantics | false_positive_stale | unknown_insufficient_parser")
+    .option("--actor <identity>", "explicit human identity: human:, github:, or git:")
+    .option("--reason <reason>", "bounded audited reason for the classification")
+    .option("--supersedes <id>", "current shadow disposition id when appending a correction")
+    .option("--min-applicable <n>", "minimum recent applicable changes for P4 review eligibility", "20")
+    .option("--recent <n>", "maximum recent applicable changes in the precision window", "100")
+    .option("--max-unknown-error-rate <rate>", "exclusive unknown/error-rate ceiling", "0.01")
+    .option("--public-only", "exclude private-overlay shadow records when inspecting")
+    .action((id, opts) => {
+    const { store, root } = storeFor();
+    try {
+        const service = new ConstitutionService(store, root);
+        const classifying = !!opts.event || !!opts.classify || !!opts.actor || !!opts.reason || !!opts.supersedes;
+        if (opts.record && classifying)
+            throw new Error("choose either --record or a shadow classification, not both");
+        if ((opts.record || classifying) && opts.publicOnly)
+            throw new Error("--public-only cannot be combined with shadow writes");
+        if (opts.record) {
+            indexRepo(store, root, { churn: false });
+            store.reindex();
+            const record = service.recordShadow(id);
+            console.log(`✓ recorded ${record.id}: ${record.evaluation.result} on ${record.evaluation.repository.graph_hash}`);
+            console.log("  shadow recording never warns, blocks, changes lifecycle, or grants authority.");
+            return;
+        }
+        if (classifying) {
+            if (!opts.event || !opts.classify || !opts.actor || !opts.reason) {
+                throw new Error("shadow classification requires --event, --classify, --actor, and --reason");
+            }
+            const classification = HistoryDispositionClassificationSchema.parse(opts.classify);
+            const disposition = service.classifyShadow(id, opts.event, classification, opts.actor, opts.reason, { supersedes: opts.supersedes });
+            console.log(`✓ recorded ${disposition.id}: ${disposition.classification} for ${disposition.shadow_id}`);
+            console.log("  disposition changes measurement only; it cannot activate or block.");
+            return;
+        }
+        const minApplicable = Number(opts.minApplicable);
+        const recentApplicable = Number(opts.recent);
+        const maxUnknownErrorRate = Number(opts.maxUnknownErrorRate);
+        console.log(JSON.stringify(service.shadowReport(id, { minApplicable, recentApplicable, maxUnknownErrorRate }, { publicOnly: opts.publicOnly }), null, 2));
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+policyCmd
+    .command("accept")
+    .description("Human-only activation of a proved policy. Blocking requires P3+ proof.")
+    .argument("<id>", "policy id")
+    .option("--advisory", "activate as advisory")
+    .option("--blocking", "activate as blocking")
+    .requiredOption("--actor <identity>", "explicit human identity: human:, github:, or git:")
+    .action((id, opts) => {
+    const { store, root } = storeFor();
+    try {
+        if (!!opts.advisory === !!opts.blocking)
+            throw new Error("choose exactly one of --advisory or --blocking");
+        const mode = opts.blocking ? "blocking" : "advisory";
+        const policy = new ConstitutionService(store, root).approve(id, mode, opts.actor);
+        console.log(`✓ ${policy.id} is ${policy.state} by ${policy.authority?.actor} (revision ${policy.revision})`);
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+policyCmd
+    .command("demote")
+    .description("Immediately demote an active blocking policy to advisory without erasing history.")
+    .argument("<id>", "policy id")
+    .requiredOption("--actor <identity>", "explicit human identity: human:, github:, or git:")
+    .requiredOption("--reason <reason>", "audited demotion reason")
+    .action((id, opts) => {
+    const { store, root } = storeFor();
+    try {
+        const policy = new ConstitutionService(store, root).demote(id, opts.actor, opts.reason);
+        console.log(`✓ ${policy.id} demoted to ${policy.state}; history retained (revision ${policy.revision})`);
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+policyCmd
+    .command("exception")
+    .description("Human-link a strictly narrower opposite policy to its parent; invalidates child proof/authority and never enables blocking.")
+    .argument("<id>", "narrow exception policy id")
+    .requiredOption("--parent <id>", "broader parent policy id")
+    .requiredOption("--actor <identity>", "explicit human identity: human:, github:, or git:")
+    .requiredOption("--reason <reason>", "audited reason this narrow opposite is intentional")
+    .action((id, opts) => {
+    const { store, root } = storeFor();
+    try {
+        const policy = new ConstitutionService(store, root).linkException(id, opts.parent, opts.actor, opts.reason);
+        console.log(`✓ ${policy.id} linked as a non-blocking exception of ${policy.exception_of} (revision ${policy.revision})`);
+        console.log("  proof and authority cleared; composition remains advisory until separately proved.");
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+policyCmd
+    .command("relations")
+    .description("Inspect explicit exception-parent links without evaluating, composing, activating, or enforcing policy.")
+    .argument("<id>", "policy id")
+    .option("--public-only", "exclude private-overlay policy records")
+    .action((id, opts) => {
+    const { store, root } = storeFor();
+    try {
+        const relations = new ConstitutionService(store, root).relations(id, { publicOnly: opts.publicOnly });
+        console.log(JSON.stringify(relations, null, 2));
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+policyCmd
+    .command("consolidation")
+    .description("Inspect a non-mutating advisory consolidation candidate from an existing scope suggestion.")
+    .argument("<id>", "anchor policy id")
+    .option("--public-only", "exclude private-overlay policy records")
+    .action((id, opts) => {
+    const { store, root } = storeFor();
+    try {
+        const candidate = new ConstitutionService(store, root).consolidation(id, { publicOnly: opts.publicOnly });
+        console.log(JSON.stringify(candidate, null, 2));
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+policyCmd
+    .command("evaluate")
+    .description("Evaluate one or all policies with the neutral deterministic result algebra.")
+    .argument("[id]", "optional policy id")
+    .option("--active", "evaluate active policies only")
+    .option("--public-only", "exclude private-overlay policies and graph records")
+    .option("--staged", "evaluate executable-behavior policies against the staged index snapshot")
+    .option("--working", "evaluate executable-behavior policies against all staged, unstaged, and untracked changes")
+    .option("--commit <sha>", "evaluate executable-behavior policies at an exact commit")
+    .option("--strict", "exit non-zero on an authorized blocking violation or evaluator error")
+    .option("--json", "emit canonical receipt objects as JSON")
+    .action((id, opts) => {
+    const { store, root } = storeFor();
+    try {
+        const sources = [opts.staged && "--staged", opts.working && "--working", opts.commit && "--commit"].filter(Boolean);
+        if (sources.length > 1)
+            throw new Error(`pick one executable-behavior snapshot source (got ${sources.join(", ")})`);
+        if (opts.commit && !revExists(opts.commit, root))
+            throw new Error(`--commit ref "${opts.commit}" does not resolve`);
+        const behavior = opts.staged ? { workspace: "staged" }
+            : opts.working ? { workspace: "working" }
+                : opts.commit ? { commit: revParse(opts.commit, root) }
+                    : undefined;
+        indexRepo(store, root, { churn: false });
+        store.reindex();
+        const results = new ConstitutionService(store, root).evaluate({ id, activeOnly: opts.active, publicOnly: opts.publicOnly, behavior });
+        if (opts.json)
+            console.log(JSON.stringify(results.map((r) => r.evaluation), null, 2));
+        else
+            renderPolicyEvaluations(results).forEach((line) => console.log(line));
+        if (opts.strict && results.some((r) => r.blocks || r.strict_error))
+            process.exitCode = 1;
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+function renderPolicyEvaluations(results) {
+    if (!results.length)
+        return ["No Constitution policies matched."];
+    const icon = { satisfied: "✅", violated: "⛔", not_applicable: "·", unknown: "?", error: "‼" };
+    const out = [`Constitution policy evaluation: ${results.length} canonical receipt(s)`];
+    for (const r of results) {
+        out.push(`  ${icon[r.evaluation.result] ?? "·"} ${r.policy.id} [${r.policy.state}] ${r.evaluation.result}${r.blocks ? " — BLOCK" : ""}`);
+        out.push(`     ${r.evaluation.explanation}`);
+        if (r.gate_error)
+            out.push(`     gate error: ${r.gate_error}`);
+        out.push(`     receipt: ${r.evaluation.deterministic_hash}`);
+    }
+    return out;
+}
+// ---- constitution (deterministic evidence -> candidate bootstrap) --------
+const constitutionCmd = program
+    .command("constitution")
+    .description("Bootstrap Hunch Constitution candidates from attributable structured evidence.");
+constitutionCmd
+    .command("scorecard")
+    .description("Validate and score a versioned EXP-03 Intent Compiler case bank; writes nothing.")
+    .argument("[file]", "path to a version-1 EXP-03 JSON case bank", join(dirname(fileURLToPath(import.meta.url)), "../../bench/constitution-exp03-v1.json"))
+    .option("--json", "emit the canonical scorecard as JSON")
+    .action((file, opts) => {
+    try {
+        const scorecard = scoreCompilerCaseBank(JSON.parse(readFileSync(resolve(file), "utf8")));
+        console.log(opts.json ? JSON.stringify(scorecard, null, 2) : renderCompilerScorecard(scorecard));
+        if (!scorecard.passed)
+            process.exitCode = 1;
+    }
+    catch (e) {
+        fail(e.message);
+    }
+});
+constitutionCmd
+    .command("ingest")
+    .description("Normalize local corrections/failures, committed instructions/ADRs, and local review/PR exports into Git-native EvidenceEvents; creates no policy authority.")
+    .option("--since <duration>", "evidence window, e.g. 90d or 12w", "90d")
+    .option("--max-events <n>", "maximum events normalized in one run (hard-capped at 200)", "100")
+    .option("--instructions", "hash-normalize bounded committed instruction and ADR markdown")
+    .option("--from <files...>", "strict local review/conversation/PR export JSON file(s)")
+    .option("--public-only", "read/write only public records")
+    .option("--private", "read/write only the configured private overlay")
+    .action((opts) => {
+    const { store, root } = storeFor();
+    try {
+        const maxEvents = Number(opts.maxEvents);
+        if (!Number.isFinite(maxEvents) || maxEvents <= 0)
+            throw new Error("--max-events must be a positive number");
+        const report = new ConstitutionService(store, root).ingest({
+            since: opts.since,
+            maxEvents,
+            instructions: opts.instructions,
+            importFiles: opts.from,
+            publicOnly: opts.publicOnly,
+            privateOnly: opts.private,
+        });
+        console.log(`Constitution evidence ingest: scanned ${report.scanned} record(s), ${report.eligible} eligible`);
+        console.log(`  ${report.normalized} normalized · ${report.existing} existing · ${report.covered} covered · ${report.uncompilable} uncompilable · ${report.excluded} excluded`);
+        for (const event of report.events) {
+            console.log(`  ${event.id} [${event.kind}/${event.compiler?.status ?? "normalized"}] ${event.text_ref ?? ""}`);
+        }
+        console.log("  authority: none; ingestion never proves, proposes, activates, or blocks.");
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+constitutionCmd
+    .command("delta")
+    .description("Inspect the exact first-parent structural delta and supported candidates for one human-confirmed fix/revert decision; writes nothing.")
+    .argument("<decision-id>", "git-anchored decision id")
+    .option("--public-only", "read only the public decision and graph")
+    .option("--private", "read only the configured private overlay decision and union graph")
+    .action((decisionId, opts) => {
+    const { store, root } = storeFor();
+    try {
+        const inspection = new ConstitutionService(store, root).inspectStructural(decisionId, {
+            publicOnly: opts.publicOnly,
+            privateOnly: opts.private,
+        });
+        console.log(JSON.stringify(inspection, null, 2));
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+constitutionCmd
+    .command("bootstrap")
+    .description("Normalize eligible decisions into evidence events and compile at most three non-active Policy IR candidates.")
+    .option("--since <duration>", "evidence window, e.g. 90d or 12w", "90d")
+    .option("--max-candidates <n>", "maximum surfaced candidates (hard-capped at 3)", "3")
+    .option("--public-only", "read/write only public evidence and policies")
+    .option("--private", "read/write only the configured private overlay")
+    .option("--history", "use exact first-parent deltas from human-confirmed fix/revert decisions; ambiguous deltas remain uncompilable")
+    .action((opts) => {
+    const { store, root } = storeFor();
+    try {
+        const requested = Number(opts.maxCandidates);
+        if (!Number.isFinite(requested) || requested <= 0)
+            throw new Error("--max-candidates must be a positive number");
+        if (opts.history) {
+            indexRepo(store, root, { churn: false });
+            store.reindex();
+        }
+        const report = new ConstitutionService(store, root).bootstrap({
+            since: opts.since,
+            maxCandidates: requested,
+            publicOnly: opts.publicOnly,
+            privateOnly: opts.private,
+            history: opts.history,
+        });
+        console.log(`Constitution ${opts.history ? "history " : ""}bootstrap: scanned ${report.scanned} decision(s), ${report.eligible} eligible`);
+        for (const candidate of report.compiled) {
+            console.log(`  + ${candidate.policy.id} [${candidate.policy.state}] ${candidate.policy.statement}`);
+            console.log(`    evidence: ${candidate.evidence.id} · ${candidate.policy.assertion.kind} · authority: none`);
+        }
+        console.log(`  ${report.compiled.length} compiled · ${report.covered} already covered · ${report.conflicted} conflicted · ${report.deferred} deferred by max-three cap · ${report.uncompilable} uncompilable`);
+        if (!report.compiled.length)
+            console.log("  No new candidates; existing policy lifecycle states were left untouched.");
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+constitutionCmd
+    .command("g2")
+    .description("Inspect exact private G2 evidence; optionally append a human plan, runbook rehearsal, or candidate review. Never grants policy authority.")
+    .option("--plan <file>", "append a private human-selected G2 plan from JSON")
+    .option("--rehearse <runbook-id>", "append a rehearsal receipt for the exact current private runbook content")
+    .option("--attest <candidate-id>", "append an exact private human selection or rejection for one reviewed candidate")
+    .option("--observe", "record at most one private shadow observation per selected policy for the current real HEAD/graph")
+    .option("--backfill <n>", "atomically record shadow observations across up to n real first-parent commits after an all-policy preflight")
+    .option("--drill <category>", "execute one exact selected operational runbook drill, or all seven with category=all; writes no evidence")
+    .option("--queue <limit>", "return the bounded current-proof queue of unclassified G2 shadow violations")
+    .option("--candidates <limit>", "return a bounded read-only review packet of exact fix-history candidates requiring human attestation")
+    .option("--behavior-candidates <limit>", "derive bounded behavior-level candidates from rejected grounded proxies plus newly added regression tests")
+    .option("--behavior-decision <decision-id>", "scope behavior review/replay/materialization to one exact current human-confirmed decision")
+    .option("--behavior-replay <candidate-id>", "run one exact behavior candidate in disposable known-bad/good worktrees")
+    .option("--behavior-deps <candidate-id>", "explicitly build or validate content-addressed historical dependency snapshots for one behavior candidate")
+    .option("--behavior-attest <candidate-id>", "append an exact private human selection or rejection bound to a snapshot-backed behavior replay")
+    .option("--behavior-materialize", "assess current selected behavior attestations against the exact supported Policy IR without creating artifacts")
+    .option("--behavior-policy-materialize", "materialize and P3-prove every current selected behavior as a private non-authoritative policy proposal")
+    .option("--behavior-review-hash <hash>", "exact behavior-candidate review content hash being replayed or provisioned")
+    .option("--allow-install-script <packages...>", "dependency packages explicitly allowed to run lifecycle scripts while building --behavior-deps")
+    .option("--dependency-timeout-ms <n>", "timeout for each npm dependency snapshot operation", "300000")
+    .option("--candidate-since <window>", "git history window for candidate review or attestation", "180d")
+    .option("--candidate-commits <n>", "maximum fix-labeled commits inspected for candidate review or attestation", "100")
+    .option("--candidate-limit <n>", "exact review-packet limit used by --attest or --behavior-replay", "30")
+    .option("--review-hash <hash>", "exact candidate review content hash being attested")
+    .option("--disposition <value>", "candidate disposition: selected | rejected")
+    .option("--result <result>", "rehearsal result: passed | failed")
+    .option("--actor <actor>", "explicit human actor (human:, github:, or git:)")
+    .option("--evidence <hashes...>", "one or more sha1 evidence hashes for a rehearsal")
+    .option("--notes <text>", "rehearsal evidence notes")
+    .option("--reason <text>", "candidate selection or rejection rationale")
+    .option("--supersedes <id>", "current rehearsal or candidate attestation corrected by this append-only receipt")
+    .option("--strict", "exit nonzero while the packet is not eligible for explicit human G2 signoff")
+    .action((opts) => {
+    const { store, root } = storeFor();
+    try {
+        const queueRequested = opts.queue !== undefined;
+        const candidatesRequested = opts.candidates !== undefined;
+        const behaviorCandidatesRequested = opts.behaviorCandidates !== undefined;
+        const behaviorReplayRequested = opts.behaviorReplay !== undefined;
+        const behaviorDepsRequested = opts.behaviorDeps !== undefined;
+        const behaviorAttestRequested = opts.behaviorAttest !== undefined;
+        const behaviorMaterializeRequested = opts.behaviorMaterialize === true;
+        const behaviorPolicyMaterializeRequested = opts.behaviorPolicyMaterialize === true;
+        const backfillRequested = opts.backfill !== undefined;
+        const drillRequested = opts.drill !== undefined;
+        const behaviorActionRequested = behaviorCandidatesRequested || behaviorReplayRequested || behaviorDepsRequested
+            || behaviorAttestRequested || behaviorMaterializeRequested || behaviorPolicyMaterializeRequested;
+        const attestRequested = opts.attest !== undefined;
+        const actions = [!!opts.plan, !!opts.rehearse, attestRequested, !!opts.observe, backfillRequested, drillRequested, queueRequested, candidatesRequested, behaviorCandidatesRequested, behaviorReplayRequested, behaviorDepsRequested, behaviorAttestRequested, behaviorMaterializeRequested, behaviorPolicyMaterializeRequested].filter(Boolean).length;
+        if (actions > 1)
+            throw new Error("choose only one G2 plan, rehearsal, structural attestation, observation, historical backfill, operational drill, queue, structural candidate, behavior candidate, behavior replay, dependency snapshot, behavior attestation, behavior assessment, or behavior policy materialization action");
+        if (opts.allowInstallScript && !behaviorDepsRequested && !behaviorPolicyMaterializeRequested)
+            throw new Error("--allow-install-script requires --behavior-deps or --behavior-policy-materialize");
+        if (opts.behaviorDecision && !behaviorActionRequested)
+            throw new Error("--behavior-decision requires a behavior candidate, replay, dependency, attestation, assessment, or materialization action");
+        const service = new ConstitutionService(store, root);
+        let output;
+        if (opts.plan) {
+            const appended = service.createG2Plan(JSON.parse(readFileSync(resolve(opts.plan), "utf8")));
+            output = { appended, readiness: service.g2Readiness() };
+        }
+        else if (attestRequested) {
+            if (opts.result || opts.evidence || opts.notes)
+                throw new Error("--attest does not accept rehearsal --result, --evidence, or --notes");
+            if (!opts.reviewHash)
+                throw new Error("--attest requires --review-hash");
+            if (opts.disposition !== "selected" && opts.disposition !== "rejected")
+                throw new Error("--attest requires --disposition selected|rejected");
+            if (!opts.actor)
+                throw new Error("--attest requires --actor");
+            if (!opts.reason)
+                throw new Error("--attest requires --reason");
+            const reviewOptions = {
+                since: opts.candidateSince,
+                maxCommits: Number(opts.candidateCommits),
+                limit: Number(opts.candidateLimit),
+            };
+            const appended = service.attestG2Candidate(opts.attest, opts.reviewHash, opts.disposition, opts.actor, opts.reason, {
+                ...reviewOptions,
+                supersedes: opts.supersedes,
+            });
+            output = { appended, review: service.g2CandidateReview(reviewOptions) };
+        }
+        else if (opts.rehearse) {
+            if (opts.reviewHash || opts.disposition || opts.reason)
+                throw new Error("--rehearse does not accept candidate --review-hash, --disposition, or --reason");
+            if (opts.result !== "passed" && opts.result !== "failed")
+                throw new Error("--rehearse requires --result passed|failed");
+            if (!opts.actor)
+                throw new Error("--rehearse requires --actor");
+            if (!opts.evidence?.length)
+                throw new Error("--rehearse requires at least one --evidence sha1 hash");
+            if (!opts.notes)
+                throw new Error("--rehearse requires --notes");
+            const appended = service.recordRunbookRehearsal(opts.rehearse, opts.result, opts.actor, opts.evidence, opts.notes, { supersedes: opts.supersedes });
+            output = { appended, readiness: service.g2Readiness() };
+        }
+        else if (opts.observe) {
+            indexRepo(store, root, { churn: false });
+            store.reindex();
+            output = { sweep: service.g2ShadowSweep(), readiness: service.g2Readiness() };
+        }
+        else if (backfillRequested) {
+            output = { backfill: service.g2ShadowBackfill(Number(opts.backfill)), readiness: service.g2Readiness() };
+        }
+        else if (drillRequested) {
+            const categories = opts.drill === "all" ? [...G2_RUNBOOK_CATEGORIES] : G2_RUNBOOK_CATEGORIES.filter((category) => category === opts.drill);
+            if (!categories.length)
+                throw new Error(`--drill must be all or one of: ${G2_RUNBOOK_CATEGORIES.join(", ")}`);
+            output = { drills: categories.map((category) => service.g2OperationalDrill(category)), readiness: service.g2Readiness() };
+        }
+        else if (queueRequested) {
+            output = service.g2ShadowQueue(Number(opts.queue));
+        }
+        else if (candidatesRequested) {
+            output = service.g2CandidateReview({ since: opts.candidateSince, maxCommits: Number(opts.candidateCommits), limit: Number(opts.candidates) });
+        }
+        else if (behaviorCandidatesRequested) {
+            if (opts.behaviorReviewHash)
+                throw new Error("--behavior-candidates does not accept --behavior-review-hash");
+            output = service.g2BehaviorCandidateReview({ since: opts.candidateSince, maxCommits: Number(opts.candidateCommits), limit: Number(opts.behaviorCandidates), decisionId: opts.behaviorDecision });
+        }
+        else if (behaviorReplayRequested) {
+            if (!opts.behaviorReviewHash)
+                throw new Error("--behavior-replay requires --behavior-review-hash");
+            if (opts.result || opts.actor || opts.evidence || opts.notes || opts.reason || opts.reviewHash || opts.disposition || opts.supersedes || opts.allowInstallScript) {
+                throw new Error("--behavior-replay accepts no human evidence or structural-attestation options");
+            }
+            output = service.g2BehaviorCandidateReplay(opts.behaviorReplay, opts.behaviorReviewHash, {
+                since: opts.candidateSince,
+                maxCommits: Number(opts.candidateCommits),
+                limit: Number(opts.candidateLimit),
+                decisionId: opts.behaviorDecision,
+            });
+        }
+        else if (behaviorDepsRequested) {
+            if (!opts.behaviorReviewHash)
+                throw new Error("--behavior-deps requires --behavior-review-hash");
+            if (opts.result || opts.actor || opts.evidence || opts.notes || opts.reason || opts.reviewHash || opts.disposition || opts.supersedes) {
+                throw new Error("--behavior-deps accepts no human evidence or structural-attestation options");
+            }
+            output = service.g2BehaviorDependencySnapshots(opts.behaviorDeps, opts.behaviorReviewHash, {
+                since: opts.candidateSince,
+                maxCommits: Number(opts.candidateCommits),
+                limit: Number(opts.candidateLimit),
+                decisionId: opts.behaviorDecision,
+                allowInstallScripts: opts.allowInstallScript ?? [],
+                timeoutMs: Number(opts.dependencyTimeoutMs),
+            });
+        }
+        else if (behaviorAttestRequested) {
+            if (!opts.behaviorReviewHash)
+                throw new Error("--behavior-attest requires --behavior-review-hash");
+            if (opts.disposition !== "selected" && opts.disposition !== "rejected")
+                throw new Error("--behavior-attest requires --disposition selected|rejected");
+            if (!opts.actor)
+                throw new Error("--behavior-attest requires --actor");
+            if (!opts.reason)
+                throw new Error("--behavior-attest requires --reason");
+            if (opts.result || opts.evidence || opts.notes || opts.reviewHash || opts.allowInstallScript) {
+                throw new Error("--behavior-attest accepts no rehearsal, structural-review, or dependency-install options");
+            }
+            const reviewOptions = {
+                since: opts.candidateSince,
+                maxCommits: Number(opts.candidateCommits),
+                limit: Number(opts.candidateLimit),
+                decisionId: opts.behaviorDecision,
+            };
+            const appended = service.attestG2BehaviorCandidate(opts.behaviorAttest, opts.behaviorReviewHash, opts.disposition, opts.actor, opts.reason, { ...reviewOptions, supersedes: opts.supersedes });
+            output = { appended, review: service.g2BehaviorCandidateReview(reviewOptions) };
+        }
+        else if (behaviorMaterializeRequested) {
+            if (opts.result || opts.actor || opts.evidence || opts.notes || opts.reason || opts.reviewHash || opts.disposition || opts.supersedes || opts.behaviorReviewHash || opts.allowInstallScript) {
+                throw new Error("--behavior-materialize accepts no human evidence, review-hash, or dependency-install options");
+            }
+            output = service.g2BehaviorMaterializationAssessment({
+                since: opts.candidateSince,
+                maxCommits: Number(opts.candidateCommits),
+                limit: Number(opts.candidateLimit),
+                decisionId: opts.behaviorDecision,
+            });
+        }
+        else if (behaviorPolicyMaterializeRequested) {
+            if (opts.result || opts.actor || opts.evidence || opts.notes || opts.reason || opts.reviewHash || opts.disposition || opts.supersedes || opts.behaviorReviewHash) {
+                throw new Error("--behavior-policy-materialize accepts no human evidence or review-hash options");
+            }
+            output = service.g2BehaviorPolicyMaterialize({
+                since: opts.candidateSince,
+                maxCommits: Number(opts.candidateCommits),
+                limit: Number(opts.candidateLimit),
+                decisionId: opts.behaviorDecision,
+                allowInstallScripts: opts.allowInstallScript ?? [],
+                dependencyTimeoutMs: Number(opts.dependencyTimeoutMs),
+            });
+        }
+        else if (opts.result || opts.actor || opts.evidence || opts.notes || opts.reason || opts.reviewHash || opts.disposition || opts.supersedes || opts.behaviorReviewHash || opts.allowInstallScript) {
+            throw new Error("human evidence options require --rehearse <runbook-id> or --attest <candidate-id>");
+        }
+        else {
+            output = service.g2Readiness();
+        }
+        const readiness = service.g2Readiness();
+        console.log(JSON.stringify(output, null, 2));
+        if (opts.strict && readiness.recommendation !== "eligible_for_human_g2_signoff")
+            process.exitCode = 1;
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+constitutionCmd
+    .command("g3")
+    .description("Inspect exact private G3 advisory evidence; optionally append a preregistration, human plan, proof review, or executable adapter receipt. Never signs off G3.")
+    .option("--experiment <file>", "append an immutable private EXP-01 or EXP-03 preregistration from JSON")
+    .option("--plan <file>", "append a private human-selected G3 plan bound to exact G2 readiness and experiment records")
+    .option("--review <file>", "append a measured human proof-card review for one plan-selected policy")
+    .option("--conformance", "execute and append the exact current plan's supported three-client adapter fixture")
+    .option("--timeout-ms <n>", "timeout for the executable adapter conformance fixture", "180000")
+    .option("--strict", "exit nonzero while the packet is not eligible for explicit human G3 signoff")
+    .action((opts) => {
+    const { store, root } = storeFor();
+    try {
+        const actions = [!!opts.experiment, !!opts.plan, !!opts.review, !!opts.conformance].filter(Boolean).length;
+        if (actions > 1)
+            throw new Error("choose only one G3 preregistration, plan, proof review, or adapter-conformance action");
+        const service = new ConstitutionService(store, root);
+        let output;
+        if (opts.experiment) {
+            const appended = service.registerG3Experiment(JSON.parse(readFileSync(resolve(opts.experiment), "utf8")));
+            output = { appended, readiness: service.g3Readiness() };
+        }
+        else if (opts.plan) {
+            const appended = service.createG3Plan(JSON.parse(readFileSync(resolve(opts.plan), "utf8")));
+            output = { appended, readiness: service.g3Readiness() };
+        }
+        else if (opts.review) {
+            const input = JSON.parse(readFileSync(resolve(opts.review), "utf8"));
+            const appended = service.recordG3ProofReview(input);
+            output = { appended, readiness: service.g3Readiness() };
+        }
+        else if (opts.conformance) {
+            const appended = service.g3AdapterConformance({ timeoutMs: Number(opts.timeoutMs) });
+            output = { appended, readiness: service.g3Readiness() };
+        }
+        else {
+            output = service.g3Readiness();
+        }
+        const readiness = service.g3Readiness();
+        console.log(JSON.stringify(output, null, 2));
+        if (opts.strict && readiness.recommendation !== "eligible_for_human_g3_signoff")
+            process.exitCode = 1;
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+// ---- experiment (fresh preregistration-bound execution) -----------------
+const experimentCmd = program
+    .command("experiment")
+    .description("Lock, execute, review, and report fresh private preregistered experiments. No result grants policy authority.");
+experimentCmd
+    .command("validate")
+    .description("Validate and content-address a draft case bank against the current preregistration without writing it.")
+    .argument("<file>", "case bank JSON input")
+    .action((file) => {
+    const { store, root } = storeFor();
+    try {
+        const input = JSON.parse(readFileSync(resolve(file), "utf8"));
+        console.log(JSON.stringify(new ConstitutionService(store, root).validateExperimentCaseBank(input), null, 2));
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+experimentCmd
+    .command("prepare")
+    .description("Lock a fresh private case bank to the exact current preregistration before assignment.")
+    .argument("<file>", "case bank JSON input")
+    .action((file) => {
+    const { store, root } = storeFor();
+    try {
+        const input = JSON.parse(readFileSync(resolve(file), "utf8"));
+        console.log(JSON.stringify(new ConstitutionService(store, root).lockExperimentCaseBank(input), null, 2));
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+experimentCmd
+    .command("create")
+    .description("Create one immutable balanced assignment manifest; one run is allowed per preregistration.")
+    .argument("<case-bank-id>", "locked private case bank id")
+    .requiredOption("--sample-per-arm <n>", "full preregistered target per arm; the minimum is only a checkpoint")
+    .requiredOption("--actor <actor>", "explicit owner (human:, git:, or github:)")
+    .requiredOption("--reason <text>", "why this exact run manifest is being created")
+    .option("--provider <provider>", "EXP-01 subscription CLI: claude-cli | codex-cli")
+    .option("--model <model>", "exact EXP-01 model version or alias")
+    .option("--max-turns <n>", "maximum agent turns for every EXP-01 assignment", "40")
+    .action((caseBankId, opts) => {
+    const { store, root } = storeFor();
+    try {
+        const service = new ConstitutionService(store, root);
+        const bank = service.experimentRepository.listCaseBanks().find((item) => item.id === caseBankId);
+        if (!bank)
+            throw new Error(`unknown private experiment case bank: ${caseBankId}`);
+        if (bank.experiment === "EXP-01" && opts.provider !== "claude-cli" && opts.provider !== "codex-cli") {
+            throw new Error("EXP-01 run creation requires explicit --provider claude-cli|codex-cli; Hunch never chooses which subscription to spend");
+        }
+        if (bank.experiment === "EXP-01" && !opts.model)
+            throw new Error("EXP-01 run creation requires an exact --model stratum");
+        if (bank.experiment === "EXP-03" && (opts.provider || opts.model))
+            throw new Error("EXP-03 is a human-review experiment and accepts no model provider");
+        const provider = opts.provider;
+        const appended = service.createExperimentRun(caseBankId, {
+            sample_per_arm: Number(opts.samplePerArm),
+            ...(provider ? { provider, provider_version: subscriptionCliVersion(provider), model_version: opts.model, max_turns: Number(opts.maxTurns) } : {}),
+            actor: opts.actor,
+            reason: opts.reason,
+        });
+        console.log(JSON.stringify({ appended, report: service.experimentReport(appended.id) }, null, 2));
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+experimentCmd
+    .command("run")
+    .description("Execute the next pending EXP-01 assignments with the manifest-selected subscription CLI.")
+    .argument("<run-id>", "immutable experiment run id")
+    .option("--limit <n>", "maximum assignments to execute in this invocation", "1")
+    .option("--timeout-ms <n>", "per-assignment subscription CLI timeout", "1800000")
+    .action((runId, opts) => {
+    const { store, root } = storeFor();
+    try {
+        console.log(JSON.stringify(new ConstitutionService(store, root).executeExperimentRun(runId, {
+            limit: Number(opts.limit),
+            timeoutMs: Number(opts.timeoutMs),
+        }), null, 2));
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+experimentCmd
+    .command("next")
+    .description("Start or resume the next randomized EXP-03 human review and return only its assigned treatment.")
+    .argument("<run-id>", "immutable experiment run id")
+    .requiredOption("--reviewer <actor>", "explicit human reviewer")
+    .action((runId, opts) => {
+    const { store, root } = storeFor();
+    try {
+        console.log(JSON.stringify(new ConstitutionService(store, root).nextExperimentReview(runId, opts.reviewer), null, 2));
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+experimentCmd
+    .command("submit")
+    .description("Complete a machine-timed EXP-03 review; duration is derived from the append-only start record.")
+    .argument("<run-id>", "immutable experiment run id")
+    .argument("<assignment-id>", "assignment returned by experiment next")
+    .argument("<file>", "review outcome JSON without a duration field")
+    .action((runId, assignmentId, file) => {
+    const { store, root } = storeFor();
+    try {
+        const input = JSON.parse(readFileSync(resolve(file), "utf8"));
+        const service = new ConstitutionService(store, root);
+        const appended = service.submitExperimentReview(runId, assignmentId, input);
+        console.log(JSON.stringify({ appended, report: service.experimentReport(runId) }, null, 2));
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+experimentCmd
+    .command("followup")
+    .description("Append the preregistered seven-day EXP-03 reversal measurement.")
+    .argument("<run-id>", "immutable experiment run id")
+    .argument("<assignment-id>", "completed review assignment")
+    .argument("<file>", "follow-up JSON")
+    .action((runId, assignmentId, file) => {
+    const { store, root } = storeFor();
+    try {
+        const input = JSON.parse(readFileSync(resolve(file), "utf8"));
+        const service = new ConstitutionService(store, root);
+        const appended = service.recordExperimentFollowup(runId, assignmentId, input);
+        console.log(JSON.stringify({ appended, report: service.experimentReport(runId) }, null, 2));
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+experimentCmd
+    .command("stop")
+    .description("Irreversibly stop a run for a preregistered safety/privacy or provider-wide inability condition.")
+    .argument("<run-id>", "immutable experiment run id")
+    .argument("<file>", "stop receipt JSON with category, actor, reason, and evidence_hashes")
+    .action((runId, file) => {
+    const { store, root } = storeFor();
+    try {
+        const input = JSON.parse(readFileSync(resolve(file), "utf8"));
+        const service = new ConstitutionService(store, root);
+        const appended = service.stopExperiment(runId, input);
+        console.log(JSON.stringify({ appended, report: service.experimentReport(runId) }, null, 2));
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
+for (const command of ["status", "report"]) {
+    experimentCmd
+        .command(command)
+        .description(command === "status" ? "Show raw denominators and remaining assignments." : "Emit the deterministic preregistration-bound analysis receipt.")
+        .argument("<run-id>", "immutable experiment run id")
+        .action((runId) => {
+        const { store, root } = storeFor();
+        try {
+            console.log(JSON.stringify(new ConstitutionService(store, root).experimentReport(runId), null, 2));
+        }
+        catch (e) {
+            fail(e.message);
+        }
+        finally {
+            store.close();
+        }
+    });
+}
 // ---- compare (rank N candidate solutions by architectural fit) ------------
 program
     .command("compare")
@@ -1300,6 +2351,10 @@ program
         store.close();
         return fail(`--base ref "${opts.base}" does not resolve. In CI, fetch the base branch first (git fetch origin <branch>).`);
     }
+    if (opts.commit && !revExists(opts.commit, root)) {
+        store.close();
+        return fail(`--commit ref "${opts.commit}" does not resolve.`);
+    }
     store.reindex(); // blast radius walks the edge graph — make the index current
     const files = opts.commit ? commitFiles(opts.commit, root)
         : opts.base ? rangeFiles(opts.base, root)
@@ -1338,7 +2393,9 @@ program
     // gate cases (--staged / --base / --commit HEAD) all have the working tree AT the change.
     // Surfaced always; gates the commit/PR under --strict, with the receipt of the why.
     const hasConformance = store.recs("decisions").some((d) => (d.conformance?.length ?? 0) > 0);
-    if (hasConformance) {
+    const constitution = new ConstitutionService(store, root);
+    const hasActivePolicies = constitution.list({ publicOnly: !!opts.publicOnly }).some((p) => p.state === "active_advisory" || p.state === "active_blocking");
+    if (hasConformance || hasActivePolicies) {
         indexRepo(store, root, { churn: false }); // refresh the symbol/dep graph from the working tree
         store.reindex();
     }
@@ -1366,7 +2423,34 @@ program
             console.log(`   The semantic invariant a linter can't see — run \`hunch conform\` for the full picture.`);
         }
     }
-    if (reportFailsStrict(report) || (!!opts.strict && confViolations.length > 0))
+    // CONSTITUTION POLICY: the same neutral receipt used by `hunch policy evaluate`
+    // and hunch_policy_evaluate. Only an active_blocking policy with explicit human
+    // authority can block. An evaluator error also fails strict CI; unknown remains
+    // visible/advisory and can never masquerade as satisfied.
+    const behavior = opts.working ? { workspace: "working" }
+        : opts.commit ? { commit: revParse(opts.commit, root) }
+            : opts.base ? undefined
+                : { workspace: "staged" };
+    const policyResults = hasActivePolicies
+        ? constitution.evaluate({ activeOnly: true, publicOnly: !!opts.publicOnly, behavior })
+        : [];
+    if (policyResults.length) {
+        if (markdown) {
+            console.log(`\n### 📜 Hunch Constitution — ${policyResults.length} policy receipt(s)\n`);
+            for (const r of policyResults) {
+                console.log(`- ${r.blocks ? "⛔" : r.evaluation.result === "satisfied" ? "✅" : r.evaluation.result === "error" ? "‼" : "⚠"} \`${r.policy.id}\` **${r.evaluation.result}** — ${r.evaluation.explanation}`);
+                console.log(`  - receipt: \`${r.evaluation.deterministic_hash}\`${r.blocks ? " **(authorized block)**" : ""}`);
+                if (r.gate_error)
+                    console.log(`  - ‼ gate error: ${r.gate_error}`);
+            }
+        }
+        else {
+            console.log("");
+            renderPolicyEvaluations(policyResults).forEach((line) => console.log(line));
+        }
+    }
+    const constitutionFails = policyResults.some((r) => r.blocks || r.strict_error);
+    if (reportFailsStrict(report) || (!!opts.strict && (confViolations.length > 0 || constitutionFails)))
         process.exitCode = 1;
     store.close();
 });
@@ -1638,6 +2722,54 @@ program
     store.close();
 });
 // ---- hook (multi-agent lifecycle hook handler) ----------------------------
+function parseStatsSince(value) {
+    const match = /^(\d+)\s*([mhdw])$/.exec(value.trim());
+    if (!match)
+        return { ms: 7 * 864e5, label: "7d" };
+    const units = { m: 6e4, h: 36e5, d: 864e5, w: 7 * 864e5 };
+    const unit = match[2];
+    return { ms: Number(match[1]) * units[unit], label: `${match[1]}${unit}` };
+}
+program
+    .command("stats")
+    .description("Compounding-value receipt: accumulated memory, caught violations, and payback")
+    .option("--json", "emit the hunch.stats/1 machine contract")
+    .option("--since <duration>", "recent return window (7d, 24h, 2w)", "7d")
+    .option("--private", "include the local private/shared overlay")
+    .action((opts) => {
+    const { store, root } = storeFor();
+    try {
+        if (opts.private && !store.hasPrivate)
+            return fail("--private needs a configured private/shared overlay");
+        const load = (kind) => opts.private ? store.recs(kind) : store.json.loadAll(kind);
+        const events = readEvents(hunchPaths(root));
+        if (opts.private && store.privateDir)
+            events.push(...readEvents(hunchPathsForDir(store.privateDir)));
+        const since = parseStatsSince(opts.since);
+        const now = Date.now();
+        const constraints = load("constraints");
+        const staleConstraints = constraints.filter((constraint) => {
+            const verified = constraint.provenance.last_verified;
+            if (!verified || Number.isNaN(Date.parse(verified)))
+                return false;
+            return constraint.scope.some((file) => {
+                const changed = lastChangeDate(file, root);
+                return !!changed && Date.parse(changed) > Date.parse(verified);
+            });
+        }).length;
+        const stats = computeStats({
+            decisions: load("decisions"), constraints, bugs: load("bugs"),
+            componentIds: load("components").map((component) => component.id),
+            runbooksCount: load("runbooks").length, events,
+            staleConstraints,
+            now, windowStart: now - since.ms, windowLabel: since.label,
+        });
+        console.log(opts.json ? JSON.stringify(stats, null, 2) : formatStats(stats));
+    }
+    finally {
+        store.close();
+    }
+});
 program
     .command("hook")
     .description("Agent-agnostic hook handler: normalizes Claude, VS Code, Cursor, Windsurf, and Antigravity events into Hunch context and strict policy checks. Reads hook JSON on stdin.")
@@ -1778,6 +2910,7 @@ program
             const proposedLines = proposedEditLines(evt.tool_input);
             const deny = blockingInScope(store, target, proposedLines);
             if (deny) {
+                appendEvent(paths, { at: new Date().toISOString(), file: target, ...deny.event });
                 emitDeny(provider, deny.reason);
                 return;
             }
@@ -1786,6 +2919,7 @@ program
             // only human-confirmed tripwires deny.
             const vetoDeny = proposedLines.length ? vetoInScope(store, target, proposedLines) : null;
             if (vetoDeny) {
+                appendEvent(paths, { at: new Date().toISOString(), file: target, ...vetoDeny.event });
                 emitDeny(provider, vetoDeny.reason);
                 return;
             }
@@ -1907,9 +3041,18 @@ program
         console.log(`✓ accepted ${opts.accept} (now ${source}, confidence 0.95${armed ? `, ${armed} tripwire(s) now blocking` : ""})`);
     }
     else if (opts.reject) {
-        const ok2 = opts.private ? store.deleteWhereItLives("decisions", opts.reject) : store.json.delete("decisions", opts.reject);
+        const d = opts.private ? store.getRec("decisions", opts.reject) : store.json.get("decisions", opts.reject);
+        if (!d) {
+            store.close();
+            return fail(`decision ${opts.reject} not found`);
+        }
+        if (d.status !== "proposed") {
+            store.close();
+            return fail(`refusing to reject ${d.status} decision ${d.id}; review --reject only removes proposed drafts`);
+        }
+        const ok2 = opts.private ? store.deleteWhereItLives("decisions", d.id) : store.json.delete("decisions", d.id);
         store.reindex();
-        console.log(ok2 ? `✓ rejected and removed ${opts.reject}` : `decision ${opts.reject} not found`);
+        console.log(ok2 ? `✓ rejected and removed ${d.id}` : `decision ${d.id} not found`);
     }
     else if (opts.rejectDuplicates) {
         // Deterministic hygiene, not a trust decision (dec_a466655539 stays intact):
@@ -1996,8 +3139,8 @@ function printAutoEntry(e) {
 }
 program
     .command("auto-review")
-    .description("Harness-driven draft triage: delegate relevance to the coding-assistant CLI, then dedup, auto-confirm the verified+relevant, and delete duplicates/irrelevant. Dry-run unless --apply.")
-    .option("--apply", "execute the plan (accept/delete). Without it, print the plan and change nothing.")
+    .description("Harness-driven draft triage: delegate relevance to the coding-assistant CLI, then dedup, auto-confirm the verified+relevant, and delete duplicates/irrelevant. Dry-run unless --apply; apply refuses an incomplete requested harness batch.")
+    .option("--apply", "execute the plan (accept/delete) only after a complete requested harness batch. Without it, print the plan and change nothing.")
     .option("--min-grounded <n>", "grounded-ness threshold for the auto-accept gate", String(READY_MIN_GROUNDED))
     .option("--min-reject-confidence <n>", "minimum harness confidence to DELETE an irrelevant draft (else kept for a human)", "0.7")
     .option("--no-llm", "skip the harness judgment (dedup + grounding only — no relevance deletion)")
@@ -2016,28 +3159,37 @@ program
             console.log("✓ No drafts to auto-review.");
             return;
         }
-        // Delegate relevance to the harness (subscription CLI) — feature-detected,
-        // and any per-draft failure degrades to "not judged" (kept for a human).
+        // Delegate relevance to the harness (subscription CLI) — feature-detected.
+        // A dry-run may remain partial (missing verdicts are kept), but --apply is
+        // all-or-nothing when judgment was requested: a provider outage must never
+        // turn an incomplete batch into an apparently safe mutation plan.
         const verdicts = new Map();
-        if (opts.llm !== false && !opts.private) {
+        const judgmentRequested = opts.llm !== false && !opts.private;
+        const judgmentFailures = [];
+        if (judgmentRequested) {
             const provider = await selectProvider({ root });
             if (provider.judgeDraft) {
-                // The candidate pool for duplicate_of / restatement: the LIVE, vouched records.
+                // Deletion anchors are only finalized, live, human-confirmed records.
                 const existing = all
-                    .filter((d) => d.provenance.source.includes("human_confirmed") && d.status !== "superseded" && d.status !== "rejected")
+                    .filter(isAcceptedDuplicateAnchor)
                     .map((d) => ({ id: d.id, title: d.title, decision: d.decision }));
                 console.log(`Judging ${drafts.length} draft(s) via ${provider.name} (subscription)…`);
                 for (const d of drafts) {
                     try {
                         verdicts.set(d.id, await provider.judgeDraft(d, existing.filter((e) => e.id !== d.id)));
                     }
-                    catch {
-                        /* transient / unparseable — leave unjudged, planner keeps it for a human */
+                    catch (e) {
+                        // Preserve the safe keep-for-human plan while making the missing
+                        // evidence observable. The apply gate below binds to this exact
+                        // draft set, so partial provider success cannot mutate the store.
+                        const error = (e instanceof Error ? e.message : String(e)).replace(/\s+/g, " ").trim();
+                        judgmentFailures.push({ id: d.id, error: error.slice(0, 240) || "unknown provider failure" });
                     }
                 }
             }
             else {
                 console.log(dim("No subscription CLI available — relevance judgment skipped (dedup + grounding only)."));
+                judgmentFailures.push(...drafts.map((d) => ({ id: d.id, error: "no subscription relevance judge available" })));
             }
         }
         else if (opts.private && opts.llm !== false) {
@@ -2045,11 +3197,28 @@ program
         }
         const plan = planAutoReview(drafts, all, verdicts, { minGrounded, minRejectConfidence });
         printAutoReviewPlan(plan);
+        if (judgmentRequested) {
+            const coverage = `${verdicts.size}/${drafts.length} judged`;
+            if (judgmentFailures.length) {
+                console.error(`\n⚠ Incomplete harness batch: ${coverage}; ${judgmentFailures.length} failure(s).`);
+                for (const failure of judgmentFailures.slice(0, 5))
+                    console.error(`   ${failure.id}: ${failure.error}`);
+                if (judgmentFailures.length > 5)
+                    console.error(`   … ${judgmentFailures.length - 5} more failure(s)`);
+            }
+            else {
+                console.log(`\n✓ Harness batch complete: ${coverage}.`);
+            }
+        }
         if (!opts.apply) {
             const n = planMutations(plan);
             console.log(`\n${dim(`Dry run — nothing changed. Re-run with --apply to ${n ? `apply ${n} change(s)` : "confirm (no changes)"}.`)}`);
             return;
         }
+        if (judgmentRequested && judgmentFailures.length) {
+            fail(`incomplete harness batch (${verdicts.size}/${drafts.length} judged); no changes applied. Re-run when the provider is healthy, or explicitly choose deterministic-only triage with --no-llm --apply.`);
+            return;
+        }
         // Apply: accept the verified+relevant, delete duplicates + irrelevant.
         let accepted = 0, deleted = 0, armedTotal = 0, publicAccepted = false;
         for (const e of plan.accept) {
@@ -2592,6 +3761,16 @@ program
     }
     const c = store.reindex().counts;
     console.log(`hunch:      ${c.symbols} symbols, ${c.edges} edges, ${c.components} components, ${c.decisions} decisions, ${c.bugs} bugs, ${c.constraints} constraints`);
+    try {
+        const policies = new ConstitutionService(store, root).list();
+        const active = policies.filter((p) => p.state === "active_advisory" || p.state === "active_blocking").length;
+        const proposed = policies.filter((p) => p.state === "proposed").length;
+        console.log(`constitution: ${policies.length} policies (${active} active, ${proposed} proposed)`);
+    }
+    catch (e) {
+        console.log(`constitution: ⛔ ${e.message}`);
+        process.exitCode = 1;
+    }
     // Overlay status speaks the TRUE mode, and a dead pointer is a loud finding, not a
     // silent empty store: the JSON reader degrades to [] when the target dir is missing,
     // so this is the one place the loss is visible.