@moretea-labs/forge 1.7.0 → 1.7.1

package/scripts/workflow-contract.ts

@@ -1,202 +1,5 @@
-import { existsSync, readFileSync } from "fs";
-import { dirname, join } from "path";
-import { fileURLToPath } from "url";
+#!/usr/bin/env bun
+export * from "../assets/templates/helpers/workflow-contract";
+import { runTrackedForgeHelper } from "./lib/run-forge-helper";
 
-export type WorkflowContract = {
-  version: string;
-  contractId: string;
-  compatibility: {
-    agents: string[];
-    repoLocalFirst: boolean;
-  };
-  externalTooling?: {
-    waza?: {
-      sourceRepo: string;
-      managedSkills: string[];
-      primaryHost: string;
-      codexPrimaryPath: string;
-      stagingCachePath: string;
-      syncMode: string;
-      hostDriftPolicy: string;
-    };
-    codexAutomationProfile?: {
-      requiredSkills: string[];
-      optionalSkills: string[];
-      mode: string;
-      source: string;
-      routes: {
-        workflowHealth: string;
-        reviewGate: string;
-        architectureDiagram: string;
-      };
-      vendoringPolicy: string;
-    };
-    diagramDesign?: {
-      skillName: string;
-      primaryHost: string;
-      codexPrimaryPath: string;
-      syncMode: string;
-      vendoringPolicy: string;
-    };
-  };
-  agenticDevelopment?: {
-    routing: {
-      productDiscovery: string;
-      complexEngineeringPlan: string;
-      designPlan: string;
-      smallOrMediumPlan: string;
-      bugOrRegression: string;
-      postImplementationReview: string;
-    };
-    dueDiligence: {
-      levels: string[];
-      explicitReportRequiredFor: string[];
-    };
-  };
-  documentation?: {
-    referenceConfigs?: {
-      source: string;
-      repoStubDirectory: string;
-      packageDirectory: string;
-      resolverCommand: string;
-      stubMarker: string;
-    };
-  };
-  helpers: {
-    runtimeDirectory?: string;
-    compatibilityDirectory?: string;
-    scripts: string[];
-  };
-  artifacts: {
-    runtimeManifest: string;
-    requiredDirectories: string[];
-    requiredFiles: string[];
-    runtimeFiles?: string[];
-  };
-  documents: {
-    spec: string;
-    currentStatus?: string;
-    planDirectory: string;
-    taskChecklist?: string;
-    deferredGoalLedger?: string;
-    researchReportsDirectory: string;
-    lessonsLog: string;
-  };
-  adoptionTemplates?: {
-    files?: Record<
-      string,
-      {
-        document: string;
-        reason: string;
-        lines: string[];
-      }
-    >;
-  };
-  migrations: {
-    legacyVersions: string[];
-    legacyPaths: string[];
-    upgrade?: {
-      strategyVersion: number;
-      supportedLegacyVersions: string[];
-      actionClasses: string[];
-      safety: {
-        removeOnlyOwnership: string;
-        unknownFiles: string;
-        customHooks: string;
-        ignoredReferenceMaterial: string;
-        localSecrets: string;
-      };
-      actions: Array<{
-        id: string;
-        signal: string;
-        action: "preserve" | "archive" | "reconfigure" | "remove";
-        risk: "low" | "medium" | "high";
-        ownership: "known_generated" | "managed_config" | "user_authored" | "user_local";
-        paths: string[];
-        targetPaths?: string[];
-        cleanupMode?: "always" | "generated_helper";
-        summary: string;
-      }>;
-    };
-  };
-};
-
-const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = SCRIPT_DIR.endsWith("/.ai/harness/scripts")
-  ? join(SCRIPT_DIR, "../../..")
-  : SCRIPT_DIR.endsWith("/assets/templates/helpers")
-    ? join(SCRIPT_DIR, "../../..")
-    : join(SCRIPT_DIR, "..");
-const LOCAL_ASSET_PATH = join(REPO_ROOT, "assets", "workflow-contract.v1.json");
-
-export function resolveAgenticDevRoot(_repoRoot = REPO_ROOT): string {
-  const configuredRoot =
-    process.env.AGENTIC_DEV_ROOT ||
-    process.env.AGENTIC_DEV_SKILL_ROOT;
-  if (configuredRoot && configuredRoot.length > 0) return configuredRoot;
-
-  if (existsSync(LOCAL_ASSET_PATH)) return REPO_ROOT;
-
-  const home = process.env.HOME;
-  if (home && home.length > 0) {
-    const candidates = [
-      join(home, "Projects", "forge"),
-      join(home, ".codex", "skills", "forge"),
-      join(home, ".claude", "skills", "forge"),
-      join(home, ".agents", "skills", "forge"),
-    ];
-
-    for (const candidate of candidates) {
-      if (existsSync(candidate)) return candidate;
-    }
-
-    return candidates[0];
-  }
-
-  return join(".forge", "skills", "forge");
-}
-
-export function resolveAgenticDevSkillRoot(repoRoot = REPO_ROOT): string {
-  return resolveAgenticDevRoot(repoRoot);
-}
-
-export function resolveUpstreamWorkflowContract(repoRoot = REPO_ROOT): string {
-  if (existsSync(LOCAL_ASSET_PATH)) return LOCAL_ASSET_PATH;
-  return join(resolveAgenticDevRoot(repoRoot), "assets", "workflow-contract.v1.json");
-}
-
-export function loadWorkflowContract(
-  contractPath = resolveUpstreamWorkflowContract()
-): WorkflowContract {
-  return JSON.parse(readFileSync(contractPath, "utf-8")) as WorkflowContract;
-}
-
-export function resolveInstalledWorkflowContract(repoRoot: string): string {
-  return join(repoRoot, ".ai", "harness", "workflow-contract.json");
-}
-
-export function resolveWorkflowContractForRepo(repoRoot: string): string {
-  const installedPath = resolveInstalledWorkflowContract(repoRoot);
-  return existsSync(installedPath) ? installedPath : resolveUpstreamWorkflowContract(repoRoot);
-}
-
-export function getHelperScripts(contract: WorkflowContract): string[] {
-  return [...contract.helpers.scripts];
-}
-
-export function getHelperRuntimeDir(contract: WorkflowContract): string {
-  return contract.helpers.runtimeDirectory ?? contract.helpers.compatibilityDirectory ?? "scripts";
-}
-
-export function getRequiredDirectories(contract: WorkflowContract): string[] {
-  return [...contract.artifacts.requiredDirectories];
-}
-
-export function getRequiredFiles(contract: WorkflowContract): string[] {
-  return [...contract.artifacts.requiredFiles];
-}
-
-if (import.meta.main) {
-  const contract = loadWorkflowContract(process.argv[2] || resolveUpstreamWorkflowContract());
-  console.log(JSON.stringify(contract, null, 2));
-}
+if (import.meta.main) runTrackedForgeHelper("workflow-contract.ts");

