@moretea-labs/forge 1.5.0-rc.1

package/docs/architecture/current/local-workspace-target-grants.md

@@ -0,0 +1,70 @@
+# Local Workspace Target Grants
+
+## Authority
+
+Repository-free local directory access uses one authority:
+
+```text
+controllerHome/system/local-system/targets.json
+```
+
+The `local_system` plugin created this authority. The reusable implementation now lives in `src/runtime/workspace-targets/`; the plugin is an adapter over that core. No second Ephemeral Workspace store, Repository Registry shadow record, or route decision store is permitted.
+
+## Grant identity
+
+A target grant authorizes one existing absolute directory for a bounded period. New grants record:
+
+- canonical root path;
+- read-only or read-write access;
+- owner scope derived from the authenticated principal propagated by the execution entrypoint;
+- optional Controller instance identity for audit;
+- deterministic workspace identity and full identity fingerprint;
+- read-only Git detection;
+- creation, expiry, and reason.
+
+The workspace identity derives from canonical root, owner scope, access mode, schema version, and authority name. It is stable across retries and Controller restarts but is not a `repoId`.
+
+Historical schema-v1 records containing only `targetKey`, `rootPath`, timestamps, and reason remain readable. They are interpreted as `read_write` and `legacy:shared` until their original expiry. Historical audit data is not bulk rewritten.
+
+The store and every record are validated before use. Unreadable JSON, malformed records, invalid timestamp ranges, or a persisted identity that no longer matches canonical root, owner scope, and access fail closed without rewriting the evidence. Git metadata is rediscovered on read rather than trusted as a permanent snapshot.
+
+New owner isolation must use the authenticated MCP/controller principal, not a generic tool name or request id. The Gateway adapter is responsible for propagating that principal into the plugin execution origin. Until a trusted principal is available, generic Controller actors are normalized to the explicit `controller:shared` scope; they never claim per-user isolation.
+
+## Filesystem boundary
+
+All plugin file paths and future command working directories must use the same core resolver. It rejects:
+
+- absolute child paths;
+- lexical traversal outside the grant root;
+- existing symlinks that escape the root;
+- non-existing destinations whose nearest existing ancestor escapes the root;
+- missing or non-directory command working directories;
+- writes through read-only grants.
+
+The resolver re-canonicalizes the root at use time. A moved, deleted, or replaced root fails closed. Grant-store mutations use the existing global Controller Lock and fail with retryable contention instead of silently losing concurrent updates.
+
+Explicit revocation uses the same owner-scoped authority and Controller Lock. It removes only the caller-owned active grant; the next read, write, or command fails closed as unavailable. Revocation is recorded through the normal plugin action receipt and local-effect Work lineage rather than a second audit store.
+
+## Git behavior
+
+Git discovery is read-only and recognizes:
+
+- a repository root with a `.git` directory;
+- a linked worktree root with a `.git` file;
+- a directory nested inside an existing repository;
+- a non-Git directory.
+
+Authorizing a target never runs `git init`, registers a repository, adopts a dirty workspace, or creates a Work.
+
+## Execution integration
+
+A Target Grant supplies workspace facts and path authorization only. It does not decide execution mode and does not authorize arbitrary commands.
+
+- Route Policy remains the only direct-versus-durable and executor authority.
+- Mutations still require Work lineage, current owner identity, policy/route evidence, base workspace fingerprint, verification, and a final receipt.
+- The existing repository command classifier and approval policy must be reused when command execution is wired to Target Grants.
+- Repository-wide Git refs, Issue ownership, release operations, and long-lived repository defaults still require explicit Repository Registry promotion.
+- Single-file deletion is a dedicated root-bounded action with strong confirmation and a durable receipt. Recursive/directory deletion and arbitrary `rm` execution remain unavailable.
+- Ordinary target commands remain typed-argv and classifier-bounded. A project script that cannot be proven read-only uses a separate high-risk action: the caller selects one fixed interpreter resolved from a closed set of canonical system locations, one root-contained script, and its exact SHA-256 digest, then provides strong confirmation. Caller-supplied executable paths, eval flags, and shell command strings are not accepted, and execution holds the target mutation lock with destructive authorization recorded on the Work contract.
+
+This boundary enables repository-free local work without weakening command policy or introducing a parallel lifecycle owner.

