공개 문서
learn/canonical/knot/KNOT-HARNESS-INTEGRATION.md
아래는 learn/canonical/knot/KNOT-HARNESS-INTEGRATION.md 와 동일한 원문입니다. Markdown과 HTML 변환 결과를 각각 복사할 수 있습니다.
공개 문서 원문 (Markdown)
# knot bridge — 지식 vault ↔ 하네스 연동
> **현재 canonical vault 구조 (Phase 5b 완료):** `schema/` · `raw/{inbox,archive,quarantine}` · `wiki/`(3문서) · `ops/`
> **knot** = 벤더중립 장기 지식 vault (`KNOT_WIKI`)
> **하네스** = 작업 단위 orchestration (`tasks/<task>/`)
> 정본: [netwaif/knot](https://github.com/netwaif/knot) · MAS 도구: `tools/knot/`
---
## 역할 분리
| | **하네스 (`tasks/`)** | **knot (`KNOT_WIKI`)** |
|--|----------------------|-------------------------|
| 단위 | bounded task (승인·검증·완료) | 지속 wiki (ingest·query·lint) |
| 메모리 | `context.md`, `log.md`, worker `result.md` | `wiki/`(3문서), `schema/index.md`, `raw/archive/` |
| 수명 | task `status: done` 후 아카이브 | 누적·상호링크 |
| 워커 | claude · codex · gemini (승인 게이트) | ingest/query/lint (`schema/schema.md` + `ops/prompts/`) |
**금지**: knot ingest를 worker pool에 넣지 않는다 — 별도 vault 규약(`schema/schema.md`)이 우선한다.
---
## 언제 knot을 쓰는가
| 상황 | knot | 하네스 task |
|------|------|-------------|
| 회의록·문서 md를 지식 그래프로 축적 | ✅ `raw/inbox/` → ingest | ❌ |
| "우리 vault에 X 관련 뭐 있지?" | ✅ query | ❌ |
| 기능 구현 + claude critique | ❌ | ✅ |
| task 완료 후 **재사용 가능한** 일반 교훈 | ✅ `raw/inbox/`에 요약 md 넣고 ingest | ✅ `_shared/learnings.md` (시스템 한정) |
| 외부 repo 코드 수정 | ❌ | ✅ codex/claude worker |
---
## 설치 (LAB 1회)
```bash
cd ~/Desktop/MultiAgentSystem
bash tools/knot/install-knot-wiki.sh
# 기본: knot-wiki/ (repo 루트)
source tools/knot/env.example # KNOT_WIKI export
```
knot vault는 **로컬 git**만 사용(push 금지 — `schema/schema.md` 정본). MAS repo와 **별도 디렉터리** (`knot-wiki/`, `.gitignore`).
---
## 오케스트레이터 워크플로
### A. task 시작 전 — 맥락 조회 (선택)
```bash
bash tools/knot/run-knot.sh query "이 task와 관련된 기존 지식 요약"
```
답변을 `tasks/<task>/context.md`에 **한 줄 근거 링크**만 넣는다(전문 paste 금지 — context 한도).
### B. task 완료 후 — 지식 승격 (선택)
1. 재사용 가치 있는 합성을 md로 작성
2. `$KNOT_WIKI/raw/inbox/`에 저장
3. `bash tools/knot/run-knot.sh ingest` (또는 drain)
4. `tasks/<task>/log.md`에 `[DECISION] knot ingest: raw/inbox/<file>` append
### C. 하네스 task로 knot ingest 위임 (명시적 task)
`_templates/knot-bridge-task.md` 템플릿으로 `tasks/knot-ingest-<name>/` 생성.
`workers_approved` 없이 **오케스트레이터가 직접** `run-knot.sh ingest` 실행 — worker 호출 아님.
---
## flavor별 실행
| flavor | ingest 실행 예 |
|--------|----------------|
| **codex** | `KNOT_RUNNER=codex bash tools/knot/run-knot.sh ingest` |
| **cursor** | 동일 (Cursor agent shell에서 run-knot.sh OK) |
| **claude** | `KNOT_RUNNER=claude bash tools/knot/run-knot.sh ingest` |
| **antigravity** | `KNOT_RUNNER=agy bash tools/knot/run-knot.sh ingest` |
Codex flavor 하네스 MCP prune과 **무관** — knot은 vault 경로 + CLI만 사용.
---
## 무인 drain (선택)
```bash
KNOT_WIKI="$ROOT/knot-wiki" KNOT_RUNNER=claude bash tools/knot/run-knot.sh drain
```
`ops/scripts/launchd.plist.template` — cron/launchd 등록은 사용자 결정.
---
## 검증
```bash
bash tools/knot/run-knot.sh validate
python3 "$KNOT_WIKI/ops/scripts/lint.py" "$KNOT_WIKI"
```
ERROR 0 = 기계 검사 통과. **일상 운영 절차:** [`KNOT-WIKI-OPS-SOP.md`](./KNOT-WIKI-OPS-SOP.md).
---
## MAS 정본과의 관계
| 경로 | knot 관련 |
|------|-----------|
| `multi-agent-system/` | 하네스 정본 — knot **필수 아님** |
| `multi-agent-system/docs/learn/chapters/09-11-*.md` | **Learning Hub** 좌측 메뉴 ch09–11 |
| `multi-agent-system/docs/learn/manual.manifest.json` | Hub sidebar SSOT (ch09–11 항목) |
| `tools/knot/` | scaffold + install/run |
| `knot-wiki/` (LAB) | `.gitignore` — 로컬 vault (`schema/raw/wiki/ops`) |
| starter `templates/*/_shared/knot-bridge.md` | init.py 시 설치본에 복사 |
공개 문서 변환 코드 (HTML)
<h1>knot bridge — 지식 vault ↔ 하네스 연동</h1>
<blockquote>
<p><strong>현재 canonical vault 구조 (Phase 5b 완료):</strong> <code>schema/</code> · <code>raw/{inbox,archive,quarantine}</code> · <code>wiki/</code>(3문서) · <code>ops/</code>
<strong>knot</strong> = 벤더중립 장기 지식 vault (<code>KNOT_WIKI</code>)
<strong>하네스</strong> = 작업 단위 orchestration (<code>tasks/<task>/</code>)
정본: <a href="https://github.com/netwaif/knot">netwaif/knot</a> · MAS 도구: <code>tools/knot/</code></p>
</blockquote>
<hr>
<h2>역할 분리</h2>
<table>
<thead>
<tr>
<th></th>
<th><strong>하네스 (<code>tasks/</code>)</strong></th>
<th><strong>knot (<code>KNOT_WIKI</code>)</strong></th>
</tr>
</thead>
<tbody><tr>
<td>단위</td>
<td>bounded task (승인·검증·완료)</td>
<td>지속 wiki (ingest·query·lint)</td>
</tr>
<tr>
<td>메모리</td>
<td><code>context.md</code>, <code>log.md</code>, worker <code>result.md</code></td>
<td><code>wiki/</code>(3문서), <code>schema/index.md</code>, <code>raw/archive/</code></td>
</tr>
<tr>
<td>수명</td>
<td>task <code>status: done</code> 후 아카이브</td>
<td>누적·상호링크</td>
</tr>
<tr>
<td>워커</td>
<td>claude · codex · gemini (승인 게이트)</td>
<td>ingest/query/lint (<code>schema/schema.md</code> + <code>ops/prompts/</code>)</td>
</tr>
</tbody></table>
<p><strong>금지</strong>: knot ingest를 worker pool에 넣지 않는다 — 별도 vault 규약(<code>schema/schema.md</code>)이 우선한다.</p>
<hr>
<h2>언제 knot을 쓰는가</h2>
<table>
<thead>
<tr>
<th>상황</th>
<th>knot</th>
<th>하네스 task</th>
</tr>
</thead>
<tbody><tr>
<td>회의록·문서 md를 지식 그래프로 축적</td>
<td>✅ <code>raw/inbox/</code> → ingest</td>
<td>❌</td>
</tr>
<tr>
<td>"우리 vault에 X 관련 뭐 있지?"</td>
<td>✅ query</td>
<td>❌</td>
</tr>
<tr>
<td>기능 구현 + claude critique</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr>
<td>task 완료 후 <strong>재사용 가능한</strong> 일반 교훈</td>
<td>✅ <code>raw/inbox/</code>에 요약 md 넣고 ingest</td>
<td>✅ <code>_shared/learnings.md</code> (시스템 한정)</td>
</tr>
<tr>
<td>외부 repo 코드 수정</td>
<td>❌</td>
<td>✅ codex/claude worker</td>
</tr>
</tbody></table>
<hr>
<h2>설치 (LAB 1회)</h2>
<pre><code class="language-bash">cd ~/Desktop/MultiAgentSystem
bash tools/knot/install-knot-wiki.sh
# 기본: knot-wiki/ (repo 루트)
source tools/knot/env.example # KNOT_WIKI export
</code></pre>
<p>knot vault는 <strong>로컬 git</strong>만 사용(push 금지 — <code>schema/schema.md</code> 정본). MAS repo와 <strong>별도 디렉터리</strong> (<code>knot-wiki/</code>, <code>.gitignore</code>).</p>
<hr>
<h2>오케스트레이터 워크플로</h2>
<h3>A. task 시작 전 — 맥락 조회 (선택)</h3>
<pre><code class="language-bash">bash tools/knot/run-knot.sh query "이 task와 관련된 기존 지식 요약"
</code></pre>
<p>답변을 <code>tasks/<task>/context.md</code>에 <strong>한 줄 근거 링크</strong>만 넣는다(전문 paste 금지 — context 한도).</p>
<h3>B. task 완료 후 — 지식 승격 (선택)</h3>
<ol>
<li>재사용 가치 있는 합성을 md로 작성</li>
<li><code>$KNOT_WIKI/raw/inbox/</code>에 저장</li>
<li><code>bash tools/knot/run-knot.sh ingest</code> (또는 drain)</li>
<li><code>tasks/<task>/log.md</code>에 <code>[DECISION] knot ingest: raw/inbox/<file></code> append</li>
</ol>
<h3>C. 하네스 task로 knot ingest 위임 (명시적 task)</h3>
<p><code>_templates/knot-bridge-task.md</code> 템플릿으로 <code>tasks/knot-ingest-<name>/</code> 생성.
<code>workers_approved</code> 없이 <strong>오케스트레이터가 직접</strong> <code>run-knot.sh ingest</code> 실행 — worker 호출 아님.</p>
<hr>
<h2>flavor별 실행</h2>
<table>
<thead>
<tr>
<th>flavor</th>
<th>ingest 실행 예</th>
</tr>
</thead>
<tbody><tr>
<td><strong>codex</strong></td>
<td><code>KNOT_RUNNER=codex bash tools/knot/run-knot.sh ingest</code></td>
</tr>
<tr>
<td><strong>cursor</strong></td>
<td>동일 (Cursor agent shell에서 run-knot.sh OK)</td>
</tr>
<tr>
<td><strong>claude</strong></td>
<td><code>KNOT_RUNNER=claude bash tools/knot/run-knot.sh ingest</code></td>
</tr>
<tr>
<td><strong>antigravity</strong></td>
<td><code>KNOT_RUNNER=agy bash tools/knot/run-knot.sh ingest</code></td>
</tr>
</tbody></table>
<p>Codex flavor 하네스 MCP prune과 <strong>무관</strong> — knot은 vault 경로 + CLI만 사용.</p>
<hr>
<h2>무인 drain (선택)</h2>
<pre><code class="language-bash">KNOT_WIKI="$ROOT/knot-wiki" KNOT_RUNNER=claude bash tools/knot/run-knot.sh drain
</code></pre>
<p><code>ops/scripts/launchd.plist.template</code> — cron/launchd 등록은 사용자 결정.</p>
<hr>
<h2>검증</h2>
<pre><code class="language-bash">bash tools/knot/run-knot.sh validate
python3 "$KNOT_WIKI/ops/scripts/lint.py" "$KNOT_WIKI"
</code></pre>
<p>ERROR 0 = 기계 검사 통과. <strong>일상 운영 절차:</strong> <a href="./KNOT-WIKI-OPS-SOP.md"><code>KNOT-WIKI-OPS-SOP.md</code></a>.</p>
<hr>
<h2>MAS 정본과의 관계</h2>
<table>
<thead>
<tr>
<th>경로</th>
<th>knot 관련</th>
</tr>
</thead>
<tbody><tr>
<td><code>multi-agent-system/</code></td>
<td>하네스 정본 — knot <strong>필수 아님</strong></td>
</tr>
<tr>
<td><code>multi-agent-system/docs/learn/chapters/09-11-*.md</code></td>
<td><strong>Learning Hub</strong> 좌측 메뉴 ch09–11</td>
</tr>
<tr>
<td><code>multi-agent-system/docs/learn/manual.manifest.json</code></td>
<td>Hub sidebar SSOT (ch09–11 항목)</td>
</tr>
<tr>
<td><code>tools/knot/</code></td>
<td>scaffold + install/run</td>
</tr>
<tr>
<td><code>knot-wiki/</code> (LAB)</td>
<td><code>.gitignore</code> — 로컬 vault (<code>schema/raw/wiki/ops</code>)</td>
</tr>
<tr>
<td>starter <code>templates/*/_shared/knot-bridge.md</code></td>
<td>init.py 시 설치본에 복사</td>
</tr>
</tbody></table>