@seanyao/roll 3.609.2 → 3.610.2

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

@@ -0,0 +1,363 @@
+# Full Contract Reference
+
+This file preserves the detailed contract extracted from SKILL.md. Read it when the hub points here for exact workflow steps, templates, rubrics, or recovery branches.
+
+---
+
+# Sentinel
+
+**Smart Patrol Inspector** - Scheduled, randomized, cost-controlled patrol and acceptance checks for production systems.
+
+## When Not to Use
+
+- One-off debugging of a reported bug (use `$roll-debug`)
+- Full-coverage regression testing (sentinel samples, does not cover)
+- Dev/staging environment checks (use CI tests instead)
+- Pre-commit self-review of diffs (use `$roll-.review`)
+
+## Core Principle
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   Smart Patrol Logic                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Not full-coverage checks! Think of it like a security      │
+│  guard on patrol:                                           │
+│                                                             │
+│  🕐 Scheduled Triggers - Auto-patrol on schedule            │
+│       └── "Patrol once every 6 hours"                       │
+│                                                             │
+│  🎲 Random Sampling - Different samples each time           │
+│       └── "Check Stories 1-10 this time, 50-60 next time"   │
+│                                                             │
+│  💰 Cost Control - AI checks are expensive, use sparingly   │
+│       └── "Only check 10 each time, not all 100"            │
+│                                                             │
+│  🎯 BACKLOG-Based - Validate against requirements           │
+│       └── "US-001 says login works, so verify login"        │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Patrol Strategy
+
+### Sampling Logic
+
+```javascript
+// Sampling logic for each patrol
+function selectSamples(backlog, strategy = 'smart') {
+  const completedStories = backlog.filter(s => s.status === '✅');
+  
+  switch(strategy) {
+    case 'random':
+      // Fully random: randomly select N from all completed Stories
+      return shuffle(completedStories).slice(0, 10);
+    
+    case 'weighted':
+      // Weighted random: prioritize recently modified and frequently used
+      return completedStories
+        .sort((a, b) => b.lastModified - a.lastModified)
+        .slice(0, 5)  // 5 most recent
+        .concat(shuffle(completedStories).slice(0, 5)); // + 5 random
+    
+    case 'coverage':
+      // Coverage sampling: ensure different modules are all covered
+      const byModule = groupBy(completedStories, 'module');
+      return Object.values(byModule).map(
+        stories => randomPick(stories)
+      );
+  }
+}
+```
+
+### Cost Control
+
+| Strategy | Sample Size | Frequency | Use Case |
+|----------|-------------|-----------|----------|
+| **Light** | 5 Stories | Once daily | Stable period |
+| **Normal** | 10 Stories | Every 6 hours | General monitoring |
+| **Intensive** | 20 Stories | Every hour | Post-release period |
+| **Full** | All | Once weekly | Weekly patrol |
+
+```yaml
+# sentinel.config.yml
+cost_control:
+  daily_budget: 100  # AI call budget
+  
+  light_patrol:
+    samples: 5
+    schedule: "0 9 * * *"  # Daily at 9am
+    
+  normal_patrol:
+    samples: 10
+    schedule: "0 */6 * * *"  # Every 6 hours
+    
+  # Intensive patrol after deployment
+  post_deploy:
+    trigger: "after_deploy"
+    samples: 20
+    duration: "2h"  # Lasts 2 hours
+```
+
+### Uncertainty Handling
+
+```javascript
+// Systems have uncertainty; a single check may be inaccurate.
+// Use multiple random checks to increase confidence.
+
+class UncertaintyHandler {
+  // Track check result history
+  history = new Map(); // storyId -> [check1, check2, ...]
+  
+  // Determine if an issue is real
+  isRealIssue(storyId, currentResult) {
+    const pastResults = this.history.get(storyId) || [];
+    pastResults.push(currentResult);
+    
+    // Only consider it a real issue if it fails 3 times consecutively
+    const recent3 = pastResults.slice(-3);
+    if (recent3.every(r => r.status === 'FAIL')) {
+      return true; // Real issue
+    }
+    
+    // If it fails occasionally, it may be intermittent; keep observing
+    if (recent3.filter(r => r.status === 'FAIL').length === 1) {
+      return false; // Likely intermittent, don't alert yet
+    }
+    
+    return false;
+  }
+}
+```
+
+## When to Patrol
+
+### Scheduled Patrols
+
+```bash
+# Daily patrol - randomly check a few each day
+$roll-sentinel patrol --mode=normal
+
+# Late-night patrol - full check during off-peak hours
+$roll-sentinel patrol --mode=full --schedule="0 3 * * *"
+
+# Weekend walkthrough - check the week's accumulation on Sunday
+$roll-sentinel patrol --mode=weekly --schedule="0 10 * * 0"
+```
+
+### Event-Triggered
+
+```bash
+# Intensive patrol for 2 hours after deployment
+$roll-sentinel patrol --mode=intensive --duration=2h --after-deploy
+
+# Emergency check after an alert
+$roll-sentinel patrol --mode=focus --target=US-XXX
+```
+
+## Patrol Report
+
+```markdown
+## 🛡️ Sentinel Patrol Report #247
+**Time**: 2024-01-15 14:00 UTC  
+**Patrol ID**: patrol-20240115-1400  
+**Mode**: Normal (Random Sampling)
+
+### 📊 Sampling Info
+| Metric | Value |
+|--------|-------|
+| Total Stories | 150 |
+| Sample Size | 10 |
+| Sampling Rate | 6.7% |
+| Cost Estimate | $0.07 |
+
+### 🎲 Random Sample
+| # | Story | Module | Last Checked | Result |
+|---|-------|--------|--------------|--------|
+| 1 | US-LOGIN-001 | Auth | 6h ago | ✅ |
+| 2 | US-STORY-042 | Content | 12h ago | ✅ |
+| 3 | US-AUDIO-015 | Player | 2h ago | 🟡* |
+| 4 | US-SEARCH-003 | Search | 18h ago | ✅ |
+| 5 | ... | ... | ... | ... |
+
+\* US-AUDIO-015: Occasional playback stuttering (2nd occurrence, under observation)
+
+### 🔴 Issues Found
+None (no confirmed issues found in this sample)
+
+### 📈 Patrol Statistics (7 days)
+| Metric | Value |
+|--------|-------|
+| Total Patrols | 28 |
+| Stories Checked | 280 |
+| Issues Found | 3 |
+| False Positives | 1 |
+| Coverage | 85% of all stories |
+
+### 💰 Cost Report
+| Item | Usage |
+|------|-------|
+| AI Checks | 280 calls |
+| Playwright Runs | 28 sessions |
+| Total Cost | $2 |
+| Budget Used | 15% of monthly |
+```
+
+## Smart Detection Logic
+
+### Pattern 1: Intermittent vs Real Issue
+
+```javascript
+// Don't alert on the first failure; look at the trend
+const checks = [
+  { time: 'T-6h', status: 'PASS' },
+  { time: 'T-12h', status: 'FAIL' },  // Intermittent?
+  { time: 'T-18h', status: 'PASS' },
+  { time: 'Now', status: 'FAIL' },    // Failed again!
+];
+
+// 2 consecutive failures → Create Issue
+if (lastN(checks, 2).all(c => c.status === 'FAIL')) {
+  createBacklogItem('FIX-XXX');
+}
+// Occasional failure → Log for observation
+else if (checks.filter(c => c.status === 'FAIL').length <= 1) {
+  logForObservation('Might be flaky, continue monitoring');
+}
+```
+
+### Pattern 2: Hotspot Detection
+
+```javascript
+// Some Stories frequently show issues when sampled.
+// Automatically increase their check frequency.
+
+const hotSpots = analyzeHistory();
+// hotSpots = [
+//   { story: 'US-AUDIO-015', failRate: 0.3 }, // 30% failure rate
+//   { story: 'US-SEARCH-003', failRate: 0.1 },
+// ]
+
+// Increase weight for hotspots
+if (hotSpots.some(h => h.story === selectedStory)) {
+  // If it's a hotspot, even if not randomly selected, add extra check probability
+  if (Math.random() < 0.3) {
+    extraCheck(story);
+  }
+}
+```
+
+## Cost Optimization
+
+### Tiered Checking
+
+```
+Level 1: Lightweight Check (cheap)
+  └── HTTP ping / API health check
+  └── Cost: $0.001 per check
+
+Level 2: Functional Check (moderate)
+  └── Playwright critical path
+  └── Cost: $0.01 per check
+
+Level 3: AI Deep Check (expensive)
+  └── AI-powered content quality analysis
+  └── Cost: $0.07 per check
+
+Strategy:
+- Each patrol: 90% Level 1 + 10% Level 2
+- Once weekly: Level 3 deep inspection
+```
+
+### Smart Batching
+
+```javascript
+// Batch checks to reduce cost.
+// Instead of 10 separate checks, open one browser for all 10.
+
+async function batchCheck(stories) {
+  const browser = await chromium.launch();
+  const context = await browser.newContext();
+  
+  // Reuse browser session to check multiple Stories
+  for (const story of stories) {
+    const page = await context.newPage();
+    await checkStory(page, story);
+    await page.close();
+  }
+  
+  await browser.close();
+  // Cost: 1 session for 10 checks
+}
+```
+
+## Workflow: Find Issue → Backlog
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│              Issue Discovery Workflow via Patrol             │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. Sentinel Patrol (scheduled random sampling)             │
+│     └── Sample: US-AUDIO-015                                │
+│                                                             │
+│  2. Check Result                                            │
+│     └── Status: FAIL (playback stuttering)                  │
+│                                                             │
+│  3. Uncertainty Check                                       │
+│     └── Check history: this is the 2nd failure              │
+│     └── 1st was 6h ago (possibly intermittent)              │
+│     └── Decision: continue observing, don't create Issue    │
+│                                                             │
+│  4. Next Patrol                                             │
+│     └── US-AUDIO-015 sampled again (hotspot weighting)      │
+│     └── Status: FAIL (failed again!)                        │
+│     └── Check history: 2 consecutive failures               │
+│     └── Decision: create FIX-AUDIO-015                      │
+│                                                             │
+│  5. Create Backlog Item                                     │
+│     └── Add FIX-AUDIO-015 to .roll/backlog.md                     │
+│     └── Status: 📋 Todo                                     │
+│     └── Awaiting human fix                                  │
+│                                                             │
+│  6. Human Fix                                               │
+│     └── User: "Fix FIX-AUDIO-015"                           │
+│     └── $roll-fix FIX-AUDIO-015                            │
+│                                                             │
+│  7. Verification                                            │
+│     └── Next patrol will prioritize verifying this FIX      │
+│     └── Status: ✅ Fixed                                     │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Integration with Other Skills
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                Complete Monitoring System                    │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  $roll-sentinel patrol        Scheduled random patrol (main) │
+│       ↓                                                     │
+│  Issue found? ──┬── Yes ──→ Create BACKLOG item             │
+│                 │           Await $roll-fix             │
+│                 │                                           │
+│                 └── No  ──→ Continue patrolling              │
+│                                                             │
+│  $roll-debug               On-demand deep diagnosis (aux) │
+│  (When Sentinel finds an issue, manually trigger deep dive) │
+│                                                             │
+│  $roll-build            Post-fix regression verify     │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Best Practices
+
+1. **Don't do full-coverage checks** - Expensive and unnecessary
+2. **Random + Hotspots** - Balance coverage and cost
+3. **Multi-check confirmation** - Avoid false positives from intermittent failures
+4. **Budget control** - Set daily/monthly AI call limits
+5. **Progressive intensity** - Light during stable periods, Intensive after releases

