@alisio/plugin-swarm 0.0.0-stage → 0.1.1

package/dist/doctor.js

@@ -0,0 +1,108 @@
+import { execFile } from "node:child_process";
+import { access, constants } from "node:fs/promises";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/** Minimum git: `git init --initial-branch` needs 2.28; worktrees and merge-base need less. */
+const MIN_GIT = [2, 28];
+const MIN_NODE = [22, 16];
+export const defaultDoctorDeps = {
+    async exec(command, args) {
+        const { stdout } = await execFileAsync(command, args, { encoding: "utf8", timeout: 5000 });
+        return stdout;
+    },
+    async writable(path) {
+        try {
+            await access(path, constants.W_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+};
+export function parseGitVersion(text) {
+    const match = /git version (\d+)\.(\d+)(?:\.(\d+))?/.exec(text);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3] ?? 0)] : undefined;
+}
+const atLeast = (version, minimum) => version[0] > minimum[0] ||
+    (version[0] === minimum[0] && version[1] >= minimum[1]);
+export async function runDoctor(deps) {
+    const items = [];
+    const node = deps.nodeVersion.split(".").map(Number);
+    items.push({
+        id: "node",
+        label: "Node.js",
+        status: atLeast(node, MIN_NODE) ? "ok" : "missing",
+        detail: atLeast(node, MIN_NODE)
+            ? deps.nodeVersion
+            : `${deps.nodeVersion} found; Node ${MIN_NODE.join(".")} or newer is required`,
+    });
+    try {
+        const version = parseGitVersion(await deps.exec("git", ["--version"]));
+        if (!version) {
+            items.push({
+                id: "git",
+                label: "git",
+                status: "missing",
+                detail: "could not read the git version",
+            });
+        }
+        else if (!atLeast(version, MIN_GIT)) {
+            items.push({
+                id: "git",
+                label: "git",
+                status: "missing",
+                detail: `${version.join(".")} found; git ${MIN_GIT.join(".")} or newer is required for worktrees and --initial-branch`,
+            });
+        }
+        else {
+            items.push({ id: "git", label: "git", status: "ok", detail: version.join(".") });
+        }
+    }
+    catch {
+        items.push({ id: "git", label: "git", status: "missing", detail: "git was not found on PATH" });
+    }
+    const writable = await deps.writable(deps.workspace);
+    items.push({
+        id: "workspace",
+        label: "Workspace",
+        status: writable ? "ok" : "missing",
+        detail: writable ? "writable" : "the workspace directory is not writable",
+    });
+    items.push({
+        id: "forge",
+        label: "Forge",
+        status: deps.initialised ? "ok" : "warn",
+        detail: deps.initialised ? "initialised" : "not initialised; run /swarm:init",
+    });
+    const commands = [
+        ...new Set(Object.values(deps.toolchain.commands).map((command) => command?.argv[0])),
+    ];
+    for (const command of commands) {
+        try {
+            await deps.exec(command, ["--version"]);
+            items.push({
+                id: `toolchain:${command}`,
+                label: `${deps.toolchain.id}: ${command}`,
+                status: "ok",
+                detail: "found",
+            });
+        }
+        catch {
+            items.push({
+                id: `toolchain:${command}`,
+                label: `${deps.toolchain.id}: ${command}`,
+                status: "warn",
+                detail: "not found; gates that use it cannot run",
+            });
+        }
+    }
+    return { items, ok: items.every((item) => item.status !== "missing") };
+}
+export function formatDoctor(report) {
+    return [
+        report.ok ? "Swarm doctor: ready" : "Swarm doctor: problems found",
+        ...report.items.map((item) => `[${item.status}] ${item.label}: ${item.detail}`),
+    ].join("\n");
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAwB1C,+FAA+F;AAC/F,MAAM,OAAO,GAAqB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC1C,MAAM,QAAQ,GAAqB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AAE5C,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,KAAK,CAAC,IAAI,CAAC,OAAe,EAAE,IAAc;QACxC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3F,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,KAAK,CAAC,QAAQ,CAAC,IAAY;QACzB,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;YACnC,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF,CAAC;AAEF,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,KAAK,GAAG,sCAAsC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACzF,CAAC;AAED,MAAM,OAAO,GAAG,CAAC,OAAiB,EAAE,OAAyB,EAAW,EAAE,CACvE,OAAO,CAAC,CAAC,CAAY,GAAG,OAAO,CAAC,CAAC,CAAC;IACnC,CAAE,OAAO,CAAC,CAAC,CAAY,KAAK,OAAO,CAAC,CAAC,CAAC,IAAK,OAAO,CAAC,CAAC,CAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAElF,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAgB;IAC9C,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACrD,KAAK,CAAC,IAAI,CAAC;QACT,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,SAAS;QAChB,MAAM,EAAE,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;QAClD,MAAM,EAAE,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;YAC7B,CAAC,CAAC,IAAI,CAAC,WAAW;YAClB,CAAC,CAAC,GAAG,IAAI,CAAC,WAAW,gBAAgB,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,uBAAuB;KACjF,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;QACvE,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,KAAK,CAAC,IAAI,CAAC;gBACT,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,SAAS;gBACjB,MAAM,EAAE,gCAAgC;aACzC,CAAC,CAAC;QACL,CAAC;aAAM,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;YACtC,KAAK,CAAC,IAAI,CAAC;gBACT,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,SAAS;gBACjB,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,eAAe,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,0DAA0D;aACvH,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnF,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,2BAA2B,EAAE,CAAC,CAAC;IAClG,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACrD,KAAK,CAAC,IAAI,CAAC;QACT,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,WAAW;QAClB,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;QACnC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,yCAAyC;KAC1E,CAAC,CAAC;IAEH,KAAK,CAAC,IAAI,CAAC;QACT,EAAE,EAAE,OAAO;QACX,KAAK,EAAE,OAAO;QACd,MAAM,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM;QACxC,MAAM,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,kCAAkC;KAC9E,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG;QACf,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAW,CAAC,CAAC;KAChG,CAAC;IACF,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;YACxC,KAAK,CAAC,IAAI,CAAC;gBACT,EAAE,EAAE,aAAa,OAAO,EAAE;gBAC1B,KAAK,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,OAAO,EAAE;gBACzC,MAAM,EAAE,IAAI;gBACZ,MAAM,EAAE,OAAO;aAChB,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,KAAK,CAAC,IAAI,CAAC;gBACT,EAAE,EAAE,aAAa,OAAO,EAAE;gBAC1B,KAAK,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,OAAO,EAAE;gBACzC,MAAM,EAAE,MAAM;gBACd,MAAM,EAAE,yCAAyC;aAClD,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,EAAE,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,OAAO;QACL,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,8BAA8B;QAClE,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;KAChF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/domain/attention.d.ts

@@ -0,0 +1,20 @@
+import type { Board } from "./task.js";
+import type { TaskState } from "./taskstate.js";
+export type AttentionKind = "approval" | "clarification" | "blocked" | "gate-failed" | "decision";
+export interface AttentionItem {
+    id: string;
+    kind: AttentionKind;
+    project: string;
+    task: string;
+    createdAt: string;
+    /** Operator actions allowed on this item. */
+    actions: string[];
+    /** The question, reason or findings behind the item, when known. Always rendered as text. */
+    detail?: string;
+}
+/**
+ * Items that need a human, derived from the board and the persisted task states (holds and
+ * approval comments). Approve is not offered while per-document comments exist (spec 8.3).
+ */
+export declare function deriveAttention(project: string, board: Board, states?: ReadonlyMap<string, TaskState>): AttentionItem[];
+//# sourceMappingURL=attention.d.ts.map

package/dist/domain/attention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attention.d.ts","sourceRoot":"","sources":["../../src/domain/attention.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAc,MAAM,WAAW,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,eAAe,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,CAAC;AAElG,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AASD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,KAAK,EACZ,MAAM,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,GACtC,aAAa,EAAE,CA0BjB"}

package/dist/domain/attention.js

@@ -0,0 +1,41 @@
+const table = {
+    waiting_approval: { kind: "approval", actions: ["documents", "approve", "reject"] },
+    clarifying: { kind: "clarification", actions: ["answer"] },
+    blocked: { kind: "blocked", actions: ["retry", "delete", "accept"] },
+    rejected: { kind: "decision", actions: ["retry", "delete", "accept"] },
+};
+/**
+ * Items that need a human, derived from the board and the persisted task states (holds and
+ * approval comments). Approve is not offered while per-document comments exist (spec 8.3).
+ */
+export function deriveAttention(project, board, states) {
+    const items = [];
+    for (const card of board.tasks) {
+        const entry = table[card.status];
+        if (!entry)
+            continue;
+        const state = states?.get(card.taskId);
+        let kind = entry.kind;
+        let actions = [...entry.actions];
+        let detail;
+        if (card.status === "blocked" && state?.hold?.kind === "gate-failed")
+            kind = "gate-failed";
+        if (card.status === "waiting_approval" && state && state.comments.length > 0) {
+            actions = ["documents", "comment", "reject"];
+            detail = `${state.comments.length} comment(s) must be resolved before approving`;
+        }
+        if (state?.hold && card.status !== "waiting_approval")
+            detail = state.hold.text;
+        items.push({
+            id: `${kind}:${project}:${card.name}`,
+            kind,
+            project,
+            task: card.name,
+            createdAt: card.updatedAt,
+            actions,
+            ...(detail !== undefined ? { detail } : {}),
+        });
+    }
+    return items;
+}
+//# sourceMappingURL=attention.js.map

package/dist/domain/attention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attention.js","sourceRoot":"","sources":["../../src/domain/attention.ts"],"names":[],"mappings":"AAiBA,MAAM,KAAK,GAA4E;IACrF,gBAAgB,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE;IACnF,UAAU,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,QAAQ,CAAC,EAAE;IAC1D,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE;IACpE,QAAQ,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE;CACvE,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAe,EACf,KAAY,EACZ,MAAuC;IAEvC,MAAM,KAAK,GAAoB,EAAE,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,MAAM,KAAK,GAAG,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACtB,IAAI,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;QACjC,IAAI,MAA0B,CAAC;QAC/B,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,EAAE,IAAI,EAAE,IAAI,KAAK,aAAa;YAAE,IAAI,GAAG,aAAa,CAAC;QAC3F,IAAI,IAAI,CAAC,MAAM,KAAK,kBAAkB,IAAI,KAAK,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7E,OAAO,GAAG,CAAC,WAAW,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;YAC7C,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,+CAA+C,CAAC;QACnF,CAAC;QACD,IAAI,KAAK,EAAE,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,kBAAkB;YAAE,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;QAChF,KAAK,CAAC,IAAI,CAAC;YACT,EAAE,EAAE,GAAG,IAAI,IAAI,OAAO,IAAI,IAAI,CAAC,IAAI,EAAE;YACrC,IAAI;YACJ,OAAO;YACP,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,OAAO;YACP,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5C,CAAC,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/domain/envelope.d.ts

@@ -0,0 +1,37 @@
+/** Child output envelopes (spec 4.4). Strict: invalid output is rejected, never repaired. */
+export interface Evidence {
+    requirement: string;
+    proof: string;
+}
+export type Envelope = {
+    schemaVersion: 1;
+    kind: "handoff";
+    commit: string;
+    summary: string;
+    evidence: Evidence[];
+} | {
+    schemaVersion: 1;
+    kind: "needs_clarification";
+    question: string;
+} | {
+    schemaVersion: 1;
+    kind: "blocked";
+    reason: string;
+} | {
+    schemaVersion: 1;
+    kind: "note";
+    message: string;
+};
+export type EnvelopeResult = {
+    ok: true;
+    envelope: Envelope;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface ParseOptions {
+    /** The child hit its turn limit: its text is partial and must not be trusted. */
+    turnsExceeded?: boolean;
+}
+export declare function parseEnvelope(output: string, options?: ParseOptions): EnvelopeResult;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/domain/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/domain/envelope.ts"],"names":[],"mappings":"AAEA,6FAA6F;AAC7F,MAAM,WAAW,QAAQ;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,QAAQ,GAChB;IAAE,aAAa,EAAE,CAAC,CAAC;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,QAAQ,EAAE,CAAA;CAAE,GAC5F;IAAE,aAAa,EAAE,CAAC,CAAC;IAAC,IAAI,EAAE,qBAAqB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACnE;IAAE,aAAa,EAAE,CAAC,CAAC;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,aAAa,EAAE,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9F,MAAM,WAAW,YAAY;IAC3B,iFAAiF;IACjF,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AA8BD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,cAAc,CAwExF"}

package/dist/domain/envelope.js

@@ -0,0 +1,106 @@
+import { validateCommit } from "./identifiers.js";
+const MAX_BYTES = 64 * 1024;
+const MAX_TEXT = 2000;
+const MAX_NOTE = 80;
+const MAX_EVIDENCE = 50;
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const fail = (reason) => ({ ok: false, reason });
+function onlyKeys(value, allowed, label) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key))
+            throw new Error(`Unknown key "${key}" in ${label}`);
+    }
+}
+function text(value, label, max) {
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`Invalid ${label}: expected non-empty text`);
+    if (value.length > max)
+        throw new Error(`Invalid ${label}: longer than ${max} characters`);
+    return value;
+}
+function unfence(raw) {
+    const fenced = /^```(?:json)?\n([\s\S]*?)\n```$/.exec(raw);
+    return fenced ? fenced[1].trim() : raw;
+}
+export function parseEnvelope(output, options = {}) {
+    if (options.turnsExceeded)
+        return fail("The run exceeded its turn limit; output is partial");
+    const raw = (output ?? "").trim();
+    if (!raw)
+        return fail("Empty output: expected one JSON envelope");
+    if (Buffer.byteLength(raw) > MAX_BYTES)
+        return fail("Output too large for an envelope");
+    let value;
+    try {
+        value = JSON.parse(unfence(raw));
+    }
+    catch {
+        return fail("Output is not a single valid JSON document");
+    }
+    if (!isRecord(value))
+        return fail("Envelope must be a JSON object");
+    try {
+        if (value.schemaVersion !== 1)
+            throw new Error("Unsupported envelope schemaVersion (expected 1)");
+        switch (value.kind) {
+            case "handoff": {
+                onlyKeys(value, ["schemaVersion", "kind", "commit", "summary", "evidence"], "handoff");
+                const commit = validateCommit(value.commit);
+                const summary = text(value.summary, "summary", MAX_TEXT);
+                if (!Array.isArray(value.evidence) || value.evidence.length === 0) {
+                    throw new Error("Invalid evidence: provide at least one requirement/proof pair");
+                }
+                if (value.evidence.length > MAX_EVIDENCE)
+                    throw new Error("Invalid evidence: too many entries");
+                const evidence = value.evidence.map((item) => {
+                    if (!isRecord(item))
+                        throw new Error("Invalid evidence entry: expected an object");
+                    onlyKeys(item, ["requirement", "proof"], "evidence entry");
+                    return {
+                        requirement: text(item.requirement, "requirement", MAX_TEXT),
+                        proof: text(item.proof, "proof", MAX_TEXT),
+                    };
+                });
+                return {
+                    ok: true,
+                    envelope: { schemaVersion: 1, kind: "handoff", commit, summary, evidence },
+                };
+            }
+            case "needs_clarification": {
+                onlyKeys(value, ["schemaVersion", "kind", "question"], "needs_clarification");
+                return {
+                    ok: true,
+                    envelope: {
+                        schemaVersion: 1,
+                        kind: "needs_clarification",
+                        question: text(value.question, "question", MAX_TEXT),
+                    },
+                };
+            }
+            case "blocked": {
+                onlyKeys(value, ["schemaVersion", "kind", "reason"], "blocked");
+                return {
+                    ok: true,
+                    envelope: {
+                        schemaVersion: 1,
+                        kind: "blocked",
+                        reason: text(value.reason, "reason", MAX_TEXT),
+                    },
+                };
+            }
+            case "note": {
+                onlyKeys(value, ["schemaVersion", "kind", "message"], "note");
+                const message = text(value.message, "message", MAX_NOTE);
+                if (/[\r\n]/.test(message))
+                    throw new Error("Invalid message: a note is a single line");
+                return { ok: true, envelope: { schemaVersion: 1, kind: "note", message } };
+            }
+            default:
+                throw new Error("Unknown envelope kind");
+        }
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : String(error));
+    }
+}
+//# sourceMappingURL=envelope.js.map

