docs: lock Forge VNext general-agent architecture

[Joncallim]

Summary

Locks the reviewed Forge VNext product direction into the repository without claiming the future runtime is already implemented.

VNext reframes Forge as a local-first, budget-aware, deterministic-first runtime for installable AI Workforces, with Software Engineering as the first Workforce rather than the permanent product boundary.

Key decisions:

• no permanent/always-on LLM parent orchestrator;
• zero-token idle as a design/release requirement;
• deterministic, provider-neutral routing and explicit Mission budgets;
• optimize expected cost to a verified outcome rather than cheapest individual calls;
• generic Mission / Execution / Resource / Capability / Grant / Principal contracts;
• agents receive scoped authority but cannot widen it;
• reviewers/verifiers produce evidence while trusted Forge gates decide;
• declarative Workforce packages are separate from executable capability adapters;
• version pinning, provenance and permission diffs for package updates;
• explicit external side-effect uncertainty, idempotency and reconciliation;
• bounded context/data-egress policy and secure execution envelope;
• three reference proofs: Software Engineering, Deep Research, Infrastructure Ops;
• Hermes/HearthBot contributes learned requirements only—no code/config/state/runtime import; HearthBot ultimately becomes a thin Forge interface and Hermes is removed;
• model ensembles are explicitly deferred.

Iterative review

The architecture was revised through independent passes covering:

1. product/contract generality;
2. phase sequencing and coding-coupling risk;
3. authority/principal/grant lineage;
4. verification/gate independence;
5. token/cost economics;
6. context and caching validity;
7. Workforce package/supply-chain boundary;
8. OS/runtime confinement;
9. uncertain external side effects and recovery;
10. persistent Mission state/leases/bounds;
11. trigger identity/dedupe/causality;
12. data privacy/provider egress;
13. parallel resource conflicts;
14. proof-workload selection;
15. Hermes cutover / single-writer migration;
16. integration with existing [EPIC] MCP Execution Readiness and Bounded Context Grants #172/[EPIC] Continuous verification and earned autonomy #184 trust architecture;
17. scope/simplification.

A final hostile specification pass also tightened concurrent budget reservations, unknown-cost provider policy, transitive package permissions, mandatory-gate ceilings, webhook/source authentication, typed model-output admission, and sensitive-artifact retention.

The documentation-governance pass removed conflicting roadmap authority and stale current-facing claims: docs/roadmap.md is now the canonical VNext product roadmap; the README/wiki distinguish today's coding-focused beta from the future VNext architecture; docs/workspace-roadmap.md is explicitly deferred rather than the active implementation order.

The review record uses the repository's scoped verdict language and records remaining implementation uncertainties instead of treating architecture confidence as proof.

Files

• README.md — truthful current boundary plus accepted VNext direction and delivered trust foundations.
• docs/wiki.md — plain-English current-state/VNext overview aligned with the repository.
• docs/forge-vnext-architecture.md — full VNext architecture and invariants.
• docs/roadmap.md — canonical concise VNext product roadmap used by normal repo roadmap discovery.
• docs/near-term-roadmap.md — exact [EPIC] Forge VNext — budget-aware general agent runtime and installable Workforces #333 execution order and phase gates.
• docs/adr/0014-forge-vnext-general-agent-runtime.md — durable architecture decision/invariants.
• docs/architecture/forge-vnext-review-record.md — iterative adversarial review record.
• docs/adr/0007-forge-agent-workforce-model.md — scopes the existing coding-role taxonomy under VNext.
• docs/workspace-roadmap.md — preserves the Workspace design proposal but marks its old sequencing as superseded/deferred.

GitHub programme

Umbrella: #333

Child phases: #334, #335, #336, #337, #338, #339, #340, #341, #342, #343, #344.

Epic #184 remains the canonical earned-autonomy/trust programme; this PR explicitly reuses #201/#185/#186 and requires remaining #187–#191 to align with VNext rather than create parallel orchestration truth.

Validation

Documentation/architecture-only change; no runtime code is changed.

• Repository-grounded orthogonal/adversarial review completed and iterated until no further material architecture finding emerged.
• Final branch diff contains exactly nine documentation files and no runtime/code files.
• The initial whitespace CI failure was caused by three Markdown hard-break spaces and was corrected without weakening CI.
• Broken/stale documentation references found during the final review were corrected, including the wiki screenshot filename and superseded Workspace/[FEATURE] Add deterministic operation catalog and typed execution harness #201 sequencing.
• Final head SHA: 196a4b376316a854c68f539b792a8b810ef160ed.
• PR Contract Check #959: success.
• Web CI #996: success, including migrations, lint, TypeScript, full zero-skip unit suite, MCP contract, build, PostgreSQL/Redis/security/concurrency proofs, operator recovery, and fail-closed E2E bridge suite.

Related: #333

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-02T23:56:06.760947Z	32488f6	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 32488f6bc4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Expand acronyms when first introduced

For readers entering through this standalone architecture, LLM is never expanded, and the document later introduces UI, CLI, API, MCP, DB, and ACP the same way; the new ADR and near-term roadmap repeat this problem. Expand each acronym on first use (for example, “large language model (LLM)”) or link to a glossary so the canonical VNext documents remain accessible to non-experts.

AGENTS.md reference: AGENTS.md:L168-L175

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Update the public roadmap entry points

Declaring VNext the current product direction leaves the public entry points contradictory: README.md:221-232 still presents the replaced #172→#184 sequence, while docs/roadmap.md:30-41 and docs/roadmap.md:451-455 still call Forge Workspace the next major direction even though this roadmap defers it at lines 330-338. Because the README links both documents as current roadmaps, readers receive mutually exclusive execution priorities; update or explicitly deprecate those stale sections in this change.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Align phase numbers across the canonical roadmaps

This reference is ambiguous because docs/forge-vnext-architecture.md:845-847 maps the Software Engineering proof (#337) to Phase 3 and package extraction (#338) to Phase 4, while this roadmap inserts architecture freeze as step 0 and labels those same issues steps 4 and 5. Consequently, “the same Phase 4 release gate” can mean either the preceding #337 proof or the current #338 package phase depending on which canonical document is used; identify the gate by issue or adopt one numbering scheme.

Useful? React with 👍 / 👎.