audit-tools 0.49.0 → 0.50.2

package/dist/shared/submission/submissionScan.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The ONE per-item host-submission scan both ingests draw from.
+ *
+ * Every submitted work item crosses the same four-step gate before any draw's
+ * domain work begins: resolve the bound path inside the boundary, read the
+ * bytes, classify a missing / unparseable / contract-invalid document, and
+ * refuse a `result_id` the caller has already seen. Both twins hand-rolled that
+ * sequence — audit in `readSubmittedResult` plus an inline duplicate check,
+ * remediate inline in its ingest loop — and the two copies had already drifted
+ * on CONTAINMENT: remediate re-checked the resolved path under the artifacts
+ * dir, audit checked the root only. This module resolves that in the stricter
+ * direction for BOTH draws.
+ *
+ * What it deliberately does NOT own — because these are the places the draws
+ * genuinely differ, not places they drifted:
+ *
+ * - the MESSAGE TEXT of each refusal (a per-draw renderer supplies it; the two
+ *   vocabularies are test-pinned and address different readers);
+ * - the DOMAIN PARSER (a callback; each draw's parser stays standalone, so the
+ *   hand-recovery lane can wrap `parseResult` directly and stay parity-pinned);
+ * - identity enforcement, which lives INSIDE those parsers — hoisting it would
+ *   change refusal precedence for a doubly-bad document;
+ * - loop iteration, aggregation order, seen-set seeding, and the TIMING of the
+ *   duplicate consume. Audit seeds from its persisted accepted ledger and
+ *   consumes only after conversion, validation and grounding; remediate uses a
+ *   fresh per-call set and consumes at parse. This scan only CHECKS.
+ */
+import { type SubmissionIssue } from "./submissionClassifier.js";
+/**
+ * The domain parser's answer, normalized. `detail` is handed straight to the
+ * draw's `contractInvalid` renderer — the scan never composes refusal prose of
+ * its own.
+ */
+export type SubmissionParse<TParsed> = {
+    readonly ok: true;
+    readonly parsed: TParsed;
+} | {
+    readonly ok: false;
+    readonly detail: string;
+};
+/**
+ * The per-draw refusal vocabulary. Text is a DRAW concern: the audit ingest
+ * addresses a host repairing a bound result file, remediate addresses one
+ * repairing a pending work item, and several strings are pinned by tests.
+ */
+export interface SubmissionScanMessages {
+    /** Nothing exists at the bound path. */
+    readonly missing: () => string;
+    /** Bytes exist but are not JSON; `detail` is the parse/IO reason. */
+    readonly malformed: (detail: string) => string;
+    /** JSON that the domain parser refused; `detail` is its stated reason. */
+    readonly contractInvalid: (detail: string) => string;
+    /** The parsed result re-uses an identity the caller has already seen. */
+    readonly duplicate: (resultId: string) => string;
+}
+/** Either the parsed submission, or the ONE issue that names why not. */
+export type SubmissionScanOutcome<TParsed> = {
+    readonly ok: true;
+    readonly parsed: TParsed;
+} | {
+    readonly ok: false;
+    readonly issue: SubmissionIssue;
+};
+/**
+ * Scan one bound submission. Throws only where the twins already threw: a bound
+ * path that escapes the repository root or the artifacts dir is a boundary
+ * violation, not a classified submission failure.
+ */
+export declare function scanBoundSubmission<TParsed>(params: {
+    /** Absolute repository root the bound path is expressed relative to. */
+    readonly root: string;
+    /** Absolute artifacts dir the submission must also stay beneath. */
+    readonly artifactsDir: string;
+    /** Names the item in the containment refusal and in both issue locators. */
+    readonly workItemId: string;
+    /** Repository-relative bound path, as the persisted contract declares it. */
+    readonly resultPath: string;
+    /** The draw's standalone contract gate. */
+    readonly parse: (value: unknown) => SubmissionParse<TParsed>;
+    /** The submitted identity the duplicate check is asked about. */
+    readonly resultId: (parsed: TParsed) => string;
+    /** Caller-owned predicate; seeding and consume timing stay per-draw. */
+    readonly seen: (resultId: string) => boolean;
+    readonly messages: SubmissionScanMessages;
+}): Promise<SubmissionScanOutcome<TParsed>>;
+//# sourceMappingURL=submissionScan.d.ts.map

