dorfl 0.0.0 → 0.1.0

package/dist/watch-session.js

@@ -0,0 +1,347 @@
+import { open } from 'node:fs/promises';
+/**
+ * The **`do --watch` observer** (tasks `do-watch` + `do-watch-session-log-format`)
+ * — a READ-ONLY concurrent tail of the pi session `.jsonl` event log, restoring
+ * for `do` the live agent-conversation view `ar-run.sh --watch` gave.
+ *
+ * `ar-run.sh --watch` piped `pi -p --mode json | jq` to surface the high-signal
+ * events; `do` runs the agent CAPTURED through the harness seam, so that live
+ * view was lost. The pi adapter writes a session `.jsonl` at the KNOWN file path
+ * the caller generated (`--session <path>`, task `session-path-pi-default`) —
+ * but that is pi's SESSION-PERSISTENCE log, a DIFFERENT format from the
+ * `--mode json` STREAM `ar-run.sh` piped. The tailer is pointed at that EXACT
+ * path (no newest-by-mtime dir guessing), so the stale-sibling race is gone.
+ *
+ * A session-log record is `{"type":"message", "message":{role, content[]}}` (or a
+ * `session`/`model_change`/`thinking_level_change` preamble record). The earlier
+ * classifier matched the STREAM vocabulary (`tool_start`/`message_end`/`agent_end`),
+ * none of which occur in the session log — so every line fell through to skip and
+ * `do --watch` was silently a no-op. This module tails the growing session log and
+ * surfaces the same high-signal level `ar-run.sh --watch` gave, read off the
+ * SESSION-LOG shape:
+ *
+ *   - an `assistant` `message` → its `content[]` `text` parts, then `▶ <name>`
+ *     (cyan) per `content[]` `toolCall` part;
+ *   - `✓ agent finished` (green) on PROCESS EXIT — the session log has no
+ *     `agent_end` event, so the tailer emits it once on `stop()`;
+ *   - everything else (`session`/`model_change`/user messages/tool results/…) →
+ *     skipped.
+ *
+ * The classifier mirrors pi-remote's `session-pool.ts` reference parser (`type` →
+ * `role` → `content[]` block walk over `thinking`/`text`/`toolCall`, incl.
+ * `tc.name||tc.toolName` and content-as-string). The JSONL is parsed in TS (NO
+ * `jq` — that bash dependency is part of what `do` replaces). It is a PURE
+ * OBSERVER: it only READS the log; it never changes the run's outcome, gate,
+ * integration, git, or exit code. Colour is honoured ONLY on a TTY / when
+ * `NO_COLOR` is unset (the same rule as `output.ts`), threaded in by the caller
+ * as a boolean.
+ */
+// The same conventional ANSI codes `ar-run.sh`'s jq filter emitted (cyan tool
+// marker, green finished marker, reset). Colour is applied ONLY when the caller
+// passes `color: true` (its TTY/NO_COLOR decision); plain otherwise.
+const CYAN = '\u001b[36m';
+const GREEN = '\u001b[32m';
+const RESET = '\u001b[0m';
+/** Wrap `text` in `code` + reset when `color`, else return it unchanged. */
+function paint(text, color, code) {
+    return color ? `${code}${text}${RESET}` : text;
+}
+/** The green `✓ agent finished` line, emitted on PROCESS EXIT (not a log event). */
+export function finishedLine(color) {
+    return paint('✓ agent finished', color, GREEN);
+}
+/**
+ * A one-line VISUAL BOUNDARY banner the caller prints between two tailed agent
+ * streams (e.g. the build stream and the Gate-2 review stream — task
+ * `watch-review-session`), so a watching human knows the first stream ended and
+ * the next began. Reuses this module's colour rule (cyan, the same marker hue as
+ * the `▶ <tool>` lines) so it reads as part of the same live view. Pure: returns
+ * the string; the caller routes it to the watch sink.
+ */
+export function boundaryLine(label, color) {
+    return paint(`▶ ${label}`, color, CYAN);
+}
+/**
+ * Parse ONE pi SESSION-LOG `.jsonl` line and return the high-signal lines to
+ * surface — or `[]` to SKIP it. This is the pure, unit-testable classifier,
+ * mirroring pi-remote's `session-pool.ts` block walk:
+ *
+ *   - a `{type:"message", message:{role:"assistant", content}}` record → for each
+ *     `content[]` part: a `text` part yields its text (parts concatenated into
+ *     ONE line, like the old `jq` `.content[]` select); a `toolCall` part yields
+ *     `▶ <name>` (cyan; `name` OR `toolName`, defaulting to `tool`); a `thinking`
+ *     part (and anything else) is skipped. A plain-string `content` yields one
+ *     text line.
+ *   - everything else (`session`/`model_change`/`thinking_level_change`, user
+ *     messages, tool results, blank/malformed lines) → `[]` (skipped).
+ *
+ * "Finished" is NOT a record here — the session log has no `agent_end`; the
+ * tailer emits {@link finishedLine} on process exit instead.
+ *
+ * Malformed JSON is skipped (not thrown): a partially-written trailing line in a
+ * growing log must not crash the observer.
+ */
+export function formatWatchEvent(line, color) {
+    const trimmed = line.trim();
+    if (trimmed === '') {
+        return [];
+    }
+    let event;
+    try {
+        event = JSON.parse(trimmed);
+    }
+    catch {
+        // A half-written trailing line in a growing log — skip, never throw.
+        return [];
+    }
+    if (typeof event !== 'object' || event === null) {
+        return [];
+    }
+    const record = event;
+    if (record.type !== 'message') {
+        return [];
+    }
+    const message = record.message;
+    if (!message || message.role !== 'assistant') {
+        // Skip user turns, tool results, and any non-assistant message.
+        return [];
+    }
+    return assistantLines(message.content, color);
+}
+/**
+ * Walk an assistant `message.content` into the lines to surface, mirroring
+ * pi-remote's `session-pool.ts` reference parser. The `text` parts are
+ * concatenated into a SINGLE leading line (so a multi-part assistant turn reads
+ * as one sentence, as `ar-run.sh --watch` showed it); each `toolCall` part adds a
+ * `▶ <name>` line after it. A plain-string content yields the single text line.
+ * `thinking` parts and any other block type are skipped.
+ */
+function assistantLines(content, color) {
+    if (typeof content === 'string') {
+        return content === '' ? [] : [content];
+    }
+    if (!Array.isArray(content)) {
+        return [];
+    }
+    const lines = [];
+    const text = assistantContentText(content);
+    for (const part of content) {
+        if (typeof part !== 'object' || part === null) {
+            continue;
+        }
+        const p = part;
+        if (p.type === 'toolCall') {
+            const name = (typeof p.name === 'string' && p.name !== '' && p.name) ||
+                (typeof p.toolName === 'string' && p.toolName !== '' && p.toolName) ||
+                'tool';
+            lines.push(paint(`▶ ${name}`, color, CYAN));
+        }
+        // `text` is collected by assistantContentText; `thinking` and any other
+        // block type are skipped.
+    }
+    return text === '' ? lines : [text, ...lines];
+}
+/**
+ * Concatenate the `text` parts of ONE assistant `message.content` (the answer
+ * text, with tool/thinking blocks dropped) — the single source of truth for
+ * "what did the assistant SAY" shared by the {@link assistantLines} watch view
+ * and the {@link lastAssistantText} output reader (task `harness-agent-output`).
+ * A plain-string content is itself the text. Returns `''` when there is no text.
+ */
+function assistantContentText(content) {
+    if (typeof content === 'string') {
+        return content;
+    }
+    if (!Array.isArray(content)) {
+        return '';
+    }
+    const textParts = [];
+    for (const part of content) {
+        if (typeof part !== 'object' || part === null) {
+            continue;
+        }
+        const p = part;
+        if (p.type === 'text' && typeof p.text === 'string') {
+            textParts.push(p.text);
+        }
+    }
+    return textParts.join('');
+}
+/**
+ * Extract the **last assistant message's text** from a pi session `.jsonl`
+ * (task `harness-agent-output`) — the agent's final ANSWER, surfaced through
+ * the harness seam as `LaunchResult.output`. It REUSES this module's session-log
+ * shape walk (one parser, not two): it scans the `{type:"message",
+ * message:{role:"assistant", content[]}}` records, takes the LAST one carrying
+ * non-empty `text`, and returns its concatenated text.
+ *
+ * Returns `undefined` when the log has no assistant text at all — an absent log,
+ * a malformed/short log, or a run whose only assistant turn was tool-calls (no
+ * `text` part). A tool-only assistant turn is NOT a final answer, so a LATER
+ * text turn (if any) wins; with no text turn anywhere the result is `undefined`.
+ *
+ * Malformed/blank lines are skipped (never thrown): a partially-written trailing
+ * line in a just-closed log must not crash the reader.
+ */
+export function lastAssistantText(jsonl) {
+    let last;
+    for (const line of jsonl.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '') {
+            continue;
+        }
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            continue; // a half-written / malformed line — skip, never throw.
+        }
+        if (typeof event !== 'object' || event === null) {
+            continue;
+        }
+        const record = event;
+        if (record.type !== 'message') {
+            continue;
+        }
+        const message = record.message;
+        if (!message || message.role !== 'assistant') {
+            continue;
+        }
+        const text = assistantContentText(message.content);
+        if (text !== '') {
+            last = text; // a later text turn supersedes an earlier one.
+        }
+    }
+    return last;
+}
+const DEFAULT_POLL_INTERVAL_MS = 100;
+/**
+ * A concurrent, READ-ONLY tail of the pi session `.jsonl`. It polls the KNOWN
+ * session-file path (which the pi adapter creates only once pi starts) until it
+ * appears, then reads newly-appended bytes, splits them into complete lines, and
+ * surfaces each via {@link formatWatchEvent}. A partial trailing line is
+ * buffered until its newline arrives, so an event split across two reads is
+ * never mis-parsed.
+ *
+ * It is a pure observer: nothing it does feeds back into the run. `start()`
+ * begins polling; `stop()` performs one final drain (to catch events written
+ * just before the agent exited), emits the `✓ agent finished` line ONCE (the
+ * session log has no `agent_end` — process exit IS the finish signal), and
+ * releases the file handle. Created and driven by `do --watch` ALONGSIDE the
+ * (async) agent launch; `stop()` runs when that launch returns (i.e. the agent
+ * process exited).
+ */
+export class SessionTailer {
+    sessionFile;
+    color;
+    sink;
+    pollIntervalMs;
+    handle;
+    offset = 0;
+    pending = '';
+    timer;
+    polling = false;
+    stopped = false;
+    finishedEmitted = false;
+    constructor(options) {
+        this.sessionFile = options.sessionFile;
+        this.color = options.color;
+        this.sink = options.sink ?? ((line) => process.stderr.write(`${line}\n`));
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    }
+    /** Begin polling for the known session file and tailing its new bytes. */
+    start() {
+        if (this.timer !== undefined || this.stopped) {
+            return;
+        }
+        this.timer = setInterval(() => {
+            void this.poll();
+        }, this.pollIntervalMs);
+        // `unref` so an orphaned timer never keeps the process alive past the run.
+        this.timer.unref?.();
+    }
+    /**
+     * Stop tailing: one final drain (events written right before the agent exited
+     * must still be surfaced), emit the `✓ agent finished` line ONCE (process exit
+     * is the finish signal — the session log carries no `agent_end`), then release
+     * the handle. Idempotent: a second `stop()` re-emits nothing.
+     */
+    async stop() {
+        const wasStopped = this.stopped;
+        this.stopped = true;
+        if (this.timer !== undefined) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        if (!wasStopped) {
+            await this.drain();
+        }
+        if (this.handle !== undefined) {
+            await this.handle.close();
+            this.handle = undefined;
+        }
+        if (!this.finishedEmitted) {
+            this.finishedEmitted = true;
+            this.sink(finishedLine(this.color));
+        }
+    }
+    /** One poll tick: ensure the handle is open, then drain new bytes. */
+    async poll() {
+        if (this.polling) {
+            return; // a slow read must not overlap the next tick.
+        }
+        this.polling = true;
+        try {
+            await this.drain();
+        }
+        catch {
+            // A transient read error (the log being rotated/created) — try next tick.
+        }
+        finally {
+            this.polling = false;
+        }
+    }
+    /** Open the log if not yet open, read appended bytes, surface whole lines. */
+    async drain() {
+        if (this.handle === undefined) {
+            // Open the KNOWN path. pi creates it ASYNCHRONOUSLY after spawn, so until
+            // it exists `open` throws ENOENT — treat that as "not yet" and retry next
+            // tick (NEVER open once at start(), which would race the file into being).
+            try {
+                this.handle = await open(this.sessionFile, 'r');
+            }
+            catch (err) {
+                if (err.code === 'ENOENT') {
+                    return; // file not written yet — wait for it.
+                }
+                throw err; // a real error — bubble to poll's try/catch (next-tick retry).
+            }
+        }
+        const stats = await this.handle.stat();
+        if (stats.size <= this.offset) {
+            return; // no new bytes.
+        }
+        const length = stats.size - this.offset;
+        const buffer = Buffer.alloc(length);
+        const { bytesRead } = await this.handle.read(buffer, 0, length, this.offset);
+        this.offset += bytesRead;
+        this.pending += buffer.toString('utf8', 0, bytesRead);
+        this.flushLines();
+    }
+    /** Split the buffer on newlines, surfacing each COMPLETE line; keep the rest. */
+    flushLines() {
+        let newlineIndex = this.pending.indexOf('\n');
+        while (newlineIndex !== -1) {
+            const line = this.pending.slice(0, newlineIndex);
+            this.pending = this.pending.slice(newlineIndex + 1);
+            // A single record may surface MULTIPLE lines (assistant text + each of
+            // its tool starts), or none (skipped record types).
+            for (const formatted of formatWatchEvent(line, this.color)) {
+                this.sink(formatted);
+            }
+            newlineIndex = this.pending.indexOf('\n');
+        }
+    }
+}
+//# sourceMappingURL=watch-session.js.map