package/docs/architecture/current/migration-roadmap.md

@@ -0,0 +1,105 @@
+# Target Architecture Migration Record
+
+> Status: **Active Migration Record**
+> Completion baseline: 2026-06-25
+> Lifecycle convergence baseline: 2026-08-02
+
+The execution-plane phases below remain completed. The seven-phase lifecycle source convergence governed by [`runtime-architecture-simplification.md`](runtime-architecture-simplification.md) is also complete. This source result does not imply that a new release has been activated on a running installation; live activation remains a separate explicit operation with exact release evidence.
+
+## P0 — Single-Owner Runtime Convergence
+
+Active target:
+
+- one `forge-runtime` process owns MCP Transport, Gateway Adapter, Controller Services, Scheduler, SQLite, and Worker Manager;
+- one Runtime Root owns core startup, shutdown, fatal failure, ownership, and binary readiness;
+- MCP binds directly to one configured Runtime endpoint; no Stable Ingress or alternate serving slot exists;
+- `runtime/releases/authority.json` owns one atomic active/previous whole-release selection;
+- SQLite contents and backups remain local Controller Home execution state and are never distributed in source, packages, releases, or manifests;
+- Workers are bounded Runtime-owned children and every state mutation is fenced by Runtime/release/Job/attempt/Lease identity;
+- standalone Recovery remains independently installable for diagnostics, self/tunnel repair, and offline whole-Runtime rollback, but owns no primary component lifecycle;
+- old bootstrap slot/writer compatibility state, restart coordinator, and component lifecycle scripts are removed; Canonical Runtime fencing is the only write authority.
+
+The convergence is one-way and fail-closed. Unsupported legacy authority must report migration/fencing errors rather than selecting a slot, component pointer, or fallback process owner.
+
+## P0 — Stabilize and Remove Request-Lifetime Execution
+
+Completed:
+
+- long and mutating MCP calls are persisted as durable Jobs and acknowledged immediately;
+- Gateway session, body size, initialization and POST concurrency are bounded;
+- overload produces explicit 429/503 responses instead of unbounded request accumulation;
+- repository commands, checks, Edit verification, Agent dispatch and integration run outside Gateway;
+- `/health`, `/ready` and repository health remain available during Worker execution;
+- synchronous legacy code is confined to isolated Workers where compatibility requires it.
+
+## P1 — Unified Execution Model
+
+Completed:
+
+- common `ExecutionJob` state machine;
+- global request-id dedupe and semantic conflict detection;
+- active/recent/request indexes;
+- durable Operation Receipts before side effects;
+- Job/Run separation, deadlines, attempts, heartbeat and reconciliation;
+- append-only entity events;
+- bounded result bodies and addressable Artifacts;
+- ambiguous mutation recovery stops for human review instead of replaying blindly.
+
+## P2 — Repository Actor and Resource Scheduling
+
+Completed:
+
+- one logical Actor mailbox per repository;
+- Claims for Workspace, Worktree, paths, Git refs, checks, integration, remote and release resources;
+- renewable Leases with monotonically increasing fencing tokens;
+- attempt/PID/Lease ownership that rejects zombie Workers;
+- conservative unknown write scope;
+- Workspace single writer and eligible automatic Worktree placement;
+- serial Integration and release barriers.
+
+## P3 — Multi-Repository Control Plane
+
+Completed:
+
+- global Worker and Agent limits;
+- Heavy Check and provider quotas;
+- memory and CPU-load admission;
+- priority plus aging fairness persisted across restart;
+- per-repository actor isolation;
+- cross-repository Portfolio DAG;
+- deterministic stop/compensation Saga semantics;
+- repository identity and remote-mapping diagnostics.
+
+## P4 — Schedule Engine
+
+Completed:
+
+- first-class Schedule, Trigger, Decision and Occurrence records;
+- interval, manual, UTC cron, calendar, condition-watch, repository-event and dependency-checkpoint triggers;
+- deterministic occurrence-window identity and active/recent indexes;
+- maximum active occurrences, cooldown, daily budget and persisted exponential backoff;
+- consecutive-failure circuit breaker and external-blocker stops;
+- dirty Workspace and release-freeze suppression;
+- Shadow Mode default;
+- Candidate Finding semantic dedupe and explicit human promotion;
+- one bounded Job per executable Occurrence;
+- unattended external-side-effect prohibition.
+
+Operational rule: new mutation Schedules still begin in Shadow Mode as a rollout policy, not because the engine is incomplete.
+
+## P5 — Verification and Release Gate
+
+Completed:
+
+- exact-revision Evidence records and environment fingerprints;
+- stale revision rejection;
+- Artifact references for large output;
+- exclusive Release Freeze Lease;
+- active Job/Run/Edit/Integration and repository-identity checks;
+- exact-revision Task Verification requirements;
+- deterministic release-ready manifest;
+- explicit human authorization boundary for push, merge, publish and deployment.
+
+## Maintenance Gate
+
+Future changes must preserve architecture invariants, add an ADR before weakening a boundary, update the current architecture documents and extend focused checks for every new Job, Claim, Trigger, recovery path or release condition.

