@moretea-labs/forge 1.5.0-rc.1

package/docs/architecture/current/system-overview.md

@@ -0,0 +1,144 @@
+# Controller Runtime System Overview
+
+> Status: **Runtime Authority**
+
+## 1. System Definition
+
+Forge Controller Runtime is an Agent Engineering Control Plane for one or more local Git repositories. ChatGPT, Local UI, CLI and optional GitHub integrations submit decisions and commands. The runtime persists accepted work, schedules it under repository-owned conflict rules, executes it outside the Gateway process and records evidence for recovery, acceptance and release.
+
+## 2. Canonical Runtime Topology
+
+```text
+Client
+  -> forge-runtime (one local MCP application)
+       MCP Transport
+       Gateway Adapter
+       Controller Services
+       SQLite control plane
+       Global Scheduler + Per-Repository Actors
+       Evidence Plane + Materialized Projections
+       |
+       +-> forge-worker (bounded Runtime-owned child)
+             command / check / Agent dispatch / integration / release gate
+             |
+             v
+           repository workspace, Worktree, GitHub provider
+```
+
+The durable execution model uses atomic state, bounded Worker processes, Leases, and fencing. Gateway Adapter, Controller Services, Scheduler, SQLite, and MCP Transport run inside one Canonical Runtime process, while Workers remain bounded child execution units.
+
+Supervisor, independent Daemon/Gateway services, Stable Ingress, runtime slots, bootstrap compatibility authority, restart coordinator, and component rollout/rollback are deleted from the source architecture. One Runtime owner record and one whole-release authority fence all current writes.
+
+The approved target is [`runtime-architecture-simplification.md`](runtime-architecture-simplification.md): one local MCP application, one active Runtime, one root lifecycle owner, one binary readiness result, and one whole-Runtime release/rollback unit.
+
+## 3. Gateway Adapter
+
+Implemented as a module under:
+
+- `src/cli/mcp/server.ts`
+- `src/cli/mcp/transports/http.ts`
+- `src/runtime/gateway/mcp/router.ts`
+- `src/runtime/gateway/mcp/runtime-tools.ts`
+
+The Gateway Adapter performs authentication, schema validation, explicit repository selection, bounded context/results, and routing inside the Canonical Runtime. Eligible reads and bounded actions may complete Direct; repository commands and checks enter Unified Process Runtime; durable Work is admitted only when lifecycle, recovery, dependency, or isolation requirements justify it. The Gateway does not make the HTTP request the owner of a long-running process.
+
+Bounded direct reads include health, Controller context, repository state, Process/Work status, and bounded results. Overload is rejected with explicit 429/503 responses instead of unbounded accumulation.
+
+The three MCP HTTP paths share one global session registry. SSE streams are bounded transport leases, not work ownership. Client DELETE, explicit prior-session replacement, lease expiry, absolute lifetime and oldest-safe capacity eviction may close a session with no active POST; capacity management never evicts active POST work. `/health` reports the global pool, while `/ready` reports whether a new initialize can be admitted safely.
+
+## 4. Controller Services and Scheduler
+
+Implemented under `src/runtime/control-plane/` and initialized by the Runtime Root.
+
+The in-process Controller Services and Scheduler own:
+
+- fair cross-repository dispatch;
+- global Worker and Agent quotas;
+- provider-specific quotas;
+- Heavy Check limits;
+- host free-memory and CPU-load admission;
+- Schedule ticks;
+- Portfolio DAG progress;
+- orphan/deadline reconciliation.
+
+Fairness state is persisted, so restart does not permanently reset repository aging.
+
+## 5. Per-Repository Actor
+
+Each repository is represented by one logical `RepoActor`. Actor decisions are serialized by a repository-specific mailbox lock whose critical section contains only state reads, Claim decisions and state transitions.
+
+The Actor owns:
+
+- dependency readiness;
+- repository-local priority and aging;
+- Workspace/Worktree placement;
+- Claim acquisition;
+- Lease and fencing assignment;
+- waiting-state classification;
+- release barriers.
+
+Long work runs after the Actor releases its short transaction lock.
+
+## 6. Execution Plane
+
+Forge uses three execution depths rather than forcing every operation through one durable protocol:
+
+1. **Direct** — bounded readonly observations, Direct Edit, and explicitly authorized ephemeral workspace actions can complete without manufacturing Work, Process, Lease, or Worker state when none is required.
+2. **Unified Process Runtime** — repository commands and checks spawn one physical process, persist a stable Process identity and lifecycle, and support status/wait/log/cancel attachment without re-execution. Resource Claims and Leases protect conflicting effects.
+3. **Durable Work / Scheduler** — long-lived, dependency-aware, recoverable, isolated, or parallel objectives use Work contracts, repository actors, workers, and optional worktrees.
+
+Repository command input has one canonical boundary: typed argv arrays preserve executable and argument boundaries end to end and execute without a shell; legacy command strings remain supported only through an explicit compatibility shell boundary. Policy classification, path scope, authorization, Process execution, and result receipts consume the same representation.
+
+Process records and durable Work are both idempotently addressable by their caller-visible identities. Fenced writes reject stale ownership. Result bodies are bounded; oversized results become addressable Artifacts. Legacy ExecutionJob records remain readable as compatibility state but are not the ordinary command/check hot path.
+
+## 7. Resource Plane
+
+Stable resource keys include:
+
+```text
+repo-state
+repo-content:*
+workspace:<checkoutId>
+worktree:<identity>
+path:<glob>
+git-refs:<repoId>
+heavy-check:<repoId>
+integration:<repoId>
+remote:<repoId>
+release:<repoId>
+```
+
+Unknown write scope becomes `repo-content:*`. Workspace writes are single-writer. A second automatically placed Agent may move to a unique Worktree Claim. Worktree implementation can run concurrently, but Integration and Git-ref mutation are exclusive.
+
+## 8. Schedule and Portfolio Planes
+
+A Schedule produces one idempotent Occurrence per normalized time window. Occurrences are bounded and indexed. Shadow Mode records the decision without mutation. Budgets, cooldowns, maximum active occurrences and failure circuit breaking are persisted.
+
+A Portfolio Workflow is a cross-repository DAG. Dependencies are explicit. Failure policy is deterministic stop or Saga compensation. External side effects are blocked from unattended workflows.
+
+## 9. Evidence and Projection Planes
+
+Evidence contains exact revision, environment fingerprint, outcome, Job identity and artifacts. Event ledgers are append-only. Large output is not embedded in hot status responses.
+
+Materialized projections summarize active Jobs, queue depth, workers, Leases, release freeze and human-attention states. HTTP readiness and Local UI read these projections rather than scanning history.
+
+## 10. Release Plane
+
+A Release Gate is a durable Job with an exclusive repository-wide release Claim. It checks:
+
+- current Git revision and clean Workspace;
+- active Jobs, Runs and Local compatibility Jobs;
+- pending Worktree integration;
+- non-final Edit Sessions;
+- other Leases;
+- active-Issue Task completion;
+- exact-revision verification evidence;
+- repository/Git/GitHub identity consistency;
+- whole-Runtime readiness evidence;
+- package metadata.
+
+The successful result is a release-ready manifest. Push, merge, publish and deployment remain separate, explicitly authorized operations.
+
+## 11. Compatibility Layer
+
+`src/cli/mcp/tools.ts` remains as a stable export facade; the preserved implementation is isolated in `src/cli/mcp/legacy-tool-service.ts`. Local Jobs and Agent Run records remain readable and operational for compatibility. In Controller mode, long compatibility implementations are invoked only by isolated Workers. The compatibility layer is not the scheduling owner.

