audit-tools 0.28.0

package/dist/shared/intent/sharedIntentData.js

@@ -0,0 +1,38 @@
+/**
+ * Shared keyword maps and patterns used by both the free-form intent
+ * interpreter and the per-clause intent interpreter. Single-sourced here
+ * so both modules stay in sync without duplication.
+ */
+/** Maps normalised keyword fragments → Lens. Longer/more-specific entries first. */
+export const LENS_KEYWORD_MAP = [
+    { keywords: ["config_deployment", "config deployment", "deployment", "deploy", "config"], lens: "config_deployment" },
+    { keywords: ["data_integrity", "data integrity", "data quality", "integrity"], lens: "data_integrity" },
+    { keywords: ["observability", "logging", "monitoring", "tracing", "metrics", "logs"], lens: "observability" },
+    { keywords: ["operability", "ops", "runbook", "runbooks", "operations"], lens: "operability" },
+    { keywords: ["maintainability", "readability", "clean code", "debt", "technical debt", "refactor"], lens: "maintainability" },
+    { keywords: ["architecture", "arch", "coupling", "cohesion", "design", "structure"], lens: "architecture" },
+    { keywords: ["reliability", "resilience", "fault tolerance", "availability", "uptime"], lens: "reliability" },
+    { keywords: ["performance", "perf", "latency", "throughput", "speed", "slow", "fast", "optimis", "optimiz"], lens: "performance" },
+    { keywords: ["security", "auth", "authn", "authz", "injection", "xss", "csrf", "vuln", "vulnerabilit", "cve", "secret", "credential"], lens: "security" },
+    { keywords: ["test", "coverage", "spec", "unit test", "integration test", "e2e"], lens: "tests" },
+    { keywords: ["correctness", "bug", "bugs", "fix", "defect", "incorrect", "wrong", "broken"], lens: "correctness" },
+];
+/** Patterns that signal scope emphasis (focus/ignore/prioritise). */
+export const SCOPE_PATTERNS = [
+    /\b(?:focus(?:ing)?\s+on|focused\s+on)\s+(.+)/i,
+    /\b(?:prioriti[sz]e?|prioriti[sz]ing)\s+(.+)/i,
+    /\b(?:ignore|ignoring|skip(?:ping)?|exclude?|excluding)\s+(.+)/i,
+    /\b(?:concentrate\s+on|look\s+at|check\s+(?:only\s+)?(?:the\s+)?)\s+(.+)/i,
+    /\b(?:limit(?:ed)?\s+to|restrict(?:ed)?\s+to|only\s+(?:in|within|for))\s+(.+)/i,
+    // Bare "only <verb> <path>" — e.g. "only audit src/", "only review packages/"
+    /^only\s+\w+\s+(\S+(?:\/\S*)?)/i,
+];
+/** Patterns that signal urgency / priority. */
+export const PRIORITY_PATTERNS = [
+    /\b(?:urgent|urgently)\b/i,
+    /\b(?:critical|critically)\b/i,
+    /\b(?:most\s+important|top\s+priority|highest\s+priority|asap|as\s+soon\s+as\s+possible)\b/i,
+    /\b(?:immediately|right\s+away|now)\b/i,
+    /\b(?:high\s+priority|high-priority)\b/i,
+];
+//# sourceMappingURL=sharedIntentData.js.map

