@seanyao/roll 2026.512.7 → 2026.512.8

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v2026.512.8
+- **Added**: `$roll-doc` — legacy 项目文档自动化技能：四阶段扫描（索引 + 缺口分析 + 草稿补全 + 报告），支持 `--dry-run` / `--force`，适用任何项目
+- **Added**: `roll-.dream` Scan 6 — 文档新鲜度检测（滞后文档 / 未记录 ENV 变量 / 架构文档缺失），依赖 roll-doc，发现写入 REFACTOR 条目
+- **Fixed**: loop CI gate 在 SSH config 改写 github.com 为 IP 的环境下失灵 — `gh` 自动识别失败被静默吞掉，loop 把 "gh 出错" 误判为 "gh 未装"，在 CI 红的情况下继续把 story 标 ✅ Done；现从 git remote 推导 `owner/repo` 强制传 `-R`，gh 调用失败 = ALERT，loop 起跑前先验 HEAD CI 红绿，红则拒绝 build
+
 ## v2026.512.7
 - **Added**: `roll alert` — 查看、确认、清除 loop 告警，不用再去翻 loop status
 - **Added**: macOS 系统通知 — story 完成或告警写入时自动弹通知，静音模式下不打扰

package/README.md

@@ -19,12 +19,13 @@
 
 ## What is Roll?
 
-Roll is an instruction and workflow framework for AI agents — it encodes proven engineering practices (TDD, TCR, SRE, INVEST) as skills any agent can follow, distributes unified conventions to every AI client on your machine, and optionally lets the agent work unattended via an autonomous evolution layer.
+Roll is an autonomous delivery system for software teams — AI agents pick stories from your BACKLOG, execute them with encoded engineering discipline, and ship continuously while you stay focused on what to build next.
 
-**Three core values:**
-1. **Any agent, same constraints** — Claude, Cursor, Kimi, DeepSeek, Codex all receive identical engineering guardrails
-2. **Skill system** — 20 skills encode research → design → build → check → fix as reliable, repeatable workflows
-3. **Autonomous evolution** — `roll loop on` runs BACKLOG items hourly; humans retain sole release authority
+**Two core values:**
+1. **Autonomous delivery** — `roll loop on` runs BACKLOG items hourly; Dream (nightly code-health scan) surfaces maintenance tasks; humans retain sole release authority
+2. **Skill-driven execution** — 20+ skills encode TDD, TCR, and INVEST practices as reliable, repeatable workflows any agent can follow
+
+_Works with Claude, Cursor, Codex, or your own agent._
 
 ---
 

package/bin/roll

@@ -4,7 +4,7 @@ set -euo pipefail
 # Roll — AI Agent Convention Manager
 # Single source of truth for how all AI coding agents behave.
 
-VERSION="2026.512.7"
+VERSION="2026.512.8"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -2595,11 +2595,12 @@ _loop_runs_dur() {
 }
 
 # Format a single JSONL run record for display.
