@su-record/vibe 3.2.6 → 3.2.8

package/skills/vibe.verify/references/trace-mode.md

@@ -0,0 +1,271 @@
+---
+name: verify-trace-mode-reference
+description: Generate and display Requirements Traceability Matrix (RTM) — REQ → SPEC → Feature → Code 관계 추적
+argument-hint: "feature-name [--html] [--save]"
+user-invocable: true
+---
+
+# /vibe.trace
+
+Generate and display Requirements Traceability Matrix (RTM).
+
+## Usage
+
+```bash
+/vibe.trace "feature-name"              # Generate RTM for feature
+/vibe.trace "feature-name" --html       # Output as HTML
+/vibe.trace "feature-name" --save       # Save to file
+```
+
+> **⏱️ Timer**: Query the system clock at START and record the result as `{start_time}`.
+
+## Description
+
+Requirements Traceability Matrix (RTM) tracks the relationship between:
+- **Requirements** (REQ-xxx-xxx)
+- **SPEC sections** (Phase tasks)
+- **Feature scenarios** (BDD)
+- **Test files** (unit/integration tests)
+
+## Process
+
+### 1. Load Files
+
+**Search order (check BOTH file AND folder):**
+
+```
+Step 1: Check if SPLIT structure exists (folder)
+  📁 .vibe/specs/{feature-name}/        → Folder with _index.md + phase files
+  📁 .vibe/features/{feature-name}/      → Folder with _index.feature + phase files
+
+Step 2: If no folder, check single file
+  📄 .vibe/specs/{feature-name}.md       → Single SPEC file
+  📄 .vibe/features/{feature-name}.feature → Single Feature file
+
+Step 3: If neither exists → Error
+```
+
+**Split structure (folder) detected:**
+```
+📁 .vibe/specs/{feature-name}/
+├── _index.md              → Master SPEC (read first)
+├── phase-1-{name}.md      → Phase 1 SPEC
+└── ...
+
+📁 .vibe/features/{feature-name}/
+├── _index.feature         → Master Feature (read first)
+├── phase-1-{name}.feature → Phase 1 scenarios
+└── ...
+
+→ Load all phase files, generate RTM across all phases
+```
+
+**Single file detected:**
+```
+📄 .vibe/specs/{feature-name}.md      → SPEC
+📄 .vibe/features/{feature-name}.feature → Feature
+```
+
+**Additional (auto-detect):**
+```
+📄 src/**/*.test.ts                           → Tests (auto-detect)
+```
+
+**Error if NEITHER file NOR folder found:**
+```
+❌ SPEC not found. Searched:
+   - .vibe/specs/{feature-name}/  (folder)
+   - .vibe/specs/{feature-name}.md (file)
+
+   Run /vibe.spec "{feature-name}" first.
+```
+
+### 2. Extract Mappings
+
+For each requirement ID (REQ-xxx-xxx):
+1. Find corresponding SPEC section
+2. Find matching Feature scenario
+3. Find related test file
+
+### 3. Calculate Coverage
+
+```
+Coverage = (Full coverage items / Total requirements) × 100%
+
+Full coverage = Has SPEC + Feature + Test
+Partial = Missing one or more
+None = Only in SPEC
+```
+
+### 4. Output RTM
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 REQUIREMENTS TRACEABILITY MATRIX: {feature-name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Summary
+| Metric            | Value    |
+|-------------------|----------|
+| Total Requirements| 10       |
+| SPEC Coverage     | 10/10    |
+| Feature Coverage  | 8/10     |
+| Test Coverage     | 6/10     |
+| **Overall**       | **60%**  |
+
+## Traceability Matrix
+
+| Requirement | SPEC | Feature | Test | Coverage |
+|-------------|------|---------|------|----------|
+| REQ-login-001 | ✅ Phase 1 | ✅ Scenario 1 | ✅ login.test.ts | ✅ Full |
+| REQ-login-002 | ✅ Phase 1 | ✅ Scenario 2 | ❌ | ⚠️ Partial |
+| REQ-login-003 | ✅ Phase 2 | ❌ | ❌ | ❌ None |
+
+## Uncovered Requirements
+
+The following requirements lack full coverage:
+
+- **REQ-login-002**: Password validation
+  - Missing: Test file
+
+- **REQ-login-003**: Remember me functionality
+  - Missing: Feature scenario, Test file
+
+## Recommendations
+
+⚠️ Coverage is at 60%. Consider:
+- Add Feature scenarios for uncovered requirements
+- Add test cases for uncovered requirements
+
+⏱️ Started: {start_time}
+⏱️ Completed: {system clock result}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Example
+
+```
+User: /vibe.trace "login"
+
+Active harness:
+📊 Generating RTM for "login"...
+
+Loading files:
+  ✅ SPEC: .vibe/specs/login.md (5 requirements)
+  ✅ Feature: .vibe/features/login.feature (4 scenarios)
+  ✅ Tests: 3 test files found
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 REQUIREMENTS TRACEABILITY MATRIX: login
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Summary
+| Metric            | Value    |
+|-------------------|----------|
+| Total Requirements| 5        |
+| SPEC Coverage     | 5/5      |
+| Feature Coverage  | 4/5      |
+| Test Coverage     | 3/5      |
+| **Overall**       | **60%**  |
+
+## Traceability Matrix
+
+| Requirement | SPEC | Feature | Test | Coverage |
+|-------------|------|---------|------|----------|
+| REQ-login-001 | ✅ | ✅ | ✅ | ✅ Full |
+| REQ-login-002 | ✅ | ✅ | ✅ | ✅ Full |
+| REQ-login-003 | ✅ | ✅ | ✅ | ✅ Full |
+| REQ-login-004 | ✅ | ✅ | ❌ | ⚠️ Partial |
+| REQ-login-005 | ✅ | ❌ | ❌ | ❌ None |
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Tool Integration
+
+The RTM generation uses core tools:
+
+```bash
+# Generate RTM (generateTraceabilityMatrix is synchronous — no .then())
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => { const m = t.generateTraceabilityMatrix('login', {projectPath: process.cwd()}); console.log(t.formatMatrixAsMarkdown(m)); })"
+
+# Generate HTML
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => { const m = t.generateTraceabilityMatrix('login', {projectPath: process.cwd()}); console.log(t.formatMatrixAsHtml(m)); })"
+```
+
+> **Note:** Default SPEC path is `.vibe/specs/<feature>.md` (falls back to `.claude/vibe/specs/` then `.claude/specs/` for legacy projects).
+> `status === 'empty'` means the gate MUST be treated as failed/not-applicable, never as 100% pass.
+
+## Post-Trace Gates
+
+After `/vibe.trace` completes and the RTM is displayed, two downstream mechanisms consume the result.
+
+### Empty-result gate
+
+`generateTraceabilityMatrix` returns `status: 'empty'` when no `REQ-<feature>-NNN` IDs are found in the SPEC. This state **must be treated as a gate failure**, not as 100% coverage. When the matrix status is `empty`, report it explicitly and do not proceed as if the feature is verified.
+
+```
+RTM status === 'empty'
+  → Coverage gate: FAILED (no requirements to trace)
+  → Action: run /vibe.spec to add REQ-IDs before re-running /vibe.trace
+```
+
+### Run-ledger flow
+
+`/vibe.verify` records its outcome through `hooks/scripts/verify-ledger.js`, binding the current run ID and command-result evidence. This writes `verifyPassed` and `verifyAt` into `.vibe/metrics/run-ledger.json`. Downstream gates consume this record:
+
+| Gate | Behavior |
+|------|----------|
+| `auto-commit` | Commits only when `verifyPassed === true` AND `verifyAt > runStarted` |
+| Explicit JUDGE | Run `/vibe.verify`; it must record `verifyPassed` and command evidence before completion |
+| Lifecycle hook (optional) | May warn when `runStarted && !verifyPassed`; never substitutes for the explicit JUDGE |
+
+**To register a passing trace as verified**, run `/vibe.verify` after `/vibe.trace` reports acceptable coverage. The verify skill records the current run ID and command evidence internally — you do not invoke the ledger CLI manually.
+
+```
+/vibe.trace "login"         → RTM: 9/9 (100%)
+/vibe.verify "login"        → runs checks → records pass + run ID + command results
+                            → .vibe/metrics/run-ledger.json updated
+auto-commit / Stop gate     → verifyPassed=true, gate clears
+```
+
+If `/vibe.verify` is skipped, `auto-commit` will log the skip reason and abort the commit.
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--html` | Output as HTML file |
+| `--save` | Save to `.vibe/reports/{feature}-rtm.md` |
+| `--json` | Output as JSON |
+
+## Coverage Targets
+
+| Coverage Level | Status |
+|----------------|--------|
+| 90-100% | ✅ Excellent - Ready for release |
+| 70-89% | ⚠️ Good - Minor gaps |
+| 50-69% | ⚠️ Fair - Significant gaps |
+| 0-49% | ❌ Poor - Major gaps |
+
+---
+
+## `.last-feature` 포인터 삭제 (워크플로 완주)
+
+```
+/vibe.trace가 정상 완료되면 (RTM 출력 + 사용자 확인 후):
+  Delete ".vibe/.last-feature"
+
+이유: /vibe.trace는 vibe 워크플로의 마지막 Phase (Phase 7).
+     완주 후에는 다음 /vibe.spec 호출 시 "빈 시작" 또는 진행 중 목록에서 다른 feature를 시작해야 한다.
+     삭제하지 않으면 완료된 feature가 계속 "이어서?" 로 뜬다.
+
+예외:
+  - /vibe.trace가 에러로 중단된 경우 → 삭제하지 않음 (재시도 가능)
+  - --save 또는 --html 플래그와 무관하게 항상 삭제
+```
+
+---
+
+ARGUMENTS: {feature-name}

