@davesheffer/hunch 1.8.1 → 1.8.3

package/dist/cli/index.js

@@ -29,7 +29,7 @@ import { selectEmbedder } from "../store/embedder.js";
 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 { readSynthesisPreference, resolveSynthesisProvider, selectProvider, SYNTH_PREFERENCES, writeSynthesisPreference, normalizeProviderName, } from "../synthesis/provider.js";
 import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, workingFiles, commitFiles, asOfDate, stagedDiff, workingDiff, commitDiff, rangeFiles, rangeDiff, rangeSubjects, revExists, revParse, commitAndPushHunch, pullHunch, gitUntrackCached, gitCommonDir, isLinkedWorktree, mainWorktreeRoot, gitMemoryLog, memoryMoveDiff, revertMemoryMove, pushCurrentBranch, commitChanges } from "../extractors/git.js";
 import { parseMemoryLog } from "../core/memorylog.js";
 import { renamesOf, planRepair, repairDecision, repairConstraint } from "../core/repair.js";
@@ -85,7 +85,7 @@ import { movePublicMemoryToPrivate } from "../store/privateMigrate.js";
 import { ENTITY_KINDS } from "../core/types.js";
 import { planCompaction } from "../store/compact.js";
 import { repairDecisionReference } from "../core/refrepair.js";
-import { resolveInvocation } from "./invocation.js";
+import { resolveInvocation, dim, synthesisStatusLines, maybeWarnOllamaContext } from "./invocation.js";
 const program = new Command();
 program.name("hunch").description("Hunch — an Engineering Memory OS: a git-native reasoning graph for your codebase.").version(HUNCH_VERSION);
 let openStore = null;
@@ -272,8 +272,8 @@ program
     .option("--since <spec>", "how far back, e.g. 90d", "90d")
     .option("--max <n>", "max commits to process", "40")
     .option("--concurrency <n>", "commits to synthesize in parallel (the LLM call is the bottleneck)", "4")
