@moretea-labs/forge 1.7.2 → 1.8.1

package/assets/plan-map.json

@@ -34,7 +34,7 @@
         "evaluation": "browser-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "typescript-lsp",
       "defaultTemplateVariables": {
@@ -60,7 +60,7 @@
         "evaluation": "browser-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "typescript-lsp",
       "defaultTemplateVariables": {
@@ -86,7 +86,7 @@
         "evaluation": "browser-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "typescript-lsp",
       "defaultTemplateVariables": {
@@ -112,7 +112,7 @@
         "evaluation": "command-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "typescript-lsp",
       "defaultTemplateVariables": {
@@ -138,7 +138,7 @@
         "evaluation": "browser-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "typescript-lsp",
       "defaultTemplateVariables": {
@@ -163,7 +163,7 @@
         "evaluation": "browser-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "typescript-lsp",
       "defaultTemplateVariables": {
@@ -190,7 +190,7 @@
         "evaluation": "command-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "pyright-lsp",
       "defaultTemplateVariables": {
@@ -215,7 +215,7 @@
         "evaluation": "command-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "gopls-lsp",
       "defaultTemplateVariables": {
@@ -240,7 +240,7 @@
         "evaluation": "browser-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "typescript-lsp",
       "defaultTemplateVariables": {
@@ -265,7 +265,7 @@
         "evaluation": "command-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "rust-analyzer-lsp",
       "defaultTemplateVariables": {
@@ -290,7 +290,7 @@
         "evaluation": "command-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "typescript-lsp",
       "defaultTemplateVariables": {

package/assets/plugin-registry.v1.json

@@ -4,15 +4,23 @@
     {
       "id": "desktop_operator",
       "name": "Forge Desktop Operator",
-      "version": "0.2.3",
+      "version": "0.4.5",
       "description": "Native macOS desktop automation provider for Forge.",
       "repository": "https://github.com/moretea-labs/forge-desktop-operator.git",
-      "ref": "v0.2.3",
+      "ref": "v0.4.5",
       "installer": "forge-plugin-install.mjs",
-      "providerVersion": "0.2.3",
+      "providerVersion": "0.4.5",
       "protocolVersion": "1.0",
       "platforms": [
         "darwin"
+      ],
+      "semanticCapabilities": [
+        "computer.observe.v1",
+        "computer.input.v1",
+        "computer.console.unlock.v1",
+        "computer.capture.v1",
+        "computer.element.observe.v2",
+        "computer.element.action.v2"
       ]
     },
     {

package/assets/plugin-trust-policy.v1.json

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 1,
+  "firstPartyRepositoryPrefixes": [
+    "https://github.com/moretea-labs/"
+  ]
+}

package/assets/recovery/ForgeRecovery.ps1

@@ -0,0 +1,100 @@
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true, Position = 0)]
+    [ValidateSet(
+        'host_status', 'task_status', 'task_install', 'task_run',
+        'wsl_status', 'wsl_start',
+        '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'
+    )]
+    [string]$Action
+)
+
+$ErrorActionPreference = 'Stop'
+$Root = Split-Path -Parent $PSCommandPath
+$ConfigPath = Join-Path $Root 'config.json'
+if (-not (Test-Path -LiteralPath $ConfigPath -PathType Leaf)) {
+    throw "FORGE_RESCUE_CONFIG_MISSING: $ConfigPath"
+}
+
+$Config = Get-Content -LiteralPath $ConfigPath -Raw -Encoding UTF8 | ConvertFrom-Json
+if ($Config.schemaVersion -ne 1 -or [string]::IsNullOrWhiteSpace($Config.distro) -or [string]::IsNullOrWhiteSpace($Config.wslRescuePath)) {
+    throw 'FORGE_RESCUE_CONFIG_INVALID'
+}
+$WslRescuePathPattern = '^/' + 'home/[A-Za-z0-9._-]+/\.forge-recovery/bin/forge-wsl-rescue$'
+if ($Config.distro -match "[\r\n'`"`$;&|<>]" -or $Config.wslRescuePath -notmatch $WslRescuePathPattern) {
+    throw 'FORGE_RESCUE_CONFIG_UNSAFE'
+}
+
+$Wsl = Join-Path $env:WINDIR 'System32\wsl.exe'
+$PowerShell = Join-Path $env:WINDIR 'System32\WindowsPowerShell\v1.0\powershell.exe'
+$TaskName = 'Forge Independent Recovery WSL'
+$RunKey = 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Run'
+$RunValueName = 'ForgeIndependentRecoveryWSL'
+$RunCommand = ('"' + $PowerShell + '" -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "' + $PSCommandPath + '" full_recover')
+if (-not (Test-Path -LiteralPath $Wsl -PathType Leaf)) {
+    throw "FORGE_RESCUE_WSL_MISSING: $Wsl"
+}
+
+function Invoke-WslRescue([string]$WslAction) {
+    & $Wsl --distribution $Config.distro --exec $Config.wslRescuePath $WslAction
+    if ($LASTEXITCODE -ne 0) {
+        throw "FORGE_RESCUE_WSL_ACTION_FAILED: action=$WslAction exitCode=$LASTEXITCODE"
+    }
+}
+
+switch ($Action) {
+    'host_status' {
+        [PSCustomObject]@{
+            executionEnvironment = 'WINDOWS_WSL'
+            hostname = $env:COMPUTERNAME
+            user = [Security.Principal.WindowsIdentity]::GetCurrent().Name
+            distro = $Config.distro
+            wslRescuePath = $Config.wslRescuePath
+        } | ConvertTo-Json -Depth 3
+    }
+    'task_status' {
+        $Task = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+        if ($null -ne $Task) {
+            [PSCustomObject]@{ installed = $true; method = 'scheduled_task'; taskName = $TaskName; state = [string]$Task.State; execute = $Task.Actions[0].Execute; arguments = $Task.Actions[0].Arguments } | ConvertTo-Json -Depth 4
+        } else {
+            $RunValue = (Get-ItemProperty -LiteralPath $RunKey -Name $RunValueName -ErrorAction SilentlyContinue).$RunValueName
+            [PSCustomObject]@{ installed = ($RunValue -eq $RunCommand); method = $(if ($RunValue) { 'hkcu_run' } else { 'none' }); taskName = $TaskName; runValueName = $RunValueName; identityMatches = ($RunValue -eq $RunCommand) } | ConvertTo-Json -Depth 4
+        }
+    }
+    'task_install' {
+        $ActionObject = New-ScheduledTaskAction -Execute $PowerShell -Argument ('-NoProfile -NonInteractive -ExecutionPolicy Bypass -File "' + $PSCommandPath + '" full_recover')
+        $Trigger = New-ScheduledTaskTrigger -AtLogOn
+        try {
+            $null = Register-ScheduledTask -TaskName $TaskName -Action $ActionObject -Trigger $Trigger -Description 'Forge independent Windows/WSL rescue cold-start trigger.' -Force -ErrorAction Stop
+            [PSCustomObject]@{ installed = $true; method = 'scheduled_task'; taskName = $TaskName } | ConvertTo-Json -Depth 3
+        } catch {
+            if (-not (Test-Path -LiteralPath $RunKey)) { $null = New-Item -Path $RunKey -Force }
+            Set-ItemProperty -LiteralPath $RunKey -Name $RunValueName -Value $RunCommand -Type String -Force
+            $InstalledValue = (Get-ItemProperty -LiteralPath $RunKey -Name $RunValueName -ErrorAction Stop).$RunValueName
+            if ($InstalledValue -ne $RunCommand) { throw 'FORGE_RESCUE_LOGON_TRIGGER_IDENTITY_MISMATCH' }
+            [PSCustomObject]@{ installed = $true; method = 'hkcu_run'; taskName = $TaskName; schedulerError = $_.Exception.HResult } | ConvertTo-Json -Depth 3
+        }
+    }
+    'task_run' {
+        $Task = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+        if ($null -ne $Task) {
+            Start-ScheduledTask -InputObject $Task
+            [PSCustomObject]@{ started = $true; method = 'scheduled_task'; taskName = $TaskName } | ConvertTo-Json -Depth 3
+        } else {
+            & $PowerShell -NoProfile -NonInteractive -ExecutionPolicy Bypass -File $PSCommandPath full_recover
+            if ($LASTEXITCODE -ne 0) { throw "FORGE_RESCUE_DIRECT_TRIGGER_FAILED: exitCode=$LASTEXITCODE" }
+            [PSCustomObject]@{ started = $true; method = 'direct_fixed_action'; taskName = $TaskName } | ConvertTo-Json -Depth 3
+        }
+    }
+    'wsl_start' {
+        & $Wsl --distribution $Config.distro --exec /bin/true
+        if ($LASTEXITCODE -ne 0) { throw "FORGE_RESCUE_WSL_START_FAILED: exitCode=$LASTEXITCODE" }
+        Invoke-WslRescue 'wsl_status'
+    }
+    default { Invoke-WslRescue $Action }
+}

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/agentic-development-flow.md

@@ -16,6 +16,31 @@ Forge owns the workflow contract. External host skills may improve reasoning qua
 
 Missing external skills must degrade only the named enhancement. Hooks may suggest Forge modes, but must not route correctness through a third-party skill.
 
+## Architecture Migration Delivery Transaction
+
+### Current-Task Lineage Fence
+
+Every controller round has one semantic task lineage. Resolve it from the user's current objective and the exact Work/Requirement/Plan relation before consulting repository-wide status. Global active Work is conflict metadata, not a work queue.
+
+The controller may inspect unrelated active Work only to answer four bounded questions: does it own an overlapping write path, does it hold an authority/resource needed by the current lineage, does it create a merge/release admission blocker, or does it prove the current lineage was superseded by an explicit typed transition? If none apply, the unrelated Work is ignored for the rest of the round.
+
+Never pivot into another Work's implementation, verification, review, release, cleanup, or progress accounting without explicit user intent or an explicit typed lineage transition. This prevents autonomous continuation from turning repository activity into accidental scope expansion.
+
+For Kernel/V2 migrations and similarly cross-cutting work, the primary unit of execution is a coherent delivery slice, not an issue, file, failing check, or incidental symptom.
+
+1. **Batch discovery**: gather the relevant architecture, ownership, runtime, persistence, and evidence facts in one bounded pass.
+2. **Root-cause decision**: identify the owning invariant/module and decide whether new observations are same-root scope or an independent delivery boundary.
+3. **Freeze the slice**: establish one candidate scope and acceptance contract. Same-root discoveries extend this candidate; they do not create sibling Works by default.
+4. **Coherent implementation**: implement the whole slice before broad validation. Use edit-session/savepoint state rather than per-file Git commits.
+5. **Whole-candidate review**: review authority, dependency, migration, lifecycle, recovery, and diff coherence once the implementation is source-complete.
+6. **Validation wave**: run focused behavior checks first, then canonical gates once. After repair, rerun only affected checks unless evidence invalidates the architecture.
+7. **Delivery boundary**: commit/merge once for the coherent candidate, then perform Candidate/canary/release once. Release must not begin while same-delivery source-changing Works remain active.
+8. **Terminal cleanup**: retire superseded Work/Plan/check/release state so the Controller's active inventory represents only real remaining work.
+
+Do not turn concrete incidents into an issue-by-issue patch campaign. Cluster symptoms by architecture owner and invariant before implementation. One-file commits are acceptable only when that file is itself the complete coherent delivery; file count is not the boundary.
+
+If execution exposes a defect in Forge lifecycle machinery, decide whether it is required for the current version to converge safely. If not, record a bounded post-version Plan with the violated invariant, evidence, intended owner, and acceptance criteria, then continue the current release without implementing that machinery refactor.
+
 ## Public CLI Boundary
 
 The user-facing CLI is intentionally smaller than the implementation surface:

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
@@ -9,6 +9,25 @@ Use this content for user-level `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md` w
 - Act as an engineering collaborator: finish the concrete task, verify it, then report conclusion, actual change, reason, verification, and residual risk.
 - Prefer direct execution over repeated confirmation. Stop to ask only when continuing would likely produce output contrary to the user's intent.
 
+## Delivery Transaction Discipline
+
+### Current Task Lineage Isolation
+
+- Select the current task from explicit user intent plus the exact Work/Requirement/Plan lineage. Never treat repository-wide active Work as the current task queue.
+- Global status/inventory exists for conflict, ownership, blocker, and release-admission checks only. Unrelated active Work must not trigger discovery, edits, validation, review, release, cleanup, or progress accounting in the current controller round.
+- Switch tasks only on explicit user intent or an explicit typed lineage transition. Similar files, shared broad Requirements, urgency, or mere visibility in status are not lineage.
+- Report current-task progress from the current lineage only; label unrelated repository activity separately if it materially blocks the task.
+
+For architecture migrations, self-hosting work, and other multi-file system changes, optimize for one bounded delivery transaction instead of repeated micro-lifecycles.
+
+- Batch facts first, decide the root cause/owner once, freeze the delivery scope, implement the coherent candidate, review the whole diff, run one focused validation wave, run canonical gates once, then deliver and clean up.
+- A newly observed symptom or affected file does not justify a new Work. Extend the current candidate when the same architecture invariant/root cause still owns the change; create a sibling Work only for a genuinely independent authority, security boundary, delivery, or architecture decision.
+- Do not use Git commits as scratch savepoints. Prefer Work/edit-session/savepoint state during implementation and one coherent candidate commit at the delivery boundary.
+- Do not repeatedly run baseline checks, broad suites, Candidate builds, canaries, or Runtime activation while source-changing work for the same delivery remains active. Release begins only after the source candidate is frozen.
+- After a check failure, repair the same candidate and rerun the affected check set unless the evidence invalidates the architecture; do not restart the whole lifecycle by default.
+- Retire superseded/covered Work and Plan state promptly. Active lifecycle records must describe real remaining work, not historical debris.
+- When the workflow machinery itself has a design problem, capture a bounded follow-up Plan. If the current version can still converge safely, defer that machinery refactor until after the release instead of expanding the release scope.
+
 ## Progressive Due Diligence
 
 For non-trivial engineering work, do P1/P2/P3 before design decisions or code edits.
@@ -29,6 +48,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.