package/vibe/rules/principles/dual-harness-doctrine.md

@@ -34,17 +34,18 @@
 
 CC의 풍부한 hook 모델(PreToolUse/PostToolUse/UserPromptSubmit/Stop)에는 Codex에 완전한 등가물이 없다. hook의 **의도**별로 하네스에 맞는 메커니즘에 매핑한다.
 
+Codex도 이제 네이티브 hook을 지원한다(`codex features list` → `hooks: stable`). vibe는 두 메커니즘을 **모두** 사용하며, hook의 **의도**별로 매핑한다.
+
 | hook 의도 | Claude Code | Codex |
 |---|---|---|
-| 라이프사이클 (turn 완료, 세션 시작/종료) | `Stop` / `SessionStart` hook | `config.toml`의 `notify` 프로그램 (agent-turn-complete 시 JSON 발화) |
-| pre-edit / scope guard | `PreToolUse` (동기 deny) | ❌ 동기 인터셉트 없음 → AGENTS.md 운영 규칙 + notify 기반 사후 검증 |
-| 키워드 디스패치 (ralph/ultrawork) | `UserPromptSubmit` | AGENTS.md 지시 (Codex가 직역 실행) |
-| 금지 패턴 차단 | `PreToolUse` | AGENTS.md 규칙 + 에이전트에게 실행하라 지시한 check 명령 |
+| 라이프사이클 (turn 완료) | `Stop` hook | `config.toml`의 `notify` (agent-turn-complete 시 JSON 발화) |
+| 세션 시작 | `SessionStart` hook | `.codex/hooks.json` → `SessionStart` |
+| pre-edit / scope guard | `PreToolUse` (동기 deny) | `.codex/hooks.json` → `PreToolUse` (동기 deny) |
+| 키워드 디스패치 | `UserPromptSubmit` | `.codex/hooks.json` → `UserPromptSubmit` |
+| 금지 패턴 차단 | `PreToolUse` | `PreToolUse` + AGENTS.md 규칙 (이중 방어) |
 
