@moretea-labs/forge 1.7.2 → 1.8.0

package/docs/architecture/decisions/20260907-assistant-learning-loop.md

@@ -0,0 +1,35 @@
+# Assistant learning loop
+
+Status: Accepted implementation decision; live promotion certification remains required after focused implementation validation.
+
+Implementation note: Xiaohongshu platform-specific publishing choreography is migrated into versioned Workflow assets; Core retains only generic Workflow execution, reconciliation, evidence, and learning authorities; this decision document is not an operational state store.
+
+Forge self-defect observed during this delivery: an accidentally isolated Work was terminalized before its active controller lease was released, so cleanup was blocked until a separate controller_release; a subsequent maintenance diagnosis also reported accumulated terminal edit-session/temp ownership records. Treat this as one lifecycle-cleanup root-cause family rather than adding per-call workarounds. Maintenance diagnosis for this state took 25-35 seconds despite no source investigation, so cleanup ownership cardinality is also a performance concern. Track under the existing lifecycle-cleanup/maintenance root-cause issue if present; otherwise create one before this delivery closes. Do not create a duplicate authority for the same defect family.
+
+The accepted user outcome is two consecutive, evidence-linked assistant rounds for one explicitly bound project/account. The first-party Xiaohongshu workflow is the concrete certification case for this implementation; production execution must enter through rh_work rather than direct platform choreography, with Workflow Runtime as the sole external-effect owner and canonical receipt producer. Operational priors remain mechanical only. Controller reasoning produces observations, hypotheses and lessons; no autonomous compiler, scheduler, authorization owner or database is introduced.
+
+## Ownership and persistence
+
+Kernel Memory owns the experience contract and application service. Its Controller Home adapter is the sole writer of `assistant_experience` records, scoped by portable project identity, with version 1 payloads, transactional revision CAS and bounded provenance. The active Controller claim authorizes writes; source Work/round and retained evidence must match the requested lineage. Observations default to 30 days and hypotheses to 90 days. Lessons require expiry or explicit durable applicability rationale. Supersession and retraction are terminal for recall; audit history remains in the existing SQLite audit authority. Central maintenance invokes bounded retirement after expiry/retraction grace. No chat-history reconstruction is allowed.
+
+Outcome observations are typed evidence linked to an existing Work and retained receipt, not a campaign lifecycle. Missing metrics are explicit null values with reasons; cumulative snapshots are never summed automatically. Source removal invalidates dependent recall. Payloads are metadata-only and exclude credentials, cookies, binaries and raw logs. Schema rollback is whole Runtime plus its paired Controller Home backup.
+
+## Context and trust
+
+Project contracts register exact knowledge sources. Repository mirrors remain projections of their repository originals; independent Brain documents retain their own authority. Context reads only registered sources within explicit roots, with realpath containment, bounded bytes/time/candidate counts, content digests and visible gaps. Chinese lexical retrieval is supported. Retrieved text and experience are advisory data, never instructions granting authority or weakening current task constraints. No persistent search index is required in v1.
+
+Provider-neutral round preparation composes bounded context; host adapters only render it. Current Work and project identity must be revalidated after claim. Knowledge failure cannot silently permit a publish that needs missing product constraints. Account/channel applicability is exact; omission never widens access to account-specific experience.
+
+## Workflow and recovery
+
+Preserve Workflow migration B/C/D/E obligations. The interpreter remains subordinate to Work, Process, provider effects and existing resource fencing. Outputs referenced by later steps must be retained with checkpoint identity. An effect dispatched before checkpoint failure is reconciled through the existing receipt authority before replay. Assets pin version/digest and inputs; changing them cannot reuse a run. Site choreography stays versioned asset data.
+
+## Concurrency, time and capacity
+
+All experience mutations run in one SQLite transaction with expected revisions and bounded rows per project. Explicit timestamps drive expiry and tests; invalid/future observations fail validation. Reads filter scope before ranking and share existing Context item/byte/token ceilings. Read failures are visible gaps. Central lifecycle maintenance owns physical cleanup; retrieval does not become another persistent writer. No new process, cross-node replication or provider identity is introduced.
+
+## Delivery and retirement
+
+Execution-quality observations reuse ControllerRound semantic fingerprints and exact check evidence. They are bounded advisory signals, not a `normal/degraded` persistent state or a second Supervisor. Legitimate wait/investigation is not failure; same-source pass/fail indicates possible flakiness, not proven code regression. Controller diagnosis and accepted design return-to-design gates retain semantic authority. Cross-task strategy A/B remains the existing benchmark's responsibility; differing task difficulty cannot establish policy superiority.
+
+Keep existing operational-memory semantics and Workflow acceptance obligations. Replace modern Brain promotion's deleted-file inference with terminal Work evidence; retain old Git import only behind an explicit legacy flag until consumers migrate. No partial Runtime activation is part of this change. Focused fault tests and whole-candidate gates precede delivery; actual two-round publication and metrics evidence precede the claim that live assistant capability is complete.

package/docs/architecture/decisions/20260907-controller-round-transition-policy.md

