@su-record/vibe 3.2.6 → 3.2.8

package/skills/vibe.run/references/process-steps.md

@@ -0,0 +1,179 @@
+# vibe.run — Process Steps 1–8 (상세)
+
+> vibe.run SKILL.md 의 Process 표에서 참조. 각 단계의 전체 절차·체크포인트 템플릿·코드 예시.
+
+### 1. Load SPEC + Feature
+
+**Search order:**
+```
+Step 1: Check split structure (folder)
+  .vibe/specs/{feature-name}/        → Folder: _index.md + phase files
+  .vibe/features/{feature-name}/     → Folder: _index.feature + phase files
+
+Step 2: If no folder, check single file
+  .vibe/specs/{feature-name}.md
+  .vibe/features/{feature-name}.feature
+
+Step 3: If neither → Error: "Run /vibe.spec first"
+```
+
+**Split structure:** Load `_index.md` first, then phase files in order. Execute phases sequentially (or per `--phase` flag).
+
+### 1-0. Compile + validate execution packet (MANDATORY)
+
+For a monolithic SPEC, compile it after resolving the canonical path. For a split SPEC, do not compile `_index.md`; defer this step until each active phase file is loaded in Phase Isolation Step B. Compile with `writeExecutionPacket`, then immediately verify the saved artifact with `validateExecutionPacket`.
+
+```bash
+node -e "import('file://{{VIBE_PATH}}/dist/tools/index.js').then(t => {
+  const projectPath=process.cwd(), specPath='.vibe/specs/{feature-name}.md';
+  const profile='{codex-or-claude-code}';
+  const written=t.writeExecutionPacket({projectPath,specPath,profile});
+  if(!written.ok){console.error(JSON.stringify(written.errors));process.exit(1)}
+  const checked=t.validateExecutionPacket({projectPath,specPath,packetPath:written.packetPath});
+  if(!checked.valid){console.error(checked.code);process.exit(1)}
+  console.log(written.packetPath);
+})"
+```
+
+- Codex uses profile `codex`; Claude Code uses `claude-code`.
+- Split SPECs compile each active `phase-N-*.md` immediately before that phase runs; `_index.md` remains the overview ANCHOR and is not treated as a phase contract.
+- Use the packet only when validation returns `valid: true`.
+- `STALE_PACKET`, invalid packet, preservation-audit failure, or budget failure is blocking: recompile from the canonical SPEC and never silently fall back to an unvalidated packet.
+- The packet is a derived execution view. The canonical SPEC remains the ANCHOR and source of truth.
+
+### 1-1. Phase Isolation Protocol (Large SPEC Guard, MANDATORY for 3+ phases)
+
+```
+Step A: Read _index.md (overview only — phase list, REQ IDs)
+Step B: For each Phase N:
+  1. RE-READ Phase N SPEC section (every time, no memory)
+  2. Compile + validate Phase N execution packet using the phase file path
+  3. RE-READ Phase N Feature scenarios
+  4. Extract Phase N scope: files, scenarios, requirements
+  5. Implement Phase N scenarios
+  6. Verify Phase N
+  7. Write Phase Checkpoint → .vibe/checkpoints/
+  8. DISCARD Phase N details from working memory
+Step C: Next Phase
+```
+
+**Phase Checkpoint** (`.vibe/checkpoints/{feature}-phase-{N}.md`):
+
+```markdown
+# Checkpoint: {feature} Phase {N}
+
+## Completed
+- Scenario 1: {name} ✅
+
+## Files Changed
+- src/auth.service.ts (added login(), validateToken())
+
+## State for Next Phase
+- Auth service exports: login(), logout(), validateToken()
+
+## Remaining Phases
+- Phase {N+1}: {name} — {scenario count} scenarios
+```
+
+**SPEC Re-anchoring (Before EVERY scenario):** Re-read the EXACT Given/When/Then from Feature file (not from memory). Compare: "Am I implementing what the SPEC says, or what I think it says?"
+
+**Scope Lock (Per Phase):**
+
+```
+At Phase start, declare:
+  MODIFY: [list of files this phase will touch]
+  CREATE: [list of files this phase will create]
+  DO NOT TOUCH: everything else
+```
+
+**Context Pressure:**
+
+| Context Level | Action |
+|---------------|--------|
+| < 50% | Normal execution |
+| 50-85% | Save checkpoint, trim exploration results |
+| 85%+ | Save checkpoint → `/new` → resume from checkpoint |
+| Phase boundary | Always save checkpoint |
+
+### 1-2. SPEC-First Gate
+
+> SPEC is the source of truth for code. To modify code, update the SPEC first.
+
+```
+Discovery: "An API endpoint not in SPEC is needed"
+    ├─ Already in SPEC? YES → Implement
+    ├─ Not in SPEC but within scope? → Add to SPEC + Feature → Implement
+    └─ Outside scope? → TODO in .vibe/todos/out-of-scope-{item}.md
+```
+
+SPEC changes and code changes must be in the **same commit**.
+
+### 2. Extract Scenario List
+
+```markdown
+| # | Scenario | Status |
+|---|----------|--------|
+| 1 | Valid login success | ⬜ |
+| 2 | Invalid password error | ⬜ |
+```
+
+### 3. Scenario-by-Scenario Implementation
+
+> Read `references/parallel-agents.md` for full parallel exploration patterns, background agents, parallel subagent group selection, and model routing.
+
+**For each scenario:**
+1. [Parallel exploration] Delegate up to 3 independent workers through native collaboration — related code, deps, patterns. Claude Code maps workers to Task/Agent; Codex maps them to native collaboration; inherit the session model by default.
+2. [Implement] Write/edit the minimum required code
+3. [Verify] Check Given/When/Then; E2E if UI scenario
+4. [Auto-fix loop] On failure: collect evidence → root cause → fix → re-verify
+
+**UI/UX Design Intelligence (auto-triggered before Phase 1 if UI keywords in SPEC):**
+- Delegate `design-system-gen` through native collaboration: framework-specific component guidelines + chart/viz library advice (viz advice conditional on chart keywords). Inherit the session model.
+- Load `.vibe/design-system/{project}/MASTER.md` if present
+
+### 4. Brand Assets (New project only)
+
+> Read `references/brand-assets.md` when SPEC contains brand context and this is the first run.
+
+Trigger conditions: first run (no favicon.ico) + SPEC has brand context + Antigravity API key configured.
+
+### 5. Race Code Review
+
+> Read `references/race-review.md` for full Race Review invocation, confidence matrix, and quality gate thresholds.
+
+After all scenarios: GPT + Antigravity review in parallel. ULTRAWORK enables this by default.
+
+### 6. Quality Report (Auto-generated)
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  QUALITY REPORT: {feature}                                       │
+├─────────────────────────────────────────────────────────────────┤
+│  Scenarios: N/N passed                                          │
+│  Quality score: 94/100                                          │
+│  Build: ✅ | Tests: ✅ | Types: ✅ | Race review: ✅             │
+│  Started: {start_time}  Completed: {system clock result}        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 7. Update Feature File
+
+Auto-update scenario status with `Last verified` timestamp and quality score.
+
+### 8. Coverage Verification Loop (RTM)
+
+> 루프 시맨틱은 `vibe/rules/loop-contract.md`를 따른다. 여기서의 exit 기준은 `coveragePercent === 100`. RTM 다이어그램, 출력 형식, 반복 규칙: `references/ralph-loop.md`
+
+After ALL phases complete:
+
+```bash
+# generateTraceabilityMatrix is synchronous — no .then()
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => { const r = t.generateTraceabilityMatrix('{feature-name}', {projectPath: process.cwd()}); console.log(JSON.stringify(r, null, 2)); })"
+```
+
+> Default SPEC path is `.vibe/specs/<feature>.md`. `status === 'empty'` must be treated as failed/not-applicable — never as 100% pass.
+
+JUDGE: `coveragePercent === 100` → 루프 종료. stuck(연속 2회 동일 커버리지) → automationLevel confirm이면 사용자 질문; autonomous이면 TODO + done.
+
+---
+

