scai 0.1.178 → 1.0.0

package/dist/agents/guardPolicy.js

@@ -41,3 +41,23 @@ export function canExecuteRoute(context, action) {
             return true;
     }
 }
+/**
+ * Builds a coarse gate matrix without changing guard behavior.
+ * Example: resolver can consume one snapshot instead of calling each gate repeatedly.
+ */
+export function buildGuardMatrix(context) {
+    return {
+        phaseAllowed: {
+            analysis: canExecutePhase(context, "analysis") && canExecuteScope(context, "analysis"),
+            planning: canExecutePhase(context, "planning") && canExecuteScope(context, "planning"),
+            transform: canExecutePhase(context, "transform") && canExecuteScope(context, "transform"),
+            write: canExecutePhase(context, "write") && canExecuteScope(context, "write"),
+        },
+        routeAllowed: {
+            searchExpand: canExecuteRoute(context, "search-expand"),
+            research: canExecuteRoute(context, "research"),
+            transform: canExecuteRoute(context, "transform"),
+        },
+    };
+}
+//# sourceMappingURL=guardPolicy.js.map

package/dist/agents/guardPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardPolicy.js","sourceRoot":"","sources":["../../src/agents/guardPolicy.ts"],"names":[],"mappings":"AAaA;;GAEG;AACH,MAAM,UAAU,eAAe,CAC7B,OAA0B,EAC1B,KAAiB;IAEjB,MAAM,WAAW,GAAG,OAAO,CAAC,gBAAgB,EAAE,WAAW,CAAC;IAC1D,MAAM,QAAQ,GAAG,WAAW,EAAE,QAAQ,IAAI,KAAK,CAAC;IAEhD,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,UAAU,CAAC;QAChB,KAAK,UAAU;YACb,OAAO,CAAC,QAAQ,CAAC;QACnB,KAAK,WAAW,CAAC;QACjB,KAAK,OAAO;YACV,OAAO,WAAW,EAAE,eAAe,IAAI,KAAK,CAAC;QAC/C;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAC7B,OAA0B,EAC1B,KAAiB;IAEjB,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,SAAS,IAAI,WAAW,CAAC;IACzD,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QACrB,OAAO,KAAK,KAAK,UAAU,IAAI,KAAK,KAAK,UAAU,CAAC;IACtD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAC7B,OAA0B,EAC1B,MAAmB;IAEnB,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,EAAE,eAAe,CAAC;IAElD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,eAAe;YAClB,OAAO,OAAO,EAAE,WAAW,IAAI,IAAI,CAAC;QACtC,KAAK,WAAW;YACd,OAAO,OAAO,EAAE,cAAc,IAAI,IAAI,CAAC;QACzC,KAAK,UAAU;YACb,OAAO,OAAO,EAAE,aAAa,IAAI,KAAK,CAAC;QACzC;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA0B;IACzD,OAAO;QACL,YAAY,EAAE;YACZ,QAAQ,EACN,eAAe,CAAC,OAAO,EAAE,UAAU,CAAC,IAAI,eAAe,CAAC,OAAO,EAAE,UAAU,CAAC;YAC9E,QAAQ,EACN,eAAe,CAAC,OAAO,EAAE,UAAU,CAAC,IAAI,eAAe,CAAC,OAAO,EAAE,UAAU,CAAC;YAC9E,SAAS,EACP,eAAe,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,eAAe,CAAC,OAAO,EAAE,WAAW,CAAC;YAChF,KAAK,EACH,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC;SACzE;QACD,YAAY,EAAE;YACZ,YAAY,EAAE,eAAe,CAAC,OAAO,EAAE,eAAe,CAAC;YACvD,QAAQ,EAAE,eAAe,CAAC,OAAO,EAAE,UAAU,CAAC;YAC9C,SAAS,EAAE,eAAe,CAAC,OAAO,EAAE,WAAW,CAAC;SACjD;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type { StructuredContext } from \"../types.js\";\n\nexport type GuardPhase = \"analysis\" | \"planning\" | \"transform\" | \"write\";\nexport type RouteAction = \"search-expand\" | \"research\" | \"transform\";\nexport type GuardMatrix = {\n  phaseAllowed: Record<GuardPhase, boolean>;\n  routeAllowed: {\n    searchExpand: boolean;\n    research: boolean;\n    transform: boolean;\n  };\n};\n\n/**\n * Gate 1: capability constraints (execution control).\n */\nexport function canExecutePhase(\n  context: StructuredContext,\n  phase: GuardPhase\n): boolean {\n  const constraints = context.executionControl?.constraints;\n  const docsOnly = constraints?.docsOnly ?? false;\n\n  switch (phase) {\n    case \"analysis\":\n    case \"planning\":\n      return !docsOnly;\n    case \"transform\":\n    case \"write\":\n      return constraints?.allowFileWrites ?? false;\n    default:\n      return false;\n  }\n}\n\n/**\n * Gate 2: scope constraints (none/single/multi/repo-wide).\n */\nexport function canExecuteScope(\n  context: StructuredContext,\n  phase: GuardPhase\n): boolean {\n  const scope = context.analysis?.scopeType ?? \"repo-wide\";\n  if (scope === \"none\") {\n    return phase === \"analysis\" || phase === \"planning\";\n  }\n  return true;\n}\n\n/**\n * Gate 3: route constraints (dynamic routing decisions).\n */\nexport function canExecuteRoute(\n  context: StructuredContext,\n  action: RouteAction\n): boolean {\n  const routing = context.analysis?.routingDecision;\n\n  switch (action) {\n    case \"search-expand\":\n      return routing?.allowSearch ?? true;\n    case \"transform\":\n      return routing?.allowTransform ?? true;\n    case \"research\":\n      return routing?.allowResearch ?? false;\n    default:\n      return true;\n  }\n}\n\n/**\n * Builds a coarse gate matrix without changing guard behavior.\n * Example: resolver can consume one snapshot instead of calling each gate repeatedly.\n */\nexport function buildGuardMatrix(context: StructuredContext): GuardMatrix {\n  return {\n    phaseAllowed: {\n      analysis:\n        canExecutePhase(context, \"analysis\") && canExecuteScope(context, \"analysis\"),\n      planning:\n        canExecutePhase(context, \"planning\") && canExecuteScope(context, \"planning\"),\n      transform:\n        canExecutePhase(context, \"transform\") && canExecuteScope(context, \"transform\"),\n      write:\n        canExecutePhase(context, \"write\") && canExecuteScope(context, \"write\"),\n    },\n    routeAllowed: {\n      searchExpand: canExecuteRoute(context, \"search-expand\"),\n      research: canExecuteRoute(context, \"research\"),\n      transform: canExecuteRoute(context, \"transform\"),\n    },\n  };\n}\n"]}

