@moretea-labs/forge 1.8.0 → 1.8.2

package/docs/architecture/decisions/20261017-edit-session-finalization-reconciliation.md

@@ -0,0 +1,17 @@
+# Edit-session finalization after integrated commits
+
+**Tracking issue:** [#235](https://github.com/moretea-labs/forge/issues/235)
+
+## Problem
+
+An edit session captures a Git baseline and workspace fingerprint when its edits are applied. After the same tracked after-images are committed, Git HEAD and the workspace fingerprint naturally change. The public finalization path previously rejected this drift before consulting the existing edit-session reconciliation logic, leaving already-integrated changes without a terminal session/receipt.
+
+## Canonical rule
+
+When the baseline or workspace fingerprint has changed, `finalizeEditSession` first invokes the existing `reconcileEditSession` path. Reconciliation may finalize only when all tracked files still match their exact recorded after-images, no tracked session path has uncommitted changes, and configured checks have passed. If the session remains dirty, the original stale-baseline/fingerprint error is preserved. Content drift follows the existing reconciliation behavior and supersedes the session rather than overwriting or rebasing its evidence.
+
+The approval requirement is checked before reconciliation. This does not adopt a new Git baseline, relax ownership checks, bypass validation, or create a completion receipt directly; the canonical finalization and receipt owners remain authoritative.
+
+## Regression coverage
+
+`tests/runtime/edit-session-continuity.test.ts` covers both successful finalization after the edited path is committed and rejection while that path remains uncommitted. The focused suite, runtime architecture check, and TypeScript checks passed on the tested revision.

package/docs/architecture/decisions/20261019-retire-host-skills.md

@@ -0,0 +1,16 @@
+# Decision: Retire Forge-owned host Skills and duplicate version authority
+
+**Status:** Accepted (2026-10-19). Supersedes the host-Skill distribution decision of 20260803.
+
+## Evidence
+Forge execution uses CLI, MCP, Runtime, and host adapters. The former root Skill only offered prompt discovery for Codex/Claude; its separate installer and version manifest added a second release authority which blocked version 1.8.2 without evidence of a Runtime defect.
+
+## Decision
+- Remove the Forge-owned host Skill, Codex Skill metadata, bundled cross-review Skills, and their installers.
+- Forge setup no longer installs third-party Waza/Mermaid Skills. Existing user-installed Skills are user-owned and left untouched.
+- Project guidance templates read their version from package.json.version. Eliminate the independent version manifest and generated per-project Skill version stamp.
+- Retire the deprecated empty Skill lifecycle-hook table and executor.
+- Keep CLI, MCP, Runtime, host hook adapters, project guidance, Forge Plugins, and unrelated Cognitive Skill semantics.
+
+## Migration and acceptance
+Packaged distributions no longer include Forge-owned host Skills. CLI init/update/adopt do not synchronize them. All changed code, project templates, architecture, and release gates must be validated with one canonical version authority. No replacement provider is introduced.

package/docs/architecture/diagrams/agentic-dev-plugin-architecture.html

@@ -177,7 +177,7 @@
 
         <rect x="120" y="470" width="882" height="86" class="box"/>
         <text x="146" y="506" class="label">Compatibility Boundary</text>
-        <text x="146" y="532" class="small">Canonical name: agentic-dev. Compatibility alias: agentic-dev-skill. Retired project-initializer install paths are cleanup targets. CodeGraph is required readiness.</text>
+        <text x="146" y="532" class="small">Canonical name: agentic-dev. Compatibility alias: agentic-dev-skill. Retired project-initializer install paths are cleanup targets. Source search is ripgrep plus language-service navigation.</text>
       </svg>
     </div>
     <p class="footer">Generated 2026-05-25. Standalone HTML with inline SVG; no JavaScript. Semantic source: docs/architecture/snapshots/2026-05-25-agentic-dev-plugin-review.md#semantic-diagram.</p>

package/docs/architecture/domains/public-surface.md

@@ -1,13 +1,12 @@
 # Architecture Domain: Public Surface
 
 > **Source**: `.ai/context/capabilities.json`
-> **Owner**: Root router and command facade docs.
+> **Owner**: CLI/MCP command facade docs.
 
 ## Purpose
 
 The public surface turns user intent into one of the supported CLI+hooks harness
-actions without duplicating engine policy in prose. It includes the root skill
-compatibility router, README, root agent docs, the `forge` CLI, and thin
+actions without duplicating engine policy in prose. It includes the README, root agent docs, the `forge` CLI, and thin
 `forge-*` command facades.
 
 ## Capabilities
@@ -17,10 +16,9 @@ compatibility router, README, root agent docs, the `forge` CLI, and thin
 
 ## Stable Rules
 
-- Root `SKILL.md` stays short and router-oriented.
+- Forge ships no host Skill; CLI/MCP and host adapters are the execution surfaces.
 - Root `AGENTS.md` and `CLAUDE.md` stay concise; detailed operating rules live in `docs/reference-configs/`.
 - Public commands are CLI-backed facades. Internal steps such as `hooks-init`, `docs-init`, and `create-project-dirs` stay behind `init`, `scaffold`, `migrate`, and `upgrade`.
-- `forge-skill` remains a compatibility trigger, not the canonical name.
 - The former `project-initializer` install paths have been fully removed; no tooling recognizes, syncs, or cleans them up.
 
 ## Verification Surface

package/docs/architecture/domains/verification.md

@@ -1,7 +1,7 @@
 # Architecture Domain: Verification
 
 > **Source**: `.ai/context/capabilities.json`
-> **Owner**: Regression tests, workflow gates, eval harness, CodeGraph readiness, and advisory tooling checks.
+> **Owner**: Regression tests, workflow gates, eval harness, and advisory tooling checks.
 
 ## Purpose
 
@@ -10,7 +10,6 @@ repos, command facades, hooks, migration helpers, and installed runtime copies.
 
 ## Capabilities
 
-- `verification-codegraph-readiness` -> `docs/architecture/modules/verification/codegraph-readiness.md`
 - `verification-evals-checks` -> `docs/architecture/modules/verification/evals-checks.md`
 
 ## Stable Rules
@@ -20,6 +19,7 @@ repos, command facades, hooks, migration helpers, and installed runtime copies.
 - Governed tests preserve typed per-file failure evidence (`source`, `fixture`, `infrastructure`, `interrupted`) in bounded receipts; Check/Work verification may collapse that evidence only to the existing acceptance-vs-infrastructure authority, never by reparsing human stderr.
 - The active Runtime always owns Process admission, leases, terminal Process state, and Work verification receipts. For ordinary repositories, persisted checks execute through that Runtime's immutable Check Runner.
 - Self-hosting Forge Work verification is the bounded exception to runner location, not to lifecycle authority: when the verified repository has the same durable `repoId` as the Runtime Source authority, a non-live verification snapshot executes the Check Runner from that exact candidate snapshot. Candidate runner/content identity is folded into the existing Check execution fingerprint so evidence cannot cross runner revisions.
+- A Work verification snapshot establishes its package dependency closure inside the existing Check Process before loading candidate Check Runner modules. Exact canonical `node_modules` reuse remains valid only when dependency metadata is equivalent; otherwise the disposable snapshot materializes dependencies from its own supported frozen lockfile. Bootstrap failure is infrastructure failure and never repository acceptance evidence.
 - `live_controller_home` certification never uses the candidate snapshot runner because it is explicitly verifying the installed Runtime. A candidate snapshot missing its Forge-owned sidecar fails closed; no arbitrary executable override or second scheduler/store is introduced.
 - Public `rh_work verify` accepts either one `check_id` or one non-empty `check_ids` batch, never both. A batch is admitted only when the registered checks form one ordinary resource-compatible wave according to Process Runtime `buildCheckExecutionSchedule`; invalid, cross-wave, release, and multi-phase batches fail closed before partial execution. Every admitted member still runs through the canonical Work verification service, Work snapshot, Process Runtime claims, Failure Contract, and VerificationRecord authority; batch aggregation is not a scheduler or lifecycle authority.
 - Work verification persistence is one read-modify-write authority: any decision derived from current `checkRefs`, scope evidence, review state, or lifecycle state must read the latest Work and derive its patch inside the existing Work-store writer critical section. Synchronous writer contention remains fail-fast/retryable rather than sleeping on the Gateway path; a retry must re-read current state before deriving its mutation, so stale snapshots cannot silently erase compatible evidence.
@@ -27,14 +27,15 @@ repos, command facades, hooks, migration helpers, and installed runtime copies.
 - `check-task-sync.sh` enforces that substantive repo changes update `tasks/`.
 - `check-task-workflow.sh --strict` is the repo-local harness readiness gate.
 - `sync-brain-docs.sh --check` verifies manifest-controlled repo-to-brain mirrors without making gbrain or MCP part of hook correctness.
-- External tooling probes remain read-only by default; CodeGraph readiness is required for agent code navigation, while other external tooling remains advisory.
-- This self-host repo may use a vendored CodeGraph dev dependency; generated downstream repos keep global CodeGraph MCP setup explicit unless policy opts in.
+- External tooling probes remain read-only by default. Agent code navigation uses current source and explicit LSP navigation; no graph index is required.
+- Source discovery must authorize each file before invoking `rg`, search the eligible inventory rather than silently truncating its alphabetic prefix, and report missing search executables as errors rather than empty matches. `rg` match records use NUL-framed paths/line numbers so standard process-output redaction cannot corrupt JSON syntax. Caller-supplied exclude globs also apply to explicit known paths. `scannedFiles` counts files contributing accepted lexical evidence, not the complete set of candidate paths examined by ripgrep.
+- For exact code-symbol discovery, rank exported declarations ahead of same-named local wrappers and ordinary usage sites, with all evidence remaining literal and current-source grounded. Compare only authorized files that actually matched `rg`; preserve the inventory ordering on equal relevance. Context Pack returns bounded source snippets fairly across inferred candidates, including when a caller raises `max_snippets`; an explicit known-file read retains its caller-selected evidence budget. A truncated discovery result is never advertised as exhaustive.
+- `rh_context.query` preserves the caller's natural-language intent; optional model-selected `search_terms` supplies up to eight source-language lexical anchors to the existing Context Pack, with no embedded translation/semantic engine. Only a single code-shaped query becomes an implicit exact search needle; natural-language sentences must not be promoted to mandatory literal code symbols. The model selects source-language keywords, inspects current raw-source hits, and progressively refines the query when results are unrelated or truncated.
 
 ## Verification Surface
 
 - `bun test`
 - `bash scripts/check-task-sync.sh`
 - `bash scripts/check-task-workflow.sh --strict`
-- `bash scripts/ensure-codegraph.sh --check --json`
 - `bun scripts/inspect-project-state.ts --repo . --format text`
 - `bash scripts/migrate-project-template.sh --repo . --dry-run`

package/docs/architecture/domains/workflow-engine.md

@@ -28,3 +28,9 @@ verify without a live service.
 - `bun test tests/migration-script.test.ts tests/create-project-dirs.runtime.test.ts tests/workflow-contract.test.ts`
 - `bash scripts/migrate-project-template.sh --repo . --dry-run`
 - `bash scripts/check-task-workflow.sh --strict`
+
+## Autonomous WorkflowRun name boundary
+
+This repo-mutation **Workflow Engine** and the existing declarative `workflow_run` checkpoint records are not the cross-assistant-turn lifecycle authority for an autonomous development Goal.
+
+The V1 Workflow Supervisor defined in [`../decisions/20260916-workflow-supervisor-authority.md`](../decisions/20260916-workflow-supervisor-authority.md) uses a distinct Supervisor persistence authority/namespace. It may eventually converge with declarative Workflow assets only through an explicit migration and authority decision. Shared terminology is not permission to share writers, reinterpret persisted states, or copy lower-layer lifecycle states upward.

package/docs/architecture/modules/controller-runtime/transport-lifecycle.md

@@ -1,17 +1,17 @@
 # MCP HTTP Transport Lifecycle
 
 > Capability: `mcp-http-transport-lifecycle`
-> Runtime Authority: `docs/architecture/../../CURRENT.md` and `docs/architecture/../../CURRENT.md`
+> Runtime Authority: [Current Architecture](../../CURRENT.md)
 
 ## Responsibility
 
-`src/cli/mcp/transports/` owns HTTP authentication handoff and protocol-era serving. MCP 2026-07-28 is the canonical public boundary and is served per request without protocol-level sessions. The session registry, global admission capacity, transport leases, and DELETE cleanup exist only for the explicit 2025-era compatibility path. The transport does not own durable Work/Process/ControllerRound authority or Gateway process recovery.
+`adapters/mcp/transports/` owns HTTP authentication handoff and protocol-era serving. MCP 2026-07-28 is the canonical public boundary and is served per request without protocol-level sessions. The session registry, global admission capacity, transport leases, and DELETE cleanup exist only for the explicit 2025-era compatibility path. The transport does not own durable Work/Process/ControllerRound authority or Gateway process recovery.
 
 ## Invariants
 
 - Modern `server/discover` and subsequent 2026-07-28 requests are handled by the SDK v2 per-request handler and do not require or emit `Mcp-Session-Id`.
 - Durable Work, Process, and ControllerRound identity is independent from both modern request bindings and legacy transport sessions.
-- A newly created Work is claimed with an opaque Work-bound controller capability immediately; modern sessionless follow-up requests must present that exact authority. Legacy owner records without a capability digest require an explicit `controller_claim` authority upgrade and are never accepted by principal identity alone.
+- A newly created Work may receive an opaque Work-bound controller capability for Runtime recovery and replay fencing. That capability is internal to normal model-facing Work execution: the Runtime/Supervisor establishes, rotates, and recovers it. Legacy owner records without a capability digest may use the explicit `controller_claim` compatibility upgrade; ordinary model-facing Work operations never require it.
 - Legacy 2025-era traffic is classified mechanically by the SDK and routed to one bounded stateful compatibility registry shared by all public MCP HTTP routes.
 - On the legacy path, route and authenticated principal must match the stored session on GET, POST, and DELETE; active POST work is protected from capacity eviction.
 - Legacy stream-only sessions are reclaimable through client DELETE, explicit prior-session replacement, lease expiry, absolute lifetime, or oldest-safe capacity eviction.

package/docs/architecture/requests/2026-09-04-computer-plugin-workflow-taxonomy.md

@@ -38,15 +38,15 @@ V2 must explicitly distinguish four concepts even if compatibility transport sti
 
 The 2026-09-09 #200 latency review proved that the native Desktop Operator is not the dominant warm-path cost, so provider transport optimization must preserve the existing authority boundary rather than introduce another controller or durable provider session. The Computer runtime therefore uses the following transport contract:
 
-- one live Desktop Operator provider binding is scoped to the current trusted registration identity/revision and endpoint contract;
+- one live Desktop Operator provider registration binding is scoped to the current trusted registration identity/revision and endpoint contract; it owns at most two lazy retained JSONL connections;
 - provider identity/capability negotiation is reused only while the same Unix-socket connection generation remains live;
-- sequential Computer requests may reuse that bounded JSONL channel instead of reconnecting and handshaking for every action;
-- registration fingerprint/revision or endpoint-contract change disposes the old provider binding before replacement;
+- native observe/element-observe/capture requests reuse an observation connection, while input, protected console, and legacy Browser compatibility requests retain the original ordered connection. Desktop Operator processes each connection serially, so a slow Browser RPC must not block unrelated native observation. Target/session locks remain the observation-epoch authority;
+- registration fingerprint/revision or endpoint-contract change disposes both old connections before replacement; each connection negotiates its own live generation and Runtime disposal closes both;
 - if the Unix connection changes after negotiation, the pending action is rejected before dispatch and the next explicit invocation must renegotiate; non-idempotent effects are never replayed automatically;
 - timeout, cancellation, response-size and protocol-error bounds remain per request; transport reuse creates no new durable lifecycle or retry authority.
 - Browser semantic mutations do not pay an unconditional fixed post-action sleep: provider primitives and bounded post-action identity/evidence are the normal completion path; `post_action_wait_ms` is explicit compatibility input only, while native foreground activation may retain a provider-specific verification budget because system foreground authority must be observed.
 - Desktop target-bound semantic actions dispatch through the current leased provider binding without a `desktop_status(limit: 500)` preflight. Only an explicit provider `SESSION_NOT_FOUND` transported as a failed/pre-effect result may rebuild the binding from stable application identity and retry once; transport, timeout, and outcome-unknown failures are never replayed. Target close likewise calls the bound session close directly instead of enumerating provider sessions first.
-- Desktop observe/input/capture product actions use the retained `ComputerProvider` channel instead of re-entering the legacy external-adapter transport for every semantic action. Target open/close remain low-frequency provider lifecycle operations; the hot path owns no parallel durable provider-session authority.
+- Desktop observe/input/capture product actions use the retained `ComputerProvider` connections instead of re-entering the legacy external-adapter transport for every semantic action. Both connections address the same provider sessions and create no second target/provider authority. Target open/close remain low-frequency provider lifecycle operations; the hot path owns no parallel durable provider-session authority.
 - the external Unix JSONL and `ComputerProviderError` failure contracts preserve `failed` versus `outcome_unknown` across adapter boundaries. A provider-declared failure keeps the negotiated connection alive; transport loss after an effectful request is dispatched invalidates negotiation and is never eligible for implicit replay.
 
 The repeatable `benchmark:computer-hotpath` run on 2026-09-09 used 50 warm semantic samples after five warmups. The isolated real dispatch path measured cold first semantic action `4.398ms`; warm `p50=0.939ms`, `p95=1.511ms`, `max=1.894ms`. Across the 50 warm samples the provider observed exactly 50 semantic RPCs, zero new connections, zero handshakes, zero manifest preflights, zero `desktop_status` preflights, and zero session reopens. This benchmark is comparative evidence, not a machine-specific release threshold.

package/docs/architecture/reviews/20261015-code-search-runtime-acceptance.md

@@ -0,0 +1,75 @@
+# Forge Code Search — Post-Release Acceptance Ledger (2026-10-15)
+
+Status: **PARTIAL — not a known-good or release acceptance.** This record describes observed evidence, not a deployment decision.
+
+## Identities and scope
+
+- Mac source checkout: `<local-forge-checkout>` (local path omitted from the public ledger), source HEAD at this measurement: `765804d762544a87e3d750287a423fad64d86ddb`.
+- Active immutable Runtime remains `1792022338979-696cc9d5f3aea62e550309206b73f7357c545d70`, authority revision 868, using source `696cc9d5f`. **Unreleased** source commits: `5a0f8d839` (model-selected lexical hints), `9a7e26f63` (retire obsolete editor rule), `765804d76` (exported-definition ranking and snippet fairness).
+- Preserve four pre-existing dirty files outside code search. No Runtime cutover, restart, promotion, external delivery, or CodeGraph process termination was performed.
+- Existing independent acceptance task: `supervisor:9089c98263b23e1bd329813b`. Enrollment remains blocked by unattributed `composer_not_empty` draft; do not treat the bootstrap URL as a delivered independent conversation.
+
+## Repository retrieval correctness: real deployed MCP vs direct rg
+
+Real `search_repository` MCP on currently deployed Runtime, with `max_results=500,max_files=20000`, compared with direct `rg -l -i --fixed-strings --no-ignore --hidden` using the same default exclusion globs:
+
+| Query | MCP distinct files | Direct rg files | Truncated | Conclusion |
+| --- | ---: | ---: | --- | --- |
+| `runProcess` | 28 | 28 | false | File-set equality; MCP trace `c71e6967-1069-4f8f-b998-8a22a64c6634` |
+| `rollbackPrevious` | 5 | 5 | false | File-set equality; MCP trace `c0031532-d2b4-47d2-a559-d5d005d572b0` |
+| `ReleaseSession` (whole repo) | 20 | 25 | true, `max_results` | Expected incomplete bounded response; MCP trace `c72f4662-aba0-416a-bc48-ebed69822982` |
+| `ReleaseSession` `src/**` | 11 | 11 | false | Exact matching subset |
+| `ReleaseSession` `tests/runtime/**` | 5 | 5 | false | Exact matching subset |
+| `ReleaseSession` `docs/**,scripts/**` | 9 | 9 | false | Exact matching subset |
+
+The three explicit scopes recover 25/25 paths, without claiming that a single bounded whole-repo search is complete. These checks concern **matching file paths**, not every returned line or all authorized filesystem states. The broad MCP count alone must not be used as full coverage.
+
+## Latency attribution: current deployed Runtime
+
+### Direct local authenticated HTTP MCP (unchanged active Runtime)
+
+Used existing `scripts/benchmark-mcp-transport.ts` via `http://127.0.0.1:8765/mcp`, `--local-service-auth`, one steady-state MCP session, 3 warmups, 20 measured calls per tool. No secret values were written to artifacts or command line.
+
+| Tool | Local MCP p50 / p95 | Server p50 / p95 | Local transport residual p50 / p95 |
+| --- | ---: | ---: | ---: |
+| `rh_status` | 20.62 / 23.25 ms | 17.01 / 20.84 ms | 2.98 / 5.02 ms |
+| `rh_context`, exact known source path | 199.78 / 215.20 ms | 196.25 / 207.57 ms | 3.40 / 4.14 ms |
+
+Reproduction examples (read-only, using the local Runtime's existing auth). Replace `REGISTERED_REPO_ID` with the local repository ID from `repository_list` before running; raw local IDs and device paths are intentionally not published:
+```sh
+bun scripts/benchmark-mcp-transport.ts --endpoint http://127.0.0.1:8765/mcp --local-service-auth --tool rh_status --iterations 20 --warmup 3 --repo-id REGISTERED_REPO_ID
+bun scripts/benchmark-mcp-transport.ts --endpoint http://127.0.0.1:8765/mcp --local-service-auth --tool rh_context --iterations 20 --warmup 3 --repo-id REGISTERED_REPO_ID --arguments '{"operation":"search","query":"runProcess","known_paths":["src/effects/process-runner.ts"],"max_files":3,"max_snippets":4,"structural_context":"off","include_learning_recall":false}'
+```
+
+### ChatGPT-connected tool invocation (separate path; not controlled A/B)
+
+Six sequential `rh_status` calls: observed invocation p50/p95 **1526/2270 ms**, Forge server p50/p95 **52.47/81.25 ms**.
+
+Six sequential `rh_context` known-path calls: observed invocation p50/p95 **2144/4338 ms**, Forge server p50/p95 **235.03/497.95 ms**.
+
+Earlier 3 samples per query gave: symbol invocation **2044–3367 ms**, known path **1395–3095 ms**, original Chinese rollback **2211–2562 ms**. The Chinese query did not find the rollback core on this older Runtime.
+
+**Inference and limit:** Direct authenticated local HTTP MCP has only a few milliseconds of transport residual; the substantial extra delay appears somewhere on the ChatGPT-to-tool calling path outside that local HTTP baseline. It has **not** been subdivided into host, tunnel, platform scheduling, or client-rendering contributions. These are separate workloads, loads, and observation windows; do not infer a specific network provider or claim a controlled causal improvement. Avoid rewriting ripgrep to solve latency not observed in local ripgrep/MCP execution.
+
+## Current source candidate correctness (NOT deployed)
+
+With code revision `765804d76` and 20 alternating local source invocations per version for `runProcess`, default `max_files=4,max_snippets=8`:
+- Before: canonical `src/effects/process-runner.ts:151` returned **0/20**, local p50/p95 **236.48/273.14 ms**.
+- After: canonical owner returned **20/20**, ranked first **20/20**, local p50/p95 **238.42/406.28 ms**.
+- Both versions reported bounded truncation **20/20**. Ranking quality improved; performance improvement is **unproven**. Focused checks on candidate: 49 pass/0 fail, type/architecture/repository/governance checks passed.
+- `search_terms` with model-provided `rollbackPrevious,cutover,recovery` locates `src/runtime/standalone-recovery/core.ts` in isolated source verification, but no new Runtime / live MCP certification has occurred.
+
+## LSP coordinate verification
+
+Live `rh_context` raw semantic-navigation call for `runProcess` references returned `totalLocations=135`, `returnedLocations=135`, `truncated=false`, `policyDeniedLocations=0`, but every location element was replaced by `[bounded-depth]` in the client-visible projection (trace `af7515e0-0fe7-43ee-8f09-b2cbf54e7700`).
+
+Independent local TypeScript Language Service inspection at `src/effects/process-runner.ts:151:19` returned **135 references in 26 files**. Each of 135 positions was checked against its current source file: **zero missing files, zero invalid line/column starts, zero out-of-repository paths**; 126 reference sites start with `runProcess`, nine use imported aliases. Direct local Language Service runtime was approximately 1608 ms for a cold query. This validates coordinates for the current source revision, not all possible dynamic call edges or complete MCP serialization fidelity.
+
+## Outstanding acceptance gates
+
+1. Repeat correctness, snippet fairness, complete scope behavior, and multilingual hints against the **future authorized deployed release**, preserving immutable source/release identity; independent new-conversation acceptance.
+2. Full LSP result coordinate inspection, fail-closed policy/readable-scope edges, changed-file behavior, and resource variability (not just success-count proxies).
+3. Live autonomous continuation proof and ReleaseSession `known_good` remain blocked; never bypass the unattributed composer draft or mark a `soaking` release known-good.
+4. The other four dirty checkout modifications remain separately owned. Some pre-existing WorkKind tests fail even on `696cc9d5f`; do not repair them as part of code search without a direct dependency.
+
+**Current decision:** Preserve ripgrep + explicit LSP as the single Forge search architecture. A bounded default context result is useful for implementation but is not complete evidence; use explicit scopes/limits to prove completeness. Optimize ChatGPT call overhead only with evidence of its real owner. Runtime switch requires new user authorization.

package/docs/forge-plugin-management.md

@@ -1,6 +1,6 @@
 # Forge Plugin Management
 
-Forge 1.5 introduces a public installation path for independently released providers while keeping the Controller trust boundary small. Official providers are **separate products** with their own repositories and releases; Forge owns how those providers are selected, installed, registered, authorized, and executed.
+Forge provides a public installation path for independently released providers while keeping the Controller trust boundary small. Official providers are **separate products** with their own repositories and releases; Forge owns how those providers are selected, installed, registered, authorized, and executed.
 
 ## Official catalog
 
@@ -10,9 +10,10 @@ forge plugin catalog
 
 | Plugin ID | Product | Pinned release | Platforms |
 | --- | --- | --- | --- |
-| `desktop_operator` | [Forge Desktop Operator](https://github.com/moretea-labs/forge-desktop-operator) | `v0.3.0` | macOS |
+| `desktop_operator` | [Forge Desktop Operator](https://github.com/moretea-labs/forge-desktop-operator) | `v0.4.5` | macOS |
 | `design` | [Forge Design](https://github.com/moretea-labs/forge-design) | `v0.3.0` | macOS, Linux, Windows |
 | `personal_knowledge` | [Personal Knowledge Assistant](https://github.com/moretea-labs/personal-knowledge-assistant) | `v0.2.1` | macOS, Linux, Windows |
+| `figma` | [Forge Figma Bridge](https://github.com/moretea-labs/forge-figma-bridge) | `v0.3.0` | macOS |
 
 Investment Decision System remains an independent product and is intentionally not a Forge plugin.
 
@@ -30,18 +31,29 @@ forge computer uninstall
 forge computer uninstall --purge
 ```
 
-`Computer` is the Forge product/capability identity. `desktop_operator` remains the implementation/provider identity used for trusted registration, release diagnostics, the stable macOS app bundle, LaunchAgent, socket, and TCC permissions. Its provider release is independent from the Forge Runtime release. `status` is a bounded projection of registration and recorded health, never proof inferred from a host browser; `doctor` refreshes provider health before reporting platform, registration, pinned-release, and readiness checks only on a compatible provider platform, and otherwise reports the stored incompatible registration without probing its transport. Setup/update use the same pinned official catalog transaction as generic plugin installation and fail before mutation when no compatible native provider exists. Uninstall invokes the provider-owned native uninstaller before Forge removes registration/package state, and fails closed rather than orphaning a native service when that lifecycle cannot be proven.
+`Computer` is the Forge product/capability identity. `desktop_operator` remains the implementation/provider identity used for trusted registration, release diagnostics, the stable macOS app bundle, LaunchAgent, socket, and TCC permissions. Its provider release is independent from the Forge Runtime release. Desktop Operator owns native macOS Computer observe/input/capture/console-unlock/element capabilities; Browser automation remains under the separate Browser provider authority rather than being claimed by the Desktop Operator catalog. `status` is a bounded projection of registration and recorded health, never proof inferred from a host browser; `doctor` refreshes provider health before reporting platform, registration, pinned-release, and readiness checks only on a compatible provider platform, and otherwise reports the stored incompatible registration without probing its transport. Setup/update use the same pinned official catalog transaction as generic plugin installation and fail before mutation when no compatible native provider exists. Uninstall invokes the provider-owned native uninstaller before Forge removes registration/package state, and fails closed rather than orphaning a native service when that lifecycle cannot be proven.
 
 Generic provider administration remains available for diagnostics and non-Computer providers:
 
 ```bash
 forge plugin install design
 forge plugin install personal_knowledge
+forge plugin install figma           # macOS, Figma bridge app/service required
 forge plugin install desktop_operator   # compatibility/advanced path on macOS
 forge plugin list --refresh
 ```
 
-Re-running `forge plugin install <id>` installs the version currently pinned by Forge. A catalog version change is a reviewed Forge source change; providers cannot silently self-update through a ChatGPT request.
+**Updating the Forge CLI does not automatically update external providers.** On macOS, use `forge computer update` after upgrading Forge; for other providers explicitly re-run `forge plugin install <id>` after checking `forge plugin catalog`. Re-running `forge plugin install <id>` installs the version currently pinned by Forge. A catalog version change is a reviewed Forge source change; providers cannot silently self-update through a ChatGPT request.
+
+## User workflow: install, configure, use
+
+1. Run `npm install -g @moretea-labs/forge@latest` and `forge setup next` to update the package/runtime connector contract.
+2. On macOS, run `forge computer setup` (or `forge computer update` for an existing provider), then `forge computer doctor` and `forge computer status --json`. Native Accessibility/Screen Recording permissions may require manual approval.
+3. Review `forge plugin catalog` and install only the extra providers you need, e.g. `forge plugin install design`, `forge plugin install personal_knowledge`, or `forge plugin install figma` on macOS.
+4. Run `forge plugin list --refresh`. A provider registration is not evidence that its app, socket, browser or service authentication is ready.
+5. Connect ChatGPT via the [MCP tutorial](tutorials/02-connect-chatgpt.md), then request a bounded outcome such as checking an open webpage, reviewing an authorized Finder folder, inspecting a design asset, or searching a configured local knowledge base. ChatGPT chooses typed actions, and Forge checks scope, authorization and evidence.
+
+See the [Computer and Plugins Wiki guide](wiki/Computer-and-Plugins.md) and the [Browser runbook](operations/controller-browser-plugin.md). Computer is currently backed by a macOS-only native provider; do not promise native desktop control on Linux/Windows. Browser and Figma readiness depend on the selected browser mode or running app-specific bridge.
 
 ## Trust boundary
 

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

@@ -315,3 +315,26 @@ bun scripts/smoke-browser-cdp-bridge.ts http://127.0.0.1:9222
 The smoke reuses an existing HTTP(S) tab, repeats the same session action, verifies that the target count does not increase, and confirms that Chrome remains reachable after the Node child disconnects. It does not read cookies or storage state and does not print the page title or full URL.
 
 Immutable Forge whole-Runtime releases include a dedicated `browser-node-bridge-host.js` bundle built for Node. The Browser adapter resolves that sibling entrypoint when running from a release and falls back to the source TypeScript host only in a source checkout. Release verification treats the bridge host as a required, hashed executable.
+
+### Exact-tab selection and local file upload
+
+- Browser URL/title is an observation, never a unique Tab identity. Sessionless URL reuse requires exactly one matching tab; an active tab, former window, duplicated owned marker, or truncated macOS inventory does not break ties. A previously saved native tab can only reattach by its exact ID; disappearance fails with `PLUGIN_BROWSER_SESSION_STATE_LOST` instead of binding a different user tab. Return `PLUGIN_BROWSER_REUSABLE_TAB_AMBIGUOUS` and request an explicit existing Tab binding rather than guessing or trying an alternative provider. Exact native `windowId`/`tabId` binding remains the first choice.
+- For a normal webpage `input[type=file]`, `attach_local_file` takes `selector` plus `file_path` or `file_paths` (1–32). Paths are relative to the repository by default. To attach files in Downloads/Desktop or another approved directory, first authorize that directory using the existing `local_system.authorize_target` (read-only is sufficient), then supply `target_key` and file paths **relative to the authorized target root**. Absolute paths, expired/wrong-caller grants, traversal, symlink escape, directories, and executable file types are rejected.
+- `attach_local_file` binds files to the DOM input and verifies their selected names/sizes, not the remote application's completed upload. The caller must separately verify its submission and server-side result. In macOS native Browser mode, bytes are transported to Chrome/Vivaldi via the existing browser scripting bridge; large/batch upload performance and live application postconditions require dedicated acceptance.
+- A system `Open Panel` triggered by Chrome is **not Finder**. The existing `local_system.reveal_in_finder` command only reveals files and does not select files in that panel. No Browser `attach_local_file` fallback to unreliable Finder clicks or undeclared foreground input is performed; a distinct exact-dialog native Computer workflow would need its own real end-to-end validation.
+
+Native Chrome/Vivaldi DOM file attachment follows one bounded transaction: validate every local regular file (up to 32 files and 16 MiB total), observe a unique enabled `input[type=file]` and its `multiple` property, stage the entire batch without modifying the input, then assign `input.files` once and emit one `input`/`change` pair. Mid-transfer failure does **not** leave a partial selection. The final DOM event can trigger a remote upload: if its receipt is unknown, re-observe the exact page before any further mutation; do not replay the transfer blindly. Upload completion still requires separate application-level verification. A macOS Open Panel remains a separate Desktop accessibility workflow, not a fallback for this action.
+
+The macOS Chrome live E2E (`bun run test:browser-live`) calls the **production Computer/Desktop Operator broker** for both active-tab observation and all Browser actions. It must not spawn `osascript`, install a test-only Apple Events callback, or override the stable provider socket; such a test would exercise a different macOS TCC/automation principal and could misattribute a JavaScript permission error to the user's Chrome setting. The E2E preserves the exact active user tab and cleans up only its own created tab. When Chrome reports a JavaScript permission error, inspect the calling provider and Chrome process/profile identity before instructing users to change settings.
+
+The public `PLUGIN_BROWSER_JAVASCRIPT_PERMISSION_REQUIRED` code reports that the **instance selected by Apple Events rejected JavaScript**; it does not prove the visible GUI Chrome checkbox is unchecked. In particular, concurrent Chrome processes using separate `--user-data-dir` roots may make process targeting ambiguous. Preserve the error code for callers but inspect the exact process/profile and real Browser broker invocation. Do not restart Chrome, toggle user settings, or silently switch providers based solely on this code.
+
+The real Chrome E2E also runs a **read-only process-root preflight before the first Apple Event**. If more than one Chrome application root exists (including headless `--user-data-dir` browser instances), it fails with `CHROME_APPLE_EVENTS_TARGET_AMBIGUOUS` instead of claiming the visible Chrome has disabled JavaScript or driving an unproven tab. It never kills the other process or toggles the user's setting. This guard is scoped to the live test harness; it is not an OS-level PID targeting solution for the production AppleScript broker.
+
+Desktop Operator Chrome Apple Events dispatch now has the canonical application-root safety preflight (native commit `cab13fdee`): when a GUI and headless Chrome share the app name, or multiple GUI roots exist, it returns `BROWSER_AUTOMATION_PROCESS_TARGET_AMBIGUOUS` before scripting rather than sending events to an unproven profile; process enumeration failures return `BROWSER_AUTOMATION_PROCESS_PROBE_UNAVAILABLE`. Browser preserves these typed errors, with no provider substitution or guessed Tab identity. This is a fail-closed safety step, not live support for selecting the GUI PID while independent headless Chrome instances remain open.
+
+**PID-bound Chrome update (Desktop Operator commit `3b3c5786`):** Chrome's production Apple Events transport is now the same Desktop Operator provider using `SBApplication(processIdentifier:)`, not name-addressed `osascript`. It selects exactly one non-headless GUI Chrome root, even if separately owned headless/CDP Chrome processes are running. Multiple GUI roots remain ambiguous; losing the verified PID/bundle/executable returns typed nonretryable `BROWSER_AUTOMATION_PROCESS_IDENTITY_LOST`. Forge Browser preserves this error and its live test now permits independent headless Chrome roots. No fallback to name addressing or provider switching. These are source-level changes until separately deployed; final authenticated Chrome Tab and upload E2E remains outstanding.
+
+Desktop Operator native Chrome Apple Event mutation failure is nonretryable `BROWSER_AUTOMATION_MUTATION_OUTCOME_UNKNOWN`; Browser preserves the typed code and `effectOutcome=outcome_unknown`, and requires exact-tab reobservation instead of retry. Read-only native event failures retain nonretryable `BROWSER_AUTOMATION_NATIVE_EVENT_FAILED`. Live E2E can use a test-only Desktop Operator Socket override and releases its Computer provider channel when exiting.
+
+Desktop Operator 0.4.7 is the single Chrome PID authority; Browser Runtime only checks process liveness. Headless Chrome roots may coexist with a unique GUI root. Duplicate Runtime pgrep process-count rejection has been removed; exact Tab ID checks, fail-closed behavior and no provider fallback remain unchanged.

package/docs/operations/controller-performance-and-502.md

@@ -256,6 +256,23 @@ Different repository roots never share a cache entry. When the registry
 is unavailable, Git discovery (`origin/HEAD`, `main`/`master`, current
 branch) is used.
 
+## Autonomous continuation cost boundary
+
+The five-second Scheduler reconciliation is a liveness safety net, not permission
+to replay a terminal provider retry decision. When a failed ControllerRound has
+already consumed `maxFailures`, autonomous continuation skips it until the
+existing provider-environment recovery transition supplies new evidence and
+resets that budget. This prevents an unchanged failed round from becoming a
+five-second error/repair loop.
+
+Automatic Forge incident repair also treats Runtime release provenance as
+existing authority. Source-mode Runtime may resolve repair ownership by exact
+registered checkout path. Immutable/package Runtime resolves it from the staged
+release manifest `sourceRepositoryId`. It must not scan every registered
+repository with synchronous `git cat-file` / `merge-base` calls from the Runtime
+Scheduler path. A package manifest without that repository identity is not
+silently repaired through Git ancestry discovery.
+
 ## Safe Cleanup
 
 Safe source-distribution exclusions:

package/docs/operations/controller-reliability-runbook.md

@@ -68,8 +68,8 @@ A release change is performed only as an explicitly authorized whole-Runtime ope
 1. validate one immutable release manifest, configuration, database compatibility range, and Worker protocol;
 2. quiesce admission and stop the complete Runtime;
 3. atomically select the candidate as the one active whole release;
-4. atomically mirror the selected release's signed `forge-runtime` entrypoint to the fixed physical service path `runtime/service/active-forge-runtime`, then let the single Forge Runtime service start that stable path with the selected release manifest/environment;
-5. require binary whole-Runtime readiness;
+4. atomically mirror the selected release's signed `forge-runtime` supervisor launcher to the fixed physical service path `runtime/service/active-forge-runtime`; the launcher validates the selected release's hashed `forge-runtime-bundle.js` and release-owned Bun interpreter, then starts exactly one interpreter child with the selected manifest/environment and forwards lifecycle/diagnostic signals to it;
+5. require whole-Runtime readiness from the child-owned Runtime owner/status and release canaries; the launcher itself is never a second Runtime authority;
 6. on failure, stop the service, restore the previous release and its bound local SQLite backup, then start and verify the complete previous Runtime.
 
 There is no blue-green pair, fixed alternate port, slot adoption, mixed-generation traffic, or component rollback. Release safety comes from pre-activation canaries, immutable artifacts, one atomic active/previous authority, whole-Runtime readiness, and previous-release recovery.

package/docs/operations/features.md

@@ -8,7 +8,7 @@ These features are part of the default local setup:
 
 - repository registration with stable `repoId` and `checkoutId` identities;
 - bounded repository inspection and context collection;
-- five preferred ChatGPT facade tools: `rh_status`, `rh_access`, `rh_inbox`, `rh_context`, and `rh_work`, plus a stable repair-capable default MCP schema;
+- five structured ChatGPT facade capabilities: `rh_status`, `rh_access`, `rh_inbox`, `rh_context`, and `rh_work`, plus a stable repair-capable default MCP schema;
 - Direct Edit sessions with path limits, SHA preconditions, revisions, savepoints, diffs, checks, and rollback;
 - durable Issue → Task → Run state and resumable evidence;
 - named verification checks instead of arbitrary remote shell access;
@@ -26,19 +26,18 @@ These features are part of the default local setup:
 | Tailscale / Cloudflare | Stable HTTPS endpoint for ChatGPT MCP | Tunnel client and appropriate account/domain configuration. |
 | Browser | Playwright navigation, screenshots, and bounded browser evidence | Browser binaries and HTTP(S) URL scheme validation. |
 | CodeGraph | Additional code relationships and impact navigation | CodeGraph CLI; native Windows automatic setup is not yet enabled. |
-| Google Workspace | Gmail and Calendar plugin actions | Explicit OAuth setup and plugin permission. |
+| Google Workspace | Gmail and Calendar plugin actions | Explicit OAuth setup and plugin permission. The OAuth client ID is non-secret managed configuration; refresh tokens and imported client secrets are stored in the platform credential store. Forge sends `client_secret` when one is stored and otherwise attempts the public-client/PKCE path; the live provider response remains authoritative for whether a specific OAuth client requires the secret. A stored refresh token or configured access token alone is **unverified**, not live-ready. Readiness becomes live-ready only after a successful provider action. If the provider returns `invalid_request: client_secret is missing`, restore the secret matching the configured OAuth client ID in macOS Keychain. If the original secret is irretrievable, configure a dedicated OAuth client ID, store its matching secret in Keychain, and reauthorize: refresh tokens do not transfer between OAuth clients. macOS Keychain is the single credential authority: do not cache refresh tokens or client secrets across external rotations. When the managed OAuth Client ID changes, restart the same running release to reload the environment; a runtime version switch is unnecessary. |
 | Schedules | Supervised recurring checks | Canonical Forge Runtime running; live actions remain policy-gated. |
 
 ## Tool exposure
 
-The default `core` / `advanced` toolset exposes one bounded ChatGPT-facing schema of 19 tools: the five `rh_*` workflow facades (with code retrieval routed through `rh_context.search`), repository selection, `repository_command_execute`, exact source read, `repository_safe_patch_apply`, `run_check`, one typed `plugin_action_execute` dispatcher with plugin schemas routed through `rh_context`, managed process lifecycle, result retrieval, and approval resolution. Git / issue-task / edit-session / other plugin / browser / iOS / maintenance atomics remain registered as internal handlers and are reachable through the `full` compatibility profile when still supported. Retired lifecycles are removed rather than kept as dormant compatibility handlers. The MCP transport does not dynamically load domain schemas.
+Forge exposes one complete MCP tool registry without `facade` / `core` / `advanced` / `full` exposure selectors. The preferred entry points remain the `rh_*` facades, `execute_command` for authorized terminal work, `capability_execute` for typed core actions, and `plugin_action_execute` for provider-owned plugin actions. Other genuinely distinct Git, repository, Process, evidence, browser, iOS, and maintenance capabilities remain public until their callers move to an equivalent canonical action and their duplicate definitions are removed. Tool selection guidance does not hide capability. The MCP transport publishes the full static schema and does not dynamically load domain schemas.
 
 ## Execution choices
 
-- Use Direct Edit for small or well-bounded changes.
-- Use durable Tasks when work must survive sessions, has dependencies, or needs formal review evidence.
-- Delegate to an Agent only when investigation or implementation breadth justifies it.
-- Use named checks to verify results before acceptance.
+- The model can choose direct terminal execution with `execute_command`, bounded source edits, structured retrieval, or domain capabilities without any required Work or Plan.
+- Durable Tasks, agents, and named checks remain optional capabilities for the model to select when they add value.
+- Forge enforces concrete execution authorization, resource isolation and write consistency, but does not choose the model's workflow.
 
 ## Authorization boundaries
 

package/docs/operations/features.zh-CN.md

@@ -26,7 +26,7 @@ Forge 不依赖编码 Agent 或外部插件也能使用。先完成核心工作
 | Tailscale / Cloudflare | 为 ChatGPT MCP 提供稳定 HTTPS 地址 | 隧道客户端及对应账号/域名。 |
 | Browser | Playwright 浏览、截图和证据 | 浏览器 binary 与允许访问的域名。 |
 | CodeGraph | 代码关系和影响范围导航 | CodeGraph CLI；Windows 原生暂不自动配置。 |
-| Google Workspace | Gmail、Calendar 助手能力 | 显式 OAuth 与插件权限。 |
+| Google Workspace | Gmail、Calendar 助手能力 | 显式 OAuth 与插件权限。OAuth Client ID 是非秘密受管配置；refresh token 与导入的 client secret 保存到平台凭据存储。Forge 在凭据存储存在 `client_secret` 时发送它，否则尝试 public-client/PKCE 路径；具体 OAuth client 是否强制要求 secret，以实时 provider 响应为准。仅保存了 refresh token 或配置了尚未验证的 access token，不等于 Gmail 已可用；只有实际 provider 调用成功才标记 live-ready。若 Google 返回 `invalid_request: client_secret is missing`，优先将与当前 OAuth Client ID 匹配的密钥恢复到 macOS Keychain；若旧密钥无法找回，则在唯一受管配置中改用专用 OAuth Client ID，将对应密钥存入 Keychain，再重新授权。不同 OAuth client 之间不能复用原 refresh token。macOS Keychain 是唯一凭据权威，不得跨进程长期缓存 refresh token 或 client secret；受管 OAuth Client ID 修改后，应重启同版本运行进程以重新载入环境配置，无需切换 Runtime 版本。 |
 | Schedule / Finding | 受监督的周期检查和候选发现 | Canonical Forge Runtime 持续运行，真实动作仍受策略控制。 |
 
 ## 工具暴露

package/docs/operations/github-repository.md

@@ -4,9 +4,9 @@ This document records the intended public GitHub configuration for Forge. The re
 
 ## Repository metadata
 
-- **Description:** `Local-first action assistant for durable, reviewable software work.`
-- **Homepage:** `https://github.com/moretea-labs/forge/wiki`
-- **Topics:** `ai-agents`, `ai-assistant`, `chatgpt`, `mcp`, `local-first`, `developer-tools`, `automation`, `agentic-workflow`, `typescript`
+- **Description:** `Local-first ChatGPT MCP runtime for secure computer use, code, browser automation, and developer workflows.`
+- **Homepage:** `https://github.com/moretea-labs/forge/blob/main/docs/README.md` (public versioned docs; the Wiki remains linked from the README)
+- **Topics:** `chatgpt`, `mcp`, `model-context-protocol`, `local-first`, `ai-assistant`, `ai-agents`, `developer-tools`, `browser-automation`, `computer-use`, `coding-assistant`, `workflow-automation`, `typescript`
 - **Features:** Issues, Discussions, Wiki, security policy, and Private Vulnerability Reporting enabled.
 - **License:** MIT, with `NOTICE` and third-party notices preserved.
 
@@ -42,7 +42,7 @@ Use Issues for reproducible defects and scoped feature requests. Use Discussions
 
 ## Documentation ownership
 
-The GitHub Wiki is a presentation target. Versioned source lives under `docs/wiki/`. Deeper engineering detail remains under `docs/architecture/CURRENT.md` and `docs/operations/`.
+The GitHub Wiki is a presentation target. Versioned source lives under `docs/wiki/` and must be explicitly synchronized to the separate `forge.wiki.git` remote after reviewed changes. Public GitHub Pages at `https://moretea-labs.github.io/forge/` is a **generated publication artifact** created by `python3 docs/site/build-pages.py --output /tmp/forge-pages` from these same Markdown sources and published through the `gh-pages` branch. Do not hand-edit generated pages, and re-publish them after changing `docs/wiki/`. The GitHub Pages branch is not a second documentation authority. At low star counts, the Wiki cannot be relied upon for general search engine indexing: prioritize the GitHub About description/topics and repository README for GitHub search, and versioned docs for externally linked canonical content. Deeper engineering detail remains under `docs/architecture/CURRENT.md` and `docs/operations/`.
 
 Public documentation must distinguish current facts from historical evidence. Avoid hard-coding “next release” versions in operational runbooks; derive versions from `package.json` so routine releases do not leave stale docs behind.
 

package/docs/operations/github-semantic-release-projection.md

@@ -0,0 +1,20 @@
+# GitHub semantic release projection
+
+## Purpose
+
+Use one root **Thin Forge Work** for a release and existing explicitly related `semanticParentWorkId` children. Forge Requirement, Plan, Work, controller binding, evidence and scheduler remain authoritative. GitHub Issues are generated **read-only projections of those durable facts**, not a task state store or an approval system.
+
+## Setup
+
+1. Register the repository in Forge; enable its existing GitHub plugin (`repository` set to the corresponding `owner/repo`).
+2. Optional: set `projectOwner` and `projectNumber` to attach the generated Issues to one GitHub Project. The local `gh` account then needs Project scopes (`read:project`, `project`). Plain Issue sync works without Project permissions.
+3. Have the model create/reuse the release Requirement and Plan, then its single primary Work. Only link independently approved or explicitly selected feature Works with `rh_work.revise(semantic_parent_work_id=...)`; **linking does not mean approval**. Continue development through the original Work and controller binding.
+4. Call the existing GitHub plugin action `plugin.github.sync_semantic_release` with `release_work_id` for the root. Re-call on meaningful progress/semantic revisions (for example, from the same ongoing controller continuation workflow). The action reads the current Forge facts each time; it never edits Forge semantics.
+
+The action creates or updates an Issue for each linked primary Work and the root release Work, using the exact `<!-- forge-semantic-work:<id> -->` marker for identity. It finds existing Issues before mutation, refuses ambiguous duplicates, and skips unchanged bodies. It never imports GitHub Issue state as a Work status and never infers user approval, tests or release completion. Exactly-once remote-send uncertainty must be reconciled by a fresh Issue inventory; do not blindly replay unknown creates.
+
+## Explicit limitations
+
+The current action is an **on-demand projection**, not a new scheduler or background daemon. A controller must call it when a Work's semantic content changes; deploying this source to the active Runtime is a separate release decision. Continuation is governed by the existing Forge Scheduler/Controller, not by Issue sync.
+
+Version release acceptance remains an explicit model/human decision based on required evidence and external App Store authority. Never merge 1.0.5 work into a frozen 1.0.4 candidate.

package/docs/operations/homebrew.md

@@ -6,8 +6,8 @@ Homebrew is planned as a convenience layer after the first stable npm/GitHub rel
 
 Do not publish a formula until all of the following are true:
 
-- `@moretea-labs/forge@1.8.0` exists on npm;
-- Git tag and GitHub Release `v1.8.0` exist and point to the tested commit;
+- `@moretea-labs/forge@1.8.2` exists on npm;
+- Git tag and GitHub Release `v1.8.2` exist and point to the tested commit;
 - the npm tarball has an immutable checksum;
 - macOS installation and `forge --version` / `forge doctor` tests pass;
 - upgrade and uninstall behavior is documented.