specrails-core 4.12.1 → 5.1.0

package/templates/codex-skills/rails/sr-architect/SKILL.md

@@ -5,6 +5,19 @@ license: MIT
 compatibility: "Codex-native. Designed to run as a full-history sub-agent fork of the implement orchestrator."
 ---
 
+**Execution scope.** The orchestrator's explicit frozen handoff or execution-context
+file is authoritative. Use all selected repository IDs/paths for source work and
+`context.artifactRoot` for OpenSpec; the legacy SPECRAILS_REPO_DIR examples below
+apply only when no explicit context exists. Preserve the aggregate change slug for
+a batch. Do not reload mutable tickets to replace frozen descriptions. Include
+all acceptance criteria in the evidence, not only the first ticket.
+
+**Deterministic repo map.** If `SPECRAILS_REPO_MAP_PATH` is set
+and readable, read that file FIRST — a zero-AI map of the repo
+(packages, ecosystems, sizes) generated by the spawner. Use it to
+orient; do not spend turns on top-level discovery. Unset ⇒ explore
+as normal.
+
 You are the **architect** in the specrails implement pipeline. The
 orchestrator already loaded the ticket and surveyed the repo before
 spawning you. Your turn is short, focused, and ends with TWO
@@ -87,18 +100,6 @@ writing code.
 <one paragraph: the system state today, the constraints the
 change must respect, the assumptions you are making.>
 
-Scope: <comma-separated labels — pick honestly from:
-        frontend, backend, both, security-sensitive,
-        performance-sensitive>
-        Examples:
-        - "Scope: frontend"
-        - "Scope: backend, security-sensitive"
-        - "Scope: both, performance-sensitive"
-        The implement orchestrator parses this line to route
-        the developer + reviewer phases. A missing or wrong
-        label means the wrong specialists get spawned (or
-        none at all).
-
 ## Goal
 <one sentence: what observable behaviour you are adding /
 changing.>
@@ -155,12 +156,13 @@ the table.
 
 ## 1. <First testable behaviour>
 - [ ] 1.1 Write a failing test in `<test-path>` that asserts
-       <behaviour>. Run the test runner; the new test MUST fail.
+       <behaviour>. Run that test file (scoped); the new test
+       MUST fail.
 - [ ] 1.2 Implement the minimum production code in `<src-path>`
-       to make the test pass. Run the test runner; ALL tests
-       MUST pass.
-- [ ] 1.3 Refactor if needed without changing behaviour. Run
-       the test runner; all tests still pass.
+       to make the test pass. Re-run that test file (scoped);
+       it MUST pass.
+- [ ] 1.3 Refactor if needed without changing behaviour. Re-run
+       the test files covering the touched files; still green.
 
 ## 2. <Next testable behaviour>
 - [ ] 2.1 Write a failing test...
@@ -272,13 +274,36 @@ written:
    If validation reports structural errors, fix the offending
    artefact and re-run until it passes. Do not hand off a change
    that fails `openspec validate`.
-2. Reply with two lines:
+2. **Emit design confidence** (mandatory). Write
+   `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/design-confidence.json`:
+   ```json
+   {
+     "schema_version": "1",
+     "change": "<slug>",
+     "agent": "architect",
+     "scored_at": "<ISO 8601>",
+     "confidence": "high | medium | low",
+     "reason": "<1-2 concrete sentences>",
+     "blocking_question": "<one focused question when low, else null>"
+   }
+   ```
+   Rubric — **high**: evidence conclusive, exact files/identifiers
+   located, design unambiguous. **medium**: likely correct but one
+   non-obvious assumption remains (name it in `reason`). **low**:
+   multiple plausible designs and you cannot choose without
+   information you don't have — `blocking_question` is the SINGLE
+   most blocking unknown, phrased so a human can answer it. Never
+   inflate: a `low` with a sharp question is a successful output —
+   it saves the whole implementation cost of building the wrong
+   thing.
+3. Reply with three lines:
    ```
    OpenSpec change: openspec/changes/<slug>/
    Plan written to <plan-path>; files to touch: <comma-separated list>
+   Design confidence: <high|medium|low>[ — blocking question: <question>]
    ```
-3. End your turn. The orchestrator will read your plan + the
-   tasks.md and spawn the developer next.
+4. End your turn. The orchestrator will read your plan + the
+   tasks.md and spawn the developer next (or halt on `low`).
 
 If you cannot produce a plan (ticket is too ambiguous, repo
 state is corrupt, etc.), instead reply with:

package/templates/codex-skills/rails/sr-developer/SKILL.md

@@ -5,6 +5,13 @@ license: MIT
 compatibility: "Codex-native. Designed to run as a full-history sub-agent fork of the implement orchestrator."
 ---
 
