---
description: 하네스가 조직 지식층(조직 위키·도메인 문서)에서 무엇을 기대하는지 정의하는 계약. 조직은 이 계약만 만족하면 쓰던 위키를 그대로 매핑한다 — 포크가 아니라 매핑이 1차 경로다. 소비자 배선 현황과 미배선 사실을 함께 명시한다.
provenance: pmh-dev@cbe3932 knowledge/shared/rules/knowledge_layer_seam.md 역수확(2026-08-10) — 조직 고유 식별자 범용화 · 배선 현황을 FH 실상으로 교체. 원 계약의 자기정정 이력(K2 임계 UNCALIBRATED · conform 경로)은 보존.
---

# 지식층 Seam — 하네스 ↔ 조직 위키 계약

## 왜 이 문서가 있나

하네스는 방법론과 게이트를 준다. 그것이 *무엇에 대해* 판단할지는 **조직 맥락**에서 온다.

**그런데 "쓰던 위키가 있으면 그걸 쓰세요"는 계약이 없으면 말로만 참이다.** 무엇을 만족해야
"쓸 수 있는" 것인지 적혀 있지 않으면 조직은 결국 처음부터 다시 만든다. 이 문서가 그 계약이다.

**관측 사실(원 필드, 2026-07-19~20)**: 4비트 양자화 로컬 모델이 이 계약 위에서 BUILD를
완주했다 — 구현·스킬 인큐베이팅·PR 개설까지(저자 정체성으로 런 분리).
⚠️ **인과는 분리되지 않았다**: 그 완주에 지식층이 얼마나 기여했는지는 **측정되지 않았다**
(스킬·게이트·운영자 교정이 함께 작용했다). 어블레이션 없이 "맥락층이 원인"이라 주장하지 않는다.
계약 문서는 *효과*를 증명할 필요가 없고 **무엇이 없으면 무엇이 깨지는지**만 정의하면 된다.

## 0. 배선 현황 (FH 기준)

| 소비자 | 무엇을 읽나 | 언제 | 상태 |
|---|---|---|---|
| `phantom-quench` **Step 2-O** | 진입 인덱스(`INDEX.md`/`index.md`/`README.md`/`readme.md` — 판정기와 동일 후보) → 후보 페이지 | **도메인 주장**(조직 고유 사실·용어·정책)이 Step 2 에서 **미선언**일 때 | ✅ **배선됨** (2026-08-10 역수확, FH 1호) |
| `steel-quench` Step 0.35 | 진입 인덱스(위와 동일 후보) → 관련 정책·용어·도메인 사실 | 공격 각도를 정하기 전 | ✅ **배선됨** (2026-08-20 역수확, FH 2호) — 🟥 단 **살리언스 층이지 기계 바닥이 아니다.** 훅도 레인도 이 절을 강제하지 않는다. 원 필드 문서에는 강제 취지의 서술이 딸려 있었으나 실측하니 그 훅 레인이 **부재**해서(팬텀 기계-주장) **가져오지 않았다.** 「배선됨」은 «절차가 스킬에 존재한다» 는 뜻이고 «기계가 강제한다» 는 뜻이 아니다 |

**1호 소비자 배선의 의미**: 그전까지 도메인 주장은 로컬 선언 파일에도 외부 인용에도 안 걸려
**전부 🔴 Source-Missing 으로 떨어졌다** — 조직 지식층이 정확히 그 근거인데 탐색 경로에 없었다.

**이 배선이 계약의 어느 조항을 실제로 쓰는가** (조항이 장식이 아님을 보이는 표):

| 계약 조항 | Step 2-O 에서의 쓰임 |
|---|---|
| K2 진입 인덱스 | 진입 인덱스를 먼저 읽는다 — **전수 스캔 안 함** |
| K3-f `review_after` | 경과 시 **Grounded 가 아니라 Partial** — stale 근거는 근거가 아니다 |
| §1-a 충돌 우선순위 | 조직 위키의 판정 규칙이 스킬 판정을 **못 덮는다**, 충돌은 보고에 명시 |
| K1-s 반출 금지 | 조직층 원문은 외부 fetch/dispatch 로 **안 나간다** |
| §6 degrade | `{org}/` 부재 = **UNMEASURED**, 🔴 유지. "맥락 없음"이지 "근거 없음 확정" 아님 |