@@ -0,0 +1,296 @@
+# ControllerRound uses one provider-neutral transition policy
+
+Status: Accepted design contract for PLAN-forge-v2-assistant-loop-execution-degradation-20260907-r3.
+
+## Decision
+
+Every durable ControllerRound lifecycle mutation MUST pass through one provider-neutral Kernel transition policy. Scheduler, Launcher, MCP compatibility, ChatGPT/Browser adapters, recovery jobs, Runtime bootstrap/restart code and provider hosts may only:
+
+1. observe durable state,
+2. submit a typed lifecycle event plus bounded fenced evidence,
+3. perform an external effect explicitly authorized by the returned transition/effect intent, and
+4. persist only the transition decision produced by the canonical policy.
+
+They MUST NOT directly invent status changes, clear blocker strings, reset budgets, rotate round authority, promote dispatch outcome, reopen waits, or create provider-specific recovery exceptions. Provider-specific facts are translated into provider-neutral evidence before reaching the Kernel.
+
+The canonical owner belongs under `packages/kernel/controller/**`. Persistence remains atomic/CAS guarded, but persistence is an executor of the policy decision rather than a second lifecycle authority.
+
+## Why
+
+The existing lifecycle has ten relay statuses and four lifecycle stages, but transition authority is distributed across initial launch, dispatch settlement, claim acknowledgement, stalled recovery, explicit authority recovery, disposition submission, release handling, successor handoff and terminal cleanup. `blocked` additionally carries several unrelated meanings. Local guards are individually sensible but the combined system permits gaps, duplicated recovery rules and route-dependent semantics.
+
+The fix is not another blocked-reason branch. The invariant is one lifecycle decision authority.
+
+## Durable state classes
+
+| Class | Relay status | Meaning | Automatic recovery |
+| --- | --- | --- | --- |
+| Open execution | `dispatching`, `dispatched`, `claimed`, `pending_release` | One semantic round is still mechanically open or closing | Yes, only idempotent recovery of the same semantic round |
+| Semantic pause | `waiting`, `waiting_for_user` | Controller intentionally stopped semantic progression | No stalled-time recovery; requires an explicit legal event |
+| Semantic terminal | `goal_complete`, `handed_off` | This lineage node is semantically closed | Never automatically reopened |
+| Failure/fuse | `failed`, `blocked` | Mechanical failure or an explicit policy fuse | Only according to typed failure class and matching evidence |
+
+`lifecycleStage` remains orthogonal evidence of the semantic boundary:
+
+- `dispatching`
+- `dispatch_confirmed`
+- `controller_claimed`
+- `semantic_round_closed`
+
+A status and lifecycle stage combination not admitted by the transition policy is invalid durable state and must fail closed.
+
+## Canonical event model
+
+External layers submit events, never target statuses. The exact TypeScript names may differ during implementation, but the semantics are frozen here.
+
+| Event | Required evidence | Policy responsibility |
+| --- | --- | --- |
+| `occurrence_requested` | occurrence identity, origin, Work/Requirement state, caller authority | Decide whether this is a legal genuinely new occurrence or an illegal fuse/wait bypass |
+| `provider_dispatch_succeeded` | exact round authority + relay scope + provider dispatch receipt/effect identity | Confirm dispatch, clear only provider-dispatch failure state for this round |
+| `provider_dispatch_failed` | exact round identity + classified failure evidence | Increment provider-failure budget and choose retry/fail/fuse |
+| `provider_dispatch_outcome_unknown` | exact effect identity, no contradictory settlement | Enter outcome-unknown reconciliation state; never blind replay |
+| `provider_effect_reconciled` | exact previously unknown effect identity + confirmed executed/not-executed evidence | Confirm existing dispatch or authorize a new dispatch only when absence is proven |
+| `controller_claim_observed` | active ControllerSession ownership + exact round authority/scope | Move the same round to claimed; never create a new semantic round |
+| `semantic_disposition_submitted` | exact claimed round identity + disposition + required handoff/evidence | Close semantic round and consume semantic budgets exactly once |
+| `controller_release_observed` | exact released controller epoch + already persisted disposition | Mechanically continue post-disposition flow without re-submitting disposition |
+| `successor_bound` | completed predecessor + already-admitted successor lineage | Atomically close predecessor relay and create successor round according to authority rule |
+| `stalled_round_observed` | exact current relay revision, liveness evidence, no active conflicting execution/claim | Recover only an unfinished open mechanical transition; elapsed time is never semantic evidence |
+| `semantic_state_changed` | new mechanical/semantic fingerprint tied to exact relay lineage | May rearm `repeated_state`; cannot clear unrelated fuse classes |
+| `provider_environment_recovered` | exact blocked relay revision + verified provider/runtime capability evidence + failure-class match | May rearm `consecutive_failures` for the same undispatched round without consuming another semantic round |
+| `user_resume_requested` | explicit user authority + exact paused/failure lineage | Resume only states whose policy explicitly permits user resume |
+| `terminal_work_observed` | failed/cancelled Work + no active claim | Retire surviving relay mechanically; never fabricate semantic completion |
+| `authority_recovery_requested` | explicit authorized recovery + no active execution/claim + exact current relay | Rekey capability only where policy permits; never change semantic budgets |
+| `runtime_or_session_evicted` | durable round still current, transport/session gone | Preserve semantic round and authority unless an explicit authority-recovery rule applies |
+
+## Blocked policy is typed, not a free-form string switch
+
+`blockedReason` may remain as a compatibility projection, but policy decisions use a typed blocker class. At minimum:
+
+| Blocker class | Meaning | Legal exit | Budget behavior | Authority behavior |
+| --- | --- | --- | --- | --- |
+| `repeated_state` | semantic continuation repeated without meaningful state progress | `semantic_state_changed` with a changed exact fingerprint | reset repeated-state counter only; round/provider-failure budgets preserved | same semantic-round authority when rearming the same undispatched/claimed lineage |
+| `provider_unavailable` / `consecutive_failures` | provider/runtime path repeatedly failed before successful progression | `provider_environment_recovered` with exact relay and verified environment/provider evidence | provider failure streak may start a new recovery epoch; historical failures remain auditable; round/repeated budgets unchanged | preserve authority for the same undispatched semantic round |
+| `round_budget_exhausted` | hard semantic continuation budget reached | no automatic exit; only explicit higher-level replanning/new authorized occurrence that does not pretend to be the same exhausted round | never reset because time passed or provider recovered | old round authority cannot be reused as a fresh semantic round |
+| `provider_dispatch_outcome_unknown` | provider effect may already have happened | exact `provider_effect_reconciled`; positive evidence confirms existing effect, negative evidence may authorize one new dispatch | no blind retry; no semantic-round budget duplication | preserve same authority/effect identity until reconciled |
+| `provider_user_action_required` | provider needs human/auth action | explicit user/handoff resolution followed by legal resume event | no background retry budget churn | same lineage; new semantic round only if policy says the resolved occurrence is new |
+
+No generic `blocked -> dispatching` transition exists.
+
+For the ChatGPT Controller provider, `provider_environment_recovered` is admitted only through exact ControllerRound authority plus a fresh non-semantic provider probe. The probe must use the same runtime provider selection as ordinary Controller dispatch, must not replay the blocked Work prompt, and must produce a server-authored durable Recovery audit record only after dispatch is confirmed. The audit identity is recovery evidence, not a second lifecycle authority: the Kernel still performs the exact relay-scope/authority/CAS checks and the canonical `provider_environment_recovered` transition. Failed, ambiguous, user-action-required, stale, or mismatched probes cannot rearm the fuse. MCP compatibility may expose this as a bounded repair intent, but it must not duplicate `controller.authority.recover` or invent a provider-specific round state.
+
+## Budget contract
+
+ControllerRound has three independent budget dimensions. No code path may use one to reset another.
+
+### `roundCount`
+
+Counts semantic `continue_immediately` progression rounds, not transport retries, Runtime restarts, claim migration, release recovery, provider recovery, outcome reconciliation or stalled-transition repair. It is consumed exactly once at semantic close/open according to the canonical policy.
+
+### `repeatedStateCount`
+
+Measures semantic continuation without meaningful state fingerprint progress. It resets only when policy observes a changed canonical semantic/mechanical fingerprint. Provider health changes alone do not reset it.
+
+### Provider failure budget
+
+Tracks failed provider dispatch/recovery attempts for the exact provider-neutral dispatch responsibility. A verified environment/provider repair may begin a bounded recovery epoch for the same semantic round, but must not erase historical failure evidence or change `roundCount`/`repeatedStateCount`. The implementation may store a typed recovery epoch or derive it from immutable evidence; either way, `consecutiveFailures = 0` alone is not sufficient evidence of recovery.
+
+Time passage is never a budget reset signal.
+
+## Authority contract
+
+There are distinct authorities and they must not be conflated:
+
+- `authorityId`: opaque per-semantic-round ControllerRound capability.
+- `relayScopeId`: durable semantic lineage scope.
+- `claimGeneration`: ControllerSession ownership epoch.
+- provider effect/dispatch identity: evidence identity for an external effect, never Controller authority.
+- MCP/browser/session ids: transport identities only.
+
+Rules:
+
+1. The same undispatched semantic round keeps `authorityId` through transport loss, Runtime restart, MCP eviction, stalled mechanical recovery and verified provider/environment recovery.
+2. A genuinely new semantic round rotates `authorityId`.
+3. Successor Work handoff creates the successor round under the same relay lineage and rotates to a new round capability.
+4. Claim/session migration changes ControllerSession identity/`claimGeneration`, not semantic round identity.
+5. Explicit authority recovery is a separate fenced capability-rekey operation. It must not silently consume a new round or reset budgets.
+6. Provider, Browser and MCP adapters can never mint lifecycle authority by presenting a transport/session id.
+
+## Fresh occurrence rule
+
+`launcher_start` or a schedule/manual trigger is not automatically proof of a fresh semantic occurrence. The transition policy must classify `occurrence_requested` against the latest lineage.
+
+A new occurrence is legal only when the prior semantic state and trigger contract explicitly allow it, for example a designed future schedule occurrence after a semantic `wait`, or an explicit higher-level user/replan action after a recoverable failure.
+
+A launch request MUST NOT bypass:
+
+- `round_budget_exhausted`,
+- an unresolved `provider_dispatch_outcome_unknown`,
+- `waiting_for_user`,
+- `goal_complete`,
+- `handed_off`, or
+- a `consecutive_failures` fuse that lacks verified provider/environment recovery evidence.
+
+Whether ordinary `waiting` permits a later scheduled occurrence is determined by the Schedule/occurrence contract and an explicit occurrence identity, not merely because `beginInitialControllerRoundDispatch` was called again.
+
+## Legal lifecycle skeleton
+
+The policy must preserve this semantic ordering while allowing idempotent retries of each mechanical edge:
+
+```text
+legal new occurrence
+  -> dispatching
+  -> dispatched          (or blocked/failed/waiting_for_user by typed provider outcome)
+  -> claimed
+  -> semantic disposition
+       continue_immediately -> pending_release -> release -> next dispatching/new authority
+       wait                 -> waiting
+       wait_for_user        -> waiting_for_user
+       goal_complete        -> goal_complete
+
+completed predecessor + admitted successor
+  -> predecessor handed_off + successor dispatching (atomic lineage transition)
+```
+
+Recovery never skips semantic edges. It only completes or replays an idempotent mechanical edge of the same semantic decision.
+
+## Persistence boundary
+
+The transition policy consumes an immutable current snapshot plus one event and returns one of:
+
+- `accept`: exact next relay record and optional external-effect intent,
+- `no_op`: idempotent duplicate with the already-authoritative record,
+- `reject`: stable reason/error code,
+- `needs_evidence`: missing exact evidence required to decide safely.
+
+The store applies accepted decisions under the relay-scope lock / transaction using the expected record revision. External effects occur only where the policy explicitly emits an effect intent. After the effect, the adapter submits its receipt as a new event; it never writes the post-effect relay state directly.
+
+This separates lifecycle decision authority from persistence and provider execution while preserving CAS fencing.
+
+## Crash-window contract
+
+Each window has exactly one legal recovery interpretation.
+
+| Crash window | Durable fact | Recovery rule | Forbidden shortcut |
+| --- | --- | --- | --- |
+| before provider dispatch starts | `dispatching`, no effect receipt | same-round dispatch may be authorized by policy | rotate authority or increment semantic round |
+| after provider may have acted but before receipt persistence | effect outcome uncertain | enter/reconcile exact outcome-unknown identity | blind replay |
+| after dispatch receipt, before relay becomes `dispatched` | durable receipt exists | replay `provider_dispatch_succeeded` idempotently | send provider effect again |
+| after `dispatched`, before Controller claim | dispatch confirmed | claim same round from exact ownership evidence | create fresh occurrence |
+| after claim persistence, before prompt/controller observes response | claimed + live/recoverable ownership | duplicate claim is no-op/migration if fenced | consume another round |
+| after semantic disposition persistence, before controller release | `pending_release`/semantic terminal | retry release/post-disposition mechanics only | resubmit disposition |
+| after controller release, before next round creation | closed disposition + released exact epoch | create/restore exactly one next round according to disposition | repeat prior round close |
+| during predecessor/successor handoff | transaction must contain both lineage writes or neither | retry atomic handoff | independently mutate predecessor and successor |
+| Runtime restart | durable relay survives transport | reconstruct from durable state and same round authority | treat restart as fresh occurrence |
+| MCP/session eviction | transport lost only | reclaim/migrate ControllerSession if fenced; preserve relay identity | use new MCP session as authority |
+
+## Fault-injection matrix frozen for the next Plan step
+
+The implementation step must add focused failures at least at:
+
+1. crash before provider call,
+2. provider call succeeds but receipt write is lost,
+3. receipt exists but `dispatched` transition is lost,
+4. `dispatched` exists but claim response is lost,
+5. claim persists then Runtime/MCP restarts,
+6. disposition persists then release fails,
+7. release persists then next-round creation fails,
+8. successor handoff crashes between predecessor/successor writes,
+9. repeated-state block with unchanged fingerprint,
+10. repeated-state block with changed fingerprint,
+11. provider failures reach fuse,
+12. verified provider/environment recovery for that exact fuse,
+13. stale/mismatched provider recovery evidence,
+14. outcome-unknown positive reconciliation,
+15. outcome-unknown proven-not-executed reconciliation,
+16. hard round-budget exhaustion,
+17. waiting scheduled occurrence with explicit occurrence identity,
+18. waiting_for_user without explicit user/handoff resolution,
+19. goal_complete/handed_off relaunch attempt,
+20. failed/cancelled Work terminal cleanup with and without active claim.
+
+Assertions must cover status, lifecycleStage, `roundCount`, `repeatedStateCount`, provider-failure epoch/history, `authorityId`, `claimGeneration`, provider dispatch/effect receipt identity, duplicate-effect count and durable revision/CAS behavior.
+
+## Real Supervisor acceptance sequence
+
+Production validation uses the existing Supervisor lineage. It may not manufacture a new Work/Requirement/relay to make the test pass.
+
+1. Build and activate one exact candidate Runtime containing the transition policy.
+2. Verify required provider/plugin capability on that installed Runtime before relay mutation.
+3. Re-read the exact existing Supervisor Work, Requirement, relay scope, authority, blocked class, budgets and current record revision.
+4. Submit verified provider/environment recovery evidence for the existing `consecutive_failures` block.
+5. Prove the same semantic round is rearmed without changing `roundCount`, `repeatedStateCount`, relay scope or per-round authority, and without erasing historical failure evidence.
+6. Prove provider dispatch occurs at most once and exact Controller claim succeeds.
+7. Let ChatGPT submit its semantic disposition.
+8. Prove at least one `continue_immediately -> pending_release -> controller release -> successor/next dispatch` sequence completes automatically without a human sending `继续`.
+9. Verify round authority rotates only at the true new-round boundary and no duplicate disposition/provider effect exists.
+10. Only after this sequence may the Automatic Progression acceptance step be considered complete.
+
+## Required implementation shape
+
+The next Plan step must converge existing mutation helpers onto one policy rather than wrapping the old special cases with another layer of exceptions. A suitable shape is:
+
+```ts
+type ControllerRoundEvent = ... // provider-neutral typed events
+type ControllerRoundTransitionDecision = Accept | NoOp | Reject | NeedsEvidence
+
+function decideControllerRoundTransition(
+  current: ControllerRoundAggregateSnapshot,
+  event: ControllerRoundEvent,
+): ControllerRoundTransitionDecision
+```
+
+Existing public helpers may remain as compatibility facades during migration, but they become thin event builders around the canonical policy. Scheduler, Launcher, MCP and provider adapters must contain no independent status/blocker transition tables after convergence.
+
+## Explicit non-solutions
+
+Do not:
+
+- add a one-off `consecutive_failures` rearm branch,
+- raise `maxFailures`/`maxRounds`,
+- clear durable counters or edit SQLite by hand,
+- use elapsed time as provider recovery proof,
+- treat Browser/ChatGPT registration as Kernel-specific lifecycle logic,
+- infer successful dispatch from a transport session id,
+- reopen semantic terminal states from stalled recovery,
+- create another Supervisor/relay to avoid the blocked lineage, or
+- keep parallel mutation tables in Scheduler/Launcher/MCP while claiming a central policy exists.
+
+This ADR is the acceptance authority for the r3 ControllerRound recovery-convergence implementation.
+
+## Explicit migration map from current implementation
+
+Current `controller-round-store.ts` exposes ten lifecycle mutators and contains fifteen direct ControllerRound persistence write sites. Migration is complete only when these entry points no longer contain independent lifecycle decision tables.
+
+| Current helper | Compatibility role after convergence | Policy event / responsibility |
+| --- | --- | --- |
+| `bindControllerRoundSuccessorWork` | thin facade | submit `successor_bound`; policy validates predecessor/successor lineage and atomic handoff eligibility |
+| `submitControllerRoundDisposition` | thin facade | submit `semantic_disposition_submitted`; all semantic-close budget/status decisions move to policy |
+| `beginInitialControllerRoundDispatch` | thin facade | submit `occurrence_requested`; policy decides whether occurrence is genuinely new and legal |
+| `beginControllerRoundRelayAfterRelease` | thin facade | submit `controller_release_observed`; policy chooses same-lineage next-round transition and authority rotation |
+| `reconcileControllerRoundAfterAbandonedRelease` | thin facade | submit released-without-disposition evidence; policy chooses mechanical failure/retirement only |
+| `reconcileControllerRoundAfterTerminalWork` | thin facade | submit `terminal_work_observed`; policy retires failed/cancelled Work relay only |
+| `finishControllerRoundRelayDispatch` | thin facade | submit one of dispatch succeeded/failed/outcome-unknown/user-action events; no local status ternary remains |
+| `acknowledgeControllerRoundClaim` | thin facade | submit `controller_claim_observed`; repeated-state/outcome-unknown recovery must not live in claim code |
+| `recoverControllerRoundRelayAuthority` | thin facade | submit `authority_recovery_requested`; policy validates state and emits capability rekey only |
+| `claimStalledControllerRoundRelays` | scanner/orchestrator only | identify candidates and submit `stalled_round_observed` / evidence events; it must not write recovered relay states itself |
+
+### Persistence convergence
+
+The current store has fifteen `writeControlPlaneRecord*` call sites associated with these lifecycle paths. The target is not necessarily one physical SQL statement, because successor handoff legitimately needs a two-record transaction, but there must be **one logical apply authority**:
+
+- ordinary single-relay transitions go through one `applyControllerRoundTransitionDecision(...)` persistence executor;
+- predecessor/successor handoff goes through one atomic `applyControllerRoundHandoffDecision(...)` executor produced by the same policy;
+- no public mutation facade calls `writeControlPlaneRecord*` after making its own status/budget/blocker decision.
+
+### Outer-layer convergence
+
+Current outer composition demonstrates why this is necessary:
+
+- `chatgpt-round-continuation.ts` currently composes initial dispatch, dispatch finish, claim acknowledgement, disposition and release/next-round helpers; after migration it orchestrates provider effects around policy events only.
+- Scheduler maintenance currently claims stalled relays and directly records dispatch success/failure; after migration it scans/authorizes wake, performs the provider effect intent, then submits the resulting receipt event.
+- MCP runtime tools currently invoke claim, disposition, release, launch and dispatch settlement helpers directly; after migration MCP is a compatibility/event translation surface only.
+- ChatGPT/Browser provider adapters remain responsible for provider-specific observation and effect execution, never lifecycle status selection.
+
+### Completion assertion
+
+A static regression should fail if Scheduler, Launcher, MCP compatibility or provider adapters acquire a new direct ControllerRound status/blocker mutation table or write ControllerRound relay records outside the canonical apply executor. This is an architecture boundary, not a code-style preference.