package/dist/shared/intent/sharedIntentData.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedIntentData.js","sourceRoot":"","sources":["../../../src/shared/intent/sharedIntentData.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,oFAAoF;AACpF,MAAM,CAAC,MAAM,gBAAgB,GAA8C;IACzE,EAAE,QAAQ,EAAE,CAAC,mBAAmB,EAAE,mBAAmB,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE;IACrH,EAAE,QAAQ,EAAE,CAAC,gBAAgB,EAAE,gBAAgB,EAAE,cAAc,EAAE,WAAW,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE;IACvG,EAAE,QAAQ,EAAE,CAAC,eAAe,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE;IAC7G,EAAE,QAAQ,EAAE,CAAC,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE;IAC9F,EAAE,QAAQ,EAAE,CAAC,iBAAiB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,UAAU,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE;IAC7H,EAAE,QAAQ,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE;IAC3G,EAAE,QAAQ,EAAE,CAAC,aAAa,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE;IAC7G,EAAE,QAAQ,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE;IAClI,EAAE,QAAQ,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE;IACzJ,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,kBAAkB,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE;IACjG,EAAE,QAAQ,EAAE,CAAC,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE;CACnH,CAAC;AAEF,qEAAqE;AACrE,MAAM,CAAC,MAAM,cAAc,GAAa;IACtC,+CAA+C;IAC/C,8CAA8C;IAC9C,gEAAgE;IAChE,0EAA0E;IAC1E,+EAA+E;IAC/E,8EAA8E;IAC9E,gCAAgC;CACjC,CAAC;AAEF,+CAA+C;AAC/C,MAAM,CAAC,MAAM,iBAAiB,GAAa;IACzC,0BAA0B;IAC1B,8BAA8B;IAC9B,4FAA4F;IAC5F,uCAAuC;IACvC,wCAAwC;CACzC,CAAC"}

package/dist/shared/io/auditToolsPaths.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Single source of truth for the on-disk `.audit-tools/` layout shared by both
+ * orchestrators. Every path is derived from a passed repository root (or, for
+ * the per-artifacts-dir helpers, from an already-resolved artifacts dir) so the
+ * literal directory names (`.audit-tools`, `audit`, `remediation`, `steps`,
+ * `incoming`) live in exactly one place. CLI arg resolvers route through this
+ * module instead of re-spelling the join literals — that is what keeps the two
+ * tools from drifting and what the CLI-args guard test enforces.
+ *
+ * Rebasing rule: the default artifacts dir is ALWAYS rebased onto the supplied
+ * root. A `--root <X>` with no explicit `--artifacts-dir` must resolve under
+ * `<X>/.audit-tools/...`, never under the process CWD. Callers that accept an
+ * explicit artifacts-dir override should honor the override verbatim and fall
+ * back to these helpers only for the default.
+ */
+/** `<root>/.audit-tools` (absolute). */
+export declare function auditToolsDir(root: string): string;
+/** `<root>/.audit-tools/audit` — audit-code's default artifacts dir (absolute). */
+export declare function auditArtifactsDir(root: string): string;
+/**
+ * `<root>/.audit-tools/remediation` — remediate-code's default artifacts dir
+ * (absolute).
+ */
+export declare function remediationArtifactsDir(root: string): string;
+/**
+ * `<artifactsDir>/steps` — where each orchestrator writes `current-step.json`
+ * and `current-prompt.md`. Takes an already-resolved artifacts dir (audit or
+ * remediation), not a root, because both halves share this child name.
+ */
+export declare function stepsDir(artifactsDir: string): string;
+/**
+ * `<artifactsDir>/incoming` — the drop directory for upstream worker results
+ * and externally supplied evidence. Takes an already-resolved artifacts dir.
+ */
+export declare function incomingDir(artifactsDir: string): string;
+//# sourceMappingURL=auditToolsPaths.d.ts.map

package/dist/shared/io/auditToolsPaths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auditToolsPaths.d.ts","sourceRoot":"","sources":["../../../src/shared/io/auditToolsPaths.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,wCAAwC;AACxC,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAExD"}

package/dist/shared/io/auditToolsPaths.js

