narrative

커밋에 결속된 프로젝트 지식 상태로 self-contained HTML 리포트를 생성합니다

무엇을 하는 명령인가

narrative는 선택된 snapshot history, commit에 결속된 문서, artifact record, event data를 읽어 self-contained HTML narrative report를 생성합니다. 이 리포트는 협업 과정을 처음부터 다시 훑지 않아도 프로젝트의 의도, 결정, 시간축을 이해해야 하는 신규 참여자나 에이전트를 위한 것입니다.

이 리포트의 canonical face는 Recovery View이며, Recover Now, What To Trust, How We Got Here의 3단 구조로 읽습니다.

운영 관점에서는 두 층으로 해석하시면 됩니다.

HTML 파일이 canonical report입니다.
--emit-model은 별도의 experimental OpenTUI viewer에 넣는 선택적 입력입니다.

언제 쓰는가 / 언제 쓰지 않는가

언제 쓰는가

프로젝트 결정이 어떻게 바뀌었는지 손쉽게 인수인계하고 싶을 때
raw log가 아니라 이야기 구조로 프로젝트 지식을 설명하고 싶을 때
CLI 밖에서도 열 수 있는 독립 HTML 산출물이 필요할 때

언제 쓰지 않는가

현재 저장소 요약만 필요할 때. status를 사용하십시오.
snapshot semantic delta가 필요할 때. log를 사용하십시오.
append-only 운영 이벤트가 필요할 때. timeline을 사용하십시오.
retrieval hit나 즉답형 질의가 필요할 때. query를 사용하십시오.

운영 절차

narrative는 아래 순서로 사용합니다.

먼저 canonical HTML report를 생성합니다.
로컬 터미널 탐색이 필요할 때만 --emit-model을 추가합니다.
model 파일이 생긴 뒤에만 tools/narrative-tui/에서 분리형 viewer를 실행합니다.

운영 성공 기준은 아래로 고정합니다.

HTML report가 생성되면 main task는 성공입니다.
viewer가 나중에 실패하더라도 그것은 explorer 실패일 뿐, narrative 생성 실패로 간주하지 않습니다.

기본 구문

pnpm ragit narrative [revRange] [--max-commits <n>] \
  [--output <path>] [--emit-model <path>] \
  [--open] [--dry-run] \
  [--format text|json|both] [--cwd <path>]

인자와 옵션

[revRange]: 선택적 git revision range입니다. 생략하면 HEAD를 사용합니다.
--max-commits <n>: 선택되는 snapshot commit 수를 제한합니다. 기본값은 10입니다.
--output <path>: 기본값 .ragit/reports/narrative/<anchorSha>.html 대신 지정 경로로 HTML 리포트를 저장합니다.
--emit-model <path>: 별도 viewer가 읽을 versioned viewer-safe narrative JSON model을 저장합니다. 이 옵션은 tools/narrative-tui/ 아래의 분리된 experimental OpenTUI explorer를 위한 것입니다.
--open: 생성된 리포트를 저장 후 기본 브라우저로 엽니다.
--dry-run: 파일을 쓰지 않고 리포트 계획과 요약만 계산합니다.
--format text|json|both: 사람이 읽는 text, JSON, 또는 둘 다를 선택합니다.
--cwd <path>: 다른 저장소를 대상으로 실행합니다.

입력/출력 계약

JSON payload 입력은 없습니다.
JSON 출력에는 dryRun, reportPath, modelPath, schemaVersion, projectionPolicyVersion, projectionMode, headSha, window, summary, warnings가 포함됩니다.
window에는 revRange, maxCommits, selectedSnapshotShas, missingSnapshotCommits가 들어 있습니다.
summary.freshnessCounts에는 ragit drift에서 계산된 fresh, suspect, stale 개수가 들어갑니다.
--dry-run도 planned report path, planned model path, summary는 반환하지만 두 파일 모두 실제로 쓰지는 않습니다.
--open은 dry-run에서는 무시되고 warning으로만 보고됩니다.
선택된 window에 manifest가 붙은 snapshot이 하나도 없어도, narrative는 empty-state report를 생성합니다.

Canonical HTML과 Experimental Viewer의 경계

