@moretea-labs/forge 1.5.1 → 1.7.0

package/docs/forge-autonomous-goal-loop.md

@@ -1,9 +0,0 @@
-# Forge Goal Loop
-
-Forge supports bounded goal progression through durable Goal, Work, Process, evidence, policy, and handoff records. The kernel does not recursively invent unlimited work, select arbitrary models, or bypass authorization. Semantic planning and provider selection belong to the external controller; deterministic repository and provider operations remain Forge-owned.
-
-Every continuation must have a finite objective, resource scope, budget, stop condition, and reviewable evidence. Remote or destructive effects stay separately authorized. A Schedule can wake an external Controller for an existing bounded Work; ChatGPT wakeups reuse a saved Forge browser session or explicit conversation URL when available, so conversation continuity is a transport concern rather than Kernel reasoning.
-The stable configuration path is `rh_work.schedule_*`: create one continuation policy for an already accepted Work, inspect it, pause/resume it, or trigger one bounded Occurrence. The engine re-checks Work terminality before launch and automatically disables the Schedule when the Work is complete, so users do not need to keep sending “continue” and Forge does not keep waking a model after acceptance is satisfied.
-A scheduled wake uses a short launch reservation rather than a fake Controller lease. The external model becomes owner only after its own authenticated MCP session calls `rh_work continue`; this is the identity handoff boundary between deterministic scheduling and semantic control.
-
-See [Dispatch and Agent Strategy](architecture/current/dispatch-and-agent-strategy.md), [Schedule Engine](architecture/current/automation-and-schedule-engine.md), and [Governance](architecture/current/governance.md).

package/docs/forge-provider-configuration.md

@@ -1,7 +0,0 @@
-# Forge Provider Configuration
-
-Forge keeps provider selection separate from Runtime ownership. Codex, Claude, GitHub, browser, Google Workspace, Apple, iOS, Desktop, and other adapters execute bounded contracts through stable Forge policy, Process, receipt, and audit layers.
-
-Provider credentials are supplied through supported environment or OS credential mechanisms and are never copied into repository state or chat output. Provider availability does not change the one-Runtime topology.
-
-See [Provider configuration](operations/provider-configuration.md), [Plugin baseline](architecture/current/personal-assistant-plugin-baseline.md), and [Security Model](wiki/Security-Model.md).

package/docs/operations/chatgpt-personal-assistant-runtime.md

