@moretea-labs/forge 1.5.1 → 1.7.0

package/scripts/ensure-task-workflow.sh

@@ -348,7 +348,7 @@ Complete this inventory before implementation. If any line is unknown, keep the
 
 - **State/progress path**:
 - **Verification evidence**:
-- **Evaluator rubric**:
+- **Impact review**:
 - **Stop condition**:
 - **Rollback surface**:
 
@@ -391,7 +391,7 @@ Describe the exact outcome this task must deliver.
 - Checks file: `.ai/harness/checks/latest.json`
 - Run snapshots: `.ai/harness/runs/`
 - Scope gate: edit only paths listed under `allowed_paths`; update this contract before widening scope.
-- Completion gate: `scripts/verify-sprint.sh` must see this contract pass, the review recommend pass, and `## External Acceptance Advice` pass or record a manual override.
+- Completion evidence: `scripts/verify-sprint.sh` reports this contract's direct checks and declared scope. Then perform a fresh semantic impact review.
 
 ## Allowed Paths
 
@@ -473,48 +473,23 @@ CONTRACT_TEMPLATE_EOF
 > **Notes File**: {{NOTES_FILE}}
 > **Checks File**: {{CHECKS_FILE}}
 > **Last Updated**: {{TIMESTAMP}}
-> **Recommendation**: fail
+> **Summary**:
 
-## Human Review Card
+## Semantic Impact Review
 
-- Verdict: pending
-- Change type: code-change | docs-only | ledger-closeout | migration | eval-only | delegated-run
-- Intended files changed:
-- Actual files changed:
-- Commands passed:
-- External acceptance: unavailable
-- Residual risks:
-- Reviewer action required: inspect diff and card
-- Rollback:
+- User intent:
+- Affected domains and downstream consumers:
+- State transitions and persistence/restart impact:
+- Missing impact areas or uncertainty:
+- Residual risks and recovery:
 
 ## Verification Evidence
 
-- Forge /review run:
+- Focused/full checks:
 - Commands run:
 - Manual checks:
 - Supporting artifacts:
 
-## External Acceptance Advice
-
-> **External Acceptance**: unavailable
-> **External Reviewer**:
-> **External Source**:
-> **External Started**:
-> **External Completed**:
-
-- P1 blockers:
-- P2 advisories:
-- Acceptance checklist:
-
-## Scorecard
-
-| Dimension | Score | Notes |
-|-----------|-------|-------|
-| Functionality | 0/10 | |
-| Product depth | 0/10 | |
-| Design quality | 0/10 | |
-| Code quality | 0/10 | |
-
 ## Failing Items
 
 - ...
