@isaacriehm/cairn-core 0.1.0

package/dist/decision-capture/types.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Phase 14 — decision capture flow.
+ *
+ * Per WORKFLOW_GUIDE / L26 / L27 / INTEGRATION_PLAN §5 Phase 14:
+ *
+ *   /direction <text>  OR  free-text Tier-0 classified as `direction`
+ *   → Tier-1 decision-extractor produces structured candidate
+ *   → cairn writes draft to .cairn/ground/decisions/_inbox/DEC-NNNN.draft.md
+ *   → Discord prompt: 🟢 commit | 🟡 edit | 🔴 not-a-decision
+ *   → on 🟢: status:accepted, move to .cairn/ground/decisions/DEC-NNNN.md,
+ *            regenerate decisions.ledger.yaml; assertions become live
+ *   → on 🟡: leave draft + post correction prompt (re-run extractor on follow-up)
+ *   → on 🔴: discard draft (no record)
+ *
+ * The extractor is read-only (no file-write tools). The draft writer + the
+ * confirm flow are pure-mechanical. The only LLM call is the extractor;
+ * everything else is the cairn assembling state from the typed payload.
+ */
+import type { ClaudeTier } from "../claude/index.js";
+/** Assertion shape the extractor proposes — superset of DecisionAssertion kinds. */
+export interface CandidateAssertion {
+    /** Optional id; cairn fills in `<DEC-id>-A<N>` if absent. */
+    id?: string;
+    kind: "schema_must_contain" | "text_must_match" | "text_must_not_match" | "index_must_exist" | "ast_pattern" | "file_must_not_be_modified" | "query_must_filter_by" | "route_must_have_guard" | "event_must_emit" | "service_method_must_call" | "human_review_hint";
+    /** Free-form description of what the assertion enforces. */
+    description: string;
+    /**
+     * Inline assertion-specific knobs — typed loosely on this side because the
+     * extractor's output is best-effort. Sensors/Layer-D evaluate these against
+     * the diff at run time; malformed entries fail loud at evaluation, not here.
+     */
+    parameters?: Record<string, unknown>;
+}
+export interface DecisionExtractorOutput {
+    /** One-line subject — imperative voice. */
+    subject: string;
+    /** 2-4 sentence summary expanding the subject. */
+    summary: string;
+    /** Repo-relative globs the decision binds. May be empty. */
+    scope_globs: string[];
+    /**
+     * Existing decision id this one supersedes, when the operator's direction
+     * is explicitly a course-change. Format DEC-NNNN. Null/undefined when not
+     * applicable.
+     */
+    supersedes?: string | null;
+    /** 0-3 candidate assertions; cairn materializes them into the draft. */
+    candidate_assertions: CandidateAssertion[];
+    /** Extractor's confidence the input was a real direction. */
+    confidence_signal: "high" | "medium" | "low";
+    /**
+     * Set when the extractor decided the input was not a direction at all
+     * (rambling, off-topic, question-shaped). When true, the draft is NOT
+     * written; the caller treats it as a no-op.
+     */
+    not_a_decision: boolean;
+}
+export interface DecisionExtractorInput {
+    /** Raw operator text (slash-arg or free-text body). */
+    raw_text: string;
+    /** Operator id (for audit / decided_by frontmatter). */
+    author_id: string;
+    /** When the message was received. ISO timestamp. */
+    received_at: string;
+    /** Source channel/source for traceability. */
+    source: string;
+    /**
+     * Optional: existing accepted-decision summaries the extractor can cite for
+     * supersedes. Each item: `{id, title, scope_summary}`. Order: most recent
+     * first. Cap to ~10 per call to keep the prompt bounded.
+     */
+    accepted_decisions?: {
+        id: string;
+        title: string;
+        scope_summary: string;
+    }[];
+    /** Tier — default 1 (Haiku) per workflow.md `decision_extractor: 1`. */
+    tier: ClaudeTier;
+    /** Per-call timeout. Default 120_000 ms. */
+    timeout_ms?: number;
+}
+/** A draft written to `_inbox/`. Returned by writeDecisionDraft. */
+export interface DecisionDraft {
+    /** Allocated DEC-id. */
+    id: string;
+    /** Repo-relative path of the draft file. */
+    draft_path: string;
+    /** Path the draft will move to on accept. */
+    canonical_path: string;
+    /** Original extractor output (for confirmation rendering). */
+    output: DecisionExtractorOutput;
+    /** Raw direction text the operator submitted. */
+    raw_text: string;
+}
+/** Operator's verdict on a draft. */
+export type DraftConfirmDecision = "commit" | "edit" | "reject";
+export interface ConfirmResult {
+    decision: DraftConfirmDecision;
+    /** Set when decision="commit" — final canonical path of the accepted decision. */
+    accepted_path?: string;
+    /** Number of ledger entries after regenerate. */
+    ledger_size?: number;
+    /** Extractor's structured output preserved for downstream observers. */
+    draft?: DecisionDraft;
+    /** When decision="edit", operator-supplied correction text. */
+    correction?: string;
+    /** Extractor confidence. */
+    confidence?: "high" | "medium" | "low";
+}
+/** Aggregate result handed back from runDecisionCapture. */
+export interface DecisionCaptureResult {
+    /** True iff the extractor flagged not_a_decision and the flow short-circuited. */
+    short_circuited: boolean;
+    /** Set when the extractor produced a draft. */
+    draft?: DecisionDraft;
+    /** Set when the operator confirmed via the dialog. */
+    confirm?: ConfirmResult;
+    /**
+     * Set when refinement ran after a 🟢 commit. Absent on edit/reject paths,
+     * on bypassRefinement, or when the proposer call failed (the accept still
+     * succeeds in that case — refinement is best-effort).
+     */
+    refinement?: RefinementResult;
+    /** Total wall-clock time. */
+    duration_ms: number;
+}
+/**
+ * The Tier-1 proposer's per-candidate verdict on whether a strict
+ * `DecisionAssertion` shape can be formed and what it should contain.
+ *
+ * The proposer never decides what gets persisted — it just provides a
+ * recommendation. The operator's dialog choice determines what actually
+ * lands in the file. The runner re-validates each `strict_assertion`
+ * against the production `DecisionAssertion` zod before lifting; a
+ * proposal that fails zod is downgraded to `demote` automatically.
+ */
+export interface RefinementProposal {
+    /** Stable id of the candidate this proposal corresponds to (`<DEC-id>-A<NN>`). */
+    candidate_id: string;
+    /** Original loose kind from the candidate. */
+    candidate_kind: CandidateAssertion["kind"];
+    /**
+     * Proposer's verdict:
+     *   - `lift`    — confident strict shape; ready to promote into `assertions:`
+     *   - `demote`  — too vague to form mechanical params; convert to
+     *                 `human_review_hint` (always soft, always zod-valid)
+     *   - `skip`    — leave under `candidate_assertions:` for future refinement
+     */
+    status: "lift" | "demote" | "skip";
+    /** Proposer's confidence in its own recommendation. */
+    confidence_signal: "high" | "medium" | "low";
+    /**
+     * Strict params object the proposer recommends. SHAPE depends on
+     * `candidate_kind`. Validated against `DecisionAssertion` zod at apply
+     * time; an invalid shape forces auto-demote.
+     * Only set when status === "lift".
+     */
+    strict_assertion?: Record<string, unknown>;
+    /**
+     * Human-readable explanation rendered into the operator dialog.
+     * Always present so the operator can audit each proposal at confirm
+     * time without reading the raw JSON.
+     */
+    rationale: string;
+}
+/** Aggregate output of `proposeStrictAssertions`. */
+export interface RefinerOutput {
+    /** One proposal per candidate, in original order. */
+    proposals: RefinementProposal[];
+}
+export interface RefinerInput {
+    decision_id: string;
+    /** Decision's one-line subject (for prompt context). */
+    subject: string;
+    /** Decision's summary (for prompt context). */
+    summary: string;
+    /** Repo-relative globs the decision binds. */
+    scope_globs: string[];
+    /** Candidate assertions to refine. Order preserved on output. */
+    candidates: CandidateAssertion[];
+    /** Tier — default haiku. */
+    tier: ClaudeTier;
+    /** Per-call timeout. Default 120_000 ms. */
+    timeout_ms?: number;
+}
+/** Final outcome after operator dialog + lift. */
+export interface RefinementResult {
+    decision_id: string;
+    /** Proposals as returned by the proposer (pre-decision). */
+    proposals: RefinementProposal[];
+    /** Operator's choice id from the refinement dialog. */
+    operator_choice: "approve_all" | "approve_high_only" | "demote_all" | "skip";
+    /** Number of candidates lifted into `assertions:`. */
+    lifted_count: number;
+    /** Number of candidates demoted into `human_review_hint`. */
+    demoted_count: number;
+    /** Number of candidates kept under `candidate_assertions:`. */
+    skipped_count: number;
+    /** Set when the proposer threw or returned malformed output. */
+    proposer_failed?: boolean;
+}