package/dist/agents/guards/executionPolicyResolver.js

@@ -0,0 +1,165 @@
+import { buildGuardMatrix } from "../guardPolicy.js";
+import path from "path";
+const MULTI_FILE_MAX = 6;
+const REPO_WIDE_MIN = 7;
+const LOCK_VERIFY_CONFIDENCE_MIN = 0.4;
+/**
+ * Resolves one deterministic execution snapshot from guards + focus lanes.
+ * Why it exists: keep lane/lock/sub-scope logic in one place instead of scattered checks.
+ */
+export function resolveExecutionPolicy(context) {
+    const matrix = buildGuardMatrix(context);
+    const analysis = context.analysis ?? {};
+    const focus = analysis.focus ?? { selectedFiles: [], candidateFiles: [] };
+    const scopeType = (analysis.scopeType ?? "repo-wide");
+    const selectedFiles = normalizeExecutionFileList(focus.selectedFiles ?? []);
+    const candidateFiles = normalizeExecutionFileList(focus.candidateFiles ?? []);
+    const rawExecutionRequired = (focus.executionRequired && focus.executionRequired.length > 0
+        ? focus.executionRequired
+        : selectedFiles) ?? [];
+    const executionRequired = normalizeExecutionFileList(rawExecutionRequired);
+    const rawExploration = (focus.explorationCandidates && focus.explorationCandidates.length > 0
+        ? focus.explorationCandidates
+        : candidateFiles) ?? [];
+    const executionSet = new Set(executionRequired);
+    const explorationCandidates = normalizeExecutionFileList(rawExploration.filter((filePath) => !executionSet.has(filePath)));
+    const scopeBand = normalizeScopeBand(scopeType, executionRequired.length);
+    const lock = deriveExecutionLock(context, matrix.phaseAllowed.transform, matrix.routeAllowed.transform, executionRequired);
+    const executionReady = executionRequired.length > 0 &&
+        matrix.phaseAllowed.transform &&
+        matrix.routeAllowed.transform &&
+        scopeType !== "none";
+    const explorationReady = explorationCandidates.length > 0 &&
+        matrix.routeAllowed.searchExpand &&
+        matrix.phaseAllowed.planning;
+    const policyNotes = [
+        `scopeType=${scopeType}`,
+        `scopeBand=${scopeBand}`,
+        `executionRequired=${executionRequired.length}`,
+        `explorationCandidates=${explorationCandidates.length}`,
+    ];
+    if (lock.enabled) {
+        policyNotes.push(`executionLock=${lock.files.join(", ")}`);
+    }
+    return {
+        phaseAllowed: matrix.phaseAllowed,
+        routeAllowed: matrix.routeAllowed,
+        scopeType,
+        scopeBand,
+        executionRequired,
+        explorationCandidates,
+        executionLock: lock,
+        executionReady,
+        explorationReady,
+        policyNotes,
+    };
+}
+/**
+ * Keeps execution policy tied to canonical repo files only.
+ * Example: "/repo/cli/src/db/fileIndex.ts" -> keep, "db/fileIndex.ts" -> drop.
+ */
+function normalizeExecutionFileList(paths) {
+    const out = new Set();
+    for (const filePath of paths) {
+        const trimmed = String(filePath ?? "").trim();
+        if (!trimmed || trimmed.startsWith("__research__/") || !path.isAbsolute(trimmed)) {
+            continue;
+        }
+        out.add(path.normalize(trimmed));
+    }
+    return Array.from(out);
+}
+/**
+ * Enforces monotonic lock invariant for the active objective.
+ * Example: once locked to cli/package.json, that file stays in executionRequired until complete/give-up.
+ */
+export function enforceExecutionPolicyInvariant(context, snapshot) {
+    var _a;
+    context.analysis || (context.analysis = {});
+    (_a = context.analysis).focus || (_a.focus = { selectedFiles: [], candidateFiles: [] });
+    const objectiveDone = context.analysis.objective?.completionStatus === "satisfied";
+    const gaveUp = context.analysis.giveUp?.status === "triggered";
+    if (objectiveDone || gaveUp)
+        return { restored: false, restoredFiles: [] };
+    if (context.analysis.recoveryEvaluation?.decision === "rework-scope") {
+        return { restored: false, restoredFiles: [] };
+    }
+    const lockFiles = snapshot.executionLock.enabled ? snapshot.executionLock.files : [];
+    if (lockFiles.length === 0)
+        return { restored: false, restoredFiles: [] };
+    const required = new Set(snapshot.executionRequired);
+    let changed = false;
+    const restoredFiles = [];
+    for (const filePath of lockFiles) {
+        if (!required.has(filePath)) {
+            required.add(filePath);
+            changed = true;
+            restoredFiles.push(filePath);
+        }
+    }
+    if (!changed)
+        return { restored: false, restoredFiles: [] };
+    const merged = Array.from(required);
+    context.analysis.focus.executionRequired = merged;
+    context.analysis.executionPolicy = {
+        ...snapshot,
+        executionRequired: merged,
+        policyNotes: [...snapshot.policyNotes, "invariant-restored-lock-files"],
+    };
+    return { restored: true, restoredFiles };
+}
+function normalizeScopeBand(scopeType, requiredCount) {
+    if (scopeType === "none")
+        return "none";
+    if (requiredCount >= REPO_WIDE_MIN)
+        return "repo-wide";
+    if (requiredCount >= 2 && requiredCount <= MULTI_FILE_MAX)
+        return "multi-file";
+    if (requiredCount === 1)
+        return "single-file";
+    return scopeType;
+}
+function deriveExecutionLock(context, transformPhaseAllowed, transformRouteAllowed, executionRequired) {
+    if (context.analysis?.recoveryEvaluation?.decision === "rework-scope") {
+        return { enabled: false, files: [], reason: "cleared-by-rework-scope" };
+    }
+    const existingLock = context.analysis?.focus?.executionLock;
+    if (existingLock?.enabled && existingLock.files.length > 0) {
+        return existingLock;
+    }
+    if (!transformPhaseAllowed || !transformRouteAllowed) {
+        return { enabled: false, files: [], reason: "transform-blocked-by-guards" };
+    }
+    if (executionRequired.length !== 1) {
+        return { enabled: false, files: [], reason: "requires-single-dominant-file" };
+    }
+    const targetFile = executionRequired[0];
+    const verify = context.analysis?.verify?.byFile?.[targetFile];
+    const verifyConfidence = verify?.fileConfidence ?? 0;
+    const explicitTargetSignal = hasExplicitTargetSignal(context, targetFile);
+    if (!explicitTargetSignal) {
+        return { enabled: false, files: [], reason: "no-explicit-target-signal" };
+    }
+    if (verifyConfidence < LOCK_VERIFY_CONFIDENCE_MIN) {
+        return { enabled: false, files: [], reason: "verify-confidence-below-threshold" };
+    }
+    return {
+        enabled: true,
+        files: [targetFile],
+        reason: `single-file-lock(explicit-target, verify>=${LOCK_VERIFY_CONFIDENCE_MIN})`,
+    };
+}
+function hasExplicitTargetSignal(context, targetFile) {
+    const resolvedFocusTargets = context.analysis?.focus?.resolvedTargetFiles ?? [];
+    if (resolvedFocusTargets.includes(targetFile))
+        return true;
+    const intentTargets = context.analysis?.intent?.targetFiles ?? [];
+    if (intentTargets.includes(targetFile))
+        return true;
+    const query = (context.analysis?.intent?.normalizedQuery ?? context.initContext?.userQuery ?? "").toLowerCase();
+    if (!query)
+        return false;
+    const basename = targetFile.split("/").pop()?.toLowerCase() ?? "";
+    return basename.length > 0 && query.includes(basename);
+}
+//# sourceMappingURL=executionPolicyResolver.js.map