@@ -908,7 +883,7 @@ ARCHITECTURE_INDEX_EOF
   "plan_capture": {
     "script": "scripts/capture-plan.sh",
     "sources": ["host-plan-mode", "forge-plan"],
-    "rule": "Forge /plan or host planning mode may capture decision-complete source plans into plans/plan-*.md; migrated lifecycle execution remains owned by Runtime Plan/Work state"
+    "rule": "Codex Plan mode and Waza think planning should capture decision-complete plans into plans/plan-*.md; implementation approval then projects the active approved plan through scripts/plan-to-todo.sh"
   },
   "planning": {
     "pending_orchestration_file": ".ai/harness/planning/pending.json",
@@ -916,8 +891,8 @@ ARCHITECTURE_INDEX_EOF
   },
   "guards": {
     "edit_plan_gate": "advice",
-    "edit_plan_gate_modes": ["enforce", "advice", "off"],
-    "rule": "pre-edit-guard advises when implementation lacks an active plan; execution remains available unless a real safety boundary blocks it"
+    "edit_plan_gate_modes": ["advice", "off"],
+    "rule": "pre-edit-guard may expose Plan/spec context, but Plan lifecycle never authorizes implementation; only real safety/resource boundaries block execution"
   },
   "sidecar_research": {
     "default": true,
@@ -998,16 +973,16 @@ ARCHITECTURE_INDEX_EOF
     "routing": {
       "primary": "forge",
       "optional_complex_helper": "gstack",
-      "optional_small_helper": "waza",
+      "optional_daily_helper": "waza",
       "optional_knowledge_helper": "gbrain"
     },
     "hosts": [
       "claude-code",
       "codex"
     ],
-    "mode": "optional-enhancement",
+    "mode": "optional-enhancements",
     "detection": "init-migrate",
-    "readiness_gate": "scripts/check-agent-tooling.sh --host codex",
+    "readiness_report": "scripts/check-agent-tooling.sh --host codex",
     "waza": {
       "source_repo": "tw93/Waza",
       "source_url": "https://github.com/tw93/Waza.git",
@@ -1021,12 +996,12 @@ ARCHITECTURE_INDEX_EOF
     "codex_automation_profile": {
       "required_skills": [],
       "optional_skills": ["health", "check", "mermaid"],
-      "mode": "codex-runtime-reference",
+      "mode": "optional-codex-runtime-reference",
       "source": "~/.codex/skills",
       "routes": {
-        "workflow_health": "forge:/debug",
-        "review_gate": "forge:/review",
-        "architecture_diagram": "mermaid-if-installed"
+        "workflow_health_optional": "waza:health",
+        "review_helper_optional": "waza:check",
+        "architecture_diagram_optional": "mermaid"
       },
       "vendoring_policy": "do-not-vendor-skill-body"
     },
@@ -1047,7 +1022,7 @@ ARCHITECTURE_INDEX_EOF
       "codex_config_path": "~/.codex/config.toml",
       "claude_config_path": "~/.claude.json",
       "index_dir": ".codegraph",
-      "readiness": "optional-global-cli-mcp; bundled-rh-context-backend-is-runtime-owned",
+      "readiness": "forge-bundled-backend; host-mcp-optional",
       "hook_policy": "do-not-block-hooks",
       "install_command": "bun add -g @colbymchenry/codegraph && forge tools configure codegraph --target codex --location global",
       "project_init_command": "codegraph init -i .",
@@ -1057,14 +1032,6 @@ ARCHITECTURE_INDEX_EOF
   },
   "agentic_development": {
     "routing": {
-      "small_bounded_change": "forge:/direct",
-      "planning": "forge:/plan",
-      "bug_or_regression": "forge:/debug",
-      "post_implementation_review": "forge:/review",
-      "release": "forge:/release",
-      "scale": "forge:/scale"
-    },
-    "optional_enhancements": {
       "direct": "forge:/direct",
       "plan": "forge:/plan",
       "debug": "forge:/debug",
@@ -1074,7 +1041,7 @@ ARCHITECTURE_INDEX_EOF
     },
     "due_diligence": {
       "levels": ["P1_GLOBAL_ARCHITECTURE", "P2_DATA_FLOW_TRACE", "P3_DESIGN_DECISION"],
-      "explicit_report_required_for": ["forge:/plan", "forge:/debug", "risky_refactor", "deployment", "auth_payment_data", "shared_contract"]
+      "explicit_report_required_for": ["architecture", "debug", "risky_refactor", "deployment", "auth_payment_data", "shared_contract"]
     }
   },
   "enforcement": {

package/scripts/host-temporary-cloud-mcp-e2e.sh

@@ -0,0 +1,265 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+BUN_BIN="${BUN_BIN:-bun}"
+RUNTIME_PORT="${FORGE_CLOUD_MCP_RUNTIME_PORT:-18765}"
+GATEWAY_PORT="${FORGE_CLOUD_MCP_GATEWAY_PORT:-18767}"
+HOLD_SECONDS="${FORGE_CLOUD_MCP_HOLD_SECONDS:-1500}"
+TUNNEL_ID="${FORGE_CLOUD_TUNNEL_ID:-}"
+TUNNEL_ALIAS="${FORGE_CLOUD_TUNNEL_ALIAS:-forge-cloud-ci}"
+TUNNEL_CLIENT_VERSION="${FORGE_TUNNEL_CLIENT_VERSION:-v0.0.12}"
+MCP_AUTH_MODE="${FORGE_CLOUD_MCP_AUTH_MODE:-none}"
+RUNTIME_API_KEY="${FORGE_CLOUD_TUNNEL_RUNTIME_API_KEY:-}"
+
+if [[ -z "$TUNNEL_ID" ]]; then
+  echo 'FORGE_CLOUD_TUNNEL_ID is required' >&2
+  exit 2
+fi
+if [[ -z "$RUNTIME_API_KEY" ]]; then
+  echo 'FORGE_CLOUD_TUNNEL_RUNTIME_API_KEY is required' >&2
+  exit 2
+fi
+if ! [[ "$HOLD_SECONDS" =~ ^[0-9]+$ ]]; then
+  echo 'FORGE_CLOUD_MCP_HOLD_SECONDS must be a non-negative integer' >&2
+  exit 2
+fi
+
+TMP_ROOT="$(mktemp -d "${RUNNER_TEMP:-${TMPDIR:-/tmp}}/forge-cloud-mcp-e2e.XXXXXX")"
+CONTROLLER_HOME="$TMP_ROOT/controller-home"
+SETUP_LOG="$TMP_ROOT/setup.log"
+INSTALL_JSON="$TMP_ROOT/runtime-install.json"
+GATEWAY_LOG="$TMP_ROOT/gateway.log"
+TUNNEL_ARCHIVE="$TMP_ROOT/tunnel-client.zip"
+TUNNEL_DIR="$TMP_ROOT/tunnel-client"
+TUNNEL_CLIENT="$TUNNEL_DIR/tunnel-client"
+TUNNEL_STATUS_JSON="$TMP_ROOT/tunnel-status.json"
+RUNTIME_PID=''
+GATEWAY_PID=''
+
+stop_pid() {
+  local pid="$1"
+  [[ -n "$pid" ]] || return 0
+  kill -0 "$pid" 2>/dev/null || return 0
+  kill "$pid" 2>/dev/null || true
+  for _ in $(seq 1 40); do
+    kill -0 "$pid" 2>/dev/null || return 0
+    sleep 0.25
+  done
+  kill -KILL "$pid" 2>/dev/null || true
+  for _ in $(seq 1 20); do
+    kill -0 "$pid" 2>/dev/null || return 0
+    sleep 0.1
+  done
+  return 1
+}
+
+tunnel_status_ready() {
+  "$TUNNEL_CLIENT" runtimes status "$TUNNEL_ALIAS" --json > "$TUNNEL_STATUS_JSON" 2>/dev/null || return 1
+  node - "$TUNNEL_STATUS_JSON" <<'NODE'
+const fs = require('node:fs');
+const status = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+process.exit(status.process_running === true && status.healthy === true && status.ready === true ? 0 : 1);
+NODE
+}
+
+print_tunnel_status_summary() {
+  if [[ ! -s "$TUNNEL_STATUS_JSON" ]]; then
+    printf 'FORGE_CLOUD_TUNNEL_STATUS unavailable\n' >&2
+    return
+  fi
+  node - "$TUNNEL_STATUS_JSON" <<'NODE'
+const fs = require('node:fs');
+try {
+  const status = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+  const flag = (name) => status[name] === true ? 'true' : status[name] === false ? 'false' : 'unknown';
+  console.error(`FORGE_CLOUD_TUNNEL_STATUS process_running=${flag('process_running')} healthy=${flag('healthy')} ready=${flag('ready')}`);
+} catch {
+  console.error('FORGE_CLOUD_TUNNEL_STATUS unreadable');
+}
+NODE
+}
+
+wait_for_tunnel_ready() {
+  local attempts="$1"
+  for _ in $(seq 1 "$attempts"); do
+    if tunnel_status_ready; then
+      return 0
+    fi
+    sleep 1
+  done
+  print_tunnel_status_summary
+  return 1
+}
+
+cleanup() {
+  local original_status=$?
+  local cleanup_failed=0
+  trap - EXIT INT TERM
+  if [[ -x "$TUNNEL_CLIENT" ]]; then
+    "$TUNNEL_CLIENT" runtimes stop "$TUNNEL_ALIAS" --json >/dev/null 2>&1 || cleanup_failed=1
+  fi
+  stop_pid "$GATEWAY_PID" || cleanup_failed=1
+  stop_pid "$RUNTIME_PID" || cleanup_failed=1
+  unset RUNTIME_API_KEY
+  for _ in $(seq 1 20); do
+    rm -rf "$TMP_ROOT" 2>/dev/null || true
+    [[ ! -e "$TMP_ROOT" ]] && break
+    sleep 0.25
+  done
+  if [[ -e "$TMP_ROOT" ]]; then
+    echo 'FORGE_CLOUD_MCP_CLEANUP_FAILED: temporary root remained after bounded teardown' >&2
+    cleanup_failed=1
+  fi
+  if (( cleanup_failed != 0 )); then
+    exit 1
+  fi
+  exit "$original_status"
+}
+trap cleanup EXIT INT TERM
+
+cd "$ROOT"
+
+"$BUN_BIN" bin/forge.mjs mcp setup chatgpt \
+  --user-level \
+  --controller-home "$CONTROLLER_HOME" \
+  --host 127.0.0.1 \
+  --port "$RUNTIME_PORT" \
+  --local-controller-port $((RUNTIME_PORT + 1)) \
+  --connector-port "$GATEWAY_PORT" > "$SETUP_LOG"
+
+# Package Runtime normally materializes its own persistent OAuth Connector from
+# chatgpt.localEndpoint. This temporary Secure Tunnel benchmark owns the
+# connector port itself with the explicit MCP_AUTH_MODE below, so suppress the
+# package connector in this disposable Controller Home before installation.
+MCP_LOCAL_CONFIG="$CONTROLLER_HOME/mcp/mcp.local.json"
+node - "$MCP_LOCAL_CONFIG" <<'NODE'
+const fs = require('node:fs');
+const path = process.argv[2];
+const config = JSON.parse(fs.readFileSync(path, 'utf8'));
+if (!config.chatgpt || typeof config.chatgpt.localEndpoint !== 'string') {
+  console.error('FORGE_CLOUD_MCP_SETUP_LOCAL_ENDPOINT_MISSING');
+  process.exit(1);
+}
+delete config.chatgpt.localEndpoint;
+fs.writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+NODE
+
+"$BUN_BIN" bin/forge.mjs repo register "$ROOT" \
+  --controller-home "$CONTROLLER_HOME" \
+  --json > "$TMP_ROOT/repository.json"
+
+"$BUN_BIN" bin/forge.mjs runtime service install-package \
+  --controller-home "$CONTROLLER_HOME" \
+  --host 127.0.0.1 \
+  --port "$RUNTIME_PORT" \
+  --portable > "$INSTALL_JSON"
+RUNTIME_PID="$(node -e "const x=require(process.argv[1]); const pid=x?.pid; if(!Number.isInteger(pid)||pid<=0) process.exit(2); process.stdout.write(String(pid))" "$INSTALL_JSON")"
+
+curl --fail --silent --show-error \
+  --retry 30 --retry-delay 1 --retry-connrefused \
+  "http://127.0.0.1:${RUNTIME_PORT}/ready" > "$TMP_ROOT/runtime-ready.json"
+
+FORGE_CONTROLLER_LIFECYCLE_OWNER=1 \
+  "$BUN_BIN" bin/forge.mjs mcp serve \
+  --repo "$ROOT" \
+  --controller-home "$CONTROLLER_HOME" \
+  --transport http \
+  --host 127.0.0.1 \
+  --port "$GATEWAY_PORT" \
+  --profile controller \
+  --auth "$MCP_AUTH_MODE" > "$GATEWAY_LOG" 2>&1 &
+GATEWAY_PID=$!
+
+case "$MCP_AUTH_MODE" in
+  oauth)
+    for _ in $(seq 1 30); do
+      if curl --fail --silent "http://127.0.0.1:${GATEWAY_PORT}/.well-known/oauth-authorization-server" > "$TMP_ROOT/local-oauth.json" 2>/dev/null; then
+        break
+      fi
+      if ! kill -0 "$GATEWAY_PID" 2>/dev/null; then
+        cat "$GATEWAY_LOG" >&2
+        exit 1
+      fi
+      sleep 1
+    done
+    test -s "$TMP_ROOT/local-oauth.json"
+    ;;
+  none)
+    MCP_INITIALIZE_HEADERS="$TMP_ROOT/mcp-initialize.headers"
+    MCP_INITIALIZE_BODY="$TMP_ROOT/mcp-initialize.body"
+    MCP_INITIALIZE_PAYLOAD='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"forge-cloud-readiness","version":"1"}}}'
+    for _ in $(seq 1 30); do
+      if curl --fail --silent --show-error \
+        --dump-header "$MCP_INITIALIZE_HEADERS" \
+        --output "$MCP_INITIALIZE_BODY" \
+        --request POST \
+        --header 'content-type: application/json' \
+        --header 'accept: application/json, text/event-stream' \
+        --data "$MCP_INITIALIZE_PAYLOAD" \
+        "http://127.0.0.1:${GATEWAY_PORT}/mcp" 2>/dev/null \
+        && grep -Eiq '^mcp-session-id:[[:space:]]*[^[:space:]]+' "$MCP_INITIALIZE_HEADERS" \
+        && grep -q 'forge-mcp' "$MCP_INITIALIZE_BODY"; then
+        break
+      fi
+      if ! kill -0 "$GATEWAY_PID" 2>/dev/null; then
+        cat "$GATEWAY_LOG" >&2
+        exit 1
+      fi
+      sleep 1
+    done
+    grep -Eiq '^mcp-session-id:[[:space:]]*[^[:space:]]+' "$MCP_INITIALIZE_HEADERS"
+    grep -q 'forge-mcp' "$MCP_INITIALIZE_BODY"
+    ;;
+  bearer)
+    echo 'FORGE_CLOUD_MCP_AUTH_MODE=bearer is not supported by the unauthenticated Secure Tunnel connector path; use oauth or none.' >&2
+    exit 2
+    ;;
+  *)
+    echo "unsupported FORGE_CLOUD_MCP_AUTH_MODE: $MCP_AUTH_MODE" >&2
+    exit 2
+    ;;
+esac
+
+mkdir -p "$TUNNEL_DIR"
+TUNNEL_CLIENT_ASSET="tunnel-client-${TUNNEL_CLIENT_VERSION}-linux-amd64.zip"
+curl -LfsS \
+  "https://github.com/openai/tunnel-client/releases/download/${TUNNEL_CLIENT_VERSION}/${TUNNEL_CLIENT_ASSET}" \
+  -o "$TUNNEL_ARCHIVE"
+unzip -q "$TUNNEL_ARCHIVE" -d "$TUNNEL_DIR"
+chmod +x "$TUNNEL_CLIENT" "$TUNNEL_DIR/cloudflared"
+
+FORGE_RUNTIME_API_KEY="$RUNTIME_API_KEY" \
+  "$TUNNEL_CLIENT" runtimes connect \
+  --alias "$TUNNEL_ALIAS" \
+  --tunnel-id "$TUNNEL_ID" \
+  --runtime-api-key 'env:FORGE_RUNTIME_API_KEY' \
+  --mcp-server-url "http://127.0.0.1:${GATEWAY_PORT}/mcp" \
+  --profile "$TUNNEL_ALIAS" \
+  --profile-dir "$TMP_ROOT/tunnel-profiles" \
+  --json > "$TMP_ROOT/tunnel-connect.json"
+
+if ! wait_for_tunnel_ready 30; then
+  echo 'FORGE_CLOUD_TUNNEL_NOT_READY' >&2
+  exit 1
+fi
+
+printf 'FORGE_CLOUD_TUNNEL_ID=%s\n' "$TUNNEL_ID"
+printf 'FORGE_CLOUD_TUNNEL_ALIAS=%s\n' "$TUNNEL_ALIAS"
+printf 'FORGE_CLOUD_MCP_RUN_ID=%s\n' "${GITHUB_RUN_ID:-unknown}"
+printf 'FORGE_CLOUD_MCP_RUNNER_OS=%s\n' "${RUNNER_OS:-unknown}"
+printf 'FORGE_CLOUD_MCP_RUNNER_ARCH=%s\n' "${RUNNER_ARCH:-unknown}"
+printf 'FORGE_CLOUD_MCP_AUTH_MODE=%s\n' "$MCP_AUTH_MODE"
+
+elapsed=0
+while (( elapsed < HOLD_SECONDS )); do
+  kill -0 "$RUNTIME_PID" 2>/dev/null || { echo 'runtime exited' >&2; exit 1; }
+  kill -0 "$GATEWAY_PID" 2>/dev/null || { cat "$GATEWAY_LOG" >&2; exit 1; }
+  if ! wait_for_tunnel_ready 5; then
+    echo 'FORGE_CLOUD_TUNNEL_LOST_READINESS' >&2
+    exit 1
+  fi
+  sleep 60
+  elapsed=$((elapsed + 60))
+  printf 'FORGE_CLOUD_MCP_HEARTBEAT elapsed=%ss tunnel_id=%s\n' "$elapsed" "$TUNNEL_ID"
+done

