@seanyao/roll 3.620.1 → 3.624.1

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

@@ -1,288 +0,0 @@
-# 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.
-
----
-
-# Spar
-
-Adversarial TDD: two agents collaborate in attack-and-defend mode to build a more robust system.
-
-## When to Use
-
-**Manual trigger:**
-- User explicitly requests `$roll-spar`
-- Involves core business logic requiring higher quality assurance
-
-**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)
-
-**Do not use for:**
-- UI styling adjustments, copy changes
-- Simple CRUD
-- Configuration changes
-- Small tasks not worth the overhead of two-agent collaboration
-
-## Roles
-
-### Attacker (Red Agent)
-
-**Goal: Find weaknesses in the code and write tests that break the system.**
-
-- 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
-
-### Defender (Green Agent)
-
-**Goal: Make all tests pass with the simplest, most robust code possible.**
-
-- 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
-
-## Workflow
-
-```
-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
-```

package/skills/route-cases/skills.json

@@ -1,216 +0,0 @@
-{
-  "version": 1,
-  "skills": {
-    "roll-.changelog": {
-      "positive": [
-        "build finished, generate CHANGELOG.md from Done backlog stories",
-        "after deploy, sync user-facing changelog with acceptance evidence"
-      ],
-      "negative": [
-        "design new stories for a feature backlog",
-        "fix a failing unit test through TCR"
-      ]
-    },
-    "roll-.clarify": {
-      "positive": [
-        "the fly-mode build request is vague and needs scope questions",
-        "the user asked for a feature but boundaries are underspecified"
-      ],
-      "negative": [
-        "the user supplied a concrete US-XXX story id",
-        "the user only wants intent restated, not scope questions"
-      ]
-    },
-    "roll-.dream": {
-      "positive": [
-        "run the nightly architecture health scan",
-        "look for dead code, doc staleness, and refactor candidates"
-      ],
-      "negative": [
-        "sample production behavior from deployed endpoints",
-        "generate CHANGELOG.md after a release"
-      ]
-    },
-    "roll-.echo": {
-      "positive": [
-        "the user message is contradictory and needs restatement",
-        "confirm a rambling request before any implementation"
-      ],
-      "negative": [
-        "ask detailed feature scope questions for roll-build fly mode",
-        "execute a clearly named US-XXX story"
-      ]
-    },
-    "roll-.qa": {
-      "positive": [
-        "choose the right test pyramid coverage for a story",
-        "decide whether visual, E2E, smoke, or unit tests are required"
-      ],
-      "negative": [
-        "perform code review findings after TCR",
-        "write a product proposal for backlog candidates"
-      ]
-    },
-    "roll-.review": {
-      "positive": [
-        "self-review code before committing a TCR micro-step",
-        "inspect a local diff for bugs, regressions, and security issues"
-      ],
-      "negative": [
-        "review a GitHub pull request from another branch",
-        "ask another agent for peer negotiation"
-      ]
-    },
-    "roll-build": {
-      "positive": [
-        "execute US-AUTH-001 through TCR and verification",
-        "turn this feature request into clarified design, implementation, tests, and backlog write-back"
-      ],
-      "negative": [
-        "only discuss architecture options and split backlog stories",
-        "fix FIX-123 as a narrow bug repair"
-      ]
-    },
-    "roll-debug": {
-      "positive": [
-        "mount a browser black-box probe on localhost to diagnose a broken page",
-        "collect console, network, DOM, and runtime state before fixing a web bug"
-      ],
-      "negative": [
-        "run a nightly code architecture scan",
-        "review a pull request diff"
-      ]
-    },
-    "roll-deck": {
-      "positive": [
-        "generate an 18-slide bilingual deck.md for this product topic",
-        "create slides from README, backlog, and evidence"
-      ],
-      "negative": [
-        "update project documentation index",
-        "write a daily owner brief"
-      ]
-    },
-    "roll-design": {
-      "positive": [
-        "discuss options and split this feature into INVEST stories",
-        "model the domain and write backlog/spec artifacts without coding"
-      ],
-      "negative": [
-        "execute an existing US-XXX story through TCR",
-        "hotfix a specific BUG-XXX item"
-      ]
-    },
-    "roll-doc-audit": {
-      "positive": [
-        "check README guide site and CLI help against implemented behavior",
-        "scan docs and generate docs/INDEX.md",
-        "find undocumented modules and draft missing documentation"
-      ],
-      "negative": [
-        "generate a bilingual presentation deck",
-        "diagnose Roll installation health"
-      ]
-    },
-    "roll-doctor": {
-      "positive": [
-        "diagnose Roll toolchain health and config validity",
-        "check skill files, templates, symlinks, and conventions sync"
-      ],
-      "negative": [
-        "repair a failing feature test",
-        "run production patrol sampling"
-      ]
-    },
-    "roll-fix": {
-      "positive": [
-        "fix FIX-123 through the lightweight TCR flow",
-        "repair this narrow bug with a regression test and backlog write-back"
-      ],
-      "negative": [
-        "design a new feature from vague product input",
-        "execute a broad US-XXX feature story"
-      ]
-    },
-    "roll-idea": {
-      "positive": [
-        "capture this short idea into backlog with an auto id",
-        "classify a one-line bug or idea note quickly"
-      ],
-      "negative": [
-        "turn an idea into full DDD stories",
-        "write owner briefing since last release"
-      ]
-    },
-    "roll-loop": {
-      "positive": [
-        "operate the autonomous backlog executor loop",
-        "scan Todo stories and dispatch US/FIX/REFACTOR work"
-      ],
-      "negative": [
-        "do a one-time nightly architecture scan",
-        "write a human product proposal"
-      ]
-    },
-    "roll-notes": {
-      "positive": [
-        "record this development discovery in today's project diary",
-        "append a success, failure, or decision to Roll notes"
-      ],
-      "negative": [
-        "generate user-facing changelog entries",
-        "create a backlog story from a product idea"
-      ]
-    },
-    "roll-onboard": {
-      "positive": [
-        "onboard this legacy project into Roll with interactive questions",
-        "produce .roll/onboard-plan.yaml for roll init --apply"
-      ],
-      "negative": [
-        "run setup after the project is already onboarded",
-        "audit existing skill routing quality"
-      ]
-    },
-    "roll-peer": {
-      "positive": [
-        "the user explicitly says /peer for this design decision",
-        "ask another agent to negotiate a high-risk ambiguous plan"
-      ],
-      "negative": [
-        "perform local self-review before commit",
-        "review a pull request without cross-agent negotiation"
-      ]
-    },
-    "roll-propose": {
-      "positive": [
-        "generate product proposal drafts from current project context",
-        "write 1-3 candidate user stories into .roll/proposals.md"
-      ],
-      "negative": [
-        "append a confirmed story directly to backlog",
-        "execute a Todo story through TCR"
-      ]
-    },
-    "roll-review-pr": {
-      "positive": [
-        "review this PR diff and emit APPROVE or REQUEST_CHANGES",
-        "inspect pull request changes with file and line grounded findings"
-      ],
-      "negative": [
-        "self-review a local TCR micro-step",
-        "run attacker and defender agents for high-risk logic"
-      ]
-    },
-    "roll-spar": {
-      "positive": [
-        "use adversarial TDD for auth or payment logic",
-        "spawn attacker tests and defender implementation for complex state logic"
-      ],
-      "negative": [
-        "ask for ordinary peer review of a plan",
-        "perform routine QA coverage selection"
-      ]
-    }
-  }
-}