specrails-core 6.0.1 → 6.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "6.0.1",
+  "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"
+          }
+        }
+      }
+    }
+  }
+}

package/templates/kimi/specrails/run-skill.mjs

@@ -231,6 +231,7 @@ export function parseRunnerArgs(argv) {
     attachmentPaths: [],
     extraPrompt: undefined,
     plainPromptStdin: false,
+    renderOnly: false,
   }
   let positionalArgs
   const seenSingleValueFlags = new Set()
@@ -251,8 +252,14 @@ export function parseRunnerArgs(argv) {
       parsed.sessionId = value
       continue
     }
+    if (token === '--render-only') {
+      if (parsed.renderOnly) throw new RunnerUsageError('--render-only may be supplied once')
+      parsed.renderOnly = true
+      continue
+    }
     if (token === PLAIN_PROMPT_STDIN_FLAG) {
-      if (parsed.plainPromptStdin) {
+      if (parsed.renderOnly && parsed.plainPromptStdin) throw new RunnerUsageError('--render-only requires a skill')
+  if (parsed.plainPromptStdin) {
         throw new RunnerUsageError(
           `${PLAIN_PROMPT_STDIN_FLAG} may be supplied once`,
         )
@@ -301,6 +308,7 @@ export function parseRunnerArgs(argv) {
     parsed.rawArgs = positionalArgs
   }
 
+  if (parsed.renderOnly && parsed.plainPromptStdin) throw new RunnerUsageError('--render-only requires a skill')
   if (parsed.plainPromptStdin) {
     for (const flag of ['--skill', '--args', '--prompt', '--attachment']) {
       if (
@@ -594,6 +602,12 @@ export async function runSkillCli(argv, dependencies = {}) {
   }
   const scriptPath = dependencies.scriptPath ?? process.argv[1]
   const providerRoot = resolveProviderRoot(scriptPath)
+  if (parsedArgs.renderOnly) {
+    const { prompt } = prepareSkillLaunch({ ...parsedArgs, providerRoot }, dependencies)
+    assertManagedPrompt(prompt)
+    ;(dependencies.writeStdout ?? (text => process.stdout.write(text)))(JSON.stringify({ prompt }) + '\n')
+    return 0
+  }
   if (parsedArgs.plainPromptStdin) {
     const readStdin =
       dependencies.readStdin ??

package/templates/commands/specrails/batch-implement.md

@@ -1,32 +0,0 @@
-# Programmatic implementation
-
-Implement the requested spec or batch through the installed agent runtime. The runtime owns architecture, development, verification, review and archive; do not delegate these phases yourself or launch a second coordinator.
-
-## Freeze the requested scope
-
-Use the supplied absolute `SPECRAILS_EXECUTION_CONTEXT` unchanged. It defines runId, specs and acceptance criteria, artifactRoot, selected repositories and ownership. For standalone use, admit the exact requested tickets once with:
-
-```sh
-node .specrails/runtime/pipeline.mjs init --change <stable-change> --tickets "<requested-ids>"
-```
-
-For a free-form request use `--scope-request <absolute-json>` with the user's specs and criteria. Use the returned absolute context path. Never select a different run by modification time or replace scope from mutable backlog. Multiple tickets share one aggregate context and one runtime invocation.
-
-## Execute
-
-```sh
-node .specrails/runtime/agent-runtime.mjs run --context <absolute-context> --config .specrails/agent-runtime.json --change <stable-change>
-```
-
-Desktop launches this runtime directly and freezes its resolved global connections and project settings. Standalone installations provide a local configuration. If required runtime/configuration files are missing, repair the Core installation; do not fall back to a prompt-orchestrated implementation.
-
-Wait for the foreground process. Report its structured status, acceptance and verification evidence. A process failure or pause preserves progress; it does not authorize a replacement run. Resume only the exact saved execution:
-
-```sh
-node .specrails/runtime/agent-runtime.mjs status --context <absolute-context>
-node .specrails/runtime/agent-runtime.mjs resume --context <absolute-context>
-```
-
-Answers, approvals and recovery flags must correspond to the pending request and user authorization. Resume keeps the saved models, scope and configuration. Never manually rewrite phase receipts, bypass review, or treat provider prose as completion.
-
-Honor the context's ownership throughout: Desktop owns worktrees, commits, PRs and backlog delivery. Runtime success prepares a reviewed candidate; host delivery remains a separate action. Preview requests must not invoke mutating execution.