specrails-core 6.0.1 → 6.2.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"
       }
     }
@@ -110,14 +116,14 @@
     "file": ".specrails/install-config.yaml",
     "version": 1,
     "fields": {
-      "version": "number — schema version, currently 1",
-      "provider": "string — claude | codex | gemini | kimi",
+      "version": "number \u2014 schema version, currently 1",
+      "provider": "string \u2014 claude | codex | gemini | kimi",
       "tier": "Deprecated legacy string, tolerated and ignored; all installs use deterministic placement.",
-      "agents.selected": "string[] — unique lowercase kebab-case agent ids to install (1-64 characters)",
-      "agents.excluded": "string[] — unique lowercase kebab-case agent ids to skip; must not overlap agents.selected",
-      "models.preset": "string — balanced | budget | max; resolved within the selected provider catalog",
-      "models.defaults.model": "string — exact provider model id or configured alias (overrides preset; Kimi: 1-128 characters matching [A-Za-z0-9][A-Za-z0-9._/:-]*; default: k3)",
-      "models.overrides": "Record<safe-agent-id, string> — exact per-agent provider model ids or configured aliases with the same provider-specific validation (highest priority)"
+      "agents.selected": "string[] \u2014 unique lowercase kebab-case agent ids to install (1-64 characters)",
+      "agents.excluded": "string[] \u2014 unique lowercase kebab-case agent ids to skip; must not overlap agents.selected",
+      "models.preset": "string \u2014 balanced | budget | max; resolved within the selected provider catalog",
+      "models.defaults.model": "string \u2014 exact provider model id or configured alias (overrides preset; Kimi: 1-128 characters matching [A-Za-z0-9][A-Za-z0-9._/:-]*; default: k3)",
+      "models.overrides": "Record<safe-agent-id, string> \u2014 exact per-agent provider model ids or configured aliases with the same provider-specific validation (highest priority)"
     }
   },
   "checkpoints": {
@@ -229,9 +235,21 @@
       "validate",
       "run",
       "status",
-      "resume"
+      "resume",
+      "prompts",
+      "capabilities",
+      "evidence",
+      "recovery",
+      "evaluate",
+      "workflows",
+      "fork",
+      "signal",
+      "cancel"
+    ],
+    "cliPresentationOperations": [
+      "help"
     ],
-    "apiOperation": "runtime api emits {type: runtime-api, apiVersion, coreVersion}; does not invoke providers",
+    "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 +259,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 +278,7 @@
     "phases": [
       "architect",
       "developer",
+      "fixer",
       "verify",
       "reviewer",
       "archive"
@@ -277,19 +296,92 @@
     "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": 7
+    },
+    "nodeKinds": [
+      "prompt",
+      "role-turn",
+      "decider",
+      "verify",
+      "shell",
+      "artifact-contract",
+      "openspec-validate",
+      "openspec-archive",
+      "condition",
+      "end",
+      "approval",
+      "question",
+      "gate",
+      "assign",
+      "implementation-step",
+      "component",
+      "map",
+      "implementation",
+      "join"
+    ],
+    "implementationSteps": {
+      "version": 1,
+      "kind": "implementation-step",
+      "ownership": "Host definitions compose phases and freeze role definitions; Core executes individual operations and evidence gates"
+    },
+    "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": true
+      }
+    ],
     "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"
+    },
+    "workflowAgentSteps": {
+      "version": 1,
+      "ownership": "Host-defined roles, schemas and gates; Core provides scoped artifact contracts and verified candidate guards"
+    }
   },
   "execution": {
     "schemaVersion": 1,
     "contextEnv": "SPECRAILS_EXECUTION_CONTEXT",
-    "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.",
+    "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 \u2014 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,7 +1,7 @@
 {
   "name": "specrails-core",
-  "version": "6.0.1",
-  "description": "Agent workflow engine for specrails-desktop: provider-independent installer and programmatic agent runtime for Claude Code, Codex, Gemini CLI and Kimi Code",
+  "version": "6.2.0",
+  "description": "Agent workflow engine for specrails-desktop: provider-independent installer and programmatic agent runtime for Claude Code and Codex",
   "type": "module",
   "exports": {
     "./agent-runtime": {
@@ -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" }
     } },