package/dist/domain/envelope.js.map

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

package/dist/domain/handoff.d.ts

@@ -0,0 +1,57 @@
+/** The phantom sender of a new task (spec 8.2). Never a real role. */
+export declare const PHANTOM_SENDER = "(New Task)";
+export type HandoffType = "git_handoff" | "note";
+export interface Handoff {
+    id: string;
+    from: string;
+    to: string[];
+    priority: number;
+    type: HandoffType;
+    task: string;
+    taskId: string;
+    commit?: string;
+    taskBaseCommit?: string;
+    approved: boolean;
+    nonForwarding: boolean;
+    createdAt: string;
+    enqueuedAt?: string;
+    dequeuedAt?: string;
+    completedAt?: string;
+    body: string;
+}
+export type InboxBox = "new" | "in_process" | "completed";
+export type HandoffLocation = {
+    kind: "outbox" | "sent" | "failed" | "audit_pending" | "pending_approval" | "join_pending";
+    role: string;
+} | {
+    kind: "inbox";
+    role: string;
+    box: InboxBox;
+};
+export interface StoredHandoff {
+    handoff: Handoff;
+    location: HandoffLocation;
+    fileName: string;
+}
+/** Header block, one blank line, then the generated body (same shape as upstream, human-readable). */
+export declare function serializeHandoff(handoff: Handoff): string;
+/** Strict parse. Handoff files are never trusted without revalidation on load. */
+export declare function parseHandoff(text: string): Handoff;
+export interface HandoffNameParts {
+    priority: number;
+    createdAt: string;
+    seq: number;
+    from: string;
+    to: string[];
+}
+/** `<NN>_<UTC>_<seq>_from_<sender>_to_<r1_r2>.handoff` */
+export declare function handoffFileName(parts: HandoffNameParts): string;
+export interface ParsedHandoffName {
+    priority: number;
+    stamp: string;
+    seq: number;
+    from: string;
+    to: string[];
+}
+export declare function parseHandoffFileName(name: string): ParsedHandoffName | undefined;
+//# sourceMappingURL=handoff.d.ts.map