## 1. 경로 규약 — seam은 디렉터리다

```
knowledge/
├── shared/      조직 불변. 하네스 레포에서 온다(§4 획득 경로 주의). 조직이 편집하지 않는다.
└── {org}/       조직 맥락. 조직이 소유한다. 하네스는 읽기만 한다.
```

**빈 슬롯도 규약이다.** `knowledge/{org}/`가 비어 있으면 "맥락 없음"이지 "맥락 불필요"가 아니다.
에이전트는 **맥락 부재를 명시**해야 하며, 없는 맥락을 추론으로 메우지 않는다.

### 1-a. 충돌 우선순위 — 가장 비싼 실패 모드

`{org}/`은 **무엇**(도메인 사실·용어·정책)만 공급한다. **어떻게 판정하나**는 공급하지 않는다.

> **shared/의 게이트·floor·판정 규칙을 `{org}/`이 덮어쓸 수 없다. 충돌 시 shared 우선 + 충돌 사실 명시.**

이 줄이 없으면 다음이 일어난다: org 위키에 "핫픽스는 main 직푸시" 같은 로컬 관행이 있고 shared
게이트는 금지인데, 에이전트가 "org 맥락이 더 구체적"이라 판단해 **게이트를 우회한다.** 조직 맥락
도입의 가장 비싼 실패 모드이며, 우선순위가 없으면 무방비다.

## 2. 하네스가 기대하는 것 (최소 계약)

| # | 기대 | 필수? | 이유 |
|---|---|---|---|
| K1 | **마크다운 디렉터리** — 에이전트가 읽을 수 있는 경로 | **필수** | 없으면 아무것도 성립 안 함 |
| K1-s | **유입 스크럽** — 동기화 시점에 시크릿/PII 스캔 통과, 실패 시 **fail-closed**(부분 동기화 금지) | **필수** | seam은 조직 데이터가 모델 컨텍스트로 들어오는 **바로 그 지점**이다 |
| K2 | **진입 인덱스 1개**(`INDEX.md`/`index.md`/`README.md`/`readme.md` — 판정기 후보와 동일, 대소문자는 Linux 에서 유효) **존재**. 규모가 커지면 섹션 인덱스로 분기 | **필수(존재)** | 전수 스캔은 토큰을 태운다. 단 평면 대형 인덱스도 같은 문제다 |
| K2-c | 인덱스 **크기 보고**(자수·추정 토큰) — **임계는 미측정이라 판정 근거로 쓰지 않는다** | 보고 | ⚠️§2-c 참조 |
| K3 | **파일당 1줄 설명** — frontmatter `description:` **또는** 인덱스에 그 파일 상대경로 **+ 설명 텍스트**가 있는 줄(경로만 나열된 줄은 불인정). **수기·생성기 산출 모두 인정** | **필수** | 열기 전 관련성 판별의 유일 수단 |
| K3-d | **최종갱신일** — frontmatter `date:`/`updated:`/`last_updated:` | **권장** (누락 = §6 degrade: stale 판정 불가 → `미상` 보고, 차단 아님) | 날짜는 §6 stale 판정의 근거. ⚠️ 초판이 K3 에 «필수»로 합쳐 적어 판정기(WARN·비차단)와 모순됐다 — 쪼개서 정직하게 |
| K3-f | **`review_after:`** — 이 페이지를 재검토해야 하는 기한(날짜). `date`(과거 — 마지막으로 손댄 날)와 달리 **미래를 향한 신선도 계약**이다 | 권장 | Step 2-O 의 **Grounded** 판정 전제 — 이 필드가 없으면 슬롯 히트도 Partial 상한(신선도 미상). ⚠️ 초판엔 §0 표에만 등장하고 여기 정의가 없었다(팬텀 조항) — 판정기가 보유율을 INFO 로 보고한다 |
| K4 | **파생 인덱스 자동 갱신** | 경로1 권장 / **경로2·3 필수** | 기존 대형 위키에 사람이 수백 줄을 쓰게 하면 1차 경로가 역차별된다 — 스크립트가 쓴다 |
| K5 | `llms.txt` | 선택 | 외부 에이전트 진입 표면 |
| K6 | 읽기전용 MCP(`*_index`/`*_get`/`*_search`) | 선택 / **경로4 필수** | 파일시스템 접근이 없는 런타임·비문서 소스용 |

