@deftai/directive 0.126.2 → 0.128.0

package/dist/story-ready-fixtures.js

@@ -1,137 +0,0 @@
-/** Test fixtures extracted from legacy parity harness (#2083). */
-import { execFileSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-function writeVbrief(root, rel, status = "running", folder = "active") {
-    const full = join(root, "xbrief", folder, rel);
-    mkdirSync(dirname(full), { recursive: true });
-    const payload = {
-        plan: { status, title: "T", items: [] },
-        xBRIEFInfo: { version: "0.8" },
-    };
-    writeFileSync(full, `${JSON.stringify(payload)}\n`, "utf8");
-}
-function renderAllocation(fields) {
-    const lines = ["Dispatch envelope.", "", "## Allocation context", ""];
-    for (const [key, value] of Object.entries(fields)) {
-        lines.push(`- ${key}: ${value === null ? "null" : value}`);
-    }
-    lines.push("", "## Next section", "- trailing: ignored");
-    return lines.join("\n");
-}
-const VALID_COHORT = {
-    allocation_plan_id: "orchestrator-run-019e80bd",
-    batching_rationale: "Three disjoint-file-scope stories from #1378.",
-    cohort_vbriefs: "[xbrief/active/a.json, xbrief/active/b.json]",
-    dispatch_kind: "swarm-cohort",
-    operator_approval_evidence: "user directive 2026-06-01T02:26Z",
-};
-/** Scenarios exercised by the parity harness (mirrors Python contract cases). */
-export const PARITY_SCENARIOS = [
-    {
-        name: "clean-active-running-solo",
-        vbriefRel: "2026-06-01-story.xbrief.json",
-        envelopeRel: null,
-    },
-    {
-        name: "dirty-tree",
-        vbriefRel: "2026-06-01-story.xbrief.json",
-        envelopeRel: null,
-        dirty: true,
-    },
-    {
-        name: "non-running-vbrief",
-        vbriefRel: "2026-06-01-pending.xbrief.json",
-        vbriefStatus: "approved",
-        envelopeRel: null,
-    },
-    {
-        name: "satisfied-swarm-cohort",
-        vbriefRel: "2026-06-01-story.xbrief.json",
-        envelopeRel: "envelope-cohort.md",
-    },
-    {
-        name: "malformed-allocation",
-        vbriefRel: "2026-06-01-story.xbrief.json",
-        envelopeRel: "envelope-bad.md",
-    },
-];
-function gitCommit(cwd, message) {
-    execFileSync("git", ["commit", "-q", "-m", message], {
-        cwd,
-        env: {
-            ...process.env,
-            GIT_AUTHOR_NAME: "deft-parity",
-            GIT_AUTHOR_EMAIL: "parity@test.local",
-            GIT_COMMITTER_NAME: "deft-parity",
-            GIT_COMMITTER_EMAIL: "parity@test.local",
-        },
-    });
-}
-/** Normalise gate message for comparison (trim, collapse whitespace). */
-export function normaliseMessage(stdout, stderr, exitCode) {
-    const raw = exitCode === 0 ? stdout : stderr;
-    return raw.trim().replace(/\s+/g, " ");
-}
-/** Build a fixture repo for one scenario; return repo root + vbrief absolute path. */
-export function buildScenarioRepo(scenario) {
-    const root = mkdtempSync(join(tmpdir(), "deft-story-ready-parity-"));
-    const vbriefName = scenario.vbriefRel;
-    const status = scenario.vbriefStatus ?? "running";
-    writeVbrief(root, vbriefName, status);
-    if (scenario.dirty) {
-        writeFileSync(join(root, "scratch.txt"), "dirty\n", "utf8");
-    }
-    let envelopePath = null;
-    if (scenario.envelopeRel === "envelope-cohort.md") {
-        envelopePath = join(root, scenario.envelopeRel);
-        writeFileSync(envelopePath, renderAllocation(VALID_COHORT), "utf8");
-    }
-    else if (scenario.envelopeRel === "envelope-bad.md") {
-        envelopePath = join(root, scenario.envelopeRel);
-        const bad = { ...VALID_COHORT };
-        delete bad.dispatch_kind;
-        writeFileSync(envelopePath, renderAllocation(bad), "utf8");
-    }
-    execFileSync("git", ["init", "-q"], { cwd: root });
-    execFileSync("git", ["add", "-A"], { cwd: root });
-    if (!scenario.dirty) {
-        gitCommit(root, "init");
-    }
-    const vbriefPath = join(root, "xbrief", "active", vbriefName);
-    return { root, vbriefPath, envelopePath };
-}
-/** Diff python vs TS gate outputs across all parity scenarios. */
-export function diffParity(python, ts) {
-    const pythonMessage = normaliseMessage(python.stdout, python.stderr, python.exitCode);
-    const tsMessage = normaliseMessage(ts.stdout, ts.stderr, ts.exitCode);
-    return {
-        exitMismatch: python.exitCode !== ts.exitCode,
-        messageMismatch: pythonMessage !== tsMessage,
-        pythonMessage,
-        tsMessage,
-    };
-}
-/** Run all parity scenarios and return a structured result. */
-/** Render a human-readable parity report (exported for unit tests). */
-export function renderReport(result) {
-    if (result.ok) {
-        return `verify_story_ready parity: CLEAN -- Python and TS agree on ${result.scenarios.length} scenario(s).`;
-    }
-    const lines = ["verify_story_ready parity: DIVERGENCE"];
-    for (const s of result.scenarios) {
-        if (s.exitMismatch || s.messageMismatch) {
-            lines.push(`  scenario: ${s.name}`);
-            if (s.exitMismatch) {
-                lines.push(`    exit mismatch: python=${s.pythonExit} ts=${s.tsExit}`);
-            }
-            if (s.messageMismatch) {
-                lines.push(`    python: ${s.pythonMessage}`);
-                lines.push(`    ts:     ${s.tsMessage}`);
-            }
-        }
-    }
-    return lines.join("\n");
-}
-//# sourceMappingURL=story-ready-fixtures.js.map

package/dist/subagent-monitor.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export declare function run(argv: string[]): number;
-//# sourceMappingURL=subagent-monitor.d.ts.map

package/dist/subagent-monitor.js

@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-import { fileURLToPath } from "node:url";
-import { cmdSubagentMonitor } from "@deftai/directive-core/orchestration";
-export function run(argv) {
-    return cmdSubagentMonitor(argv);
-}
-if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
-    process.exit(run(process.argv.slice(2)));
-}
-//# sourceMappingURL=subagent-monitor.js.map

