audit-tools 0.28.0

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

@@ -0,0 +1,766 @@
+import { z } from "zod";
+import type { RemediationItemStatus } from "./itemStatus.js";
+import type { Finding, RemediationOutcome } from "audit-tools/shared";
+export type { Finding };
+export declare const RemediationBlockSchema: z.ZodObject<{
+    block_id: z.ZodString;
+    items: z.ZodArray<z.ZodString, "many">;
+    parallel_safe: z.ZodBoolean;
+    dependencies: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Commands to run as a post-merge verification gate after this block's
+     * worktree branch is merged into the main tree. When present, these are
+     * preferred over `RemediationPlan.test_command` for the gate check.
+     */
+    targeted_commands: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Repo-relative paths that this block's implementation is expected to touch.
+     * Used by `attributePostMergeFailure` to identify which merged blocks share
+     * an implicated surface when the post-merge gate fails.
+     */
+    touched_files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    items: string[];
+    block_id: string;
+    parallel_safe: boolean;
+    targeted_commands?: string[] | undefined;
+    dependencies?: string[] | undefined;
+    touched_files?: string[] | undefined;
+}, {
+    items: string[];
+    block_id: string;
+    parallel_safe: boolean;
+    targeted_commands?: string[] | undefined;
+    dependencies?: string[] | undefined;
+    touched_files?: string[] | undefined;
+}>;
+export type RemediationBlock = z.infer<typeof RemediationBlockSchema>;
+export declare const RemediationPlanSchema: z.ZodObject<{
+    plan_id: z.ZodString;
+    goal_id: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+    findings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        category: z.ZodString;
+        severity: z.ZodEnum<["critical", "high", "medium", "low", "info"]>;
+        confidence: z.ZodEnum<["high", "medium", "low"]>;
+        lens: z.ZodString;
+        summary: z.ZodString;
+        affected_files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            line_start: z.ZodOptional<z.ZodNumber>;
+            line_end: z.ZodOptional<z.ZodNumber>;
+            symbol: z.ZodOptional<z.ZodString>;
+            quoted_text: z.ZodOptional<z.ZodString>;
+            hash_at_plan_time: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+            symbol?: string | undefined;
+            line_start?: number | undefined;
+            line_end?: number | undefined;
+            quoted_text?: string | undefined;
+            hash_at_plan_time?: string | undefined;
+        }, {
+            path: string;
+            symbol?: string | undefined;
+            line_start?: number | undefined;
+            line_end?: number | undefined;
+            quoted_text?: string | undefined;
+            hash_at_plan_time?: string | undefined;
+        }>, "many">;
+        impact: z.ZodOptional<z.ZodString>;
+        likelihood: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        reproduction: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        systemic: z.ZodOptional<z.ZodBoolean>;
+        related_findings: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        theme_id: z.ZodOptional<z.ZodString>;
+        evidence_grounded: z.ZodOptional<z.ZodBoolean>;
+        grounding: z.ZodOptional<z.ZodObject<{
+            status: z.ZodEnum<["grounded", "ungrounded", "refuted"]>;
+            reason: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            status: "grounded" | "ungrounded" | "refuted";
+            reason?: string | undefined;
+        }, {
+            status: "grounded" | "ungrounded" | "refuted";
+            reason?: string | undefined;
+        }>>;
+        executable_anchor: z.ZodOptional<z.ZodObject<{
+            command: z.ZodArray<z.ZodString, "many">;
+            confirm_if: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+                kind: z.ZodLiteral<"exit_zero">;
+            }, "strip", z.ZodTypeAny, {
+                kind: "exit_zero";
+            }, {
+                kind: "exit_zero";
+            }>, z.ZodObject<{
+                kind: z.ZodLiteral<"exit_nonzero">;
+            }, "strip", z.ZodTypeAny, {
+                kind: "exit_nonzero";
+            }, {
+                kind: "exit_nonzero";
+            }>, z.ZodObject<{
+                kind: z.ZodLiteral<"output_includes">;
+                text: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                kind: "output_includes";
+                text: string;
+            }, {
+                kind: "output_includes";
+                text: string;
+            }>, z.ZodObject<{
+                kind: z.ZodLiteral<"output_excludes">;
+                text: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                kind: "output_excludes";
+                text: string;
+            }, {
+                kind: "output_excludes";
+                text: string;
+            }>]>;
+            claim: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            command: string[];
+            confirm_if: {
+                kind: "exit_zero";
+            } | {
+                kind: "exit_nonzero";
+            } | {
+                kind: "output_includes";
+                text: string;
+            } | {
+                kind: "output_excludes";
+                text: string;
+            };
+            claim?: string | undefined;
+        }, {
+            command: string[];
+            confirm_if: {
+                kind: "exit_zero";
+            } | {
+                kind: "exit_nonzero";
+            } | {
+                kind: "output_includes";
+                text: string;
+            } | {
+                kind: "output_excludes";
+                text: string;
+            };
+            claim?: string | undefined;
+        }>>;
+        contract_goal_id: z.ZodOptional<z.ZodString>;
+        contract_obligation_ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        verification_obligation_ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        targeted_commands: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        confidence: "high" | "low" | "medium";
+        title: string;
+        category: string;
+        severity: "high" | "low" | "critical" | "medium" | "info";
+        lens: string;
+        summary: string;
+        affected_files: {
+            path: string;
+            symbol?: string | undefined;
+            line_start?: number | undefined;
+            line_end?: number | undefined;
+            quoted_text?: string | undefined;
+            hash_at_plan_time?: string | undefined;
+        }[];
+        impact?: string | undefined;
+        likelihood?: string | undefined;
+        evidence?: string[] | undefined;
+        reproduction?: string[] | undefined;
+        systemic?: boolean | undefined;
+        related_findings?: string[] | undefined;
+        theme_id?: string | undefined;
+        evidence_grounded?: boolean | undefined;
+        grounding?: {
+            status: "grounded" | "ungrounded" | "refuted";
+            reason?: string | undefined;
+        } | undefined;
+        executable_anchor?: {
+            command: string[];
+            confirm_if: {
+                kind: "exit_zero";
+            } | {
+                kind: "exit_nonzero";
+            } | {
+                kind: "output_includes";
+                text: string;
+            } | {
+                kind: "output_excludes";
+                text: string;
+            };
+            claim?: string | undefined;
+        } | undefined;
+        contract_goal_id?: string | undefined;
+        contract_obligation_ids?: string[] | undefined;
+        verification_obligation_ids?: string[] | undefined;
+        targeted_commands?: string[] | undefined;
+    }, {
+        id: string;
+        confidence: "high" | "low" | "medium";
+        title: string;
+        category: string;
+        severity: "high" | "low" | "critical" | "medium" | "info";
+        lens: string;
+        summary: string;
+        affected_files: {
+            path: string;
+            symbol?: string | undefined;
+            line_start?: number | undefined;
+            line_end?: number | undefined;
+            quoted_text?: string | undefined;
+            hash_at_plan_time?: string | undefined;
+        }[];
+        impact?: string | undefined;
+        likelihood?: string | undefined;
+        evidence?: string[] | undefined;
+        reproduction?: string[] | undefined;
+        systemic?: boolean | undefined;
+        related_findings?: string[] | undefined;
+        theme_id?: string | undefined;
+        evidence_grounded?: boolean | undefined;
+        grounding?: {
+            status: "grounded" | "ungrounded" | "refuted";
+            reason?: string | undefined;
+        } | undefined;
+        executable_anchor?: {
+            command: string[];
+            confirm_if: {
+                kind: "exit_zero";
+            } | {
+                kind: "exit_nonzero";
+            } | {
+                kind: "output_includes";
+                text: string;
+            } | {
+                kind: "output_excludes";
+                text: string;
+            };
+            claim?: string | undefined;
+        } | undefined;
+        contract_goal_id?: string | undefined;
+        contract_obligation_ids?: string[] | undefined;
+        verification_obligation_ids?: string[] | undefined;
+        targeted_commands?: string[] | undefined;
+    }>, "many">;
+    blocks: z.ZodArray<z.ZodObject<{
+        block_id: z.ZodString;
+        items: z.ZodArray<z.ZodString, "many">;
+        parallel_safe: z.ZodBoolean;
+        dependencies: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * Commands to run as a post-merge verification gate after this block's
+         * worktree branch is merged into the main tree. When present, these are
+         * preferred over `RemediationPlan.test_command` for the gate check.
+         */
+        targeted_commands: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * Repo-relative paths that this block's implementation is expected to touch.
+         * Used by `attributePostMergeFailure` to identify which merged blocks share
+         * an implicated surface when the post-merge gate fails.
+         */
+        touched_files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        items: string[];
+        block_id: string;
+        parallel_safe: boolean;
+        targeted_commands?: string[] | undefined;
+        dependencies?: string[] | undefined;
+        touched_files?: string[] | undefined;
+    }, {
+        items: string[];
+        block_id: string;
+        parallel_safe: boolean;
+        targeted_commands?: string[] | undefined;
+        dependencies?: string[] | undefined;
+        touched_files?: string[] | undefined;
+    }>, "many">;
+    project_type: z.ZodString;
+    test_command: z.ZodOptional<z.ZodString>;
+    e2e_command: z.ZodOptional<z.ZodString>;
+    candidate_closing_actions: z.ZodArray<z.ZodEnum<["commit", "push", "open-pr", "publish", "tag", "none", "custom"]>, "many">;
+    block_strategy: z.ZodOptional<z.ZodEnum<["test_graph", "git_cocommit", "file_overlap", "manual"]>>;
+    /** Synthesis themes carried from audit-findings.json (Phase 6/7 fix hints). */
+    themes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        theme_id: z.ZodString;
+        title: z.ZodString;
+        root_cause: z.ZodString;
+        finding_ids: z.ZodArray<z.ZodString, "many">;
+        suggested_fix_pattern: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        theme_id: string;
+        finding_ids: string[];
+        root_cause: string;
+        suggested_fix_pattern: string;
+    }, {
+        title: string;
+        theme_id: string;
+        finding_ids: string[];
+        root_cause: string;
+        suggested_fix_pattern: string;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    findings: {
+        id: string;
+        confidence: "high" | "low" | "medium";
+        title: string;
+        category: string;
+        severity: "high" | "low" | "critical" | "medium" | "info";
+        lens: string;
+        summary: string;
+        affected_files: {
+            path: string;
+            symbol?: string | undefined;
+            line_start?: number | undefined;
+            line_end?: number | undefined;
+            quoted_text?: string | undefined;
+            hash_at_plan_time?: string | undefined;
+        }[];
+        impact?: string | undefined;
+        likelihood?: string | undefined;
+        evidence?: string[] | undefined;
+        reproduction?: string[] | undefined;
+        systemic?: boolean | undefined;
+        related_findings?: string[] | undefined;
+        theme_id?: string | undefined;
+        evidence_grounded?: boolean | undefined;
+        grounding?: {
+            status: "grounded" | "ungrounded" | "refuted";
+            reason?: string | undefined;
+        } | undefined;
+        executable_anchor?: {
+            command: string[];
+            confirm_if: {
+                kind: "exit_zero";
+            } | {
+                kind: "exit_nonzero";
+            } | {
+                kind: "output_includes";
+                text: string;
+            } | {
+                kind: "output_excludes";
+                text: string;
+            };
+            claim?: string | undefined;
+        } | undefined;
+        contract_goal_id?: string | undefined;
+        contract_obligation_ids?: string[] | undefined;
+        verification_obligation_ids?: string[] | undefined;
+        targeted_commands?: string[] | undefined;
+    }[];
+    plan_id: string;
+    blocks: {
+        items: string[];
+        block_id: string;
+        parallel_safe: boolean;
+        targeted_commands?: string[] | undefined;
+        dependencies?: string[] | undefined;
+        touched_files?: string[] | undefined;
+    }[];
+    project_type: string;
+    candidate_closing_actions: ("push" | "custom" | "none" | "tag" | "commit" | "open-pr" | "publish")[];
+    themes?: {
+        title: string;
+        theme_id: string;
+        finding_ids: string[];
+        root_cause: string;
+        suggested_fix_pattern: string;
+    }[] | undefined;
+    source?: string | undefined;
+    goal_id?: string | undefined;
+    test_command?: string | undefined;
+    e2e_command?: string | undefined;
+    block_strategy?: "manual" | "test_graph" | "git_cocommit" | "file_overlap" | undefined;
+}, {
+    findings: {
+        id: string;
+        confidence: "high" | "low" | "medium";
+        title: string;
+        category: string;
+        severity: "high" | "low" | "critical" | "medium" | "info";
+        lens: string;
+        summary: string;
+        affected_files: {
+            path: string;
+            symbol?: string | undefined;
+            line_start?: number | undefined;
+            line_end?: number | undefined;
+            quoted_text?: string | undefined;
+            hash_at_plan_time?: string | undefined;
+        }[];
+        impact?: string | undefined;
+        likelihood?: string | undefined;
+        evidence?: string[] | undefined;
+        reproduction?: string[] | undefined;
+        systemic?: boolean | undefined;
+        related_findings?: string[] | undefined;
+        theme_id?: string | undefined;
+        evidence_grounded?: boolean | undefined;
+        grounding?: {
+            status: "grounded" | "ungrounded" | "refuted";
+            reason?: string | undefined;
+        } | undefined;
+        executable_anchor?: {
+            command: string[];
+            confirm_if: {
+                kind: "exit_zero";
+            } | {
+                kind: "exit_nonzero";
+            } | {
+                kind: "output_includes";
+                text: string;
+            } | {
+                kind: "output_excludes";
+                text: string;
+            };
+            claim?: string | undefined;
+        } | undefined;
+        contract_goal_id?: string | undefined;
+        contract_obligation_ids?: string[] | undefined;
+        verification_obligation_ids?: string[] | undefined;
+        targeted_commands?: string[] | undefined;
+    }[];
+    plan_id: string;
+    blocks: {
+        items: string[];
+        block_id: string;
+        parallel_safe: boolean;
+        targeted_commands?: string[] | undefined;
+        dependencies?: string[] | undefined;
+        touched_files?: string[] | undefined;
+    }[];
+    project_type: string;
+    candidate_closing_actions: ("push" | "custom" | "none" | "tag" | "commit" | "open-pr" | "publish")[];
+    themes?: {
+        title: string;
+        theme_id: string;
+        finding_ids: string[];
+        root_cause: string;
+        suggested_fix_pattern: string;
+    }[] | undefined;
+    source?: string | undefined;
+    goal_id?: string | undefined;
+    test_command?: string | undefined;
+    e2e_command?: string | undefined;
+    block_strategy?: "manual" | "test_graph" | "git_cocommit" | "file_overlap" | undefined;
+}>;
+export type RemediationPlan = z.infer<typeof RemediationPlanSchema>;
+/**
+ * Canonical names of the bounded remediation steps. Defined as named constants
+ * (rather than bare string literals scattered across the phases) so the
+ * implement phase, the validator, and the item-spec contract share one source
+ * of truth for these magic strings.
+ */
+export declare const REMEDIATION_STEP: {
+    readonly WRITE_TESTS: "Write Tests";
+    readonly REFACTOR_CODE: "Refactor Code";
+    readonly VERIFY_AGAINST_TESTS: "Verify Code Against Tests";
+    readonly VERIFY_AGAINST_DOCUMENTATION: "Verify Code Against Documentation";
+};
+export type RemediationStepName = (typeof REMEDIATION_STEP)[keyof typeof REMEDIATION_STEP];
+export declare const ItemSpecSchema: z.ZodObject<{
+    finding_id: z.ZodString;
+    concrete_change: z.ZodString;
+    no_change: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Repo-relative paths the fix will create or modify, as declared by the
+     * document worker. The document phase can correct or extend the finding's
+     * pre-document affected_files (e.g. when the real fix lives elsewhere); block
+     * access is recomputed from this union so the implementer may write them.
+     */
+    touched_files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    tests_to_write: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        assertions: z.ZodArray<z.ZodString, "many">;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        assertions: string[];
+    }, {
+        name: string;
+        assertions: string[];
+    }>, "many">;
+    not_applicable_steps: z.ZodArray<z.ZodObject<{
+        step: z.ZodEnum<["Write Tests", "Refactor Code", "Verify Code Against Tests", "Verify Code Against Documentation"]>;
+        rationale: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        rationale: string;
+        step: "Write Tests" | "Refactor Code" | "Verify Code Against Tests" | "Verify Code Against Documentation";
+    }, {
+        rationale: string;
+        step: "Write Tests" | "Refactor Code" | "Verify Code Against Tests" | "Verify Code Against Documentation";
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    finding_id: string;
+    concrete_change: string;
+    tests_to_write: {
+        name: string;
+        assertions: string[];
+    }[];
+    not_applicable_steps: {
+        rationale: string;
+        step: "Write Tests" | "Refactor Code" | "Verify Code Against Tests" | "Verify Code Against Documentation";
+    }[];
+    touched_files?: string[] | undefined;
+    no_change?: boolean | undefined;
+}, {
+    finding_id: string;
+    concrete_change: string;
+    tests_to_write: {
+        name: string;
+        assertions: string[];
+    }[];
+    not_applicable_steps: {
+        rationale: string;
+        step: "Write Tests" | "Refactor Code" | "Verify Code Against Tests" | "Verify Code Against Documentation";
+    }[];
+    touched_files?: string[] | undefined;
+    no_change?: boolean | undefined;
+}>;
+export type ItemSpec = z.infer<typeof ItemSpecSchema>;
+export declare const ClarificationRequestSchema: z.ZodObject<{
+    finding_id: z.ZodString;
+    category: z.ZodEnum<["public_contract", "behavioral_semantics", "scope_of_fix", "dependency_introduction", "compatibility_policy", "intent_vs_symptom", "issue_appropriateness"]>;
+    description: z.ZodString;
+    options: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    category: "public_contract" | "behavioral_semantics" | "scope_of_fix" | "dependency_introduction" | "compatibility_policy" | "intent_vs_symptom" | "issue_appropriateness";
+    description: string;
+    finding_id: string;
+    options?: string[] | undefined;
+}, {
+    category: "public_contract" | "behavioral_semantics" | "scope_of_fix" | "dependency_introduction" | "compatibility_policy" | "intent_vs_symptom" | "issue_appropriateness";
+    description: string;
+    finding_id: string;
+    options?: string[] | undefined;
+}>;
+export type ClarificationRequest = z.infer<typeof ClarificationRequestSchema>;
+export declare const ClosingActionPreviewSchema: z.ZodObject<{
+    /** Repo-relative paths that would be staged for the commit. */
+    files: z.ZodArray<z.ZodString, "many">;
+    /** Generated commit message derived from item summaries / finding titles. */
+    commit_message: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    files: string[];
+    commit_message: string;
+}, {
+    files: string[];
+    commit_message: string;
+}>;
+export type ClosingActionPreview = z.infer<typeof ClosingActionPreviewSchema>;
+export declare const ClosingPlanSchema: z.ZodObject<{
+    action: z.ZodEnum<["commit", "push", "open-pr", "publish", "tag", "none", "custom"]>;
+    custom_command: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * When true, the host has explicitly confirmed the closing action preview and
+     * the close phase may proceed to execute git/publish commands without an
+     * additional confirmation prompt.
+     */
+    pre_authorized: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Set by the close phase before executing actions that require user
+     * confirmation. Contains the staged file list and generated commit message so
+     * the host can present them to the user. Cleared once the action executes.
+     */
+    closing_action_preview: z.ZodOptional<z.ZodObject<{
+        /** Repo-relative paths that would be staged for the commit. */
+        files: z.ZodArray<z.ZodString, "many">;
+        /** Generated commit message derived from item summaries / finding titles. */
+        commit_message: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        files: string[];
+        commit_message: string;
+    }, {
+        files: string[];
+        commit_message: string;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    action: "push" | "custom" | "none" | "tag" | "commit" | "open-pr" | "publish";
+    custom_command?: string[] | undefined;
+    pre_authorized?: boolean | undefined;
+    closing_action_preview?: {
+        files: string[];
+        commit_message: string;
+    } | undefined;
+}, {
+    action: "push" | "custom" | "none" | "tag" | "commit" | "open-pr" | "publish";
+    custom_command?: string[] | undefined;
+    pre_authorized?: boolean | undefined;
+    closing_action_preview?: {
+        files: string[];
+        commit_message: string;
+    } | undefined;
+}>;
+export type ClosingPlan = z.infer<typeof ClosingPlanSchema>;
+export interface CoverageLedgerEntry {
+    finding_id: string;
+    title?: string;
+    disposition: "planned" | "folded_into" | "dropped_no_evidence" | "dropped_by_checkpoint" | "dropped_phantom_paths" | "declined_by_review";
+    block_id?: string;
+    folded_into?: string;
+    rationale?: string;
+    /** Phantom (non-existent) cited paths the grounding pass stripped. */
+    phantom_paths_removed?: string[];
+    /** Whether the finding's evidence cites a real repo path (extracted findings only). */
+    evidence_grounded?: boolean;
+    /**
+     * Full original Finding payload (the shared `Finding` type, verbatim). Carried
+     * for never-planned findings so the outcomes contract can record what was
+     * dropped — without it the payload is lost once state.json is deleted at close.
+     */
+    finding?: Finding;
+}
+export interface CoverageLedger {
+    contract_version: "remediate-code-coverage/v1alpha1";
+    plan_id: string;
+    source_finding_count: number;
+    planned_count: number;
+    folded_count: number;
+    dropped_count: number;
+    /** Findings excluded by the intent checkpoint (filters / excluded scope). */
+    checkpoint_dropped_count: number;
+    /** Findings dropped because every cited path was phantom (after one repair attempt). */
+    phantom_dropped_count: number;
+    /**
+     * Findings the user disapproved at the review-approval gate (excluded from the
+     * pipeline before planning). Optional + kept SEPARATE from the source-disposition
+     * reconciliation (planned+folded+dropped+checkpoint+phantom === source_finding_count):
+     * declined findings are never part of the planned source/node set, they are an
+     * upstream exclusion, so they are counted here and appended as extra entries.
+     */
+    declined_review_count?: number;
+    entries: CoverageLedgerEntry[];
+}
+/**
+ * Retry-oriented final status of an outcomes item. Coarser than
+ * `RemediationOutcomeStatus`: `fixed` covers resolved / verified-no-change,
+ * `failed` covers blocked and force-closed non-terminal items, `skipped`
+ * covers deemed-inappropriate items, `ignored` covers user-ignored items.
+ */
+export type RemediationOutcomeFinalStatus = "fixed" | "failed" | "ignored" | "skipped";
+/**
+ * Typed subset of `ItemSpec` carried on each outcomes item — the documented
+ * fields a retry needs without re-running the document phase.
+ */
+export interface ItemSpecSummary extends Pick<ItemSpec, "concrete_change" | "no_change" | "touched_files"> {
+    /** Names of the tests the document phase specified (`ItemSpec.tests_to_write[].name`). */
+    tests_to_write: string[];
+}
+/**
+ * One fully self-describing entry per finding in `remediation-outcomes.json`.
+ * Extends the shared per-finding outcome so the file is retryable on its own:
+ * close deletes state.json, so every payload a retry needs must be here.
+ *
+ * Runtime invariants (enforced by the close phase, not expressible in TS):
+ * - `reason` is always a non-empty string when `final_status` is `skipped` or
+ *   `ignored`.
+ * - `original_state` is present exactly when the run was force-closed while
+ *   this item was still non-terminal; such items get `final_status: "failed"`
+ *   and a `reason` saying they were force-closed.
+ */
+export interface RemediationOutcomeItem extends RemediationOutcome {
+    /** Full original Finding payload (the shared `Finding` type, verbatim). */
+    finding: Finding;
+    /** Summary of the documented `ItemSpec`; absent when never documented. */
+    item_spec?: ItemSpecSummary;
+    /** Owning block id (`RemediationBlock.block_id`). */
+    block_id: RemediationBlock["block_id"];
+    /** The owning block's dependency block ids (`RemediationBlock.dependencies`). */
+    block_dependencies: string[];
+    /** Retry-oriented final status (see `RemediationOutcomeFinalStatus`). */
+    final_status: RemediationOutcomeFinalStatus;
+    /**
+     * The non-terminal `RemediationItemState["status"]` this item was in when the
+     * run was force-closed. Absent for items that reached a terminal status.
+     */
+    original_state?: RemediationItemState["status"];
+}
+/** Why a never-planned finding was dropped before remediation started. */
+export type NeverPlannedDropReason = "cross_lens_dedup" | "intent_checkpoint" | "no_evidence" | "phantom_paths" | "review_gate";
+/**
+ * Coverage-ledger entry as written into `remediation-outcomes.json`: the plan's
+ * `CoverageLedgerEntry` enriched with a `drop_reason` discriminator and (for
+ * never-planned findings) the full `Finding` payload instead of a bare id.
+ */
+export interface OutcomeCoverageEntry extends CoverageLedgerEntry {
+    /** Set on never-planned findings (folded / checkpoint- / evidence- / phantom-dropped). */
+    drop_reason?: NeverPlannedDropReason;
+}
+/** The outcomes file's coverage-ledger section (enriched entries). */
+export interface OutcomeCoverageLedger extends Omit<CoverageLedger, "entries"> {
+    entries: OutcomeCoverageEntry[];
+}
+/**
+ * How the denominator for this ledger was derived. Determines what counts as
+ * "complete" and drives the `assertLedgerComplete` gate (INV-CL-05).
+ *
+ * - `finding_enumeration`: structured_audit source — every finding-id from
+ *   `finding-enumeration.json` must appear exactly once among the items.
+ * - `dag_node`: document / non-enumerable source — every promoted
+ *   implementation-DAG node must reach a terminal disposition.
+ */
+export type PerFindingDenominatorKind = "finding_enumeration" | "dag_node";
+/**
+ * Disposition of a single finding or DAG-node within the per-finding ledger.
+ * Only terminal dispositions count toward coverage (INV-CL-05 fail-closed rule).
+ */
+export type PerFindingDisposition = "resolved" | "resolved_no_change" | "ignored" | "deemed_inappropriate" | "force_closed_unresolved";
+/** Single entry in `PerFindingCoverageLedger.entries`. */
+export interface PerFindingLedgerEntry {
+    /** Finding id (structured_audit) or promoted DAG-node id (document source). */
+    id: string;
+    disposition: PerFindingDisposition;
+}
+/**
+ * Per-finding / per-node coverage ledger — source_type-aware denominator.
+ *
+ * For `structured_audit` sources the denominator is the complete
+ * `finding-enumeration.json` set; for document / non-enumerable sources the
+ * denominator is the set of promoted implementation-DAG nodes.  A 0/0 ledger
+ * is INCOMPLETE (fail-closed) — zero denominator never counts as vacuously
+ * complete (INV-CL-05).
+ */
+export interface PerFindingCoverageLedger {
+    /** Discriminates structured vs. document/non-enumerable sources. */
+    denominator_kind: PerFindingDenominatorKind;
+    /** Total items expected (finding-enumeration count or promoted-node count). */
+    denominator: number;
+    /** Items that reached a terminal disposition (len(entries) after build). */
+    covered: number;
+    entries: PerFindingLedgerEntry[];
+}
+export interface RemediationItemState {
+    finding_id: string;
+    status: RemediationItemStatus;
+    block_id: string;
+    item_spec?: ItemSpec;
+    last_successful_step?: string;
+    failure_reason?: string;
+    /** Times this item was sent back for rework via triage (Phase 7B outcomes). */
+    rework_count?: number;
+    /** ISO-8601 timestamp when this item first left pending. */
+    started_at?: string;
+    /** ISO-8601 timestamp when this item most recently reached a terminal status. */
+    completed_at?: string;
+    /** User's clarification answer, carried from applyClarificationResolution into the implement prompt. */
+    clarification_context?: string;
+    /**
+     * The failure context (failure_reason + last_successful_step) captured at
+     * the time this item was queued for retry. Carried into re-dispatch prompts
+     * so the worker knows what failed previously and avoids identical attempts.
+     */
+    failure_context?: string;
+    /**
+     * Times this item was sent back for rework due to infrastructure failures
+     * (quota, rate-limit, EPERM, timeout, tool crash, provider error). Split from
+     * `rework_count` so the two failure classes can have independent retry budgets.
+     */
+    infra_rework_count?: number;
+}
+//# sourceMappingURL=types.d.ts.map