package/dist/domain/handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../../src/domain/handoff.ts"],"names":[],"mappings":"AAEA,sEAAsE;AACtE,eAAO,MAAM,cAAc,eAAe,CAAC;AAG3C,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,YAAY,GAAG,WAAW,CAAC;AAC1D,MAAM,MAAM,eAAe,GACvB;IACE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,eAAe,GAAG,kBAAkB,GAAG,cAAc,CAAC;IAC3F,IAAI,EAAE,MAAM,CAAC;CACd,GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEnD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,eAAe,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAgDD,sGAAsG;AACtG,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAqBzD;AAsCD,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CA6ClD;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,EAAE,CAAC;CACd;AAID,0DAA0D;AAC1D,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAI/D;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,EAAE,CAAC;CACd;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAchF"}

package/dist/domain/handoff.js

@@ -0,0 +1,191 @@
+import { validateCommit, validateRole, validateTaskId, validateTaskName } from "./identifiers.js";
+/** The phantom sender of a new task (spec 8.2). Never a real role. */
+export const PHANTOM_SENDER = "(New Task)";
+const PHANTOM_TOKEN = "new-task";
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const optionalStamps = [
+    ["enqueued_at", "enqueuedAt"],
+    ["dequeued_at", "dequeuedAt"],
+    ["completed_at", "completedAt"],
+];
+const singleLine = (value, label) => {
+    if (/[\r\n\0]/.test(value))
+        throw new Error(`Invalid ${label}: line breaks are not allowed`);
+    return value;
+};
+const validSender = (from) => (from === PHANTOM_SENDER ? from : validateRole(from));
+function isoStamp(value, label) {
+    if (!/^\d{4}-\d{2}-\d{2}T[\d:.]+Z$/.test(value) || Number.isNaN(Date.parse(value))) {
+        throw new Error(`Invalid ${label}: expected an ISO-8601 UTC timestamp`);
+    }
+    return value;
+}
+function checkHandoff(handoff) {
+    if (!uuidPattern.test(handoff.id))
+        throw new Error("Invalid id: expected a UUID");
+    validSender(handoff.from);
+    if (handoff.to.length === 0)
+        throw new Error("Invalid to: at least one recipient is required");
+    for (const role of handoff.to)
+        validateRole(role);
+    if (!Number.isInteger(handoff.priority) || handoff.priority < 0 || handoff.priority > 99) {
+        throw new Error("Invalid priority: expected an integer from 0 to 99");
+    }
+    if (handoff.type !== "git_handoff" && handoff.type !== "note") {
+        throw new Error("Invalid type: expected git_handoff or note");
+    }
+    validateTaskName(handoff.task);
+    validateTaskId(handoff.taskId);
+    if (handoff.type === "git_handoff" && handoff.commit === undefined) {
+        throw new Error("A git_handoff needs a commit");
+    }
+    if (handoff.commit !== undefined)
+        validateCommit(handoff.commit);
+    if (handoff.taskBaseCommit !== undefined)
+        validateCommit(handoff.taskBaseCommit);
+    isoStamp(handoff.createdAt, "created_at");
+    for (const [, field] of optionalStamps) {
+        const value = handoff[field];
+        if (value !== undefined)
+            isoStamp(value, field);
+    }
+}
+/** Header block, one blank line, then the generated body (same shape as upstream, human-readable). */
+export function serializeHandoff(handoff) {
+    checkHandoff(handoff);
+    const lines = [
+        `id: ${handoff.id}`,
+        `from: ${singleLine(handoff.from, "from")}`,
+        `to: ${handoff.to.map((role) => singleLine(role, "to")).join(",")}`,
+        `priority: ${handoff.priority}`,
+        `type: ${handoff.type}`,
+        `task: ${singleLine(handoff.task, "task")}`,
+        `task_id: ${handoff.taskId}`,
+    ];
+    if (handoff.commit !== undefined)
+        lines.push(`commit: ${handoff.commit}`);
+    if (handoff.taskBaseCommit !== undefined)
+        lines.push(`task_base_commit: ${handoff.taskBaseCommit}`);
+    lines.push(`approved: ${handoff.approved}`, `non-forwarding: ${handoff.nonForwarding}`);
+    lines.push(`created_at: ${handoff.createdAt}`);
+    for (const [key, field] of optionalStamps) {
+        const value = handoff[field];
+        if (value !== undefined)
+            lines.push(`${key}: ${value}`);
+    }
+    return `${lines.join("\n")}\n\n${handoff.body}`;
+}
+const headerKeys = [
+    "id",
+    "from",
+    "to",
+    "priority",
+    "type",
+    "task",
+    "task_id",
+    "commit",
+    "task_base_commit",
+    "approved",
+    "non-forwarding",
+    "created_at",
+    "enqueued_at",
+    "dequeued_at",
+    "completed_at",
+];
+const requiredKeys = [
+    "id",
+    "from",
+    "to",
+    "priority",
+    "type",
+    "task",
+    "task_id",
+    "approved",
+    "non-forwarding",
+    "created_at",
+];
+function bool(value, label) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    throw new Error(`Invalid ${label}: expected true or false`);
+}
+/** Strict parse. Handoff files are never trusted without revalidation on load. */
+export function parseHandoff(text) {
+    const normalized = text.replace(/\r\n/g, "\n");
+    const split = normalized.indexOf("\n\n");
+    if (split < 0)
+        throw new Error("Malformed handoff: missing the blank line after the header");
+    const header = new Map();
+    for (const line of normalized.slice(0, split).split("\n")) {
+        const match = /^([a-z_-]+): ?(.*)$/.exec(line);
+        if (!match)
+            throw new Error(`Malformed handoff header line: ${JSON.stringify(line.slice(0, 40))}`);
+        const key = match[1];
+        if (!headerKeys.includes(key))
+            throw new Error(`Unknown header "${key}"`);
+        if (header.has(key))
+            throw new Error(`Duplicate header "${key}"`);
+        header.set(key, match[2]);
+    }
+    for (const key of requiredKeys) {
+        if (!header.has(key))
+            throw new Error(`Missing header "${key}"`);
+    }
+    const get = (key) => header.get(key);
+    const priority = Number(get("priority"));
+    if (!/^\d{1,2}$/.test(get("priority")))
+        throw new Error("Invalid priority: expected an integer");
+    const type = get("type");
+    if (type !== "git_handoff" && type !== "note")
+        throw new Error("Invalid type in handoff header");
+    const handoff = {
+        id: get("id"),
+        from: get("from"),
+        to: get("to")
+            .split(",")
+            .map((role) => role.trim())
+            .filter(Boolean),
+        priority,
+        type,
+        task: get("task"),
+        taskId: get("task_id"),
+        approved: bool(get("approved"), "approved"),
+        nonForwarding: bool(get("non-forwarding"), "non-forwarding"),
+        createdAt: get("created_at"),
+        body: normalized.slice(split + 2),
+    };
+    if (header.has("commit"))
+        handoff.commit = get("commit");
+    if (header.has("task_base_commit"))
+        handoff.taskBaseCommit = get("task_base_commit");
+    for (const [key, field] of optionalStamps) {
+        if (header.has(key))
+            handoff[field] = get(key);
+    }
+    checkHandoff(handoff);
+    return handoff;
+}
+const compactStamp = (iso) => `${iso.replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z")}`;
+/** `<NN>_<UTC>_<seq>_from_<sender>_to_<r1_r2>.handoff` */
+export function handoffFileName(parts) {
+    const sender = parts.from === PHANTOM_SENDER ? PHANTOM_TOKEN : validateRole(parts.from);
+    for (const role of parts.to)
+        validateRole(role);
+    return `${String(parts.priority).padStart(2, "0")}_${compactStamp(isoStamp(parts.createdAt, "created_at"))}_${String(parts.seq).padStart(4, "0")}_from_${sender}_to_${parts.to.join("_")}.handoff`;
+}
+export function parseHandoffFileName(name) {
+    const match = /^(\d{2})_(\d{8}T\d{6}Z)_(\d{4,})_from_([a-z][a-z0-9-]{0,23})_to_([a-z][a-z0-9-]{0,23}(?:_[a-z][a-z0-9-]{0,23})*)\.handoff$/.exec(name);
+    if (!match)
+        return undefined;
+    const sender = match[4];
+    return {
+        priority: Number(match[1]),
+        stamp: match[2],
+        seq: Number(match[3]),
+        from: sender === PHANTOM_TOKEN ? PHANTOM_SENDER : sender,
+        to: match[5].split("_"),
+    };
+}
+//# sourceMappingURL=handoff.js.map

