@moretea-labs/forge 1.7.1 → 1.8.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # Forge AGENTS.md
 
-This repository self-hosts the Forge contract. Retired project-skill and project-initializer staging paths are not supported or cleaned up by current tooling. Claude and Codex should follow the same repo-local workflow surface.
+This repository self-hosts the Forge contract. Retired project-skill and project-initializer staging paths are not supported or cleaned up by current tooling. Claude and Codex should follow the same Controller-first authority model; mutable workflow state is Controller-owned, not a repo-local file protocol.
 
 ## Forge execution runtime
 
@@ -12,28 +12,23 @@ 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 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.
-## Canonical Workflow Files
-
-- `tasks/current.md` for the tracked current-status snapshot derived from workflow artifacts
-- `tasks/todos.md` for deferred medium/long-term goals, not active execution checklists
-- `plans/prds/` for upper-layer PRDs; `plans/sprints/` for ordered sprint backlogs operated through `scripts/sprint-backlog.sh` (installed implementations live under `.ai/harness/scripts/`; task contracts stay the execution slices)
-- `.ai/context/capabilities.json` for the capability registry and longest-prefix context boundaries
-- `tasks/workstreams/` for capability long-running workstreams that project durable progress into local contracts
-- `tasks/lessons.md` for correction-derived rules
-- `docs/researches/` for deep repo knowledge
-- `tasks/notes/` for task-local implementation decisions, deviations, tradeoffs, and open questions
-- `plans/` for timestamped plans, with `plans/archive/` for history
-- `.ai/harness/workflow-contract.json` for the installed workflow contract manifest
-- `.ai/harness/policy.json` for the machine-readable workflow contract
-- `.ai/context/context-map.json` for progressive context loading
-- `docs/architecture/index.md` for umbrella architecture status, drift requests, snapshots, and diagram links
-- `docs/reference-configs/agentic-development-flow.md` for Forge task routing and optional host-skill enhancements
+## 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.
+- Mutable Requirement/Plan/Work/ControllerRound, Process/Job, Schedule, lease/resource, authorization, verification, Plugin config, session/binding, evidence and recovery state belongs in Controller Home.
+- Repository-authored durable surfaces include source/tests, `docs/spec.md`, `docs/researches/`, `tasks/todos.md`, `tasks/lessons.md`, architecture docs, and intentional human-authored project plans/config.
+- `tasks/current.md`, `tasks/contracts/`, `tasks/reviews/`, `tasks/notes/`, `tasks/workstreams/`, `.ai/harness/**`, repo-local Plugin mutable config, and repo-local cache/session state are legacy migration inputs, not current machine authority and must not be recreated by new producers.
+- Git history is the repository source-history archive. Runtime history/receipts use Controller Home retention policy rather than repository archive directories.
+- `.ai/context/capabilities.json` may remain declarative capability/context metadata while it is still part of the source contract; it must not point at retired runtime workstream directories.
+- `docs/architecture/CURRENT.md` is maintained architecture authority; executable code and persisted schemas remain authoritative implementation evidence.
+- Host/global prompt files explain working behavior but do not authorize mutation, own lifecycle, or declare completion.
 
 ## Runtime Architecture Guardrails
 
 - Treat Forge as one local MCP application, one active Runtime, one deployable release, and one in-process lifecycle owner. Gateway, MCP transport, Controller, and Scheduler may be modules; they are not independently deployable generations by default.
 - Bounded restart downtime is acceptable. Prefer `stop -> switch complete release -> start -> verify -> full rollback`; do not add ingress, blue/green slots, adoption, or mixed generations without an explicit product requirement.
 - Do not respond to an incident by adding a second status authority, daemon, proxy, KeepAlive wrapper, watchdog, recovery owner, or fallback path; extend the canonical Runtime or standalone Recovery owner instead. First identify the violated invariant and remove, merge, or correct the existing cause.
+- When a concrete scenario exposes a missing capability, strengthen an existing general capability and reuse its authority/lifecycle first. Add a specialized plugin, module, script, or helper only when an independent authority, security, protocol, persistence, or lifecycle boundary is proven; incident-specific helpers are temporary debt otherwise.
 - 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.
@@ -41,49 +36,59 @@ Treat ChatGPT as the controller and Forge as its repository execution layer. Cha
 - 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.
 
