codex-workflow-v2 2.0.0-alpha.1

package/roles/delivery-coordinator.md

@@ -0,0 +1,10 @@
+# Delivery Coordinator
+
+Own state transitions, dispatch envelopes, evidence collection, and recovery guidance.
+
+- Verify Project Knowledge Map freshness before Plan authorization and role dispatch.
+- Own derived map revisions and context selection, but never edit the meaning of canonical project files.
+- Treat CLI `status`, `next`, revision, and lock state as authoritative machine state.
+- Never bypass authorization, scope checks, failed validation, or stale review.
+- Dispatch one Worker at a time for a concrete Step.
+- Do not make product-scope decisions or implement production changes.

package/roles/independent-reviewer.md

@@ -0,0 +1,10 @@
+# Independent Reviewer
+
+Compare requirements, acceptance, Plan, task-branch diff, checks, and generated evidence.
+
+- Verify that declared knowledge impact matches the diff and that canonical project files agree with implemented behavior.
+- Treat MCP and the local map as navigation/evidence metadata; confirm critical claims against repository files and Git.
+- Operate read-only and do not fix findings.
+- Mark the review `unverified` when read-only isolation or required evidence is unavailable.
+- A failed review must contain actionable findings; a passed review contains none.
+- Do not grant final acceptance on behalf of the user.

package/roles/scope-lead.md

@@ -0,0 +1,11 @@
+# Scope Lead
+
+Own requirements discovery before any Task, branch, or execution artifact exists.
+
+- Scan existing repository files and propose a Project Knowledge Map before code-aware discovery.
+- Classify candidate sources and explicit gaps; never appoint a canonical source without user approval.
+- Read broad approved project knowledge, treating the local map as derived metadata rather than content.
+- Separate facts, decisions, assumptions, and unknowns.
+- Ask only for missing information that changes scope, outcome, constraints, or acceptance.
+- Do not implement, create branches, or treat an assumption as an approved requirement.
+- Recommend Task materialization only when the readiness gate reports no blocking gaps.

package/roles/technical-planner.md

@@ -0,0 +1,10 @@
+# Technical Planner
+
+Translate an approved Brief into an execution-ready Plan.
+
+- Read the approved knowledge sources relevant to the Task and bind the Plan to the active map revision/hash.
+- Declare `knowledgeImpact`, its reason, targets, and `graphUse`; do not hide missing knowledge as an implementation choice.
+- Every requirement must be covered by at least one `STEP-*`.
+- Each Step declares dependencies, outputs, allowed writes, forbidden scope, and checks.
+- Do not edit production files or silently expand the Brief.
+- Return unresolved semantic choices to the user through the Delivery Coordinator.

package/roles/worker.md

@@ -0,0 +1,10 @@
+# Worker
+
+Implement exactly one dispatched Step under its context envelope.
+
+- Read only the mapped sources selected for the Step plus explicitly targeted knowledge files.
+- Update canonical project files only when they appear in the authorized knowledge targets and `allowedWrites`.
+- Read only declared inputs and repository context needed for the Step.
+- Write only `allowedWrites`; stop on required scope expansion.
+- Run the declared checks and report limitations honestly.
+- Do not edit the Brief, Plan, acceptance, other Steps, workflow state, or Git history manually.

