@moretea-labs/forge 1.8.0 → 1.8.2

package/AGENTS.md

@@ -6,12 +6,65 @@ This repository self-hosts the Forge contract. Retired project-skill and project
 
 Treat ChatGPT as the controller and Forge as its repository execution layer. ChatGPT chooses how to inspect, plan, edit, verify, or delegate. Forge provides deterministic repository tools and does not impose an Agent-first workflow.
 
+- **User-directed verification priority (2026-10-12):** Do not add new automated test cases or test files during normal Forge implementation unless the user explicitly changes this instruction. Prefer direct verification of the real requested workflow and inspect its actual effect/tool receipts; do not substitute expanded mock suites, repeated full test runs, or source-only green checks for a delivered product. Preserve existing unrelated tests, and never weaken exact-target/unknown-send protections to make live acceptance appear successful.
+
+- Scheduling, explicit workspace placement choice, integration timing, baseline activation, delivery, and acceptance are model decisions made from the user's current objective and live repository evidence. Forge supplies callable execution primitives and fixed mechanical compatibility mappings only; it must not infer, gate, override, or auto-advance semantic workflow decisions from a Work transition, executor completion, risk classification, policy, or heuristic. Repository rules guide the model; they are not a Forge workflow state machine.
+
 - Direct Edit is the default for understood work. One session may accept many patch batches, keep revision history, create savepoints, run checks, roll back selected revisions, and finalize one aggregate localized diff.
 - Tasks describe objectives, scope, checks, and acceptance criteria. They do not permanently bind Codex, Claude, or GitHub Copilot. The executor is selected when each Run starts.
 - Agents are optional implementation tools for broad exploration, large refactors, or compile/test/fix loops. They receive a high-level implementation contract; ChatGPT still reviews the result and decides what happens next.
 - Ordinary local risk levels are metadata, not permission gates. There is no approval queue and no `approve_risk` handshake. Only an explicitly destructive or irreversible operation requires authorization in the same request.
 - The Controller UI is an auxiliary configuration/state utility behind ChatGPT: Overview, Work, Automations, Capabilities, Repositories, Settings, and System. It presents durable user-facing state and hides Issue/Task/Run internals unless diagnostics require them.
 - Hard runtime boundaries remain for secrets, credentials, Git internals, concurrent write conflicts, out-of-scope writes when a scope is declared, and remote or irreversible side effects.
