elanous 0.2.0 → 0.2.4

package/skills/omni-digest/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: omni-digest
+description: >
+  통합 콘텐츠 요약 스킬. 비-YouTube URL의 X(Twitter) 포스트/아티클, 웹페이지,
+  GitHub(레포/PR/이슈/커밋), PDF/DOCX/이미지 등 모든 소스를 하나의
+  엔트리포인트로 요약. 요약 형식은 essential(간략)/rich-cards(카드형)/rich(심층).
+  출력 타겟은 obsidian, markdown, web, pdf (복수 선택 가능).
+  X API/OCR/다이어그램 내장. X 포스트는 note_tweet(장문) 전문과 첨부 영상 STT 전사까지
+  자동 수집해 요약 근거로 삼는다. YouTube만 youtube-master에 위임.
+  "sum" 키워드 시 summarize CLI(steipete/summarize)를 콘텐츠 추출 우선 엔진으로 사용.
+  "enrich/풍부하게" 시 omni-crawl로 컨텍스트 보강. 원문 crawl/extract 요청은 omni-crawl 전용.
+  Use when the user provides a non-YouTube URL or file and asks for:
+  요약, 정리, 저장, 분석, digest, summarize, sum, enrich, 풍부, cc웹, ccv웹, pdf, obsidian.
+  A YouTube URL belongs to youtube-master unless the user explicitly requests absorb,
+  channel, or subscription work, which belongs to yt-vault.
+minTier: T2
+composes: [youtube-master, omni-crawl, diagram-master]
+category: digest
+# 오픈코어 경계(scripts/skill-boundary.ts) — requires = 없으면 이 스킬이 일을 못 하는 catalog/resources.yaml 자원 id
+# 요약기 = Grok(XAI_API_KEY 필수 · src/summarize.ts requireEnv). X 수집 BEARER_TOKEN·S3·OCR 은 선택(없으면 그 갈래만 빠진다).
+requires: [xai]
+boundary: core
+boundary_reason: 대표 2026-09-27 «omni-digest 는 배포판 필수» — 요약에 LLM 이 필요한 것은 제품 전제(elanous 는 LLM 자격 없이 일을 못 한다 · xai 행 boundary_note «THE FLOOR»). 후속 = 요약기를 Grok 고정에서 elanous 공급자 체인으로
+---
+
+# OmniDigest
+
+**모든 콘텐츠** → 자동 감지 → 요약 → 다중 타겟 출력 + 다이어그램.
+
+## 트리거
+
+URL (X, YouTube, 웹, GitHub) 또는 파일 (PDF, DOCX, 이미지) + 요약/정리/분석 의도.
+
+## 소스 자동 감지
+
+| 소스 | 패턴 | 처리 |
+|------|------|------|
+| **X 포스트** | `x.com/*/status/*` | X API v2 직접 (내장) + 장문 전문 + 영상 STT |
+| **X 아티클** | `x.com/*/article/*` | Jina Reader (내장) |
+| **YouTube** | `youtube.com`, `youtu.be` | → youtube-master 위임 |
+| **웹페이지** | `https://...` | firecrawl CLI (기본) → summarize CLI 폴백 → Jina Reader 폴백 |
+| **웹 (sum 모드)** | `https://...` + "sum" | summarize CLI (우선) → firecrawl 폴백 → Jina Reader 폴백 |
+| **GitHub** | `github.com/...` | gh CLI |
+| **로컬 파일** | `.pdf`, `.docx`, `.txt`, `.md` | 텍스트 추출 |
+| **이미지** | `.png`, `.jpg` 등 | Upstage OCR / OCR.space |
+
+## 요약 형식 (Format)
+
+| 형식 | 트리거 |
+|------|--------|
+| **essential** | 간단히, 짧게, brief |
+| **rich-cards** (기본) | (기본), 카드 |
+| **rich** | 상세, 깊게, 분석 |
+
+## 출력 타겟 (복수 선택)
+
+| 타겟 | 트리거 |
+|------|--------|
+| **obsidian** (기본) | 저장 |
+| **markdown** | md로 |
+| **web** | cc웹 |
+| **web-deploy** | ccv웹 |
+| **pdf** | pdf |
+
+### 전달은 호출 서피스가 범용 처리
+
+이 스킬은 요약 결과(마크다운 + Obsidian 저장 경로)만 산출한다. 특정 봇/채널로의 전송은 스킬이 하드코딩하지 않는다 —
+**호출한 서피스(elanous 세션 sink·Claude Code 등)가 자기 채널에 맞게 렌더·전달**한다. 별도 전달 스크립트나 특정 봇에 결합하지 않는다(범용화).
+
+## 실행
+
+```bash
+npx tsx ~/.claude/skills/omni-digest/scripts/main.ts "<INPUT>" --message "<의도>" --print
+```
+
+### 예시
+
+```bash
+# X 포스트 카드형 요약
+npx tsx scripts/main.ts "https://x.com/user/status/123" --print
+
+# 웹 아티클 상세 + 다이어그램
+npx tsx scripts/main.ts "https://example.com" --format rich --diagram --print
+
+# GitHub PR + Obsidian + 웹 동시
+npx tsx scripts/main.ts "https://github.com/o/r/pull/42" --target obsidian,web --print
+
+# PDF OCR + 요약
+npx tsx scripts/main.ts "/path/to/scan.pdf" --print
+
+# 이미지 OCR + 요약
+npx tsx scripts/main.ts "photo.png" --print
+```
+
+## 옵션
+
+| 옵션 | 설명 |
+|------|------|
+| `--message, -m` | 의도 (자동 라우팅) |
+| `--format` | essential, rich-cards, rich |
+| `--target` | 쉼표 구분: obsidian, markdown, web, web-deploy, pdf |
+| `--diagram` | Mermaid 다이어그램 포함 |
+| `--content` | 사전 추출 텍스트 (Claude 파이핑) |
+| `--print` | stdout 출력 |
+| `--dry-run` | 라우팅만 확인 |
+| `--no-obsidian` | Obsidian 생략 |
+| `--output-dir` | 저장 경로 오버라이드 |
+| `--self-test` | 테스트 |
+
+## 환경변수
+
+`.env` 하나로 관리. youtube-master/grok `.env` 자동 상속.
+
+필수: `XAI_API_KEY`, `BEARER_TOKEN` (X용)
+선택: `OBSIDIAN_VAULT_ROOT`, `UPSTAGE_API_KEY`, `OCR_API_KEY`, `AWS_S3_BUCKET`(X 첨부 이미지·영상 프레임 «시각 흡수» — 공개 읽기 버킷 ⊕ `aws` CLI 자격 · 없으면 그 갈래만 건너뛴다 · 기본값 없음)
+
+## 흡수한 기능
+
+### X API (x-to-obsidian 흡수)
+- X API v2로 트윗 메타/댓글/링크 직접 수집
+- **note_tweet 전문 확보**: 280자를 넘는 장문 트윗은 `tweet.text`가 잘려서 온다.
+  `tweet.fields=note_tweet`를 함께 요청해 전문을 쓰고, `meta.isLongform`으로 표시한다.
+  (이 필드를 안 넣으면 장문 포스트의 절반 이상이 요약에서 통째로 누락된다)
+- X 아티클은 Jina Reader로 본문 스크래핑
+- X 전용 프롬프트 (포스트/아티클 × essential/rich-cards/rich)
+
+### 첨부 영상 STT (`src/media.ts`)
+
+X 포스트에 영상이 있으면 **자동으로 다운로드 → 오디오 추출 → 전사**해 요약의 1차 자료로 넣는다.
+발표·데모·피치 영상은 본문 텍스트보다 정보량이 많은 경우가 많아, 이걸 빼면 요약이 껍데기가 된다.
+
+```
+X API media.variants → 최저 비트레이트 MP4 → ffmpeg 오디오 추출 → STT → 프롬프트 주입
+                                                                    └→ Obsidian "# 영상 전사" 부록
+```
+
+| 항목 | 내용 |
+|------|------|
+| 다운로드 | `media.variants`의 MP4 직링크 (yt-dlp 불필요, curl로 충분) |
+| **화질 선택** | **최저 비트레이트 변형**. 전사는 오디오만 쓰는데 4K를 받으면 66초짜리가 200MB를 넘는다 |
+| STT 1순위 | 로컬 `whisper` CLI (무료·오프라인) |
+| STT 2순위 | youtube-master `scripts/transcribe-local.ts` (ElevenLabs → OpenAI → Gemini 체인) |
+| 실패 시 | 전사 생략하고 **텍스트만으로 요약 계속** (파이프라인 중단 없음) |
+
+**옵션**
+
+| 플래그 | 설명 |
+|--------|------|
+| `--no-media` | 영상 전사 비활성 (기본은 영상 있으면 자동 전사) |
+| `--media-lang <code>` | 전사 언어. 기본 `en`, 한국어 영상은 `ko` |
+
+**환경변수**
+
+| 변수 | 기본값 | 용도 |
+|------|--------|------|
+| `OMNI_DIGEST_MEDIA_MAX_MS` | `1200000` (20분) | 이보다 긴 영상은 전사 생략 |
+| `OMNI_DIGEST_WHISPER_MODEL` | `small` | 로컬 whisper 모델 |
+| `OMNI_DIGEST_STT_LANG` | `en` | 기본 전사 언어 |
+| `YOUTUBE_MASTER_ROOT` | `~/.claude/skills/youtube-master` | 폴백 STT 스킬 경로 |
+
+> **주의**: `--media-lang`을 실제 음성과 다르게 주면 엔진이 번역하거나 오전사한다.
+> 한국어 영상에 기본값 `en`이 걸리지 않도록, 한국어 콘텐츠는 `--media-lang ko`를 명시할 것.
+
+### X 첨부 미디어 «시각» 흡수 (`src/visual.ts`)
+
+전사는 소리만 본다 — 말 없는 화면 데모·모션그래픽·벤치 표 이미지는 전사가 비거나 «MUSIC» 한 줄이었다(2026-09-27 저장된 메시지 X 5편 실측). 그래서 화면도 흡수한다.
+
+| 미디어 | 처리 | 노트 |
+|---|---|---|
+| 사진 | `?name=large` 로 받아 S3(`x/media/<tweetId>/photo_N.jpg`) → Grok 비전 설명(표·그래프 수치, 화면 글자까지) | `# 첨부 미디어 (시각)` 부록에 이미지 ⊕ 설명 |
+| 영상·GIF | 장면 전환 프레임(최대 8장 · 모자라면 균등 6장) → S3(`x/media/<tweetId>/vN_fNN.jpg`) → Grok 비전으로 화면 흐름 설명 | 프레임 띠 ⊕ 설명 |
+
+- 설명은 요약 프롬프트에도 들어간다(«첨부 미디어 — 1차 자료»). `--no-media` 면 전사와 함께 끈다.
+- 무음 영상은 전사를 건너뛴다(`ffprobe` 로 오디오 스트림 확인) — 화면은 시각 흡수가 본다.
+- 의존: `ffmpeg`(`-fps_mode` — 옛 `-vsync` 는 새 ffmpeg 에서 없어졌다) · `aws` CLI · `XAI_API_KEY`. 비전 모델 = `GROK_VISION_MODEL` → `GROK_MODEL` → `grok-4-1-fast-reasoning`. 프레임 상한 영상 길이 = `OMNI_DIGEST_FRAMES_MAX_MS`(기본 10분).
+- 실패는 전부 건너뛰고 요약은 계속한다.
+
+### OCR (photo-intake-ocr 흡수)
+- Upstage Document OCR (TypeScript 네이티브 포팅)
+  - API 키: env → ~/.cache/upstage_api_key → ~/.zshrc 순 탐색
+  - 한국어+영어 혼합 문서 지원
+- OCR.space 자동 폴백
+- PDF → pdftotext 실패 시 OCR 자동 전환
+- 이미지 파일 자동 OCR
+
+### 다이어그램 (내장)
+- `--diagram` 또는 "다이어그램/시각화" 키워드로 활성화
+- Grok으로 Mermaid 다이어그램 코드 자동 생성
+- 요약 마크다운에 다이어그램 섹션 자동 추가
+- content-to-web RICH 모드에서 Excalidraw/Mermaid 추가 다이어그램 가능
+
+## 웹 배포 연계 (content-to-web)
+
+타겟에 web/web-deploy 시:
+1. 요약 마크다운 + Obsidian 저장
+2. `---SIGNAL: webDeploy=...---` 출력
+3. Claude가 content-to-web 스킬 호출
+   - QUICK: Becoming X 스타일 웹페이지
+   - RICH: Excalidraw 다이어그램 + SVG 포함 풍부한 아티클
+4. RICH 모드 다이어그램: diagram-master 스킬 (auto-routing) → PNG → Live SVG
+
+## Obsidian 저장 (소스별 자동 분류)
+
+| 소스 | 경로 |
+|------|------|
+| X | `03. X Summary/` |
+| YouTube | `02. Youtube Summary/` |
+| 웹 | `04. Web Digest/` |
+| GitHub | `06. GitHub Digest/` |
+| 문서 | `07. Document Digest/` |
+
+## summarize CLI 연동
+
+`steipete/summarize` CLI를 콘텐츠 추출 엔진으로 통합.
+
+두 가지 모드:
+
+| 모드 | 키워드 | 파이프라인 | LLM |
+|------|--------|-----------|-----|
+| **sum** | `sum` | summarize `--extract` → Grok 요약 | Grok (기존) |
+| **sum full** | `sum full` | summarize CLI end-to-end | summarize의 auto 모델 (OpenAI/Grok/Gemini/로컬) |
+
+- **sum**: summarize CLI가 **1순위 추출기**, Grok이 요약 (기존 품질 유지)
+- **sum full**: summarize CLI가 **추출+요약 모두 수행** (Grok API 비용 절감, 더 빠름)
+- **기본 모드** (sum 없음): firecrawl → summarize CLI → Jina Reader 순 폴백
+
+```bash
+# sum 모드: summarize 추출 → Grok 요약
+npx tsx scripts/main.ts "https://example.com" -m "sum 요약" --print
+
+# sum full 모드: summarize CLI가 추출+요약 모두 (Grok 스킵)
+npx tsx scripts/main.ts "https://example.com" -m "sum full" --print
+
+# 기본 모드 (summarize는 firecrawl 폴백으로 동작)
+npx tsx scripts/main.ts "https://example.com" --print
+```
+
+### summarize CLI 설치
+
+```bash
+brew install summarize
+# 또는
+npm i -g @steipete/summarize
+```
+
+### summarize CLI 설정 (선택)
+
+```bash
+# ~/.summarize/config.json 에서 기본 모델/언어 등 설정 가능
+summarize --help
+```
+
+## 설치
+
+```bash
+cd ~/.claude/skills/omni-digest
+npm install
+cp .env.example .env
+npx tsx scripts/main.ts --self-test
+```