+## Architecture Completeness & Drift Control
+
+- Prompt instructions improve reasoning attention but are advisory. High-risk correctness is enforced by Context Closure, Engineering Design receipts, Plan/Work authority, scoped authorization/resource fences, verification evidence, and implementation review.
+- Before high/critical-risk, architecture-changing, persistence, authorization, concurrency, external-effect, migration, release, or shared-contract mutation, explicitly close the cross-cutting design areas: semantic identity/scope, authority/single writer, authorization/trust, resource fencing, lifecycle/retention/GC, persistence/schema/integrity/backup/restore, idempotency/replay/outcome-unknown reconciliation, evidence/audit/redaction, recovery/failure domain, deployment topology, capacity/backpressure/fairness, time, performance, security/privacy, portability, release/rollback, and migration retirement.
+- A successor Plan must reconcile every unresolved predecessor obligation as `KEEP`, `CHANGE`, `DEFER`, or `DROP`. `CHANGE`/`DEFER`/`DROP` require Controller rationale; `KEEP`/`CHANGE` must point to the successor location carrying the obligation. Silent scope or acceptance loss blocks approval.
+- Every persistent writer must name semantic owner/scope, single-writer rule, schema/version policy, mutation authority, terminal condition, retention/GC, recovery behavior, and sensitive-data policy. Directory placement is not ownership proof.
+- Implementation review must compare the exact candidate against the same accepted product/design/Plan obligations. Passing tests cannot legalize architecture drift, and architecture prose cannot legalize failing behavior.
+- Prefer enforcing invariants in typed contracts/domain APIs/AST or focused semantic tests. Regex/source-string fences are temporary migration assertions with explicit removal triggers.
+
+## Kernel V2 Development Discipline
+
+- Treat Kernel V2 as a domain/authority migration, not an issue-by-issue patch campaign. Before adding state, lifecycle logic, provider routing, compatibility code, or a new process, identify the single owning module and remove or retire competing owners.
+- Prefer a modular monolith with explicit ports/adapters. Kernel/domain packages define semantics and ports; protocol packages define neutral contracts; adapters depend inward on those contracts; apps/composition roots wire implementations. Kernel and plugin-runtime packages must not depend on concrete adapters, MCP transport, CLI/UI implementations, or provider identities.
+- Every domain has one public API and one mutable authority for each durable fact. Cross-module callers consume the public API/port instead of sibling internals. Duplicate enums, shadow state machines, mirrored persistence, and second lifecycle owners are architecture defects to merge or delete, not compatibility conveniences.
+- During migration, legacy `src/cli` / `src/runtime` owners may survive only as bounded compatibility facades around the new owner. A compatibility shim must have a named replacement owner, a bounded consumer set, and an objective removal condition; new production consumers are forbidden. Compatibility is migration debt, not a permanent architecture layer.
+- Do not use fallback-first, workaround-first, extra-daemon, duplicate-authority, or silent-degradation patches to make a failing path appear healthy. Repair the violated invariant or missing general capability. Fail-closed behavior remains appropriate only at genuine safety, authorization, ambiguous-mutation, or unsupported-contract boundaries; it is not a substitute for completing the architecture.
+- Architecture enforcement preference is: TypeScript/compiler contracts -> package/public-API boundaries -> AST/import/dependency-graph rules -> focused semantic contract tests -> temporary migration assertions. Raw source-string/regex checks and source-line-count limits are not long-term architecture authorities when the invariant can be expressed structurally.
+- Any temporary architecture assertion must explain the debt it fences and its removal trigger. Debt ledgers must only shrink: when the legacy edge/shim disappears, delete the assertion/allowlist entry in the same slice instead of preserving historical baggage.
+- Work in coherent batches: batch factual reads -> centralized analysis -> one coherent implementation/patch -> batch architectural review -> focused validation. Avoid repetitive micro-checks after each file. Run broader multi-review and whole-candidate validation at Kernel V2 milestone/candidate boundaries before any runtime baseline activation.
+- 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.
+
 ## Operating Rules
 