package/skills/roll-spar/SKILL.md

@@ -2,288 +2,46 @@
 name: roll-spar
 license: MIT
 allowed-tools: "Read, Edit, Write, Bash, Agent, Skill"
-description: Adversarial TDD mode with Attacker/Defender agents. Attacker writes tests to break the system, Defender writes minimal code to pass. Use for high-risk logic like auth, payments, data integrity, or complex state machines.
+description: "Load when high-risk logic needs adversarial TDD with attacker tests and defender implementation, such as auth, payments, data integrity, or state machines."
 ---
+# Roll Spar
 
-# Spar
+This hub keeps the routing boundary, hard gates, and execution skeleton in the initial context. Load the heavier runbook only when the task actually needs the detailed contract.
 
-Adversarial TDD: two agents collaborate in attack-and-defend mode to build a more robust system.
+## Load
 
-## When to Use
+Load when high-risk logic needs adversarial TDD with attacker tests and defender implementation, such as auth, payments, data integrity, or state machines.
 
-**Manual trigger:**
-- User explicitly requests `$roll-spar`
-- Involves core business logic requiring higher quality assurance
+## When Not to Use
 
-**Auto trigger (agent judgment):** Recommend enabling when any of these conditions are met
-- Involves authentication / authorization / security
-- Involves money / payments / billing
-- Involves data integrity (writes are irreversible)
-- Complex state machines / concurrency logic
-- Module has had previous bugs (BACKLOG has related FIX records)
+- Routine QA planning; load roll-.qa.
+- Ordinary peer review; load roll-peer.
 