self-contained HTML report가 canonical narrative 산출물입니다.
canonical narrative face는 Recover Now, What To Trust, How We Got Here로 구성된 Recovery View입니다.
--emit-model은 분리된 local OpenTUI explorer를 위한 viewer input일 뿐입니다.
emitted model은 versioned이며 viewer-safe projection을 따릅니다.
schemaVersion은 구조 호환성 키입니다.
projectionPolicyVersion은 public projection governance 호환성 키입니다.
projectionMode는 현재 viewer-safe로 고정됩니다.
producerVersion은 producer metadata일 뿐입니다.
현재 ragit narrative --emit-model은 versioned model과 versioned projection policy를 함께 씁니다. schemaVersion이 없는 legacy model은 viewer의 backward-compatible read 경로에서만 허용합니다.
viewer는 의도적으로 tools/narrative-tui/ 아래에 분리되어 있으며, .ragit나 git 상태를 직접 읽지 않습니다.
공유 가능한 결과만 필요하면 HTML만 생성하면 됩니다.

Recovery View

Recover Now는 현재 목표, 활성 제약, 열린 루프, 다음 행동, 가장 짧은 재진입 경로를 보여줍니다.
What To Trust는 projected memory state에서 나온 freshness, validation, trust badge를 보여줍니다.
How We Got Here는 lineage, formation step, drift 또는 repair, 그리고 현재 상태를 만든 근거를 압축해 보여줍니다.
Recovery View는 ragit의 기존 memory model을 다시 투영한 형상이며, 새로운 저장소나 별도 memory system을 만들지 않습니다.
active memory와 durable memory의 분리는 Memory Model Guide를 참고하십시오.

Freshness Overlay

narrative report는 trust, sensitivity, lineage와 별도의 freshness 축을 가집니다.
freshness는 ragit drift를 재사용해 계산하며 fresh, suspect, stale만 사용합니다.
fresh는 선택된 snapshot window와 현재 결속이 맞는 상태를 뜻합니다.
suspect는 baseline, binding, evidence가 불완전한 상태를 뜻합니다.
stale은 경로, 결속, 의존성이 drift된 상태를 뜻합니다.
freshness는 projected narrative model과 HTML report에 반영되며, OpenTUI viewer는 이 상태를 소비만 하고 drift를 다시 계산하지 않습니다.

Validation Overlay

narrative report는 freshness, trust, sensitivity, lineage와 별도의 validation 축도 가집니다.
validation은 harness/drift assets에서 파생되며 verified, attention, unverified로 현재 검증 자세를 표현합니다.
verified는 하네스/증거 맥락이 있고 현재 검증 우려가 없는 상태입니다.
attention은 drift 또는 failure evidence에서 온 검증 경고가 있는 상태입니다.
unverified는 아직 충분한 검증 맥락이 없어 확정 분류를 하지 않은 상태입니다.
validation은 전체 검증 연대기가 아니라 현재 posture를 설명합니다.
validation은 projected narrative model과 HTML report에 반영되며, OpenTUI viewer는 이 상태를 소비만 하고 다시 계산하지 않습니다.
HTML report에는 별도의 Validation Panel이 있고, OpenTUI 오른쪽 rail은 Intent | Validation | Timeline입니다.

Projection Governance

emitted model에는 viewer-safe projected field만 포함됩니다.
binding metadata는 raw goal/session 식별자 대신 count 형태로만 노출됩니다.
trust badge는 durable-doc, reviewed-artifact, promoted-artifact, operational-event를 구분합니다.
sensitivity badge는 standard, redacted, restricted를 구분합니다.
freshness badge는 fresh, suspect, stale를 구분하며 ragit drift에서 나온 별도 축입니다.
restricted는 숨겨진 binding 상태를 raw 값이 아니라 safe projected summary로만 보여준다는 뜻입니다.

대표 사용 예시

기본 narrative report 생성:

pnpm ragit narrative

window를 제한하고 결과를 열기:

pnpm ragit narrative HEAD~20..HEAD --max-commits 5 --open

JSON으로 report plan 미리 보기:

pnpm ragit narrative --dry-run --format json

HTML과 sanitized model을 함께 만든 뒤 experimental local explorer 열기:

pnpm ragit narrative --emit-model .ragit/reports/narrative/current.model.json
cd tools/narrative-tui
bun run start -- --model ../../.ragit/reports/narrative/current.model.json

실패/주의 사항

--output은 파일을 쓰므로 상위 디렉터리에 쓰기 권한이 있어야 합니다.
--emit-model도 파일을 쓰며, canonical HTML을 대체하지 않는 viewer input으로만 취급해야 합니다.
emitted model의 schemaVersion 또는 projectionPolicyVersion이 viewer와 맞지 않아도, HTML report가 이미 생성되었다면 narrative의 canonical 산출은 성공한 것입니다.
이 리포트는 raw transcript가 아니라 snapshot-backed knowledge를 기반으로 생성됩니다.
--open은 best-effort이며, 현재 머신에 opener가 없으면 건너뛸 수 있습니다.
선택된 window에 snapshot manifest가 없더라도 command는 실패하지 않고 empty-state report로 성공합니다.