@seanyao/roll 2026.424.4 → 2026.504.1

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.424.4"
+VERSION="2026.504.1"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"

package/conventions/global/AGENTS.md

@@ -6,6 +6,15 @@
 - User's language. Code/Git/Comments: English. UI: Chinese.
 - Concise. No summaries/code-walking. Implementation invisible.
 - Strategy (Why) OK; Tactics (How) NO. Outcomes only.
+- **Ambiguity resolution**: When user says "explicit" in automation contexts,
+  interpret as "logged/observable with clear output", NOT "requiring manual
+  intervention". Confirm with one question if uncertain.
+- **Bilingual output**: EN + ZH on separate lines, never inline.
+  ```
+  Processing...
+  处理中...
+  ```
+  Not: `Processing... 处理中...`
 
 ## 2. Code
 - **TS**: Strict, no `any`. Functional hooks. Early returns.
@@ -20,5 +29,23 @@
 
 ## 4. Workflow
 - **TCR**: Test -> Green = Commit / Red = Revert. No WIP commits.
+  - Before implementing: confirm exact files, test strategy, and commit message
+    draft with user. Do not write code until approved.
+  - Before claiming completion: verify in the target environment mentioned by
+    user (e.g., specific CLI tool, remote server, hardware platform).
 - **Workspace**: `BACKLOG.md` index. `docs/features/` for details.
 - **Done**: Push + CI passes + deployed. Local-only is not done.
+
+## 5. Refactoring & Renames
+
+Project-wide renames require systematic checking. Never assume find/replace
+is sufficient. Execute in order:
+
+1. **Code references** — imports, function names, string literals
+2. **Documentation** — README, methodology, API docs
+3. **Config files** — YAML frontmatter, package names, manifests
+4. **Symlinks** — verify all resolve after rename
+5. **Installer scripts** — update paths and references
+6. **Shell environment** — remind user to reload or restart sessions
+
+Confirm each phase clean before proceeding to the next.

package/conventions/global/CLAUDE.md

@@ -17,12 +17,33 @@
 
 ## Claude Code-Specific
 
-- When a project has Roll skills, use them (`$roll-design`, `$roll-story`, etc.).
+- When a project has Roll skills, use them (`$roll-design`, `$roll-build`, `$roll-fix`, etc.).
 - Use plan mode for complex multi-step tasks before executing.
 - Prefer Edit tool over Bash for file modifications.
 - Use Agent tool with worktree isolation for parallel independent subtasks.
 - When I say "帮我看下" or "处理下", go ahead and do it, not just analyze it.
 
+## Verification and Testing
+
+Before claiming any fix is complete, verify it works in the target environment
+mentioned by the user. If they said a specific CLI tool, remote server, or
+hardware platform, test there explicitly. Do not claim completion until verified.
+
+## Configuration File Editing
+
+When editing config files (YAML, TOML, JSON with schema):
+1. Find official documentation or a verified working example first
+2. Do not guess syntax
+3. If no docs found after 2 searches, ask user for a reference config
+4. Maximum 2 syntax attempts before escalating to research mode
+
+## External Service Integration
+
+For npm publishing, proxy configurations, or auth-dependent deployment:
+- Stop after 2 failed attempts and ask user for preferred fallback
+- Do not continue iterating on auth/proxy debugging without explicit direction
+- If OIDC/token issues persist, immediately fallback to manual with explanation
+
 ## Frontend Default Stack
 
 - React + shadcn/ui + Tailwind CSS is the default.

package/conventions/templates/fullstack/CLAUDE.md

@@ -13,5 +13,5 @@
 
 - Use `$roll-design` to plan features that span frontend and backend.
 - When modifying API contracts, update both `api/types.ts` and `src/shared/types/` in the same commit.
-- Use worktree isolation for parallel frontend/backend Actions in `$roll-story-build`.
+- Use worktree isolation for parallel frontend/backend Actions in `$roll-build`.
 - Run `npm run build` to verify both frontend and backend compile before pushing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.424.4",
+  "version": "2026.504.1",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "find tests/unit tests/integration -name '*.bats' | sort | xargs ./tests/helpers/bats-core/bin/bats"

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

