feat: introduce Forge 2.0 durable workflow control plane

.agents/skills/forge-workflow-authoring/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: forge-workflow-authoring
+description: Create, explain, change, or review Forge declarative workflow definitions. Use for Forge workflow YAML/JSON, topology, step permissions, validation failures, revisions, and migration planning.
+---
+
+# Forge Workflow Authoring
+
+Help the user express a Forge process as readable YAML. Treat canonical JSON as generated publication storage, not as the human authoring format.
+
+## Start here
+
+1. Read [references/workflow-format.md](references/workflow-format.md).
+2. For a new workflow, copy [assets/workflow.yaml](assets/workflow.yaml). For a change, start from the active definition or the closest built-in workflow and convert it to YAML if needed.
+3. Establish the intended stages, decisions, loops, human pauses, and external commands before editing fields.
+4. Run `forge workflow catalog STATE` and use only the nodes and routers it reports. Never invent catalog names.
+5. Keep the definition flow-only. Do not add node kinds, station contracts, effect capabilities, required or mandatory policies, extension declarations, observation policies, or external-entry flags. Forge derives and enforces those concerns from its trusted catalog and publication policy.
+6. Validate and render before presenting the result:
+
+   ```bash
+   forge workflow validate WORKFLOW.yaml
+   forge workflow render WORKFLOW.yaml
+   ```
+
+Explain the rendered process in plain language when the user is trying to understand an existing definition.
+
+## Changing an existing workflow
+
+Increment `metadata.revision`, preserve the workflow name, and compare revisions:
+
+```bash
+forge workflow diff PREVIOUS.yaml CURRENT.yaml
+```
+
+If saved nodes were renamed or removed, add explicit `spec.resume.fromRevisions` mappings. When checkpoint snapshots are available, verify them:
+
+```bash
+forge workflow simulate-migration PREVIOUS.yaml CURRENT.yaml INSTANCES.json
+```
+
+Do not claim migration safety based only on successful validation.
+
+## Review expectations
+
+Before publication, verify:
+
+- all transitions and router outcomes resolve to existing steps or `__end__`;
+- expected human and CI pause points remain present;
+- cycles cross an approved pause boundary;
+- exceptional commands such as PR rebasing are absent from graph topology;
+- revision and resume mappings protect in-flight instances.
+
+Report review problems with the affected step and a concrete correction. Distinguish topology, execution-policy, and migration findings; catalog and governance concerns are Forge implementation findings, not fields to add to the workflow.
+
+Do not publish, activate, roll back, or delete a workflow unless the user explicitly requests that external change. If asked to publish, validate and review first, then use a meaningful actor and reason.

.agents/skills/forge-workflow-authoring/assets/workflow.yaml

@@ -0,0 +1,21 @@
+apiVersion: forge/v1
+kind: Workflow
+metadata:
+  name: example-workflow
+  revision: 1
+  description: Replace with the purpose of this workflow
+spec:
+  state: feature
+  entry: generate_prd
+  steps:
+    generate_prd:
+      next: prd_approval_gate
+    prd_approval_gate:
+      route: route_prd_approval
+      branches:
+        generate_spec: __end__
+        regenerate_prd: generate_prd
+        answer_question: answer_question
+        __end__: __end__
+    answer_question:
+      next: prd_approval_gate

.agents/skills/forge-workflow-authoring/references/workflow-format.md