+
+### Starting checkout and worktree policy
+
+- `main` is the canonical local integration branch. Bounded Direct Edit/investigation that does not need durable Work normally runs in the selected current checkout.
+- Work lifecycle and Git topology remain separate decisions: Forge never creates durable Work merely to obtain a branch. Once the model explicitly chooses a mutating durable repository Work, legacy/default `auto` placement mechanically means a managed isolated checkout with the Work start revision frozen; explicit `current` means reuse the selected registered checkout.
+- Forge must not infer or rewrite placement from task size, risk text, dirty paths, parallel relations, recovery state, or other semantic context. `auto -> isolated` is a fixed compatibility/mechanical placement contract, not a semantic heuristic.
+- During implementation, a Work may advance only through its own checkout changes/commits. Target-branch advancement is considered only at the delivery/finalization boundary; if an explicitly reused current checkout drifts, return the WorkHandle/Git conflict instead of adopting, rebasing, merging, or switching topology.
+- An isolated worktree is containment, not a semantic integration authority. After successful delivery, remove its managed worktree/branch only after containment and cleanup are proven. Do not accumulate completed worktrees as standing development environments.
+- Do not inspect, activate, switch, certify, or otherwise mutate a source/runtime baseline merely because a Work changes phase or an executor exits. Baseline activation remains a separate model decision after the coherent candidate is reviewed and verified.
+
+### Dirty checkout and cross-Work integration policy
+
+- A Work may freely keep uncommitted changes in its selected checkout while it is implementing, reviewing, or repairing its own candidate. A dirty checkout is normal development state and is not itself a Forge error, lifecycle state, or reason to switch topology.
+- **User-directed conflict-based integration rule (2026-10-15):** A receiving checkout's staged, unstaged, or untracked changes are **not by themselves a merge gate** and do not require the receiving Work to commit first. Inspect exact source and target revisions, merge base, candidate changes, receiving dirty paths and contents, and Git's actual merge result. When the reviewed changes can be integrated without overwriting existing work or changing its index state, proceed through an authorized safe Git path. A coarse `WORK_DELIVERY_TARGET_DIRTY` tool rejection is not evidence of an actual Git merge conflict.
+- If source and receiving changes overlap or Git reports a real conflict, inspect both implementations and resolve the specific semantic difference. Preserve concurrent-writer ownership and mutation leases; those are separate from merely having uncommitted changes. Never repeat a branch whose equivalent changes are already integrated under other commit IDs.
+- Do not auto-stash, auto-reset, auto-clean, silently commit, or discard receiving changes merely to complete integration. Verify that original uncommitted bytes, staged/unstaged distinctions, and untracked files are preserved after a merge. If a primitive cannot preserve them safely, identify the mechanical limitation and choose another authorized, non-destructive integration path.
+- When committed histories conflict, resolve semantically from the merge base, both sides' commits/diffs, and the current Requirement/Plan/Work objective. Preserve the current architecture and replay the other Work's intent onto it when implementation shape has changed; never use `ours`/`theirs`, timestamp, or commit order as a general semantic authority.
+- These are Controller/model workflow rules, not new Forge Kernel policy. Do not add merge lifecycle states, automatic integration policy, or repository guards merely to encode this procedure; Forge should expose the Git/worktree/diff/commit primitives and report real Git or concurrent-writer conflicts mechanically.
+
+## Root-Cause-First Learning Discipline
+
+- Treat a newly observed failure or inefficiency as evidence, not an automatic patch trigger. Accumulate and cluster related symptoms by violated invariant, semantic owner, authority, and lifecycle before changing source.
+- Default learning loop: `observe -> cluster -> identify common root cause -> one coherent correction -> whole-diff review -> focused verification -> institutionalize the reusable rule/capability`. This is the **Root-Cause-First / Batch-Convergence** default; do not turn every symptom into its own patch/Work/validation cycle.
+- **Learn early, trust gradually.** The model decides whether an observation is reusable, how abstract it should be, and the narrowest justified scope. Repetition/evidence may change the model's confidence or support a broader abstraction, but Forge must not use fixed counts, kinds, keywords, scores, or failure frequency as semantic admission/generalization gates.
+- Project observations normally become Project lessons; when the model explicitly judges a distilled principle genuinely cross-project it may record portable Workspace advisory memory. Workspace scope is a semantic choice by the model, not an automatic promotion rule and not restricted to human-authored wording. Neither scope silently overrides product/domain contracts, architecture authority, authorization, Requirement/Plan/Work, acceptance, or verification gates.
+- Emergency containment is narrow: active security exposure, data corruption/loss, production-wide outage, or a foundational blocker that prevents safe investigation may receive the smallest reversible containment first. Containment must be recorded as such and followed by root-cause closure; it is never the final architecture.
+- When a learned pattern can recur, prefer strengthening the existing typed contract, workflow, architecture rule, or gate over retaining a prose-only lesson. Do not create a second learning store, policy authority, lifecycle owner, fallback, or project-specific helper.
+
+## Mandatory Delivery Transaction
+
+### Current Task Lineage Isolation
+
+- The current task is selected by explicit user intent and the exact current Work/Requirement/Plan lineage. Repository-wide active Work is not a task queue.
+- `rh_status`, Plan listings, scheduler inventories, and other global projections may be consulted only to detect path conflicts, writer/authority ownership, blockers, or release admission conditions. They must not cause unrelated Work to enter discovery, implementation, validation, review, release, cleanup, or completion decisions for the current task.
+- Do not switch to another active Work because it looks urgent, is nearby in the repository, shares a broad Requirement, or appears in a global status response. A task switch requires explicit user intent or an explicit typed lineage transition from the current Work/Requirement.
+- When global state contains unrelated active Work, ignore its objectives and evidence unless they directly conflict with the current Work's files/authority or block the current delivery boundary. Record the conflict narrowly; do not absorb the unrelated Work.
+- When reporting progress, count only the current lineage. Repository-wide active counts must be labeled as unrelated inventory and never presented as remaining work for the current task.
+
+For Kernel V2 and other architecture migrations, optimize for one coherent delivery transaction rather than issue-by-issue lifecycle churn.
+
+- Default execution shape: `batch factual discovery -> root-cause/architecture decision -> freeze one delivery scope -> coherent implementation -> whole-diff review -> one focused validation wave -> one canonical-gate wave -> one final delivery -> terminal cleanup`.
+- Do not create a new Work, commit, validation cycle, or release merely because a new symptom, file, or same-root-cause path is discovered. Extend the current candidate when the architecture invariant and delivery objective remain the same.
+- During implementation, do not repeatedly re-check baseline, run broad gates, stage Candidate releases, or activate Runtime baselines. Early checks are reserved for facts that can invalidate the architecture/design or for safety-critical ambiguity.
+- Git commits are delivery/history boundaries, not Work/lifecycle boundaries or scratch savepoints. Preserve intermediate state with the Work/edit-session/savepoint mechanisms and keep related implementation, review fixes, verification repairs, and same-goal Works in the same checkout without committing between them. Default to one semantic commit for the coherent delivery transaction; create additional commits only when they represent genuinely independent, reviewable delivery units. Never create commits whose subject is merely a lifecycle transition such as `Complete work-*`; commit subjects describe the product/architecture/source change, not Forge record ids.
+- Release is a Requirement/candidate boundary, not a per-Work boundary. Do not start Candidate/canary/cutover while source-changing Works for the same delivery remain active or the candidate scope is still moving.
+- A failed focused/canonical check returns to the same candidate and reruns only the affected check set after repair unless the failure invalidates the architecture. Do not restart the entire lifecycle by default.
+- Before opening another Work for an observed defect, cluster symptoms by root cause and owner. If the new fact belongs to the same invariant, keep it in the current Work; only a genuinely independent authority, delivery, security boundary, or architecture decision justifies a sibling Work.
+- Superseded, covered, or delivery-complete Work/Plan records must be reconciled and retired promptly so active lifecycle state represents real remaining work.
+- If lifecycle machinery itself is inefficient but the current V2 candidate can still converge safely, record a bounded post-V2 Plan and defer the machinery refactor. Do not expand the current release scope to fix the workflow that is executing it.
 ## Canonical Workflow Authority
 
 - Root `forge.config.json` is the modern declarative opt-in marker. It selects Controller Home Runtime authority; it is not a mirror of mutable state.
@@ -32,6 +85,9 @@ Treat ChatGPT as the controller and Forge as its repository execution layer. Cha
 - Readiness is one derived whole-system conclusion. Multiple diagnostic checks and reason codes are allowed, but they must not become independent durable readiness state machines.
 - Keep lifecycle, readiness, liveness, capability, authorization, release identity, and diagnostics separate. Do not create composite states such as `status=ready` with `degraded=true`.
 - Only one component may perform lifecycle or recovery side effects. Observers and probes are read-only and submit typed requests to that owner.