package/skills/omni-digest/digest.md

@@ -0,0 +1,197 @@
+# 하니스 통합 리포트 — §8·§9·§10·§16
+
+> 대상: `내부 문서 `TECH-harness-execution-anatomy-current-state-2026-08-10``의 §8, §9, §10, §16
+>
+> 기준: 문서에 표시된 자동병합 사다리의 **R1~R8**. 여기서 R1~R7은 `pr-opened`로 넘기는 보류 사유이고, R8은 여섯 조건을 모두 만족하여 `review-clean-armed`로 자동 병합되는 성공 칸이다. 문서의 §9-2 표는 R1~R7과 성공 행을 명시한다. §9-0의 라이브 관측에는 별도/과거 계측 사유 `review-clean-verify-inconclusive`도 있으므로, 이는 현행 도식의 독립 R칸으로 단정하지 않는다.
+
+## SCQA
+
+### S — 관측
+
+하니스는 구현만 하는 직선 실행기가 아니라, **구현 → 검증·리뷰·재작업 → main 정합 → PR → 자동병합 또는 HITL → 원장·관측으로 재판정**하는 폐루프다. §8은 실행 노드, §9는 착지 판정, §10은 이력의 세 저장소, §16은 관측 도구의 사각지대를 각각 확대한다.
+
+### C — 맥락
+
+자동병합은 PR을 열었다는 사실만으로 허용되지 않는다. `autoMerge`, 요구 증거 충족, 신호 완전성, 실제 리뷰 수행, 리뷰 verdict, diff 완전성이라는 여섯 조건이 모두 필요하다. 하나라도 만족하지 못하거나 알 수 없으면 병합 실패로 처리하지 않고 `pr-opened` 상태로 사람(HITL)에게 넘긴다.
+
+### Q — 이 네 절을 통합하면 무엇을 답하는가?
+
+1. 한 런은 실제로 어떤 노드를 어떤 순서로 통과하는가?
+2. PR 이후 자동으로 착지할지, 왜 사람에게 넘길지를 어떤 순서로 판정하는가?
+3. 그 결과와 실패 재발을 어느 원장에 남기며, 각 원장은 무엇을 답하지 못하는가?
+4. 운영자가 이 판정을 검증할 때 어떤 도구의 관측 범위와 한계를 먼저 확인해야 하는가?
+
+### A — 결론
+
+§8·§9·§10·§16은 각각 실행·결정·기억·관측 층을 맡는다. 따라서 R1~R8은 §9의 병합 분기만이 아니라, §8이 만든 판정 입력을 §9가 소비하고, §10이 이력을 남기며, §16이 그 이력과 라이브 상태를 과장 없이 읽게 만드는 **통합 착지 사다리**다.
+
+---
+
+## 1. 통합 사다리 R1~R8
+
+| 칸 | `mergeReason` / 결과 | §9의 질문 | 결과 |
+|---|---|---|---|
+| **R1** | `no-auto-flag` | 자동병합이 켜졌는가? | 아니오면 `pr-opened` → HITL |
+| **R2** | `required-evidence-uncovered` | 골이 이름으로 요구한 증거 태그가 모두 덮였는가? | 아니오면 HITL |
+| **R3** | `signal-incomplete` | 최신 신호가 완전한가? | 아니오면 HITL |
+| **R4** | `no-real-review` | 리뷰가 실제로 수행되었는가(`reviewed`)? | 아니오면 HITL. “지적 0건”과 다름 |
+| **R5** | `review-must-fix` | 실제 리뷰의 verdict가 `fail`이 아닌가? | fail이면 HITL 및 rework 근거 |
+| **R6** | `review-diff-truncated` | 리뷰어가 diff 전체를 보았는가? | 잘렸으면 HITL |
+| **R7** | `review-diff-budget-unknown` | diff 완전성조차 판정 가능한가? | 모르면 HITL |
+| **R8** | `review-clean-armed` | 여섯 병합 조건이 모두 참인가? | 예면 squash 자동병합 → `merged` |
+
+**판정식:**
+
+```ts
+canAuto = autoMerge
+       && reviewReal
+       && review.verdict !== 'fail'
+       && reviewDiffComplete
+       && !requiredEvidenceMissing
+       && !latestSignalIncomplete
+```
+
+R1~R7은 “실패”가 아니라 자동 판단을 멈추는 안전한 보류다. 이때 종결은 `pr-opened`이고, 사람에게 판단권을 넘긴다. R8만 자동병합 허가다.
+
+---
+
+## 2. 절별 요약과 R1~R8 접점
+
+### §8 — 파이프라인 노드 아홉 × 모듈 × 액션
+
+**이 절이 답하는 질문:** “한 하니스 런은 실제로 무엇을 하는가? 각 단계는 어느 모듈에서 실행되고, 화면·종결 stage에는 무엇을 남기는가?”
+
+**핵심 내용**
+
+- 9개 노드는 `implement → gate → review → rework → main-sync → regate → typecheck-recheck → open-pr → merge`다.
+- `gate` 실패는 바로 종결하지 않고 `rework`로 되먹인다. `review`의 must-fix도 rework를 만든다.
+- PR 전에는 `main-sync → regate → typecheck-recheck`의 정합 삼단을 통과한다. 즉, 최초 gate 통과만으로 병합 판단을 하지 않는다.
+- `merge`는 두 가지 종결을 가진다. 병합 성공은 `merged`, 자동병합 불허는 `pr-opened`이며 후자는 HITL 전환이다.
+- 같은 `gate-failed`가 rework·regate·typecheck-recheck에서 나올 수 있으므로 stage 하나만 보고 실패 위치를 단정할 수 없다.
+
+**R1~R8과의 접점:** **간접 입력 생산층 + R8의 실행 종결층.**
+
+| 사다리 칸 | §8 연결 근거 |
+|---|---|
+| R1 | 노드 8 `open-pr` 뒤에 병합 관문으로 진입한다. 자동병합 설정이 없으면 노드 9는 병합 대신 `pr-opened`로 끝난다. |
+| R2 | `gate`, `regate`, `typecheck-recheck`와 골 검증 산출은 요구 증거가 충분한지 판단할 수 있는 실행 근거를 만든다. 다만 R2의 최종 판정은 §9가 한다. |
+| R3 | 하니스 런이 내는 신호·종결 산출이 §9의 신호 완전성 검사 입력이다. |
+| R4~R7 | 노드 3 `review`가 `reviewed`, verdict, diff 완전성 정보를 만든다. 리뷰가 실행되지 않았거나 결과·범위가 불완전/불명인 경우 §9가 각각 R4~R7로 분기한다. |
+| R8 | 노드 9 `merge`의 성공 종결이 `merged`다. §9가 `review-clean-armed`를 내면 이 노드가 squash 자동병합을 수행한다. |
+
+**통합상 의미:** §8은 병합 판단기가 믿을 수 있는 입력을 만드는 곳이다. 특히 review를 빼면 R4~R7이 성립하지 않고, 정합 삼단을 빼면 R8은 오래된 main 기준의 오판이 된다.
+
+---
+
+### §9 — 후반부: rework · 정합 · PR · 무인 병합
+
+**이 절이 답하는 질문:** “검증 또는 리뷰 문제가 난 뒤 어떻게 고치고 정합하며, PR 이후에는 어떤 순서와 근거로 무인 병합 또는 HITL을 결정하는가?”
+
+**핵심 내용**
+
+- 후반부는 rework, main 정합, 재게이트, 타입 재검증, PR, 무인 병합의 결합이다.
+- 병합 관측에는 `verifyByBreaking` 구조화 필드를 싣지만, 현행 라운드는 `canAuto` 임계식을 바꾸지 않고 값을 흐르게 하는 단계다.
+- 종료 관측의 필드를 타입으로 강제하여 새 종결 경로가 관측 필드를 빠뜨리면 컴파일 오류가 나게 한다.
+- 반복 리뷰 지적은 원문 동일성이 아니라 `reviewFindingKey`로 의미상 반복을 센다.
+- 자동병합은 위 표의 여섯 조건을 모두 만족할 때만 가능하며, R1~R7은 모두 `pr-opened`로 전환된다.
+
+**R1~R8과의 접점:** **직접적인 사다리 소유 절.**
+
+| 사다리 칸 | §9 연결 근거 |
+|---|---|
+| R1 | `autoMerge` 플래그가 꺼진 경우의 최우선 보류 사유다. |
+| R2 | 골이 요구한 증거가 덮이지 않았음을 병합 전에 차단한다. |
+| R3 | 최신 신호의 불완전성을 자동병합 불허로 취급한다. |
+| R4 | `reviewed` 여부를 판정하므로 “리뷰 지적이 없었다”와 “리뷰가 없었다”를 구별한다. |
+| R5 | 리뷰 verdict의 must-fix를 자동병합 중단 및 재작업 근거로 쓴다. |
+| R6 | 리뷰어가 diff 일부만 본 경우를 명시적으로 차단한다. |
+| R7 | diff 완전성 판단 자체가 불명인 경우도 안전하게 차단한다. |
+| R8 | 여섯 조건이 모두 참일 때 `review-clean-armed`로 squash 자동병합한다. |
+
+**통합상 의미:** §9는 불확실성을 성공으로 환산하지 않는다. 모르는 것은 R7로, 검증되지 않은 것은 R4/R6으로, 사람이 선택해야 할 것은 `pr-opened`로 보낸다. 이것이 하니스의 무인화 경계다.
+
+---
+
+### §10 — 원장 관리
+
+**이 절이 답하는 질문:** “런의 결과·종료 방식·재발을 어디에 남기고, 각 기록은 어떤 질문과 어떤 공백을 갖는가?”
+
+**핵심 내용**
+
+원장은 하나가 아니라 셋이다.
+
+| 원장 | 기록 주체·형태 | 답하는 질문 | 답하지 못하는 것 |
+|---|---|---|---|
+| ① 런 원장 | 런 종료 시 자동 기록, `run-ledger/<runId>.jsonl` | 끝났는가, 성공했는가, 몇 라운드였는가, `reviewed`였는가 | 왜 그렇게 되었는가 |
+| ② 골-런 스토어 | 종결 레코드 자동 확정, SQLite `GoalExecutionRecord` | 어떻게 끝났는가: stage·goalType·리뷰 계열·PR 번호 | 같은 실패가 재발했는가 |
+| ③ 영역 원장 | 사고 때 사람이 `내부 문서 `ISSUES``에 기록 | 같은 자리를 몇 번 밟았는가: 성격·재발·방어 주체 | 자동으로는 생기지 않음 |
+
+- 연합 미완 조회는 원장별 독립 판정의 유령 미완을 runId 가로 대조로 제거한다.
+- 반복되면 영역 원장의 사례를 `내부 문서 `PATTERNS``의 교훈으로 승격한다.
+
+**R1~R8과의 접점:** **판정 이력·재발 학습층. 직접 판정하지는 않지만, 모든 칸의 사후 검증과 개선에 필수다.**
+
+| 사다리 칸 | §10 연결 근거 |
+|---|---|
+| R1~R7 | 자동병합이 보류되어 `pr-opened`로 끝난 이유·stage·리뷰 상태를 원장 ①·②가 남겨, HITL 전환이 설정 부재·증거·신호·리뷰 중 어디에서 생겼는지 추적하게 한다. |
+| R4~R7 | 특히 `reviewed`, 리뷰 계열, diff·관측 관련 기록은 “리뷰가 없었는지/실패했는지/범위를 몰랐는지”를 사후 구분하는 근거다. |
+| R8 | `merged` 및 PR 번호가 자동 착지의 결과를 확정한다. |
+| R1~R8 공통 | 자동 원장은 반복 원인을 완성하지 못한다. 동일한 보류·오판이 재발한 경우에는 사람 원장 ③에 기록하고 패턴으로 승격해야 방어가 누적된다. |
+
+**통합상 의미:** §10은 R칸을 “한 번의 병합 판단”에서 “재발을 학습하는 운영 데이터”로 바꾼다. 다만 원장 하나만 보면 원인을 놓치거나 재발을 놓치므로 셋을 함께 읽어야 한다.
+
+---
+
+### §16 — 관측 툴 전체
+
+**이 절이 답하는 질문:** “하니스의 라이브 상태·이력·화면을 확인할 때 각 도구는 무엇을 알려 주며, 특히 무엇을 보지 못하는가?”
+
+**핵심 내용**
+
+- 이 절의 핵심은 도구 목록이 아니라 **각 도구의 사각지대**다. 부분 관측을 전체 관측으로 오독하지 않게 한다.
+- `self unfinished-runs --path`는 자기 트리 우주만 본다.
+- `pty list --all --include-test --json`은 다른 트리도 찾지만 살아 있는 PTY만 보며, 멈춘 런은 못 본다.
+- `pty snapshot`은 현재 화면을 보지만 짧은 수명의 자식은 폴링으로 놓칠 수 있다.
+- `logs --instance`는 레코드에 트리 식별 필드가 없어 모호한 instance를 해결하지 못한다.
+- 원장 ①은 종료·라운드를, 원장 ②는 종료 방식을, 원장 ③은 재발을 보지만 어느 하나도 모든 질문에 답하지 못한다.
+- 조회 전에는 limit, 표시 절단, 결론 행 위치, JSON Lines 형태, 그리고 “전수”가 어느 우주에 대한 전수인지를 점검해야 한다.
+
+**R1~R8과의 접점:** **사다리 판정의 검증·반증층.**
+
+| 사다리 칸 | §16 연결 근거 |
+|---|---|
+| R1 | PR은 열렸으나 자동병합이 꺼진 상태인지, 혹은 다른 우주·다른 트리의 런을 보고 있지는 않은지 범위를 먼저 검증하게 한다. |
+| R2 | 요구 증거 미충족은 로그·레코드가 어느 우주에서 수집됐는지와 표시 절단 여부를 확인하지 않으면 잘못 판정할 수 있다. |
+| R3 | 신호 완전성은 관측 자체의 범위·상한·누락을 함께 검증해야 한다. 관측이 불완전한데 신호만 완전하다고 결론 내릴 수 없다. |
+| R4 | `reviewed` 여부는 원장 ①과 종료 기록을 확인해야 하며, 화면 스냅샷만으로 리뷰 수행 여부를 단정할 수 없다. |
+| R5 | 리뷰 verdict는 원장 ② 등의 구조화 이력을 읽어야 한다. PTY 생존 여부만으로 must-fix를 판단할 수 없다. |
+| R6~R7 | diff 절단/예산 불명은 “값이 없었다”와 “표시에 잘렸다·다른 우주에 있었다”를 구분해야 한다. §16의 JSON·limit·우주 경계 규율이 바로 그 반증 장치다. |
+| R8 | `merged`를 관측할 때도 하나의 화면이나 현재 PTY만으로 확정하지 않고, 종결 원장·PR 기록·관측 우주를 교차 확인해야 한다. |
+
+**통합상 의미:** §16은 R1~R8을 새로 결정하지 않는다. 대신 “어떤 R칸에 도달했다”는 운영자의 결론이 도구의 사각지대 때문에 틀리지 않도록, 관측의 전제와 한계를 드러낸다.
+
+---
+
+## 3. 하니스 통합 흐름
+
+```mermaid
+flowchart LR
+  A[§8 실행 노드 1~9\n구현·검증·리뷰·정합·PR] --> B[§9 병합 사다리]
+  B -->|R1~R7: 조건 불충족·불명| C[pr-opened\nHITL]
+  B -->|R8: review-clean-armed| D[자동 squash 병합\nmerged]
+  C --> E[§10 원장 ①②\n종료·방법 기록]
+  D --> E
+  E --> F[§10 원장 ③\n재발 기록 → 패턴 승격]
+  G[§16 관측 도구·사각지대] -.검증/반증.-> A
+  G -.판정 근거 확인.-> B
+  G -.이력 범위 확인.-> E
+```
+
+## 4. 운영 결론
+
+- **§8 없이는 §9가 판단할 입력이 없다.** 리뷰·재게이트·타입 재검증을 실제 노드로 통과해야 R2~R7과 R8이 의미를 갖는다.
+- **§9 없이는 §8의 결과가 안전하게 착지하지 않는다.** 자동화를 원하더라도 불확실성은 R1~R7로 명시해 HITL에 넘긴다.
+- **§10 없이는 판단이 누적 학습으로 바뀌지 않는다.** 자동 이력은 종료와 방식을, 사람 원장은 재발과 방어 주체를 보완한다.
+- **§16 없이는 위 세 층의 관측이 과신된다.** 우주·트리·PTy 생존·표시 절단·limit을 먼저 확인해야 “없음”, “전수”, “병합됨” 같은 결론이 성립한다.
+
+즉 하니스 통합의 핵심은 “자동병합 성공률”이 아니라, **실행 근거를 만든 뒤(R8 포함) 자동판정 가능성만 기계에 맡기고, 근거 부족·불명은 명시적인 R1~R7로 남겨 기록·관측·HITL의 폐루프로 회수하는 것**이다.