package/dist/agents/guards/executionPolicyResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executionPolicyResolver.js","sourceRoot":"","sources":["../../../src/agents/guards/executionPolicyResolver.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,MAAM,cAAc,GAAG,CAAC,CAAC;AACzB,MAAM,aAAa,GAAG,CAAC,CAAC;AACxB,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAA0B;IAC/D,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;IACxC,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;IAC1E,MAAM,SAAS,GAAG,CAAC,QAAQ,CAAC,SAAS,IAAI,WAAW,CAAc,CAAC;IACnE,MAAM,aAAa,GAAG,0BAA0B,CAAC,KAAK,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC;IAC5E,MAAM,cAAc,GAAG,0BAA0B,CAAC,KAAK,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC;IAE9E,MAAM,oBAAoB,GACxB,CAAC,KAAK,CAAC,iBAAiB,IAAI,KAAK,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC;QAC5D,CAAC,CAAC,KAAK,CAAC,iBAAiB;QACzB,CAAC,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;IAC3B,MAAM,iBAAiB,GAAG,0BAA0B,CAAC,oBAAoB,CAAC,CAAC;IAE3E,MAAM,cAAc,GAClB,CAAC,KAAK,CAAC,qBAAqB,IAAI,KAAK,CAAC,qBAAqB,CAAC,MAAM,GAAG,CAAC;QACpE,CAAC,CAAC,KAAK,CAAC,qBAAqB;QAC7B,CAAC,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;IAC5B,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAChD,MAAM,qBAAqB,GAAG,0BAA0B,CACtD,cAAc,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CACjE,CAAC;IAEF,MAAM,SAAS,GAAG,kBAAkB,CAAC,SAAS,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC1E,MAAM,IAAI,GAAG,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC;IAE3H,MAAM,cAAc,GAClB,iBAAiB,CAAC,MAAM,GAAG,CAAC;QAC5B,MAAM,CAAC,YAAY,CAAC,SAAS;QAC7B,MAAM,CAAC,YAAY,CAAC,SAAS;QAC7B,SAAS,KAAK,MAAM,CAAC;IAEvB,MAAM,gBAAgB,GACpB,qBAAqB,CAAC,MAAM,GAAG,CAAC;QAChC,MAAM,CAAC,YAAY,CAAC,YAAY;QAChC,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC;IAE/B,MAAM,WAAW,GAAG;QAClB,aAAa,SAAS,EAAE;QACxB,aAAa,SAAS,EAAE;QACxB,qBAAqB,iBAAiB,CAAC,MAAM,EAAE;QAC/C,yBAAyB,qBAAqB,CAAC,MAAM,EAAE;KACxD,CAAC;IACF,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,WAAW,CAAC,IAAI,CAAC,iBAAiB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO;QACL,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,SAAS;QACT,SAAS;QACT,iBAAiB;QACjB,qBAAqB;QACrB,aAAa,EAAE,IAAI;QACnB,cAAc;QACd,gBAAgB;QAChB,WAAW;KACZ,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,0BAA0B,CAAC,KAAe;IACjD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,QAAQ,IAAI,KAAK,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC9C,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACjF,SAAS;QACX,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,+BAA+B,CAC7C,OAA0B,EAC1B,QAAiC;;IAEjC,OAAO,CAAC,QAAQ,KAAhB,OAAO,CAAC,QAAQ,GAAK,EAAE,EAAC;IACxB,MAAA,OAAO,CAAC,QAAQ,EAAC,KAAK,QAAL,KAAK,GAAK,EAAE,aAAa,EAAE,EAAE,EAAE,cAAc,EAAE,EAAE,EAAE,EAAC;IAErE,MAAM,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,SAAS,EAAE,gBAAgB,KAAK,WAAW,CAAC;IACnF,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,KAAK,WAAW,CAAC;IAC/D,IAAI,aAAa,IAAI,MAAM;QAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;IAC3E,IAAI,OAAO,CAAC,QAAQ,CAAC,kBAAkB,EAAE,QAAQ,KAAK,cAAc,EAAE,CAAC;QACrE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;IAChD,CAAC;IAED,MAAM,SAAS,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACrF,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;IAE1E,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IACrD,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5B,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACvB,OAAO,GAAG,IAAI,CAAC;YACf,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;IAE5D,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,iBAAiB,GAAG,MAAM,CAAC;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,GAAG;QACjC,GAAG,QAAQ;QACX,iBAAiB,EAAE,MAAM;QACzB,WAAW,EAAE,CAAC,GAAG,QAAQ,CAAC,WAAW,EAAE,+BAA+B,CAAC;KACxE,CAAC;IACF,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;AAC3C,CAAC;AAED,SAAS,kBAAkB,CAAC,SAAoB,EAAE,aAAqB;IACrE,IAAI,SAAS,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC;IACxC,IAAI,aAAa,IAAI,aAAa;QAAE,OAAO,WAAW,CAAC;IACvD,IAAI,aAAa,IAAI,CAAC,IAAI,aAAa,IAAI,cAAc;QAAE,OAAO,YAAY,CAAC;IAC/E,IAAI,aAAa,KAAK,CAAC;QAAE,OAAO,aAAa,CAAC;IAC9C,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,mBAAmB,CAC1B,OAA0B,EAC1B,qBAA8B,EAC9B,qBAA8B,EAC9B,iBAA2B;IAE3B,IAAI,OAAO,CAAC,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,KAAK,cAAc,EAAE,CAAC;QACtE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC;IAC1E,CAAC;IAED,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,aAAa,CAAC;IAC5D,IAAI,YAAY,EAAE,OAAO,IAAI,YAAY,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3D,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,IAAI,CAAC,qBAAqB,IAAI,CAAC,qBAAqB,EAAE,CAAC;QACrD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,6BAA6B,EAAE,CAAC;IAC9E,CAAC;IAED,IAAI,iBAAiB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,+BAA+B,EAAE,CAAC;IAChF,CAAC;IAED,MAAM,UAAU,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,UAAU,CAAC,CAAC;IAC9D,MAAM,gBAAgB,GAAG,MAAM,EAAE,cAAc,IAAI,CAAC,CAAC;IACrD,MAAM,oBAAoB,GAAG,uBAAuB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAE1E,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAC1B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,2BAA2B,EAAE,CAAC;IAC5E,CAAC;IAED,IAAI,gBAAgB,GAAG,0BAA0B,EAAE,CAAC;QAClD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,mCAAmC,EAAE,CAAC;IACpF,CAAC;IAED,OAAO;QACL,OAAO,EAAE,IAAI;QACb,KAAK,EAAE,CAAC,UAAU,CAAC;QACnB,MAAM,EAAE,6CAA6C,0BAA0B,GAAG;KACnF,CAAC;AACJ,CAAC;AAED,SAAS,uBAAuB,CAAC,OAA0B,EAAE,UAAkB;IAC7E,MAAM,oBAAoB,GAAG,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,mBAAmB,IAAI,EAAE,CAAC;IAChF,IAAI,oBAAoB,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAE3D,MAAM,aAAa,GAAG,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,IAAI,EAAE,CAAC;IAClE,IAAI,aAAa,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAEpD,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,eAAe,IAAI,OAAO,CAAC,WAAW,EAAE,SAAS,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAChH,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAEzB,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAClE,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACzD,CAAC","sourcesContent":["/**\n * Resolves one deterministic execution policy snapshot from scope, route, and focus state.\n *\n * Why this file exists:\n * - keep execution breadth, lock rules, and exploration lanes in one place\n * - give downstream loop code one policy input before guard resolution\n * - prevent transform and exploration checks from being scattered\n */\nimport type { ExecutionPolicySnapshot, ScopeBand, ScopeType, StructuredContext } from \"../../types.js\";\nimport { buildGuardMatrix } from \"../guardPolicy.js\";\nimport path from \"path\";\n\nconst MULTI_FILE_MAX = 6;\nconst REPO_WIDE_MIN = 7;\nconst LOCK_VERIFY_CONFIDENCE_MIN = 0.4;\n\n/**\n * Resolves one deterministic execution snapshot from guards + focus lanes.\n * Why it exists: keep lane/lock/sub-scope logic in one place instead of scattered checks.\n */\nexport function resolveExecutionPolicy(context: StructuredContext): ExecutionPolicySnapshot {\n  const matrix = buildGuardMatrix(context);\n  const analysis = context.analysis ?? {};\n  const focus = analysis.focus ?? { selectedFiles: [], candidateFiles: [] };\n  const scopeType = (analysis.scopeType ?? \"repo-wide\") as ScopeType;\n  const selectedFiles = normalizeExecutionFileList(focus.selectedFiles ?? []);\n  const candidateFiles = normalizeExecutionFileList(focus.candidateFiles ?? []);\n\n  const rawExecutionRequired =\n    (focus.executionRequired && focus.executionRequired.length > 0\n      ? focus.executionRequired\n      : selectedFiles) ?? [];\n  const executionRequired = normalizeExecutionFileList(rawExecutionRequired);\n\n  const rawExploration =\n    (focus.explorationCandidates && focus.explorationCandidates.length > 0\n      ? focus.explorationCandidates\n      : candidateFiles) ?? [];\n  const executionSet = new Set(executionRequired);\n  const explorationCandidates = normalizeExecutionFileList(\n    rawExploration.filter((filePath) => !executionSet.has(filePath))\n  );\n\n  const scopeBand = normalizeScopeBand(scopeType, executionRequired.length);\n  const lock = deriveExecutionLock(context, matrix.phaseAllowed.transform, matrix.routeAllowed.transform, executionRequired);\n\n  const executionReady =\n    executionRequired.length > 0 &&\n    matrix.phaseAllowed.transform &&\n    matrix.routeAllowed.transform &&\n    scopeType !== \"none\";\n\n  const explorationReady =\n    explorationCandidates.length > 0 &&\n    matrix.routeAllowed.searchExpand &&\n    matrix.phaseAllowed.planning;\n\n  const policyNotes = [\n    `scopeType=${scopeType}`,\n    `scopeBand=${scopeBand}`,\n    `executionRequired=${executionRequired.length}`,\n    `explorationCandidates=${explorationCandidates.length}`,\n  ];\n  if (lock.enabled) {\n    policyNotes.push(`executionLock=${lock.files.join(\", \")}`);\n  }\n\n  return {\n    phaseAllowed: matrix.phaseAllowed,\n    routeAllowed: matrix.routeAllowed,\n    scopeType,\n    scopeBand,\n    executionRequired,\n    explorationCandidates,\n    executionLock: lock,\n    executionReady,\n    explorationReady,\n    policyNotes,\n  };\n}\n\n/**\n * Keeps execution policy tied to canonical repo files only.\n * Example: \"/repo/cli/src/db/fileIndex.ts\" -> keep, \"db/fileIndex.ts\" -> drop.\n */\nfunction normalizeExecutionFileList(paths: string[]): string[] {\n  const out = new Set<string>();\n  for (const filePath of paths) {\n    const trimmed = String(filePath ?? \"\").trim();\n    if (!trimmed || trimmed.startsWith(\"__research__/\") || !path.isAbsolute(trimmed)) {\n      continue;\n    }\n    out.add(path.normalize(trimmed));\n  }\n  return Array.from(out);\n}\n\n/**\n * Enforces monotonic lock invariant for the active objective.\n * Example: once locked to cli/package.json, that file stays in executionRequired until complete/give-up.\n */\nexport function enforceExecutionPolicyInvariant(\n  context: StructuredContext,\n  snapshot: ExecutionPolicySnapshot\n): { restored: boolean; restoredFiles: string[] } {\n  context.analysis ||= {};\n  context.analysis.focus ||= { selectedFiles: [], candidateFiles: [] };\n\n  const objectiveDone = context.analysis.objective?.completionStatus === \"satisfied\";\n  const gaveUp = context.analysis.giveUp?.status === \"triggered\";\n  if (objectiveDone || gaveUp) return { restored: false, restoredFiles: [] };\n  if (context.analysis.recoveryEvaluation?.decision === \"rework-scope\") {\n    return { restored: false, restoredFiles: [] };\n  }\n\n  const lockFiles = snapshot.executionLock.enabled ? snapshot.executionLock.files : [];\n  if (lockFiles.length === 0) return { restored: false, restoredFiles: [] };\n\n  const required = new Set(snapshot.executionRequired);\n  let changed = false;\n  const restoredFiles: string[] = [];\n  for (const filePath of lockFiles) {\n    if (!required.has(filePath)) {\n      required.add(filePath);\n      changed = true;\n      restoredFiles.push(filePath);\n    }\n  }\n\n  if (!changed) return { restored: false, restoredFiles: [] };\n\n  const merged = Array.from(required);\n  context.analysis.focus.executionRequired = merged;\n  context.analysis.executionPolicy = {\n    ...snapshot,\n    executionRequired: merged,\n    policyNotes: [...snapshot.policyNotes, \"invariant-restored-lock-files\"],\n  };\n  return { restored: true, restoredFiles };\n}\n\nfunction normalizeScopeBand(scopeType: ScopeType, requiredCount: number): ScopeBand {\n  if (scopeType === \"none\") return \"none\";\n  if (requiredCount >= REPO_WIDE_MIN) return \"repo-wide\";\n  if (requiredCount >= 2 && requiredCount <= MULTI_FILE_MAX) return \"multi-file\";\n  if (requiredCount === 1) return \"single-file\";\n  return scopeType;\n}\n\nfunction deriveExecutionLock(\n  context: StructuredContext,\n  transformPhaseAllowed: boolean,\n  transformRouteAllowed: boolean,\n  executionRequired: string[]\n): ExecutionPolicySnapshot[\"executionLock\"] {\n  if (context.analysis?.recoveryEvaluation?.decision === \"rework-scope\") {\n    return { enabled: false, files: [], reason: \"cleared-by-rework-scope\" };\n  }\n\n  const existingLock = context.analysis?.focus?.executionLock;\n  if (existingLock?.enabled && existingLock.files.length > 0) {\n    return existingLock;\n  }\n\n  if (!transformPhaseAllowed || !transformRouteAllowed) {\n    return { enabled: false, files: [], reason: \"transform-blocked-by-guards\" };\n  }\n\n  if (executionRequired.length !== 1) {\n    return { enabled: false, files: [], reason: \"requires-single-dominant-file\" };\n  }\n\n  const targetFile = executionRequired[0];\n  const verify = context.analysis?.verify?.byFile?.[targetFile];\n  const verifyConfidence = verify?.fileConfidence ?? 0;\n  const explicitTargetSignal = hasExplicitTargetSignal(context, targetFile);\n\n  if (!explicitTargetSignal) {\n    return { enabled: false, files: [], reason: \"no-explicit-target-signal\" };\n  }\n\n  if (verifyConfidence < LOCK_VERIFY_CONFIDENCE_MIN) {\n    return { enabled: false, files: [], reason: \"verify-confidence-below-threshold\" };\n  }\n\n  return {\n    enabled: true,\n    files: [targetFile],\n    reason: `single-file-lock(explicit-target, verify>=${LOCK_VERIFY_CONFIDENCE_MIN})`,\n  };\n}\n\nfunction hasExplicitTargetSignal(context: StructuredContext, targetFile: string): boolean {\n  const resolvedFocusTargets = context.analysis?.focus?.resolvedTargetFiles ?? [];\n  if (resolvedFocusTargets.includes(targetFile)) return true;\n\n  const intentTargets = context.analysis?.intent?.targetFiles ?? [];\n  if (intentTargets.includes(targetFile)) return true;\n\n  const query = (context.analysis?.intent?.normalizedQuery ?? context.initContext?.userQuery ?? \"\").toLowerCase();\n  if (!query) return false;\n\n  const basename = targetFile.split(\"/\").pop()?.toLowerCase() ?? \"\";\n  return basename.length > 0 && query.includes(basename);\n}\n"]}