package/dist/subagent-pre-cancel.d.ts

@@ -1,21 +0,0 @@
-#!/usr/bin/env node
-export declare const SUBAGENT_PRE_CANCEL_HELP = "subagent:pre-cancel \u2014 query-before-cancel gate (#5278)\n\nUsage:\n  task subagent:pre-cancel -- --agent <id> --canceller-id <id> [options]\n\nExit 0 only when one ordered branch clears:\n  (a) canceller-authored status steer (kind note|correction) + matching ack\n      OR observed first-seen window (default 3 minutes; PA-18 forward skew only)\n  (b) heartbeat STALE/missing under startup grace from --dispatch-started-at\n  (c) --force --reason <text>\n\nOptions:\n  --agent ID                 Target child agent_id (required)\n  --canceller-id ID          Canceller identity; must match steer writer_id for (a)\n  --target-id PATH           Worktree root (resolves steer/scratch/first-seen under it)\n  --steer-dir PATH           Steer inbox dir (default: <cwd|target>/.deft-scratch/subagent-steer)\n  --scratch-dir PATH         Heartbeat dir (default: <cwd|target>/.deft-scratch/subagent-status)\n  --first-seen-dir PATH      First-seen stamps (default: .../subagent-steer-firstseen)\n  --dispatch-started-at ISO  DeliveryAttemptRecord.startedAt for grace path (b)\n  --expected-worker-id ID    Refuse when agent does not match current attempt worker\n  --observed-window-seconds N  Default 180\n  --force                    Explicit force clear (requires --reason)\n  --reason TEXT              Printed force reason\n  --json                     Machine-readable verdict\n\nExit codes:\n  0  Pre-cancel green\n  1  Refused (gate red)\n  2  Config / usage error\n";
-export interface SubagentPreCancelArgs {
-    agentId: string | null;
-    cancellerId: string | null;
-    targetId: string | null;
-    steerDir: string | null;
-    scratchDir: string | null;
-    firstSeenDir: string | null;
-    dispatchStartedAt: string | null;
-    expectedWorkerId: string | null;
-    observedWindowSeconds: number | null;
-    force: boolean;
-    forceReason: string | null;
-    emitJson: boolean;
-    help: boolean;
-    error?: string;
-}
-export declare function parseSubagentPreCancelArgs(argv: readonly string[]): SubagentPreCancelArgs;
-export declare function run(argv: readonly string[], cwd?: string): number;
-//# sourceMappingURL=subagent-pre-cancel.d.ts.map