@@ -1,83 +0,0 @@
-# ChatGPT-first Personal Assistant Runtime
-
-This runtime is designed for a local-first personal assistant where ChatGPT is the primary natural-language controller and Forge is the guarded local execution layer.
-
-## Product boundary
-
-The Local Controller should not be the main task input surface. It stores routines, inbox items, memory, approvals, audit events, device tokens, and plugin state. ChatGPT, MCP, or a GPT Action should translate natural language into one of the high-level assistant APIs.
-
-## High-level API surface
-
-Expose these endpoints to ChatGPT Actions instead of exposing every low-level plugin action:
-
-- `POST /api/assistant/intent` — submit a natural-language utterance or a ChatGPT-planned action list.
-- `GET /api/assistant/inbox` — read assistant outputs, routine results, and approval notes.
-- `GET /api/assistant/routines` — list saved routines.
-- `POST /api/assistant/routines` — create a routine from a natural-language goal.
-- `POST /api/assistant/routines/:routineId/run` — run one routine immediately.
-- `POST /api/assistant/routines/:routineId/pause` — pause a routine.
-- `POST /api/assistant/routines/:routineId/resume` — resume a routine.
-- `POST /api/assistant/routines/:routineId/delete` — soft-delete a routine.
-- `GET /api/assistant/memory` and `POST /api/assistant/memory` — read/write local preference memory.
-- `GET /api/assistant/openapi.json` — minimal OpenAPI schema for a Custom GPT Action.
-
-All `/api/*` routes still require the local controller token.
-
-## Intent modes
-
-`/api/assistant/intent` supports three modes:
-
-- `plan_only`: return the interpreted plan without submitting execution jobs.
-- `plan_then_execute`: plan and submit safe steps; block high-risk steps.
-- `execute`: submit the supplied plan directly through the same policy gate.
-
-The preferred ChatGPT flow is:
-
-1. ChatGPT understands the user request.
-2. ChatGPT asks for missing information or confirmation when needed.
-3. ChatGPT calls `/api/assistant/intent` with either the natural-language utterance or an explicit `plan`.
-4. Forge validates policy, creates durable Execution Jobs, stores an Assistant Inbox item, and returns display text.
-
-## Routine model
-
-A routine stores the user's natural-language goal rather than a traditional GUI rule form:
-
-```json
-{
-  "name": "每日邮件整理",
-  "naturalLanguageGoal": "每天早上 9 点整理过去 24 小时重要邮件，重点关注工作、API、BA、Jira、PR，用中文输出摘要。",
-  "scheduleText": "每天 09:00",
-  "dataSources": ["gmail", "calendar", "tasks"],
-  "output": "assistant_inbox",
-  "allowedActions": ["gmail.list_messages", "gmail.get_message"],
-  "forbiddenActions": ["gmail.send_message", "gmail.trash_message"]
-}
-```
-
-The first version stores the routine and can run it on demand. Automatic time-based scheduling should attach this store to the existing schedule engine in a later iteration.
-
-## Policy defaults
-
-Allowed without extra approval:
-
-- Read Gmail, Calendar, and Tasks.
-- Create a Google Task / reminder.
-- Create a Gmail draft.
-- Create a personal calendar event without attendees.
-
-Requires human approval:
-
-- Send email.
-- Trash email.
-- Cancel calendar event.
-- Reschedule calendar event.
-- Delete task.
-- Scheduled routine writes beyond explicitly allowed draft/reminder behavior.
-
-## Assistant Inbox
-
-Assistant Inbox is the user-facing result surface for routine outputs and intent execution records. ChatGPT can read it and then present the result conversationally, for example: "今天助理整理了什么？"
-
-## Current limitation
-
-The runtime does not embed a full NLP model. ChatGPT Actions should provide structure when precision matters. The local runtime includes conservative intent inference only for routine creation, reminders, and immediate mail-summary collection.

package/docs/operations/controller-desktop-plugin.md