package/dist/decision-capture/types.js

@@ -0,0 +1,20 @@
+/**
+ * Phase 14 — decision capture flow.
+ *
+ * Per WORKFLOW_GUIDE / L26 / L27 / INTEGRATION_PLAN §5 Phase 14:
+ *
+ *   /direction <text>  OR  free-text Tier-0 classified as `direction`
+ *   → Tier-1 decision-extractor produces structured candidate
+ *   → cairn writes draft to .cairn/ground/decisions/_inbox/DEC-NNNN.draft.md
+ *   → Discord prompt: 🟢 commit | 🟡 edit | 🔴 not-a-decision
+ *   → on 🟢: status:accepted, move to .cairn/ground/decisions/DEC-NNNN.md,
+ *            regenerate decisions.ledger.yaml; assertions become live
+ *   → on 🟡: leave draft + post correction prompt (re-run extractor on follow-up)
+ *   → on 🔴: discard draft (no record)
+ *
+ * The extractor is read-only (no file-write tools). The draft writer + the
+ * confirm flow are pure-mechanical. The only LLM call is the extractor;
+ * everything else is the cairn assembling state from the typed payload.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/decision-capture/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/decision-capture/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/decision-capture/writer.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Draft writer + confirm-side persistence.
+ *
+ * `writeDecisionDraft` materializes the extractor output into
+ * `.cairn/ground/decisions/_inbox/<DEC-id>.draft.md`. Frontmatter
+ * conforms to `DecisionFrontmatter` (status: "draft").
+ *
+ * `acceptDraft` moves the draft to its canonical path with status flipped
+ * to "accepted" and triggers a ledger regenerate.
+ *
+ * `rejectDraft` removes the draft file entirely. The id remains burned —
+ * `allocateDecisionId` always returns mark+1, so a rejected DEC-NNNN never
+ * gets reissued (per monotonic-id principle, single source in decision-capture/id.ts).
+ */
+import type { DecisionDraft, DecisionExtractorOutput } from "./types.js";
+export interface WriteDecisionDraftArgs {
+    repoRoot: string;
+    id: string;
+    output: DecisionExtractorOutput;
+    rawText: string;
+    authorId: string;
+    receivedAt: string;
+    source: string;
+}
+export declare function writeDecisionDraft(args: WriteDecisionDraftArgs): DecisionDraft;
+export interface AcceptDraftResult {
+    acceptedPath: string;
+    ledgerSize: number;
+    ledgerPath: string;
+}
+/**
+ * Move a draft to the canonical decisions/ dir, flip status:draft → accepted,
+ * then regenerate the decisions ledger so accepted assertions become live.
+ *
+ * If a `supersedes` link exists, this also stamps `superseded_by` on the
+ * referenced decision (when the file is present). Best-effort — a missing
+ * referent doesn't block acceptance.
+ */
+export declare function acceptDraft(args: {
+    repoRoot: string;
+    draft: DecisionDraft;
+}): AcceptDraftResult;
+/**
+ * Discard a draft. The DEC-id is NOT recycled — the allocator advances
+ * past every existing DEC-NNNN.* file. Per the monotonic-id rule, even
+ * rejected drafts burn their id, so we leave a tombstone at
+ * `_inbox/<DEC-id>.rejected.md` rather than deleting outright. The
+ * tombstone has `status: rejected` and is excluded from the ledger by
+ * the existing `status === "accepted"` filter.
+ */
+export declare function rejectDraft(args: {
+    repoRoot: string;
+    draft: DecisionDraft;
+}): void;
+export interface LiftVerdict {
+    candidate_id: string;
+    status: "lift" | "demote" | "skip";
+    /** Strict assertion params (without id/kind — writer injects them). */
+    strict_assertion?: Record<string, unknown>;
+    /** Original candidate kind (carried onto lifted assertion). */
+    candidate_kind: "schema_must_contain" | "text_must_match" | "text_must_not_match" | "index_must_exist" | "ast_pattern" | "file_must_not_be_modified" | "query_must_filter_by" | "route_must_have_guard" | "event_must_emit" | "service_method_must_call" | "human_review_hint";
+    /** Original candidate description (used when demoted to human_review_hint). */
+    candidate_description: string;
+}
+export interface LiftResult {
+    decision_id: string;
+    decision_path: string;
+    lifted_count: number;
+    demoted_count: number;
+    skipped_count: number;
+    ledger_size: number;
+}
+/**
+ * Apply per-candidate verdicts to an accepted decision file.
+ *
+ * For each verdict:
+ *   - status="lift"   → strict_assertion (with id/kind injected) lands in
+ *                       frontmatter `assertions:`
+ *   - status="demote" → a `{kind: human_review_hint, description}` assertion
+ *                       lands in `assertions:` (always soft, always zod-valid)
+ *   - status="skip"   → original candidate stays under `candidate_assertions:`
+ *
+ * Then regenerates the decisions ledger so the new strict assertions are
+ * visible to Layer-D sensors on the next run.
+ */
+export declare function liftCandidatesToAssertions(args: {
+    repoRoot: string;
+    decisionId: string;
+    verdicts: LiftVerdict[];
+}): LiftResult;