package/docs/architecture/decisions/20260907-maintenance-diagnosis-bounded-read.md

@@ -0,0 +1,39 @@
+# Runtime maintenance diagnosis uses bounded read-side inventory
+
+Status: Accepted and implemented on 2026-09-07.
+
+## Problem
+
+Runtime maintenance diagnosis had three multiplicative costs on repositories with long-lived Controller history:
+
+- stale EditSession discovery called `reconcileEditSession` for every open-like candidate, which hashes tracked after-images, runs Git dirty-path inspection, and may persist reconciliation metadata;
+- every stale Work/EditSession independently reloaded active Plans, Schedules, Controller ownership and up to 500 Process history records;
+- stale Work repository source inspection ran before the visible `maxCandidates` bound, so expensive Git status/revision/containment checks could exceed the advertised candidate budget.
+
+On the real Forge Controller Home with 637 WorkContracts and 388 EditSessions, the observed maintenance diagnosis path took roughly 25–35 seconds.
+
+## Decision
+
+Maintenance status discovery is inventory, not repair:
+
+1. Resolve the existing repository runtime-storage binding first, then build one bounded authority snapshot for the status pass.
+2. Reuse Work, live Controller session, active Plan, Requirement, Schedule and Process ownership facts across all candidates in that pass.
+3. Read active Process authority from Process Runtime's recoverable index instead of enumerating terminal Process history.
+4. EditSession discovery reads summary/ownership metadata only. Workspace hashing, Git dirty checks, supersession and finalization occur only in explicit maintenance for a selected candidate.
+5. Sort and bound stale Work candidates before repository source Git inspection.
+6. Destructive stale-Work maintenance re-reads current authority at its mutation boundary; the status snapshot never becomes mutation authority.
+
+The snapshot is a derived in-memory view for one diagnosis call. It is not persisted and is not a second lifecycle authority.
+
+## Verification
+
+After implementation on the same real Controller data set:
+
+- `buildRuntimeMaintenanceStatus`: 563.8 ms for 200 returned candidates;
+- legacy `listProcessRecords(..., 500)`: 729.82 ms for 500 historical records;
+- `listRecoverableProcessRecords`: 2.82 ms for the active/recoverable index in the same repository;
+- targeted maintenance semantic regressions: 5 passed, 0 failed;
+- Direct Edit / EditSession continuity consumers: 28 passed, 0 failed;
+- `package:check:type`: passed.
+
+The 25–35 second diagnosis regression is therefore removed without lowering lifecycle gates or hiding candidates.