package/docs/architecture/current/multi-repository-execution.md

@@ -0,0 +1,371 @@
+# Multi-Repository Execution
+
+> Status: **Runtime Authority**
+
+## 1. Objective
+
+Multi-repository execution allows unrelated projects to progress concurrently while preserving repository-local ownership, fair system capacity, explicit cross-repository dependencies, and failure isolation.
+
+The core rule is:
+
+> The Global Control Plane allocates capacity; each Repo Actor decides repository-local safety.
+
+No global repository lock is permitted for ordinary work.
+
+## 2. Repository Identity and Isolation
+
+Every command resolves to:
+
+```text
+repoId
+checkoutId when applicable
+```
+
+A repository has independent:
+
+- Issue and Task state;
+- Jobs and Runs;
+- Claims and Leases;
+- Workspaces and Worktrees;
+- check queues;
+- integration queue;
+- release freeze;
+- GitHub mapping;
+- runtime projections and evidence.
+
+A repository-local failure MUST NOT mutate or block another repository's state.
+
+## 3. Global Capacity Model
+
+The Global Scheduler maintains configurable limits such as:
+
+```text
+maxConcurrentRepositories
+maxWorkers
+maxAgentProcesses
+maxAgentProcessesByProvider
+maxHeavyChecks
+maxHeavyChecksByRepository
+maxWritesByRepository
+maxWorktreesByRepository
+memoryBudget
+cpuBudget
+optional provider cost budget
+```
+
+Recommended defaults favor stability:
+
+- at least one slot remains available for explicit user work when scheduled work is active;
+- one Heavy Check per repository;
+- a small global Heavy Check cap;
+- one Workspace writer per Checkout;
+- Worktree writers limited by repository and global Worker capacity.
+
+These are policy defaults, not hard-coded architecture constants.
+
+## 4. Scheduling Eligibility
+
+A repository Job is globally eligible when:
+
+1. its Repo Actor reports repository-local readiness;
+2. dependencies are satisfied;
+3. required Claims can eventually be granted;
+4. no release barrier prohibits its class;
+5. global quota is available or the Job may enter a fair queue;
+6. the Job has not exceeded budget, deadline, or retry policy.
+
+The Global Scheduler does not re-evaluate path conflicts. That remains the Repo Actor's responsibility.
+
+## 5. Priority Classes
+
+Recommended priority classes:
+
+```text
+P0 — Controller availability, data integrity, security, active incident
+P1 — explicit user-requested work
+P2 — continuation of current accepted Task or release-critical dependency
+P3 — scheduled repair or confirmed maintenance
+P4 — discovery, optimization candidate, background hygiene
+```
+
+Priority does not bypass safety, dependency, or authorization gates.
+
+## 6. Fair Queueing
+
+The target policy is aging weighted fair queueing across repositories.
+
+A scheduling score may consider:
+
+```text
+priority class
+wait duration
+user initiated vs scheduled
+critical dependency path
+repository recent resource share
+estimated execution cost
+retry count
+provider availability
+deadline proximity
+```
+
+Fairness rules:
+
+- one busy repository cannot consume all Workers indefinitely;
+- low-priority Jobs age toward eligibility;
+- a repository with a blocked Workspace may still run read-only or Worktree work;
+- scheduled maintenance yields to explicit user work;
+- capacity is not reserved for disabled or release-frozen repositories unless release policy requires it.
+
+## 7. Failure Isolation
+
+Repository A states that must not block Repository B include:
+
+- dirty Workspace;
+- path conflict;
+- stale Job;
+- orphaned Worker;
+- failed Heavy Check;
+- unresolved integration conflict;
+- missing local Agent configuration;
+- invalid GitHub mapping;
+- release freeze;
+- corrupted projection that can be rebuilt locally.
+
+System-wide degradation is justified only for shared infrastructure failures such as:
+
+- Controller Home unavailable;
+- scheduler state cannot be persisted safely;
+- global authentication boundary compromised;
+- Worker pool unavailable;
+- process-wide resource exhaustion.
+
+## 8. Repository Backpressure
+
+A Repo Actor may signal:
+
+```text
+ready
+capacity_limited
+workspace_blocked
+integration_backlog
+release_frozen
+configuration_blocked
+storage_blocked
+disabled
+```
+
+Backpressure removes or limits that repository's dispatch eligibility without blocking status queries or unrelated repositories.
+
+## 9. Cross-Repository Portfolio Workflow
+
+Cross-repository intent is represented by a Portfolio Workflow, not by attaching foreign Tasks directly to one repository Issue.
+
+Example:
+
+```text
+Portfolio: API v2 migration
+  -> backend/schema Task in Repository A
+  -> SDK generation Task in Repository B depends on A checkpoint
+  -> client migration Task in Repository C depends on B
+  -> documentation Task in Repository D independent after A
+```
+
+Each node contains:
+
+```text
+portfolioNodeId
+repoId
+issueId / taskId or creation template
+dependsOn nodes
+required checkpoint
+failure policy
+compensation metadata
+```
+
+The Portfolio coordinator observes repository node outcomes but cannot directly mutate repository-local execution state outside the owning Actor command path.
+
+## 10. Saga Semantics
+
+Cross-repository work uses Saga semantics rather than distributed atomic transactions.
+
+```text
+prepare node
+  -> execute in repository
+  -> verify repository checkpoint
+  -> persist portfolio checkpoint
+  -> unlock dependent nodes
+```
+
+On failure:
+
+```text
+stop dependents
+  -> preserve successful checkpoints
+  -> execute explicit compensation when safe
+  -> or require human decision
+```
+
+Compensation examples:
+
+- revert a generated SDK commit through a reviewed change;
+- disable a feature flag;
+- restore a prior configuration artifact;
+- abandon an unmerged branch.
+
+Unsafe compensation must not be inferred or executed automatically.
+
+## 11. Checkpoint Contract
+
+A cross-repository dependency is satisfied by an explicit checkpoint, not by another repository's raw process exit.
+
+Checkpoint examples:
+
+```text
+Task accepted and verified
+artifact published to a local staging path
+schema hash recorded
+commit SHA prepared
+API contract generated
+release candidate manifest approved
+```
+
+Each checkpoint records:
+
+```text
+repoId
+source entity
+revision or artifact hash
+verification evidence
+createdAt
+validity or expiry conditions
+```
+
+If a checkpoint becomes stale, dependent nodes must pause or re-evaluate.
+
+## 12. Cross-Repository Concurrency
+
+Independent nodes may execute concurrently when:
+
+- their repository-local Actors report readiness;
+- global capacity exists;
+- no shared external resource requires serialization;
+- the Portfolio DAG has no dependency edge between them.
+
+Cross-repository writes do not conflict merely because paths have the same name. Conflict keys include `repoId`.
+
+Shared external resources may still require global Claims, for example:
+
+```text
+package-name:<registry>:<name>
+deployment-environment:<name>
+shared-database:<identifier>
+shared-generated-artifact:<key>
+remote-project:<provider>:<id>
+```
+
+## 13. Multi-Checkout Repositories
+
+Multiple local Checkouts of one logical repository share:
+
+- repository identity;
+- Git ref mutation coordination;
+- provider and release mapping;
+- repository-wide Heavy Check or release policy when configured.
+
+They have separate Workspace claims.
+
+A Checkout cannot be treated as a separate repository solely to bypass repository-level ordering or release policy.
+
+## 14. Git and Remote Mapping
+
+Repository registry canonical remote and GitHub plugin mapping must be diagnosable separately.
+
+A mismatch may mean:
+
+- local fork with upstream remote;
+- stale plugin configuration;
+- repository transfer;
+- duplicate registry record;
+- intentionally different collaboration target.
+
+The system must warn and require explicit reconciliation. It must not silently create a second active `repoId` or publish to an inferred remote.
+
+## 15. Cross-Repository Release
+
+A Portfolio release uses staged barriers:
+
+```text
+all required nodes verified
+  -> each repository enters local release freeze
+  -> validate checkpoints are current
+  -> generate portfolio release manifest
+  -> human authorization
+  -> execute repository release actions in declared order
+  -> record partial or complete outcome
+```
+
+A partial release is a first-class outcome. Recovery follows the declared rollout or compensation policy; it is not hidden as global success.
+
+## 16. Scheduled Work Across Repositories
+
+A global Schedule may select multiple repositories, but it creates one repository-scoped Occurrence per selected `repoId`, plus an optional parent portfolio occurrence.
+
+This preserves:
+
+- repository-local idempotency;
+- independent failure and backoff;
+- per-repository budget;
+- fair scheduling;
+- scoped notifications.
+
+One failing repository does not force successful repository Occurrences to rerun.
+
+## 17. Disable and Removal
+
+A disabled repository:
+
+- accepts read-only historical queries;
+- does not admit new execution Jobs;
+- retains durable state and audit history;
+- may finish or explicitly cancel active work according to disable policy.
+
+A soft-removed repository remains addressable with `include_removed` for audit and recovery. Removal does not delete evidence automatically.
+
+## 18. Implemented Runtime
+
+The current runtime provides:
+
+- stable repository registry and multiple checkout records;
+- repository-scoped Controller Home storage;
+- explicit `repo_id` and `checkout_id` routing;
+- one logical Repo Actor mailbox per repository;
+- global Worker, Agent, provider, Heavy Check, CPU and memory budgets;
+- persisted aging/fairness state across Daemon restart;
+- repository-local Claims, renewable Leases and fencing tokens;
+- Portfolio DAG dependencies with deterministic stop or Saga compensation;
+- repository-scoped Schedule Occurrences;
+- explicit repository identity and remote-mapping drift diagnostics;
+- disabled/removed repository admission barriers while retaining audit reads.
+
+## 19. Compatibility and Extension Rules
+
+The legacy Umbrella entity remains readable for stored-state compatibility. New cross-repository execution ownership belongs to `PortfolioWorkflow`, not Umbrella mutation code.
+
+New multi-repository features must:
+
+- create repository-scoped durable Jobs;
+- declare cross-repository dependencies explicitly;
+- avoid global repository locks;
+- preserve independent failure, retry, budget and evidence per repository;
+- route external publication through verified repository/GitHub mapping;
+- add an ADR before weakening fairness or repository isolation.
+
+## 20. Runtime Verification
+
+The architecture gate and process smokes verify that:
+
+- Scheduler dispatch history is persisted;
+- one repository can wait without blocking another repository's actor;
+- Portfolio dependency cycles are rejected;
+- external side effects are rejected in unattended Portfolio execution;
+- Worker failure is reconciled through durable Job state rather than Gateway lifetime.