-**Do not use for:**
-- UI styling adjustments, copy changes
-- Simple CRUD
-- Configuration changes
-- Small tasks not worth the overhead of two-agent collaboration
+## Read On Demand
 
-## Roles
+- Read [the full contract](references/full-contract.md) before executing the workflow end to end, recovering from failures, or checking exact output templates.
+- Keep this hub in context for trigger boundaries and hard gates.
 
-### Attacker (Red Agent)
+## Workflow Skeleton
 
-**Goal: Find weaknesses in the code and write tests that break the system.**
+1. Define the high-risk invariant.
+2. Attacker writes breaking tests first.
+3. Defender implements the minimal passing code.
+4. Iterate until the invariant is defended.
+5. Record adversarial evidence.
 
-- Think about boundary conditions, invalid inputs, concurrency scenarios, state inconsistencies
-- Write the trickiest test cases possible
-- Don't care about implementation difficulty — only care about "can the system handle this scenario"
-- Write at least 1 RED test per round, can write multiple
+## Hard Gates
 
-### Defender (Green Agent)
+- Keep attacker/defender roles separate.
+- Use only when added cost matches risk.
 
-**Goal: Make all tests pass with the simplest, most robust code possible.**
+## Gotchas
 
-- Cannot modify tests written by the Attacker (unless the test itself has a bug)
-- Aim for minimal implementation, avoid over-engineering
-- Make all tests GREEN each round, then commit
-- May refactor, but must stay GREEN
+- Use spar only for high-risk logic where adversarial tests are worth the added cost.
+- Attacker and defender roles must stay separate; do not let implementation assumptions weaken the breaking tests.
 