package/dist/agents/guards/guardState.js

@@ -0,0 +1,195 @@
+import { canExecutePhase, canExecuteScope } from "../guardPolicy.js";
+import { resolveExecutionPolicy } from "./executionPolicyResolver.js";
+function isResearchStep(step) {
+    return (step.action ?? "").startsWith("research-") || (step.filePath ?? "").startsWith("__research__/");
+}
+function deriveGuardLane(context) {
+    const resolvedTargetFiles = context.analysis?.focus?.resolvedTargetFiles ??
+        context.analysis?.intent?.resolvedTargetFiles ??
+        [];
+    const resolvedTargetFolders = context.analysis?.focus?.resolvedTargetFolders ?? [];
+    if (resolvedTargetFiles.length > 0 || resolvedTargetFolders.length > 0) {
+        return "explicit-target";
+    }
+    if (context.analysis?.continuityDecision?.answerNow)
+        return "resume-continuity";
+    const routing = context.analysis?.routingDecision;
+    const readiness = context.analysis?.readiness?.decision;
+    if (routing?.allowSearch === false && routing?.allowTransform === false)
+        return "direct-answer";
+    if (routing?.decision === "needs-info" || readiness !== "ready")
+        return "evidence";
+    return "coding";
+}
+function deriveTerminalState(context) {
+    if (context.analysis?.giveUp?.status === "triggered" || context.task.status === "gave-up") {
+        return {
+            continuationMode: "terminal",
+            terminalReason: "give-up",
+            blockingReason: context.analysis?.giveUp?.rationale ?? "Bounded give-up triggered.",
+        };
+    }
+    if (context.task.status === "completed") {
+        return {
+            continuationMode: "terminal",
+            terminalReason: "complete",
+            blockingReason: "Task completed.",
+        };
+    }
+    if (context.task.status === "paused") {
+        return {
+            continuationMode: "terminal",
+            terminalReason: "request-feedback",
+            blockingReason: "Awaiting user clarification.",
+        };
+    }
+    const nextAction = context.analysis?.iterationReasoning?.nextAction;
+    if (nextAction === "give-up") {
+        return {
+            continuationMode: "terminal",
+            terminalReason: "give-up",
+            blockingReason: context.analysis?.iterationReasoning?.rationale ?? "Bounded give-up triggered.",
+        };
+    }
+    if (nextAction === "complete") {
+        return {
+            continuationMode: "terminal",
+            terminalReason: "complete",
+            blockingReason: context.analysis?.iterationReasoning?.rationale ?? "Task completed.",
+        };
+    }
+    if (nextAction === "request-feedback") {
+        return {
+            continuationMode: "terminal",
+            terminalReason: "request-feedback",
+            blockingReason: context.analysis?.iterationReasoning?.rationale ?? "Awaiting user clarification.",
+        };
+    }
+    return null;
+}
+function deriveGuardReadiness(context) {
+    return context.analysis?.readiness?.decision === "ready" ? "ready" : "not-ready";
+}
+/**
+ * Builds the shared non-observability fields for the resolved guard.
+ * Example: terminal and non-terminal states both reuse route permissions and execution lock fields.
+ */
+function buildGuardState(context, policy, lane, continuationMode, extras) {
+    return {
+        lane,
+        readiness: deriveGuardReadiness(context),
+        continuationMode,
+        allowSearchExpand: policy.routeAllowed.searchExpand,
+        allowResearch: policy.routeAllowed.research,
+        allowTransform: policy.routeAllowed.transform,
+        executionReady: policy.executionReady,
+        executionLockEnabled: policy.executionLock.enabled,
+        executionRequired: policy.executionRequired,
+        ...(extras?.blockingReason ? { blockingReason: extras.blockingReason } : {}),
+        ...(extras?.terminalReason ? { terminalReason: extras.terminalReason } : {}),
+    };
+}
+/**
+ * Resolves the forced bridge or free-execution state for the current loop turn.
+ * Example: no related files yet -> `need-search`; ready evidence with transform disabled -> `can-research` or `can-execute`.
+ */
+function deriveContinuationMode(context, policy) {
+    if (context.analysis?.recoveryEvaluation?.decision === "rework-scope") {
+        return {
+            continuationMode: "can-execute",
+            blockingReason: context.analysis.recoveryEvaluation.reason,
+        };
+    }
+    const resolvedTargets = context.analysis?.intent?.resolvedTargetFiles ?? [];
+    const focusResolvedTargets = context.analysis?.focus?.resolvedTargetFiles ?? [];
+    const relatedFiles = context.initContext?.relatedFiles ?? [];
+    const selectedFiles = context.analysis?.focus?.selectedFiles ?? [];
+    const candidateFiles = context.analysis?.focus?.candidateFiles ?? [];
+    const workingFiles = context.workingFiles ?? [];
+    if (canExecuteScope(context, "analysis") &&
+        resolvedTargets.length === 0 &&
+        focusResolvedTargets.length === 0 &&
+        relatedFiles.length === 0 &&
+        selectedFiles.length === 0 &&
+        candidateFiles.length === 0 &&
+        workingFiles.length === 0) {
+        return {
+            continuationMode: "need-search",
+            blockingReason: "Initial evidence bootstrap has not run yet; run search before verify or execution seeding.",
+        };
+    }
+    const readinessDecision = context.analysis?.readiness?.decision ?? "not-ready";
+    const readinessConfidence = context.analysis?.readiness?.confidence ?? 0;
+    if (canExecuteScope(context, "analysis") && readinessDecision !== "ready") {
+        return {
+            continuationMode: "need-verify",
+            blockingReason: `Readiness not achieved (decision=${readinessDecision}, confidence=${readinessConfidence})`,
+        };
+    }
+    const researchAllowed = policy.routeAllowed.research;
+    const transformAllowed = policy.routeAllowed.transform;
+    const hasResearchStep = (context.task?.steps ?? []).some(step => isResearchStep(step));
+    if (!policy.executionReady && !(researchAllowed || !transformAllowed || hasResearchStep)) {
+        return {
+            continuationMode: "need-verify",
+            blockingReason: `Execution not ready after verify (executionReady=${policy.executionReady}, researchAllowed=${researchAllowed}, transformAllowed=${transformAllowed})`,
+        };
+    }
+    if (researchAllowed &&
+        canExecuteScope(context, "analysis") &&
+        !(context.task?.steps ?? []).some(step => isResearchStep(step))) {
+        return {
+            continuationMode: "can-research",
+        };
+    }
+    const executionSteps = (context.task?.steps ?? []).filter(step => !isResearchStep(step));
+    const pendingExecutionSteps = executionSteps.filter(step => step.status !== "completed");
+    if (canExecutePhase(context, "planning") &&
+        canExecuteScope(context, "planning") &&
+        pendingExecutionSteps.length === 0 &&
+        executionSteps.length === 0) {
+        return {
+            continuationMode: "can-plan",
+        };
+    }
+    return {
+        continuationMode: "can-execute",
+    };
+}
+export function resolveGuardState(context, policyOverride) {
+    const policy = policyOverride ?? context.analysis?.executionPolicy ?? resolveExecutionPolicy(context);
+    const terminal = deriveTerminalState(context);
+    const lane = deriveGuardLane(context);
+    if (terminal) {
+        return buildGuardState(context, policy, lane, terminal.continuationMode, {
+            blockingReason: terminal.blockingReason,
+            terminalReason: terminal.terminalReason,
+        });
+    }
+    const continuation = deriveContinuationMode(context, policy);
+    return buildGuardState(context, policy, lane, continuation.continuationMode, {
+        blockingReason: continuation.blockingReason,
+    });
+}
+export function buildAllowedActionsFromGuardState(guard) {
+    switch (guard.continuationMode) {
+        case "need-search":
+            return ["run-search"];
+        case "need-verify":
+            return ["run-verify"];
+        case "can-research":
+            return ["seed-research"];
+        case "can-plan":
+            return ["seed-plan"];
+        case "terminal":
+            if (guard.terminalReason === "complete")
+                return ["complete"];
+            if (guard.terminalReason === "request-feedback")
+                return ["request-feedback"];
+            return ["give-up"];
+        case "can-execute":
+        default:
+            return ["continue", "expand-scope", "request-feedback", "complete", "give-up"];
+    }
+}
+//# sourceMappingURL=guardState.js.map