@@ -1,112 +0,0 @@
-# Controller Desktop Plugin
-
-The `desktop` plugin is a bundled first-party Forge capability for bounded
-macOS desktop observation and application launch. It is not downloaded from a
-marketplace and it does not require a user-configured socket, executable path, or
-registration descriptor.
-
-## Architecture
-
-```text
-ChatGPT / CLI / Local UI
-  -> list_plugins / get_plugin / plugin_action_execute
-     -> existing plugin policy, schema, receipt, and audit layers
-        -> Desktop adapter (Controller process)
-           -> one-shot managed child process
-              -> JSON-lines stdio handshake and action
-                 -> bundled forge-desktop-helper.mjs
-```
-
-The Controller starts the helper on demand for one action. The child performs a
-versioned handshake, executes one bounded request, returns one structured result,
-and exits. Forge enforces request and response size limits, timeout,
-cancellation, capability negotiation, bounded diagnostics, and process cleanup.
-The helper is launched directly without a shell.
-
-This initial implementation deliberately does not provide:
-
-- plugin search, download, installation, or a marketplace;
-- arbitrary commands or user-configured helper paths;
-- sockets, background registration files, or a second plugin registry;
-- screen capture, clicks, coordinates, keyboard input, or text entry;
-- dynamic MCP tool loading.
-
-The existing static MCP tools remain the public entry point, while action schemas,
-permissions, lifecycle, health, receipts, and audit events remain authoritative in
-the existing plugin runtime.
-
-## Actions
-
-| Action | Effect | Policy |
-| --- | --- | --- |
-| `configure` | Enable or disable the bundled Desktop plugin. | Authorization required. |
-| `status` | Run a live helper handshake and return bounded readiness diagnostics. | Read-only. |
-| `observe` | Read the frontmost macOS application through `NSWorkspace`; no screen pixels are captured. | Read-only. |
-| `open_application` | Open one app by exact `app_name` or `bundle_id`. | Authorization required. |
-
-`open_application` accepts exactly one selector. It invokes `/usr/bin/open` with an
-argv array and never interpolates a shell command.
-
-## Enable on this Mac
-
-Use the controller-scoped plugin action without a repository id:
-
-```json
-{
-  "plugin_id": "desktop",
-  "action_id": "configure",
-  "request_id": "desktop-enable-1",
-  "confirm_authorization": true,
-  "arguments": {
-    "enabled": true
-  }
-}
-```
-
-Then call `get_plugin` for `desktop`, followed by `status` and `observe`.
-No ChatGPT reconnect is required because Forge reuses the existing
-`list_plugins`, `get_plugin`, and `plugin_action_execute` tool schemas. Loading a
-new Runtime revision may require the external lifecycle owner to restart the
-existing single Forge Runtime; it must not create a second Runtime or rollout slot.
-
-Configuration authority is stored under:
-
-```text
-<controller-home>/system/desktop/config.json
-```
-
-The derived manifest and registry remain Controller projections. The helper path
-is resolved from the active Forge installation and is not returned as
-user-facing configuration.
-
-## Permissions
-
-The current version does not request Screen Recording permission because it does
-not capture screenshots. Read-only observation uses AppKit `NSWorkspace` through
-the system JavaScript bridge and does not intentionally trigger Accessibility
-consent prompts. Health reports Accessibility as `not_probed` rather than claiming
-permission that has not been verified.
-
-Future click, keyboard, screenshot, or accessibility-tree actions must be added as
-separate capabilities with explicit permission probes, stronger policy, redaction,
-and fault-injection coverage. They must not be inferred from this initial plugin.
-
-## Failure behavior
-
-The plugin fails closed when:
-
-- it is disabled;
-- the platform is not macOS;
-- the bundled helper is missing;
-- the helper handshake or capability set is incompatible;
-- a response is malformed or exceeds the output bound;
-- the helper crashes, times out, or is cancelled;
-- `open_application` receives zero or multiple selectors.
-
-A helper failure is surfaced as a structured `PLUGIN_MANAGED_PROCESS_*` or
-`PLUGIN_DESKTOP_*` error through the existing plugin receipt and audit path.
-
-
-## Immutable release packaging
-
-Whole-Runtime releases include `forge-desktop-helper.mjs` as a required, hashed sibling artifact. The Desktop adapter resolves it from the validated active Runtime release identity, then uses argv/source candidates only as development compatibility fallbacks. It launches the helper with the same trusted Node resolver used by the bounded Node bridge path; it does not execute the compiled Forge binary as a JavaScript interpreter. Release validation fails closed when the helper is missing or empty, and plugin health reports helper and trusted-runtime availability without returning either local path.

package/docs/operations/gmail-assistant-routines.md

