@moretea-labs/forge 1.5.0-rc.1

package/docs/architecture/current/verification-and-release-gates.md

@@ -0,0 +1,391 @@
+# Verification and Release Gates
+
+> Status: **Runtime Authority**
+
+## 1. Objective
+
+Verification determines whether evidence satisfies a declared contract for an exact repository state. Release gating determines whether the repository is ready for an externally visible delivery action.
+
+The system distinguishes:
+
+```text
+execution success
+integration success
+verification success
+Task acceptance
+Issue completion
+release readiness
+release execution
+```
+
+No step implies the next without its required evidence.
+
+## 2. Evidence Principles
+
+Evidence must be:
+
+- generated by the Controller or a trusted repository system;
+- bound to stable repository and checkout identity;
+- bound to an exact Revision or artifact hash;
+- addressable through a durable artifact reference;
+- bounded when returned to clients;
+- honest about failure, timeout, truncation, or missing data;
+- reusable only while its cache/precondition contract remains valid.
+
+Worker or Agent prose is supplementary evidence, not authoritative pass/fail proof.
+
+## 3. Verification Record
+
+A Verification Record contains:
+
+```text
+repoId
+checkoutId
+revision
+issueId / taskId
+runId / editSessionId / integrationId
+reviewedDiffHash
+checkResults
+commandEvidence
+acceptanceResults
+reviewer
+verifiedAt
+environmentFingerprint
+artifact references
+staleAt / staleReason when invalidated
+```
+
+A caller cannot satisfy required named checks by reporting `ok: true`. The Controller executes the check or verifies a trusted external artifact.
+
+## 4. Exact Revision
+
+Verification applies to one Revision definition, normally derived from:
+
+```text
+HEAD
+tracked working-tree diff
+relevant untracked files
+check configuration
+environment fingerprint
+```
+
+The Revision contract excludes known runtime-only evidence directories.
+
+If relevant files change after verification:
+
+- the previous record remains historical;
+- completion logic treats it as stale;
+- required verification runs again for the new Revision.
+
+## 5. Verification Layers
+
+### Layer 1 — Patch Integrity
+
+For Direct Edit or integration:
+
+- allowed paths respected;
+- before/after hashes recorded;
+- diff is available;
+- change budget respected;
+- no unsupported binary/rename behavior hidden;
+- user changes outside scope preserved.
+
+### Layer 2 — Focused Checks
+
+Run the smallest deterministic checks that directly cover the change.
+
+Examples:
+
+- one test file;
+- one package type check;
+- one domain test suite;
+- one architecture or documentation gate.
+
+### Layer 3 — Task Contract
+
+Evaluate all Task-declared checks and acceptance criteria.
+
+Acceptance criteria must be observable and must not merely repeat “implementation complete.”
+
+### Layer 4 — Integration Verification
+
+After an isolated Run is integrated:
+
+- verify target Revision, not only Worktree Revision;
+- verify integration record and reviewed diff hash;
+- rerun affected checks when target state changed;
+- retain Worktree until durable integration outcome exists.
+
+### Layer 5 — Issue or System Integration
+
+Run broader checks required by the Issue, architecture boundary, or affected runtime subsystem.
+
+### Layer 6 — Release Gate
+
+Run release-specific checks against a frozen candidate Revision.
+
+## 6. Risk-Adaptive Verification
+
+### Read-only
+
+Requires evidence of the requested observation. No diff gate.
+
+### Low-risk change
+
+Focused checks when declared; may auto-complete after successful applicable evidence.
+
+### Medium-risk change
+
+Declared checks and acceptance evidence apply. Auto-completion is allowed only when policy says no human decision is required.
+
+### High-risk change
+
+Requires:
+
+- reviewed diff or integrated Revision;
+- required verification evidence;
+- acceptance criteria results;
+- explicit human acceptance.
+
+### Destructive change
+
+Requires all high-risk evidence plus explicit same-request destructive authorization and operation-specific safety/rollback plan.
+
+## 7. Task Acceptance
+
+Task acceptance occurs after verification policy passes.
+
+Acceptance action records:
+
+```text
+acceptedBy
+acceptedAt
+verificationId
+revision
+note
+```
+
+Dependent Tasks unlock only from accepted terminal semantics, not from a successful Run alone.
+
+For eligible low/medium-risk work, Controller policy may auto-accept and records that automation explicitly.
+
+## 8. Failed Verification
+
+A real failed check or acceptance criterion moves work to `changes_requested` or a similarly explicit corrective state.
+
+Failure handling:
+
+1. preserve check output and artifact;
+2. classify failure as introduced, pre-existing, environmental, flaky, stale, or contract-related;
+3. avoid claiming unrelated pre-existing failure was caused or fixed;
+4. create a focused correction or blocker;
+5. rerun only the necessary evidence after the Revision changes.
+
+A flaky check requires explicit flake evidence and retry policy. Repeating until green without recording attempts is forbidden.
+
+## 9. Shared Check Evidence
+
+Identical check requests may share one execution when these match:
+
+```text
+repoId
+checkoutId
+checkId
+revision
+timeout contract
+environment fingerprint
+```
+
+Every subscriber links to the same immutable evidence. One subscriber cancellation must not terminate execution required by others.
+
+## 10. Release Readiness
+
+A repository is `release_ready` only when all required conditions are true for the candidate Revision.
+
+Baseline gate:
+
+```text
+repository identity valid
+remote/GitHub mapping diagnosed
+candidate Revision fixed
+Workspace ownership known
+no active write Job
+no active Agent Run
+no pending integration
+no unresolved integration conflict
+no dirty Edit Session
+no orphan/unknown execution affecting candidate
+required Tasks accepted
+required checks pass for candidate Revision
+architecture/document gates pass
+package/public metadata valid
+release manifest generated
+rollback or recovery plan recorded when required
+human authorization boundary identified
+```
+
+A project may add stricter repository-specific gates.
+
+## 11. Release Freeze
+
+Before final release verification, the Repo Actor acquires an exclusive release Claim and enters Release Freeze.
+
+During freeze:
+
+- new mutation Jobs wait;
+- active writers finish or are explicitly resolved;
+- Integration Queue drains;
+- read-only inspection continues;
+- release checks run against the fixed candidate;
+- Schedule mutation work pauses;
+- any relevant file change invalidates the candidate and requires a new gate.
+
+Release Freeze is released after:
+
+- release execution completes;
+- release is cancelled;
+- verification fails and the candidate returns to development;
+- Lease expires and recovery reconciles state.
+
+## 12. Release Manifest
+
+The release gate produces a durable manifest:
+
+```text
+repoId
+checkoutId
+candidateRevision
+branch
+target version or release identifier
+included Issues and Tasks
+verification records
+check artifact hashes
+known warnings
+known non-blocking pre-existing failures
+remote target
+release actions requiring authorization
+rollback/recovery instructions
+createdAt
+approvedBy / approvedAt when applicable
+```
+
+The manifest is an execution input and audit record. It does not execute release actions by itself.
+
+## 13. External Actions
+
+The following remain explicit external boundaries:
+
+- commit when user policy requires review;
+- push;
+- create/update remote PR when not already authorized by the Task;
+- merge;
+- tag;
+- package publication;
+- production deployment;
+- remote Issue closure;
+- destructive migration or data mutation.
+
+The Controller may prepare exact commands and evidence. It may execute only with explicit authorization appropriate to the operation.
+
+## 14. Release Job
+
+Release execution, when authorized, is a durable Job.
+
+It records:
+
+```text
+releaseManifestId
+requestId
+remote target
+operation sequence
+current step
+external identifiers
+stdout/stderr/artifacts
+partial outcome
+compensation or resume instructions
+```
+
+A disconnected client does not make external outcome unknown if provider or command evidence can prove it. Otherwise the Release Job becomes orphaned/unknown and requires reconciliation before retry.
+
+## 15. Partial Release
+
+Multi-step or multi-repository release may end partially complete.
+
+Partial outcome records:
+
+- completed external actions;
+- failed or unstarted actions;
+- current deployed/published versions;
+- safe compensation options;
+- actions that require human decision.
+
+The system must not collapse partial release into success or rerun all actions blindly.
+
+## 16. Rollback and Recovery
+
+Rollback is not assumed universally safe.
+
+A release plan declares one of:
+
+```text
+reversible with deterministic rollback
+forward-fix preferred
+feature-flag disable
+provider-native rollback
+manual recovery only
+```
+
+Rollback itself is externally visible/destructive work and requires appropriate authorization and evidence.
+
+## 17. Architecture Gate
+
+Architecture-sensitive releases must pass:
+
+- current architecture document presence;
+- Runtime Authority marker;
+- historical document marker policy;
+- architecture drift check;
+- relevant ADR linkage;
+- migration roadmap update when target gaps change.
+
+Architecture documentation is part of the release contract, not an optional afterthought.
+
+## 18. Verification Performance
+
+Verification must remain proportional:
+
+- focused checks during iteration;
+- Task checks before acceptance;
+- broader Issue/system checks at integration boundaries;
+- full release gate once the candidate is frozen.
+
+Running the full release suite after every small patch wastes resources and increases queue contention. Running only focused checks before release is insufficient.
+
+Check results and revision-aware caches prevent unnecessary duplication without hiding stale evidence.
+
+## 19. Current Implementation
+
+Verification evidence is bound to Job, repository and exact Git revision with an environment fingerprint. Revision changes invalidate reusable evidence. Oversized result bodies are stored as Artifacts and only bounded previews are returned through Job status.
+
+Release readiness is implemented as a durable `release-gate` Job holding an exclusive `release:<repoId>` Lease. The Gate checks Workspace cleanliness, active Execution Jobs, Agent Runs, Local compatibility Jobs, pending Worktree integration, unfinished Edit Sessions, other Leases, active-Issue Tasks, exact-revision verification, repository remote identity, GitHub mapping, Canonical Forge Runtime readiness and package metadata.
+
+A successful Gate returns a release manifest for the exact current revision. Push, merge, publish, deploy and destructive external operations still require a separate explicit user authorization.
+
+## 20. Required Release Tests
+
+Runtime and release checks cover:
+
+- candidate revision changes invalidate evidence;
+- active writers block release;
+- pending Worktree integration blocks release;
+- dirty Edit Sessions block release;
+- remote and GitHub mapping drift block release;
+- release Lease blocks new writes;
+- a successful Gate does not execute an external side effect;
+- partial external outcomes never become global success.
+
+## 21. Immutable Check Definition Snapshot
+
+A scheduled check stores the normalized command, cwd, timeout, source, registry revision, and definition digest at admission time. Execution validates the digest and repository-relative cwd, then uses that snapshot even if another checkout or a later commit changes the check registry.
+
+The snapshot stabilizes check identity; the produced evidence is still bound to the revision observed when execution starts and becomes stale if repository content changes while the command runs. This prevents both `check not found` after checkout switching and accidental reuse of evidence from a different repository revision.

