@moretea-labs/forge 1.6.0 → 1.7.1

package/docs/architecture/current/runtime-directory-map.md

@@ -1,49 +0,0 @@
-# Runtime Directory Map
-
-> Status: **Runtime Authority**
-
-```text
-src/runtime/
-  root/                        Canonical Runtime root lifecycle, readiness and write fencing
-  release/                     Whole-release identity, active/previous selection and rollback metadata
-  standalone-recovery/         Independent diagnostics, service repair and offline whole-Runtime rollback
-  gateway/mcp/                 Thin command admission, policy and runtime tools
-  control-plane/
-    global-scheduler/          Global fairness, quotas, process dispatch and reconciliation
-    repo-actor/                Repository-local single-owner scheduling
-    governance/                External side-effect and requirement-growth policy
-  workflow/
-    schedules/                 Trigger, bounded Occurrence, persisted Decision and backoff
-    portfolio/                 Cross-repository DAG and Saga
-    findings/                  Deduplicated Candidate Finding and explicit promotion
-  plugins/                     Derived manifests, discovery registry, policy-typed actions and provider adapters
-  execution/
-    jobs/                      Durable Job schema, indexes, Operation Receipts and compatibility projection
-    workers/                   Isolated one-Job process execution
-    thin-harness/              Fast Path router, latency trace, receipts, typed batch, lightweight lanes
-  resources/
-    claims/                    Conflict taxonomy and conservative unknown scope
-    leases/                    Lease, renewal, release and fencing
-  evidence/                    Unified events, exact-revision evidence and bounded Artifacts
-  projections/                 Dirty-marker invalidated materialized read models
-  release/                     Release freeze, gate and manifest
-  shared/                      Atomic file and portable Node TypeScript-loader utilities
-```
-
-`src/cli/` contains the Forge CLI, MCP adapter surface and bounded internal operation implementations. It is not a second lifecycle owner. Gateway handlers admit and route work; the Runtime Root, Process Runtime and bounded Workers own execution.
-
-When Controller Home explicitly enables the Local Bridge without selecting external `standalone` or `remote` mode, `src/runtime/root/local-bridge.ts` starts that HTTP UI/API as an in-process module of the Canonical Runtime and closes it before releasing Runtime ownership. Its compatibility projection may describe the endpoint, but it is not a separate process, launch service, readiness authority, or recovery owner.
-
-New scheduling ownership must be added under `src/runtime/`, never inside MCP transport handlers.
-
-## Runtime Storage Ownership and Quarantine
-
-Each bound directory under Controller Home contains `.forge-owner.json` with `repoId`, binding name, and management identity. Repository-local `.ai/harness/<binding>` paths are links to these owned directories.
-
-Migration tooling may quarantine pre-cutover state for offline inspection under:
-
-```text
-<controller-home>/repositories/<repoId>/quarantine/runtime-storage/<binding>/
-```
-
-Execution readiness remains false for active/unreadable Run or Local Job state and for non-directory/path conflicts. A non-empty worktree directory by itself is not a reason to perform an unsafe move or to block forever.

package/docs/architecture/current/runtime-health-and-resource-lifecycle.md

