@moretea-labs/forge 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -4,7 +4,34 @@ All notable public Forge changes are recorded here. Release entries are tied to
 
 ## Unreleased
 
-No unreleased public changes are currently recorded.
+## 1.6.0 - 2026-08-16
+
+### Architecture V2 and execution governance
+
+- Complete the V2 Direct / bounded Work / Plan execution model, including isolated Work materialization, authoritative finalization, dead-Plan recovery, duplicate-writer prevention, and safer Work validation.
+- Decouple durable Work ownership from transient MCP transport sessions so scheduled and interactive ChatGPT execution can resume against stable controller leases and checkout identity.
+- Add bounded impact context and CodeGraph-aware retrieval while keeping routing, semantic context, and repository authority converged on one deterministic control path.
+
+### Performance and Runtime
+
+- Reduce controller hot-path overhead with canonical repository-root reuse, exact-file retrieval fast paths, Runtime proxy session reuse, batched Process identity probes, narrower service claims, and read-only SQLite diagnostics.
+- Preserve resumable Process/check execution while improving persisted-check retry idempotency, stale-process handling, worktree reconciliation, and release/runtime identity safety.
+- Keep the stable 19-tool ChatGPT surface while moving more domain behavior behind typed capability and plugin contracts.
+
+### Automation and plugins
+
+- Add Forge-native ChatGPT workflows, schedules, Work-bound browser watchers, cross-session workflow attribution, and more reliable ChatGPT mode/reasoning selection.
+- Add trusted external-plugin registration lifecycle support and official Forge Figma Bridge catalog installation; retire the bundled desktop helper in favor of the external provider boundary.
+- Improve plugin scope/compatibility handling, browser URL behavior, image artifact delivery, Gmail Unicode subjects, and automation history/configuration surfaces.
+
+## 1.5.1 - 2026-08-13
+
+### ChatGPT Secure Tunnel and package setup
+
+- Make `--tunnel auto` prefer OpenAI Secure MCP Tunnel instead of silently selecting an installed public-ingress CLI. Cloudflare, Tailscale, existing HTTPS, and deferred remote access remain explicit fallbacks.
+- Add a package-managed loopback OAuth Gateway for ChatGPT alongside the bearer-only Canonical Runtime, and persist the local OAuth endpoint in user-level MCP configuration so Secure Tunnel never targets the internal Runtime directly.
+- Accept modern ChatGPT `server/discover` probing with the correct legacy fallback response, detect tunnel runtimes by `tunnel_id` rather than a hard-coded alias, and prefer an existing repository Controller Home during setup reconciliation.
+- Clarify that the ChatGPT App/connector owns application/tool identity while Secure Tunnel owns transport, document migration from Cloudflare/HTTPS, and add the supported npm update flow (`npm install -g @moretea-labs/forge@latest` then `forge setup next`).
 
 ## 1.5.0 - 2026-08-13
 

package/DESIGN.md

@@ -218,9 +218,14 @@ Dark, persistent and quiet. It contains Forge identity, grouped navigation, and
 ### Command bar
 Each route owns a compact command bar: eyebrow, title, one-line purpose, refreshed time and route actions. `Open ChatGPT` remains globally available but visually secondary.
 
+## Page composition rules
+Each workspace has **one dominant information region** and at most one contextual secondary region. Pages are not collections of cards; layout, typography, aligned columns, whitespace and hairlines establish hierarchy before enclosure.
+
+Collections use rows or tables. A selected entity uses one contextual detail pane. Configuration uses titled sections with field rows. Metrics stay inline or in compact definition rows unless direct metric comparison is the task. Normal state is visually neutral; semantic color is reserved for exceptions, attention and explicit interaction.
+
 ## Core component grammar
 ### Metric strip
-Overview may show at most four coarse operational facts in one horizontal strip. Metrics share one surface and divider rhythm; they are not separate cards.
+Metric strips are exceptional. Use them only when comparing coarse operational facts is itself useful; never make equal metric cards the default page composition.
 
 ### Data list
 Primary scanning surface for Work, Capabilities and Repositories. Rows use hairline separators and bounded one-line context.
@@ -236,7 +241,7 @@ Use a 7px dot plus short text. Filled badges are exceptional.
 
 ## Page grammar
 ### Overview
-Command bar, one four-column metric strip, a deduplicated attention list capped to actionable groups, and a compact persistent-goals summary. No prompt composer, run timeline or grid of equal cards.
+Overview is a **cross-workspace status and attention surface**, not a collection manager. Keep it single-column and lightweight: first surface a bounded, deduplicated Needs attention list across Work, Automations, Capabilities, Repositories and System; then show one compact Workspace summary row for each owning workspace. Overview does not enumerate ordinary Work, group content by repository, expose collection filters or open a detail pane. It routes the user to the owning workspace for management. Healthy state stays compact and neutral. Activity feeds require authoritative event semantics and must never be inferred from `updatedAt` or other incidental timestamps. No prompt composer, run timeline, repository portfolio, equal metric grid or decorative posture hero.
 
 ### Automations
 Use a configuration-first table with Name, Schedule, Scope, Delivery, Status, Last and Next; filters Enabled / Paused / Attention / All; selected detail pane with exact source and Run/Pause/Resume. Never duplicate report body.

package/README.md