package/docs/architecture/decisions/20260801-controller-home-sqlite-state.md

@@ -0,0 +1,100 @@
+# Controller-home SQLite state authority
+
+Status: accepted, amended 2026-08-02, implemented for the Requirement control plane 2026-08-05
+Date: 2026-08-01
+Amended by: `20260802-requirement-centered-control-plane.md`
+
+## Decision
+
+Controller-owned mutable execution facts will converge on a SQLite database at
+`<durable-controller-home>/control-plane.sqlite`. The database is local to the
+Controller installation, never a repository worktree. It is the authority for
+migrated records; JSON files are import-only compatibility inputs, not a
+mirrored write target.
+
+The initial schema intentionally has one versioned record envelope rather than
+an ORM or a premature table per product concept:
+
+- `control_plane_records` has a namespace, scope, record key, schema version,
+  monotonic revision, JSON payload, and timestamps;
+- its primary key gives one atomic identity per durable fact;
+- `control_plane_audit` records each authoritative write or legacy import;
+- SQLite WAL, foreign-key enforcement, a busy timeout, and `BEGIN IMMEDIATE`
+  make cross-process writes serializable; and
+- `control_plane_schema` records schema migrations independently from payload
+  versions.
+
+The adapter uses Bun's bundled SQLite binding in the normal runtime and Node
+22's built-in SQLite fallback for the package launcher. No native npm module or
+ORM is introduced.
+
+## Authority boundaries
+
+| Data | Authority | Repository projection |
+| --- | --- | --- |
+| Execution sessions, Work handles, work-prepare idempotency claims, and WorkContracts | Controller-home SQLite as each namespace migrates | Legacy JSON is readable only for first import; it is never rewritten |
+| Leases, process receipts, Jobs, Runs, checks, and evidence | Existing controller-home stores until their named migration | Existing artifacts remain evidence/read compatibility sources |
+| Repository identity, checkout/worktree/branch/HEAD observations | Git plus the Controller repository registry | Never inferred from an Issue or handoff |
+| Requirement, ExecutionPlan, PlanStep, Work relationships and user-facing lifecycle | Controller-home SQLite after the Requirement namespace cutover defined by `20260802-requirement-centered-control-plane.md` | Legacy Issue/Task files import once; optional Git snapshots are one-way, revision-stamped exports and never runtime authority |
+| Accepted architecture decisions and operator-authored documentation | Git | Human-reviewable design/source material, never a runtime mutation log |
+| Secrets and credentials | External credential providers or OS-managed stores | Never stored in SQLite payloads, projections, receipts, or audit data |
+
+SQLite records are structured facts and bounded evidence references. Large logs,
+binary artifacts, and source diffs remain filesystem artifacts addressed by
+stable IDs and content/revision metadata.
+
+## Migration and rollback rules
+
+1. Read the SQLite record first. If it exists, ignore any legacy JSON changes.
+2. If no record exists, validate and import exactly one legacy JSON value in a
+   transaction. A malformed record fails closed and changes neither source.
+3. After import, all writes go only to SQLite. A projection can be regenerated
+   later, but cannot become a second mutation authority.
+4. Each namespace migrates independently with focused compatibility and crash
+   tests. Do not batch-migrate all controller directories.
+5. A failed payload/schema migration rolls back its transaction and preserves
+   the last known-good record. Downgrade readers must reject unknown required
+   versions rather than overwrite them.
+6. A reversible rollback means selecting the prior database backup or a
+   verified read-only JSON import path before a namespace cutover; it never
+   means replaying stale JSON on top of an existing SQLite row.
+
+## Rollout sequence
+
+1. Establish the durable SQLite envelope and migrate the execution session,
+   Work-handle, idempotent work-prepare, and WorkContract namespaces.
+2. Migrate process/check receipts and lease ownership, retaining exact Git
+   identity in every verification record.
+3. Migrate controller-owned Run, Job, and evidence indexes; keep append-only
+   artifacts outside the database.
+4. Migrate Requirement, versioned ExecutionPlan, PlanStep and Work relationships
+   using the accepted requirement-centered boundary. Import Issue/Task records
+   exactly once, switch reads to SQLite, and permit only one-way exports.
+5. Delete runtime Issue/Task writers and legacy status fallbacks after the
+   revision-stamped portfolio migration validates. Only then migrate optional
+   Campaign and plugin state that still has durable product value.
+
+Each phase requires focused concurrent-write, interrupted-write, legacy-import,
+restart, and stale-revision tests before the next namespace becomes
+authoritative.
+
+## Current implementation
+
+The Requirement control-plane cutover is complete. Execution sessions, Work
+handles, idempotent work-prepare claims, WorkContracts, Requirements,
+ExecutionPlans, PlanSteps, Work relationships, migration markers, revisions and
+audit continuity are mutable only through
+`<durable-controller-home>/control-plane.sqlite`.
+
+Repository Issue/Task JSON and Markdown, `currentIssue`, the legacy project
+board and task-ledger artifacts are frozen compatibility material. A missing
+SQLite record may consume its reviewed import source only during the named
+one-time migration transaction. Once a row exists, later repository changes are
+ignored. Compatibility reads are SQLite-derived and explicitly marked
+`deprecated`, `frozen` and `readOnly`.
+
+Offline exports are revision-stamped, one-way SQLite-to-filesystem snapshots.
+They cannot be written under `tasks/issues`, cannot be replayed into existing
+rows and are not a rollback mechanism. Post-cutover rollback accepts only a
+verified SQLite backup whose schema, integrity, audit continuity and entity
+relationships pass validation.

