@moretea-labs/forge 1.7.1 → 1.8.0

package/assets/recovery/forge-wsl-rescue

@@ -0,0 +1,271 @@
+#!/usr/bin/env bash
+# This file is installed outside a Forge checkout by
+# scripts/install-independent-windows-wsl-recovery.ts.  It deliberately has a
+# fixed command surface because it is the last-resort rescue path for Forge.
+set -euo pipefail
+
+RESCUE_ROOT="${FORGE_RESCUE_ROOT:-$HOME/.forge-recovery}"
+CONFIG_PATH="$RESCUE_ROOT/config/rescue.env"
+
+if [[ ! -r "$CONFIG_PATH" ]]; then
+  printf 'FORGE_RESCUE_CONFIG_MISSING path=%s\n' "$CONFIG_PATH" >&2
+  exit 2
+fi
+
+# shellcheck disable=SC1090
+source "$CONFIG_PATH"
+
+readonly ACTIONS=(
+  wsl_status forge_source_status controller_status
+  runtime_status runtime_start runtime_restart
+  connector_status connector_start connector_restart
+  recovery_status recovery_start recovery_restart
+  tunnel_status tunnel_start tunnel_restart
+  forge_cloud_verify full_recover watch
+)
+
+usage() {
+  printf 'Usage: %s {%s}\n' "$0" "$(IFS='|'; printf '%s' "${ACTIONS[*]}")" >&2
+  exit 64
+}
+
+require_config() {
+  local key
+  for key in WSL_DISTRO CONTROLLER_HOME SOURCE_ROOT RUNTIME_UNIT CONNECTOR_UNIT RECOVERY_UNIT TUNNEL_CLIENT TUNNEL_ALIAS TUNNEL_ID TUNNEL_RUNTIME_API_KEY_REF TUNNEL_PROFILE TUNNEL_PROFILE_DIR TUNNEL_ADMIN_PROFILE MCP_LOCAL_URL; do
+    if [[ -z "${!key:-}" ]]; then
+      printf 'FORGE_RESCUE_CONFIG_INVALID missing=%s\n' "$key" >&2
+      exit 2
+    fi
+  done
+  local user_home_prefix='/'
+  user_home_prefix+='home/'
+  case "$CONTROLLER_HOME" in
+    "${user_home_prefix}"*/.forge/controller) ;;
+    *) printf 'FORGE_RESCUE_CONFIG_INVALID controller_home=%s\n' "$CONTROLLER_HOME" >&2; exit 2 ;;
+  esac
+  case "$MCP_LOCAL_URL" in
+    http://127.0.0.1:*) ;;
+    *) printf 'FORGE_RESCUE_CONFIG_INVALID mcp_local_url=%s\n' "$MCP_LOCAL_URL" >&2; exit 2 ;;
+  esac
+}
+
+with_mutation_lock() (
+  local lock_path="$RESCUE_ROOT/locks/recovery.lock"
+  mkdir -p "$(dirname "$lock_path")"
+  exec 9>"$lock_path"
+  if ! flock -w 30 9; then
+    printf 'FORGE_RESCUE_MUTATION_LOCK_BUSY\n' >&2
+    return 75
+  fi
+  "$@"
+)
+
+unit_state() {
+  local unit="$1"
+  systemctl --user show "$unit" --no-pager \
+    -p Id -p LoadState -p ActiveState -p SubState -p MainPID -p ExecStart -p WorkingDirectory
+}
+
+unit_active() {
+  [[ "$(systemctl --user is-active "$1" 2>/dev/null || true)" == 'active' ]]
+}
+
+start_unit() {
+  systemctl --user start "$1"
+  unit_active "$1"
+}
+
+restart_unit() {
+  systemctl --user restart "$1"
+  unit_active "$1"
+}
+
+mcp_status_code() {
+  curl --silent --show-error --output /dev/null --write-out '%{http_code}' \
+    --connect-timeout 3 --max-time 8 \
+    --request POST \
+    --header 'content-type: application/json' \
+    --header 'accept: application/json, text/event-stream' \
+    --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"forge-host-rescue","version":"1"}}}' \
+    "$MCP_LOCAL_URL" 2>/dev/null || true
+}
+
+mcp_is_available() {
+  local status
+  status="$(mcp_status_code)"
+  [[ "$status" == '200' || "$status" == '401' ]]
+}
+
+wait_for_local_mcp() {
+  local attempt
+  for attempt in $(seq 1 15); do
+    mcp_is_available && return 0
+    sleep 1
+  done
+  return 1
+}
+
+tunnel_status_json() {
+  # This is an explicit inspection action. The health path below is used by
+  # automatic recovery because remote control-plane inspection can stall.
+  timeout --kill-after=2s 10s "$TUNNEL_CLIENT" runtimes status "$TUNNEL_ALIAS" --json
+}
+
+tunnel_local_ready() {
+  local health_file="$HOME/.local/state/tunnel-client/health/$TUNNEL_ALIAS.url"
+  local health_url
+  [[ -r "$health_file" ]] || return 1
+  health_url="$(<"$health_file")"
+  [[ "$health_url" =~ ^http://127\.0\.0\.1:[0-9]+$ ]] || return 1
+  [[ "$(curl --silent --show-error --output /dev/null --write-out '%{http_code}' --connect-timeout 2 --max-time 5 "$health_url/readyz" 2>/dev/null || true)" == '200' ]]
+}
+
+start_tunnel() {
+  # tunnel-client starts a long-lived tmux child. Close the rescue lock FD in
+  # that child path so a successful reconnect cannot retain the mutation lock.
+  (
+    exec 9>&-
+    "$TUNNEL_CLIENT" runtimes connect \
+      --alias "$TUNNEL_ALIAS" \
+      --tunnel-id "$TUNNEL_ID" \
+      --runtime-api-key "$TUNNEL_RUNTIME_API_KEY_REF" \
+      --admin-profile "$TUNNEL_ADMIN_PROFILE" \
+      --profile "$TUNNEL_PROFILE" \
+      --profile-dir "$TUNNEL_PROFILE_DIR" \
+      --mcp-server-url "$MCP_LOCAL_URL" \
+      --json
+  )
+}
+
+restart_tunnel() {
+  "$TUNNEL_CLIENT" runtimes stop "$TUNNEL_ALIAS" >/dev/null 2>&1 || true
+  start_tunnel
+}
+
+wsl_status() {
+  printf 'WSL_DISTRO=%s\n' "$WSL_DISTRO"
+  hostname
+  uname -a
+  systemctl --user is-system-running --wait 2>/dev/null || true
+  loginctl show-user "$USER" -p Linger -p State -p RuntimePath
+}
+
+forge_source_status() {
+  printf 'SOURCE_ROOT=%s\n' "$SOURCE_ROOT"
+  if [[ ! -d "$SOURCE_ROOT/.git" ]]; then
+    printf 'SOURCE_PRESENT=false\n'
+    return 1
+  fi
+  printf 'SOURCE_PRESENT=true\n'
+  git -C "$SOURCE_ROOT" rev-parse HEAD
+  git -C "$SOURCE_ROOT" status --short --branch
+}
+
+controller_status() {
+  printf 'CONTROLLER_HOME=%s\n' "$CONTROLLER_HOME"
+  [[ -d "$CONTROLLER_HOME" ]] && printf 'CONTROLLER_HOME_PRESENT=true\n' || { printf 'CONTROLLER_HOME_PRESENT=false\n'; return 1; }
+  [[ -f "$CONTROLLER_HOME/control-plane.sqlite" ]] && printf 'CONTROL_PLANE_DB_PRESENT=true\n' || printf 'CONTROL_PLANE_DB_PRESENT=false\n'
+  [[ -f "$CONTROLLER_HOME/runtime/releases/authority.json" ]] && printf 'RUNTIME_AUTHORITY_PRESENT=true\n' || printf 'RUNTIME_AUTHORITY_PRESENT=false\n'
+  [[ -f "$CONTROLLER_HOME/runtime/connector-service/authority.json" ]] && printf 'CONNECTOR_AUTHORITY_PRESENT=true\n' || printf 'CONNECTOR_AUTHORITY_PRESENT=false\n'
+}
+
+runtime_status() { unit_state "$RUNTIME_UNIT"; }
+runtime_start() { with_mutation_lock runtime_start_impl; }
+runtime_start_impl() { start_unit "$RUNTIME_UNIT"; runtime_status; }
+runtime_restart() { with_mutation_lock runtime_restart_impl; }
+runtime_restart_impl() { restart_unit "$RUNTIME_UNIT"; runtime_status; }
+
+connector_status() { unit_state "$CONNECTOR_UNIT"; }
+connector_start() { with_mutation_lock connector_start_impl; }
+connector_start_impl() { start_unit "$CONNECTOR_UNIT"; wait_for_local_mcp; connector_status; }
+connector_restart() { with_mutation_lock connector_restart_impl; }
+connector_restart_impl() { restart_unit "$CONNECTOR_UNIT"; wait_for_local_mcp; connector_status; }
+
+recovery_status() { unit_state "$RECOVERY_UNIT"; }
+recovery_start() { with_mutation_lock recovery_start_impl; }
+recovery_start_impl() { start_unit "$RECOVERY_UNIT"; recovery_status; }
+recovery_restart() { with_mutation_lock recovery_restart_impl; }
+recovery_restart_impl() { restart_unit "$RECOVERY_UNIT"; recovery_status; }
+
+tunnel_status() {
+  printf 'TUNNEL_ALIAS=%s\n' "$TUNNEL_ALIAS"
+  printf 'TUNNEL_ID=%s\n' "$TUNNEL_ID"
+  tunnel_local_ready && printf 'TUNNEL_LOCAL_READY=true\n' || printf 'TUNNEL_LOCAL_READY=false\n'
+  tunnel_status_json || true
+}
+tunnel_start() { with_mutation_lock tunnel_start_impl; }
+tunnel_start_impl() {
+  start_tunnel
+  tunnel_local_ready
+  printf 'TUNNEL_ALIAS=%s\nTUNNEL_ID=%s\nTUNNEL_LOCAL_READY=true\n' "$TUNNEL_ALIAS" "$TUNNEL_ID"
+}
+tunnel_restart() { with_mutation_lock tunnel_restart_impl; }
+tunnel_restart_impl() {
+  restart_tunnel
+  tunnel_local_ready
+  printf 'TUNNEL_ALIAS=%s\nTUNNEL_ID=%s\nTUNNEL_LOCAL_READY=true\n' "$TUNNEL_ALIAS" "$TUNNEL_ID"
+}
+
+forge_cloud_verify() {
+  local status=0
+  printf 'LOCAL_MCP_URL=%s\n' "$MCP_LOCAL_URL"
+  printf 'LOCAL_MCP_HTTP_STATUS=%s\n' "$(mcp_status_code)"
+  printf 'TUNNEL_ALIAS=%s\n' "$TUNNEL_ALIAS"
+  printf 'TUNNEL_ID=%s\n' "$TUNNEL_ID"
+  mcp_is_available || status=1
+  tunnel_local_ready || status=1
+  return "$status"
+}
+
+full_recover() {
+  with_mutation_lock full_recover_impl
+}
+
+full_recover_impl() {
+  local status=0
+  start_unit "$RECOVERY_UNIT" || status=1
+  start_unit "$RUNTIME_UNIT" || status=1
+  start_unit "$CONNECTOR_UNIT" || status=1
+  wait_for_local_mcp || status=1
+  if ! tunnel_local_ready; then
+    start_tunnel || status=1
+  fi
+  forge_cloud_verify || status=1
+  return "$status"
+}
+
+watch() {
+  # This is the sole long-lived mutation owner. It only reconciles the exact
+  # unit and tunnel identities recorded in its root-owned configuration.
+  while true; do
+    full_recover >/dev/null 2>&1 || true
+    sleep 30
+  done
+}
+
+main() {
+  require_config
+  case "${1:-}" in
+    wsl_status) wsl_status ;;
+    forge_source_status) forge_source_status ;;
+    controller_status) controller_status ;;
+    runtime_status) runtime_status ;;
+    runtime_start) runtime_start ;;
+    runtime_restart) runtime_restart ;;
+    connector_status) connector_status ;;
+    connector_start) connector_start ;;
+    connector_restart) connector_restart ;;
+    recovery_status) recovery_status ;;
+    recovery_start) recovery_start ;;
+    recovery_restart) recovery_restart ;;
+    tunnel_status) tunnel_status ;;
+    tunnel_start) tunnel_start ;;
+    tunnel_restart) tunnel_restart ;;
+    forge_cloud_verify) forge_cloud_verify ;;
+    full_recover) full_recover ;;
+    watch) watch ;;
+    *) usage ;;
+  esac
+}
+
+main "$@"