package/dist/shared/submission/submissionScan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submissionScan.d.ts","sourceRoot":"","sources":["../../../src/shared/submission/submissionScan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,2BAA2B,CAAC;AAGnC;;;;GAIG;AACH,MAAM,MAAM,eAAe,CAAC,OAAO,IAC/B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IACrD,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CAClD;AAED,yEAAyE;AACzE,MAAM,MAAM,qBAAqB,CAAC,OAAO,IACrC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;CAAE,CAAC;AAE5D;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE;IACzD,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,eAAe,CAAC,OAAO,CAAC,CAAC;IAC7D,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC;IAC/C,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;CAC3C,GAAG,OAAO,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CA2D1C"}

package/dist/shared/submission/submissionScan.js

@@ -0,0 +1,93 @@
+/**
+ * The ONE per-item host-submission scan both ingests draw from.
+ *
+ * Every submitted work item crosses the same four-step gate before any draw's
+ * domain work begins: resolve the bound path inside the boundary, read the
+ * bytes, classify a missing / unparseable / contract-invalid document, and
+ * refuse a `result_id` the caller has already seen. Both twins hand-rolled that
+ * sequence — audit in `readSubmittedResult` plus an inline duplicate check,
+ * remediate inline in its ingest loop — and the two copies had already drifted
+ * on CONTAINMENT: remediate re-checked the resolved path under the artifacts
+ * dir, audit checked the root only. This module resolves that in the stricter
+ * direction for BOTH draws.
+ *
+ * What it deliberately does NOT own — because these are the places the draws
+ * genuinely differ, not places they drifted:
+ *
+ * - the MESSAGE TEXT of each refusal (a per-draw renderer supplies it; the two
+ *   vocabularies are test-pinned and address different readers);
+ * - the DOMAIN PARSER (a callback; each draw's parser stays standalone, so the
+ *   hand-recovery lane can wrap `parseResult` directly and stay parity-pinned);
+ * - identity enforcement, which lives INSIDE those parsers — hoisting it would
+ *   change refusal precedence for a doubly-bad document;
+ * - loop iteration, aggregation order, seen-set seeding, and the TIMING of the
+ *   duplicate consume. Audit seeds from its persisted accepted ledger and
+ *   consumes only after conversion, validation and grounding; remediate uses a
+ *   fresh per-call set and consumes at parse. This scan only CHECKS.
+ */
+// Sibling modules imported DIRECTLY, never through ../index.js: the barrel
+// re-exports this module, so importing the barrel here would close a cycle
+// (index → submissionScan → index) that check:depgraph refuses.
+import { readSubmissionDocument, } from "./submissionClassifier.js";
+import { resolveContainedPath } from "./submissionIdentity.js";
+/**
+ * Scan one bound submission. Throws only where the twins already threw: a bound
+ * path that escapes the repository root or the artifacts dir is a boundary
+ * violation, not a classified submission failure.
+ */
+export async function scanBoundSubmission(params) {
+    const locators = {
+        work_item_id: params.workItemId,
+        result_path: params.resultPath,
+    };
+    const label = `result path for ${params.workItemId}`;
+    const absolutePath = resolveContainedPath(params.root, params.resultPath, label);
+    // Both boundaries, both draws: a submission lives under the artifacts dir,
+    // and root containment alone would admit any other tracked file in the repo.
+    resolveContainedPath(params.artifactsDir, absolutePath, label);
+    const read = await readSubmissionDocument(absolutePath);
+    if (read.kind === "missing") {
+        return {
+            ok: false,
+            issue: {
+                code: "submission_missing",
+                message: params.messages.missing(),
+                ...locators,
+            },
+        };
+    }
+    if (read.kind === "malformed") {
+        return {
+            ok: false,
+            issue: {
+                code: "submission_malformed",
+                message: params.messages.malformed(read.detail),
+                ...locators,
+            },
+        };
+    }
+    const parsed = params.parse(read.value);
+    if (!parsed.ok) {
+        return {
+            ok: false,
+            issue: {
+                code: "submission_contract_invalid",
+                message: params.messages.contractInvalid(parsed.detail),
+                ...locators,
+            },
+        };
+    }
+    const resultId = params.resultId(parsed.parsed);
+    if (params.seen(resultId)) {
+        return {
+            ok: false,
+            issue: {
+                code: "duplicate_submission_id",
+                message: params.messages.duplicate(resultId),
+                ...locators,
+            },
+        };
+    }
+    return { ok: true, parsed: parsed.parsed };
+}
+//# sourceMappingURL=submissionScan.js.map