@@ -0,0 +1,47 @@
+import { join, resolve } from "node:path";
+/**
+ * Single source of truth for the on-disk `.audit-tools/` layout shared by both
+ * orchestrators. Every path is derived from a passed repository root (or, for
+ * the per-artifacts-dir helpers, from an already-resolved artifacts dir) so the
+ * literal directory names (`.audit-tools`, `audit`, `remediation`, `steps`,
+ * `incoming`) live in exactly one place. CLI arg resolvers route through this
+ * module instead of re-spelling the join literals — that is what keeps the two
+ * tools from drifting and what the CLI-args guard test enforces.
+ *
+ * Rebasing rule: the default artifacts dir is ALWAYS rebased onto the supplied
+ * root. A `--root <X>` with no explicit `--artifacts-dir` must resolve under
+ * `<X>/.audit-tools/...`, never under the process CWD. Callers that accept an
+ * explicit artifacts-dir override should honor the override verbatim and fall
+ * back to these helpers only for the default.
+ */
+/** `<root>/.audit-tools` (absolute). */
+export function auditToolsDir(root) {
+    return resolve(root, ".audit-tools");
+}
+/** `<root>/.audit-tools/audit` — audit-code's default artifacts dir (absolute). */
+export function auditArtifactsDir(root) {
+    return join(auditToolsDir(root), "audit");
+}
+/**
+ * `<root>/.audit-tools/remediation` — remediate-code's default artifacts dir
+ * (absolute).
+ */
+export function remediationArtifactsDir(root) {
+    return join(auditToolsDir(root), "remediation");
+}
+/**
+ * `<artifactsDir>/steps` — where each orchestrator writes `current-step.json`
+ * and `current-prompt.md`. Takes an already-resolved artifacts dir (audit or
+ * remediation), not a root, because both halves share this child name.
+ */
+export function stepsDir(artifactsDir) {
+    return join(artifactsDir, "steps");
+}
+/**
+ * `<artifactsDir>/incoming` — the drop directory for upstream worker results
+ * and externally supplied evidence. Takes an already-resolved artifacts dir.
+ */
+export function incomingDir(artifactsDir) {
+    return join(artifactsDir, "incoming");
+}
+//# sourceMappingURL=auditToolsPaths.js.map

package/dist/shared/io/auditToolsPaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auditToolsPaths.js","sourceRoot":"","sources":["../../../src/shared/io/auditToolsPaths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C;;;;;;;;;;;;;;GAcG;AAEH,wCAAwC;AACxC,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,OAAO,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;AACvC,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,YAAoB;IAC3C,OAAO,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,YAAoB;IAC9C,OAAO,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;AACxC,CAAC"}

