@moretea-labs/forge 1.5.1 → 1.7.0

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() {

package/scripts/check-architecture-sync.sh

@@ -19,85 +19,6 @@ target_branch=""
 changed_files_file=""
 format="text"
 
-required_current_docs=(
-  "docs/architecture/current/README.md"
-  "docs/architecture/current/governance.md"
-  "docs/architecture/current/system-overview.md"
-  "docs/architecture/current/architecture-invariants.md"
-  "docs/architecture/current/entity-model.md"
-  "docs/architecture/current/job-and-run-lifecycle.md"
-  "docs/architecture/current/dispatch-and-agent-strategy.md"
-  "docs/architecture/current/scheduler-and-resource-claims.md"
-  "docs/architecture/current/multi-repository-execution.md"
-  "docs/architecture/current/automation-and-schedule-engine.md"
-  "docs/architecture/current/failure-recovery.md"
-  "docs/architecture/current/verification-and-release-gates.md"
-  "docs/architecture/current/implementation-status.md"
-  "docs/architecture/current/migration-roadmap.md"
-  "docs/architecture/current/runtime-directory-map.md"
-  "docs/architecture/current/operations-runbook.md"
-)
-
-historical_runtime_docs=(
-  "docs/architecture/history.md"
-)
-
-runtime_architecture_gate_enabled() {
-  [[ -d "docs/architecture/current" ]] && return 0
-  local file
-  for file in "${historical_runtime_docs[@]}"; do
-    [[ -f "$file" ]] && return 0
-  done
-  [[ -f "docs/architecture/index.md" ]] && grep -Fq -- "Controller Runtime" "docs/architecture/index.md"
-}
-
-architecture_baseline_fail() {
-  echo "[ArchitectureSync] current Controller Runtime architecture baseline failed: $1" >&2
-  return 1
-}
-
-require_architecture_file() {
-  local file="$1"
-  [[ -f "$file" ]] || architecture_baseline_fail "missing required file $file"
-}
-
-require_architecture_text() {
-  local file="$1"
-  local text="$2"
-  if ! require_architecture_file "$file"; then
-    return 1
-  fi
-  grep -Fq -- "$text" "$file" || architecture_baseline_fail "$file must contain: $text"
-}
-
-check_runtime_architecture_baseline() {
-  local file
-  local failed=0
-  require_architecture_text "docs/architecture/index.md" "Runtime Authority" || failed=1
-  require_architecture_text "docs/architecture/index.md" "docs/architecture/current/" || failed=1
-  require_architecture_text "docs/architecture/current/README.md" "Runtime Authority" || failed=1
-  require_architecture_text "docs/architecture/current/governance.md" "Runtime Authority" || failed=1
-
-  for file in "${required_current_docs[@]}"; do
-    require_architecture_file "$file" || failed=1
-  done
-
-  for file in "${historical_runtime_docs[@]}"; do
-    require_architecture_text "$file" "Historical Design" || failed=1
-    require_architecture_text "$file" "Not Runtime Authority" || failed=1
-    require_architecture_text "$file" "docs/architecture/current/README.md" || failed=1
-  done
-
-  require_architecture_text "docs/architecture/current/architecture-invariants.md" "Invariant 2 — Persist Before Execute" || failed=1
-  require_architecture_text "docs/architecture/current/architecture-invariants.md" "Invariant 4 — Task Is Intent; Run Is Attempt" || failed=1
-  require_architecture_text "docs/architecture/current/architecture-invariants.md" "Invariant 16 — Evidence Binds to Exact Revision" || failed=1
-  require_architecture_text "docs/architecture/current/architecture-invariants.md" "Invariant 21 — Scheduled Work Is Bounded" || failed=1
-  require_architecture_text "docs/architecture/current/implementation-status.md" "## Completion Statement" || failed=1
-  require_architecture_text "docs/architecture/current/migration-roadmap.md" "## P0" || failed=1
-  require_architecture_text "docs/architecture/current/migration-roadmap.md" "## P5" || failed=1
-  return "$failed"
-}
-
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --mode)
@@ -277,13 +198,6 @@ case "$mode" in
     ;;
 esac
 
-# Structural authority checks are invariant and must run even when freshness gating is disabled.
-if runtime_architecture_gate_enabled; then
-  if ! check_runtime_architecture_baseline; then
-    exit 1
-  fi
-fi
-
 if [[ ! -x "scripts/architecture-queue.sh" ]]; then
   if [[ "$mode" == "strict" ]]; then
     echo "[ArchitectureSync] strict gate failed: missing scripts/architecture-queue.sh" >&2
@@ -298,6 +212,23 @@ if ! bash scripts/architecture-queue.sh reindex --check >/dev/null; then
   exit 1
 fi
 
+if [[ -f "docs/architecture/current/README.md" ]]; then
+  if [[ ! -f "docs/architecture/CURRENT.md" ]]; then
+    echo "[ArchitectureSync] architecture baseline failed: missing required file docs/architecture/CURRENT.md" >&2
+    exit 1
+  fi
+
+  if ! grep -Fq "Runtime Authority" "docs/architecture/CURRENT.md"; then
+    echo "[ArchitectureSync] architecture baseline failed: docs/architecture/CURRENT.md must contain: Runtime Authority" >&2
+    exit 1
+  fi
+
+  if ! grep -Fq "Not Runtime Authority" "docs/architecture/current/README.md"; then
+    echo "[ArchitectureSync] architecture baseline failed: docs/architecture/current/README.md must contain: Not Runtime Authority" >&2
+    exit 1
+  fi
+fi
+
 if [[ "$mode" == "off" ]]; then
   case "$format" in
     json) printf '{"mode":"off","changed_capabilities":0,"blocking":0}\n' ;;