package/dist/decision-capture/writer.js

@@ -0,0 +1,267 @@
+/**
+ * Draft writer + confirm-side persistence.
+ *
+ * `writeDecisionDraft` materializes the extractor output into
+ * `.cairn/ground/decisions/_inbox/<DEC-id>.draft.md`. Frontmatter
+ * conforms to `DecisionFrontmatter` (status: "draft").
+ *
+ * `acceptDraft` moves the draft to its canonical path with status flipped
+ * to "accepted" and triggers a ledger regenerate.
+ *
+ * `rejectDraft` removes the draft file entirely. The id remains burned —
+ * `allocateDecisionId` always returns mark+1, so a rejected DEC-NNNN never
+ * gets reissued (per monotonic-id principle, single source in decision-capture/id.ts).
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { decisionsDir, decisionsLedgerPath } from "../ground/paths.js";
+import { writeDecisionsLedger } from "../ground/ledgers.js";
+import { parseFrontmatter } from "../ground/frontmatter.js";
+export function writeDecisionDraft(args) {
+    const dir = decisionsDir(args.repoRoot);
+    const inboxDir = join(dir, "_inbox");
+    mkdirSync(inboxDir, { recursive: true });
+    const draftFilename = `${args.id}.draft.md`;
+    const canonicalFilename = `${args.id}.md`;
+    const draftAbs = join(inboxDir, draftFilename);
+    const canonicalAbs = join(dir, canonicalFilename);
+    const draftRel = `.cairn/ground/decisions/_inbox/${draftFilename}`;
+    const canonicalRel = `.cairn/ground/decisions/${canonicalFilename}`;
+    const now = new Date().toISOString();
+    // candidate_assertions are PROPOSALS — schema-loose. They live under
+    // `candidate_assertions:` in the frontmatter (passthrough), NOT under
+    // `assertions:` which DecisionFrontmatter validates strictly. A future
+    // refinement step (Phase 14.x) lifts candidates into the strict
+    // `assertions:` form once parameters are filled in. Until then the
+    // ledger ignores them and Layer-D sensors don't enforce them.
+    const candidateAssertions = args.output.candidate_assertions.map((a, idx) => {
+        const id = a.id ?? `${args.id}-A${(idx + 1).toString().padStart(2, "0")}`;
+        return {
+            id,
+            kind: a.kind,
+            description: a.description,
+            ...(a.parameters !== undefined ? { parameters: a.parameters } : {}),
+        };
+    });
+    const frontmatter = {
+        id: args.id,
+        title: args.output.subject,
+        type: "adr",
+        status: "draft",
+        audience: "dual",
+        generated: now,
+        "verified-at": now,
+        decided_at: args.receivedAt,
+        decided_by: args.authorId,
+        ...(args.output.scope_globs.length > 0 ? { scope_globs: args.output.scope_globs } : {}),
+        ...(args.output.supersedes ? { supersedes: args.output.supersedes } : {}),
+        ...(candidateAssertions.length > 0
+            ? { candidate_assertions: candidateAssertions }
+            : {}),
+        capture_source: args.source,
+        capture_confidence: args.output.confidence_signal,
+    };
+    const yaml = stringifyYaml(frontmatter);
+    const body = composeDraftBody(args);
+    const fileContent = `---\n${yaml}---\n\n${body}\n`;
+    writeFileSync(draftAbs, fileContent, "utf8");
+    return {
+        id: args.id,
+        draft_path: draftRel,
+        canonical_path: canonicalRel,
+        output: args.output,
+        raw_text: args.rawText,
+    };
+}
+function composeDraftBody(args) {
+    const lines = [];
+    lines.push(`# ${args.id} — ${args.output.subject}`);
+    lines.push("");
+    lines.push("## Summary");
+    lines.push(args.output.summary.trim());
+    lines.push("");
+    lines.push("## Original direction");
+    lines.push("```");
+    lines.push(args.rawText.trim());
+    lines.push("```");
+    lines.push("");
+    if (args.output.scope_globs.length > 0) {
+        lines.push("## Scope");
+        for (const g of args.output.scope_globs)
+            lines.push(`- \`${g}\``);
+        lines.push("");
+    }
+    if (args.output.candidate_assertions.length > 0) {
+        lines.push("## Candidate assertions");
+        for (const a of args.output.candidate_assertions) {
+            lines.push(`- **${a.kind}** — ${a.description}`);
+        }
+        lines.push("");
+    }
+    if (args.output.supersedes) {
+        lines.push(`## Supersedes`);
+        lines.push(`- ${args.output.supersedes}`);
+        lines.push("");
+    }
+    lines.push(`_Confidence: ${args.output.confidence_signal}. This is a DRAFT — pending operator confirmation via Discord._`);
+    return lines.join("\n");
+}
+/**
+ * Move a draft to the canonical decisions/ dir, flip status:draft → accepted,
+ * then regenerate the decisions ledger so accepted assertions become live.
+ *
+ * If a `supersedes` link exists, this also stamps `superseded_by` on the
+ * referenced decision (when the file is present). Best-effort — a missing
+ * referent doesn't block acceptance.
+ */
+export function acceptDraft(args) {
+    const draftAbs = join(args.repoRoot, args.draft.draft_path);
+    const canonicalAbs = join(args.repoRoot, args.draft.canonical_path);
+    const original = readFileSync(draftAbs, "utf8");
+    const flipped = original.replace(/^status:\s*draft\s*$/m, "status: accepted");
+    mkdirSync(dirname(canonicalAbs), { recursive: true });
+    writeFileSync(canonicalAbs, flipped, "utf8");
+    rmSync(draftAbs, { force: true });
+    if (args.draft.output.supersedes) {
+        stampSupersededBy({
+            repoRoot: args.repoRoot,
+            supersededId: args.draft.output.supersedes,
+            supersedingId: args.draft.id,
+        });
+    }
+    const ledger = writeDecisionsLedger({ repoRoot: args.repoRoot });
+    return {
+        acceptedPath: args.draft.canonical_path,
+        ledgerSize: ledger.entries.length,
+        ledgerPath: decisionsLedgerPath(args.repoRoot).replace(args.repoRoot + "/", ""),
+    };
+}
+/**
+ * Discard a draft. The DEC-id is NOT recycled — the allocator advances
+ * past every existing DEC-NNNN.* file. Per the monotonic-id rule, even
+ * rejected drafts burn their id, so we leave a tombstone at
+ * `_inbox/<DEC-id>.rejected.md` rather than deleting outright. The
+ * tombstone has `status: rejected` and is excluded from the ledger by
+ * the existing `status === "accepted"` filter.
+ */
+export function rejectDraft(args) {
+    const draftAbs = join(args.repoRoot, args.draft.draft_path);
+    if (!existsSync(draftAbs))
+        return;
+    const original = readFileSync(draftAbs, "utf8");
+    const tombstone = original.replace(/^status:\s*draft\s*$/m, "status: rejected");
+    const tombstoneRel = args.draft.draft_path.replace(/\.draft\.md$/, ".rejected.md");
+    const tombstoneAbs = join(args.repoRoot, tombstoneRel);
+    writeFileSync(tombstoneAbs, tombstone, "utf8");
+    rmSync(draftAbs, { force: true });
+}
+function stampSupersededBy(args) {
+    const target = join(decisionsDir(args.repoRoot), `${args.supersededId}.md`);
+    if (!existsSync(target))
+        return;
+    const original = readFileSync(target, "utf8");
+    // Inject `superseded_by:` into the frontmatter block if not already present.
+    if (/^superseded_by:/m.test(original))
+        return;
+    const fenceEnd = original.indexOf("\n---", 3);
+    if (fenceEnd === -1)
+        return;
+    const fenceText = original.slice(0, fenceEnd);
+    const restText = original.slice(fenceEnd);
+    const updated = `${fenceText}\nsuperseded_by: ${args.supersedingId}${restText}`;
+    writeFileSync(target, updated, "utf8");
+}
+/**
+ * Apply per-candidate verdicts to an accepted decision file.
+ *
+ * For each verdict:
+ *   - status="lift"   → strict_assertion (with id/kind injected) lands in
+ *                       frontmatter `assertions:`
+ *   - status="demote" → a `{kind: human_review_hint, description}` assertion
+ *                       lands in `assertions:` (always soft, always zod-valid)
+ *   - status="skip"   → original candidate stays under `candidate_assertions:`
+ *
+ * Then regenerates the decisions ledger so the new strict assertions are
+ * visible to Layer-D sensors on the next run.
+ */
+export function liftCandidatesToAssertions(args) {
+    const decisionRel = `.cairn/ground/decisions/${args.decisionId}.md`;
+    const decisionAbs = join(args.repoRoot, decisionRel);
+    if (!existsSync(decisionAbs)) {
+        throw new Error(`liftCandidatesToAssertions: decision file missing at ${decisionRel}`);
+    }
+    const original = readFileSync(decisionAbs, "utf8");
+    const parsed = parseFrontmatter(original);
+    const fmRaw = parsed.raw.length > 0 ? parseYaml(parsed.raw) : {};
+    const existingAssertions = Array.isArray(fmRaw["assertions"])
+        ? fmRaw["assertions"].slice()
+        : [];
+    const existingCandidates = Array.isArray(fmRaw["candidate_assertions"])
+        ? fmRaw["candidate_assertions"].slice()
+        : [];
+    let liftedCount = 0;
+    let demotedCount = 0;
+    let skippedCount = 0;
+    const newAssertions = [...existingAssertions];
+    const liftedIds = new Set();
+    const demotedIds = new Set();
+    const skippedIds = new Set();
+    for (const v of args.verdicts) {
+        if (v.status === "lift" && v.strict_assertion !== undefined) {
+            newAssertions.push({
+                id: v.candidate_id,
+                kind: v.candidate_kind,
+                ...v.strict_assertion,
+            });
+            liftedIds.add(v.candidate_id);
+            liftedCount++;
+            continue;
+        }
+        if (v.status === "demote") {
+            newAssertions.push({
+                id: v.candidate_id,
+                kind: "human_review_hint",
+                description: v.candidate_description,
+            });
+            demotedIds.add(v.candidate_id);
+            demotedCount++;
+            continue;
+        }
+        skippedIds.add(v.candidate_id);
+        skippedCount++;
+    }
+    const remainingCandidates = existingCandidates.filter((c) => {
+        const id = typeof c["id"] === "string" ? c["id"] : "";
+        return !liftedIds.has(id) && !demotedIds.has(id);
+    });
+    // Build the new frontmatter object preserving every existing field, just
+    // updating assertions: + candidate_assertions: + verified-at.
+    const newFm = { ...fmRaw };
+    if (newAssertions.length > 0) {
+        newFm["assertions"] = newAssertions;
+    }
+    else {
+        delete newFm["assertions"];
+    }
+    if (remainingCandidates.length > 0) {
+        newFm["candidate_assertions"] = remainingCandidates;
+    }
+    else {
+        delete newFm["candidate_assertions"];
+    }
+    newFm["verified-at"] = new Date().toISOString();
+    const newYaml = stringifyYaml(newFm);
+    const newContent = `---\n${newYaml}---\n${parsed.body.startsWith("\n") ? "" : "\n"}${parsed.body}`;
+    writeFileSync(decisionAbs, newContent, "utf8");
+    const ledger = writeDecisionsLedger({ repoRoot: args.repoRoot });
+    return {
+        decision_id: args.decisionId,
+        decision_path: decisionRel,
+        lifted_count: liftedCount,
+        demoted_count: demotedCount,
+        skipped_count: skippedCount,
+        ledger_size: ledger.entries.length,
+    };
+}
+//# sourceMappingURL=writer.js.map