@@ -44,11 +44,11 @@ forge setup configure --controller chatgpt --tunnel auto
 forge setup next
 ```
 
-Setup persists progress and guides the selected path through the user-level Package Runtime, remote connectivity, controller registration, and connection verification. For ChatGPT, prefer **OpenAI Secure MCP Tunnel** when your organization supports it; Cloudflare Tunnel, Tailscale Funnel, an existing HTTPS `/mcp` URL, or deferred remote access remain alternatives. Local Codex/Claude controllers do not need a tunnel.
+Setup persists progress and guides the selected path through the user-level Package Runtime, remote connectivity, controller registration, and connection verification. For ChatGPT, `--tunnel auto` now means **OpenAI Secure MCP Tunnel first**: Forge keeps the Canonical Runtime private, installs a loopback OAuth Gateway for ChatGPT, and lets the official `tunnel-client` carry MCP traffic outbound to OpenAI. Cloudflare Tunnel, Tailscale Funnel, an existing HTTPS `/mcp` URL, or deferred remote access remain explicit fallbacks when Secure Tunnel is unavailable. Local Codex/Claude controllers do not need a tunnel. The ChatGPT App/connector is the application identity; Secure Tunnel is only its network transport, so switching transport does not create a second Forge tool schema.
 
-Then follow [Install and start](docs/tutorials/01-install-and-start.md) and [Connect ChatGPT](docs/tutorials/02-connect-chatgpt.md). A repository is optional during initial setup; add one later with `forge adopt --repo /path/to/your-project`.
+Then follow [Install and start](docs/tutorials/01-install-and-start.md) and [Connect ChatGPT](docs/tutorials/02-connect-chatgpt.md). A repository is optional during initial setup; add one later with `forge adopt --repo /path/to/your-project`. Upgrade an existing install with `npm install -g @moretea-labs/forge@latest`, verify with `forge --version`, then run `forge setup next` to reconcile newer Runtime/connector setup contracts.
 
-For a reviewed source checkout: `git clone https://github.com/moretea-labs/forge.git && cd forge && npm ci --ignore-scripts --no-audit --no-fund && npm install -g . --omit=optional --no-audit --no-fund`.
+For a reviewed source checkout: `git clone https://github.com/moretea-labs/forge.git && cd forge && bun install --frozen-lockfile && npm install -g . --omit=optional --no-audit --no-fund`.
 
 ## Built in, and extensible
 
@@ -58,7 +58,7 @@ Forge ships typed local/browser/desktop/iOS/GitHub/Gmail/Calendar/Tasks/App Stor
 
 Local read/write grants are explicit and expiring; remote or destructive effects are distinguished from ordinary local work; high-impact actions require stronger confirmation. Full Access reduces repetitive prompts for normal work without removing the hard boundaries around secrets, destructive actions, and outside-workspace access. See [Security](SECURITY.md) and the [Security Model](docs/wiki/Security-Model.md).
 
-**Docs:** [Wiki](docs/wiki/Home.md) · [Support](SUPPORT.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md). Current stable release: `1.5.0`; stable installs use npm `latest`.
+**Docs:** [Wiki](docs/wiki/Home.md) · [Support](SUPPORT.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md). Current stable release: `1.6.0`; stable installs use npm `latest`.
 
 ---
 <a id="zh-cn"></a>
@@ -101,12 +101,12 @@ forge setup configure --controller chatgpt --tunnel auto
 forge setup next     # 按每次显示的 Next 动作继续
 ```
 
-远程主控的 setup 会继续引导 Package Runtime、远程连接、主控配置和连接验证；ChatGPT 在组织支持时优先 **OpenAI Secure MCP Tunnel**，也可选 Cloudflare Tunnel、Tailscale Funnel、已有 HTTPS `/mcp`，或暂缓远程连接。本地 Codex/Claude 主控不需要 tunnel，也不会配置未选择的 CLI。
+远程主控的 setup 会继续引导 Package Runtime、远程连接、主控配置和连接验证；对 ChatGPT，`--tunnel auto` 现在明确表示 **优先 OpenAI Secure MCP Tunnel**。Forge 保持 Canonical Runtime 私有，并安装一个仅监听 loopback 的 OAuth Gateway，再由官方 `tunnel-client` 出站连接 OpenAI。只有 Secure Tunnel 不可用时才显式选择 Cloudflare Tunnel、Tailscale Funnel、已有 HTTPS `/mcp` 或暂缓远程连接。本地 Codex/Claude 主控不需要 tunnel。ChatGPT App/connector 是应用身份，Secure Tunnel 只是网络传输层，因此切换网络不会产生另一套 Forge 工具 schema。
 
-继续阅读[安装与启动](docs/tutorials/01-install-and-start.zh-CN.md)和[连接 ChatGPT](docs/tutorials/02-connect-chatgpt.zh-CN.md)。仓库不是首次 setup 的前置条件，需要开发能力时再运行 `forge adopt --repo /path/to/your-project`。源码安装：`git clone https://github.com/moretea-labs/forge.git && cd forge && npm ci --ignore-scripts --no-audit --no-fund && npm install -g . --omit=optional --no-audit --no-fund`。
+继续阅读[安装与启动](docs/tutorials/01-install-and-start.zh-CN.md)和[连接 ChatGPT](docs/tutorials/02-connect-chatgpt.zh-CN.md)。仓库不是首次 setup 的前置条件，需要开发能力时再运行 `forge adopt --repo /path/to/your-project`。已安装用户升级：`npm install -g @moretea-labs/forge@latest`，确认 `forge --version` 后运行 `forge setup next` 让新版 setup 自动补齐 Runtime/connector 配置。源码安装：`git clone https://github.com/moretea-labs/forge.git && cd forge && bun install --frozen-lockfile && npm install -g . --omit=optional --no-audit --no-fund`。
 
 Forge 内置本机、Browser、Desktop、iOS、GitHub、Gmail、Calendar、Tasks、App Store Connect、Resend 等类型化能力；公开 Provider 目录还有 **Forge Desktop Operator / Forge Design / Personal Knowledge Assistant**。详见[功能清单](docs/operations/features.zh-CN.md)与[插件管理](docs/forge-plugin-management.md)。
 
 安全上，普通本地修改、远程影响、破坏性操作、密钥和工作区外访问是不同边界；Full Access 不会取消高风险确认。详见[安全说明](SECURITY.md)和[安全模型](docs/wiki/Security-Model.md)。
 