package/skills/vibe.run/references/restraint.md

@@ -0,0 +1,66 @@
+# Restraint — Don't Write It, Don't Tune It (Yet)
+
+> vibe.run 내부 구현. YAGNI 사다리 · Pike 최적화 규칙 · 차단 충동 · 무효화 불가 예외의 전문.
+
+# Restraint — Don't Write It, Don't Tune It (Yet)
+
+Two constraints, one gate:
+
+- **No premature code.** New abstractions must be *pulled* by a demonstrated
+  need, never pushed by "might need it later." Once the code exists, deleting
+  it costs more than never writing it.
+- **No premature optimization.** Performance work must be *pulled* by a
+  measurement, never by a hunch.
+
+## The YAGNI Ladder (code axis)
+
+Satisfy the need at the **highest** rung that covers it; lower rungs are
+blocked while a higher one applies:
+
+1. **Not needed** — the requirement doesn't ask for it → don't build it
+2. **Stdlib / built-ins** already do it (`crypto`, `Intl`, `pathlib`, …)
+3. **Native platform feature** does it (`<input type="date">`, CSS `:has()`, DB constraints)
+4. **Already-installed dependency** covers it — check the lockfile, don't guess
+5. **One line** — a single expression; no new file, no class
+6. **Minimal code** — only now, and nothing for "later"
+
+Tie-break: native beats a one-liner; stdlib beats a dependency. Generalize
+only when a *second* caller exists.
+
+## Pike's Rules (optimization axis)
+
+- You can't tell where a program spends its time — bottlenecks surprise.
+  **Measure; don't guess.**
+- Don't tune until one part *measurably* overwhelms the rest.
+- Fancy algorithms are slow when n is small — and n is usually small.
+  Ask "what's n?" before "what's the Big-O?"
+- Simple algorithms + the right data structures beat clever code. Data dominates.
+
+Optimization is justified only when ALL hold: a measured bottleneck exists →
+it dominates runtime → the fix is the simplest change addressing it → you
+re-measure after.
+
+## Blocked Impulses
+
+| Impulse | Constraint | Counter |
+|---|---|---|
+| helper / utility / wrapper / manager class | rungs 1–5 | a stdlib call or one line usually suffices |
+| config system for one value | rung 1 | a `const` is the config |
+| generic `Processor(strategy, validator…)` | rung 1 | one concrete function until a second caller exists |
+| "add a cache here" / "parallelize this" | measure first | is this path even hot? Often it's I/O |
+| swap in a B-tree / trie / skip list | what's n? | O(n²) with n=100 is microseconds |
+| "this loop looks slow" | measure first | the bottleneck is probably elsewhere |
+
+## Overrides — Restraint Never Erodes These
+
+1. **Security and trust-boundary work are requirements**, not optional
+   complexity. Input validation, auth checks, escaping stay in — "one line"
+   is no excuse to drop them.
+2. **Deliberate simplifications get a comment + upgrade path**, so the next
+   reader sees a *choice*, not an oversight:
+
+   ```ts
+   // Global lock is enough at current throughput.
+   // Switch to per-account locking if write contention shows up.
+   const lock = new Mutex();
+   ```

