@uzysjung/agent-harness 26.111.1 → 26.113.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uzysjung/agent-harness",
-  "version": "26.111.1",
+  "version": "26.113.0",
   "description": "Curate vetted AI-coding skills & plugins by your tech stack — install only what you need, across Claude Code, Codex, OpenCode & Antigravity",
   "type": "module",
   "publishConfig": {

package/templates/skills/model-orchestration/SKILL.md

@@ -164,6 +164,19 @@ it. How that plays out per lane:
 This pairs with, not replaces, deterministic gates (tests, typecheck, CI) — the verifier
 judges what automation can't: spec fit, missed edge cases, design drift.
 
+**Verdict vocabulary (fixed).** A verifier's report never ends in free prose — it ends with
+exactly one verdict, `PASS` / `PASS_WITH_NITS` / `FAIL`, and every finding carries one
+severity label, `CRITICAL` / `HIGH` / `MEDIUM` / `LOW` (full contract: the verification-loop
+skill's Verdict Contract). Two consequences for orchestration:
+
+- **FAIL closes only on re-verification.** Fix → re-verify is one cycle; if the same
+  reviewer will re-verify, keep it alive via SendMessage and *declare* that intent
+  (worker lifecycle) — otherwise spawn a fresh verifier.
+- **PASS_WITH_NITS is not silent PASS.** Its LOW/MEDIUM findings come back to the
+  orchestrator as recorded follow-ups, not as buried prose — deciding their fate is an
+  orchestrator judgment call, never the verifier's. (The name says nits, but the tier it
+  covers is LOW **and** MEDIUM.)
+
 ## Orchestrator handoff (quota exhaustion)
 
 When the top-tier orchestrator's quota runs out mid-project, **Opus @ `max` takes over
@@ -203,6 +216,7 @@ build on. Hand off manually:
                                → 오케스트레이터(Fable) 직접
 기획·스펙·계획 문서 작성·관리 / 핵심 구현 / V&V
                                → opus  @ xhigh (또는 max)   — pinned role 또는 Workflow opts
+V&V 판정                       → PASS | PASS_WITH_NITS | FAIL + CRITICAL~LOW (verification-loop 계약)
 반복 구현 / E2E 테스트 / 리서치 스윕
                                → sonnet @ high 이상
 결정적 변환 (rename·포맷)      → 모델 위임 금지 — sed/grep/스크립트 직접

package/templates/skills/north-star/NORTH_STAR.template.md

@@ -15,6 +15,10 @@
 
 ## 2. North Star Metric (NSM)
 
+> [진짜 목표가 직접 측정 불가하면 여기서 프록시를 선언: "진짜 목표 X 는 (외부적/지연이라)
+> 직접 측정 불가하므로, Y(양) + Z(사후 품질)를 프록시로 최적화한다. 근거: …" — 기능은
+> "이 프록시를 올리는가"로 평가한다.]
+
 **1차 지표 (현재 단계)**: **[지표 약어 — 풀네임]**
 - 정의: [어떻게 계산하는가]
 - 목표: [수치 + 도달 시점]
@@ -32,16 +36,45 @@
 
 ---
 
-## 3. Strategic Boundaries (방향성 경계)
+## 3. Pillars (전략 축)
+
+각 축은 North Star 로 가는 단계이며, 모든 모듈은 최소 1개 축에 속한다.
+
+### Pillar 1 — [이름]
+- **정의**: [이 축이 사용자에게 주는 것 1문장]
+- **현재 위치**: [이 축에 속한 기존 모듈/기능]
+- **전방 목표**: [다음에 쌓을 것]
+- **가설**: [이 축이 NSM 을 올린다고 믿는 이유 1줄]
+
+### Pillar 2 — [이름]
+- **정의** / **현재 위치** / **전방 목표** / **가설**: [동일 4요소]
 
-### 3.1 Will (집중)
+### Pillar 3 — [이름]
+- **정의** / **현재 위치** / **전방 목표** / **가설**: [동일 4요소]
+
+### 모듈 ↔ 축 매핑
+
+| 모듈 | 주 축 | 비고 |
+|---|---|---|
+| [모듈 A] | P1 | |
+| [모듈 B] | P2 / P3 | [복수 축이면 병기] |
+| [공통 인프라 — 인증·관리 등] | 공통 | 축을 가로지르는 플랫폼 |
+
+> 어떤 신규 모듈이 위 축 어디에도 매핑되지 않으면, **착수 전에 북극성 정렬을 재검토**한다.
+> 로드맵 항목도 정기 리뷰 때 축에 매핑해 "새 축·방향 변경 필요 여부"를 판정·기록한다.
+
+---
+
+## 4. Strategic Boundaries (방향성 경계)
+
+### 4.1 Will (집중)
 
 - **[집중 영역 1]**: [짧은 설명]
 - **[집중 영역 2]**: [짧은 설명]
 - **[집중 영역 3]**: [짧은 설명]
 - **[집중 영역 4]**: [짧은 설명]
 
-### 3.2 Won't (의도적 비-방향)
+### 4.2 Won't (의도적 비-방향)
 
 scope creep의 1차 방어선. "X는 안 한다"를 명시.
 
@@ -51,7 +84,7 @@ scope creep의 1차 방어선. "X는 안 한다"를 명시.
 - **[안 하는 것 4]**: [근거]
 - **[안 하는 것 5]**: [근거]
 
-### 3.3 Trade-offs (의식적 선택)
+### 4.3 Trade-offs (의식적 선택)
 
 | 선택 | 포기한 것 | 근거 |
 |------|----------|------|
@@ -61,7 +94,7 @@ scope creep의 1차 방어선. "X는 안 한다"를 명시.
 
 ---
 
-## 4. Phase Roadmap (장기 진화 단계)
+## 5. Phase Roadmap (장기 진화 단계)
 
 ### Phase 1 — [이름] (현재)
 - 목표: [한 문장]
@@ -84,7 +117,9 @@ scope creep의 1차 방어선. "X는 안 한다"를 명시.
 
 ---
 
-## 5. Decision Heuristics (의사결정 휴리스틱)
+## 6. Decision Heuristics (의사결정 휴리스틱)
+
+### 6.1 4-Gate — "할 것인가"
 
 신규 요청·제안이 들어왔을 때 다음 4 게이트를 **모두** 통과해야 우선순위 진입.
 
@@ -97,9 +132,18 @@ scope creep의 1차 방어선. "X는 안 한다"를 명시.
 
 4개 모두 Pass = 우선순위 진입. 1개라도 Fail = 보류 또는 거절.
 
+### 6.2 우선순위 순서 — "언제 할 것인가"
+
+무엇을 먼저 할지 모호하면 이 순서로 판정한다. **상위 순위에 미완이 있으면 하위로 건너뛰지
+않는다** (긴급 hotfix·사용자 명시 지시 예외).
+
+1. **기본 필수 기능** — 없으면 제품이 성립 안 되는 기본기.
+2. **기능 완성도** — shipped 기능이 사용자 관점 end-to-end 완결인가. 단순 존재 ≠ 완결.
+3. **차별화 깊이** — 핵심 경쟁력의 advanced 구현. research/ADR 선행 필수.
+
 ---
 
-## 6. Versioning & Review
+## 7. Versioning & Review
 
 - 본 문서는 **분기 1회** 또는 **NSM 도달/미달** 시 갱신.
 - 주요 갱신 (Major CR): NSM 변경 / Phase 정의 변경 / Won't 변경.
@@ -108,7 +152,7 @@ scope creep의 1차 방어선. "X는 안 한다"를 명시.
 
 ---
 
-## 7. Changelog
+## 8. Changelog
 
 - YYYY-MM-DD: 초안 작성. 참조: [관련 ideation/raw 문서].
 - (이후 갱신 기록)

package/templates/skills/north-star/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: north-star
-description: "Defines and enforces a project's long-term direction (North Star Statement, NSM, Will/Won't, 4-gate decision heuristic). Use when starting a new project, when scope creep is suspected, or when a non-obvious feature request needs prioritization. Sits one layer above SPEC/PRD — answers 'why and where to', not 'what and how'."
+description: "Defines and enforces a project's long-term direction (North Star Statement, metric-as-proxy NSM, strategic Pillars with a module↔pillar map, Will/Won't, 4-gate + priority-order decision heuristics). Use when starting a new project, when scope creep is suspected, or when a non-obvious feature request needs prioritization. Sits one layer above SPEC/PRD — answers 'why and where to', not 'what and how'."
 ---
 
 # North Star
@@ -32,22 +32,49 @@ CLAUDE.md의 P1(가정 금지) / P2(Simplicity First) / Decision Making 메타
 **좋은 예**: 도메인 명사 + 사용자 + 측정 가능한 결과.
 **나쁜 예**: "최고의 X" / "사용자 만족" — 측정 불가.
 
-### 2. North Star Metric (NSM) 정의
+### 2. North Star Metric (NSM) 정의 — metric-as-proxy
 
 1차 지표 1개 + 2차 보조 지표 2-4개. 모두 단일 사용자 환경에서 자가 수집 가능해야 한다.
 
+**진짜 목표가 직접 측정 불가하면 프록시를 선언한다.** 많은 프로젝트의 실제 목표(사용자의
+투자 수익, 팀의 생산성, 학습 성과 등)는 외부적이거나 지연되어 직접 측정할 수 없다. 그때
+"측정 불가"로 방치하지 말고:
+
+1. **프록시 지표를 명시적으로 선언** — "진짜 목표 X 는 직접 측정 불가하므로 Y 를 프록시로
+   최적화한다"를 문서에 그대로 적는다. 왜 이 프록시인지 1줄 근거 필수.
+2. **양(1차) + 사후 품질(2차) 짝** — 프록시는 행동의 양(추적되는 의사결정 수 등)과 그 행동의
+   사후 품질(성과 추적이 양(+)인 비율 등)을 짝으로 잡는다. 양만 재면 굿하트 법칙으로 프록시
+   자체가 게임된다.
+3. **기능 평가 기준으로 사용** — "이 기능이 프록시 지표 둘 중 하나를 올리는가?" NO 면 북극성
+   이탈 신호.
+
 NSM 결정 기준:
 - Lagging (결과) vs Leading (원인) — Leading 권장
 - 단일 행동만 측정 (composite 금지)
 - 목표값 명시 ("≥ 40% by 2026")
 
-### 3. Will / Won't / Trade-offs
+### 3. Pillars (전략 축) + 모듈 ↔ 축 매핑
+
+North Star 로 가는 길을 3-5개 **전략 축**으로 분해한다. 각 축은 4요소로 정의:
+
+- **정의** — 이 축이 사용자에게 주는 것 1문장.
+- **현재 위치** — 이 축에 속한 기존 모듈/기능.
+- **전방 목표** — 다음에 쌓을 것.
+- **가설** — 이 축이 NSM 을 올린다고 믿는 이유 1줄.
+
+그리고 **모듈 ↔ 축 매핑 표**를 유지한다: 모든 모듈은 최소 1개 축에 속한다 (플랫폼 공통
+인프라는 "공통"으로 명시). **어떤 신규 모듈이 어느 축에도 매핑되지 않으면 착수 전에 북극성
+정렬을 재검토한다** — 매핑 실패 = scope creep 의 조기 신호. 로드맵 항목도 정기 리뷰 때 축에
+매핑해 "새 축·방향 변경이 필요한가"를 점검한다. (Pillars = northstar-roadmap 스킬이 말하는
+*Inputs* 와 동일 개념 — 두 스킬은 같은 축 분해를 서로 다른 이름으로 가리킨다.)
+
+### 4. Will / Won't / Trade-offs
 
 - **Will**: 집중 영역 4-6개. 동사로 시작 ("개인 사용 깊이 우선", "AI 친화 1급 시민").
 - **Won't**: 의도적 비-방향 5-8개. "X는 안 한다" 명시. 가장 중요한 섹션 — scope creep의 1차 방어선.
 - **Trade-offs**: "X 선택 → Y 포기 → 근거" 표. 의식적 결정의 추적 기록.
 
-### 4. 4-Gate Decision Heuristic
+### 5. 4-Gate Decision Heuristic — "할 것인가"
 
 신규 요청·제안이 들어왔을 때 다음 4개 게이트를 **모두** 통과해야 우선순위 진입:
 
@@ -60,7 +87,24 @@ NSM 결정 기준:
 
 게이트 명칭은 프로젝트마다 customize 가능하나 **4개 ALL True** 원칙은 유지.
 
-### 5. Versioning
+### 6. 우선순위 순서 게이트 — "언제 할 것인가"
+
+(gates-taxonomy 룰의 검증 체크포인트 4유형과 무관 — 이것은 작업 **순서** 규칙이다.)
+4-gate 는 "할 것인가"를 거른다. 통과한 것들 사이의 **순서**는 별도 규칙이다 — 무엇을 먼저
+할지 모호하면 이 순서로 판정한다:
+
+1. **기본 필수 기능** — 없으면 제품이 성립 안 되는 기본기 (예: 표준 로그인). "기본"이 빠진 채
+   화려함부터 쌓지 않는다.
+2. **기능 완성도** — 이미 shipped 된 기능이 사용자 관점 end-to-end 로 진짜 완결인가.
+   **단순 존재 ≠ 완결** (버튼이 동작하나, 링크가 목적지까지 가나, 빈/에러 상태가 처리되나).
+   UI 트랙 설치 시 benchmark-parity 룰의 "완결성 검토" 루프와 동일 기준.
+3. **차별화 깊이** — 핵심 경쟁력의 advanced 구현. **research/ADR 선행 필수** — advanced 부터
+   코드로 뛰어들지 않는다.
+
+**상위 순위에 미완이 있으면 하위로 건너뛰지 않는다** (긴급 hotfix·사용자 명시 지시 예외).
+Plan/Define 단계에서 "이 작업이 ①/②/③ 중 어디이고, 앞 순위가 남아있지 않나"를 먼저 점검.
+
+### 7. Versioning
 
 - 분기 1회 또는 NSM 도달/미달 시 갱신.
 - 주요 갱신: NSM 변경 / Phase 정의 변경 / Won't 변경 → Major CR 분류.
@@ -71,14 +115,15 @@ NSM 결정 기준:
 
 `docs/NORTH_STAR.md`에 다음 구조로 저장. 본 skill 디렉토리의 `NORTH_STAR.template.md`를 복사해 채운다.
 
-7 섹션:
+8 섹션:
 1. North Star Statement (1문장)
-2. North Star Metric (1차 + 2차)
-3. Strategic Boundaries (Will / Won't / Trade-offs)
-4. Phase Roadmap (장기 진화 단계)
-5. Decision Heuristics (4-gate)
-6. Versioning & Review
-7. Changelog
+2. North Star Metric (1차 + 2차, metric-as-proxy 선언)
+3. Pillars (전략 축) + 모듈 ↔ 축 매핑
+4. Strategic Boundaries (Will / Won't / Trade-offs)
+5. Phase Roadmap (장기 진화 단계)
+6. Decision Heuristics (4-gate + 우선순위 순서)
+7. Versioning & Review
+8. Changelog
 
 ## Integration with Workflow
 
@@ -89,15 +134,24 @@ NSM 결정 기준:
 ## Anti-Patterns
 
 - **NSM이 vanity metric** ("downloads", "stars") — 사용자 행동 측정 X
+- **측정 불가 목표를 프록시 선언 없이 방치** — "좋은 제품"류 목표만 있고 최적화 대상이 없음
+- **프록시가 양(量)만 측정** — 사후 품질 짝 없이는 굿하트 법칙으로 지표 자체가 게임됨
+- **축에 매핑되지 않는 모듈 방치** — 매핑 실패는 scope creep 의 조기 신호인데 무시
+- **기본 미완인데 advanced 착수** — 우선순위 순서 게이트 위반 (기본→완성도→차별화)
 - **Won't가 비어있음** — scope creep 방어선 부재
 - **4-gate 검증 없이 "유용해 보이니까" 추가** — Decision Making 메타원칙 위반
 - **NORTH_STAR.md를 작성만 하고 한 번도 참조 안 함** — 죽은 문서. 분기 리뷰로 살림
 
 ## Examples
 
-GoalTrack 프로젝트의 NORTH_STAR.md (참고 사례, 도메인 종속):
-- NSM: WAGI (Weekly AI-Initiated Goal Items) ≥ 40%
-- Won't: 팀 협업 도구 / 모바일 우선 / 게이미피케이션 / 외부 통합 폭발 / CRDT
-- 4-gate: Trend × Persona × MCP × Lean
+참고 사례 (도메인 종속 — 실운영 프로젝트 2종):
+
+- 프로젝트 A (목표 추적 SaaS): NSM = WAGI (Weekly AI-Initiated Goal Items) ≥ 40% ·
+  Won't: 팀 협업 도구 / 모바일 우선 / 게이미피케이션 / 외부 통합 폭발 / CRDT ·
+  4-gate: Trend × Persona × MCP × Lean · 우선순위 순서(기본→완성도→차별화) 실운영.
+- 프로젝트 B (투자 분석 서비스): 진짜 목표(사용자 투자 수익)가 외부·지연이라 직접 측정 불가 →
+  **프록시 선언** "추적되는 근거 기반 의사결정 수(양) + 사후 성과 양(+) 비율(품질)" ·
+  5 Pillars(각 정의/현재 위치/전방 목표/가설) + 전 모듈 ↔ 축 매핑 표 · 로드맵 항목의 축 매핑
+  정기 점검("새 축 불필요" 판정 기록).
 
-본 skill은 그 패턴을 도메인 비종속으로 일반화한 것.
+본 skill은 그 패턴들을 도메인 비종속으로 일반화한 것.

package/templates/skills/verification-loop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verification-loop
-description: "A comprehensive verification system for Claude Code sessions."
+description: "A comprehensive verification system for Claude Code sessions. Every run ends with a fixed verdict — PASS / PASS_WITH_NITS / FAIL — plus severity-labeled findings (CRITICAL/HIGH/MEDIUM/LOW)."
 origin: ECC
 ---
 
@@ -26,7 +26,9 @@ npm run build 2>&1 | tail -20
 pnpm build 2>&1 | tail -20
 ```
 
-If build fails, STOP and fix before continuing.
+If build fails, STOP and fix — then re-verify from Phase 1 in a fresh instance. Continuing
+through the remaining phases yourself would make you the verifier of code you just wrote,
+which the Verdict Contract below forbids.
 
 ### Phase 2: Type Check
 ```bash
@@ -100,13 +102,43 @@ Tests:     [PASS/FAIL] (X/Y passed, Z% coverage)
 Security:  [PASS/FAIL] (X issues)
 Diff:      [X files changed]
 
-Overall:   [READY/NOT READY] for PR
+Verdict:   PASS | PASS_WITH_NITS | FAIL
 
-Issues to Fix:
-1. ...
-2. ...
+Findings:
+| ID | Severity | Finding | Evidence (file:line / command output) |
+|----|----------|---------|---------------------------------------|
+| F1 | HIGH     | ...     | ...                                   |
 ```
 
+## Verdict Contract
+
+The report ends with exactly one verdict. Free-prose closings ("looks ready", "should be
+fine") are banned — they leave room to bury defects. A fixed vocabulary makes the report
+honest and machine-checkable.
+
+| Verdict | Meaning | Action |
+|---------|---------|--------|
+| **PASS** | All gates green, zero findings at any severity | Ship |
+| **PASS_WITH_NITS** | Ship-safe: only LOW/MEDIUM findings, each recorded with a follow-up | Ship + log follow-ups |
+| **FAIL** | Any gate red, or one or more CRITICAL/HIGH findings | Block → fix → **re-verify** |
+
+Every finding gets exactly one severity:
+
+- **CRITICAL** — data loss, security hole, or the change misbehaves in real use if shipped
+- **HIGH** — main-path defect or regression; users will hit it
+- **MEDIUM** — edge-case or quality defect; unlikely to block real use
+- **LOW** — nit: style, naming, doc wording
+
+Rules:
+- Severity is judged by impact evidence, not by how easy the fix is.
+- FAIL → fix → re-verify is one cycle. A fix alone never upgrades the verdict — the
+  re-verification must reproduce green.
+- A run that aborts early (Phase 1 build failure) still emits a report: verdict **FAIL**
+  with the failing gate as a CRITICAL finding. Stopping to fix is how you *reach* the next
+  verdict, not a reason to skip issuing this one — an unreported run reads as "not run".
+- The instance that wrote the change never issues its own verdict: verification runs in a
+  fresh instance (see the model-orchestration skill's V&V separation).
+
 ## Continuous Mode
 
 For long sessions, run verification every 15 minutes or after major changes: