@moretea-labs/forge 1.6.0 → 1.7.0

package/scripts/benchmark-typescript-navigation.ts

@@ -0,0 +1,186 @@
+#!/usr/bin/env bun
+
+import { execFileSync } from 'child_process';
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+import { performance } from 'perf_hooks';
+import {
+  clearTypeScriptNavigationCache,
+  navigateTypeScriptSymbol,
+  type TypeScriptNavigationKind,
+} from '../src/runtime/context/typescript-navigation';
+
+interface BenchmarkCase {
+  label: string;
+  path: string;
+  symbol: string;
+  marker: string;
+}
+
+const repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim();
+const cases: BenchmarkCase[] = [
+  {
+    label: 'repository command execution',
+    path: 'src/cli/repositories/command-executor.ts',
+    symbol: 'executeRepositoryCommand',
+    marker: 'export function executeRepositoryCommand(',
+  },
+  {
+    label: 'MCP repository dispatch',
+    path: 'src/cli/mcp/repository-tools.ts',
+    symbol: 'callRepositoryTool',
+    marker: 'export async function callRepositoryTool(',
+  },
+  {
+    label: 'canonical Runtime proxy',
+    path: 'src/cli/mcp/server.ts',
+    symbol: 'createCanonicalRuntimeProxy',
+    marker: 'export function createCanonicalRuntimeProxy(',
+  },
+  {
+    label: 'Runtime MCP dispatch',
+    path: 'src/runtime/gateway/mcp/runtime-tools.ts',
+    symbol: 'callRuntimeTool',
+    marker: 'export async function callRuntimeTool(',
+  },
+  {
+    label: 'Lightweight command execution',
+    path: 'src/runtime/execution/process-runtime/lightweight-managed.ts',
+    symbol: 'startLightweightRepositoryCommand',
+    marker: 'export async function startLightweightRepositoryCommand(',
+  },
+];
+const requestedSymbols = new Set(
+  String(process.env.FORGE_TSNAV_BENCHMARK_SYMBOLS ?? '')
+    .split(',')
+    .map((value) => value.trim())
+    .filter(Boolean),
+);
+const benchmarkCases = requestedSymbols.size === 0
+  ? cases
+  : cases.filter((case_) => requestedSymbols.has(case_.symbol));
+if (benchmarkCases.length === 0) {
+  throw new Error(`No benchmark cases match FORGE_TSNAV_BENCHMARK_SYMBOLS=${[...requestedSymbols].join(',')}`);
+}
+
+function target(case_: BenchmarkCase): { line: number; column: number } {
+  const text = readFileSync(resolve(repoRoot, case_.path), 'utf8');
+  const markerOffset = text.indexOf(case_.marker);
+  if (markerOffset < 0) throw new Error(`marker not found for ${case_.label}: ${case_.marker}`);
+  const symbolOffset = markerOffset + case_.marker.indexOf(case_.symbol);
+  const before = text.slice(0, symbolOffset);
+  const lines = before.split('\n');
+  return { line: lines.length, column: (lines.at(-1)?.length ?? 0) + 1 };
+}
+
+function navigate(case_: BenchmarkCase, navigation: TypeScriptNavigationKind) {
+  const point = target(case_);
+  return navigateTypeScriptSymbol(repoRoot, { navigation, path: case_.path, ...point });
+}
+
+function lexicalMatches(symbol: string): string[] {
+  try {
+    const output = execFileSync('git', ['grep', '-n', '-w', symbol, '--', 'src', 'scripts', 'tests'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      maxBuffer: 8 * 1024 * 1024,
+    }).trim();
+    return output ? output.split('\n') : [];
+  } catch {
+    return [];
+  }
+}
+
+function percentile(values: number[], ratio: number): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((left, right) => left - right);
+  const index = Math.min(sorted.length - 1, Math.floor(sorted.length * ratio));
+  return Math.round((sorted[index] ?? 0) * 100) / 100;
+}
+
+const results = [];
+for (const case_ of benchmarkCases) {
+  clearTypeScriptNavigationCache();
+  // This first reference call represents the user-visible cold path.
+  const coldReferenceStartedAt = performance.now();
+  const coldReferences = navigate(case_, 'references');
+  const coldReferenceMs = performance.now() - coldReferenceStartedAt;
+
+  // Then separately initialize a fresh project through the cheap definition
+  // query and measure references on that already-built Language Service. This
+  // makes project construction and high-fanout reference cost visible instead
+  // of attributing both to one opaque cold number.
+  clearTypeScriptNavigationCache();
+  const projectSetupStartedAt = performance.now();
+  const coldDefinition = navigate(case_, 'definition');
+  const projectSetupMs = performance.now() - projectSetupStartedAt;
+  const firstReferenceStartedAt = performance.now();
+  const firstReferencesOnPreparedProject = navigate(case_, 'references');
+  const firstReferenceOnPreparedProjectMs = performance.now() - firstReferenceStartedAt;
+
+  const warmDurations: number[] = [];
+  let warmReferences = firstReferencesOnPreparedProject;
+  for (let index = 0; index < 3; index += 1) {
+    const startedAt = performance.now();
+    warmReferences = navigate(case_, 'references');
+    warmDurations.push(performance.now() - startedAt);
+  }
+  const definitions = navigate(case_, 'definition');
+  const implementations = navigate(case_, 'implementations');
+  const lexical = lexicalMatches(case_.symbol);
+
+  results.push({
+    label: case_.label,
+    symbol: case_.symbol,
+    target: { path: case_.path, ...target(case_) },
+    semantic: {
+      coldReferenceLocations: coldReferences.locations.length,
+      coldDefinitionLocations: coldDefinition.locations.length,
+      references: warmReferences.locations.length,
+      definitions: definitions.locations.length,
+      implementations: implementations.locations.length,
+      crossFileReferences: warmReferences.locations.filter((location) => location.path !== case_.path).length,
+      sampleReferences: warmReferences.locations.slice(0, 8),
+    },
+    lexical: {
+      exactMatches: lexical.length,
+      sampleMatches: lexical.slice(0, 8),
+    },
+    latencyMs: {
+      coldReferences: Math.round(coldReferenceMs * 100) / 100,
+      projectSetupViaDefinition: Math.round(projectSetupMs * 100) / 100,
+      firstReferencesOnPreparedProject: Math.round(firstReferenceOnPreparedProjectMs * 100) / 100,
+      warmReferences: warmDurations.map((value) => Math.round(value * 100) / 100),
+    },
+  });
+}
+clearTypeScriptNavigationCache();
+
+const preparedReferenceDurations = results.map((entry) => entry.latencyMs.firstReferencesOnPreparedProject);
+const warmReferenceDurations = results.flatMap((entry) => entry.latencyMs.warmReferences);
+const thresholds = {
+  firstReferencesOnPreparedProjectP95MaxMs: 250,
+  warmReferencesP95MaxMs: 150,
+};
+const assertions = {
+  allDefinitionsResolved: results.every((entry) => entry.semantic.definitions >= 1),
+  allReferencesResolved: results.every((entry) => entry.semantic.references >= 1),
+  allImplementationsResolved: results.every((entry) => entry.semantic.implementations >= 1),
+  crossFileSemanticReferencesResolved: results.every((entry) => entry.semantic.crossFileReferences >= 1),
+  preparedReferenceLatencyBounded: percentile(preparedReferenceDurations, 0.95) <= thresholds.firstReferencesOnPreparedProjectP95MaxMs,
+  warmReferenceLatencyBounded: percentile(warmReferenceDurations, 0.95) <= thresholds.warmReferencesP95MaxMs,
+};
+const output = {
+  repoRoot,
+  requestedSymbols: [...requestedSymbols],
+  cases: results,
+  summary: {
+    firstReferencesOnPreparedProjectP95Ms: percentile(preparedReferenceDurations, 0.95),
+    warmReferencesP95Ms: percentile(warmReferenceDurations, 0.95),
+  },
+  thresholds,
+  assertions,
+  passed: Object.values(assertions).every(Boolean),
+};
+console.log(JSON.stringify(output, null, 2));
+if (!output.passed) process.exitCode = 1;

