/** * Task Ledger — append-only per-increment event log (SpecWeave 2.0). * * `.specweave/increments//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}. * * Increment-level events use the task id `*` and never change task state: * * note a message for whoever works on this increment next (another * thread, tool or account). `specweave note` writes it. * session a tool session picked the increment up (`specweave pickup`). * handoff a session handed the increment off (`specweave handoff`). * pickup a session picked up a handoff (`specweave pickup`). * wait the increment waits on a person (`note` says on whom and for * what). A `wait` whose note is empty, `none`, `cleared` or * `resolved` clears the earlier ones. `handoff --all` lists them. * * `accept-skip` is keyed by an AC id (`t: "AC-03"`) and one named check of * that AC. It records that a person accepted skipping the check (no license, * no installation) and never changes task state or counts as verified: * * {"t":"AC-03","e":"accept-skip","by":"claude@mbp","at":"…","check":"wonder-full-shown-when-entitled", * "reason":"…","acceptedBy":"anton","acceptedAt":"…","authorization":"…"} * * `specweave ac accept-skip` writes it; core/tasks/accepted-skip.ts derives * each AC's `acceptance` from it. * * 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 TaskEventType = 'claim' | 'done' | 'release' | 'block' | 'skip'; export type IncrementEventType = 'note' | 'session' | 'handoff' | 'pickup' | 'wait'; /** An AC-level event: a person accepted skipping one named check of an AC. */ export type AcEventType = 'accept-skip'; export type LedgerEventType = TaskEventType | IncrementEventType | AcEventType; /** Task id used by increment-level events (notes, sessions, handoffs). */ export declare const INCREMENT_EVENT_TASK = "*"; 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; /** Card text: one line, at most {@link MAX_CARD_LINE} chars (longer text is truncated). */ line?: string; /** Card link: PR URL, report path, artifact URL … */ link?: string; /** Model the writing agent ran on, when its environment names one (see {@link detectModel}). */ model?: string; /** `accept-skip`: the named check of the AC that is skipped. */ check?: string; /** `accept-skip`: why the check cannot be run (no license, no installation, …). */ reason?: string; /** `accept-skip`: the person who accepted the skip. */ acceptedBy?: string; /** `accept-skip`: when that person accepted it (ISO-8601). */ acceptedAt?: string; /** `accept-skip`: their authorization, quoted, or a message/thread reference. */ authorization?: string; } /** One accepted skip as the fold keeps it: the AC, its named check and who accepted it. */ export interface AcceptedSkip { ac: string; check: string; reason: string; acceptedBy: string; acceptedAt: string; authorization: string; /** Agent that recorded it. */ by: string; /** When it was recorded. */ at: string; } /** Fields an `accept-skip` must carry, in ledger key order. */ export declare const ACCEPT_SKIP_FIELDS: readonly ["check", "reason", "acceptedBy", "acceptedAt", "authorization"]; /** Longest card line kept in the ledger; longer text is truncated with `…`. */ export declare const MAX_CARD_LINE = 100; /** One-line card text capped at {@link MAX_CARD_LINE}. `truncated` lets callers warn. */ export declare function clampCardLine(text: string): { line: string; truncated: boolean; }; 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; /** 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; }>; /** * Card text and link per id: the latest `line` / `link` carried by an * accepted event (ignored events change nothing). Ids appear in the order * they first show up in the sorted ledger; see core/tasks/cards.ts. */ cards: Map; /** * Accepted skips, oldest first: the first complete `accept-skip` per * (AC, check). They never change `tasks`; see core/tasks/accepted-skip.ts. */ acceptedSkips: AcceptedSkip[]; } 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 `@` where the tool * is inferred from the host AI tool's environment and the host is the short * hostname, or `cloud` inside a cloud session (whose hostname is random per * session, which would make every cloud session a stranger to its own claims). */ export declare function getAgentId(env?: NodeJS.ProcessEnv): string; /** * The AI tool this process runs under. `SPECWEAVE_TOOL` wins; then the * cross-tool `AI_AGENT` variable (e.g. `claude-code_2-1-282_agent`); then * each tool's own environment markers. */ export declare function detectTool(env?: NodeJS.ProcessEnv): string; /** `cloud` inside a cloud session, else the short hostname. */ export declare function detectHost(env?: NodeJS.ProcessEnv): string; /** The tool's own session id, when it exposes one (for `session` events). */ export declare function detectSessionId(env?: NodeJS.ProcessEnv): string | undefined; /** * The model this process runs on: `SPECWEAVE_MODEL` (set by SpecWithCode or the * user), else Claude Code's `ANTHROPIC_MODEL`. Unknown → undefined. */ export declare function detectModel(env?: NodeJS.ProcessEnv): string | undefined; /** 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; }; /** Why an `accept-skip` cannot be kept, or undefined when it is complete. */ export declare function acceptSkipProblem(ev: LedgerEvent): string | undefined; 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. * - `accept-skip` never touches task state. The first complete one per * (AC, check) is kept in `acceptedSkips`; later duplicates and incomplete * ones are ignored with a reason. * - 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; /** Increment-level events (notes, sessions, handoffs), oldest first. */ export declare function readIncrementEvents(ledgerFile: string, types?: IncrementEventType[]): LedgerEvent[]; /** * Record which tool session works on this increment, once per session id, so * the ledger shows the chain of sessions (and accounts) that touched it. Only * runs when the tool exposes a session id. */ export declare function recordSessionOnce(ledgerFile: string, by: string, env?: NodeJS.ProcessEnv): boolean; /** 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