+- Autonomous execution is **single-attempt-first**. A normal external mutation should succeed once; retry exists only for a mechanically classified transient failure with preserved causal identity. The same external mutation may have at most **3 total provider attempts** (initial attempt plus at most 2 retries), with exponential backoff and provider Retry-After/cooldown respected.
+- Outcome-unknown observation and provider re-dispatch are different mechanisms. Unknown observation is read-only, must never authorize resend by itself, must have its own durable spacing/budget, and must not poll an unchanged Browser/Computer surface at active tick rate. Prefer event-driven wakeups or materially new evidence; repeated identical unknown observations are diagnostic noise, not progress.
+- Recovery must reduce uncertainty, not create activity. If bounded retries/observations are exhausted, expose one durable blocker/diagnostic fact and stop. Never add an infinite retry loop, watchdog cascade, replacement tab/session, or second recovery owner to make autonomous continuation appear live.
 - Release and rollback scope is the complete compatible Runtime, configuration, entrypoint, and SQLite schema/backup state; component-level rollback is forbidden.
 - Any new process, persistent state, enum value, health mode, authority file, or compatibility fallback requires an explicit architecture decision, transition owner, cleanup/removal criterion, and failure-injection tests.
 - Follow `docs/reference-configs/runtime-architecture-guardrails.md` for the normative review gates and target topology.
@@ -58,14 +114,25 @@ Treat ChatGPT as the controller and Forge as its repository execution layer. Cha
 - Keep Kernel V2 source development on the designated integration/main branch until the integrated candidate is complete. A clean current mainline checkout is the default source-development placement; do not create an isolated branch/worktree merely because a Plan or Work exists. Do not activate a partially migrated slice as the Runtime baseline merely because its local checks pass; baseline activation is a separate candidate-level decision after architecture review and validation.
 - Forge-core additions should solve reusable system capabilities or preserve a Kernel invariant. Do not expand Forge with project-specific one-off machinery when an adapter/plugin or existing general primitive is the correct owner.
 
+### Verification & Test Value Discipline
+
+- Implementation is architecture- and behavior-first, not test-first. A failing historical test is evidence to inspect, not an instruction to preserve the old implementation. When a test conflicts with the current accepted architecture/authority model, decide the intended source contract first; update or delete the stale test instead of bending production code back toward retired semantics.
+- Keep tests only when a failure would indicate a realistic product or mechanical-safety defect that static contracts cannot prove cheaply. High-value examples include stale-CAS no-write guarantees, non-idempotent effect dedupe/outcome-unknown reconciliation, authorization boundaries, concrete Process/Git/worktree/resource ownership, crash/restart recovery, Runtime/Recovery reconnect, release/rollback integrity, and real end-to-end continuation behavior.
+- Delete tests whose only purpose is to assert retired implementation shape, internal field presence, legacy lifecycle/phase ordering, obsolete error strings, deprecated Controller/Work ownership gates, or compatibility behavior that the current architecture explicitly removes. Do not keep such tests merely for coverage or historical symmetry.
+- Prefer the cheapest authoritative proof for each invariant: TypeScript/compiler contracts -> architecture/import/AST fences -> focused behavior/E2E scenario -> broader regression suite. Do not duplicate a structural invariant with an expensive Runtime test when a maintained architecture fence already proves it.
+- Do not add unit tests by default during architecture refactors. Add a focused test only when it protects a concrete regression class that cannot be covered more directly by a compiler/architecture fence or an existing end-to-end behavior check.
+- **Current Kernel V2 convergence rule:** do not add any new test files or new test cases while the active migration is removing duplicate lifecycle/provider authorities. Govern the existing suite first: keep only tests that still protect an accepted external behavior or safety invariant, update a retained test only when its invariant still exists, and delete stale tests together with the retired API/path they assert. This temporary freeze ends only after the single-authority Runtime candidate is accepted and the remaining suite has been reclassified by value.
+- A production API, compatibility shim, state, branch, fallback, or provider path must never be restored or retained solely to satisfy an existing test. When production architecture and a historical test disagree, the accepted architecture wins and the stale test is deleted.
+- Inner-loop verification must stay narrow. Run only checks that can change the next implementation decision. Broad suites are candidate-level evidence, not a per-edit ritual. A green obsolete test suite is not delivery evidence; a failing obsolete test is not a blocker once its retired contract is deliberately removed.
+
 ## Operating Rules
 
 - Default to end-to-end execution and minimize avoidable human intervention. Continue reversible, policy-allowed implementation, verification, cleanup, and delivery; stop only at a genuine user-only identity/legal/financial/strong-confirmation/irreversible boundary.
 - Work top-down: requirement/product intent -> product interaction when relevant -> architecture/authority -> implementation -> focused verification -> independent review -> delivery/terminal cleanup. Do not repeatedly patch symptoms while a higher-level contract remains wrong.
