specrails-core 6.0.0 → 6.1.0

package/integration-contract.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "5.0",
+  "schemaVersion": "5.1",
   "providers": {
     "claude": {
       "cli": {
@@ -13,7 +13,6 @@
       "initCommand": "init",
       "workflows": {
         "implement": "/specrails:implement",
-        "batch-implement": "/specrails:batch-implement",
         "retry": "/specrails:retry"
       }
     },
@@ -29,7 +28,6 @@
       "initCommand": "init",
       "workflows": {
         "implement": "$implement",
-        "batch-implement": "$batch-implement",
         "retry": "$retry"
       }
     },
@@ -45,7 +43,6 @@
       "initCommand": "init",
       "workflows": {
         "implement": "/specrails:implement",
-        "batch-implement": "/specrails:batch-implement",
         "retry": "/specrails:retry"
       }
     },
@@ -85,12 +82,21 @@
           "<model-id>",
           "--args",
           "<arguments>"
+        ],
+        "renderOnlyArgs": [
+          ".kimi-code/specrails/run-skill.mjs",
+          "--skill",
+          "<skill-id>",
+          "--model",
+          "<model-id>",
+          "--args",
+          "<arguments>",
+          "--render-only"
         ]
       },
       "initCommand": "init",
       "workflows": {
         "implement": "/skill:specrails-implement",
-        "batch-implement": "/skill:specrails-batch-implement",
         "retry": "/skill:specrails-retry"
       }
     }
@@ -229,9 +235,19 @@
       "validate",
       "run",
       "status",
-      "resume"
+      "resume",
+      "prompts",
+      "capabilities",
+      "evidence",
+      "recovery",
+      "evaluate",
+      "workflows",
+      "fork",
+      "signal",
+      "cancel"
     ],
-    "apiOperation": "runtime api emits {type: runtime-api, apiVersion, coreVersion}; does not invoke providers",
+    "cliPresentationOperations": ["help"],
+    "apiOperation": "runtime api emits {type: runtime-api, apiVersion, coreVersion, runtimeIdentity, workflowVersions, engineVersion, engines, nodeKindsVersion, nodeKinds, capabilities, guardrails}; does not invoke providers",
     "validationTransport": "runtime validate --stdin accepts UTF-8 configuration JSON up to 2 MiB, mutually exclusive with --config",
     "compactStatus": "runtime status --compact omits workflow history, events and outputs, frozen pipeline context and verification command output; retains identities (runId, traceId), phase statuses and visits, pendingApproval, pendingQuestion, usage, completion, acceptance summary and verification metadata",
     "interrupts": "A paused run (exit 2) carries pendingApproval (resume --approve <step>) or pendingQuestion (resume --answer <text>, nonempty, at most 20000 characters); the architect asks only after one autonomous investigation pass unless architect.onLowConfidence is proceed",
@@ -241,7 +257,7 @@
     "configSchemaPath": "schemas/agent-runtime.schema.json",
     "configSchemaExport": "specrails-core/schemas/agent-runtime.schema.json",
     "projectConfigPath": ".specrails/agent-runtime.json",