package/skills/omni-digest/docs/diagrams/noncode-terminal-promotion-path-2026-08-13.mmd

@@ -0,0 +1,32 @@
+flowchart TD
+  classDef pass fill:#d7f5df,stroke:#198754,color:#102a16
+  classDef gate fill:#fff3cd,stroke:#b7791f,color:#3b2f00
+  classDef fail fill:#fde2e2,stroke:#b42318,color:#3b0a0a
+  classDef data fill:#e7f0ff,stroke:#2563eb,color:#102a43
+
+  A[Domain executor returns dr<br/>ok · changes · outcome · ref · evidence]:::data
+  B{Execute conditions?<br/>ok AND changes = 0<br/>AND verifiedNonCodeOutcome(dr)}:::gate
+  C[No nonCodeOutcome<br/>ordinary no-changes result]:::fail
+  D[Create in-memory nonCodeOutcome<br/>outcome · ref · nonCodeEvidence]:::pass
+  E[deploy: files = changedFiles(cwd)]:::data
+  F{Code changes exist?}:::gate
+  G[Code deploy path]:::data
+  H{nonCodeOutcome exists?}:::gate
+  I[observe deploy-no-changes<br/>return { ok:false, kind:none }]:::fail
+  J{Evidence is artifact-created?}:::gate
+  K{PR #8731 · 2026-08-13<br/>existsSync(resolve(cwd, ref))?}:::gate
+  L[observe deploy-noncode-blocked<br/>reason: artifact-created-ref-missing<br/>then deploy-no-changes]:::fail
+  M[Do not treat ref as a file<br/>published-url / execution-completed]:::data
+  N[observe deploy-noncode<br/>return terminal:<br/>published or executed]:::pass
+
+  A --> B
+  B -- no --> C
+  B -- yes --> D --> E --> F
+  F -- yes --> G
+  F -- no --> H
+  H -- no --> I
+  H -- yes --> J
+  J -- yes --> K
+  K -- no --> L
+  K -- yes --> N
+  J -- no --> M --> N