@@ -1,85 +0,0 @@
-# Runtime Health and Resource Lifecycle
-
-Status: Current implementation note (2026-07-16)
-
-This note records the additive runtime-health and cleanup semantics. It does not
-create a new Controller boundary, health database, projection worker, or cleanup
-scheduler.
-
-## Observation versus evaluation
-
-Runtime callers collect diagnostic observations from the Canonical Runtime,
-Scheduler, Workers, materialized projections, Local Controller endpoint, and
-runtime storage. `src/runtime/health/evaluator.ts` remains a side-effect-free
-operational evaluator for blockers and warnings; it is not a lifecycle or
-readiness authority. The Runtime Root publishes the only public Runtime
-readiness decision as `ready: boolean`, with module observations retained only
-as diagnostic evidence.
-
-Projection age is not a health signal by itself. A readable idle projection is
-usable even when old. A dirty/source-changed projection is warning-level during
-the bounded refresh grace period and becomes a blocker only when the required
-refresh is missed or the build fails.
-
-Task Ledger status describes workflow progress and is not live process
-ownership. A Task may remain `running` across sequential Runs while no Worker is
-currently active. Differences between Task Ledger running counts and runtime
-Worker counts are repository-scoped attention evidence; they never block the
-global Gateway, Controller readiness, or release rollout. Execution readiness
-continues to fail closed on durable Job, queue, Lease, current-attention, and
-projection-build evidence.
-
-## Projection content and producer health
-
-`RepositoryRuntimeProjection.metadata` distinguishes content revision, source
-revision, content fingerprint, build attempt/success times, build errors, and
-producer generation. Dirty-marker invalidation remains the source-change signal;
-hot reads may rebuild in memory but do not clear the marker or rewrite a
-projection heartbeat.
-
-## Local Controller capability
-
-The expected health endpoint and its Local Controller surface are authoritative.
-Embedded, standalone, remote, disabled, and unknown modes are represented in
-runtime state and `/health`. A healthy expected endpoint can therefore report a
-ready capability while persisted `running=false` or stale PID evidence is kept
-as a warning. Wrong surfaces, missing endpoints, generation mismatches, and
-inactive-slot evidence remain blockers when the capability is required.
-
-## Current attention and history
-
-`buildRuntimeOperationalView` provides one read model with three explicit
-sections: current health blockers, pending attention, and recent history.
-Pending handoffs include acknowledged/in-progress items until they are explicitly
-resolved or dismissed. Terminal Jobs, resolved handoffs, and prior incidents
-remain in history and never degrade readiness merely because they exist. The
-underlying Job, event, and handoff records are not deleted by this view.
-
-## Ownership-aware cleanup
-
-Ownership is embedded in supported lifecycle records through `ManagedResource`.
-Agent Run worktrees and Execution Jobs carry an owner, type, timestamps, state,
-and optional retention/path data. Transitional runtime-slot records are not
-cleanup authority. Missing legacy metadata remains unknown and is protected.
-Existing cleanup authorities retain
-their startup/periodic/manual entrypoints, now emit a bounded audited
-`CleanupCycleSummary`, isolate failures, and default automatic removal to 50
-items per cycle. Type-specific collectors continue to guard process identity,
-TTL, worktree references, and known runtime roots.
-
-The implementation intentionally does not broaden automatic deletion for legacy
-artifacts, edit sessions, branches, or unproven temporary resources. Those
-resources remain retained until their existing Git/reference/lease authority can
-prove eligibility.
-
-## Canonical lifecycle boundary
-
-Runtime slot, candidate/standby, and Supervisor records are no longer source
-contracts. Cleanup proves eligibility from current Runtime ownership, exact
-release authority, process identity, Job attempt, Lease tokens, and explicit
-whole-release rollback references; it never infers authority from historical
-slot or component metadata.
-
-Focused regression coverage protects idle projections, missed refreshes, endpoint
-capability precedence, attention/history separation, bounded cleanup, and
-identity-safe compatibility behavior.

package/docs/architecture/current/scheduler-and-resource-claims.md