-**文档：** [Wiki](docs/wiki/Home.md) · [支持](SUPPORT.md) · [贡献](CONTRIBUTING.md) · [更新日志](CHANGELOG.md)。当前稳定版为 `1.5.0`，稳定安装使用 npm `latest`。
+**文档：** [Wiki](docs/wiki/Home.md) · [支持](SUPPORT.md) · [贡献](CONTRIBUTING.md) · [更新日志](CHANGELOG.md)。当前稳定版为 `1.6.0`，稳定安装使用 npm `latest`。

package/README.zh-CN.md

@@ -52,15 +52,17 @@ forge setup configure --controller chatgpt --tunnel auto
 forge setup next     # 按每次显示的 Next 动作继续
 ```
 
-`forge setup` 会持久化进度。远程主控会继续经过 Package Runtime、远程连接、主控配置和连接验证；ChatGPT 在组织支持时优先 **OpenAI Secure MCP Tunnel**，也可选择 Cloudflare Tunnel、Tailscale Funnel、已有 HTTPS `/mcp` 或暂缓远程连接。本地主控 Codex/Claude 不需要 tunnel。
+`forge setup` 会持久化进度。对 ChatGPT，`--tunnel auto` 现在明确表示 **优先 OpenAI Secure MCP Tunnel**：Forge 保持 Canonical Runtime 私有，安装一个仅监听 loopback 的 OAuth Gateway，再由官方 `tunnel-client` 通过出站连接接入 OpenAI。Secure Tunnel 不可用时，再显式选择 Cloudflare Tunnel、Tailscale Funnel、已有 HTTPS `/mcp` 或暂缓远程连接。本地主控 Codex/Claude 不需要 tunnel。ChatGPT App/connector 是应用身份，Secure Tunnel 是网络传输层；切换 tunnel 不会创建另一套 Forge 工具 schema。
 
 接着阅读：[安装与启动](docs/tutorials/01-install-and-start.zh-CN.md) · [连接 ChatGPT](docs/tutorials/02-connect-chatgpt.zh-CN.md) · [第一个仓库任务](docs/tutorials/03-first-repository-task.zh-CN.md)。仓库不是首次 setup 的前置条件；需要时再 `forge adopt --repo /path/to/your-project`。
 
+已安装用户升级：`npm install -g @moretea-labs/forge@latest` → `forge --version` → `forge setup next`。
+
 从源码安装已审查 checkout：
 
 ```bash
 git clone https://github.com/moretea-labs/forge.git && cd forge
