@su-record/vibe 2.9.2 → 2.9.3

package/commands/vibe.harness.md

@@ -0,0 +1,177 @@
+---
+description: Diagnose project Harness Engineering maturity across 6 axes
+argument-hint: (no arguments)
+---
+
+# /vibe.harness
+
+Diagnose project Harness Engineering maturity across 6 axes and suggest targeted improvements.
+
+> Harness = the working environment that enables AI to operate effectively on its own.
+> Encompasses context, constraints, workflows, verification, and compounding — not just guardrails.
+
+## Step 0: Detect Project Type
+
+Before scoring, read `CLAUDE.md` and `package.json` to determine project type:
+
+| Type | Signal | Effect |
+|------|--------|--------|
+| **Application** (webapp, api, fullstack, mobile) | `type` in config, app-like structure | Full rubric applies |
+| **Package/Library** | `"main"` or `"exports"` in package.json, "npm package" in CLAUDE.md | Skip docs/, .dev/ items (mark N/A), adjust total denominator |
+| **Monorepo** | `workspaces` in package.json, `apps/` or `packages/` dirs | Score each workspace separately |
+
+When items are N/A, **remove their points from the total** rather than scoring 0. A library scoring 65/80 (N/A items excluded) = 81%, not 65%.
+
+---
+
+## Process
+
+### 1. Collect Project State (Parallel Agents)
+
+Dispatch 3 explorer agents in a single message:
+
+```text
+Agent(subagent_type="explorer-low", model="haiku",
+  prompt="Check project scaffolding: 1) Does docs/ exist with business documents? 2) Does .dev/ exist for AI logs? 3) Is src/ organized by role (not flat)? 4) Is tests/ separate from src/? 5) List top-level directory structure.")
+
+Agent(subagent_type="explorer-low", model="haiku",
+  prompt="Check project context and boundaries: 1) Does CLAUDE.md exist? How many lines? 2) Does .claude/rules/ or .claude/vibe/ exist? How many rule files? 3) Does .claude/settings.local.json exist with hooks? 4) Does .claude/vibe/config.json exist? 5) Are there any .claude/skills/ directories?")
+
+Agent(subagent_type="explorer-low", model="haiku",
+  prompt="Check project planning, execution, and verification: 1) Are there SPEC files in .claude/vibe/specs/? 2) Are there Feature (BDD) files in .claude/vibe/features/? 3) Are there test files? How many? 4) Is there CI config (.github/workflows, etc.)? 5) Are there .dev/learnings/ files?")
+```
+
+### 2. Score Each Axis
+
+#### Axis 1: Scaffolding — /20
+
+| Item | Criteria | Points |
+|------|----------|--------|
+| Role-based folders | src/ subdivided by role (components/, services/, models/, etc.) | /5 |
+| docs/ exists | Business document directory with content (N/A for packages/libraries) | /4 |
+| .dev/ exists | AI work log directory (N/A for packages/libraries) | /3 |
+| tests/ separated | Tests not co-located with source files | /3 |
+| .gitignore complete | Includes out/, .dev/scratch/, settings.local.json | /2 |
+| Layer separation | Domain/service/infra or similar architectural layers | /3 |
+
+#### Axis 2: Context — /20
+
+| Item | Criteria | Points |
+|------|----------|--------|
+| CLAUDE.md exists | Serves as project map | /5 |
+| CLAUDE.md is concise | ~100 lines or fewer, pointer-based | /3 |
+| Rules defined | Coding rules and test conventions in .claude/rules/ or similar | /4 |
+| Progressive disclosure | Skill tier separation or rules loaded via glob patterns | /3 |
+| docs/ referenced | CLAUDE.md references docs/ for business context | /3 |
+| Language rules | Stack-specific coding standards defined | /2 |
+
+#### Axis 3: Planning — /15
+
+| Item | Criteria | Points |
+|------|----------|--------|
+| SPEC workflow | System for generating spec/feature files | /5 |
+| Requirements gathering | Interview or requirements collection process exists | /4 |
+| Approval gates | Confirmation step between planning and implementation | /3 |
+| Templates | SPEC/Feature templates available | /3 |
+
+#### Axis 4: Orchestration — /15
+
+| Item | Criteria | Points |
+|------|----------|--------|
+| Agents or skills | Specialized agents or skills defined | /5 |
+| Team composition | Agent teams (architect + implementer + tester, etc.) | /4 |
+| Permission model | Per-agent permission separation (read-only vs write) | /3 |
+| Non-code workflows | Support for documentation, research, and other non-code tasks | /3 |
+
+#### Axis 5: Verification — /15
+
+| Item | Criteria | Points |
+|------|----------|--------|
+| Automated quality checks | PostToolUse hooks for code inspection | /4 |
+| Tests exist | Test files present and executable | /4 |
+| CI/CD | Automated build/test pipeline configured | /4 |
+| Traceability | SPEC → code → test mapping (RTM) | /3 |
+
+#### Axis 6: Compounding — /15
+
+| Item | Criteria | Points |
+|------|----------|--------|
+| Learnings recorded | Troubleshooting records in .dev/learnings/ (N/A for packages/libraries) | /4 |
+| Pattern accumulation | Repeated tasks codified as skills or rules | /4 |
+| Auto-improvement | Evolution Engine or similar self-improvement mechanism | /4 |
+| Memory | Cross-session learning persistence mechanism | /3 |
+
+### 3. Generate Report
+
+```markdown
+## Harness Diagnosis (N/100)
+
+### Score and Grade
+- **Score**: N/100
+- **Grade**: [S / A / B / C / D]
+
+| Grade | Range | Description |
+|-------|-------|-------------|
+| S | 90-100 | Production-ready Harness |
+| A | 75-89 | Well-structured, minor gaps |
+| B | 60-74 | Functional but missing key elements |
+| C | 40-59 | Basic setup, significant gaps |
+| D | 0-39 | Minimal or no Harness |
+
+### Axis Scores
+
+| Axis | Score | Details |
+|------|-------|---------|
+| Scaffolding | /20 | [findings] |
+| Context | /20 | [findings] |
+| Planning | /15 | [findings] |
+| Orchestration | /15 | [findings] |
+| Verification | /15 | [findings] |
+| Compounding | /15 | [findings] |
+
+### Top 3 Improvements
+
+1. **[lowest axis]**: [specific action with command]
+2. **[second lowest]**: [specific action with command]
+3. **[third lowest]**: [specific action with command]
+
+### Auto-Fixable Items
+
+The following can be improved immediately:
+1. [ ] `/vibe.scaffold` — generate missing project directories
+2. [ ] `vibe init` — initialize AI configuration
+3. [ ] `vibe update` — regenerate CLAUDE.md from project analysis
+
+Proceed with auto-fix? (y/n)
+```
+
+### 4. Save Report
+
+Save results to `.claude/vibe/reports/harness-{date}.md` for historical tracking.
+
+### 5. Self-Repair Chain
+
+After scoring, if actionable gaps are detected:
+
+| Condition | Auto-Suggestion |
+|-----------|-----------------|
+| Scaffolding < 10/20 | Suggest `/vibe.scaffold` to generate missing directories |
+| Context < 10/20 | Suggest `vibe update` to regenerate CLAUDE.md |
+| Planning < 8/15 | Suggest `/vibe.spec` to establish SPEC workflow |
+| Verification < 8/15 | Suggest `vibe init` to install quality hooks |
+| Compounding < 8/15 | Suggest creating `.dev/learnings/` and enabling evolution engine |
+
+If user approves auto-fix, execute the suggested commands in sequence, then re-run `/vibe.harness` to verify improvement.
+
+---
+
+## Principles
+
+1. **Score honestly** — never inflate scores
+2. **Suggest specific actions** — executable commands, not vague advice like "improve structure"
+3. **Focus on top 3** — don't try to fix everything at once
+4. **Track over time** — enable score comparison across runs via saved reports
+
+---
+
+ARGUMENTS: $ARGUMENTS