package/scripts/install-standalone-recovery.ts

@@ -44,6 +44,22 @@ const recoveryTunnelService = launchdService(
   'RECOVERY_TUNNEL_SERVICE',
 );
 if (Boolean(recoveryTunnelService) !== Boolean(recoveryPublicUrl)) throw new Error('RECOVERY_PUBLIC_URL_AND_TUNNEL_SERVICE_MUST_BE_CONFIGURED_TOGETHER');
+const primaryConnectorLocalUrl = endpointOption('--primary-connector-local-url');
+const primaryConnectorBase = launchdService(
+  option('--primary-connector-service-label'),
+  option('--primary-connector-service-plist'),
+  'RECOVERY_PRIMARY_CONNECTOR',
+);
+if (primaryConnectorLocalUrl && !primaryConnectorBase) throw new Error('RECOVERY_PRIMARY_CONNECTOR_LABEL_REQUIRED_FOR_LOCAL_URL');
+const primaryConnectorService = primaryConnectorBase
+  ? { ...primaryConnectorBase, ...(primaryConnectorLocalUrl ? { localMcpUrl: primaryConnectorLocalUrl } : {}) }
+  : undefined;
+const primaryPublicTunnelService = launchdService(
+  option('--primary-tunnel-service-label'),
+  option('--primary-tunnel-service-plist'),
+  'RECOVERY_PRIMARY_TUNNEL',
+);
+if (primaryPublicTunnelService && !primaryConnectorService) throw new Error('RECOVERY_PRIMARY_CONNECTOR_REQUIRED_FOR_PRIMARY_TUNNEL');
 
 const result = await installStandaloneRecovery({
   controllerHome,
@@ -54,6 +70,8 @@ const result = await installStandaloneRecovery({
   publicMcpUrl,
   recoveryPublicUrl,
   recoveryTunnelService,
+  primaryPublicTunnelService,
+  primaryConnectorService,
 });
 const config = result.config;
 console.log(JSON.stringify({
@@ -70,5 +88,11 @@ console.log(JSON.stringify({
     recoveryTunnelService: config.recoveryTunnelService
       ? { platform: config.recoveryTunnelService.platform, label: config.recoveryTunnelService.label, plistPath: config.recoveryTunnelService.plistPath }
       : undefined,
+    primaryConnectorService: config.primaryConnectorService
+      ? { platform: config.primaryConnectorService.platform, label: config.primaryConnectorService.label, plistPath: config.primaryConnectorService.plistPath, localMcpUrl: config.primaryConnectorService.localMcpUrl }
+      : undefined,
+    primaryPublicTunnelService: config.primaryPublicTunnelService
+      ? { platform: config.primaryPublicTunnelService.platform, label: config.primaryPublicTunnelService.label, plistPath: config.primaryPublicTunnelService.plistPath }
+      : undefined,
   },
 }, null, 2));

package/scripts/lib/project-init-lib.sh

@@ -64,8 +64,6 @@ tasks/.current.md.tmp.*
 .ai/harness/chatgpt/bridge-extension/
 .ai/harness/chatgpt/tmp/
 .ai/harness/chatgpt/sessions/
-.ai/harness/triage/*
-!.ai/harness/triage/.gitkeep
 .forge/chatgpt-browser.local.json
 .forge/chatgpt-browser.tokens.json
 .forge/interactions/
@@ -208,7 +206,7 @@ Complete this inventory before implementation. If any line is unknown, keep the
 
 - **State/progress path**:
 - **Verification evidence**:
-- **Evaluator rubric**:
+- **Impact review**:
 - **Stop condition**:
 - **Rollback surface**:
 
@@ -249,7 +247,7 @@ Describe the exact outcome this task must deliver.
 - Checks file: `.ai/harness/checks/latest.json`
 - Run snapshots: `.ai/harness/runs/`
 - Scope gate: edit only paths listed under `allowed_paths`; update this contract before widening scope.
-- Completion gate: `scripts/verify-sprint.sh` must see this contract pass, the review recommend pass, and `## External Acceptance Advice` pass or record a manual override.
+- Completion evidence: `scripts/verify-sprint.sh` reports the direct checks and declared scope. Then perform a fresh semantic impact review.
 
 ## Allowed Paths
 
@@ -302,7 +300,7 @@ exit_criteria:
   tests_pass:
     - path: tests/unit/{{TASK_SLUG}}.test.ts
   commands_succeed:
-    - bun run typecheck
+    - bun run check:type
   files_contain:
     - path: src/modules/{{TASK_SLUG}}/index.ts
       pattern: "export"
@@ -329,40 +327,24 @@ PI_TEMPLATE_REVIEW=$(cat <<'EOF_TEMPLATE_REVIEW'
 > **Notes File**: {{NOTES_FILE}}
 > **Checks File**: {{CHECKS_FILE}}
 > **Last Updated**: {{TIMESTAMP}}
-> **Recommendation**: fail
+> **Summary**:
 
-## Human Review Card
+## Semantic Impact Review
 
-- Verdict: pending
-- Change type: code-change | docs-only | ledger-closeout | migration | eval-only | delegated-run
-- Intended files changed:
-- Actual files changed:
-- Commands passed:
-- External acceptance: unavailable
-- Residual risks:
-- Reviewer action required: inspect diff and card
-- Rollback:
+- User intent:
+- Affected domains and downstream consumers:
+- State transitions and persistence/restart impact:
+- Missing impact areas or uncertainty:
+- Residual risks and recovery:
 
 ## Verification Evidence
 
-- Forge /review run:
+- Focused/full checks:
 - Commands run:
 - Manual checks:
 - Supporting artifacts:
 
-## External Acceptance Advice
-
-> **External Acceptance**: unavailable
-> **External Reviewer**:
-> **External Source**:
-> **External Started**:
-> **External Completed**:
-
-- P1 blockers:
-- P2 advisories:
-- Acceptance checklist:
-
-## Behavior Diff Notes
+## Scenario Evidence
 
 - ...
 
@@ -370,15 +352,6 @@ PI_TEMPLATE_REVIEW=$(cat <<'EOF_TEMPLATE_REVIEW'
 
 - ...
 
-## Scorecard
-
-| Dimension | Score | Notes |
-|-----------|-------|-------|
-| Functionality | 0/10 | |
-| Product depth | 0/10 | |
-| Design quality | 0/10 | |
-| Code quality | 0/10 | |
-
 ## Failing Items
 
 - ...
@@ -441,8 +414,8 @@ PI_EVALUATION_PROFILE_DEFAULT="browser-qa"
 PI_HANDOFF_PROFILE_DEFAULT="artifact-aware"
 PI_DOCUMENTATION_PROFILE_DEFAULT="minimal-agentic"
 PI_DEFAULT_LSP_PROFILE="typescript-lsp"
-PI_MINIMAL_REFERENCE_CONFIGS="harness-overview.md agentic-development-flow.md external-tooling.md sprint-contracts.md heartbeat-triage.md handoff-protocol.md document-generation.md global-working-rules.md"
-PI_FULL_REFERENCE_CONFIGS="agentic-development-flow.md ai-workflows.md changelog-versioning.md coding-standards.md development-protocol.md document-generation.md evaluator-rubric.md external-tooling.md git-strategy.md global-working-rules.md heartbeat-triage.md handoff-protocol.md harness-overview.md hook-operations.md release-deploy.md spa-day-protocol.md sprint-contracts.md workflow-orchestration.md"
+PI_MINIMAL_REFERENCE_CONFIGS="harness-overview.md agentic-development-flow.md external-tooling.md sprint-contracts.md handoff-protocol.md document-generation.md global-working-rules.md"
+PI_FULL_REFERENCE_CONFIGS="agentic-development-flow.md ai-workflows.md changelog-versioning.md coding-standards.md development-protocol.md document-generation.md evaluator-rubric.md external-tooling.md git-strategy.md global-working-rules.md handoff-protocol.md harness-overview.md hook-operations.md release-deploy.md spa-day-protocol.md sprint-contracts.md workflow-orchestration.md"
 PI_REFERENCE_CONFIG_STUB_MARKER="<!-- forge: reference-config-stub v1 -->"
 
 pi_write_file_if_apply() {
@@ -1066,7 +1039,7 @@ pi_install_helpers() {
   local target_dir="$1"
   local helpers_dir="$2"
   local mode="${3:-apply}"
-  local helper_names="${4:-new-spec.sh new-sprint.sh new-plan.sh capture-plan.sh plan-to-todo.sh contract-run.ts contract-worktree.sh ship-worktrees.sh archive-workflow.sh refresh-current-status.sh prepare-handoff.sh verify-contract.sh summarize-failures.sh verify-sprint.sh harness-trace-grade.sh sprint-backlog.sh check-task-sync.sh check-deploy-sql-order.sh check-architecture-sync.sh check-agent-tooling.sh check-context-files.sh check-brain-manifest.sh sync-brain-docs.sh check-skill-version.ts select-agent-context-blocks.sh ensure-task-workflow.sh check-task-workflow.sh maintenance-triage.sh heartbeat-triage.sh switch-plan.sh workflow-contract.ts inspect-project-state.ts migrate-workflow-docs.ts migrate-project-template.sh capability-resolver.ts architecture-event.ts capability-config.ts architecture-queue.sh archive-architecture-request.sh context-contract-sync.sh workstream-sync.sh prepare-codex-handoff.sh codex-handoff-resume.sh}"
+  local helper_names="${4:-new-spec.sh new-sprint.sh new-plan.sh capture-plan.sh plan-to-todo.sh contract-run.ts contract-worktree.sh ship-worktrees.sh archive-workflow.sh refresh-current-status.sh prepare-handoff.sh verify-contract.sh summarize-failures.sh verify-sprint.sh sprint-backlog.sh check-task-sync.sh check-deploy-sql-order.sh check-architecture-sync.sh check-agent-tooling.sh check-context-files.sh check-brain-manifest.sh sync-brain-docs.sh check-skill-version.ts select-agent-context-blocks.sh ensure-task-workflow.sh check-task-workflow.sh switch-plan.sh workflow-contract.ts inspect-project-state.ts migrate-workflow-docs.ts migrate-project-template.sh capability-resolver.ts architecture-event.ts capability-config.ts architecture-queue.sh archive-architecture-request.sh context-contract-sync.sh workstream-sync.sh prepare-codex-handoff.sh codex-handoff-resume.sh}"
   local scripts_dir="$target_dir/scripts"
   local runtime_dir="$target_dir/.ai/harness/scripts"
   local helper_name
@@ -2411,7 +2384,6 @@ pi_ensure_harness_state_surface() {
     "$target_dir/.ai/harness/worktrees" \
     "$target_dir/.ai/harness/controller" \
     "$target_dir/.ai/harness/local-jobs" \
-    "$target_dir/.ai/harness/triage" \
     "$target_dir/docs/researches" \
     "$target_dir/docs/architecture/domains" \
     "$target_dir/docs/architecture/modules" \
@@ -2433,7 +2405,6 @@ pi_ensure_harness_state_surface() {
   [[ -f "$target_dir/.ai/harness/planning/.gitkeep" ]] || : > "$target_dir/.ai/harness/planning/.gitkeep"
   [[ -f "$target_dir/.ai/harness/worktrees/.gitkeep" ]] || : > "$target_dir/.ai/harness/worktrees/.gitkeep"
   [[ -f "$target_dir/.ai/harness/runs/.gitkeep" ]] || : > "$target_dir/.ai/harness/runs/.gitkeep"
-  [[ -f "$target_dir/.ai/harness/triage/.gitkeep" ]] || : > "$target_dir/.ai/harness/triage/.gitkeep"
   [[ -f "$target_dir/tasks/workstreams/.gitkeep" ]] || : > "$target_dir/tasks/workstreams/.gitkeep"
   if [[ ! -f "$target_dir/docs/researches/README.md" ]]; then
     cat > "$target_dir/docs/researches/README.md" <<'RESEARCH_README_EOF'