-- Direct execution is preferred for bounded understood work. Create durable Plan/Work only for real decomposition, continuity, scheduling, recovery, independent delivery, or external effects; durable Work/Plan authority by itself does not require an isolated checkout.
-- Repository placement is mainline-first: when the current designated main/integration checkout is clean enough for the owned paths and no competing writer owns overlapping paths, edit and validate there directly.
-- Create an isolated branch/worktree only for a concrete placement reason: an active concurrent writer or dirty-path ownership conflict that cannot be safely reconciled in place, an explicitly independent delivery that must remain separately mergeable, a destructive/high-risk experiment that genuinely requires containment, or a branch/policy constraint that forbids current-main mutation. Do not use task size, multi-step execution, recovery, or the mere existence of a WorkContract as isolation reasons.
-- When isolation is necessary, record the concrete conflict/reason, merge or reconcile the result promptly once validated, and delete the temporary branch/worktree immediately after delivery. Do not accumulate completed managed worktrees.
+- Direct execution is preferred for bounded understood work. Create durable Plan/Work only for real decomposition, continuity, scheduling, recovery, independent delivery, or external effects; durable Work/Plan authority by itself does not require an isolated checkout and does not create a Git commit boundary.
+- Repository placement is sticky once selected for a coherent delivery. Direct execution reuses the explicitly selected current checkout; mutating durable repository Work defaults through legacy `auto` to one isolated frozen-base checkout and reuses that checkout across implementation/review/verification. Never switch placement mid-Work merely because target state changes.
+- For mutating durable repository Work, `auto` is the fixed isolated/frozen-base default; `current` is an explicit reuse choice. Do not let Forge infer topology from task size, risk text, dirty-path heuristics, parallel relations, recovery, or other semantic context; actual occupancy and Git identity conflicts are reported mechanically at execution time.
+- After isolated delivery is selected and validated, integrate/reconcile at the delivery boundary and delete the temporary branch/worktree after containment and cleanup are proven. Do not accumulate completed managed worktrees.
 - For authenticated browser work, preserve the user's explicitly selected/signed-in browser identity; never silently create a replacement authentication state.
 - After a managed repository change is verified and committed/merged, push the delivered target branch promptly unless the user requested local-only delivery or a concrete safety/auth/branch-policy blocker exists.
 - Treat unrelated dirty work as ownership/placement evidence. Isolate or reconcile it; never absorb it merely to make the tree look clean.
@@ -77,7 +144,7 @@ Treat ChatGPT as the controller and Forge as its repository execution layer. Cha
 
 ## Required Checks
 
-For affected Forge-core changes, select focused checks from the registered Process Runtime surfaces. At architecture/runtime-boundary candidate points include at least:
+For affected Forge-core changes, select the smallest verification set that proves the changed architecture and real safety boundaries. At architecture/runtime-boundary candidate points normally include:
 
 ```bash
 bun run check:type
@@ -85,10 +152,9 @@ bun run check:repository-hygiene
 bun run check:runtime-architecture
 bun run check:architecture-sync
 bun run check:bootstrap-files
-bun run test
 ```
 
-`bun run check:main` is the candidate-level governed gate after focused failures are resolved. Full-suite testing remains explicit through `bun run test:full`; do not substitute a huge suite for targeted diagnosis.
+Add focused behavior/E2E tests only for the concrete risk being changed. `bun run test` is not a mandatory inner-loop or candidate prerequisite by itself; run it only when its curated cases materially cover the candidate. `bun run check:main` remains the candidate-level governed gate, but obsolete tests/contracts must be deleted or removed from that gate rather than forcing production code to preserve retired architecture. Full-suite testing remains explicit through `bun run test:full`; do not substitute a huge suite for targeted diagnosis.
 
 <!-- BEGIN ARCHITECTURE CONTRACT -->
 ## Architecture Contract

package/CHANGELOG.md

@@ -4,6 +4,40 @@ All notable public Forge changes are recorded here. Release entries are tied to
 
 ## Unreleased
 
+## 1.8.2 - 2026-10-19
+- Retire Forge-owned host Skill distribution and independent Skill version authority, retaining CLI/MCP and project templates.
+
+### Reliable autonomous delivery
+
+- Restore exact ChatGPT conversation targeting and recover lost Chrome tab/provider bindings without replaying an uncertain external send.
+- Harden Supervisor effect-ledger ownership, no-click dispatch proofs, bootstrap reconciliation, stale composer recovery, and Chrome Native Messaging heartbeat handling.
+- Stop Work-owned auto-progression after semantic completion while retaining exact request identity and terminal receipts.
+
+### Plugins and scheduled workflows
+
+- Persist Browser plugin v1/v2 configuration migrations into the single Controller Home v3 authority, with atomic write and legacy retirement.
+- Tighten scheduled Gmail digests, fixed-mailbox authorization, unknown notification receipts, and daily wake identity.
+
+### Runtime and packaging
+
+- Make Process Runner release canaries authoritative before promoting immutable package/Runtime releases; reject broken runner artifacts and invalid execution modes.
+- Strengthen Recovery release ownership, package validation, whole-Runtime rollback boundaries, and source/runtime identity.
+
+
+## 1.8.1 - 2026-09-19
+
+### Automatic workflows and V2
+
+- Stabilize the durable Workflow Supervisor boundary for automatic cross-turn continuation, exact effect identity, restart recovery, and same-principal conversation isolation.
+- Harden the native ChatGPT adapter against provider-owned generation state and DOM-added UI text while preserving unique effect-marker confirmation.
+- Preserve explicit `DONE` and `NEEDS_USER` validation while keeping provider, MCP, schedule, and ordinary Forge failures on autonomous recovery paths.
+- Harden schedule progression, duplicate-wake suppression, settlement fencing, and bounded maintenance backoff across manual, repository-event, condition, cron, and calendar triggers.
+
+### Runtime and release readiness
+
+- Reuse the held Recovery mutation lock during configured release-session cutover so whole-release activation cannot race its enclosing Recovery authority.
+- Keep runtime residue outside the source tree and remove real external repository identifiers from the tracked public surface.
+
 ## 1.8.0 - 2026-09-13
 
 ### Controller and workflow authority

package/CLAUDE.md

