specrails-core 5.3.0 → 5.4.0

package/templates/commands/specrails/implement.md

@@ -1,291 +1,32 @@
-# Implementation Pipeline
+# Programmatic implementation
 
-Implement one feature or a batch as one frozen candidate: architect designs, developer implements, reviewer validates, then the coordinator authorizes archive and delivery. Reuse completed phases only when the executable journal confirms current evidence.
+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.
 
-**Input:** $ARGUMENTS: ticket references (`#85, #71`), a feature description, area names to explore before selecting scope, `--dry-run`/`--preview`, or `--apply <change>`.
+## Freeze the requested scope
 
-## Execution scope and ownership (read first)
+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:
 
-Use the installed runtime `node "${SPECRAILS_PIPELINE_RUNTIME:-.specrails/runtime/pipeline.mjs}"`, never an assumed global/downloaded substitute. `SPECRAILS_EXECUTION_CONTEXT` identifies the authoritative schemaVersion 1 context: runId, frozen specs[] with acceptance criteria, backlogRoot/backlogPath, artifactRoot/artifactRepositoryId, selected repositories[] and ownership. Do not refetch tickets to replace this scope.
-
-The working directory may be a framework workspace. Set `SPECRAILS_REPO_DIR` to artifactRoot for `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<change>/`. Source edits and tests use the explicit selected repository ID/path; secondary tasks never default to the artifact root. Backlog belongs to backlogPath, independently of source roots.
-
-Inspect ownership **before any mutation**:
-- Host-owned worktrees: use supplied roots; no nested allocation, merge, deletion or reconstruction.
-- Host-owned git: no staging, commits, pushes, PRs or shipping CI; return the candidate for host delivery.
-- Host-owned backlog: no closing tickets/status writes; host acceptance owns completion.
-- Core ownership permits only operations authorized by the user/settings. Preview or false GIT_AUTO disables shipping regardless. Never change permissions or forge context to bypass ownership.
-
-Give every worker the absolute runtime/context paths, exact change, selected roots and frozen task group. Include env in each invocation; exports do not persist across tools. Workers stay foreground and must return terminal results. A background task start, summary or empty final message is not completion evidence.
-
-### Standalone admission
-
-Without host context, choose one stable aggregate change and freeze requested tickets once:
-
-```bash
-node "${SPECRAILS_PIPELINE_RUNTIME:-.specrails/runtime/pipeline.mjs}" init --change <change> --tickets "85,71"
-```
-
-Optional `--backlog-path <absolute-file>` selects a file under the workspace. Freeform/selected proposals use `--scope-request <absolute-file>` containing `{"specs":[{"id":"feature","title":"...","description":"...","acceptanceCriteria":["..."]}],"ownership":{"git":"host","backlog":"host","worktrees":"host"}}`. Populate real user requirements; never invent a ticket or discard scope. Complete multi-repository standalone scope uses `--context <absolute-file>`.
-
-Default fallback ownership is review-only. An explicitly authorized Core ownership request may accompany --tickets without a specs field. After init, run status and pass the returned absolute stateDir/context.json to every child/retry as SPECRAILS_EXECUTION_CONTEXT. Same-change init preserves progress and original scope; another change creates a new run. Never select the most recently modified artifact directory or use old ad-hoc state as authority.
-
-## Phase 0: Preflight
-
-1. Read supplied context or perform standalone admission. Resolve --apply to its existing journal; never silently initialize a missing preview.
-2. Confirm Node, Git, managed runtime, official OpenSpec commands/skills and project dependencies. Missing required tooling stops with a concrete repair command. Do not emulate missing skills or silently install an unpinned global.
-3. Inspect dependencies and CI commands once per selected repo; relevant package/config changes invalidate assumptions.
-4. Resolve the profile below and honor host model/effort/custom roles.
-5. Read `status --json`: a completed valid phase requires no new model call; blocked/failed phases are resumable and dependents remain pending.
-
-#### 5. Agent discovery
-
-`AVAILABLE_AGENTS` resolves through a single path: **a profile if one is active, otherwise the baseline trio**. There are no modes — the baseline is just the default value the resolution falls back to when no profile is present.
-
-##### Resolve the profile path
-
-A profile is active when either condition holds (highest precedence first):
-
-1. `SPECRAILS_PROFILE_PATH` is set AND points to a readable file. Tools like `specrails-desktop` set this to a job-scoped snapshot.
-2. `.specrails/profiles/project-default.json` exists and is readable.
-
-```bash
-if [[ -n "${SPECRAILS_PROFILE_PATH:-}" && -r "${SPECRAILS_PROFILE_PATH:-}" ]]; then
-  PROFILE_PATH="$SPECRAILS_PROFILE_PATH"
-elif [[ -r ".specrails/profiles/project-default.json" ]]; then
-  PROFILE_PATH=".specrails/profiles/project-default.json"
-else
-  PROFILE_PATH=""
-fi
-```
-
-##### No profile → baseline default
-
-When `PROFILE_PATH` is empty, `AVAILABLE_AGENTS` is the baseline trio and there are no per-agent model overrides (each agent uses the `model:` in its own `.md` frontmatter). No profile file is written — the baseline is an in-memory default, honoring the reserved-paths contract (`.specrails/profiles/**` is never created by the pipeline):
-
-```bash
-if [[ -z "$PROFILE_PATH" ]]; then
-  AVAILABLE_AGENTS="$(printf '%s\n' sr-architect sr-developer sr-reviewer)"
-  PROFILE_NAME=""
-fi
-```
-
-##### Profile present → load, validate, populate
-
-`jq` is required to read a profile JSON:
-
-```bash
-command -v jq >/dev/null 2>&1 || { echo "[error] 'jq' is required to read a profile. Install with: brew install jq / apt install jq / https://stedolan.github.io/jq/"; exit 1; }
-PROFILE="$(cat "$PROFILE_PATH")"
-```
-
-Validate the schema version. Only `schemaVersion: 1` is supported:
-
-```bash
-SCHEMA_VERSION="$(jq -r '.schemaVersion // empty' <<<"$PROFILE")"
-case "$SCHEMA_VERSION" in
-  1) ;;
-  "") echo "[error] profile validation failed: missing required field 'schemaVersion'"; exit 1 ;;
-  *) echo "[error] profile validation failed: unsupported schemaVersion '$SCHEMA_VERSION'. Supported: 1"; exit 1 ;;
-esac
-```
-
-Validate required top-level fields. Every valid v1 profile MUST contain `name`, `orchestrator.model`, `agents` (non-empty array), and `routing` (non-empty array):
-
-```bash
-for field in name orchestrator agents routing; do
-  jq -e ".$field" <<<"$PROFILE" >/dev/null 2>&1 || { echo "[error] profile validation failed: missing required field '$field'"; exit 1; }
-done
-jq -e '.orchestrator.model' <<<"$PROFILE" >/dev/null 2>&1 || { echo "[error] profile validation failed: missing required field 'orchestrator.model'"; exit 1; }
-jq -e '.agents | length > 0' <<<"$PROFILE" >/dev/null 2>&1 || { echo "[error] profile validation failed: 'agents' must be a non-empty array"; exit 1; }
-jq -e '.routing | length > 0' <<<"$PROFILE" >/dev/null 2>&1 || { echo "[error] profile validation failed: 'routing' must be a non-empty array"; exit 1; }
-```
-
-Validate baseline agents — `sr-architect`, `sr-developer`, and `sr-reviewer` MUST appear in `agents[]`:
-
-```bash
-for required in sr-architect sr-developer sr-reviewer; do
-  jq -e --arg id "$required" '[.agents[].id] | index($id)' <<<"$PROFILE" >/dev/null 2>&1 \
-    || { echo "[error] profile validation failed: required baseline agent '$required' missing from 'agents[]'"; exit 1; }
-done
+```sh
+node .specrails/runtime/pipeline.mjs init --change <stable-change> --tickets "<requested-ids>"
 ```
 
-Validate routing terminal rule — exactly one entry SHALL have `default: true` and it MUST be the last element:
-
-```bash
-DEFAULT_COUNT="$(jq '[.routing[] | select(.default == true)] | length' <<<"$PROFILE")"
-if [[ "$DEFAULT_COUNT" -ne 1 ]]; then
-  echo "[error] profile validation failed: routing must contain exactly one entry with 'default: true' (found $DEFAULT_COUNT)"; exit 1
-fi
-IS_LAST="$(jq '(.routing | last | .default) == true' <<<"$PROFILE")"
-if [[ "$IS_LAST" != "true" ]]; then
-  echo "[error] profile validation failed: the 'default: true' routing rule must be the last element of 'routing'"; exit 1
-fi
-```
+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.
 
-Populate `AVAILABLE_AGENTS` from the profile. The three baseline agents are **hard-required**: if a baseline agent's file is missing, STOP. A **non-baseline** agent whose file is missing is **warned and skipped** — this is how a pre-v5 profile that still references a removed agent (e.g. `sr-frontend-developer`) degrades gracefully:
+## Execute
 
-```bash
-AVAILABLE_AGENTS=""
-for id in $(jq -r '.agents[].id' <<<"$PROFILE" | sort); do
-  if [[ -f ".claude/agents/$id.md" ]]; then
-    AVAILABLE_AGENTS="$AVAILABLE_AGENTS$id"$'\n'
-  elif [[ "$id" == "sr-architect" || "$id" == "sr-developer" || "$id" == "sr-reviewer" ]]; then
-    echo "[error] Core agent $id not found. Run npx specrails-core update to reinstall."; exit 1
-  else
-    echo "[warn] profile references agent '$id' but no agent file exists — skipping (removed in v5; use a custom-* agent)"
-  fi
-done
-AVAILABLE_AGENTS="$(printf '%s' "$AVAILABLE_AGENTS" | sed '/^$/d')"
+```sh
+node .specrails/runtime/agent-runtime.mjs run --context <absolute-context> --config .specrails/agent-runtime.json --change <stable-change>
 ```
 
