@isaacriehm/cairn-core 0.2.0 → 0.3.1

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

@@ -1,70 +0,0 @@
-/**
- * JSON Schema enforced by `claude --json-schema` for the decision-extractor
- * output. Mirrors `DecisionExtractorOutput` exactly.
- *
- * Assertion kinds match the production set in `src/ground/schemas.ts`. The
- * extractor's `parameters` is a free-form object; the cairn materializes
- * the assertion into the draft as-is and lets sensors validate at evaluation
- * time. Rejecting at extract time would block the operator's intent over
- * a malformed parameter the agent might still get right on the next pass.
- */
-export declare const DECISION_EXTRACTOR_OUTPUT_SCHEMA: {
-    readonly type: "object";
-    readonly additionalProperties: false;
-    readonly properties: {
-        readonly subject: {
-            readonly type: "string";
-            readonly minLength: 1;
-        };
-        readonly summary: {
-            readonly type: "string";
-            readonly minLength: 1;
-        };
-        readonly scope_globs: {
-            readonly type: "array";
-            readonly items: {
-                readonly type: "string";
-            };
-        };
-        readonly supersedes: {
-            readonly anyOf: readonly [{
-                readonly type: "string";
-                readonly pattern: "^DEC-\\d{4,}$";
-            }, {
-                readonly type: "null";
-            }];
-        };
-        readonly candidate_assertions: {
-            readonly type: "array";
-            readonly maxItems: 3;
-            readonly items: {
-                readonly type: "object";
-                readonly additionalProperties: false;
-                readonly properties: {
-                    readonly id: {
-                        readonly type: "string";
-                    };
-                    readonly kind: {
-                        readonly enum: readonly ["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"];
-                    };
-                    readonly description: {
-                        readonly type: "string";
-                        readonly minLength: 1;
-                    };
-                    readonly parameters: {
-                        readonly type: "object";
-                        readonly additionalProperties: true;
-                    };
-                };
-                readonly required: readonly ["kind", "description"];
-            };
-        };
-        readonly confidence_signal: {
-            readonly enum: readonly ["high", "medium", "low"];
-        };
-        readonly not_a_decision: {
-            readonly type: "boolean";
-        };
-    };
-    readonly required: readonly ["subject", "summary", "scope_globs", "candidate_assertions", "confidence_signal", "not_a_decision"];
-};

package/dist/decision-capture/schema.js

@@ -1,71 +0,0 @@
-/**
- * JSON Schema enforced by `claude --json-schema` for the decision-extractor
- * output. Mirrors `DecisionExtractorOutput` exactly.
- *
- * Assertion kinds match the production set in `src/ground/schemas.ts`. The
- * extractor's `parameters` is a free-form object; the cairn materializes
- * the assertion into the draft as-is and lets sensors validate at evaluation
- * time. Rejecting at extract time would block the operator's intent over
- * a malformed parameter the agent might still get right on the next pass.
- */
-export const DECISION_EXTRACTOR_OUTPUT_SCHEMA = {
-    type: "object",
-    additionalProperties: false,
-    properties: {
-        subject: { type: "string", minLength: 1 },
-        summary: { type: "string", minLength: 1 },
-        scope_globs: {
-            type: "array",
-            items: { type: "string" },
-        },
-        supersedes: {
-            anyOf: [
-                { type: "string", pattern: "^DEC-\\d{4,}$" },
-                { type: "null" },
-            ],
-        },
-        candidate_assertions: {
-            type: "array",
-            maxItems: 3,
-            items: {
-                type: "object",
-                additionalProperties: false,
-                properties: {
-                    id: { type: "string" },
-                    kind: {
-                        enum: [
-                            "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",
-                        ],
-                    },
-                    description: { type: "string", minLength: 1 },
-                    parameters: {
-                        type: "object",
-                        additionalProperties: true,
-                    },
-                },
-                required: ["kind", "description"],
-            },
-        },
-        confidence_signal: { enum: ["high", "medium", "low"] },
-        not_a_decision: { type: "boolean" },
-    },
-    required: [
-        "subject",
-        "summary",
-        "scope_globs",
-        "candidate_assertions",
-        "confidence_signal",
-        "not_a_decision",
-    ],
-};
-//# sourceMappingURL=schema.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/decision-capture/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG;IAC9C,IAAI,EAAE,QAAQ;IACd,oBAAoB,EAAE,KAAK;IAC3B,UAAU,EAAE;QACV,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE;QACzC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE;QACzC,WAAW,EAAE;YACX,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SAC1B;QACD,UAAU,EAAE;YACV,KAAK,EAAE;gBACL,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,eAAe,EAAE;gBAC5C,EAAE,IAAI,EAAE,MAAM,EAAE;aACjB;SACF;QACD,oBAAoB,EAAE;YACpB,IAAI,EAAE,OAAO;YACb,QAAQ,EAAE,CAAC;YACX,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,oBAAoB,EAAE,KAAK;gBAC3B,UAAU,EAAE;oBACV,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACtB,IAAI,EAAE;wBACJ,IAAI,EAAE;4BACJ,qBAAqB;4BACrB,iBAAiB;4BACjB,qBAAqB;4BACrB,kBAAkB;4BAClB,aAAa;4BACb,2BAA2B;4BAC3B,sBAAsB;4BACtB,uBAAuB;4BACvB,iBAAiB;4BACjB,0BAA0B;4BAC1B,mBAAmB;yBACpB;qBACF;oBACD,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE;oBAC7C,UAAU,EAAE;wBACV,IAAI,EAAE,QAAQ;wBACd,oBAAoB,EAAE,IAAI;qBAC3B;iBACF;gBACD,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,CAAC;aAClC;SACF;QACD,iBAAiB,EAAE,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE;QACtD,cAAc,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;KACpC;IACD,QAAQ,EAAE;QACR,SAAS;QACT,SAAS;QACT,aAAa;QACb,sBAAsB;QACtB,mBAAmB;QACnB,gBAAgB;KACjB;CACO,CAAC"}

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

@@ -1,201 +0,0 @@
-/**
- * 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

@@ -1,20 +0,0 @@
-/**
- * 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

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

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

@@ -1,90 +0,0 @@
-/**
- * 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;