-**핵심 통찰: Codex의 직역 성향이 AGENTS.md "soft hook"을 신뢰성 있게 만든다.** CC는 soft 지시를 가끔 무시해 hard hook이 필요하지만, Codex는 적힌 대로 실행한다. 따라서:
+**구현**: `hooks/scripts/codex-hook-adapter.js`가 Codex hook 이벤트를 기존 vibe hook 스크립트로 번역하고 deny 결정(JSON)을 보존한다. 설치는 `installProjectCodexHooks()` → `.codex/hooks.json` (프로젝트 로컬, gitignored). 라이프사이클 후처리(auto-commit·devlog)는 `codex-notify.js`가 `notify` 경로로 담당한다.
 
-- **하드 라이프사이클 이벤트** → Codex `config.toml notify` (실제·결정적). `stop-dispatcher` 로직(auto-commit, devlog, review gate) 재사용 가능.
-- **행동 가드** → AGENTS.md 운영 규칙. 직역이라 *오히려* 신뢰성 있음.
-- **진짜 동기 pre-edit 차단은 Codex에서 불가** — 사후 검증을 완화책으로 수용한다.
+**핵심 통찰: Codex의 직역 성향이 AGENTS.md "soft hook"을 신뢰성 있게 만든다.** CC는 soft 지시를 가끔 무시해 hard hook이 필요하지만, Codex는 적힌 대로 실행한다. 따라서 AGENTS.md 운영 규칙은 네이티브 hook이 생긴 뒤에도 **폐기하지 않고 2차 방어선으로 유지한다** — hook이 설치되지 않은 환경(전역 설치만 한 경우, 다른 클론)에서도 가드가 남는다.
 