@@ -208,4 +208,4 @@ If project lacks Playwright setup:
 
 - [Playwright Docs](https://playwright.dev/)
 - [Visual Regression Guide](https://playwright.dev/docs/test-snapshots)
-- Example implementation: `seanyao/kids-game/e2e/`
+- Example implementation: `<owner>/<repo>/e2e/`

package/skills/roll-debug/SKILL.md

@@ -1,16 +1,19 @@
 ---
 name: roll-debug
 license: MIT
-description: Universal web debugger. Collects diagnostics (console/network/DOM) via Playwright, analyzes root causes, and suggests fixes. Works with or without Black Box (BB) integration.
+description: Universal web debugger. Mounts a Black Box (BB) diagnostic probe on any page, collects rich diagnostics, analyzes root causes, and suggests fixes. Cleans up after itself.
 ---
 
 # Roll Debug
 
-Universal web debugging tool that combines diagnostic collection and analysis into a single workflow: **Diagnose → Analyze → Suggest Fix**.
+Web debugging tool that treats the **Black Box (BB) as a diagnostic probe** — mounted when needed, unmounted when done. Combines diagnostic collection and analysis into a single workflow: **Mount → Collect → Analyze → Unmount**.
 
-Two collection modes:
-- **Native BB Mode**: Page has Black Box integrated; click button to collect rich diagnostic data
-- **Universal Diagnostic Mode**: Page has no BB; use Playwright to directly collect console/network/DOM/screenshot data
+## Philosophy
+
+- BB is a **diagnostic probe**, not a product feature. Pages do not need to integrate BB natively.
+- For any web diagnosis, **mount BB first** (unless already present).
+- The entire lifecycle is **explicit and visible**: you see when BB mounts, when it collects, and when it unmounts.
+- A visible **BB button** appears on the page during diagnosis so you always know the probe is active.
 
 ## When to Use
 
@@ -31,15 +34,18 @@ Two collection modes:
 ## Quick Start
 
 ```bash
-# Full workflow: collect + analyze + suggest fix (recommended)
+# Full workflow: mount + collect + analyze + unmount (recommended)
 $roll-debug https://example.com/page
 
 # Collect data only, skip analysis
 $roll-debug https://example.com/page --no-analyze
 
-# Force universal diagnostic mode (no BB)
+# Skip BB mount, use built-in universal collector
 $roll-debug https://example.com/page --universal
 
+# Use a custom BB SDK instead of the built-in stub
+$roll-debug https://example.com/page --bb-sdk-url https://cdn.example.com/bb.js
+
 # Collect + analyze + auto-fix
 $roll-debug https://example.com/page --fix
 
@@ -51,44 +57,21 @@ $roll-debug https://site.com/page1,https://site.com/page2
 $roll-debug --file urls.txt
 ```
 
-## Two Collection Modes
-
-### Mode 1: Native BB (Page has Black Box integrated)
-
-```
-Page with BB  →  Playwright clicks BB button  →  Download diagnostic JSON
-```
-
-Requirements:
-- Page has `[data-testid="bb-toggle"]` button
-- Or exposes `window.__BB_DATA__`
-- Or stores data in `localStorage.bb_diagnostic`
-
-### Mode 2: Universal Diagnostic (No BB required)
-
-```
-Any page  →  Playwright injects collector  →  Gather console/network/DOM/screenshot
-```
-
-Collects:
-- Console logs (error/warn/info)
-- Network requests (failed XHR/fetch, slow requests)
-- DOM state (key elements visibility, HTML length)
-- Screenshot (full page + viewport)
-- Performance metrics (load time, FCP, LCP, render blocking)
-- JavaScript errors with stack traces
-
-## Full Workflow
+## BB Probe Lifecycle
 
 ```
 User: "Debug the page"
     │
     ▼
 ┌─────────────────────────────────────┐
-│ 1. Auto-detect collection mode      │
-│    ├── Try BB button → found?       │
-│    ├── Try window.__BB_DATA__?      │
-│    └── Fallback to Universal        │
+│ 1. Mount BB Probe                   │
+│    ├── Check: page already has BB?  │
+│    │   ├── Yes → reuse existing     │
+│    │   └── No  → inject BB          │
+│    │       ├── Built-in stub (default)
+│    │       └── Custom SDK (--bb-sdk-url)
+│    ├── Wait for initialization      │
+│    └── BB button appears on page    │
 └──────────────────┬──────────────────┘
                    │
                    ▼
@@ -97,6 +80,7 @@ User: "Debug the page"
 │    ├── Console logs                 │
 │    ├── Network requests             │
 │    ├── DOM state                    │
+│    ├── Performance metrics          │
 │    └── Screenshot                   │
 └──────────────────┬──────────────────┘
                    │
@@ -111,40 +95,82 @@ User: "Debug the page"
                    │
                    ▼
 ┌─────────────────────────────────────┐
-│ 4. Suggest (or apply) fix           │
-│    ├── Actionable fix suggestions   │
-│    ├── Auto-fix via TCR (--fix)     │
-│    └── Deploy & verify              │
-└─────────────────────────────────────┘
+│ 4. Unmount BB Probe                 │
+│    ├── Restore console/fetch/XHR    │
+│    ├── Remove BB button from DOM    │
+│    ├── Delete window.__BB_DATA__    │
+│    └── Page state fully restored    │
+└──────────────────┬──────────────────┘
+                   │
+                   ▼
+    Fix suggestions (or --fix to apply)
 ```
 
+## Collection Modes
+
+### Mode 1: Mounted BB (Default)
+
+BB probe is mounted on the page — either reused from an existing BB or freshly injected.
+
+**Visual indicator**: a red circular **BB** button appears at the bottom-right of the page.
+
+**Data collected via BB interface**:
+- Console logs (error/warn/info)
+- Network requests (failed XHR/fetch, slow requests)
+- DOM state (key elements visibility, HTML length)
+- Performance metrics (load time, FCP, LCP)
+- JavaScript errors with stack traces
+
+**BB Sources**:
+
+| Source | When Used | Capability |
+|--------|-----------|------------|
+| Existing native BB | Page already has `[data-testid="bb-toggle"]` or `window.__BB_DATA__` | Full app-specific metrics (contentState, audioState, etc.) |
+| Built-in stub | Default when no BB present | Generic metrics (console, network, DOM, performance, errors) |
+| Custom SDK | `--bb-sdk-url` provided | Determined by the SDK implementation |
+
+### Mode 2: Universal Diagnostic (No BB)
+
+When `--universal` is passed, skip BB mount entirely. Use Playwright's built-in event listeners directly.
+
+```bash
+$roll-debug https://example.com/page --universal
+```
+
+Useful when:
+- You explicitly do not want to modify the page state
+- The page has strict CSP that blocks script injection
+- You need a quick check without probe overhead
+
 ## Usage Examples
 
-### Example 1: Full auto-detect + analyze (default)
+### Example 1: Full auto-mount + analyze (default)
 
 ```bash
 $roll-debug https://yyy.up.railway.app/story/cars/chapter/1
 
-Detecting diagnostic capability...
-├── BB found: [data-testid="bb-toggle"]
-└── Using: Native BB mode
-
-Collecting data...
-├── Console: 3 errors, 5 warnings
-├── Network: 2 failed requests
-├── DOM: #app rendered, .content empty
-└── Screenshot: saved to /tmp/bb-screenshot.png
+🔍 Diagnosing https://yyy.up.railway.app/story/cars/chapter/1
+📡 Mounting BB probe...
+   ├── Source: built-in stub
+   └── Status: ready (320ms)
+   └── BB button visible on page ✓
+📊 Collecting data via BB...
+   ├── Console: 3 errors, 5 warnings
+   ├── Network: 2 failed requests
+   ├── DOM: #app rendered, .content empty
+   └── Screenshot: saved to /tmp/bb-screenshot.png
+🔬 Analyzing...
+🧹 Unmounting BB probe... done
+   └── Page state restored ✓
 
 Report: /tmp/bb-report.json
 
-Analyzing...
-
 ## Diagnostic Analysis Report
 
 ### Basic Info
 | Field | Value |
 |-------|-------|
-| Diagnostic Mode | native-bb |
+| Diagnostic Mode | mounted-bb (stub) |
 | Page URL | https://yyy.up.railway.app/story/cars/chapter/1 |
 
 ### Key Findings
@@ -165,58 +191,58 @@ Modify Player.tsx line 45, change useEffect dependency
 from `[chapter?.id]` to `[chapter?.number]`
 ```
 
-### Example 2: Universal mode (no BB)
+### Example 2: Reuse existing native BB
+
+```bash
+$roll-debug https://example.com/page
+
+🔍 Diagnosing https://example.com/page
+📡 Mounting BB probe...
+   ├── Native BB detected
+   └── Reusing existing probe
+📊 Collecting data via BB...
+   ├── Console: 0 errors
+   ├── Network: 0 failed
+   └── DOM: fully rendered
+🔬 Analyzing...
+🧹 Unmounting BB probe... skipped
+   └── Native BB left intact
+
+No issues found. Page is healthy.
+```
+
+### Example 3: Universal mode (no BB mount)
 
 ```bash
 $roll-debug https://example.com --universal
 
-Universal diagnostic mode (no BB required)
-
-Collected:
-├── Console Errors: 2
-│   ├── TypeError: Cannot read property 'id' of undefined
-│   │   at Player.tsx:45
-│   └── ReferenceError: AudioContext is not defined
-├── Failed Network: 1
-│   └── GET https://api.example.com/data 404
-├── DOM State:
-│   ├── body.innerHTML length: 2340
-│   ├── #root: rendered
-│   ├── .loading: still visible (timeout?)
-│   └── .error-message: visible
-├── Performance:
-│   ├── DOMContentLoaded: 1.2s
-│   ├── First Contentful Paint: 2.3s
-│   └── Largest Contentful Paint: 4.5s
-└── Screenshot: /tmp/bb-screenshot.png
+🔍 Diagnosing https://example.com (universal mode)
+📡 BB mount skipped (--universal)
+📊 Collecting data via Playwright events...
+   ├── Console Errors: 2
+   │   ├── TypeError: Cannot read property 'id' of undefined
+   │   │   at Player.tsx:45
+   │   └── ReferenceError: AudioContext is not defined
+   ├── Failed Network: 1
+   │   └── GET https://api.example.com/data 404
+   └── Screenshot: /tmp/bb-screenshot.png
+🔬 Analyzing...
 
 Report: /tmp/bb-report.json
 
-Analyzing...
-
 ### Key Findings
 | Metric | Value | Status |
 |--------|-------|--------|
 | Console Errors | 2 | Critical |
 | Network Failed | 1 | Critical |
-| DOM Rendering | Partial | Warning |
-| Load Time (LCP) | 4.5s | Slow |
-
-### Diagnosis Conclusion
-API endpoint returning 404 causes content not to load.
-AudioContext undefined suggests missing polyfill or browser incompatibility.
-
-### Suggested Fix
-1. Fix API route for /data endpoint (404)
-2. Add AudioContext polyfill or guard with `typeof AudioContext !== 'undefined'`
 ```
 
-### Example 3: Analyze existing report file
+### Example 4: Analyze existing report file
 
 ```bash
 $roll-debug --report /tmp/bb-report.json
 
-Reading report: /tmp/bb-report.json (mode: universal)
+Reading report: /tmp/bb-report.json (mode: mounted-bb)
 
 ### Key Findings
 ...
@@ -226,11 +252,13 @@ Reading report: /tmp/bb-report.json (mode: universal)
 
 | Format | Source | Description |
 |--------|--------|-------------|
-| Native BB | Page with Black Box | `window.__BB_DATA__` or `localStorage.bb_diagnostic` |
-| Universal | Playwright collector | Injected collector data |
+| Mounted BB (stub) | Injected built-in stub | `window.__BB_DATA__` via injectable-bb.js |
+| Mounted BB (native) | Page with existing Black Box | `window.__BB_DATA__` or `localStorage.bb_diagnostic` |
+| Mounted BB (custom) | Custom SDK via `--bb-sdk-url` | Determined by SDK |
+| Universal | Playwright native events | Direct event listener data |
 | Legacy | Old diagnostic files | Backward compatible |
 
-### Native BB Mode Fields
+### Mounted BB Mode Fields
 
 ```javascript
 const bbData = report.diagnostic.bbData;
@@ -240,6 +268,11 @@ bbData.audioState?.src
 bbData.audioState?.error
 bbData.hasAudio
 bbData.errors
+bbData.console.errors
+bbData.console.warnings
+bbData.network.failed
+bbData.dom.keyElements
+bbData.performance.loadComplete
 ```
 
 ### Universal Mode Fields
@@ -255,7 +288,6 @@ d.dom['#root']
 d.dom.htmlLength
 d.performance.loadComplete
 d.performance.domContentLoaded
-d.errors
 ```
 
 ## Analysis Report Template
@@ -266,7 +298,8 @@ d.errors
 ### Basic Info
 | Field | Value |
 |-------|-------|
-| Diagnostic Mode | {native-bb / universal} |
+| Diagnostic Mode | {mounted-bb / universal} |
+| BB Source | {native / stub / custom-sdk} |
 | Page URL | {url} |
 | Collected At | {timestamp} |
 
@@ -309,62 +342,123 @@ d.errors
 
 ## Implementation Notes
 
-### Universal Mode Injection
-
-When page has no BB, inject a lightweight collector via `page.evaluate()`:
+### BB Mount Flow (Playwright)
 
 ```javascript
-window.__ROLL_DEBUG_COLLECTOR__ = {
-  console: [],
-  network: [],
-  errors: [],
-
-  init() {
-    // Hook console methods
-    ['error', 'warn', 'log', 'info'].forEach(method => {
-      const original = console[method];
-      console[method] = (...args) => {
-        this.console.push({method, args, timestamp: Date.now()});
-        original.apply(console, args);
-      };
-    });
-
-    // Hook fetch/XHR for network interception
-
-    // Listen for JS errors
-    window.addEventListener('error', e => {
-      this.errors.push({message: e.message, stack: e.error?.stack});
-    });
-  },
+// Pseudocode for AI agent execution
+async function diagnose(page, url, args) {
+  log(`🔍 Diagnosing ${url}`);
+
+  // Step 1: Mount
+  const bbState = await mountBB(page, args);
+  log(`📡 Mounting BB probe...`);
+  log(`   ├── Source: ${bbState.source}`); // native / stub / custom
+  log(`   └── Status: ${bbState.ready ? 'ready' : 'failed'}`);
+
+  if (bbState.ready && bbState.source !== 'native') {
+    log(`   └── BB button visible on page ✓`);
+  }
+
+  // Step 2: Collect
+  log(`📊 Collecting data via BB...`);
+  const data = await collectViaBB(page);
+
+  // Step 3: Analyze
+  log(`🔬 Analyzing...`);
+  const analysis = await analyze(data);
+
+  // Step 4: Unmount (unless native BB)
+  if (bbState.source !== 'native') {
+    log(`🧹 Unmounting BB probe...`);
+    const ok = await page.evaluate(() => window.__BB_UNMOUNT__?.());
+    log(`   └── ${ok ? 'done' : 'failed'}`);
+    log(`   └── Page state restored ✓`);
+  } else {
+    log(`🧹 Unmounting BB probe... skipped`);
+    log(`   └── Native BB left intact`);
+  }
+
+  return analysis;
+}
+
+async function mountBB(page, args) {
+  // Check for existing BB
+  const hasNative = await page.evaluate(() =>
+    !!document.querySelector('[data-testid="bb-toggle"]') || !!window.__BB_DATA__
+  );
+  if (hasNative) {
+    return { source: 'native', ready: true };
+  }
+
+  if (args.universal) {
+    return { source: 'universal', ready: false };
+  }
 
-  getData() {
-    return {
-      console: this.console,
-      network: this.network,
-      errors: this.errors,
-      dom: this.captureDOM(),
-      performance: this.capturePerformance()
-    };
+  // Inject BB
+  try {
+    if (args.bbSdkUrl) {
+      await page.addScriptTag({ url: args.bbSdkUrl });
+    } else {
+      const stubPath = path.join(__dirname, 'injectable-bb.js');
+      await page.addScriptTag({ path: stubPath });
+    }
+
+    // Poll for readiness
+    const ready = await poll(
+      () => page.evaluate(() => !!window.__BB_DATA__),
+      { timeout: 5000, interval: 200 }
+    );
+
+    return { source: args.bbSdkUrl ? 'custom' : 'stub', ready };
+  } catch (e) {
+    return { source: 'stub', ready: false, error: e.message };
   }
-};
+}
 ```
 
-The injected collector only exists in the Playwright browser context — no cleanup needed.
+### Built-in Stub (`injectable-bb.js`)
+
+The stub is injected via `page.addScriptTag({ path })` when no native BB exists.
+
+**Capabilities**:
+- Hooks `console.*` with internal error firewall (stub bugs never leak to page)
+- Hooks `fetch` and `XMLHttpRequest` transparently — original behavior fully preserved
+- Listens for `error` and `unhandledrejection`
+- Captures Performance Navigation Timing + FCP + LCP
+- Captures DOM state (title, HTML length, key element visibility)
+- Renders a visible **BB** button on the page
+
+**Cleanup**:
+- `window.__BB_UNMOUNT__()` restores all modified globals to their original references
+- Removes the BB button from DOM
+- Deletes `window.__BB_DATA__` and `window.__BB_UNMOUNT__`
+
+### Universal Mode (No BB)
+
+When `--universal` is used, collect via Playwright native events:
+
+```javascript
+page.on('console', msg => ...);
+page.on('requestfailed', req => ...);
+page.on('response', res => ...);
+page.on('pageerror', err => ...);
+```
+
+No page state is modified.
 
 ## Data Output Formats
 
-### Native BB Mode
+### Mounted BB Mode
 
 ```json
 {
-  "mode": "native-bb",
+  "mode": "mounted-bb",
+  "bbSource": "stub",
   "timestamp": "2024-01-15T10:30:00Z",
   "url": "https://example.com/page",
   "bbData": {},
-  "collected": {
-    "console": [],
-    "network": []
-  }
+  "mountedAt": 1705315800000,
+  "unmountedAt": 1705315805000
 }
 ```
 
@@ -389,7 +483,7 @@ The injected collector only exists in the Playwright browser context — no clea
       "title": "Page Title",
       "htmlLength": 2340,
       "keyElements": {
-        "#root": {"exists": true, "visible": true, "children": 5},
+        "#root": {"exists": true, "visible": true, "text": "..."},
         ".error": {"exists": false}
       }
     },
@@ -409,16 +503,26 @@ The injected collector only exists in the Playwright browser context — no clea
 
 ## Capability Comparison
 
-| Feature | Native BB Mode | Universal Mode |
-|---------|---------------|----------------|
-| Requires BB integration | Yes | No |
-| Console logs | Yes | Yes |
-| Network data | Yes | Yes |
-| DOM state | Detailed | Key elements |
-| App-specific metrics | Yes | No |
-| Screenshot | Yes | Yes |
-| Performance metrics | Yes | Yes |
-| Works on any site | No | Yes |
+| Feature | Mounted BB (stub) | Mounted BB (native) | Universal |
+|---------|-------------------|---------------------|-----------|
+| Page modification | Yes (mount/unmount) | No (already there) | No |
+| Visible BB button | Yes | If native has one | No |
+| Console logs | Yes | Yes | Yes |
+| Network data | Yes | Yes | Yes |
+| DOM state | Detailed | Detailed | Key elements |
+| App-specific metrics | No | Yes | No |
+| Screenshot | Yes | Yes | Yes |
+| Performance metrics | Yes | Yes | Yes |
+| Works offline | Yes | Yes | Yes |
+| Cleanup on exit | Yes (full restore) | N/A | N/A |
+
+## Safety & Cleanup Guarantees
+
+1. **Stub errors are firewalled** — every hook wraps its internal logic in try/catch. A bug in the stub cannot crash the page.
+2. **Original behavior preserved** — fetch/XHR wrappers return the exact same values/throw the exact same errors as the originals.
+3. **Full unmount** — `__BB_UNMOUNT__()` restores console, fetch, XHR, removes listeners, removes DOM element, and deletes globals.
+4. **Native BB untouched** — if a page already has BB, it is reused but never unmounted.
+5. **CSP fallback** — if script injection fails (CSP), automatically falls back to Universal mode.
 
 ## Integration with Build Skills
 

package/skills/roll-debug/injectable-bb.js

@@ -0,0 +1,263 @@
+// Roll Debug — Injectable BB Diagnostic Stub
+// Injected into page context by Playwright when native BB is absent.
+// Exposes window.__BB_DATA__ and [data-testid="bb-toggle"] for unified collection.
+// Fully unmountable via window.__BB_UNMOUNT__().
+
+(function () {
+  'use strict';
+
+  if (window.__BB_DATA__) return; // Already mounted
+
+  // ─── Backup originals ───
+  const _orig = {
+    console: {},
+    fetch: window.fetch,
+    XHR_open: XMLHttpRequest.prototype.open,
+    XHR_send: XMLHttpRequest.prototype.send,
+  };
+  ['error', 'warn', 'log', 'info'].forEach((m) => {
+    _orig.console[m] = console[m];
+  });
+
+  // ─── BB State ───
+  const BB = {
+    version: 'stub-1.0',
+    mountedAt: Date.now(),
+    console: { errors: [], warnings: [], logs: [] },
+    network: { failed: [], slow: [], all: [] },
+    errors: [],
+    dom: {},
+    performance: {},
+  };
+
+  // ─── Console hooks (with internal error firewall) ───
+  ['error', 'warn', 'log', 'info'].forEach((m) => {
+    const key = m === 'error' ? 'errors' : m === 'warn' ? 'warnings' : 'logs';
+    const orig = _orig.console[m];
+    console[m] = function bbHookedConsole(...args) {
+      try {
+        BB.console[key].push({
+          message: args
+            .map((a) => {
+              try {
+                return typeof a === 'object' ? JSON.stringify(a) : String(a);
+              } catch (e) {
+                return '[unstringifiable]';
+              }
+            })
+            .join(' '),
+          timestamp: Date.now(),
+        });
+      } catch (e) {
+        /* swallow stub internal error */
+      }
+      return orig.apply(this, args);
+    };
+  });
+
+  // ─── Fetch hook (transparent wrapper) ───
+  const origFetch = _orig.fetch;
+  window.fetch = function bbHookedFetch(...args) {
+    const start = Date.now();
+    const url =
+      typeof args[0] === 'string'
+        ? args[0]
+        : args[0]?.url || '[unknown]';
+    const method = args[1]?.method || 'GET';
+
+    return origFetch.apply(this, args).then(
+      (res) => {
+        try {
+          const duration = Date.now() - start;
+          const entry = { url, status: res.status, duration, method };
+          BB.network.all.push(entry);
+          if (!res.ok) BB.network.failed.push(entry);
+          if (duration > 3000) BB.network.slow.push(entry);
+        } catch (e) {
+          /* swallow */
+        }
+        return res;
+      },
+      (err) => {
+        try {
+          BB.network.failed.push({
+            url,
+            error: err.message,
+            duration: Date.now() - start,
+            method,
+          });
+        } catch (e) {
+          /* swallow */
+        }
+        throw err;
+      }
+    );
+  };
+  try {
+    window.fetch.toString = () => 'function fetch() { [native code] }';
+  } catch (e) {
+    /* ignore */
+  }
+
+  // ─── XHR hook ───
+  XMLHttpRequest.prototype.open = function bbHookedOpen(method, url, ...rest) {
+    this._bb = { method, url: String(url), start: null };
+    return _orig.XHR_open.call(this, method, url, ...rest);
+  };
+
+  XMLHttpRequest.prototype.send = function bbHookedSend(...args) {
+    if (this._bb) this._bb.start = Date.now();
+    const handler = () => {
+      if (!this._bb) return;
+      try {
+        const duration = Date.now() - this._bb.start;
+        const entry = {
+          url: this._bb.url,
+          status: this.status,
+          duration,
+          method: this._bb.method,
+        };
+        BB.network.all.push(entry);
+        if (this.status >= 400 || this.status === 0)
+          BB.network.failed.push(entry);
+        if (duration > 3000) BB.network.slow.push(entry);
+      } catch (e) {
+        /* swallow */
+      }
+    };
+    this.addEventListener('loadend', handler, { once: true });
+    return _orig.XHR_send.apply(this, args);
+  };
+
+  // ─── JS Error listeners ───
+  const onError = (e) => {
+    try {
+      BB.errors.push({
+        message: e.message,
+        stack: e.error?.stack,
+        timestamp: Date.now(),
+      });
+    } catch (e) {
+      /* swallow */
+    }
+  };
+  const onRejection = (e) => {
+    try {
+      BB.errors.push({
+        message: e.reason?.message || String(e.reason),
+        stack: e.reason?.stack,
+        timestamp: Date.now(),
+      });
+    } catch (e) {
+      /* swallow */
+    }
+  };
+  window.addEventListener('error', onError);
+  window.addEventListener('unhandledrejection', onRejection);
+
+  // ─── Performance ───
+  const capturePerf = () => {
+    try {
+      const nav = performance.getEntriesByType('navigation')[0];
+      BB.performance = {
+        domContentLoaded: nav?.domContentLoadedEventEnd,
+        loadComplete: nav?.loadEventEnd,
+        firstContentfulPaint:
+          performance.getEntriesByName('first-contentful-paint')[0]?.startTime,
+        largestContentfulPaint: performance
+          .getEntriesByType('largest-contentful-paint')
+          .pop()?.startTime,
+      };
+    } catch (e) {
+      /* swallow */
+    }
+  };
+  if (document.readyState === 'complete') {
+    capturePerf();
+  } else {
+    window.addEventListener('load', capturePerf, { once: true });
+  }
+
+  // ─── DOM Capture ───
+  function captureDOM() {
+    try {
+      const info = (sel) => {
+        const el = document.querySelector(sel);
+        return el
+          ? {
+              exists: true,
+              visible: el.offsetParent !== null,
+              text: el.textContent?.slice(0, 200),
+            }
+          : { exists: false };
+      };
+      return {
+        title: document.title,
+        url: location.href,
+        htmlLength: document.documentElement.innerHTML.length,
+        keyElements: {
+          '#root': info('#root'),
+          '#app': info('#app'),
+          '[data-testid="error"]': info('[data-testid="error"]'),
+          '.error': info('.error'),
+          '.loading': info('.loading'),
+        },
+      };
+    } catch (e) {
+      return { error: 'DOM capture failed', url: location.href };
+    }
+  }
+
+  // ─── Public API ───
+  BB.getData = () => ({ ...BB, dom: captureDOM(), collectedAt: Date.now() });
+  window.__BB_DATA__ = BB;
+
+  // ─── Visible BB toggle button ───
+  let btn;
+  if (document.body) {
+    btn = document.createElement('button');
+    btn.dataset.testid = 'bb-toggle';
+    btn.textContent = 'BB';
+    btn.title = 'Black Box Diagnostic Probe — click to download report';
+    btn.style.cssText =
+      'position:fixed;bottom:12px;right:12px;z-index:99999;' +
+      'width:36px;height:36px;border-radius:50%;border:none;' +
+      'background:#ff4444;color:#fff;font-size:11px;font-weight:bold;' +
+      'font-family:sans-serif;cursor:pointer;box-shadow:0 2px 8px rgba(0,0,0,0.3);' +
+      'display:flex;align-items:center;justify-content:center;' +
+      'opacity:0.85;transition:opacity 0.2s;';
+    btn.onmouseenter = () => (btn.style.opacity = '1');
+    btn.onmouseleave = () => (btn.style.opacity = '0.85');
+    btn.onclick = () => {
+      const data = BB.getData();
+      const blob = new Blob([JSON.stringify(data, null, 2)], {
+        type: 'application/json',
+      });
+      const a = document.createElement('a');
+      a.href = URL.createObjectURL(blob);
+      a.download = `bb-diagnostic-${Date.now()}.json`;
+      a.click();
+    };
+    document.body.appendChild(btn);
+  }
+
+  // ─── Unmount (restore page to original state) ───
+  window.__BB_UNMOUNT__ = function () {
+    try {
+      ['error', 'warn', 'log', 'info'].forEach(
+        (m) => (console[m] = _orig.console[m])
+      );
+      window.fetch = _orig.fetch;
+      XMLHttpRequest.prototype.open = _orig.XHR_open;
+      XMLHttpRequest.prototype.send = _orig.XHR_send;
+      window.removeEventListener('error', onError);
+      window.removeEventListener('unhandledrejection', onRejection);
+      if (btn) btn.remove();
+      delete window.__BB_DATA__;
+      delete window.__BB_UNMOUNT__;
+      return true;
+    } catch (e) {
+      return false;
+    }
+  };
+})();

package/skills/roll-doctor/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: roll-doctor
+license: MIT
+description: "Diagnose Roll toolchain health. Checks skill files, YAML frontmatter, symlinks, conventions sync, template integrity, and config validity."
+---
+
+# Roll Doctor
+
+诊断 Roll 工具链健康状态。快速定位 skill 不工作、convention 不同步、symlink 断裂等问题。
+
+## When to Use
+
+- "roll 怎么不工作了"
+- "skill 找不到了"
+- "convention 没有同步"
+- "$roll-debug 不响应"
+- 任何 Roll 相关功能异常
+
+## Checks
+
+### 1. Roll Installation
+
+```bash
+# Verify ROLL_HOME structure
+ls -la ~/.roll/
+ls -la ~/.roll/skills/
+ls -la ~/.roll/conventions/
+```
+
+Expected:
+- `~/.roll/` exists
+- `~/.roll/skills/` has roll-* directories
+- `~/.roll/conventions/global/` has AGENTS.md, CLAUDE.md, etc.
+- `~/.roll/conventions/templates/` has backend-service, cli, frontend-only, fullstack
+
+### 2. Skill Health
+
+```bash
+# List all skills and check YAML frontmatter
+for f in ~/.roll/skills/*/SKILL.md; do
+  echo "=== $(basename $(dirname $f)) ==="
+  head -5 "$f"
+done
+```
+
+Check:
+- Each skill directory has `SKILL.md`
+- YAML frontmatter has `name:` and `description:`
+- No duplicate `name` values across skills
+- File is readable markdown
+
+### 3. Symlinks
+
+```bash
+# Claude Code
+ls -la ~/.claude/skills/roll-*
+
+# Gemini (if exists)
+ls -la ~/.gemini/skills/roll-* 2>/dev/null
+
+# Trae (if exists)
+ls -la ~/.trae/skills/roll-* 2>/dev/null
+```
+
+Check:
+- Each symlink exists
+- Each symlink points to valid target in `~/.roll/skills/`
+- No broken symlinks (red in ls output)
+
+### 4. Conventions Sync
+
+```bash
+# Check roll.md sync
+diff ~/.roll/conventions/global/CLAUDE.md ~/.claude/roll.md
+
+# Check CLAUDE.md includes @roll.md
+grep "@roll.md" ~/.claude/CLAUDE.md
+```
+
+Check:
+- `~/.claude/roll.md` exists and matches `~/.roll/conventions/global/CLAUDE.md`
+- `~/.claude/CLAUDE.md` contains `@roll.md` reference
+- `~/.claude/CLAUDE.md` is not missing or stale
+
+### 5. Template Integrity
+
+```bash
+# Global conventions
+ls ~/.roll/conventions/global/
+
+# Project type templates
+for t in backend-service cli frontend-only fullstack; do
+  ls ~/.roll/conventions/templates/$t/
+done
+
+# New project template
+ls ~/.roll/template/
+```
+
+Check:
+- All expected files present in each directory
+- No missing AGENTS.md, CLAUDE.md, or GEMINI.md
+
+### 6. Config
+
+```bash
+cat ~/.roll/config.yaml
+```
+
+Check:
+- File exists and is valid YAML
+- Has required `ai_tool_name` or `ai_claude` entries
+
+## Report Format
+
+```
+🔬 Roll Doctor Report
+
+[✓/✗] Roll installation
+[✓/✗] Skills (N skills checked)
+[✓/✗] Symlinks (N tools checked)
+[✓/✗] Conventions sync
+[✓/✗] Templates integrity
+[✓/✗] Config
+
+---
+Issues found: N
+
+1. [severity] description → fix command
+2. [severity] description → fix command
+
+Recommendation: ...
+```
+
+## Severity Levels
+
+| Level | Meaning | Example |
+|-------|---------|---------|
+| 🔴 Critical | Skill completely broken | Broken symlink, missing SKILL.md |
+| 🟡 Warning | Partial functionality | Stale convention, outdated roll.md |
+| 🟢 Info | Recommendations | Missing optional tool symlink |
+
+## Auto-Fix
+
+If user confirms, automatically fix safe issues:
+
+- **Broken/missing symlinks** → `roll setup` (recreates all)
+- **Stale conventions** → `roll sync conventions`
+- **Missing template files** → warn user to re-install
+
+Never auto-fix without user confirmation for:
+- Overwriting `~/.claude/CLAUDE.md` (may have user customizations)
+- Deleting files
+
+## Quick Fix Commands
+
+```bash
+# Recreate all symlinks and sync conventions
+roll setup
+
+# Sync only conventions
+roll sync conventions
+
+# Reinstall (nuclear option)
+curl -fsSL https://raw.githubusercontent.com/seanyao/roll/main/install.sh | bash
+```

package/skills/roll-notes/SKILL.md

@@ -30,9 +30,13 @@ $roll-notes 今天的 code review 给了很好的反馈
 
 1. **Determine file path**: `notes/YYYY-MM-DD.md` relative to project root
 2. **Get current time**: Use `Asia/Shanghai` timezone (`TZ=Asia/Shanghai date`)
-3. **Append**: Add new entry at end of file — never overwrite existing content
-4. **Create if missing**: If file doesn't exist, create with a `# YYYY-MM-DD — <one-line summary>` header
-5. **Free format**: Paragraph, list, code block — whatever fits the moment
+3. **Read existing entries for style**: Before writing, read the last 2–3 entries
+   in the same file. Analyze their style: heading format, voice/tone,
+   paragraph structure, emoji usage, code block conventions, sign-off pattern.
+   New entries must continue this style — do not invent new structural patterns.
+4. **Append**: Add new entry at end of file — never overwrite existing content
+5. **Create if missing**: If file doesn't exist, create with a `# YYYY-MM-DD — <one-line summary>` header
+6. **Free format**: Paragraph, list, code block — whatever fits the moment
 
 ## File format
 
@@ -54,8 +58,34 @@ $roll-notes 今天的 code review 给了很好的反馈
 ...
 ```
 
+## 写作风格（强制）
+
+**禁止干巴巴的 checklist。禁止只有结论没有过程。必须有人的声音。**
+
+### 叙事驱动
+以时间线和事件推进为主线，像讲故事一样记录。不是 `补了功能，pytest 绿`，而是 `"电池剩余电量在哪里看？"我一愣，US-PLAT-003 的 AC 明明写了...`
+
+### 技术细节嵌入叙事
+代码、数据、命令行是故事的一部分，自然插入，不是附录。
+
+### 对话与互动
+记录用户的反馈、提问、情绪。日记是对话记录，不是独白。
+
+### 诚实记录错误
+失败、困惑、教训比成功更值得记录。
+
+### 标题有画面感
+不是功能清单。如 `每秒 20 行的噪音`、`22 个文件挤在一个抽屉里`。
+
+### 结尾有收束
+最后一段回到人的状态。如 `"值了"。"睡了"。push。`
+
 ## Rules
 
+- **Style continuity**: Match the EXACT style, tone, and formatting of previous
+  entries in the same file. Do not invent new structural patterns or section
+  headers. If the file already has entries, analyze them first and confirm your
+  understanding of their style before writing.
 - **No planning**: Never write "明日待办" or "下一步"
 - **No summaries**: Never write "今日收获" or "经验教训"
 - **Pure record**: What happened, as-is — honest, immediate, rough is fine

package/skills/roll-release/SKILL.md

@@ -10,7 +10,7 @@ One-command publish flow for roll maintainers.
 
 ## When Not to Use
 
-- Non-maintainer users (this skill publishes `@seanyao/roll` to npm under seanyao)
+- Non-maintainer users (this skill publishes the package defined in `package.json` — confirm scope before running)
 - Internal project releases — only for the `roll` CLI package itself
 - Hotfixing code without a version bump (use `$roll-fix`)
 - Generating user-facing release notes (use `$roll-.changelog`)
@@ -92,8 +92,8 @@ After publish, show:
 ```
 ✅ Released v{version}
 🏷  Tag: v{version} pushed to origin
-📦 npm published: @seanyao/roll@{version}
-🔗 https://www.npmjs.com/package/@seanyao/roll
+📦 npm published: {package_name}@{version}   # package name read from package.json
+🔗 https://www.npmjs.com/package/{package_name}
 ```
 
 ## Abort Conditions