-npm ci --ignore-scripts --no-audit --no-fund
+bun install --frozen-lockfile
 npm install -g . --omit=optional --no-audit --no-fund
 ```
 
@@ -76,4 +78,4 @@ Forge 把读取、普通本地写入、远程操作、破坏性操作、工作
 
 [中文文档中心](docs/README.zh-CN.md) · [Wiki](docs/wiki/Home.md) · [SUPPORT.md](SUPPORT.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [CHANGELOG.md](CHANGELOG.md)
 
-当前稳定版本是 `1.5.0`，稳定安装使用 npm `latest`。
+当前稳定版本是 `1.6.0`，稳定安装使用 npm `latest`。

package/THIRD_PARTY_NOTICES.md

@@ -1,6 +1,6 @@
 # Third-party notices
 
-This inventory covers the direct runtime and development dependencies declared by `@moretea-labs/forge@1.5.0`.
+This inventory covers the direct runtime and development dependencies declared by `@moretea-labs/forge@1.6.0`.
 
 License values come from `package-lock.json` where available. For lock entries without a license field, the declared license was verified from package metadata during release preparation. This file is informational and does not replace the license text distributed by each dependency.
 

package/assets/hooks/pre-edit-guard.sh

@@ -79,17 +79,13 @@ is_workflow_surface_path() {
 
 edit_plan_gate_mode() {
   local mode="${FORGE_EDIT_PLAN_GATE:-}"
-  if [[ -z "$mode" ]]; then
-    mode="$(workflow_policy_get '.guards.edit_plan_gate' 'advice')"
-  fi
-  printf '%s' "$mode"
+  [[ -z "$mode" ]] && mode="$(workflow_policy_get '.guards.edit_plan_gate' 'advice')"
+  [[ "$mode" == "off" ]] && printf 'off' || printf 'advice'
 }
 
-# Edit-layer plan gate: the deterministic enforcement point for "no
-# implementation edits without an approved plan". The prompt layer only
-# advises (natural-language intent guessing is unreliable); this gate keys
-# off path + plan state. Modes: advice (default) | enforce | off, via
-# FORGE_EDIT_PLAN_GATE or policy .guards.edit_plan_gate.
+# Plan/spec lifecycle is Controller context, never write authorization. This
+# compatibility hook may advise; real enforcement remains path/private-surface,
+# authorization, lease and fencing boundaries.
 run_edit_plan_gate() {
   local mode gate_plan gate_status
   mode="$(edit_plan_gate_mode)"
@@ -99,31 +95,13 @@ run_edit_plan_gate() {
 
   if [[ ! -f "docs/spec.md" ]]; then
     echo "[SpecGuard] Implementation edit without docs/spec.md: $FILE_PATH"
-    if [[ "$mode" == "advice" ]]; then
-      echo "[SpecGuard] Advisory: run bash scripts/new-spec.sh and capture stable product intent."
-    else
-      hook_structured_error \
-        "SpecGuard" \
-        "Implementation edit to $FILE_PATH without docs/spec.md." \
-        "Run bash scripts/new-spec.sh and capture stable product intent before implementing." \
-        "missing_artifact"
-      exit 2
-    fi
+    echo "[SpecGuard] Advisory: capture stable product intent when it materially helps this change."
   fi
 
   gate_plan="$(get_active_plan || true)"
   if [[ -z "$gate_plan" || ! -f "$gate_plan" ]]; then
     echo "[PlanStatusGuard] No active plan covers implementation edit: $FILE_PATH"
-    if [[ "$mode" == "advice" ]]; then
-      echo "[PlanStatusGuard] Advisory: capture the approved plan with bash scripts/capture-plan.sh --slug <slug> --title <title> --status Approved --execute"
-    else
-      hook_structured_error \
-        "PlanStatusGuard" \
-        "Implementation edit to $FILE_PATH without an active plan." \
-        "Capture the approved planning output with bash scripts/capture-plan.sh --slug <slug> --title <title> --status Approved --execute, or set policy .guards.edit_plan_gate to advice/off for this repo." \
-        "missing_artifact"
-      exit 2
-    fi
+    echo "[PlanStatusGuard] Advisory: use a Plan only when ChatGPT has chosen staged/dependency coordination."
     return 0
   fi
 
@@ -131,16 +109,7 @@ run_edit_plan_gate() {
   case "$gate_status" in
     Draft|Annotating)
       echo "[PlanStatusGuard] Plan status is '$gate_status' in $gate_plan; implementation edit: $FILE_PATH"
-      if [[ "$mode" == "advice" ]]; then
-        echo "[PlanStatusGuard] Advisory: complete the annotation cycle and move the plan to Approved before implementation."
-      else
-        hook_structured_error \
-          "PlanStatusGuard" \
-          "Implementation edit to $FILE_PATH while plan status is $gate_status in $gate_plan." \
-          "Complete the annotation cycle and move the plan to Approved before implementation." \
-          "state_violation"
-        exit 2
-      fi
+      echo "[PlanStatusGuard] Advisory: this Plan is not execution-ready; ordinary Direct work remains independent."
       ;;
   esac
 }

package/assets/hooks/prompt-guard.sh

@@ -768,7 +768,7 @@ render_prompt_guard_action() {
       exit 0
       ;;
     plan_status_no_active_block)
-      echo "[PlanStatusGuard] Advisory: No active plan found in plans/. Implementation edits will be blocked at the edit layer until a plan is captured."
+      echo "[PlanStatusGuard] Legacy advisory: no active Plan found. Ordinary implementation is not gated by Plan presence."
       echo "[PlanStatusGuard] Capture the approved planning output with: bash scripts/capture-plan.sh --slug <slug> --title <title> --status Approved --execute"
       echo "[PlanStatusGuard] If there is no captured planning output yet, run: bash scripts/ensure-task-workflow.sh --slug <slug> --title <title>"
       exit 0
@@ -780,7 +780,7 @@ render_prompt_guard_action() {
       exit 0
       ;;
     plan_status_not_approved_block)
-      echo "[PlanStatusGuard] Advisory: plan status is '$plan_status' in $active_plan. Complete the annotation cycle and move the plan to Approved; implementation edits are blocked at the edit layer until then."
+      echo "[PlanStatusGuard] Legacy advisory: plan status is '$plan_status' in $active_plan. This does not authorize or block ordinary implementation."
       exit 0
       ;;
     evidence_contract_block)

package/assets/plugin-registry.v1.json

@@ -1,8 +1,59 @@
 {
   "schemaVersion": 1,
   "plugins": [
-    {"id":"desktop_operator","name":"Forge Desktop Operator","version":"0.2.1","description":"Native macOS desktop automation provider for Forge.","repository":"https://github.com/moretea-labs/forge-desktop-operator.git","ref":"v0.2.1","installer":"forge-plugin-install.mjs","platforms":["darwin"]},
-    {"id":"design","name":"Forge Design","version":"0.3.0","description":"Repository-native deterministic design workspace and design.md provider.","repository":"https://github.com/moretea-labs/forge-design.git","ref":"v0.3.0","installer":"forge-plugin-install.mjs","platforms":["darwin","linux","win32"]},
-    {"id":"personal_knowledge","name":"Personal Knowledge Assistant","version":"0.2.1","description":"Local-first personal knowledge retrieval, memory, safe-write and analysis provider.","repository":"https://github.com/moretea-labs/personal-knowledge-assistant.git","ref":"v0.2.1","installer":"forge-plugin-install.mjs","platforms":["darwin","linux","win32"]}
+    {
+      "id": "desktop_operator",
+      "name": "Forge Desktop Operator",
+      "version": "0.2.1",
+      "description": "Native macOS desktop automation provider for Forge.",
+      "repository": "https://github.com/moretea-labs/forge-desktop-operator.git",
+      "ref": "v0.2.1",
+      "installer": "forge-plugin-install.mjs",
+      "providerVersion": "0.2.0",
+      "protocolVersion": "1.0",
+      "platforms": [
+        "darwin"
+      ]
+    },
+    {
+      "id": "design",
+      "name": "Forge Design",
+      "version": "0.3.0",
+      "description": "Repository-native deterministic design workspace and design.md provider.",
+      "repository": "https://github.com/moretea-labs/forge-design.git",
+      "ref": "v0.3.0",
+      "installer": "forge-plugin-install.mjs",
+      "platforms": [
+        "darwin",
+        "linux",
+        "win32"
+      ]
+    },
+    {
+      "id": "personal_knowledge",
+      "name": "Personal Knowledge Assistant",
+      "version": "0.2.1",
+      "description": "Local-first personal knowledge retrieval, memory, safe-write and analysis provider.",
+      "repository": "https://github.com/moretea-labs/personal-knowledge-assistant.git",
+      "ref": "v0.2.1",
+      "installer": "forge-plugin-install.mjs",
+      "platforms": [
+        "darwin",
+        "linux",
+        "win32"
+      ]
+    },
+    {
+      "id": "figma",
+      "name": "Forge Figma Bridge",
+      "version": "0.3.0",
+      "description": "Direct Figma Plugin API bridge for typed canvas inspection, editing and native review capture.",
+      "repository": "https://github.com/moretea-labs/forge-figma-bridge.git",
+      "ref": "v0.3.0",
+      "installer": "forge-plugin-install.mjs",
+      "platforms": [
+        "darwin"
+      ]
+    }
   ]
 }

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

@@ -18,7 +18,7 @@ Generated host adapter commands carry a 30 second timeout; long-running work bel
 
 `UserPromptSubmit.default` dispatches to the active `prompt-guard.sh` resolved by the central-first hook source decision. For ordinary repos that means the packaged/user-level runtime; `.ai/hooks/prompt-guard.sh` is active only when the repo pins `"hook_source": "repo"`. The shell layer parses host prompt JSON, reads workflow files, performs capture side effects, and renders host-safe output; it pipes `{"prompt": ...}` into `forge-hook prompt-guard-decide`, which owns every prompt-text intent classifier (Unicode-aware, in `src/cli/hook/prompt-intents.ts`) plus the intent x state decision table and returns one verdict JSON line (action, intent facts, derived strings). If the engine is unreachable or predates the protocol, the prompt layer degrades to a one-shot advisory instead of guessing; there is no shell fallback decision table.
 
-Prompt-layer plan/spec/contract gates are advisory routing only. `PreToolUse.edit` keeps real path/scope and private-surface safety checks authoritative, while the plan-state gate defaults to `advice`; repositories may opt into `enforce` or `off` through policy `.guards.edit_plan_gate` or `FORGE_EDIT_PLAN_GATE`. Done-claim gates block only on real failed or missing completion evidence, not on workflow ceremony.
+Prompt-layer plan/spec/contract signals are advisory context only. `PreToolUse.edit` keeps real path/scope and private-surface safety checks authoritative; Plan/spec lifecycle is never a write-authorization gate. Legacy `.guards.edit_plan_gate=enforce` or `FORGE_EDIT_PLAN_GATE=enforce` is accepted as advisory compatibility, while `off` suppresses the guidance. Done-claim compatibility gates remain separate until goal-acceptance/evidence convergence removes workflow ceremony from completion.
 
 If you are asking "which hook file should I edit?", default to `assets/hooks/` for product changes and mirror into `.ai/hooks/` only for this self-host repo or another repo that pins `"hook_source": "repo"`; runtime pickup outside repo-pinned development happens on the next `install`/CLI upgrade because hooks resolve central-first.
 After installing or refreshing `~/.codex/hooks.json`, open Codex Settings and mark the user-level hook config as trusted; otherwise Codex will not execute it.

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

@@ -79,11 +79,11 @@ Existing contracts without this block remain valid. `.ai/harness/scripts/verify-
 ## Review Coupling
 
 - A contract is not truly done until the matching review file records a passing recommendation.