package/assets/reference-configs/development-protocol.md

@@ -1,21 +1,17 @@
 # Development Protocol Reference
 
-> Partially externalized: full pattern lives in default brain.
+## Authority model
 
-## Default Brain
+Forge is Controller-first. Repository files hold authored product/architecture/source/test/declarative content; mutable execution lifecycle state belongs to Controller Home. Optional host skills and prompts may improve reasoning but cannot authorize mutation or declare completion.
 
-- File vault: `brain/forge/patterns/pattern-agentic-development-protocol.md`
-- gbrain slug: `patterns/pattern-agentic-development-protocol`
+## Default flow
 
-## Repo Role
+1. Read the requirement and current source/context evidence.
+2. Establish product/architecture direction before low-level patching.
+3. For high-risk/cross-cutting work, satisfy the Engineering Design completeness contract.
+4. Use direct execution for bounded work; use durable Plan/Work only for real continuity/decomposition/recovery/external-effect needs.
+5. Implement one coherent slice, then run focused checks and exact implementation review.
+6. Reconcile blockers and terminal cleanup before delivery.
+7. If replanning, account for every unresolved predecessor obligation explicitly; never silently lose scope.
 
-The executable source of truth is still repo-local:
-
-- Active execution: `plans/plan-*.md` `## Task Breakdown` plus `tasks/contracts/`
-- Deferred goals: `tasks/todos.md`
-- Plans: `plans/`
-- Contracts: `tasks/contracts/`
-- Reviews: `tasks/reviews/`
-- Hook ownership and parity: `docs/reference-configs/hook-operations.md`
-
-Use the external pattern for broader feature, bug, and response-shaping guidance.
+Human durable repo surfaces include `docs/spec.md`, `docs/researches/`, `tasks/todos.md`, and `tasks/lessons.md`. Legacy task-contract/review/current/workstream files are migration evidence, not the modern workflow source of truth.