package/scripts/check-mcp-compatibility.ts

@@ -1,3 +1,4 @@
+import { readFileSync } from 'fs';
 import { FORGE_TOOL_SURFACE, FORGE_VERSION, forgeToolSurfaceFingerprint } from '../src/cli/controller/runtime-config';
 import { runtimePolicy } from '../src/cli/mcp/multi-repository';
 import { buildMcpToolDefinitions } from '../src/cli/mcp/tools';
@@ -48,6 +49,16 @@ const missingCatalog = catalogNames.filter((name) => !fullNames.includes(name));
 const sourceCollisions = Object.entries(sourceGroups).flatMap(([group, names], groupIndex, entries) =>
   names.filter((name) => entries.slice(0, groupIndex).some(([, earlier]) => earlier.includes(name)))
     .map((name) => `${group}:${name}`));
+const currentToolNames = new Set([
+  ...sourceGroups.runtime,
+  ...sourceGroups.execution,
+  ...sourceGroups.process,
+  ...sourceGroups.access,
+  ...sourceGroups.repository,
+]);
+const legacyHandlerSource = readFileSync(new URL('../src/cli/mcp/legacy-tool-service.ts', import.meta.url), 'utf8');
+const legacyHandlerNames = [...legacyHandlerSource.matchAll(/case\s+["']([^"']+)["']\s*:/g)].map((match) => match[1]);
+const legacyHandlerCollisions = [...new Set(legacyHandlerNames.filter((name) => currentToolNames.has(name)))].sort();
 
 const failures: string[] = [];
 if (defaultNames.length > MAX_DEFAULT_TOOL_COUNT) {
@@ -56,6 +67,8 @@ if (defaultNames.length > MAX_DEFAULT_TOOL_COUNT) {
 if (duplicateDefault.length) failures.push(`default duplicate names: ${[...new Set(duplicateDefault)].join(', ')}`);
 if (missingDefault.length) failures.push(`default tools missing from registered definitions: ${missingDefault.join(', ')}`);
 if (missingCatalog.length) failures.push(`compatibility catalog tools missing from registered definitions: ${missingCatalog.join(', ')}`);
+if (sourceCollisions.length) failures.push(`tool schema authority collisions: ${sourceCollisions.join(', ')}`);
+if (legacyHandlerCollisions.length) failures.push(`legacy execution authority collisions: ${legacyHandlerCollisions.join(', ')}`);
 if (coreNames.join('\n') !== defaultNames.join('\n')) {
   failures.push('core surface must alias the bounded default ChatGPT surface');
 }
@@ -89,5 +102,6 @@ console.log(JSON.stringify({
   fullCompatibilityFingerprint: fullFingerprint,
   sourceToolCounts: Object.fromEntries(Object.entries(sourceGroups).map(([name, tools]) => [name, tools.length])),
   sourceCollisions: [...new Set(sourceCollisions)].sort(),
+  legacyHandlerCollisions,
   accessModeChangesSchema: false,
 }, null, 2));

package/scripts/check-public-docs.sh

@@ -72,9 +72,22 @@ grep -q "$README_CHANNEL_EN" README.md || { echo "[public-docs] English README m
 grep -q "$README_CHANNEL_ZH" README.zh-CN.md || { echo "[public-docs] Chinese README must state the npm channel for $PACKAGE_VERSION" >&2; exit 1; }
 grep -q 'See \[README.md\](README.md)' README.en.md || { echo "[public-docs] README.en.md must point to the maintained English README" >&2; exit 1; }
 
+source_install_docs=(
+  README.md README.zh-CN.md
+  docs/tutorials/01-install-and-start.md docs/tutorials/01-install-and-start.zh-CN.md
+  docs/wiki/Quick-Start.md docs/wiki/Installation.md
+)
+for path in "${source_install_docs[@]}"; do
+  grep -q 'bun install --frozen-lockfile' "$path" || { echo "[public-docs] source checkout must use the CI-authoritative Bun frozen lock: $path" >&2; exit 1; }
+  grep -q 'npm install -g \.' "$path" || { echo "[public-docs] missing source package install: $path" >&2; exit 1; }
+done
+if git grep -n 'npm ci --ignore-scripts --no-audit --no-fund' -- "${source_install_docs[@]}" >/dev/null; then
+  echo "[public-docs] generic npm ci must not be advertised for Forge source checkouts" >&2
+  exit 1
+fi
+
 for path in docs/tutorials/01-install-and-start.md docs/tutorials/01-install-and-start.zh-CN.md; do
   grep -q 'Node.js 20.10' "$path" || { echo "[public-docs] missing Node baseline: $path" >&2; exit 1; }
-  grep -q 'npm install -g \.' "$path" || { echo "[public-docs] missing source install: $path" >&2; exit 1; }
   grep -q "$INSTALL_SPEC" "$path" || { echo "[public-docs] missing package command for $PACKAGE_VERSION: $path" >&2; exit 1; }
 done