**진입 장벽을 낮게 두는 것이 이 계약의 목적이다.** 그래서 K3의 비용은 K4로 옮길 수 있게 열어뒀다.

## 2-c. ⚠️ K2 임계는 UNCALIBRATED 다 (원 계약의 자기정정 — 이력째 보존)

원 계약 초안은 **"≤200줄"** 을 필수 조건으로 걸었다. **그 숫자에 유도 과정이 없었다 — 지어낸
것이다.** 인용할 수 없는 임계는 판정 근거가 아니다. **게다가 줄수는 나쁜 계기다** — 실측
(2026-07-21, 실물 위키 974 파일): 인덱스가 **337줄인데 약 23k 토큰**이었다(줄당 143자).
비용은 토큰인데 줄로 재고 있었다.

**현재 규약**: 존재는 필수(K2) · 크기는 보고(K2-c — PASS/FAIL 근거로 쓰지 않는다) ·
분기 판단은 조직이 자기 예산으로. **임계를 되살리려면** 인덱스 크기와 (a) 관련성 판별 정확도
(b) 세션 토큰 예산의 관계를 실측해야 한다. 그 전까지 `UNCALIBRATED` 다.

## 3. 채택 경로 (다섯)

| 상황 | 경로 |
|---|---|
| **위키가 없다** | 조직 표준 LLM-위키 템플릿(있다면)을 포크해 `knowledge/{org}/`로 매핑 — 구조가 K1–K3 를 만족하도록 |
| **위키가 있다 (git)** | submodule 또는 동기화로 붙인다. 미충족분만 보충 + **K4 필수** |
| **위키가 있다 (비-git: 컨플루언스 등)** | export → 마크다운 → 동기화. **4항 명시 필수**: export 주체 · 주기 · 산출 경로 · 실패 시 동작(fail-closed). **K4 필수** |
| **문서 자체가 없다** (맥락이 티켓·채팅·코드 주석에만) | 주기 추출로 마크다운 스냅샷 생성, 또는 **K6 MCP로 노출**. K4·K6 필수 |
| **이미 위키가 있고 그 자리에서 계약에 맞춘다**(옮기지 않고 독립 운영) | **`conform`** — 부족분(설명·날짜)만 **생성기로 백필**. 새로 만들거나 이전하지 않는다 |

다섯 경로가 **같은 계약 위에 선다.** 그래서 "쓰던 걸 쓰세요"가 실제로 성립한다.

### 3-c. `conform` — 도그푸딩이 찾은 다섯 번째 경로 (원 필드 실측)

초안의 네 경로는 전부 **"위키를 어떻게 확보하나"** 였다(포크·매핑·export·추출). 그런데 계약을
처음 실물에 먹여본 대상(974 파일 개인 위키)은 넷 중 아무것도 아니었다 — 이미 있었고, 옮길 데도
없고, **그 자리에서 계약에 맞추면 되는** 경우였다. 아마 가장 흔한 실제 경우다.
`conform` 의 비용은 사람이 아니라 **생성기**가 낸다(K4 의 존재 이유). 실측: **설명 누락
406 → 0 · 날짜 누락 547 → 6.** 백필 도구가 96%를 처리했고, 본문에서 파생할 수 없는 9건은
**지어내지 않고 남겨서** 사람이 썼다. 그게 옳은 분업이다.

## 4. 포크가 아니라 매핑이 1차

원칙: **맥락 때문에 하네스를 포크하지 않는다.** 맥락은 `{org}/`에만 있으므로 그 디렉터리
매핑으로 충분하다. 포크는 하네스 자체를 개조할 때, 그리고 아래 예외에만.

**예외 — 폐쇄망 벤더링**: 배포 채널을 당길 수 없는 망 분리 조직에겐 버전 고정 vendored 복사가
유일 경로다. 그 경우 **upstream diff 주기를 명시**(예: 분기)하고 drift를 의도된 비용으로
관리한다.