package/assets/reference-configs/document-generation.md

@@ -33,6 +33,6 @@ Create these only when the agent has concrete repo evidence or the user asks:
 - Keep complete workstream TODOs in `tasks/workstreams/<domain>/<capability>/`; contract blocks should link to them instead of becoming task logs.
 - Keep onboarding docs split by reader: agents read active source artifacts first; humans review the semantic-impact evidence, diff, latest checks, and recovery options first.
 - Hooks may create `docs/architecture/requests/*.md`; agents own semantic snapshots, embedded Mermaid, and optional `mermaid` HTML output.
-- Archive handled architecture requests with `.ai/harness/scripts/archive-architecture-request.sh`; keep `docs/architecture/requests/` pending-only and preserve handled requests under `docs/architecture/requests/archive/YYYY/`.
+- Resolve handled architecture requests with `.ai/harness/scripts/architecture-queue.sh resolve --file <request>`; keep `docs/architecture/requests/` pending-only and use Git history as the archive.
 - When both Mermaid and HTML exist, keep the Mermaid in Markdown as the semantic source and make the HTML link back to that Markdown source.
 - Treat `mermaid` as an external installed skill dependency at `~/.codex/skills/mermaid`; do not copy or inline its assets into generated repos.

package/assets/reference-configs/global-working-rules.md