package/docs/architecture/decisions/20260803-canonical-skill-surface.md

@@ -0,0 +1,40 @@
+# Canonical Forge Skill Surface
+
+Status: accepted
+
+## Decision
+
+Forge exposes one host-discoverable skill: `forge`. CLI commands,
+controller actions, and workflow modes are routed by that canonical skill and are
+not installed as standalone skills.
+
+## Removed standalone entries
+
+The former command facades for planning, review, autoplan, ship, init, scaffold,
+migrate, upgrade, capability, architecture, handoff, deploy, repair, check, PRD,
+sprint, goal, GPT Pro setup, and GPT Pro consultation were duplicate discovery
+surfaces over existing CLI commands. The repo-local ChatGPT bridge and browser
+skills were also removed as standalone discovery entries; their durable safety
+and controller rules remain in the canonical skill, controller tool contracts,
+and ordinary documentation.
+
+## Why
+
+- A command alias is not an independent knowledge domain.
+- Overlapping descriptions make automatic skill routing less reliable.
+- ChatGPT Controller does not need a second skill registry or new MCP tools to
+  operate existing typed capabilities.
+- One canonical skill keeps Codex and Claude discovery predictable while the CLI
+  remains fully expressive.
+
+## Distribution
+
+`scripts/sync-codex-installed-copies.sh` installs the canonical skill and removes
+historical managed facade names from Codex and Claude skill roots. It does not
+create a new registry, resolver, background service, or MCP tool.
+
+## Reconsideration gate
+
+A new standalone skill requires evidence of a recurring failure that cannot be
+addressed through the canonical router, existing context/resources, or typed
+controller/plugin capabilities. Tool-count growth is not an acceptable default.