-- Default to end-to-end execution and minimize avoidable human intervention. Continue through reversible, policy-allowed setup, implementation, verification, cleanup, and delivery steps without asking the user to babysit the workflow; stop only at a genuinely user-only identity, legal/contract, financial authorization, strong-confirmation, or irreversible decision boundary.
-- For authenticated browser work, preserve the user's existing browser identity: reuse the already-running signed-in Google Chrome via attach-preferred, native-auto, Chrome-only, fail-closed routing. Preserve its cookies, tokens, sessions, and settings; never silently launch or switch to a managed, isolated, Vivaldi, or otherwise unauthenticated browser/profile. Managed or isolated browser modes require an explicit task/action request. If the user Chrome cannot be attached safely, fail closed and surface the concrete blocker instead of creating a replacement login state.
-- After a managed repository change is verified and committed/merged, push the delivered target branch to its configured remote promptly. Do not leave a successfully delivered commit only on local refs unless the user explicitly requested local-only delivery or the push is blocked by safety, permissions, authentication, or branch policy; surface the exact blocker when a push cannot complete.
-- Treat the Google Cloud `forge-cloud` VM experiment as retired infrastructure. Do not restart or reuse that VM for Forge Cloud. Any future remote Forge maintainer must use a separately evaluated host/transport and must demonstrate better latency and reliability than the local Forge path before adoption.
-- Sync `tasks/` whenever substantive repo changes are made.
-- Use `tasks/notes/<plan-stem>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; `<plan-stem>` is the active plan filename without `plan-` and `.md` (for example `20260531-0045-governance-workflow`). Do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
-- Treat hook execution as central-first: trusted repos run `~/.forge/hooks/` (bash shim) or the packaged CLI copy; this self-host repo pins `"hook_source": "repo"` in `.ai/harness/policy.json` so `.ai/hooks/` stays the live development runtime, with `assets/hooks/` as the product source mirrored on install. User-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapters.
-- Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todos.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
-- Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are compatibility inputs only.
-- Keep architecture drift handling split: `architecture-queue.sh` writes architecture requests/events, `workstream-sync.sh` maintains durable capability workstreams, and `context-contract-sync.sh` only updates controlled local `CLAUDE.md`/`AGENTS.md` architecture blocks.
-- Keep `assets/workflow-contract.v1.json` and `.ai/harness/workflow-contract.json` in sync.
-- Keep `CLAUDE.md` and `AGENTS.md` short; put detailed guidance in `docs/reference-configs/`.
-- Treat Codex auto-compact as a fallback only; use `.ai/harness/session/continuation.md` and `.ai/harness/session/resume.md` for long-task rollover.
-- Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `docs/researches/`.
-- Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
-- Treat `_ops/` as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
-- Treat contract-level task execution as worktree-first when policy requires isolation: `scripts/plan-to-todo.sh --plan <approved-plan>` may start `scripts/contract-worktree.sh start --plan <approved-plan>`; finish through Forge `/review`, focused checks, and `scripts/contract-worktree.sh finish`.
-- Forge task directives are the stable user-facing routing surface: `/direct`, `/plan`, `/debug`, `/review`, `/release`, and `/scale`. Do not require users or automation to remember third-party skill commands.
-- After Forge `/plan`, Codex Plan mode, or an optional external planning skill produces a decision-complete plan, capture it with `scripts/capture-plan.sh --slug <slug> --title <title>` so `plans/` becomes the file-backed source of truth; if implementation is already approved, capture with `--status Approved --execute` or run `scripts/plan-to-todo.sh --plan <active-plan>`.
-- If current repo state conflicts with the task, isolate the work, finish there, run Forge `/review`-style validation plus focused checks, then merge back without absorbing unrelated dirty changes.
-- Waza, gstack, Mermaid, gbrain, and cross-review skills are optional host enhancements. Use them only when already installed or explicitly requested; their absence must never block Forge planning, debugging, review, or execution.
-- Register valuable repo-authored docs in `.ai/harness/brain-manifest.json` with `sync.direction=repo-to-brain`; `scripts/sync-brain-docs.sh` and the PostEdit hook mirror only those explicit entries into the default brain vault.
-- Use `docs/reference-configs/external-tooling.md` and `bash scripts/check-agent-tooling.sh --host both --check-updates` for optional host-tool diagnostics. Forge structural retrieval uses its bundled CodeGraph read backend; a global CodeGraph CLI/MCP is an optional developer integration, not Runtime readiness.
-- When changing `scripts/migrate-project-template.sh` or `scripts/lib/project-init-lib.sh`, verify self-migration of this repo still works.
-- Treat repo-local `.claude/settings.json` and `.codex/hooks.json` hook adapters as retired legacy config; migration may back them up locally, but they are not product deliverables.
+- 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.
+- 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.
+- 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.
+- `deploy/` is trackable deployment/runbook/submission/config-example source. Secrets, real environment state, provider state, logs, caches, and credentials stay outside Git.
+- `/direct`, `/plan`, `/debug`, `/review`, `/release`, and `/scale` are user-facing routing concepts; correctness must not depend on optional Waza/gstack/gbrain/peer-review skills.
+- When a concrete incident reveals a general gap, strengthen the existing general capability/authority rather than adding another helper, daemon, fallback, or state machine.
 
 ## 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:
+
 ```bash
