specrails-core 5.3.0 → 5.4.0

package/templates/codex-skills/batch-implement/SKILL.md

@@ -1,63 +1,38 @@
 ---
 name: batch-implement
-description: "Implement the frozen batch in one OpenSpec change and journal, with aggregate verification, review and archive gates."
+description: "Run or resume implementation through the installed programmatic agent runtime."
 license: MIT
-compatibility: "Codex-native root-level role delegation. One aggregate change per run; hosted worktrees stay under host ownership."
 ---
 
-You coordinate one batch run. Explicit #IDs retain their order; filters resolve
-against the shared backlog. Freeze the full ticket descriptions, acceptance criteria
-and repository IDs once. With host context use its complete specs unchanged.
-
-Initialize ONE stable aggregate change slug and journal for the batch. Do not
-initialize another change with the same runId or create child per-ticket journals.
-Resolve source via context.repositories, OpenSpec via context.artifactRoot, and
-backlog via context.backlogPath/backlogRoot; cwd can be an external workspace.
-
-Read the single implement role instructions, but execute the following aggregate
-pipeline DIRECTLY from this root. Do NOT spawn `$implement` as a sub-agent.
-Each role receives the explicit bounded handoff including ALL frozen specs and
-repository paths, aggregate change slug and already completed task groups.
-
-1. Architect: one `$sr-architect` creates and validates one change covering every
-   ticket, grouping tasks by ticket and repository and recording dependency order.
-   Record architect running/done via the helper. Require high/medium design
-   confidence. Missing or low confidence blocks development; never infer a pass.
-2. Developer: one `$sr-developer` applies the task groups sequentially, preserving
-   preceding groups and all repositories. Persist per-group progress in tasks.md
-   before yielding. Scoped checks run per group; the full verification gate runs
-   once for the aggregate candidate through the helper. Only then record developer
-   done. Incomplete groups block downstream review and remain retriable.
-3. Reviewer: one `$sr-reviewer` semantically checks every ticket/criterion and
-   cross-ticket interaction. Include the full receipt and changed-file inventory.
-   Ordinary review does NOT archive. If recoverable findings need changes, invoke
-   developer once with the exact findings and re-review. Missing/ambiguous verdicts
-   and stale receipts never become done; record blocked/failed with a next action.
-4. Archive: after semantic reviewer done and canonical confidence thresholds from
-   implement pass (including security), run `archive-check`. Only success permits
-   `$sr-reviewer` with ARCHIVE_ONLY=true and ARCHIVE_AUTHORIZED=true. Validate the
-   archive exists and active change is absent; record archive done. Failure leaves
-   EVERY batch ticket open.
-5. Delivery/CI: follow implement ownership exactly. Host-owned Git records ship/ci
-   skipped and returns evidence; Core-owned authorized delivery records each selected
-   repository outcome and required CI. Partial delivery keeps the batch incomplete.
-6. Backlog: only Core-owned backlog may close participating tickets at
-   context.backlogPath after required delivery and live-vs-frozen requirements match.
-   Preserve unrelated data and revisions. Host-owned backlog stays untouched.
-
-Before any role, inspect status.resumePhase; reuse every still-valid phase without
-respawning. Use available worker capabilities and capability-aware cleanup from
-implement; never invent close_agent or native model override support.
-
-On a provider turn limit, continue the same role from explicit saved progress;
-never launch a nested coordinator or repeat valid earlier stages. Retry resumes
-this same aggregate change/journal. Two continuations without progress block.
-
-`--parallel` is a preference, not permission to create unmanaged worktrees or
-assume ten available agent slots. The aggregate pipeline is sequential by default;
-keep hosted worktrees in the supplied repositories. Do not claim parallel work
-when it did not run. Do not override models on a full-history fork.
-
-Report one table with every ticket and actual implemented/reviewed outcome, the
-aggregate verification receipt, archive result and outstanding groups. No ticket
-is done until the whole aggregate close succeeds.
+# 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/codex-skills/implement/SKILL.md

@@ -1,141 +1,38 @@
 ---
 name: implement
-description: "Implement one frozen spec or route multiple specs to an aggregate pipeline, with resumable design, implementation, verification, review, archive and ownership-aware delivery."
+description: "Run or resume implementation through the installed programmatic agent runtime."
 license: MIT
-compatibility: "Codex-native role delegation with explicit handoffs and the installed SpecRails pipeline runtime. Use only capabilities exposed by the host."
 ---
 
