specrails-core 5.0.0 → 5.1.0

package/templates/codex-skills/retry/SKILL.md

@@ -1,122 +1,42 @@
 ---
 name: retry
-description: "Resume a previously-attempted $implement pipeline for a ticket. Detects what's already on disk (OpenSpec change package, partial code, ticked tasks.md) and re-invokes $implement so the architect/developer/reviewer agents skip work that's already correct and pick up where the prior run left off. Use when the user invokes `$retry #N` after a $implement run that ended in `todo` or `blocked`."
+description: "Resume the first invalid implement phase using the durable pipeline journal and explicit role handoffs."
 license: MIT
-compatibility: "Codex-native. Thin wrapper around $implement — relies on the implement pipeline's existing idempotence rather than tracking its own state."
+compatibility: "Codex-native root-level role delegation; no nested implement or assumed provider conversation memory."
 ---
 
-You are the **retry orchestrator**. The user wants to continue a
-prior `$implement` run for a single ticket without redoing work
-that's already correct on disk.
-
-You are NOT a separate pipeline. You inspect what `$implement`
-left behind, summarise the current state, and re-invoke
-`$implement` with a hint about what's already in place. The
-implement skill is idempotent — architect reuses an existing
-`${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/`, developer detects ticked tasks and
-already-correct files, reviewer re-validates from scratch.
-
-**Repository location.** `openspec/**` and `.git` live under
-`${SPECRAILS_REPO_DIR:-.}` (unset ⇒ `.` ⇒ classic in-repo run); inspect change
-artefacts there. The ticket store and `.specrails/agent-memory/` are run-state,
-relative to the working directory.
-
-## How the user invokes you
-
-- `$retry #N` — retry the implement run for ticket `N`.
-- `$retry #N --yes` — same, non-interactive.
-
-## Steps
-
-### 0. Locate the prior run's artefacts
-
-1. Confirm the repo root with `git -C "${SPECRAILS_REPO_DIR:-.}" rev-parse --show-toplevel`.
-2. Load the ticket (run-state, relative to the working directory):
-   `jq '.tickets["<ID>"]' .specrails/local-tickets.json`. If
-   the ticket doesn't exist, stop and report.
-3. Inspect what's already on disk for this ticket:
-   - **Architect artefacts**: any matching plan file under
-     `.specrails/agent-memory/explanations/` named
-     `*-architect-ticket-<ID>.md`. List the latest.
-   - **OpenSpec change package**: any
-     `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/` whose proposal.md mentions
-     the ticket title or whose tasks.md has tasks scoped to
-     the ticket. Find the slug.
-   - **tasks.md progress**: count `[x]` vs `[ ]` boxes in
-     `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/tasks.md`.
-   - **Reviewer verdict**: latest matching
-     `*-reviewer-ticket-<ID>.confidence-score.json`. Read
-     the issues list and overall score.
-
-### 1. Summarise (≤6 lines)
-
-Print a concise state summary so the user sees what you
-detected:
-
-```
-Prior run for #<ID>:
-  Plan:        <path or "missing">
-  Change pkg:  openspec/changes/<slug>/ (<found / missing>)
-  Tasks:       <X>/<N> ticked
-  Last review: <score>/100 — <verdict>
-  Open issues: <count> (top: "<first issue note, truncated>")
-```
-
-If no prior artefacts exist, say so explicitly — `$retry` on a
-ticket that was never attempted is just `$implement`, and you
-fall through to step 2 anyway.
-
-### 2. Re-invoke $implement
-
-`spawn_agent` (full-history fork, no agent_type / model /
-reasoning_effort). `send_message`:
-
-> `$implement`
->
-> Ticket id: `<TICKET_ID>`
-> Mode: **retry**
->
-> A prior run left:
->   - plan at `<plan-path-or-none>`
->   - change package at `openspec/changes/<slug>/` (<found|missing>)
->   - tasks.md progress: <X>/<N> ticked
->   - last reviewer score: <N>/100 with <K> open issues
->
-> Open issues from the last review (verbatim):
-> - <issue 1 from confidence-score.json>
-> - <issue 2>
-> - ...
->
-> Honour these on this retry:
-> 1. If the change package exists and proposal.md is sane,
->    REUSE it. The architect should refine design.md / tasks.md
->    if the issues call for it, not start from scratch.
-> 2. The developer should pick up at the first un-ticked task
->    box. Already-ticked boxes whose files match the intended
->    state should NOT be redone.
-> 3. The reviewer re-runs from scratch — no caching of prior
->    verdict.
->
-> Follow the $implement skill instructions exactly. Reply
-> with the standard implement summary.
-
-`wait_agent`. `close_agent`. Print the sub-agent's reply
-verbatim as your own final report.
-
-## What you must NOT do
-
-- **Do NOT re-implement the pipeline**. You only inspect +
-  delegate. The implement skill owns the actual work.
-- **Do NOT modify any file directly** — neither the OpenSpec
-  package nor the ticket. The spawned `$implement` does that.
-- **Do NOT skip the "open issues" passthrough**. If the last
-  review listed fixes, the next pipeline needs to see them
-  verbatim — that's what makes retry produce a different
-  result than a fresh `$implement`.
-- **Do NOT loop on retry**. If the user wants a second retry,
-  they invoke `$retry #N` again themselves. One retry per
-  invocation.
-- **Do NOT pass `agent_type`, `model`, or `reasoning_effort`**
-  to `spawn_agent` on full-history forks.
-- **Do NOT touch `.claude/agent-memory/`** — codex projects
-  use `.specrails/agent-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.
+
+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.
+
+- 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.
+
+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.

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

@@ -1,299 +1,27 @@
-# Batch Implementation Orchestrator
+# Batch Implement
 
-Macro-orchestrator above `/specrails:implement`. Accepts a set of feature references, computes a dependency-aware wave execution plan, invokes `/specrails:implement` per wave, and produces a batch-level progress dashboard and final report. All per-feature pipeline work (sr-architect, sr-developer, sr-reviewer, git, CI) is fully delegated to `/specrails:implement`.
+**Input:** $ARGUMENTS — selected ticket references, dependency hints, --dry-run/--preview or existing aggregate change for retry.
 
-**MANDATORY: Always follow this pipeline exactly as written. NEVER skip, shortcut, or "optimize away" any phase — even if the batch seems small enough to handle directly. The orchestrator MUST compute waves, confirm with the user, and invoke `/specrails:implement` per wave as specified. Do NOT implement any feature yourself in the main conversation. No exceptions.**
+## One scope and one candidate
 
-**Input:** $ARGUMENTS — one or more feature references with optional flags:
+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.
 
-- **Feature refs**: `#85 #71 #63` (GitHub issue numbers) — required, at least two
-- **`--deps "<spec>"`**: inline dependency spec, e.g. `"#71 -> #85, #63 -> #85"` (meaning #71 and #63 must complete before #85)
-- **`--concurrency N`**: max features running in parallel across waves (default: 3)
-- **`--wave-size N`**: max features per wave regardless of concurrency (default: unlimited)
-- **`--dry-run` / `--preview`**: passed through to each `/specrails:implement` invocation; no git or backlog operations will run
+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.
 
-**IMPORTANT:** Before running, ensure Read/Write/Bash/Glob/Grep permissions are set to "allow" — subagents cannot request permissions interactively.
+## Dependency plan
 
----
+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.
 
-## Desktop rail execution context (isolated worktree)
+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.
 
-specrails-desktop launches this command INSIDE an isolated rail worktree allocated for the batch. Detect it: the working directory path contains `/worktrees/` (e.g. `~/.specrails/projects/<slug>/worktrees/ticket-N`), typically on a `feat/...` branch. When that is the case, ALL of the following hold — they override any instinct to the contrary:
+## Acceptance and completion
 
-- **You ARE the assigned executor of this rail.** The desktop's own bookkeeping (rail slots, ticket-ownership rows in its `jobs.sqlite`, state under `~/.specrails/`) describes THIS very launch — it is never evidence of a competing process. NEVER read specrails-desktop's internal databases or state files, and NEVER stop to ask "which process should run this batch".
-- **The current worktree + current branch ARE the workspace for the WHOLE batch.** Implement every ticket here, in dependency order — including tickets whose refs differ from the branch name. The desktop assembles this branch into a batch PR after you finish; nothing needs to land on the integration branch (main) first. Do NOT create sibling worktrees, do NOT switch branches, do NOT run any ticket "against main in the base repo".
-- **Run tickets SEQUENTIALLY (effective concurrency 1)** regardless of `--concurrency`: parallel pipelines editing one shared checkout corrupt each other. Wave order still sequences the work; only the parallelism collapses.
-- Everything else (per-ticket `/specrails:implement` delegation, wave gates, failure isolation, final report) applies unchanged.
+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.
 
----
+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.
 
-## Phase 0: Parse Input
-
-### Step 1: Extract feature refs
-
-Scan `$ARGUMENTS` for issue/ticket references (e.g. `#85`, `#71`). Collect into `FEATURE_REFS` list. If fewer than 2 refs are found, stop and print:
-
-```
-[batch-implement] Error: at least 2 feature refs are required. For a single feature, use /specrails:implement directly.
-```
-
-### Step 2: Extract flags
-
-Scan `$ARGUMENTS` for control flags:
-
-- If `--dry-run` or `--preview` is present: set `DRY_RUN=true`. This flag is forwarded to every `/specrails:implement` call.
-- If `--deps "<spec>"` is present: capture the quoted string as `DEPS_SPEC`. Strip from arguments.
-- If `--concurrency N` is present: set `CONCURRENCY=N` (integer ≥ 1). Default: 3.
-- If `--wave-size N` is present: set `WAVE_SIZE=N` (integer ≥ 1). Default: unlimited (no per-wave cap).
-- If `--profiles "<spec>"` is present: parse a per-rail profile map of the form `ref=profile-name,ref=profile-name,...`. Capture as `PROFILE_MAP` and strip from arguments. Each mapped ref's `/specrails:implement` invocation will run under the named profile (the profile must exist at `.specrails/profiles/<profile-name>.json`). Unmapped refs inherit the batch-level profile resolution (see below).
-
-**If `DRY_RUN=true`**, print:
-```
-[dry-run] Preview mode active — /specrails:implement will be called with --dry-run for each wave.
-```
-
-### Step 3: Fetch issue titles
-
-For each ref in `FEATURE_REFS`, fetch the issue title to use in progress output:
-
-```bash
-{{BACKLOG_VIEW_CMD}} --json number,title
-```
-
-Store as `FEATURE_TITLES` map: `{ref: title}`.
-
----
-
-## Phase 1: Wave Planning
-
-### Step 1: Parse dependency graph
-
-Build a directed graph `DEP_GRAPH` where an edge `A -> B` means "A must complete before B starts".
-
-Parse `DEPS_SPEC` (if provided) by splitting on `,` and parsing each token as `<ref> -> <ref>`.
-
-```
-for each token in DEPS_SPEC.split(","):
-    left, right = token.split("->")
-    DEP_GRAPH.add_edge(left.strip(), right.strip())
-```
-
-All refs in `FEATURE_REFS` that appear in no edge are treated as independent (no dependencies).
-
-### Step 2: Detect circular dependencies
-
-Run cycle detection on `DEP_GRAPH`:
-
-```
-visited = {}
-rec_stack = {}
-
-function has_cycle(node):
-    visited[node] = true
-    rec_stack[node] = true
-    for neighbor in DEP_GRAPH.neighbors(node):
-        if not visited[neighbor] and has_cycle(neighbor):
-            return true
-        elif rec_stack[neighbor]:
-            return true
-    rec_stack[node] = false
-    return false
-
-CYCLES = [node for node in FEATURE_REFS if not visited[node] and has_cycle(node)]
-```
-
-If `CYCLES` is non-empty: stop and print:
-
-```
-[batch-implement] Error: circular dependency detected.
-Cycle involves: <ref-list>
-Fix the --deps spec and re-run.
-```
-
-### Step 3: Compute waves via Kahn's algorithm
-
-```
-in_degree = {ref: 0 for ref in FEATURE_REFS}
-for each edge (A -> B) in DEP_GRAPH:
-    in_degree[B] += 1
-
-WAVES = []
-ready = [ref for ref in FEATURE_REFS if in_degree[ref] == 0]
-sort ready alphabetically (stable ordering)
-
-while ready is non-empty:
-    wave = ready[:WAVE_SIZE]  # cap at WAVE_SIZE if set; else take all
-    remaining = ready[WAVE_SIZE:] if WAVE_SIZE else []
-    WAVES.append(wave)
-    for ref in wave:
-        for neighbor in DEP_GRAPH.neighbors(ref):
-            in_degree[neighbor] -= 1
-            if in_degree[neighbor] == 0:
-                remaining.append(neighbor)
-    sort remaining alphabetically
-    ready = remaining
-```
-
-Set `TOTAL_WAVES = len(WAVES)`.
-
-### Step 4: Print execution plan and ask for confirmation
-
-Print the wave execution plan:
-
-```
-## Batch Execution Plan
-
-Total features : <N>
-Total waves    : <TOTAL_WAVES>
-Max concurrency: <CONCURRENCY>
-Dry-run        : <yes / no>
-
-| Wave | Features | Depends On |
-|------|----------|------------|
-| 1    | #85, #71 | —          |
-| 2    | #63      | #85, #71   |
-
-Dependency graph:
-  #71 -> #63
-  #85 -> #63
-
-Proceed? (yes / no / edit-deps)
-```
-
-Wait for user confirmation.
-
-- **`yes`**: proceed to Phase 2.
-- **`no`**: stop. Print `[batch-implement] Aborted by user.`
-- **`edit-deps`**: ask the user to provide a corrected `--deps` spec, re-run Phase 1 from Step 1.
-
----
-
-## Phase 2: Wave Execution Loop
-
-Execute waves sequentially. Within each wave, invoke `/specrails:implement` for all features in parallel (up to `CONCURRENCY` at a time).
-
-### Progress Dashboard
-
-Before starting each wave, print the current dashboard state:
-
-```
-## Batch Progress
-
-| # | Feature | Title | Wave | Status | Notes |
-|---|---------|-------|------|--------|-------|
-| 1 | #85     | <title> | 1  | done   |       |
-| 2 | #71     | <title> | 1  | done   |       |
-| 3 | #63     | <title> | 2  | running|       |
-| 4 | #42     | <title> | 2  | blocked| depends on #63 |
-| 5 | #17     | <title> | 3  | pending|       |
-```
-
-Status values:
-- `pending` — not yet started
-- `running` — `/specrails:implement` invocation is active
-- `done` — `/specrails:implement` completed successfully
-- `failed` — `/specrails:implement` exited with an error
-- `blocked` — a dependency failed; this feature will not run
-
-### Wave invocation
-
-For each wave `W`:
-
-1. Print: `[wave W/TOTAL_WAVES] Starting — features: <ref-list>`
-2. For each feature batch of size ≤ `CONCURRENCY` within the wave:
-   - For every ref in the batch, determine the profile spawn env:
-     - If `PROFILE_MAP` contains an entry for this ref, set `SPECRAILS_PROFILE_PATH=<abs path to .specrails/profiles/<mapped-name>.json>` for this invocation only.
-     - Otherwise, inherit whatever `$SPECRAILS_PROFILE_PATH` was set by the caller (e.g. specrails-desktop), or leave unset so the rail falls back to `.specrails/profiles/project-default.json` or legacy mode.
-   - Invoke `/specrails:implement` with the feature refs and forwarded flags:
-     ```
-     SPECRAILS_PROFILE_PATH=<resolved-per-rail-path> /specrails:implement <ref> [--dry-run]
-     ```
-   - Each ref in the batch spawns with its own resolved profile path — **distinct rails in the same batch MAY use distinct profiles concurrently**.
-   - Run invocations in the batch **concurrently in the FOREGROUND**: emit every agent invocation for the batch in a single message with `run_in_background: false`. They still run in parallel, and your turn blocks until all of them return.
-   - **NEVER use `run_in_background: true`, and NEVER end your reply while a wave is still running.** In headless/pipeline execution (`claude -p`, specrails-desktop loops) the host tears the process down as soon as your turn ends — background agents are killed before they write a single file. Replies like "wave 1 is running in the background, I'll pick it up when it finishes" lose the entire wave.
-   - Wait for all in the batch to complete before starting the next batch.
-3. For each completed invocation, record outcome in `WAVE_RESULTS`:
-   - `{ref, wave, status: "done" | "failed", profile: "<name or empty>", error_summary: "..." | null}`
-
-### Failure isolation
-
-After each wave completes:
-
-```
-FAILED_THIS_WAVE = [ref for ref in wave if WAVE_RESULTS[ref].status == "failed"]
-
-for each ref in FAILED_THIS_WAVE:
-    BLOCKED = all refs in DEP_GRAPH.descendants(ref)
-    for each blocked_ref in BLOCKED:
-        WAVE_RESULTS[blocked_ref] = {status: "blocked", reason: "depends on failed " + ref}
-        remove blocked_ref from all future waves
-```
-
-A failed feature blocks ONLY its transitive dependents. Features in other branches of the dependency graph continue unaffected.
-
-Print updated dashboard after each wave.
-
-### Wave completion gate
-
-Before starting wave W+1, confirm all features in wave W have status `done` or `blocked`. Never start a downstream wave while upstream features are still running.
-
----
-
-## Phase 3: Batch Report
-
-After all waves complete (or all remaining features are blocked), print the final batch report.
-
-```
-## Batch Implementation Report
-
-Run completed: <ISO 8601 timestamp>
-Dry-run: <yes / no>
-
-### Summary
-
-| Metric | Count |
-|--------|-------|
-| Total features | N |
-| Succeeded | N |
-| Failed | N |
-| Blocked (dep failure) | N |
-
-### Per-Feature Results
-
-| # | Feature | Title | Wave | Status | Notes |
-|---|---------|-------|------|--------|-------|
-| 1 | #85     | <title> | 1  | done   |       |
-| 2 | #71     | <title> | 1  | failed | see /specrails:implement output |
-| 3 | #63     | <title> | 2  | blocked| depends on #71 |
-
-### Merge Conflicts
-
-[List any merge conflicts reported by /specrails:implement across all waves. If none: "No merge conflicts detected."]
-
-| Feature | File | Conflicting Region |
-|---------|------|--------------------|
-| #85     | src/utils/parser.ts | function parseQuery |
-
-### Next Steps
-
-[If all features succeeded:]
-All features implemented. Review open PRs and monitor CI.
-
-[If any features failed:]
-Re-run failed features individually:
-  /specrails:implement <failed-ref>
-  /specrails:implement <failed-ref>
-
-[If any features were blocked:]
-Once failed features are fixed, re-run blocked features:
-  /specrails:implement <blocked-ref> [--deps "..."]
-```
-
----
-
-## Error Handling
-
-- If a `/specrails:implement` invocation fails: record failure, apply failure isolation, continue remaining waves
-- If GitHub CLI is unavailable (detected during issue title fetch): proceed without titles, show refs only
-- If `--deps` spec contains unknown refs: warn and continue — unknown refs are ignored in graph construction
-- Never block the entire batch on a single feature failure. Always produce a final report.
+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.