-bun run check:task
-bash scripts/check-deploy-sql-order.sh
-bash scripts/check-architecture-sync.sh
-bash scripts/check-task-sync.sh
-bash scripts/check-task-workflow.sh --strict
-bun scripts/inspect-project-state.ts --repo . --format text
-bash scripts/migrate-project-template.sh --repo . --dry-run
+bun run check:type
+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 test` is the affected gate. `bun run check:main` reuses the focused
-task receipt and never expands to the full suite. Full testing is manual and
-explicit through `bun run test:full`; it is not a task, CI, or release gate.
+`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.
 
 <!-- BEGIN ARCHITECTURE CONTRACT -->
 ## Architecture Contract
@@ -109,14 +114,5 @@ explicit through `bun run test:full`; it is not a task, CI, or release gate.
 - Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
 - Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
-
-## Active Workstreams
-
-- (none yet)
-
-## Current Session Projection
-
-- Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
-- `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.
-- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+- Runtime progress authority: Forge Controller Home Requirement/Plan/Work/Evidence; this repository block contains authored architecture context only.
 <!-- END ARCHITECTURE CONTRACT -->

package/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable public Forge changes are recorded here. Release entries are tied to
 
 ## Unreleased
 
+## 1.8.0 - 2026-09-13
+
+### Controller and workflow authority
+
+- Converge Forge V2 onto explicit Failure, Tool Contract ABI, Work lifecycle, and ControllerRound authorities while keeping semantic acceptance with the external GPT controller.
+- Keep the default MCP contract at a stable 19-tool surface and preserve that schema across normal access-mode changes.
+- Advance eligible Controller rounds through explicit `continue_immediately` disposition, release, and successor dispatch without requiring a user `继续`, while preserving same-principal authority across Runtime or transport rotation.
+- Make Work delivery, review transfer, terminal cleanup, and stale-generation fencing atomic enough to avoid duplicate ownership, duplicate handoff, or newer-epoch cleanup.
+
+### Runtime and recovery
+
+- Strengthen immutable whole-release Runtime activation, rollback, readiness, and standalone Recovery identity checks so installed Runtime/Recovery evidence stays bound to one release artifact.
+- Repair Recovery MCP verification to carry the negotiated MCP session through initialization and SSE responses, and close the exact session after verification.
+- Reconcile external-controller launcher exit and terminal-cleanup paths so an already-claimed Work does not remain stranded after provider or launcher termination.
+
+### Context, execution, and performance
+
+- Reduce synchronous MCP diagnostic and control-plane hot-path overhead, reuse negotiated provider channels, and prefilter active Work candidates before heavier lifecycle reads.
+- Tighten Context Plane and Handoff boundaries so bounded evidence remains revision-identified without creating a second semantic or lifecycle authority.
+- Preserve Ephemeral/Lightweight execution for ordinary local work while reserving durable state for real continuity, release, scheduling, recovery, and external effects.
+
+### Release certification
+
+- Freeze cross-version evaluator, corpus, environment, and v1.7.2 baseline authority before V2 observation; fail closed on missing accounting metrics instead of inventing passes.
+- Add exact package, Runtime, Recovery, stable-MCP, portability, lifecycle, and automatic-progression evidence to the release path. The formal v1.7.2 comparison introduced no measured correctness failure or timeout, while incomplete execution-quality metrics remain explicitly inconclusive rather than being presented as superiority evidence.
+
+## 1.7.2 - 2026-08-30
+
+### Runtime lifecycle reliability
+
+- Restart an already-active Linux/systemd Runtime after immutable package activation so the running process cannot remain fenced behind a newer release-authority revision.
+- Avoid duplicate systemd process-group shutdown signals from the package launcher, allowing controlled Runtime restarts to terminate cleanly.
+
+### Work and Controller authority
+
+- Promote effect Work to repository-change authority before governed source mutation and add narrowly fenced reconciliation for already-delivered historical effect Work.
+- Preserve authenticated explicit Controller session capability across MCP transport rotation while keeping same-principal conversations isolated.
+- Make the Windows worker-stderr path assertion platform-correct without changing production path behavior.
+
 ## 1.7.1 - 2026-08-30
 
 ### Runtime and lifecycle stabilization

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Forge AGENTS.md
 
-This repository self-hosts the Forge contract. Retired project-skill and project-initializer staging paths are not supported or cleaned up by current tooling. Claude and Codex should follow the same repo-local workflow surface.
+This repository self-hosts the Forge contract. Retired project-skill and project-initializer staging paths are not supported or cleaned up by current tooling. Claude and Codex should follow the same Controller-first authority model; mutable workflow state is Controller-owned, not a repo-local file protocol.
 
 ## Forge execution runtime
 
@@ -12,28 +12,23 @@ 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.
-## Canonical Workflow Files
-
-- `tasks/current.md` for the tracked current-status snapshot derived from workflow artifacts
-- `tasks/todos.md` for deferred medium/long-term goals, not active execution checklists
-- `plans/prds/` for upper-layer PRDs; `plans/sprints/` for ordered sprint backlogs operated through `scripts/sprint-backlog.sh` (installed implementations live under `.ai/harness/scripts/`; task contracts stay the execution slices)
-- `.ai/context/capabilities.json` for the capability registry and longest-prefix context boundaries
-- `tasks/workstreams/` for capability long-running workstreams that project durable progress into local contracts
-- `tasks/lessons.md` for correction-derived rules
-- `docs/researches/` for deep repo knowledge
-- `tasks/notes/` for task-local implementation decisions, deviations, tradeoffs, and open questions
-- `plans/` for timestamped plans, with `plans/archive/` for history
-- `.ai/harness/workflow-contract.json` for the installed workflow contract manifest
-- `.ai/harness/policy.json` for the machine-readable workflow contract
-- `.ai/context/context-map.json` for progressive context loading
-- `docs/architecture/index.md` for umbrella architecture status, drift requests, snapshots, and diagram links
-- `docs/reference-configs/agentic-development-flow.md` for Forge task routing and optional host-skill enhancements
+## 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.
+- Mutable Requirement/Plan/Work/ControllerRound, Process/Job, Schedule, lease/resource, authorization, verification, Plugin config, session/binding, evidence and recovery state belongs in Controller Home.
+- Repository-authored durable surfaces include source/tests, `docs/spec.md`, `docs/researches/`, `tasks/todos.md`, `tasks/lessons.md`, architecture docs, and intentional human-authored project plans/config.
+- `tasks/current.md`, `tasks/contracts/`, `tasks/reviews/`, `tasks/notes/`, `tasks/workstreams/`, `.ai/harness/**`, repo-local Plugin mutable config, and repo-local cache/session state are legacy migration inputs, not current machine authority and must not be recreated by new producers.
+- Git history is the repository source-history archive. Runtime history/receipts use Controller Home retention policy rather than repository archive directories.
+- `.ai/context/capabilities.json` may remain declarative capability/context metadata while it is still part of the source contract; it must not point at retired runtime workstream directories.
+- `docs/architecture/CURRENT.md` is maintained architecture authority; executable code and persisted schemas remain authoritative implementation evidence.
+- Host/global prompt files explain working behavior but do not authorize mutation, own lifecycle, or declare completion.
 
 ## Runtime Architecture Guardrails
 
 - Treat Forge as one local MCP application, one active Runtime, one deployable release, and one in-process lifecycle owner. Gateway, MCP transport, Controller, and Scheduler may be modules; they are not independently deployable generations by default.
 - Bounded restart downtime is acceptable. Prefer `stop -> switch complete release -> start -> verify -> full rollback`; do not add ingress, blue/green slots, adoption, or mixed generations without an explicit product requirement.
 - Do not respond to an incident by adding a second status authority, daemon, proxy, KeepAlive wrapper, watchdog, recovery owner, or fallback path; extend the canonical Runtime or standalone Recovery owner instead. First identify the violated invariant and remove, merge, or correct the existing cause.
+- When a concrete scenario exposes a missing capability, strengthen an existing general capability and reuse its authority/lifecycle first. Add a specialized plugin, module, script, or helper only when an independent authority, security, protocol, persistence, or lifecycle boundary is proven; incident-specific helpers are temporary debt otherwise.
 - 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.
@@ -41,49 +36,43 @@ Treat ChatGPT as the controller and Forge as its repository execution layer. Cha
 - 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.
 
+## Architecture Completeness & Drift Control
+
+- Prompt instructions improve reasoning attention but are advisory. High-risk correctness is enforced by Context Closure, Engineering Design receipts, Plan/Work authority, scoped authorization/resource fences, verification evidence, and implementation review.
+- Before high/critical-risk, architecture-changing, persistence, authorization, concurrency, external-effect, migration, release, or shared-contract mutation, explicitly close the cross-cutting design areas: semantic identity/scope, authority/single writer, authorization/trust, resource fencing, lifecycle/retention/GC, persistence/schema/integrity/backup/restore, idempotency/replay/outcome-unknown reconciliation, evidence/audit/redaction, recovery/failure domain, deployment topology, capacity/backpressure/fairness, time, performance, security/privacy, portability, release/rollback, and migration retirement.
+- A successor Plan must reconcile every unresolved predecessor obligation as `KEEP`, `CHANGE`, `DEFER`, or `DROP`. `CHANGE`/`DEFER`/`DROP` require Controller rationale; `KEEP`/`CHANGE` must point to the successor location carrying the obligation. Silent scope or acceptance loss blocks approval.
+- Every persistent writer must name semantic owner/scope, single-writer rule, schema/version policy, mutation authority, terminal condition, retention/GC, recovery behavior, and sensitive-data policy. Directory placement is not ownership proof.
+- Implementation review must compare the exact candidate against the same accepted product/design/Plan obligations. Passing tests cannot legalize architecture drift, and architecture prose cannot legalize failing behavior.
+- Prefer enforcing invariants in typed contracts/domain APIs/AST or focused semantic tests. Regex/source-string fences are temporary migration assertions with explicit removal triggers.
+
 ## Operating Rules
 
-- Default to end-to-end execution and minimize avoidable human intervention. Continue through reversible, policy-allowed setup, implementation, verification, cleanup, and delivery steps without asking the user to babysit the workflow; stop only at a genuinely user-only identity, legal/contract, financial authorization, strong-confirmation, or irreversible decision boundary.
-- For authenticated browser work, preserve the user's existing browser identity: reuse the already-running signed-in Google Chrome via attach-preferred, native-auto, Chrome-only, fail-closed routing. Preserve its cookies, tokens, sessions, and settings; never silently launch or switch to a managed, isolated, Vivaldi, or otherwise unauthenticated browser/profile. Managed or isolated browser modes require an explicit task/action request. If the user Chrome cannot be attached safely, fail closed and surface the concrete blocker instead of creating a replacement login state.
-- After a managed repository change is verified and committed/merged, push the delivered target branch to its configured remote promptly. Do not leave a successfully delivered commit only on local refs unless the user explicitly requested local-only delivery or the push is blocked by safety, permissions, authentication, or branch policy; surface the exact blocker when a push cannot complete.
-- Treat the Google Cloud `forge-cloud` VM experiment as retired infrastructure. Do not restart or reuse that VM for Forge Cloud. Any future remote Forge maintainer must use a separately evaluated host/transport and must demonstrate better latency and reliability than the local Forge path before adoption.
-- Sync `tasks/` whenever substantive repo changes are made.
-- Use `tasks/notes/<plan-stem>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; `<plan-stem>` is the active plan filename without `plan-` and `.md` (for example `20260531-0045-governance-workflow`). Do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
-- Treat hook execution as central-first: trusted repos run `~/.forge/hooks/` (bash shim) or the packaged CLI copy; this self-host repo pins `"hook_source": "repo"` in `.ai/harness/policy.json` so `.ai/hooks/` stays the live development runtime, with `assets/hooks/` as the product source mirrored on install. User-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapters.
-- Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todos.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
-- Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are compatibility inputs only.
-- Keep architecture drift handling split: `architecture-queue.sh` writes architecture requests/events, `workstream-sync.sh` maintains durable capability workstreams, and `context-contract-sync.sh` only updates controlled local `CLAUDE.md`/`AGENTS.md` architecture blocks.
-- Keep `assets/workflow-contract.v1.json` and `.ai/harness/workflow-contract.json` in sync.
-- Keep `CLAUDE.md` and `AGENTS.md` short; put detailed guidance in `docs/reference-configs/`.
-- Treat Codex auto-compact as a fallback only; use `.ai/harness/session/continuation.md` and `.ai/harness/session/resume.md` for long-task rollover.
-- Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `docs/researches/`.
-- Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
-- Treat `_ops/` as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
-- Treat contract-level task execution as worktree-first when policy requires isolation: `scripts/plan-to-todo.sh --plan <approved-plan>` may start `scripts/contract-worktree.sh start --plan <approved-plan>`; finish through Forge `/review`, focused checks, and `scripts/contract-worktree.sh finish`.
-- Forge task directives are the stable user-facing routing surface: `/direct`, `/plan`, `/debug`, `/review`, `/release`, and `/scale`. Do not require users or automation to remember third-party skill commands.
-- After Forge `/plan`, Codex Plan mode, or an optional external planning skill produces a decision-complete plan, capture it with `scripts/capture-plan.sh --slug <slug> --title <title>` so `plans/` becomes the file-backed source of truth; if implementation is already approved, capture with `--status Approved --execute` or run `scripts/plan-to-todo.sh --plan <active-plan>`.
-- If current repo state conflicts with the task, isolate the work, finish there, run Forge `/review`-style validation plus focused checks, then merge back without absorbing unrelated dirty changes.
-- Waza, gstack, Mermaid, gbrain, and cross-review skills are optional host enhancements. Use them only when already installed or explicitly requested; their absence must never block Forge planning, debugging, review, or execution.
-- Register valuable repo-authored docs in `.ai/harness/brain-manifest.json` with `sync.direction=repo-to-brain`; `scripts/sync-brain-docs.sh` and the PostEdit hook mirror only those explicit entries into the default brain vault.
-- Use `docs/reference-configs/external-tooling.md` and `bash scripts/check-agent-tooling.sh --host both --check-updates` for optional host-tool diagnostics. Forge structural retrieval uses its bundled CodeGraph read backend; a global CodeGraph CLI/MCP is an optional developer integration, not Runtime readiness.
-- When changing `scripts/migrate-project-template.sh` or `scripts/lib/project-init-lib.sh`, verify self-migration of this repo still works.
-- Treat repo-local `.claude/settings.json` and `.codex/hooks.json` hook adapters as retired legacy config; migration may back them up locally, but they are not product deliverables.
+- 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.
+- 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.
+- 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.
+- `deploy/` is trackable deployment/runbook/submission/config-example source. Secrets, real environment state, provider state, logs, caches, and credentials stay outside Git.
+- `/direct`, `/plan`, `/debug`, `/review`, `/release`, and `/scale` are user-facing routing concepts; correctness must not depend on optional Waza/gstack/gbrain/peer-review skills.
+- When a concrete incident reveals a general gap, strengthen the existing general capability/authority rather than adding another helper, daemon, fallback, or state machine.
 
 ## 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:
+
 ```bash
-bun run check:task
-bash scripts/check-deploy-sql-order.sh
-bash scripts/check-architecture-sync.sh
-bash scripts/check-task-sync.sh
-bash scripts/check-task-workflow.sh --strict
-bun scripts/inspect-project-state.ts --repo . --format text
-bash scripts/migrate-project-template.sh --repo . --dry-run
+bun run check:type
+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 test` is the affected gate. `bun run check:main` reuses the focused
-task receipt and never expands to the full suite. Full testing is manual and
-explicit through `bun run test:full`; it is not a task, CI, or release gate.
+`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.
 
 <!-- BEGIN ARCHITECTURE CONTRACT -->
 ## Architecture Contract
@@ -109,14 +98,5 @@ explicit through `bun run test:full`; it is not a task, CI, or release gate.
 - Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
 - Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
-
-## Active Workstreams
-
-- (none yet)
-
-## Current Session Projection
-
-- Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
-- `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.
-- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+- Runtime progress authority: Forge Controller Home Requirement/Plan/Work/Evidence; this repository block contains authored architecture context only.
 <!-- END ARCHITECTURE CONTRACT -->

package/README.md

@@ -52,7 +52,7 @@ 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. The public provider catalog currently includes **Forge Desktop Operator**, **Forge Design**, and **Personal Knowledge Assistant**; install with `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>`. See [Features](docs/operations/features.md) and [Plugin Management](docs/forge-plugin-management.md).
 
 ## Controlled by design
 
@@ -105,7 +105,7 @@ 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 等类型化能力；公开 Provider 目录还有 **Forge Desktop Operator / Forge Design / Personal Knowledge Assistant**。详见[功能清单](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>` 管理。详见[功能清单](docs/operations/features.zh-CN.md)与[插件管理](docs/forge-plugin-management.md)。
 
 安全上，普通本地修改、远程影响、破坏性操作、密钥和工作区外访问是不同边界；Full Access 不会取消高风险确认。详见[安全说明](SECURITY.md)和[安全模型](docs/wiki/Security-Model.md)。
 

package/SKILL.md

@@ -424,5 +424,4 @@ bun scripts/migrate-workflow-docs.ts --repo . --dry-run
 
 - Keep this file short; detailed policy belongs in `docs/reference-configs/`
 - Keep stack-specific detail in assets and references, not in this skill body
-- If the router changes, update `evals/evals.json`
 - If the contract changes, update templates, migration, checks, and tests together

package/THIRD_PARTY_NOTICES.md

@@ -1,12 +1,15 @@
 # Third-party notices
 
-This inventory covers the direct runtime and development dependencies declared by `@moretea-labs/forge@1.7.1`.
+This inventory covers the direct runtime and development dependencies declared by `@moretea-labs/forge@1.8.0`.
 
 License values come from `package-lock.json` where available. For lock entries without a license field, the declared license was verified from package metadata during release preparation. This file is informational and does not replace the license text distributed by each dependency.
 
 | Package | Version | Role | Declared license | Source |
 | --- | --- | --- | --- | --- |
-| `@modelcontextprotocol/sdk` | `1.29.0` | runtime | `MIT` | package-lock.json |
+| `@modelcontextprotocol/client` | `2.0.0` | runtime | `MIT` | package-lock.json |
+| `@modelcontextprotocol/node` | `2.0.0` | runtime | `MIT` | package-lock.json |
+| `@modelcontextprotocol/server` | `2.0.0` | runtime | `MIT` | package-lock.json |
+| `@modelcontextprotocol/server-legacy` | `2.0.0` | runtime | `MIT` | package-lock.json |
 | `commander` | `14.0.3` | runtime | `MIT` | package metadata |
 | `express` | `5.2.1` | runtime | `MIT` | package metadata |
 | `playwright` | `1.61.1` | runtime | `Apache-2.0` | package metadata |

package/adapters/browser/index.ts

@@ -0,0 +1,2 @@
+// Browser provider adapters no longer own durable interaction identity.
+export {};

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

@@ -0,0 +1,71 @@
+import {
+  chatgptProviderError,
+  classifyChatgptProviderFailure,
+  type ChatgptProviderDeliveryHost,
+} from './provider-delivery';
+
+export interface ChatgptBrowserNavigationResult {
+  submissionTargetUrl: string;
+  recoveredFromStaleBinding: boolean;
+  browserSessionId: string;
+}
+
+export interface ChatgptBrowserDeliveryOperations {
+  ensureBrowser(controllerHome: string, workId: string): Promise<void>;
+  navigate(controllerHome: string, workId: string, browserSessionId: string, targetUrl: string, timeoutMs?: number): Promise<ChatgptBrowserNavigationResult>;
+  ensureExecutionPreference(controllerHome: string, workId: string, browserSessionId: string, model: string, reasoning: 'medium' | 'high' | 'xhigh', timeoutMs?: number): Promise<boolean>;
+  submitPrompt(controllerHome: string, workId: string, browserSessionId: string, prompt: string, targetUrl: string, timeoutMs?: number): Promise<string>;
+}
+
+/** Native Browser delivery host. It owns session acquisition/navigation and prompt dispatch confirmation. */
+export function createChatgptBrowserDeliveryHost(operations: ChatgptBrowserDeliveryOperations): ChatgptProviderDeliveryHost {
+  return {
+    async dispatch(input) {
+      let effectiveBrowserSessionId = input.browserSessionId;
+      try {
+        await operations.ensureBrowser(input.controllerHome, input.workId);
+        const navigation = await operations.navigate(
+          input.controllerHome,
+          input.workId,
+          effectiveBrowserSessionId,
+          input.targetUrl,
+          input.timeoutMs,
+        );
+        effectiveBrowserSessionId = navigation.browserSessionId;
+        const executionPreferenceVerified = await operations.ensureExecutionPreference(
+          input.controllerHome,
+          input.workId,
+          effectiveBrowserSessionId,
+          input.model,
+          input.reasoning,
+          input.timeoutMs,
+        );
+        const observedUrl = await operations.submitPrompt(
+          input.controllerHome,
+          input.workId,
+          effectiveBrowserSessionId,
+          input.prompt,
+          navigation.submissionTargetUrl,
+          input.timeoutMs,
+        );
+        return {
+          status: 'dispatch_confirmed',
+          provider: 'controller-browser',
+          browserSessionId: effectiveBrowserSessionId,
+          conversationUrl: observedUrl,
+          executionPreferenceVerified,
+        };
+      } catch (error) {
+        const providerError = chatgptProviderError(error, 'CHATGPT_CONTROLLER_BROWSER_FAILED');
+        return {
+          status: classifyChatgptProviderFailure(providerError.code, providerError.message),
+          provider: 'controller-browser',
+          browserSessionId: effectiveBrowserSessionId,
+          conversationUrl: providerError.conversationUrl ?? input.targetUrl,
+          executionPreferenceVerified: false,
+          error: providerError,
+        };
+      }
+    },
+  };
+}