specweave 1.0.593 → 2.0.3

package/dist/src/core/tasks/closure-gate.js

@@ -0,0 +1,72 @@
+/**
+ * Closure gate for `specweave complete` (2.0).
+ *
+ * The ONLY blocking check: `reports/verify.json` must exist with `ok: true`,
+ * unless the caller supplies `--reason` (stored as metadata.closeReason).
+ * Grill / code-review / judge-llm / rubric reports are optional evidence and
+ * never block. A missing `reports/review.md` produces a one-line notice.
+ *
+ * @module core/tasks/closure-gate
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { readVerifyReport, describeUncheckedAcs } from './verify-runner.js';
+import { loadTaskBoard } from './task-board.js';
+export function checkClosureGate(incrementDir, incrementId, opts = {}) {
+    const errors = [];
+    const notices = [];
+    const info = [];
+    const verify = readVerifyReport(incrementDir);
+    const reason = opts.reason?.trim();
+    if (!verify) {
+        if (!reason) {
+            errors.push(`reports/verify.json missing — run \`specweave verify ${incrementId}\` first, or pass --reason "<why closing without it>"`);
+        }
+        else {
+            notices.push(`closing without verify.json — reason: ${reason}`);
+        }
+    }
+    else if (!verify.ok) {
+        // Say WHY it is not ok: failing commands and/or unticked acceptance
+        // criteria. "not ok (failed)" sent people hunting for a broken test that
+        // did not exist when the real blocker was 0 of 2 ACs.
+        const parts = [];
+        const failed = verify.commands.filter((c) => c.exit !== 0).map((c) => `${c.cmd} (exit ${c.exit})`).join(', ');
+        if (failed)
+            parts.push(failed);
+        const unchecked = describeUncheckedAcs(verify.acs);
+        if (unchecked)
+            parts.push(unchecked);
+        const why = parts.join('; ') || 'failed';
+        if (!reason) {
+            errors.push(`verify.json is not ok (${why}) — fix and re-run \`specweave verify ${incrementId}\`, or pass --reason`);
+        }
+        else {
+            notices.push(`closing with failed verify (${why}) — reason: ${reason}`);
+        }
+    }
+    else {
+        info.push(`verify ok (${verify.ranAt}; ${verify.commands.length} command(s); ACs ${verify.acs.done}/${verify.acs.total})`);
+        // An `ok` report that still has open ACs can only come from a spec with no
+        // AC lines at all, or a hand-edited verify.json. Say so out loud.
+        const unchecked = describeUncheckedAcs(verify.acs);
+        if (unchecked)
+            notices.push(`${unchecked} — verify.json still reports ok; check reports/verify.json`);
+        if (verify.acs.total === 0)
+            notices.push('spec.md declares no acceptance criteria — nothing was verified against');
+    }
+    try {
+        const board = loadTaskBoard(incrementDir);
+        const open = board.tasks.filter((t) => t.state.status !== 'done' && t.state.status !== 'skipped');
+        if (open.length)
+            notices.push(`${open.length} task(s) not done: ${open.map((t) => `${t.id} (${t.state.status})`).join(', ')}`);
+    }
+    catch {
+        // tasks.md unreadable → nothing to add
+    }
+    if (!fs.existsSync(path.join(incrementDir, 'reports', 'review.md'))) {
+        notices.push('no reports/review.md — consider running sw:review before shipping user-facing work');
+    }
+    return { ok: errors.length === 0, errors, notices, info };
+}
+//# sourceMappingURL=closure-gate.js.map

package/dist/src/core/tasks/closure-gate.js.map

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

package/dist/src/core/tasks/increment-updated.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `metadata.updated` bookkeeping.
+ *
+ * The 2.0 metadata shape carries `updated` — "when did this increment last
+ * move". Before this, the only timestamp was `lastActivity`, and it was
+ * touched exclusively by status transitions: a whole session of `task claim` /
+ * `task done` / `task skip` left it frozen at the creation time, so `status`
+ * and any staleness heuristic read as "nothing happened here in days".
+ *
+ * Ledger appends go through {@link touchIncrementUpdated}, which is a raw
+ * read-modify-write of metadata.json (NOT MetadataManager) on purpose: it must
+ * not validate, must not transition, must not fire sync triggers, and must
+ * never make a task command fail.
+ *
+ * @module core/tasks/increment-updated
+ */
+/**
+ * Stamp `updated` (and the legacy `lastActivity` mirror) on the increment's
+ * metadata.json. Best-effort: any error is swallowed — losing a timestamp must
+ * never lose a ledger event.
+ *
+ * @param incrementDir - increment folder (the one holding metadata.json)
+ * @param at - ISO timestamp to stamp (defaults to now)
+ * @returns true when metadata.json was rewritten
+ */
+export declare function touchIncrementUpdated(incrementDir: string, at?: string): boolean;
+//# sourceMappingURL=increment-updated.d.ts.map