-You coordinate the implementation. Role skills supply design, coding and review
-instructions; the installed runtime supplies immutable scope, phase status and
-actual verification evidence. A completed valid phase needs no new model call.
+# Programmatic implementation
 
-**Input:** `$implement #N`, `$implement #N --yes`, a free-form description, or
-multiple `#N` references. More than one ID routes directly to
-`.codex/skills/batch-implement/SKILL.md` with the original arguments and complete
-frozen context. Do not ask the user to resend or spawn a nested implement.
+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.
 
-## Admission and capabilities
+## Freeze the requested scope
 
-Follow the executable pipeline contract above. Initialize the one stable change
-with supplied context, explicit ticket IDs, or a free-form scope request; then
-read `status`. Do not initialize another run on retry or replace frozen requirements
-with live ticket text. OpenSpec lives under `context.artifactRoot`; the compatibility
-path `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/` applies only after resolving
-that variable to artifactRoot. Source/tests use the selected repository ID/path;
-backlog uses `context.backlogPath`, independent of cwd.
+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:
 
-Discover `.codex/skills/rails/` and require sr-architect, sr-developer and
-sr-reviewer. Validate any explicit profile (`SPECRAILS_PROFILE_PATH`, otherwise the
-project's configured default): schemaVersion 1, baseline trio, routing/default and
-referenced installed roles. Only installed custom-* roles may supplement or fulfill
-a routed task group; they do not bypass the canonical phase gates.
+```sh
+node .specrails/runtime/pipeline.mjs init --change <stable-change> --tickets "<requested-ids>"
+```
 
-Use the host's actual `spawn_agent`, `send_message` and `wait_agent` signatures.
-Invoke required architect/developer/reviewer roles as real workers and collect their
-terminal outcomes. Full-history forks inherit the current model; do not pass model
-or reasoning overrides unsupported by that fork mode. Report unsupported profile
-model overrides honestly. Use `close_agent` only when that capability exists and
-only after the worker finished; never invent a cleanup tool or interrupt running
-work to simulate completion. Avoid parallel writers in shared candidate roots.
+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.
 
-Every worker receives its `$sr-*` skill and the explicit bounded handoff: runId,
-phase, absolute runtime/context paths, all frozen criteria, repository ownership,
-change/plan/tasks paths, prior outcome and next action. Do not rely on inherited
-conversation memory. A task start, turn limit or process exit alone is not success.
-Continue from durable progress; two continuations without progress become blocked.
+## Execute
 
-## Durable phases
+```sh
+node .specrails/runtime/agent-runtime.mjs run --context <absolute-context> --config .specrails/agent-runtime.json --change <stable-change>
+```
 
-`architect → developer → reviewer → archive → ship → ci`
+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.
 
-Follow `status.resumePhase`. Start required work with the helper's
-`phase --phase <phase> --status running`. Record done only after validating actual
-outcomes and runtime gates. Record blocked/failed with a concrete reason; dependent
-phases remain incomplete. Reopening a phase invalidates dependent completion.
-If every phase is valid, report existing completion without new worker calls.
+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:
 
-### Architect
+```sh
+node .specrails/runtime/agent-runtime.mjs status --context <absolute-context>
+node .specrails/runtime/agent-runtime.mjs resume --context <absolute-context>
+```
 
-Invoke `$sr-architect` with the exact slug and aggregate frozen scope. Use the
-installed official OpenSpec fast-forward workflow. Require proposal, design, specs,
-tasks and medium/high design-confidence.json. Missing/malformed/low confidence
-blocks development; record the unresolved issue and retain artifacts for retry.
-Do not edit a ticket and silently substitute the new description into this run.
-Changed requirements need a newly admitted scope.
+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.
 
-### Developer
-
-Invoke `$sr-developer` or the validated profile role for each task group. Keep
-source writes in its selected repositories, serialize dependencies/shared files,
-and persist real task progress. A BLOCKED outcome stops downstream phases.
-Scoped checks support development; once all groups are implemented, execute one
-full CI-equivalent check request through the installed helper. Derive actual checks
-from each selected repository and include required cross-repository integration.
-All tasks and current full evidence must pass before recording developer done.
-
-### Reviewer and bounded repair
-
-Invoke `$sr-reviewer` with complete criteria, candidate inventory and current
-verification receipt. Ordinary review does not archive. Require explicit semantic
-acceptance, safe behavior and required regression coverage; green baseline tests
-with missing implementation are incomplete. Reuse unchanged full verification;
-review edits require one fresh final full request on the resulting candidate.
-
-Read canonical `<context.artifactRoot>/openspec/changes/<slug>/confidence-score.json`.
-Require overall ≥70, security ≥75 and every other aspect ≥60 (or stricter configured
-thresholds), all tasks complete and no unresolved explicit blocker. Missing or
-ambiguous verdicts/scores fail closed. A numeric score never converts a blocked
-security or design finding into clean acceptance.
-
-For concrete recoverable findings, reopen developer and invoke it once with those
-exact findings, then re-review and refresh evidence. An architectural blocker
-returns to architect; do not infer its category from a score range. If the one
-repair round does not resolve acceptance, preserve work and record blocked.
-Only then may the runtime record reviewer done.
-
-### Archive
-
-Run `archive-check` immediately before archiving. Nonzero means stop. After success,
-invoke `$sr-reviewer` with ARCHIVE_ONLY=true and ARCHIVE_AUTHORIZED=true and the
-same explicit handoff, or run the installed official archive workflow directly
-as coordinator. Preserve approved confidence bytes; no rescoring or code changes.
-Confirm the exact active change is gone, its archive exists under
-`<context.artifactRoot>/openspec/changes/archive/<date>-<slug>/` and canonical specs
-synced before `phase --phase archive --status done`. Do not emulate an official
-archive with file moves or accept incomplete-task prompts. A failed archive remains
-resumable; it never closes specs or restarts valid development automatically.
-
-### Delivery and CI
-
-For `context.ownership.git === "host"`, record ship and ci skipped with the ownership
-reason and return evidence to the host. Do not stage, commit, push or open PRs.
-For Core-owned git, perform only the delivery already authorized by user/settings,
-in each selected repository. `GIT_AUTO=false` and preview disable shipping even if
-Core owns git. Preserve unrelated changes; stage only the reviewed candidate.
-Record actual per-repository commits/PRs and required CI results before phase done.
-Partial delivery stays incomplete. CI retry checks existing delivery, without
-creating duplicate commits or PRs. No authorized delivery means a concrete blocker,
-not a fabricated successful ship phase.
-
-### Backlog and report
-
-Host-owned backlog remains untouched. Core-owned backlog may close only after all
-required delivery succeeds, current evidence remains valid, and live participating
-ticket requirements still match frozen IDs/descriptions/criteria/repository scope.
-A mismatch leaves that ticket open and reports the conflict. Read/write only
-`context.backlogPath` (fallback context.backlogRoot/.specrails/local-tickets.json),
-preserve unrelated tickets/fields, and apply the store's revision protocol. Workers
-never close tickets. A free-form scope without a real ticket has no ticket mutation.
-
-Report run/change, frozen tickets/roots, reused and newly completed phases,
-verification commands, confidence, archive and each repository's actual delivery.
-Distinguish ready-for-host-delivery from delivered. Include concrete remaining
-blockers; no complete/done claim while a required gate or repository is incomplete.
-
-## Preview and apply
-
-`--dry-run`/`--preview` uses the runtime preview contract and reports UNVERIFIED
-PREVIEW. Tests on untouched source are baseline evidence only. `--apply` resumes the
-exact existing preview journal, verifies unchanged base/cache and runs checks on
-actual applied source through `apply-preview`; continue the ordinary review,
-confidence and archive gates. Preview never grants shipping/backlog ownership.
+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/codex-skills/retry/SKILL.md

@@ -1,42 +1,16 @@
 ---
 name: retry
-description: "Resume the first invalid implement phase using the durable pipeline journal and explicit role handoffs."
+description: "Run or resume implementation through the installed programmatic agent runtime."
 license: MIT
-compatibility: "Codex-native root-level role delegation; no nested implement or assumed provider conversation memory."
 ---
 
-You are the retry orchestrator. Accept `$retry #N`, `$retry <change>`, and `--yes`.
-Resolve `${SPECRAILS_REPO_DIR:-.}` only as the legacy source default; the installed
-pipeline helper and SPECRAILS_EXECUTION_CONTEXT provide the authoritative roots.
-Call `status` for the existing run/change. Report its completed phases and
-`resumePhase`. Do not search other projects or guess a change from a matching title.
-When there is no journal, report the missing run/context and require explicit new
-admission; do not silently initialize a replacement retry scope. Never erase existing
-code or use a checked task alone as proof of implementation.
+# Resume a programmatic implementation
 
-Read `.codex/skills/implement/SKILL.md` as the phase definition; execute its remaining
-roles DIRECTLY from this root agent. Do not spawn `$implement` as a sub-agent.
-Use `spawn_agent`, `send_message` and `wait_agent` only for `$sr-architect`,
-`$sr-developer`, `$sr-reviewer` or explicitly configured installed custom roles.
-Preserve the configured provider model; do not pass model/reasoning_effort on
-full-history forks. Give every role the bounded explicit handoff from the shared
-contract, including unchanged frozen acceptance criteria and exact prior findings.
+Resolve the exact saved context for the requested run. Do not initialize a replacement, guess the latest change, or discard work.
 
-- Architect resumes only if status says design is invalid/missing/blocked.
-- Developer resumes the first incomplete or stale task; do not repeat valid design.
-- Reviewer resumes semantic review with the actual candidate and verification
-  receipts. If findings require code changes, record developer running and invoke
-  developer with those exact findings, then reviewer again (at most one fix round).
-- Never assume a `MAX_TURNS` or successful process exit completed a phase. Save the
-  checkpoint and invoke the same role with the pending work; two continuations
-  without file/task/evidence progress stop as blocked with the outstanding action.
-- Archive uses `archive-check`, followed by reviewer archive-only authorization;
-  missing/low confidence or stale checks never become success through retry.
-- Ship resumes only missing authorized Core-owned delivery; CI checks existing
-  delivery without shipping again. Host-owned ship/ci record skipped; backlog and
-  worktrees remain with their owner. Backlog closure also compares live requirements
-  with frozen scope at context.backlogPath, as implement requires.
+```sh
+node .specrails/runtime/agent-runtime.mjs status --context <absolute-context>
+node .specrails/runtime/agent-runtime.mjs resume --context <absolute-context>
+```
 
-Record each outcome with the helper. A blocked phase is resumable, never an
-intentionally skipped phase. Report the run, change, resumed roles, verification,
-archive outcome and any remaining blocker. No recursive retry loops.
+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/commands/specrails/batch-implement.md

@@ -1,27 +1,32 @@
-# Batch Implement
+# Programmatic implementation
 
-**Input:** $ARGUMENTS — selected ticket references, dependency hints, --dry-run/--preview or existing aggregate change for retry.
+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.
 
-## One scope and one candidate
+## Freeze the requested scope
 
-Use implement's installed runtime and immutable execution context. Host context.specs[] is the batch; never replace it from another repository's backlog. Standalone init --change <aggregate-change> --tickets "17,18" freezes local entries once; freeform/multi-repo uses explicit scope request/context.
+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:
 
-There is **one aggregate OpenSpec change and one journal**, not a full pipeline per ticket. Delegate to implement once with all frozen specs and selected roots. Architect, developer, reviewer, confidence, archive and delivery gates are mandatory and resumable.
+```sh
+node .specrails/runtime/pipeline.mjs init --change <stable-change> --tickets "<requested-ids>"
+```
 
-## Dependency plan
+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.
 
-1. Validate dependency IDs against selected specs/completed external prerequisites; reject cycles or missing prerequisites.
-2. One architect designs shared contracts and task groups labeled with ticket/repository ID. Cross-repository behavior belongs to the same acceptance matrix.
-3. Execute dependency-ordered groups in supplied roots; serialize shared-file/contract changes. Profile routing selects appropriate roles; each handoff includes exact context/runtime paths.
-4. Collect foreground terminal results. Task start or unsupported PASS is not completion.
-5. Scoped tests support development; one full receipt covers the aggregate candidate and cross-repository integration. Reviewer reuses it unchanged; edits need a fresh final full pass.
+## Execute
 
-Never recursively launch implement for each wave, change the run identity, allocate nested worktrees, guess a main branch, merge copied file lists or delete supplied roots. Respect host/Core ownership from entry.
+```sh
+node .specrails/runtime/agent-runtime.mjs run --context <absolute-context> --config .specrails/agent-runtime.json --change <stable-change>
+```
 
-## Acceptance and completion
+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.
 
-Review every ticket's criteria before canonical confidence. Runtime reviewer and archive approval gates precede official archive. Missing implementation/regressions, low confidence or one required failed repo keeps the batch incomplete; preserve per-ticket/repository retry progress.
+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:
 
-Preview remains unverified until runtime apply checks an unchanged base and executes checks on applied candidate. Retry resumes earliest invalid phase, preserving valid design and successful delivery.
+```sh
+node .specrails/runtime/agent-runtime.mjs status --context <absolute-context>
+node .specrails/runtime/agent-runtime.mjs resume --context <absolute-context>
+```
 
-Core-owned backlog may close only after complete delivery and matching current/frozen requirements. Host-owned backlog remains for host acceptance. Report partial outcomes and preserve reviewable work.
+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.