@@ -1,6 +1,6 @@
 # Global Working Rules
 
-Use this content for user-level `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md` when a runtime needs concise but enforceable engineering behavior. Keep repo-local workflow contracts in the repo; do not paste Codex or Claude tool-compatibility maps into global files.
+Use this content for user-level `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md` as concise reasoning guidance. Prompt text improves attention but is not correctness or lifecycle authority: Forge admission, persisted contracts, scoped policy, checks, and review receipts enforce the workflow. Keep mutable Runtime/Plan/Work/session/check state in Controller Home; keep repositories for authored/declarative content.
 
 ```md
 # Global Working Rules
@@ -29,6 +29,14 @@ Before changing behavior, infer why the current shape exists: compatibility boun
 
 Do not introduce a new abstraction unless it removes real complexity, matches an existing local pattern, or protects a cross-module invariant.
 
+### P4: Cross-cutting Completeness
+
+For high-risk, architecture-changing, persistence, authorization, concurrency, external-effect, migration, or shared-contract work, do not rely on a module-local happy path. Explicitly account for semantic scope/identity, authority/single writer, authorization/trust, resource fencing, lifecycle/retention/GC, persistence/schema/backup/restore, idempotency/replay/outcome_unknown, evidence/audit/redaction, recovery/failure domain, deployment topology, capacity/backpressure/fairness, time, performance, security/privacy, portability, release/rollback, and compatibility retirement.
+
+If a successor Plan replaces an unfinished Plan, reconcile every unresolved predecessor obligation as KEEP / CHANGE / DEFER / DROP. CHANGE/DEFER/DROP require rationale; KEEP/CHANGE must identify where the successor carries the obligation. Never let a replan silently erase an acceptance criterion.
+
+Treat these prompt rules as guidance only. For Forge-managed high-risk work, the current Context Closure, Engineering Design receipt, PlanContract, authorization/resource fences, implementation review, and verification evidence are the enforceable authorities.
+
 ## Reporting
 
 For small tasks, keep P1/P2/P3 internal and report only the conclusion.

package/assets/reference-configs/harness-overview.md

@@ -1,124 +1,34 @@
 # Harness Overview
 
-This repo uses a shared long-running harness. The durable workflow lives in repo-local artifacts, not in chat memory.
+Forge uses ChatGPT (or another explicit semantic Controller) for interpretation and decisions, while Forge owns deterministic execution, durable Runtime authority, scoped authorization/resource fencing, evidence, verification, recovery, and optional continuation.
 
-## Adoption Model
+## Current state boundary
 
-Use this file as the first onboarding map after `forge adopt` installs
-or refreshes a repo. The harness gives agents three durable surfaces:
+- Repository-authored/declarative surfaces: source, tests, `docs/spec.md`, `docs/researches/`, `tasks/todos.md`, `tasks/lessons.md`, intentional human-maintained plans/docs, and root `forge.config.json`.
+- Controller Home: Requirement/Plan/Work/ControllerRound, Schedule/occurrence, Process/Job, leases/resource claims, authorization requests/grants, verification receipts, mutable Plugin configuration, Runtime/session bindings, operational evidence, recovery state, and retention metadata.
+- Provider/cache/temp data: Controller-owned provider/cache roots with explicit retention, or OS temp for disposable scratch.
 
-- **Shared standards**: `docs/spec.md`, `docs/reference-configs/`, root
-  `AGENTS.md`, and root `CLAUDE.md` explain stable product intent, coding
-  rules, and local workflow boundaries.
-- **Task contracts**: `plans/`, `tasks/contracts/`, `tasks/reviews/`, and
-  `.ai/harness/checks/` turn a request into scoped implementation work with
-  evidence-backed completion.
-- **Session cache**: `.ai/harness/session/`, `tasks/current.md`, and
-  `.ai/harness/events.jsonl` let a new agent session resume from repo state
-  without treating chat history as authority.
+A Markdown or JSON file is not repository source merely because a human can read it. Ownership, authority, lifecycle, and retention decide placement.
 
-The install is not an app scaffold or an agent gateway. It adds a reviewable
-workflow contract around an existing repo, then leaves product code ownership
-with the project.
+## Workflow
 
-## Roles
+1. **Understand**: use current raw source and bounded context evidence.
+2. **Design**: for material/high-risk changes, close the Engineering Design contract across identity/authority, authorization, resources, lifecycle, persistence, replay, evidence, recovery, topology, capacity, security, portability, migration, release, and performance.
+3. **Plan only when useful**: bounded understood work may remain direct; durable Plan/Work is for real decomposition, continuity, isolation, scheduling, recovery, or external effects.
+4. **Execute coherently**: one owner, one mutable authority, explicit resource claims, no incident-specific parallel lifecycle.
+5. **Review and verify**: implementation review is tied to exact source/workspace/check evidence and the same design/acceptance contract.
+6. **Terminalize**: release leases/worktrees/temp state, retain only policy-required evidence, and let bounded GC reclaim terminal operational data.
 
-- **Planner** updates `docs/spec.md`, researches constraints, and writes or approves `plans/plan-*.md`.
-- **Generator** implements only against the active sprint contract and the plan's `## Task Breakdown`, leaving `tasks/todos.md` as a deferred-goal ledger, and records task-local implementation judgments in `tasks/notes/<plan-stem>.notes.md`.
-- **Evaluator** runs Forge `/review`, then writes `tasks/reviews/<plan-stem>.review.md` using fresh evidence from `.ai/harness/checks/latest.json` and `.ai/harness/runs/*.json`.
+## Omission and drift control
 