@@ -0,0 +1,75 @@
+# Forge workflow format
+
+## How to read it
+
+A definition has four important parts:
+
+- `metadata.name` is the stable workflow identity; `metadata.revision` increases with every change.
+- `spec.state` chooses the `feature`, `bug`, or `task_takeover` catalog.
+- `spec.entry` names the first ordinary step.
+- `spec.steps` maps registered node names to their transitions.
+
+Start at `entry`. Follow `next` for a fixed transition. At a step with `route`, follow every target in `branches`. A branch key is a possible router result; its value is the next step. `__end__` stops the current invocation and is not itself a declared step.
+
+Use `forge workflow render FILE` instead of tracing a large definition manually.
+
+## Step shapes
+
+A fixed transition:
+
+```yaml
+generate_prd:
+  next: prd_approval_gate
+```
+
+A routed transition:
+
+```yaml
+prd_approval_gate:
+  route: route_prd_approval
+  branches:
+    generate_spec: __end__
+    regenerate_prd: generate_prd
+    answer_question: answer_question
+    __end__: __end__
+```
+
+Every possible static router result must be represented in `branches`.
+
+Dynamic fan-out uses `dynamicRoute: true` and an explicit `maxConcurrency`. Forge derives the router's permitted destinations from the trusted catalog; inspect them with `forge workflow catalog STATE`. A join uses `join: all` or `join: any`. Copy the applicable shape from a validated built-in definition instead of reconstructing advanced routing from memory.
+
+## Separation of concerns
+
+The workflow owns topology and flow-level execution choices. `retryBound`, `maxConcurrency`, and join behavior remain valid because they change how the graph advances.
+
+Do not author `kind`, `stationContract`, `stationContractVersion`, `requiredPolicies`, `allowedEffects`, `externalEntry`, `observationPolicy`, `mandatoryPolicies`, or `extensionPoints`. Forge derives node identity, authority, reconciliation, and mandatory governance from the selected state profile. Exceptional commands such as PR rebasing execute through the command-operation boundary and do not appear as workflow steps. Older pinned definitions containing catalog metadata remain readable for compatibility.
+
+Run `forge workflow catalog STATE` when you need to inspect the derived node metadata; do not copy that metadata into the workflow.
+
+## Revision compatibility
+
+Running instances pin a definition, so publishing a revision does not silently move them. If a saved position was renamed or removed, map it explicitly:
+
+```yaml
+spec:
+  resume:
+    fromRevisions:
+      1:
+        old_gate: replacement_gate
+```
+
+Do not reuse a revision with changed content or assume a valid new graph can resume old checkpoints.
+
+## Commands and outputs
+
+```bash
+forge workflow validate workflow.yaml
+forge workflow catalog feature
+forge workflow validate workflow.yaml --json
+forge workflow render workflow.yaml
+forge workflow render workflow.yaml --format json
+forge workflow diff previous.yaml workflow.yaml
+forge workflow simulate-migration previous.yaml workflow.yaml instances.json
+```
+
+`validate --json` emits canonical storage JSON. `render --format json` emits a compact process manifest. These outputs serve different purposes.

.env.example

@@ -77,7 +77,7 @@ FORGE_REQUIRE_PROJECT_CONFIG=true
 # variables; connection definitions contain no secrets.
 GOOGLE_CLOUD_PROJECT=your-gcp-project-id
 GOOGLE_CLOUD_LOCATION=global
-MODEL_CONNECTIONS={"vertex-prod":{"backend":"vertex-ai","project":"your-gcp-project-id","location":"global","allowed_models":["gemini-3.5-pro","gemini-3.5-flash"],"capabilities":["tools"]}}
+MODEL_CONNECTIONS={"vertex-prod":{"backend":"vertex-ai","project":"your-gcp-project-id","location":"global","allowed_models":["gemini-3.5-pro","gemini-3.5-flash"],"capabilities":["structured_output","tools"]}}
 MODEL_DEFAULT={"connection":"vertex-prod","model":"gemini-3.5-flash"}
 # Optional per-stage override:
 # MODEL_POLICY={"generate_prd":{"connection":"vertex-prod","model":"gemini-3.5-pro"}}
@@ -270,6 +270,10 @@ WORKER_METRICS_ENABLED=true
 # API server uses port 8000, worker uses 8001 for metrics
 WORKER_METRICS_PORT=8001
 
+# Enables authenticated durable-effect inspection and replay endpoints.
+# Leave unset to keep /api/v1/effects disabled.
+# EFFECT_OPERATOR_TOKEN=replace-with-a-long-random-secret
+
 # =============================================================================
 # Application Configuration
 # =============================================================================

.github/workflows/ci.yml

@@ -2,11 +2,6 @@ name: CI
 
 on:
   pull_request:
-    branches:
-      - main
-      - integration/dev-to-main
-      - prototype/declarative-workflows
-      - prototype/layered-planning-state
 
 jobs:
   helm-lint:

README.md

@@ -56,9 +56,13 @@ The built-in model factory supports direct Anthropic API credentials and Google
 
 Forge is not just an agent with a large prompt or a folder of skills. It is a stateful delivery workflow that decides what should happen next, when to pause, which artifact needs review, which repository should be changed, and how to recover when something fails.
 
