audit-tools 0.28.0

package/dist/remediate/steps/leanFastPath.js

@@ -0,0 +1,151 @@
+// A1 — the conservative lean fast path past the contract pipeline.
+//
+// Most remediation runs route through the heavy contract pipeline
+// (goal_normalization → … → critic → judge → implementation_dag), which exists
+// to reason about DESIGN correctness for complex/coupled changes: module
+// contracts, seam reconciliation, an obligation ledger, and an adversarial
+// critic→judge→repair loop. That is the right machinery for a tangled change —
+// and overkill for a handful of concrete, already-grounded fixes.
+//
+// This module is the gate that decides when a run may skip that loop, plus the
+// builder for the lean `extracted-plan.json` the fast path emits. The gate is
+// deliberately CONSERVATIVE: it fast-paths ONLY when every simplicity signal
+// holds, and defaults to the full pipeline on any doubt. That asymmetry is how
+// the "a subtle change must not skip the safety net" requirement is enforced —
+// a mis-classified complex change costs extra pipeline work, never a skipped
+// design review.
+//
+// What the fast path KEEPS (the retained safety net): the produced plan rejoins
+// the normal plan→implement→close machinery — deterministic grounding re-pass,
+// applyPlanPipeline's block derivation + affected-file hash snapshot (integrity
+// check), the implement-phase per-node verify-before-merge, and the tool-owned
+// final whole-repo gate. A fast-pathed fix that breaks something fails its
+// verify and routes to triage; it never silently lands.
+//
+// What it DROPS: only the adversarial contract design loop + obligation
+// derivation — precisely the work that earns its cost on coupled/systemic
+// changes the gate has already excluded.
+//
+// Pure + deterministic: no IO, no clock, no randomness. The caller supplies the
+// plan id so this stays trivially unit-testable.
+import { findingIsGrounded } from "audit-tools/shared";
+/**
+ * Max approved findings the lean path will take — "a handful". Above this, the
+ * coordination risk of a batch warrants the full pipeline.
+ */
+export const MAX_FAST_PATH_FINDINGS = 5;
+/**
+ * Max DISTINCT affected files across the approved set. A small footprint is the
+ * primary structural proxy for "no broad cross-module ripple": a shared-contract
+ * change that fans out to its consumers touches many files and trips this cap,
+ * routing to the pipeline where seam reconciliation belongs.
+ */
+export const MAX_FAST_PATH_FILES = 5;
+/** Source tag stamped on a lean-fast-path extracted plan (distinguishes it from `contract_pipeline`). */
+export const LEAN_FAST_PATH_SOURCE = "lean_fast_path";
+/** Distinct affected-file paths across an approved finding set. */
+function distinctAffectedFiles(findings) {
+    const paths = new Set();
+    for (const finding of findings) {
+        for (const location of finding.affected_files ?? []) {
+            if (location?.path) {
+                paths.add(location.path);
+            }
+        }
+    }
+    return [...paths];
+}
+/**
+ * Decide whether an APPROVED, post-filter structured-audit finding set is simple
+ * enough for the lean fast path. The caller guarantees the source is structured
+ * (this never runs on free-form/document/conversation intake) and that every
+ * finding already cleared the review-approval gate + the pre-planning filter
+ * (evidence-bearing, deduped, non-phantom-path, checkpoint-kept).
+ *
+ * Every check is a conservative AND: any failing signal returns ineligible with
+ * the reason, so the run takes the full pipeline.
+ */
+export function evaluateFastPath(findings) {
+    if (findings.length === 0) {
+        return { eligible: false, reason: "no approved findings to fast-path" };
+    }
+    if (findings.length > MAX_FAST_PATH_FINDINGS) {
+        return {
+            eligible: false,
+            reason: `${findings.length} findings exceeds the ${MAX_FAST_PATH_FINDINGS}-finding fast-path cap`,
+        };
+    }
+    const files = distinctAffectedFiles(findings);
+    if (files.length > MAX_FAST_PATH_FILES) {
+        return {
+            eligible: false,
+            reason: `${files.length} affected files exceeds the ${MAX_FAST_PATH_FILES}-file fast-path cap`,
+        };
+    }
+    // Grounding: require the auditor's strong S7 verdict (cited span re-verified
+    // against disk, or an executable anchor confirmed the behavior). This is the
+    // protection that REPLACES the adversarial loop — a fast-pathed finding is
+    // never one the auditor couldn't positively ground.
+    const ungrounded = findings.filter((finding) => !findingIsGrounded(finding));
+    if (ungrounded.length > 0) {
+        return {
+            eligible: false,
+            reason: `not positively grounded: ${ungrounded.map((f) => f.id).join(", ")}`,
+        };
+    }
+    // High confidence: a medium/low-confidence finding carries doubt the
+    // adversarial loop exists to resolve. (Note: an ungrounded finding is already
+    // downgraded to low confidence upstream, so this is defense in depth.)
+    const belowHigh = findings.filter((finding) => finding.confidence !== "high");
+    if (belowHigh.length > 0) {
+        return {
+            eligible: false,
+            reason: `below high confidence: ${belowHigh.map((f) => f.id).join(", ")}`,
+        };
+    }
+    // No cross-cutting / seam signal. These are the auditor's own markers that a
+    // finding is architecture-level or coupled to others; the small-footprint cap
+    // above is the backstop for a finding the auditor failed to mark.
+    const systemic = findings.filter((finding) => finding.systemic === true);
+    if (systemic.length > 0) {
+        return {
+            eligible: false,
+            reason: `systemic / cross-cutting: ${systemic.map((f) => f.id).join(", ")}`,
+        };
+    }
+    const coupled = findings.filter((finding) => (finding.related_findings?.length ?? 0) > 0);
+    if (coupled.length > 0) {
+        return {
+            eligible: false,
+            reason: `coupled to related findings (seam risk): ${coupled.map((f) => f.id).join(", ")}`,
+        };
+    }
+    const architectural = findings.filter((finding) => finding.lens === "architecture");
+    if (architectural.length > 0) {
+        return {
+            eligible: false,
+            reason: `architecture-lens (design-level): ${architectural.map((f) => f.id).join(", ")}`,
+        };
+    }
+    return {
+        eligible: true,
+        reason: `${findings.length} grounded high-confidence finding(s) across ${files.length} file(s); none systemic, coupled, or architecture-lens`,
+    };
+}
+/**
+ * Build the lean extracted plan from the approved findings. Blocks are
+ * intentionally omitted: `normalizeExtractedPlan` synthesizes one block per
+ * finding and `applyPlanPipeline` then merges blocks sharing a file + splits by
+ * context budget — the same deterministic block derivation the contract pipeline
+ * feeds into, single-sourced rather than reimplemented here.
+ */
+export function buildLeanExtractedPlan(findings, planId) {
+    return {
+        plan_id: planId,
+        findings,
+        project_type: "unknown",
+        source: LEAN_FAST_PATH_SOURCE,
+        candidate_closing_actions: ["none"],
+    };
+}
+//# sourceMappingURL=leanFastPath.js.map