package/schemas/context-envelope.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://codex-workflow.local/schemas/context-envelope.schema.json",
+  "title": "Codex Workflow V2 Context Envelope",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "protocolVersion",
+    "packageVersion",
+    "role",
+    "objective",
+    "inputs",
+    "allowedReads",
+    "allowedWrites",
+    "commands",
+    "forbiddenScope",
+    "resultSchema",
+    "stopConditions",
+    "contextBudget",
+    "taskId",
+    "stepId",
+    "expectedRevision",
+    "writerToken",
+    "knowledgeMap",
+    "knowledgeSources"
+  ],
+  "properties": {
+    "protocolVersion": { "const": 1 },
+    "packageVersion": { "type": "string" },
+    "role": {
+      "enum": ["scope-lead", "technical-planner", "delivery-coordinator", "worker", "independent-reviewer"]
+    },
+    "objective": { "type": "string", "minLength": 1 },
+    "inputs": { "type": "array", "items": { "type": "string" } },
+    "allowedReads": { "type": "array", "items": { "type": "string" } },
+    "allowedWrites": { "type": "array", "items": { "type": "string" } },
+    "commands": { "type": "array", "items": { "type": "string" } },
+    "forbiddenScope": { "type": "array", "items": { "type": "string" } },
+    "resultSchema": { "type": "object" },
+    "stopConditions": { "type": "array", "items": { "type": "string" } },
+    "contextBudget": { "enum": ["small", "medium", "large"] },
+    "taskId": { "type": "string", "pattern": "^TASK-[0-9A-HJKMNP-TV-Z]{26}$" },
+    "stepId": { "type": "string", "pattern": "^STEP-[0-9]{3}(?:-[A-Z0-9-]+)?$" },
+    "expectedRevision": { "type": "integer", "minimum": 1 },
+    "writerToken": { "type": ["string", "null"] },
+    "knowledgeMap": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["revision", "hash", "status"],
+      "properties": {
+        "revision": { "type": "integer", "minimum": 1 },
+        "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "status": { "enum": ["draft", "awaiting_approval", "active", "stale", "conflicted"] }
+      }
+    },
+    "knowledgeSources": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/discovery.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://codex-workflow.local/schemas/discovery.schema.json",
+  "title": "Codex Workflow V2 Discovery State",
+  "type": "object",
+  "required": ["schemaVersion", "revision", "id", "projectId", "kind", "status", "goal", "acceptance"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "revision": { "type": "integer", "minimum": 1 },
+    "id": { "type": "string", "pattern": "^DISC-[0-9A-HJKMNP-TV-Z]{26}$" },
+    "projectId": { "type": "string", "pattern": "^[a-f0-9]{24}$" },
+    "kind": { "const": "discovery" },
+    "status": {
+      "enum": ["needs_discovery", "needs_clarification", "ready_to_materialize", "materialized", "abandoned"]
+    },
+    "goal": { "type": "string", "minLength": 1 },
+    "acceptance": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/graph-binding.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://codex-workflow.local/schemas/graph-binding.schema.json",
+  "title": "Codex Workflow V2 Graph Binding",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "revision", "id", "projectId", "kind", "graphKind", "provider", "rootFingerprint", "mode", "status", "observedAt", "evidenceHash", "previous"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "revision": { "type": "integer", "minimum": 1 },
+    "id": { "enum": ["GRAPH-product", "GRAPH-workflow"] },
+    "projectId": { "type": "string", "pattern": "^[a-f0-9]{24}$" },
+    "kind": { "const": "graph-binding" },
+    "graphKind": { "enum": ["product", "workflow"] },
+    "provider": { "const": "codebase-memory-mcp" },
+    "projectKey": { "type": ["string", "null"] },
+    "rootFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "indexedHead": { "type": ["string", "null"] },
+    "packageVersion": { "type": ["string", "null"] },
+    "manifestHash": { "type": ["string", "null"] },
+    "mode": { "enum": ["moderate", "full"] },
+    "status": { "enum": ["ready", "stale", "unavailable", "fallback"] },
+    "nodeCount": { "type": ["integer", "null"], "minimum": 0 },
+    "edgeCount": { "type": ["integer", "null"], "minimum": 0 },
+    "observedAt": { "type": "string", "format": "date-time" },
+    "evidenceHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "fallbackReason": { "type": ["string", "null"] },
+    "previous": { "type": ["object", "null"] }
+  }
+}

package/schemas/milestone.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://codex-workflow.local/schemas/milestone.schema.json",
+  "title": "Codex Workflow V2 Milestone State",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion", "revision", "id", "projectId", "createdAt", "updatedAt", "kind", "status",
+    "title", "discoveryId", "outcome", "successSignal", "acceptance", "baseBranch", "taskIds",
+    "memberships", "checks", "membershipRevision", "authorizations", "planHash", "resultHash",
+    "evidenceHash", "acceptedHead", "cancellationReason"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "revision": { "type": "integer", "minimum": 1 },
+    "id": { "type": "string", "pattern": "^MS-[0-9A-HJKMNP-TV-Z]{26}$" },
+    "projectId": { "type": "string", "pattern": "^[a-f0-9]{24}$" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" },
+    "kind": { "const": "milestone" },
+    "status": {
+      "enum": [
+        "planning", "awaiting_execution_authorization", "active", "validating",
+        "awaiting_final_acceptance", "accepted", "blocked", "cancelled"
+      ]
+    },
+    "title": { "type": "string", "minLength": 1 },
+    "discoveryId": { "type": "string", "pattern": "^DISC-[0-9A-HJKMNP-TV-Z]{26}$" },
+    "outcome": { "type": "string" },
+    "successSignal": { "type": "string" },
+    "acceptance": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "baseBranch": { "type": "string", "minLength": 1 },
+    "taskIds": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/taskId" } },
+    "memberships": { "type": "array", "items": { "$ref": "#/$defs/membership" } },
+    "checks": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "membershipRevision": { "type": "integer", "minimum": 0 },
+    "authorizations": { "type": "array", "items": { "type": "object" } },
+    "planHash": { "$ref": "#/$defs/nullableHash" },
+    "resultHash": { "$ref": "#/$defs/nullableHash" },
+    "evidenceHash": { "$ref": "#/$defs/nullableHash" },
+    "acceptedHead": { "$ref": "#/$defs/nullableHash" },
+    "cancellationReason": { "type": ["string", "null"] }
+  },
+  "$defs": {
+    "taskId": { "type": "string", "pattern": "^TASK-[0-9A-HJKMNP-TV-Z]{26}$" },
+    "nullableHash": { "type": ["string", "null"], "pattern": "^[a-f0-9]{40,64}$" },
+    "membership": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["taskId", "disposition", "reason"],
+      "properties": {
+        "taskId": { "$ref": "#/$defs/taskId" },
+        "disposition": { "enum": ["required", "waived", "cancelled"] },
+        "reason": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/project-knowledge-map.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://codex-workflow.local/schemas/project-knowledge-map.schema.json",
+  "title": "Codex Workflow V2 Project Knowledge Map",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "revision", "id", "projectId", "kind", "status", "entries", "gaps", "conflicts", "approval"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "revision": { "type": "integer", "minimum": 1 },
+    "id": { "const": "PROJECT-KNOWLEDGE-MAP" },
+    "projectId": { "type": "string", "pattern": "^[a-f0-9]{24}$" },
+    "kind": { "const": "knowledge-map" },
+    "status": { "enum": ["draft", "awaiting_approval", "active", "stale", "conflicted"] },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "category", "path", "scope", "authority", "contentHash", "discoveredBy", "lastVerifiedAt"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^KS-[a-f0-9]{16}$" },
+          "category": { "enum": ["agent-guidance", "onboarding", "architecture", "decisions", "commands", "ownership", "testing", "operations", "domain"] },
+          "path": { "type": "string", "minLength": 1 },
+          "scope": { "type": "string", "minLength": 1 },
+          "authority": { "enum": ["canonical", "supporting"] },
+          "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "discoveredBy": { "type": "string", "minLength": 1 },
+          "lastVerifiedAt": { "type": "string", "format": "date-time" }
+        }
+      }
+    },
+    "gaps": { "type": "array" },
+    "conflicts": { "type": "array" },
+    "approval": { "type": ["object", "null"] }
+  }
+}