-## Workflow
+## Maintenance
 
-```
-User: "$roll-spar implement transfer logic" or agent auto-triggers
-    │
-    ▼
-┌─────────────────────────────────────┐
-│ 0. Setup                            │
-│    - Define feature scope and AC    │
-│    - Create test file skeleton      │
-│    - Context brief for Attacker     │
-│      and Defender                    │
-└─────────────┬───────────────────────┘
-              │
-              ▼
-┌─────────────────────────────────────┐
-│ Spar Loop (repeat until converged)  │
-│                                     │
-│  ┌───────────────────────────────┐  │
-│  │ 🔴 Attacker Turn             │  │
-│  │    - Analyze current code/API │  │
-│  │    - Write 1+ RED tests      │  │
-│  │    - State attack intent:     │  │
-│  │      "Test balance consistency│  │
-│  │       during concurrent       │  │
-│  │       transfers"              │  │
-│  └──────────────┬────────────────┘  │
-│                 │                    │
-│                 ▼                    │
-│  ┌───────────────────────────────┐  │
-│  │ 🟢 Defender Turn             │  │
-│  │    - Read Attacker's tests   │  │
-│  │    - Write minimal code to   │  │
-│  │      make tests pass         │  │
-│  │    - Run all tests → GREEN   │  │
-│  │    - git commit              │  │
-│  └──────────────┬────────────────┘  │
-│                 │                    │
-│                 ▼                    │
-│  ┌───────────────────────────────┐  │
-│  │ 🔴 Attacker Turn (again)     │  │
-│  │    - Review Defender's impl  │  │
-│  │    - Find new weaknesses,    │  │
-│  │      write new RED tests     │  │
-│  │    - Or: "No new weaknesses  │  │
-│  │      found"                  │  │
-│  └──────────────┬────────────────┘  │
-│                 │                    │
-│        ┌────────┴────────┐          │
-│        │                 │          │
-│   Has new tests    No new tests     │
-│   → Continue loop  → Exit Spar      │
-│                                     │
-└─────────────────────────────────────┘
-              │
-              ▼
-┌─────────────────────────────────────┐
-│ Wrap-up                             │
-│    - Attacker summarizes attack     │
-│      coverage                       │
-│    - Defender summarizes defense    │
-│      strategy                       │
-│    - Merged report                  │
-│    - Continue normal roll-build     │
-│      flow                           │
-│      (push → CI → deploy → verify)  │
-└─────────────────────────────────────┘
-```
-
-## Spar Convergence Conditions
-
-Attacker declares completion when any of these are met:
-- Cannot write a new RED test for 2 consecutive rounds
-- Already covered: happy path + boundary values + invalid inputs + concurrency/race conditions + state consistency
-- Reached the agreed maximum number of rounds (default: 5 rounds)
-
-## Agent Context Brief
-
-### Attacker Brief Template
-
-```markdown
-## Role: Attacker (Red Agent)
-
-Your goal is to find weaknesses in this code.
-
-### Feature Description
-{Feature AC and interface definition}
-
-### Current Implementation
-{Defender's latest code, or "not yet implemented"}
-
-### Existing Tests
-{Currently existing test cases}
-
-### Your Task
-Write 1+ new test cases that make the current implementation fail (RED).
-Directions to explore:
-- Boundary values (0, -1, MAX_INT, empty string, null)
-- Exception flows (network disconnect, timeout, duplicate requests)
-- Concurrency (two requests arriving simultaneously)
-- State consistency (is system state clean after mid-process failure)
-
-### Output Format
-For each test, state the attack intent:
-  "Attack: {scenario description} — expected system behavior: {expected behavior}"
-```
-
-### Defender Brief Template
-
-```markdown
-## Role: Defender (Green Agent)
-
-Your goal is to make all tests pass with the simplest implementation.
-
-### Feature Description
-{Feature AC and interface definition}
-
-### Current Code
-{Your previously written code, or empty}
-
-### New RED Tests
-{Tests written by the Attacker this round}
-
-### Your Task
-Modify/add code to make all tests (including previous ones) pass.
-Rules:
-- Cannot modify tests written by the Attacker
-- Aim for minimal changes
-- Keep the code clear
-- Commit after all tests are GREEN
-```
-
-## Status Report
-
-Report to the user after each round:
-
-```
-⚔️ Spar Round {N}
-
-  🔴 Attacker:
-     Attack: {scenario 1} — {result}
-     Attack: {scenario 2} — {result}
-
-  🟢 Defender:
-     Defense strategy: {brief description of how it was defended}
-     Test status: {passed}/{total} ✅
-
-  📊 Cumulative: {total tests} tests, {total rounds} rounds
-  🔄 Next round: Attacker continues looking for weaknesses...
-```
-
-## Hard Rules
-
-1. **Attacker does not write implementation code** — only writes tests and attack analysis
-2. **Defender does not modify tests** — unless the test itself has a bug (must explain the reason)
-3. **Must commit each round** — Defender commits immediately after making tests GREEN, keeping the repo clean
-4. **Attack intent must be explained** — cannot just write tests without explaining "why this scenario matters"
-5. **Maximum round limit** — default 5 rounds, prevents infinite loops
-
-## Integration with roll-build
-
-Spar replaces steps 4-5 in roll-build (Test Design + TCR Implementation):
-
-```
-roll-build normal flow:
-  1. Clarify Story
-  2. Split Actions
-  3. Define verification
-  ──────────────────────
-  4. Test Design Review    ← Spar replaces this step
-  5. TCR Implementation    ← and this step
-  ──────────────────────
-  6. Local CI check        ← Back to normal flow
-  7. Quality Review
-  ...
-```
-
-**Auto-switching from roll-build to Spar:**
-
-When the agent assesses an Action as high-risk at step 3:
-```
-⚔️ High-risk Action detected: {description}
-   Risk factors: {auth/payment/data integrity/...}
-   Recommend enabling Spar mode — confirm? [Y/n]
-```
-
-After user confirms, enter Spar. Once complete, return to roll-build step 6 to continue.
-
-## Example
-
-```
-User: "$roll-spar implement user balance transfer"
-
-⚔️ Spar: User Balance Transfer
-
-── Round 1 ──
-
-🔴 Attacker:
-   Attack 1: Transfer amount is 0 — should reject
-   Attack 2: Transfer amount is negative — should reject
-   Attack 3: Transfer amount exceeds balance — should reject and keep balance unchanged
-
-🟢 Defender:
-   Implementation: transfer(from, to, amount) basic validation
-   Tests: 3/3 ✅
-   commit: "tcr: transfer basic validation"
-
-── Round 2 ──
-
-🔴 Attacker:
-   Attack 4: Transfer to self — should reject
-   Attack 5: Two concurrent transfers whose total exceeds balance — only one should succeed
-
-🟢 Defender:
-   Implementation: add self-transfer check + optimistic lock
-   Tests: 5/5 ✅
-   commit: "tcr: transfer self-check and concurrency lock"
-
-── Round 3 ──
-
-🔴 Attacker:
-   Attack 6: Database error mid-transfer — both balances should remain unchanged (atomicity)
-   Attack 7: Recipient account does not exist — should reject and keep sender's balance
-
-🟢 Defender:
-   Implementation: database transaction wrapper + recipient existence check
-   Tests: 7/7 ✅
-   commit: "tcr: transfer atomicity and recipient validation"
-
-── Round 4 ──
-
-🔴 Attacker:
-   No new weaknesses found. Covered: input validation, self-transfer, concurrency, atomicity, related accounts.
-
-⚔️ Spar Complete!
-   📊 4 rounds, 7 tests, 3 commits
-   🔴 Attack coverage: input boundaries + business rules + concurrency + atomicity
-   🟢 Defense strategy: upfront validation + optimistic lock + transactions
-```
+- Description changes require updates in `route-cases/skills.json`.
+- New observed failures should add a gotcha and the matching positive or negative route case.
+- Heavy examples, templates, recovery paths, and deterministic snippets belong in `references/`, `assets/`, or `scripts/`, not in this hub.