package/skills/vibe.run/references/ultrawork-mode.md

@@ -10,7 +10,7 @@
 
 | Feature | Description |
 |---------|-------------|
-| **Parallel Exploration** | 3+ Task(haiku) agents run simultaneously (ACT 병렬화) |
+| **Parallel Exploration** | 3+ Task agents run simultaneously (ACT 병렬화) |
 | **Loop (기본 동작)** | 모든 실행의 기본 — exit=게이트 통과 또는 stuck 또는 max_iterations |
 | **Context Compression** | Aggressive auto-save at 70%+ context |
 | **No Pause** | stuck·SPEC 게이트 외 확인 없음 (`automationLevel: autonomous`) |

package/skills/vibe.scaffold/SKILL.md

@@ -1,12 +1,19 @@
 ---
 name: vibe.scaffold
-description: Generate or audit project folder structure optimized for AI-assisted development
+description: 새 프로젝트 구조를 만들거나 기존 폴더 구조가 AI-assisted development에 적합한지 감사할 때 사용한다.
 argument-hint: --check (audit existing) or project-type
 user-invocable: true
 ---
 
 # /vibe.scaffold
 
+## 완료 기준
+
+- [ ] 요청된 디렉터리와 필수 설정 파일이 존재한다.
+- [ ] 생성한 package 또는 module의 build 명령이 통과한다.
+- [ ] import·module 해석 검사가 통과한다.
+- [ ] audit mode에서는 발견 항목마다 실제 경로 근거가 있다.
+
 Design and generate a project structure where AI works effectively on its own.
 
 > "A well-designed project structure trains AI to follow it naturally."
