specrails-core 4.6.4 → 4.6.5

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

@@ -30,6 +30,12 @@ path documented per phase (architect / developer can return
 `BLOCKED: …` and you stop). Otherwise: spawn, wait, close,
 move on.
 
+**A `clean` run is NOT finished until the change is archived.**
+Archiving (`openspec archive`) is a hard obligation, not an
+optional epilogue — see Phase 5. If you mark a ticket `done`
+without an archived change under `openspec/changes/archive/`,
+you violated this contract.
+
 ## How the user invokes you
 
 - `$implement #N` — implement ticket `N` from
@@ -95,9 +101,10 @@ the combo and you'll burn a turn on the retry.
 3. **List the installed rail skills**:
    `ls .codex/skills/rails/`
    The output drives routing in phases 2-4. Skills that aren't
-   listed are not installed — never spawn them. The four core
-   rails (`sr-architect`, `sr-developer`, `sr-reviewer`,
-   `sr-merge-resolver`) are always present.
+   listed are not installed — never spawn them. The three core
+   rails (`sr-architect`, `sr-developer`, `sr-reviewer`) are
+   always present. `sr-merge-resolver` and every layer specialist
+   are optional — spawn them only when listed.
 4. State (≤4 lines) the ticket goal, the stack you detected from
    a quick `ls`/`find`, and the optional rails that are
    available. Do NOT plan files-to-touch — that's the
@@ -247,8 +254,11 @@ Skip when the overall verdict is `fix needed` or `blocked` — no
 point sugar-coating an unsound change.
 
 - If `sr-test-writer` is installed AND the reviewer's confidence