@@ -1,186 +0,0 @@
-# Durable Gmail Assistant Routines
-
-Gmail Assistant Routines use the existing Repository Schedule Engine and durable Execution Jobs. They do not introduce a second cron service.
-
-## Execution flow
-
-1. Creating a confirmed Assistant Routine persists the Routine and creates one Repository Schedule.
-2. The Schedule stores an IANA timezone, a five-field local cron expression, and a bounded catch-up window.
-3. A due occurrence creates one `assistant_routine_execute` Runtime Job with an exclusive Routine resource claim.
-4. The Runtime Job reads Gmail incrementally, hydrates bounded message bodies, advances the per-Routine cursor, analyzes the bounded message set, creates structured action proposals, and writes a final Assistant Inbox report.
-5. Proposals either remain pending for explicit approval or match a previously authorized Standing Grant.
-6. Every approved or Standing-Grant action runs as a separate durable plugin Job. Schedule execution never becomes remote-write authorization.
-7. Sending mail and moving mail to Trash retain their existing strong-confirmation requirements and are never Standing-Grant eligible.
-
-## Google OAuth setup
-
-Create a Google OAuth client with this loopback redirect URI:
-
-```text
-http://127.0.0.1:8766/oauth/google/callback
-```
-
-Expose the client configuration only through the managed secret environment:
-
-- `FORGE_GOOGLE_CLIENT_ID`
-- `FORGE_GOOGLE_CLIENT_SECRET`
-
-The `FORGE_GOOGLE_WORKSPACE_CLIENT_ID` and `FORGE_GOOGLE_WORKSPACE_CLIENT_SECRET` aliases are also supported.
-
-Call `workspace_auth_login_prepare` for `gmail` or `google-workspace`, then open the returned authorization URL. The request uses OAuth Authorization Code flow with PKCE, a random one-time state, a ten-minute expiry, and a loopback-only callback. Redirect URIs outside `127.0.0.1` or `localhost`, unexpected callback paths, and scopes outside the Gmail/Calendar/Tasks allowlist are rejected.
-
-The callback exchanges the authorization code and stores only the refresh token in macOS Keychain. Access and refresh tokens are never returned through MCP, written to repository files, or written to normal Controller runtime state. The transient PKCE verifier is stored under Controller Home with restrictive permissions and is redacted after the callback is consumed.
-
-The current secure persistence backend is macOS Keychain. Non-macOS hosts must provide a supported credential-store adapter or use managed environment credentials.
-
-## Credential refresh and readiness
-
-A configured access token is not considered provider-verified until a real Google API request succeeds. Before that first successful probe, health reports `live_token_unverified`.
-
-After OAuth setup, Controller restarts can reload the refresh token from Keychain. When no valid cached access token exists, or Gmail returns HTTP 401/403, the provider performs one refresh-token exchange and at most one request retry. A failed refresh is classified as `PLUGIN_AUTH_FAILED`; the Routine Run becomes `auth_required` and Assistant Inbox requests reauthorization.
-
-Managed environment credentials remain compatible:
-
-- `FORGE_GMAIL_ACCESS_TOKEN`
-- `FORGE_GMAIL_REFRESH_TOKEN`
-- `FORGE_GMAIL_CLIENT_ID`
-- `FORGE_GMAIL_CLIENT_SECRET`
-- `FORGE_GOOGLE_WORKSPACE_ACCESS_TOKEN`
-- `FORGE_GOOGLE_WORKSPACE_REFRESH_TOKEN`
-- `FORGE_GOOGLE_WORKSPACE_CLIENT_ID`
-- `FORGE_GOOGLE_WORKSPACE_CLIENT_SECRET`
-
-## Scheduling semantics
-
-Routine schedule text is normalized when the Routine is created. The first implementation recognizes daily and weekday expressions with an optional `HH:mm` or Chinese `点/时` form. Examples:
-
-- `每天 09:00`
-- `每周一 08:30`
-- `Monday 07:00`
-
-The normalized Schedule preserves the IANA timezone, so daylight-saving transitions remain aligned to local wall-clock time. Missed runs catch up at most once inside the configured window because the occurrence key is derived from the local scheduled minute rather than the actual wake-up minute.
-
-## Gmail History cursor
-
-Each Routine stores an independent cursor under `.forge/assistant/gmail-cursors.json`:
-
-- last successful collection time
-- bounded processed-message ID set
-- Gmail `historyId`
-- a bounded History or query continuation token while a backlog is still being drained
-
-After the initial query, Gmail History is the primary incremental source. An expired History ID falls back to a five-minute-overlap Gmail query. Collection reads at most five pages, 100 IDs, and 50 full messages per run. If the page or hydration limit is reached, the history cursor does not advance; a continuation token or the original window is retained so the next run drains the remaining messages without loss.
-
-## Optional model analysis
-
-The model layer is optional. When it is disabled, unavailable, times out, or returns malformed output, the Routine completes with the deterministic rules engine rather than failing.
-
-Configure an OpenAI-compatible endpoint with:
-
-- `FORGE_ASSISTANT_MODEL_PROVIDER=openai-compatible`
-- `FORGE_ASSISTANT_MODEL_ENDPOINT`
-- `FORGE_ASSISTANT_MODEL`
-- `FORGE_ASSISTANT_MODEL_API_KEY`
-
-For the exact official hosts, provider-specific keys are also supported:
-
-- `api.openai.com` may use `OPENAI_API_KEY`
-- `api.deepseek.com` may use `FORGE_DEEPSEEK_API_KEY` or `DEEPSEEK_API_KEY`
-
-A custom endpoint never receives `OPENAI_API_KEY` or a DeepSeek key. It must use the dedicated `FORGE_ASSISTANT_MODEL_API_KEY`. Endpoints must use HTTPS, except loopback HTTP used for a local model.
-
-Optional budgets:
-
-- `FORGE_ASSISTANT_MODEL_TIMEOUT_MS`
-- `FORGE_ASSISTANT_MODEL_MAX_MESSAGES`
-- `FORGE_ASSISTANT_MODEL_MAX_INPUT_CHARS`
-- `FORGE_ASSISTANT_MODEL_MAX_OUTPUT_TOKENS`
-
-The provider requests strict structured JSON, validates the result locally, and maps only these proposal types:
-
-- Gmail draft creation
-- Google Task creation
-- Gmail archive
-- Gmail mark read or unread
-
-Email contents are untrusted input. Instructions in an email, quoted thread, signature, link, or attachment description cannot expand the action allowlist or request tools, credentials, files, commands, or additional permissions. Security, authentication, billing, incident, production, quota, and repository-permission messages are protected from model-generated archive actions.
-
-The deterministic fallback also uses Gmail's `CATEGORY_PROMOTIONS` label as a high-confidence archive signal (`0.98`) for non-protected messages. Marketing/newsletter keyword matches remain a lower-confidence fallback (`0.7`). The protected-message veto wins over both signals, so a security, authentication, billing, production, incident, quota, or permission-related message is never proposed for automatic archive merely because Gmail classified it as Promotions.
-
-Use `assistant_model_readiness` or `GET /api/assistant/model` to inspect the redacted configuration and budgets. Model credentials and raw secrets are never returned.
-
-## Action proposals and approval
-
-Routine analysis persists structured proposals under `.forge/assistant/action-proposals.json`. Each proposal records:
-
-- Routine and Run identity
-- target plugin/action and bounded arguments
-- supporting Gmail message IDs
-- sender/subject context and protected-message status
-- reason, confidence, risk, expiry, and execution status
-- the separate Execution Job created after approval
-
-Use `assistant_action_proposals` to list or inspect proposals. Use `assistant_action_proposal_resolve` with `decision=approve` or `decision=reject`. MCP approval requires `confirm_authorization=true`; strong-confirmation actions also require the action's exact confirmation text. Local Controller exposes equivalent authenticated proposal endpoints.
-
-Approval is idempotent. Repeating approval returns the same Execution Job rather than creating another remote write. Proposal audit records preserve whether approval came from MCP, Local UI, or a Standing Grant.
-
-## Standing Grants
-
-A Standing Grant is an explicit, expiring pre-authorization for one hardcoded low-risk action. It is not a general plugin permission.
-
-Eligible actions are limited to:
-
-- `gmail.create_draft`
-- `gmail.archive_message`
-- `gmail.mark_message_read`
-- `gmail.mark_message_unread`
-- `google_tasks.create_task`
-
-A grant must include at least one constraint:
-
-- Routine ID allowlist
-- sender/domain allowlist
-- required subject fragment
-
-It also declares minimum proposal confidence, maximum executions per Routine Run, and expiry. Automatic draft grants additionally require a sender allowlist. Security-protected messages cannot be auto-archived.
-
-Create a grant through `assistant_standing_grant_create` or `POST /api/assistant/standing-grants` with explicit authorization. List it through `assistant_standing_grants`; revoke it through `assistant_standing_grant_revoke` or the Local Controller revoke endpoint.
-
-Example: automatically archive at most one high-confidence newsletter from a trusted sender per run:
-
-```json
-{
-  "plugin_id": "gmail",
-  "action_id": "archive_message",
-  "sender_allowlist": ["news@example.com"],
-  "subject_contains": ["newsletter"],
-  "min_confidence": 0.9,
-  "max_per_run": 1,
-  "expires_in_days": 30,
-  "confirm_authorization": true
-}
-```
-
-Standing-Grant executions use a dedicated `standing-grant` origin and a defense-in-depth plugin allowlist. Modifying the stored grant cannot enable send, Trash, permanent deletion, calendar cancellation/rescheduling, or task deletion. Multiple matching grants cannot submit the same proposal twice, and retries preserve each grant's per-run budget.
-
-## Safety boundary
-
-Scheduled Routines may:
-
-- list and read Gmail messages
-- classify and summarize collected mail
-- create bounded draft, task, archive, and read/unread proposals
-- execute an eligible proposal only when a matching active Standing Grant already exists
-- write Assistant Inbox reports
-
-Scheduled Routines may not:
-
-- send mail
-- move mail to Trash
-- permanently delete mail
-- cancel or reschedule meetings
-- delete tasks
-- execute instructions embedded in mail
-- open arbitrary attachments or links
-
-A proposal is evidence for a later authorized action, not implicit authorization. A Standing Grant authorizes only its exact action and constraints. The Schedule origin never becomes authorization for a remote write.