package/dist/subagent-pre-cancel.js

@@ -1,240 +0,0 @@
-#!/usr/bin/env node
-/**
- * Fail-closed query-before-cancel gate (#5278 Prefer-A).
- * Dest-capable args required for linked-worktree children (#4066).
- */
-import { resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { defaultFirstSeenDir, defaultScratchDir, defaultSteerDir, EXIT_PRE_CANCEL_CONFIG, EXIT_PRE_CANCEL_OK, evaluatePreCancel, } from "@deftai/directive-core/orchestration";
-export const SUBAGENT_PRE_CANCEL_HELP = `subagent:pre-cancel — query-before-cancel gate (#5278)
-
-Usage:
-  task subagent:pre-cancel -- --agent <id> --canceller-id <id> [options]
-
-Exit 0 only when one ordered branch clears:
-  (a) canceller-authored status steer (kind note|correction) + matching ack
-      OR observed first-seen window (default 3 minutes; PA-18 forward skew only)
-  (b) heartbeat STALE/missing under startup grace from --dispatch-started-at
-  (c) --force --reason <text>
-
-Options:
-  --agent ID                 Target child agent_id (required)
-  --canceller-id ID          Canceller identity; must match steer writer_id for (a)
-  --target-id PATH           Worktree root (resolves steer/scratch/first-seen under it)
-  --steer-dir PATH           Steer inbox dir (default: <cwd|target>/.deft-scratch/subagent-steer)
-  --scratch-dir PATH         Heartbeat dir (default: <cwd|target>/.deft-scratch/subagent-status)
-  --first-seen-dir PATH      First-seen stamps (default: .../subagent-steer-firstseen)
-  --dispatch-started-at ISO  DeliveryAttemptRecord.startedAt for grace path (b)
-  --expected-worker-id ID    Refuse when agent does not match current attempt worker
-  --observed-window-seconds N  Default 180
-  --force                    Explicit force clear (requires --reason)
-  --reason TEXT              Printed force reason
-  --json                     Machine-readable verdict
-
-Exit codes:
-  0  Pre-cancel green
-  1  Refused (gate red)
-  2  Config / usage error
-`;
-export function parseSubagentPreCancelArgs(argv) {
-    const acc = {
-        agentId: null,
-        cancellerId: null,
-        targetId: null,
-        steerDir: null,
-        scratchDir: null,
-        firstSeenDir: null,
-        dispatchStartedAt: null,
-        expectedWorkerId: null,
-        observedWindowSeconds: null,
-        force: false,
-        forceReason: null,
-        emitJson: false,
-        help: false,
-    };
-    for (let i = 0; i < argv.length; i += 1) {
-        const arg = argv[i];
-        if (arg === "--help" || arg === "-h") {
-            return { ...acc, help: true };
-        }
-        if (arg === "--json") {
-            acc.emitJson = true;
-        }
-        else if (arg === "--force") {
-            acc.force = true;
-        }
-        else if (arg === "--agent" || arg === "--agent-id") {
-            const value = argv[i + 1];
-            if (value === undefined)
-                return { ...acc, error: `argument ${arg}: expected one argument` };
-            acc.agentId = value;
-            i += 1;
-        }
-        else if (arg?.startsWith("--agent=") || arg?.startsWith("--agent-id=")) {
-            acc.agentId = arg.slice(arg.indexOf("=") + 1);
-        }
-        else if (arg === "--canceller-id" || arg === "--canceller") {
-            const value = argv[i + 1];
-            if (value === undefined)
-                return { ...acc, error: `argument ${arg}: expected one argument` };
-            acc.cancellerId = value;
-            i += 1;
-        }
-        else if (arg?.startsWith("--canceller-id=") || arg?.startsWith("--canceller=")) {
-            acc.cancellerId = arg.slice(arg.indexOf("=") + 1);
-        }
-        else if (arg === "--target-id" || arg === "--target") {
-            const value = argv[i + 1];
-            if (value === undefined)
-                return { ...acc, error: `argument ${arg}: expected one argument` };
-            acc.targetId = value;
-            i += 1;
-        }
-        else if (arg?.startsWith("--target-id=") || arg?.startsWith("--target=")) {
-            acc.targetId = arg.slice(arg.indexOf("=") + 1);
-        }
-        else if (arg === "--steer-dir") {
-            const value = argv[i + 1];
-            if (value === undefined)
-                return { ...acc, error: "argument --steer-dir: expected one argument" };
-            acc.steerDir = value;
-            i += 1;
-        }
-        else if (arg?.startsWith("--steer-dir=")) {
-            acc.steerDir = arg.slice("--steer-dir=".length);
-        }
-        else if (arg === "--scratch-dir") {
-            const value = argv[i + 1];
-            if (value === undefined)
-                return { ...acc, error: "argument --scratch-dir: expected one argument" };
-            acc.scratchDir = value;
-            i += 1;
-        }
-        else if (arg?.startsWith("--scratch-dir=")) {
-            acc.scratchDir = arg.slice("--scratch-dir=".length);
-        }
-        else if (arg === "--first-seen-dir") {
-            const value = argv[i + 1];
-            if (value === undefined) {
-                return { ...acc, error: "argument --first-seen-dir: expected one argument" };
-            }
-            acc.firstSeenDir = value;
-            i += 1;
-        }
-        else if (arg?.startsWith("--first-seen-dir=")) {
-            acc.firstSeenDir = arg.slice("--first-seen-dir=".length);
-        }
-        else if (arg === "--dispatch-started-at") {
-            const value = argv[i + 1];
-            if (value === undefined) {
-                return { ...acc, error: "argument --dispatch-started-at: expected one argument" };
-            }
-            acc.dispatchStartedAt = value;
-            i += 1;
-        }
-        else if (arg?.startsWith("--dispatch-started-at=")) {
-            acc.dispatchStartedAt = arg.slice("--dispatch-started-at=".length);
-        }
-        else if (arg === "--expected-worker-id") {
-            const value = argv[i + 1];
-            if (value === undefined) {
-                return { ...acc, error: "argument --expected-worker-id: expected one argument" };
-            }
-            acc.expectedWorkerId = value;
-            i += 1;
-        }
-        else if (arg?.startsWith("--expected-worker-id=")) {
-            acc.expectedWorkerId = arg.slice("--expected-worker-id=".length);
-        }
-        else if (arg === "--observed-window-seconds") {
-            const value = argv[i + 1];
-            if (value === undefined) {
-                return { ...acc, error: "argument --observed-window-seconds: expected one argument" };
-            }
-            acc.observedWindowSeconds = Number(value);
-            i += 1;
-        }
-        else if (arg?.startsWith("--observed-window-seconds=")) {
-            acc.observedWindowSeconds = Number(arg.slice("--observed-window-seconds=".length));
-        }
-        else if (arg === "--reason") {
-            const value = argv[i + 1];
-            if (value === undefined)
-                return { ...acc, error: "argument --reason: expected one argument" };
-            acc.forceReason = value;
-            i += 1;
-        }
-        else if (arg?.startsWith("--reason=")) {
-            acc.forceReason = arg.slice("--reason=".length);
-        }
-        else if (arg?.startsWith("-")) {
-            return { ...acc, error: `unrecognized argument: ${arg}` };
-        }
-        else {
-            return { ...acc, error: `unrecognized argument: ${arg}` };
-        }
-    }
-    return acc;
-}
-export function run(argv, cwd = process.cwd()) {
-    const args = parseSubagentPreCancelArgs(argv);
-    if (args.help) {
-        process.stdout.write(SUBAGENT_PRE_CANCEL_HELP);
-        return EXIT_PRE_CANCEL_OK;
-    }
-    if (args.error !== undefined) {
-        process.stderr.write(`subagent:pre-cancel: ${args.error}\n`);
-        return EXIT_PRE_CANCEL_CONFIG;
-    }
-    const root = args.targetId !== null && args.targetId.trim().length > 0 ? resolve(cwd, args.targetId) : cwd;
-    const steerDir = resolve(root, args.steerDir ?? defaultSteerDir(root));
-    const scratchDir = resolve(root, args.scratchDir ?? defaultScratchDir(root));
-    const firstSeenDir = resolve(root, args.firstSeenDir ?? defaultFirstSeenDir(root));
-    // Linked-worktree children: refuse default-to-parent-cwd alone without dest args (#4066 / #5278).
-    // Partial dest (only --steer-dir or only --scratch-dir) mixes worktrees — require a pair or --target-id.
-    const hasTarget = args.targetId !== null && args.targetId.trim().length > 0;
-    const hasSteer = args.steerDir !== null;
-    const hasScratch = args.scratchDir !== null;
-    if (!hasTarget && hasSteer !== hasScratch) {
-        process.stderr.write("subagent:pre-cancel: --steer-dir and --scratch-dir must be paired when --target-id is omitted (partial dest mixes worktrees)\n");
-        return EXIT_PRE_CANCEL_CONFIG;
-    }
-    const hasDest = hasTarget || (hasSteer && hasScratch);
-    if (!hasDest) {
-        process.stderr.write("subagent:pre-cancel: dest-capable --target-id and/or paired --steer-dir/--scratch-dir required (default-to-cwd alone is refuse-closed for linked-worktree children)\n");
-        return EXIT_PRE_CANCEL_CONFIG;
-    }
-    if (args.observedWindowSeconds !== null &&
-        (!Number.isFinite(args.observedWindowSeconds) || args.observedWindowSeconds <= 0)) {
-        process.stderr.write("subagent:pre-cancel: --observed-window-seconds must be positive\n");
-        return EXIT_PRE_CANCEL_CONFIG;
-    }
-    const verdict = evaluatePreCancel({
-        agentId: args.agentId ?? "",
-        cancellerId: args.cancellerId ?? "",
-        steerDir,
-        firstSeenDir,
-        scratchDir,
-        force: args.force,
-        forceReason: args.forceReason ?? undefined,
-        dispatchStartedAt: args.dispatchStartedAt,
-        expectedWorkerId: args.expectedWorkerId,
-        observedWindowSeconds: args.observedWindowSeconds ?? undefined,
-    });
-    if (args.emitJson) {
-        process.stdout.write(`${JSON.stringify(verdict.json, null, 2)}\n`);
-    }
-    else if (verdict.message.length > 0) {
-        if (verdict.ok) {
-            process.stdout.write(`${verdict.message}\n`);
-        }
-        else {
-            process.stderr.write(`${verdict.message}\n`);
-        }
-    }
-    return verdict.exitCode;
-}
-if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
-    process.exit(run(process.argv.slice(2)));
-}
-//# sourceMappingURL=subagent-pre-cancel.js.map