## 5. 한 레포 = 한 **기밀 경계** (조직 수가 아니라)

*"위키 하나에 모든 조직 맥락을 모으면 안 되나"* — 기준은 **조직**이 아니라 **기밀 경계**다.

- **한 조직 안에서도 경계가 갈리면 쪼갠다** (공개 OSS 맥락 + 조직 기밀이 한 곳에 섞이면 조직이
  하나여도 residency가 깨진다).
- **같은 경계를 공유하는 복수 조직은 `{org}/` 분리로 허용** (지주사·자회사 등).
- **예시/시드 org(`example/`)는 명시적 예외** — 없으면 워크드 예시조차 못 싣는다.

**메타층에 있어야 할 것은 맥락이 아니라 스키마의 스키마와 시드다** — 구체 스키마는 org가 소유한다.

## 6. Degrade 방향

| 상황 | 방향 |
|---|---|
| `knowledge/{org}/` 부재 | **맥락 부재를 명시하고 진행.** 추론으로 메우지 않는다 |
| 인덱스(K2) 부재 | 전수 스캔하지 않는다 — 부재 보고 + 인덱스 생성 제안 |
| 날짜(K3-d) 부재 | stale 판정 불가 → **`미상`으로 보고**. 최신으로 가정하지 않는다 |
| 위키는 있으나 stale | **stale 명시.** 최신인 척하는 것이 없는 것보다 나쁘다 |
| 매핑 실패(경로·권한) | 조용히 빈 결과로 진행하지 않는다 — **실패로 보고** |
| 스크럽(K1-s) 실패 | **fail-closed** — 부분 동기화 금지 |

공통: **부재와 실패는 0이 아니다.** 낮은 값은 PASS처럼 읽히므로 명시적으로 구분한다.

## Done When

- `knowledge/{org}/`가 K1·K2·K3를 만족한다
  (check class: **mandatory-pass** — `scripts/knowledge_seam_check.sh`가 기계 판정,
  known-pair 레인 = `scripts/test_knowledge_seam_lanes.sh` 34레인(권한 3레인은 root 실행 시 skip).
  **exit 계약이 판정이다**: `0`=PASS · `1`=FAIL · `3`=UNMEASURED(부재/빈슬롯/내용 페이지 0건 —
  보일러플레이트만으로 PASS 를 살 수 없다) · `4`=READ-FAIL(경로/권한 — §6 «실패로 보고»).
  호출자는 3·4 를 명시 처리한다 — 0/비0 이분법에서 3·4 는 FAIL 쪽으로 떨어진다(안전 방향))
- **K1-s(유입 스크럽)는 이 판정기의 범위 밖이다 — 미기계화를 명시한다**
  (check class: **judged — 미기계화**. 스크럽은 각 채택 경로(§3)의 동기화 도구 소관이며,
  이 계약은 «실패 시 fail-closed» 요구까지만 정의한다. 판정기가 이것까지 초록으로 보이게
  하지 않도록 여기 명시 — 스크럽 없는 동기화는 K1-s 위반이고, 그 검증은 동기화 파이프라인의
  레인이 진다)
- 채택 경로가 `knowledge/{org}/SEAM.md` frontmatter에 기록된다:
  `adoption_path: fork|git-map|export-sync|extract|conform` + `synced_at: YYYY-MM-DD`
  (check class: **mandatory-pass** — 같은 스크립트가 frontmatter 위치·값 경계·날짜 형식까지 검사)
- 맥락 부재 시 에이전트가 그것을 명시한다
  (check class: **judged** — 적대 짝: `tests/seam_absence_probes.md`의 고정 프롬프트 5건을
  맥락 없는 상태로 주고 **추론으로 메우는지** 관찰. 합격 = **5/5 명시적 부재선언**.
  ⚠️ 이 짝은 §6이 에이전트가 읽는 자리에 인라인되기 전까지는 **구조적으로 통과가 어렵다** —
  gate-locality: 규칙이 행위자가 안 읽는 파일에 있으면 장식이다. Step 2-O 가 §6 의 핵심
  행(부재=UNMEASURED)을 스킬 본문에 인라인한 것이 그 1차 처방이다)