package/docs/architecture/decisions/20260803-release-identity-binding-and-exit-policy.md

@@ -0,0 +1,53 @@
+# ADR: Whole-Forge-Runtime Release Identity and Exit Policy
+
+- **Status:** Accepted and aligned with the Canonical Forge Runtime
+- **Date:** 2026-08-03; revised 2026-08-09
+- **Authority:** [`../current/runtime-architecture-simplification.md`](../current/runtime-architecture-simplification.md), [`../current/failure-recovery.md`](../current/failure-recovery.md)
+
+## Decision
+
+One immutable release identity binds the complete `forge-runtime` process and every bounded child it launches:
+
+```text
+ReleaseIdentityBinding {
+  releasePath
+  releaseId
+  releaseRevision
+  sourceCommit
+  cleanWorkspace
+}
+```
+
+Authority order is:
+
+1. `FORGE_RELEASE_*` binding injected by the active whole release;
+2. the immutable release `manifest.json`;
+3. an owning Git checkout only for explicit developer launches;
+4. never an ambient parent repository.
+
+The OS service manager starts and automatically restarts the single `forge-runtime` root process after unexpected process death. Module readiness failure does not create component restart authority. A release transition stops and starts the complete Runtime, verifies binary whole-Runtime readiness, and on failure restores the previous complete release together with its bound SQLite backup.
+
+Standalone Recovery remains independently installed. It may diagnose the service, repair the service definition or tunnel, and perform authorized offline whole-Runtime rollback when the primary Runtime cannot start. It never becomes a second scheduler, Gateway, state writer, or component owner.
+
+The immutable release carries every helper executable or library needed by those bounded children. This includes the Process/Check runners, Browser/Desktop helpers, external-plugin probe, and the matching CodeGraph Node executable, read-only sidecar, and compiled library tree. CodeGraph is invoked once per bounded context query by `forge-runtime`; it is not a daemon, service, recovery owner, readiness authority, or persistent state writer. Its only durable input is the repository-owned `.codegraph/` index selected for the request.
+
+The CodeGraph artifact group is all-or-nothing in `manifest.json`: canonical co-located paths and SHA-256 identities are declared for the Node executable, sidecar, and library directory. A missing platform bundle fails release staging before publication. At runtime, an unavailable or failed structural query produces typed degraded context evidence and fails a mode's required-context condition; it does not create a second Runtime readiness state or restart authority.
+
+CodeGraph child cleanup is owned by the initiating bounded query through timeout/exit handling. Release retention and deletion operate on the complete release directory, so the executable, sidecar, and library tree are removed only with their whole Runtime release. There is no component-level upgrade, fallback to an ambient checkout dependency, adoption, or independent rollback path.
+
+## Exit policy
+
+- explicit authorized stop remains stopped;
+- unexpected root-process death is handled by the OS service manager;
+- incomplete readiness is reported as degraded or failed whole-Runtime readiness;
+- stale Workers cannot renew Leases or publish under a replacement Runtime/release fence;
+- uncertain external writes are reconciled from receipts and are never replayed blindly.
+
+## Verification
+
+- immutable release identity never follows ambient Git HEAD;
+- advancing a developer checkout cannot alter the active release identity;
+- failed activation restores the previous release and matching SQLite backup;
+- service restart preserves durable Work, Process and evidence identities;
+- a release missing any CodeGraph artifact fails closed before activation, a bounded query times out or exits without leaving a child owner, and a complete previous-release rollback restores the matching CodeGraph artifact group;
+- no component-level restart, slot selection, ingress fallback or Supervisor authority exists.

package/docs/architecture/diagrams/.gitkeep

@@ -0,0 +1 @@
+