package/docs/architecture/current/operations-runbook.md

@@ -0,0 +1,45 @@
+# Controller Runtime Operations Runbook
+
+> Status: **Runtime Authority**
+
+## Health
+
+- `GET /health`: Gateway event loop, session pressure and tool surface. Must stay fast.
+- `GET /ready`: binary whole-Runtime readiness for the Canonical Forge Runtime.
+- `GET /repos/<repoId>/health`: repository projection, queue and Lease state.
+- MCP `controller_ready`: equivalent structured readiness.
+
+## Job Inspection
+
+Use `get_job` with the returned Job ID. Include events only for lifecycle diagnosis. Use `get_artifact` for bounded access to oversized results.
+
+Key waiting states are not failures:
+
+- `waiting_for_dependency`
+- `waiting_for_workspace`
+- `waiting_for_heavy_check`
+- `waiting_for_integration`
+- `waiting_for_release_barrier`
+
+## Recovery
+
+The Canonical Forge Runtime reconciles running Jobs every five seconds. Operation Receipts distinguish a completed side effect from an uncertain mutation window. A completed receipt closes the Job after restart; an uncertain mutating operation becomes `human_attention_required` and is never replayed blindly. Safe read-only work may be retried while attempts remain. Cancellation terminates the owned Worker when present and releases only the exact Lease/fencing set for that attempt. Stale Workers cannot renew, release or publish against a replacement attempt.
+
+## 502 Diagnosis
+
+1. Check `/health`. A failure here indicates Gateway or transport failure.
+2. Check `/ready`. A healthy Gateway with failed readiness indicates Daemon/control-plane degradation.
+3. Read the accepted Job by ID. Do not infer failure from a disconnected MCP request.
+4. Inspect repository projection for waiting resources.
+5. Inspect Job events and Worker heartbeat.
+6. Distinguish explicit 429/503 admission pressure from an upstream tunnel 502.
+
+Long work is not retried by resending an arbitrary request ID. Reuse the original request ID to recover the accepted Job.
+
+## Schedule Safety
+
+Create mutation Schedules with Shadow Mode enabled. Review persisted Decisions and Occurrences before enabling execution. Interval, UTC cron, calendar, condition-watch, repository-event, dependency-checkpoint and manual triggers all produce one bounded idempotent Occurrence. Failures use persisted exponential backoff. Schedules cannot push, publish, close remote Issues, deploy, inflate requirements directly or run arbitrary repository commands.
+
+## Release
+
+Request a Release Gate Job. A successful Gate produces `releaseReady: true` and a manifest for the exact current revision. It does not push, tag, publish or deploy.

