@seanyao/roll 3.608.1 → 3.609.2

package/package.json

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

package/skills/roll-build/SKILL.md

@@ -233,7 +233,7 @@ Wait for the user's response before editing files. If the user does not object w
 
 - Use `$roll-design` to split vague request into INVEST-compliant User Stories
 - Insert US into `.roll/backlog.md` under the relevant Epic > Feature group
-- If a new story folder is needed, create `.roll/features/<epic>/<story>/spec.md` (with `roll idea` or manually)
+- If a new story folder is needed, mint it via `roll story new <ID> --title <t> --epic <e>` (the single channel, US-META-009), then edit the spec
 
 After creation, switch to **Story mode** and execute the first US immediately.
 
@@ -497,16 +497,19 @@ the full diff as a single-pass fallback — do not skip review entirely.
 🟢 Suggestions / ✅ All clear → Proceed to Phase 8
 ```
 
-### Phase 8: Commit & Push
+### Phase 8: Commit & Push (branch + PR — NEVER direct to main)
 
-```bash
-# All TCR micro-commits are already made
-# Squash or keep as-is based on repo convention
-
-git log --oneline -{n}  # Review TCR commits
+`main` is PR-protected. Push the worktree's branch and open a PR — never
+`git push origin main`. (When invoked by `roll-loop`, the runner already
+created the worktree + branch and opens the PR; this is the manual-path
+equivalent.)
 
-git pull origin main --rebase
-git push origin main
+```bash
+# All TCR micro-commits are already made on the worktree's branch (Phase 0).
+git log --oneline -{n}                 # Review TCR commits
+git push -u origin <branch>            # the dispatch/<id> branch from Phase 0
+gh pr create --title "{story-id}: …" --body "…"
+# After CI is green: gh pr merge --rebase
 ```
 
 Commit message (if squashing):
@@ -727,6 +730,15 @@ Before creating any file or directory:
 
 ## Hard Rules
 
+0. **Worktree-first, PR-at-end (ALWAYS)**
+   Before writing any code, work in a dedicated git worktree on its own
+   branch (`git worktree add ../wt-<id> -b <branch>`), never in the shared
+   checkout — so concurrent cycles / sessions never collide. Finish by
+   pushing the branch and opening a PR; `main` is PR-protected — NEVER
+   `git push origin main`. (Under `roll-loop` the runner creates the
+   worktree + branch and opens the PR; this rule is the manual-path
+   equivalent and must hold either way.)
+
 1. **No local-only "done"**
    Work is not complete until it reaches:
    commit → push → CI signal → deploy → online verification → backlog update
@@ -782,7 +794,7 @@ 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/notes/<date>-roll-build-<US-id>-<epoch>.md`
+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)
 with YAML frontmatter so trend analysis (US-SKILL-014) can aggregate later:
 
 ```bash

package/skills/roll-design/SKILL.md

@@ -132,8 +132,9 @@ Document structure (story-first layout, US-META-005):
 
 **File path resolution:**
 1. Determine epic from story ID prefix (e.g., US-META-* → backlog-lifecycle, FIX-* → query index.json)
-2. Create story folder: `.roll/features/<epic>/<story>/`
-3. Write spec.md: `.roll/features/<epic>/<story>/spec.md` (full AC + details)
+2. Mint the card via the single channel (US-META-009 — never hand-create the folder):
+   `roll story new <ID> --title "<one-line title>" --epic <epic>`
+3. Then EDIT the minted spec.md to add the full AC / Files / Dependencies / Agent profile
 4. Backlog row links to: `.roll/features/<epic>/<story>/spec.md`
 5. Design / plan docs (when needed): `.roll/features/<epic>/<feature>.md` + `<feature>-plan.md`
 

package/skills/roll-fix/SKILL.md

@@ -48,6 +48,14 @@ Before creating any file or directory:
 
 ## Hard Rules
 
+0. **Worktree-first, PR-at-end (ALWAYS)**
+   Before editing, work in a dedicated git worktree on its own branch
+   (`git worktree add ../wt-<id> -b <branch>`), never the shared checkout —
+   concurrent cycles/sessions must not collide. Finish by pushing the branch
+   and opening a PR; `main` is PR-protected — NEVER `git push origin main`.
+   (Under `roll-loop` the runner handles the worktree + PR; this rule is the
+   manual-path equivalent and holds either way.)
+
 1. **No local-only "done"**
    Even for a minor change, the work is not complete until it reaches:
    - TCR micro-commits (test-guaranteed working states)
@@ -276,14 +284,17 @@ $roll-.review staged
 
 **Note:** `code-reviewer` placeholder replaced with `$roll-.review` for local execution.
 
-### 7. Commit and push
+### 7. Commit and push (branch + PR — NEVER direct to main)
 
-```bash
-# TCR commits already made during implementation
-# May squash or keep micro-commits based on repo convention
+`main` is PR-protected. Push the worktree's branch and open a PR — never
+`git push origin main`. (Under `roll-loop` the runner already made the
+worktree + branch and opens the PR; this is the manual-path equivalent.)
 
-git pull origin main --rebase
-git push origin main
+```bash
+# TCR commits already made on the worktree's branch (see Hard Rule 0).
+git push -u origin <branch>
+gh pr create --title "{fix|hotfix}: …" --body "…"
+# After CI is green: gh pr merge --rebase
 ```
 
 Commit message:
@@ -500,7 +511,7 @@ A minor change is only "done" when all are true:
 ### Self-score (US-SKILL-011)
 
 Before exiting the cycle, write one self-score note. The helper validates
-inputs and lands the note under `.roll/notes/<date>-roll-fix-<FIX-id>-<epoch>.md`:
+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):
 
 ```bash
 bash -c 'source "$(command -v roll)"; \