-Also store per-agent model overrides and the orchestrator model for use in later phases:
+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.
 
-```bash
-# ORCHESTRATOR_MODEL is informational; the caller is responsible for spawning
-# the orchestrator with this model (e.g. specrails-desktop reads this field directly).
-ORCHESTRATOR_MODEL="$(jq -r '.orchestrator.model' <<<"$PROFILE")"
+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:
 
-# Per-agent model overrides keyed by agent id.
-# Consumed by subagent invocation sites in later phases.
-declare -A AGENT_MODEL
-while IFS=$'\t' read -r id model; do
-  [[ -n "$model" && "$model" != "null" ]] && AGENT_MODEL[$id]="$model"
-done < <(jq -r '.agents[] | [.id, (.model // "null")] | @tsv' <<<"$PROFILE")
-
-# Routing rules (array), consumed by Phase 3b.
-ROUTING="$(jq '.routing' <<<"$PROFILE")"
-
-PROFILE_NAME="$(jq -r '.name' <<<"$PROFILE")"
+```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.
 
-##### Invocation configuration
-
-Forward resolved models through supported per-invocation configuration; never rewrite shared agent frontmatter or profiles. If an override cannot be honored, report that limitation, not a false model claim. The caller selects the orchestrator model before launch.
-
-Route task groups by the first matching rule and final default. Missing optional targets fall through to default. Custom roles assist a canonical phase; they never bypass its acceptance gate. The baseline trio is required.
-
-## Durable phases and verification
-
-Use `architect → developer → reviewer → archive → ship → ci`. Start a phase with running; only actual completion and its runtime gate permit done. Failed/blocked needs a concrete reason. Reopening resets dependent completion. Never skip an implementation phase because its predecessor failed.
-
-```bash
-node "${SPECRAILS_PIPELINE_RUNTIME:-.specrails/runtime/pipeline.mjs}" phase --phase architect --status running
-node "${SPECRAILS_PIPELINE_RUNTIME:-.specrails/runtime/pipeline.mjs}" phase --phase architect --status done
-node "${SPECRAILS_PIPELINE_RUNTIME:-.specrails/runtime/pipeline.mjs}" phase --phase reviewer --status blocked --reason "Unresolved acceptance condition"
-```
-
-Store check requests/notes under stateDir, not as candidate files. Verification is executable argv:
-
-```json
-{"kind":"full","commands":[{"repositoryId":"primary","command":"npm","args":["test"],"cwd":"/absolute/selected/repo","env":{"CI":"1"},"timeoutMs":900000}]}
-```
-
-```bash
-node "${SPECRAILS_PIPELINE_RUNTIME:-.specrails/runtime/pipeline.mjs}" verify --request <stateDir/full-checks.json>
-```
-
-Derive actual CI-equivalent checks from each selected repository's scripts/config/workflows. The example is not universal. Full requests cover every selected root and required cross-repository integration; scoped requests target repair cycles. The runtime executes commands and binds exits/output, command/argv/cwd/environment identity to frozen scope and actual candidate, including additions and deletions.
-
-Reuse a full receipt only while status.verification.valid is true **and recorded commands cover the required checks**. Baseline-only/stale evidence cannot certify changes. After candidate edits, use scoped repairs and one fresh final full pass. Command success still needs semantic acceptance review; do not replace it with another full-suite run.
-
-## Phase 1: Architect
-
-Start architect if required by resumePhase, then invoke sr-architect once with specName and aggregate frozen scope/roots. Use the actual `Skill("opsx:ff", "<change>")` workflow (or provider-native equivalent) for `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<change>/`.
-
-One design covers shared contracts, explicit repository task ownership, integration order and acceptance. Batch tickets are dependency-ordered task groups within this change, not separate full pipelines. Validate existing Modify paths and genuinely new Create paths against selected roots; do not reject a plan by a percentage-of-paths-exist heuristic.
-
-Require proposal/design/specs/tasks and medium/high design-confidence.json. Missing, malformed or low confidence blocks development with the unresolved issue. The runtime checks this before architect done. Reuse valid design after interruption; task checkbox progress does not invalidate its contract.
-
-## Phase 2: Developer
-
-Invoke sr-developer or profile-routed roles with immutable task groups and official `Skill("opsx:apply", "<change>")`. Serialize dependent/shared-file groups in supplied candidate roots. Read-only investigations may run concurrently, but collect every result; no recursive full pipeline or colliding writers.
-
-Keep real checked task progress. Use meaningful scoped regressions during implementation and bounded repairs (at most two unsuccessful cycles per issue, then a concrete blocker). After all aggregate tasks finish, run one full CI-equivalent request. Runtime developer done requires completed tasks and current actual evidence.
-
-Supplied roots already contain the candidate: inspect additions, renames and deletions there. Do not copy changed-file lists over another checkout, patch against an assumed main branch or force-remove worktrees.
-
-## Phase 3: Reviewer and confidence
-
-Invoke sr-reviewer once with the context, exact specName, candidate summary and receipt. Map every frozen requirement to code and behavioral evidence. Existing green tests with missing implementation mean incomplete, not PASS.
-
-Reuse unchanged full evidence; run cheap static/scoped checks as needed. Any review edit requires one fresh full request after all fixes. Security, acceptance gaps, missing required regressions, untested critical side effects or unchecked tasks block acceptance.
-
-Before archive, write `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<change>/confidence-score.json` with canonical change, overall and five numeric aspects. Require overall ≥70, security ≥75, other aspects ≥60; stricter configured thresholds still apply. Missing/malformed score fails closed; a numeric average never overrules an explicit blocker.
-
-Normal reviewer returns acceptance/security verdict and confidence **without archiving**. Validate SECURITY_STATUS, task completion and acceptance, then runtime reviewer done. A human-facing PASS alone is insufficient.
-
-## Phase 4: Archive after approval
-
-```bash
-node "${SPECRAILS_PIPELINE_RUNTIME:-.specrails/runtime/pipeline.mjs}" archive-check
-```
-
-Approval binds candidate, requirements and exact confidence bytes. Invoke reviewer with ARCHIVE_ONLY=true and ARCHIVE_AUTHORIZED=true, or execute the equivalent official workflow in the coordinator. No rescoring/code edits after approval. Run the Skill from `${SPECRAILS_REPO_DIR:-.}`:
-
-```
-Skill("opsx:archive", "<change>")
-```
-
-Confirm active artifacts moved and canonical specs synced, then record archive done. Do not emulate with file moves or automatically accept incomplete-task prompts. Failure is a resumable archive blocker, not permission to redevelop or reship.
-
-## Phase 5: Delivery and backlog
-
-Host-owned git: only ship/ci may be skipped; return ready-for-delivery evidence. Host-owned backlog stays untouched until host acceptance.
-
-For explicitly Core-owned git and GIT_AUTO=true, use the project's shipping workflow in each correct selected repo, staging only reviewed candidate changes. Preserve unrelated preexisting work. Record real commits/PRs and CI results per repository; partial delivery is not whole-batch success. CI-only retry checks existing delivery and does not ship again.
-
-Only Core-owned backlog can close after all required delivery succeeds. First compare live ticket requirements against frozen scope; changed requirements remain open with the conflict reported. Failures preserve open tickets and resumable phase details.
-
-## Preview and apply
-
---dry-run/--preview prepares bytes under stateDir without source edits/shipping/backlog writes. Manifest entries are `{repositoryId,path,operation:"write"|"delete",sourcePath?}`; targets are repository-relative. Record with `preview --request <stateDir/preview-request.json>`. Report **UNVERIFIED PREVIEW**; tests on untouched code describe only baseline.
-
---apply resumes the exact journal and calls `apply-preview --request <stateDir/full-checks.json>`. Runtime rejects stale base/cache, applies exact additions/edits/deletions and executes checks on the actual candidate. Failed checks retain reviewable applied work without success evidence. Continue developer task completion, reviewer/confidence and archive gates; never skip directly to shipping.
-
-## Completion
-
-Report run/change, frozen tickets/roots, phase statuses, actual receipt commands, acceptance, confidence, archive and per-repository delivery. Distinguish reused evidence, newly executed checks and gaps. Keep failure excerpts bounded and refer to durable receipts. Missing workers, failed gates or incomplete required repositories stay blocked/failed, never falsely complete.
-
-
-### Acceptance evidence and completion
-
-After development, normal review MUST write `stateDir/acceptance.json` and run
-`acceptance --request <absolute-path>` before `phase --phase reviewer --status done`.
-The request is `{criteria: [...], checks: [...], findings: [...]}`:
-- Each criterion has `specId` (string), `criterionIndex` (zero-based), `requirement`
-  (exact frozen text), `status` (`met`, `exception`, `blocked`, `pending`) and a
-  nonempty `evidence` array of concrete code/test/capture references and observations.
-  Cover every frozen acceptance criterion once. If a spec has no explicit criteria,
-  use its complete frozen description (or title if empty) at index 0.
-- An `exception` MUST include `{reason, impact, material, acceptedBy, approvalEvidence}`.
-  `acceptedBy` is `reviewer`, `user`, or `host`. Material scope changes require actual
-  user/host authorization; do not invent approval or label material changes minor.
-  Previously authorized decisions need no new confirmation. Unresolved requirements
-  remain `blocked` or `pending`, never `met` through a rewritten interpretation.
-- Each check has `{name, status, required, evidence, scope, limitations}`; status is
-  `passed`, `failed`, or `unavailable`. Include required and supplementary checks from
-  the design. Record the original required classification; never downgrade a failed
-  check to make the gate pass. For benchmarks state what is measured and excluded:
-  a Node microbenchmark does not establish browser Canvas/GPU/frame performance.
-- `findings` lists concrete review conclusions, risks and resolutions; use an empty
-  array only when no findings remain. Numeric confidence cannot replace this report.
-
-The runtime binds this evidence to frozen scope, source and design. Missing/stale
-acceptance or unresolved requirements/required checks block review and archive.
-Accepted exceptions and supplementary failures produce `with-exceptions` validation.
-Replacing the report requires review and archive authorization again; a green command
-receipt alone is insufficient. Evidence references and approval attribution remain
-reviewer assertions, not independently authenticated proof of human approval.
-
-Keep operational completion notes, check requests and reports in `stateDir` from
-start to finish. Run scoped checks for repairs and one final full verification after
-all edits. Reuse that full receipt while runtime status says it is valid and its
-commands cover required checks. New prose/phase handoffs alone do not warrant reruns.
-
-End with ONE concise summary from runtime `status.completion`: implementation,
-validation (including exceptions), archive, delivery, and evidence references.
-Host-owned delivery stays `pending-host`; do not call uncommitted files "landed".
-Report phase durations/attempts from `status.phases`; report per-phase cost only when
-provider telemetry attributes it, otherwise unavailable. Do not invent cost splits.
+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.