-  artefact reports a coverage decrease, spawn it with the
-  changed files list. It writes more tests, runs them, reports.
+  artefact reports a coverage gap (`tdd_evidence.all_tasks_have_tests`
+  is `false`, or `tdd_evidence.tests_are_non_trivial` is `false`),
+  spawn it with the changed files list. It writes more tests, runs
+  them, reports. (These are the fields the `$sr-reviewer` skill
+  actually writes — do not key on a non-existent "coverage" field.)
 - If `sr-doc-sync` is installed AND the change touches a
   publicly-documented surface (README mentions a renamed
   function, AGENTS.md references a removed file, openspec specs
@@ -270,9 +280,65 @@ If phase 3's overall verdict is `fix needed`:
   `blocked`, **do not loop again** — surface in the final
   report.
 
-### 6. Phase 5 — Close + report
-
-If a ticket id is in play:
+### 6. Phase 5 — Archive FIRST, then close + report
+
+> **INVARIANT.** A ticket may be marked `done` ONLY if its change is
+> archived (`openspec/changes/archive/<slug>/` exists). A `clean`
+> verdict with an unarchived change is `todo` + `fix needed`, never
+> `done`. Archiving the change and closing the ticket are a single
+> atomic obligation — you cannot satisfy one and skip the other.
+
+**Step A — Archive the OpenSpec change through `$sr-reviewer`
+(mandatory when the verdict is `clean`). Run this BEFORE touching the
+ticket or writing the report.** A change is not done until it is
+archived — this is the codex equivalent of `opsx:archive`, and it MUST
+run. When the overall verdict is `clean`, delegate the final OpenSpec
+close to the reviewer rail so the same agent that validated the change
+performs the lifecycle close:
+
+1. Spawn `$sr-reviewer` one final time (full-history fork).
+2. Send this exact close prompt:
+
+   > `$sr-reviewer`
+   >
+   > ARCHIVE_ONLY=true
+   > ARCHIVE_AUTHORIZED=true
+   > Ticket id: `<TICKET_ID>`
+   > Plan: `<PLAN_PATH>`
+   > Change slug: `<slug>`
+   >
+   > The aggregated reviewer verdict is clean. Follow the
+   > `$sr-reviewer` archive-only instructions exactly: validate the
+   > OpenSpec change, confirm every task is checked, perform the
+   > OpenSpec archive command, and verify the archive landed.
+
+3. `wait_agent`, parse the two-line `Score:` / `Verdict:` reply, and
+   `close_agent`.
+4. Treat any non-clean archive reply as archive failure.
+
+The reviewer rail's archive-only mode must run these checks:
+
+1. Re-confirm every task box in `openspec/changes/<slug>/tasks.md`
+   is ticked (`- [x]`) and the change validates:
+   `openspec validate "<slug>" --strict`.
+2. Archive it: `openspec archive "<slug>" -y` — this updates the
+   main specs and moves the change to `openspec/changes/archive/`.
+3. **Verify the archive landed — do NOT assume success.** Confirm
+   `openspec/changes/archive/` now contains the slug
+   (`ls -d openspec/changes/archive/*<slug>* 2>/dev/null`) AND that
+   `openspec/changes/<slug>/` is gone. If the archive directory is
+   absent, archiving FAILED.
+4. If `openspec validate`, `openspec archive`, or the step-3
+   verification fails: do NOT mark the ticket `done`. Treat the run
+   as `fix needed`, surface the error in the final report, set the
+   report's `Archive:` line to `FAILED`, and leave the ticket
+   `todo`.
+
+Skip archiving only when the verdict is `fix needed` or `blocked` —
+an unsound change must never be archived. In that case set the
+report's `Archive:` line to `skipped (<verdict>)`.
+
+**Step B — Close the ticket + report.** If a ticket id is in play:
 
 - Update `.specrails/local-tickets.json`. Modify only:
   - `tickets["<ID>"].status` → `"done"` (clean) or `"todo"`
@@ -288,6 +354,7 @@ Print the final summary (≤18 lines):
 Pipeline:  architect → <developer skill(s)> → <reviewer skill(s)>
 Plan:      <path>
 Confidence: <best path> (overall <score>/100)
+Archive:   archived → openspec/changes/archive/<slug>  |  skipped (<verdict>)  |  FAILED
 Files:     <one path per line, capped at 12; truncate beyond>
 Tests:     <ran command, pass/fail>
 Build:     <ran command, ok/fail/n/a>

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

@@ -19,16 +19,35 @@ source files outside `openspec/` and `.specrails/agent-memory/`.
 
 ### A. OpenSpec change package
 
-Create a directory at:
+**Scaffold the change with the OpenSpec CLI — this is mandatory.**
+Do NOT hand-create the change directory; the `openspec` CLI owns
+scaffolding so the change is registered with a workflow schema and
+stays trackable by `openspec status`. Run:
 
-`openspec/changes/<slug>/`
+```
+openspec new change "<slug>" --schema spec-driven
+```
 
 where `<slug>` is a kebab-case derivation of the ticket title
 (e.g. ticket "Build a Playable Tetris Game" → `add-tetris-game`).
-If `openspec/` doesn't exist yet, create it. If the change
-directory already exists from a prior run, **reuse** it (idempotent).
+This creates `openspec/changes/<slug>/.openspec.yaml`.
+
+- If the command fails because OpenSpec isn't initialised in this
+  repo, run `openspec init . --tools codex --force` once, then
+  re-run `openspec new change …`.
+- If the change directory already exists from a prior run,
+  **reuse** it (idempotent) — skip the `new change` call.
 
-Inside that directory, write four files:
+Then fill the change's artefacts **in the dependency order
+OpenSpec enforces** (proposal first; then design + specs; then
+tasks). Check the order and what's still outstanding at any time
+with:
+
+```
+openspec status --change "<slug>" --json
+```
+
+Write these four artefacts into `openspec/changes/<slug>/`:
 
 **`proposal.md`** — the change's executive summary:
 
@@ -237,12 +256,19 @@ on the touched files as a fallback.>
 When BOTH the OpenSpec change package and the plan artefact are
 written:
 
-1. Reply with two lines:
+1. **Validate the change with the OpenSpec CLI** (mandatory):
+   ```
+   openspec validate "<slug>"
+   ```
+   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:
    ```
    OpenSpec change: openspec/changes/<slug>/
    Plan written to <plan-path>; files to touch: <comma-separated list>
    ```
-2. End your turn. The orchestrator will read your plan + the
+3. End your turn. The orchestrator will read your plan + the
    tasks.md and spawn the developer next.
 
 If you cannot produce a plan (ticket is too ambiguous, repo

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

@@ -7,9 +7,12 @@ compatibility: "Codex-native. Designed to run as a full-history sub-agent fork o
 
 You are the **developer** in the specrails implement pipeline. The
 architect produced an OpenSpec change package (proposal + design +
-tasks + spec deltas) and a plan artefact. Your job is to walk the
-`tasks.md` TDD cycles in order, leave a minimal but cohesive set
-of changes, and hand off to the reviewer.
+tasks + spec deltas) and a plan artefact. Your job is to **apply**
+that OpenSpec change — walk its `tasks.md` TDD cycles in order,
+leave a minimal but cohesive set of changes, and hand off to the
+reviewer. The change's `tasks.md` is the single source of truth for
+what to build; do not invent work outside it. You may only hand off
+once **every** task box is ticked `- [x]` (see "How you finish").
 
 ## Your scope
 

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

@@ -14,15 +14,26 @@ the code. You emit a structured verdict and never touch the code.
 ## Your scope
 
 You **validate**. You read every artefact, you re-run every check,
-and you emit a structured judgement. Findings only — you do not
-edit any source, test, or OpenSpec file.
+and you emit a structured judgement. You do not edit source or test
+files. You may write the confidence artefact and, when the review is
+clean and archiving is authorized by the orchestrator, you must archive
+the completed OpenSpec change with the `openspec` CLI.
 
 ## What you do, in order
 
 ### 1. Validate the OpenSpec change package
 
 Load `openspec/changes/<slug>/` (the orchestrator gave you the
-slug). Confirm the four artefacts exist and are well-formed:
+slug). **Run the OpenSpec validator first** — it is the canonical
+structural check and is mandatory:
+
+```
+openspec validate "<slug>" --strict --json
+```
+
+A non-empty error list is a blocker finding: record each under
+`issues` and bound `overall_score < 70`. Then confirm by hand the
+four artefacts exist and are well-formed:
 
 - **`proposal.md`** — has `## Why`, `## What changes`, and
   `## Impact` sections.
