audit-tools 0.51.11 → 0.52.1

package/dist/remediate/review/reviewGate.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import type { Finding, FindingSeverity, FindingConfidence } from "audit-tools/shared";
 import { type ReviewNecessity, type ImplementationCost } from "./reviewNecessity.js";
 export declare const REVIEW_REQUEST_SCHEMA_VERSION: "remediate-code-review-request/v1";
@@ -31,18 +32,59 @@ export interface ReviewRequest {
     /** Non-empty tiers only, ordered most-review-needed first. */
     tiers: ReviewTierGroup[];
 }
-/** The user's verdict (`review_resolution.json`). */
-export interface ReviewResolution {
-    plan_id?: string;
-    /** Finding ids the user disapproved — do NOT act on these. */
-    disapproved_findings?: string[];
-    /** Whole tiers the user disapproved (e.g. "decline everything strategic"). */
-    disapproved_tiers?: ReviewNecessity[];
+/**
+ * The user's verdict (`review_resolution.json`). Strict at every level: the
+ * gate's default is APPROVE, so a field the tool does not read (a mistyped
+ * name, the retired `disapproved_*` names) would turn the user's decline into
+ * an approval in silence. An unknown field refuses the whole file instead.
+ */
+declare const ReviewResolutionSchema: z.ZodObject<{
+    plan_id: z.ZodOptional<z.ZodString>;
+    /** Findings the user declined — do NOT act on these. */
+    declined_findings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        finding_id: z.ZodString;
+        /** The user's reason, in their words. Blank reads as absent. */
+        reason: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        finding_id: string;
+        reason?: string | undefined;
+    }, {
+        finding_id: string;
+        reason?: string | undefined;
+    }>, "many">>;
+    /** Whole tiers the user declined (e.g. "decline everything strategic"). */
+    declined_tiers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    plan_id?: string | undefined;
+    declined_findings?: {
+        finding_id: string;
+        reason?: string | undefined;
+    }[] | undefined;
+    declined_tiers?: string[] | undefined;
+}, {
+    plan_id?: string | undefined;
+    declined_findings?: {
+        finding_id: string;
+        reason?: string | undefined;
+    }[] | undefined;
+    declined_tiers?: string[] | undefined;
+}>;
+export type ReviewResolution = z.infer<typeof ReviewResolutionSchema>;
+export type ParsedReviewResolution = {
+    kind: "ok";
+    resolution: ReviewResolution;
 }