package/templates/commands/specrails/retry.md

@@ -1,38 +1,10 @@
-# Retry an Implementation Pipeline
+# Resume a programmatic implementation
 
-**Input:** $ARGUMENTS — existing change and optional --from <phase>.
+Resolve the exact saved context for the requested run. Do not initialize a replacement, guess the latest change, or discard work.
 
-## Resolve the exact run
-
-Use the same absolute SPECRAILS_PIPELINE_RUNTIME and SPECRAILS_EXECUTION_CONTEXT. The managed fallback is .specrails/runtime/pipeline.mjs; the standalone workspace pointer is only discovery. Do not initialize another run, choose the newest change, replace frozen tickets from mutable backlog, or trust old ad-hoc pipeline state.
-
-```bash
-node "${SPECRAILS_PIPELINE_RUNTIME:-.specrails/runtime/pipeline.mjs}" status --json
+```sh
+node .specrails/runtime/agent-runtime.mjs status --context <absolute-context>
+node .specrails/runtime/agent-runtime.mjs resume --context <absolute-context>
 ```
 
-Verify runId/change match. Preserve context.specs, selected roots, backlog identity and ownership. The artifact compatibility root is `${SPECRAILS_REPO_DIR:-.}`, not necessarily the framework workspace.
-
-## Resume earliest invalid evidence
-
-Follow resumePhase and receipt reasons. Completed valid phases require no model call. Blocked/failed is resumable; never convert dependent implementation into skipped. Explicit --from can reopen an earlier phase, but runtime prerequisite checks still apply.
-
-```bash
-node "${SPECRAILS_PIPELINE_RUNTIME:-.specrails/runtime/pipeline.mjs}" phase --phase <phase> --status running
-```
-
-| Phase | Resume action |
-|-------|---------------|
-| architect | Repair official design artifacts/confidence; unblock development only after actual gate passes. |
-| developer | Continue unchecked tasks, retain completed code; scoped repairs followed by one full receipt. |
-| reviewer | Review acceptance/confidence; reuse current full evidence, refresh after edits. Do not redo valid architecture because review was blocked. |
-| archive | Fresh archive-check, then authorized official archive/sync only; preserve approved confidence bytes. |
-| ship | Only Core-owned and authorized; resume missing repository delivery without duplicating successful commits/PRs. |
-| ci | Check existing delivery; never reship merely because CI needs retry. |
-
-Only host-owned ship/ci may skip. Actual done clears old reason; failed/blocked records concrete remaining work. Reopening invalidates dependent completion.
-
-## Evidence and report
-
-Use the implement contracts for command receipts, foreground worker completion and exact repository routing. Receipt validity plus required command coverage permits reuse; baseline-only or stale evidence does not. Preview apply must check base/cache and execute checks on actual applied source.
-
-Confidence, acceptance and archive approval precede delivery. Preserve host-owned Git/worktrees/backlog. Return current state, reused/new evidence and per-repository outcomes. If all phases remain valid, report completion without rerunning.
+Use the saved scope and configuration. Pass an answer, approval or recovery flag only for the corresponding pending request with user authorization. The runtime selects the next phase and preserves valid completed work; never invoke roles directly or edit phase receipts. Preserve host ownership of Git, worktrees and backlog. Report the structured result and outstanding delivery actions.

package/templates/gemini-commands/batch-implement.toml

@@ -1,31 +1,37 @@
-description = "Aggregate batch implementation with one durable journal and final candidate gates."
+description = "Programmatic implementation with durable recovery."
 
 prompt = '''
-Resolve all target IDs or filters and freeze their complete descriptions,
-acceptance criteria and repository IDs. With a host context preserve context.specs
-unchanged. Resolve source/artifact/backlog roots explicitly; cwd can be external.
-
-Initialize ONE aggregate OpenSpec change and journal for this runId. Never create
-per-ticket child changes/journals with the same context. Read
-`.gemini/commands/specrails/implement.toml` and apply its capability preflight,
-explicit invoke_agent(agent_name,prompt) handoff, progress-bound continuation and
-gates to the whole batch:
-
-1. One architect designs all tickets, groups tasks by ticket/repository and
-   dependency order, validates OpenSpec and high/medium design confidence.
-2. One developer implements groups sequentially, persisting progress in tasks.md.
-   Use scoped checks per group and one full helper verification for the aggregate
-   candidate before developer done. Incomplete groups remain retriable.
-3. One reviewer checks every acceptance criterion and cross-ticket interaction;
-   pass all frozen specs, changed paths and the full receipt. Ordinary review
-   never archives. At most one exact-findings developer repair plus re-review.
-4. After clean semantic reviewer done, run archive-check; only success authorizes
-   reviewer archive-only mode. Verify the archive and record archive done. Only
-   then close ALL Core-owned tickets, or report results to the owning host.
-
-Run these roles directly at root, no nested implement coordinator. Retry resumes
-this aggregate journal without repeating valid phases. A --parallel preference
-never overrides host ownership, unknown capacity or overlapping mutation paths;
-use sequential execution and report it honestly. Final output lists each ticket,
-aggregate verification/archive status and unresolved task groups; no partial done.
+# 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.
+
 '''

package/templates/gemini-commands/implement.toml

@@ -1,58 +1,37 @@
-description = "Implementation with durable phase checkpoints and explicit Gemini role handoffs."
+description = "Programmatic implementation with durable recovery."
 
 prompt = '''
-You are the implement orchestrator. Delegate role work to `invoke_agent` using
-only its supported fields: `agent_name` and `prompt`. Do not claim session-based
-resume: each invocation may start a fresh executor and conversation.
-
-For multiple ticket IDs, read `.gemini/commands/specrails/batch-implement.toml`
-and execute it at this root with the same context; do not ask the user to resend.
-For one ticket or free-form input, use the stages below.
-
-0. Preflight: require the named sr-architect, sr-developer and sr-reviewer tools,
-   and readable `.gemini/skills/openspec-{ff,apply,archive}-change/SKILL.md` in
-   the execution workspace. Roles must expose `activate_skill`. If a capability
-   is absent, record blocked with the exact missing role/skill and request Core
-   refresh; do not silently switch to a generic agent or implement inline.
-   Resolve `${SPECRAILS_REPO_DIR:-.}` only as a legacy fallback. The shared helper
-   returns the actual repositories, artifactRoot and frozen ticket descriptions.
-
-1. DESIGN: record architect running, invoke sr-architect with an explicit prompt
-   containing runId, phase, current ticket/full frozen acceptance criteria,
-   repository IDs and absolute roots, artifactRoot, change slug and prior artifact
-   paths. Require validated OpenSpec proposal/design/specs/tasks and a non-low
-   design-confidence.json. Missing confidence is blocked, never implicit success.
-   Record architect done only after those checks.
-
-2. APPLY: record developer running; invoke sr-developer with the SAME scope plus
-   change slug, plan/tasks paths, unfinished tasks, prior findings and next action.
-   Developer runs verification through the managed helper to produce a candidate-
-   bound full receipt. Unchecked tasks or missing implementation block handoff,
-   even when unrelated baseline tests pass. Record developer done after evidence.
-
-3. REVIEW: invoke sr-reviewer with the complete explicit handoff, changed files,
-   verification receipt and acceptance criteria. Ordinary review must NOT archive.
-   Require its semantic verdict and confidence artifact; PASS alone without these
-   artifacts is insufficient. On changes requested, give the exact findings to
-   developer and re-review, with at most one fix round. Record reviewer done only
-   for a clean semantic result. Preserve blockers and incomplete work for retry.
-
-4. ARCHIVE: run `archive-check`; only success permits a new sr-reviewer invocation
-   with ARCHIVE_ONLY=true and ARCHIVE_AUTHORIZED=true plus the same handoff. Verify
-   that the active change is gone and its archive exists, then record archive done.
-   If the combined gate or archive fails, leave the ticket open and record failure.
-   Only Core-owned backlog may be updated to done; hosted runs report to Desktop.
-
-For EVERY invocation: `MAX_TURNS`, timeout, missing verdict, or early return is
-incomplete work. Read the on-disk checkpoint and compare task/file/evidence
-progress, then re-invoke the SAME role with an updated explicit prompt. At most
-two continuations per phase, and stop earlier when no progress was recorded.
-Never substitute orchestration memory for the handoff. Native turn limits are
-optional capabilities: use only fields accepted by the installed loader; if
-unknown, retain its defaults and use these bounded continuations.
-
-Record all stage outcomes with the shared helper, including blocked/failed.
-Retry reads that journal, not legacy .gemini/pipeline-state prose snapshots.
-Report actual phase outcomes and evidence; never equate tool completion with
-implemented behavior or close after an ambiguous review.
+# 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.
+
 '''

package/templates/gemini-commands/retry.toml

@@ -1,21 +1,15 @@
-description = "Resume incomplete Gemini phases from the shared executable journal."
+description = "Programmatic implementation with durable recovery."
 
 prompt = '''
-Call the installed pipeline helper `status` for the requested change and run.
-Use its `context`, `resumePhase`, phases and verification to select the earliest
-invalid phase. If legacy artifacts have no journal, initialize without deleting
-work and validate each claimed completed phase before recording it.
+# Resume a programmatic implementation
 
-Read `.gemini/commands/specrails/implement.toml` and drive its remaining role
-stages directly through invoke_agent(agent_name, prompt). Do not spawn another
-implement orchestrator. Every call starts with the full bounded handoff including
-frozen acceptance criteria, all repository paths, artifactRoot, change/plan/tasks,
-last result and next action. Do not assume native session continuity or `.gemini`
-legacy pipeline-state files. A blocked phase is retriable, not intentionally skipped.
+Resolve the exact saved context for the requested run. Do not initialize a replacement, guess the latest change, or discard work.
+
+```sh
+node .specrails/runtime/agent-runtime.mjs status --context <absolute-context>
+node .specrails/runtime/agent-runtime.mjs resume --context <absolute-context>
+```
+
+Use the saved scope and configuration. Pass an answer, approval or recovery flag only for the corresponding pending request with user authorization. The runtime selects the next phase and preserves valid completed work; never invoke roles directly or edit phase receipts. Preserve host ownership of Git, worktrees and backlog. Report the structured result and outstanding delivery actions.
 
-Do not repeat completed valid design/development after a reviewer failure. If
-review actually requires code changes, record developer running and pass the exact
-findings. Follow the same progress-bound continuation and one-round repair limits.
-Archive-check must succeed before reviewer archive-only authorization. Preserve
-host ownership and report unresolved work honestly with its durable resume point.
 '''