package/dist/src/core/tasks/increment-updated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"increment-updated.d.ts","sourceRoot":"","sources":["../../../../src/core/tasks/increment-updated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,EAAE,GAAE,MAAiC,GAAG,OAAO,CAe1G"}

package/dist/src/core/tasks/increment-updated.js

@@ -0,0 +1,47 @@
+/**
+ * `metadata.updated` bookkeeping.
+ *
+ * The 2.0 metadata shape carries `updated` — "when did this increment last
+ * move". Before this, the only timestamp was `lastActivity`, and it was
+ * touched exclusively by status transitions: a whole session of `task claim` /
+ * `task done` / `task skip` left it frozen at the creation time, so `status`
+ * and any staleness heuristic read as "nothing happened here in days".
+ *
+ * Ledger appends go through {@link touchIncrementUpdated}, which is a raw
+ * read-modify-write of metadata.json (NOT MetadataManager) on purpose: it must
+ * not validate, must not transition, must not fire sync triggers, and must
+ * never make a task command fail.
+ *
+ * @module core/tasks/increment-updated
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Stamp `updated` (and the legacy `lastActivity` mirror) on the increment's
+ * metadata.json. Best-effort: any error is swallowed — losing a timestamp must
+ * never lose a ledger event.
+ *
+ * @param incrementDir - increment folder (the one holding metadata.json)
+ * @param at - ISO timestamp to stamp (defaults to now)
+ * @returns true when metadata.json was rewritten
+ */
+export function touchIncrementUpdated(incrementDir, at = new Date().toISOString()) {
+    const metaPath = path.join(incrementDir, 'metadata.json');
+    try {
+        if (!fs.existsSync(metaPath))
+            return false;
+        const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+        if (!meta || typeof meta !== 'object' || Array.isArray(meta))
+            return false;
+        meta.updated = at;
+        meta.lastActivity = at;
+        const tmp = `${metaPath}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(meta, null, 2) + '\n', 'utf-8');
+        fs.renameSync(tmp, metaPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=increment-updated.js.map

package/dist/src/core/tasks/increment-updated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"increment-updated.js","sourceRoot":"","sources":["../../../../src/core/tasks/increment-updated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,YAAoB,EAAE,KAAa,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;IAC/F,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,eAAe,CAAC,CAAC;IAC1D,IAAI,CAAC;QACH,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAA4B,CAAC;QACvF,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3E,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAClB,IAAI,CAAC,YAAY,GAAG,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,GAAG,QAAQ,MAAM,CAAC;QAC9B,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;QACrE,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/src/core/tasks/ledger.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Task Ledger — append-only per-increment event log (SpecWeave 2.0).
+ *
+ * `.specweave/increments/<id>/ledger.jsonl` is the ONLY mutable task state.
+ * One JSON object per line:
+ *
+ *   {"t":"T-01","e":"claim","by":"claude@mbp","at":"2026-09-02T10:00:00Z","note":"…","evidence":"…"}
+ *
+ * Any agent from any vendor participates by appending a line — via
+ * `specweave task …` or a plain `echo '…' >> ledger.jsonl`. Lines are never
+ * edited or deleted; state is DERIVED by {@link foldLedger}.
+ *
+ * Writes are single-line O_APPEND appends (same rationale as
+ * core/sync/event-queue.ts): atomic for short lines on every major OS, so two
+ * agents in one working tree never tear each other's lines. Across worktrees or
+ * clones, `.gitattributes` `merge=union` concatenates both sides and the fold is
+ * order-independent (events are sorted by timestamp before folding).
+ *
+ * @module core/tasks/ledger
+ */
+export type LedgerEventType = 'claim' | 'done' | 'release' | 'block' | 'skip';
+export interface LedgerEvent {
+    /** Task id, e.g. `T-01`. */
+    t: string;
+    /** Event type. */
+    e: LedgerEventType;
+    /** Agent id (see {@link getAgentId}). */
+    by: string;
+    /** ISO-8601 timestamp (UTC). */
+    at: string;
+    /** Free-text note (block reason, release reason, …). */
+    note?: string;
+    /** Evidence for `done`: commit sha, test command + tail, … Required for `done`. */
+    evidence?: string;
+}
+export type TaskLedgerStatus = 'open' | 'claimed' | 'stale' | 'blocked' | 'done' | 'skipped';
+export interface TaskLedgerState {
+    status: TaskLedgerStatus;
+    /** Owner (claimed/stale/blocked) or completer (done). */
+    by?: string;
+    /** ISO timestamp of the claim/block/done that produced this state. */
+    since?: string;
+    /** Evidence attached to `done`. */
+    evidence?: string;
+    /** Last note (block reason etc.). */
+    note?: string;
+}
+export interface LedgerFold {
+    /** Task id → derived state. Only tasks that have at least one event appear. */
+    tasks: Map<string, TaskLedgerState>;
+    /** Lines that were not valid events (skipped, never fatal). */
+    malformed: number;
+    /** Events the fold ignored (lost races, done without evidence, …). */
+    ignored: Array<{
+        event: LedgerEvent;
+        reason: string;
+    }>;
+}
+export declare const LEDGER_FILE = "ledger.jsonl";
+export declare const DEFAULT_LEASE_HOURS = 2;
+/** Resolve the ledger path for an increment directory. */
+export declare function ledgerPath(incrementDir: string): string;
+/**
+ * Agent identity: `SPECWEAVE_AGENT` env, else `<tool>@<hostname>` where the
+ * tool is inferred from the host AI tool's environment.
+ */
+export declare function getAgentId(env?: NodeJS.ProcessEnv): string;
+export declare function detectTool(env?: NodeJS.ProcessEnv): string;
+/** Serialize one event as a single ledger line (with trailing newline). */
+export declare function formatLedgerLine(event: LedgerEvent): string;
+/**
+ * Append one event. Single-line O_APPEND write; creates the file on first use.
+ *
+ * Also stamps `metadata.updated` for the increment (best-effort, never fatal)
+ * so "when did this increment last move" reflects ledger activity and not just
+ * status transitions.
+ */
+export declare function appendEvent(ledgerFile: string, event: LedgerEvent): void;
+/** Parse a ledger file. Missing file → no events. Malformed lines are counted, never fatal. */
+export declare function readLedger(ledgerFile: string): {
+    events: LedgerEvent[];
+    malformed: number;
+};
+export declare function parseLedger(content: string): {
+    events: LedgerEvent[];
+    malformed: number;
+};
+export interface FoldOptions {
+    /** "Now" for staleness computation (default: current time). */
+    now?: Date;
+    /** Lease length in hours (default {@link DEFAULT_LEASE_HOURS}). */
+    leaseHours?: number;
+}
+/**
+ * Deterministic fold: events sorted by (at, by, file order); per task:
+ *
+ * - `claim` on open → claimed(by). On a task claimed by ANOTHER agent whose
+ *   claim is still within the lease at the time of the new claim → ignored
+ *   (lost the race; earliest claim wins, equal timestamps → smaller `by` wins).
+ *   A claim older than the lease is stale and may be taken over. Re-claim by
+ *   the owner renews the lease. Claim on done → ignored.
+ * - `done` requires non-empty evidence. Accepted on open, by the owner, or when
+ *   the current claim is stale. Otherwise ignored.
+ * - `release` by the owner → open. Non-owner → ignored.
+ * - `block` on open or by the owner → blocked(by). Non-owner → ignored.
+ * - `skip` requires a note (reason) and is terminal (`skipped`); accepted on
+ *   open, by the owner, or when the current claim is stale.
+ * - Final pass: claimed older than the lease → `stale`.
+ */
+export declare function foldLedger(events: LedgerEvent[], opts?: FoldOptions): LedgerFold;
+/** Read + fold a ledger file in one call. */
+export declare function foldLedgerFile(ledgerFile: string, opts?: FoldOptions): LedgerFold;
+/** Human-readable one-liner for a task state (used by `task list`, handoff, verify). */
+export declare function describeState(state: TaskLedgerState | undefined): string;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/src/core/tasks/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../../../src/core/tasks/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9E,MAAM,WAAW,WAAW;IAC1B,4BAA4B;IAC5B,CAAC,EAAE,MAAM,CAAC;IACV,kBAAkB;IAClB,CAAC,EAAE,eAAe,CAAC;IACnB,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAE7F,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,gBAAgB,CAAC;IACzB,yDAAyD;IACzD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,+EAA+E;IAC/E,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACpC,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxD;AAED,eAAO,MAAM,WAAW,iBAAiB,CAAC;AAC1C,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAIrC,0DAA0D;AAC1D,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAIvE;AAED,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAKvE;AAOD,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAM3D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAIxE;AAED,+FAA+F;AAC/F,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAG3F;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CA+BzF;AAED,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,IAAI,GAAE,WAAgB,GAAG,UAAU,CAsEpF;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,UAAU,CAIrF;AAED,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,GAAG,MAAM,CASxE"}

package/dist/src/core/tasks/ledger.js

@@ -0,0 +1,250 @@
+/**
+ * Task Ledger — append-only per-increment event log (SpecWeave 2.0).
+ *
+ * `.specweave/increments/<id>/ledger.jsonl` is the ONLY mutable task state.
+ * One JSON object per line:
+ *
+ *   {"t":"T-01","e":"claim","by":"claude@mbp","at":"2026-09-02T10:00:00Z","note":"…","evidence":"…"}
+ *
+ * Any agent from any vendor participates by appending a line — via
+ * `specweave task …` or a plain `echo '…' >> ledger.jsonl`. Lines are never
+ * edited or deleted; state is DERIVED by {@link foldLedger}.
+ *
+ * Writes are single-line O_APPEND appends (same rationale as
+ * core/sync/event-queue.ts): atomic for short lines on every major OS, so two
+ * agents in one working tree never tear each other's lines. Across worktrees or
+ * clones, `.gitattributes` `merge=union` concatenates both sides and the fold is
+ * order-independent (events are sorted by timestamp before folding).
+ *
+ * @module core/tasks/ledger
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { touchIncrementUpdated } from './increment-updated.js';
+export const LEDGER_FILE = 'ledger.jsonl';
+export const DEFAULT_LEASE_HOURS = 2;
+const VALID_EVENTS = new Set(['claim', 'done', 'release', 'block', 'skip']);
+/** Resolve the ledger path for an increment directory. */
+export function ledgerPath(incrementDir) {
+    return path.join(incrementDir, LEDGER_FILE);
+}
+/**
+ * Agent identity: `SPECWEAVE_AGENT` env, else `<tool>@<hostname>` where the
+ * tool is inferred from the host AI tool's environment.
+ */
+export function getAgentId(env = process.env) {
+    const explicit = env.SPECWEAVE_AGENT?.trim();
+    if (explicit)
+        return explicit;
+    return `${detectTool(env)}@${shortHostname()}`;
+}
+export function detectTool(env = process.env) {
+    if (env.CLAUDECODE || env.CLAUDE_CODE)
+        return 'claude';
+    if (Object.keys(env).some((k) => k.startsWith('CODEX_')))
+        return 'codex';
+    if (Object.keys(env).some((k) => k.startsWith('OPENCODE')))
+        return 'opencode';
+    return 'cli';
+}
+function shortHostname() {
+    const h = os.hostname() || 'host';
+    return h.split('.')[0].toLowerCase();
+}
+/** Serialize one event as a single ledger line (with trailing newline). */
+export function formatLedgerLine(event) {
+    // Fixed key order keeps lines diff-friendly and grep-able.
+    const ordered = { t: event.t, e: event.e, by: event.by, at: event.at };
+    if (event.note)
+        ordered.note = event.note;
+    if (event.evidence)
+        ordered.evidence = event.evidence;
+    return JSON.stringify(ordered) + '\n';
+}
+/**
+ * Append one event. Single-line O_APPEND write; creates the file on first use.
+ *
+ * Also stamps `metadata.updated` for the increment (best-effort, never fatal)
+ * so "when did this increment last move" reflects ledger activity and not just
+ * status transitions.
+ */
+export function appendEvent(ledgerFile, event) {
+    fs.mkdirSync(path.dirname(ledgerFile), { recursive: true });
+    fs.appendFileSync(ledgerFile, formatLedgerLine(event), { encoding: 'utf-8', flag: 'a' });
+    touchIncrementUpdated(path.dirname(ledgerFile), event.at);
+}
+/** Parse a ledger file. Missing file → no events. Malformed lines are counted, never fatal. */
+export function readLedger(ledgerFile) {
+    if (!fs.existsSync(ledgerFile))
+        return { events: [], malformed: 0 };
+    return parseLedger(fs.readFileSync(ledgerFile, 'utf-8'));
+}
+export function parseLedger(content) {
+    const events = [];
+    let malformed = 0;
+    // Tolerate BOM (PowerShell `>>` writes UTF-16/BOM by default), CRLF, blank lines.
+    for (const raw of content.replace(/^\uFEFF/, '').split('\n')) {
+        const line = raw.replace(/\uFEFF/g, '').trim();
+        if (!line)
+            continue;
+        try {
+            const obj = JSON.parse(line);
+            if (typeof obj.t === 'string' && obj.t &&
+                typeof obj.e === 'string' && VALID_EVENTS.has(obj.e) &&
+                typeof obj.by === 'string' && obj.by &&
+                typeof obj.at === 'string' && !Number.isNaN(Date.parse(obj.at))) {
+                events.push({
+                    t: obj.t,
+                    e: obj.e,
+                    by: obj.by,
+                    at: obj.at,
+                    ...(typeof obj.note === 'string' ? { note: obj.note } : {}),
+                    ...(typeof obj.evidence === 'string' ? { evidence: obj.evidence } : {}),
+                });
+            }
+            else {
+                malformed++;
+            }
+        }
+        catch {
+            malformed++;
+        }
+    }
+    return { events, malformed };
+}
+/**
+ * Deterministic fold: events sorted by (at, by, file order); per task:
+ *
+ * - `claim` on open → claimed(by). On a task claimed by ANOTHER agent whose
+ *   claim is still within the lease at the time of the new claim → ignored
+ *   (lost the race; earliest claim wins, equal timestamps → smaller `by` wins).
+ *   A claim older than the lease is stale and may be taken over. Re-claim by
+ *   the owner renews the lease. Claim on done → ignored.
+ * - `done` requires non-empty evidence. Accepted on open, by the owner, or when
+ *   the current claim is stale. Otherwise ignored.
+ * - `release` by the owner → open. Non-owner → ignored.
+ * - `block` on open or by the owner → blocked(by). Non-owner → ignored.
+ * - `skip` requires a note (reason) and is terminal (`skipped`); accepted on
+ *   open, by the owner, or when the current claim is stale.
+ * - Final pass: claimed older than the lease → `stale`.
+ */
+export function foldLedger(events, opts = {}) {
+    const leaseMs = (opts.leaseHours ?? DEFAULT_LEASE_HOURS) * 3600 * 1000;
+    const nowMs = (opts.now ?? new Date()).getTime();
+    const sorted = events
+        .map((ev, i) => ({ ev, i }))
+        .sort((a, b) => {
+        const ta = Date.parse(a.ev.at);
+        const tb = Date.parse(b.ev.at);
+        if (ta !== tb)
+            return ta - tb;
+        if (a.ev.by !== b.ev.by)
+            return a.ev.by < b.ev.by ? -1 : 1;
+        return a.i - b.i;
+    })
+        .map((x) => x.ev);
+    const tasks = new Map();
+    const ignored = [];
+    const isStaleAt = (state, atMs) => state.since !== undefined && atMs - Date.parse(state.since) > leaseMs;
+    for (const ev of sorted) {
+        const cur = tasks.get(ev.t) ?? { status: 'open' };
+        const atMs = Date.parse(ev.at);
+        const heldByOther = (cur.status === 'claimed' || cur.status === 'blocked') && cur.by !== ev.by && !isStaleAt(cur, atMs);
+        switch (ev.e) {
+            case 'claim': {
+                if (cur.status === 'done' || cur.status === 'skipped') {
+                    ignored.push({ event: ev, reason: `already ${cur.status}` });
+                    break;
+                }
+                if (heldByOther) {
+                    ignored.push({ event: ev, reason: `claimed by ${cur.by}` });
+                    break;
+                }
+                tasks.set(ev.t, { status: 'claimed', by: ev.by, since: ev.at, note: ev.note });
+                break;
+            }
+            case 'done': {
+                if (!ev.evidence || !ev.evidence.trim()) {
+                    ignored.push({ event: ev, reason: 'done without evidence' });
+                    break;
+                }
+                if (cur.status === 'skipped') {
+                    ignored.push({ event: ev, reason: 'already skipped' });
+                    break;
+                }
+                if (heldByOther) {
+                    ignored.push({ event: ev, reason: `claimed by ${cur.by}` });
+                    break;
+                }
+                tasks.set(ev.t, { status: 'done', by: ev.by, since: ev.at, evidence: ev.evidence, note: ev.note });
+                break;
+            }
+            case 'release': {
+                if (cur.status === 'done' || cur.status === 'open' || cur.status === 'skipped') {
+                    ignored.push({ event: ev, reason: `task is ${cur.status}` });
+                    break;
+                }
+                if (cur.by !== ev.by) {
+                    ignored.push({ event: ev, reason: `not owner (${cur.by})` });
+                    break;
+                }
+                tasks.set(ev.t, { status: 'open', note: ev.note });
+                break;
+            }
+            case 'block': {
+                if (cur.status === 'done' || cur.status === 'skipped') {
+                    ignored.push({ event: ev, reason: `already ${cur.status}` });
+                    break;
+                }
+                if (heldByOther) {
+                    ignored.push({ event: ev, reason: `claimed by ${cur.by}` });
+                    break;
+                }
+                tasks.set(ev.t, { status: 'blocked', by: ev.by, since: ev.at, note: ev.note });
+                break;
+            }
+            case 'skip': {
+                if (!ev.note || !ev.note.trim()) {
+                    ignored.push({ event: ev, reason: 'skip without reason' });
+                    break;
+                }
+                if (cur.status === 'done' || cur.status === 'skipped') {
+                    ignored.push({ event: ev, reason: `already ${cur.status}` });
+                    break;
+                }
+                if (heldByOther) {
+                    ignored.push({ event: ev, reason: `claimed by ${cur.by}` });
+                    break;
+                }
+                tasks.set(ev.t, { status: 'skipped', by: ev.by, since: ev.at, note: ev.note });
+                break;
+            }
+        }
+    }
+    for (const [t, state] of tasks) {
+        if (state.status === 'claimed' && isStaleAt(state, nowMs)) {
+            tasks.set(t, { ...state, status: 'stale' });
+        }
+    }
+    return { tasks, malformed: 0, ignored };
+}
+/** Read + fold a ledger file in one call. */
+export function foldLedgerFile(ledgerFile, opts = {}) {
+    const { events, malformed } = readLedger(ledgerFile);
+    const fold = foldLedger(events, opts);
+    return { ...fold, malformed };
+}
+/** Human-readable one-liner for a task state (used by `task list`, handoff, verify). */
+export function describeState(state) {
+    if (!state || state.status === 'open')
+        return 'open';
+    switch (state.status) {
+        case 'done': return `done by ${state.by}`;
+        case 'claimed': return `claimed by ${state.by} since ${state.since}`;
+        case 'stale': return `STALE claim by ${state.by} since ${state.since}`;
+        case 'blocked': return `blocked by ${state.by}${state.note ? `: ${state.note}` : ''}`;
+        case 'skipped': return `skipped by ${state.by}${state.note ? `: ${state.note}` : ''}`;
+    }
+}
+//# sourceMappingURL=ledger.js.map

package/dist/src/core/tasks/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../../../src/core/tasks/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AA0C/D,MAAM,CAAC,MAAM,WAAW,GAAG,cAAc,CAAC;AAC1C,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAErC,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;AAEjG,0DAA0D;AAC1D,MAAM,UAAU,UAAU,CAAC,YAAoB;IAC7C,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,QAAQ,GAAG,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC;IAC7C,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,aAAa,EAAE,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,IAAI,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,WAAW;QAAE,OAAO,QAAQ,CAAC;IACvD,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAAE,OAAO,OAAO,CAAC;IACzE,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;QAAE,OAAO,UAAU,CAAC;IAC9E,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,aAAa;IACpB,MAAM,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,IAAI,MAAM,CAAC;IAClC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;AACvC,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,gBAAgB,CAAC,KAAkB;IACjD,2DAA2D;IAC3D,MAAM,OAAO,GAA2B,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;IAC/F,IAAI,KAAK,CAAC,IAAI;QAAE,OAAO,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IAC1C,IAAI,KAAK,CAAC,QAAQ;QAAE,OAAO,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IACtD,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,UAAkB,EAAE,KAAkB;IAChE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,EAAE,CAAC,cAAc,CAAC,UAAU,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;IACzF,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,UAAU,CAAC,UAAkB;IAC3C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IACpE,OAAO,WAAW,CAAC,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,kFAAkF;IAClF,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC/C,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAyB,CAAC;YACrD,IACE,OAAO,GAAG,CAAC,CAAC,KAAK,QAAQ,IAAI,GAAG,CAAC,CAAC;gBAClC,OAAO,GAAG,CAAC,CAAC,KAAK,QAAQ,IAAI,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;gBACpD,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ,IAAI,GAAG,CAAC,EAAE;gBACpC,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAC/D,CAAC;gBACD,MAAM,CAAC,IAAI,CAAC;oBACV,CAAC,EAAE,GAAG,CAAC,CAAC;oBACR,CAAC,EAAE,GAAG,CAAC,CAAoB;oBAC3B,EAAE,EAAE,GAAG,CAAC,EAAE;oBACV,EAAE,EAAE,GAAG,CAAC,EAAE;oBACV,GAAG,CAAC,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC3D,GAAG,CAAC,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACxE,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,SAAS,EAAE,CAAC;YACd,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,EAAE,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC/B,CAAC;AASD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,UAAU,CAAC,MAAqB,EAAE,OAAoB,EAAE;IACtE,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,mBAAmB,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IACvE,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IAEjD,MAAM,MAAM,GAAG,MAAM;SAClB,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;SAC3B,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACb,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAC/B,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAC/B,IAAI,EAAE,KAAK,EAAE;YAAE,OAAO,EAAE,GAAG,EAAE,CAAC;QAC9B,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE;YAAE,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3D,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC,CAAC;SACD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAEpB,MAAM,KAAK,GAAG,IAAI,GAAG,EAA2B,CAAC;IACjD,MAAM,OAAO,GAA0B,EAAE,CAAC;IAE1C,MAAM,SAAS,GAAG,CAAC,KAAsB,EAAE,IAAY,EAAW,EAAE,CAClE,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC;IAExE,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,MAA0B,EAAE,CAAC;QACtE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAC/B,MAAM,WAAW,GACf,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,IAAI,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAEtG,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC;YACb,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;oBAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;oBAAC,MAAM;gBAAC,CAAC;gBAC/H,IAAI,WAAW,EAAE,CAAC;oBAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,cAAc,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;oBAAC,MAAM;gBAAC,CAAC;gBACxF,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;gBAC/E,MAAM;YACR,CAAC;YACD,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,IAAI,CAAC,EAAE,CAAC,QAAQ,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;oBAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC,CAAC;oBAAC,MAAM;gBAAC,CAAC;gBACjH,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;oBAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAAC;oBAAC,MAAM;gBAAC,CAAC;gBAChG,IAAI,WAAW,EAAE,CAAC;oBAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,cAAc,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;oBAAC,MAAM;gBAAC,CAAC;gBACxF,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;gBACnG,MAAM;YACR,CAAC;YACD,KAAK,SAAS,CAAC,CAAC,CAAC;gBACf,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;oBAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;oBAAC,MAAM;gBAAC,CAAC;gBACxJ,IAAI,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;oBAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,cAAc,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;oBAAC,MAAM;gBAAC,CAAC;gBAC9F,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;gBACnD,MAAM;YACR,CAAC;YACD,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;oBAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;oBAAC,MAAM;gBAAC,CAAC;gBAC/H,IAAI,WAAW,EAAE,CAAC;oBAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,cAAc,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;oBAAC,MAAM;gBAAC,CAAC;gBACxF,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;gBAC/E,MAAM;YACR,CAAC;YACD,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,IAAI,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;oBAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC,CAAC;oBAAC,MAAM;gBAAC,CAAC;gBACvG,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;oBAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;oBAAC,MAAM;gBAAC,CAAC;gBAC/H,IAAI,WAAW,EAAE,CAAC;oBAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,cAAc,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;oBAAC,MAAM;gBAAC,CAAC;gBACxF,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;gBAC/E,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC;QAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;YAC1D,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC;AAC1C,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,cAAc,CAAC,UAAkB,EAAE,OAAoB,EAAE;IACvE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACtC,OAAO,EAAE,GAAG,IAAI,EAAE,SAAS,EAAE,CAAC;AAChC,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,aAAa,CAAC,KAAkC;IAC9D,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC;IACrD,QAAQ,KAAK,CAAC,MAAM,EAAE,CAAC;QACrB,KAAK,MAAM,CAAC,CAAC,OAAO,WAAW,KAAK,CAAC,EAAE,EAAE,CAAC;QAC1C,KAAK,SAAS,CAAC,CAAC,OAAO,cAAc,KAAK,CAAC,EAAE,UAAU,KAAK,CAAC,KAAK,EAAE,CAAC;QACrE,KAAK,OAAO,CAAC,CAAC,OAAO,kBAAkB,KAAK,CAAC,EAAE,UAAU,KAAK,CAAC,KAAK,EAAE,CAAC;QACvE,KAAK,SAAS,CAAC,CAAC,OAAO,cAAc,KAAK,CAAC,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACtF,KAAK,SAAS,CAAC,CAAC,OAAO,cAAc,KAAK,CAAC,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACxF,CAAC;AACH,CAAC"}

package/dist/src/core/tasks/resolve-increment.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Increment resolution shared by `task`, `verify`, `handoff`.
+ *
+ * - explicit id: short (`0874`) or full slug, via resolveIncrementId
+ * - omitted: the SINGLE increment whose metadata.json status is in flight
+ *   (`active`, `in-progress`, `ready_for_review`). When nothing is in flight we
+ *   fall back to the single `planned`/`backlog` increment, so an increment that
+ *   has not been started yet still resolves (`task claim` starts it).
+ *   (2+ → error listing candidates; 0 → error). metadata.json is read directly
+ *   (never lazily created).
+ *
+ * @module core/tasks/resolve-increment
+ */
+export interface ResolvedIncrement {
+    id: string;
+    dir: string;
+}
+export declare class IncrementResolutionError extends Error {
+    readonly candidates: string[];
+    constructor(message: string, candidates?: string[]);
+}
+export declare function incrementsDir(projectRoot: string): string;
+/** Ids of increments whose metadata.json says `active` (read-only scan). */
+export declare function listActiveIncrementIds(projectRoot: string): string[];
+/** Ids of increments that exist but have not been started (`planned`/`backlog`). */
+export declare function listStartableIncrementIds(projectRoot: string): string[];
+export declare function resolveIncrement(projectRoot: string, id?: string): ResolvedIncrement;
+/** Lease hours from config (`tasks.leaseHours`), default 2. */
+export declare function readLeaseHours(projectRoot: string): number;
+/**
+ * Active increments whose task board is finished (every task done or skipped,
+ * and at least one task exists). This is the candidate set for
+ * `specweave complete --all --reason "…"`.
+ */
+export declare function listTaskCompleteIncrementIds(projectRoot: string, leaseHours?: number): string[];
+/**
+ * Move a not-started increment (`planned`/`planning`/`backlog`) to `active`.
+ *
+ * Claiming a task IS starting the increment, so the CLI owns this transition —
+ * the skills forbid hand-editing metadata.json, and before 2.0 there was no
+ * command that performed it at all.
+ *
+ * Returns a one-line note when it transitioned, `undefined` when the increment
+ * was already in flight (or metadata.json is missing/unreadable).
+ */
+export declare function ensureIncrementStarted(incrementDir: string): string | undefined;
+//# sourceMappingURL=resolve-increment.d.ts.map

package/dist/src/core/tasks/resolve-increment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-increment.d.ts","sourceRoot":"","sources":["../../../../src/core/tasks/resolve-increment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;CACb;AAED,qBAAa,wBAAyB,SAAQ,KAAK;aACJ,UAAU,EAAE,MAAM,EAAE;gBAArD,OAAO,EAAE,MAAM,EAAkB,UAAU,GAAE,MAAM,EAAO;CAIvE;AAaD,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEzD;AAoBD,4EAA4E;AAC5E,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAEpE;AAED,oFAAoF;AACpF,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAEvE;AAED,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAsCpF;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAU1D;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAU/F;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAe/E"}