package/scripts/benchmark-work-efficiency.ts

@@ -0,0 +1,334 @@
+#!/usr/bin/env bun
+
+/**
+ * Forge Work efficiency benchmark.
+ *
+ * Measures end-to-end controller ceremony for a tiny, real repository change
+ * against isolated temporary repository/controller state. It compares the
+ * streamlined path (verify -> finalize) with the legacy-style ceremony
+ * (verify -> continue -> finalize) without mutating the Forge checkout.
+ */
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { spawnSync } from 'child_process';
+import { createMcpToolContext } from '../src/cli/mcp/server';
+import type { MultiRepositoryMcpToolContext } from '../src/cli/mcp/multi-repository';
+import { ensureControllerHome } from '../src/cli/repositories/controller-home';
+import { registerRepository } from '../src/cli/repositories/registry';
+import { callRuntimeTool } from '../src/runtime/gateway/mcp/runtime-tools';
+import { getWorkContract } from '../src/runtime/control-plane/facade/work-contract-store';
+import { waitForProcess } from '../src/runtime/execution/process-runtime';
+import { acquireRuntimeOwnership } from '../src/runtime/root/ownership';
+import { forgeRuntimeServicePaths } from '../src/runtime/root/service';
+import { writeRuntimeStatusSnapshot } from '../src/runtime/root/status';
+import { ensureActiveRuntimeRelease } from '../src/runtime/root/release-store';
+import { bindRuntimeWriteClaim, clearRuntimeWriteClaimForTests } from '../src/runtime/root/write-fence';
+
+interface TimedCall {
+  elapsedMs: number;
+  value: Record<string, any>;
+}
+
+interface FlowSample {
+  mode: 'streamlined' | 'legacy_ceremony';
+  sample: number;
+  ok: boolean;
+  controllerCalls: number;
+  processWaits: number;
+  startMs: number;
+  verifySubmitMs: number;
+  verifyWaitMs: number;
+  verifyReattachMs: number;
+  continueMs: number;
+  finalizeMs: number;
+  totalMs: number;
+  verificationNextStep?: string;
+  finalStatus?: string;
+  cleanupComplete: boolean;
+}
+
+function argNumber(name: string, fallback: number): number {
+  const index = process.argv.indexOf(name);
+  if (index < 0) return fallback;
+  const parsed = Number(process.argv[index + 1]);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+
+function git(root: string, args: string[]): string {
+  const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+  if (result.status !== 0) throw new Error(String(result.stderr || `git ${args.join(' ')} failed`));
+  return String(result.stdout ?? '').trim();
+}
+
+function runtimeManifest(controllerHome: string): string {
+  const path = join(controllerHome, 'benchmark-runtime.manifest.json');
+  writeFileSync(path, JSON.stringify({
+    schemaVersion: 1,
+    releaseId: 'release-work-efficiency-benchmark',
+    artifactIdentity: 'artifact-work-efficiency-benchmark',
+    entrypoint: 'forge-runtime',
+    arguments: [],
+    configurationSchemaVersion: 1,
+    controllerHome,
+    databaseSchemaCompatibility: { minimum: 1, maximum: 1 },
+    workerProtocolVersion: 1,
+    createdAt: new Date().toISOString(),
+  }));
+  return path;
+}
+
+function createFixture(label: string) {
+  const root = mkdtempSync(join(tmpdir(), `forge-work-efficiency-${label}-`));
+  const controllerHome = join(root, 'controller');
+  const repoRoot = join(root, 'repo');
+  ensureControllerHome(controllerHome);
+  mkdirSync(repoRoot, { recursive: true });
+  git(repoRoot, ['init', '-b', 'main']);
+  git(repoRoot, ['config', 'user.name', 'Work Efficiency Benchmark']);
+  git(repoRoot, ['config', 'user.email', 'benchmark@example.test']);
+  writeFileSync(join(repoRoot, 'README.md'), 'fixture\n');
+  writeFileSync(join(repoRoot, 'package.json'), JSON.stringify({
+    name: `work-efficiency-${label}`,
+    private: true,
+    scripts: { 'check:bench': 'node -e "process.exit(0)"' },
+  }, null, 2));
+  git(repoRoot, ['add', '.']);
+  git(repoRoot, ['commit', '-m', 'fixture']);
+
+  const repository = registerRepository({ path: repoRoot, controllerHome, displayName: `work-efficiency-${label}` });
+  const owner = acquireRuntimeOwnership(controllerHome, `runtime-work-efficiency-${label}`);
+  const authority = ensureActiveRuntimeRelease(controllerHome, runtimeManifest(controllerHome));
+  bindRuntimeWriteClaim({ controllerHome, owner: owner.record, authority });
+
+  const runtimeService = forgeRuntimeServicePaths(controllerHome);
+  mkdirSync(runtimeService.serviceRoot, { recursive: true });
+  mkdirSync(join(controllerHome, 'mcp'), { recursive: true });
+  const runtimeTokenPath = join(controllerHome, 'mcp', 'runtime-token');
+  writeFileSync(runtimeTokenPath, `fixture-token-${label}\n`, { mode: 0o600 });
+  writeFileSync(runtimeService.configPath, JSON.stringify({
+    schemaVersion: 1,
+    controllerHome,
+    repositoryRoot: repoRoot,
+    host: '127.0.0.1',
+    port: 9876,
+    authTokenFile: runtimeTokenPath,
+  }));
+  const observedAt = new Date().toISOString();
+  writeRuntimeStatusSnapshot(controllerHome, {
+    schemaVersion: 1,
+    runtimeInstanceId: owner.record.runtimeInstanceId,
+    pid: owner.record.pid,
+    releaseId: authority.active.releaseId,
+    artifactIdentity: authority.active.artifactIdentity,
+    endpoint: 'http://127.0.0.1:9876/mcp',
+    readiness: {
+      ready: true,
+      reasonCodes: [],
+      diagnostics: {
+        database: { outcome: 'pass' },
+        scheduler: { outcome: 'pass' },
+        releaseCoherence: { outcome: 'pass' },
+        mcpEndToEnd: { outcome: 'pass' },
+      },
+      observedAt,
+    },
+    startedAt: observedAt,
+    updatedAt: observedAt,
+  });
+
+  const ctx = createMcpToolContext({
+    controllerHome,
+    profile: 'controller',
+    repo: repoRoot,
+    sessionId: `mcp-work-efficiency-${label}`,
+    principalId: `principal-work-efficiency-${label}`,
+    controllerInstanceId: owner.record.runtimeInstanceId,
+  }) as MultiRepositoryMcpToolContext;
+  return { root, controllerHome, repoRoot, repository, ctx };
+}
+
+async function timedCall(ctx: MultiRepositoryMcpToolContext, args: Record<string, unknown>): Promise<TimedCall> {
+  const startedAt = performance.now();
+  const result = await callRuntimeTool(ctx, 'rh_work', args);
+  const elapsedMs = Math.round((performance.now() - startedAt) * 100) / 100;
+  if (!result) throw new Error('rh_work returned no benchmark result');
+  const value = (result.structuredContent ?? JSON.parse(result.content?.[0]?.text ?? '{}')) as Record<string, any>;
+  return { elapsedMs, value };
+}
+
+async function runFlow(mode: FlowSample['mode'], sample: number): Promise<FlowSample> {
+  const label = `${mode}-${sample}-${Date.now()}`;
+  const fx = createFixture(label);
+  const wallStartedAt = performance.now();
+  let controllerCalls = 0;
+  let processWaits = 0;
+  try {
+    const started = await timedCall(fx.ctx, {
+      repo_id: fx.repository.repoId,
+      operation: 'start',
+      objective: `Benchmark ${mode} work lifecycle`,
+      scope_clear: true,
+      expected_files: 1,
+      expected_changed_lines: 1,
+      requires_recovery: true,
+      allowed_paths: ['README.md'],
+      check_ids: ['package:check:bench'],
+      constraints: { workspaceMode: 'isolated' },
+      request_id: `work-efficiency-start-${label}`,
+    });
+    controllerCalls += 1;
+    const workId = String(started.value.data?.work?.workId ?? '');
+    if (!workId) throw new Error('benchmark Work was not created');
+    const store = { controllerHome: fx.controllerHome, repoId: fx.repository.repoId };
+    const contract = getWorkContract(store, workId);
+    if (!contract?.worktreeRef) throw new Error('benchmark Work has no managed worktree');
+    writeFileSync(join(contract.worktreeRef, 'README.md'), `fixture\n${mode}\n`);
+
+    const verifyArgs = {
+      repo_id: fx.repository.repoId,
+      operation: 'verify',
+      work_id: workId,
+      check_id: 'package:check:bench',
+      request_id: `work-efficiency-verify-${label}`,
+    };
+    const verifySubmit = await timedCall(fx.ctx, verifyArgs);
+    controllerCalls += 1;
+    const processId = String(verifySubmit.value.data?.verification?.processId ?? '');
+    if (!processId) throw new Error('benchmark verification did not return a Process id');
+    const waitStartedAt = performance.now();
+    await waitForProcess(fx.controllerHome, fx.repository.repoId, processId, { timeoutMs: 10_000 });
+    const verifyWaitMs = Math.round((performance.now() - waitStartedAt) * 100) / 100;
+    processWaits += 1;
+
+    const verifyReattach = await timedCall(fx.ctx, verifyArgs);
+    controllerCalls += 1;
+    const verificationOutcome = String(verifyReattach.value.data?.verification?.outcome ?? '');
+    const verificationNextStep = typeof verifyReattach.value.data?.nextStep === 'string'
+      ? verifyReattach.value.data.nextStep
+      : undefined;
+    if (verificationOutcome !== 'valid_pass') throw new Error(`benchmark verification outcome: ${verificationOutcome}`);
+
+    let continueMs = 0;
+    if (mode === 'legacy_ceremony') {
+      const continued = await timedCall(fx.ctx, {
+        repo_id: fx.repository.repoId,
+        operation: 'continue',
+        work_id: workId,
+      });
+      controllerCalls += 1;
+      continueMs = continued.elapsedMs;
+      if (continued.value.data?.nextStep !== 'finalize') throw new Error('legacy ceremony did not reach finalize');
+    }
+
+    const finalized = await timedCall(fx.ctx, {
+      repo_id: fx.repository.repoId,
+      operation: 'finalize',
+      work_id: workId,
+    });
+    controllerCalls += 1;
+    const finalStatus = String(finalized.value.data?.finalStatus ?? '');
+    const cleanupComplete = !existsSync(contract.worktreeRef);
+    const totalMs = Math.round((performance.now() - wallStartedAt) * 100) / 100;
+    return {
+      mode,
+      sample,
+      ok: finalStatus === 'completed' && cleanupComplete,
+      controllerCalls,
+      processWaits,
+      startMs: started.elapsedMs,
+      verifySubmitMs: verifySubmit.elapsedMs,
+      verifyWaitMs,
+      verifyReattachMs: verifyReattach.elapsedMs,
+      continueMs,
+      finalizeMs: finalized.elapsedMs,
+      totalMs,
+      verificationNextStep,
+      finalStatus,
+      cleanupComplete,
+    };
+  } finally {
+    clearRuntimeWriteClaimForTests();
+    rmSync(fx.root, { recursive: true, force: true });
+  }
+}
+
+function percentile(values: number[], p: number): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const index = Math.min(sorted.length - 1, Math.ceil(sorted.length * p) - 1);
+  return Math.round((sorted[Math.max(0, index)] ?? 0) * 100) / 100;
+}
+
+function summarize(samples: FlowSample[]) {
+  return {
+    count: samples.length,
+    allOk: samples.every((sample) => sample.ok),
+    controllerCalls: samples[0]?.controllerCalls ?? 0,
+    processWaits: samples[0]?.processWaits ?? 0,
+    totalMs: {
+      p50: percentile(samples.map((sample) => sample.totalMs), 0.5),
+      p95: percentile(samples.map((sample) => sample.totalMs), 0.95),
+    },
+    startMs: { p50: percentile(samples.map((sample) => sample.startMs), 0.5), p95: percentile(samples.map((sample) => sample.startMs), 0.95) },
+    verifyWallMs: {
+      p50: percentile(samples.map((sample) => sample.verifySubmitMs + sample.verifyWaitMs + sample.verifyReattachMs), 0.5),
+      p95: percentile(samples.map((sample) => sample.verifySubmitMs + sample.verifyWaitMs + sample.verifyReattachMs), 0.95),
+    },
+    continueMs: { p50: percentile(samples.map((sample) => sample.continueMs), 0.5), p95: percentile(samples.map((sample) => sample.continueMs), 0.95) },
+    finalizeMs: { p50: percentile(samples.map((sample) => sample.finalizeMs), 0.5), p95: percentile(samples.map((sample) => sample.finalizeMs), 0.95) },
+  };
+}
+
+async function main(): Promise<void> {
+  const sampleCount = Math.min(argNumber('--samples', 3), 10);
+  const sourceHeadBefore = git(process.cwd(), ['rev-parse', 'HEAD']);
+  const streamlined: FlowSample[] = [];
+  const legacy: FlowSample[] = [];
+
+  for (let sample = 1; sample <= sampleCount; sample += 1) {
+    if (sample % 2 === 1) {
+      streamlined.push(await runFlow('streamlined', sample));
+      legacy.push(await runFlow('legacy_ceremony', sample));
+    } else {
+      legacy.push(await runFlow('legacy_ceremony', sample));
+      streamlined.push(await runFlow('streamlined', sample));
+    }
+  }
+
+  const sourceHeadAfter = git(process.cwd(), ['rev-parse', 'HEAD']);
+  const streamlinedSummary = summarize(streamlined);
+  const legacySummary = summarize(legacy);
+  const result = {
+    schemaVersion: 1,
+    benchmark: 'work-efficiency',
+    revision: sourceHeadAfter,
+    generatedAt: new Date().toISOString(),
+    sampleCount,
+    methodology: 'Real rh_work start + managed Check Process + authoritative reattach + finalize on isolated temporary repositories. Legacy comparison adds only the mechanical continue call.',
+    streamlined: streamlinedSummary,
+    legacyCeremony: legacySummary,
+    productivity: {
+      controllerCallsSavedPerWork: legacySummary.controllerCalls - streamlinedSummary.controllerCalls,
+      controlRoundTripReductionRatio: legacySummary.controllerCalls > 0
+        ? Math.round(((legacySummary.controllerCalls - streamlinedSummary.controllerCalls) / legacySummary.controllerCalls) * 10_000) / 10_000
+        : 0,
+      measuredContinueCeremonyMsP50: legacySummary.continueMs.p50,
+      totalWallClockDeltaMsP50: Math.round((legacySummary.totalMs.p50 - streamlinedSummary.totalMs.p50) * 100) / 100,
+    },
+    acceptance: {
+      sourceCheckoutHeadStable: sourceHeadBefore === sourceHeadAfter,
+      streamlinedAllOk: streamlinedSummary.allOk,
+      legacyAllOk: legacySummary.allOk,
+      streamlinedDirectsFinalPassToFinalize: streamlined.every((sample) => sample.verificationNextStep === 'finalize'),
+      oneControllerCallSaved: legacySummary.controllerCalls - streamlinedSummary.controllerCalls === 1,
+      cleanupComplete: [...streamlined, ...legacy].every((sample) => sample.cleanupComplete),
+    },
+    samples: { streamlined, legacyCeremony: legacy },
+  };
+  const allAccepted = Object.values(result.acceptance).every(Boolean);
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  if (!allAccepted) process.exitCode = 1;
+}
+
+await main();