@@ -12,6 +12,21 @@ Treat ChatGPT as the controller and Forge as its repository execution layer. Cha
 - Ordinary local risk levels are metadata, not permission gates. There is no approval queue and no `approve_risk` handshake. Only an explicitly destructive or irreversible operation requires authorization in the same request.
 - The Controller UI is hierarchical: Overview, Work, Activity, and Settings. Work is organized as Issue -> Task -> Execution instead of exposing every technical record as a top-level destination.
 - Hard runtime boundaries remain for secrets, credentials, Git internals, concurrent write conflicts, out-of-scope writes when a scope is declared, and remote or irreversible side effects.
+### Dirty checkout and cross-Work integration policy
+
+- A Work may keep uncommitted changes in its selected checkout while advancing its own candidate; dirty state is normal development state, not a Forge lifecycle condition.
+- Before integrating another Work/branch into that checkout, first converge the receiving Work's own changes into a coherent semantic commit. Cross-Work integration should therefore operate on explicit committed provenance, while implementation inside one Work may remain dirty until that boundary.
+- Do not auto-stash, auto-reset, auto-clean, or silently discard local changes to make integration possible. When committed histories conflict, use the merge base, both sides' commits/diffs, and the current Requirement/Plan/Work intent for semantic reconciliation rather than generic `ours`/`theirs` precedence.
+- This is model workflow guidance, not a request for new Forge merge states, policy engines, or code gates. Forge provides repository primitives and reports actual Git/concurrent-writer conflicts; the controller decides when and how to integrate.
+
+## Root-Cause-First Learning Discipline
+
+- Treat a newly observed failure or inefficiency as evidence, not an automatic patch trigger. Accumulate and cluster related symptoms by violated invariant, semantic owner, authority, and lifecycle before changing source.
+- Default learning loop: `observe -> cluster -> identify common root cause -> one coherent correction -> whole-diff review -> focused verification -> institutionalize the reusable rule/capability`.
+- The model decides whether an observation is reusable, how far to abstract it, and whether it remains Project-local or is genuinely portable Workspace guidance. Forge may validate scope/provenance/evidence and bound transport/recall resources, but fixed kinds, keywords, failure/repetition counts or score thresholds must not become semantic learning/generalization gates. Learned guidance never silently overrides product/domain contracts, architecture authority, authorization, or verification gates.
+- Emergency containment is narrow: active security exposure, data corruption/loss, production-wide outage, or a foundational blocker that prevents safe investigation may receive the smallest reversible containment first. Containment must be recorded as such and followed by root-cause closure; it is never the final architecture.
+- When a learned pattern can recur, prefer strengthening the existing typed contract, workflow, architecture rule, or gate over retaining a prose-only lesson. Do not create a second learning store, policy authority, lifecycle owner, fallback, or project-specific helper.
+
 ## Canonical Workflow Authority
 
 - Root `forge.config.json` is the modern declarative opt-in marker. It selects Controller Home Runtime authority; it is not a mirror of mutable state.
@@ -49,9 +64,9 @@ Treat ChatGPT as the controller and Forge as its repository execution layer. Cha
 
 - Default to end-to-end execution and minimize avoidable human intervention. Continue reversible, policy-allowed implementation, verification, cleanup, and delivery; stop only at a genuine user-only identity/legal/financial/strong-confirmation/irreversible boundary.
 - Work top-down: requirement/product intent -> product interaction when relevant -> architecture/authority -> implementation -> focused verification -> independent review -> delivery/terminal cleanup. Do not repeatedly patch symptoms while a higher-level contract remains wrong.
-- Direct execution is preferred for bounded understood work. Create durable Plan/Work only for real decomposition, continuity, isolation, scheduling, recovery, independent delivery, or external effects.
+- Direct execution is preferred for bounded understood work and normally uses the current main/integration checkout. Create durable Plan/Work only for real decomposition, continuity, scheduling, recovery, independent delivery, or external effects. Once the model explicitly chooses a mutating durable repository Work, `auto` placement freezes its start revision in a managed checkout; canonical/current reuse is explicit, HEAD drift is never auto-adopted, and target integration waits until the final delivery boundary.
 - For authenticated browser work, preserve the user's explicitly selected/signed-in browser identity; never silently create a replacement authentication state.
-- After a managed repository change is verified and committed/merged, push the delivered target branch promptly unless the user requested local-only delivery or a concrete safety/auth/branch-policy blocker exists.
+- Git commits are delivery/history boundaries, not per-Work checkpoints. Keep same-goal implementation, review fixes, and verification repairs uncommitted in the same checkout until a coherent delivery boundary; default to one semantic commit, split only for genuinely independent reviewable delivery units, and never use lifecycle-only subjects such as `Complete work-*`. After the coherent delivery is committed/merged, push the target branch promptly unless the user requested local-only delivery or a concrete safety/auth/branch-policy blocker exists.
 - Treat unrelated dirty work as ownership/placement evidence. Isolate or reconcile it; never absorb it merely to make the tree look clean.
 - Current Runtime hooks are central-first/package-owned. Modern `forge.config.json` repositories must not materialize repo-local `.ai/harness`, `.codegraph`, `.claude` session state, generated task lifecycle files, or mutable Plugin config from prompt routing. Legacy readers/hooks exist only to migrate older projects.
 - `_ref/` is an ignored external-reference checkout cache; `_ops/` is ignored/private operational residue only while legacy/external tooling requires it. Neither is a source authority.

package/CONTRIBUTING.md

@@ -28,7 +28,7 @@ bun bin/forge.mjs --help
 
 Forge has no previous-product command aliases. New documentation, tests, fixtures, and examples must use the Forge package, command, state, and protocol names unless they are explicitly asserting that a retired surface is absent.
 