-> **Action item (미구현):** `.codex/settings.local.json`에 죽은 hook을 쓰는 것을 중단하고, 대신 `.codex/config.toml`에 `notify` 핸들러를 생성해 `stop-dispatcher` 로직을 재사용하며, 가드 규칙은 AGENTS.md로 방출한다.
+> ⚠️ **훅은 "설치돼 있다"고 가정하지 않는다.** 훅은 프로젝트 로컬 아티팩트라 `vibe upgrade` 만으로는 설치되지 않는다(전역 자산만 갱신). `vibe status` 가 하네스별 훅 설치 여부를 보고하고, `vibe upgrade` 는 현재 프로젝트의 누락 훅을 복구한다. 결정론적 가드의 생사는 **관측 가능해야** 한다 — 조용히 죽은 가드는 없는 가드보다 나쁘다.

package/skills/vibe.regress/templates/test-vitest.md

@@ -1,30 +0,0 @@
-/**
- * Regression test — {{SLUG}}
- *
- * Symptom: {{SYMPTOM}}
- * Root cause tag: {{ROOT_CAUSE_TAG}}
- * Fix commit: {{FIX_COMMIT}}
- * Source record: .vibe/regressions/{{SLUG}}.md
- *
- * DO NOT delete this test when the bug is fixed — it exists to prevent the
- * same bug from being reintroduced. Update only if the reproduction steps
- * in the source record change.
- */
-
-import { describe, it, expect{{EXTRA_IMPORTS}} } from 'vitest';
-{{IMPORTS_FROM_SUT}}
-
-describe('regression: {{SYMPTOM_SHORT}}', () => {
-  it('{{TEST_NAME}}', {{ASYNC}}() => {
-    // Given: {{GIVEN}}
-    {{GIVEN_CODE}}
-
-    // When: {{WHEN}}
-    {{WHEN_CODE}}
-
-    // Then: {{THEN}}
-    {{THEN_ASSERTIONS}}
-  });
-
-  {{EXTRA_IT_BLOCKS}}
-});