package/docs/operations/personal-assistant-operator-guide.md

@@ -1,61 +0,0 @@
-# Personal assistant operator guide
-
-This runtime is intended to be used with ChatGPT as the primary control plane. The Local Controller is the execution, policy, audit, and persistence layer.
-
-## Recommended daily path
-
-1. Ask ChatGPT for the goal in natural language.
-2. ChatGPT calls the high-level assistant API or MCP tools.
-3. The runtime plans safe plugin actions, submits durable jobs, and writes results into Assistant Inbox.
-4. High-risk actions stay blocked until explicit human confirmation.
-
-## Readiness check
-
-Use `assistant_readiness` or `GET /api/assistant/readiness` before relying on the assistant.
-
-The report separates:
-
-- live Google capability
-- mock-only capability
-- disabled plugins
-- routine, inbox, and memory state
-- recommended next actions
-
-Mock mode proves the execution path only. It does not read real Gmail, Calendar, or Tasks data.
-
-## Gmail read self-test
-
-A low-risk Gmail read test can be submitted through either:
-
-- `plugin_action_execute` with `gmail.list_messages`
-- `POST /api/assistant/self-test/gmail-read`
-- `POST /api/assistant/intent` with an utterance such as `测试读取最近一周 Gmail`
-
-When Gmail is in mock mode, the test returns deterministic mock messages. For real Gmail, configure the plugin with provider `google-workspace` and set one of the supported token environment variables documented by the plugin health message.
-
-## Cleanup workflow
-
-Use `runtime_cleanup_preview` or `POST /api/assistant/maintenance/cleanup-preview` first. It is non-destructive.
-
-Use cleanup apply only after reviewing the preview:
-
-- `runtime_cleanup_apply` with `confirm_cleanup=true`
-- `POST /api/assistant/maintenance/cleanup-apply` with `confirmCleanup=true`
-
-Cleanup is limited to explicit Forge candidates:
-
-- old `Forge-*` temp directories that are not referenced by running processes
-- terminal local jobs, when explicitly included
-- historical attention acknowledgements, when explicitly included
-
-Do not use cleanup apply as a substitute for reviewing active jobs, active leases, or running workers.
-
-## What still needs real productization
-
-The current runtime can route assistant intents and run safe data collection jobs. A full personal-assistant product still needs:
-
-- real OAuth/token broker and refresh support
-- wall-clock routine scheduling
-- model-backed summarization of collected data
-- approval summaries for risky actions
-- cleanup apply integration in a dedicated maintenance UI