-    .option("--deep", "Deep Synthesis: ensemble every available subscription CLI per commit and reconcile their drafts (slower, higher-quality; advisory)")
-    .option("--verify", "Critic pass: audit each draft against its commit, prune unsupported alternatives/consequences, down-weight weak grounding (extra subscription call; advisory)")
+    .option("--deep", "Deep Synthesis: ensemble every available LLM provider per commit and reconcile their drafts (slower, higher-quality; advisory)")
+    .option("--verify", "Critic pass: audit each draft against its commit, prune unsupported alternatives/consequences, down-weight weak grounding (extra provider call; advisory)")
     .option("--samples <n>", "self-consistency depth when only one CLI is installed: sample it n times per commit and reconcile (default 2 under --deep)")
     .action(async (opts) => {
     const { store, root } = storeFor();
@@ -283,6 +283,15 @@ program
     const commits = logSince(opts.since, root, Number(opts.max));
     const conc = Math.max(1, Math.min(16, Number(opts.concurrency) || 4));
     console.log(`Backfilling from ${commits.length} commit(s) since ${opts.since} (concurrency ${conc})…`);
+    // Best-effort context-window advisory (issue #11): printed ONCE, before any
+    // commit is drafted — not per-commit, and not under --deep (an ensemble may
+    // fan out to several distinct workers, each with its own configuration).
+    if (!opts.deep && commits.length > 0) {
+        const ctxProvider = await selectProvider();
+        const ctxWarning = await maybeWarnOllamaContext(ctxProvider.name, process.env);
+        if (ctxWarning)
+            console.log(ctxWarning);
+    }
     let written = 0, skipped = 0, llm = 0, heuristic = 0;
     // The per-commit cost is the Claude synthesis spawn; run several at once. Safe:
     // each commit drafts independently and writes its OWN decision file atomically,
@@ -322,8 +331,8 @@ program
     .option("--overlay", "alias of --private")
     .option("--commit", "after a capture, also git add+commit the repo the decision landed in (default: follows auto-commit, ON unless opted out) — the overlay is also pushed; the public .hunch/ rides your next push")
     .option("--no-commit", "skip the auto-commit for this capture even when auto-commit is on")
-    .option("--deep", "Deep Synthesis: ensemble every available subscription CLI and reconcile their drafts (agreement-weighted, advisory). Slower; subscription-only")
-    .option("--verify", "Critic pass: audit the draft against its commit, prune unsupported alternatives/consequences, down-weight weak grounding (extra subscription call; advisory)")
+    .option("--deep", "Deep Synthesis: ensemble every available LLM provider and reconcile their drafts (agreement-weighted, advisory). Slower; uses configured subscriptions/local endpoint")
+    .option("--verify", "Critic pass: audit the draft against its commit, prune unsupported alternatives/consequences, down-weight weak grounding (extra provider call; advisory)")
     .option("--samples <n>", "self-consistency depth when only one CLI is installed: sample it n times and reconcile (default 2 under --deep)")
     .action(async (sha, opts) => {
     const { store, root } = storeFor();
@@ -1948,6 +1957,23 @@ experimentCmd
         store.close();
     }
 });
+experimentCmd
+    .command("qualify")
+    .description("Record a passing excluded comprehension check before an EXP-03 revision-2 timed review.")
+    .argument("<file>", "reviewer qualification JSON")
+    .action((file) => {
+    const { store, root } = storeFor();
+    try {
+        const input = JSON.parse(readFileSync(resolve(file), "utf8"));
+        console.log(JSON.stringify(new ConstitutionService(store, root).qualifyExperimentReviewer(input), 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.")
@@ -2744,15 +2770,15 @@ program
     const next = writeConfig(paths, { firmness: level }).firmness;
     console.log(`✓ firmness set to ${next} (takes effect on the next agent edit — no restart needed).`);
 });
-// ---- provider (per-user synthesis subscription choice) -------------------
+// ---- provider (per-user synthesis provider choice) -----------------------
 program
     .command("provider")
-    .description("Show or set the local coding-assistant subscription Hunch may use for synthesis. Never changes team config.")
+    .description("Show or set the local LLM provider Hunch may use for synthesis. Never changes team config.")
     .argument("[name]", `auto | ${SYNTH_PREFERENCES.filter((p) => p !== "auto").join(" | ")} (omit to inspect)`)
     .action(async (value) => {
     const root = findRoot();
     if (value != null) {
-        const preference = value.trim();
+        const preference = normalizeProviderName(value.trim()) ?? value.trim();
         if (!SYNTH_PREFERENCES.includes(preference)) {
             return fail(`provider must be one of: ${SYNTH_PREFERENCES.join(", ")}`);
         }
@@ -2765,7 +2791,7 @@ program
         console.log(`✓ local synthesis preference set to ${preference} (gitignored; it never changes a teammate's billing choice).`);
     }
     const resolution = await resolveSynthesisProvider({ root });
-    const envValue = process.env.HUNCH_SYNTH_PROVIDER?.trim();
+    const envValue = normalizeProviderName(process.env.HUNCH_SYNTH_PROVIDER?.trim());
     const local = readSynthesisPreference(root);
     const hasValidEnv = !!envValue && SYNTH_PREFERENCES.includes(envValue);
     console.log(`selected:    ${resolution.provider.name} (${resolution.source})`);
@@ -2779,7 +2805,7 @@ program
     }
     if (resolution.source === "ambiguous") {
         const choices = resolution.statuses.filter((s) => s.name !== "deterministic" && s.available).map((s) => `hunch provider ${s.name}`);
-        console.log(dim("Multiple subscription CLIs are available, so Hunch uses the free deterministic fallback rather than guessing which plan to spend."));
+        console.log(dim("Multiple LLM providers are available, so Hunch uses the free deterministic fallback rather than guessing which subscription or endpoint to use."));
         console.log(`choose one:  ${choices.join("  or  ")}`);
     }
     else if (resolution.source === "unavailable-preference") {
@@ -3313,7 +3339,7 @@ program
             console.log("✓ No drafts to auto-review.");
             return;
         }
-        // Delegate relevance to the harness (subscription CLI) — feature-detected.
+        // Delegate relevance to the configured LLM provider — 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.
@@ -3342,7 +3368,7 @@ program
                 }
             }
             else {
-                console.log(dim("No subscription CLI available — relevance judgment skipped (dedup + grounding only)."));
+                console.log(dim("No LLM synthesis provider available — relevance judgment skipped (dedup + grounding only)."));
                 judgmentFailures.push(...drafts.map((d) => ({ id: d.id, error: "no subscription relevance judge available" })));
             }
         }
@@ -3779,7 +3805,7 @@ program
 // ---- wiki (generated component wiki — a derived VIEW of the graph) ----------
 program
     .command("wiki")
-    .description("Generate a component wiki from the graph — pages are a derived VIEW (the graph stays the source of truth), pinned with hunch:topic anchors and freshness-hashed into a wiki-manifest. Stale pages surface as wiki-stale in `hunch drift`; --heal regenerates ONLY those. Prose via a subscription CLI when available; deterministic template otherwise. Default: PUBLIC-store records only, written to <repo>/wiki/. With --private: the FULL graph (overlay included), written into the private overlay repo — never committed here.")
+    .description("Generate a component wiki from the graph — pages are a derived VIEW (the graph stays the source of truth), pinned with hunch:topic anchors and freshness-hashed into a wiki-manifest. Stale pages surface as wiki-stale in `hunch drift`; --heal regenerates ONLY those. Prose via the configured LLM provider when available; deterministic template otherwise. Default: PUBLIC-store records only, written to <repo>/wiki/. With --private: the FULL graph (overlay included), written into the private overlay repo — never committed here.")
     .option("--dir <dir>", "output directory (default: wiki/, or the manifest's dir once adopted)")
     .option("--heal", "regenerate only new/stale pages (manifest hash mismatch) and remove orphans")
     .option("--check", "report stale pages and exit non-zero (CI gate); writes nothing")
@@ -3844,8 +3870,8 @@ program
         // otherwise: drift says "remove with --heal", --heal refuses to run).
         if (!status.entries.length && !opts.heal)
             return fail("no active components in the graph — run `hunch index` first.");
-        // Prose is optional garnish on the deterministic skeleton: subscription CLI
-        // only (same rule as synthesis), feature-detected, and any failure degrades
+        // Prose is optional garnish on the deterministic skeleton: configured LLM
+        // provider only (same guards as synthesis), feature-detected, and any failure degrades
         // to a template page — generation never depends on a model being present.
         if (opts.proseHeal && opts.llm === false)
             return fail("--prose-heal needs the LLM — drop --no-llm.");
@@ -3854,13 +3880,13 @@ program
         if (opts.llm !== false) {
             const provider = await selectProvider({ root });
             if (provider.draftProse) {
-                console.log(`Prose via ${provider.name} (subscription); the drift-bearing skeleton stays deterministic.`);
+                console.log(`Prose via ${provider.name}; the drift-bearing skeleton stays deterministic.`);
                 prose = (pack, excerpts) => provider.draftProse(wikiPrompt(pack, excerpts));
                 if (opts.proseHeal)
                     adoptionProse = (doc, content) => provider.draftProse(adoptProsePrompt(doc, content, status.decisions));
             }
             else {
-                console.log(`No subscription CLI available — deterministic template pages${opts.proseHeal ? " (prose-heal skipped)" : ""}.`);
+                console.log(`No LLM synthesis provider available — deterministic template pages${opts.proseHeal ? " (prose-heal skipped)" : ""}.`);
             }
         }
         const res = await generateWiki(store, root, home, {
@@ -4087,22 +4113,16 @@ program
     const resolution = await resolveSynthesisProvider({ root });
     const provider = resolution.provider;
     console.log(`synthesis:  ${provider.name} (${resolution.source})`);
-    const selected = resolution.statuses.find((s) => s.name === provider.name);
-    if (selected?.subscription) {
-        console.log(`            ↳ LLM synthesis uses your ${selected.subscription}; provider API credentials are not used.`);
-    }
-    else if (resolution.source === "ambiguous") {
-        const names = resolution.statuses.filter((s) => s.name !== "deterministic" && s.available).map((s) => s.name);
-        console.log(dim(`            ↳ ${names.join(", ")} are available; Hunch will not guess which subscription to spend.`));
-        console.log(dim(`              choose one locally: ${names.map((name) => `hunch provider ${name}`).join("  or  ")}`));
-    }
-    else if (resolution.source === "unavailable-preference") {
-        console.log(dim(`            ↳ ${resolution.preference} was selected but is unavailable; using the offline heuristic.`));
-    }
-    else {
-        console.log(dim(`            ↳ no assistant CLI found — synthesis uses the offline heuristic (advisory, low-confidence).`));
-        console.log(dim(`              install or log into Claude Code, Codex, or Cursor; then select one with \`hunch provider <name>\`.`));
-    }
+    // Synthesis uses the user's SUBSCRIPTION via a coding-assistant CLI or a
+    // configured local/self-hosted endpoint. Public remotes require the named
+    // metered opt-in. Surface which one — or what's missing (issue #9:
+    // openai-compat has no `subscription` and must not fall through to the
+    // "no assistant CLI found" branch).
+    for (const line of synthesisStatusLines(resolution, process.env))
+        console.log(line);
+    const ctxWarning = await maybeWarnOllamaContext(provider.name, process.env);
+    if (ctxWarning)
+        console.log(ctxWarning);
     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 {
@@ -4199,9 +4219,6 @@ function reportClaudeConfigHeal() {
     }
     console.log(dim(`  ↳ backup: ${res.backup}`));
 }
-function dim(s) {
-    return `\x1b[2m${s}\x1b[0m`;
-}
 function fail(msg) {
     console.error(`error: ${msg}`);
     process.exitCode = 1;

package/dist/cli/invocation.js

@@ -1,8 +1,61 @@
-/** Figures out how to re-invoke this CLI from a git hook / .mcp.json, working
- *  both when running the built dist (plain node) and in dev via tsx. */
+/** Side-effect-free shared CLI logic — safe for any module (including tests)
+ *  to import, unlike src/cli/index.ts, which runs the whole program at
+ *  import time. Holds: how to re-invoke this CLI from a git hook / .mcp.json
+ *  (working both when running the built dist and in dev via tsx), plus small
+ *  formatting helpers (dim(), doctor's synthesisStatusLines()) that need the
+ *  same import-safety to be unit-testable. */
 import { fileURLToPath } from "node:url";
+import { probeOllamaNumCtx } from "../synthesis/provider.js";
 /** Published package name — used for OS-agnostic invocations (see below). */
 const PKG = "@davesheffer/hunch";
+export function dim(s) {
+    return `\x1b[2m${s}\x1b[0m`;
+}
+/** The doctor command's synthesis-status line(s) for a resolved provider.
+ *  Exported for testing — the previous version (a bare provider-name switch,
+ *  before the resolveSynthesisProvider preference system existed) had zero
+ *  test coverage, which is how issue #8 (openai-compat misreported as "no
+ *  assistant CLI found") shipped unnoticed through three review passes. That
+ *  bug resurfaces here for the same reason: resolution.statuses carries a
+ *  `subscription` field for the CLI providers but openai-compat's is null (it
+ *  isn't a subscription), so it must be special-cased explicitly rather than
+ *  falling through to the "no assistant CLI" branch. */
+export function synthesisStatusLines(resolution, env) {
+    const provider = resolution.provider;
+    const selected = resolution.statuses.find((s) => s.name === provider.name);
+    if (selected?.subscription) {
+        return [`            ↳ LLM synthesis uses your ${selected.subscription}; provider API credentials are not used.`];
+    }
+    if (provider.name === "openai-compat") {
+        const base = env.HUNCH_SYNTH_BASE_URL ?? "(unset)";
+        const model = env.HUNCH_SYNTH_MODEL ?? "(unset)";
+        const keyNote = env.HUNCH_SYNTH_API_KEY ? " (HUNCH_SYNTH_API_KEY set)" : " (no API key)";
+        return [`            ↳ LLM synthesis via local/self-hosted endpoint ${base} (model: ${model})${keyNote}`];
+    }
+    if (resolution.source === "ambiguous") {
+        const names = resolution.statuses.filter((s) => s.name !== "deterministic" && s.available).map((s) => s.name);
+        return [
+            dim(`            ↳ ${names.join(", ")} are available; Hunch will not guess which provider to use.`),
+            dim(`              choose one locally: ${names.map((name) => `hunch provider ${name}`).join("  or  ")}`),
+        ];
+    }
+    if (resolution.source === "unavailable-preference") {
+        return [dim(`            ↳ ${resolution.preference} was selected but is unavailable; using the offline heuristic.`)];
+    }
+    return [
+        dim(`            ↳ no assistant CLI found — synthesis uses the offline heuristic (advisory, low-confidence).`),
+        dim(`              install or log into Claude Code, Codex, or Cursor; then select one with \`hunch provider <name>\`.`),
+    ];
+}
+/** Gate + fetch the Ollama context-window advisory (issue #11): only relevant
+ *  for the openai-compat provider, so every other provider is a no-op. Kept
+ *  separate from synthesisStatusLines (sync, already fully covered) because
+ *  this one makes a best-effort network call. */
+export async function maybeWarnOllamaContext(providerName, env) {
+    if (providerName !== "openai-compat")
+        return null;
+    return probeOllamaNumCtx(env.HUNCH_SYNTH_BASE_URL ?? "", env.HUNCH_SYNTH_MODEL ?? "");
+}
 export function resolveInvocation() {
     const entry = fileURLToPath(import.meta.url).replace(/invocation\.(js|ts)$/, "index.$1");
     const isDev = entry.endsWith(".ts");

package/dist/constitution/experiment.js

@@ -245,6 +245,46 @@ export function assignmentTreatment(bank, run, assignment) {
         throw new Error(`assignment ${assignment.id} treatment hash mismatch`);
     return treatment;
 }
+/** Human-facing help is deliberately outside the hash-bound treatment. It may
+ * explain the review task, but must never interpret the assigned evidence. */
+export function experimentReviewGuide(arm) {
+    const notEnough = {
+        value: "uncompilable",
+        label: "Not enough information",
+        use_when: "The requirement does not clearly say which code relationship must always hold.",
+    };
+    if (arm === "A") {
+        return {
+            title: "Write one code rule from the requirement",
+            question: "Can one exact code rule be written from the requirement without guessing?",
+            action: "If yes, write one sentence naming the code elements, required or forbidden relationship, direct or transitive meaning, and file scope. If no, choose Not enough information.",
+            answer_template: "<subject> must <directly or transitively> <required or forbidden relationship> <target>; scope: <file or component>",
+            warning: "Use only the stated requirement. Current code may confirm names, but cannot add intent.",
+            choices: [
+                { value: "accepted_precise", label: "Rule written", use_when: "Your sentence expresses one exact rule fully supported by the requirement." },
+                notEnough,
+            ],
+        };
+    }
+    const choices = [
+        { value: "accepted_precise", label: "Yes — exact match", use_when: "The proposed rule says exactly what the requirement says." },
+        { value: "accepted_edited", label: "Needs editing", use_when: "The requirement supports one rule, but the proposal needs a specific correction." },
+        { value: "rejected", label: "Unsupported", use_when: "The proposal adds or changes meaning that the requirement does not support." },
+        notEnough,
+    ];
+    return {
+        title: arm === "C" ? "Check the proposed rule and its proof card" : "Check the proposed rule",
+        question: "Does the proposed rule say exactly what the requirement says?",
+        action: arm === "C"
+            ? "Compare the requirement with the proposed rule, then use the proof card only to check that the named code targets are bound correctly."
+            : "Compare the requirement with the proposed rule. Check the relationship, direction, direct or transitive meaning, and scope.",
+        answer_template: "Choose one plain-language option; include corrected rule text only for Needs editing.",
+        warning: arm === "C"
+            ? "The proof card can verify code bindings, but it cannot add intent missing from the requirement."
+            : "Do not infer intent from the current implementation or from nearby code.",
+        choices,
+    };
+}
 export function experimentRunContentHash(run) {
     const { id: _id, content_hash: _hash, ...body } = run;
     return canonicalHash(body);
@@ -537,6 +577,38 @@ export function compileExperimentReviewStart(run, assignment, reviewer, opts = {
     const contentHash = canonicalHash(body);
     return ExperimentReviewStartSchema.parse({ id: `expreview_${shortHash(contentHash)}`, content_hash: contentHash, ...body });
 }
+export const ExperimentReviewerQualificationSchema = z.object({
+    id: z.string().regex(/^expreviewqual_[a-f0-9]{10}$/),
+    content_hash: z.string().regex(HASH),
+    preregistration_id: z.string().regex(/^expreg_[a-f0-9]{10}$/),
+    preregistration_hash: z.string().regex(HASH),
+    reviewer: z.string().regex(/^human:[^\s]+$/i),
+    protocol: z.literal("exp03-plain-language-comprehension-v2"),
+    cases_hash: z.string().regex(HASH),
+    passed: z.literal(true),
+    reason: z.string().trim().min(1).max(4000),
+    data_class: z.literal("private"),
+    authority: z.literal("none"),
+    recorded_at: z.string().datetime({ offset: true }),
+}).strict();
+export function experimentReviewerQualificationContentHash(record) {
+    const { id: _id, content_hash: _hash, ...body } = record;
+    return canonicalHash(body);
+}
+export function compileExperimentReviewerQualification(input, preregistration, opts = {}) {
+    if (preregistration.experiment !== "EXP-03" || preregistration.revision < 2)
+        throw new Error("plain-language reviewer qualification requires EXP-03 revision 2 or later");
+    if (input.preregistration_id !== preregistration.id || input.preregistration_hash !== preregistration.content_hash)
+        throw new Error("reviewer qualification must bind the exact current preregistration");
+    const body = {
+        ...input,
+        data_class: "private",
+        authority: "none",
+        recorded_at: opts.now ?? new Date().toISOString(),
+    };
+    const contentHash = canonicalHash(body);
+    return ExperimentReviewerQualificationSchema.parse({ id: `expreviewqual_${shortHash(contentHash)}`, content_hash: contentHash, ...body });
+}
 export const ExperimentFollowupSchema = z.object({
     id: z.string().regex(/^expfollow_[a-f0-9]{10}$/),
     content_hash: z.string().regex(HASH),
@@ -943,6 +1015,24 @@ export class ExperimentRepository {
         this.put("experiment-review-starts", parsed.id, parsed);
         return parsed;
     }
+    listReviewerQualifications() {
+        return this.load("experiment-review-qualifications", "expreviewqual_", (raw) => {
+            const parsed = ExperimentReviewerQualificationSchema.parse(raw);
+            if (experimentReviewerQualificationContentHash(parsed) !== parsed.content_hash || parsed.id !== `expreviewqual_${shortHash(parsed.content_hash)}`)
+                throw new Error(`experiment reviewer qualification ${parsed.id} content hash mismatch`);
+            return parsed;
+        }).sort((a, b) => a.id.localeCompare(b.id));
+    }
+    putReviewerQualification(record) {
+        const parsed = ExperimentReviewerQualificationSchema.parse(record);
+        if (experimentReviewerQualificationContentHash(parsed) !== parsed.content_hash || parsed.id !== `expreviewqual_${shortHash(parsed.content_hash)}`)
+            throw new Error(`experiment reviewer qualification ${parsed.id} content hash mismatch`);
+        const incumbent = this.listReviewerQualifications().find((item) => item.preregistration_id === parsed.preregistration_id && item.reviewer === parsed.reviewer);
+        if (incumbent)
+            return incumbent;
+        this.put("experiment-review-qualifications", parsed.id, parsed);
+        return parsed;
+    }
     listFollowups() {
         const records = this.load("experiment-followups", "expfollow_", (raw) => {
             const parsed = ExperimentFollowupSchema.parse(raw);

package/dist/constitution/service.js

@@ -31,7 +31,7 @@ import { evaluateExecutableBehaviorPolicy } from "./behaviorEvaluator.js";
 import { executeG2OperationalDrill } from "./g2Drills.js";
 import { G3_REQUIRED_EXPERIMENTS, G3EvidenceRepository, compileExperimentPreregistration, compileG3Plan, compileProofReviewMeasurement, scoreG3Readiness, } from "./g3.js";
 import { executeG3AdapterConformance, g3ConformanceSourceHash } from "./g3Conformance.js";
-import { ExperimentRepository, assignmentTreatment, buildExperimentReport, compileExperimentCaseBank, compileExperimentFollowup, compileExperimentOutcome, compileExperimentReviewStart, compileExperimentRun, compileExperimentStop, compileExp03ReviewResponse, currentExperimentOutcomes, normalizedEditDistance, } from "./experiment.js";
+import { ExperimentRepository, assignmentTreatment, buildExperimentReport, compileExperimentCaseBank, compileExperimentFollowup, compileExperimentOutcome, compileExperimentReviewStart, compileExperimentReviewerQualification, compileExperimentRun, compileExperimentStop, compileExp03ReviewResponse, currentExperimentOutcomes, experimentReviewGuide, normalizedEditDistance, } from "./experiment.js";
 import { executeExp01Assignment } from "./experimentRunner.js";
 function relationSummary(policy) {
     return {
@@ -492,11 +492,22 @@ export class ConstitutionService {
         const bank = this.experimentRepository.listCaseBanks().find((item) => item.id === run.case_bank_id);
         if (!bank)
             throw new Error(`run ${run.id} is missing exact case bank ${run.case_bank_id}`);
+        const preregistration = this.g3Repository.listExperiments().find((item) => item.id === run.preregistration_id && item.content_hash === run.preregistration_hash);
+        const usesPlainLanguageReview = bank.cases.some((item) => "required_relationship" in item);
+        if (usesPlainLanguageReview && !preregistration)
+            throw new Error(`run ${run.id} is missing exact preregistration ${run.preregistration_id}`);
+        if (preregistration && preregistration.revision >= 2) {
+            const qualification = this.experimentRepository.listReviewerQualifications().find((item) => item.preregistration_id === preregistration.id && item.preregistration_hash === preregistration.content_hash && item.reviewer === reviewer);
+            if (!qualification)
+                throw new Error(`${reviewer} must pass the excluded plain-language comprehension check before a revision-${preregistration.revision} timed review`);
+            const targetReviewers = new Set(bank.cases.map((item) => item.strata.target_reviewer).filter(Boolean));
+            if (targetReviewers.has(reviewer) || targetReviewers.has(reviewer.replace(/^human:/i, "")))
+                throw new Error(`${reviewer} cannot perform timed reviews because the same actor labeled revision-${preregistration.revision} targets`);
+        }
         // Single-operator mitigation (expreg_9c9617cd13, revision >= 3): at least 48 hours
         // must separate the case-bank lock from the FIRST review start — enforced, not
         // merely auditable, so a violation is impossible rather than post-hoc visible.
-        const prereg = this.g3Repository.listExperiments().find((item) => item.id === run.preregistration_id);
-        if (prereg && prereg.revision >= 3) {
+        if (preregistration && preregistration.revision >= 3) {
             const elapsed = Date.parse(opts.now ?? new Date().toISOString()) - Date.parse(bank.locked_at);
             const hasStart = this.experimentRepository.listReviewStarts().some((item) => item.run_id === run.id);
             if (!hasStart && elapsed < 48 * 3_600_000) {
@@ -518,7 +529,13 @@ export class ConstitutionService {
         if (!assignment)
             throw new Error(`no unreviewed EXP-03 assignment is available for ${reviewer}`);
         const start = existing ?? this.experimentRepository.putReviewStart(compileExperimentReviewStart(run, assignment, reviewer, opts));
-        return { start, assignment, treatment: assignmentTreatment(bank, run, assignment) };
+        return { start, assignment, treatment: assignmentTreatment(bank, run, assignment), review_guide: experimentReviewGuide(assignment.arm) };
+    }
+    qualifyExperimentReviewer(input, opts = {}) {
+        const preregistration = this.g3Repository.currentExperiments().find((item) => item.experiment === "EXP-03");
+        if (!preregistration)
+            throw new Error("no current EXP-03 preregistration");
+        return this.experimentRepository.putReviewerQualification(compileExperimentReviewerQualification(input, preregistration, opts));
     }
     /** Resolve an EXP-03 run/assignment/case triple (the shared lookup for both
      *  review-submission dialects). */

package/dist/store/embedder.js

@@ -3,7 +3,7 @@
  * "add embeddings once keyword search proves insufficient" upgrade).
  *
  * Embeddings are LOCAL and FREE. Anthropic has no embeddings endpoint and the
- * project is subscription-only (see synthesis/provider.ts), so we run a small
+ * project avoids implicit metered inference (see synthesis/provider.ts), so we run a small
  * sentence-transformer locally via transformers.js. That library is an OPTIONAL
  * dependency, dynamically imported — if it isn't installed, `selectEmbedder()`
  * returns null and the whole feature degrades to pure FTS (the lean-install