+# Reads _LOOP_RUNS_BACKLOG global for ID→description lookup (set by _loop_runs).
 _loop_runs_format_line() {
-  local line="$1" show_project="$2"
+  local line="$1" show_project="$2" is_darwin="$3"
   command -v jq >/dev/null 2>&1 || { echo "  (jq required)"; return 0; }
 
-  local ts status project tcr duration alerts run_id reason built_count built_csv skipped_count
+  local ts status project tcr duration alerts run_id reason built_count skipped_count
   ts=$(jq -r '.ts // ""' <<<"$line")
   status=$(jq -r '.status // ""' <<<"$line")
   project=$(jq -r '.project // ""' <<<"$line")
@@ -2609,10 +2610,16 @@ _loop_runs_format_line() {
   run_id=$(jq -r '.run_id // ""' <<<"$line")
   reason=$(jq -r '.reason // ""' <<<"$line")
   built_count=$(jq -r '(.built // []) | length' <<<"$line")
-  built_csv=$(jq -r '(.built // []) | join(", ")' <<<"$line")
   skipped_count=$(jq -r '(.skipped // []) | length' <<<"$line")
 
-  local hhmm; hhmm=$(printf "%s" "$ts" | sed -E 's/.*T([0-9]{2}):([0-9]{2}).*/\1:\2/')
+  local hhmm epoch=""
+  if [[ "$is_darwin" == "1" ]]; then
+    epoch=$(date -j -u -f "%Y-%m-%dT%H:%M:%SZ" "$ts" "+%s" 2>/dev/null) || epoch=""
+    [[ -n "$epoch" ]] && hhmm=$(date -j -f "%s" "$epoch" "+%H:%M" 2>/dev/null) || hhmm=""
+  else
+    hhmm=$(date -d "$ts" "+%H:%M" 2>/dev/null) || hhmm=""
+  fi
+  [[ -z "$hhmm" ]] && hhmm=$(printf "%s" "$ts" | sed -E 's/.*T([0-9]{2}):([0-9]{2}).*/\1:\2/')
   local prefix=""
   if [[ "$show_project" == "true" ]]; then
     prefix="[$(basename "$project")] "
@@ -2622,8 +2629,29 @@ _loop_runs_format_line() {
     built)
       local skipped_note=""
       [[ "$skipped_count" -gt 0 ]] && skipped_note=", ${skipped_count} skipped"
-      printf "  %s  %s✅ built %s  (%d items, %d tcr%s, %s)\n" \
-        "$hhmm" "$prefix" "$built_csv" "$built_count" "$tcr" "$skipped_note" "$(_loop_runs_dur "$duration")"
+      local items_word; [[ "$built_count" -eq 1 ]] && items_word="item" || items_word="items"
+      printf "  %s  %s✅ built %d %s (%d tcr%s, %s)\n" \
+        "$hhmm" "$prefix" "$built_count" "$items_word" "$tcr" "$skipped_note" "$(_loop_runs_dur "$duration")"
+      local id desc
+      while IFS= read -r id; do
+        [[ -z "$id" ]] && continue
+        desc=""
+        if [[ -n "$_LOOP_RUNS_BACKLOG" ]]; then
+          desc=$(printf "%s\n" "$_LOOP_RUNS_BACKLOG" | awk -F'|' -v id="$id" '
+            NF >= 3 {
+              cell = $2; gsub(/^[[:space:]]+|[[:space:]]+$/, "", cell)
+              if (cell == id || cell ~ "^\\[" id "\\]") {
+                gsub(/^[[:space:]]+|[[:space:]]+$/, "", $3); print $3; exit
+              }
+            }')
+        fi
+        if [[ -n "$desc" ]]; then
+          [[ ${#desc} -gt 72 ]] && desc="${desc:0:69}..."
+          printf "    • %-14s %s\n" "$id" "$desc"
+        else
+          printf "    • %s\n" "$id"
+        fi
+      done < <(jq -r '(.built // []) | .[]' <<<"$line")
       ;;
     idle)
       printf "  %s  %s○ idle — no Todo items\n" "$hhmm" "$prefix"
@@ -2676,10 +2704,17 @@ _loop_runs() {
   local reversed; reversed=$(printf "%s\n" "$filtered" | awk '{a[NR]=$0} END{for(i=NR; i>=1; i--) print a[i]}')
   local recent; recent=$(printf "%s\n" "$reversed" | head -n "$n")
 
+  local _is_darwin=""
+  [[ "$(uname)" == "Darwin" ]] && _is_darwin="1"
+
+  _LOOP_RUNS_BACKLOG=""
+  [[ -f "$project_path/BACKLOG.md" ]] && _LOOP_RUNS_BACKLOG=$(cat "$project_path/BACKLOG.md")
+
   while IFS= read -r line; do
     [[ -z "$line" ]] && continue
-    _loop_runs_format_line "$line" "$all_flag"
+    _loop_runs_format_line "$line" "$all_flag" "$_is_darwin"
   done <<<"$recent"
+  unset _LOOP_RUNS_BACKLOG
 }
 
 # Send a macOS system notification. No-op when muted, non-macOS, or osascript unavailable.
@@ -2699,9 +2734,27 @@ _loop_tcr_count() {
     | awk '/^[a-f0-9]+ tcr:/{n++} END{print n+0}'
 }
 
+# Parse origin remote URL → "owner/repo" for GitHub repos.
+# Returns non-zero if no origin, or origin is not github.com.
+# Decoupled from `gh` auto-detection so SSH config host rewrites don't break it.
+_gh_repo_slug() {
+  local url
+  url=$(git config --get remote.origin.url 2>/dev/null) || return 1
+  case "$url" in
+    git@github.com:*)          url="${url#git@github.com:}" ;;
+    ssh://git@github.com/*)    url="${url#ssh://git@github.com/}" ;;
+    https://github.com/*)      url="${url#https://github.com/}" ;;
+    http://github.com/*)       url="${url#http://github.com/}" ;;
+    *)                         return 1 ;;
+  esac
+  url="${url%.git}"
+  [[ -z "$url" ]] && return 1
+  printf "%s\n" "$url"
+}
+
 # Poll gh run list until current commit's CI completes.
-# Returns 0 on success or when gh is unavailable (graceful skip).
-# Returns 1 on CI failure or timeout.
+# Returns 0 on success (or when gh binary missing — graceful skip).
+# Returns 1 on CI failure, timeout, or any gh call failure.
 _ci_wait() {
   local timeout="${1:-300}"
   local interval=15
@@ -2712,13 +2765,20 @@ _ci_wait() {
   local commit; commit=$(git rev-parse HEAD 2>/dev/null) || { err "Not a git repo  非 git 仓库"; return 1; }
   local short; short=$(git rev-parse --short HEAD 2>/dev/null)
 
-  ok "Waiting for CI on ${short}  等待 CI: ${short}"
+  # Resolve owner/repo from git remote so we don't depend on gh's auto-detection,
+  # which breaks when ~/.ssh/config rewrites `Host github.com` → IP address.
+  local repo_slug; repo_slug=$(_gh_repo_slug) || {
+    err "Cannot determine GitHub repo from origin remote  无法从 origin 推导 GitHub 仓库"
+    return 1
+  }
+
+  ok "Waiting for CI on ${short} (${repo_slug})  等待 CI: ${short}"
 
   while (( elapsed < timeout )); do
     local runs
-    runs=$(gh run list --commit "$commit" --json status,conclusion 2>/dev/null) || {
-      warn "gh run list failed — skipping CI gate"
-      return 0
+    runs=$(gh -R "$repo_slug" run list --commit "$commit" --json status,conclusion 2>&1) || {
+      err "gh run list failed for ${repo_slug}@${short}: ${runs}  gh 调用失败"
+      return 1
     }
 
     if [[ -z "$runs" || "$runs" == "[]" ]]; then
@@ -2754,6 +2814,46 @@ _ci_wait() {
   return 1
 }
 
+# Pre-run CI health check — call before picking up new stories.
+# Refuses to build on a red base (HEAD CI failed). Lenient on unknown states
+# (gh missing, repo unparseable, no runs yet) — the post-build _loop_enforce_ci
+# is the strict gate.
+# Returns 0: ok to proceed (green / pending / unknown / no gh).
+# Returns 1: HEAD CI is definitively red → ALERT written, do not build.
+_loop_precheck_ci() {
+  command -v gh &>/dev/null || return 0
+
+  local commit; commit=$(git rev-parse HEAD 2>/dev/null) || return 0
+  local slug; slug=$(_gh_repo_slug) || return 0
+
+  local runs
+  runs=$(gh -R "$slug" run list --commit "$commit" --json conclusion 2>/dev/null) || return 0
+  [[ -z "$runs" || "$runs" == "[]" ]] && return 0
+
+  local failed
+  failed=$(echo "$runs" | jq -r '[.[] | select(.conclusion != null and .conclusion != "success" and .conclusion != "skipped")] | length' 2>/dev/null || echo "0")
+
+  if [[ "$failed" -gt 0 ]]; then
+    local short; short=$(git rev-parse --short HEAD 2>/dev/null || echo unknown)
+    err "Pre-run CI check: HEAD CI is red — refuse to build on broken base (${short})  HEAD CI 红，拒绝在破损的基础上构建"
+    mkdir -p "$(dirname "$_LOOP_ALERT")"
+    cat > "$_LOOP_ALERT" << EOF
+# ALERT — Pre-run CI check failed (red base)
+
+**Time**: $(date '+%Y-%m-%d %H:%M')
+**Commit**: ${short}
+**Reason**: HEAD CI is red — loop refused to build on a broken base  HEAD CI 红，loop 拒绝在破损的基础上构建
+
+**Action required**:
+- Investigate and fix CI: \`gh -R $(_gh_repo_slug) run list --commit ${commit}\`
+- After fixing and pushing green commit: \`roll loop now\`
+EOF
+    _notify "roll ⚠ CI red" "loop refused to build on broken base (${short})"
+    return 1
+  fi
+  return 0
+}
+
 # CI gate before marking a story Done.
 # On CI failure: writes ALERT, returns 1 (caller keeps story 🔨 In Progress).
 # When gh unavailable: returns 0 (graceful skip).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.512.7",
+  "version": "2026.512.8",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "bash tests/run.sh"

package/skills/roll-.dream/SKILL.md

@@ -6,8 +6,9 @@ allowed-tools: "Read, Glob, Grep, Bash(git:*), Write, Edit"
 description: |
   Nightly code and architecture health scan. Passively triggered by scheduler
   (cron or GitHub Actions), not invoked by users directly. Detects dead code,
-  architectural drift from domain model, pruning candidates, and emerging patterns.
-  Outputs REFACTOR entries to BACKLOG.md and a daily log to docs/dream/.
+  architectural drift from domain model, pruning candidates, emerging patterns,
+  doc coverage gaps, and doc staleness (文档新鲜度). Outputs REFACTOR entries
+  to BACKLOG.md and a daily log to docs/dream/.
   Distinct from roll-sentinel: sentinel monitors runtime behavior; dream reviews
   code structure and architectural health.
 ---
@@ -33,7 +34,7 @@ in the morning brief.
 
 ## Scan Logic
 
-Run all four scans every night. Each scan is independent.
+Run all six scans every night. Each scan is independent.
 
 ### Scan 1 — Dead Code
 
@@ -68,6 +69,8 @@ Flag: modules that import directly from a different Bounded Context without
 an Anti-Corruption Layer, or module names that have diverged from the
 Ubiquitous Language.
 
+**Distinction from Scan 6C**: Scan 2 flags *import boundary violations* (cross-context coupling). Scan 6C flags *missing documentation entries* (module exists but has no entry in `docs/domain/*.md`). Never double-flag — Scan 2 and Scan 6C are orthogonal checks.
+
 ### Scan 3 — Pruning Candidates
 
 Find over-engineering that can be simplified:
@@ -137,6 +140,77 @@ Flag any `.md` file directly in `docs/` root (allowed subdirs: `guide/`, `domain
 {发现内容 或 "文档结构符合规范，无缺口。"}
 ```
 
+### Scan 6 — 文档新鲜度 (Doc Freshness)
+
+**Dependency gate**: Skip Scan 6 entirely when `$roll-doc` (US-SKILL-008) is not yet deployed.
+Check: `[ -f "$ROLL_HOME/skills/roll-doc/SKILL.md" ]`. If absent, log "Scan 6 skipped — roll-doc not deployed" in the dream log and stop. No fallback.
+
+When deployed, each finding produces a REFACTOR entry with `$roll-doc` as execution hint:
+```markdown
+| REFACTOR-XXX | docs: <description> — flagged by dream <date> (hint: $roll-doc) | 📋 Todo |
+```
+
+#### Check A — Stale Docs
+
+Flag source files whose owning doc is >30 days stale:
+
+```bash
+# For each file listed in docs/features/*.md or README.md "## Files:" sections:
+#   owner_doc_commit = git log -1 --format="%ci" -- <doc_file>
+#   source_commit    = git log -1 --format="%ci" -- <source_file>
+#   lag_days = (source_commit - owner_doc_commit) in days
+#   if lag_days > 30 AND doc contains at least one specific file path reference → flag
+```
+
+The "owner doc" for a source file is the nearest `README.md` or `docs/features/*.md` that lists the file path in a `## Files:` section. Skip docs that contain only conceptual descriptions (no specific file path references) — they cannot be objectively stale.
+
+#### Check B — Undocumented ENV Vars
+
+Flag environment variables that appear frequently in source but have no documentation:
+
+```bash
+# Detect ENV var patterns in non-test source files:
+patterns=(
+  'process\.env\.[A-Z_]+'        # Node.js
+  'os\.getenv\("[A-Z_]+"\)'      # Python
+  'ENV\["[A-Z_]+"\]'             # Ruby
+)
+# For each matched variable name:
+#   count occurrences across all source files
+#   if count >= 5 AND zero mentions in any .md file → flag
+```
+
+Flag variables appearing ≥5× in source with zero mentions in any `.md`.
+"Other convention signals" (comment clusters, module structure templates) are explicitly deferred — too vague for deterministic detection.
+
+#### Check C — Existence Drift
+
+Find module directories that exist in code but are absent from architecture docs.
+This is distinct from Scan 2 (which checks *import violations*) — Scan 6C checks *documentation existence*:
+
+```bash
+# Walk all non-excluded directories
+# For each dir with >= 3 non-hidden, non-.md source files:
+#   check if any docs/domain/*.md contains the directory name
+#   if not found → flag as "existence drift"
+```
+
+Exclusions: `node_modules/`, `.git/`, `dist/`, `build/`, `.shared/`, `docs/`, `tests/`.
+
+Flag directories with ≥3 source files and zero name-match in `docs/domain/*.md`.
+
+#### Dream Log Section
+
+Add after `## 文档覆盖度` section:
+
+```markdown
+## 文档新鲜度
+- 滞后文档：{N} 个（超过 30 天未更新但绑定了代码文件）
+- 未记录 ENV 变量：{N} 个（出现 ≥5 次但无文档）
+- 架构文档缺失模块：{N} 个（≥3 个源文件的目录未出现在 docs/domain/）
+{发现内容列表 或 "文档新鲜度良好，无滞后或缺失项。"}
+```
+
 ## Output
 
 ### REFACTOR Entry (BACKLOG.md)
@@ -161,7 +235,7 @@ without context switching:
 # Dream Log {YYYY-MM-DD}
 
 ## 概要
-- 扫描项：死代码 / 架构漂移 / 裁剪候选 / 新兴模式 / 文档覆盖度
+- 扫描项：死代码 / 架构漂移 / 裁剪候选 / 新兴模式 / 文档覆盖度 / 文档新鲜度
 - 发现：{N} 项标记，{M} 个 REFACTOR 条目已创建
 
 ## 死代码
@@ -176,6 +250,15 @@ without context switching:
 ## 新兴模式
 {发现内容 或 "未发现可提取的重复模式。"}
 
+## 文档覆盖度
+{发现内容 或 "文档结构符合规范，无缺口。"}
+
+## 文档新鲜度
+- 滞后文档：{N} 个
+- 未记录 ENV 变量：{N} 个
+- 架构文档缺失模块：{N} 个
+{发现内容 或 "文档新鲜度良好，无滞后或缺失项。"}
+
 ## 创建的 REFACTOR 条目
 {列表 或 "无。"}
 ```

package/skills/roll-doc/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: roll-doc
+license: MIT
+allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(date:*,find:*,stat:*,wc:*)"
+description: "Legacy project documentation automation. Scans all docs, builds/updates docs/INDEX.md, identifies undocumented modules, and generates draft fills for gaps. Works on any project."
+---
+
+# roll-doc
+
+Four-phase legacy documentation automation: scan → index → gap analysis → fill.
+
+Works on any project root. No manual mode switching — reads the project state and decides what to do.
+
+## When to Use
+
+- Starting to work on a legacy project with scattered or missing documentation
+- `docs/INDEX.md` is out of date or doesn't exist yet
+- `roll-.dream` Scan 6 flagged undocumented modules (REFACTOR entry referencing roll-doc)
+- You want a complete picture of what's documented and what isn't
+
+## When Not to Use
+
+- The project has up-to-date, maintained docs — no need to rebuild the index
+- You need authoritative documentation reviewed and approved (drafts only; human reviews and commits)
+- You want to write a specific known doc from scratch — write it directly
+
+## Invocation
+
+```
+$roll-doc              # Full four-phase run
+$roll-doc --dry-run    # Phases 1–2 only; print Phase 3 plan without writing any files
+$roll-doc --force      # Re-generate drafts even for existing files
+```
+
+## Phase 1 — Scan & Index
+
+Scan the project root for all `*.md` files and known convention files.
+
+**Exclusions — never scan these directories:**
+
+```
+node_modules/   .git/   dist/   build/   .shared/   docs/dream/   docs/briefs/
+```
+
+**Convention files — detect by filename anywhere in the tree:**
+
+```
+AGENTS.md   CLAUDE.md   GEMINI.md   CONVENTIONS.md   CONTRIBUTING.md
+ARCHITECTURE.md   ADR-*.md
+```
+
+**Classification rules:**
+
+| Category | Criteria |
+|----------|----------|
+| `guide` | Path under `docs/guide/` |
+| `domain` | Path under `docs/domain/` |
+| `convention` | Filename matches convention markers list above |
+| `module` | File is `<dir>/README.md` for a source directory |
+| `stray` | None of the above (top-level, unorganized, or orphaned) |
+
+**Output — produce/update `docs/INDEX.md`:**
+
+```markdown
+# Documentation Index
+
+> Auto-generated by roll-doc on YYYY-MM-DD. Edit individual docs, not this file.
+
+## Index
+
+| Path | Title | Category | Last Modified |
+|------|-------|----------|---------------|
+| docs/guide/en/loop.md | Loop User Guide | guide | 2026-05-01 |
+| AGENTS.md | Agent Conventions | convention | 2026-04-28 |
+
+## Coverage Summary
+
+- Total docs indexed: N
+- By category: guide (N) / domain (N) / convention (N) / module (N) / stray (N)
+
+## Gap Report
+
+Directories with ≥3 source files and no linked documentation:
+
+| Directory | Source Files | Missing Doc |
+|-----------|-------------|-------------|
+| src/commands/ | 8 | README.md |
+```
+
+`docs/INDEX.md` is always overwritten on each run — it is a derived artifact, not authoritative content.
+
+## Phase 2 — Gap Analysis
+
+Walk every directory (applying Phase 1 exclusions):
+
+1. Count non-hidden, non-`.md` source files directly in the directory
+2. If count ≥ 3 AND no `README.md` in that directory AND no `docs/INDEX.md` entry links to it → **module gap**
+
+**Special gaps (checked once per project):**
+- No `docs/domain/` directory or empty → gap: `docs/domain/context-map.md`
+- No `CONVENTIONS.md` or `docs/CONVENTIONS.md` exists → gap: `docs/CONVENTIONS.md`
+
+**Threshold**: directories with ≥ 3 source files (default). Tune by editing the skill.
+
+Record all gaps — they become Phase 3 input.
+
+## Phase 3 — Fill
+
+**Skip this phase entirely when:**
+- `--dry-run` was passed (print the fill plan to stdout, write nothing)
+- Phase 2 found zero gaps
+
+**Idempotency rule**: Without `--force`, re-running when no new gaps exist is a **no-op** — no files are written, no existing drafts are modified.
+
+For each gap:
+1. Read up to 20 source files from the target directory to infer module purpose, key exports, dependencies, and configuration patterns
+2. Generate a draft document at the conventional location (see table below)
+3. **Skip if the target file already exists**, unless `--force` was passed
+
+**Draft locations by gap type:**
+
+| Gap Type | Draft Location |
+|----------|---------------|
+| Module with no README | `<dir>/README.md` |
+| No `docs/domain/` entries | `docs/domain/context-map.md` |
+| No conventions doc | `docs/CONVENTIONS.md` |
+
+**Every generated file starts with this exact header line:**
+
+```
+> **Draft** — auto-generated by roll-doc on YYYY-MM-DD. Review before treating as authoritative.
+```
+
+**Minimum draft content:**
+
+- Module README: purpose (1–2 sentences), key files with one-line descriptions, dependencies (imports from / depended on by)
+- Context map: bounded contexts identified in the project, their responsibilities, relationships
+- Conventions: detected patterns — ENV vars, naming conventions, repeated file structure templates
+
+Do not fabricate details — infer only from source files actually read.
+
+## Phase 4 — Report
+
+After all phases complete, output a summary:
+
+```
+📚 roll-doc complete
+
+Phase 1 — Index
+  N docs scanned, docs/INDEX.md updated
+  Categories: guide(N) domain(N) convention(N) module(N) stray(N)
+
+Phase 2 — Gaps
+  N undocumented module directories found
+  N special gaps (domain map / conventions)
+
+Phase 3 — Fill
+  N drafts generated: [list of paths]
+  N skipped (already exist; use --force to regenerate)
+
+📋 Review priority (largest / most active modules first):
+  1. src/commands/README.md — 8 source files
+  2. docs/CONVENTIONS.md — 6 patterns detected
+```
+
+If no gaps were found:
+
+```
+✅ roll-doc: no gaps found. docs/INDEX.md updated.
+```
+
+If `--dry-run`:
+
+```
+🔍 roll-doc --dry-run: N drafts would be generated (nothing written).
+```
+
+## Rules
+
+- Never modify existing documentation files — only generate new drafts
+- `docs/INDEX.md` is the only existing file that may be overwritten (derived artifact)
+- Draft files are never committed by this skill — human reviews and commits them
+- Works on any project; always read project structure before acting
+- Do not fabricate module details — infer only from source files actually read

package/skills/roll-loop/SKILL.md

@@ -68,7 +68,21 @@ fi
 2. For each such story, check `state.yaml`:
    - If `current_item` matches the story id AND `status: running` → this is the resume case (handled above), leave it.
    - Otherwise → this is an **orphan 🔨** (the loop that marked it crashed before finishing). Revert the status back to `📋 Todo`, commit `chore: revert orphan 🔨 US-XXX to 📋`, and append a line to `~/.shared/roll/loop/ALERT.md` recording the orphan id and time so the next brief surfaces it.
-3. After orphan sweep, proceed to Step 2 (Scan BACKLOG) — the reverted stories will be picked up normally if they're top of the queue.
+3. After orphan sweep, proceed to Step 1.5 (Pre-run CI health check) before scanning.
+
+### Step 1.5 — Pre-run CI Health Check
+
+Call `_loop_precheck_ci` before scanning BACKLOG. This is a **defensive gate**
+against building on a broken base — if the most recent commit on the branch
+has red CI, the loop must not stack new commits on top (which would create the
+exact stuck-red state FIX-026 traces to).
+
+- HEAD CI green / pending / no-run-yet → proceed to Step 2.
+- HEAD CI red → write ALERT, **do not pick up any stories this cycle**,
+  exit cleanly. The next cycle will retry; the human must fix CI manually
+  (typically by reverting or pushing a green commit) before the loop resumes.
+- `gh` missing or repo unparseable → graceful skip (`_loop_precheck_ci`
+  returns 0); the post-build `_loop_enforce_ci` remains the strict gate.
 
 ### Step 2 — Scan BACKLOG
 
@@ -142,11 +156,18 @@ After each item completes:
    - Count `tcr:` prefix commits since `started_at` via `git log --oneline --since=<started_at>`
    - Count == 0 → revert story status in BACKLOG.md from ✅ Done → 📋 Todo; write ALERT to `~/.shared/roll/loop/ALERT.md` with story ID, time, reason "zero tcr: commits since story start", and suggested actions (`roll loop now` / `$roll-build <id>` / `roll loop reset`)
    - Count > 0 → continue normally
-2. **CI Gate** — call `roll ci --wait` (or `_loop_enforce_ci <story_id>`):
-   - Polls `gh run list --commit <HEAD>` until all CI runs complete
+2. **CI Gate** — **MUST** invoke `roll ci --wait` (the `_loop_enforce_ci`
+   wrapper). **Do NOT call `gh` directly** (no `gh run list`, no `gh run watch`,
+   no ad-hoc shell checks): `roll ci --wait` is the only sanctioned entry —
+   it derives `owner/repo` from the git remote and uses `gh -R <slug>`, which
+   is required to work through `~/.ssh/config` host rewrites that break gh's
+   auto-detection.
    - CI passes → continue normally
-   - CI fails or times out → keep story as `🔨 In Progress` (do NOT mark ✅ Done); write ALERT; skip to next story
-   - `gh` not installed → skip gracefully (return 0)
+   - CI fails / times out / `gh` call fails → keep story as `🔨 In Progress`
+     (do NOT mark ✅ Done); write ALERT; skip to next story
+   - `gh` binary not installed (`command -v gh` fails) → skip gracefully
+     (return 0). Any other `gh` error is **not** "gh unavailable" — it is a
+     hard failure and must block the gate.
 3. Update state file: `status: idle`
 4. Check if a Feature is now fully complete (all its Stories ✅)
 5. If yes and `brief_on_feature_complete: true` → invoke `Skill("roll-brief")`