@@ -1,422 +0,0 @@
-# Scheduler and Resource Claims
-
-> Status: **Runtime Authority**
-
-## 1. Objective
-
-The scheduler decides when accepted work may execute and where it may run. It protects repository state without turning every repository into a global serial bottleneck.
-
-The core model is:
-
-```text
-Global Scheduler
-  -> Repo Actor mailbox
-     -> Job readiness
-     -> Resource Claims
-     -> Placement
-     -> Lease
-     -> Worker
-     -> Integration Queue
-```
-
-## 2. Per-Repository Actor
-
-### Target Architecture
-
-Each Repository has one logical Repo Actor that serializes repository-local scheduling decisions.
-
-Its mailbox accepts commands such as:
-
-```text
-admit Job
-cancel Job
-retry Job
-grant/release Claim
-renew/revoke Lease
-reconcile active state
-enqueue integration
-enter/leave release freeze
-update Task after evidence
-```
-
-The mailbox may be implemented through a single daemon queue, durable file queue, or equivalent mechanism. The invariant is single logical ownership, not one operating-system thread per repository.
-
-### Actor Responsibilities
-
-The Repo Actor owns:
-
-- idempotency admission;
-- dependency readiness;
-- active write conflict decisions;
-- Workspace and Worktree placement;
-- Heavy Check ordering;
-- integration ordering;
-- release barriers;
-- repository-local priority aging;
-- reconciliation after restart.
-
-It does not run Agent processes or long commands.
-
-## 3. Global Scheduler
-
-The Global Scheduler owns scarce system capacity:
-
-```text
-Agent process slots
-Worker slots
-Heavy Check slots
-provider quotas
-memory / CPU budgets
-cross-repository priority
-```
-
-It does not inspect path-level repository conflicts itself. It asks the relevant Repo Actor for repository-local eligibility.
-
-## 4. Resource Taxonomy
-
-Resources use stable keys.
-
-### Repository and Checkout Resources
-
-```text
-repo-state:<repoId>
-workspace:<checkoutId>
-git-index:<checkoutId>
-git-refs:<repoId>
-integration:<checkoutId>
-release:<repoId>
-remote-write:<repoId>
-```
-
-### Execution Capacity Resources
-
-```text
-agent-slot:<provider>
-worker-slot:<class>
-heavy-check:<repoId>
-light-check:<repoId>
-worktree-slot:<repoId>
-```
-
-### Path Resources
-
-```text
-path:<repoId>:<normalized-scope>
-```
-
-Path Claims are advisory scheduling precision layered on top of Workspace/Worktree isolation. They never weaken hard path-policy enforcement.
-
-## 5. Claim Model
-
-A Job declares required Claims before dispatch:
-
-```text
-resourceKey
-mode: shared | exclusive
-scope
-reason
-holdPhase
-```
-
-`holdPhase` identifies how long the resource is required:
-
-- admission transaction;
-- execution;
-- integration;
-- verification;
-- release.
-
-Claims are persisted so waiting state survives Controller restart.
-
-## 6. Claim Compatibility
-
-General compatibility:
-
-| Existing | Requested | Compatible |
-| --- | --- | ---: |
-| shared | shared | yes, subject to quota |
-| shared | exclusive | no |
-| exclusive | shared | no |
-| exclusive | exclusive | no |
-
-Path compatibility adds scope comparison. Two explicit non-overlapping path scopes may execute concurrently only when placement and checkout resources also permit it.
-
-Read-only work normally uses shared Claims and does not conflict with path writes unless it requires a repository mechanism that itself is exclusive.
-
-## 7. Unknown Scope
-
-A non-read-only Job with no trustworthy write scope claims:
-
-```text
-path:<repoId>:*
-```
-
-It conflicts with every other repository write scope.
-
-This is intentionally stricter than treating missing scope as “no known conflict.” Unknown means uncertainty, not independence.
-
-The Controller may reduce the Claim after bounded investigation identifies explicit paths.
-
-## 8. Workspace Single Writer
-
-A Checkout Workspace has one exclusive write Claim:
-
-```text
-workspace:<checkoutId>
-```
-
-The following all require it:
-
-- Direct Edit;
-- Workspace Agent execution;
-- repository command classified as workspace write;
-- integration into that Checkout;
-- deterministic formatter or generator that writes files.
-
-Read-only queries and processes may run concurrently if they do not require an exclusive Git/index resource.
-
-## 9. Worktree Placement
-
-Worktree execution requires:
-
-```text
-worktree-slot:<repoId>
-git-refs:<repoId> during creation/cleanup
-workspace:<worktreeCheckoutId> during execution
-path claims for scheduling visibility
-```
-
-Worktrees allow implementation concurrency but do not bypass:
-
-- Task dependencies;
-- allowed/forbidden path enforcement;
-- Agent/Worker quotas;
-- integration serialization;
-- release freeze policy.
-
-## 10. Placement Algorithm
-
-For one ready write Job:
-
-```text
-1. honor explicit workspace/worktree/provider request when safe
-2. inspect current Workspace writer
-3. inspect repository dirty state and ownership
-4. inspect path scope and concurrent Jobs
-5. prefer Workspace for one serial writer
-6. choose Worktree when concurrency or isolation is required
-7. wait when Worktree creation or later integration would be unsafe
-```
-
-A dirty Workspace is not automatically unavailable. The Actor distinguishes:
-
-- changes owned by the same Edit Session/Job;
-- unrelated user changes;
-- staged/index changes;
-- untracked generated artifacts;
-- known runtime-only paths.
-
-Unrelated user changes must be preserved. A new writer may be isolated or wait.
-
-## 11. Conflict Matrix
-
-| Work A | Work B | Default policy |
-| --- | --- | --- |
-| Read-only | Read-only | concurrent |
-| Read-only | Workspace write | concurrent when read mechanism is safe |
-| Direct Edit | Direct Edit, same Checkout | serialize |
-| Direct Edit | Workspace Agent, same Checkout | serialize |
-| Workspace Agent | Workspace Agent, same Checkout | serialize |
-| Worktree Agent | Worktree Agent | concurrent subject to quotas |
-| Worktree Agent, overlapping paths | Worktree Agent | may execute concurrently; integration serialized and conflict-checked |
-| Workspace write | Worktree Agent | concurrent if Git ref operations are bounded and path policy allows |
-| Light Check | Workspace write | configured by check purity; default shared read |
-| Heavy Check | Heavy Check, same repo | serialize |
-| Integration | Any Checkout writer | serialize on target Workspace |
-| Git ref mutation | Another Git ref mutation | serialize per repository |
-| Release Gate | New write admission | release freeze blocks new writes |
-| Remote write | Remote write | serialize and require authorization |
-
-## 12. Conflict Outcomes
-
-Temporary resource contention produces waiting details, not failure:
-
-```text
-waiting_for_workspace
-waiting_for_worktree_slot
-waiting_for_agent_slot
-waiting_for_heavy_check
-waiting_for_git_refs
-waiting_for_integration
-waiting_for_release_barrier
-waiting_for_dependency
-```
-
-Each waiting Job records:
-
-```text
-blockedResource
-blockedByJobIds
-queuedAt
-priority
-nextEvaluationAt
-deadlineAt
-```
-
-Irrecoverable policy or scope violations fail before execution.
-
-## 13. Short Locks and Long Leases
-
-### Transaction Lock
-
-Used for atomic operations such as:
-
-- reserve request ID;
-- create Job;
-- transition Task;
-- update active index;
-- grant Claim;
-- advance fencing token.
-
-It should be held for milliseconds and released before Worker execution.
-
-### Lease
-
-Used for long ownership:
-
-- Workspace writer;
-- Worktree owner;
-- Heavy Check execution;
-- Integration;
-- release freeze stewardship.
-
-Leases are renewable, expiring, and fenced.
-
-## 14. Fencing Tokens
-
-Every exclusive resource maintains a monotonically increasing token.
-
-When a new Lease is granted:
-
-```text
-fencingToken = previousToken + 1
-```
-
-A Worker includes the token on lifecycle and result writes. A write with an older token is rejected or recorded as stale evidence.
-
-This prevents a paused or partitioned Worker from overwriting state after ownership moved.
-
-## 15. Heavy and Light Checks
-
-Checks declare a concurrency class.
-
-### Heavy Check
-
-Examples include full test, CI, release, public export, coverage, or controller-wide verification.
-
-Default policy:
-
-- one active per repository;
-- global heavy-check quota;
-- identical Revision/check requests share execution;
-- Revision changes while queued make the old request stale;
-- subscriber cancellation is independent.
-
-### Light Check
-
-Examples include type checks or focused tests when repository policy classifies them as light.
-
-They may run concurrently up to a per-repository limit, but should not overload the same build cache or mutate generated files without explicit Claims.
-
-## 16. Integration Queue
-
-Every isolated change targeting the same Checkout enters one serialized queue.
-
-Queue record:
-
-```text
-sourceRunId
-reviewedDiffHash
-baseRevision
-targetCheckoutId
-priority
-enqueuedAt
-requiredChecks
-```
-
-Integration flow:
-
-```text
-acquire integration + workspace Claims
-  -> verify source evidence
-  -> compare target Revision and dirty state
-  -> apply deterministic patch
-  -> persist Integration Record
-  -> run focused verification
-  -> release Claims
-  -> clean Worktree only after durable success
-```
-
-On conflict:
-
-- preserve the Worktree;
-- mark integration conflict;
-- release target Claims;
-- create a focused repair action;
-- do not rebase, reset, or overwrite automatically.
-
-## 17. Priority and Aging
-
-Within a repository, Jobs are ordered by:
-
-```text
-explicit priority
-user-initiated over scheduled work
-critical dependency path
-wait age
-risk and review boundary
-estimated resource cost
-```
-
-Aging prevents low-priority Jobs from starving. Scheduled maintenance cannot continuously outrank a new user request.
-
-## 18. Preemption
-
-Default local work is non-preemptive once a Worker is actively writing. New higher-priority work waits or uses a Worktree.
-
-Preemption may cancel only when:
-
-- the Job contract declares it safe;
-- no external side effect is in an uncertain state;
-- a durable checkpoint exists;
-- cancellation evidence and cleanup are recorded.
-
-## 19. Release Freeze
-
-When a repository enters Release Freeze:
-
-- no new write Job is admitted for execution;
-- existing writers may finish or be explicitly cancelled;
-- Integration Queue must drain;
-- read-only inspection and release checks may continue;
-- Schedule Occurrences may triage but cannot dispatch mutation Jobs;
-- the release Lease is exclusive.
-
-The full release contract is defined in `verification-and-release-gates.md`.
-
-## 20. Implemented Runtime and Maintenance Rule
-
-The runtime now implements:
-
-- one repository-specific actor mailbox;
-- persisted Claims on every Execution Job;
-- renewable Leases with monotonically increasing fencing tokens;
-- conservative `repo-content:*` scope for unknown writes;
-- explicit waiting states for Workspace, Heavy Check, Integration, release and dependencies;
-- Workspace single-writer semantics and automatic Worktree placement for eligible Agent work;
-- exclusive Integration, Git-ref, remote and release resources;
-- global/per-repository capacity, provider quotas, Heavy Check limits and host-pressure admission;
-- persisted priority aging and repository fairness state;
-- owner-bound Worker heartbeat, Lease renewal, release and terminal writes.
-
-New concurrency features must express their resources through this model. Additional ad-hoc long-lived locks require an ADR and may not execute on the Gateway event loop.