-- **Workflow first, agents second**: LangGraph coordinates the lifecycle from ticket intake to PR review. Agents perform bounded stage work; the workflow owns routing, checkpoints, retries, approvals, and handoffs.
+- **Workflow first, agents second**: Forge-owned, versioned definitions coordinate the lifecycle
+  from ticket intake to PR review. LangGraph executes those definitions; typed stations perform
+  bounded work without owning routing, checkpoints, approvals, or handoffs.
 - **Cross-repo by design**: Forge can plan features and bugs across services, clients, infrastructure, and documentation repos, then split the work into repo-scoped units that can be implemented and reviewed independently.
-- **Controlled write boundaries**: Agents do not directly mutate Jira, GitHub, or production repositories. Implementation agents write only inside their local/container workspace; Forge's integration layer performs external updates such as Jira comments, labels, branch pushes, and PR creation at explicit workflow steps.
+- **Controlled write boundaries**: Agents do not directly mutate Jira, GitHub, or production
+  repositories. Forge journals required external effects before execution and retains attempt and
+  provider evidence for recovery and operator replay.
 - **Native engineering loop**: Forge works through Jira tickets, Jira comments, Jira labels, GitHub PRs, GitHub reviews, and CI webhooks instead of forcing teams into a separate agent UI.
 - **Traceable by default**: Work is reflected back into Jira and GitHub as comments, labels, PRs, review updates, CI decisions, and post-merge summaries, so teams can follow why the workflow moved or paused.
 - **Project visibility**: Prometheus metrics, Langfuse traces, and Grafana dashboards expose workflow throughput, step latency, ticket execution cost, model usage, CI behavior, and observability health by project, ticket type, workflow step, and Jira issue.
@@ -170,19 +174,24 @@ This lets Forge follow local engineering conventions without forking the orchest
 
 ## Architecture
 
-Forge is event-driven:
+Forge is event-driven and checkpointed:
 
 ```text
-Jira + GitHub Webhooks
+Jira + GitHub Webhooks / Poller
   -> FastAPI Gateway
   -> Redis Streams Queue
-  -> LangGraph Workflow
-  -> Host Orchestrator Agent
-  -> Container Agent for Implementation
-  -> Jira + GitHub Updates
+  -> Observation Reconciliation
+  -> Pinned Versioned Workflow
+  -> Typed Stations
+  -> Durable External Effects
+  -> Jira + GitHub
 ```
 
-Jira and GitHub send webhooks to Forge. Forge queues events, resumes the right workflow state, runs the next node, and posts the result back to Jira or GitHub. Planning runs through the host orchestrator. Code implementation runs in short-lived containers. Agents generate artifacts and local code changes; Forge's workflow and integration layer decide when those outputs become Jira updates, branch pushes, or pull requests.
+Webhook and poller deliveries normalize to the same observation contract. Forge deduplicates and
+orders provider revisions, interprets accepted evidence through the instance's pinned workflow
+definition, and invokes typed stations. Planning agents run on the host and implementation agents
+run in short-lived containers. Jira and source-control mutations cross a durable effect journal;
+operators can inspect the combined process, observation, station, and effect timeline.
 
 ## Quick Start
 
@@ -218,6 +227,10 @@ See [Getting Started](https://Forge-sdlc.github.io/forge/getting-started/) for t
 - [Task Workflow](https://Forge-sdlc.github.io/forge/guide/task-workflow/): Understand standalone Task and Epic implementation.
 - [PR Commands](https://Forge-sdlc.github.io/forge/guide/pr-commands/): Rebase PRs and handle CI gate skips.
 - [Configuration Reference](https://Forge-sdlc.github.io/forge/reference/config/): Environment variables and project configuration.
+- [Architecture](https://Forge-sdlc.github.io/forge/architecture/): Versioned workflows,
+  reconciliation, typed stations, durable effects, and execution inspection.
+- [Declarative Workflows](https://Forge-sdlc.github.io/forge/reference/declarative-workflows/):
+  Author and govern constrained project workflow definitions.
 - [Skills System](https://Forge-sdlc.github.io/forge/skills/): Customize Forge for your team and stack.
 - [Developer Guide](https://Forge-sdlc.github.io/forge/developer-guide/): Local testing, debugging, Prometheus metrics, Langfuse tracing, and Grafana dashboards.
 

charts/forge/Chart.yaml

@@ -2,5 +2,5 @@ apiVersion: v2
 name: forge
 description: Forge API and Kubernetes sandbox worker
 type: application
-version: 1.0.0
-appVersion: "1.0.0"
+version: 2.0.0
+appVersion: "2.0.0"