package/docs/architecture/current/peer-supercontroller-runtime.md

@@ -0,0 +1,32 @@
+# Peer SuperController Runtime
+
+Status: active on `codex/supercontroller-refactor`
+
+## Boundary
+
+- External SuperController chooses models, planning, and Agent launches.
+- Kernel owns repository truth, Work/Plan/Handoff contracts, Process Runtime,
+  Direct Edit, deterministic maintenance, and plugin receipts.
+- Kernel does **not** select models, create Agent Runs, create ExecutionJobs, or
+  create Local Bridge Jobs for ordinary work.
+
+## Deterministic Kernel paths
+
+- `work_submit` / `rh_work` → WorkContract + ControllerSession ownership
+- `repository_command_execute` short path → Process Runtime
+- `plugin_action_execute` → validate → confirm → adapter → receipt
+- `runtime_maintenance_apply` schedules → preview → apply → occurrence receipt
+
+## Semantic / external paths
+
+- Non-deterministic schedules record occurrence + Handoff only
+- Campaign reconcile migrates unfinished tasks into Work + Handoff
+- Legacy Agent dispatch tools return structured retirement responses
+
+## Failure policy
+
+- No automatic retry/replay of ordinary writes
+- Temporary deterministic schedule failures account consecutiveFailures and write
+  one Handoff; permanent config errors pause the schedule
+- After rollout 502s, inspect by request ID / Process / WorkContract; do not
+  auto-replay writes