@crewhaus/contract-compiler 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Track G (§58) — `contract-compiler`. Two-pass compilation of a raw
+ * issue/spec draft into a structured contract suitable for downstream
+ * agent execution.
+ *
+ * Source: Meta-Engineering Harnesses (Sengupta et al., HireNimbus,
+ * arxiv 2605.25665, §4.2). The two-pass model:
+ *
+ *   - **Pass 1 (completeness)** — Converts the raw issue to a
+ *     structured draft, making implicit assumptions explicit through
+ *     types, state transitions, edge cases, trust boundaries, error
+ *     conditions.
+ *   - **Pass 2 (scope/ambiguity)** — Reduces and clarifies. Removes
+ *     unsupported requirements. Rewrites ambiguous clauses so
+ *     downstream agents don't treat multiple interpretations as
+ *     equally valid.
+ *
+ * Empirical motivation from the paper: **first-pass contracts can
+ * over-specify**, and over-specification is dangerous because
+ * downstream agents treat unsupported requirements as mandatory.
+ *
+ * v0 ships the pure-function pipeline. The "completeness" and
+ * "ambiguity" detectors here are rule-based; the production CLI wires
+ * an LLM-backed refiner on top via the `refiner?` option. Either way
+ * the pass shapes are the same and the registered specialization
+ * invariants are injected at the end of pass 1 (before ambiguity
+ * resolution can prune them).
+ *
+ * Cited paper: Meta-Engineering Harnesses (arxiv 2605.25665).
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { type Invariant, type Specialization, type SpecializationMatch } from "@crewhaus/specialization-registry";
+export declare class ContractCompilerError extends CrewhausError {
+    readonly name = "ContractCompilerError";
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * A compiled contract — the structured artifact downstream tools
+ * (codegen, eval, optimizer) consume. The shape is intentionally
+ * minimal; richer fields can be added without breaking callers
+ * because every consumer treats unknown fields as opaque.
+ */
+export type CompiledContract = {
+    readonly title: string;
+    readonly summary: string;
+    readonly requirements: ReadonlyArray<Requirement>;
+    readonly invariants: ReadonlyArray<Invariant>;
+    readonly outOfScope: ReadonlyArray<string>;
+    readonly ambiguitiesResolved: ReadonlyArray<AmbiguityResolution>;
+    readonly specialization?: SpecializationMatch;
+};
+export type Requirement = {
+    readonly id: string;
+    readonly text: string;
+    readonly source: "user" | "specialization" | "completeness-pass";
+};
+export type AmbiguityResolution = {
+    readonly clause: string;
+    readonly originalText: string;
+    readonly resolution: string;
+};
+export type CompileContractOptions = {
+    /** The raw issue text the user supplied. */
+    readonly rawIssue: string;
+    /**
+     * Optional registry override. Defaults to BUILTIN_SPECIALIZATIONS.
+     * Pass `loadRegistry(".crewhaus/specializations")` to merge project
+     * overrides on top.
+     */
+    readonly registry?: ReadonlyArray<Specialization>;
+    /**
+     * When set, force a specialization match (skip auto-detection).
+     * Useful when the user explicitly names the domain.
+     */
+    readonly forceSpecialization?: string;
+    /**
+     * Optional LLM-backed refiner. When supplied, replaces the rule-based
+     * completeness/ambiguity passes. The signature is `(draft) → refined`
+     * so the package stays pure for tests.
+     */
+    readonly refiner?: RefinerFn;
+};
+export type RefinerFn = (draft: CompiledContract) => Promise<CompiledContract>;
+/**
+ * Run the two-pass compilation. Returns the final contract; throws
+ * ContractCompilerError if the raw issue is empty (the completeness
+ * pass has nothing to work with).
+ */
+export declare function compileContract(opts: CompileContractOptions): Promise<CompiledContract>;
+/**
+ * Render a CompiledContract back to a YAML-friendly fragment that can
+ * be appended into a `crewhaus.yaml`'s `agent.instructions` field.
+ * Strict — no host code, no env access, just string concatenation.
+ */
+export declare function renderContract(c: CompiledContract): string;

package/dist/index.js

@@ -0,0 +1,213 @@
+/**
+ * Track G (§58) — `contract-compiler`. Two-pass compilation of a raw
+ * issue/spec draft into a structured contract suitable for downstream
+ * agent execution.
+ *
+ * Source: Meta-Engineering Harnesses (Sengupta et al., HireNimbus,
+ * arxiv 2605.25665, §4.2). The two-pass model:
+ *
+ *   - **Pass 1 (completeness)** — Converts the raw issue to a
+ *     structured draft, making implicit assumptions explicit through
+ *     types, state transitions, edge cases, trust boundaries, error
+ *     conditions.
+ *   - **Pass 2 (scope/ambiguity)** — Reduces and clarifies. Removes
+ *     unsupported requirements. Rewrites ambiguous clauses so
+ *     downstream agents don't treat multiple interpretations as
+ *     equally valid.
+ *
+ * Empirical motivation from the paper: **first-pass contracts can
+ * over-specify**, and over-specification is dangerous because
+ * downstream agents treat unsupported requirements as mandatory.
+ *
+ * v0 ships the pure-function pipeline. The "completeness" and
+ * "ambiguity" detectors here are rule-based; the production CLI wires
+ * an LLM-backed refiner on top via the `refiner?` option. Either way
+ * the pass shapes are the same and the registered specialization
+ * invariants are injected at the end of pass 1 (before ambiguity
+ * resolution can prune them).
+ *
+ * Cited paper: Meta-Engineering Harnesses (arxiv 2605.25665).
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { match as matchSpecialization, } from "@crewhaus/specialization-registry";
+export class ContractCompilerError extends CrewhausError {
+    name = "ContractCompilerError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+/**
+ * Run the two-pass compilation. Returns the final contract; throws
+ * ContractCompilerError if the raw issue is empty (the completeness
+ * pass has nothing to work with).
+ */
+export async function compileContract(opts) {
+    const raw = opts.rawIssue.trim();
+    if (raw.length === 0) {
+        throw new ContractCompilerError("rawIssue is empty");
+    }
+    // Pass 1 — completeness: extract requirements, identify
+    // state-transition / trust-boundary / error-handling gaps, inject
+    // specialization invariants when confidence is sufficient.
+    const matched = matchSpecialization(raw, {
+        ...(opts.forceSpecialization !== undefined
+            ? { mode: "strict", forceMatch: opts.forceSpecialization }
+            : {}),
+        ...(opts.registry !== undefined ? { registry: opts.registry } : {}),
+    });
+    const userRequirements = extractRequirements(raw);
+    const completenessRequirements = inferCompletenessRequirements(raw);
+    const requirements = [
+        ...userRequirements.map((text, i) => ({
+            id: `user-${i}`,
+            text,
+            source: "user",
+        })),
+        ...completenessRequirements.map((text, i) => ({
+            id: `completeness-${i}`,
+            text,
+            source: "completeness-pass",
+        })),
+    ];
+    const invariants = matched !== undefined ? [...matched.specialization.invariants] : [];
+    if (matched !== undefined) {
+        for (const inv of matched.specialization.invariants) {
+            requirements.push({
+                id: `spec-${matched.specialization.name}-${inv.id}`,
+                text: `${matched.specialization.name}: ${inv.description}`,
+                source: "specialization",
+            });
+        }
+    }
+    const draft = {
+        title: extractTitle(raw),
+        summary: raw,
+        requirements,
+        invariants,
+        outOfScope: [],
+        ambiguitiesResolved: [],
+        ...(matched !== undefined ? { specialization: matched } : {}),
+    };
+    // Pass 2 — scope/ambiguity: remove obvious unsupported clauses,
+    // rewrite ambiguous wording. When a refiner is supplied, defer to
+    // it; otherwise apply the rule-based detectors.
+    const refined = opts.refiner !== undefined ? await opts.refiner(draft) : ambiguityPass(draft);
+    return refined;
+}
+/**
+ * Bullet-extractor: lines starting with -, *, or numbered. Collects
+ * the trimmed body of each.
+ */
+function extractRequirements(text) {
+    const lines = text.split(/\r?\n/);
+    const out = [];
+    for (const line of lines) {
+        const m = line.match(/^\s*[-*]\s+(.+)$/) ?? line.match(/^\s*\d+\.\s+(.+)$/);
+        if (m !== null && m[1] !== undefined)
+            out.push(m[1].trim());
+    }
+    return out;
+}
+function extractTitle(text) {
+    const firstLine = text.split(/\r?\n/)[0]?.trim() ?? "";
+    if (firstLine.startsWith("#"))
+        return firstLine.replace(/^#+\s*/, "");
+    return firstLine.slice(0, 120);
+}
+/**
+ * Completeness inferences. Looks for known omissions and adds a
+ * one-line "the contract should also say" requirement so the
+ * specification author sees the gap explicitly. Idempotent: each rule
+ * only fires when the corresponding signal is *absent* from the raw
+ * text.
+ */
+function inferCompletenessRequirements(text) {
+    const lower = text.toLowerCase();
+    const inferred = [];
+    if (!/error|fail|exception|reject/.test(lower)) {
+        inferred.push("Specify the error-handling contract: which failures the agent must surface vs swallow.");
+    }
+    if (!/edge\s*case|boundary|invalid|empty/.test(lower)) {
+        inferred.push("Enumerate edge cases (empty inputs, invalid inputs, boundary conditions).");
+    }
+    if (/state|status|transition/.test(lower) && !/transition/.test(lower)) {
+        inferred.push("Document the allowed state transitions explicitly (rather than implying them).");
+    }
+    if (/(?:auth|token|secret|password|credential)/.test(lower) &&
+        !/(trust\s*bound|threat\s*model|attacker)/.test(lower)) {
+        inferred.push("Name the trust boundaries: what the system trusts the caller for vs what it independently verifies.");
+    }
+    return inferred;
+}
+/**
+ * Ambiguity pass. Heuristic detectors for the most common authoring
+ * mistakes the paper highlights: vague quantifiers ("some", "a few",
+ * "maybe"), passive-voice subject elision ("it should be handled"),
+ * and contradictory pairs detected by negation distance.
+ *
+ * Each resolved ambiguity gets recorded in `ambiguitiesResolved` so
+ * the contract reviewer sees the substitution explicitly.
+ */
+function ambiguityPass(draft) {
+    const resolutions = [];
+    const VAGUE_RE = /\b(some|a few|several|maybe|possibly|might|perhaps)\b/gi;
+    const newRequirements = [];
+    for (const req of draft.requirements) {
+        if (VAGUE_RE.test(req.text)) {
+            VAGUE_RE.lastIndex = 0;
+            const resolved = req.text.replace(VAGUE_RE, "[QUANTIFY]");
+            resolutions.push({
+                clause: req.id,
+                originalText: req.text,
+                resolution: "Vague quantifier flagged; replaced with [QUANTIFY] placeholder. The contract reviewer must supply a number or remove the clause.",
+            });
+            newRequirements.push({ ...req, text: resolved });
+        }
+        else {
+            newRequirements.push(req);
+        }
+    }
+    return {
+        ...draft,
+        requirements: newRequirements,
+        ambiguitiesResolved: resolutions,
+    };
+}
+/**
+ * Render a CompiledContract back to a YAML-friendly fragment that can
+ * be appended into a `crewhaus.yaml`'s `agent.instructions` field.
+ * Strict — no host code, no env access, just string concatenation.
+ */
+export function renderContract(c) {
+    const lines = [];
+    lines.push(`# Contract: ${c.title}`);
+    if (c.specialization !== undefined) {
+        lines.push(`# Specialization: ${c.specialization.specialization.name} (confidence ${c.specialization.confidence.toFixed(2)})`);
+    }
+    lines.push("");
+    lines.push("## Requirements");
+    for (const r of c.requirements) {
+        lines.push(`- [${r.source}] ${r.text}`);
+    }
+    if (c.invariants.length > 0) {
+        lines.push("");
+        lines.push("## Invariants");
+        for (const inv of c.invariants) {
+            lines.push(`- [${inv.required ? "required" : "optional"}] ${inv.id}: ${inv.description}`);
+        }
+    }
+    if (c.outOfScope.length > 0) {
+        lines.push("");
+        lines.push("## Out of scope");
+        for (const oos of c.outOfScope)
+            lines.push(`- ${oos}`);
+    }
+    if (c.ambiguitiesResolved.length > 0) {
+        lines.push("");
+        lines.push("## Ambiguities resolved");
+        for (const a of c.ambiguitiesResolved) {
+            lines.push(`- ${a.clause}: ${a.resolution}`);
+        }
+    }
+    return lines.join("\n");
+}

package/package.json

@@ -1,19 +1,22 @@
 {
   "name": "@crewhaus/contract-compiler",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "Track G / §58 — two-pass contract compilation (completeness + scope/ambiguity). Source: Meta-Engineering Harnesses (arxiv 2605.25665, §4.2).",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.3",
-    "@crewhaus/specialization-registry": "0.1.3"
+    "@crewhaus/errors": "0.1.5",
+    "@crewhaus/specialization-registry": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -33,5 +36,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,242 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { ContractCompilerError, compileContract, renderContract } from "./index";
-
-describe("compileContract — pass 1 completeness", () => {
-  test("throws on empty input", async () => {
-    await expect(compileContract({ rawIssue: "   " })).rejects.toThrow(ContractCompilerError);
-  });
-
-  test("extracts bullet-list requirements", async () => {
-    const c = await compileContract({
-      rawIssue: "Implement search\n- Must handle empty queries\n- Should return top 10 results",
-    });
-    const userReqs = c.requirements.filter((r) => r.source === "user");
-    expect(userReqs.length).toBe(2);
-    expect(userReqs[0]?.text).toContain("empty queries");
-  });
-
-  test("extracts numbered requirements", async () => {
-    const c = await compileContract({
-      rawIssue: "Add login\n1. JWT tokens\n2. Refresh after 1h",
-    });
-    const userReqs = c.requirements.filter((r) => r.source === "user");
-    expect(userReqs.length).toBe(2);
-  });
-
-  test("adds completeness-pass requirements when error handling is unmentioned", async () => {
-    const c = await compileContract({ rawIssue: "Add a button that increments a counter" });
-    const completeness = c.requirements.filter((r) => r.source === "completeness-pass");
-    expect(completeness.some((r) => /error-handling/i.test(r.text))).toBe(true);
-  });
-
-  test("skips completeness rule when the signal is already present", async () => {
-    const c = await compileContract({
-      rawIssue:
-        "Add /search endpoint with explicit error handling and edge case enumeration for empty + invalid inputs.",
-    });
-    const completeness = c.requirements.filter((r) => r.source === "completeness-pass");
-    expect(completeness.some((r) => /error-handling/i.test(r.text))).toBe(false);
-  });
-});
-
-describe("compileContract — specialization injection", () => {
-  test("injects payments invariants when input mentions stripe", async () => {
-    const c = await compileContract({
-      rawIssue: "Build a Stripe paymentintent + refund flow",
-    });
-    expect(c.specialization?.specialization.name).toBe("payments");
-    const ids = c.invariants.map((i) => i.id);
-    expect(ids).toContain("idempotency-key");
-    expect(ids).toContain("trust-boundary-client-status");
-  });
-
-  test("does not inject any specialization for unrelated input", async () => {
-    const c = await compileContract({
-      rawIssue: "Style the homepage with a new color scheme",
-    });
-    expect(c.specialization).toBeUndefined();
-    expect(c.invariants.length).toBe(0);
-  });
-
-  test("forceSpecialization overrides auto-detect", async () => {
-    const c = await compileContract({
-      rawIssue: "anything at all",
-      forceSpecialization: "auth",
-    });
-    expect(c.specialization?.specialization.name).toBe("auth");
-    expect(c.specialization?.confidence).toBe(1);
-  });
-});
-
-describe("compileContract — pass 2 ambiguity", () => {
-  test("flags vague quantifiers in requirements", async () => {
-    const c = await compileContract({
-      rawIssue: "Notes:\n- Return some results when the user searches",
-    });
-    expect(c.ambiguitiesResolved.length).toBeGreaterThan(0);
-    const r = c.requirements.find((r) => r.source === "user");
-    expect(r?.text).toContain("[QUANTIFY]");
-  });
-
-  test("supplied refiner replaces the rule-based pass 2", async () => {
-    const c = await compileContract({
-      rawIssue: "Maybe handle the timeout case",
-      refiner: async (draft) => ({
-        ...draft,
-        outOfScope: ["everything except the happy path"],
-      }),
-    });
-    expect(c.outOfScope).toEqual(["everything except the happy path"]);
-    // Refiner replaced the rule-based pass, so vague quantifiers are NOT
-    // automatically flagged.
-    expect(c.ambiguitiesResolved.length).toBe(0);
-  });
-});
-
-describe("compileContract — completeness inference branches", () => {
-  test("infers a state-transition requirement when status is implied but transitions are not", async () => {
-    const c = await compileContract({
-      // mentions "status" (matches state-rule's positive signal) but never
-      // says "transition" (negative signal absent) -> rule fires.
-      rawIssue: "Track the order status and surface invalid empty failures.",
-    });
-    const completeness = c.requirements.filter((r) => r.source === "completeness-pass");
-    expect(completeness.some((r) => /state transitions/i.test(r.text))).toBe(true);
-  });
-
-  test("does not infer a state-transition requirement when 'transition' is already present", async () => {
-    const c = await compileContract({
-      rawIssue: "Document each status transition; handle invalid empty error inputs.",
-    });
-    const completeness = c.requirements.filter((r) => r.source === "completeness-pass");
-    expect(completeness.some((r) => /state transitions/i.test(r.text))).toBe(false);
-  });
-
-  test("infers a trust-boundary requirement when secrets are mentioned without a threat model", async () => {
-    const c = await compileContract({
-      // mentions "token"/"password" but no trust-boundary/threat-model/attacker.
-      rawIssue: "Store the user password and issue a token. Handle invalid empty failures.",
-    });
-    const completeness = c.requirements.filter((r) => r.source === "completeness-pass");
-    expect(completeness.some((r) => /trust boundaries/i.test(r.text))).toBe(true);
-  });
-
-  test("does not infer a trust-boundary requirement when a threat model is already named", async () => {
-    const c = await compileContract({
-      rawIssue:
-        "Handle the auth token under an explicit threat model. Cover invalid empty error inputs.",
-    });
-    const completeness = c.requirements.filter((r) => r.source === "completeness-pass");
-    expect(completeness.some((r) => /trust boundaries/i.test(r.text))).toBe(false);
-  });
-});
-
-describe("compileContract — title + requirement extraction edge cases", () => {
-  test("strips a leading markdown heading marker from the title", async () => {
-    const c = await compileContract({ rawIssue: "# Build the widget\nbody text" });
-    expect(c.title).toBe("Build the widget");
-  });
-
-  test("truncates a long single-line title to 120 chars", async () => {
-    const long = "x".repeat(200);
-    const c = await compileContract({ rawIssue: long });
-    expect(c.title.length).toBe(120);
-  });
-
-  test("ignores bullet markers that have no body", async () => {
-    // "-" / "1." with no following text must not produce a requirement.
-    const c = await compileContract({ rawIssue: "Title line\n-\n1.\n- real item" });
-    const userReqs = c.requirements.filter((r) => r.source === "user");
-    expect(userReqs.length).toBe(1);
-    expect(userReqs[0]?.text).toBe("real item");
-  });
-});
-
-describe("ambiguityPass — global-regex statefulness regression", () => {
-  test("flags vague quantifiers independently across consecutive requirements", async () => {
-    // Regression guard: VAGUE_RE carries the /g flag and is reused across the
-    // requirement loop. A leaked lastIndex would cause a later requirement to
-    // be skipped or mis-matched. Every vague line must be flagged regardless
-    // of position.
-    const c = await compileContract({
-      rawIssue: [
-        "Title",
-        "- return some results",
-        "- handle maybe the timeout",
-        "- a clean requirement with no vague words",
-        "- perhaps several edge cases",
-        "- another clean concrete requirement",
-        "- might retry once",
-      ].join("\n"),
-    });
-    const userReqs = c.requirements.filter((r) => r.source === "user");
-    const flagged = userReqs.filter((r) => r.text.includes("[QUANTIFY]"));
-    // Lines containing some / maybe / perhaps+several / might -> 4 flagged.
-    expect(flagged.length).toBe(4);
-    // Each flagged requirement is recorded once in ambiguitiesResolved.
-    expect(c.ambiguitiesResolved.length).toBe(4);
-    // The two concrete requirements are passed through untouched.
-    expect(userReqs.some((r) => r.text === "a clean requirement with no vague words")).toBe(true);
-    expect(userReqs.some((r) => r.text === "another clean concrete requirement")).toBe(true);
-  });
-
-  test("replaces every vague occurrence within a single requirement", async () => {
-    const c = await compileContract({ rawIssue: "Title\n- perhaps several retries" });
-    const req = c.requirements.find((r) => r.source === "user");
-    expect(req?.text).toBe("[QUANTIFY] [QUANTIFY] retries");
-  });
-});
-
-describe("renderContract", () => {
-  test("emits a markdown-flavored block including invariants and ambiguities", async () => {
-    const c = await compileContract({
-      rawIssue: "Stripe paymentintent flow\n- Refund support\n- Some retries",
-    });
-    const md = renderContract(c);
-    expect(md).toContain("# Contract:");
-    expect(md).toContain("## Requirements");
-    expect(md).toContain("## Invariants");
-    expect(md).toContain("idempotency-key");
-    expect(md).toContain("## Ambiguities resolved");
-  });
-
-  test("renders the specialization header line with confidence when matched", async () => {
-    const c = await compileContract({ rawIssue: "anything", forceSpecialization: "auth" });
-    const md = renderContract(c);
-    expect(md).toContain("# Specialization: auth (confidence 1.00)");
-  });
-
-  test("renders required vs optional invariants distinctly", async () => {
-    const c = await compileContract({ rawIssue: "Stripe refund and invoice charge flow" });
-    const md = renderContract(c);
-    // payments has both required (idempotency-key) and optional
-    // (discount-deduction-source) invariants.
-    expect(md).toContain("- [required] idempotency-key:");
-    expect(md).toContain("- [optional] discount-deduction-source:");
-  });
-
-  test("omits the optional sections when the contract has no invariants/oos/ambiguities", async () => {
-    // Plain input with explicit error+edge handling -> no specialization, no
-    // invariants, no completeness noise that triggers ambiguity, no out-of-scope.
-    const c = await compileContract({
-      rawIssue:
-        "Rename a CSS class with explicit error handling and edge case enumeration for empty + invalid inputs.",
-    });
-    const md = renderContract(c);
-    expect(md).not.toContain("## Invariants");
-    expect(md).not.toContain("## Out of scope");
-    expect(md).not.toContain("## Ambiguities resolved");
-    expect(md).not.toContain("# Specialization:");
-    expect(md).toContain("## Requirements");
-  });
-
-  test("renders an out-of-scope section when present", async () => {
-    const c = await compileContract({
-      rawIssue: "Add a feature",
-      refiner: async (draft) => ({ ...draft, outOfScope: ["payments integration"] }),
-    });
-    const md = renderContract(c);
-    expect(md).toContain("## Out of scope");
-    expect(md).toContain("- payments integration");
-  });
-});

package/src/index.ts

@@ -1,287 +0,0 @@
-/**
- * Track G (§58) — `contract-compiler`. Two-pass compilation of a raw
- * issue/spec draft into a structured contract suitable for downstream
- * agent execution.
- *
- * Source: Meta-Engineering Harnesses (Sengupta et al., HireNimbus,
- * arxiv 2605.25665, §4.2). The two-pass model:
- *
- *   - **Pass 1 (completeness)** — Converts the raw issue to a
- *     structured draft, making implicit assumptions explicit through
- *     types, state transitions, edge cases, trust boundaries, error
- *     conditions.
- *   - **Pass 2 (scope/ambiguity)** — Reduces and clarifies. Removes
- *     unsupported requirements. Rewrites ambiguous clauses so
- *     downstream agents don't treat multiple interpretations as
- *     equally valid.
- *
- * Empirical motivation from the paper: **first-pass contracts can
- * over-specify**, and over-specification is dangerous because
- * downstream agents treat unsupported requirements as mandatory.
- *
- * v0 ships the pure-function pipeline. The "completeness" and
- * "ambiguity" detectors here are rule-based; the production CLI wires
- * an LLM-backed refiner on top via the `refiner?` option. Either way
- * the pass shapes are the same and the registered specialization
- * invariants are injected at the end of pass 1 (before ambiguity
- * resolution can prune them).
- *
- * Cited paper: Meta-Engineering Harnesses (arxiv 2605.25665).
- */
-import { CrewhausError } from "@crewhaus/errors";
-import {
-  type Invariant,
-  type Specialization,
-  type SpecializationMatch,
-  match as matchSpecialization,
-} from "@crewhaus/specialization-registry";
-
-export class ContractCompilerError extends CrewhausError {
-  override readonly name = "ContractCompilerError";
-  constructor(message: string, cause?: unknown) {
-    super("config", message, cause);
-  }
-}
-
-/**
- * A compiled contract — the structured artifact downstream tools
- * (codegen, eval, optimizer) consume. The shape is intentionally
- * minimal; richer fields can be added without breaking callers
- * because every consumer treats unknown fields as opaque.
- */
-export type CompiledContract = {
-  readonly title: string;
-  readonly summary: string;
-  readonly requirements: ReadonlyArray<Requirement>;
-  readonly invariants: ReadonlyArray<Invariant>;
-  readonly outOfScope: ReadonlyArray<string>;
-  readonly ambiguitiesResolved: ReadonlyArray<AmbiguityResolution>;
-  readonly specialization?: SpecializationMatch;
-};
-
-export type Requirement = {
-  readonly id: string;
-  readonly text: string;
-  readonly source: "user" | "specialization" | "completeness-pass";
-};
-
-export type AmbiguityResolution = {
-  readonly clause: string;
-  readonly originalText: string;
-  readonly resolution: string;
-};
-
-export type CompileContractOptions = {
-  /** The raw issue text the user supplied. */
-  readonly rawIssue: string;
-  /**
-   * Optional registry override. Defaults to BUILTIN_SPECIALIZATIONS.
-   * Pass `loadRegistry(".crewhaus/specializations")` to merge project
-   * overrides on top.
-   */
-  readonly registry?: ReadonlyArray<Specialization>;
-  /**
-   * When set, force a specialization match (skip auto-detection).
-   * Useful when the user explicitly names the domain.
-   */
-  readonly forceSpecialization?: string;
-  /**
-   * Optional LLM-backed refiner. When supplied, replaces the rule-based
-   * completeness/ambiguity passes. The signature is `(draft) → refined`
-   * so the package stays pure for tests.
-   */
-  readonly refiner?: RefinerFn;
-};
-
-export type RefinerFn = (draft: CompiledContract) => Promise<CompiledContract>;
-
-/**
- * Run the two-pass compilation. Returns the final contract; throws
- * ContractCompilerError if the raw issue is empty (the completeness
- * pass has nothing to work with).
- */
-export async function compileContract(opts: CompileContractOptions): Promise<CompiledContract> {
-  const raw = opts.rawIssue.trim();
-  if (raw.length === 0) {
-    throw new ContractCompilerError("rawIssue is empty");
-  }
-
-  // Pass 1 — completeness: extract requirements, identify
-  // state-transition / trust-boundary / error-handling gaps, inject
-  // specialization invariants when confidence is sufficient.
-  const matched = matchSpecialization(raw, {
-    ...(opts.forceSpecialization !== undefined
-      ? { mode: "strict", forceMatch: opts.forceSpecialization }
-      : {}),
-    ...(opts.registry !== undefined ? { registry: opts.registry } : {}),
-  });
-
-  const userRequirements = extractRequirements(raw);
-  const completenessRequirements = inferCompletenessRequirements(raw);
-  const requirements: Requirement[] = [
-    ...userRequirements.map((text, i) => ({
-      id: `user-${i}`,
-      text,
-      source: "user" as const,
-    })),
-    ...completenessRequirements.map((text, i) => ({
-      id: `completeness-${i}`,
-      text,
-      source: "completeness-pass" as const,
-    })),
-  ];
-  const invariants: Invariant[] =
-    matched !== undefined ? [...matched.specialization.invariants] : [];
-  if (matched !== undefined) {
-    for (const inv of matched.specialization.invariants) {
-      requirements.push({
-        id: `spec-${matched.specialization.name}-${inv.id}`,
-        text: `${matched.specialization.name}: ${inv.description}`,
-        source: "specialization",
-      });
-    }
-  }
-
-  const draft: CompiledContract = {
-    title: extractTitle(raw),
-    summary: raw,
-    requirements,
-    invariants,
-    outOfScope: [],
-    ambiguitiesResolved: [],
-    ...(matched !== undefined ? { specialization: matched } : {}),
-  };
-
-  // Pass 2 — scope/ambiguity: remove obvious unsupported clauses,
-  // rewrite ambiguous wording. When a refiner is supplied, defer to
-  // it; otherwise apply the rule-based detectors.
-  const refined = opts.refiner !== undefined ? await opts.refiner(draft) : ambiguityPass(draft);
-  return refined;
-}
-
-/**
- * Bullet-extractor: lines starting with -, *, or numbered. Collects
- * the trimmed body of each.
- */
-function extractRequirements(text: string): string[] {
-  const lines = text.split(/\r?\n/);
-  const out: string[] = [];
-  for (const line of lines) {
-    const m = line.match(/^\s*[-*]\s+(.+)$/) ?? line.match(/^\s*\d+\.\s+(.+)$/);
-    if (m !== null && m[1] !== undefined) out.push(m[1].trim());
-  }
-  return out;
-}
-
-function extractTitle(text: string): string {
-  const firstLine = text.split(/\r?\n/)[0]?.trim() ?? "";
-  if (firstLine.startsWith("#")) return firstLine.replace(/^#+\s*/, "");
-  return firstLine.slice(0, 120);
-}
-
-/**
- * Completeness inferences. Looks for known omissions and adds a
- * one-line "the contract should also say" requirement so the
- * specification author sees the gap explicitly. Idempotent: each rule
- * only fires when the corresponding signal is *absent* from the raw
- * text.
- */
-function inferCompletenessRequirements(text: string): string[] {
-  const lower = text.toLowerCase();
-  const inferred: string[] = [];
-  if (!/error|fail|exception|reject/.test(lower)) {
-    inferred.push(
-      "Specify the error-handling contract: which failures the agent must surface vs swallow.",
-    );
-  }
-  if (!/edge\s*case|boundary|invalid|empty/.test(lower)) {
-    inferred.push("Enumerate edge cases (empty inputs, invalid inputs, boundary conditions).");
-  }
-  if (/state|status|transition/.test(lower) && !/transition/.test(lower)) {
-    inferred.push("Document the allowed state transitions explicitly (rather than implying them).");
-  }
-  if (
-    /(?:auth|token|secret|password|credential)/.test(lower) &&
-    !/(trust\s*bound|threat\s*model|attacker)/.test(lower)
-  ) {
-    inferred.push(
-      "Name the trust boundaries: what the system trusts the caller for vs what it independently verifies.",
-    );
-  }
-  return inferred;
-}
-
-/**
- * Ambiguity pass. Heuristic detectors for the most common authoring
- * mistakes the paper highlights: vague quantifiers ("some", "a few",
- * "maybe"), passive-voice subject elision ("it should be handled"),
- * and contradictory pairs detected by negation distance.
- *
- * Each resolved ambiguity gets recorded in `ambiguitiesResolved` so
- * the contract reviewer sees the substitution explicitly.
- */
-function ambiguityPass(draft: CompiledContract): CompiledContract {
-  const resolutions: AmbiguityResolution[] = [];
-  const VAGUE_RE = /\b(some|a few|several|maybe|possibly|might|perhaps)\b/gi;
-  const newRequirements: Requirement[] = [];
-  for (const req of draft.requirements) {
-    if (VAGUE_RE.test(req.text)) {
-      VAGUE_RE.lastIndex = 0;
-      const resolved = req.text.replace(VAGUE_RE, "[QUANTIFY]");
-      resolutions.push({
-        clause: req.id,
-        originalText: req.text,
-        resolution:
-          "Vague quantifier flagged; replaced with [QUANTIFY] placeholder. The contract reviewer must supply a number or remove the clause.",
-      });
-      newRequirements.push({ ...req, text: resolved });
-    } else {
-      newRequirements.push(req);
-    }
-  }
-  return {
-    ...draft,
-    requirements: newRequirements,
-    ambiguitiesResolved: resolutions,
-  };
-}
-
-/**
- * Render a CompiledContract back to a YAML-friendly fragment that can
- * be appended into a `crewhaus.yaml`'s `agent.instructions` field.
- * Strict — no host code, no env access, just string concatenation.
- */
-export function renderContract(c: CompiledContract): string {
-  const lines: string[] = [];
-  lines.push(`# Contract: ${c.title}`);
-  if (c.specialization !== undefined) {
-    lines.push(
-      `# Specialization: ${c.specialization.specialization.name} (confidence ${c.specialization.confidence.toFixed(2)})`,
-    );
-  }
-  lines.push("");
-  lines.push("## Requirements");
-  for (const r of c.requirements) {
-    lines.push(`- [${r.source}] ${r.text}`);
-  }
-  if (c.invariants.length > 0) {
-    lines.push("");
-    lines.push("## Invariants");
-    for (const inv of c.invariants) {
-      lines.push(`- [${inv.required ? "required" : "optional"}] ${inv.id}: ${inv.description}`);
-    }
-  }
-  if (c.outOfScope.length > 0) {
-    lines.push("");
-    lines.push("## Out of scope");
-    for (const oos of c.outOfScope) lines.push(`- ${oos}`);
-  }
-  if (c.ambiguitiesResolved.length > 0) {
-    lines.push("");
-    lines.push("## Ambiguities resolved");
-    for (const a of c.ambiguitiesResolved) {
-      lines.push(`- ${a.clause}: ${a.resolution}`);
-    }
-  }
-  return lines.join("\n");
-}