dorfl 0.0.0 → 0.1.0

package/dist/buildable-body.js

@@ -0,0 +1,131 @@
+/**
+ * The SINGLE owner of the buildable-task (and PRD-body) markdown SECTION SCHEMA
+ * (prd `centralize-buildable-task-renderer-shared-by-intake-and-promotion`, US
+ * #1/#4/#7). dorfl has TWO independent producers of a buildable task/PRD body —
+ * `intake.ts` (`renderBacklogTask`/`renderSpec`, a wrapper+fallback) and
+ * `triage-persist.ts` (`buildPromotedBody`, a structured renderer) — and until
+ * this module they each HAND-ROLLED the `## What to build` / `## Acceptance
+ * criteria` / `## Open questions` / `## Prompt` skeleton, so the schema could (and
+ * did) DRIFT apart silently (the promptless-promotion stuck-lock bug, see the
+ * origin observation
+ * `advance-promotion-builds-promptless-task-that-self-claims-stuck-2026-06-25`).
+ *
+ * This module renders only the BODY (the markdown AFTER the frontmatter fence) —
+ * the part both producers actually share. Each producer keeps its OWN frontmatter
+ * writer (intake stamps `issue:`/`originTrust:`; promotion stamps `needsAnswers:`/
+ * `blockedBy:`) and its OWN writer/integration mode (intake's branch+PR front
+ * door; promotion's triage-local CAS create) — only the section skeleton is
+ * centralized here.
+ *
+ * The two producers are ASYMMETRIC, and that asymmetry is expressed by the
+ * renderer's inputs rather than by two divergent bodies:
+ *
+ *   - intake's DEFAULT-SCAFFOLD skeleton (used ONLY when the intake agent drafted
+ *     no body) is `## What to build` + `## Acceptance criteria` + a thin default
+ *     `## Prompt`. Reproduced by passing all three.
+ *   - promotion's structured body is `## What to build` (the mechanism prose) +
+ *     optional `## Open questions` + a `## Prompt` seeded (blockquoted) from the
+ *     mechanism prose, and NO `## Acceptance criteria`. Reproduced by omitting
+ *     `acceptanceCriteria` and passing the open-questions block + the seed prose.
+ *
+ * Symmetrically, {@link renderSpecBody} owns the FULL PRD section schema both PRD
+ * producers need: intake's default PRD scaffold is `## Problem Statement` +
+ * `## Solution` + `## User Stories` (reproduced by passing all three), while
+ * promotion's structured PRD body is `## Problem Statement` + optional
+ * `## Open questions` (reproduced by omitting `solution`/`userStories`). Each
+ * optional section is emitted only when its input is non-empty.
+ *
+ * `## Prompt` is TASK-ONLY: a PRD is not dispatched by `do`/`run`, so a PRD body
+ * carries none (the symmetric reason the task body MUST carry one — the consumer
+ * `extractPromptSection`/`resolveTask` in `prompt.ts` throws "has no '## Prompt'
+ * section" at dispatch time without it). {@link renderTaskBody} always emits a
+ * `## Prompt`; {@link renderSpecBody} never does.
+ *
+ * NOTE (extract-only): this module is a PURE ADDITION. Neither producer is rewired
+ * here — that is the two follow-on tasks (kept file-orthogonal so each proves its
+ * own output is byte-for-byte preserved). This task lands the renderer + its
+ * golden-shape test ONLY.
+ */
+/** Blockquote a prompt SEED: each line gets a `> ` prefix (blank lines → `>`). */
+function blockquote(seed) {
+    return seed
+        .split('\n')
+        .map((line) => (line === '' ? '>' : `> ${line}`))
+        .join('\n');
+}
+/**
+ * Render a buildable TASK body (the markdown AFTER the frontmatter fence). Emits,
+ * in order: `## What to build`, `## Acceptance criteria` (only when given),
+ * `## Open questions` (only when given), and ALWAYS `## Prompt` (blockquoted).
+ *
+ * The output passes `extractPromptSection`/`resolveTask` without the
+ * "has no '## Prompt' section" throw, because `## Prompt` is unconditional and
+ * never empty. The caller wraps this body with its own frontmatter.
+ *
+ * FENCE↔HEADING BOUNDARY: this renderer starts at its first heading with NO
+ * leading blank line — the caller's frontmatter serializer owns the single blank
+ * line between the closing `---` fence and this first heading (ratified in
+ * `docs/adr/frontmatter-owns-fence-to-heading-blank-line.md`). Do NOT add a
+ * leading blank here; that would reintroduce the fence-spacing drift class.
+ */
+export function renderTaskBody(input) {
+    const lines = [
+        '## What to build',
+        '',
+        input.whatToBuild.trim() === ''
+            ? '(no `## What to build` prose was supplied.)'
+            : input.whatToBuild.trim(),
+        '',
+    ];
+    const acceptance = (input.acceptanceCriteria ?? '').trim();
+    if (acceptance !== '') {
+        lines.push('## Acceptance criteria', '', acceptance, '');
+    }
+    const openQuestions = (input.openQuestions ?? '').trim();
+    if (openQuestions !== '') {
+        lines.push('## Open questions', '', openQuestions, '');
+    }
+    const seed = input.prompt.trim() === ''
+        ? 'Build the task described above.'
+        : input.prompt.trim();
+    lines.push('## Prompt', '', blockquote(seed), '');
+    return lines.join('\n');
+}
+/**
+ * Render a PRD body (the markdown AFTER the frontmatter fence). Emits, in the
+ * canonical order, `## Problem Statement`, then `## Solution`, `## User Stories`,
+ * and `## Open questions` (each only when its input is given), and NEVER a
+ * `## Prompt` — a PRD is a north-star doc, not a dispatchable task. The symmetric twin of
+ * {@link renderTaskBody}, owning the FULL SPEC section schema both producers need
+ * (intake's default scaffold supplies Problem Statement + Solution + User Stories;
+ * promotion's structured body supplies Problem Statement + optional Open
+ * questions) so the two artifact shapes cannot drift apart.
+ *
+ * FENCE↔HEADING BOUNDARY: same convention as {@link renderTaskBody} — no leading
+ * blank; the frontmatter serializer owns the `\n\n` after the closing `---` fence
+ * (see `docs/adr/frontmatter-owns-fence-to-heading-blank-line.md`).
+ */
+export function renderSpecBody(input) {
+    const lines = [
+        '## Problem Statement',
+        '',
+        input.problemStatement.trim() === ''
+            ? '(no `## Problem Statement` prose was supplied.)'
+            : input.problemStatement.trim(),
+        '',
+    ];
+    const solution = (input.solution ?? '').trim();
+    if (solution !== '') {
+        lines.push('## Solution', '', solution, '');
+    }
+    const userStories = (input.userStories ?? '').trim();
+    if (userStories !== '') {
+        lines.push('## User Stories', '', userStories, '');
+    }
+    const openQuestions = (input.openQuestions ?? '').trim();
+    if (openQuestions !== '') {
+        lines.push('## Open questions', '', openQuestions, '');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=buildable-body.js.map

package/dist/buildable-body.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildable-body.js","sourceRoot":"","sources":["../src/buildable-body.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,kFAAkF;AAClF,SAAS,UAAU,CAAC,IAAY;IAC/B,OAAO,IAAI;SACT,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;SAChD,IAAI,CAAC,IAAI,CAAC,CAAC;AACd,CAAC;AA8BD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAC,KAA0B;IACxD,MAAM,KAAK,GAAa;QACvB,kBAAkB;QAClB,EAAE;QACF,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE;YAC9B,CAAC,CAAC,6CAA6C;YAC/C,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE;QAC3B,EAAE;KACF,CAAC;IAEF,MAAM,UAAU,GAAG,CAAC,KAAK,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3D,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,wBAAwB,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,aAAa,GAAG,CAAC,KAAK,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACzD,IAAI,aAAa,KAAK,EAAE,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,MAAM,IAAI,GACT,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE;QACzB,CAAC,CAAC,iCAAiC;QACnC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACxB,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAElD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AA4BD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,KAA0B;IACxD,MAAM,KAAK,GAAa;QACvB,sBAAsB;QACtB,EAAE;QACF,KAAK,CAAC,gBAAgB,CAAC,IAAI,EAAE,KAAK,EAAE;YACnC,CAAC,CAAC,iDAAiD;YACnD,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,IAAI,EAAE;QAChC,EAAE;KACF,CAAC;IAEF,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/C,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,WAAW,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACrD,IAAI,WAAW,KAAK,EAAE,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,aAAa,GAAG,CAAC,KAAK,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACzD,IAAI,aAAa,KAAK,EAAE,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC"}

package/dist/categorise.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure categorisation of backlog items into the "who can take it" groups used by
+ * the human decision dashboard. Grouping is deliberately INDEPENDENT of the
+ * repo's `autoBuild` policy: a human always sees the full picture, and the
+ * policy only changes the eligibility *verdict* / summary counts elsewhere —
+ * never which group an item lands in.
+ */
+import type { ScannedItem } from './scan.js';
+/**
+ * Which group an item belongs to, derived from its two autonomy axes
+ * (`humanOnly`, `needsAnswers`) and its dependency readiness (NOT the runner's
+ * `autoBuild` policy):
+ *   - `agent-claimable` — neither axis gated AND deps satisfied: an agent can
+ *     claim it now (provided this repo's `autoBuild` policy is on).
+ *   - `human-only` — `humanOnly: true`: a human decides/builds it; an agent never
+ *     claims it, regardless of policy or deps.
+ *   - `needs-answers` — not `humanOnly` but `needsAnswers: true`: open questions
+ *     block autonomous work until they are answered (the questions live in the
+ *     body); an agent never claims it.
+ *   - `blocked` — neither axis gated but deps unsatisfied: would be
+ *     agent-claimable once its blockers reach `work/done/`.
+ *
+ * `humanOnly` takes precedence over `needsAnswers` for display grouping (a single
+ * group per item), but BOTH gate the agent identically in `eligibility`.
+ */
+export type Category = 'agent-claimable' | 'human-only' | 'needs-answers' | 'blocked';
+/** Stable display order for the four groups. */
+export declare const CATEGORY_ORDER: Category[];
+/** Human-facing section headings for each group. */
+export declare const CATEGORY_LABELS: Record<Category, string>;
+/** A scanned item, classified for the dashboard. */
+export interface CategorisedItem {
+    item: ScannedItem;
+    category: Category;
+    /** Whether its `blockedBy` deps are all satisfied (ready to be picked up). */
+    ready: boolean;
+}
+/**
+ * Map an item's autonomy axes (`humanOnly`, `needsAnswers`) + dependency
+ * readiness to its dashboard category. Policy-independent by design: the
+ * category reflects what the author declared and whether its deps are met, not
+ * the runner's `autoBuild` policy. `humanOnly` is shown before `needsAnswers`
+ * when both are set, so the REASON is always visible.
+ */
+export declare function categoriseItem(item: ScannedItem): CategorisedItem;
+/** The items of one repo, bucketed by category and sorted ready-first. */
+export type CategorisedGroups = Record<Category, CategorisedItem[]>;
+/**
+ * Bucket a repo's scanned items into the three groups. Within each group, ready
+ * (deps-satisfied) items sort above blocked ones; ties keep the incoming order
+ * (the scan core already sorts items by slug), so the result is deterministic.
+ */
+export declare function categoriseItems(items: ScannedItem[]): CategorisedGroups;
+/** Stable sort placing ready items before blocked ones, preserving order otherwise. */
+export declare function sortReadyFirst(items: CategorisedItem[]): CategorisedItem[];
+/** Per-category and readiness tallies for the dashboard summary. */
+export interface CategorySummary {
+    agentClaimable: number;
+    humanOnly: number;
+    needsAnswers: number;
+    blocked: number;
+    ready: number;
+}
+/** Aggregate counts across every repo's groups for the summary line. */
+export declare function summariseGroups(allGroups: CategorisedGroups[]): CategorySummary;
+//# sourceMappingURL=categorise.d.ts.map

package/dist/categorise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"categorise.d.ts","sourceRoot":"","sources":["../src/categorise.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,WAAW,CAAC;AAE3C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,QAAQ,GACjB,iBAAiB,GACjB,YAAY,GACZ,eAAe,GACf,SAAS,CAAC;AAEb,gDAAgD;AAChD,eAAO,MAAM,cAAc,EAAE,QAAQ,EAKpC,CAAC;AAEF,oDAAoD;AACpD,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAOpD,CAAC;AAEF,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,8EAA8E;IAC9E,KAAK,EAAE,OAAO,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,eAAe,CAajE;AAED,0EAA0E;AAC1E,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,QAAQ,EAAE,eAAe,EAAE,CAAC,CAAC;AAWpE;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,iBAAiB,CAUvE;AAED,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAU1E;AAED,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACd;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAC9B,SAAS,EAAE,iBAAiB,EAAE,GAC5B,eAAe,CAsBjB"}

package/dist/categorise.js

@@ -0,0 +1,106 @@
+/**
+ * Pure categorisation of backlog items into the "who can take it" groups used by
+ * the human decision dashboard. Grouping is deliberately INDEPENDENT of the
+ * repo's `autoBuild` policy: a human always sees the full picture, and the
+ * policy only changes the eligibility *verdict* / summary counts elsewhere —
+ * never which group an item lands in.
+ */
+/** Stable display order for the four groups. */
+export const CATEGORY_ORDER = [
+    'agent-claimable',
+    'human-only',
+    'needs-answers',
+    'blocked',
+];
+/** Human-facing section headings for each group. */
+export const CATEGORY_LABELS = {
+    'agent-claimable': 'Agent-claimable now (not human-only, no open questions, deps satisfied; needs --auto-build)',
+    'human-only': 'Human-only (humanOnly: true — a human decides/builds)',
+    'needs-answers': 'Needs answers (needsAnswers: true — open questions block autonomous work)',
+    blocked: 'Blocked (not gated, waiting on deps)',
+};
+/**
+ * Map an item's autonomy axes (`humanOnly`, `needsAnswers`) + dependency
+ * readiness to its dashboard category. Policy-independent by design: the
+ * category reflects what the author declared and whether its deps are met, not
+ * the runner's `autoBuild` policy. `humanOnly` is shown before `needsAnswers`
+ * when both are set, so the REASON is always visible.
+ */
+export function categoriseItem(item) {
+    const ready = item.eligibility.blockedBy.satisfied;
+    let category;
+    if (item.humanOnly === true) {
+        category = 'human-only';
+    }
+    else if (item.needsAnswers === true) {
+        category = 'needs-answers';
+    }
+    else if (ready) {
+        category = 'agent-claimable';
+    }
+    else {
+        category = 'blocked';
+    }
+    return { item, category, ready };
+}
+function emptyGroups() {
+    return {
+        'agent-claimable': [],
+        'human-only': [],
+        'needs-answers': [],
+        blocked: [],
+    };
+}
+/**
+ * Bucket a repo's scanned items into the three groups. Within each group, ready
+ * (deps-satisfied) items sort above blocked ones; ties keep the incoming order
+ * (the scan core already sorts items by slug), so the result is deterministic.
+ */
+export function categoriseItems(items) {
+    const groups = emptyGroups();
+    for (const item of items) {
+        const categorised = categoriseItem(item);
+        groups[categorised.category].push(categorised);
+    }
+    for (const category of CATEGORY_ORDER) {
+        groups[category] = sortReadyFirst(groups[category]);
+    }
+    return groups;
+}
+/** Stable sort placing ready items before blocked ones, preserving order otherwise. */
+export function sortReadyFirst(items) {
+    return items
+        .map((value, index) => ({ value, index }))
+        .sort((a, b) => {
+        if (a.value.ready !== b.value.ready) {
+            return a.value.ready ? -1 : 1;
+        }
+        return a.index - b.index;
+    })
+        .map((entry) => entry.value);
+}
+/** Aggregate counts across every repo's groups for the summary line. */
+export function summariseGroups(allGroups) {
+    const summary = {
+        agentClaimable: 0,
+        humanOnly: 0,
+        needsAnswers: 0,
+        blocked: 0,
+        ready: 0,
+    };
+    for (const groups of allGroups) {
+        summary.agentClaimable += groups['agent-claimable'].length;
+        summary.humanOnly += groups['human-only'].length;
+        summary.needsAnswers += groups['needs-answers'].length;
+        summary.blocked += groups['blocked'].length;
+        for (const category of CATEGORY_ORDER) {
+            for (const entry of groups[category]) {
+                if (entry.ready) {
+                    summary.ready++;
+                }
+            }
+        }
+    }
+    return summary;
+}
+//# sourceMappingURL=categorise.js.map

package/dist/categorise.js.map

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

package/dist/claim-cas.d.ts

@@ -0,0 +1,117 @@
+/**
+ * In-process TypeScript implementation of the atomic compare-and-swap claim from
+ * `scripts/CLAIM-PROTOCOL.md`. This is the first-class `dorfl claim`
+ * command (ADR §9: dorfl is the PRIMARY implementation of the claim
+ * protocol; `scripts/claim.sh` is retained as the portable, zero-dependency
+ * bootstrap / reference). The lock-substrate cut-over (prd
+ * `ledger-status-per-item-lock-refs`) has since diverged it from `claim.sh`'s
+ * body-move semantics — see the lock note below — but the exit codes are the same.
+ *
+ * It is async (each git call is a non-blocking `runAsync`) so two awaited claims
+ * over the same slug genuinely race — the arbiter's per-item-ref CAS (not test
+ * ordering) picks the single winner.
+ *
+ * Exit codes:
+ *   0  claim landed (the per-item lock is held; the body stays where it rested:
+ *       `tasks/ready/` normally, or `tasks/backlog/` under --allow-backlog)
+ *   1  usage / environment error, or a readiness REFUSAL (unmet blockedBy)
+ *   2  item not claimable (not in backlog, or lost the lock race to someone else)
+ *   3  (legacy) push contention — no longer reachable: the per-item lock never
+ *      falsely contends, so there is no retry budget to exhaust
+ *
+ * UNIFIED PER-ITEM LOCK (prd `ledger-status-per-item-lock-refs` US #1/#15/#16,
+ * ADR `ledger-status-on-per-item-lock-refs`): a claim ACQUIRES the item's
+ * per-item lock (`action: implement`) via the lock module and writes NOTHING to
+ * `main` — the body STAYS at `work/backlog/<slug>.md`. The claimable predicate is
+ * "in `backlog/` on `main` AND no lock held"; the held lock IS the claim. The lock
+ * is acquired FIRST, so a lock `lost` (the SAME item is already locked) makes the
+ * claim lose definitively (exit 2, NO retry budget). A subsequent claimability
+ * re-check (the body left `backlog/`) RELEASES the lock (never orphaned). Because
+ * claim touches no `main` (and no protected ref), a protected-`main` repo CAN be
+ * claimed. The interim dual-write (`git mv backlog→in-progress` + a `main` claim
+ * commit) is GONE.
+ *
+ * Before the claim runs, the HUMAN path's readiness guard (resolveReadiness) is
+ * applied: a task with an unmet `blockedBy` is REFUSED (exit 1, outcome
+ * 'not-ready') unless overridden; a `needsAnswers: true` task is WARNED about
+ * but still claimed. The autonomous runner does NOT pass `humanPath`, so its
+ * behaviour is unchanged (eligibility already filters those items upstream).
+ */
+/** Maps onto the four claim.sh exit codes. */
+export type ClaimExitCode = 0 | 1 | 2 | 3;
+/** A semantic label for each exit code (for callers/tests, never the verdict). */
+export type ClaimCasOutcome = 'claimed' | 'usage-error' | 'lost' | 'contended' | 'not-ready';
+export interface ClaimCasOptions {
+    /** The slug to claim (`work/backlog/<slug>.md`). */
+    slug: string;
+    /** Working clone/worktree the claim runs in. */
+    cwd: string;
+    /** Name of the arbiter remote (`--arbiter`). Defaults to `origin`. */
+    arbiter?: string;
+    /**
+     * (LEGACY, accepted-but-ignored) Cap on push retries when main merely advanced.
+     * The per-item lock never falsely contends (a per-item ref CAS is self-arbitrating),
+     * so there is no retry loop and nothing to bound. Kept on the option shape so
+     * existing callers/tests that pass `--retries` keep type-checking; it has NO effect.
+     */
+    retries?: number;
+    /** Show the intended push without mutating the arbiter (`--dry-run`). */
+    dryRun?: boolean;
+    /**
+     * Apply the human-path readiness guard before the CAS: refuse an unmet
+     * `blockedBy`, warn on `needsAnswers`. The HUMAN `claim`/`start` path sets
+     * this; the autonomous runner leaves it off (it filters upstream via
+     * eligibility and must NOT change behaviour here).
+     */
+    humanPath?: boolean;
+    /**
+     * Override flag (`--force` / `--ignore-not-ready`): bypass the readiness
+     * refusal and silence the `needsAnswers` warning, printing a loud notice that
+     * the guard was overridden. Only meaningful with `humanPath`.
+     */
+    override?: boolean;
+    /**
+     * `--allow-backlog` (prd
+     * `do-allow-backlog-drive-staged-tasks-without-promotion`): WIDEN the claimable
+     * predicate to ALSO accept a `tasks/backlog/`-resident body (staging), so a
+     * human can drive a staged task in place WITHOUT promoting it to the pool. The
+     * claim STAYS a pure per-item-lock acquire \u2014 it writes NOTHING to `main` and
+     * does NOT `git mv` the body (the body stays in `tasks/backlog/`). Competitor
+     * exclusion is the HELD LOCK (the pool scan subtracts held slugs folder-
+     * agnostically), not the folder, so no move is needed. Default off \u21d2 the
+     * predicate is "in `tasks/ready/` on `main` AND no lock held" exactly as today;
+     * reachable ONLY via the explicit flag, never `run`/auto-pick/advance.
+     */
+    allowBacklog?: boolean;
+    /** Environment for child git processes (identity etc.). */
+    env?: NodeJS.ProcessEnv;
+    /** Sink for human-readable progress notes (claim.sh writes these to stderr). */
+    note?: (message: string) => void;
+}
+export interface ClaimCasResult {
+    exitCode: ClaimExitCode;
+    outcome: ClaimCasOutcome;
+    /** Human-readable summary of the terminal condition. */
+    message: string;
+    /**
+     * (RETAINED for the option shape; now ALWAYS absent.) Historically the sha of
+     * the CLAIM COMMIT that landed on `main`, used by in-place onboarding to branch
+     * the work branch off the exact claim commit. The lock-substrate claim writes
+     * NOTHING to `main` (the body stays where it rested — `tasks/ready/` normally,
+     * or `tasks/backlog/` under --allow-backlog), so there is no claim
+     * commit — onboarding cuts the work branch straight off `<arbiter>/main` (which
+     * carries the backlog body). Kept on the result shape so existing readers
+     * (`do.ts` threads `claim.claimCommit` into onboarding) keep type-checking; an
+     * `undefined` value drives onboarding's fresh-off-`<arbiter>/main` branch path.
+     */
+    claimCommit?: string;
+}
+/**
+ * Perform the claim CAS. Never throws for the expected "lost the race" or
+ * "contended" cases — those are returned as exit 2 / 3. Usage/environment
+ * problems surface as exit 1. A successful claim is exit 0. This mirrors
+ * claim.sh's control flow exactly (refuse dirty tree → loop attempts → on
+ * rejection refetch & decide lost-vs-advanced → cap retries → back off).
+ */
+export declare function performClaim(options: ClaimCasOptions): Promise<ClaimCasResult>;
+//# sourceMappingURL=claim-cas.d.ts.map

package/dist/claim-cas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim-cas.d.ts","sourceRoot":"","sources":["../src/claim-cas.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,8CAA8C;AAC9C,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAE1C,kFAAkF;AAClF,MAAM,MAAM,eAAe,GACxB,SAAS,GACT,aAAa,GACb,MAAM,GACN,WAAW,GACX,WAAW,CAAC;AAEf,MAAM,WAAW,eAAe;IAC/B,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,gFAAgF;IAChF,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,eAAe,CAAC;IACzB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAsCD;;;;;;GAMG;AACH,wBAAsB,YAAY,CACjC,OAAO,EAAE,eAAe,GACtB,OAAO,CAAC,cAAc,CAAC,CAgBzB"}