@@ -103,18 +110,7 @@ lib/
 
 ### 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
+When clean architecture is explicitly selected, read `references/clean-architecture.md`. Default stack layouts and `--check` audits do not load it.
 
 ### 6. Generate Supporting Files
 

package/skills/vibe.scaffold/references/clean-architecture.md

@@ -0,0 +1,17 @@
+# Optional Clean Architecture Layout
+
+Load only when clean architecture is explicitly selected.
+
+```
+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

package/skills/vibe.spec/SKILL.md

@@ -1,12 +1,19 @@
 ---
 name: vibe.spec
-description: SPEC 진입점 — 자연어 요구사항(+첨부)을 받아 단일 패스 SPEC 작성 → 1회 승인 → /vibe.run 핸드오프
+description: 자연어 요구사항이나 첨부 자료로 승인 가능한 SPEC을 작성해야 할 때 — 단일 패스로 작성하고 1회 승인 후 vibe.run으로 넘긴다.
 argument-hint: "(선택) feature name, requirement, file path, or idea"
 user-invocable: true
 ---
 
 # /vibe.spec
 
+## 완료 기준
+
+- [ ] `.vibe/specs/<feature>.md`가 존재한다.
+- [ ] 모든 REQ에 결정론적 Done Criteria와 Evidence Required가 있다.
+- [ ] 제약, 범위 제외, stakes가 명시되어 있다.
+- [ ] confirm mode에서는 사용자 승인 상태가 기록되어 있다.
+
 **SPEC 단계의 얇은 진입점.** 요구사항을 받아 `spec` 스킬(단일 패스)을 실행하고, SPEC 승인(유일한 의무 게이트) 후 `/vibe.run` 으로 넘긴다. interview → plan → spec → review 다단계 파이프라인은 폐지되었다 — 명확화 질문은 spec 패스 안에서 인라인으로, 리뷰는 셀프 리뷰 1회로 흡수됐다.
 
 ## Usage
@@ -50,10 +57,7 @@ SPEC 승인 (1회 — automationLevel: autonomous 면 생략)
 
 ### 레거시 아티팩트 호환 (구버전 .vibe/interviews/, .vibe/plans/)
 
-구버전 vibe 가 남긴 `.vibe/interviews/{feature}.md`, `.vibe/plans/{feature}.md` 가 존재할 수 있다:
-
-- **존재하면**: spec 패스의 **입력 컨텍스트**로 읽어 활용한다 (이미 답한 질문을 다시 묻지 않게).
-- **절대 요구하거나 재생성하지 않는다**: 이 파일들의 부재는 결함이 아니라 정상 상태다. interview/plan 스킬은 더 이상 존재하지 않는다.
+Legacy `.vibe/interviews/` or `.vibe/plans/` artifacts가 실제로 감지된 경우에만 `references/legacy-artifacts.md`를 읽는다. 신규 프로젝트와 현재 형식만 있는 호출은 읽지 않는다.
 
 ### `.last-feature` 포인터
 
@@ -95,7 +99,7 @@ ARGUMENTS: $ARGUMENTS
 | 입력 | 처리 |
 |---|---|
 | 자연어 요구사항 | 그대로 SPEC 패스의 주 입력 |
-| 📎 첨부 (md/txt/pdf/이미지 등) | Read 도구로 분석 후 요구사항에 병합 |
+| 📎 첨부 (md/txt/pdf/이미지 등) | 하네스의 파일 읽기 수단(CC `Read` 도구 / Codex 셸 등)으로 전체를 읽어 분석 후 요구사항에 병합 |
 | 파일 경로 인자 (PRD 등) | 존재 확인 후 Read — 첨부와 동일 취급 |
 | **레거시 아티팩트** `.vibe/interviews/{feature}.md`, `.vibe/plans/{feature}.md` | 존재하면 **입력 컨텍스트로만** 읽는다. 절대 요구하거나 재생성하지 않는다 — 없어도 정상 경로 |
 
@@ -109,11 +113,11 @@ ARGUMENTS: $ARGUMENTS
 ### 2. Project context
 
 - `.vibe/config.json` 읽기 — `references.languages[]` 의 스택 가이드, `stacks` 확인.
-- 기존 코드 파악이 필요하면 네이티브 Explore 서브에이전트에 위임 (main session 에서 프로젝트 파일을 훑지 않는다):
+- 기존 코드 파악이 필요하면 하네스의 네이티브 협업 기능에 독립 탐색 worker로 위임한다. Claude Code는 Task/Agent, Codex는 native collaboration에 매핑하며 기본 모델을 상속한다 (coordinator session에서 프로젝트 전체를 훑지 않는다):
 
 ```text