package/dist/decision-capture/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../src/decision-capture/writer.ts"],"names":[],"mappings":"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"}

package/dist/doctor/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `cairn doctor` — verify the adoption is healthy.
+ *
+ * Pure filesystem reads + a status.json check. No LLM. No subprocess fan-out.
+ * Returns a structured `DoctorReport` the CLI renders. Exit-code mapping:
+ *   0 — all checks pass
+ *   1 — at least one error (missing core file, broken layout)
+ *   2 — at least one warning (drafty brand, empty scope, daemon not running, …)
+ *
+ * Spec: BUILD_REPORT.md "Task D — cairn doctor command".
+ */
+export type DoctorStatus = "ok" | "warn" | "error" | "info";
+export interface DoctorCheck {
+    group: "core" | "ground" | "sensors";
+    /** Short label rendered in the report. */
+    label: string;
+    status: DoctorStatus;
+    /** One-line detail rendered next to the icon. */
+    detail: string;
+    /** When non-null, the exact command the operator can run to fix this. */
+    fixCommand?: string;
+}
+export interface DoctorReport {
+    projectName: string;
+    repoRoot: string;
+    checks: DoctorCheck[];
+    errors: number;
+    warnings: number;
+}
+export interface RunDoctorOptions {
+    repoRoot: string;
+}
+export declare function runDoctor(opts: RunDoctorOptions): DoctorReport;
+export interface RunFixOptions {
+    repoRoot: string;
+    /** Inject a non-default scope-rebuild handler — used by smokes. */
+    rebuildScopeIndexFn?: (repoRoot: string) => Promise<{
+        filesClassified: number;
+    }>;
+}
+export interface FixReport {
+    appliedFixes: string[];
+    manualFixes: {
+        check: string;
+        command: string | null;
+    }[];
+}
+export declare function runFix(opts: RunFixOptions): Promise<FixReport>;