package/docs/architecture/domains/verification.md

@@ -17,6 +17,13 @@ repos, command facades, hooks, migration helpers, and installed runtime copies.
 
 - Self-host and generated behavior must be checked together when shared assets change.
 - `bun test` is the broad regression gate.
+- Governed tests preserve typed per-file failure evidence (`source`, `fixture`, `infrastructure`, `interrupted`) in bounded receipts; Check/Work verification may collapse that evidence only to the existing acceptance-vs-infrastructure authority, never by reparsing human stderr.
+- The active Runtime always owns Process admission, leases, terminal Process state, and Work verification receipts. For ordinary repositories, persisted checks execute through that Runtime's immutable Check Runner.
+- Self-hosting Forge Work verification is the bounded exception to runner location, not to lifecycle authority: when the verified repository has the same durable `repoId` as the Runtime Source authority, a non-live verification snapshot executes the Check Runner from that exact candidate snapshot. Candidate runner/content identity is folded into the existing Check execution fingerprint so evidence cannot cross runner revisions.
+- `live_controller_home` certification never uses the candidate snapshot runner because it is explicitly verifying the installed Runtime. A candidate snapshot missing its Forge-owned sidecar fails closed; no arbitrary executable override or second scheduler/store is introduced.
+- Public `rh_work verify` accepts either one `check_id` or one non-empty `check_ids` batch, never both. A batch is admitted only when the registered checks form one ordinary resource-compatible wave according to Process Runtime `buildCheckExecutionSchedule`; invalid, cross-wave, release, and multi-phase batches fail closed before partial execution. Every admitted member still runs through the canonical Work verification service, Work snapshot, Process Runtime claims, Failure Contract, and VerificationRecord authority; batch aggregation is not a scheduler or lifecycle authority.
+- Work verification persistence is one read-modify-write authority: any decision derived from current `checkRefs`, scope evidence, review state, or lifecycle state must read the latest Work and derive its patch inside the existing Work-store writer critical section. Synchronous writer contention remains fail-fast/retryable rather than sleeping on the Gateway path; a retry must re-read current state before deriving its mutation, so stale snapshots cannot silently erase compatible evidence.
+- Legacy Work lifecycle inference is migration-only. The exact bounded historical shapes accepted by the compatibility migrator, including the pre-review-checkpoint schema-v3 row, are canonicalized and persisted once with revision-fenced Controller Home authority. Normal current-schema reads validate canonical state; malformed schema-v3 rows outside those historical shapes fail closed instead of receiving generic read-time repair.
 - `check-task-sync.sh` enforces that substantive repo changes update `tasks/`.
 - `check-task-workflow.sh --strict` is the repo-local harness readiness gate.
 - `sync-brain-docs.sh --check` verifies manifest-controlled repo-to-brain mirrors without making gbrain or MCP part of hook correctness.

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