package/docs/operations/provider-configuration.md

@@ -1,31 +0,0 @@
-# Provider configuration and routing
-
-Forge does not require or privilege a specific model vendor. A fresh installation builds neutral routing from provider kind, declared capabilities, health, and the configured provider priority. Providers with the same priority use the provider id only as a deterministic tie-breaker.
-
-## Where configuration lives
-
-The Controller GUI and the JSON files below edit the same controller-scoped configuration:
-
-- `<controllerHome>/global/provider-config.json`: enable/disable providers, priority, model and non-secret API settings.
-- `<controllerHome>/global/executor-routing.json`: explicit provider order for each task intent.
-- `<controllerHome>/global/provider-secrets.json`: locally stored API credentials. This file is outside the repository and must never be committed.
-
-Opening the GUI or reading configuration does not rewrite these files. Existing routing and priority choices remain authoritative across upgrades.
-
-## Precedence
-
-Provider selection applies these rules in order:
-
-1. Per-request provider preferences and allow/deny constraints.
-2. An explicit order or default in `executor-routing.json`, including changes made in the GUI routing editor.
-3. Neutral generated defaults based on provider kind and `provider-config.json` priority.
-4. Availability, enablement, authentication, live-call policy, safety gates, and required capabilities.
-5. A ChatGPT handoff packet when no direct provider can safely run.
-
-An explicit routing order intentionally overrides the general provider priority. The GUI shows both controls so users can decide whether task types follow a specific route or the general provider preference. Use **Use automatic routing** in the routing panel to remove explicit overrides and resume generated priority-based routing; do not delete the whole controller configuration.
-
-## Personal preferences
-
-Maintainers and users may place Grok, Codex, Claude, an API provider, or another registered provider first in their own Controller configuration. Those preferences belong under `controllerHome`; they are not open-source defaults and are not copied into the repository.
-
-Remote API calls remain double-gated: the provider must be enabled/configured in the GUI and `FORGE_ENABLE_LIVE_MODEL_PROVIDERS` must explicitly allow live calls. Without both, the API provider is proposal-only.