-Task(subagent_type="Explore",
-  prompt="Find existing implementations related to [FEATURE]. Return: tech stack, relevant files, patterns. Under 200 tokens.")
+Worker: Find existing implementations related to [FEATURE]. Return the tech stack,
+relevant files, and patterns in under 200 tokens.
 ```
 
 ### 3. Clarify — 진짜 모호할 때만

package/skills/vibe.spec/references/legacy-artifacts.md

@@ -0,0 +1,6 @@
+# Legacy SPEC Input Artifacts
+
+Load only when `.vibe/interviews/{feature}.md` or `.vibe/plans/{feature}.md` exists.
+
+- Read existing legacy artifacts as SPEC input context so answered questions are not repeated.
+- Never require or regenerate them. Their absence is normal; interview/plan skills no longer exist.

package/skills/vibe.test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vibe.test
-description: Self-test vibe — probe every entry skill/skill/hook/agent in the target harness install dir and write a pass/fail report
+description: Use when verifying that a vibe install is intact or that CC and Codex are in sync — before a release, after changing skills/hooks/agents, or when a harness behaves inconsistently. Probes every shipped surface in the target install dir and writes a pass/fail report with STCV skill-quality verdicts.
 argument-hint: "[cc|codex]  (empty = current harness)"
 user-invocable: true
 ---
@@ -37,13 +37,13 @@ Execute the bundled implementation below with target harness: `$ARGUMENTS`
 - If `$ARGUMENTS` is empty, detect the current harness (CC vs Codex) and use that.
 - If the target install dir is missing, exit cleanly with guidance (not an error).
 
-See `skills/vibe.test/SKILL.md` for the probe spec and the report template.
+Probe spec: below. Report schema: `references/report-template.md`.
 
 ## Done Criteria
 
 - [ ] Runs without any external LLM call — file reads + vitest only
 - [ ] A single probe failure never halts the overall run
-- [ ] JSON report matches the template in SKILL.md exactly
+- [ ] JSON report matches `references/report-template.md` exactly
 - [ ] P1 failures auto-register via `/vibe.regress`
 
 ---
@@ -87,81 +87,100 @@ All probes are **structural or test-based** — no interactive command is ever a
 | entry skills | `<install>/skills/vibe*/SKILL.md` | file readable · frontmatter parses · `name`, `description`, `user-invocable: true` present |
 | skills | `<install>/skills/*/SKILL.md` | frontmatter parses · required fields (`name`, `description`) · body non-empty |
 | hooks | repo `hooks/scripts/*.js` | for each script with a matching `__tests__/<name>.test.js`, run `npx vitest run <test> --reporter=json` and parse pass/fail counts |
-| agents | `<install>/agents/*.md` | file readable · frontmatter parses · required fields (`name`, `description`) |
+| agents | `<install>/agents/**/*.md` (**recursive**) | file readable · frontmatter parses · required fields (`name`, `description`) |
+| skill quality | `<install>/skills/*/SKILL.md` | STCV 4-axis quality check (below) |
 
 A probe's failure is captured in its `error` field; the overall run never halts because of one failure.
 
-## Report template
+**Agent discovery must recurse.** Agents live in subdirectories by capability group —
+`agents/ui/*.md` and `agents/event/*.md` are installed conditionally per stack/capability. A
+non-recursive `agents/*.md` glob silently skips 4 of the 11 shipped agents, so the report claims
+parity it never checked. Record each agent by its path-relative name (`ui/design-reviewer`, not
+`design-reviewer`) so group membership stays visible in the report.
+
+### Skill quality (STCV)
 
-Written to `~/.vibe/test-reports/<YYYYMMDD-HHmm>-<harness>.{json,md}`. Exact schema:
+Structural checks only — line counts, directory existence, and section/word presence. **No LLM call**, consistent with the rest of the probes.
 
-### JSON
+| Axis | Check | Verdict |
+|---|---|---|
+| **S**cope | SKILL.md line count | ≤250 `pass` · 251–400 `warn` · >400 `fail` |
+| **C**ontext | body fenced code blocks ≥3 **and** no sibling `references/` dir | `warn` |
+| **T**rigger | `description` contains no activation-condition wording | `warn` |
+| **V**erify | no `Done Criteria` / `완료 기준` section in body | `warn` |
+
+**WHY each axis** — a skill is loaded whole into context on invocation, so an oversized SKILL.md
+spends the caller's context on material most invocations never need (Scope), and material that
+*is* only needed sometimes belongs behind a reference pointer (Context). `description` is the
+only signal `/vibe` Catch-all routing sees, so a purely descriptive one cannot be matched against
+a request (Trigger). And a skill with no stated completion test cannot be judged by the
+deterministic JUDGE step in `vibe/rules/loop-contract.md` (Verify).
+
+Axis detail:
+
+- **Scope** — count lines of `SKILL.md` verbatim (frontmatter included). The `fail` threshold is
+  deliberately above the `warn` threshold so that a skill drifting past 250 gets flagged long
+  before it breaks the build.
+- **Context** — count ` ``` ` fence *pairs* in the body. Three or more blocks with no `references/`
+  sibling directory means templates/examples/schemas are inlined where they should be extracted.
+  A skill with a `references/` dir passes regardless of fence count.
+- **A `references/` dir is not by itself a pass.** The context axis asks whether *conditional bulk
+  still sits inline*, not whether the directory exists — a 6-line reference file next to a 150-line
+  body clears the directory check while saving nothing. Judge the body: does it still inline a
+  block that most invocations skip? If yes, the axis warns regardless of the sibling directory.
+- **Safety and correctness rules never move behind a conditional load.** "Read
+  `references/protected-branches.md` if the branch is protected" is circular — deciding whether the
+  rule applies requires already knowing the rule. Anything the skill must obey *before* it can
+  classify the situation (destructive-operation guards, push/force-push prohibitions, data-loss
+  boundaries) stays inline. Only material that is *looked up after* the situation is known is
+  eligible.
+- **Anti-gaming (scope + context)** — a reference only saves context if it is **conditionally**
+  loaded. If the body instructs reading a reference unconditionally ("read `references/x.md`" with
+  no condition attached), nothing was saved: the invocation now costs body + reference *plus* an
+  extra round trip. Emit `scope: warn` with `"unconditional reference load"` when a skill's body is
+  small but a reference it always loads is large — regardless of the line count passing. **A stub
+  that forwards to a wholesale copy of its own former body is a regression, not a split.** The test
+  for a real split: name a plausible invocation that never needs the reference. If none exists, the
+  material belongs inline.
+- **Trigger** — the `description` must contain at least one activation-condition marker:
+  `when` / `if` / `use for` / `use when` / `…할 때` / `…하면` / `…인 경우` / `…이 있고`.
+  A bare capability restatement (`"Execute implementation from SPEC"`) has none and warns.
+- **Verify** — case-insensitive search for a heading containing `Done Criteria` or `완료 기준`.
+
+**Alias exemption**: a merged skill leaves behind a thin alias — a body of ≤20 lines whose only
+content is a pointer at the canonical skill. Aliases are exempt from the **context** and **verify**
+axes: they hold no templates to extract and no work to complete, so demanding `references/` or a
+`Done Criteria` section would only pad them back into the duplication the merge removed. **Scope and
+trigger still apply** — an alias must stay small and must still say when it fires. Mark exempt axes
+`"n/a"` in the `quality` object rather than `"pass"`, so the report never claims a check it skipped.
+
+**Severity policy**: only `scope` can produce `fail`. The other three axes emit `warn` in this
+release — `verify` in particular currently applies to 17 of the 22 entry skills, and promoting it
+to `fail` before that backlog clears would ship a self-test that fails on vibe's own package and
+flood `/vibe.regress` with P1s. Promote `verify` to `fail` for entry skills in a later release
+once those skills carry Done Criteria.
+
+Quality findings attach to the existing skill entry rather than creating a second entry per skill:
 
 ```json
-{
-  "harness": "cc",
-  "timestamp": "2026-04-16T18:30:00+09:00",
-  "vibe_version": "2.9.24",
-  "install_dir": "/Users/grove/.claude",
-  "summary": {
-    "total": 42,
-    "passed": 40,
-    "failed": 2
-  },
-  "probes": {
-    "entrySkills": [
-      { "name": "vibe.spec", "status": "pass" },
-      { "name": "vibe.test", "status": "pass" }
-    ],
-    "skills": [
-      { "name": "test", "status": "pass" },
-      { "name": "spec", "status": "fail", "error": "invocation includes `auto` but triggers array is empty" }
-    ],
-    "hooks": [
-      { "name": "pre-tool-guard", "status": "pass", "tests": "38/38" },
-      { "name": "scope-guard", "status": "pass", "tests": "12/12" }
-    ],
-    "agents": [
-      { "name": "implementer", "status": "pass" }
-    ]
-  },
-  "failed": [
-    {
-      "category": "skills",
-      "name": "spec",
-      "error": "frontmatter: triggers array is empty"
-    }
-  ]
-}
+{ "name": "vibe.run", "status": "fail",
+  "quality": { "scope": "fail", "context": "warn", "trigger": "warn", "verify": "warn" },
+  "error": "scope: 845 lines (>400)" }
 ```
 
-- `status`: `"pass"` | `"fail"`
-- `error`: required when `status === "fail"`, omitted otherwise
-- `tests` (hooks only): short `passed/total` string from the vitest JSON reporter
-- `failed[]`: flat list of every failure for quick scanning — mirrors entries found across `probes.*`
-
-### Markdown
+A skill's `status` is the worst verdict across its structural check and all four axes
+(`fail` > `warn` > `pass`).
 
-```markdown
-# vibe self-test · cc · 2026-04-16 18:30
-
-**Version**: 2.9.24   **Install**: /Users/grove/.claude
-
-| Category | Pass | Fail |
-|---|---:|---:|
-| entry skills | 15 | 0 |
-| skills   | 17 | 1 |
-| hooks    |  6 | 0 |
-| agents   |  3 | 1 |
-| **total**| **41** | **2** |
+## Report template
 
-## Failures
+JSON 스키마와 Markdown 출력 포맷의 전문(필드·타입·명명·Warnings/STCV 섹션):
+`references/report-template.md`
 
-- **skills / spec** — invocation includes `auto` but triggers array is empty
-- **agents / implementer** — agent file not found
-```
+핵심 계약만 요약:
 
-If `failed` is empty, replace the Failures section with `_All probes passed._`.
+- `status`: `"pass"` | `"warn"` | `"fail"` — 구조 검사와 STCV 4축 중 **최악** 판정
+- `quality` (skills 만): `{ scope, context, trigger, verify }`, 각 `pass`/`warn`/`fail`/`n/a`
+- `failed[]` 는 `fail` 만, `warned[]` 는 `warn` 만. **`warned[]` 는 절대 `vibe.regress` 로 넘기지 않는다**
 
 ## Steps
 
@@ -169,11 +188,12 @@ If `failed` is empty, replace the Failures section with `_All probes passed._`.
 2. **Resolve install dir**: `cc` → `~/.claude`, `codex` → `~/.codex`. If missing → print guidance + exit.
 3. **Read `vibe_version`** from `package.json` in the current repo.
 4. **Walk each category**, run its check, append `{ name, status, error? }` to `probes.<category>`.
-5. **Compute** `summary` counts and the flat `failed[]` list.
-6. **Ensure** `~/.vibe/test-reports/` exists (`mkdir -p`, dir mode `0o700` — consistent with `~/.vibe/config.json`).
-7. **Write** `<ts>-<harness>.json` and `<ts>-<harness>.md`.
-8. **Print** the Markdown summary to the console.
-9. **If `summary.failed > 0`**, load skill `vibe.regress` with `subcommand: register --from-test` and pass the failed entries. P1 = any probe with `status: fail`.
+5. **Run the STCV check** on every `skills` entry, attach `quality`, and fold the worst axis verdict into that entry's `status`.
+6. **Compute** `summary` counts and the flat `failed[]` / `warned[]` lists.
+7. **Ensure** `~/.vibe/test-reports/` exists (`mkdir -p`, dir mode `0o700` — consistent with `~/.vibe/config.json`).
+8. **Write** `<ts>-<harness>.json` and `<ts>-<harness>.md`.
+9. **Print** the Markdown summary to the console.
+10. **If `summary.failed > 0`**, load skill `vibe.regress` with `subcommand: register --from-test` and pass the failed entries. P1 = any probe with `status: fail`. **`warned[]` is never passed to regress** — warnings are advisory and must not create P1 backlog.
 
 ## Done Criteria
 
@@ -184,4 +204,7 @@ If `failed` is empty, replace the Failures section with `_All probes passed._`.
 - [ ] Markdown summary printed to console after the run
 - [ ] Reports land in `~/.vibe/test-reports/`, never in project-local `.vibe/`
 - [ ] `failed.length > 0` → auto-invokes `vibe.regress register --from-test`
+- [ ] `warned.length > 0` alone never invokes `vibe.regress`
+- [ ] Every `skills` entry carries a `quality` object with all four STCV axes
+- [ ] Agent discovery recurses — `agents/ui/*` and `agents/event/*` appear in the report under their group-qualified names
 - [ ] Entry skills are verified as user-invocable skill surfaces, not deprecated command files