@@ -18,7 +18,7 @@ verify without a live service.
 ## Stable Rules
 
 - `assets/workflow-contract.v1.json` is the canonical contract asset.
-- `.ai/harness/workflow-contract.json` is the installed runtime copy.
+- `forge.config.json` (legacy `.ai/harness/workflow-contract.json` remains migration-only) is the installed runtime copy.
 - Migration deletes only manifest-owned `known_generated` surfaces.
 - User-authored legacy docs are preserved or archived before template refresh.
 - `_ref/`, `_ops/`, secrets, local env, and custom hooks are not product migration surfaces.

package/docs/architecture/index.md

@@ -8,7 +8,7 @@ The canonical documentation model is intentionally small:
 - [`../ROADMAP.md`](../ROADMAP.md) — current and next architecture/product priorities.
 - [`EVOLUTION.md`](EVOLUTION.md) — append-only historical architecture change log.
 - [`versions/`](versions/) — per-version architecture snapshots.
-- [`history/`](history/) and [`history.md`](history.md) — archived historical evidence, never runtime authority.
+- [`history.md`](history.md) — compatibility pointer to the evolution log and Git history; never runtime authority.
 - [`../../CHANGELOG.md`](../../CHANGELOG.md) — release history.
 - `decisions/` — accepted ADR rationale; accepted invariants are folded into `CURRENT.md` when they become ordinary current architecture.
 - `requests/` — pending architecture drift/change requests only.
