@moretea-labs/forge 1.5.0-rc.1

package/docs/architecture/current/automation-and-schedule-engine.md

@@ -0,0 +1,453 @@
+# Automation and Schedule Engine
+
+> Status: **Runtime Authority**
+
+## 1. Objective
+
+The Schedule Engine enables recurring discovery, repair, verification, reporting, and release-readiness workflows without creating an unbounded autonomous Agent.
+
+The central rule is:
+
+> A Schedule is policy. An Occurrence is one bounded execution window.
+
+The system must be able to conclude that nothing should be done.
+
+## 2. Non-Goals
+
+The Schedule Engine is not:
+
+- a forever-running Agent process;
+- permission to bypass repository conflict rules;
+- permission to create unlimited Issues;
+- permission to auto-publish or deploy;
+- a replacement for repository-owned CI;
+- an excuse to retry external failures indefinitely;
+- a global lock across selected repositories.
+
+## 3. Schedule Entity
+
+A Schedule stores:
+
+```text
+scheduleId
+title
+enabled
+repositorySelector or portfolioSelector
+trigger
+workTemplate
+triagePolicy
+executionPolicy
+budget
+retryPolicy
+backoffPolicy
+notificationPolicy
+stopConditions
+createdBy
+createdAt
+updatedAt
+```
+
+### Trigger Types
+
+Implemented trigger classes:
+
+- fixed interval;
+- cron/calendar expression;
+- condition watch;
+- repository event;
+- dependency checkpoint;
+- manual run-now.
+
+Trigger delivery creates an Occurrence request. It does not directly start an Agent.
+
+## 4. Occurrence Identity
+
+One trigger window produces at most one Occurrence per repository.
+
+```text
+occurrenceKey = scheduleId + repoId + normalizedWindow
+requestId = occurrenceKey
+```
+
+The normalized window is deterministic for the trigger type. Repeated delivery, reconnect, or scheduler restart returns the same Occurrence.
+
+## 5. Occurrence State Machine
+
+```text
+created
+  -> triaging
+  -> nothing_to_do
+  -> candidate_recorded
+  -> waiting_for_resource
+  -> work_dispatched
+  -> verifying
+  -> completed
+
+created/triaging/waiting_for_resource/work_dispatched/verifying
+  -> failed
+  -> timed_out
+  -> budget_exhausted
+  -> human_attention_required
+  -> external_blocker
+  -> cancelled
+```
+
+An Occurrence reaches terminal state. A later trigger creates a new Occurrence rather than reviving the old one.
+
+## 6. Trigger Processing
+
+```text
+1. receive trigger delivery
+2. resolve selected repositories
+3. deduplicate occurrence window
+4. acquire short Schedule admission lock
+5. persist Occurrence
+6. submit repository-scoped triage command to Repo Actor
+7. release admission lock
+8. triage from compact snapshot
+9. persist Decision
+10. dispatch bounded Jobs or finish with no-op outcome
+```
+
+The trigger handler must return quickly and must not wait for implementation or checks.
+
+## 7. Triage Before Execution
+
+Every automated Occurrence begins with triage.
+
+Triage inputs should be bounded:
+
+```text
+repository health
+active Jobs and Runs
+current Issue/Task queue
+recent failed checks
+recent accepted work
+Git summary and dirty ownership
+release state
+existing Candidate Findings
+Schedule history and budget
+```
+
+Triage produces one normalized Decision:
+
+```text
+nothing_to_do
+continue_existing_task
+retry_infrastructure_failure
+create_candidate_finding
+promote_existing_finding
+run_readonly_check
+run_repair_task
+release_ready
+external_blocker
+human_attention_required
+```
+
+The Decision and evidence are persisted before any write Job is dispatched.
+
+## 8. Deterministic vs Agent Triage
+
+Deterministic rules are preferred for:
+
+- active conflict detection;
+- known failed checks;
+- stale/orphan reconciliation;
+- duplicate Issue or Finding detection;
+- budget and cooldown enforcement;
+- release gate status;
+- repository disabled/frozen state.
+
+An Agent may assist when semantic analysis is required, such as grouping related failures or proposing a bounded improvement. Its output remains a proposal evaluated by deterministic policy.
+
+## 9. Candidate Finding Governance
+
+Automation does not immediately convert every observation into an Issue.
+
+A Candidate Finding records:
+
+```text
+semanticKey
+category
+evidence
+confidence
+firstSeenAt
+lastSeenAt
+occurrenceCount
+existingIssueIds
+recommendedAction
+status
+```
+
+Promotion policy may require one or more:
+
+- reproducible failure;
+- named check failure;
+- explicit policy violation;
+- repeated observation across multiple Occurrences;
+- high-confidence static diagnosis with evidence;
+- user-configured auto-promotion category;
+- human approval.
+
+Speculative “could be improved” observations remain candidates and deduplicate by semantic key.
+
+## 10. Existing Work First
+
+Before creating new work, triage checks:
+
+1. Is an equivalent Issue active?
+2. Is an equivalent Task ready, running, under review, or blocked?
+3. Is an equivalent Job active?
+4. Did a recent terminal attempt fail and require explicit retry?
+5. Is the finding already resolved by the current Revision?
+6. Is another Schedule responsible for the same semantic key?
+
+Default priority is to continue or repair existing accepted work rather than create duplicates.
+
+## 11. Budget Contract
+
+Each Schedule defines bounded budgets, for example:
+
+```text
+maxActiveOccurrences
+maxJobsPerOccurrence
+maxAgentRunsPerOccurrence
+maxRetriesPerOccurrence
+maxWallClockPerOccurrence
+maxDailyWallClock
+maxDailyAgentRuns
+maxChangedFiles
+maxChangedLines
+optional token/cost budget
+```
+
+Budget is reserved before dispatch and settled from actual usage.
+
+Budget exhaustion is a valid terminal outcome. It may notify or defer to the next eligible window; it must not silently expand.
+
+## 12. Concurrency Policy
+
+Default:
+
+```text
+maxActiveOccurrences per schedule + repo = 1
+```
+
+If a trigger arrives while one is active:
+
+- return the existing Occurrence;
+- coalesce the trigger into a pending signal;
+- or skip according to Schedule policy.
+
+It must not create parallel duplicate loops.
+
+Cross-repository Schedules create independent repository Occurrences and use Global Scheduler fairness.
+
+## 13. Backoff and Cooldown
+
+Retry policy distinguishes failure classes.
+
+### Infrastructure failure
+
+May retry with bounded exponential backoff:
+
+```text
+baseDelay * 2^attempt, capped by maxDelay
+```
+
+### Scope or resource conflict
+
+Waits for resource or next eligibility; does not consume implementation retry count unless deadline expires.
+
+### Implementation or acceptance failure
+
+Creates or updates durable Task state and normally stops the Occurrence for review or a separately authorized retry.
+
+### External blocker
+
+Enters cooldown and notifies only when meaningful state changes or the configured reminder interval passes.
+
+### Repeated no-op
+
+May reduce frequency through quiet backoff when the Schedule repeatedly returns `nothing_to_do`.
+
+## 14. Stop Conditions
+
+A Schedule or Occurrence stops dispatching mutation work when any configured condition is true:
+
+```text
+release_ready
+human_review_required
+external_blocker
+budget_exhausted
+maximum_failures_reached
+repository_disabled
+release_freeze
+user_paused
+end_date or occurrence_count reached
+```
+
+A stop condition may disable the Schedule, pause it, or only terminate the current Occurrence according to policy.
+
+## 15. Dirty Workspace Policy
+
+Automation must not treat a dirty Workspace as disposable.
+
+Before mutation:
+
+- identify whether changes belong to an active Controller entity;
+- preserve unrelated user changes;
+- use a Worktree when isolation is safe;
+- otherwise record `human_attention_required` or wait.
+
+Automatic `git reset`, `git clean`, stash mutation, or overwrite is forbidden.
+
+## 16. Release Freeze Policy
+
+During Release Freeze:
+
+- read-only triage may run;
+- release checks may run;
+- Candidate Findings may be recorded;
+- new mutation Jobs are not dispatched;
+- existing approved release workflow continues according to the release contract.
+
+## 17. Notification Policy
+
+Schedules should be quiet by default.
+
+Notify on:
+
+- material progress;
+- new confirmed failure;
+- external blocker requiring action;
+- human review requirement;
+- release readiness;
+- budget exhaustion that changes expected outcome;
+- newly promoted Issue/Task.
+
+Do not notify repeatedly for unchanged no-op or unchanged blocker state.
+
+Every notification links to durable Occurrence, Job, Task, or Finding identities.
+
+## 18. Shadow Mode
+
+New mutation-capable Schedule policies should first run in Shadow Mode.
+
+Shadow Mode:
+
+- performs trigger, snapshot, triage, deduplication, budget, and policy decisions;
+- records what Jobs it would have dispatched;
+- does not create mutation Jobs;
+- may run explicitly safe read-only checks;
+- produces divergence and usefulness reports.
+
+Recommended graduation evidence:
+
+- sufficient number of Occurrences or time window;
+- no critical unsafe dispatch decisions;
+- acceptable duplicate and false-positive rate;
+- useful human adoption of findings;
+- bounded cost and latency;
+- explicit user enablement.
+
+## 19. Schedule Types
+
+### Health and Availability Watch
+
+Checks Controller/Gateway/Worker health and creates incidents only for confirmed changes.
+
+### Repair Loop
+
+Continues a known Issue through one bounded Task or retry per Occurrence until release-ready, blocked, or budget-exhausted.
+
+### Bug Discovery
+
+Runs deterministic scans and creates Candidate Findings. Promotion threshold should be strict.
+
+### Dependency or Release Watch
+
+Monitors an external condition and notifies or unlocks a Task when it changes.
+
+### Report Schedule
+
+Builds compact summaries without mutation.
+
+Each type uses the same Occurrence and Job model rather than a custom forever loop.
+
+## 20. Self-Improvement Limits
+
+A Schedule may propose changes to its own policy only as a Candidate Finding or Governance Issue. It cannot silently:
+
+- increase its budget;
+- shorten its interval;
+- broaden repository selection;
+- broaden write scope;
+- remove human stop conditions;
+- enable destructive or remote actions;
+- modify acceptance criteria to make itself pass.
+
+## 21. Recovery
+
+After Controller restart:
+
+1. reload enabled Schedules;
+2. rebuild active Occurrence index;
+3. deduplicate due trigger windows;
+4. reconcile active child Jobs;
+5. terminalize expired or orphaned Occurrences when appropriate;
+6. preserve completed Decisions and outcomes;
+7. resume only from durable boundaries.
+
+In-memory timers are delivery optimizations, not Schedule truth.
+
+## 22. Audit and Metrics
+
+Track:
+
+```text
+occurrences by outcome
+no-op rate
+candidate promotion rate
+duplicate suppression
+jobs and runs per occurrence
+retry classifications
+budget usage
+mean wait and execution time
+human adoption rate
+false-positive or rollback rate
+```
+
+The purpose is to remove unhelpful automation, not merely prove it is active.
+
+## 23. Current Implementation
+
+The runtime implements first-class `RepositorySchedule`, `ScheduleDecision` and `ScheduleOccurrence` records under `src/runtime/workflow/schedules/`. Supported triggers are interval, manual, five-field UTC cron, one-shot calendar timestamp, condition watch, repository event and dependency checkpoint.
+
+Every due trigger uses a deterministic window or event identity. The Decision is persisted before executable work is admitted. Occurrences are indexed, Shadow Mode defaults on, one Occurrence creates at most one durable Job, and repeated trigger delivery returns the existing Occurrence.
+
+Budgets, cooldown, maximum active Occurrences, consecutive-failure circuit breaking and exponential backoff are persisted. Dirty Workspaces, release barriers, repository disablement, human-attention state and recent external/infrastructure failures suppress unattended writes. Candidate Findings deduplicate observations and require explicit human promotion before Issue creation.
+
+The in-process Scheduler owned by the Canonical Runtime ticks timer/condition/dependency triggers and resumes from durable state after a whole-Runtime restart. Repository events and manual triggers enter through the same idempotent path. Worker and Reconciler settlement keep Job, Occurrence and Schedule failure state consistent.
+
+## 24. Safety Boundary
+
+Schedules may perform bounded repository work but cannot push, merge, publish, deploy, close remote Issues, remove repositories, or run arbitrary repository commands. The policy is checked at creation and again in the Worker.
+
+## 25. Rollout Rule
+
+New mutation Schedules begin in Shadow Mode until their decisions are reviewed. This is an operational rollout rule, not an implementation gap.
+
+## 26. ChatGPT-Supervised Campaigns
+
+Campaigns complement Schedules. A Schedule answers *when should a bounded occurrence run*; a Campaign answers *how should a multi-step goal progress across many bounded Jobs and review checkpoints*.
+
+Campaign reconciliation is event-driven and restart-safe. It uses short per-Campaign mutations, deterministic child request IDs, persisted retry timestamps, bounded parallelism, and the existing global scheduler/resource-claim system. It does not hold locks while ChatGPT, Codex, browser automation, or a human is working.
+
+A failed task blocks only descendants in the Campaign DAG. Independent tasks remain dispatchable. Pull-mode Supervisor waiting creates no periodic write loop. Agent operations force worktree isolation while preserving the executor's normal engineering and Computer Use capabilities.
+
+Campaigns stop at `ready_for_human_acceptance`; remote merge, publish, deploy, and release authority remain outside the autonomous loop.
+
+### Campaign workspace hierarchy
+
+A supervised Campaign defaults to a deterministic long-lived feature worktree. Its checkout identity is persisted on the Campaign and copied to every child ExecutionJob. Agent Runs may create short-lived task worktrees, but their automatic integration target is the Campaign checkout, never the repository's unrelated active checkout. Human acceptance does not merge or remove the Campaign worktree.