-    "minimumNode": "20.19.0",
+    "minimumNode": "22.22.3",
     "platforms": [
       "darwin",
       "win32"
@@ -260,6 +276,7 @@
     "phases": [
       "architect",
       "developer",
+      "fixer",
       "verify",
       "reviewer",
       "archive"
@@ -277,19 +294,74 @@
     "specificationFormat": "Architect specs contain complete main-spec replacements, including unchanged requirements; archive does not merge partial delta snippets.",
     "compatibility": "Additive to integration schema 4 and execution context schema 1. Legacy workflows and profile v1 remain supported. Hosts must check RUNTIME_API_VERSION, not infer runtime support from Core major version.",
     "documentation": "docs/agent-runtime.md",
-    "instructionsVersion": "3",
-    "workflowVersion": "3",
+    "instructionsVersion": "10",
+    "workflowVersion": "7",
+    "engines": [1, 2],
+    "engine": {
+      "version": 2,
+      "definitionSchema": "schemas/workflow-definition.schema.json",
+      "nodeKindsVersion": 5
+    },
+    "nodeKinds": [
+      "prompt",
+      "role-turn",
+      "decider",
+      "verify",
+      "shell",
+      "openspec-validate",
+      "openspec-archive",
+      "condition",
+      "end",
+      "approval",
+      "question",
+      "gate",
+      "assign",
+      "component",
+      "map",
+      "implementation",
+      "join"
+    ],
+    "engineStatePath": "<backlogRoot>/.specrails/pipeline/<runId>/agent-workflow/run.sqlite",
+    "frozenRequest": "agent-runtime-request.json carries workflow {id, version, source: builtin|definition, definitionHash, engine: 1|2}; resume and status select the engine from workflow.engine and a request without the block is a legacy (engine 1) run",
+    "builtins": [
+      { "id": "specrails-implementation", "version": "7", "deprecated": false }
+    ],
     "developerTools": "The developer role runs with each CLI's autonomous edit+shell mode (claude --tools default --dangerously-skip-permissions with Agent/Task/Skill disallowed; codex workspace-write; gemini --yolo; kimi print mode). Architect and reviewer stay read-only. Claude roles load project settings only (--setting-sources project,local).",
     "verificationPolicy": "Configured commands are optional. The architect proposes commands for repositories without one; repositories with no automated check are admitted and recorded in the receipt as unverifiedRepositories. Unchecked tasks return to the developer as feedback instead of failing the run.",
     "sessionReuse": "Developer correction passes resume the previous provider session (claude --resume, codex exec resume, gemini --resume, kimi --session) with a short correction prompt; an unavailable session falls back to a fresh full turn. Structured roles get one repair turn in-session when their JSON is unusable.",
     "structuredOutput": "Claude receives --json-schema and Codex --output-schema for architect/reviewer replies; other providers are parsed leniently.",
     "resumeBudget": "An explicit resume resets the transition ceiling and grants the developer a fresh maxAttempts budget.",
-    "defaultImplementationEngine": true
+    "defaultImplementationEngine": true,
+    "openRoles": {
+      "version": 1,
+      "builtinRoles": [
+        "architect",
+        "developer",
+        "reviewer"
+      ],
+      "configField": "roles",
+      "roleIdPattern": "^[a-z][a-z0-9-]{0,63}$",
+      "access": [
+        "read",
+        "write"
+      ],
+      "artifacts": [
+        "none",
+        "tasks-checkboxes",
+        "all"
+      ],
+      "instructions": [
+        "role",
+        "none"
+      ],
+      "customAgentLoop": "free",
+      "nativeCommandUnsupported": "native_command_unsupported"
+    }
   },
   "execution": {
     "schemaVersion": 1,
     "contextEnv": "SPECRAILS_EXECUTION_CONTEXT",
-    "context": "Absolute JSON file: runId, backlogRoot, backlogPath?, artifactRoot, artifactRepositoryId, repositories[{id,name,path,baseSha?}], ownership{git,backlog,worktrees:host|core}, specs[{id,title,description,repositoryIds?,acceptanceCriteria?}]",
+    "context": "Absolute JSON file: runId, backlogRoot, backlogPath?, artifactRoot, artifactRepositoryId, repositories[{id,name,path,baseSha?,scope?}], ownership{git,backlog,worktrees:host|core}, specs[{id,title,description,repositoryIds?,acceptanceCriteria?}]. scope (runtime capability repositoryScope) lists the checkout-relative directories a repository is confined to — a package registered inside a larger checkout: commands without cwd run in the first one, model-proposed checks stay inside it, edits outside it are undone after each developer/fixer turn and reviews judge the git change set against the run base.",
     "runtime": ".specrails/runtime/pipeline.mjs",
     "operations": [
       "init",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "Agent workflow engine for specrails-desktop: provider-independent installer and programmatic agent runtime for Claude Code, Codex, Gemini CLI and Kimi Code",
   "type": "module",
   "exports": {
@@ -9,9 +9,15 @@
       "import": "./dist/agent-runtime/index.js",
       "default": "./dist/agent-runtime/index.js"
     },
+    "./agent-runtime/engine": {
+      "types": "./dist/agent-runtime/engine/index.d.ts",
+      "import": "./dist/agent-runtime/engine/index.js",
+      "default": "./dist/agent-runtime/engine/index.js"
+    },
     "./package.json": "./package.json",
     "./integration-contract.json": "./integration-contract.json",
-    "./schemas/agent-runtime.schema.json": "./schemas/agent-runtime.schema.json"
+    "./schemas/agent-runtime.schema.json": "./schemas/agent-runtime.schema.json",
+    "./schemas/workflow-definition.schema.json": "./schemas/workflow-definition.schema.json"
   },
   "bin": {
     "specrails-core": "bin/specrails-core.mjs"
@@ -25,7 +31,7 @@
     "pinned-versions.json"
   ],
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=22.22.3"
   },
   "repository": {
     "type": "git",
@@ -66,7 +72,8 @@
     "test:coverage": "npm run build && vitest run --coverage",
     "dogfood": "npm run build && node bin/specrails-core.mjs init --yes",
     "prepack": "npm run build",
-    "test:scripts": "node --test scripts/release-utils.test.mjs scripts/ci-tests.test.mjs",
+    "test:scripts": "node --test scripts/release-utils.test.mjs scripts/ci-tests.test.mjs scripts/evaluate-definition-corpus.test.mjs",
+    "test:engine-spikes": "npm run build && node scripts/run-engine-spikes.mjs",
     "check:package": "npm run build && node scripts/verify-package.mjs",
     "ci": "npm run typecheck && npm run test:scripts && npm run test:coverage && npm run check:package"
   },
@@ -76,6 +83,7 @@
     "@langchain/langgraph": "1.4.14",
     "@langchain/langgraph-checkpoint": "1.1.5",
     "@modelcontextprotocol/sdk": "1.29.0",
+    "ajv": "^8.20.0",
     "cross-spawn": "7.0.6",
     "js-yaml": "^4.1.0",
     "picocolors": "^1.1.1",
@@ -86,7 +94,6 @@
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.10.2",
     "@vitest/coverage-v8": "^4.1.5",
-    "ajv": "^8.20.0",
     "typescript": "^5.7.2",
     "vitest": "^4.1.5"
   },