@@ -19,7 +19,7 @@ Executable code and persisted schemas are authoritative for implementation facts
 ## Pending Architecture Requests
 
 <!-- BEGIN ARCHITECTURE PENDING REQUESTS -->
-- (none)
+- [ ] 2026-09-04 [unknown] `unknown` -> [2026-09-04-computer-plugin-workflow-taxonomy](requests/2026-09-04-computer-plugin-workflow-taxonomy.md)
 <!-- END ARCHITECTURE PENDING REQUESTS -->
 
 ## Accepted Architecture Decisions
@@ -28,4 +28,4 @@ Existing accepted ADRs remain under [`decisions/`](decisions/). Once a decision
 
 ## Change discipline
 
-Do not create another current-architecture page for each refactor. Architecture-root Markdown is limited to `CURRENT.md`, `EVOLUTION.md`, `history.md`, and this index; historical pages belong under `history/`. Update `CURRENT.md` only when the architecture contract changes, update `ROADMAP.md` when priorities change, append `EVOLUTION.md` for material architecture transitions, and create/update a version snapshot only at a release/version boundary. Implementation phases, pending manual work, operator-local paths, and other execution status belong in durable Work/Plan evidence rather than maintained current architecture.
+Do not create another current-architecture page for each refactor. Architecture-root Markdown is limited to `CURRENT.md`, `EVOLUTION.md`, `history.md`, and this index. Obsolete architecture evidence belongs in Git history rather than a maintained history tree. Update `CURRENT.md` only when the architecture contract changes, update `ROADMAP.md` when priorities change, append `EVOLUTION.md` for material architecture transitions, and create/update a version snapshot only at a release/version boundary. Implementation phases, pending manual work, operator-local paths, and other execution status belong in durable Work/Plan evidence rather than maintained current architecture.

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

@@ -5,20 +5,31 @@
 
 ## Responsibility
 
-`src/cli/mcp/transports/` owns HTTP authentication handoff, MCP Streamable HTTP session lifecycle, global admission capacity, transport leases, DELETE cleanup, and liveness/readiness metrics. It does not own durable Job execution or Gateway process recovery.
+`src/cli/mcp/transports/` owns HTTP authentication handoff and protocol-era serving. MCP 2026-07-28 is the canonical public boundary and is served per request without protocol-level sessions. The session registry, global admission capacity, transport leases, and DELETE cleanup exist only for the explicit 2025-era compatibility path. The transport does not own durable Work/Process/ControllerRound authority or Gateway process recovery.
 
 ## Invariants
 
-- All public MCP HTTP routes share one registry and one global maximum.
-- Route and authenticated principal must match the stored session on GET, POST, and DELETE.
-- Active POST work is protected from capacity eviction.
-- Stream-only sessions are reclaimable through client DELETE, explicit prior-session replacement, lease expiry, absolute lifetime, or oldest-safe capacity eviction.
-- Initialize admission is an atomic registry reservation. Shared static-bearer clients use the global pool; per-principal fairness applies only where authentication provides a meaningful distinct principal.
-- Health metrics report actual global counts; readiness reflects whether initialize can be admitted safely.
-- Closing transport state never implies that a durably accepted Job is cancelled.
+- Modern `server/discover` and subsequent 2026-07-28 requests are handled by the SDK v2 per-request handler and do not require or emit `Mcp-Session-Id`.
+- Durable Work, Process, and ControllerRound identity is independent from both modern request bindings and legacy transport sessions.
+- A newly created Work is claimed with an opaque Work-bound controller capability immediately; modern sessionless follow-up requests must present that exact authority. Legacy owner records without a capability digest require an explicit `controller_claim` authority upgrade and are never accepted by principal identity alone.
+- Legacy 2025-era traffic is classified mechanically by the SDK and routed to one bounded stateful compatibility registry shared by all public MCP HTTP routes.
+- On the legacy path, route and authenticated principal must match the stored session on GET, POST, and DELETE; active POST work is protected from capacity eviction.
+- Legacy stream-only sessions are reclaimable through client DELETE, explicit prior-session replacement, lease expiry, absolute lifetime, or oldest-safe capacity eviction.
+- Legacy initialize admission is an atomic registry reservation. Shared static-bearer clients use the global pool; per-principal fairness applies only where authentication provides a meaningful distinct principal.
+- Legacy capacity readiness distinguishes `immediate`, `eviction`, and `blocked` admission. Capacity eviction releases registry routing/ownership synchronously before old transport cleanup; peer cleanup is best-effort and must never hold the serialized initialize admission lane after the old session is fenced out.
+- Health session metrics describe only legacy compatibility state; modern request serving has no long-lived session capacity authority.
+- Closing or replacing transport state never implies that a durably accepted Work or Process is cancelled.
+- The Gateway-to-Canonical-Runtime client classifies structured SDK HTTP 404 as an expired inner session, reconnects once, and replays only an operation already proven replay-safe by its idempotency contract.
+- The public Gateway may burst-scale a bounded shared pool of inner Canonical Runtime MCP lanes. A released lane remains hot only for a bounded idle lease; reuse cancels retirement, while expiry explicitly terminates the Streamable HTTP session before closing the local client so the Runtime does not retain an orphaned Server/transport graph. Durable Work, Process, and Controller authority is never coupled to that transport retention window.
 
 ## Verification
 
 ```text
 bun test tests/unit/fix-mcp-session-lifecycle.test.ts tests/cli/mcp-http.test.ts
 ```