package/dist/subagent-steer-write.d.ts

@@ -1,41 +0,0 @@
-#!/usr/bin/env node
-import { type SteerKind, type SteerWriterKind } from "@deftai/directive-core/orchestration";
-export declare const EXIT_STEER_WRITE_OK: number;
-export declare const EXIT_STEER_WRITE_CONFIG: number;
-export declare const SUBAGENT_STEER_WRITE_HELP = "subagent:steer \u2014 write a closed parent-steer inbox (#5278 / #4286)\n\nUsage:\n  task subagent:steer -- --agent <id> --writer-id <id> --kind <kind> --text <text> [options]\n\nOptions:\n  --agent ID              Child agent_id (inbox file stem)\n  --writer-id ID          Writer identity (must match independent parent/owner record)\n  --writer-kind KIND      occupancy-owner | dispatching-parent (default: dispatching-parent)\n  --kind KIND             constraint | correction | halt | note\n  --text TEXT             Steer body (\u22642000 chars)\n  --steer-id ID           Optional stable steer id (default: uuid)\n  --ttl-seconds N         Expiry TTL (default: 1800)\n  --target-id PATH        Worktree root for dest inbox\n  --steer-dir PATH        Inbox directory override\n  --scratch-dir PATH      Heartbeat dir (not used for writer authority)\n  --parent-id ID          Must match child occupancy lease parentId\n  --occupancy-owner-id ID Must match live occupancy session under --target-id\n  --json                  Emit written record\n\nExit codes:\n  0  Wrote inbox\n  2  Config / validation error\n";
-export interface SubagentSteerWriteArgs {
-    agentId: string | null;
-    writerId: string | null;
-    writerKind: SteerWriterKind;
-    kind: SteerKind | null;
-    text: string | null;
-    steerId: string | null;
-    ttlSeconds: number | null;
-    targetId: string | null;
-    steerDir: string | null;
-    scratchDir: string | null;
-    parentId: string | null;
-    occupancyOwnerId: string | null;
-    emitJson: boolean;
-    help: boolean;
-    error?: string;
-}
-/**
- * Resolve parent/owner from dispatcher-recorded child occupancy + live occupancy.
- * Heartbeat alone is never authority (caller-selected --scratch-dir cannot mint parent_id).
- */
-export declare function resolveIndependentSteerAuthority(input: {
-    root: string;
-    agentId: string;
-    writerKind: SteerWriterKind;
-    writerId: string;
-    claimedParentId?: string | null;
-    claimedOccupancyOwnerId?: string | null;
-}): {
-    parentId?: string;
-    occupancyOwnerId?: string;
-    error?: string;
-};
-export declare function parseSubagentSteerWriteArgs(argv: readonly string[]): SubagentSteerWriteArgs;
-export declare function run(argv: readonly string[], cwd?: string): number;
-//# sourceMappingURL=subagent-steer-write.d.ts.map