package/dist/watch-session.js.map

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

package/dist/work-layout.d.ts

@@ -0,0 +1,198 @@
+/**
+ * The **work-layout** module: the SOLE source of every `work/...` path string,
+ * folder-name union/array, the item-scan predicate, and the prefix-task helpers
+ * used across `src/`.
+ *
+ * This is Phase 0 of the `folder-taxonomy-reorg-and-rename` prd — the de-risking
+ * checkpoint. EVERY raw work-path literal (`join(cwd, 'work', ...)`, `'work/<folder>'`,
+ * `'work/<folder>/'.length` prefix-tasks) and EVERY folder-name union/array that
+ * used to be scattered across ~70 files now routes through here. The NAMES are
+ * byte-identical to today (no rename, no behaviour change); only the SOURCE of the
+ * string has moved into this one module.
+ *
+ * The whole point of the seam: the LATER rename tasks flip the VALUES in
+ * {@link WORK_FOLDER_NAME} (and `git mv` the on-disk folders) and NOTHING ELSE.
+ * Call sites reference folders by their SYMBOLIC key (`'tasks-ready'`,
+ * `'specs-ready'`, …), never by a raw string, so a folder-VALUE flip never
+ * re-touches a single call site (a KEY rename, e.g. the prd→spec cutover below,
+ * is a mechanical relabel of the key literal at each site — behaviour-preserving).
+ *
+ * Domain note (crown-jewel invariant): a `work/` tree is a set of governance
+ * folders where "status IS the folder" — a CAS `git mv` between durable folders is
+ * the conflict-safe state machine. This module owns the folder NAMES that literally
+ * are that state machine, so it is deliberately the one place a careless rename can
+ * touch.
+ *
+ * The transient states (`in-progress`/`needs-attention`/`tasking`/`advancing`) are
+ * NOT folders — they are per-item lock-ref state (see `item-lock.ts`). A stray
+ * `in-progress` literal still referenced by some legacy/recovery readers routes
+ * through this module like any other folder, but is NOT part of the durable
+ * folder-as-status set.
+ */
+/**
+ * The repo-relative root of the `work/` governance tree. The single literal `'work'`
+ * the whole package shares — every path builder below is rooted here.
+ */
+export declare const WORK_ROOT: "work";
+/**
+ * Every work-folder SYMBOLIC KEY → its current on-disk folder NAME (byte-identical
+ * to today). This is the ONE place a folder name lives; the later taxonomy rename is
+ * a value-only flip of the right-hand side here.
+ *
+ * Folder kinds (kept here as a single registry, but their distinct roles matter):
+ *   - TASK lifecycle, the `tasks/` Kanban board: `tasks/backlog` (staging, key
+ *     `tasks-backlog`) → `tasks/ready` (the agent pool, key `tasks-ready`) →
+ *     `tasks/done` / `tasks/cancelled` (the PER-REGIME won't-proceed terminal, key
+ *     `cancelled`).
+ *   - SPEC lifecycle, the `specs/` regime: `specs/proposed` (staging, key
+ *     `specs-proposed`) → `specs/ready` (auto-task pool, key `specs-ready`) →
+ *     `specs/tasked` (tasked, resting, key `specs-tasked`) / `specs/dropped`
+ *     (the PER-REGIME won't-proceed terminal, key `specs-dropped`).
+ *   - The PER-REGIME won't-proceed terminals (`tasks/cancelled` + `specs/dropped`)
+ *     replace the previous shared top-level `work/dropped/`: a dropped task and a
+ *     dropped spec sharing a slug used to COLLIDE on one bare-slug
+ *     `work/dropped/<slug>.md`; namespacing each regime's terminal removes the
+ *     collision. A dropped OBSERVATION needs no terminal — notes leave by deletion.
+ *   - Capture buckets under the `notes/` umbrella (do NOT flow; leave by deletion):
+ *     `notes/observations` / `notes/ideas` / `notes/findings`.
+ *   - Top-level surfaces: `questions` (the "what needs me?" queue), `protocol`
+ *     (propagated protocol docs). NEITHER is folded under an umbrella.
+ *   - The stray transient `in-progress` still referenced by legacy/recovery readers
+ *     and `needs-attention` (both are really lock-ref state, NOT durable folders;
+ *     routed here only so no reader hand-writes the literal).
+ *
+ * NOTE on the prd→spec vocabulary cutover
+ * (`rename-spec-work-layout-and-folders`, migrate-batch 1 of
+ * `prd-to-spec-vocabulary-cutover-and-migration-command`): the spec-regime KEYS
+ * below now read in the `spec` vocabulary (`specs-proposed`/`specs-ready`/
+ * `specs-tasked`/`specs-dropped`) AND their VALUES flip to `work/specs/*` in
+ * lockstep with the on-disk `git mv work/prds/* → work/specs/*`. Unlike the earlier
+ * key-only relabel, this batch moves the folders too, so the KEY and VALUE change
+ * together and the self-renaming-folder guard stays green. The KEY rename is a
+ * mechanical relabel of the key literal at each call site (behaviour-preserving);
+ * the frontmatter `prd:` field (a DATA alias the migration command converts) is the
+ * one deliberate survivor; the `--specs-land-in` flag/`specsLandIn` config + the
+ * `Spec*` symbols were completed by the later batches + the contract task. The
+ * folder-as-status invariant is unchanged.
+ */
+export declare const WORK_FOLDER_NAME: {
+    readonly 'tasks-backlog': "tasks/backlog";
+    readonly 'tasks-ready': "tasks/ready";
+    readonly 'in-progress': "in-progress";
+    readonly 'needs-attention': "needs-attention";
+    readonly done: "tasks/done";
+    readonly cancelled: "tasks/cancelled";
+    readonly 'specs-proposed': "specs/proposed";
+    readonly 'specs-ready': "specs/ready";
+    readonly 'specs-tasked': "specs/tasked";
+    readonly 'specs-dropped': "specs/dropped";
+    readonly observations: "notes/observations";
+    readonly ideas: "notes/ideas";
+    readonly findings: "notes/findings";
+    readonly questions: "questions";
+    readonly protocol: "protocol";
+};
+/** The SYMBOLIC KEY of a work folder (stable across the later rename). */
+export type WorkFolderKey = keyof typeof WORK_FOLDER_NAME;
+/**
+ * Resolve a folder's current on-disk NAME from its symbolic key. The ONE accessor
+ * every other folder-name lookup derives from, so the rename flips it in lockstep.
+ */
+export declare function workFolderName(folder: WorkFolderKey): string;
+/**
+ * Absolute path of a work folder under a repo/cwd root:
+ * `<root>/work/<folder-name>`. Replaces every `join(cwd, 'work', '<folder>')` and
+ * `join(repoPath, 'work', folder)` call site.
+ */
+export declare function workFolderPath(root: string, folder: WorkFolderKey): string;
+/**
+ * Absolute path of a single item's `.md` file in a work folder:
+ * `<root>/work/<folder-name>/<slug>.md`. Replaces every
+ * `join(cwd, 'work', folder, `${slug}.md`)` call site. `slug` is the bare slug
+ * (the `.md` suffix is appended here).
+ */
+export declare function workItemPath(root: string, folder: WorkFolderKey, slug: string): string;
+/**
+ * REPO-RELATIVE path of a work folder: `work/<folder-name>` (no trailing slash, no
+ * root). The form used for `git mv` / `git`-relative paths and the staging/pool dir
+ * constants (`STAGED_TASKS_DIR`, etc.). Replaces raw `'work/<folder>'` literals.
+ */
+export declare function workFolderRel(folder: WorkFolderKey): string;
+/**
+ * REPO-RELATIVE path of a single item file: `work/<folder-name>/<basename>`. The
+ * `basename` is a full filename (caller decides whether it carries `.md`), matching
+ * the existing `join('work', folder, '<file>')` call sites that pass either a
+ * `${slug}.md` or a pre-suffixed name.
+ */
+export declare function workItemRel(folder: WorkFolderKey, basename: string): string;
+/**
+ * The REPO-RELATIVE folder PREFIX (WITH trailing slash): `work/<folder-name>/`. The
+ * form a reader matches with `startsWith(...)` and tasks off to recover a filename
+ * (see {@link stripWorkFolderPrefix}). Replaces hand-written `'work/<folder>/'`
+ * literals and their `.length` prefix-tasks.
+ */
+export declare function workFolderPrefix(folder: WorkFolderKey): string;
+/**
+ * Recover the filename portion of a repo-relative path that lives DIRECTLY under a
+ * work folder, by stripping its `work/<folder-name>/` prefix. Replaces the
+ * hand-written `path.slice('work/<folder>/'.length)` prefix-task. Returns
+ * `undefined` when `path` is not under that folder, so callers that already
+ * `startsWith`-guarded keep their exact behaviour (and callers that did not can
+ * branch on `undefined` instead of tasking a wrong length).
+ */
+export declare function stripWorkFolderPrefix(path: string, folder: WorkFolderKey): string | undefined;
+/**
+ * The ITEM-SCAN predicate: does this directory entry NAME count as a `work/` item?
+ * Defined ONCE here so no reader re-implements the `.md` filter. Case-insensitive
+ * on the extension, matching every existing `name.toLowerCase().endsWith('.md')`
+ * call site verbatim.
+ */
+export declare function isWorkItemFile(name: string): boolean;
+/**
+ * The TASK-RESOLUTION folders `resolveTask` (prompt.ts) walks, in precedence
+ * order: `in-progress` over `tasks-ready`, with `done` appended only behind the
+ * stranded-continue gate. Order is load-bearing — kept exactly as the original
+ * union/array. (`tasks-backlog` is NOT in this DEFAULT order: it is appended at
+ * the LOWEST priority ONLY behind the explicit `--allow-backlog` flag, prd
+ * `do-allow-backlog-drive-staged-tasks-without-promotion` — see
+ * {@link TaskResolutionFolder}.)
+ */
+export declare const TASK_RESOLUTION_FOLDERS: readonly ["in-progress", "tasks-ready", "done"];
+/**
+ * One of the folders a task can be RESOLVED from (prompt.ts `TaskFolder`): the
+ * default {@link TASK_RESOLUTION_FOLDERS} PLUS `tasks-backlog`, which is reachable
+ * ONLY behind the explicit `--allow-backlog` flag (never on a default resolution).
+ * Kept off the default-order array on purpose so no autonomous path resolves
+ * staging.
+ */
+export type TaskResolutionFolder = (typeof TASK_RESOLUTION_FOLDERS)[number] | 'tasks-backlog';
+/**
+ * The task LIFECYCLE folders a `task:<slug>` / lone-task `issue:` can reside
+ * in (spec-complete.ts + close-job.ts `TASK_FOLDERS`): `tasks-ready`, `in-progress`,
+ * `needs-attention`, `done`.
+ */
+export declare const TASK_LIFECYCLE_FOLDERS: readonly ["tasks-ready", "in-progress", "needs-attention", "done"];
+/** One of the task lifecycle folders (spec-complete.ts / close-job.ts). */
+export type TaskLifecycleFolder = (typeof TASK_LIFECYCLE_FOLDERS)[number];
+/**
+ * The DURABLE task-status folders the ledger lint / integration core treat as the
+ * one-slug-one-folder state machine: `tasks-ready`, `done`, `cancelled`
+ * (ledger-lint.ts + integration-core.ts `LEDGER_STATUS_FOLDERS`). The transient
+ * `in-progress`/`needs-attention`/`tasking` are NOT here (they are lock-ref state).
+ * `cancelled` is the task regime's won't-proceed terminal (the per-regime split
+ * of the previous shared `dropped/`); the spec regime's terminal `specs-dropped`
+ * is NOT here (this set is the TASK board's state machine, keyed by `tasks/`-slug,
+ * and a spec never co-resides with a task on the tasks board).
+ */
+export declare const LEDGER_STATUS_FOLDERS: readonly ["tasks-ready", "done", "cancelled"];
+/** One of the durable ledger status folders (ledger-lint.ts / integration-core.ts). */
+export type LedgerStatusFolder = (typeof LEDGER_STATUS_FOLDERS)[number];
+/**
+ * The SPEC-lifecycle folders an `issue:`-bearing spec / a tasked spec can reside
+ * in: `specs-ready` (source / pool), `specs-tasked` (tasked, resting) —
+ * close-job.ts `SPEC_FOLDERS`.
+ */
+export declare const SPEC_FOLDERS: readonly ["specs-ready", "specs-tasked"];
+/** One of the spec-lifecycle folders (close-job.ts / ledger-read.ts). */
+export type SpecFolder = (typeof SPEC_FOLDERS)[number];
+//# sourceMappingURL=work-layout.d.ts.map

package/dist/work-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-layout.d.ts","sourceRoot":"","sources":["../src/work-layout.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAG,MAAe,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;CAgBnB,CAAC;AAEX,0EAA0E;AAC1E,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC3B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,MAAM,GACV,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,GACnB,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,iDAIS,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAC7B,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,GACxC,eAAe,CAAC;AAEnB;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,oEAKU,CAAC;AAE9C,2EAA2E;AAC3E,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,+CAIW,CAAC;AAE9C,uFAAuF;AACvF,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,YAAY,0CAGoB,CAAC;AAE9C,yEAAyE;AACzE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC"}