+
+## MCP Runtime adapter decomposition boundary
+
+The public MCP Tool Contract is frozen independently from implementation placement. `check:mcp-compatibility` records both the stable tool-name fingerprint and the canonical schema fingerprint, so moving a handler between adapters cannot silently change the connector ABI.
+
+`runtime-tools.ts` and `router.ts` are currently migration debt, not architecture authorities. Runtime Architecture keeps shrinking inventories for their direct imports into Kernel/Context/Control Plane/Execution/Recovery/Plugin/Workflow/Repository domains and for the `callRuntimeTool` switch cases. A stage may remove an inventory entry only when ownership moves behind the correct domain adapter/application API; adding a new entry fails the architecture gate. This deliberately avoids source-line-count rules while making mega-adapter regrowth mechanically impossible.

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

@@ -0,0 +1,124 @@
+# Computer / Plugin / Workflow taxonomy convergence
+
+> **Status**: Pending
+> **Detected**: 2026-09-04
+> **Requirement**: `REQ-forge-v2-durable-agent-harness-foundation-20260902`
+> **Predecessor plan**: `PLAN-kernel-v2-module-authority-computer-convergence-20260903-r2`
+> **Captured successor draft**: `PLAN-kernel-v2-module-authority-computer-workflow-convergence-20260904-r3`
+> **Source revision reviewed**: `18490210a328fac2c4585ee4f2d43771dec19d3d`
+
+## Why this request exists
+
+The existing V2 Computer convergence plan already covers the important Computer-side architecture: `computer` as the single normal public interaction product, Browser/Desktop semantic namespaces, one durable interaction ownership graph, provider-only native Desktop Operator semantics, Process Runtime resource authority, and `outcome_unknown -> observe/reconcile`. It does **not** yet make the higher-level Plugin taxonomy or runtime Workflow model an explicit executable architecture boundary.
+
+Current source proves the gap: `src/runtime/plugins/first-party-registry.ts` registers Computer, Browser, true API integrations and the Xiaohongshu publishing flow through the same `AssistantPluginAdapter` abstraction. `src/runtime/plugins/xiaohongshu-publish.ts` is a compiled Browser workflow: it owns site URLs, selectors, visible-text anchors, publish modes, auth/page-state classification, ordered Browser actions and post-publish verification, then executes the actual steps through the Browser capability. That is workflow content, not an independent plugin/provider authority.
+
+## Required taxonomy
+
+V2 must explicitly distinguish four concepts even if compatibility transport still exposes `plugin_action_execute`:
+
+1. **Capability**: reusable semantic operation Forge can request.
+2. **Provider**: replaceable implementation of one or more capabilities.
+3. **Integration**: external-system owner justified by an independent protocol/auth/security/persistence/lifecycle boundary. Platform branding alone is insufficient.
+4. **Workflow / Recipe**: user-goal composition of capabilities. Site-specific URLs/selectors/visible-text/page-state/verification sequences belong here unless a real Integration boundary exists.
+
+`Plugin` must not remain the only internal taxonomy. A shared tool/manifest transport does not grant equal authority semantics.
+
+## Computer boundary that must be preserved
+
+- `computer` remains the single normal public interaction product.
+- Browser and Desktop remain distinct semantic subdomains beneath Computer.
+- Browser DOM/CDP/navigation/query/file-input semantics are preferred when stronger than physical input.
+- Desktop Operator/native macOS is provider/device-driver only: OS/TCC/socket/handshake/capture/input/live handles. It does not own Forge workflows, policy, durable lifecycle, semantic completion, scheduling or independent retry/reconciliation.
+- Browser session/Computer target state converges under one deliberate durable interaction ownership graph in Controller Home. Provider/browser/OS handles remain rebuildable observations.
+- Non-idempotent mutations never blind-replay after `outcome_unknown`; existing observe/reconcile authority remains canonical.
+- Process Runtime claims/leases remain the only execution concurrency authority.
+
+## Computer hot-path transport contract
+
+The 2026-09-09 #200 latency review proved that the native Desktop Operator is not the dominant warm-path cost, so provider transport optimization must preserve the existing authority boundary rather than introduce another controller or durable provider session. The Computer runtime therefore uses the following transport contract:
+
+- one live Desktop Operator provider binding is scoped to the current trusted registration identity/revision and endpoint contract;
+- provider identity/capability negotiation is reused only while the same Unix-socket connection generation remains live;
+- sequential Computer requests may reuse that bounded JSONL channel instead of reconnecting and handshaking for every action;
+- registration fingerprint/revision or endpoint-contract change disposes the old provider binding before replacement;
+- if the Unix connection changes after negotiation, the pending action is rejected before dispatch and the next explicit invocation must renegotiate; non-idempotent effects are never replayed automatically;
+- timeout, cancellation, response-size and protocol-error bounds remain per request; transport reuse creates no new durable lifecycle or retry authority.
+- Browser semantic mutations do not pay an unconditional fixed post-action sleep: provider primitives and bounded post-action identity/evidence are the normal completion path; `post_action_wait_ms` is explicit compatibility input only, while native foreground activation may retain a provider-specific verification budget because system foreground authority must be observed.
+- Desktop target-bound semantic actions dispatch through the current leased provider binding without a `desktop_status(limit: 500)` preflight. Only an explicit provider `SESSION_NOT_FOUND` transported as a failed/pre-effect result may rebuild the binding from stable application identity and retry once; transport, timeout, and outcome-unknown failures are never replayed. Target close likewise calls the bound session close directly instead of enumerating provider sessions first.
+- Desktop observe/input/capture product actions use the retained `ComputerProvider` channel instead of re-entering the legacy external-adapter transport for every semantic action. Target open/close remain low-frequency provider lifecycle operations; the hot path owns no parallel durable provider-session authority.
+- the external Unix JSONL and `ComputerProviderError` failure contracts preserve `failed` versus `outcome_unknown` across adapter boundaries. A provider-declared failure keeps the negotiated connection alive; transport loss after an effectful request is dispatched invalidates negotiation and is never eligible for implicit replay.
+
+The repeatable `benchmark:computer-hotpath` run on 2026-09-09 used 50 warm semantic samples after five warmups. The isolated real dispatch path measured cold first semantic action `4.398ms`; warm `p50=0.939ms`, `p95=1.511ms`, `max=1.894ms`. Across the 50 warm samples the provider observed exactly 50 semantic RPCs, zero new connections, zero handshakes, zero manifest preflights, zero `desktop_status` preflights, and zero session reopens. This benchmark is comparative evidence, not a machine-specific release threshold.
+
+This is a transport/runtime optimization beneath the existing Computer authority. Browser/OS handles remain ephemeral observations, and Process Runtime plus existing unknown-outcome reconciliation remain authoritative for execution concurrency and effect recovery.
+
+## Workflow Asset Contract
+
+Introduce the smallest generic versioned Workflow Asset model needed to move user-goal automation out of Core. Human-editable assets include:
+
+- workflow definition / step composition;
+- prompt guidance for semantic judgement;
+- deterministic helper scripts;
+- templates/selectors/resources;
+- asset version and content digest.
+
+Machine authority is separate and records only what the runtime must trust/decide, including installed/active workflow identity/version/digest, capability grants/bindings, and bounded execution receipts/checkpoints. Prompt/script bodies are not the primary SQLite authority.
+
+Default active user workflow assets belong under Controller Home, not the Forge source repository or arbitrary target repositories. Project-owned workflow assets are allowed only through an explicit project contract and remain project data. Secrets are referenced through existing secret/authorization authority; workflow files must not become a new secret store.
+
+## Workflow Runtime boundary
+
+The Workflow Runtime is a thin interpreter/composer, **not another Kernel**. It may validate inputs, resolve assets and capabilities, order steps, record subordinate checkpoints/receipts, and request reconciliation. It must not create competing authority for:
+
+- Requirement / Work / ControllerRound lifecycle;
+- semantic acceptance or goal completion;
+- scheduler continuation;
+- retry decisions after unknown external outcome;
+- process/resource locking.
+
+Durable or external-effect workflow execution is subordinate to an existing Work/run identity. Scripts execute only through existing Process Runtime, policy and resource-claim boundaries.
+
+## Xiaohongshu migration proof
+
+Use Xiaohongshu publishing as the first bounded migration proof after Computer/plugin taxonomy convergence:
+
+- remove compiled first-party workflow authority from `src/runtime/plugins/xiaohongshu-publish.ts`;
+- express publish modes, Browser actions, auth markers, selectors, checkpoints and dual verification as versioned workflow data;
+- do not recreate the same platform-specific TypeScript under `packages/workflow-runtime`;
+- any temporary `xiaohongshu` plugin/action compatibility alias is translation-only, owns no workflow state, has bounded consumers and an explicit removal trigger.
+
+If a future official Xiaohongshu API creates a true protocol/auth/resource boundary, only that protocol-facing owner becomes an Integration. User-goal orchestration remains Workflow.
+
+## Architecture gates
+
+Extend the existing architecture checker with ownership-aware rules so new business/site workflows cannot quietly return to Kernel/Computer/provider/first-party integration code. The gate must reject end-user workflow orchestration embedded in generic layers unless an independent Integration boundary is explicitly justified, while still allowing legitimate endpoint/protocol constants inside a real Integration adapter. Prefer import/manifest/ownership rules over brittle string bans.
+
+Workflow asset digest/version changes must invalidate stale binding/receipt reuse. Compatibility shims must have a named replacement owner, bounded consumers and removal trigger.
+
+## Required execution order
+
+Do **not** start a parallel V2 implementation from this request. Preserve the predecessor plan order and execute only after current overlapping V2 Stage8/final-certification/portability work is reconciled:
+
+1. Stage B: shrink module/legacy ownership debt and strengthen existing architecture gates.
+2. Stage C: finish Controller/MCP/composition convergence.
+3. Stage D: finish Computer/Browser/Desktop convergence **and** make Capability/Provider/Integration taxonomy explicit.
+4. Stage E: add Workflow Asset Contract + thin Workflow Runtime + Xiaohongshu migration + anti-regression gates.
+
+Before implementation starts, refresh exact source revision and active path ownership. Never open a second Computer/Workflow plan merely to bypass an occupied or stale scope.
+
+## Plan metadata blocker discovered while capturing this request
+
+The decision-complete successor was persisted as draft `PLAN-kernel-v2-module-authority-computer-workflow-convergence-20260904-r3`, with the four stages and detailed acceptance criteria above. Forge incorrectly persisted its `scopeKey` as `unknown`, so approval is blocked. Creating a successor with the intended scope `kernel-v2-module-authority-computer-convergence-20260903` is also blocked because the scope index still reports terminal predecessor `...-r1` as owner even though r1 already points to r2 and r2 was superseded during successor creation.
+
+This is a Forge Plan authority/index defect, not permission to create a parallel scope. Future V2 mainline must first repair/reconcile the stale scope owner + draft scope-key persistence, then approve/recreate the captured successor under the original scope. Do not delete this request until an approved successor PlanContract with the correct scope exists.
+
+## Completion criteria for this request
+
+This architecture request may be marked complete only when:
+
+- one approved successor PlanContract under the original Computer-convergence scope contains the taxonomy, Workflow Asset, runtime authority and Xiaohongshu migration decisions above;
+- predecessor/draft Plan metadata is reconciled with no duplicate active authority;
+- later implementation proves the Stage D/E boundaries and their focused architecture/type/main checks;
+- `docs/architecture/CURRENT.md` is updated **after** the implementation is true, not before;
+- obsolete public Browser/workflow-plugin compatibility authority is removed or bounded with an explicit removal trigger.