package/schemas/agent-runtime.schema.json

@@ -13,7 +13,7 @@
       "verification": { "type": "object", "additionalProperties": false, "properties": { "maxConcurrency": { "type": "integer", "minimum": 1, "maximum": 4 } } }
     } },
     "guardrails": { "type": "object", "additionalProperties": false, "properties": { "plan-validation": { "type": "boolean" }, "genuine-blocking-question": { "type": "boolean" }, "plan-language-hint": { "type": "boolean" }, "frozen-plan-writes": { "type": "boolean" }, "primary-language": { "type": "boolean" }, "duplicate-sibling": { "type": "boolean" }, "one-test-per-module": { "type": "boolean" }, "empty-write": { "type": "boolean" }, "evidence-gated-ticking": { "type": "boolean" }, "inventory-retry": { "type": "boolean" }, "synthetic-corrections": { "type": "boolean" }, "silent-group-closure": { "type": "boolean" }, "verify-per-group": { "type": "boolean" }, "test-reachability": { "type": "boolean" }, "exit-code-honesty": { "type": "boolean" }, "environment-repair": { "type": "boolean" }, "lockfile-repair": { "type": "boolean" }, "verify-idle-timeout": { "type": "boolean" } } },
-    "rolePrompts": { "type": "object", "additionalProperties": false, "properties": {
+    "rolePrompts": { "type": "object", "propertyNames": { "pattern": "^[a-z][a-z0-9-]{0,63}$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 20000, "pattern": "\\S" }, "properties": {
       "architect": { "type": "string", "minLength": 1, "maxLength": 20000, "pattern": "\\S" },
       "developer": { "type": "string", "minLength": 1, "maxLength": 20000, "pattern": "\\S" },
       "reviewer": { "type": "string", "minLength": 1, "maxLength": 20000, "pattern": "\\S" },
@@ -35,6 +35,98 @@
       } }
     ] } },
     "fixer": { "$ref": "#/definitions/agent" },
+    "roles": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]{0,63}$",
+        "not": {
+          "const": "fixer"
+        }
+      },
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "provider",
+          "access",
+          "artifacts"
+        ],
+        "dependencies": {
+          "escalation": [
+            "model"
+          ]
+        },
+        "properties": {
+          "effort": {
+            "$ref": "#/definitions/effort"
+          },
+          "thinking": {
+            "type": "string",
+            "enum": [
+              "on",
+              "off"
+            ],
+            "description": "OpenAI-compatible engines only: private thinking (chat_template_kwargs.enable_thinking). Default off."
+          },
+          "escalation": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "model"
+            ],
+            "properties": {
+              "model": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 256,
+                "pattern": "^[^-\\r\\n\\u0000][^\\r\\n\\u0000]*$"
+              },
+              "effort": {
+                "$ref": "#/definitions/effort"
+              }
+            }
+          },
+          "provider": {
+            "$ref": "#/definitions/id"
+          },
+          "model": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256,
+            "pattern": "^[^-\\r\\n\\u0000][^\\r\\n\\u0000]*$"
+          },
+          "maxTurns": {
+            "$ref": "#/definitions/positiveInteger"
+          },
+          "access": {
+            "enum": [
+              "read",
+              "write"
+            ]
+          },
+          "artifacts": {
+            "enum": [
+              "none",
+              "tasks-checkboxes",
+              "all"
+            ]
+          },
+          "prompt": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 20000,
+            "pattern": "\\S"
+          },
+          "openspecSkill": {
+            "enum": [
+              "openspec-ff-change",
+              "openspec-apply-change",
+              "openspec-verify-change"
+            ]
+          }
+        }
+      }
+    },
     "agents": { "type": "object", "additionalProperties": false, "required": ["architect", "developer", "reviewer"], "properties": {
       "architect": { "$ref": "#/definitions/agent" }, "developer": { "$ref": "#/definitions/agent" }, "reviewer": { "$ref": "#/definitions/agent" }
     } },

