@seanyao/roll 3.612.1 → 3.613.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "3.612.1",
+  "version": "3.613.1",
   "description": "Roll — Roll out features with AI agents",
   "packageManager": "pnpm@11.1.3",
   "scripts": {

package/skills/docs/skill-authoring.md

@@ -42,6 +42,10 @@ Every hub must include `## Gotchas` or `## Known Failure Modes`.
 - If a gotcha comes from a missed load, add a positive route case.
 - If a gotcha comes from an off-target load, add a negative route case.
 - Treat the section as append-mostly unless an entry is proven obsolete.
+- Never instruct agents to `source "$(command -v roll)"`: the TS-native `roll`
+  is a bundled CLI, not a bash library, and sourcing it executes JS as shell
+  (FIX-274). Skill steps call `roll <command>` directly — e.g. self-score notes
+  go through `roll self-score <skill> <story> <score> <verdict> "<rationale>"`.
 
 ## Maintenance Workflow
 

package/skills/roll-build/references/full-contract.md

@@ -797,15 +797,27 @@ Before creating any file or directory:
 
 ### Self-score (US-SKILL-012)
 
-Before reporting completion to the user, write one self-score note. The
-helper lands the note under `.roll/features/<epic>/<US-id>/notes/<date>-roll-build-<US-id>-<epoch>.md` (the card folder is the note home, US-META-008; resolve <epic> via .roll/index.json)
+Before reporting completion to the user, ensure one score note lands.
+**Pair-first (US-PAIR-009/010): when `.roll/pairing.yaml` enables the `score`
+stage, the paired heterogeneous agent produces the score — self-score is the
+fallback, not the default.** Run from the main project root (the directory
+holding `.roll/`); the note lands under `.roll/features/<epic>/<US-id>/notes/<date>-roll-build-<US-id>-<epoch>.md` (the card folder is the note home, US-META-008; epic resolution and the `.roll/notes/` fallback are built in)
 with YAML frontmatter so trend analysis (US-SKILL-014) can aggregate later:
 
 ```bash
-bash -c 'source "$(command -v roll)"; \
-  _skill_write_self_score roll-build US-XXX-NNN <score 1..10> <good|ok|regression> "<rationale>"'
+# 1. pair-first: ask the paired heterogeneous agent to score the cycle
+roll pair score US-XXX-NNN --summary "<one-paragraph delivery summary>"
+# 2. ONLY when the command prints a fallback hint (pairing off / no candidate /
+#    timeout), write the self-score with the printed reason:
+roll self-score roll-build US-XXX-NNN <score 1..10> <good|ok|regression> "<rationale>" --fallback-reason "<reason>"
 ```
 
+Both commands are idempotent — retrying after a transient failure is safe.
+
+> FIX-274: the TS-native `roll` is a bundled CLI and MUST NOT be sourced as a
+> bash library — the old `source`-based `_skill_write_self_score`
+> path is dead. Retrying after a transient failure is safe (idempotent).
+
 Score guidance (integer 1..10):
 - **9..10** — story shipped cleanly: AC fully met, TCR rhythm tight, no
   re-tries from `verdict: too_big`, peer review concerns addressed inline.

package/skills/roll-design/references/full-contract.md

@@ -793,13 +793,22 @@ landed and the user has either confirmed or chosen `No` (story still
 queued) — write a single self-score note covering the design session:
 
 ```bash
-bash -c 'source "$(command -v roll)"; \
-  _skill_write_self_score roll-design US-XXX-NNN <score 1..10> <good|ok|regression> "<rationale>"'
+# 1. pair-first (US-PAIR-009/010): when .roll/pairing.yaml enables the `score`
+#    stage, the paired heterogeneous agent scores the design session
+roll pair score US-XXX-NNN --skill roll-design --summary "<one-paragraph design-session summary>"
+# 2. ONLY when the command prints a fallback hint (pairing off / no candidate /
+#    timeout), write the self-score with the printed reason:
+roll self-score roll-design US-XXX-NNN <score 1..10> <good|ok|regression> "<rationale>" --fallback-reason "<reason>"
 ```
 
+> FIX-274: the TS-native `roll` is a bundled CLI and MUST NOT be sourced as a
+> bash library — the old `source`-based `_skill_write_self_score`
+> path is dead. Retrying after a transient failure is safe (idempotent).
+
 Use the **first** US-id of the batch as the story handle (or the
-representative story when splitting). The note lands under
-`.roll/notes/<date>-roll-design-<id>-<epoch>.md` so US-SKILL-014 can
+representative story when splitting). Run from the main project root; when the
+story already has a card folder the note lands there, otherwise it falls back
+to `.roll/notes/<date>-roll-design-<id>-<epoch>.md` so US-SKILL-014 can
 read trend data.
 
 Score guidance for design quality (integer 1..10):

package/skills/roll-fix/references/full-contract.md

@@ -508,20 +508,32 @@ A minor change is only "done" when all are true:
 - [ ] Online verification performed
 - [ ] **Verification Gate passed** (fresh evidence for tests, build, fix confirmation, no regression)
 - [ ] **Self-score note written (US-SKILL-010 / 011)** — before exit, the agent
-      writes a structured score note via `_skill_write_self_score` so trend
+      writes a structured score note via `roll self-score` so trend
       analysis (US-SKILL-014) and skill-self-scoring docs (US-SKILL-015) have
       data to read.
 
 ### Self-score (US-SKILL-011)
 
-Before exiting the cycle, write one self-score note. The helper validates
-inputs and lands the note under `.roll/features/<epic>/<FIX-id>/notes/<date>-roll-fix-<FIX-id>-<epoch>.md` (the card folder is the note home, US-META-008; resolve <epic> via .roll/index.json):
+Before exiting the cycle, ensure one score note lands. **Pair-first
+(US-PAIR-009/010): when `.roll/pairing.yaml` enables the `score` stage, the
+paired heterogeneous agent produces the score — self-score is the fallback,
+not the default.** Run from the main project root (the directory holding
+`.roll/`); the note lands under `.roll/features/<epic>/<FIX-id>/notes/<date>-roll-fix-<FIX-id>-<epoch>.md` (the card folder is the note home, US-META-008; epic resolution and the `.roll/notes/` fallback are built in):
 
 ```bash
-bash -c 'source "$(command -v roll)"; \
-  _skill_write_self_score roll-fix FIX-XXX-NNN <score 1..10> <good|ok|regression> "<rationale>"'
+# 1. pair-first: ask the paired heterogeneous agent to score the cycle
+roll pair score FIX-XXX-NNN --summary "<one-paragraph delivery summary>"
+# 2. ONLY when the command prints a fallback hint (pairing off / no candidate /
+#    timeout), write the self-score with the printed reason:
+roll self-score roll-fix FIX-XXX-NNN <score 1..10> <good|ok|regression> "<rationale>" --fallback-reason "<reason>"
 ```
 
+Both commands are idempotent — retrying after a transient failure is safe.
+
+> FIX-274: the TS-native `roll` is a bundled CLI and MUST NOT be sourced as a
+> bash library — the old `source`-based `_skill_write_self_score`
+> path is dead. Retrying after a transient failure is safe (idempotent).
+
 Score guidance (integer 1..10):
 - **9..10** — clean root-cause fix; regression test added; TCR cycle smooth.
 - **6..8** — fix shipped but with caveats (e.g. workaround, partial coverage,