package/docs/architecture/current/target-requirements-traceability.md

@@ -0,0 +1,202 @@
+# Target Architecture Requirements Traceability
+
+> Status: **Runtime Authority**  
+> Baseline: **2026-06-25 target architecture migration**
+
+This document maps every major section of the approved target architecture to executable implementation and verification evidence. It is a traceability index, not a second design authority.
+
+Approved input: [`approved-target-architecture.zh-CN.md`](approved-target-architecture.zh-CN.md).
+
+## 1. Overall topology
+
+| Requirement | Status | Evidence |
+| --- | --- | --- |
+| Thin Gateway | Implemented | `src/runtime/gateway/mcp/`, `src/cli/mcp/server.ts` |
+| Global Scheduler | Implemented | `src/runtime/control-plane/global-scheduler/` |
+| Per-Repository Actor | Implemented | `src/runtime/control-plane/repo-actor/` |
+| Durable Job | Implemented | `src/runtime/execution/jobs/` |
+| Isolated Worker | Implemented | `src/runtime/execution/workers/` |
+| Evidence Plane | Implemented | `src/runtime/evidence/`, `src/runtime/projections/` |
+
+## 2. Layer responsibility migration
+
+- MCP performs authentication, schema validation, repository routing, bounded projection reads and durable acknowledgement inside the Canonical Runtime.
+- Runtime Root owns Controller Services, scheduling, reconciliation, Schedule and Portfolio progression in the same process.
+- Repo Actor owns repository-local scheduling decisions and resource acquisition.
+- Worker owns commands, checks, Agent execution, integration and compatibility implementations.
+- Historical state is not used as a hot queue; active/recent/request indexes and projections are authoritative for observation.
+
+Runtime evidence: `root/runtime.ts`, `root/entry.ts`, `router.ts`, `scheduler.ts`, `actor.ts`, `worker-entry.ts`, `materialized-view.ts`.
+
+## 3. Target process topology
+
+Implemented as one canonical application process plus isolated execution Workers:
+
+```text
+forge-runtime (Runtime Root + Controller Services + Scheduler + Gateway/MCP)
+forge isolated Worker
+```
+
+One Runtime process owns the complete local application. One Worker process executes one bounded Job and is fenced by Runtime/Job/lease identity; Worker failure does not create another Runtime owner.
+
+Verification: `tests/runtime/canonical-single-runtime.test.ts`, `scripts/smoke-mcp-http-runtime.ts`.
+
+## 4. Architecture constitution
+
+| Constitution rule | Implementation |
+| --- | --- |
+| MCP does not execute long work | Durable router; Workbench is a Job; Controller Context is a materialized read with Worker refresh |
+| Persist before execute | `createExecutionJob` precedes Daemon dispatch |
+| Idempotent mutations | global `requestId` index plus `semanticKey` conflict detection |
+| Task and Run remain separate | legacy lifecycle preserved; Execution Job is a separate system entity |
+| One scheduler owner per repository | Repo Actor mailbox and registry |
+| Unknown Scope is conservative | `repo-content:*` write Claim |
+| Short state locks, long execution Leases | atomic JSON transactions plus renewable Lease records |
+| Hot paths use indexes | active/recent/request/run/integration/occurrence/portfolio/finding indexes |
+| Execution and observation are isolated | Worker process plus health/projection reads |
+| Verification binds exact Revision | Evidence record and release-gate revision checks |
+| Conflicts queue instead of failing | explicit `waiting_for_*` Job states |
+| External effects need authorization | defense-in-depth governance checks in Gateway, Schedule, Portfolio and Worker |
+
+## 5. Work-mode and Agent strategy
+
+The original Direct Edit, Quick Agent and Issue/Task assessment remains available. Runtime dispatch persists the chosen operation and preserves allowed Agent providers, timeout and browser permissions. Explorer/Implementer/Verifier policy remains a planning concern; deterministic integration and release checks remain program-owned rather than LLM-owned.
+
+Evidence: `src/cli/controller/work-mode.ts`, `src/runtime/gateway/mcp/router.ts`, `src/runtime/execution/workers/executor.ts`.
+
+## 6. Single-repository concurrency
+
+Implemented Claims cover:
+
+- `repo-state`;
+- `workspace:<checkoutId>`;
+- `worktree:<id>`;
+- `path:<glob>`;
+- `git-refs:<repoId>`;
+- `heavy-check:<repoId>`;
+- `integration:<repoId>`;
+- `remote:<repoId>`;
+- `release:<repoId>`.
+
+Workspace writes serialize. Independent Worktrees may execute concurrently. Integration and Git-ref changes serialize. Unknown writes conflict with repository content. Lease ownership includes Job, Attempt, Worker PID and Fencing Token.
+
+## 7. Multi-repository scheduling
+
+Implemented:
+
+- global Worker, repository, Agent-provider and Heavy Check quotas;
+- CPU-load and memory admission;
+- P0-P4 priority with Aging;
+- persisted repository fairness;
+- Portfolio DAG validation;
+- stop or compensation Saga policy;
+- repository-local failure isolation.
+
+Evidence: `src/runtime/control-plane/global-scheduler/`, `src/runtime/workflow/portfolio/`.
+
+## 8. Schedule architecture
+
+Implemented first-class `Schedule`, `Trigger`, `Occurrence`, `Decision`, `ExecutionJob` and `Outcome` records.
+
+Supported triggers:
+
+- interval;
+- manual;
+- five-field UTC cron;
+- calendar timestamp;
+- condition watch;
+- repository event;
+- dependency checkpoint.
+
+Safety controls include deterministic occurrence IDs, active-occurrence limit, daily budget, cooldown, exponential backoff, failure circuit breaker, stop conditions, default Shadow Mode, dirty-workspace suppression and release-freeze suppression. Automated discoveries become Candidate Findings; they cannot directly create Issue, Task, PRD or Plan.
+
+## 9. State storage
+
+- Business intent stays in repository files: `plans/`, `tasks/`, Issue records and architecture decisions.
+- Runtime state stays under Controller Home by `repoId`.
+- Evidence, Artifacts, events, receipts, indexes and projections are independently addressable.
+- Writes are atomic; event records are append-only; large output is bounded or externalized as an Artifact.
+
+## 10. 502 and latency controls
+
+Implemented internal controls:
+
+- no Agent, Check, command, integration, Workbench or release execution in the Gateway request lifetime;
+- `controller_context` returns a materialized snapshot immediately and refreshes in a Worker;
+- Local Bridge status and output use bounded snapshot readers without reconciliation or Git commands in Gateway;
+- MCP session limit and idle collection;
+- initialization, per-session and global POST backpressure;
+- explicit 429/503 with retry guidance;
+- aligned keep-alive, header and request timeouts;
+- bounded logs and indexed history;
+- split `/health`, `/ready` and repository health.
+
+External tunnel, platform and physical-network failures remain outside the local process guarantee.
+
+## 11. Verification and release
+
+Implemented layered Evidence and an exclusive Release Gate. The gate checks workspace cleanliness, active Jobs/Runs/Edits/Integrations, Leases, required Tasks, exact-Revision verification, registry/remote/GitHub mapping, Daemon readiness and package metadata. Push, merge, tag, publish and production deployment remain separately authorized.
+
+## 12. Agent control principles
+
+- Controller plans and reviews; Workers execute bounded operations.
+- Worker completion is not Task acceptance.
+- Verification uses declared acceptance criteria and exact Revision evidence.
+- Deterministic integration and release operations are program-owned.
+- Automation may return `nothing_to_do`, Shadow decisions or Candidate Findings without manufacturing work.
+
+## 13. Runtime directory migration
+
+The new implementation is organized under:
+
+```text
+src/runtime/gateway/
+src/runtime/control-plane/
+src/runtime/workflow/
+src/runtime/execution/
+src/runtime/resources/
+src/runtime/evidence/
+src/runtime/projections/
+src/runtime/release/
+```
+
+The former 4,700-line MCP implementation is retained as `legacy-tool-service.ts` for compatibility and invoked in Workers. `src/cli/mcp/tools.ts` is a thin facade.
+
+## 14. Documentation governance
+
+`docs/architecture/current/` is the only Runtime Authority. V4-V8 documents remain Historical Design. `plans/` remains a business-intent and implementation-plan catalog, not a runtime queue.
+
+## 15. P0-P5 migration status
+
+All migration phases have executable implementations:
+
+- P0: request-lifetime execution removal and health isolation;
+- P1: unified Job, receipts, indexes, evidence and recovery;
+- P2: Repo Actor, Claims, Leases, Fencing and integration serialization;
+- P3: fair multi-repository scheduling and Portfolio Saga;
+- P4: bounded Schedule engine and Candidate Finding governance;
+- P5: exact-Revision verification and release gate.
+
+Detailed evidence: [`migration-roadmap.md`](migration-roadmap.md).
+
+## 16. Standard execution flow
+
+```text
+Resolve Repository
+-> read compact projection
+-> classify work mode
+-> select/create Issue and Task when required
+-> declare Scope and Claims
+-> persist requestId and ExecutionJob
+-> return Job ID
+-> Repo Actor schedules
+-> Worker executes with heartbeat and Lease renewal
+-> persist Receipt, events, Artifact and Evidence
+-> reconcile terminal state
+-> integrate serially
+-> verify exact Revision
+-> accept Task
+-> evaluate dependency / release gate / stop
+```
+
+No Worker may bypass Scope, persistent Job ownership, Claims, Evidence or verification.

package/docs/architecture/current/thin-harness-governance-policy.md

@@ -0,0 +1,32 @@
+# Thin Harness Governance Policy
+
+## Purpose
+
+Preserve thin harness performance goals while allowing controlled workflow evolution.
+
+## Execution routing
+
+Direct edit is the default path for bounded, low-risk changes. Escalate to Requirement/Issue/Work only when complexity requires lifecycle tracking, parallelism, long-running execution, or additional protection.
+
+Priority order:
+
+1. Direct edit
+2. Requirement/workflow
+3. Issue/task orchestration
+4. Campaign
+
+## Architecture strategy changes
+
+The following changes require explicit user approval before migration:
+
+- changing the default execution mode
+- replacing direct execution with mandatory orchestration
+- changing thin harness performance goals
+- introducing additional lifecycle layers that affect latency
+- changing authority models or user entry points
+
+Storage migrations must not silently change user workflow semantics.
+
+## Conflict handling
+
+When a refactor conflicts with an established architecture strategy, report the conflict and request approval instead of silently applying the new strategy.