package/docs/architecture/current/session-aware-execution-and-authorization.md

@@ -1,77 +0,0 @@
-# Session-Aware Execution and Authorization
-
-> Status: **Runtime Authority**
-
-## Scope
-
-Controller MCP execution is bound to a durable Session Context and Work Handle. A
-Work Handle is the execution binding for an existing WorkContract; it is not a
-second task lifecycle. The binding records repository, checkout/worktree, branch,
-Goal, principal, controller instance, and the captured permission revision.
-
-## Execution path
-
-```text
-MCP transport
-  -> Session Context
-     -> Work Handle + WorkContract
-        -> cheap/full validation
-           -> unified authorization decision
-              -> repository command or structured Git operation
-                 -> bounded result / resultRef + timing audit
-```
-
-Ordinary read, test, build, lint, format, local edit, and repository Git
-operations inside the active worktree are automatically allowed when Full Access
-is active. Request mode uses a GoalDelegation captured by `work_prepare` for the
-same session, repository, work, Goal, and permission revision. This removes
-per-command interruptions without creating a parallel policy engine.
-
-## Work preparation idempotency
-
-Creating new Work requires a stable `request_id`. Before a WorkContract or
-managed worktree is created, the Controller atomically persists a request record
-scoped to repository, authenticated session, and principal. The record binds a
-canonical preparation fingerprint to one Work id. Identical sequential,
-concurrent, or post-restart retries reuse that Work id and workspace. Reusing the
-same request id with different preparation parameters fails closed before any
-additional WorkContract, branch, checkout, or worktree is created.
-
-## Authorization boundary
-
-The unified decision is one of:
-
-- `allow`, with source `policy`, `full_access`, `goal_delegation`,
-  `gpt_risk_delegate`, or `user_confirmation`;
-- `user_confirmation_required`, with a durable `approvalRequestId`, exact
-  consequences, and a continuation that can be retried from the conversation;
-- `deny`, for example secret and credential access.
-
-Full Access does not authorize repository escape, secret access, destructive
-loss of existing user work, force push, remote publication, deployment, or
-other external side effects. A Goal delegation has the same hard boundaries.
-
-## Invalidation
-
-Delegation and approval state are invalid when any of these change: repository,
-work handle, Goal, principal/session, controlled worktree, command parameters,
-risk class, or permission revision. Controller instance changes explicitly
-invalidate persisted sessions so an old process cannot continue with stale
-authority.
-
-## Natural-language approval
-
-The Controller persists approval requests under repository-scoped Controller
-Home storage. `approval_resolve` records a confirmation from the current
-conversation; GUI approval is an optional projection, not the only continuation
-path. A resolved request may be retried only with the same identity, permission
-revision, and command parameters. Any incomplete approval response is an
-internal error: user-facing responses must contain a request id and continuation.
-
-## Compatibility and evidence
-
-Legacy stateless repository tools remain available. They use the same command
-classifier and authorization result, while composite execution tools provide
-session/work validation, idempotent finalization, bounded result references, and
-MCP timing records. Result references are Controller Home scoped to session,
-principal, repository, and optional work handle.