SSOT와 Derived Knowledge 향상 보고서

보고서 목적

이 보고서는 Sanctum LLM 운영에서 무엇을 SSOT로 인정하고 무엇을 Derived Knowledge 또는 Derived Index로 격리할지 결정한다. 목표는 LLM worker가 보기 좋은 요약, Graphify graph, RAG 검색 결과, 과거 thread summary를 canonical fact처럼 믿는 일을 막는 것이다.

핵심 결론

Sanctum의 SSOT는 사람이 검토하고 유지하는 canonical 문서와 현재 source/contract에 있어야 한다. contracts/는 service-to-service contract의 강한 SSOT 후보다. 그러나 contracts/만으로 worker 실행 문맥은 부족하므로 각 서비스에 AGENTS.md와 llm-context/ pack을 둔다.

Graphify와 RAG는 Derived Index다. LLM Wiki와 generated summary는 Derived Knowledge다. 둘 다 planning과 탐색에는 유용하지만 write authorization이나 canonical fact 판정에는 사용할 수 없다.

원본 문서의 주요 내용

지식 계층은 다음처럼 나뉜다.

SSOT: canonical docs, contracts, checked-in source, service AGENTS.md
  -> Derived Knowledge: 검증된 결론, 운영 판단, flow 해석, worker guidance
  -> Derived Index: Graphify graph, RAG embeddings/index, generated summaries
  -> LLM working context: 특정 작업 수행을 위한 임시 prompt/context

SSOT 후보는 contracts/, service AGENTS.md, service llm-context/service.md, commands.md, test-scope.md, e2e-role.md, approved runbook, current source code다. llm-context/contracts.md는 계약 내용 자체의 SSOT가 아니라 canonical contract로 가는 mapping SSOT다.

Derived Knowledge는 최소한 다음 metadata를 가져야 한다.

knowledge_type: derived
scope: <service-or-flow-or-repo>
source_truth: []
source_observations: []
confidence: low|medium|high
validation_state: draft|validated|stale|retired
stale_when: []
allowed_use: []
not_allowed_use: []
owner: <team-or-role>

Graphify/RAG index에는 generated_at, commit, branch, scan roots, ignore policy, source map, known limitations, status: derived_index_not_ssot가 필요하다.

Sanctum 적용 해석

Sanctum에서 SSOT는 하나의 문서가 아니라 역할별 canonical source의 집합이다. 예를 들어 contracts/는 contract SSOT지만 wallet-api worker의 테스트 명령, 허용 write scope, dependency stub 정책까지 책임지지 않는다. 따라서 wallet-api, kms-api, hd-manager, rust-mpc/mpc-manager-rs, rust-mpc/party-node-rs 각각에 다음 구조가 필요하다.

<service>/
  AGENTS.md
  llm-context/
    service.md
    commands.md
    test-scope.md
    e2e-role.md
    contracts.md
    dependency-stubs.md

Derived Knowledge는 wallet-api 변경이 kms-api key operation contract에 미치는 영향, hd-manager derivation 변경의 lifecycle 영향, mpc-manager-rs와 party-node-rs compatibility checklist, root Graphify graph pilot 판단, Codex App workspace limit correction 등을 담을 수 있다. 그러나 이 지식은 planning aid이며 write authorization이 아니다.

운영 판단

충돌 시 우선순위는 다음이다.

승인된 canonical SSOT: contracts/, AGENTS.md, approved runbook, architecture decision
현재 파일 시스템의 source code와 tests
validated Derived Knowledge
RAG 검색 결과
Graphify navigation result
unreviewed generated summary

이 순서는 충돌 시 신뢰 우선순위다. 실제 작업에서는 Graphify로 후보를 좁히고 RAG로 evidence를 모은 뒤 SSOT와 current source로 확정하는 흐름이 효율적이다.

리스크와 가드레일

리스크	설명	가드레일
Derived Knowledge가 shadow SSOT가 됨	자세한 wiki note가 canonical처럼 사용됨	`knowledge_type: derived`, `not_allowed_use`, source_truth, stale_when 필수
`contracts.md`가 contract 복제본이 됨	field detail 중복으로 `contracts/`와 drift	mapping only, snapshot이면 commit과 stale condition 기록
confidence를 권한으로 오해	high confidence note가 다른 서비스 write를 정당화	confidence는 planning 신뢰도일 뿐 write는 allowlist가 결정
validation_state 미연동	stale note가 계속 사용됨	stale/retired는 final recommendation 근거 사용 금지
index metadata 부족	Graphify/RAG가 어느 revision인지 모름	commit, branch, generated_at, scan root, source map 필수
Codex App boundary 과신	workspace 분리가 hard enforcement로 오해됨	enforced worker는 sparse worktree/container/runtime diff guard 사용

실행 체크리스트

contracts/를 contract SSOT로 선언하고 owner/review path를 명시한다.
service AGENTS.md에 write/read/propose-only boundary와 handoff rule을 작성한다.
service llm-context/에 service, commands, test-scope, e2e-role, contracts, dependency-stubs 문서를 둔다.
contracts.md는 canonical path, service impact, validation command만 담는다.
Derived Knowledge template을 도입한다.
Graphify/RAG index metadata에 derived_index_not_ssot 상태를 포함한다.
worker가 write 전 canonical file 또는 current source를 직접 확인하게 한다.
stale condition 발생 시 wiki/RAG/Graphify 갱신 또는 handoff를 남긴다.