@moretea-labs/forge 1.5.0-rc.1 → 1.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +9 -11
- package/CHANGELOG.md +27 -1
- package/CLAUDE.md +8 -10
- package/DESIGN.md +278 -0
- package/README.md +70 -90
- package/README.zh-CN.md +52 -55
- package/SKILL.md +8 -11
- package/THIRD_PARTY_NOTICES.md +9 -3
- package/assets/branding/README.md +4 -2
- package/assets/hooks/lib/workflow-state.sh +19 -18
- package/assets/hooks/post-edit-guard.sh +6 -75
- package/assets/hooks/prompt-guard.sh +24 -12
- package/assets/hooks/session-start-context.sh +17 -17
- package/assets/hooks/stop-orchestrator.sh +2 -2
- package/assets/partials/04-project-structure.partial.md +6 -6
- package/assets/partials/05-workflow.partial.md +6 -6
- package/assets/partials/07-footer.partial.md +1 -1
- package/assets/partials/08-orchestration.partial.md +2 -2
- package/assets/partials-agents/02-operating-mode.partial.md +5 -5
- package/assets/partials-agents/03-orchestration.partial.md +3 -3
- package/assets/partials-agents/04-task-protocol.partial.md +3 -3
- package/assets/partials-agents/08-deep-docs.partial.md +1 -1
- package/assets/reference-configs/agentic-development-flow.md +49 -86
- package/assets/reference-configs/external-tooling.md +21 -61
- package/assets/reference-configs/handoff-protocol.md +25 -20
- package/assets/reference-configs/harness-overview.md +8 -8
- package/assets/skill-version.json +2 -2
- package/assets/templates/helpers/archive-workflow.sh +0 -1
- package/assets/templates/helpers/capture-plan.sh +3 -3
- package/assets/templates/helpers/check-task-workflow.sh +2 -2
- package/assets/templates/helpers/codex-handoff-resume.sh +5 -5
- package/assets/templates/helpers/ensure-task-workflow.sh +37 -35
- package/assets/templates/helpers/new-plan.sh +1 -1
- package/assets/templates/helpers/plan-to-todo.sh +2 -2
- package/assets/templates/helpers/prepare-codex-handoff.sh +2 -2
- package/assets/templates/helpers/prepare-handoff.sh +9 -9
- package/assets/templates/helpers/refresh-current-status.sh +2 -2
- package/assets/templates/helpers/ship-worktrees.sh +1 -1
- package/assets/templates/helpers/sprint-backlog.sh +1 -1
- package/assets/templates/helpers/verify-sprint.sh +7 -7
- package/assets/templates/helpers/workstream-sync.sh +1 -1
- package/assets/templates/plan.template.md +1 -1
- package/assets/workflow-contract.v1.json +6 -3
- package/docs/architecture/current/README.md +10 -9
- package/docs/architecture/current/approved-target-architecture.zh-CN.md +2 -2
- package/docs/architecture/current/architecture-invariants.md +2 -2
- package/docs/architecture/current/automation-and-schedule-engine.md +15 -15
- package/docs/architecture/current/codegraph-context-provider.md +2 -2
- package/docs/architecture/current/control-plane-authority-inventory.md +12 -0
- package/docs/architecture/current/dispatch-and-agent-strategy.md +11 -11
- package/docs/architecture/current/entity-model.md +0 -27
- package/docs/architecture/current/failure-recovery.md +0 -24
- package/docs/architecture/current/governance.md +1 -1
- package/docs/architecture/current/implementation-status.md +1 -1
- package/docs/architecture/current/legacy-governance.md +58 -0
- package/docs/architecture/current/multi-repository-execution.md +1 -1
- package/docs/architecture/current/peer-supercontroller-runtime.md +1 -1
- package/docs/architecture/current/personal-assistant-plugin-baseline.md +4 -5
- package/docs/architecture/current/scheduler-and-resource-claims.md +0 -10
- package/docs/architecture/current/target-requirements-traceability.md +2 -2
- package/docs/architecture/current/thin-harness-governance-policy.md +1 -1
- package/docs/architecture/current/thin-harness-v1.md +9 -11
- package/docs/architecture/domains/runtime-harness.md +1 -1
- package/docs/forge-autonomous-goal-loop.md +3 -1
- package/docs/forge-chatgpt-mcp-setup.md +67 -176
- package/docs/images/forge-banner-cn.svg +26 -1
- package/docs/images/forge-banner.svg +26 -1
- package/docs/operations/features.md +1 -1
- package/docs/operations/homebrew.md +3 -3
- package/docs/operations/mcp-tool-exposure.md +5 -5
- package/docs/operations/platform-support.md +45 -37
- package/docs/operations/platform-support.zh-CN.md +40 -38
- package/docs/operations/releasing.md +3 -3
- package/docs/operations/releasing.zh-CN.md +3 -3
- package/docs/operations/troubleshooting.md +11 -6
- package/docs/operations/troubleshooting.zh-CN.md +11 -6
- package/docs/public-usage-guide.md +28 -21
- package/docs/public-usage-guide.zh-CN.md +28 -21
- package/docs/tutorials/01-install-and-start.md +58 -35
- package/docs/tutorials/01-install-and-start.zh-CN.md +58 -35
- package/docs/tutorials/02-connect-chatgpt.md +118 -46
- package/docs/tutorials/02-connect-chatgpt.zh-CN.md +119 -45
- package/docs/wiki/Architecture.md +1 -1
- package/docs/wiki/Installation.md +2 -2
- package/docs/wiki/Quick-Start.md +1 -1
- package/docs/wiki/Work-Lifecycle.md +1 -1
- package/install.ps1 +4 -5
- package/install.sh +4 -6
- package/package.json +15 -5
- package/scripts/archive-workflow.sh +0 -1
- package/scripts/benchmark-thin-harness-mcp-e2e.ts +27 -14
- package/scripts/build-controller-ui.ts +28 -0
- package/scripts/capture-plan.sh +4 -4
- package/scripts/check-agent-tooling.sh +12 -1
- package/scripts/check-platform-support.mjs +2 -2
- package/scripts/check-public-docs.sh +16 -5
- package/scripts/check-release-readiness.sh +5 -11
- package/scripts/check-runtime-architecture.mjs +14 -22
- package/scripts/check-tarball-install-smoke.sh +3 -2
- package/scripts/check-task-workflow.sh +2 -2
- package/scripts/codex-handoff-resume.sh +5 -5
- package/scripts/create-project-dirs.sh +3 -3
- package/scripts/ensure-task-workflow.sh +45 -35
- package/scripts/init-project.sh +4 -4
- package/scripts/install-desktop-operator-registration.ts +2 -2
- package/scripts/lib/project-init-lib.sh +46 -44
- package/scripts/migrate-project-template.sh +7 -4
- package/scripts/new-plan.sh +1 -1
- package/scripts/plan-to-todo.sh +2 -2
- package/scripts/prepare-codex-handoff.sh +2 -2
- package/scripts/prepare-handoff.sh +9 -9
- package/scripts/refresh-current-status.sh +2 -2
- package/scripts/setup-plugins.sh +3 -3
- package/scripts/ship-worktrees.sh +1 -1
- package/scripts/sprint-backlog.sh +5 -5
- package/scripts/sync-codex-installed-copies.sh +2 -3
- package/scripts/verify-sprint.sh +7 -7
- package/scripts/workstream-sync.sh +1 -1
- package/src/cli/chatgpt-browser/bridge-extension.ts +1 -1
- package/src/cli/chatgpt-browser/bridge-provider.ts +29 -0
- package/src/cli/chatgpt-browser/file-policy.ts +3 -1
- package/src/cli/commands/chatgpt.ts +51 -0
- package/src/cli/commands/doctor.ts +1 -1
- package/src/cli/commands/init-hook.ts +213 -70
- package/src/cli/commands/init.ts +5 -6
- package/src/cli/commands/mcp.ts +31 -5
- package/src/cli/commands/runtime.ts +61 -8
- package/src/cli/commands/setup-profile.ts +472 -0
- package/src/cli/controller/check-runner.ts +20 -3
- package/src/cli/controller/codex-continuation.ts +4 -7
- package/src/cli/controller/context-pack.ts +118 -14
- package/src/cli/controller/operational-plan.ts +4 -4
- package/src/cli/controller/task-ledger.ts +10 -10
- package/src/cli/controller/work-mode.ts +6 -13
- package/src/cli/index.ts +14 -35
- package/src/cli/local-bridge/connector-freshness.ts +1 -1
- package/src/cli/local-bridge/console-assets.ts +17 -0
- package/src/cli/local-bridge/console-automations.ts +160 -0
- package/src/cli/local-bridge/dashboard.ts +8 -1303
- package/src/cli/local-bridge/facade-api.ts +16 -7
- package/src/cli/local-bridge/frontend/src/App.tsx +10 -0
- package/src/cli/local-bridge/frontend/src/components/Button.tsx +1 -0
- package/src/cli/local-bridge/frontend/src/components/DetailPane.tsx +3 -0
- package/src/cli/local-bridge/frontend/src/components/SearchField.tsx +1 -0
- package/src/cli/local-bridge/frontend/src/components/SectionHeader.tsx +1 -0
- package/src/cli/local-bridge/frontend/src/components/Segmented.tsx +1 -0
- package/src/cli/local-bridge/frontend/src/components/StatusText.tsx +3 -0
- package/src/cli/local-bridge/frontend/src/design/icons.tsx +11 -0
- package/src/cli/local-bridge/frontend/src/design/tokens.css +8 -0
- package/src/cli/local-bridge/frontend/src/features/automations/AutomationsView.tsx +3 -0
- package/src/cli/local-bridge/frontend/src/features/capabilities/CapabilitiesView.tsx +4 -0
- package/src/cli/local-bridge/frontend/src/features/overview/OverviewView.tsx +3 -0
- package/src/cli/local-bridge/frontend/src/features/repositories/RepositoriesView.tsx +2 -0
- package/src/cli/local-bridge/frontend/src/features/settings/SettingsView.tsx +2 -0
- package/src/cli/local-bridge/frontend/src/features/system/SystemView.tsx +2 -0
- package/src/cli/local-bridge/frontend/src/features/work/WorkView.tsx +3 -0
- package/src/cli/local-bridge/frontend/src/lib/api.ts +23 -0
- package/src/cli/local-bridge/frontend/src/lib/format.ts +4 -0
- package/src/cli/local-bridge/frontend/src/lib/routes.ts +7 -0
- package/src/cli/local-bridge/frontend/src/main.tsx +1 -0
- package/src/cli/local-bridge/frontend/src/shell/AppShell.tsx +1 -0
- package/src/cli/local-bridge/frontend/src/shell/CommandBar.tsx +2 -0
- package/src/cli/local-bridge/frontend/src/shell/Sidebar.tsx +3 -0
- package/src/cli/local-bridge/frontend/src/styles.css +12 -0
- package/src/cli/local-bridge/frontend/src/types.ts +14 -0
- package/src/cli/local-bridge/frontend/src/vite-env.d.ts +1 -0
- package/src/cli/local-bridge/frontend/vite.config.ts +27 -0
- package/src/cli/local-bridge/server.ts +45 -0
- package/src/cli/local-bridge/ui-dist/app.css +1 -0
- package/src/cli/local-bridge/ui-dist/app.js +11094 -0
- package/src/cli/mcp/auth.ts +2 -0
- package/src/cli/mcp/instructions.ts +3 -3
- package/src/cli/mcp/legacy-tool-service.ts +27 -23
- package/src/cli/mcp/multi-repository.ts +2 -0
- package/src/cli/mcp/policy.ts +7 -5
- package/src/cli/mcp/repository-tools.ts +53 -14
- package/src/cli/mcp/server.ts +5 -10
- package/src/cli/mcp/setup.ts +220 -276
- package/src/cli/mcp/tool-capability-cache.ts +1 -1
- package/src/cli/mcp/toolset-names.ts +1 -1
- package/src/cli/mcp/toolset.ts +0 -1
- package/src/cli/mcp/transports/http.ts +51 -4
- package/src/cli/repositories/branch-name-policy.ts +0 -7
- package/src/cli/repositories/controller-home.ts +110 -3
- package/src/cli/repositories/safe-patch.ts +1 -1
- package/src/cli/repositories/selected-path-actions.ts +26 -24
- package/src/core/adoption/gitignore-plan.ts +2 -3
- package/src/core/adoption/plan.ts +4 -1
- package/src/runtime/control-plane/execution/edit-validation-coordinator.ts +556 -0
- package/src/runtime/control-plane/execution/work-handle-store.ts +128 -1
- package/src/runtime/control-plane/execution/work-validation-reconciler.ts +277 -0
- package/src/runtime/control-plane/execution/work-verification-snapshot.ts +169 -0
- package/src/runtime/control-plane/facade/capability-registry.ts +0 -10
- package/src/runtime/control-plane/facade/handoff-inbox-store.ts +44 -25
- package/src/runtime/control-plane/facade/suggested-actions.ts +7 -1
- package/src/runtime/control-plane/facade/types.ts +0 -1
- package/src/runtime/control-plane/global-scheduler/scheduler.ts +30 -8
- package/src/runtime/control-plane/launcher/chatgpt-work-binding-store.ts +114 -0
- package/src/runtime/control-plane/launcher/chatgpt-work-continuation.ts +175 -0
- package/src/runtime/control-plane/launcher/launch-reservation-store.ts +161 -0
- package/src/runtime/control-plane/launcher/provider-mcp-bootstrap.ts +64 -0
- package/src/runtime/control-plane/launcher/thin-launcher.ts +117 -24
- package/src/runtime/control-plane/routing/route-policy.ts +14 -14
- package/src/runtime/control-plane/runtime-cleanup.ts +0 -1
- package/src/runtime/evidence/event-ledger.ts +1 -1
- package/src/runtime/{workflow/campaigns/workspace.ts → execution/managed-workspace.ts} +41 -43
- package/src/runtime/execution/process-runtime/check-facade.ts +6 -0
- package/src/runtime/execution/process-runtime/check-result.ts +45 -0
- package/src/runtime/execution/process-runtime/check-runner-sidecar.ts +42 -16
- package/src/runtime/execution/process-runtime/command-facade.ts +4 -2
- package/src/runtime/execution/process-runtime/gc.ts +1 -1
- package/src/runtime/execution/process-runtime/index.ts +3 -0
- package/src/runtime/execution/process-runtime/interactive-admission.ts +14 -5
- package/src/runtime/execution/process-runtime/persisted-check.ts +285 -0
- package/src/runtime/execution/process-runtime/resource-claims.ts +30 -0
- package/src/runtime/execution/process-runtime/runtime.ts +18 -1
- package/src/runtime/execution/process-runtime/store.ts +1 -19
- package/src/runtime/execution/process-runtime/types.ts +4 -0
- package/src/runtime/execution/thin-harness/execution-router.ts +0 -1
- package/src/runtime/execution/thin-harness/fast-executor.ts +1 -1
- package/src/runtime/execution/thin-harness/lightweight-lanes.ts +1 -2
- package/src/runtime/execution/thin-harness/types.ts +0 -1
- package/src/runtime/execution/workers/executor.ts +1 -1
- package/src/runtime/gateway/mcp/execution-tools.ts +1 -1
- package/src/runtime/gateway/mcp/persisted-check-process.ts +3 -255
- package/src/runtime/gateway/mcp/process-tools.ts +16 -3
- package/src/runtime/gateway/mcp/resource-policy.ts +0 -9
- package/src/runtime/gateway/mcp/router.ts +117 -182
- package/src/runtime/gateway/mcp/runtime-tools.ts +331 -409
- package/src/runtime/gateway/mcp/work-validation-reconciler.ts +1 -219
- package/src/runtime/plugins/browser-adapter.ts +5 -0
- package/src/runtime/plugins/desktop-operator-registration.ts +1 -1
- package/src/runtime/plugins/store.ts +14 -6
- package/src/runtime/plugins/types.ts +1 -1
- package/src/runtime/projections/materialized-view.ts +1 -23
- package/src/runtime/recovery/maintenance-executor.ts +9 -0
- package/src/runtime/resources/ownership.ts +0 -1
- package/src/runtime/root/gateway-adapter.ts +2 -0
- package/src/runtime/root/mcp-transport.ts +10 -2
- package/src/runtime/root/package-connector-service.ts +136 -0
- package/src/runtime/root/package-runtime-release.ts +161 -0
- package/src/runtime/root/package-runtime-service.ts +185 -0
- package/src/runtime/root/release-materialize.ts +19 -0
- package/src/runtime/root/runtime.ts +2 -1
- package/src/runtime/root/scheduler.ts +5 -0
- package/src/runtime/root/service.ts +18 -5
- package/src/runtime/standalone-recovery/core.ts +65 -16
- package/src/runtime/workflow/findings/store.ts +145 -106
- package/src/runtime/workflow/findings/types.ts +22 -0
- package/src/runtime/workflow/schedules/engine.ts +132 -2
- package/src/runtime/workflow/schedules/pending-activation.ts +139 -0
- package/src/runtime/workflow/schedules/work-continuation.ts +218 -0
- package/docs/CHANGELOG.md +0 -978
- package/docs/README.zh-CN.md +0 -58
- package/scripts/smoke-chatgpt-supervised-automation.ts +0 -208
- package/src/cli/commands/controller.ts +0 -680
- package/src/runtime/workflow/campaigns/cleanup.ts +0 -263
- package/src/runtime/workflow/campaigns/engine.ts +0 -112
- package/src/runtime/workflow/campaigns/normalize.ts +0 -100
- package/src/runtime/workflow/campaigns/review.ts +0 -315
- package/src/runtime/workflow/campaigns/store.ts +0 -526
- package/src/runtime/workflow/campaigns/supervisor.ts +0 -112
- package/src/runtime/workflow/campaigns/types.ts +0 -290
- /package/src/runtime/{workflow/campaigns → execution}/workspace-agent.ts +0 -0
|
@@ -66,14 +66,14 @@ search/read
|
|
|
66
66
|
-> inspect aggregate diff
|
|
67
67
|
-> focused checks
|
|
68
68
|
-> finalize or rollback
|
|
69
|
-
->
|
|
69
|
+
-> Work verification when linked
|
|
70
70
|
```
|
|
71
71
|
|
|
72
72
|
Direct Edit MUST use the same Workspace single-writer resource boundary as a Workspace Agent.
|
|
73
73
|
|
|
74
74
|
### 3.2 Quick Agent
|
|
75
75
|
|
|
76
|
-
Quick Agent is used when the objective is clear but implementation requires meaningful exploration or repeated local edit/test cycles, without needing a durable multi-
|
|
76
|
+
Quick Agent is used when the objective is clear but implementation requires meaningful exploration or repeated local edit/test cycles, without needing a durable multi-Work dependency graph.
|
|
77
77
|
|
|
78
78
|
Preferred characteristics:
|
|
79
79
|
|
|
@@ -84,11 +84,11 @@ Preferred characteristics:
|
|
|
84
84
|
- retry can replace the whole attempt;
|
|
85
85
|
- Agent autonomy provides clear value over Direct Edit.
|
|
86
86
|
|
|
87
|
-
Quick Agent work may
|
|
87
|
+
Quick Agent work may carry ephemeral diagnostic metadata, but Job and Run evidence remain durable.
|
|
88
88
|
|
|
89
|
-
### 3.3
|
|
89
|
+
### 3.3 Requirement, Plan, and Work
|
|
90
90
|
|
|
91
|
-
A durable
|
|
91
|
+
A durable Requirement/Plan/Work graph is required when work has one or more of:
|
|
92
92
|
|
|
93
93
|
- multiple independently verifiable objectives;
|
|
94
94
|
- dependencies or ordered migration phases;
|
|
@@ -101,7 +101,7 @@ A durable Issue/Task graph is required when work has one or more of:
|
|
|
101
101
|
- a need for review and recovery across multiple sessions;
|
|
102
102
|
- release or rollout coordination.
|
|
103
103
|
|
|
104
|
-
A durable
|
|
104
|
+
A durable Work contract is not ceremony. It owns bounded execution scope, dependencies, evidence, retry history, and completion receipts; Requirement owns user-visible intent and acceptance outcome.
|
|
105
105
|
|
|
106
106
|
## 4. Decision Order
|
|
107
107
|
|
|
@@ -111,7 +111,7 @@ The Controller applies this order:
|
|
|
111
111
|
1. Is the request read-only?
|
|
112
112
|
2. Can bounded Direct Edit safely satisfy it?
|
|
113
113
|
3. Is one scoped Agent attempt sufficient?
|
|
114
|
-
4. Does the work require
|
|
114
|
+
4. Does the work require durable Requirement/Plan/Work state?
|
|
115
115
|
5. Does it cross repositories or require a Schedule?
|
|
116
116
|
6. Does any external or destructive boundary require human authorization?
|
|
117
117
|
```
|
|
@@ -234,15 +234,15 @@ Response policy:
|
|
|
234
234
|
| Acceptance | Refine implementation, not the criteria unless product intent changed |
|
|
235
235
|
| Integration | Preserve Worktree; repair from current target state |
|
|
236
236
|
| Capability mismatch | Select a more suitable Agent/provider |
|
|
237
|
-
| Controller contract | Re-plan
|
|
237
|
+
| Controller contract | Re-plan Work before another Run |
|
|
238
238
|
|
|
239
|
-
## 8.
|
|
239
|
+
## 8. Work Execution Contract
|
|
240
240
|
|
|
241
241
|
Every Agent Run receives a generated contract containing:
|
|
242
242
|
|
|
243
243
|
```text
|
|
244
244
|
repository and checkout identity
|
|
245
|
-
|
|
245
|
+
Requirement and Work objective
|
|
246
246
|
current implementation context
|
|
247
247
|
allowed and forbidden paths
|
|
248
248
|
required outputs
|
|
@@ -347,7 +347,7 @@ The dispatch layer MUST avoid:
|
|
|
347
347
|
|
|
348
348
|
## 13. Current Implementation
|
|
349
349
|
|
|
350
|
-
The repository implements Direct Edit, Quick Agent and
|
|
350
|
+
The repository implements Direct Edit, Quick Agent and Requirement/Work assessment; runtime Agent selection; bounded Task scope; persistent Runs; Workspace/Worktree placement; and risk-adaptive verification.
|
|
351
351
|
|
|
352
352
|
The Thin Gateway keeps deterministic local commands on Direct Edit or Process Runtime paths. Agent dispatch is now an explicit external-Controller handoff; the Kernel no longer creates Execution Jobs for ordinary Agent launches. Work ownership, repository placement, and resource claims remain durable Controller state, while provider selection and model execution belong to the claimed external Controller.
|
|
353
353
|
|
|
@@ -577,21 +577,6 @@ Ephemeral Quick Agent Issue metadata may be cleaned after terminal completion, b
|
|
|
577
577
|
|
|
578
578
|
Runtime projections, expired Leases, caches, and disposable Worktrees may be removed after durable terminal evidence and cleanup records exist.
|
|
579
579
|
|
|
580
|
-
## ChatGPT-Supervised Campaign
|
|
581
|
-
|
|
582
|
-
A Campaign is a durable project-level objective that coordinates existing Tasks, Execution Jobs, Agent Runs, Evidence, and human acceptance without replacing their lifecycles.
|
|
583
|
-
|
|
584
|
-
- A Campaign has revisioned goals and a stable goal hash.
|
|
585
|
-
- A Campaign Task references one existing MCP operation and explicit dependencies.
|
|
586
|
-
- A Checkpoint is a persisted ChatGPT review boundary, not a running Job.
|
|
587
|
-
- A Supervisor Decision is bound to one checkpoint nonce and goal revision.
|
|
588
|
-
- `waiting_for_supervisor` holds no worker or resource lease.
|
|
589
|
-
- `ready_for_human_acceptance` is not completion; only explicit human acceptance transitions to `completed`.
|
|
590
|
-
|
|
591
|
-
Campaign records are repository-scoped. Execution remains delegated to the existing durable Job and Agent Run models.
|
|
592
|
-
|
|
593
|
-
A Campaign owns an immutable `workspace` binding containing mode, checkout id, branch, root, original base revision, and whether Forge manages the worktree. ExecutionJob workers must resolve `job.checkoutId`; falling back to the active checkout is an identity violation.
|
|
594
|
-
|
|
595
580
|
## 22. Structured Execution Outcome
|
|
596
581
|
|
|
597
582
|
A Job result and a Job failure are separate concepts. Durable execution records may contain all of the following independently:
|
|
@@ -605,15 +590,3 @@ error terminal workflow error when the Job did not succeed
|
|
|
605
590
|
```
|
|
606
591
|
|
|
607
592
|
Successful stdout is never stored in `error`. Compatibility Local Jobs project the durable Execution Job status, result, and structured outcome without becoming a second source of lifecycle truth.
|
|
608
|
-
|
|
609
|
-
## 23. Campaign Completion Outcome
|
|
610
|
-
|
|
611
|
-
A Campaign Task distinguishes an implementation change from an already-satisfied objective:
|
|
612
|
-
|
|
613
|
-
```text
|
|
614
|
-
succeeded completed with changes or a non-repository result
|
|
615
|
-
succeeded_no_change completed with a proven empty repository diff
|
|
616
|
-
failed_no_effect changes were required but the Run produced no diff
|
|
617
|
-
```
|
|
618
|
-
|
|
619
|
-
`requiresChanges` is part of Task intent. A no-change Task never opens a review solely because it completed, and it is never rescheduled after reaching a terminal no-change outcome. A Campaign whose Tasks are all `succeeded_no_change` or `skipped` becomes ready for human acceptance with `completionOutcome=already_satisfied`.
|
|
@@ -440,30 +440,6 @@ The Gateway does not infer execution failure from a disconnected request. Caller
|
|
|
440
440
|
- repository A recovery does not require locking repository B;
|
|
441
441
|
- bounded projections remain readable while Workers execute.
|
|
442
442
|
|
|
443
|
-
## Campaign Recovery
|
|
444
|
-
|
|
445
|
-
Campaign state survives Gateway, MCP, ChatGPT, scheduler, and worker restarts. Reconciliation treats persisted Execution Jobs and Agent Runs as the execution source of truth. Missing, orphaned, timed-out, or human-attention child work becomes a bounded Campaign task failure and may open a Supervisor Checkpoint.
|
|
446
|
-
|
|
447
|
-
No in-memory ChatGPT conversation is required for recovery. Duplicate review delivery and scheduler delivery are idempotent. A stale checkpoint nonce, stale goal revision, or conflicting request-ID reuse is rejected rather than replayed against newer state.
|
|
448
|
-
|
|
449
|
-
### Campaign checkout recovery
|
|
450
|
-
|
|
451
|
-
Campaign worktree identity is stored in Controller Home with its request id, branch, path, and original base revision. Repeated creation reuses this manifest and registered checkout even if the source checkout advances. A missing directory is reconstructed from the retained branch after stale Git worktree metadata is pruned.
|
|
452
|
-
|
|
453
|
-
## 25. Campaign Cancellation Finalizer
|
|
454
|
-
|
|
455
|
-
Campaign cancellation is a two-phase state transition:
|
|
456
|
-
|
|
457
|
-
```text
|
|
458
|
-
active / paused / waiting_for_supervisor
|
|
459
|
-
-> cancelling
|
|
460
|
-
-> cancelled | cancelled_with_leaks
|
|
461
|
-
```
|
|
462
|
-
|
|
463
|
-
Entering `cancelling` blocks new Task dispatch, supersedes open checkpoints, and marks non-terminal Tasks cancelled. The finalizer then cancels Task and Supervisor Execution Jobs, which terminate owned process trees and release Leases. A managed Campaign worktree is removed only when its path and branch identity match and the workspace is clean. Unknown, dirty, or committed resources are preserved and reported as leaks.
|
|
464
|
-
|
|
465
|
-
`cancelled` is written only after the cleanup report is durable. Cleanup is idempotent; a Campaign in `cancelled_with_leaks` may be reconciled again after an operator resolves the preserved resource.
|
|
466
|
-
|
|
467
443
|
## 26. Runtime Storage Recovery
|
|
468
444
|
|
|
469
445
|
Every Controller Home runtime directory carries a repository/binding owner marker. Empty or terminal legacy storage is migrated and replaced with a repository-local link. Non-conflicting entries are merged. Name collisions are moved to a repository-scoped quarantine with a diagnostic path rather than overwritten or deleted.
|
|
@@ -62,7 +62,7 @@ The normal ChatGPT-facing MCP surface is a bounded **19-tool** schema. The five
|
|
|
62
62
|
|
|
63
63
|
The Runtime keeps internal atomic handlers and an exhaustive `full` compatibility profile without advertising them to ordinary ChatGPT discovery. `core` remains a compatibility label for the same bounded default surface. Request/Full Access changes execution authorization, not tool discovery.
|
|
64
64
|
|
|
65
|
-
Small understood work is Direct-first. Repository commands and checks use Unified Process Runtime and return one stable Process lifecycle; known-long calls can return a handle immediately, while later `process_get`, `process_wait`, `process_logs`, and `process_cancel` attach to that same physical execution. Durable Work, isolated worktrees,
|
|
65
|
+
Small understood work is Direct-first. Repository commands and checks use Unified Process Runtime and return one stable Process lifecycle; known-long calls can return a handle immediately, while later `process_get`, `process_wait`, `process_logs`, and `process_cancel` attach to that same physical execution. Durable Work, isolated worktrees, or workers are introduced when recovery, dependency tracking, isolation, parallelism, or a longer lifecycle actually requires them.
|
|
66
66
|
|
|
67
67
|
Tool names and input schemas are fingerprinted. A stale MCP session receives `MCP_TOOL_SURFACE_CHANGED` with a reinitialize instruction while its transport remains available for the host to observe the reset. Replacement initialize then supersedes and closes the old session; schema rotation must not unregister the Forge namespace from the host conversation.
|
|
68
68
|
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# Legacy Capability Governance
|
|
2
|
+
|
|
3
|
+
> Status: **Runtime Authority**
|
|
4
|
+
|
|
5
|
+
Forge is a direct descendant of RepoHarness. Provenance is historical fact, not a runtime compatibility requirement. Governance removes obsolete authorities and duplicate entrypoints while retaining implementations that still satisfy current invariants.
|
|
6
|
+
|
|
7
|
+
## Rule
|
|
8
|
+
|
|
9
|
+
A capability may survive from RepoHarness when it has one current owner, does not create a second lifecycle writer, and does not require an external Agent/skill for correctness. Code should be rewritten only when the old implementation violates those invariants; lineage alone is not a reason to rewrite working code.
|
|
10
|
+
|
|
11
|
+
## Capability disposition
|
|
12
|
+
|
|
13
|
+
| Capability | Disposition | Current authority |
|
|
14
|
+
|---|---|---|
|
|
15
|
+
| Plan/spec source artifacts | keep | Git source artifacts; Runtime Plan/Work owns migrated lifecycle state |
|
|
16
|
+
| Contract/check/review evidence | keep and bound | Git/evidence plane; completion policy evaluates evidence |
|
|
17
|
+
| Repository/process/worktree execution | replace legacy orchestration | Canonical Runtime, Process Runtime, Resource Claims/Leases |
|
|
18
|
+
| CodeGraph | internalize | `rh_context` + bundled structural backend; host MCP is optional |
|
|
19
|
+
| Hook adapters | keep thin | host event adapter only; never lifecycle owner |
|
|
20
|
+
| Session resume context | rename/demote | `.ai/harness/session/*` rebuildable cache only |
|
|
21
|
+
| Decision handoff | keep as Runtime object | `HandoffItem` surfaced through `rh_inbox` |
|
|
22
|
+
| Browser human-interaction handoff | keep separate | browser interaction policy; not Work/Plan handoff |
|
|
23
|
+
| Waza/gstack/gbrain/Mermaid | optional | external host enhancement only |
|
|
24
|
+
| Campaign | remove | no current authority |
|
|
25
|
+
| legacy Issue/Task/project writers | freeze/remove | migrated Requirement/Plan/Work state in SQLite |
|
|
26
|
+
| legacy helper/host commands | hide then delete when no managed callers remain | public CLI exposes product workflows only |
|
|
27
|
+
|
|
28
|
+
## Handoff terminology
|
|
29
|
+
|
|
30
|
+
Three historical concepts used the same word and must remain separated:
|
|
31
|
+
|
|
32
|
+
1. **Runtime HandoffItem** — a durable decision/attention item created for ambiguity, authorization, repeated infrastructure failure, or human review. This is the only generic Forge object called a handoff.
|
|
33
|
+
2. **Session continuation cache** — ignored Markdown under `.ai/harness/session/` used to rehydrate a fresh Codex/Claude session. It is derived, rebuildable, and cannot approve work or override Runtime state.
|
|
34
|
+
3. **Browser human-interaction handoff** — a bounded browser/UI interaction that needs a human (for example login/CAPTCHA). It is an interaction-plane event, not a repository lifecycle state.
|
|
35
|
+
|
|
36
|
+
Hooks may refresh (2). Hooks must never synthesize or resolve (1) by writing Markdown.
|
|
37
|
+
|
|
38
|
+
## CLI governance
|
|
39
|
+
|
|
40
|
+
Public top-level commands should describe user goals, not implementation layers.
|
|
41
|
+
|
|
42
|
+
Public: `install`, `update`, `adopt`, `uninstall`, `setup`, `status`, `doctor`, `repo`, `runtime`, `recovery`, `plugin`, `chatgpt`, `mcp`, `tools`, `security`, `docs`.
|
|
43
|
+
|
|
44
|
+
Hidden compatibility/host machinery may remain callable while generated workflows still use it: `hook`, `run`, legacy `controller`, `migrate`, `brain`, `capability-context`, and `prompt-guard-decide`.
|
|
45
|
+
|
|
46
|
+
`init` and `init-hook` are retired duplicate public entrypoints. Use `install` and `setup check` respectively.
|
|
47
|
+
|
|
48
|
+
## Removal policy
|
|
49
|
+
|
|
50
|
+
A hidden compatibility surface can be deleted when:
|
|
51
|
+
|
|
52
|
+
1. no current generated asset writes or documents it as a primary route;
|
|
53
|
+
2. no current Runtime/host adapter invokes it;
|
|
54
|
+
3. migration/readback coverage proves old persisted state has an explicit replacement or is intentionally abandoned;
|
|
55
|
+
4. focused tests and architecture checks prove the replacement path;
|
|
56
|
+
5. deletion does not recreate the capability under a new duplicate abstraction.
|
|
57
|
+
|
|
58
|
+
Historical Git commits, changelog entries, ADRs, and third-party notices are not rewritten merely to erase RepoHarness provenance.
|
|
@@ -20,7 +20,7 @@ Status: active on `codex/supercontroller-refactor`
|
|
|
20
20
|
## Semantic / external paths
|
|
21
21
|
|
|
22
22
|
- Non-deterministic schedules record occurrence + Handoff only
|
|
23
|
-
-
|
|
23
|
+
- Long-lived work persists as Work + Handoff and can be resumed by an external SuperController
|
|
24
24
|
- Legacy Agent dispatch tools return structured retirement responses
|
|
25
25
|
|
|
26
26
|
## Failure policy
|
|
@@ -18,7 +18,7 @@ Current implementation:
|
|
|
18
18
|
adapters under `src/runtime/plugins/`, all surfaced through Controller CLI,
|
|
19
19
|
Local Bridge APIs, and MCP compatibility tools.
|
|
20
20
|
- ChatGPT browser automation exists under `src/cli/chatgpt-browser/` and the
|
|
21
|
-
|
|
21
|
+
runtime control plane. It is an execution channel, not a plugin
|
|
22
22
|
registry entry.
|
|
23
23
|
- Calendar support exists both as a runtime Schedule trigger under
|
|
24
24
|
`src/runtime/workflow/schedules/` and as a separate Google Calendar account
|
|
@@ -43,7 +43,7 @@ Compatibility rule:
|
|
|
43
43
|
ChatGPT / Local UI / CLI
|
|
44
44
|
-> MCP Gateway + Local Bridge
|
|
45
45
|
-> Controller Runtime
|
|
46
|
-
-> durable Jobs /
|
|
46
|
+
-> durable Jobs / Goal/Work / schedules / evidence
|
|
47
47
|
-> optional provider adapters
|
|
48
48
|
-> GitHub plugin (implemented)
|
|
49
49
|
-> Gmail adapter (implemented)
|
|
@@ -61,9 +61,8 @@ operations on top of that runtime, not as a second orchestrator.
|
|
|
61
61
|
|
|
62
62
|
| Capability | Source of truth | Persistence and boundary | External side effect | Status |
|
|
63
63
|
| --- | --- | --- | --- | --- |
|
|
64
|
-
| GitHub Issue/Project sync | `src/cli/github/plugin.ts`, `src/cli/
|
|
64
|
+
| GitHub Issue/Project sync | `src/cli/github/plugin.ts`, `src/cli/local-bridge/server.ts` | `.Forge/plugins/github.json` plus repository registry mapping | GitHub issue/project mutation | Implemented |
|
|
65
65
|
| Durable assistant work submission | `src/runtime/gateway/mcp/runtime-tools.ts`, `src/runtime/execution/jobs/` | Controller Home `execution-jobs/`, events, artifacts, projections | Repository-local work and approved provider actions | Implemented |
|
|
66
|
-
| ChatGPT-supervised campaigns | `src/runtime/workflow/campaigns/`, `src/cli/chatgpt-browser/` | Campaign records, review packets, workspaces, evidence | Browser-visible ChatGPT session or delegated local work | Implemented and opt-in |
|
|
67
66
|
| Calendar time-based triggering | `src/runtime/workflow/schedules/store.ts`, `engine.ts` | Schedule, Decision, Occurrence records | Launches bounded runtime Jobs only | Implemented |
|
|
68
67
|
| Calendar account read/write | `src/runtime/plugins/google-calendar-adapter.ts` | `.Forge/plugins/google-calendar.json`, derived manifest/index, env-only credentials | Google Calendar event read/write | Implemented |
|
|
69
68
|
| Gmail mailbox read/write | `src/runtime/plugins/gmail-adapter.ts` | `.Forge/plugins/gmail.json`, derived manifest/index, env-only credentials | Gmail read/send/trash | Implemented |
|
|
@@ -155,7 +154,7 @@ Current implementation:
|
|
|
155
154
|
|
|
156
155
|
The current source-aligned assistant baseline is:
|
|
157
156
|
|
|
158
|
-
- Controller Runtime plus durable Jobs/
|
|
157
|
+
- Controller Runtime plus durable Jobs/Goal/Work/schedules are the assistant
|
|
159
158
|
execution substrate.
|
|
160
159
|
- GitHub, Gmail, Google Calendar, and Google Tasks are implemented persisted
|
|
161
160
|
plugin adapters behind the generic plugin runtime contract.
|
|
@@ -420,13 +420,3 @@ The runtime now implements:
|
|
|
420
420
|
- owner-bound Worker heartbeat, Lease renewal, release and terminal writes.
|
|
421
421
|
|
|
422
422
|
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.
|
|
423
|
-
|
|
424
|
-
## Campaign Scheduling
|
|
425
|
-
|
|
426
|
-
The global scheduler runs bounded Campaign reconciliation outside the global dispatch reservation lock. Campaigns use one short lock per Campaign identity, while child Jobs continue to use normal resource claims and fencing tokens. This prevents one slow review or failed task from serializing unrelated Campaigns or repositories.
|
|
427
|
-
|
|
428
|
-
Agent Campaign tasks are normalized to `isolate: true` and therefore claim a task worktree rather than the active production workspace. Waiting Checkpoints carry no lease. Retry timestamps are durable and include bounded backoff and jitter to avoid retry storms.
|
|
429
|
-
|
|
430
|
-
### Campaign creation claims
|
|
431
|
-
|
|
432
|
-
`create_campaign` briefly claims repository state and `git-refs:<repoId>` while creating or recovering the deterministic Campaign worktree. Normal Campaign reconciliation uses short per-Campaign locks. Supervisor triggers claim no repository resource, and implementation Jobs claim the Campaign checkout or a task-specific child worktree.
|
|
@@ -60,7 +60,7 @@ Verification: `tests/runtime/canonical-single-runtime.test.ts`, `scripts/smoke-m
|
|
|
60
60
|
|
|
61
61
|
## 5. Work-mode and Agent strategy
|
|
62
62
|
|
|
63
|
-
|
|
63
|
+
Direct Edit and Quick Agent remain available; historical Issue/Task assessment is compatibility/read-only after Requirement/Work cutover. Runtime dispatch persists the chosen operation and preserves allowed Agent providers, timeout and browser permissions. Explorer/Implementer/Verifier policy remains a planning concern; deterministic integration and release checks remain program-owned rather than LLM-owned.
|
|
64
64
|
|
|
65
65
|
Evidence: `src/cli/controller/work-mode.ts`, `src/runtime/gateway/mcp/router.ts`, `src/runtime/execution/workers/executor.ts`.
|
|
66
66
|
|
|
@@ -185,7 +185,7 @@ Detailed evidence: [`migration-roadmap.md`](migration-roadmap.md).
|
|
|
185
185
|
Resolve Repository
|
|
186
186
|
-> read compact projection
|
|
187
187
|
-> classify work mode
|
|
188
|
-
-> select/create
|
|
188
|
+
-> select/create Requirement and Work when required
|
|
189
189
|
-> declare Scope and Claims
|
|
190
190
|
-> persist requestId and ExecutionJob
|
|
191
191
|
-> return Job ID
|
|
@@ -14,7 +14,7 @@ Core principle:
|
|
|
14
14
|
Default to direct Fast Path execution.
|
|
15
15
|
Escalate to Durable Work only when recovery, background, isolation,
|
|
16
16
|
concurrent writes, or high-risk control is required.
|
|
17
|
-
Use
|
|
17
|
+
Use durable Goal Workloop plus PlanContract/Work only when multiple independent, long-lived deliverables need resumable coordination.
|
|
18
18
|
```
|
|
19
19
|
|
|
20
20
|
## Current Implementation
|
|
@@ -53,11 +53,11 @@ interface ExecutionDecision {
|
|
|
53
53
|
|
|
54
54
|
The sole Route Policy exposes three task-shape tiers. These are routing labels over existing execution primitives, not separate engines:
|
|
55
55
|
|
|
56
|
-
1. **Direct** — `direct_edit` + `direct_control` + `fast`. Use for small, scope-clear, low-risk work. Readonly work creates no Work; small mutations may retain lightweight Work lineage without Issue, Plan,
|
|
56
|
+
1. **Direct** — `direct_edit` + `direct_control` + `fast`. Use for small, scope-clear, low-risk work. Readonly work creates no Work; small mutations may retain lightweight Work lineage without Issue, Plan, or isolated worktree by default.
|
|
57
57
|
2. **Bounded Work** — `bounded_work` + `goal_workloop` + `durable`. Use for one-owner work that needs investigation, recovery, isolation, protected-path handling, or broader bounded scope. It uses the existing WorkContract / `rh_work` lifecycle and does **not** require an Issue or Plan.
|
|
58
|
-
3. **
|
|
58
|
+
3. **Coordinated durable Work** — `bounded_work` + `goal_workloop` + `durable`. Use when multiple independent deliverables need resumable coordination; decompose them with PlanContract/Work instead of a separate project-level lifecycle.
|
|
59
59
|
|
|
60
|
-
`quick_agent` and `issue_task` remain executor/delegation-oriented modes when an Agent is explicitly requested
|
|
60
|
+
`quick_agent` and `issue_task` remain executor/delegation-oriented modes when an Agent is explicitly requested. Provider choice never promotes a small task into a heavier lifecycle by itself. An explicit approved Plan may bind dependent Work steps, but Plan is optional for ordinary Bounded Work.
|
|
61
61
|
|
|
62
62
|
### Fast Path eligibility (default)
|
|
63
63
|
|
|
@@ -141,7 +141,6 @@ For short **typed-argv** readonly repository commands, the bounded direct reader
|
|
|
141
141
|
- Local Job
|
|
142
142
|
- Scheduler record
|
|
143
143
|
- Worker process
|
|
144
|
-
- Campaign state
|
|
145
144
|
- Issue Task
|
|
146
145
|
- Project Board records
|
|
147
146
|
- full projection rebuild per step
|
|
@@ -252,7 +251,7 @@ Rules:
|
|
|
252
251
|
### Read-only Analysis Lane
|
|
253
252
|
|
|
254
253
|
- max concurrency 4
|
|
255
|
-
- shared checkout, no branch / worktree / Issue
|
|
254
|
+
- shared checkout, no branch / worktree / Issue
|
|
256
255
|
- parent receipt only; child lanes use `receiptMode: none`
|
|
257
256
|
- real overlap via async primitives; `concurrent` flag reports start/finish overlap
|
|
258
257
|
- fail-fast optional (default continue)
|
|
@@ -264,12 +263,11 @@ Rules:
|
|
|
264
263
|
- never writes the main checkout
|
|
265
264
|
- Integrator rechecks revision, conflicts, writePaths subset, digests before apply
|
|
266
265
|
|
|
267
|
-
##
|
|
266
|
+
## Durable coordination boundary
|
|
268
267
|
|
|
269
|
-
- Fast Path never depends on
|
|
270
|
-
-
|
|
271
|
-
- ordinary Direct Edit must not auto-upgrade
|
|
272
|
-
- this slice does **not** rewrite Campaign completion, merge, cleanup, or workspace models
|
|
268
|
+
- Fast Path never depends on a project-level orchestration lifecycle.
|
|
269
|
+
- Independent deliverables use Goal Workloop plus PlanContract/Work only when durable coordination is needed.
|
|
270
|
+
- ordinary Direct Edit must not auto-upgrade merely because parallel analysis is possible.
|
|
273
271
|
|
|
274
272
|
## Latency measurement
|
|
275
273
|
|
|
@@ -19,7 +19,7 @@ instead of becoming separate hook sources of truth.
|
|
|
19
19
|
- User-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapter surfaces.
|
|
20
20
|
- Repo-local `.claude/settings.json` and `.codex/hooks.json` hook adapters are retired legacy config, not required contract files.
|
|
21
21
|
- Other repo-local `.codex/*` files are runtime residue unless promoted by an explicit contract change.
|
|
22
|
-
- Runtime files under `.ai/harness/checks`, `.ai/harness/
|
|
22
|
+
- Runtime files under `.ai/harness/checks`, `.ai/harness/session`, `.ai/harness/controller/packets`, `.ai/harness/projections`, `.ai/harness/transfers`, `.ai/harness/failures`, `.ai/harness/architecture/events.jsonl`, `.ai/harness/worktrees`, and `.ai/harness/runs` are ignored state, not durable deliverables.
|
|
23
23
|
|
|
24
24
|
## Verification Surface
|
|
25
25
|
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Forge supports bounded goal progression through durable Goal, Work, Process, evidence, policy, and handoff records. The kernel does not recursively invent unlimited work, select arbitrary models, or bypass authorization. Semantic planning and provider selection belong to the external controller; deterministic repository and provider operations remain Forge-owned.
|
|
4
4
|
|
|
5
|
-
Every continuation must have a finite objective, resource scope, budget, stop condition, and reviewable evidence. Remote or destructive effects stay separately authorized.
|
|
5
|
+
Every continuation must have a finite objective, resource scope, budget, stop condition, and reviewable evidence. Remote or destructive effects stay separately authorized. A Schedule can wake an external Controller for an existing bounded Work; ChatGPT wakeups reuse a saved Forge browser session or explicit conversation URL when available, so conversation continuity is a transport concern rather than Kernel reasoning.
|
|
6
|
+
The stable configuration path is `rh_work.schedule_*`: create one continuation policy for an already accepted Work, inspect it, pause/resume it, or trigger one bounded Occurrence. The engine re-checks Work terminality before launch and automatically disables the Schedule when the Work is complete, so users do not need to keep sending “continue” and Forge does not keep waking a model after acceptance is satisfied.
|
|
7
|
+
A scheduled wake uses a short launch reservation rather than a fake Controller lease. The external model becomes owner only after its own authenticated MCP session calls `rh_work continue`; this is the identity handoff boundary between deterministic scheduling and semantic control.
|
|
6
8
|
|
|
7
9
|
See [Dispatch and Agent Strategy](architecture/current/dispatch-and-agent-strategy.md), [Schedule Engine](architecture/current/automation-and-schedule-engine.md), and [Governance](architecture/current/governance.md).
|