-## State Flow
+Prompt instructions are advisory. Correctness comes from executable gates:
 
-1. `docs/spec.md` captures stable product intent.
-2. `plans/plan-*.md` captures a concrete execution approach.
-3. `tasks/contracts/<plan-stem>.contract.md` defines done for the active sprint.
-4. `tasks/current.md` is a tracked mainline status snapshot derived from workflow artifacts; it is not a live lock, kanban board, or implementation gate.
-5. `tasks/todos.md` is the deferred-goal ledger; the plan's `## Task Breakdown` and active contract carry sprint execution.
-6. `tasks/notes/<plan-stem>.notes.md` records design decisions, deviations, tradeoffs, open questions, and promotion candidates for this sprint only.
-7. `tasks/reviews/<plan-stem>.review.md` records evaluator judgment.
-8. `.ai/harness/policy.json` is the machine-readable workflow contract.
-9. `information_lifecycle` inside `.ai/harness/policy.json` separates notes, raw evidence, reusable assets, advisory memory, and external knowledge.
-10. `agentic_development` inside `.ai/harness/policy.json` captures product, engineering, design, bug-hunt, and review routing.
-11. `external_tooling` inside `.ai/harness/policy.json` captures host install/update defaults for gstack, Waza, gbrain, and required CodeGraph readiness.
-12. `.ai/context/capabilities.json` declares capability prefixes, contract files, architecture modules, and workstream directories.
-13. `.ai/context/context-map.json` indexes stable root context and discoverable capability context derived from the registry.
-14. `documentation` inside `.ai/harness/policy.json` keeps generated docs minimal and moves optional docs to agent-created, evidence-backed output.
-15. `lsp_profiles` inside policy and context-map files select tooling hints per capability.
-16. `worktree_strategy` inside policy tells agents when to isolate contract-level work in `codex/<slug>` worktrees, start execution through `.ai/harness/scripts/contract-worktree.sh start --plan <plan>`, and finish with Forge `/review` plus `.ai/harness/scripts/contract-worktree.sh finish`.
-17. `.ai/harness/session/continuation.md` preserves resumable state across sessions.
-18. `.ai/harness/events.jsonl` and `.ai/harness/runs/*.json` retain lightweight execution traces.
+- Context Closure makes material evidence gaps visible before design.
+- Engineering Design receipts require cross-cutting decisions for high-risk work.
+- Plan supersession must reconcile unresolved predecessor obligations as KEEP/CHANGE/DEFER/DROP.
+- Implementation review and verification bind to exact source/workspace/check identity.
+- Repository hygiene prevents modern producers from recreating repo-local Runtime state.
 
-## Session Boundaries
+## Legacy compatibility
 