package/scripts/capture-plan.sh

@@ -266,7 +266,7 @@ Use the captured planning output below as the execution source of truth.
 ### Trade-offs
 | Option | Pros | Cons | Decision |
 |--------|------|------|----------|
-| Captured plan | Preserves the approved Forge /plan, Codex Plan, or optional external planning decision | Requires the captured text to be concrete enough to execute | Use |
+| Captured plan | Preserves the approved Codex Plan or Waza think decision | Requires the captured text to be concrete enough to execute | Use |
 
 ## Detailed Design
 ### File Changes
@@ -302,8 +302,8 @@ See captured planning output.
 
 - **State/progress path**: \`${plan_file}\` task breakdown, \`tasks/todos.md\` deferred-goal ledger, \`tasks/contracts/${artifact_stem}.contract.md\`, \`tasks/reviews/${artifact_stem}.review.md\`, and \`tasks/notes/${artifact_stem}.notes.md\`
 - **Verification evidence**: \`.ai/harness/checks/latest.json\`, \`.ai/harness/runs/\`, and the commands named in the captured planning output
-- **Evaluator rubric**: \`tasks/reviews/${artifact_stem}.review.md\` must record a passing Forge /review recommendation
-- **Stop condition**: all task breakdown items are complete, sprint verification passes, and the review recommends pass
+- **Impact review**: after direct checks, reassess user intent, affected domains, downstream consumers, state transitions, and residual risks
+- **Stop condition**: all task breakdown items are complete and sprint verification reports direct checks plus declared scope passing
 - **Rollback surface**: before execution remove \`${plan_file}\`; after execution revert branch \`codex/${slug}\` or the generated task artifacts
 
 ## Captured Planning Output

package/scripts/check-agent-tooling.sh

@@ -1,18 +1,17 @@
 #!/bin/bash
 set -euo pipefail
 
-if command -v bun >/dev/null 2>&1; then
+if command -v node >/dev/null 2>&1; then
+  RUNTIME_BIN="$(command -v node)"
+elif command -v bun >/dev/null 2>&1; then
   RUNTIME_BIN="$(command -v bun)"
 elif [[ -x "${HOME}/.bun/bin/bun" ]]; then
   RUNTIME_BIN="${HOME}/.bun/bin/bun"
-elif command -v node >/dev/null 2>&1; then
-  RUNTIME_BIN="$(command -v node)"
 else
-  echo "check-agent-tooling.sh requires bun or node" >&2
+  echo "check-agent-tooling.sh requires node or bun" >&2
   exit 1
 fi
 
-export FORGE_TOOLING_PATH_SNAPSHOT="${PATH:-}"
 exec "$RUNTIME_BIN" - "$@" <<'NODE_EOF'
 const fs = require("fs");
 const crypto = require("crypto");
@@ -77,7 +76,6 @@ const WAZA_RAW_BASE_URL = "https://raw.githubusercontent.com/tw93/Waza/main";
 const WAZA_MANAGED_SKILLS = ["think", "hunt", "check", "health"];
 const WAZA_SHARED_RULES = ["anti-patterns.md", "chinese.md", "durable-context.md", "english.md"];
 const CODEX_AUTOMATION_SKILLS = ["health", "check", "mermaid"];
-const SKILLS_CLI_TIMEOUT_MS = 5000;
 const CODEGRAPH_PACKAGE = "@colbymchenry/codegraph";
 const CODEGRAPH_GLOBAL_INSTALL_COMMAND = `bun add -g ${CODEGRAPH_PACKAGE} && forge tools configure codegraph --target codex --location global`;
 const GBRAIN_INSTALL_COMMAND = "bun install -g github:garrytan/gbrain";
@@ -140,21 +138,7 @@ function fileIsExecutable(filePath) {
 
 function detectTimeoutBin() {
   if (timeoutBin !== undefined) return timeoutBin;
-  const candidate = resolvePathCommand("timeout");
-  if (!candidate) {
-    timeoutBin = "";
-    return timeoutBin;
-  }
-
-  const capability = spawnSync(candidate, ["--version"], {
-    encoding: "utf8",
-    timeout: 500,
-    env: process.env,
-  });
-  const output = `${capability.stdout || ""}\n${capability.stderr || ""}`;
-  timeoutBin = capability.status === 0 && /GNU coreutils|coreutils/i.test(output)
-    ? candidate
-    : "";
+  timeoutBin = resolvePathCommand("timeout") || "";
   return timeoutBin;
 }
 
@@ -705,7 +689,7 @@ function detectWaza() {
   const skillLock = readJson(skillLockPath);
   const skillsBin = resolvePathCommand("skills");
   const skillsResult = skillsBin
-    ? run(skillsBin, ["ls", "-g", "--json"], { timeoutMs: SKILLS_CLI_TIMEOUT_MS })
+    ? run(skillsBin, ["ls", "-g", "--json"], { timeoutMs: 1500 })
     : { ok: false, status: null, stdout: "", stderr: "", error: "skills CLI is not installed", timed_out: false };
   const skillItems = skillsResult.ok ? parseJson(skillsResult.stdout) || [] : [];
   const wazaEntries = Object.entries(skillLock?.skills || {}).filter(([, meta]) => meta?.source === WAZA_SOURCE_REPO);
@@ -1178,7 +1162,7 @@ function parseCodeGraphProjectStatus(output) {
 }
 
 function resolvePathCommand(command) {
-  const pathValue = process.env.FORGE_TOOLING_PATH_SNAPSHOT || process.env.PATH || "";
+  const pathValue = process.env.PATH || "";
   for (const dir of pathValue.split(path.delimiter)) {
     if (!dir) continue;
     const candidate = path.join(dir, command);
@@ -1203,18 +1187,7 @@ function codeGraphPlatformPackageName() {
 
 function codeGraphPlatformBundleBin() {
   if (process.platform === "win32") return null;
-  const direct = path.join(REPO_ROOT, "node_modules", codeGraphPlatformPackageName(), "bin", "codegraph");
-  if (fileIsExecutable(direct)) return direct;
-  // Git worktrees commonly reuse the canonical checkout's dependencies. Resolve
-  // the platform package through Node/Bun module lookup instead of declaring the
-  // bundled Runtime missing just because this worktree has no local node_modules.
-  try {
-    const packageJson = require.resolve(`${codeGraphPlatformPackageName()}/package.json`, { paths: [REPO_ROOT] });
-    const resolved = path.join(path.dirname(packageJson), "bin", "codegraph");
-    return fileIsExecutable(resolved) ? resolved : direct;
-  } catch {
-    return direct;
-  }
+  return path.join(REPO_ROOT, "node_modules", codeGraphPlatformPackageName(), "bin", "codegraph");
 }
 
 function resolveCodeGraphBinary() {