package/commands/vibe.run.md

@@ -132,7 +132,7 @@ After implementing each scenario, **automatic verification**:
 │              → Fix code (Read full file first)                   │
 │              → Re-run failed scenario only                       │
 │              → PASS? → Next scenario                             │
-│              → FAIL? → Retry (max 3)                             │
+│              → FAIL (same as prev)? → STUCK → Ask user           │
 │                                                                  │
 │  핵심: 검증이 가벼울수록 루프는 더 많이 돈다                       │
 │  - 접근성 트리: button "Sign In" = 15 chars                      │
@@ -171,9 +171,17 @@ Scenario verification failed (코드 분석 또는 E2E)
       ↓
 [Re-verify] - Re-run ONLY failed scenario (save tokens)
       ↓
-Repeat until pass (max 3 times)
+Repeat until pass (라운드 수 캡 없음 — stuck 감지로 종료)
 ```
 
+**Termination conditions:**
+- ✅ PASS → 다음 scenario
+- ⚠️ Stuck (같은 failure가 이전 라운드와 동일) → 사용자 질문:
+    1. 직접 수정 방법 제공 (예: "LoginForm.tsx 42줄 수정") → 재시도
+    2. "proceed" — 남은 실패 TODO 기록 후 다음 scenario
+    3. "abort" — 구현 중단
+- `ultrawork` 모드: stuck 시 프롬프트 없이 TODO 기록 후 다음 scenario
+
 ---
 
 ## **ULTRAWORK Mode** (ulw)
@@ -191,7 +199,7 @@ When you include `ultrawork` (or `ulw`), ALL of these activate automatically:
 | **Context Compression** | Aggressive auto-save at 70%+ context |
 | **No Pause** | Doesn't wait for confirmation between phases |
 | **External LLMs** | Auto-consults GPT/Gemini if enabled |
-| **Error Recovery** | Auto-retries on failure (up to 3 times) |
+| **Error Recovery** | Loops until 100% or stuck; on stuck auto-records TODO and proceeds (no user prompt) |
 | **Race Review (v2.6.9)** | Multi-LLM review (GPT+Gemini) with cross-validation |
 
 ### Boulder Loop (Inspired by Sisyphus)
@@ -258,7 +266,7 @@ Like Sisyphus rolling the boulder, ULTRAWORK **keeps going until done**:
 │   └──────────────────────────────────────────────────────────┘  │
 │                              │                                   │
 │                   ┌──────────┴──────────┐                       │
-│                   │  Coverage ≥ 95%?    │                       │
+│                   │  Coverage == 100%?  │                       │
 │                   └──────────┬──────────┘                       │
 │                       │              │                          │
 │                      NO            YES                          │
@@ -273,9 +281,18 @@ Like Sisyphus rolling the boulder, ULTRAWORK **keeps going until done**:
 │                      │                                          │
 │                      └──────────→ [Re-generate RTM]             │
 │                                                                  │
-│   MAX_ITERATIONS: 5 (prevent infinite loops)                    │
-│   COVERAGE_THRESHOLD: 95% (quality gate)                        │
-│   ZERO TOLERANCE for scope reduction                            │
+│                      │                                          │
+│                      ↓                                          │
+│              Stuck? (coverage unchanged from prev iteration)    │
+│                      │                                          │
+│                      ├─ Interactive: Ask user                   │
+│                      │     1. Provide resolution → retry        │
+│                      │     2. "proceed" → TODO + done           │
+│                      │     3. "abort" → stop                    │
+│                      └─ ultrawork: TODO + done                  │
+│                                                                  │
+│   NO iteration cap — loop until 100% OR stuck                   │
+│   ZERO TOLERANCE for silent scope reduction                     │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
@@ -302,18 +319,18 @@ node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index
 | Rule | Description |
 |------|-------------|
 | **No Scope Reduction** | Never say "simplified" or "basic version" - implement FULL request |
-| **Iteration Tracking** | Display `[{{ITER}}/{{MAX}}]` to show progress |
+| **Iteration Tracking** | Display `[{{ITER}}]` to show progress (no max — loop until done) |
 | **RTM-Based Gap List** | Use `uncoveredRequirements` array - no manual comparison |
-| **Coverage Threshold** | Must reach 95% coverage to complete |
-| **Max Iterations** | Stop at 5 iterations (report remaining gaps as TODO) |
-| **Convergence Detection** | If coverage % unchanged between iterations → STOP (converged) |
-| **Diminishing Returns** | Iteration 3+ → only implement unmet core requirements (REQ-*-001~003), rest goes to TODO |
+| **Coverage Threshold** | Must reach 100% coverage to complete |
+| **No Iteration Cap** | Loop until 100% coverage OR stuck (convergence detected) |
+| **Stuck Handling** | If coverage % unchanged between iterations → ask user (proceed/abort/fix), or ultrawork → TODO + done |
+| **Diminishing Returns (Narrowing)** | Iteration 3+ → focus on core requirements (REQ-*-001~003) first; P2/P3 requirements continue to loop but lower priority |
 
 **Ralph Loop Output Format:**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🔄 RALPH VERIFICATION [Iteration 1/5]
+🔄 RALPH VERIFICATION [Iteration 1]
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 📊 RTM Coverage Report: login
@@ -334,7 +351,7 @@ Requirements Traceability:
   ❌ REQ-login-008: Error toast → NOT IMPLEMENTED
   ✅ REQ-login-009: Session storage → Scenario 4 → (no test)
 
-Overall Coverage: 55% ⚠️ BELOW 95% THRESHOLD
+Overall Coverage: 55% ⚠️ BELOW 100% TARGET
 
 UNCOVERED REQUIREMENTS (auto-extracted from RTM):
   1. REQ-login-004: Remember me checkbox
@@ -345,7 +362,7 @@ UNCOVERED REQUIREMENTS (auto-extracted from RTM):
 ⚠️ NOT COMPLETE - Implementing uncovered requirements...
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🔄 RALPH VERIFICATION [Iteration 2/5]
+🔄 RALPH VERIFICATION [Iteration 2]
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 📊 RTM Coverage Report: login
@@ -356,7 +373,7 @@ Requirements Traceability:
   Feature Covered: 9/9 (100%)
   Test Covered: 9/9 (100%)
 
-Overall Coverage: 100% ✅ ABOVE 95% THRESHOLD
+Overall Coverage: 100% ✅ TARGET REACHED
 
 Build: ✅ Passed
 Tests: ✅ 12/12 Passed
@@ -396,7 +413,7 @@ Claude:
 📄 SPEC: .claude/vibe/specs/brick-game.md
 🎯 4 Phases detected
 ⚡ Boulder Loop: ENABLED (will continue until all phases complete)
-🔄 Auto-retry: ON (max 3 per phase)
+🔄 Auto-retry: ON (loop until 100% or stuck → auto-TODO)
 💾 Context compression: AGGRESSIVE
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -416,7 +433,7 @@ Claude:
 ✅ Exploration complete (6.8s)
 🔨 Implementing...
 ❌ Test failed: collision detection
-🔄 Auto-retry 1/3...
+🔄 Auto-retry [iteration 1]...
 🔨 Fixing...
 ✅ Phase 2 complete
 
@@ -454,13 +471,13 @@ Magic keywords in the user input automatically set the **AutomationLevel**, whic
 
 ### Level Definitions
 
-| Level | Name | Keyword(s) | Auto-advance | Auto-retry | Max Retries | Parallel Agents | Checkpoints |
-|-------|------|------------|--------------|------------|-------------|-----------------|-------------|
-| L0 | Manual | `manual` | No | No | 0 | No | All |
-| L1 | Guided | `guided`, `verify` | No | No | 0 | No | All |
-| L2 | Semi-auto | `quick` (default) | Yes | Yes | 2 | No | Key points |
-| L3 | Auto | `ultrawork`, `ulw` | Yes | Yes | 3 | Yes | Checkpoint-only |
-| L4 | Full-auto | `ralph`, `ralplan` | Yes | Yes | 5 | Yes | None |
+| Level | Name | Keyword(s) | Auto-advance | Auto-retry | Stuck Behavior | Parallel Agents | Checkpoints |
+|-------|------|------------|--------------|------------|----------------|-----------------|-------------|
+| L0 | Manual | `manual` | No | No | Ask user every step | No | All |
+| L1 | Guided | `guided`, `verify` | No | No | Ask user on stuck | No | All |
+| L2 | Semi-auto | `quick` (default) | Yes | Yes (low cap: 2) | Ask user after 2 retries | No | Key points |
+| L3 | Auto | `ultrawork`, `ulw` | Yes | Yes (no cap) | Auto-TODO + proceed | Yes | Checkpoint-only |
+| L4 | Full-auto | `ralph`, `ralplan` | Yes | Yes (no cap) | Auto-TODO + proceed | Yes | None |
 
 ### Detection Rule
 
@@ -1043,7 +1060,7 @@ Then: Login success + JWT token returned
   ❌ Then: "Invalid credentials" error message
      Actual: "Error occurred" returned
 
-[Auto-fix 1/3]
+[Auto-fix iteration 1]
   Cause: Error message not properly set
   Fix: auth.service.ts line 42
 
@@ -1675,7 +1692,7 @@ Then: Login success + JWT token returned
   ❌ Then: "Invalid credentials" error message
      Actual: "Error" returned
 
-🔄 Auto-fix 1/3...
+🔄 Auto-fix [iteration 1]...
   Fix: auth.service.ts line 42
 
 🔍 Re-verifying...

package/commands/vibe.scaffold.md

@@ -0,0 +1,195 @@
+---
+description: Generate or audit project folder structure optimized for AI-assisted development
+argument-hint: --check (audit existing) or project-type
+---
+
+# /vibe.scaffold
+
+Design and generate a project structure where AI works effectively on its own.
+
+> "A well-designed project structure trains AI to follow it naturally."
+
+## Usage
+
+```
+/vibe.scaffold                 # Generate structure (auto-detect stack)
+/vibe.scaffold --check         # Audit existing structure + suggest improvements
+/vibe.scaffold webapp          # Generate webapp-type structure
+/vibe.scaffold api             # Generate api-type structure
+```
+
+---
+
+## Process
+
+### 1. Assess Current State
+
+1. Read `CLAUDE.md`, `package.json`, `pyproject.toml`, `pubspec.yaml`
+2. Scan existing folder structure via `Glob`
+3. Read `.claude/vibe/config.json` for detected stacks
+
+### 2. Determine Project Type
+
+| Type | Structure |
+|------|-----------|
+| `webapp` | src/ + pages/ + components/ + hooks/ + styles/ |
+| `api` | src/ + routes/ + services/ + models/ + middleware/ |
+| `fullstack` | src/client/ + src/server/ or apps/ monorepo |
+| `library` | src/ + examples/ + benchmarks/ |
+| `mobile` | lib/ (Flutter) or src/ (React Native) |
+
+### 3. Generate Base Structure
+
+Common directories for all projects:
+
+```
+my-project/
+├── src/              # Business logic
+├── docs/             # Human-maintained business documents (AI reference)
+│   ├── README.md     # Explains purpose: business rules, domain defs, ADR
+│   └── adr/          # Architecture Decision Records
+├── tests/            # Test infrastructure
+├── .dev/             # AI-generated work logs
+│   ├── README.md     # Explains purpose: learnings, debug logs, scratch
+│   ├── learnings/    # Troubleshooting records
+│   └── scratch/      # Experiments, scratchpad (gitignored)
+├── .claude/          # AI configuration (managed by vibe init)
+├── out/              # Build artifacts (gitignored)
+└── CLAUDE.md         # Project map
+```
+
+### 4. Stack-Specific src/ Layout
+
+**React/Next.js (webapp):**
+```
+src/
+├── components/       # Reusable UI components
+│   ├── ui/           # Primitives (Button, Input, Modal)
+│   └── features/     # Feature-specific components
+├── pages/ or app/    # Routes (varies by Next.js version)
+├── hooks/            # Custom hooks
+├── lib/              # Utilities, helpers
+├── services/         # API calls, external services
+├── stores/           # State management (zustand, jotai, etc.)
+├── types/            # Type definitions
+└── styles/           # Global styles
+```
+
+**Express/NestJS/FastAPI (api):**
+```
+src/
+├── routes/           # API routes (or controllers/)
+├── services/         # Business logic
+├── models/           # Data models, schemas
+├── middleware/       # Auth, logging, error handling
+├── lib/              # Utilities
+├── types/            # Type definitions
+└── config/           # Configuration management
+```
+
+**Flutter (mobile):**
+```
+lib/
+├── screens/          # Screen widgets
+├── widgets/          # Reusable widgets
+├── services/         # API, local storage
+├── providers/        # State management
+├── models/           # Data models
+├── utils/            # Utilities
+└── config/           # Configuration, constants
+```
+
+### 5. Clean Architecture Layers (Optional)
+
+```
+src/
+├── domain/           # Business rules (pure logic, no external deps)
+├── application/      # Use cases (domain composition)
+├── infrastructure/   # External integrations (DB, API, files)
+└── presentation/     # UI or API endpoints
+```
+
+Layer rules:
+- Dependency direction: presentation → application → domain (reverse forbidden)
+- domain must not import external packages
+- infrastructure implements domain interfaces
+
+### 6. Generate Supporting Files
+
+| File | Content |
+|------|---------|
+| `docs/README.md` | Purpose of docs/ directory |
+| `.dev/README.md` | Purpose of .dev/ directory |
+| `.gitignore` additions | `out/`, `.dev/scratch/` entries |
+
+### 7. Update CLAUDE.md
+
+Add generated structure as pointers in CLAUDE.md:
+
+```markdown
+## Project Structure
+- `src/` — Business logic
+- `docs/` — Human-maintained business docs (AI reads before work)
+- `tests/` — Test infrastructure
+- `.dev/` — AI-generated work logs
+- `.claude/` — AI configuration
+```
+
+---
+
+## --check Mode: Audit Existing Structure
+
+### Checklist
+
+| Item | Criteria | Points |
+|------|----------|--------|
+| `docs/` exists | Business documents separated | /15 |
+| `.dev/` exists | AI work logs separated | /10 |
+| src/ sub-structure | Role-based folder organization | /20 |
+| tests/ separated | Not co-located with source | /15 |
+| CLAUDE.md describes structure | Folder purposes documented | /10 |
+| .gitignore complete | Includes out/, .dev/scratch/ | /5 |
+| Layer separation | Domain/service/infra distinction | /15 |
+| Dependency direction consistency | No reverse imports | /10 |
+
+### Output
+
+```markdown
+## Scaffold Audit Result (N/100)
+
+### Current Structure
+[tree output]
+
+### Findings
+| Item | Status | Recommendation |
+|------|--------|----------------|
+| docs/ | Missing | `mkdir docs && echo "..." > docs/README.md` |
+| ... | ... | ... |
+
+### Auto-Fixable Items
+1. [ ] Create docs/
+2. [ ] Create .dev/
+3. [ ] Update .gitignore
+
+Proceed with auto-fix? (y/n)
+```
+
+### Self-Repair
+
+If audit score < 60, automatically suggest:
+1. Run `/vibe.scaffold` to generate missing directories
+2. Run `vibe update` to regenerate CLAUDE.md with structure info
+3. Run `/vibe.harness` for full maturity assessment
+
+---
+
+## Principles
+
+1. **Never delete or move existing files** — only add new directories
+2. **Empty directories get a README.md** — purpose description helps AI understand context
+3. **No structure < bad structure < good structure** — any scaffolding improves AI output
+4. **Separate by ownership** — human docs (docs/) vs AI logs (.dev/) in different directories
+
+---
+
+ARGUMENTS: $ARGUMENTS