package/dist/shared/submission/submissionScan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"submissionScan.js","sourceRoot":"","sources":["../../../src/shared/submission/submissionScan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,2EAA2E;AAC3E,2EAA2E;AAC3E,gEAAgE;AAChE,OAAO,EACL,sBAAsB,GAEvB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAgC/D;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAU,MAgBlD;IACC,MAAM,QAAQ,GAAG;QACf,YAAY,EAAE,MAAM,CAAC,UAAU;QAC/B,WAAW,EAAE,MAAM,CAAC,UAAU;KACtB,CAAC;IACX,MAAM,KAAK,GAAG,mBAAmB,MAAM,CAAC,UAAU,EAAE,CAAC;IACrD,MAAM,YAAY,GAAG,oBAAoB,CACvC,MAAM,CAAC,IAAI,EACX,MAAM,CAAC,UAAU,EACjB,KAAK,CACN,CAAC;IACF,2EAA2E;IAC3E,6EAA6E;IAC7E,oBAAoB,CAAC,MAAM,CAAC,YAAY,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC;IAE/D,MAAM,IAAI,GAAG,MAAM,sBAAsB,CAAC,YAAY,CAAC,CAAC;IACxD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE;gBACL,IAAI,EAAE,oBAAoB;gBAC1B,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE;gBAClC,GAAG,QAAQ;aACZ;SACF,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC9B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE;gBACL,IAAI,EAAE,sBAAsB;gBAC5B,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC;gBAC/C,GAAG,QAAQ;aACZ;SACF,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE;gBACL,IAAI,EAAE,6BAA6B;gBACnC,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC;gBACvD,GAAG,QAAQ;aACZ;SACF,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAChD,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE;gBACL,IAAI,EAAE,yBAAyB;gBAC/B,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC;gBAC5C,GAAG,QAAQ;aACZ;SACF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;AAC7C,CAAC"}

package/dist/shared/types/obligationLedger.d.ts

@@ -8,9 +8,13 @@
  */
 import type { ObligationEntry, ObligationLedger } from "./contractPipeline.js";
 /**
- * Detect cycles in an obligation dependency graph using DFS with three-color
- * marking (white/gray/black). Returns the IDs of obligations forming the first
- * cycle detected, or null when the graph is acyclic.
+ * Detect cycles in an obligation dependency graph. Returns the IDs of
+ * obligations forming the first cycle detected as a witness path with its start
+ * repeated at the end (`["A","B","A"]`), or null when the graph is acyclic.
+ *
+ * A thin draw over the shared directed-cycle core: an obligation that depends
+ * on ITSELF is a cycle here (self-loops included), and dependencies naming an
+ * id outside the ledger are external references the core ignores.
  *
  * INV-shared-core-07: called at construction time so a cycle is caught early
  * rather than causing an infinite loop or confusing error at scheduling time.

package/dist/shared/types/obligationLedger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"obligationLedger.d.ts","sourceRoot":"","sources":["../../../src/shared/types/obligationLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAK/B;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,SAAS,eAAe,EAAE,GACtC,MAAM,EAAE,GAAG,IAAI,CAmCjB;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,gBAAgB,CAgBlB"}
+{"version":3,"file":"obligationLedger.d.ts","sourceRoot":"","sources":["../../../src/shared/types/obligationLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAM/B;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,SAAS,eAAe,EAAE,GACtC,MAAM,EAAE,GAAG,IAAI,CAEjB;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,gBAAgB,CAgBlB"}

package/dist/shared/types/obligationLedger.js

@@ -7,49 +7,21 @@
  * if a dependency cycle is present.
  */
 import { CONTRACT_PIPELINE_OBLIGATION_LEDGER_VERSION, } from "./contractPipeline.js";