package/dist/domain/handoff.js.map

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

package/dist/domain/identifiers.d.ts

@@ -0,0 +1,18 @@
+/** Identifier rules (spec 4.1). Every identifier is untrusted input and validated at each boundary. */
+export declare const projectNamePattern: RegExp;
+export declare const taskNamePattern: RegExp;
+export declare const rolePattern: RegExp;
+export declare const taskIdPattern: RegExp;
+export declare const commitPattern: RegExp;
+export declare function validateProjectName(name: string): string;
+export declare function validateTaskName(name: string): string;
+export declare function validateRole(role: string): string;
+export declare function validateTaskId(taskId: string): string;
+export declare function validateCommit(commit: string): string;
+/** Derive a task slug from free-form text. May return an empty string when nothing is usable. */
+export declare function slugify(text: string): string;
+/** `YYYYMMDDTHHMMSSffffffZ-<slug>`; `sequence` (0-999) disambiguates ids minted in one millisecond. */
+export declare function makeTaskId(now: Date, slug: string, sequence?: number): string;
+/** A relative path made of plain segments: no absolute, drive, backslash, empty, `.` or `..` parts. */
+export declare function assertRelativePath(path: string): string;
+//# sourceMappingURL=identifiers.d.ts.map

package/dist/domain/identifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifiers.d.ts","sourceRoot":"","sources":["../../src/domain/identifiers.ts"],"names":[],"mappings":"AAAA,uGAAuG;AAEvG,eAAO,MAAM,kBAAkB,QAA8B,CAAC;AAC9D,eAAO,MAAM,eAAe,QAA8B,CAAC;AAC3D,eAAO,MAAM,WAAW,QAA2B,CAAC;AACpD,eAAO,MAAM,aAAa,QAA4C,CAAC;AACvE,eAAO,MAAM,aAAa,QAAmB,CAAC;AAE9C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOxD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOrD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOjD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKrD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKrD;AAED,iGAAiG;AACjG,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO5C;AAED,uGAAuG;AACvG,wBAAgB,UAAU,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CASxE;AAED,uGAAuG;AACvG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAavD"}