-- Exploration and planning are allowed before a contract exists.
-- Before implementation, the plan and contract should both expose a concrete workflow inventory so the agent does not rediscover or guess active artifacts.
-- Implementation should prefer `docs/spec.md`, an approved plan, and an active sprint contract.
-- Claiming completion should include contract verification evidence, a run snapshot, implementation notes, and a passing Forge `/review` artifact.
-- Stopping a session should refresh `.ai/harness/session/continuation.md` for easier resume; while pending planning orchestration is open, Stop may block once to force a plan completeness self-review before execution.
-- Refresh `tasks/current.md` with `.ai/harness/scripts/refresh-current-status.sh --write --reason <reason>` only at explicit lifecycle boundaries or as a deliberate maintainer action; ordinary hooks should not dirty tracked files.
-- In non-target worktrees, read the target branch snapshot with `git show <target>:tasks/current.md` and verify stale or surprising state against the source artifacts before acting.
-- Use `docs/reference-configs/agentic-development-flow.md` for skill routing and `docs/reference-configs/external-tooling.md` for install/update commands.
-- Use `docs/reference-configs/global-working-rules.md` as the user-level Claude/Codex rule template; keep repo-local workflow contracts in repo files.
-- Externalized reference docs are indexed by `.ai/harness/brain-manifest.json` and checked by `.ai/harness/scripts/check-brain-manifest.sh`. Valuable repo docs can opt into default-brain mirroring with `sync.direction=repo-to-brain`; `post-edit-guard.sh` then calls `.ai/harness/scripts/sync-brain-docs.sh --changed <path>` for that specific file.
-- Contract-level execution should run in an isolated `codex/<task-slug>` worktree. Merge back only after the contract is fulfilled, `tasks/reviews/<plan-stem>.review.md` recommends pass, and the target worktree is clean.
-- Architecture-sensitive work also runs `scripts/check-architecture-sync.sh`: the check keeps the request index derived from `docs/architecture/requests/` and, when policy is strict, blocks finish if the current diff touches a capability with a pending architecture request at or above `architecture.gate_min_severity`.
-- Migration cleans legacy root `scripts/<forge-helper>` files only when content is identifiable as generated forge runtime; ambiguous app-owned root scripts are reported and preserved.
-
-## Documentation Profile
-
-- Default profile: `minimal-agentic`.
-- Required docs: `docs/spec.md` and `docs/architecture/index.md`.
-- Optional docs such as `docs/brief.md`, `docs/tech-stack.md`, `docs/decisions.md`, `docs/architecture.md`, and `docs/packages.md` are created only when the agent has concrete repo evidence or the user asks.
-- Root `specs/` is a legacy scaffold surface; use `docs/spec.md`, `interfaces/`, and tests instead.
-- Use `docs/reference-configs/document-generation.md` for the creation rules.
-
-## Information Lifecycle
-
-- Notes: `tasks/notes/<plan-stem>.notes.md` is task-local and auditable. It should not be treated as durable knowledge by default.
-- Current status: `tasks/current.md` is a tracked derived snapshot for orientation only. It must be regenerated from source artifacts and must not contain hand-written kanban/checklist state.
-- Evidence: `.ai/harness/checks/latest.json` is the current gate, while `.ai/harness/runs/*.json` keeps immutable verification snapshots for later audit.
-- Memory: `docs/researches/`, `tasks/lessons.md`, and gbrain are advisory. Current repo state and evidence override summaries.
-- External knowledge: `brain/<project>/*` stores long-form explanations, runbooks, decisions, and patterns. Hooks may write only explicitly opted-in `repo-to-brain` manifest entries; checks must not require gbrain or MCP.
-- Assets: policies, hooks, scripts, templates, and reference configs only change when a pattern has evidence across tasks or fixtures.
-
-## Trace Evidence
-
-`scripts/verify-sprint.sh` writes `.ai/harness/checks/latest.json` and an immutable `.ai/harness/runs/*.json` snapshot using `schema: forge-run-trace.v1`. The trace is local evidence for workflow grading, not a cloud tracing dependency.
-
-Required v1 fields:
-
-- `run_id`, `generated_at`, `status`, `exit_code`, and `source`
-- `task_profile`, `active_plan`, `contract`, `review`, `worktree`, and `branch`
-- `commands`, `guards`, `handoffs`, `files_changed`, and `allowed_paths_check`
-- `external_acceptance`, `failure_class`, and `next_step`
-
-`scripts/check-task-workflow.sh --strict` validates the latest trace shape when a non-empty latest checks file exists. Behavioral evidence comes from the selected checks and fresh controller review, not a score of plan or review metadata.
-
-## Capability Context
-
-- Do not infer agent context boundaries from physical layout globs such as `apps/*`, `packages/*`, or `services/*`.
-- Declare capabilities in `.ai/context/capabilities.json`; each capability owns prefixes, paired contract files, an architecture module, a workstream directory, and local verification hints.
-- Add selected capabilities with `forge-capability` or `bun .ai/harness/scripts/capability-config.ts add --prefix <path>` when the harness already exists and a full init/migrate/upgrade pass would be too broad.
-- Resolve edited paths through `.ai/harness/scripts/capability-resolver.ts match --path <path>`; longest prefix wins and equal-length ambiguity fails.
-- Treat `.ai/context/agent-context-blocks.txt`, `FORGE_CONTEXT_BLOCKS`, and existing nested `CLAUDE.md`/`AGENTS.md` files as migration inputs or compatibility fallbacks only.
-- Selected capabilities receive paired `CLAUDE.md` and `AGENTS.md` files so Claude Code and Codex share the same local contract.
-- Use `forge capability-context status|request|sync` to keep paired local context files aligned with the registry. The command writes only the controlled `CAPABILITY CONTEXT` block and preserves hand-authored content plus the separate architecture contract block.
-- `.ai/context/capability-source-map.json` is the optional human-edited source-map manifest for capability positioning and source pointers. Missing entries fall back to registry/architecture/workstream metadata; `--auto-fill-positioning` writes deterministic draft entries explicitly, not from hooks.
-- `.ai/harness/capability-context/` is ignored runtime queue state. Post-edit hooks may enqueue requests, and `SessionStart` only reminds the current agent to run `forge capability-context sync --pending --apply`.
-- `SessionStart` also summarizes pending architecture request cards so a resumed agent can see drift debt before claiming finish.
-
-## Initializer and Runtime Model
-
-Maintainer-facing detail on how the initializer and runtime defaults are wired.
-
-- Question flow uses **12 grouped decision points** with harness defaults inferred first.
-- Plan menu is tiered: **Core Plans (A-F)** first, **Custom Presets (G-K)** only when needed.
-- Skill routing is inspection-first: `scripts/inspect-project-state.ts`, `scripts/migrate-workflow-docs.ts`, `assets/workflow-contract.v1.json`.
-- Runtime mode is configurable with template vars: `{{RUNTIME_MODE}}`, `{{RUNTIME_PROFILE}}`, `{{RECOVERY_PROFILE}}`, `{{STATE_PROFILE}}`.
-- Question-pack source of truth: `assets/initializer-question-pack.v4.json`.
-- Generated repos default to the repo-local harness flow: `docs/spec.md -> plans/ -> tasks/contracts/ -> tasks/reviews/ -> .ai/context/context-map.json -> .ai/harness/*`.
-- Generated and self-hosted repos install `.ai/harness/workflow-contract.json` and `.ai/harness/policy.json`.
-- Generated and migrated repos route primarily through Forge modes; gstack, Waza, gbrain, and Mermaid are optional host enhancements only.
-- `forge install` bootstraps Forge-owned CLI/runtime and global Codex/Claude hook adapters. Third-party Waza/Mermaid/cross-review skills require explicit `--with-external-skills`; host CodeGraph MCP configuration is optional because Forge structural retrieval uses its bundled backend. `forge setup open/next/close` is the preferred guided first-run workflow.
-- Other external tooling stays advisory-only: `bash scripts/check-agent-tooling.sh --host both --check-updates`; Waza update checks compare upstream `tw93/Waza` `SKILL.md` hashes without running `npx skills check`; no automatic gstack, gbrain MCP, CodeGraph daemon, or provider setup.
-- Manual distillation stays repo-local: repeated corrections -> `tasks/lessons.md`; deep findings and hidden contracts -> topic-scoped `docs/researches/*.md`; sprint verification evidence -> `tasks/reviews/*.review.md`; durable capability progress -> `tasks/workstreams/`; release history -> `docs/CHANGELOG.md`.
+Older `.ai/harness/**`, `tasks/current.md`, `tasks/contracts/`, `tasks/reviews/`, `tasks/notes/`, `tasks/workstreams/`, repo-local Plugin config, and repo-local cache/session surfaces are migration inputs only when a legacy project still contains them. New projects and modern `forge.config.json` projects must not create or mirror-write them. Git history remains the source-history archive; Controller Home owns mutable Runtime history according to retention policy.

