@moretea-labs/forge 1.7.2 → 1.8.1

package/scripts/canary-chatgpt-provider-delivery.ts

@@ -0,0 +1,97 @@
+#!/usr/bin/env bun
+import { randomUUID } from 'crypto';
+import { resolveControllerHome } from '../src/cli/repositories/controller-home';
+import { isWslWindowsRuntime } from '../src/cli/chatgpt-browser/bridge-provider';
+import { createChatgptBrowserDeliveryHost } from '../adapters/chatgpt/browser-delivery-host';
+import { createChatgptWslBridgeDeliveryHost } from '../adapters/chatgpt/wsl-bridge-delivery-host';
+import {
+  ensureChatgptExecutionPreference,
+  ensureControllerChatgptBrowser,
+  navigateWorkConversation,
+  submitChatgptPrompt,
+} from '../adapters/chatgpt/browser-delivery-runtime';
+import type { ChatgptProviderDeliveryHost } from '../adapters/chatgpt/provider-delivery';
+
+type ProviderMode = 'auto' | 'browser' | 'wsl-bridge';
+
+function arg(name: string): string | undefined {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : undefined;
+}
+
+function positiveInt(value: string | undefined, fallback: number): number {
+  const parsed = Number(value ?? fallback);
+  if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`${value ?? ''} is not a positive integer`);
+  return parsed;
+}
+
+function providerMode(): ProviderMode {
+  const value = (arg('--provider') ?? 'auto').trim();
+  if (value === 'auto' || value === 'browser' || value === 'wsl-bridge') return value;
+  throw new Error(`Unsupported --provider ${value}; expected auto, browser, or wsl-bridge.`);
+}
+
+function nativeBrowserHost(): ChatgptProviderDeliveryHost {
+  return createChatgptBrowserDeliveryHost({
+    ensureBrowser: ensureControllerChatgptBrowser,
+    navigate: navigateWorkConversation,
+    ensureExecutionPreference: ensureChatgptExecutionPreference,
+    submitPrompt: submitChatgptPrompt,
+  });
+}
+
+async function main(): Promise<void> {
+  const requested = providerMode();
+  const detectedWsl = isWslWindowsRuntime();
+  const provider = requested === 'auto' ? (detectedWsl ? 'wsl-bridge' : 'browser') : requested;
+  if (provider === 'wsl-bridge' && !detectedWsl) {
+    throw new Error('STAGE3B_WSL_CANARY_REQUIRES_WSL: run the wsl-bridge canary from the WSL Forge instance.');
+  }
+
+  const controllerHome = resolveControllerHome(arg('--controller-home'));
+  const timeoutMs = positiveInt(arg('--timeout-ms'), 60_000);
+  const nonce = randomUUID();
+  const targetUrl = arg('--target-url')?.trim() || 'https://chatgpt.com/';
+  const prompt = arg('--prompt')?.trim()
+    || `Forge Stage3B provider delivery canary ${nonce}. Reply with ACK only. Do not invoke tools or modify external state.`;
+  const browserSessionId = arg('--browser-session-id')?.trim() || `forge-stage3b-canary-${nonce.slice(0, 12)}`;
+  const workId = arg('--work-id')?.trim() || `stage3b-provider-canary-${nonce.slice(0, 12)}`;
+  const host = provider === 'wsl-bridge' ? createChatgptWslBridgeDeliveryHost() : nativeBrowserHost();
+
+  const startedAt = new Date().toISOString();
+  const result = await host.dispatch({
+    controllerHome,
+    repoId: 'controller',
+    repoRoot: process.cwd(),
+    workId,
+    prompt,
+    browserSessionId,
+    targetUrl,
+    model: 'gpt-5.6',
+    reasoning: 'high',
+    timeoutMs,
+  });
+  const receipt = {
+    schemaVersion: 1,
+    canary: 'forge-v2-stage3b-provider-delivery',
+    provider,
+    requestedProvider: requested,
+    detectedWsl,
+    controllerHome,
+    workId,
+    startedAt,
+    completedAt: new Date().toISOString(),
+    status: result.status,
+    browserSessionId: result.browserSessionId,
+    conversationUrl: result.conversationUrl,
+    executionPreferenceVerified: result.executionPreferenceVerified,
+    error: result.error,
+  };
+  process.stdout.write(`${JSON.stringify(receipt, null, 2)}\n`);
+  if (result.status !== 'dispatch_confirmed') process.exitCode = 1;
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

package/scripts/canary-controller-semantic-wait.ts

@@ -0,0 +1,183 @@
+#!/usr/bin/env bun
+import { execFileSync } from 'child_process';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { ensureControllerHome } from '../src/cli/repositories/controller-home';
+import { registerRepository } from '../src/cli/repositories/registry';
+import { createRequirement, updateRequirement } from '../src/runtime/control-plane/persistence/requirement-store';
+import { createWorkContract, recordWorkEvidenceState, updateWorkContract } from '../src/runtime/control-plane/facade/work-contract-store';
+import { claimControllerSession } from '../src/runtime/control-plane/facade/controller-session-store';
+import {
+  acknowledgeControllerRoundClaim,
+  beginInitialControllerRoundDispatch,
+  finishControllerRoundRelayDispatch,
+  getControllerRoundRelay,
+  readControllerRoundSemanticStateFingerprint,
+  submitControllerRoundDisposition,
+} from '../packages/kernel/controller/api/index';
+import { bindControllerSessionBinding, resumeControllerRoundOccurrence } from '../packages/kernel/controller/api/index';
+import { upsertChatgptControllerBinding } from '../adapters/chatgpt/controller-binding-store';
+
+const root = mkdtempSync(join(tmpdir(), 'forge-stage3c-semantic-wait-canary-'));
+const controllerHome = join(root, 'controller');
+const repoRoot = join(root, 'repo');
+const workId = 'WORK-STAGE3C-SEMANTIC-WAIT-CANARY';
+const requirementId = 'REQ-STAGE3C-SEMANTIC-WAIT-CANARY';
+
+function git(args: string[]): void {
+  execFileSync('git', args, { cwd: repoRoot, stdio: 'ignore' });
+}
+
+try {
+  ensureControllerHome(controllerHome);
+  mkdirSync(repoRoot, { recursive: true });
+  git(['init', '-q', '-b', 'main']);
+  git(['config', 'user.email', 'forge-canary@example.test']);
+  git(['config', 'user.name', 'Forge Stage3C Canary']);
+  writeFileSync(join(repoRoot, 'README.md'), 'stage3c semantic wait canary\n');
+  git(['add', '.']);
+  git(['commit', '-qm', 'fixture']);
+
+  const repository = registerRepository({ path: repoRoot, controllerHome, displayName: 'stage3c-semantic-wait-canary' });
+  const store = { controllerHome, repoId: repository.repoId };
+  createRequirement({ controllerHome }, {
+    requirementId,
+    title: 'Stage3C semantic wait canary',
+    outcomeStatement: 'Unchanged semantic wait does not dispatch a provider; one semantic change wakes one successor.',
+    acceptanceCriteria: ['zero provider dispatch while unchanged', 'exactly one provider dispatch after semantic change'],
+  });
+  updateRequirement({ controllerHome }, {
+    requirementId,
+    action: 'stage3c_canary_requirement_activate',
+    mutate: (current) => ({ ...current, state: 'active' }),
+  });
+  createWorkContract(store, {
+    workId,
+    repoId: repository.repoId,
+    requirementId,
+    checkoutId: repository.activeCheckoutId,
+    objective: 'Prove semantic wait admission before provider dispatch.',
+    acceptanceCriteria: ['Unchanged semantic state stays quiescent.', 'One meaningful state change wakes one successor.'],
+    allowedPaths: [],
+    forbiddenPaths: [],
+    checks: [],
+    constraints: {},
+    requestedBy: 'chatgpt',
+    phase: 'verification',
+  });
+
+  const owner = claimControllerSession(store, {
+    workId,
+    controllerId: 'stage3c-canary-controller',
+    controllerType: 'chatgpt',
+    sessionId: 'stage3c-canary-session',
+    principalId: 'stage3c-canary-controller',
+    controllerInstanceId: 'stage3c-canary-runtime',
+    leaseMs: 60_000,
+  });
+  const adapter = upsertChatgptControllerBinding(store, {
+    workId,
+    sessionId: owner.sessionId,
+    title: 'Stage3C canary provider target',
+    model: 'gpt-5.6',
+    reasoning: 'high',
+    tabPolicy: 'auto',
+  });
+  bindControllerSessionBinding(store, { workId, sessionId: owner.sessionId, binding: adapter.binding });
+  const relayScopeId = `requirement:${requirementId}`;
+  beginInitialControllerRoundDispatch(store, {
+    workId,
+    requirementId,
+    relayScopeId,
+    bindingId: adapter.binding.bindingId,
+    identity: {
+      controllerId: owner.controllerId,
+      controllerType: owner.controllerType,
+      principalId: owner.principalId!,
+      controllerInstanceId: owner.controllerInstanceId!,
+      sessionId: owner.sessionId,
+    },
+  });
+  finishControllerRoundRelayDispatch(store, {
+    workId,
+    ok: true,
+    bindingId: adapter.binding.bindingId,
+    providerDispatchReceiptId: 'stage3c-canary-initial-dispatch',
+  });
+  const claimed = acknowledgeControllerRoundClaim(store, { workId, session: owner });
+  if (claimed?.status !== 'claimed') throw new Error(`CANARY_CLAIM_FAILED:${claimed?.status ?? 'missing'}`);
+  const waiting = submitControllerRoundDisposition(store, {
+    workId,
+    relayScopeId,
+    identity: {
+      controllerId: owner.controllerId,
+      controllerType: owner.controllerType,
+      principalId: owner.principalId!,
+      controllerInstanceId: owner.controllerInstanceId!,
+      sessionId: owner.sessionId,
+    },
+    disposition: 'wait',
+  });
+  if (waiting.status !== 'waiting') throw new Error(`CANARY_WAIT_FAILED:${waiting.status}`);
+
+  const baselineFingerprint = readControllerRoundSemanticStateFingerprint(store, workId);
+  updateWorkContract(store, workId, {}); // updatedAt churn only
+  const timestampChurnFingerprint = readControllerRoundSemanticStateFingerprint(store, workId);
+  if (!baselineFingerprint || timestampChurnFingerprint !== baselineFingerprint) {
+    throw new Error('CANARY_TIMESTAMP_CHURN_CHANGED_SEMANTIC_FINGERPRINT');
+  }
+
+  let providerCalls = 0;
+  const providerCallCount = (): number => providerCalls;
+  const host = {
+    resume: async () => {
+      providerCalls += 1;
+      return { accepted: true, dispatchId: `stage3c-canary-provider-${providerCalls}` };
+    },
+  };
+  const unchanged = await resumeControllerRoundOccurrence(store, {
+    occurrenceId: 'stage3c-canary-unchanged',
+    workId,
+    controllerBindingId: adapter.binding.bindingId,
+    relayScopeId,
+  }, host);
+  if (unchanged.outcome !== 'semantic_wait' || providerCallCount() !== 0) {
+    throw new Error(`CANARY_UNCHANGED_WAIT_DISPATCHED:${unchanged.outcome}:calls=${providerCallCount()}`);
+  }
+
+  recordWorkEvidenceState(store, workId, 'partial');
+  const changedFingerprint = readControllerRoundSemanticStateFingerprint(store, workId);
+  if (!changedFingerprint || changedFingerprint === baselineFingerprint) throw new Error('CANARY_MEANINGFUL_CHANGE_NOT_DETECTED');
+  const changed = await resumeControllerRoundOccurrence(store, {
+    occurrenceId: 'stage3c-canary-changed',
+    workId,
+    controllerBindingId: adapter.binding.bindingId,
+    relayScopeId,
+  }, host);
+  if (changed.outcome !== 'dispatched' || providerCallCount() !== 1) {
+    throw new Error(`CANARY_CHANGED_STATE_DISPATCH_COUNT:${changed.outcome}:calls=${providerCallCount()}`);
+  }
+  const finalRelay = getControllerRoundRelay(store, workId);
+  if (finalRelay?.providerDispatchReceiptId !== 'stage3c-canary-provider-1') {
+    throw new Error('CANARY_PROVIDER_RECEIPT_MISSING');
+  }
+
+  console.log(JSON.stringify({
+    schemaVersion: 1,
+    canary: 'forge-v2-stage3c-semantic-wait',
+    status: 'passed',
+    requirementId,
+    workId,
+    relayScopeId,
+    baselineFingerprint,
+    timestampChurnFingerprint,
+    changedFingerprint,
+    unchangedDispatchStatus: unchanged.outcome,
+    changedDispatchStatus: changed.outcome,
+    providerCalls: providerCallCount(),
+    providerDispatchReceiptId: finalRelay.providerDispatchReceiptId,
+  }, null, 2));
+} finally {
+  rmSync(root, { recursive: true, force: true });
+}

package/scripts/canary-global-hook.sh

@@ -10,8 +10,8 @@
 # auto-reload (Claude); confirm trust hash registration in ~/.codex/config.toml
 # under user-level [hooks.state] keys.
 #
-# See: plans/plan-20260528-1436-hook-global-runtime.md (Phase 0)
-#      tasks/notes/hook-global-runtime.notes.md (verification rounds 1+2)
+# Phase 0 rationale and verification rounds are preserved in Git history; this
+# script is the current executable canary contract.
 
 set -euo pipefail
 

package/scripts/check-mcp-compatibility.ts

@@ -1,5 +1,8 @@
 import { readFileSync } from 'fs';
 import { FORGE_TOOL_SURFACE, FORGE_VERSION, forgeToolSurfaceFingerprint } from '../src/cli/controller/runtime-config';
+import { injectAutomationEnvelopeFields } from '../adapters/mcp/runtime-gateway/automation-receipt-adapter';
+import { injectCognitionSettlementFields } from '../adapters/mcp/runtime-gateway/cognition-settlement';
+import { injectDurableCommandFields } from '../src/runtime/gateway/mcp/router';
 import { runtimePolicy } from '../src/cli/mcp/multi-repository';
 import { buildMcpToolDefinitions } from '../src/cli/mcp/tools';
 import { accessToolDefinitions } from '../src/cli/mcp/access-tools';
@@ -20,20 +23,45 @@ import {
 // caught before they become discovery latency and schema-cache churn.
 const MAX_DEFAULT_TOOL_COUNT = 24;
 
+// #197 decomposition authority: the public/frozen Tool Contract is an explicit
+// baseline, independent from whichever internal adapter currently defines a
+// tool. Adapter extraction may move implementation ownership without silently
+// changing names, descriptions, input schemas, or annotations.
+const EXPECTED_STABLE_CONTROLLER_TOOL_NAMES = [
+  'rh_access', 'rh_status', 'rh_inbox', 'rh_context', 'rh_work', 'capability_execute',
+  'repository_list', 'repository_get', 'repository_register', 'repository_command_execute',
+  'read_repository_file', 'repository_safe_patch_apply', 'run_check', 'plugin_action_execute',
+  'process_exec', 'process_get', 'process_wait', 'process_logs', 'process_cancel', 'result_read', 'result_search',
+] as const;
+// The stable bounded surface now includes the generic typed capability executor
+// already shipped on main. V3 Work objective relations intentionally extend only
+// the existing rh_work input schema; both changes must invalidate stale Connector
+// schema snapshots without adding a parallel execution or graph authority.
+const EXPECTED_STABLE_TOOL_NAME_FINGERPRINT = 'b25da75c1f774e66';
+// Every public object-schema tool carries shared transport metadata only through
+// the final tools/list materialization path. Automation and Cognition settlement
+// revisions intentionally invalidate stale Connector schema snapshots.
+const EXPECTED_STABLE_TOOL_SCHEMA_FINGERPRINT = '643521037647c28a';
+
 const policy = runtimePolicy(process.cwd(), {
   profile: 'controller',
   enableDevRunner: true,
   devRunnerAgents: 'codex,claude',
 });
 
-const sourceGroups = {
-  runtime: runtimeToolDefinitions.map((tool) => tool.name),
-  execution: executionToolDefinitions.map((tool) => tool.name),
-  process: processToolDefinitions.map((tool) => tool.name),
-  access: accessToolDefinitions.map((tool) => tool.name),
-  repository: repositoryToolDefinitions.map((tool) => tool.name),
-  legacyCompatibility: buildMcpToolDefinitions(policy).map((tool) => tool.name),
+const sourceDefinitionGroups = {
+  runtime: runtimeToolDefinitions,
+  execution: executionToolDefinitions,
+  process: processToolDefinitions,
+  access: accessToolDefinitions,
+  repository: repositoryToolDefinitions,
+  legacyCompatibility: buildMcpToolDefinitions(policy),
 };
+const sourceGroups = Object.fromEntries(
+  Object.entries(sourceDefinitionGroups).map(([group, definitions]) => [group, definitions.map((tool) => tool.name)]),
+) as Record<keyof typeof sourceDefinitionGroups, string[]>;
+const allDefinitions = Object.values(sourceDefinitionGroups).flat();
+const definitionByName = new Map(allDefinitions.map((tool) => [tool.name, tool]));
 const fullNames = [...new Set(Object.values(sourceGroups).flat())];
 const defaultNames: string[] = [...DEFAULT_CONTROLLER_TOOL_NAMES];
 const coreNames: string[] = [...CORE_CONTROLLER_TOOL_NAMES];
@@ -41,6 +69,10 @@ const advancedNames: string[] = [...ADVANCED_CONTROLLER_TOOL_NAMES];
 const catalogNames: string[] = [...STABLE_CONTROLLER_TOOL_NAMES];
 const preferredNames: string[] = [...PREFERRED_FACADE_TOOL_NAMES];
 const defaultFingerprint = forgeToolSurfaceFingerprint(defaultNames);
+const stableDefinitions = defaultNames
+  .map((name) => definitionByName.get(name)).filter((tool) => tool !== undefined)
+  .map((tool) => injectCognitionSettlementFields(injectAutomationEnvelopeFields(injectDurableCommandFields(tool))));
+const stableSchemaFingerprint = forgeToolSurfaceFingerprint(stableDefinitions);
 const catalogFingerprint = forgeToolSurfaceFingerprint(catalogNames);
 const fullFingerprint = forgeToolSurfaceFingerprint(fullNames);
 const duplicateDefault = defaultNames.filter((name, index) => defaultNames.indexOf(name) !== index);
@@ -59,8 +91,42 @@ const currentToolNames = new Set([
 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 recoveryMcpSource = readFileSync(new URL('../src/runtime/standalone-recovery/mcp-server.ts', import.meta.url), 'utf8');
+const recoveryStatelessMarkers = [
+  'createMcpHandler',
+  'toNodeHandler',
+  "legacy: 'stateless'",
+  "responseMode: 'auto'",
+];
+const recoverySessionAuthorityMarkers = [
+  'McpSessionRegistry',
+  'NodeStreamableHTTPServerTransport',
+  'Mcp-Session-Reset',
+  'sessionIdGenerator',
+];
 
 const failures: string[] = [];
+for (const marker of recoveryStatelessMarkers) {
+  if (!recoveryMcpSource.includes(marker)) {
+    failures.push(`Standalone Recovery MCP must remain stateless across protocol eras: missing ${marker}`);
+  }
+}
+for (const marker of recoverySessionAuthorityMarkers) {
+  if (recoveryMcpSource.includes(marker)) {
+    failures.push(`Standalone Recovery MCP must not own transport-session state: found ${marker}`);
+  }
+}
+if (defaultNames.join('\n') !== EXPECTED_STABLE_CONTROLLER_TOOL_NAMES.join('\n')) {
+  failures.push(`stable ChatGPT Tool Contract names changed: ${defaultNames.join(', ')}`);
+}
+if (defaultFingerprint !== EXPECTED_STABLE_TOOL_NAME_FINGERPRINT) {
+  failures.push(`stable ChatGPT tool-name fingerprint changed: ${defaultFingerprint} != ${EXPECTED_STABLE_TOOL_NAME_FINGERPRINT}`);
+}
+if (stableDefinitions.length !== defaultNames.length) {
+  failures.push(`stable ChatGPT Tool Contract definitions are incomplete: ${stableDefinitions.length}/${defaultNames.length}`);
+} else if (stableSchemaFingerprint !== EXPECTED_STABLE_TOOL_SCHEMA_FINGERPRINT) {
+  failures.push(`stable ChatGPT Tool Contract schema fingerprint changed: ${stableSchemaFingerprint} != ${EXPECTED_STABLE_TOOL_SCHEMA_FINGERPRINT}`);
+}
 if (defaultNames.length > MAX_DEFAULT_TOOL_COUNT) {
   failures.push(`default ChatGPT tools/list exceeds the schema budget: ${defaultNames.length} > ${MAX_DEFAULT_TOOL_COUNT}`);
 }
@@ -83,6 +149,17 @@ if (fullNames.length < defaultNames.length) {
   failures.push(`full compatibility surface is smaller than default surface: ${fullNames.length} < ${defaultNames.length}`);
 }
 
+const rhWorkDefinition = runtimeToolDefinitions.find((tool) => tool.name === 'rh_work');
+const rhWorkProperties = (rhWorkDefinition?.inputSchema?.properties ?? {}) as Record<string, unknown>;
+for (const field of [
+  'checkout_id',
+  'workflow_id',
+  'workflow_run_id',
+  'outcome_observation',
+  'experience_draft',
+] as const) {
+  if (!(field in rhWorkProperties)) failures.push(`stable rh_work Tool Contract missing ${field}`);
+}
 if (failures.length) {
   console.error('[mcp-compatibility] FAILED');
   for (const failure of failures) console.error(`- ${failure}`);
@@ -95,6 +172,7 @@ console.log(JSON.stringify({
   version: FORGE_VERSION,
   stableToolCount: defaultNames.length,
   stableFingerprint: defaultFingerprint,
+  stableSchemaFingerprint,
   defaultToolBudget: MAX_DEFAULT_TOOL_COUNT,
   compatibilityCatalogToolCount: catalogNames.length,
   compatibilityCatalogFingerprint: catalogFingerprint,

package/scripts/check-platform-support.mjs

@@ -4,6 +4,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { findWindowsIncompatiblePaths } from "./windows-paths.mjs";
+import { findPortabilityBindings, portabilityBindingDetectorSelfCheck } from "./portability-bindings.mjs";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const failures = [];
@@ -21,8 +22,9 @@ function requireText(path, value) {
   if (!text(path).includes(value)) failures.push(`${path} must contain ${JSON.stringify(value)}`);
 }
 
+let trackedPaths = [];
 try {
-  const trackedPaths = execFileSync("git", ["ls-files", "-z"], { cwd: root, encoding: "utf8" })
+  trackedPaths = execFileSync("git", ["ls-files", "-z"], { cwd: root, encoding: "utf8" })
     .split("\0")
     .filter(Boolean);
   for (const entry of findWindowsIncompatiblePaths(trackedPaths)) {
@@ -36,10 +38,11 @@ const pkg = JSON.parse(text("package.json") || "{}");
 if (pkg.engines?.node !== ">=20.10.0") failures.push("package.json engines.node must be >=20.10.0");
 if (!pkg.engines?.bun) failures.push("package.json must document the supported Bun runtime");
 if (!pkg.scripts?.["check:platform-support"]) failures.push("package.json is missing check:platform-support");
+if (!pkg.scripts?.["smoke:tarball-install"]) failures.push("package.json is missing smoke:tarball-install");
+if (!pkg.scripts?.["check:portable-package"]) failures.push("package.json is missing check:portable-package");
 
 requireText("bin/forge.mjs", "#!/usr/bin/env node");
 for (const path of ["install.sh", "install.ps1"]) {
-  requireText(path, "FORGE_INSTALL_RUNTIME");
   requireText(path, "FORGE_INSTALL_RUNTIME");
   requireText(path, "Node.js 20.10");
   requireText(path, "Git is optional");
@@ -54,6 +57,29 @@ requireText("docs/tutorials/01-install-and-start.md", "Node.js 20.10");
 requireText("docs/tutorials/01-install-and-start.zh-CN.md", "Node.js 20.10");
 requireText(".github/workflows/windows-smoke.yml", "windows-latest");
 requireText(".github/workflows/windows-smoke.yml", "-DryRun");
+requireText("docs/operations/platform-support.md", "| Platform | Runtime | Controller / MCP | Browser | Native Desktop / Computer | Recovery | Service persistence |");
+requireText("docs/operations/platform-support.md", "non-persistent portable");
+requireText("docs/operations/platform-support.md", "Windows-host Recovery binding");
+
+requireText("scripts/check-tarball-install-smoke.sh", "FORGE_CONTROLLER_HOME");
+requireText("scripts/check-tarball-install-smoke.sh", "CLEAN_HOME");
+requireText("scripts/check-tarball-install-smoke.sh", "npm pack --silent");
+requireText("scripts/check-tarball-install-smoke.sh", "PACKAGE_VERSION=\"$(node");
+
+const productTextPaths = trackedPaths.filter((entry) =>
+  /^(?:bin|src|packages|adapters|assets)\//.test(entry)
+  || entry === "install.sh"
+  || entry === "install.ps1"
+);
+for (const failure of portabilityBindingDetectorSelfCheck()) {
+  failures.push(`portability binding detector self-check failed: ${failure}`);
+}
+for (const path of productTextPaths) {
+  const content = text(path);
+  for (const finding of findPortabilityBindings(path, content)) {
+    failures.push(`${finding.path} contains ${finding.label}; use host discovery/configuration instead`);
+  }
+}
 
 const publicDocs = [
   "README.md",

package/scripts/check-public-docs.sh

@@ -41,7 +41,7 @@ for path in "${required[@]}"; do
   [[ -f "$path" ]] || { echo "[public-docs] missing: $path" >&2; exit 1; }
 done
 
-if git grep -n -E 'controller_capabilities and project_snapshot|Start repository work with controller_capabilities|20260612-legacy-research-notes|github[.]com/greyson[O]uyang/' -- README*.md docs ':!docs/architecture/history/**' ':!docs/architecture/snapshots/**' >/dev/null; then
+if git grep -n -E 'controller_capabilities and project_snapshot|Start repository work with controller_capabilities|20260612-legacy-research-notes|github[.]com/greyson[O]uyang/' -- README*.md docs ':!docs/architecture/snapshots/**' >/dev/null; then
   echo "[public-docs] stale onboarding, personal repository URL, or removed legacy reference found" >&2
   exit 1
 fi

package/scripts/check-repository-hygiene.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const tracked = execFileSync('git', ['ls-files'], { cwd: ROOT, encoding: 'utf8' })
+  .split('\n').map((line) => line.trim()).filter(Boolean);
+const failures = [];
+
+for (const prefix of ['evals/', 'references/', 'recovery/', 'tasks/issues/', 'tasks/contracts/', 'tasks/reviews/', 'tasks/notes/', 'tasks/workstreams/']) {
+  const hits = tracked.filter((path) => path.startsWith(prefix));
+  if (hits.length) failures.push(`retired tracked root ${prefix}: ${hits.slice(0, 5).join(', ')}`);
+}
+for (const exact of ['scripts/run-skill-evals.ts', 'tasks/current.md']) {
+  if (tracked.includes(exact)) failures.push(`retired tracked file: ${exact}`);
+}
+
+const sourcePollution = [
+  '.ai/harness/local-jobs-archive',
+  '.ai/harness/jobs-archive',
+  '.forge/tools',
+  '.forge/tmp',
+  '.forge/assistant',
+  '_ops',
+  '.repo-harness',
+];
+for (const relativePath of sourcePollution) {
+  if (existsSync(join(ROOT, relativePath))) failures.push(`runtime/cache data must not live in source tree: ${relativePath}`);
+}
+for (const relativePath of [
+  '.forge/browser',
+  '.forge/interactions',
+  '.forge/plugins',
+  '.codegraph',
+  '.ai/harness/checks',
+  '.ai/harness/session',
+  '.ai/harness/planning',
+  '.ai/harness/security',
+  '.ai/harness/transfers',
+  '.ai/harness/edit-sessions',
+]) {
+  const path = join(ROOT, relativePath);
+  if (!existsSync(path)) continue;
+  try {
+    if (!lstatSync(path).isSymbolicLink()) failures.push(`runtime data must be Controller-Home-backed (symlink or absent): ${relativePath}`);
+  } catch {
+    failures.push(`cannot inspect runtime path: ${relativePath}`);
+  }
+}
+
+
+const producerSources = [
+  'src/core/adoption/plan.ts',
+  'scripts/create-project-dirs.sh',
+  'scripts/init-project.sh',
+  'scripts/lib/project-init-lib.sh',
+];
+const forbiddenProducerFragments = [
+  'tasks/current.md',
+  'tasks/issues',
+  'tasks/workstreams',
+  'mkdir -p _ops',
+  'mkdir -p .ai/harness/checks',
+];
+for (const relativePath of producerSources) {
+  const content = readFileSync(join(ROOT, relativePath), 'utf8');
+  for (const fragment of forbiddenProducerFragments) {
+    if (content.includes(fragment)) failures.push(`project bootstrap/adoption must not produce machine lifecycle surface (${fragment}): ${relativePath}`);
+  }
+}
+
+const packageJson = readFileSync(join(ROOT, 'package.json'), 'utf8');
+if (packageJson.includes('benchmark:skills') || packageJson.includes('run-skill-evals')) {
+  failures.push('legacy skill benchmark entrypoint is still exposed by package.json');
+}
+const cleanupSource = readFileSync(join(ROOT, 'src/runtime/maintenance/cleanup.ts'), 'utf8');
+if (cleanupSource.includes(".ai/harness/local-jobs-archive") || cleanupSource.includes(".ai/harness/jobs-archive")) {
+  failures.push('runtime cleanup must not create archive namespaces inside repository source');
+}
+const gateSource = readFileSync(join(ROOT, 'scripts/run-governed-gate.ts'), 'utf8');
+if (gateSource.includes("join(ROOT, '.ai/harness/checks/gates')")) {
+  failures.push('governed gate receipts must use Controller Home cache, not repository source');
+}
+
+if (failures.length) {
+  console.error('[repository-hygiene] failed');
+  for (const failure of failures) console.error(`- ${failure}`);
+  process.exit(1);
+}
+console.log('[repository-hygiene] ok');