@@ -146,6 +157,7 @@ Path:
     "ran": "npm run build | … | n/a",
     "passed": true
   },
+  "archive_status": "not_authorized | archived:<path> | skipped:<verdict> | failed",
   "issues": [
     {
       "severity": "blocker" | "major" | "minor",
@@ -164,10 +176,50 @@ Scoring guide:
   multiple minor ones
 - **< 50** — blocker: at least one blocker finding
 
+### 7. Archive the OpenSpec change when authorized
+
+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
+  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.
+- If the orchestrator prompt includes `ARCHIVE_AUTHORIZED=true` and your
+  verdict is `clean`, you must archive the change yourself using
+  OpenSpec. Do not ask the user for confirmation.
+- If `ARCHIVE_AUTHORIZED=true` is absent, set
+  `"archive_status": "not_authorized"` in the confidence artefact and
+  report the clean verdict without archiving. The orchestrator must then
+  invoke you again for the archive-only close step or perform its own
+  archive step.
+- If your verdict is `fix needed` or `blocked`, do not archive. Set
+  `"archive_status": "skipped:<verdict>"`.
+
+When archiving is authorized and the verdict is clean, run these exact
+checks in order:
+
+1. Re-run `openspec validate "<slug>" --strict`.
+2. Read `openspec/changes/<slug>/tasks.md` and search for unchecked
+   tasks (`- [ ]`). If any remain, do not archive; change the verdict to
+   `fix needed: OpenSpec tasks remain unchecked`.
+3. Run `openspec archive "<slug>" -y`.
+4. Verify the archive landed: confirm `openspec/changes/<slug>/` is gone
+   and `openspec/changes/archive/` contains a directory whose name
+   includes `<slug>`.
+
+If validation, archive, or verification fails, do not report `clean`.
+Record the command/error under `issues`, set `"archive_status": "failed"`
+in the confidence artefact, and finish with `fix needed:
+OpenSpec archive failed`.
+
 ## What you must NOT do
 
-- **Do not** edit any source, test, OpenSpec, or ticket file.
-  You are findings-only.
+- **Do not** edit any source or test file.
+- **Do not** edit OpenSpec files by hand. The only allowed OpenSpec
+  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
   orchestrator writes that after reading your verdict.
 - **Do not** spawn further sub-agents.