+/** A resolution from another run (its `plan_id` names a different request). */
+ | {
+    kind: "stale";
+} | {
+    kind: "refused";
+    reason: string;
+};
 export interface ReviewDecision {
     /** Finding ids approved to proceed to implementation. */
     approved_ids: string[];
-    /** Disapproved items, each with the recorded reason for its terminal disposition. */
+    /** Declined items, each with the recorded reason for its terminal disposition. */
     declined: Array<{
         finding_id: string;
         reason: string;
@@ -56,44 +98,31 @@ export interface ReviewDecision {
  */
 export declare function buildReviewRequest(findings: readonly Finding[], planId: string): ReviewRequest;
 /**
- * Whether `resolution` answers THIS `request` (INV-RSM-RESOLUTION-CORRELATE).
- * An absent resolution or an absent `plan_id` correlates (host-lenient: the
- * single-run common case writes no plan_id); a PRESENT plan_id that differs
- * from the request's marks a stale leftover from another run — the caller must
- * archive it and re-halt rather than apply a cross-run answer.
+ * Read the text of `review_resolution.json` against the request it answers.
+ * The WHOLE file is refused — never partly applied — when it is not valid
+ * JSON, has a field the schema does not name (the retired `disapproved_*`
+ * names get their replacement stated), has a wrong type, or names an id or a
+ * tier outside the request. The reason names each problem. A file whose
+ * `plan_id` names a different request is `stale`: it answers another run.
  */
-export declare function isResolutionForRequest(request: ReviewRequest, resolution: ReviewResolution | null | undefined): boolean;
-/**
- * Screen a resolution's id references against the request (uniform id-join
- * contract): every `disapproved_findings` entry must name an item in the
- * request, and every `disapproved_tiers` entry must be one of the closed
- * review-necessity names. A stray id here is not a no-op — the gate's default
- * is APPROVE, so a typo'd decline would silently become an approval. Empty
- * arrays = clean. A tier that is valid but empty in this request stays a
- * harmless no-op (it names a real vocabulary member, not a phantom item).
- */
-export declare function screenResolutionIds(request: ReviewRequest, resolution: ReviewResolution | null | undefined): {
-    unknown_finding_ids: string[];
-    unknown_tiers: string[];
-    valid_finding_ids: string[];
-};
+export declare function parseReviewResolution(text: string, request: ReviewRequest): ParsedReviewResolution;
 /**
  * Apply the user's resolution to a request: every item is either approved (act
  * on it) or declined (recorded terminal disposition with a reason). An item is
- * declined if its id is in `disapproved_findings` OR its tier is in
- * `disapproved_tiers`. Everything else is approved — the default is to act,
+ * declined if its id is in `declined_findings` OR its tier is in
+ * `declined_tiers`. Everything else is approved — the default is to act,
  * because the gate's job is to let the user REMOVE items, not to require
  * opting every item in. An absent/empty resolution approves everything.
  *
- * A resolution carrying a MISMATCHED `plan_id` is rejected (throws): applying a
- * stale cross-run answer would approve/decline the wrong finding set
- * (INV-RSM-RESOLUTION-CORRELATE, COR-0b906e37). Callers pre-screen with
- * {@link isResolutionForRequest} to archive-and-re-halt instead of crashing;
- * the throw here is the mechanical backstop, not the primary UX.
+ * The resolution must come from {@link parseReviewResolution}; a stale
+ * `plan_id` or an unknown id still throws here as the mechanical backstop
+ * (INV-RSM-RESOLUTION-CORRELATE, COR-0b906e37), never the primary UX.
  *
- * Crucially, declined items are returned with an explicit reason so the caller
- * records a terminal disposition (e.g. `ignored`) rather than silently closing
- * them — the exact failure this gate exists to prevent.
+ * Crucially, declined items are returned with an explicit reason — the user's
+ * own words when they gave one — so the caller records a terminal disposition
+ * (e.g. `ignored`) rather than silently closing them, the exact failure this
+ * gate exists to prevent.
  */
-export declare function applyReviewResolution(request: ReviewRequest, resolution: ReviewResolution | null | undefined): ReviewDecision;
+export declare function applyReviewResolution(request: ReviewRequest, resolution: ReviewResolution | undefined): ReviewDecision;
+export {};
 //# sourceMappingURL=reviewGate.d.ts.map

package/dist/remediate/review/reviewGate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reviewGate.d.ts","sourceRoot":"","sources":["../../../src/remediate/review/reviewGate.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EAKxB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,6BAA6B,EAAG,kCAA2C,CAAC;AAEzF,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,iBAAiB,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,SAAS,EAAE,eAAe,CAAC;IAC3B,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,kBAAkB,CAAC;CACzC;AAED,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,eAAe,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,eAAe,EAAE,CAAC;CAC1B;AAED,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,OAAO,6BAA6B,CAAC;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IACxC,8DAA8D;IAC9D,KAAK,EAAE,eAAe,EAAE,CAAC;CAC1B;AAED,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE,eAAe,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,qFAAqF;IACrF,QAAQ,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzD;AAsBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,MAAM,EAAE,MAAM,GACb,aAAa,CAyBf;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAC9C,OAAO,CAIT;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAC9C;IAAE,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAC;IAAC,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAAE,CAazF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAC9C,cAAc,CAsDhB"}
+{"version":3,"file":"reviewGate.d.ts","sourceRoot":"","sources":["../../../src/remediate/review/reviewGate.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EAKxB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,6BAA6B,EAAG,kCAA2C,CAAC;AAEzF,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,iBAAiB,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,SAAS,EAAE,eAAe,CAAC;IAC3B,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,kBAAkB,CAAC;CACzC;AAED,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,eAAe,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,eAAe,EAAE,CAAC;CAC1B;AAED,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,OAAO,6BAA6B,CAAC;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IACxC,8DAA8D;IAC9D,KAAK,EAAE,eAAe,EAAE,CAAC;CAC1B;AAED;;;;;GAKG;AACH,QAAA,MAAM,sBAAsB;;IAGxB,wDAAwD;;;QAMhD,gEAAgE;;;;;;;;;IAMxE,2EAA2E;;;;;;;;;;;;;;;;EAGpE,CAAC;AAEZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAStE,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,gBAAgB,CAAA;CAAE;AAC9C,+EAA+E;GAC7E;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,kFAAkF;IAClF,QAAQ,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzD;AAsBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,MAAM,EAAE,MAAM,GACb,aAAa,CAyBf;AAkDD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,aAAa,GACrB,sBAAsB,CA8CxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,gBAAgB,GAAG,SAAS,GACvC,cAAc,CA0ChB"}

package/dist/remediate/review/reviewGate.js

@@ -1,5 +1,6 @@
+// sites-pinned: tests/remediate/reviewGate.test.ts, tests/remediate/next-step-review-gate.test.ts
 // Review-approval gate engine — builds the tiered item-set the user
-// approves/disapproves, and consumes their verdict.
+// approves or declines, and consumes their verdict.
 //
 // This is the single review surface for both paths. It replaced the classic
 // per-block implementation-risk preview, which fired AFTER the contract pipeline
@@ -14,10 +15,39 @@
 // pipeline can mark it terminal-without-change.
 //
 // Tool owns the structure (tiering, rationale, cost, which items must be shown);
-// the host fills only the semantic pros/cons slots when presenting. Disapproved
+// the host fills only the semantic pros/cons slots when presenting. Declined
 // items become a RECORDED terminal disposition, never a silent close.
+import { z } from "zod";
 import { classifyReviewNecessity, partitionByReviewNecessity, REVIEW_NECESSITY_ORDER, REVIEW_NECESSITY_LABELS, } from "./reviewNecessity.js";
 export const REVIEW_REQUEST_SCHEMA_VERSION = "remediate-code-review-request/v1";
+/**
+ * The user's verdict (`review_resolution.json`). Strict at every level: the
+ * gate's default is APPROVE, so a field the tool does not read (a mistyped
+ * name, the retired `disapproved_*` names) would turn the user's decline into
+ * an approval in silence. An unknown field refuses the whole file instead.
+ */
+const ReviewResolutionSchema = z
+    .object({
+    plan_id: z.string().optional(),
+    /** Findings the user declined — do NOT act on these. */
+    declined_findings: z
+        .array(z
+        .object({
+        finding_id: z.string(),
+        /** The user's reason, in their words. Blank reads as absent. */
+        reason: z.string().optional(),
+    })
+        .strict())
+        .optional(),
+    /** Whole tiers the user declined (e.g. "decline everything strategic"). */
+    declined_tiers: z.array(z.string()).optional(),
+})
+    .strict();
+/** The retired field names, each with the field that replaced it. */
+const RETIRED_RESOLUTION_FIELDS = {
+    disapproved_findings: '`declined_findings`, whose entries are `{ "finding_id": "<id>", "reason": "<optional>" }`',
+    disapproved_tiers: "`declined_tiers`",
+};
 function firstPath(finding) {
     return (finding.affected_files ?? []).map((f) => f.path).filter(Boolean);
 }
@@ -76,88 +106,141 @@ export function buildReviewRequest(findings, planId) {
  * from the request's marks a stale leftover from another run — the caller must
  * archive it and re-halt rather than apply a cross-run answer.
  */
-export function isResolutionForRequest(request, resolution) {
+function isResolutionForRequest(request, resolution) {
     const resolutionPlanId = resolution?.plan_id;
     if (resolutionPlanId === undefined)
         return true;
     return resolutionPlanId === request.plan_id;
 }
 /**
- * Screen a resolution's id references against the request (uniform id-join
- * contract): every `disapproved_findings` entry must name an item in the
- * request, and every `disapproved_tiers` entry must be one of the closed
- * review-necessity names. A stray id here is not a no-op — the gate's default
- * is APPROVE, so a typo'd decline would silently become an approval. Empty
- * arrays = clean. A tier that is valid but empty in this request stays a
- * harmless no-op (it names a real vocabulary member, not a phantom item).
+ * The id references a resolution names outside the request (uniform id-join
+ * contract): every `declined_findings` id must name an item in the request,
+ * and every `declined_tiers` entry must be one of the closed review-necessity
+ * names. A tier that is valid but empty in this request stays a harmless no-op
+ * (it names a real vocabulary member, not a phantom item).
  */
-export function screenResolutionIds(request, resolution) {
+function unknownResolutionIds(request, resolution) {
     const validIds = request.tiers.flatMap((t) => t.items.map((i) => i.finding_id));
     const validIdSet = new Set(validIds);
     const validTiers = new Set(REVIEW_NECESSITY_ORDER);
-    return {
-        unknown_finding_ids: (resolution?.disapproved_findings ?? []).filter((id) => !validIdSet.has(id)),
-        unknown_tiers: (resolution?.disapproved_tiers ?? []).filter((t) => !validTiers.has(t)),
-        valid_finding_ids: validIds,
-    };
+    const problems = [];
+    (resolution.declined_findings ?? []).forEach((entry, index) => {
+        if (!validIdSet.has(entry.finding_id)) {
+            problems.push(`\`declined_findings[${index}].finding_id\`: \`${entry.finding_id}\` is not in the request (valid: ${validIds.map((i) => `\`${i}\``).join(", ")})`);
+        }
+    });
+    (resolution.declined_tiers ?? []).forEach((tier, index) => {
+        if (!validTiers.has(tier)) {
+            problems.push(`\`declined_tiers[${index}]\`: \`${tier}\` is not a tier (valid: ${REVIEW_NECESSITY_ORDER.map((t) => `\`${t}\``).join(", ")})`);
+        }
+    });
+    return problems;
+}
+/**
+ * Read the text of `review_resolution.json` against the request it answers.
+ * The WHOLE file is refused — never partly applied — when it is not valid
+ * JSON, has a field the schema does not name (the retired `disapproved_*`
+ * names get their replacement stated), has a wrong type, or names an id or a
+ * tier outside the request. The reason names each problem. A file whose
+ * `plan_id` names a different request is `stale`: it answers another run.
+ */
+export function parseReviewResolution(text, request) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        return {
+            kind: "refused",
+            reason: `the file is not valid JSON (${error instanceof Error ? error.message : String(error)})`,
+        };
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return {
+            kind: "refused",
+            reason: 'the file must be one JSON object: `{ "declined_findings": [...], "declined_tiers": [...] }`',
+        };
+    }
+    const planId = value.plan_id;
+    if (typeof planId === "string" && planId !== request.plan_id)
+        return { kind: "stale" };
+    const problems = [];
+    for (const [retired, replacement] of Object.entries(RETIRED_RESOLUTION_FIELDS)) {
+        if (retired in value) {
+            problems.push(`\`${retired}\` is not a field — write ${replacement}`);
+        }
+    }
+    const parsed = ReviewResolutionSchema.safeParse(value);
+    if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+            if (issue.code === z.ZodIssueCode.unrecognized_keys) {
+                const unknown = issue.keys.filter((k) => !(k in RETIRED_RESOLUTION_FIELDS));
+                const where = issue.path.length > 0 ? ` in \`${issue.path.join(".")}\`` : "";
+                if (unknown.length > 0) {
+                    problems.push(`unknown field(s)${where}: ${unknown.map((k) => `\`${k}\``).join(", ")}`);
+                }
+                continue;
+            }
+            const field = issue.path.length > 0 ? `\`${issue.path.join(".")}\`: ` : "";
+            problems.push(`${field}${issue.message}`);
+        }
+    }
+    else {
+        problems.push(...unknownResolutionIds(request, parsed.data));
+    }
+    return problems.length > 0 || !parsed.success
+        ? { kind: "refused", reason: problems.join("; ") }
+        : { kind: "ok", resolution: parsed.data };
 }
 /**
  * Apply the user's resolution to a request: every item is either approved (act
  * on it) or declined (recorded terminal disposition with a reason). An item is
- * declined if its id is in `disapproved_findings` OR its tier is in
- * `disapproved_tiers`. Everything else is approved — the default is to act,
+ * declined if its id is in `declined_findings` OR its tier is in
+ * `declined_tiers`. Everything else is approved — the default is to act,
  * because the gate's job is to let the user REMOVE items, not to require
  * opting every item in. An absent/empty resolution approves everything.
  *
- * A resolution carrying a MISMATCHED `plan_id` is rejected (throws): applying a
- * stale cross-run answer would approve/decline the wrong finding set
- * (INV-RSM-RESOLUTION-CORRELATE, COR-0b906e37). Callers pre-screen with
- * {@link isResolutionForRequest} to archive-and-re-halt instead of crashing;
- * the throw here is the mechanical backstop, not the primary UX.
+ * The resolution must come from {@link parseReviewResolution}; a stale
+ * `plan_id` or an unknown id still throws here as the mechanical backstop
+ * (INV-RSM-RESOLUTION-CORRELATE, COR-0b906e37), never the primary UX.
  *
- * Crucially, declined items are returned with an explicit reason so the caller
- * records a terminal disposition (e.g. `ignored`) rather than silently closing
- * them — the exact failure this gate exists to prevent.
+ * Crucially, declined items are returned with an explicit reason — the user's
+ * own words when they gave one — so the caller records a terminal disposition
+ * (e.g. `ignored`) rather than silently closing them, the exact failure this
+ * gate exists to prevent.
  */
 export function applyReviewResolution(request, resolution) {
     if (!isResolutionForRequest(request, resolution)) {
         throw new Error(`review resolution plan_id "${resolution?.plan_id}" does not answer review request plan_id "${request.plan_id}" — stale cross-run resolution rejected (INV-RSM-RESOLUTION-CORRELATE).`);
     }
-    const screen = screenResolutionIds(request, resolution);
-    if (screen.unknown_finding_ids.length > 0 || screen.unknown_tiers.length > 0) {
-        // Uniform id-join contract: refuse the WHOLE resolution. Callers pre-screen
-        // with screenResolutionIds to archive-and-re-halt; this throw is the
-        // mechanical backstop, mirroring the plan_id-mismatch backstop above.
-        const parts = [];
-        if (screen.unknown_finding_ids.length > 0) {
-            parts.push(`unknown finding id(s) ${screen.unknown_finding_ids.map((i) => `"${i}"`).join(", ")} ` +
-                `(valid: ${screen.valid_finding_ids.join(", ")})`);
-        }
-        if (screen.unknown_tiers.length > 0) {
-            parts.push(`unknown tier(s) ${screen.unknown_tiers.map((t) => `"${t}"`).join(", ")} ` +
-                `(valid: ${REVIEW_NECESSITY_ORDER.join(", ")})`);
-        }
-        throw new Error(`review resolution refused — ${parts.join("; ")}. The gate's default is approve, ` +
-            `so a mistyped decline would silently become an approval; re-submit the whole ` +
-            `resolution with ids drawn from the request.`);
+    const unknown = resolution ? unknownResolutionIds(request, resolution) : [];
+    if (unknown.length > 0) {
+        throw new Error(`review resolution refused — ${unknown.join("; ")}`);
     }
-    const disapprovedIds = new Set(resolution?.disapproved_findings ?? []);
-    const disapprovedTiers = new Set(resolution?.disapproved_tiers ?? []);
+    const userReasons = new Map((resolution?.declined_findings ?? []).map((d) => [d.finding_id, d.reason?.trim() || undefined]));
+    const declinedTiers = new Set(resolution?.declined_tiers ?? []);
     const approved_ids = [];
     const declined = [];
     for (const tier of request.tiers) {
-        const tierDisapproved = disapprovedTiers.has(tier.necessity);
+        const tierDeclined = declinedTiers.has(tier.necessity);
         for (const item of tier.items) {
-            if (tierDisapproved) {
+            const userReason = userReasons.get(item.finding_id);
+            if (userReason !== undefined) {
+                declined.push({
+                    finding_id: item.finding_id,
+                    reason: `Declined by the user at the review gate: ${userReason}`,
+                });
+            }
+            else if (tierDeclined) {
                 declined.push({
                     finding_id: item.finding_id,
-                    reason: `Disapproved by the user at the review gate — declined the entire "${item.necessity}" tier.`,
+                    reason: `Declined by the user at the review gate — declined the entire "${item.necessity}" tier.`,
                 });
             }
-            else if (disapprovedIds.has(item.finding_id)) {
+            else if (userReasons.has(item.finding_id)) {
                 declined.push({
                     finding_id: item.finding_id,
-                    reason: `Disapproved by the user at the review gate (review-necessity: ${item.necessity}).`,
+                    reason: `Declined by the user at the review gate (review-necessity: ${item.necessity}).`,
                 });
             }
             else {

package/dist/remediate/review/reviewGate.js.map

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

package/dist/remediate/state/store.d.ts

@@ -1,5 +1,5 @@
 import { SKIP_WRITE } from "audit-tools/shared";
-import { RemediationPlan, RemediationItemState, ClarificationRequest, ClosingPlan, CoverageLedger, RemediationHostHandoffRecord } from "./types.js";
+import { RemediationPlan, RemediationItemState, ClosingPlan, CoverageLedger, RemediationHostHandoffRecord } from "./types.js";
 import { type RemediationRunStatus } from "./runStatus.js";
 /**
  * The schema version stamped on every persisted `state.json`.
@@ -44,7 +44,6 @@ export interface RemediationState {
     status: RemediationRunStatus;
     plan?: RemediationPlan;
     items?: Record<string, RemediationItemState>;
-    clarifications?: ClarificationRequest[];
     closing_plan?: ClosingPlan;
     started_at?: string;
     step_count?: number;

package/dist/remediate/state/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/remediate/state/store.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,UAAU,EAEX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,WAAW,EACX,cAAc,EACd,4BAA4B,EAE7B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,kCAAkC,EAC7C,+BAAwC,CAAC;AAK3C,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,kCAAkC,CAAC;IAC7D,MAAM,EAAE,oBAAoB,CAAC;IAC7B,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC7C,cAAc,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACxC,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,cAAc,CAAC;IAC/B;;;;OAIG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC;IAChC;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC;;;;;;;;;;;;;;;;;;OAkBG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;OAIG;IACH,YAAY,CAAC,EAAE,4BAA4B,CAAC;CAC7C;AA+ID,eAAO,MAAM,eAAe,QAA+B,CAAC;AAU5D,qBAAa,UAAU;IAWnB,OAAO,CAAC,YAAY;IAEpB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;IAZlC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2C;gBAGvD,YAAY,EAAE,MAAM,EAEX,cAAc,CAAC,EAAE,MAAM,YAAA;IA4CpC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;;;;;;OAQG;IACG,SAAS,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAInD;;;;;;;;;;;;;;OAcG;IACG,MAAM,CACV,EAAE,EAAE,CACF,OAAO,EAAE,gBAAgB,GAAG,IAAI,KAC7B,OAAO,CAAC,gBAAgB,GAAG,OAAO,UAAU,CAAC,GACjD,OAAO,CAAC,gBAAgB,CAAC;IA4B5B;;;;;OAKG;IACG,SAAS,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAMxD"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/remediate/state/store.ts"],"names":[],"mappings":"AAGA,OAAO,EAKL,UAAU,EAEX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,WAAW,EAEX,cAAc,EACd,4BAA4B,EAE7B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,kCAAkC,EAC7C,+BAAwC,CAAC;AAK3C,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,kCAAkC,CAAC;IAC7D,MAAM,EAAE,oBAAoB,CAAC;IAC7B,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC7C,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,cAAc,CAAC;IAC/B;;;;OAIG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC;IAChC;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC;;;;;;;;;;;;;;;;;;OAkBG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;OAIG;IACH,YAAY,CAAC,EAAE,4BAA4B,CAAC;CAC7C;AA4QD,eAAO,MAAM,eAAe,QAA+B,CAAC;AAU5D,qBAAa,UAAU;IAWnB,OAAO,CAAC,YAAY;IAEpB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;IAZlC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2C;gBAGvD,YAAY,EAAE,MAAM,EAEX,cAAc,CAAC,EAAE,MAAM,YAAA;IA+CpC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;;;;;;OAQG;IACG,SAAS,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAInD;;;;;;;;;;;;;;OAcG;IACG,MAAM,CACV,EAAE,EAAE,CACF,OAAO,EAAE,gBAAgB,GAAG,IAAI,KAC7B,OAAO,CAAC,gBAAgB,GAAG,OAAO,UAAU,CAAC,GACjD,OAAO,CAAC,gBAAgB,CAAC;IA4B5B;;;;;OAKG;IACG,SAAS,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAMxD"}

package/dist/remediate/state/store.js

@@ -1,7 +1,8 @@
+// sites-pinned: tests/remediate/clarification-round-contract.test.ts
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { createLockedJsonStore, LOCKED_JSON_STORE_TIMEOUT_MS, SchemaVersionMismatchError, SKIP_WRITE, assertNotNodeWorktreeCwd, } from "audit-tools/shared";
-import { RemediationHostHandoffRecordSchema, } from "./types.js";
+import { isClarificationCategory, RemediationHostHandoffRecordSchema, } from "./types.js";
 import { validateRemediationBlock } from "../validation/remediationState.js";
 import { REMEDIATION_RUN_STATUSES, isRemediationRunStatus, } from "./runStatus.js";
 /**
@@ -142,6 +143,7 @@ function validateState(value) {
             }
         }
     }
+    errors.push(...clarificationQuestionErrors(obj));
     if (status === "closing") {
         const closingPlan = obj["closing_plan"];
         if (!closingPlan || typeof closingPlan !== "object" || Array.isArray(closingPlan)) {
@@ -161,6 +163,122 @@ function validateState(value) {
     }
     return errors;
 }
+/**
+ * The clarification invariants. A worker question lives on its item, so:
+ *
+ * - the retired run-level `clarifications` list is refused (it was a second
+ *   copy of the questions, and clearing it after a partial answer left the
+ *   unanswered items with nothing to show — the round then listed no question
+ *   and the run could not progress);
+ * - an item paused as `needs_clarification` must carry its question, because
+ *   the clarification round is built from those items alone.
+ *
+ * A state written before the move is translated on READ by
+ * {@link adoptLegacyClarifications}, so these refuse only a WRITE of the old
+ * shape.
+ */
+function clarificationQuestionErrors(obj) {
+    const errors = [];
+    if (obj["clarifications"] !== undefined) {
+        errors.push("clarifications is retired: a worker question lives on its item as clarification_question");
+    }
+    const items = obj["items"];
+    if (!items || typeof items !== "object" || Array.isArray(items))
+        return errors;
+    for (const [key, item] of Object.entries(items)) {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const it = item;
+        if (it["status"] !== "needs_clarification")
+            continue;
+        const question = it["clarification_question"];
+        if (!question ||
+            typeof question !== "object" ||
+            Array.isArray(question) ||
+            !isClarificationCategory(question["category"]) ||
+            typeof question["description"] !== "string" ||
+            question["description"].trim().length === 0) {
+            errors.push(`items["${key}"] is needs_clarification but carries no valid clarification_question ` +
+                "(a category and a non-empty description)");
+        }
+    }
+    return errors;
+}
+/**
+ * The READ rule for a state written before the worker question moved onto its
+ * item. Such a state holds the questions in a run-level `clarifications` list,
+ * and the old ingest ALSO wrote each question into the paused item's
+ * `failure_reason`.
+ *
+ * Every `needs_clarification` item without a `clarification_question` takes
+ * one: from its entry in the legacy list when there is one, else from its
+ * `failure_reason` (this recovers a run that the old partial-answer defect
+ * already wedged, where the list was cleared but the item still waits). The
+ * legacy list is then dropped, and the next write persists the new shape.
+ *
+ * This is the one place a read is not byte-faithful, and it touches only the
+ * retired shape: a current state passes through unchanged.
+ */
+function adoptLegacyClarifications(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return raw;
+    const obj = raw;
+    const items = obj["items"];
+    const hasItems = Boolean(items) && typeof items === "object" && !Array.isArray(items);
+    const needsQuestion = hasItems
+        ? Object.values(items).some((item) => Boolean(item) &&
+            typeof item === "object" &&
+            item["status"] === "needs_clarification" &&
+            item["clarification_question"] === undefined)
+        : false;
+    if (obj["clarifications"] === undefined && !needsQuestion)
+        return raw;
+    const legacy = new Map();
+    if (Array.isArray(obj["clarifications"])) {
+        for (const entry of obj["clarifications"]) {
+            if (!entry || typeof entry !== "object" || Array.isArray(entry))
+                continue;
+            const e = entry;
+            if (typeof e["finding_id"] === "string" && !legacy.has(e["finding_id"])) {
+                legacy.set(e["finding_id"], e);
+            }
+        }
+    }
+    const { clarifications: _retired, ...rest } = obj;
+    if (!hasItems)
+        return rest;
+    const nextItems = {};
+    for (const [key, item] of Object.entries(items)) {
+        const it = item;
+        if (!it ||
+            typeof it !== "object" ||
+            it["status"] !== "needs_clarification" ||
+            it["clarification_question"] !== undefined) {
+            nextItems[key] = item;
+            continue;
+        }
+        const entry = legacy.get(key);
+        const description = typeof entry?.["description"] === "string" && entry["description"].trim()
+            ? entry["description"]
+            : typeof it["failure_reason"] === "string" && it["failure_reason"].trim()
+                ? it["failure_reason"]
+                : "The worker paused this finding for a clarification but recorded no question text.";
+        const options = Array.isArray(entry?.["options"])
+            ? entry["options"].filter((o) => typeof o === "string")
+            : [];
+        nextItems[key] = {
+            ...it,
+            clarification_question: {
+                category: isClarificationCategory(entry?.["category"])
+                    ? entry["category"]
+                    : "scope_of_fix",
+                description,
+                ...(options.length > 0 ? { options } : {}),
+            },
+        };
+    }
+    return { ...rest, items: nextItems };
+}
 const LOCK_FILENAME = "state.lock";
 // Acquire timeout for the shared file lock — the STALE_LOCK_MS-minus-margin
 // derivation is single-sourced in the shared locked JSON store (a fresh-but-held
@@ -199,7 +317,8 @@ export class StateStore {
                 // `validateState` throws SchemaVersionMismatchError for a state stamped
                 // with another release's contract version; that propagates out of the
                 // read exactly as the policy requires (see the constant's doc).
-                const errors = validateState(raw);
+                const adopted = adoptLegacyClarifications(raw);
+                const errors = validateState(adopted);
                 if (errors.length > 0) {
                     throw new Error(`state.json failed schema validation: ${errors.join("; ")}`);
                 }
@@ -210,7 +329,9 @@ export class StateStore {
                 // written before the field existed has none until its next write, and
                 // `validateState` admits that (see the constant's doc) — which is the
                 // whole reason the field is optional on the type rather than required.
-                return raw;
+                // The one exception is the retired clarification shape, translated by
+                // `adoptLegacyClarifications`; a current state is returned unchanged.
+                return adopted;
             },
             // The WRITE hook. Without it the store's own `persist` wrote whatever a
             // caller handed it — the load gate was the only validation on the path,