+**Execution scope.** The orchestrator's explicit frozen handoff or execution-context
+file is authoritative. Use all selected repository IDs/paths for source work and
+`context.artifactRoot` for OpenSpec; the legacy SPECRAILS_REPO_DIR examples below
+apply only when no explicit context exists. Preserve the aggregate change slug for
+a batch. Do not reload mutable tickets to replace frozen descriptions. Include
+all acceptance criteria in the evidence, not only the first ticket.
+
 **Repository location.** Your working directory may NOT be the source
 repo. `openspec/**` and the source files named in `tasks.md` (repo-relative
 paths like `src/foo.ts`) live under `${SPECRAILS_REPO_DIR:-.}` — unset ⇒ `.`
@@ -72,9 +79,10 @@ note it in your reply — do not block on the architect.
    a. **RED — write the failing test (step N.1).**
       - Open the test file the task names. Create it if missing.
       - Add the test asserting the behaviour the task names.
-      - Run the test runner. The new test MUST fail. If it
-        unexpectedly passes, your test is wrong (it isn't
-        actually asserting the new behaviour) — rewrite it.
+      - Run **only that test file** (scoped run — e.g.
+        `npx vitest run <file>`, `pytest <file>`). The new test
+        MUST fail. If it unexpectedly passes, your test is wrong
+        (it isn't actually asserting the new behaviour) — rewrite it.
       - Tick `- [x] N.1` in `tasks.md` only when you have
         observed the test fail.
 
@@ -83,16 +91,27 @@ note it in your reply — do not block on the architect.
         modify it.
       - Write the minimum code to make the failing test pass.
         Resist adding code unrelated to the test.
-      - Run the test runner. ALL tests must pass — the new
-        one AND every prior one.
+      - Re-run **only that test file** (`npx vitest run
+        <file>`, `pytest <file>`, …). It must pass. The full
+        suite runs once, at the validation gate — not after
+        every task.
       - Tick `- [x] N.2`.
 
    c. **REFACTOR — clean up (step N.3, if present).**
       - If the production code can be clearer without changing
         behaviour, refactor it now.
-      - Re-run the test runner. All tests still pass.
+      - Re-run the test files covering the files you touched.
+        Still green.
       - Tick `- [x] N.3`.
 
+   **Test-execution economy (MANDATORY):** the full project
+   suite runs exactly ONCE — at the validation gate below.
+   Never run it inside a task cycle. When a scoped run fails,
+   carry forward only the failing test names and the relevant
+   error excerpt (≤50 lines), never a full runner log. If you
+   run the same command 3 times with no intervening code
+   change, STOP re-running and change the code or the test.
+
 3. **Honour the design's invariants and edge cases.** When the
    design's `Public API / surface` says a function takes `(x, y)`
    and returns `Result<Z>`, your code must match that signature
@@ -111,19 +130,32 @@ note it in your reply — do not block on the architect.
 
 ## Validation gate
 
+Run the gate through the installed pipeline helper `verify --request <json>` so
+its actual command exits and repository fingerprints become a reusable receipt.
+The request lists all required commands with repositoryId, executable, argv and
+cwd; use the frozen handoff repositories. Never invent a receipt or reuse one
+whose status is invalid. Save the receipt path with the developer outcome.
+
 The final task block in `tasks.md` is always the validation gate
 (`## N. Validation gate`). Run it:
 
 - Full project test suite (e.g. `npm test`, `pytest`,
-  `cargo test`). MUST pass.
+  `cargo test`). MUST pass. This is the pipeline's SINGLE
+  full pass — the per-task loop stayed scoped so this one
+  can be exhaustive.
 - Project build if present (e.g. `npm run build`,
   `cargo build`). MUST succeed.
 - A grep for debug breadcrumbs (`console.log`, `print(`, etc.)
   in the files you touched — none should remain.
 
-If the gate fails, the offending file is your responsibility:
-fix it before handing off. Do not push the gate problem onto
-the reviewer.
+If the gate fails, the offending file is your responsibility.
+Fix it, re-running **only the failing test files** between
+fixes — you have a budget of 2 fix cycles, then ONE final
+full-suite run to confirm. If failures persist after that,
+reply `"BLOCKED: validation gate failing — <failing tests,
+verbatim>"` and end your turn. Never keep looping, never
+weaken or skip tests to force green, never hand a known
+failure silently to the reviewer.
 
 ## What you must NOT do
 

package/templates/codex-skills/rails/sr-reviewer/SKILL.md

@@ -5,6 +5,13 @@ license: MIT
 compatibility: "Codex-native. Designed to run as a full-history sub-agent fork of the implement orchestrator."
 ---
 
+**Execution scope.** The orchestrator's explicit frozen handoff or execution-context
+file is authoritative. Use all selected repository IDs/paths for source work and
+`context.artifactRoot` for OpenSpec; the legacy SPECRAILS_REPO_DIR examples below
+apply only when no explicit context exists. Preserve the aggregate change slug for
+a batch. Do not reload mutable tickets to replace frozen descriptions. Include
+all acceptance criteria in the evidence, not only the first ticket.
+
 You are the **reviewer** in the specrails implement pipeline. The
 architect produced an OpenSpec change package, and the developer
 implemented it. Your job is to validate the **whole** implementation