package/assets/reference-configs/hook-operations.md

@@ -7,7 +7,7 @@
 Start with the shortest truth path:
 
 1. `~/.claude/settings.json` and `~/.codex/hooks.json` wire host events into `forge-hook` (bash-shim installs use `bash ~/.forge/hook-shim.sh <hook>.sh`), with `forge hook` as the compatibility fallback.
-2. The dispatcher checks whether the current repo is opted in through `.ai/harness/workflow-contract.json` (and, for the bash shim, that its primary root is trusted in `~/.forge/trusted-repos`).
+2. The dispatcher checks whether the current repo is opted in through `forge.config.json` (legacy `.ai/harness/workflow-contract.json` remains migration-only) (and, for the bash shim, that its primary root is trusted in `~/.forge/trusted-repos`).
 3. The route registry selects the ordered hook scripts for that event and route.
 4. Hook scripts resolve **central-first**: env `FORGE_HOOK_SOURCE` (`repo` | `central` | absolute dir) → repo policy pin `"hook_source": "repo"` in `.ai/harness/policy.json` → the central copy → vendored `<repo>/.ai/hooks` fallback. The central copy is `~/.forge/hooks/` (installed by `scripts/forge.sh install`, stamped with `.version`) on the bash chain, and the packaged `assets/hooks/` inside the globally installed CLI on the `forge-hook` chain.
 

package/assets/reference-configs/sprint-contracts.md