-- `tasks/reviews/<plan-stem>.review.md` should be filled from Waza `/check` after verification and cite the contract, implementation notes, checks file, run snapshot, `## External Acceptance Advice`, and any manual observations.
+- `tasks/reviews/<plan-stem>.review.md` should be filled from Forge `/review` after verification and cite the contract, implementation notes, checks file, run snapshot, `## External Acceptance Advice`, and any manual observations.
 - `tasks/notes/<plan-stem>.notes.md` captures task-local decisions and should be archived or promoted deliberately, not left as hidden long-term memory.
 
 ## Worktree Lifecycle
 
 - When `.ai/harness/policy.json` has `worktree_strategy.auto_for_contract_tasks: true`, `.ai/harness/scripts/plan-to-todo.sh --plan <approved-plan>` starts a linked `codex/<slug>` worktree instead of mutating the primary tree.
 - Execute the sprint in that linked worktree. The primary worktree remains a merge target and must stay clean before merge-back.
-- After implementation, run Waza `/check` so the review file recommends pass, record passing `## External Acceptance Advice` from the peer reviewer or a concrete manual override, then run `.ai/harness/scripts/contract-worktree.sh finish`. The finish command gates on external acceptance before `verify-sprint.sh`, commits the branch, and fast-forwards the target branch only when the target worktree is clean.
+- After implementation, run Forge `/review` so the review file recommends pass, record passing `## External Acceptance Advice` from the peer reviewer or a concrete manual override, then run `.ai/harness/scripts/contract-worktree.sh finish`. The finish command gates on external acceptance before `verify-sprint.sh`, commits the branch, and fast-forwards the target branch only when the target worktree is clean.

package/assets/skill-version.json

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

package/assets/templates/helpers/ensure-task-workflow.sh