package/dist/remediate/steps/leanFastPath.js.map

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

package/dist/remediate/steps/nextStep.d.ts

@@ -0,0 +1,323 @@
+import { type RemediationState } from "../state/store.js";
+import type { RemediationBlock } from "../state/types.js";
+import { type InterpretedIntent, type SessionConfig, type HostModelRosterEntry, type CapacityPool, type RollingDispatchResult, type ProviderSlot } from "audit-tools/shared";
+import type { RemediationStep } from "./types.js";
+import { isTerminalStatus, isVerifiedCompleteStatus } from "../state/itemStatus.js";
+import type { IntentCheckpoint } from "audit-tools/shared";
+export interface NextStepOptions {
+    root?: string;
+    artifactsDir?: string;
+    input?: string | string[];
+    hostCanDispatchSubagents?: boolean;
+    hostMaxConcurrent?: number;
+    hostContextTokens?: number | null;
+    hostOutputTokens?: number | null;
+    /** Ordered model roster (lowest rank first); outranks the scalar pair. */
+    hostModels?: HostModelRosterEntry[] | null;
+    /** Opaque model identity for the quota key when no model name resolves. */
+    hostModelId?: string | null;
+    finalizeClosing?: boolean;
+    forceReplan?: boolean;
+    /**
+     * Opt IN to the in-process rolling dispatch engine for the implement phase.
+     * Defaults off (proven host-fanned wave path). See `resolveRollingEngineEnabled`.
+     */
+    rollingEngine?: boolean;
+    sessionConfig?: SessionConfig | null;
+    /**
+     * Skip the tool-owned final completion gate (INV-RS-10) at the all-terminal
+     * transition. Production never sets this; it is a test-hermeticity affordance
+     * so suites that drive an unrelated flow to completion do not spawn a real
+     * build. Also honored via `REMEDIATE_SKIP_FINAL_GATE`. The gate's correctness
+     * is verified directly (rolling-scheduler.test.ts) regardless of this flag.
+     */
+    skipFinalGate?: boolean;
+    /**
+     * Injectable runner for the tool-owned final gate (INV-RS-10). When set, the
+     * gate uses it instead of spawning real commands, so the all-terminal
+     * transition (coarse re-block / bounded terminate) can be exercised
+     * deterministically in tests. Unset in production → real env-scrubbed builds.
+     */
+    finalGateRunner?: GateRunner;
+}
+export declare function resolveHostDispatchCapability(options: {
+    hostCanDispatchSubagents?: boolean;
+    sessionConfig?: SessionConfig | null;
+    env?: NodeJS.ProcessEnv;
+}): boolean;
+/**
+ * Whether the rolling dispatch engine drives the implement phase. Defaults to TRUE:
+ * both rolling drivers on the shared `acceptNodeWorktree` core (per-node worktree →
+ * tool-owned commit → verify → cherry-pick merge; verify-fail → triage) are now
+ * validated end-to-end — the host-subagent driver via a real-subagent smoke
+ * (f18138fe) and the in-process provider driver via a live-NIM run THROUGH
+ * decideNextStep (2026-06-17, tests/nim-rolling-e2e.test.ts). The legacy host-fanned
+ * wave (`dispatch_implement`) is retained as an explicit opt-OUT (rolling_engine:false
+ * / REMEDIATE_ROLLING_ENGINE=false), not deleted. Resolution order: explicit option →
+ * sessionConfig.dispatch.rolling_engine → REMEDIATE_ROLLING_ENGINE env → true.
+ */
+export declare function resolveRollingEngineEnabled(options: {
+    rollingEngine?: boolean;
+    sessionConfig?: SessionConfig | null;
+    env?: NodeJS.ProcessEnv;
+}): boolean;
+export type { FindingRiskTier, FindingClassification, } from "./stepUtils.js";
+export { NO_CHANGE_RE, dependenciesSatisfied, dependencyVerifiedComplete, specIndicatesNoChange, classifyFindingRisk, } from "./stepUtils.js";
+export { isTerminalStatus, isVerifiedCompleteStatus };
+/**
+ * Partition pending nodes into rolling dependency LEVELS. Level 0 is every
+ * pending node already eligible (deps verified-complete now); each subsequent
+ * level is the pending nodes that become eligible once all earlier levels are
+ * assumed verified-complete. The boundary between two levels is exactly where a
+ * shared rebuild is interposed (so a later level builds against the realized
+ * upstream surface). A node with a permanently-unsatisfiable edge (its
+ * prerequisite is skipped/blocked, not merely pending) is NOT placed in any
+ * level — it is dead-ended by `handlePlanning`.
+ *
+ * Pure and deterministic: levels and the nodes within a level are ordered by
+ * block_id so the interposed-rebuild boundaries are stable across runs.
+ */
+export declare function rollingDependencyLevels(state: RemediationState): RemediationBlock[][];
+/** A single node's dispatch handler for the in-process rolling engine. */
+export type RollingNodeDispatcher = (block: RemediationBlock, slot: ProviderSlot) => Promise<RollingDispatchResult<{
+    block_id: string;
+}>>;
+export interface DriveRollingDispatchOptions {
+    /** Confirmed quota pools (scheduler-owned concurrency — no separate wave cap). */
+    confirmedPools: CapacityPool[];
+    sessionConfig: SessionConfig;
+    /** Per-node dispatch (host subagent / tool worker). Must resolve, never reject. */
+    dispatchNode: RollingNodeDispatcher;
+    /**
+     * Rebuild `audit-tools/shared` (and any upstream surface) BETWEEN dependency
+     * levels. Single-flight is enforced by the driver: this is invoked at most
+     * once per inter-level boundary and never concurrently with itself.
+     */
+    rebuildSharedBetweenLevels: () => Promise<void>;
+    /** Per-node estimated input tokens (defaults to a flat overhead estimate). */
+    estimateTokens?: (block: RemediationBlock) => number;
+    /** Quota state dir for `recordWaveOutcome` (defaults to leaving it unset). */
+    quotaStateDir?: string;
+}
+export interface DriveRollingDispatchResult {
+    /** Per-level dispatch results, in level order. */
+    levels: Array<{
+        blockIds: string[];
+        results: RollingDispatchResult<{
+            block_id: string;
+        }>[];
+    }>;
+    /** Number of inter-level shared rebuilds performed (== levels.length - 1 when >1 level). */
+    rebuilds: number;
+}
+/**
+ * Drive a rolling per-node dispatch run IN PROCESS over the precomputed
+ * dependency levels, wiring onto the shared `createRollingDispatcher`
+ * (quota-only throttle; transient-429 re-queue + empty-pool stranding owned by
+ * the shared engine). The driver's own responsibilities are the two properties
+ * the shared engine does not own:
+ *   1. SHARED-REBUILD-BETWEEN-LEVELS — after a level completes, rebuild the
+ *      upstream surface before the next level dispatches, so dependents
+ *      typecheck/run against the realized upstream output.
+ *   2. SINGLE-FLIGHT BUILD (CE-001) — the rebuild runs exactly once per
+ *      inter-level boundary, never twice or concurrently.
+ *
+ * Within a level, concurrency is whatever the shared engine's quota headroom
+ * allows over `confirmedPools` — there is no wave-size cap (INV-S05).
+ */
+export declare function driveRollingDispatch(levels: RemediationBlock[][], options: DriveRollingDispatchOptions): Promise<DriveRollingDispatchResult>;
+/** A programmatic per-node implement worker: edits within the node's worktree, writes its result file. */
+export type ProgrammaticNodeDispatcher = (args: {
+    block: RemediationBlock;
+    slot: ProviderSlot;
+    /** The isolated worktree root the worker must edit within. */
+    worktreeRoot: string;
+    /** The absolute path the worker must write its result JSON to. */
+    resultPath: string;
+}) => Promise<RollingDispatchResult<{
+    block_id: string;
+}>>;
+export interface DriveRollingImplementDispatchOptions {
+    root: string;
+    artifactsDir: string;
+    runId: string;
+    sessionConfig: SessionConfig | null;
+    /**
+     * Programmatic per-node dispatcher. Defaults to the live provider-backed worker
+     * (`makeProviderNodeDispatcher`: resolves the configured provider and launches it
+     * with the node's worktree-rooted prompt). Tests inject a stub to exercise the
+     * engine without spawning a real worker.
+     */
+    dispatchNode?: ProgrammaticNodeDispatcher;
+    /** Rebuild the upstream shared surface between dependency levels (single-flight). */
+    rebuildSharedBetweenLevels: () => Promise<void>;
+    /** Wave/host inputs used to size the quota-derived confirmed pools. */
+    waveOptions?: {
+        hostMaxConcurrent?: number;
+        hostContextTokens?: number | null;
+        hostOutputTokens?: number | null;
+        hostModels?: HostModelRosterEntry[] | null;
+        hostModelId?: string | null;
+    };
+}
+export interface DriveRollingImplementDispatchResult {
+    /** Per-node verify + merge outcome, in dispatch order. */
+    nodes: Array<{
+        block_id: string;
+        outcome: RollingDispatchResult<{
+            block_id: string;
+        }>["outcome"];
+        verify_passed: boolean;
+        merged: boolean;
+    }>;
+    /** Number of inter-level shared rebuilds performed. */
+    rebuilds: number;
+    /** The state status after the deterministic merge of all node results. */
+    state_status: RemediationState["status"];
+}
+/**
+ * Drive the implement phase through the in-process rolling engine. Engages the
+ * shared `createRollingDispatcher` (via `driveRollingDispatch`) over
+ * quota-derived `confirmedPools`, runs each node in an isolated worktree, gates
+ * acceptance on a per-node verify, and finally merges through the deterministic
+ * `mergeImplementResults`. Returns null when there is no eligible pending work.
+ *
+ * SAFETY: this never touches the main tree except through `mergeWorktree` (which
+ * cherry-picks a verified branch and aborts cleanly on conflict). A node whose
+ * verify fails is NOT merged; its worktree is removed and the deterministic merge
+ * marks it blocked (its result file is absent / unaccounted) so the run routes it
+ * to triage rather than landing an unverified change.
+ */
+export declare function driveRollingImplementDispatch(options: DriveRollingImplementDispatchOptions): Promise<DriveRollingImplementDispatchResult | null>;
+/** One command in the tool-owned final gate. */
+export interface FinalGateCommandSpec {
+    argv: string[];
+    /** True for commands that neither build nor run a build-prepending test script. */
+    build_free: boolean;
+    /** The package this command's unit suite targets (single-flight key), if any. */
+    package_dir?: string;
+    /** Which layer of the floor this belongs to. */
+    layer: "build" | "check" | "unit";
+}
+/**
+ * Whether `root` is the audit-tools monorepo — the repo the tool-owned final
+ * gate's suite (INV-RS-10, literally the audit-tools build/check/per-package
+ * commands) applies to. The gate's command list is audit-tools-specific by
+ * design (this remediation run remediates the audit-tools monorepo), so it is
+ * scoped to that structure rather than fabricated for an arbitrary target repo.
+ */
+export declare function isAuditToolsMonorepo(root: string): boolean;
+/**
+ * The tool-owned final-gate command list (INV-RS-10) for the audit-tools
+ * monorepo. Pure and deterministic so tests can assert: it is non-vacuous
+ * (always > 0 build + check + unit commands) for the audit-tools structure,
+ * never references `plan.test_command`, every UNIT command is build-free, and no
+ * package's unit suite appears twice (single-flight — CE-001). Returns `[]` when
+ * `root` is not the audit-tools monorepo (the audit-tools-specific suite is
+ * inapplicable there — see `runToolOwnedFinalGate`).
+ */
+export declare function toolOwnedFinalGateCommands(root: string): FinalGateCommandSpec[];
+/** A command's recorded outcome within a gate run. */
+export interface FinalGateCommandResult {
+    argv: string[];
+    layer: FinalGateCommandSpec["layer"];
+    package_dir?: string;
+    exit_code: number | null;
+    passed: boolean;
+}
+export interface ToolOwnedFinalGateResult {
+    passed: boolean;
+    results: FinalGateCommandResult[];
+    /**
+     * True when the audit-tools-specific suite did not apply (target is not the
+     * audit-tools monorepo). The gate then does not block; it is a declared scope,
+     * not a vacuous pass.
+     */
+    scoped_out: boolean;
+    /**
+     * The runtime/packaging surface the hard floor does NOT gate, declared as a
+     * residual for a separate pass (CE-002). Always present (the floor is scoped
+     * to build+check+unit by design).
+     */
+    runtime_residual: {
+        surface: string;
+        commands: string[];
+    };
+}
+/** Injectable runner so the gate is unit-testable without spawning a real build. */
+export type GateRunner = (argv: string[], cwd: string, packageDir?: string) => {
+    status: number | null;
+};
+/**
+ * Run the tool-owned final gate (INV-RS-10). Each command runs through
+ * `runCommand` → shared `runTracked`, which scrubs CLAUDECODE / CLAUDE_CODE_*.
+ * The first failing command short-circuits the floor (a broken build makes the
+ * later layers meaningless). A `runner` may be injected for tests. When the
+ * audit-tools suite does not apply (non-monorepo target), the gate is
+ * `scoped_out` (does not block) rather than vacuously passing.
+ */
+export declare function runToolOwnedFinalGate(root: string, opts?: {
+    runner?: GateRunner;
+}): Promise<ToolOwnedFinalGateResult>;
+/**
+ * The bound on coarse re-block iterations before the run converges to a terminal
+ * `blocked` close (CE-003). Two re-block attempts give a flaky-but-recoverable
+ * suite a chance to settle; the third unattributable red terminates
+ * deterministically rather than livelocking.
+ */
+export declare const COARSE_REBLOCK_BOUND = 2;
+export type CoarseReblockAction = "reattempt_all" | "terminal_blocked";
+export interface CoarseReblockDecision {
+    state: RemediationState;
+    action: CoarseReblockAction;
+    next_count: number;
+}
+/**
+ * Coarse re-block-ALL-non-terminal on an unattributable final-gate red
+ * (INV-RS-09) with a bounded, monotonic auto-terminate (CE-003).
+ *
+ * The tool-owned gate is whole-repo, so a red is inherently unattributable to a
+ * single node. Below the bound, EVERY non-skip item (including `resolved` ones —
+ * a resolved item's own change may have caused the red) is re-opened to `pending`
+ * and the run re-attempts the whole repo through the rolling scheduler
+ * (`reattempt_all` → `implementing`). At or above the bound, the run STOPS
+ * re-attempting and converges DETERMINISTICALLY: every non-skip item becomes
+ * terminal `blocked` and the run advances to `closing`.
+ *
+ * CE-003 no-human-host guarantee: the loop is owned entirely by the gate + the
+ * rolling scheduler — it NEVER routes through the human triage prompt
+ * (`waiting_for_triage`) and is bounded by `bound`, so a permanently-red sibling
+ * converges to a terminal `blocked` close deterministically: never livelocking,
+ * never stranding on a human prompt, and never force-closed to green (a RED gate
+ * always leaves `blocked` items, so close.ts's `!anyBlocked` guard keeps the run
+ * out of the fully-green path). User SKIP dispositions (ignored /
+ * deemed_inappropriate) are settled decisions and are left alone. Pure (the
+ * counter is supplied / returned).
+ */
+export declare function applyCoarseReblock(state: RemediationState, currentCount: number, gateSummary: string, bound?: number): CoarseReblockDecision;
+export declare function decideNextStep(options?: NextStepOptions | string): Promise<RemediationStep>;
+/** Sidecar artifact recording the deterministic interpretation of free_form_intent. */
+export declare const INTENT_INTERPRETATION_FILENAME = "intent-interpretation.json";
+export declare const INTENT_INTERPRETATION_SCHEMA_VERSION = "remediate-code-intent-interpretation/v1alpha1";
+export interface PersistedIntentInterpretation {
+    schema_version: typeof INTENT_INTERPRETATION_SCHEMA_VERSION;
+    /** The interpreter's structured output (lens weights / priority / scope). */
+    interpreted: InterpretedIntent;
+    /**
+     * Clauses the interpreter could not encode as a lens weight, priority signal,
+     * or scope emphasis. Surfaced so the host can promote them to constraints —
+     * never silently dropped.
+     */
+    unencodable_clauses: string[];
+    created_at: string;
+}
+/**
+ * Interpret a confirmed checkpoint's `free_form_intent` via the shared
+ * deterministic interpreter and persist the structured signals to a sidecar
+ * artifact. Idempotent and best-effort: returns the persisted interpretation (or
+ * null when there is nothing to interpret / no confirmed checkpoint) and never
+ * throws into the decide loop. The raw `free_form_intent` string is NOT returned
+ * or threaded anywhere — only the structured `InterpretedIntent` is (INV-S04).
+ */
+export declare function interpretConfirmedCheckpointIntent(artifactsDir: string, checkpoint: IntentCheckpoint | undefined): Promise<PersistedIntentInterpretation | null>;
+//# sourceMappingURL=nextStep.d.ts.map

package/dist/remediate/steps/nextStep.d.ts.map

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