@moretea-labs/forge 1.6.0 → 1.7.0

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

package/scripts/heartbeat-triage.sh

@@ -1,361 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-usage() {
-  cat <<'USAGE_EOF'
-Usage: scripts/heartbeat-triage.sh [run] [--repo PATH] [--inbox PATH] [--run-id ID] [--source manual|scheduled] [--json]
-
-Writes a heartbeat triage run to .ai/harness/triage/inbox.md. The command is
-safe for cron/loop schedulers: findings are recorded as inbox entries and do
-not make the process fail unless the runner itself is misconfigured.
-USAGE_EOF
-}
-
-command="run"
-repo="."
-inbox_path=".ai/harness/triage/inbox.md"
-run_id=""
-run_source="manual"
-json_output=0
-
-if [[ "${1:-}" == "run" ]]; then
-  shift
-elif [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
-  usage
-  exit 0
-elif [[ "${1:-}" != "" && "${1:-}" != --* ]]; then
-  echo "heartbeat-triage: unknown command: $1" >&2
-  usage >&2
-  exit 2
-fi
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --repo)
-      [[ -n "${2:-}" ]] || { echo "heartbeat-triage: --repo requires a value" >&2; exit 2; }
-      repo="$2"
-      shift 2
-      ;;
-    --inbox)
-      [[ -n "${2:-}" ]] || { echo "heartbeat-triage: --inbox requires a value" >&2; exit 2; }
-      inbox_path="$2"
-      shift 2
-      ;;
-    --run-id)
-      [[ -n "${2:-}" ]] || { echo "heartbeat-triage: --run-id requires a value" >&2; exit 2; }
-      run_id="$2"
-      shift 2
-      ;;
-    --source)
-      [[ -n "${2:-}" ]] || { echo "heartbeat-triage: --source requires a value" >&2; exit 2; }
-      run_source="$2"
-      shift 2
-      ;;
-    --json)
-      json_output=1
-      shift
-      ;;
-    --help|-h)
-      usage
-      exit 0
-      ;;
-    *)
-      echo "heartbeat-triage: unknown argument: $1" >&2
-      usage >&2
-      exit 2
-      ;;
-  esac
-done
-
-[[ "$command" == "run" ]] || { echo "heartbeat-triage: unsupported command: $command" >&2; exit 2; }
-
-repo="$(cd "$repo" 2>/dev/null && pwd -P)" || { echo "heartbeat-triage: repo not found: $repo" >&2; exit 2; }
-cd "$repo"
-
-timestamp="$(date '+%Y-%m-%dT%H:%M:%S%z')"
-if [[ -z "$run_id" ]]; then
-  run_id="heartbeat-$(date '+%Y%m%dT%H%M%S')-$$"
-fi
-safe_run_id="$(printf '%s' "$run_id" | sed -E 's/[^A-Za-z0-9._-]+/-/g')"
-
-if [[ "$inbox_path" = /* ]]; then
-  inbox_file="$inbox_path"
-else
-  inbox_file="$repo/$inbox_path"
-fi
-
-runs_dir="$repo/.ai/harness/runs"
-triage_dir="$(dirname "$inbox_file")"
-run_file="$runs_dir/${safe_run_id}-heartbeat-triage.json"
-mkdir -p "$triage_dir" "$runs_dir"
-
-json_escape() {
-  local value="$1"
-  value="${value//\\/\\\\}"
-  value="${value//\"/\\\"}"
-  value="${value//$'\n'/\\n}"
-  value="${value//$'\r'/\\r}"
-  value="${value//$'\t'/\\t}"
-  printf '%s' "$value"
-}
-
-policy_get() {
-  local jq_path="$1"
-  local default_value="$2"
-
-  if [[ -f ".ai/harness/policy.json" ]] && command -v jq >/dev/null 2>&1; then
-    local value
-    value="$(jq -r "$jq_path // empty" ".ai/harness/policy.json" 2>/dev/null || true)"
-    if [[ -n "$value" ]]; then
-      printf '%s' "$value"
-      return 0
-    fi
-  fi
-
-  printf '%s' "$default_value"
-}
-
-helper_runtime_dir="$(policy_get '.harness.helper_runtime_dir' '.ai/harness/scripts')"
-
-helper_path() {
-  local helper_name="$1"
-
-  if [[ -f "$helper_runtime_dir/$helper_name" ]]; then
-    printf '%s/%s' "$helper_runtime_dir" "$helper_name"
-    return 0
-  fi
-
-  if [[ -f "scripts/$helper_name" ]]; then
-    printf '%s/%s' "scripts" "$helper_name"
-    return 0
-  fi
-
-  printf '%s/%s' "$helper_runtime_dir" "$helper_name"
-}
-
-repo_relative() {
-  local path="$1"
-  case "$path" in
-    "$repo"/*) printf '%s' "${path#"$repo"/}" ;;
-    "$repo") printf '.' ;;
-    *) printf '%s' "$path" ;;
-  esac
-}
-
-first_line() {
-  awk 'NF { print; exit }'
-}
-
-date_plus_14_days() {
-  if date -v+14d '+%Y-%m-%d' >/dev/null 2>&1; then
-    date -v+14d '+%Y-%m-%d'
-  elif date -d '+14 days' '+%Y-%m-%d' >/dev/null 2>&1; then
-    date -d '+14 days' '+%Y-%m-%d'
-  else
-    date '+%Y-%m-%d'
-  fi
-}
-
-entry_kinds=()
-entry_statuses=()
-entry_summaries=()
-entry_details=()
-
-add_entry() {
-  entry_kinds+=("$1")
-  entry_statuses+=("$2")
-  entry_summaries+=("$3")
-  entry_details+=("$4")
-}
-
-run_workflow_check() {
-  local output status summary
-  local check_script
-  check_script="$(helper_path "check-task-workflow.sh")"
-
-  if [[ ! -f "$check_script" ]]; then
-    add_entry "workflow-check" "warning" "$check_script is missing" ""
-    return 0
-  fi
-
-  set +e
-  output="$(bash "$check_script" --strict 2>&1)"
-  status=$?
-  set -e
-
-  if [[ "$status" -eq 0 ]]; then
-    add_entry "workflow-check" "pass" "check-task-workflow.sh --strict passed" "$output"
-  else
-    summary="$(printf '%s\n' "$output" | first_line)"
-    add_entry "workflow-check" "fail" "${summary:-check-task-workflow.sh --strict failed}" "$output"
-  fi
-}
-
-extract_next_pending_from_sprint() {
-  local sprint_file="$1"
-  awk -F '|' '
-    function trim(s) {
-      gsub(/^[[:space:]]+|[[:space:]]+$/, "", s)
-      return s
-    }
-    /^## Backlog[[:space:]]*$/ { in_section = 1; next }
-    in_section && /^## / { exit }
-    !in_section { next }
-    /^\|[[:space:]]*[0-9]+[[:space:]]*\|/ {
-      idx = trim($2)
-      status = trim($3)
-      task = trim($4)
-      mode = trim($5)
-      acceptance = trim($6)
-      plan = trim($7)
-      if (status == "[ ]") {
-        printf "index: %s\ntask: %s\nmode: %s\nacceptance: %s\nplan: %s\n", idx, task, mode, acceptance, plan
-        exit
-      }
-    }
-  ' "$sprint_file"
-}
-
-find_executing_sprint() {
-  local file status
-  local sprints_dir
-  sprints_dir="$(policy_get '.sprints.dir' 'plans/sprints')"
-  [[ -d "$sprints_dir" ]] || return 1
-  while IFS= read -r file; do
-    status="$(awk '/\*\*Status\*\*:/ { sub(/^.*\*\*Status\*\*: */, ""); gsub(/\r/, ""); print; exit }' "$file" | xargs)"
-    case "$status" in
-      Executing|Approved)
-        printf '%s\n' "$file"
-        return 0
-        ;;
-    esac
-  done < <(find "$sprints_dir" -maxdepth 1 -name '*.sprint.md' -type f | sort -r)
-  return 1
-}
-
-run_sprint_next() {
-  local output status summary sprint_file task
-  local sprint_helper
-  sprint_helper="$(helper_path "sprint-backlog.sh")"
-
-  if [[ -f ".ai/harness/sprint/active-sprint" && -f "$sprint_helper" ]]; then
-    set +e
-    output="$(bash "$sprint_helper" next 2>&1)"
-    status=$?
-    set -e
-    if [[ "$status" -eq 0 ]]; then
-      task="$(printf '%s\n' "$output" | awk -F ': ' '/^task:/ { print $2; exit }')"
-      add_entry "sprint-next" "action" "next sprint task: ${task:-unknown}" "$output"
-      return 0
-    fi
-    if [[ "$status" -eq 3 ]]; then
-      add_entry "sprint-next" "pass" "no pending sprint task" "$output"
-      return 0
-    fi
-  fi
-
-  if sprint_file="$(find_executing_sprint)"; then
-    output="$(extract_next_pending_from_sprint "$sprint_file")"
-    if [[ -n "$output" ]]; then
-      task="$(printf '%s\n' "$output" | awk -F ': ' '/^task:/ { print $2; exit }')"
-      add_entry "sprint-next" "action" "next sprint task: ${task:-unknown}" "$output"
-    else
-      add_entry "sprint-next" "pass" "no pending sprint task in $sprint_file" ""
-    fi
-  else
-    add_entry "sprint-next" "info" "no active or executing sprint found" ""
-  fi
-}
-
-run_drift_requests() {
-  local details count
-  if [[ ! -d "docs/architecture/requests" ]]; then
-    add_entry "drift-requests" "pass" "no architecture request directory" ""
-    return 0
-  fi
-
-  details="$(find docs/architecture/requests -maxdepth 1 -type f ! -name '.gitkeep' | sort)"
-  if [[ -z "$details" ]]; then
-    add_entry "drift-requests" "pass" "no pending architecture drift requests" ""
-    return 0
-  fi
-
-  count="$(printf '%s\n' "$details" | sed '/^$/d' | wc -l | xargs)"
-  add_entry "drift-requests" "action" "${count} pending architecture drift request(s)" "$details"
-}
-
-write_json_snapshot() {
-  local target="$1"
-  local idx
-  {
-    echo "{"
-    printf '  "version": 1,\n'
-    printf '  "kind": "forge-heartbeat-triage",\n'
-    printf '  "run_id": "%s",\n' "$(json_escape "$run_id")"
-    printf '  "source": "%s",\n' "$(json_escape "$run_source")"
-    printf '  "generated_at": "%s",\n' "$(json_escape "$timestamp")"
-    printf '  "repo": "%s",\n' "$(json_escape "$repo")"
-    printf '  "inbox": "%s",\n' "$(json_escape "$(repo_relative "$inbox_file")")"
-    printf '  "run_file": "%s",\n' "$(json_escape "$(repo_relative "$run_file")")"
-    printf '  "adoption_review_due": "%s",\n' "$(json_escape "$adoption_review_due")"
-    echo '  "entries": ['
-    for idx in "${!entry_kinds[@]}"; do
-      [[ "$idx" -eq 0 ]] || echo ","
-      printf '    {"kind":"%s","status":"%s","summary":"%s","details":"%s"}' \
-        "$(json_escape "${entry_kinds[$idx]}")" \
-        "$(json_escape "${entry_statuses[$idx]}")" \
-        "$(json_escape "${entry_summaries[$idx]}")" \
-        "$(json_escape "${entry_details[$idx]}")"
-    done
-    echo
-    echo '  ]'
-    echo "}"
-  } > "$target"
-}
-
-write_inbox() {
-  local idx detail_line
-  if [[ ! -f "$inbox_file" ]]; then
-    {
-      echo "# Heartbeat Triage Inbox"
-      echo
-      echo "<!-- managed by scripts/heartbeat-triage.sh; append-only run log -->"
-      echo
-    } > "$inbox_file"
-  fi
-
-  {
-    echo "## Run ${run_id} - ${timestamp}"
-    echo
-    echo "- Source: ${run_source}"
-    echo "- Run snapshot: $(repo_relative "$run_file")"
-    echo "- Adoption review due: ${adoption_review_due}"
-    echo
-    echo "### Entries"
-    echo
-    for idx in "${!entry_kinds[@]}"; do
-      printf -- "- [%s] %s: %s\n" "${entry_statuses[$idx]}" "${entry_kinds[$idx]}" "${entry_summaries[$idx]}"
-      if [[ -n "${entry_details[$idx]}" ]]; then
-        while IFS= read -r detail_line; do
-          [[ -n "$detail_line" ]] || continue
-          printf '  - %s\n' "$detail_line"
-        done <<< "${entry_details[$idx]}"
-      fi
-    done
-    echo
-  } >> "$inbox_file"
-}
-
-adoption_review_due="$(date_plus_14_days)"
-run_workflow_check
-run_sprint_next
-run_drift_requests
-write_json_snapshot "$run_file"
-write_inbox
-
-if [[ "$json_output" -eq 1 ]]; then
-  cat "$run_file"
-else
-  echo "[Heartbeat] wrote $(repo_relative "$inbox_file")"
-  echo "[Heartbeat] run snapshot: $(repo_relative "$run_file")"
-fi