+import { findFirstCycleWitness } from "../graph/directedCycles.js";
 /**
- * Detect cycles in an obligation dependency graph using DFS with three-color
- * marking (white/gray/black). Returns the IDs of obligations forming the first
- * cycle detected, or null when the graph is acyclic.
+ * Detect cycles in an obligation dependency graph. Returns the IDs of
+ * obligations forming the first cycle detected as a witness path with its start
+ * repeated at the end (`["A","B","A"]`), or null when the graph is acyclic.
+ *
+ * A thin draw over the shared directed-cycle core: an obligation that depends
+ * on ITSELF is a cycle here (self-loops included), and dependencies naming an
+ * id outside the ledger are external references the core ignores.
  *
  * INV-shared-core-07: called at construction time so a cycle is caught early
  * rather than causing an infinite loop or confusing error at scheduling time.
  */
 export function detectObligationCycle(obligations) {
-    const idSet = new Set(obligations.map((o) => o.id));
-    const depMap = new Map();
-    for (const o of obligations) {
-        depMap.set(o.id, o.depends_on.filter((dep) => idSet.has(dep)));
-    }
-    // Three-color DFS: 0 = unvisited, 1 = in-stack (gray), 2 = done (black).
-    const color = new Map();
-    const path = [];
-    function dfs(id) {
-        const c = color.get(id) ?? 0;
-        if (c === 2)
-            return null; // already done
-        if (c === 1) {
-            // Cycle detected: return the cycle slice.
-            const cycleStart = path.indexOf(id);
-            return path.slice(cycleStart).concat(id);
-        }
-        color.set(id, 1);
-        path.push(id);
-        for (const dep of depMap.get(id) ?? []) {
-            const cycle = dfs(dep);
-            if (cycle)
-                return cycle;
-        }
-        path.pop();
-        color.set(id, 2);
-        return null;
-    }
-    for (const o of obligations) {
-        const cycle = dfs(o.id);
-        if (cycle)
-            return cycle;
-    }
-    return null;
+    return findFirstCycleWitness(obligations, { includeSelfLoops: true });
 }
 /**
  * Build a validated ObligationLedger.

package/dist/shared/types/obligationLedger.js.map

@@ -1 +1 @@
-{"version":3,"file":"obligationLedger.js","sourceRoot":"","sources":["../../../src/shared/types/obligationLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,EACL,2CAA2C,GAC5C,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,WAAuC;IAEvC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC3C,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;QAC5B,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACjE,CAAC;IAED,yEAAyE;IACzE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,MAAM,IAAI,GAAa,EAAE,CAAC;IAE1B,SAAS,GAAG,CAAC,EAAU;QACrB,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC,eAAe;QACzC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACZ,0CAA0C;YAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YACpC,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC3C,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACjB,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACd,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC;YACvC,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;YACvB,IAAI,KAAK;gBAAE,OAAO,KAAK,CAAC;QAC1B,CAAC;QACD,IAAI,CAAC,GAAG,EAAE,CAAC;QACX,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACxB,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;IAC1B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAQD;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAqC;IAErC,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAErD,MAAM,KAAK,GAAG,qBAAqB,CAAC,WAAW,CAAC,CAAC;IACjD,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CACb,wFAAwF,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAC5G,CAAC;IACJ,CAAC;IAED,OAAO;QACL,gBAAgB,EAAE,2CAA2C;QAC7D,OAAO;QACP,WAAW;QACX,UAAU,EAAE,UAAU,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACnD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"obligationLedger.js","sourceRoot":"","sources":["../../../src/shared/types/obligationLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,EACL,2CAA2C,GAC5C,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CACnC,WAAuC;IAEvC,OAAO,qBAAqB,CAAC,WAAW,EAAE,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC,CAAC;AACxE,CAAC;AAQD;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAqC;IAErC,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAErD,MAAM,KAAK,GAAG,qBAAqB,CAAC,WAAW,CAAC,CAAC;IACjD,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CACb,wFAAwF,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAC5G,CAAC;IACJ,CAAC;IAED,OAAO;QACL,gBAAgB,EAAE,2CAA2C;QAC7D,OAAO;QACP,WAAW;QACX,UAAU,EAAE,UAAU,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACnD,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audit-tools",
-  "version": "0.49.0",
+  "version": "0.50.2",
   "private": false,
   "license": "ISC",
   "description": "Provider-neutral code auditing and remediation workflows for arbitrary repositories.",
@@ -51,7 +51,7 @@
     "test": "npm run build && node scripts/shared/run-vitest-gate.mjs",
     "test:single": "npm run build && node scripts/shared/run-vitest-gate.mjs",
     "verify:guards": "node scripts/shared/run-vitest-gate.mjs --retry=2 --exclude \"**/audit-code-completion-*.test.ts\" --exclude \"**/audit-code-wrapper-*.test.ts\" --exclude \"**/audit/next-step-core-*.test.ts\" --exclude \"**/seam-host-only-next-step.test.ts\" --exclude \"**/*-e2e.test.*\" --exclude \"**/next-step-implement-dispatch.test.ts\" --exclude \"**/next-step-pipeline-dispatch.test.ts\"",