@@ -916,8 +916,8 @@ ARCHITECTURE_INDEX_EOF
   },
   "guards": {
     "edit_plan_gate": "advice",
-    "edit_plan_gate_modes": ["enforce", "advice", "off"],
-    "rule": "pre-edit-guard advises when implementation lacks an active plan; execution remains available unless a real safety boundary blocks it"
+    "edit_plan_gate_modes": ["advice", "off"],
+    "rule": "pre-edit-guard may expose Plan/spec context, but Plan lifecycle never authorizes implementation; only real safety/resource boundaries block execution"
   },
   "sidecar_research": {
     "default": true,

package/assets/templates/helpers/sprint-backlog.sh

@@ -21,11 +21,11 @@ Usage:
 
 Program-level sprint backlog helper. PRDs live in plans/prds/ as the upper
 planning layer; sprints live in plans/sprints/ as ordered execution backlogs.
-Each backlog row is expanded with $think before the existing plan -> contract
+Each backlog row is expanded with /plan before the existing plan -> contract
 -> worktree flow. tasks/todos.md stays the deferred-goal ledger.
 
 start-task reserves the next (or named) pending backlog row and can capture a
-thin plan seed. The coding agent must still use `$think` to expand the row into
+thin plan seed. The coding agent must still use `/plan` to expand the row into
 a decision-complete plan before code edits.
 --sprint overrides the active-sprint marker (still confined to the sprints
 dir), which finish back-fill uses inside worktrees where the runtime marker
@@ -218,7 +218,7 @@ render_sprint_file() {
 
 Program-level sprint container. The Source PRD summary and ordered backlog
 decompose product intent into task-contract slices; each backlog row is a
-long-task waypoint that must be expanded with `$think` before code edits.
+long-task waypoint that must be expanded with `/plan` before code edits.
 `tasks/todos.md` stays the deferred-goal ledger and never carries this backlog.
 
 ## PRD
@@ -740,12 +740,12 @@ Deliver backlog task \`${target_task}\` so that the acceptance line holds: ${tar
 
 ## Planning Expansion
 
-Before editing code, use \`\$think\` to expand this sprint row into a decision-complete implementation plan. The \`\$think\` pass should read the sprint file, preserve the acceptance line, name concrete files or commands, and produce the detailed \`plans/plan-*.md\` body that drives contract execution.
+Before editing code, use \`/plan\` to expand this sprint row into a decision-complete implementation plan. The \`/plan\` pass should read the sprint file, preserve the acceptance line, name concrete files or commands, and produce the detailed \`plans/plan-*.md\` body that drives contract execution.
 
 ## Task Breakdown
 
-- [ ] Run \`\$think\` for backlog task \`${target_task}\` using sprint \`${sprint_file}\` and acceptance: ${target_acceptance}
-- [ ] Capture the approved Forge \`/plan\` output with \`scripts/capture-plan.sh --source forge-plan --source-ref sprint:${sprint_file}#${target_task}\`
+- [ ] Run \`/plan\` for backlog task \`${target_task}\` using sprint \`${sprint_file}\` and acceptance: ${target_acceptance}
+- [ ] Capture the approved \`/plan\` output with \`scripts/capture-plan.sh --source forge-plan --source-ref sprint:${sprint_file}#${target_task}\`
 - [ ] Verify acceptance: ${target_acceptance}
 BODY_EOF
 

package/docs/architecture/current/automation-and-schedule-engine.md

@@ -160,11 +160,17 @@ Deterministic rules are preferred for:
 
 Semantic analysis remains external-controller-owned. Forge does not invent the next product or code decision inside the Schedule Engine. A Schedule may use the deterministic `external_controller_wake` action to resume an already bounded Work through Thin Launcher. The wake operation only transports the persisted Work/Handoff context to an external Controller; it does not interpret the model response inside the Kernel.
 
+Work-bound continuation is one Schedule subtype, not the universal Schedule model. Long-lived policy belongs to the Schedule; one firing belongs to the terminal Occurrence; a Work remains a finite objective. Generic Schedules may therefore finish with `nothing_to_do`, run an explicitly allowlisted deterministic operation/check, or wake an existing finite Work. If an external Controller observes a genuinely new semantic objective, that later request returns through the normal Route Policy and Work admission path rather than turning the Schedule itself into a forever-running Work.
+
+For external systems that do not expose a reliable event API, a Work-bound Schedule may instead use the deterministic `browser_probe` operation. The Kernel may navigate or reload one allowed browser target, extract bounded text, normalize a caller-selected projection, compute a stable fingerprint, compare it with the previous persisted observation, and detect explicitly configured login markers. It must not classify the business meaning of the page. The first observation is a silent baseline by default, unchanged observations are `nothing_to_do`, and only a changed observation (or an explicit authentication-required condition) may wake the bound external Controller.
+
 `external_controller_wake` accepts a `work_id`, `controller_type`, and optional launcher/session metadata. For ChatGPT, Thin Launcher prefers a saved Forge browser session (`browser_session_id`), then an explicit `https://chatgpt.com/...` conversation URL, then a new browser consult. Codex/Claude remain external CLI controllers. If the Work already has an active Controller lease, the Occurrence is a deterministic no-op rather than spawning a competing controller.
 
-The stable ChatGPT tool surface manages this policy through `rh_work` rather than exposing another Schedule tool. `rh_work.schedule_create/list/get/pause/resume/trigger` binds only an existing non-terminal Work to `external_controller_wake`; callers cannot use the facade to schedule an arbitrary MCP or repository operation. Creation is idempotent by a stable schedule request identity, defaults to `shadow_mode=true`, limits active occurrences to one, and carries explicit failure/cooldown/daily-budget/backoff policy.
+The stable ChatGPT tool surface manages this policy through `rh_work` rather than exposing another Schedule tool. `rh_work.schedule_create/list/get/pause/resume/trigger` binds only an existing non-terminal Work to one of three bounded modes: `continuation` (`external_controller_wake`), `browser_watch` (`browser_probe` with change-triggered wake), or `browser_keepalive` (`browser_probe` without content-change wake). Callers cannot use the facade to schedule an arbitrary MCP or repository operation. Creation is idempotent by a stable schedule request identity, defaults to `shadow_mode=true`, limits active occurrences to one, and carries explicit failure/cooldown/daily-budget/backoff policy.
+
+A Work-bound Schedule is acceptance-driven, not perpetual. Before every wake **or browser probe**, Forge re-reads the bound Work. A missing Work pauses the Schedule; a terminal Work (`completed`, `cancelled`, or another terminal Work state) deterministically disables the Schedule and returns `nothing_to_do` before touching the external browser target. An active Controller lease also suppresses a competing wake. Therefore recurring triggers are only observation/continuation policy for unfinished bounded Work, never a forever-running agent.
 
-A Work continuation Schedule is acceptance-driven, not perpetual. Before every wake, Forge re-reads the bound Work. A missing Work pauses the Schedule; a terminal Work (`completed`, `cancelled`, or another terminal Work state) deterministically disables the Schedule and returns `nothing_to_do`. An active Controller lease also returns `nothing_to_do`. Therefore the recurring trigger is only a wake policy for unfinished bounded Work, never a forever-running agent.
+`browser_watch` persists only normalized observation metadata (fingerprint, observation time/status, and bounded diagnostics), not the extracted page body as Schedule state. Callers may provide `include_terms` and `ignore_patterns` to exclude unrelated or volatile text such as relative timestamps. `browser_keepalive` refreshes the configured browser session and checks explicit login URL/text markers; it can wake ChatGPT when re-authentication is required, but a successful refresh is not treated as a guarantee that a third-party session can never expire.
 
 Thin Launcher does not pre-claim Controller ownership. It records a short Controller-Home launch reservation (configured with `launch_reservation_ms`) only to fence duplicate spawns while the provider starts. The external provider must connect to Forge MCP and call `rh_work continue` with its authenticated transport identity; that authenticated principal/session becomes the Work owner. This separation prevents the scheduler from impersonating ChatGPT/Codex/Claude and preserves the Controller-session identity fence. Detached CLI providers also use their non-interactive execution contracts (`codex ... exec` and `claude --print`) instead of launching interactive TUIs with ignored stdio.
 
@@ -434,7 +440,7 @@ The purpose is to remove unhelpful automation, not merely prove it is active.
 
 The runtime implements first-class `RepositorySchedule`, `ScheduleDecision` and `ScheduleOccurrence` records under `src/runtime/workflow/schedules/`. Supported triggers are interval, manual, five-field UTC cron, one-shot calendar timestamp, condition watch, repository event and dependency checkpoint.
 
-Every due trigger uses a deterministic window or event identity. The Decision is persisted before executable work is admitted. Occurrences are indexed, Shadow Mode defaults on, one Occurrence creates at most one durable Job, and repeated trigger delivery returns the existing Occurrence.
+Every due trigger uses a deterministic window or event identity. The Decision is persisted before executable work is admitted. Occurrences are indexed, Shadow Mode defaults on, one Occurrence creates at most one durable Job, and repeated trigger delivery returns the existing Occurrence. Work-bound continuation/browser-watch helpers remain specialized views over this same Schedule/Occurrence engine rather than a second Workflow lifecycle.
 
 Budgets, cooldown, maximum active Occurrences, consecutive-failure circuit breaking and exponential backoff are persisted. Dirty Workspaces, release barriers, repository disablement, human-attention state and recent external/infrastructure failures suppress unattended writes. Candidate Findings deduplicate observations and require explicit human promotion before Issue creation.
 

package/docs/architecture/current/codegraph-context-provider.md

@@ -1,6 +1,6 @@
 # CodeGraph Context Provider
 
-Status: reviewed for Phase 1 implementation  
+Status: **Runtime Authority — impact-context convergence implemented**
 Source baseline: `a49465096c4e2532da37ab2f9d10dca2238217ac`  
 Scope: Controller Context Plane only
 
@@ -99,12 +99,14 @@ Default is `off` to preserve current Direct performance and behavior.
 
 Expected mode usage:
 
-- ordinary Direct: `off`
+- ordinary Direct: `off` (zero CodeGraph provider calls)
 - explicit `-debug`: `auto`
 - explicit `-plan`: `required` when a CodeGraph index is present; otherwise return a clear degraded-plan warning and use bounded text search
 - Goal/Plan planning and review: `auto` or `required` when structural evidence materially improves the decision
 
-When enabled, graph results augment candidate ranking. They do not replace raw source reads. Important files selected through CodeGraph still pass through `resolveMcpPath` and `readRepositoryRange` before implementation.
+When enabled, graph results augment candidate ranking and the bounded impact contract. They do not replace raw source reads. Important files selected through CodeGraph still pass through `resolveMcpPath` and `readRepositoryRange` before implementation.
+
+After the initial structural `context` query, the Context Plane may issue bounded `file_dependencies` queries for a small number of entry-point files. Dependencies and dependents are folded into the same policy-filtered Context Pack; they are not exposed as another ChatGPT tool flow. The pack derives an `impactContext` containing primary targets, must-inspect and likely-affected files, related tests/checks, architecture contracts, coverage gaps, freshness, and confidence. These remain discovery evidence: ChatGPT is still the semantic-sufficiency authority.
 
 Context Pack gains a bounded `structuralContext` section containing:
 
@@ -138,6 +140,16 @@ If the provider reports changed files, stale extraction, or an index built by an
 
 A later typed maintenance action may perform refresh. That action is separate from planning and may write only derived `.codegraph` state, never source files.
 
+### Isolated checkout baseline overlay
+
+CodeGraph binds source root and `.codegraph` database root to the same `projectRoot`; the embedded API does not expose a separate read-only database path. Forge therefore does **not** copy or synchronously build an 84MB-class structural index for every managed worktree.
+
+When structural context is requested for an isolated checkout that has no local index, the Context Plane may reuse an indexed non-worktree checkout from the same Repository Registry family as **repository-baseline structural evidence**. Current-checkout lexical/raw source remains authoritative. Forge overlays the selected checkout's current Git-changed paths on the graph candidates and reports `indexSource=repository_baseline` plus explicit coverage gaps.
+
+The baseline is never presented as current-checkout truth. A dirty current checkout or a baseline/current HEAD mismatch marks the structural evidence stale and prevents `structural_context=required` from being satisfied. Optional structural requests may still use the graph as bounded discovery evidence while raw current-checkout reads cover changed files.
+
+This fallback executes only when structural context was already requested. Ordinary Direct routing remains `structural_context=off`, performs zero CodeGraph provider calls, and pays no baseline lookup or structural refresh cost.
+
 ## Packaging and platform behavior
 
 The provider locates the matching optional platform package:

package/docs/architecture/current/dispatch-and-agent-strategy.md

@@ -10,7 +10,9 @@ The Controller owns dispatch decisions. Workers and Agents execute scoped contra
 
 ## 2. Work Assessment
 
-Every change request is assessed before execution using:
+The Controller commits an execution mode only after it has enough evidence to do so. An already-explicit bounded request may commit immediately; an ambiguous or architectural request starts with read-only exploration and is assessed only after that context is available. Forge does not create a Plan/Work merely to perform this exploration.
+
+When an execution commitment is needed, the Controller assesses:
 
 ```text
 objective clarity
@@ -39,7 +41,21 @@ verificationClass
 humanBoundary
 ```
 
-Repository search is an information-gathering step, not by itself a reason to start an Agent or create a durable Issue.
+Repository search, CodeGraph impact analysis, Runtime state reads, and history/evidence lookup are information-gathering steps. They are not by themselves reasons to start an Agent, create Work, or create a Plan. ChatGPT/human Controller owns semantic sufficiency and the Direct/Work/Plan choice; Forge Route/Hook compatibility code may supply mechanics, safety facts, or advice but MUST NOT become a second semantic decision authority.
+
+### 2.1 Orthogonal routing dimensions
+
+Forge keeps three decisions separate:
+
+```text
+semantic ownership   = unbound | continue/extend an explicit Work | Plan/Requirement binding
+execution depth      = Direct | Process | Durable Work | Handoff
+resource placement   = visible checkout | isolated Worktree | external provider resource
+```
+
+`RouteDecision` is the sole authority for execution depth. An unrelated active Work, an existing Plan, or a checkout writer MUST NOT reinterpret an already-safe Direct operation as Durable Work. Explicit Work ownership may be attached to a Direct Edit or Process for attribution/evidence without changing its execution depth. A real checkout writer conflict changes placement or waits for a resource; it does not manufacture a semantic `parallel`/`new_goal` relation.
+
+When `rh_work start` actually creates a Durable repository Work, the facade materializes the same-ID execution `WorkHandle` for the selected checkout/worktree and atomically claims that new Work for the authenticated initiating Controller. `work_prepare` remains a lower-level execution/compatibility primitive; a normal new Work does not require a second mechanical prepare/claim round trip before useful execution can begin.
 
 ## 3. Execution Modes
 
@@ -88,7 +104,7 @@ Quick Agent work may carry ephemeral diagnostic metadata, but Job and Run eviden
 
 ### 3.3 Requirement, Plan, and Work
 
-A durable Requirement/Plan/Work graph is required when work has one or more of:
+Requirement, Plan, Work, and Workflow are independent durable tools rather than a mandatory graph. The Controller introduces only the minimum durable object justified by the task. A finite Work is useful when one bounded responsibility needs cross-session recovery/ownership; a Plan is useful for real staged/dependency coordination; a Requirement represents longer-lived intent; Workflow/Schedule represents recurrence. Durable state is commonly justified by one or more of:
 
 - multiple independently verifiable objectives;
 - dependencies or ordered migration phases;
@@ -97,25 +113,26 @@ A durable Requirement/Plan/Work graph is required when work has one or more of:
 - protected or release-sensitive surfaces;
 - cross-repository work;
 - long-running verification or environment dependencies;
-- schedule-driven recurrence;
 - a need for review and recovery across multiple sessions;
 - release or rollout coordination.
 
-A durable Work contract is not ceremony. It owns bounded execution scope, dependencies, evidence, retry history, and completion receipts; Requirement owns user-visible intent and acceptance outcome.
+A durable Work contract is optional, not ceremony and not a universal task wrapper. When explicitly chosen it owns a bounded recoverable responsibility and its execution attribution; Process/ExecutionJob/EditSession remain the technical execution truth. Requirement owns longer-lived user intent; ChatGPT/user review owns semantic acceptance. A Schedule/Occurrence does not require Work unless a particular occurrence needs durable responsibility.
 
 ## 4. Decision Order
 
-The Controller applies this order:
+The Controller follows a late-commit order rather than classifying every request at ingress:
 
 ```text
-1. Is the request read-only?
-2. Can bounded Direct Edit safely satisfy it?
-3. Is one scoped Agent attempt sufficient?
-4. Does the work require durable Requirement/Plan/Work state?
-5. Does it cross repositories or require a Schedule?
-6. Does any external or destructive boundary require human authorization?
+1. Is the request already explicit and bounded enough to act safely?
+2. If not, gather the minimum read-only context first.
+3. After context is sufficient, can Direct/Process satisfy it?
+4. Does this bounded responsibility genuinely need durable Work recovery/ownership?
+5. Does coordination genuinely need a Plan, or recurrence a Workflow/Schedule?
+6. Independently, do hard authorization/resource/destructive boundaries constrain execution?
 ```
 
+Steps 1-5 are semantic Controller decisions. Step 6 and execution mechanics are Forge authority. A later hard-safety rejection may stop an unsafe action, but Forge must not force an A→B execution-mode switch merely because a Plan/Work artifact is absent.
+
 The system MUST NOT default to Agent execution merely because an Agent is available.
 
 ## 5. Agent Roles
@@ -315,6 +332,8 @@ Use when:
 
 The default `auto` placement policy chooses Workspace for one local serial writer and Worktree when concurrency exists. It MUST still honor explicit claims and dirty-state safety.
 
+Placement is evaluated after execution depth and semantic ownership. A new durable objective may therefore create a new finite Work and select a Worktree purely because the visible checkout already has a writer; the caller does not need to classify that resource conflict as a semantic `parallel` relation first. Only a managed Worktree/branch is a disposable Work-owned resource: stopping a Work on the current checkout closes lifecycle/process ownership but never removes the repository's current checkout or branch.
+
 ## 11. Review and Continuation
 
 After execution:
@@ -347,7 +366,7 @@ The dispatch layer MUST avoid:
 
 ## 13. Current Implementation
 
-The repository implements Direct Edit, Quick Agent and Requirement/Work assessment; runtime Agent selection; bounded Task scope; persistent Runs; Workspace/Worktree placement; and risk-adaptive verification.
+The repository implements one canonical Route Policy for execution depth, Direct Edit, Process Runtime, finite Requirement/Work execution, optional Plan decomposition, runtime Agent selection, bounded Task scope, persistent Runs, Workspace/Worktree placement, and risk-adaptive verification.
 
 The Thin Gateway keeps deterministic local commands on Direct Edit or Process Runtime paths. Agent dispatch is now an explicit external-Controller handoff; the Kernel no longer creates Execution Jobs for ordinary Agent launches. Work ownership, repository placement, and resource claims remain durable Controller state, while provider selection and model execution belong to the claimed external Controller.