package/schemas/review-result.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://codex-workflow.local/schemas/review-result.schema.json",
+  "title": "Codex Workflow V2 Strict Review Result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["status", "reviewer", "summary", "findings", "isolationProbe"],
+  "properties": {
+    "status": { "enum": ["passed", "failed", "unverified"] },
+    "reviewer": { "type": "string", "minLength": 1 },
+    "summary": { "type": "string", "minLength": 1 },
+    "isolationProbe": { "enum": ["denied", "written", "not-attempted"] },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "severity", "requirement", "summary", "evidence", "requiredAction"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "severity": { "enum": ["critical", "major", "minor"] },
+          "requirement": { "type": ["string", "null"] },
+          "summary": { "type": "string", "minLength": 1 },
+          "evidence": { "type": "string", "minLength": 1 },
+          "requiredAction": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/schemas/task.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://codex-workflow.local/schemas/task.schema.json",
+  "title": "Codex Workflow V2 Task State",
+  "type": "object",
+  "required": ["schemaVersion", "revision", "id", "projectId", "kind", "status", "title", "knowledgeImpact", "knowledgeTargets", "knowledgeMapRevision", "knowledgeMapHash", "graphUse", "steps", "authorizations"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "revision": { "type": "integer", "minimum": 1 },
+    "id": { "type": "string", "pattern": "^TASK-[0-9A-HJKMNP-TV-Z]{26}$" },
+    "projectId": { "type": "string", "pattern": "^[a-f0-9]{24}$" },
+    "kind": { "const": "task" },
+    "status": {
+      "enum": [
+        "planning",
+        "awaiting_execution_authorization",
+        "ready",
+        "in_progress",
+        "validating",
+        "needs_fix",
+        "awaiting_final_acceptance",
+        "merging",
+        "ready_to_merge",
+        "merged",
+        "blocked",
+        "cancelled"
+      ]
+    },
+    "title": { "type": "string", "minLength": 1 },
+    "knowledgeImpact": { "enum": ["none", "update", "create", "retire", null] },
+    "knowledgeImpactReason": { "type": ["string", "null"] },
+    "knowledgeTargets": { "type": "array" },
+    "knowledgeMapRevision": { "type": ["integer", "null"], "minimum": 1 },
+    "knowledgeMapHash": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
+    "graphUse": { "enum": ["code-aware", "not-applicable", null] },
+    "steps": { "type": "array" },
+    "authorizations": { "type": "array" }
+  }
+}

package/templates/brief.md

@@ -0,0 +1,21 @@
+# {{title}} Brief
+
+## Goal
+
+{{goal}}
+
+## Observable Outcome
+
+{{outcome}}
+
+## Requirements
+
+{{requirements}}
+
+## Scope
+
+{{scope}}
+
+## Acceptance Scenarios
+
+{{acceptance}}

package/templates/plan.md

@@ -0,0 +1,17 @@
+# {{taskId}} Plan
+
+## Objective
+
+{{objective}}
+
+## Requirements and Acceptance
+
+{{requirementsAndAcceptance}}
+
+## Risks
+
+{{risks}}
+
+## Steps
+
+{{steps}}

package/templates/result.md

@@ -0,0 +1,13 @@
+# {{taskId}} Result
+
+## Summary
+
+{{summary}}
+
+## Completed Steps and Commits
+
+{{completedSteps}}
+
+## Limitations
+
+{{limitations}}