package/dist/agents/guards/guardState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardState.js","sourceRoot":"","sources":["../../../src/agents/guards/guardState.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Resolves one authoritative loop-facing guard state from the agent's current policy inputs.\n *\n * Why this file exists:\n * - routing, readiness, execution policy, and terminal state previously overlapped as separate policy sources\n * - the work loop now needs one explicit policy handoff before it decides the next action\n * - `runtimeState` stays tracing-only, while `GuardState` explains what the loop may do next\n *\n * Boundary:\n * - upstream signals like `routingDecision`, `readiness`, and focus/lock state still exist\n * - this file combines them into one resolved policy snapshot for the work loop\n * - it does not execute work; it only classifies the current continuation state\n */\nimport type {\n  ExecutionPolicySnapshot,\n  GuardContinuationMode,\n  GuardState,\n  NextActionName,\n  StructuredContext,\n} from \"../../types.js\";\nimport { canExecutePhase, canExecuteScope } from \"../guardPolicy.js\";\nimport { resolveExecutionPolicy } from \"./executionPolicyResolver.js\";\n\nfunction isResearchStep(step: { filePath?: string; action?: string }): boolean {\n  return (step.action ?? \"\").startsWith(\"research-\") || (step.filePath ?? \"\").startsWith(\"__research__/\");\n}\n\nfunction deriveGuardLane(context: StructuredContext): GuardState[\"lane\"] {\n  const resolvedTargetFiles =\n    context.analysis?.focus?.resolvedTargetFiles ??\n    context.analysis?.intent?.resolvedTargetFiles ??\n    [];\n  const resolvedTargetFolders = context.analysis?.focus?.resolvedTargetFolders ?? [];\n  if (resolvedTargetFiles.length > 0 || resolvedTargetFolders.length > 0) {\n    return \"explicit-target\";\n  }\n  if (context.analysis?.continuityDecision?.answerNow) return \"resume-continuity\";\n\n  const routing = context.analysis?.routingDecision;\n  const readiness = context.analysis?.readiness?.decision;\n  if (routing?.allowSearch === false && routing?.allowTransform === false) return \"direct-answer\";\n  if (routing?.decision === \"needs-info\" || readiness !== \"ready\") return \"evidence\";\n  return \"coding\";\n}\n\nfunction deriveTerminalState(context: StructuredContext): {\n  continuationMode: GuardContinuationMode;\n  terminalReason: GuardState[\"terminalReason\"];\n  blockingReason: string;\n} | null {\n  if (context.analysis?.giveUp?.status === \"triggered\" || context.task.status === \"gave-up\") {\n    return {\n      continuationMode: \"terminal\",\n      terminalReason: \"give-up\",\n      blockingReason: context.analysis?.giveUp?.rationale ?? \"Bounded give-up triggered.\",\n    };\n  }\n\n  if (context.task.status === \"completed\") {\n    return {\n      continuationMode: \"terminal\",\n      terminalReason: \"complete\",\n      blockingReason: \"Task completed.\",\n    };\n  }\n\n  if (context.task.status === \"paused\") {\n    return {\n      continuationMode: \"terminal\",\n      terminalReason: \"request-feedback\",\n      blockingReason: \"Awaiting user clarification.\",\n    };\n  }\n\n  const nextAction = context.analysis?.iterationReasoning?.nextAction;\n  if (nextAction === \"give-up\") {\n    return {\n      continuationMode: \"terminal\",\n      terminalReason: \"give-up\",\n      blockingReason: context.analysis?.iterationReasoning?.rationale ?? \"Bounded give-up triggered.\",\n    };\n  }\n  if (nextAction === \"complete\") {\n    return {\n      continuationMode: \"terminal\",\n      terminalReason: \"complete\",\n      blockingReason: context.analysis?.iterationReasoning?.rationale ?? \"Task completed.\",\n    };\n  }\n  if (nextAction === \"request-feedback\") {\n    return {\n      continuationMode: \"terminal\",\n      terminalReason: \"request-feedback\",\n      blockingReason: context.analysis?.iterationReasoning?.rationale ?? \"Awaiting user clarification.\",\n    };\n  }\n\n  return null;\n}\n\nfunction deriveGuardReadiness(context: StructuredContext): GuardState[\"readiness\"] {\n  return context.analysis?.readiness?.decision === \"ready\" ? \"ready\" : \"not-ready\";\n}\n\n/**\n * Builds the shared non-observability fields for the resolved guard.\n * Example: terminal and non-terminal states both reuse route permissions and execution lock fields.\n */\nfunction buildGuardState(\n  context: StructuredContext,\n  policy: ExecutionPolicySnapshot,\n  lane: GuardState[\"lane\"],\n  continuationMode: GuardContinuationMode,\n  extras?: Pick<GuardState, \"blockingReason\" | \"terminalReason\">\n): GuardState {\n  return {\n    lane,\n    readiness: deriveGuardReadiness(context),\n    continuationMode,\n    allowSearchExpand: policy.routeAllowed.searchExpand,\n    allowResearch: policy.routeAllowed.research,\n    allowTransform: policy.routeAllowed.transform,\n    executionReady: policy.executionReady,\n    executionLockEnabled: policy.executionLock.enabled,\n    executionRequired: policy.executionRequired,\n    ...(extras?.blockingReason ? { blockingReason: extras.blockingReason } : {}),\n    ...(extras?.terminalReason ? { terminalReason: extras.terminalReason } : {}),\n  };\n}\n\n/**\n * Resolves the forced bridge or free-execution state for the current loop turn.\n * Example: no related files yet -> `need-search`; ready evidence with transform disabled -> `can-research` or `can-execute`.\n */\nfunction deriveContinuationMode(\n  context: StructuredContext,\n  policy: ExecutionPolicySnapshot\n): { continuationMode: GuardContinuationMode; blockingReason?: string } {\n  if (context.analysis?.recoveryEvaluation?.decision === \"rework-scope\") {\n    return {\n      continuationMode: \"can-execute\",\n      blockingReason: context.analysis.recoveryEvaluation.reason,\n    };\n  }\n\n  const resolvedTargets = context.analysis?.intent?.resolvedTargetFiles ?? [];\n  const focusResolvedTargets = context.analysis?.focus?.resolvedTargetFiles ?? [];\n  const relatedFiles = context.initContext?.relatedFiles ?? [];\n  const selectedFiles = context.analysis?.focus?.selectedFiles ?? [];\n  const candidateFiles = context.analysis?.focus?.candidateFiles ?? [];\n  const workingFiles = context.workingFiles ?? [];\n\n  if (\n    canExecuteScope(context, \"analysis\") &&\n    resolvedTargets.length === 0 &&\n    focusResolvedTargets.length === 0 &&\n    relatedFiles.length === 0 &&\n    selectedFiles.length === 0 &&\n    candidateFiles.length === 0 &&\n    workingFiles.length === 0\n  ) {\n    return {\n      continuationMode: \"need-search\",\n      blockingReason: \"Initial evidence bootstrap has not run yet; run search before verify or execution seeding.\",\n    };\n  }\n\n  const readinessDecision = context.analysis?.readiness?.decision ?? \"not-ready\";\n  const readinessConfidence = context.analysis?.readiness?.confidence ?? 0;\n  if (canExecuteScope(context, \"analysis\") && readinessDecision !== \"ready\") {\n    return {\n      continuationMode: \"need-verify\",\n      blockingReason: `Readiness not achieved (decision=${readinessDecision}, confidence=${readinessConfidence})`,\n    };\n  }\n\n  const researchAllowed = policy.routeAllowed.research;\n  const transformAllowed = policy.routeAllowed.transform;\n  const hasResearchStep = (context.task?.steps ?? []).some(step => isResearchStep(step));\n  if (!policy.executionReady && !(researchAllowed || !transformAllowed || hasResearchStep)) {\n    return {\n      continuationMode: \"need-verify\",\n      blockingReason: `Execution not ready after verify (executionReady=${policy.executionReady}, researchAllowed=${researchAllowed}, transformAllowed=${transformAllowed})`,\n    };\n  }\n\n  if (\n    researchAllowed &&\n    canExecuteScope(context, \"analysis\") &&\n    !(context.task?.steps ?? []).some(step => isResearchStep(step))\n  ) {\n    return {\n      continuationMode: \"can-research\",\n    };\n  }\n\n  const executionSteps = (context.task?.steps ?? []).filter(step => !isResearchStep(step));\n  const pendingExecutionSteps = executionSteps.filter(step => step.status !== \"completed\");\n  if (\n    canExecutePhase(context, \"planning\") &&\n    canExecuteScope(context, \"planning\") &&\n    pendingExecutionSteps.length === 0 &&\n    executionSteps.length === 0\n  ) {\n    return {\n      continuationMode: \"can-plan\",\n    };\n  }\n\n  return {\n    continuationMode: \"can-execute\",\n  };\n}\n\nexport function resolveGuardState(\n  context: StructuredContext,\n  policyOverride?: ExecutionPolicySnapshot\n): GuardState {\n  const policy = policyOverride ?? context.analysis?.executionPolicy ?? resolveExecutionPolicy(context);\n  const terminal = deriveTerminalState(context);\n  const lane = deriveGuardLane(context);\n\n  if (terminal) {\n    return buildGuardState(context, policy, lane, terminal.continuationMode, {\n      blockingReason: terminal.blockingReason,\n      terminalReason: terminal.terminalReason,\n    });\n  }\n\n  const continuation = deriveContinuationMode(context, policy);\n  return buildGuardState(context, policy, lane, continuation.continuationMode, {\n    blockingReason: continuation.blockingReason,\n  });\n}\n\nexport function buildAllowedActionsFromGuardState(guard: GuardState): NextActionName[] {\n  switch (guard.continuationMode) {\n    case \"need-search\":\n      return [\"run-search\"];\n    case \"need-verify\":\n      return [\"run-verify\"];\n    case \"can-research\":\n      return [\"seed-research\"];\n    case \"can-plan\":\n      return [\"seed-plan\"];\n    case \"terminal\":\n      if (guard.terminalReason === \"complete\") return [\"complete\"];\n      if (guard.terminalReason === \"request-feedback\") return [\"request-feedback\"];\n      return [\"give-up\"];\n    case \"can-execute\":\n    default:\n      return [\"continue\", \"expand-scope\", \"request-feedback\", \"complete\", \"give-up\"];\n  }\n}\n"]}