package/scripts/harness-trace-grade.sh

@@ -1,150 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-usage() {
-  cat <<'USAGE_EOF'
-Usage: scripts/harness-trace-grade.sh --run <trace.json> [--repo <repo>] [--strict]
-USAGE_EOF
-}
-
-run_file=""
-repo="."
-strict=0
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --run)
-      run_file="${2:-}"
-      shift 2
-      ;;
-    --repo)
-      repo="${2:-.}"
-      shift 2
-      ;;
-    --strict)
-      strict=1
-      shift
-      ;;
-    --help|-h)
-      usage
-      exit 0
-      ;;
-    *)
-      echo "Unknown argument: $1" >&2
-      usage
-      exit 1
-      ;;
-  esac
-done
-
-[[ -n "$run_file" ]] || { usage >&2; exit 1; }
-[[ -f "$run_file" ]] || { echo "Trace run file not found: $run_file" >&2; exit 1; }
-command -v jq >/dev/null 2>&1 || { echo "jq is required for harness trace grading" >&2; exit 1; }
-
-if REPO_ROOT="$(cd "$repo" && pwd -P 2>/dev/null)"; then
-  :
-else
-  echo "Repo path not found: $repo" >&2
-  exit 1
-fi
-
-results_file="$(mktemp)"
-trap 'rm -f "$results_file"' EXIT
-: > "$results_file"
-
-record() {
-  local id="$1"
-  local passed="$2"
-  local message="$3"
-  jq -n \
-    --arg id "$id" \
-    --argjson passed "$passed" \
-    --arg message "$message" \
-    '{id: $id, passed: $passed, message: $message}' >> "$results_file"
-}
-
-trace_get() {
-  local query="$1"
-  jq -r "$query // empty" "$run_file"
-}
-
-schema="$(trace_get '.schema')"
-active_plan="$(trace_get '.active_plan')"
-task_profile="$(trace_get '.task_profile')"
-review_card_verdict="$(trace_get '.review.card.verdict')"
-review_card_change_type="$(trace_get '.review.card.change_type')"
-review_card_rollback="$(trace_get '.review.card.rollback')"
-commands_count="$(jq '.commands | if type == "array" then length else 0 end' "$run_file")"
-outside_count="$(jq '.allowed_paths_check.outside | if type == "array" then length else 0 end' "$run_file")"
-allowed_status="$(trace_get '.allowed_paths_check.status')"
-
-if [[ "$schema" == "forge-run-trace.v1" ]]; then
-  record "schema.v1" true "trace schema is forge-run-trace.v1"
-else
-  record "schema.v1" false "trace schema is ${schema:-missing}"
-fi
-
-if [[ -n "$active_plan" && -f "$REPO_ROOT/$active_plan" ]]; then
-  record "active_plan.resolves" true "active plan resolves: $active_plan"
-else
-  record "active_plan.resolves" false "active plan does not resolve: ${active_plan:-missing}"
-fi
-
-case "$task_profile" in
-  code-change|docs-only|ledger-closeout|migration|eval-only|delegated-run)
-    record "contract_profile.valid" true "contract profile is valid: $task_profile"
-    ;;
-  *)
-    record "contract_profile.valid" false "contract profile is invalid: ${task_profile:-missing}"
-    ;;
-esac
-
-if [[ "$review_card_verdict" == "pass" ]]; then
-  record "review_card.pass" true "Human Review Card verdict is pass"
-else
-  record "review_card.pass" false "Human Review Card verdict is ${review_card_verdict:-missing}"
-fi
-
-if [[ -n "$review_card_change_type" && "$review_card_change_type" == "$task_profile" ]]; then
-  record "review_card.change_type" true "Human Review Card change type matches task profile"
-else
-  record "review_card.change_type" false "Human Review Card change type ${review_card_change_type:-missing} does not match task profile ${task_profile:-missing}"
-fi
-
-rollback_token="$(printf '%s' "$review_card_rollback" | sed -E 's/[;,].*$//; s/[[:space:]].*$//; s/^[[:space:]]+//; s/[[:space:]]+$//' | tr '[:upper:]' '[:lower:]')"
-case "$rollback_token" in
-  ""|tbd|todo|n/a|na|none|unknown|unavailable|pending|...)
-    record "review_card.rollback" false "Human Review Card rollback is missing or not concrete"
-    ;;
-  *)
-    record "review_card.rollback" true "Human Review Card rollback is concrete"
-    ;;
-esac
-
-if [[ "$commands_count" -gt 0 ]] && jq -e '.commands[]? | select((.command // "") | length > 0)' "$run_file" >/dev/null; then
-  record "commands.present" true "commands evidence is present"
-else
-  record "commands.present" false "commands evidence is missing"
-fi
-
-if [[ "$outside_count" -eq 0 && "$allowed_status" == "pass" ]]; then
-  record "allowed_paths.clean" true "no changed file is outside allowed paths"
-else
-  record "allowed_paths.clean" false "allowed_paths status is ${allowed_status:-missing}; changed files outside allowed paths: $outside_count"
-fi
-
-failed="$(jq -s '[.[] | select(.passed == false)] | length' "$results_file")"
-total="$(jq -s 'length' "$results_file")"
-status="pass"
-[[ "$failed" -eq 0 ]] || status="fail"
-
-jq -s \
-  --arg status "$status" \
-  --arg run "$run_file" \
-  --argjson total "$total" \
-  --argjson failed "$failed" \
-  '{status: $status, run: $run, total: $total, failed: $failed, graders: .}' "$results_file"
-
-if [[ "$strict" -eq 1 && "$failed" -ne 0 ]]; then
-  exit 1
-fi