package/dist/shared/io/json.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Windows can transiently fail an atomic rename-over-existing with EPERM/EBUSY
+ * (antivirus, the search indexer, or a concurrent reader briefly holding the
+ * destination handle). Those are retryable; a missing path or bad input is not.
+ */
+export declare function isTransientFsError(error: unknown): boolean;
+export interface FsRetryOptions {
+    attempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    /** Injectable for tests so retries don't actually wait. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Retry a filesystem operation on transient Windows lock errors with bounded
+ * exponential backoff (mirrors the quota file lock's 50ms→500ms convention).
+ * Non-transient errors propagate immediately.
+ */
+export declare function withFsRetry<T>(operation: () => Promise<T>, options?: FsRetryOptions): Promise<T>;
+export declare function isFileMissingError(error: unknown): boolean;
+export declare function readJsonFile<T>(path: string): Promise<T>;
+export declare function writeJsonFile(path: string, value: unknown): Promise<void>;
+export declare function appendNdjsonFile(path: string, value: unknown): Promise<void>;
+export declare function readNdjsonFile<T>(path: string): Promise<T[]>;
+export declare function readOptionalJsonFile<T>(path: string): Promise<T | undefined>;
+export declare function readOptionalNdjsonFile<T>(path: string): Promise<T[] | undefined>;
+export declare function writeNdjsonFile(path: string, values: unknown[]): Promise<void>;
+export declare function readOptionalTextFile(path: string): Promise<string | undefined>;
+export declare function writeTextFile(path: string, value: string): Promise<void>;
+//# sourceMappingURL=json.d.ts.map

package/dist/shared/io/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../../src/shared/io/json.ts"],"names":[],"mappings":"AAiCA;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM1D;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAOD;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAgBZ;AAoBD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAO1D;AAED,wBAAsB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAgB9D;AAED,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAmClE;AAED,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CASxB;AAED,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,CAS1B;AAED,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,EAAE,GAChB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS7B;AAED,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/dist/shared/io/json.js

@@ -0,0 +1,183 @@
+import { mkdir, readFile, writeFile, appendFile, rename, rm, } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function ioError(action, path, error) {
+    return new Error(`Failed to ${action} ${path}: ${errorMessage(error)}`);
+}
+async function ensureParentDirectory(path) {
+    try {
+        await mkdir(dirname(path), { recursive: true });
+    }
+    catch (error) {
+        throw ioError("prepare parent directory", path, error);
+    }
+}
+const TRANSIENT_FS_CODES = new Set(["EPERM", "EBUSY", "EACCES", "EEXIST"]);
+/**
+ * Windows can transiently fail an atomic rename-over-existing with EPERM/EBUSY
+ * (antivirus, the search indexer, or a concurrent reader briefly holding the
+ * destination handle). Those are retryable; a missing path or bad input is not.
+ */
+export function isTransientFsError(error) {
+    if (typeof error !== "object" || error === null || !("code" in error)) {
+        return false;
+    }
+    const code = error.code;
+    return typeof code === "string" && TRANSIENT_FS_CODES.has(code);
+}
+const defaultSleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+/**
+ * Retry a filesystem operation on transient Windows lock errors with bounded
+ * exponential backoff (mirrors the quota file lock's 50ms→500ms convention).
+ * Non-transient errors propagate immediately.
+ */
+export async function withFsRetry(operation, options = {}) {
+    const attempts = options.attempts ?? 20;
+    const maxDelayMs = options.maxDelayMs ?? 250;
+    const sleep = options.sleep ?? defaultSleep;
+    let delayMs = options.initialDelayMs ?? 20;
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (attempt >= attempts || !isTransientFsError(error)) {
+                throw error;
+            }
+            await sleep(delayMs);
+            delayMs = Math.min(delayMs * 2, maxDelayMs);
+        }
+    }
+}
+async function writeFileAtomic(path, content) {
+    await ensureParentDirectory(path);
+    const temp = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temp, content, "utf8");
+        // The temp name is unique per process+uuid, so only the final rename-over-
+        // existing-destination is exposed to transient Windows lock errors.
+        await withFsRetry(() => rename(temp, path));
+    }
+    catch (error) {
+        throw ioError("write", path, error);
+    }
+    finally {
+        await rm(temp, { force: true }).catch(() => undefined);
+    }
+}
+export function isFileMissingError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+export async function readJsonFile(path) {
+    let content;
+    try {
+        content = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isFileMissingError(error)) {
+            throw error;
+        }
+        throw ioError("read", path, error);
+    }
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON in ${path}: ${errorMessage(error)}`);
+    }
+}
+export async function writeJsonFile(path, value) {
+    await writeFileAtomic(path, JSON.stringify(value, null, 2) + "\n");
+}
+export async function appendNdjsonFile(path, value) {
+    await ensureParentDirectory(path);
+    try {
+        await appendFile(path, JSON.stringify(value) + "\n", "utf8");
+    }
+    catch (error) {
+        throw ioError("append", path, error);
+    }
+}
+export async function readNdjsonFile(path) {
+    try {
+        const content = await readFile(path, "utf8");
+        const values = [];
+        let sawContent = false;
+        for (const [index, line] of content.split(/\r?\n/).entries()) {
+            if (line.trim().length === 0) {
+                continue;
+            }
+            sawContent = true;
+            try {
+                values.push(JSON.parse(line));
+            }
+            catch (error) {
+                throw new Error(`Invalid NDJSON in ${path} at line ${index + 1}: ${errorMessage(error)}`);
+            }
+        }
+        if (!sawContent && content.length > 0) {
+            throw new Error(`NDJSON file ${path} contains only whitespace — possible truncated write`);
+        }
+        return values;
+    }
+    catch (error) {
+        if (isFileMissingError(error)) {
+            throw error;
+        }
+        if (error instanceof Error && error.message.includes(path)) {
+            throw error;
+        }
+        throw ioError("read", path, error);
+    }
+}
+export async function readOptionalJsonFile(path) {
+    try {
+        return await readJsonFile(path);
+    }
+    catch (error) {
+        if (isFileMissingError(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+export async function readOptionalNdjsonFile(path) {
+    try {
+        return await readNdjsonFile(path);
+    }
+    catch (error) {
+        if (isFileMissingError(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+export async function writeNdjsonFile(path, values) {
+    const content = values.length === 0
+        ? ""
+        : values.map((v) => JSON.stringify(v)).join("\n") + "\n";
+    await writeFileAtomic(path, content);
+}
+export async function readOptionalTextFile(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isFileMissingError(error)) {
+            return undefined;
+        }
+        throw ioError("read", path, error);
+    }
+}
+export async function writeTextFile(path, value) {
+    await writeFileAtomic(path, value);
+}
+//# sourceMappingURL=json.js.map

package/dist/shared/io/json.js.map

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

package/dist/shared/io/stepContractWriter.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Single source of truth for the step-contract object + writer shared by both
+ * orchestrators (drift-plan R3). Before this module existed, audit-code
+ * (`src/cli/steps.ts`) and remediate-code (`src/steps/stepWriter.ts`) each had
+ * their own `writeCurrentStep` with REAL behavioural drift: remediate
+ * normalized every host-facing path to forward slashes via `toPromptPathToken`,
+ * but audit wrote raw Windows paths (backslashes), which break in the bash-like
+ * shells a host may use to run the step's commands. This module owns:
+ *
+ *  - the `steps/` filenames (`current-step.json`, `current-prompt.md`), via the
+ *    shared `stepsDir` helper;
+ *  - `mkdir` of the steps dir, the `current-prompt.md` write, and the atomic
+ *    `writeJsonFile` of `current-step.json`;
+ *  - the `toPromptPathToken` normalization of ALL host-facing path fields
+ *    (`prompt_path`, `repo_root`, `artifacts_dir`, and every value in
+ *    `artifact_paths`);
+ *  - the "computed canonical paths win" merge guard: caller-supplied
+ *    `artifact_paths` are merged FIRST so the canonical `current_step` /
+ *    `current_prompt` entries always overwrite them — a caller (or step config)
+ *    must never be able to repoint a host at a different current-step.json or
+ *    current-prompt.md.
+ *
+ * Each orchestrator extends `BaseStepContract` with its own `step_kind` enum
+ * and optional fields (progress, allowed_mcp_tools, access, ...) and calls
+ * `writeStepContract` with its concrete types; neither writes raw paths.
+ */
+/** Path of `current-step.json` for a given artifacts dir. */
+export declare function currentStepPath(artifactsDir: string): string;
+/** Path of `current-prompt.md` for a given artifacts dir. */
+export declare function currentPromptPath(artifactsDir: string): string;
+/**
+ * Fields every step contract shares. Orchestrators extend this with a narrowed
+ * `step_kind` (their own enum), a narrowed `contract_version` literal, and any
+ * orchestrator-specific optional fields.
+ *
+ * `TStepKind` is the orchestrator's step-kind enum; `TArtifactValue` is whether
+ * artifact path values may be `null` (audit allows null entries for not-yet
+ * materialized artifacts; remediate does not).
+ */
+export interface BaseStepContract<TStepKind extends string = string, TArtifactValue extends string | null = string | null> {
+    contract_version: string;
+    step_kind: TStepKind;
+    status: string;
+    prompt_path: string;
+    run_id: string | null;
+    allowed_commands: string[];
+    stop_condition: string;
+    repo_root: string;
+    artifacts_dir: string;
+    artifact_paths: Record<string, TArtifactValue>;
+}
+/**
+ * Input to {@link writeStepContract}. `contractVersion`, `stepKind`, `status`,
+ * `runId`, `allowedCommands`, `stopCondition`, `repoRoot`, `artifactsDir`, and
+ * `prompt` map onto the matching base contract fields. `artifactPaths` is the
+ * caller's extra artifact map (merged before the canonical step/prompt keys).
+ * `extraFields` is a shallow object spread onto the contract AFTER the base
+ * fields but BEFORE the canonical `prompt_path`/`repo_root`/`artifacts_dir`/
+ * `artifact_paths` normalization — so an orchestrator's optional fields
+ * (progress, allowed_mcp_tools, access, ...) ride along without this module
+ * knowing about them, and can never clobber the normalized path fields.
+ */
+export interface WriteStepContractInput<TStepKind extends string = string, TArtifactValue extends string | null = string | null> {
+    contractVersion: string;
+    stepKind: TStepKind;
+    status: string;
+    runId: string | null;
+    allowedCommands: string[];
+    stopCondition: string;
+    repoRoot: string;
+    artifactsDir: string;
+    prompt: string;
+    /**
+     * Caller-supplied artifact map. Merged FIRST; the canonical `current_step`
+     * and `current_prompt` entries always win. All values are normalized to
+     * forward-slash prompt path tokens.
+     */
+    artifactPaths?: Record<string, TArtifactValue>;
+    /**
+     * Orchestrator-specific optional fields (progress, allowed_mcp_tools,
+     * access, ...). Spread onto the contract before the canonical path fields,
+     * so they can never overwrite the normalized paths or `artifact_paths`.
+     */
+    extraFields?: Record<string, unknown>;
+    /**
+     * Whether to trim leading whitespace from the prompt before writing it.
+     * Remediate trims (its prompts are built with a leading newline); audit
+     * writes the prompt verbatim. Defaults to `false` (verbatim).
+     */
+    trimPromptStart?: boolean;
+}
+/**
+ * Write `current-prompt.md` and an atomically-replaced `current-step.json`
+ * under `<artifactsDir>/steps/`, returning the contract object that was
+ * persisted (path fields normalized to forward slashes). The generic
+ * parameters let each orchestrator recover its concrete contract type.
+ *
+ * Path normalization is applied to EVERY host-facing path field so a step
+ * never carries Windows backslashes into the JSON a host reads and runs
+ * commands from.
+ */
+export declare function writeStepContract<TStep extends BaseStepContract<TStepKind, TArtifactValue>, TStepKind extends string = string, TArtifactValue extends string | null = string | null>(input: WriteStepContractInput<TStepKind, TArtifactValue>): Promise<TStep>;
+//# sourceMappingURL=stepContractWriter.d.ts.map

package/dist/shared/io/stepContractWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stepContractWriter.d.ts","sourceRoot":"","sources":["../../../src/shared/io/stepContractWriter.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,6DAA6D;AAC7D,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB,CAC/B,SAAS,SAAS,MAAM,GAAG,MAAM,EACjC,cAAc,SAAS,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI;IAEpD,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAChD;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB,CACrC,SAAS,SAAS,MAAM,GAAG,MAAM,EACjC,cAAc,SAAS,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI;IAEpD,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC/C;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,SAAS,gBAAgB,CAAC,SAAS,EAAE,cAAc,CAAC,EACzD,SAAS,SAAS,MAAM,GAAG,MAAM,EACjC,cAAc,SAAS,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,EACpD,KAAK,EAAE,sBAAsB,CAAC,SAAS,EAAE,cAAc,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CA0C1E"}

package/dist/shared/io/stepContractWriter.js

@@ -0,0 +1,85 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { stepsDir } from "./auditToolsPaths.js";
+import { writeJsonFile } from "./json.js";
+import { toPromptPathToken } from "../tooling/exec.js";
+/**
+ * Single source of truth for the step-contract object + writer shared by both
+ * orchestrators (drift-plan R3). Before this module existed, audit-code
+ * (`src/cli/steps.ts`) and remediate-code (`src/steps/stepWriter.ts`) each had
+ * their own `writeCurrentStep` with REAL behavioural drift: remediate
+ * normalized every host-facing path to forward slashes via `toPromptPathToken`,
+ * but audit wrote raw Windows paths (backslashes), which break in the bash-like
+ * shells a host may use to run the step's commands. This module owns:
+ *
+ *  - the `steps/` filenames (`current-step.json`, `current-prompt.md`), via the
+ *    shared `stepsDir` helper;
+ *  - `mkdir` of the steps dir, the `current-prompt.md` write, and the atomic
+ *    `writeJsonFile` of `current-step.json`;
+ *  - the `toPromptPathToken` normalization of ALL host-facing path fields
+ *    (`prompt_path`, `repo_root`, `artifacts_dir`, and every value in
+ *    `artifact_paths`);
+ *  - the "computed canonical paths win" merge guard: caller-supplied
+ *    `artifact_paths` are merged FIRST so the canonical `current_step` /
+ *    `current_prompt` entries always overwrite them — a caller (or step config)
+ *    must never be able to repoint a host at a different current-step.json or
+ *    current-prompt.md.
+ *
+ * Each orchestrator extends `BaseStepContract` with its own `step_kind` enum
+ * and optional fields (progress, allowed_mcp_tools, access, ...) and calls
+ * `writeStepContract` with its concrete types; neither writes raw paths.
+ */
+/** Path of `current-step.json` for a given artifacts dir. */
+export function currentStepPath(artifactsDir) {
+    return join(stepsDir(artifactsDir), "current-step.json");
+}
+/** Path of `current-prompt.md` for a given artifacts dir. */
+export function currentPromptPath(artifactsDir) {
+    return join(stepsDir(artifactsDir), "current-prompt.md");
+}
+/**
+ * Write `current-prompt.md` and an atomically-replaced `current-step.json`
+ * under `<artifactsDir>/steps/`, returning the contract object that was
+ * persisted (path fields normalized to forward slashes). The generic
+ * parameters let each orchestrator recover its concrete contract type.
+ *
+ * Path normalization is applied to EVERY host-facing path field so a step
+ * never carries Windows backslashes into the JSON a host reads and runs
+ * commands from.
+ */
+export async function writeStepContract(input) {
+    const stepsDirPath = stepsDir(input.artifactsDir);
+    await mkdir(stepsDirPath, { recursive: true });
+    const promptPath = currentPromptPath(input.artifactsDir);
+    const stepPath = currentStepPath(input.artifactsDir);
+    await writeFile(promptPath, input.trimPromptStart ? input.prompt.trimStart() : input.prompt, "utf8");
+    const callerArtifactPaths = input.artifactPaths ?? {};
+    const normalizedArtifactPaths = {};
+    // Caller-supplied paths are merged FIRST so the canonical, computed
+    // step/prompt locations always win — a caller (or step config) must not be
+    // able to repoint the host at a different current-step.json / -prompt.md.
+    for (const [key, value] of Object.entries(callerArtifactPaths)) {
+        normalizedArtifactPaths[key] =
+            value === null ? null : toPromptPathToken(value);
+    }
+    normalizedArtifactPaths.current_step = toPromptPathToken(stepPath);
+    normalizedArtifactPaths.current_prompt = toPromptPathToken(promptPath);
+    const step = {
+        contract_version: input.contractVersion,
+        step_kind: input.stepKind,
+        status: input.status,
+        run_id: input.runId,
+        allowed_commands: input.allowedCommands,
+        stop_condition: input.stopCondition,
+        // Orchestrator-specific optional fields ride here; the canonical path
+        // fields below are written last so extraFields can never clobber them.
+        ...(input.extraFields ?? {}),
+        prompt_path: toPromptPathToken(promptPath),
+        repo_root: toPromptPathToken(input.repoRoot),
+        artifacts_dir: toPromptPathToken(input.artifactsDir),
+        artifact_paths: normalizedArtifactPaths,
+    };
+    await writeJsonFile(stepPath, step);
+    return step;
+}
+//# sourceMappingURL=stepContractWriter.js.map

package/dist/shared/io/stepContractWriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stepContractWriter.js","sourceRoot":"","sources":["../../../src/shared/io/stepContractWriter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,6DAA6D;AAC7D,MAAM,UAAU,eAAe,CAAC,YAAoB;IAClD,OAAO,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC,CAAC;AAC3D,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,iBAAiB,CAAC,YAAoB;IACpD,OAAO,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC,CAAC;AAC3D,CAAC;AAuED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAIrC,KAAwD;IACxD,MAAM,YAAY,GAAG,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAClD,MAAM,KAAK,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE/C,MAAM,UAAU,GAAG,iBAAiB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACrD,MAAM,SAAS,CACb,UAAU,EACV,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,EAC/D,MAAM,CACP,CAAC;IAEF,MAAM,mBAAmB,GAAG,KAAK,CAAC,aAAa,IAAI,EAAE,CAAC;IACtD,MAAM,uBAAuB,GAAkC,EAAE,CAAC;IAClE,oEAAoE;IACpE,2EAA2E;IAC3E,0EAA0E;IAC1E,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,CAAC;QAC/D,uBAAuB,CAAC,GAAG,CAAC;YAC1B,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC,KAAe,CAAC,CAAC;IAC/D,CAAC;IACD,uBAAuB,CAAC,YAAY,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACnE,uBAAuB,CAAC,cAAc,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;IAEvE,MAAM,IAAI,GAAG;QACX,gBAAgB,EAAE,KAAK,CAAC,eAAe;QACvC,SAAS,EAAE,KAAK,CAAC,QAAQ;QACzB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,MAAM,EAAE,KAAK,CAAC,KAAK;QACnB,gBAAgB,EAAE,KAAK,CAAC,eAAe;QACvC,cAAc,EAAE,KAAK,CAAC,aAAa;QACnC,sEAAsE;QACtE,uEAAuE;QACvE,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAC;QAC5B,WAAW,EAAE,iBAAiB,CAAC,UAAU,CAAC;QAC1C,SAAS,EAAE,iBAAiB,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC5C,aAAa,EAAE,iBAAiB,CAAC,KAAK,CAAC,YAAY,CAAC;QACpD,cAAc,EAAE,uBAAuB;KACpB,CAAC;IAEtB,MAAM,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACpC,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/shared/observability/runLog.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Stable vocabulary of run-log event kinds emitted across both orchestrators.
+ * Typed as a union so consumers can rely on a fixed set when aggregating logs.
+ */
+export type RunLogEventKind = "obligation" | "executor_start" | "executor_end" | "artifact_write" | "scope" | "outcome" | "provider_launch" | "step" | "state" | "error";
+export interface RunLogEvent {
+    /** Coarse phase/state, e.g. "advance" or "implementing". */
+    phase?: string;
+    /** The obligation/decision this event relates to. */
+    obligation?: string;
+    /** Event kind drawn from the stable {@link RunLogEventKind} vocabulary. */
+    kind: RunLogEventKind;
+    artifact?: string;
+    provider?: string;
+    tokens_est?: number;
+    duration_ms?: number;
+    note?: string;
+    /** Run- or request-scoped token for correlating log events across a single invocation. */
+    correlationId?: string;
+}
+export interface RunLoggerOptions {
+    enabled?: boolean;
+    /** Injectable clock (epoch ms) for deterministic tests. */
+    now?: () => number;
+}
+export declare class RunLogger {
+    private readonly path;
+    private readonly enabled;
+    private readonly now;
+    constructor(path: string, options?: RunLoggerOptions);
+    /** A logger that drops every event. Use when observability is disabled. */
+    static disabled(): RunLogger;
+    get isEnabled(): boolean;
+    /** Append one event line. Atomic per line (O_APPEND); swallows all errors. */
+    event(event: RunLogEvent): void;
+}
+//# sourceMappingURL=runLog.d.ts.map

package/dist/shared/observability/runLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runLog.d.ts","sourceRoot":"","sources":["../../../src/shared/observability/runLog.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,MAAM,MAAM,eAAe,GACvB,YAAY,GACZ,gBAAgB,GAChB,cAAc,GACd,gBAAgB,GAChB,OAAO,GACP,SAAS,GACT,iBAAiB,GACjB,MAAM,GACN,OAAO,GACP,OAAO,CAAC;AAEZ,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB;IAMxD,2EAA2E;IAC3E,MAAM,CAAC,QAAQ,IAAI,SAAS;IAI5B,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,8EAA8E;IAC9E,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;CAgBhC"}