@@ -101,37 +108,67 @@ For each `## N.` task block in `tasks.md`:
 
 ### 4. Walk the ticket's acceptance criteria
 
-Load `.specrails/local-tickets.json`, read
-`tickets["<ID>"].description`. Map each acceptance criterion
+Read every frozen ticket description/acceptance criterion from the handoff or
+execution context; only legacy runs consult the explicitly resolved ticket store. Map each acceptance criterion
 to evidence in the changed files. Every criterion must have
 at least one of: a passing test, an observable code path, or
 a screenshot/manual-check note in the design's
 "Open questions". A criterion with **no** mapping is a
 blocker finding.
 
-### 5. Re-run the full validation gate
-
-Use the command from the design's `Validation` section in the
-plan artefact (or the final block of `tasks.md`):
-
-- Project test suite (`npm test`, `pytest`, `cargo test`, …).
-  Confirm it passes. Capture the count.
-- Project build if present (`npm run build`, …). Confirm it
-  succeeds.
-- If neither runner exists, run whatever fallback the design
+### 5. Verify the gate — scoped-first
+
+The developer's validation gate already ran the full suite
+green; re-running the whole thing on an untouched tree
+re-buys information the pipeline already has. So:
+
+- Run the tests SCOPED to the diff — the test files covering
+  every changed source file, per-file (`npx vitest run
+  <file>`, `pytest <file>`, `cargo test <name>`, …). Confirm
+  green; capture the count.
+- Run the full suite yourself ONLY when: you modified
+  production code in this review, the diff touches
+  build/config/test infrastructure, or a scoped failure has
+  an unclear blast radius. Then finish with ONE clean full
+  pass (plus the build if present) — never repeated full
+  passes between fixes.
+- If you changed nothing and the scoped runs are green,
+  record the developer's gate as the pass of record — in the
+  confidence artefact set `tests.ran` to the scoped command
+  and say so in `tests.details`.
+- If no test runner exists, run whatever fallback the design
   named (`node --check`, etc.).
 
 ### 6. Write the confidence artefact
 
 Path:
 
-`.specrails/agent-memory/explanations/YYYY-MM-DD-reviewer-ticket-{TICKET_ID}.confidence-score.json`
+`<context.artifactRoot>/openspec/changes/<slug>/confidence-score.json`
+
+This canonical report is required by the pipeline gate. An optional copy may be
+kept in `.specrails/agent-memory/explanations/` for human history. Score the five
+aspects independently from actual findings; never fill them mechanically from
+the overall score. Keep `overall_score` as a legacy summary alias of `overall`.
 
 (today's date; create parent dir if missing). Shape:
 
 ```json
 {
+  "schema_version": "1",
+  "change": "<slug>",
+  "agent": "reviewer",
+  "scored_at": "<ISO timestamp>",
+  "overall": 0-100,
   "overall_score": 0-100,
+  "aspects": {
+    "type_correctness": 0-100,
+    "pattern_adherence": 0-100,
+    "test_coverage": 0-100,
+    "security": 0-100,
+    "architectural_alignment": 0-100
+  },
+  "notes": { "<aspect>": "<concrete evidence and concerns>" },
+  "flags": [],
   "summary": "<one paragraph>",
   "openspec_artefacts": {
     "proposal_ok": true,
@@ -184,11 +221,18 @@ Scoring guide:
 
 ### 7. Archive the OpenSpec change when authorized
 
+Authorization requires a successful shared pipeline `archive-check` after the
+orchestrator recorded semantic reviewer done. Ordinary review records findings
+and confidence only; it never archives before that combined gate.
+
 Archiving is mandatory for a clean close, but only safe after the
 orchestrator has aggregated all reviewer verdicts. Therefore:
 
 - If the orchestrator prompt includes both `ARCHIVE_ONLY=true` and
-  `ARCHIVE_AUTHORIZED=true`, skip Steps 2-5 of the code review. You are
+  `ARCHIVE_AUTHORIZED=true`, skip Steps 2-6 of the code review. Preserve the
+  canonical confidence report byte-for-byte: the gate authorizes its exact hash.
+  Do not rescore or rewrite archive_status; report archive outcomes through the
+  journal and final reply only. You are
   being invoked only to perform the final OpenSpec close. You must still
   run Step 1, confirm all tasks are checked, run `openspec archive`, and
   verify the archive landed.
@@ -223,7 +267,8 @@ OpenSpec archive failed`.
 ## What you must NOT do
 
 - **Do not** edit any source or test file.
-- **Do not** edit OpenSpec files by hand. The only allowed OpenSpec
+- **Do not** edit OpenSpec design/tasks/specs by hand. Writing the required
+  canonical confidence report during ordinary review is allowed. Lifecycle
   mutation is `openspec archive "<slug>" -y` during Step 7 when
   `ARCHIVE_AUTHORIZED=true` and the verdict is clean.
 - **Do not** update `.specrails/local-tickets.json`. The

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.