@moretea-labs/forge 1.7.2 → 1.8.1

package/AGENTS.md

@@ -1,89 +1,157 @@
 # 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
 
 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.
 
+- 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.
-## 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
+
+### 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.
+- Do not integrate another Work/branch into a receiving checkout while that receiving Work still has uncommitted source changes. First converge the receiving Work's own changes into a coherent semantic commit so the integration boundary has explicit Git provenance; then merge/rebase/cherry-pick the other committed result as the model judges appropriate.
+- Do not auto-stash, auto-reset, auto-clean, or silently discard dirty changes to make integration possible. The current Work owns the decision to keep editing, commit, or deliberately discard its own changes.
+- 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.
+- 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.
+- 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.
 
+## 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.
+
+### 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 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 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.
+- 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 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: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` 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.
+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
@@ -109,14 +177,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,46 @@ All notable public Forge changes are recorded here. Release entries are tied to
 
 ## Unreleased
 
+## 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
+
+- 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

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,38 @@ 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
+### 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.
+- 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 +51,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 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.
+- 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.
+- `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 +113,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/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.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