package/docs/architecture/current/codegraph-context-provider.md

@@ -0,0 +1,226 @@
+# CodeGraph Context Provider
+
+Status: reviewed for Phase 1 implementation  
+Source baseline: `a49465096c4e2532da37ab2f9d10dca2238217ac`  
+Scope: Controller Context Plane only
+
+## Problem
+
+Forge already installs and diagnoses `@colbymchenry/codegraph`, and the repository already has a local `.codegraph/codegraph.db`. However, ChatGPT/Controller planning still relies on token search plus bounded raw file reads. CodeGraph is not available as a policy-bounded Controller read capability, so `-plan` and `-debug` cannot use symbol, call-graph, dependency, or impact data directly.
+
+The missing capability is not another top-level MCP tool. It is a Context Plane provider that can add structural evidence to the existing `rh_context` / `controller_context_pack` path.
+
+## Constraints
+
+1. The default workflow remains unchanged. No explicit mode directive still uses the existing automatic Direct-first routing.
+2. `-plan`, `-debug`, and `-campaign` are opt-in routing instructions. CodeGraph must not add latency to ordinary Direct edits by default.
+3. Forge continues to support Node.js `>=20.10.0`.
+4. CodeGraph's embedded SDK requires Node.js `>=22.5` to open its SQLite database through `node:sqlite`.
+5. CodeGraph's CLI/MCP server uses its own bundled runtime and may auto-sync the index. Planning must not silently mutate source files or silently refresh derived indexes.
+6. Source reads remain governed by the existing repository/path policy. A graph hit is discovery evidence, not permission to read a denied path.
+7. The existing five facade tools remain the preferred host surface. Do not add a `codegraph_*` top-level Forge tool family.
+8. If CodeGraph is absent, stale, incompatible, or unavailable, Context Pack must fail open to the existing bounded text search when structural context is optional, and fail clearly when structural context was explicitly required.
+
+## Decision
+
+Add a `CodeGraphReadProvider` to the Context Plane, backed by a self-contained CodeGraph sidecar running on CodeGraph's bundled Node runtime.
+
+The Forge Controller process never imports and opens CodeGraph directly on Node 20. Instead it launches a small packaged sidecar with the matching platform bundle runtime and communicates through a bounded JSON protocol.
+
+The sidecar opens CodeGraph with:
+
+```text
+CodeGraph.open(projectRoot, { sync: false, readOnly: true })
+```
+
+It never calls:
+
+- `init` / `initSync`
+- `indexAll` / `indexFiles`
+- `sync`
+- `watch`
+- `optimize`
+- `clear`
+- `uninitialize`
+
+This keeps structural planning read-only with respect to both the repository and the derived CodeGraph index.
+
+## Runtime layout
+
+```text
+ChatGPT
+  -> rh_context / controller_context_pack
+  -> Context Pack builder
+       -> bounded text search + raw repository reads
+       -> CodeGraphReadProvider (only when requested)
+            -> CodeGraph sidecar
+                 -> bundled CodeGraph Node runtime
+                 -> CodeGraph.open(... readOnly=true, sync=false)
+                 -> .codegraph/codegraph.db
+```
+
+The sidecar is a provider implementation detail. It is not a second Forge Runtime and does not own Controller state, Work, scheduling, repository mutation, or recovery.
+
+## Provider contract
+
+Phase 1 provider operations:
+
+- `status`
+  - initialized
+  - provider/runtime availability
+  - index last indexed time
+  - index build version/extraction version
+  - stale-engine signal
+  - changed-file signal from CodeGraph when available
+- `search`
+  - symbol/name search
+  - bounded node metadata only
+- `context`
+  - task/query relevant subgraph via CodeGraph structural context
+  - bounded nodes and edges
+- `impact`
+  - impact radius from a resolved node
+- `file_dependencies`
+  - dependencies and dependents for explicit files
+
+Later operations may add callers/callees/usages and affected-test calculation, but Phase 1 should not expand before the Context Pack integration is proven useful.
+
+Every request includes the canonical repository root chosen by Repository Registry. The sidecar must reject attempts to substitute an arbitrary root after startup.
+
+## Context Pack integration
+
+Extend `ControllerContextPackOptions` with a structural context policy:
+
+```text
+structuralContext = off | auto | required
+```
+
+Default is `off` to preserve current Direct performance and behavior.
+
+Expected mode usage:
+
+- ordinary Direct: `off`
+- explicit `-debug`: `auto`
+- explicit `-plan`: `required` when a CodeGraph index is present; otherwise return a clear degraded-plan warning and use bounded text search
+- Campaign planning/review: `auto` or `required` depending on the campaign contract
+
+When enabled, graph results augment candidate ranking. They do not replace raw source reads. Important files selected through CodeGraph still pass through `resolveMcpPath` and `readRepositoryRange` before implementation.
+
+Context Pack gains a bounded `structuralContext` section containing:
+
+- provider: `codegraph`
+- requested mode
+- status: `ready | unavailable | stale | degraded`
+- index freshness/build metadata
+- query terms used
+- selected structural entry points
+- related/impact file paths
+- graph truncation metadata
+- fallback reason when graph data was not used
+
+Candidate reasons should distinguish graph evidence, for example:
+
+- `codegraph:search:<symbol>`
+- `codegraph:context`
+- `codegraph:impact:<node-id>`
+- `codegraph:dependent:<path>`
+
+## Freshness policy
+
+Read-only planning never auto-syncs CodeGraph.
+
+If the provider reports changed files, stale extraction, or an index built by an older extraction engine:
+
+1. mark structural context stale/degraded;
+2. do not silently run `sync` or `index`;
+3. use direct repository reads for affected files;
+4. optionally recommend an explicit CodeGraph refresh action outside the read-only planning step.
+
+A later typed maintenance action may perform refresh. That action is separate from planning and may write only derived `.codegraph` state, never source files.
+
+## Packaging and platform behavior
+
+The provider locates the matching optional platform package:
+
+```text
+@colbymchenry/codegraph-<platform>-<arch>
+```
+
+and uses its bundled `node` / `node.exe` to launch the packaged sidecar.
+
+If the platform package is missing, provider status is `unavailable` with remediation to reinstall CodeGraph with optional dependencies enabled. Forge must remain usable without CodeGraph.
+
+The sidecar code ships inside Forge's existing published `src/` or `scripts/` package surface; no new external service or daemon is required for Phase 1.
+
+## Security and policy
+
+- Structural queries are repository-scoped and read-only.
+- Sidecar stdin accepts typed JSON requests, not shell commands.
+- Sidecar output is bounded before returning to the host.
+- Telemetry is disabled for provider subprocesses (`CODEGRAPH_TELEMETRY=0`, `DO_NOT_TRACK=1`).
+- No network capability is required.
+- No arbitrary executable path is accepted from the user.
+- No arbitrary repository root is accepted from the user after Controller selection.
+- Graph-selected paths are rechecked through Forge read policy before raw code is returned.
+- Errors return bounded diagnostics and never dump database contents.
+
+## Performance policy
+
+Phase 1 uses an on-demand sidecar request path and records timing for:
+
+- process startup
+- CodeGraph open
+- graph query
+- Context Pack merge
+
+Do not introduce a persistent sidecar pool until measurements show startup/open dominates p95 planning latency. If pooling is later justified, use bounded per-repository LRU instances with explicit close/eviction and no file watcher.
+
+This avoids adding a new always-running process before benchmark evidence exists.
+
+## Phase 1 implementation steps
+
+1. Add the read-only sidecar and host provider with availability/freshness reporting.
+2. Add unit tests proving no mutation operations are exposed by the provider protocol.
+3. Add `structural_context` to `controller_context_pack`; default remains `off`.
+4. Merge CodeGraph structural candidates with existing text-search candidates while retaining policy checks and raw snippets.
+5. Update `SKILL.md` so explicit `-plan` requests structural context and explicit `-debug` prefers it when available. Do not change automatic Direct routing.
+6. Add focused tests for unavailable provider fallback, stale-index warnings, graph candidate ranking, denied-path rechecks, and output bounds.
+7. Run a live Forge CodeGraph query and record evidence before declaring CodeGraph integration ready.
+
+## Acceptance criteria
+
+Phase 1 is accepted only when all of the following are true:
+
+- Node.js 20.10 remains the public Forge baseline.
+- Default Direct workflow and Route Policy are unchanged.
+- `controller_context_pack` with no structural option performs no CodeGraph process work.
+- `structural_context=auto` degrades cleanly when CodeGraph is unavailable.
+- `structural_context=required` reports a clear blocker/degraded state instead of silently pretending structural evidence exists.
+- Sidecar opens the index read-only with sync disabled.
+- A query cannot invoke CodeGraph mutation APIs.
+- CodeGraph-selected files still obey Forge path policy before raw source is returned.
+- Context Pack output remains bounded.
+- Typecheck and targeted Context Pack/provider tests pass.
+- A real query against Forge's `.codegraph` index returns structural evidence.
+- No second Forge Runtime, rollout slot, or hidden managed browser/process authority is introduced.
+
+## Architecture review
+
+Review result: approved for Phase 1.
+
+Reasons:
+
+- Reuses the existing Context Plane instead of widening the top-level tool surface.
+- Preserves the Node 20 public contract by isolating the SDK runtime requirement.
+- Separates derived-index maintenance from read-only planning.
+- Keeps Direct fast by making structural context opt-in.
+- Preserves Forge path policy as the final authority for raw code access.
+- Provides a measurable migration path: on-demand sidecar first, pooling only after benchmark evidence.
+
+Rejected alternatives:
+
+1. Import CodeGraph directly into Controller: rejected because it raises the effective Node runtime requirement to 22.5+.
+2. Use `codegraph serve --mcp` directly for Plan reads: rejected for Phase 1 because its normal lifecycle includes connect-time catch-up and watcher/auto-sync behavior, which blurs the read-only planning boundary.
+3. Add new Forge top-level `codegraph_*` MCP tools: rejected because the existing five-facade architecture should remain the preferred host surface.
+4. Parse CodeGraph CLI human-readable output: rejected because the SDK provides a typed API and CLI text is a weaker protocol contract.
+5. Auto-sync before every Plan: rejected because derived-state mutation must be explicit and should not inflate planning latency without evidence.