package/scripts/workstream-sync.sh

@@ -1,263 +1,4 @@
 #!/bin/bash
 set -euo pipefail
-
-# Contract invariant: durable capability ledgers live under tasks/workstreams.
-
-usage() {
-  cat <<'USAGE_EOF'
-Usage:
-  scripts/workstream-sync.sh ensure --block <capability-prefix> [--slug <slug>] [--title <title>] [--plan <plan-file>] [--slice <todo-id>] [--request <architecture-request>]
-USAGE_EOF
-}
-
-repo="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
-repo="$(cd "$repo" && pwd)"
-cd "$repo"
-
-command_name="${1:-ensure}"
-shift || true
-
-functional_block=""
-slug=""
-title=""
-source_plan="(none)"
-current_slice="todo-01"
-request_file="(none)"
-
-json_escape() {
-  local value="$1"
-  value="${value//\\/\\\\}"
-  value="${value//\"/\\\"}"
-  value="${value//$'\n'/\\n}"
-  value="${value//$'\r'/\\r}"
-  value="${value//$'\t'/\\t}"
-  printf '%s' "$value"
-}
-
-json_get() {
-  local json_input="$1"
-  local key="$2"
-  local parsed=""
-
-  if [[ -z "$json_input" ]]; then
-    return 1
-  fi
-
-  if command -v jq >/dev/null 2>&1; then
-    parsed="$(printf '%s' "$json_input" | jq -r ".$key // empty" 2>/dev/null || true)"
-  fi
-
-  if [[ -z "$parsed" ]] && command -v node >/dev/null 2>&1; then
-    parsed="$(JSON_INPUT="$json_input" JSON_KEY="$key" node -e '
-const raw = process.env.JSON_INPUT || "";
-const key = process.env.JSON_KEY || "";
-try {
-  const value = JSON.parse(raw)[key];
-  if (value === undefined || value === null) process.exit(1);
-  process.stdout.write(String(value));
-} catch {
-  process.exit(1);
-}
-' 2>/dev/null || true)"
-  fi
-
-  [[ -n "$parsed" ]] || return 1
-  printf '%s' "$parsed"
-}
-
-safe_token() {
-  local value="$1"
-  value="$(printf '%s' "$value" | tr '[:upper:]' '[:lower:]')"
-  value="$(printf '%s' "$value" | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-{2,}/-/g')"
-  printf '%s' "${value:-workstream}"
-}
-
-validate_block() {
-  local block="$1"
-  case "$block" in
-    ""|.|..|../*|*/../*|/*|*$'\n'*|*$'\r'*)
-      return 1
-      ;;
-  esac
-  [[ -e "$block" ]]
-}
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --block)
-      [[ -n "${2:-}" ]] || { echo "workstream-sync: --block requires a value" >&2; exit 2; }
-      functional_block="${2#./}"
-      functional_block="${functional_block%/}"
-      shift 2
-      ;;
-    --slug)
-      [[ -n "${2:-}" ]] || { echo "workstream-sync: --slug requires a value" >&2; exit 2; }
-      slug="$(safe_token "$2")"
-      shift 2
-      ;;
-    --title)
-      [[ -n "${2:-}" ]] || { echo "workstream-sync: --title requires a value" >&2; exit 2; }
-      title="$2"
-      shift 2
-      ;;
-    --plan)
-      [[ -n "${2:-}" ]] || { echo "workstream-sync: --plan requires a value" >&2; exit 2; }
-      source_plan="$2"
-      shift 2
-      ;;
-    --slice)
-      [[ -n "${2:-}" ]] || { echo "workstream-sync: --slice requires a value" >&2; exit 2; }
-      current_slice="$2"
-      shift 2
-      ;;
-    --request)
-      [[ -n "${2:-}" ]] || { echo "workstream-sync: --request requires a value" >&2; exit 2; }
-      request_file="$2"
-      shift 2
-      ;;
-    --help|-h)
-      usage
-      exit 0
-      ;;
-    *)
-      echo "workstream-sync: unknown argument: $1" >&2
-      usage
-      exit 2
-      ;;
-  esac
-done
-
-if [[ "$command_name" != "ensure" ]]; then
-  echo "workstream-sync: unknown command: $command_name" >&2
-  usage
-  exit 2
-fi
-
-if ! validate_block "$functional_block"; then
-  echo "workstream-sync: --block must be an existing repo-relative capability prefix" >&2
-  exit 2
-fi
-
-if [[ ! -f "scripts/capability-resolver.ts" ]] || ! command -v bun >/dev/null 2>&1; then
-  echo "workstream-sync: scripts/capability-resolver.ts and bun are required" >&2
-  exit 2
-fi
-
-if ! resolver_json="$(bun scripts/capability-resolver.ts match --path "$functional_block" --format json 2>&1)"; then
-  echo "$resolver_json" >&2
-  exit 1
-fi
-
-if [[ "$(json_get "$resolver_json" "matched" || true)" != "true" ]]; then
-  echo "workstream-sync: --block must match a declared capability prefix in .ai/context/capabilities.json" >&2
-  exit 2
-fi
-
-capability_id="$(json_get "$resolver_json" "capability_id")"
-matched_prefix="$(json_get "$resolver_json" "matched_prefix")"
-architecture_domain="$(json_get "$resolver_json" "architecture_domain")"
-architecture_capability="$(json_get "$resolver_json" "architecture_capability")"
-architecture_module="$(json_get "$resolver_json" "architecture_module")"
-workstream_dir="$(json_get "$resolver_json" "workstream_dir")"
-contract_agents="$(json_get "$resolver_json" "contract_agents" || true)"
-contract_claude="$(json_get "$resolver_json" "contract_claude" || true)"
-
-if [[ -z "$slug" ]]; then
-  if [[ -n "$title" ]]; then
-    slug="$(safe_token "$title")"
-  else
-    slug="$(date '+%Y%m%d')-${architecture_capability}"
-  fi
-fi
-title="${title:-$slug}"
-workstream_file="${workstream_dir}/${slug}.md"
-event_file=".ai/harness/events.jsonl"
-iso_timestamp="$(date '+%Y-%m-%dT%H:%M:%S%z')"
-architecture_domain_file="docs/architecture/domains/${architecture_domain}.md"
-
-mkdir -p "$workstream_dir" "$(dirname "$architecture_module")" "$(dirname "$architecture_domain_file")" ".ai/harness"
-
-if [[ ! -f "$architecture_domain_file" ]]; then
-  cat > "$architecture_domain_file" <<EOF_DOMAIN
-# Architecture Domain: ${architecture_domain}
-
-> **Source**: \`.ai/context/capabilities.json\`
-
-## Capabilities
-
-- \`${capability_id}\` -> \`${architecture_module}\`
-EOF_DOMAIN
-elif ! grep -Fq "$architecture_module" "$architecture_domain_file"; then
-  {
-    echo ""
-    echo "- \`${capability_id}\` -> \`${architecture_module}\`"
-  } >> "$architecture_domain_file"
-fi
-
-if [[ ! -f "$architecture_module" ]]; then
-  cat > "$architecture_module" <<EOF_MODULE
-# Architecture Module: ${architecture_domain}/${architecture_capability}
-
-> **Capability ID**: \`${capability_id}\`
-> **Functional Block**: \`${functional_block}\`
-> **Matched Prefix**: \`${matched_prefix}\`
-> **Domain**: \`${architecture_domain}\`
-> **Capability**: \`${architecture_capability}\`
-
-## Boundary
-
-- Responsibility: Keep the capability boundary, entrypoints, runtime path, dependency rules, and local verification pointers for \`${capability_id}\`.
-- Entrypoints: \`${matched_prefix}\`
-- Runtime path: \`${matched_prefix}\`
-- Local contracts: \`${contract_agents:-none}\`, \`${contract_claude:-none}\`
-
-## Active Workstreams
-
-- \`${workstream_file}\`
-EOF_MODULE
-elif ! grep -Fq "$workstream_file" "$architecture_module"; then
-  {
-    echo ""
-    echo "- \`${workstream_file}\`"
-  } >> "$architecture_module"
-fi
-
-if [[ ! -f "$workstream_file" ]]; then
-  cat > "$workstream_file" <<EOF_WORKSTREAM
-# Workstream: ${title}
-
-> **Status**: active
-> **Capability ID**: \`${capability_id}\`
-> **Functional Block**: \`${functional_block}\`
-> **Matched Prefix**: \`${matched_prefix}\`
-> **Architecture Domain**: \`${architecture_domain}\`
-> **Architecture Capability**: \`${architecture_capability}\`
-> **Architecture Module**: \`${architecture_module}\`
-> **Source Plan**: ${source_plan}
-> **Current Slice**: ${current_slice}
-> **Last Handoff**: \`.ai/harness/session/continuation.md\`
-> **Architecture Request**: ${request_file}
-
-## Purpose
-
-Track durable multi-session progress for \`${capability_id}\` without inflating local agent instructions.
-
-## TODOs
-
-- [ ] ${current_slice}: Complete the current executable slice for \`${capability_id}\`.
-
-## Notes
-
-- Project the current slice into \`tasks/todos.md\` for a single session.
-- Keep architecture facts in \`${architecture_module}\`; keep execution progress here.
-EOF_WORKSTREAM
-fi
-
-event_json="{\"ts\":\"$(json_escape "$iso_timestamp")\",\"file_path\":\"$(json_escape "$workstream_file")\",\"severity\":\"medium\",\"functional_block\":\"$(json_escape "$functional_block")\",\"capability_id\":\"$(json_escape "$capability_id")\",\"matched_prefix\":\"$(json_escape "$matched_prefix")\",\"architecture_domain\":\"$(json_escape "$architecture_domain")\",\"architecture_capability\":\"$(json_escape "$architecture_capability")\",\"architecture_module\":\"$(json_escape "$architecture_module")\",\"workstream_dir\":\"$(json_escape "$workstream_dir")\",\"contract_agents\":\"$(json_escape "$contract_agents")\",\"contract_claude\":\"$(json_escape "$contract_claude")\",\"active_workstream\":\"$(json_escape "$workstream_file")\",\"change_type\":\"workstream-sync\",\"spawn_recommended\":false,\"contract_sync_required\":true,\"request_file\":\"$(json_escape "$request_file")\"}"
-printf '%s\n' "$event_json" >> "$event_file"
-
-if [[ -x "scripts/context-contract-sync.sh" ]]; then
-  bash "scripts/context-contract-sync.sh" sync-event --json "$event_json"
-fi
-
-echo "[WorkstreamSync] Ensured $workstream_file for $capability_id."
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec "$SCRIPT_DIR/lib/run-forge-helper.sh" "workstream-sync.sh" "$@"

package/src/cli/agent-jobs/executor-health.ts

@@ -1,4 +1,4 @@
-import type { GitHubStatus } from "../github/github";
+import type { GitHubStatus } from "../github/contracts";
 import type { McpAgentRunnerName } from "../mcp/types";
 import type { ControllerAgent, ControllerTask } from "../controller/types";
 

package/src/cli/commands/plugin.ts

@@ -63,13 +63,17 @@ export function installerNextSteps(result:Record<string,unknown>):string[]{
     .filter(Boolean)
     .slice(0,10);
 }
-export function registrationFrom(result:Record<string,unknown>,entry:RegistryEntry):ExternalPluginRegistrationInput{
+export function registrationFrom(
+  result:Record<string,unknown>,
+  entry:RegistryEntry,
+  options: { packageIdentityVerified?: boolean } = {},
+):ExternalPluginRegistrationInput{
   if(result.registration){const input=result.registration as ExternalPluginRegistrationInput;if(input.pluginId!==entry.id)throw new Error('PLUGIN_INSTALLER_ID_MISMATCH');if(input.pluginVersion!==entry.version)throw new Error('PLUGIN_INSTALLER_VERSION_MISMATCH');return input;}
   const facts=result.providerInstall as Record<string,unknown>|undefined;
   if(!facts||facts.kind!=='desktop_operator'||entry.id!=='desktop_operator')throw new Error('PLUGIN_INSTALLER_REGISTRATION_MISSING');
   const expectedProviderVersion=entry.providerVersion??entry.version;
   const expectedProtocolVersion=entry.protocolVersion??'1.0';
-  if(facts.pluginVersion!==expectedProviderVersion)throw new Error(`PLUGIN_INSTALLER_PROVIDER_VERSION_MISMATCH: expected ${expectedProviderVersion} for ${entry.id}@${entry.version}, actual ${String(facts.pluginVersion??'missing')}`);
+  if(facts.pluginVersion!==expectedProviderVersion&&!options.packageIdentityVerified)throw new Error(`PLUGIN_INSTALLER_PROVIDER_VERSION_MISMATCH: expected ${expectedProviderVersion} for ${entry.id}@${entry.version}, actual ${String(facts.pluginVersion??'missing')}`);
   if(facts.protocolVersion!==expectedProtocolVersion)throw new Error(`PLUGIN_INSTALLER_PROTOCOL_VERSION_MISMATCH: expected ${expectedProtocolVersion} for ${entry.id}@${entry.version}, actual ${String(facts.protocolVersion??'missing')}`);
   const socketPath=typeof facts.socketPath==='string'?facts.socketPath:'';const launchAgentLabel=typeof facts.launchAgentLabel==='string'?facts.launchAgentLabel:'';const expectedProgramContains=typeof facts.expectedProgramContains==='string'?facts.expectedProgramContains:'';
   if(!isAbsolute(socketPath)||!launchAgentLabel||!expectedProgramContains)throw new Error('PLUGIN_INSTALLER_PROVIDER_FACTS_INVALID');
@@ -86,7 +90,12 @@ function install(entry:RegistryEntry,controllerHome:string):Record<string,unknow
     const manifest=JSON.parse(readFileSync(manifestPath,'utf8')) as Record<string,unknown>;if(manifest.id!==entry.id||manifest.version!==entry.version)throw new Error(`PLUGIN_PACKAGE_IDENTITY_MISMATCH: ${entry.id}`);
     if(existsSync(finalRoot)){renameSync(finalRoot,backup);backed=true;}renameSync(stage,finalRoot);
     const result=installerJson(run(process.execPath,[within(finalRoot,entry.installer)],finalRoot,180000));
-    const installed=installExternalPluginRegistration(controllerHome,registrationFrom(result,entry));
+    // The staged package manifest is checked against the catalog before the
+    // installer runs. Provider identity is then probed through the installed
+    // socket during registry sync. The installer's providerInstall version is
+    // useful diagnostics, but must not strand a verified package when that
+    // helper field is stale.
+    const installed=installExternalPluginRegistration(controllerHome,registrationFrom(result,entry,{packageIdentityVerified:true}));
     const repository=controllerPluginRepository(controllerHome);syncAssistantPluginRegistry(controllerHome,repository);const plugin=getAssistantPluginManifest(controllerHome,repository,entry.id);
     if(backed)rmSync(backup,{recursive:true,force:true});
     return{pluginId:entry.id,version:entry.version,packageRoot:finalRoot,registrationRevision:installed.revision,enabled:plugin.enabled,health:plugin.health,nextSteps:installerNextSteps(result)};

package/src/cli/controller/check-runner.ts

@@ -773,6 +773,8 @@ export function runControllerCheck(repoRoot: string, id: string, requestedTimeou
 
 export interface AsyncControllerCheckOptions {
   snapshot?: ControllerCheckSnapshot;
+  /** Explicit isolated authority for Candidate verification child processes. */
+  isolatedControllerHome?: string;
   requestedTimeoutMs?: number;
   onSpawn?: (pid: number) => void;
   subscriberId?: string;
@@ -912,12 +914,15 @@ async function executeControllerCheckAsync(
   check: ControllerCheck,
   timeoutMs: number,
   onSpawn?: (pid: number) => void,
+  isolatedControllerHome?: string,
 ): Promise<ControllerCheckResult> {
   const maxOutputBytes = 256 * 1024;
   const command = [check.command[0], ...check.command.slice(1)];
+  const childEnvironment = repositoryChildProcessEnvironment();
+  if (isolatedControllerHome?.trim()) childEnvironment.FORGE_CONTROLLER_HOME = resolve(isolatedControllerHome);
   const supervised = await runBoundedChild(check.command[0], check.command.slice(1), {
     cwd: resolve(repoRoot, check.cwd),
-    env: repositoryChildProcessEnvironment(),
+    env: childEnvironment,
     timeoutMs,
     maxOutputBytes,
     stdio: 'capture',
@@ -1050,7 +1055,7 @@ export function runControllerCheckAsync(
     const result = await executeControllerCheckAsync(repoRoot, check, timeoutMs, (pid) => {
       lease?.setChildPid(pid);
       notifySpawn(pid);
-    });
+    }, options.isolatedControllerHome);
     const completedRevision = currentControllerCheckRevision(repoRoot);
     const stale = completedRevision !== revision;
     const finalized = {

package/src/cli/controller/context-pack.ts

@@ -254,11 +254,17 @@ export function buildControllerContextPack(
         ? [...metadata.changedFiles.added, ...metadata.changedFiles.modified]
         : [];
       overlayChangedFiles = Array.from(new Set([...overlayChangedFiles, ...providerChangedFiles]));
+      const structuralEvidenceCurrent = structural.status === "ready"
+        && baselineRevisionMatches
+        && overlayChangedFiles.length === 0;
+      const structuralStatus = structural.status === "ready" && !structuralEvidenceCurrent
+        ? "stale"
+        : structural.status;
       structuralContext = {
         provider: "codegraph",
         requestedMode: structuralMode,
-        status: indexSource === "repository_baseline" && (!baselineRevisionMatches || overlayChangedFiles.length > 0) && structural.status === "ready" ? "stale" : structural.status,
-        requiredSatisfied: structuralMode !== "required" || (structural.status === "ready" && baselineRevisionMatches && overlayChangedFiles.length === 0),
+        status: structuralStatus,
+        requiredSatisfied: structuralMode !== "required" || structuralEvidenceCurrent,
         indexSource,
         overlayChangedFiles,
         baselineRevisionMatches,
@@ -285,24 +291,28 @@ export function buildControllerContextPack(
       const addStructuralPath = (path: string, reason: string, line?: number): void => {
         if (!path || !coveredByGlob(path, searchIncludeGlobs) || excludeGlobs.some((glob) => globMatches(glob, path))) return;
         const readable = readableFile(repoRoot, policy, path);
-        if (!readable.ok) {
+        if (readable.ok === false) {
           deniedPaths.push({ path: readable.path, reason: readable.reason });
           return;
         }
         addReason(candidates, readable.path, reason, line);
       };
-      for (const node of graph.nodes.slice(0, maxFiles * 6)) {
-        addStructuralPath(node.filePath, `codegraph:context:${node.kind}:${node.name}`, node.startLine);
-      }
-      for (const node of graph.entryPoints) {
-        addStructuralPath(node.filePath, `codegraph:entry:${node.name}`, node.startLine);
-      }
-      for (const path of graph.relatedFiles.slice(0, maxFiles * 6)) addStructuralPath(path, "codegraph:related");
-      // Context search identifies the structural entry points. For a bounded
-      // number of those files, enrich the same Context Plane call with direct
-      // file dependencies/dependents. This is impact evidence, not a second
-      // routing/tool surface, and remains completely off for ordinary Direct.
-      if (structural.status === "ready") {
+      // Structural relationships may only influence discovery/materialization
+      // when the graph is current for this exact source identity. Stale graph
+      // nodes remain visible through structuralContext/impactContext hints, but
+      // must never steer which raw source GPT sees first.
+      if (structuralEvidenceCurrent) {
+        for (const node of graph.nodes.slice(0, maxFiles * 6)) {
+          addStructuralPath(node.filePath, `codegraph:context:${node.kind}:${node.name}`, node.startLine);
+        }
+        for (const node of graph.entryPoints) {
+          addStructuralPath(node.filePath, `codegraph:entry:${node.name}`, node.startLine);
+        }
+        for (const path of graph.relatedFiles.slice(0, maxFiles * 6)) addStructuralPath(path, "codegraph:related");
+        // Context search identifies the structural entry points. For a bounded
+        // number of those files, enrich the same Context Plane call with direct
+        // file dependencies/dependents. This is impact evidence, not a second
+        // routing/tool surface, and remains completely off for ordinary Direct.
         const primaryFiles = Array.from(new Set(graph.entryPoints.map((node) => node.filePath).filter(Boolean))).slice(0, 4);
         for (const filePath of primaryFiles) {
           const adjacency = queryStructural(structuralIndexRoot, { operation: "file_dependencies", filePath, limit: 40 });
@@ -323,10 +333,13 @@ export function buildControllerContextPack(
           }
         }
       }
-      for (const path of metadata?.changedFiles.added ?? []) addStructuralPath(path, "codegraph:changed-file", 1);
-      for (const path of metadata?.changedFiles.modified ?? []) addStructuralPath(path, "codegraph:changed-file", 1);
       for (const path of metadata?.changedFiles.removed ?? []) omitted.push({ path, reason: "codegraph reports file removed since index" });
-      for (const path of overlayChangedFiles) addStructuralPath(path, "worktree:changed-file", 1);
+      // A repository-baseline graph deliberately runs against another checkout.
+      // Current worktree changes are still authoritative raw-source evidence,
+      // but they come from Git rather than stale CodeGraph metadata.
+      if (indexSource === "repository_baseline") {
+        for (const path of gitStatusChangedPaths(git.status)) addStructuralPath(path, "worktree:changed-file", 1);
+      }
     }
   }
 
@@ -430,7 +443,15 @@ export function buildControllerContextPack(
       return left.path.localeCompare(right.path);
     });
   const isExactKnownCandidate = (entry: { reasons: string[] }): boolean => entry.reasons.includes("explicit-known-path");
-  const multiWaveEligible = retrievalMode !== "implementation";
+  // Adaptive closure is enabled whenever the caller asks for investigation/review
+  // evidence or leaves structural discovery enabled. A deliberately narrow
+  // implementation read with structural discovery disabled stays single-wave.
+  // This keeps the common exact-file edit path cheap without making the default
+  // implementation mode a permanent evidence-closure blind spot.
+  const multiWaveEligible = retrievalMode !== "implementation"
+    || structuralMode !== "off"
+    || impactDomains.length > 0
+    || explicitKnownPaths.length > 1;
   timingsMs.expansionBudgetMax = multiWaveEligible ? Math.min(6, Math.max(2, Math.ceil(maxFiles / 2))) : 0;
   const rankedExactKnownCount = rankedCandidates.filter(isExactKnownCandidate).length;
   const initialCandidateLimit = multiWaveEligible
@@ -511,7 +532,7 @@ export function buildControllerContextPack(
     }
   }
 
-  // Investigation modes perform bounded internal evidence-closure waves after
+  // Evidence-closure eligible requests perform bounded internal waves after
   // Wave 1 raw source materialization. Each later wave derives concrete paths
   // from the source that was just read plus current CodeGraph adjacency, then
   // materializes those paths in the same context request.
@@ -794,6 +815,7 @@ export function buildControllerContextPack(
     ...expansionSignals,
     ...(likelyRelatedNotInspected.length > 0 ? ["likely_related_files_not_inspected"] : []),
   ])).slice(0, 80);
+  const materialRelationshipUnresolved = unresolvedExpansionPaths.length > 0;
   const readinessReasonCodes = Array.from(new Set([
     ...(files.length === 0 ? ["raw_source_unavailable"] : []),
     ...(rawSnippetTruncated ? ["raw_source_truncated"] : []),
@@ -804,9 +826,12 @@ export function buildControllerContextPack(
     ...(policyDeniedFiles > 0 || deniedPaths.length > 0 ? ["policy_denied_evidence"] : []),
     ...(skippedLargeFiles > 0 ? ["large_evidence_skipped"] : []),
     ...(expansionBudgetExhausted ? ["expansion_budget_exhausted"] : []),
+    ...(materialRelationshipUnresolved ? ["material_relationship_unresolved"] : []),
     ...(likelyRelatedNotInspected.length > 0 ? ["related_evidence_not_materialized"] : []),
   ])).slice(0, 40);
-  const readinessStatus = files.length === 0 || (structuralMode === "required" && !structuralContext.requiredSatisfied)
+  const readinessStatus = files.length === 0
+    || (structuralMode === "required" && !structuralContext.requiredSatisfied)
+    || materialRelationshipUnresolved
     ? "insufficient" as const
     : readinessReasonCodes.length > 0
       ? "degraded" as const