@@ -74,13 +74,13 @@ Existing contracts without this block remain valid. `.ai/harness/scripts/verify-
 - `Active`: approved for implementation
 - `Blocked`: waiting on a missing dependency or decision
 - `Verified`: all machine checks passed; awaiting or holding review
-- `Archived`: sprint is complete or superseded
+- `Closed`: sprint is complete or superseded; terminal repo-local lifecycle artifacts are removed after exact final evidence is committed
 
 ## Review Coupling
 
 - After direct verification, use Forge `/review` for a fresh semantic impact review: user intent, affected domains, downstream consumers, missing state transitions, scenario evidence, and residual risks. The review is controller context, not a parser-owned completion gate.
 - `tasks/reviews/<plan-stem>.review.md` may cite the contract, implementation notes, checks file, run snapshot, and manual observations when they clarify the impact review.
-- `tasks/notes/<plan-stem>.notes.md` captures task-local decisions and should be archived or promoted deliberately, not left as hidden long-term memory.
+- `tasks/notes/<plan-stem>.notes.md` captures task-local decisions. Promote durable truth to canonical docs/source before closeout; terminal task-local notes are then deleted with their plan lifecycle artifacts after exact final evidence is committed.
 
 ## Worktree Lifecycle
 

package/assets/skill-version.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.7.1",
-  "templateVersion": "1.7.1",
+  "version": "1.8.0",
+  "templateVersion": "1.8.0",
   "skillName": "forge",
   "contractId": "tasks-first-harness-v1",
   "compatibility": {

package/assets/templates/helpers/architecture-event.ts

@@ -367,8 +367,8 @@ function renderRequiredFollowUp(event: ArchitectureEvent): string {
     "- When a visual explains the boundary better than prose, add or update a Mermaid fenced block in the relevant architecture module or snapshot Markdown first; that Markdown is the semantic source for LLM readers.",
     "- When a human-readable rendering is useful, generate a matching `$mermaid` architecture HTML file under `docs/architecture/diagrams/` and link it back to the Markdown semantic source.",
     "- Treat `mermaid` as an external installed skill dependency at `~/.codex/skills/mermaid`; do not copy, vendor, or inline its templates into this repo.",
-    `- If this starts or advances durable execution, run \`scripts/workstream-sync.sh ensure --block "${functionalBlock}" --request "${requestFile}"\`.`,
-    "- After the snapshot or diagram is produced, run `scripts/context-contract-sync.sh sync-latest` so the local architecture contract block links to the latest artifacts.",
+    "- Durable Requirement/Plan/Work progress belongs to Forge Controller Home; do not create repo-local workstream/session projections for this architecture event.",
+    "- After the snapshot or diagram is produced, run `scripts/context-contract-sync.sh sync-latest` so the local architecture contract block links only to authored architecture artifacts.",
   ].join("\n");
 }
 
@@ -407,7 +407,6 @@ function renderRequestCard(event: ArchitectureEvent, events: ArchitectureEvent[]
     `> **Architecture Domain**: \`${event.architecture_domain}\``,
     `> **Architecture Capability**: \`${event.architecture_capability}\``,
     `> **Architecture Module**: \`${event.architecture_module}\``,
-    `> **Workstream Directory**: \`${event.workstream_dir}\``,
     `> **Contract Files**: \`${event.contract_agents || "none"}\`, \`${event.contract_claude || "none"}\``,
     `> **Contract Sync Required**: ${Boolean(event.contract_sync_required)}`,
     `> **Spawn Recommended**: ${events.some((entry) => Boolean(entry.spawn_recommended))}`,
@@ -607,26 +606,6 @@ function metadataValue(file: string, label: string): string {
   return "";
 }
 
-function activeWorkstreams(workstreamDir: string): string {
-  if (!existsSync(workstreamDir)) return "- (none yet)";
-  const files = readdirMarkdown(workstreamDir).slice(0, 5);
-  if (files.length === 0) return "- (none yet)";
-
-  return files
-    .flatMap((file) => {
-      const status = metadataValue(file, "Status") || "unknown";
-      const currentSlice = metadataValue(file, "Current Slice") || "unknown";
-      const sourcePlan = metadataValue(file, "Source Plan") || "unknown";
-      return [
-        `- \`${file}\``,
-        `  - status: ${status}`,
-        `  - current_slice: ${currentSlice}`,
-        `  - source_plan: ${sourcePlan}`,
-      ];
-    })
-    .join("\n");
-}
-
 function readdirMarkdown(dir: string): string[] {
   try {
     return readdirSync(dir, { withFileTypes: true })
@@ -670,7 +649,6 @@ function renderContractBlock(args: Args): string {
   const architectureDomain = requireOption(args, "architectureDomain");
   const architectureCapability = requireOption(args, "architectureCapability");
   const architectureModule = requireOption(args, "architectureModule");
-  const workstreamDir = requireOption(args, "workstreamDir");
   const blockSlug = safeToken(functionalBlock);
   const latestSnapshot = findLatestMatchingFile("docs/architecture/snapshots", blockSlug, ".md");
   const latestHumanDiagram = findLatestMatchingFile("docs/architecture/diagrams", blockSlug, ".html");
@@ -707,16 +685,7 @@ function renderContractBlock(args: Args): string {
     `- Semantic diagram source: \`${semanticDiagramSource}\``,
     `- Latest human diagram: \`${latestHumanDiagram}\``,
     `- Pending architecture request: \`${requestFile}\``,
-    "",
-    "## Active Workstreams",
-    "",
-    activeWorkstreams(workstreamDir),
-    "",
-    "## Current Session Projection",
-    "",
-    `- Durable progress lives under \`${workstreamDir}\`.`,
-    "- `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.",
-    "- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.",
+    "- Runtime progress authority: Forge Controller Home Requirement/Plan/Work/Evidence; this repository block contains authored architecture context only.",
     "<!-- END ARCHITECTURE CONTRACT -->",
     "",
   ].join("\n");