-Run focused tests while working. Before requesting review, run the checks relevant to the change; public and release-facing changes should normally include:
+Run the cheapest authoritative checks while working. Prefer compiler/type and architecture/import gates before behavior tests. Before requesting review, run the checks relevant to the change; public and release-facing changes should normally include:
 
 ```bash
 npm run check:type
@@ -55,7 +55,8 @@ smoke and publish. `test:full` is a manual diagnostic only.
 - Do not commit Controller Home, `.ai/harness` runtime state, local jobs, logs, worktrees, tokens, OAuth material, or machine-specific paths.
 - Prefer an isolated worktree or a dedicated branch. Do not mix unrelated fixes.
 - Preserve structured authorization boundaries. Remote writes, destructive actions, and secret access must remain explicit.
-- Add or update tests for behavior changes.
+- Do not add tests mechanically for every behavior change. Keep or update a test only when it protects an accepted externally meaningful behavior or mechanical-safety invariant that cheaper compiler/architecture checks do not already prove. Delete tests that assert retired implementation shape, lifecycle ordering, compatibility paths, or removed APIs instead of restoring production code for them.
+- During the current Kernel V2 single-authority convergence, do not add new test files or test cases. First reduce the existing suite to high-value architecture/safety/E2E coverage; use existing type and architecture gates plus retained behavior tests for validation.
 - Keep the root README user-focused. Detailed architecture and operations belong in `docs/` and the GitHub Wiki source under `docs/wiki/`.
 - English and Simplified Chinese are the maintained public documentation languages. Other translation landing pages must clearly identify themselves as unmaintained unless a maintainer owns them.
 - Do not bump a package version or create a release tag without following [the release process](docs/operations/releasing.md).

package/README.en.md

@@ -1,5 +1,26 @@
-# Forge
+# Forge — local-first ChatGPT MCP action runtime
 
-Forge is a local-first action runtime for bounded, resumable and reviewable software work.
+Forge connects ChatGPT (or another selected external MCP controller) to permission-scoped operations on your computer, code repositories, browser, and connected services. **ChatGPT decides; Forge executes, persists, and verifies.** Forge is not an internal AI coding model and does not require a separate OpenAI API key when using ChatGPT as the controller.
 
-See [README.md](README.md) for installation, product identity, architecture entry points and operating guidance.
+## Install and connect
+
+Requires Node.js 20.10+ and npm (or Bun).
+
+```bash
+npm install -g @moretea-labs/forge@latest
+forge --version
+forge setup
+forge setup configure --controller chatgpt --tunnel auto
+forge setup next
+```
+
+Supported hosts: macOS and modern Linux; use WSL2 for the recommended Windows path. Native Windows is a preview with a limited portable Runtime scope. Git is needed only for repository development features.
+
+## Learn more
+
+- See [README.md](README.md) for the maintained English product overview, capability descriptions, and security model.
+- [Installation and setup](docs/tutorials/01-install-and-start.md)
+- [Connect ChatGPT over MCP](docs/tutorials/02-connect-chatgpt.md)
+- [Features and providers](docs/operations/features.md)
+- [Docs](docs/README.md) · [GitHub Wiki](https://github.com/moretea-labs/forge/wiki)
+- [Latest stable release (v1.8.1)](https://github.com/moretea-labs/forge/releases/tag/v1.8.1) · [npm package](https://www.npmjs.com/package/@moretea-labs/forge)

package/README.md

@@ -2,9 +2,11 @@
 
 <p align="center"><img src="docs/images/forge-banner.svg" alt="Forge — ChatGPT decides, Forge acts" width="1280"></p>
 <p align="center"><strong>Give ChatGPT real, controlled hands on your computer, code, browser, and services.</strong></p>
-<p align="center"><a href="#english">English</a> · <a href="#zh-cn">简体中文</a> · <a href="docs/README.md">Docs</a> · <a href="docs/operations/features.md">Features</a> · <a href="docs/forge-plugin-management.md">Plugins</a> · <a href="https://github.com/moretea-labs/forge/releases">Releases</a></p>
+<p align="center"><a href="#english">English</a> · <a href="#zh-cn">简体中文</a> · <a href="https://moretea-labs.github.io/forge/">Documentation Site</a> · <a href="docs/README.md">Docs</a> · <a href="docs/operations/features.md">Features</a> · <a href="docs/forge-plugin-management.md">Plugins</a> · <a href="https://github.com/moretea-labs/forge/releases">Releases</a></p>
 <p align="center"><img alt="CI" src="https://github.com/moretea-labs/forge/actions/workflows/ci.yml/badge.svg"> <img alt="Release" src="https://img.shields.io/github/v/release/moretea-labs/forge?include_prereleases&sort=semver"> <img alt="npm latest" src="https://img.shields.io/npm/v/%40moretea-labs%2Fforge?tag=latest&label=npm%20latest"> <img alt="License" src="https://img.shields.io/github/license/moretea-labs/forge"></p>
 
+**Forge is a local-first ChatGPT MCP action runtime** for permission-scoped computer use, software engineering, browser automation, and connected services. It is not an autonomous coding model or a hosted AI API.
+
 **Forge has no internal AI brain.** One external controller owns semantic decisions; Forge provides the controlled execution, state, permissions, and recovery layer. ChatGPT is the recommended controller, but you can choose Codex, Claude, or another MCP client instead, and you may configure several controller entries while keeping one primary controller at a time.
 
 With ChatGPT as the controller, Forge does **not** require a separate OpenAI API key or a second per-token model budget. Your existing ChatGPT plan/session limits still apply. Codex and Claude are not Forge dependencies unless you explicitly choose or configure them.
@@ -52,20 +54,22 @@ For a reviewed source checkout: `git clone https://github.com/moretea-labs/forge
 
 ## Built in, and extensible
 