package/schemas/workflow-definition.schema.json

@@ -0,0 +1,312 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://specrails.dev/schemas/workflow-definition/1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "id",
+    "version",
+    "title",
+    "journal",
+    "change",
+    "entry",
+    "maxTransitions",
+    "roles",
+    "nodes"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 120
+    },
+    "journal": {
+      "enum": [
+        "ledger-only",
+        "implementation"
+      ]
+    },
+    "change": {
+      "enum": [
+        "new",
+        "existing",
+        "none"
+      ]
+    },
+    "entry": {
+      "$ref": "#/$defs/nodeId"
+    },
+    "maxTransitions": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 10000
+    },
+    "budget": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "maxCostUsd": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "maxTokens": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "maxDurationMs": {
+          "type": "integer",
+          "minimum": 1000
+        }
+      }
+    },
+    "policies": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "failFast": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10,
+          "default": 2
+        },
+        "noProgress": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10,
+          "default": 2
+        },
+        "historyMaxChars": {
+          "type": "integer",
+          "minimum": 200,
+          "maximum": 20000,
+          "default": 1500
+        },
+        "concurrency": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8,
+          "default": 1
+        }
+      }
+    },
+    "roles": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/roleId"
+      },
+      "uniqueItems": true
+    },
+    "nodes": {
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": {
+        "$ref": "#/$defs/nodeId"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/node"
+      }
+    },
+    "components": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/componentBody"
+      }
+    },
+    "delivery": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "requiresVerified": {
+          "type": "boolean"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "nodeId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,119}$",
+      "not": {
+        "enum": [
+          "START",
+          "END",
+          "__start__",
+          "__end__",
+          "next"
+        ]
+      }
+    },
+    "roleId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{0,63}$"
+    },
+    "engine": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "provider"
+      ],
+      "properties": {
+        "provider": {
+          "type": "string"
+        },
+        "model": {
+          "type": "string"
+        },
+        "effort": {
+          "type": "string"
+        },
+        "thinking": {
+          "enum": [
+            "on",
+            "off"
+          ]
+        }
+      }
+    },
+    "retry": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "maxAttempts": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10
+        },
+        "backoffMs": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 600000
+        },
+        "retryOn": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "idle_timeout",
+              "timeout",
+              "provider_request_error",
+              "session_not_found",
+              "invalid_structured_output"
+            ]
+          }
+        }
+      }
+    },
+    "ends": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]{0,31}$"
+      },
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "$ref": "#/$defs/nodeId"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "node": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "params",
+        "ends"
+      ],
+      "properties": {
+        "kind": {
+          "enum": [
+            "prompt",
+            "role-turn",
+            "decider",
+            "condition",
+            "assign",
+            "verify",
+            "shell",
+            "openspec-validate",
+            "openspec-archive",
+            "approval",
+            "question",
+            "gate",
+            "map",
+            "join",
+            "component",
+            "implementation",
+            "end"
+          ]
+        },
+        "params": {
+          "type": "object"
+        },
+        "ends": {
+          "$ref": "#/$defs/ends"
+        },
+        "retry": {
+          "$ref": "#/$defs/retry"
+        },
+        "label": {
+          "type": "string",
+          "maxLength": 80
+        }
+      }
+    },
+    "componentBody": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "entry",
+        "nodes"
+      ],
+      "properties": {
+        "entry": {
+          "$ref": "#/$defs/nodeId"
+        },
+        "maxTransitions": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10000
+        },
+        "inputs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "outputs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "nodes": {
+          "type": "object",
+          "minProperties": 1,
+          "propertyNames": {
+            "$ref": "#/$defs/nodeId"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/node"
+          }
+        }
+      }
+    }
+  }
+}