-    "verify:checks": "node scripts/shared/profile-run.mjs verify-checks check:control-bytes check:shared-primitives check:version-gates check:guard-reach check:ci-trigger-paths check:offload-lanes check:loop-core-patterns check:constitutional-doc-paths check:runtime-artifact-names check:executor-producers check:cli-surface check:deadcode check:lint check:dup check:depgraph check:doc-manifest check:doc-links check:doc-code-citations check:gate-enumeration check:philosophy-brief check:readme-sample-report check:proposal-red-at check:nightly-routine-prompt check:handoff-roadmap check:backlog-index check:memory-citations check:backlog-budget check:backlog-status check:backlog-line-numbers check:tests build check:scripts verify:hosts verify:remediate-hosts pack:smoke smoke:packaged-audit-code smoke:packaged-remediate-code",
+    "verify:checks": "node scripts/shared/profile-run.mjs verify-checks check:control-bytes check:shared-primitives check:version-gates check:guard-reach check:ci-trigger-paths check:offload-lanes check:loop-core-patterns check:constitutional-doc-paths check:runtime-artifact-names check:executor-producers check:spec-mirrors check:cli-surface check:deadcode check:lint check:dup check:depgraph check:doc-manifest check:doc-links check:doc-code-citations check:gate-enumeration check:philosophy-brief check:readme-sample-report check:proposal-red-at check:nightly-routine-prompt check:handoff-roadmap check:backlog-index check:memory-citations check:backlog-budget check:backlog-status check:backlog-line-numbers check:tests build check:scripts verify:hosts verify:remediate-hosts pack:smoke smoke:packaged-audit-code smoke:packaged-remediate-code",
     "verify:release": "npm run verify:checks && node scripts/shared/run-vitest-gate.mjs && npm run smoke:linked-audit-code && npm run smoke:linked-remediate-code",
     "check:control-bytes": "node scripts/check-control-bytes.mjs",
     "check:shared-primitives": "node scripts/check-shared-primitives.mjs",
@@ -101,6 +101,7 @@
     "check:backlog-line-numbers": "node scripts/check-backlog-line-numbers.mjs",
     "check:runtime-artifact-names": "node scripts/shared/generate-runtime-artifact-names.mjs --check",
     "check:executor-producers": "node scripts/shared/generate-executor-producers.mjs --check",