-Forge ships typed local/browser/desktop/iOS/GitHub/Gmail/Calendar/Tasks/App Store Connect/Resend capabilities. On macOS, manage the native **Computer** capability with `forge computer setup|status|doctor|update|uninstall`; Forge Desktop Operator remains the independently released native provider behind that product surface. The generic provider catalog also includes **Forge Design** and **Personal Knowledge Assistant** and remains available through `forge plugin catalog` / `forge plugin install <id>`. See [Features](docs/operations/features.md) and [Plugin Management](docs/forge-plugin-management.md).
+Forge ships typed local/browser/desktop/iOS/GitHub/Gmail/Calendar/Tasks/App Store Connect/Resend capabilities. On macOS, manage the native **Computer** capability with `forge computer setup|status|doctor|update|uninstall`; Forge Desktop Operator remains the independently released native provider behind that product surface. The generic provider catalog also includes **Forge Design** and **Personal Knowledge Assistant** and remains available through `forge plugin catalog` / `forge plugin install <id>`. Run `forge computer doctor` to verify readiness; updating the Forge CLI does **not** automatically update pinned native providers. See [Computer and Plugins](docs/wiki/Computer-and-Plugins.md), [Features](docs/operations/features.md), and [Plugin Management](docs/forge-plugin-management.md).
 
 ## Controlled by design
 
 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.7.0`; stable installs use npm `latest`.
+**Docs:** [GitHub Wiki](https://github.com/moretea-labs/forge/wiki) · [Wiki source](docs/wiki/Home.md) · [Support](SUPPORT.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md). Current stable release: [`v1.8.2`](https://github.com/moretea-labs/forge/releases/tag/v1.8.2); stable installs use npm `latest`.
 
 ---
 <a id="zh-cn"></a>
 
 <p align="center"><img src="docs/images/forge-banner-cn.svg" alt="Forge——ChatGPT 决策，Forge 执行" width="1280"></p>
 <p align="center"><strong>让 ChatGPT 真正、安全地操作你的电脑、代码、浏览器和外部服务。</strong></p>
-<p align="center"><a href="#english">English</a> · <a href="#zh-cn">简体中文</a> · <a href="docs/README.zh-CN.md">中文文档</a> · <a href="docs/operations/features.zh-CN.md">功能</a> · <a href="docs/forge-plugin-management.md">插件</a></p>
+<p align="center"><a href="#english">English</a> · <a href="#zh-cn">简体中文</a> · <a href="https://moretea-labs.github.io/forge/Computer-and-Plugins.zh-CN.html">中文 Computer 教程</a> · <a href="docs/README.zh-CN.md">中文文档</a> · <a href="docs/operations/features.zh-CN.md">功能</a> · <a href="docs/forge-plugin-management.md">插件</a></p>
+
+**Forge 是一个本地优先的 ChatGPT MCP 执行运行时**，将 AI 对话连接到有权限边界的电脑操作、代码开发、浏览器自动化和外部服务，而不是额外的在线 AI 模型。
 
 **Forge 自己没有 AI 大脑。** 语义判断始终由一个外部主控负责，Forge 负责受控执行、持久状态、权限和恢复。推荐 ChatGPT，也可以明确选择 Codex、Claude 或其他 MCP 客户端；可以预配置多个入口，但同一时刻只有一个主控负责决策。
 
@@ -105,8 +109,8 @@ forge setup next     # 按每次显示的 Next 动作继续
 
 继续阅读[安装与启动](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 等类型化能力。macOS 原生 **Computer** 能力统一通过 `forge computer setup|status|doctor|update|uninstall` 管理；Forge Desktop Operator 仍作为其独立发布的原生 Provider 保持稳定身份。通用 Provider 目录还包含 **Forge Design / Personal Knowledge Assistant**，继续使用 `forge plugin catalog` / `forge plugin install <id>` 管理。详见[功能清单](docs/operations/features.zh-CN.md)与[插件管理](docs/forge-plugin-management.md)。
+Forge 内置本机、Browser、Desktop、iOS、GitHub、Gmail、Calendar、Tasks、App Store Connect、Resend 等类型化能力。macOS 原生 **Computer** 能力统一通过 `forge computer setup|status|doctor|update|uninstall` 管理；Forge Desktop Operator 仍作为其独立发布的原生 Provider 保持稳定身份。通用 Provider 目录还包含 **Forge Design / Personal Knowledge Assistant**，继续使用 `forge plugin catalog` / `forge plugin install <id>` 管理。升级 Forge CLI 不会自动升级独立 Provider；Computer 用户须运行 `forge computer update`，并用 `forge computer doctor` 检查状态。详见 [Computer 与插件安装指南](docs/wiki/Computer-and-Plugins.md)、[功能清单](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.7.0`，稳定安装使用 npm `latest`。
+**文档：** [GitHub Wiki](https://github.com/moretea-labs/forge/wiki) · [Wiki source](docs/wiki/Home.md) · [支持](SUPPORT.md) · [贡献](CONTRIBUTING.md) · [更新日志](CHANGELOG.md)。当前稳定版为 [`v1.8.2`](https://github.com/moretea-labs/forge/releases/tag/v1.8.2)，稳定安装使用 npm `latest`。

package/README.zh-CN.md

@@ -5,6 +5,8 @@
 <p align="center"><a href="https://github.com/moretea-labs/forge#english">English</a> · <a href="https://github.com/moretea-labs/forge#zh-cn">仓库首页中文</a> · <a href="docs/README.zh-CN.md">中文文档</a> · <a href="docs/operations/features.zh-CN.md">功能清单</a> · <a href="https://github.com/moretea-labs/forge/releases">版本发布</a></p>
 <p align="center"><img alt="CI" src="https://github.com/moretea-labs/forge/actions/workflows/ci.yml/badge.svg"> <img alt="Release" src="https://img.shields.io/github/v/release/moretea-labs/forge?include_prereleases&sort=semver"> <img alt="npm latest" src="https://img.shields.io/npm/v/%40moretea-labs%2Fforge?tag=latest&label=npm%20latest"> <img alt="License" src="https://img.shields.io/github/license/moretea-labs/forge"></p>
 
+**Forge 是本地优先的 ChatGPT MCP 执行工具**：通过权限受控的 Runtime，让 ChatGPT 操作电脑、Git 仓库、浏览器和已授权服务；也支持选择其他外部主控。
+
 **Forge 自己没有 AI 大脑。** 每次语义决策都由一个外部主控负责，Forge 负责执行、持久状态、权限和恢复。默认推荐 ChatGPT，也可以明确选择 Codex、Claude 或其他 MCP 客户端；可以配置多个控制入口，但同一时刻只有一个主控拥有语义控制权。
 
 选择 ChatGPT 时**不要求单独配置 OpenAI API Key，也不需要额外准备一套按 token 计费的模型预算**；仍受你的 ChatGPT 套餐和会话限制。没有选择 Codex/Claude，就不会把它们当成安装或就绪依赖。
@@ -68,7 +70,7 @@ 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**。运行 `forge plugin catalog` 查看当前固定版本目录，详见[插件管理](docs/forge-plugin-management.md)和[功能清单](docs/operations/features.zh-CN.md)。
+Forge 内置本机、Browser、Desktop、iOS、GitHub、Gmail、Calendar、Tasks、App Store Connect、Resend 等类型化插件；公开 Provider 目录还提供 **Forge Desktop Operator**、**Forge Design**、**Personal Knowledge Assistant**。运行 `forge plugin catalog` 查看当前固定版本目录，CLI 升级不会自动更新这些 Provider。macOS Computer 使用 `forge computer update` 和 `forge computer doctor` 更新并检查，其他 Provider 需按官方 pin 重新安装。详见 [Computer 与插件安装指南](docs/wiki/Computer-and-Plugins.md)、[插件管理](docs/forge-plugin-management.md)和[功能清单](docs/operations/features.zh-CN.md)。
 
 ## 安全不是宣传词
 
@@ -76,6 +78,6 @@ Forge 把读取、普通本地写入、远程操作、破坏性操作、工作
 
 ## 文档与项目
 
-[中文文档中心](docs/README.zh-CN.md) · [Wiki](docs/wiki/Home.md) · [SUPPORT.md](SUPPORT.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [CHANGELOG.md](CHANGELOG.md)
+[Computer 中文教程](https://moretea-labs.github.io/forge/Computer-and-Plugins.zh-CN.html) · [中文文档中心](docs/README.zh-CN.md) · [GitHub Wiki](https://github.com/moretea-labs/forge/wiki) · [Wiki 源码](docs/wiki/Home.md) · [SUPPORT.md](SUPPORT.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [CHANGELOG.md](CHANGELOG.md)
 
-当前稳定版本是 `1.7.0`，稳定安装使用 npm `latest`。
+当前稳定版本为 [`v1.8.1`](https://github.com/moretea-labs/forge/releases/tag/v1.8.1)，稳定安装使用 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.8.0`.
+This inventory covers the direct runtime and development dependencies declared by `@moretea-labs/forge@1.8.2`.
 
 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.
 
@@ -16,7 +16,6 @@ License values come from `package-lock.json` where available. For lock entries w
 | `react` | `19.2.8` | runtime | `MIT` | package metadata |
 | `react-dom` | `19.2.8` | runtime | `MIT` | package metadata |
 | `agent-device` | `0.20.2` | optional runtime (iOS/Android device automation provider) | `MIT` | package-lock.json |
-| `@colbymchenry/codegraph` | `1.0.1` | development | `MIT` | package-lock.json |
 | `@types/bun` | `1.3.14` | development | `MIT` | package-lock.json |
 | `@types/cors` | `2.8.19` | development | `MIT` | package-lock.json |
 | `@types/express` | `5.0.6` | development | `MIT` | package-lock.json |

package/adapters/chatgpt/browser-delivery-host.ts

@@ -57,8 +57,14 @@ export function createChatgptBrowserDeliveryHost(operations: ChatgptBrowserDeliv
         };
       } catch (error) {
         const providerError = chatgptProviderError(error, 'CHATGPT_CONTROLLER_BROWSER_FAILED');
+        // SUBMISSION_NOT_CONFIRMED is only a known failure when no provider-side
+        // conversation identity appeared. A new /c/<id> means the send may have
+        // committed despite lagging DOM confirmation, so preserve outcome_unknown.
+        const status = providerError.code === 'CHATGPT_AUTOMATION_SUBMISSION_NOT_CONFIRMED' && providerError.conversationUrl
+          ? 'outcome_unknown'
+          : classifyChatgptProviderFailure(providerError.code, providerError.message);
         return {
-          status: classifyChatgptProviderFailure(providerError.code, providerError.message),
+          status,
           provider: 'controller-browser',
           browserSessionId: effectiveBrowserSessionId,
           conversationUrl: providerError.conversationUrl ?? input.targetUrl,