+    "check:spec-mirrors": "node scripts/shared/generate-spec-mirrors.mjs --check",
     "check:cli-surface": "node scripts/shared/generate-cli-surface.mjs --check",
     "generate:shard-baseline": "node scripts/shared/generate-vitest-shard-baseline.mjs"
   },

package/skills/audit-code/audit-code.prompt.md

@@ -21,8 +21,11 @@ repository root.
 
 Preserve user arguments:
 
-- pass the user-supplied target directory with `--root <path>` on every
-  `audit-code` command (`ensure` and each `next-step`)
+- run `audit-code` from inside the target repository; every command resolves
+  that repository's root from the working directory on its own, so normal usage
+  passes no `--root`
+- pass the user-supplied target directory with `--root <path>` only when running
+  from outside that repository
 
 This is the one full statement of the target-directory rule; the `audit-code`
 skill points here instead of restating it.

package/wrapper/audit-code-wrapper-install-hosts.mjs

@@ -19,6 +19,7 @@ import {
   findLegacyAuditCodeSurfaceFiles,
   removeLegacyAuditCodeSurfaceFiles,
 } from './audit-code-wrapper-legacy.mjs';
+import { resolveWrapperRoot } from './repo-root.mjs';
 import {
   renderVSCodeAgentFile,
   renderCodexAutomationRecipe,
@@ -603,7 +604,11 @@ export async function writeAntigravityAssets(assetPaths, promptBody, skillSource
 
 export async function installBootstrap(argv, options = {}) {
   const host = (getFlag(argv, '--host') ?? DEFAULT_INSTALL_HOST).toLowerCase();
-  const root = resolve(getFlag(argv, '--root') ?? '.');
+  // An absent --root is the repository the caller is standing in, discovered
+  // the same way `next-step` discovers it — never the cwd verbatim, which would
+  // deposit a full set of host assets in whatever subdirectory the operator
+  // happened to be in.
+  const root = resolveWrapperRoot(getFlag(argv, '--root'));
   await assertDirectoryExists(root, 'Target repository root');
   const profile = getInstallProfile(host);
   const promptSource = await readFile(promptAssetPath, 'utf8');
@@ -828,7 +833,7 @@ export async function verifyHostsIsolated(options = {}) {
 }
 
 export async function verifyInstalledBootstrap(argv) {
-  const root = resolve(getFlag(argv, '--root') ?? '.');
+  const root = resolveWrapperRoot(getFlag(argv, '--root'));
   const requestedHost = getFlag(argv, '--host')?.toLowerCase() ?? null;
   const installManifestPath = join(
     root,
@@ -1118,7 +1123,7 @@ export async function detectBootstrapRefreshReason(root, host) {
 
 export async function ensureBootstrap(argv) {
   const host = (getFlag(argv, '--host') ?? DEFAULT_INSTALL_HOST).toLowerCase();
-  const root = resolve(getFlag(argv, '--root') ?? '.');
+  const root = resolveWrapperRoot(getFlag(argv, '--root'));
   const quiet = hasFlag(argv, '--quiet');
   const force = hasFlag(argv, '--force');
   await assertDirectoryExists(root, 'Target repository root');

package/wrapper/audit-code-wrapper-lib.mjs

@@ -20,6 +20,7 @@ import {
   installerVerbHelp,
   installerVerbSummaries,
 } from './installer-verb-help.mjs';
+import { resolveWrapperRoot } from './repo-root.mjs';
 
 export { shouldBuildDistForPaths, assertWorkspaceInstalled };
 export { _INSTALL_HOST_ORDER, _INSTALL_HOST_DEFINITIONS, _getInstallHostKeys, _getInstallProfile, _renderGeminiCommandToml };
@@ -263,7 +264,7 @@ function printHelp({ usageName, preferredEntrypoint }) {
     '- status summarizes deterministic audit state and pending review work',
     '',
     'Defaults:',
-    '- --root .',
+    '- --root the repository the working directory is in (nearest ancestor owning .audit-tools/ or .git); pass it only to target a repository you are not inside',
     '- --artifacts-dir <root>/.audit-tools/audit',
   ];
 
@@ -284,7 +285,11 @@ async function printPromptPath() {
 
 async function runDistCommand(commandName, argv, { ensureArtifactsDir = false } = {}) {
   const commandArgs = [...argv];
-  const rootValue = resolve(getFlag(commandArgs, '--root') ?? '.');
+  // An absent --root is DISCOVERED (nearest ancestor owning .audit-tools/.git),
+  // not defaulted to the caller's cwd verbatim: the wrapper normalizes the root
+  // to an absolute path before the child sees it (CE-001), so a cwd-verbatim
+  // default here would pin the wrong root no matter what dist resolves.
+  const rootValue = resolveWrapperRoot(getFlag(commandArgs, '--root'));
   const artifactsDir = resolve(getFlag(commandArgs, '--artifacts-dir') ?? join(rootValue, '.audit-tools', 'audit'));
 
   // Overwrite (not default) so a user-supplied relative value is normalized to
@@ -304,7 +309,9 @@ async function runDistCommand(commandName, argv, { ensureArtifactsDir = false }
 
 async function runDistCommandInline(commandName, argv, { ensureArtifactsDir = false } = {}) {
   const commandArgs = [...argv];
-  const rootValue = resolve(getFlag(commandArgs, '--root') ?? '.');
+  // Same discovery as runDistCommand — the two paths must not answer "which
+  // repository is this?" differently.
+  const rootValue = resolveWrapperRoot(getFlag(commandArgs, '--root'));
   const artifactsDir = resolve(getFlag(commandArgs, '--artifacts-dir') ?? join(rootValue, '.audit-tools', 'audit'));
 
   setFlag(commandArgs, '--root', rootValue);

package/wrapper/installer-verb-help.mjs

@@ -97,7 +97,9 @@ export function installerVerbHelp(verb, { usageName, product }) {
     ...VERB_DETAIL[verb],
     '',
     'Common options:',
-    '- --root PATH   repository root (default: .)',
+    // NOT "(default: .)" — an absent --root is DISCOVERED (nearest ancestor
+    // owning .audit-tools/ or .git), not the cwd verbatim, on both bins.
+    '- --root PATH   repository root (default: the repository the working directory is in)',
     '- --quiet       suppress output',
   ].join('\n');
 }

package/wrapper/remediate-code-wrapper-install-hosts.mjs

@@ -21,6 +21,7 @@ import {
   findLegacyRemediateCodeSurfaceFiles,
   removeLegacyRemediateCodeSurfaceFiles,
 } from './remediate-code-wrapper-legacy.mjs';
+import { resolveWrapperRoot } from './repo-root.mjs';
 import {
   renderVSCodeAgentFile,
   renderCodexAutomationRecipe,
@@ -597,7 +598,11 @@ export async function writeAntigravityAssets(assetPaths, promptBody, skillSource
 
 export async function installBootstrap(argv, options = {}) {
   const host = (getFlag(argv, '--host') ?? DEFAULT_INSTALL_HOST).toLowerCase();
-  const root = resolve(getFlag(argv, '--root') ?? '.');
+  // An absent --root is the repository the caller is standing in, discovered
+  // the same way `next-step` discovers it — never the cwd verbatim, which would
+  // deposit a full set of host assets in whatever subdirectory the operator
+  // happened to be in.
+  const root = resolveWrapperRoot(getFlag(argv, '--root'));
   await assertDirectoryExists(root, 'Target repository root');
   const profile = getInstallProfile(host);
   const promptSource = (await readFile(promptAssetPath, 'utf8')).replace(/\r\n/g, '\n');
@@ -864,7 +869,7 @@ export async function verifyHostsIsolated(options = {}) {
 }
 
 export async function verifyInstalledBootstrap(argv) {
-  const root = resolve(getFlag(argv, '--root') ?? '.');
+  const root = resolveWrapperRoot(getFlag(argv, '--root'));
   const requestedHost = getFlag(argv, '--host')?.toLowerCase() ?? null;
   const installManifestPath = join(
     root,
@@ -1154,7 +1159,7 @@ export async function detectBootstrapRefreshReason(root, host) {
 
 export async function ensureBootstrap(argv) {
   const host = (getFlag(argv, '--host') ?? DEFAULT_INSTALL_HOST).toLowerCase();
-  const root = resolve(getFlag(argv, '--root') ?? '.');
+  const root = resolveWrapperRoot(getFlag(argv, '--root'));
   const quiet = hasFlag(argv, '--quiet');
   const force = hasFlag(argv, '--force');
   await assertDirectoryExists(root, 'Target repository root');

package/wrapper/repo-root.mjs

@@ -0,0 +1,80 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve, sep } from 'node:path';
+
+// Canonical repo-root discovery for the WRAPPER side of BOTH bins.
+//
+// Bin-neutral by name and by ownership, like `installer-verb-help.mjs`: audit-code
+// and remediate-code answer their installer verbs from this one module, so the two
+// wrappers cannot resolve "no --root" differently (one core, two draws — never a
+// per-bin fork of the same algorithm).
+//
+// This is a deliberate, pinned MIRROR of `discoverRepoRoot` / `climbOutOfAuditTools`
+// in src/shared/io/repoRoot.ts, kept for the same bootstrap constraint that
+// forces `quoteForCmd` to be mirrored here: the wrapper runs BEFORE dist exists
+// (the installer verbs `ensure` / `install` / `verify-install` are answered
+// entirely in the wrapper and must never trigger a build just to learn where
+// they are), so it cannot import the TypeScript source or the built module.
+// `tests/shared/wrapper-repo-root-parity.test.ts` runs BOTH implementations over
+// the same fixture trees and fails if they ever disagree — the two copies cannot
+// drift silently.
+//
+// Behaviour, stated once here and pinned by that parity test: climb out of any
+// `.audit-tools/` the start dir sits inside, then walk up to the nearest
+// ancestor carrying `.audit-tools` or `.git` (either may be a file — a linked
+// worktree's `.git` is one), stopping BELOW the home directory because
+// `~/.audit-tools/` is the tool's machine-wide cache home and would otherwise
+// match on every box. No marker → the start dir unchanged.
+
+export const AUDIT_TOOLS_DIRNAME = '.audit-tools';
+
+export const REPO_ROOT_MARKERS = [AUDIT_TOOLS_DIRNAME, '.git'];
+
+/** @param {string} p */
+export function climbOutOfAuditTools(p) {
+  const resolved = resolve(p);
+  const segments = resolved.split(sep);
+  const idx = segments.indexOf(AUDIT_TOOLS_DIRNAME);
+  if (idx <= 0) return resolved;
+  return segments.slice(0, idx).join(sep) || resolved;
+}
+
+/** @returns {string | null} */
+function repoRootCeiling() {
+  try {
+    const home = homedir();
+    return home ? resolve(home) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** @param {string} [startDir] @returns {string} */
+export function discoverRepoRoot(startDir = process.cwd()) {
+  const start = climbOutOfAuditTools(resolve(startDir));
+  const ceiling = repoRootCeiling();
+  let current = start;
+  for (;;) {
+    if (ceiling !== null && current === ceiling) return start;
+    if (REPO_ROOT_MARKERS.some((marker) => existsSync(join(current, marker)))) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return start;
+    current = parent;
+  }
+}
+
+/**
+ * The root a wrapper-side command acts on: an explicitly supplied `--root` is
+ * honored verbatim (resolved against the caller's cwd), an absent one is
+ * discovered. The ONE place either wrapper turns "no --root" into a directory,
+ * so `next-step`, `ensure`, `install` and `verify-install` cannot answer it
+ * differently — across both bins.
+ *
+ * @param {string | undefined} rawRoot
+ * @returns {string}
+ */
+export function resolveWrapperRoot(rawRoot) {
+  return rawRoot === undefined ? discoverRepoRoot() : resolve(rawRoot);
+}