정합성과 내역 뷰

VMark의 정합성 레이어는 재귀적으로 발전하는 글쓰기 프로젝트를 정직하게 유지합니다. 각 AI 생성이 실제로 어떤 문서를 읽었는지 기록하고, 그 업스트림 문서가 이후에 변경되면 이를 알아차리며, 어떤 다운스트림 아티팩트가 이제 오래되었을 수 있는지를 — 요청 시에만 — 정확히 보여줍니다. 아무것도 자동으로 업데이트되지 않습니다. 편집장은 언제나 당신입니다.

작동 방식 (30초 요약)

• 출처 추적은 선택 사항입니다. 먼저 설정 → 파일 및 이미지 → 저장 → 저장 시 식별 블록 기록 을 켜세요. 켜기 전까지는 저장, 지니 적용, 수락된 AI 제안, MCP 쓰기, 이전 버전 복원, 파일 탐색기에서 만든 새 파일 등 어떤 쓰기도 파일에 식별 블록을 넣거나 .vmark/를 만들지 않습니다.
• 설정을 켜면 모든 저장, 지니 적용, 수락된 AI 제안, MCP 쓰기, 이전 버전 복원, 워크플로 save-file 단계는 워크스페이스 내부의 일반 텍스트 원장에 변환 으로 기록됩니다 (.vmark/ — git 친화적이고 사람이 읽을 수 있는 JSONL; 파생된 index.db를 삭제해도 아무것도 잃지 않습니다).
• 이미 원장이 있는 워크스페이스 — 이전에 만든 .vmark/나 공동 작업자가 커밋한 .vmark/ — 는 설정이 꺼져 있어도 추적 중인 문서에 대한 쓰기를 계속 기록합니다. 원장이 이전에 기록한 적이 있는 문서, 또는 파일이 이미 자체 vmark: 식별 블록을 지닌 문서(옮기거나 복사해 넣거나 체크아웃한 추적 파일 등)가 추적 중인 문서로 간주되며, 원장 자체의 스캔이 받아들이는 것도 바로 이런 문서입니다. 식별 블록은 넣지 않습니다. 식별 블록이 없는 문서는 제외되며, 그 때문에 입력이 불완전해진 쓰기는 exact 대신 inferred 로 기록됩니다.
• AI가 다른 문서들을 읽으면서 한 문서를 쓰면, 그 읽기는 읽은 시점의 리비전에 고정된 의존성 엣지 가 됩니다. 앱 내부의 계측된 경로는 exact 입력을 기록하고, MCP 쓰기는 세션에서 관찰된 읽기 집합을 inferred 로 정직하게 기록합니다.
• 업스트림 문서가 고정된 리비전을 지나 앞으로 나아가면 해당 엣지는 지남 (stale) 상태가 됩니다. 두 리비전이 병렬로 발전했다면 (예: git 브랜치에서) 엣지는 분기됨 (diverged) 상태가 됩니다 — 추측하지 않고 드러내기만 합니다.
• VMark 외부에서 (터미널, 다른 편집기) 편집된 파일은 스캔 시 관찰된 외부 편집 으로 조정됩니다 — 기록은 공백 없이 유지되며, 출처 불명으로 정직하게 표시됩니다.

내역 뷰

창 → 정합성 내역 (또는 명령 팔레트: "Breakdown View")에서 엽니다. 이 뷰는 철저히 풀 기반 입니다: 뷰를 열거나 새로 고침을 누를 때만 갱신되며, 백그라운드에서 재촉하는 일이 없습니다.

항목은 아티팩트 (다운스트림 문서) 별로 그룹화되며, 업스트림 문서, 고정된 리비전, 현재 상태를 보여줍니다:

상태	의미
version-stale	이 아티팩트의 기반이 된 시점을 지나 업스트림이 앞으로 나아감
diverged	고정된 리비전과 현재 리비전이 병렬 관계 — 계보가 이어지지 않음
diverged-multi-head	업스트림 자체에 병렬 현행 버전이 존재함
waived	사유를 기록하고 분기를 수용함
unpinnable	업스트림을 확인할 수 없음 (예: 잘못된 고정)

액션

각 항목은 세 가지 정직한 액션을 제공하며, 어느 것도 기록을 다시 쓰지 않습니다:

• 최신 버전 수용 — 아티팩트가 더 새로운 업스트림과 여전히 호환된다고 기록합니다 (추인). 항목은 목록에서 사라지며, 업스트림이 다시 변경되면 돌아옵니다.
• 수정 — 아티팩트를 열어 직접 업데이트할 수 있게 합니다. 새 버전을 저장하면 이전 엣지는 물러납니다.
• 면제 — 필수 사유 와 함께 의도적인 분기를 기록합니다 (신뢰할 수 없는 서술자는 존재하기 마련입니다). v0에서 면제는 의도적으로 범위가 좁습니다: 이 엣지와, 면제가 기준으로 삼는 특정 업스트림 리비전에만 적용됩니다. 면제된 항목은 뚜렷하게 구분되어 계속 표시되며, 업스트림이 다시 움직이면 다시 열립니다.

업스트림에 여러 현행 버전이 있으면 최신 버전 수용과 면제는 비활성화됩니다 — 해결의 기준이 될 단일 리비전이 없기 때문입니다. 먼저 수정하거나 버전들을 조정하세요.

필요 없는 알림 줄이기

내역의 각 행에 있는 두 가지 컨트롤로 레이어가 묻는 범위를 좁힐 수 있습니다. 둘 다 사람 전용이며 — 어떤 MCP 도구도 이를 설정할 수 없습니다.

완료로 표시 (문서 수명 주기). 다운스트림 문서가 끝났다면 — 출간된 챕터, 전달된 보고서처럼 — 그 문서의 아무 행에서나 완료로 표시 를 선택하세요. 그 문서로 향하는 모든 의존성이 알림에서 제외되며, 현재 목록에 없는 것까지 포함되므로 확인을 거칩니다. 해당 엣지는 패널 하단의 접힌 묻지 않는 항목 그룹으로 옮겨지고 완료된 문서 라는 레이블이 붙습니다: 여전히 추적되고, 요청하면 여전히 보이며, 다만 더 이상 방해하지 않을 뿐입니다. 다시 열기 는 확인 없이 클릭 한 번으로 되돌립니다 — 다시 여는 것은 알림을 되살릴 뿐이기 때문입니다. 수명 주기는 프런트매터가 아니라 원장에 기록되므로, 문서를 완료로 표시해도 그 문서의 새 리비전이 만들어지지 않습니다.

섹션 고정. 고정되지 않은 엣지는 "업스트림 파일이 바뀌었는가?"를 묻습니다. 섹션에 고정 은 이를 "내가 의존하는 섹션이 바뀌었는가?"로 좁힙니다: 업스트림 문서에서 제목 하나를 고르면 엣지가 그 제목 경로에 고정됩니다. 고정된 섹션이 그대로인 동안에는 다른 곳의 업스트림 편집이 있어도 엣지는 의존하는 섹션이 변경되지 않음 으로 제외 그룹에 남습니다. 섹션 안에서 편집이 일어나면 고정된 섹션이 변경됨 으로 드러납니다. 제목이 사라지면 엣지는 조용히 파일 전체 동작으로 돌아가는 대신 고정 위치를 잃음 으로 표시됩니다. 고정 위치 변경 은 다시 고정하고, 파일 전체 는 고정을 해제합니다. 고정은 그 자체로 수정 가능한 원장 항목이므로, 이후 리비전에서도 엣지를 따라갑니다.

일관성 로그와 알림 판정

일관성 로그(내역 패널 안의 펼침 영역)는 원장이 보관하는 엣지별 기록입니다: 모든 검사, 추인, 면제, 각 엣지가 몇 번 해결되었는지(3회 해결), 그리고 두 번 이상 해결된 엣지가 몇 개인지 — 이 반복(churn)이야말로 시끄러운 의존성 그래프의 실제 부담입니다. 모델이 신뢰도 기준 미만으로 답한 의미 검사는 보존된 판정과 신뢰도와 함께 표시되므로(모델 답변 … (신뢰도 …), 임계값 미만), "신호 없음"과 "답은 했지만 충분히 확신하지 못함"이 계속 구별됩니다. 로그는 원장 전체에서 읽어 오므로, 펼칠 때만 로드되고 펼칠 때마다 다시 로드됩니다.

알릴 만했나요? 드러난 각 행은 알릴 만했나요? 를 제공하며, 답은 예, 아니오, 모르겠음 세 가지이고 — 의도적으로 기본값이 없습니다. 답은 그 자체로 원장 항목으로 기록되고 로그에 집계됩니다(판정: 관련 … · 노이즈 … · 불확실 … · 미판정 …). 이것이 레이어가 조정의 기준으로 삼는 오래됨-관련성 지표입니다: 노이즈로 판정한 알림은 섹션 고정이나 완료 표시의 후보입니다.

의미 검사, 설정, 컨텍스트

버전이 지났다는 것은 업스트림이 움직였다는 뜻일 뿐입니다. 의미 검사는 그 움직임이 파생 문서와 실제로 모순되는지를 알려줍니다. 검사는 철저히 풀 기반 입니다: 지난 엣지에서 검사 를 누르면 VMark가 구성된 AI 제공자에게 고정된 업스트림 리비전, 현재 리비전, 파생 텍스트를 비교해 달라고 요청합니다. 판정은 배지로 표시됩니다 — 검증됨(유효), 모순됨 (항상 원문 그대로의 근거 인용과 함께), 그리고 모델이 확신하지 못했거나, 시간이 초과되었거나, 확신도 기준에 못 미치는 답을 한 경우의 미검증입니다. 알 수 없음은 정직함이며, 결코 숨겨지지 않습니다. 검사는 두 문서 중 하나가 다시 움직이는 순간 — 또는 설정 집합이 바뀌는 순간 만료됩니다.

캐논 설정 은 당신이 명시적으로 만든 사실입니다 ("엘레나는 왼손잡이다"). 문서에서 텍스트를 선택하고 선택 영역에서 설정 추출 을 실행하면, 설정은 출처 (어느 문서, 어느 리비전) 와 함께 초안 으로 태어납니다. 설정을 보고 관리하려면 명령 팔레트에서 캐논 설정을 실행하세요 — 이 패널에는 메뉴 항목이나 단축키가 없으며, 선택 영역에서 설정 추출 을 실행하면 새 초안과 함께 패널이 열립니다. 설정이 캐논이 되면 확립됨 으로 승격하세요 — 의미 검사에 투입되는 것은 확립된 설정뿐입니다. 설정을 정정하거나 종료하면 기록이 덧붙습니다. 아무것도 삭제되지 않습니다. 컨텍스트에서 설정을 숨기는 것은 되돌릴 수 있는 가시성 조작이지, 종료가 아닙니다.

컨텍스트 는 워크스페이스의 이름 붙은 뷰입니다 (default 컨텍스트는 항상 존재합니다). 각 컨텍스트는 "현재"가 무엇을 의미하는지, 어떤 설정이 적용되는지를 선택합니다. 자식 컨텍스트는 부모의 설정을 가산적으로 상속합니다. 컨텍스트는 기본적으로 온실 입니다 — 검사 판정은 조언 성격의 긴장으로 읽힙니다. 컨텍스트를 강제 적용 으로 전환하면 (명시적이고 확인을 거치는 행위) 모순이 캐논 위반으로 표시됩니다. 내역 뷰의 컨텍스트 선택기는 어떤 컨텍스트를 통해 볼지 정합니다. 검사 결과는 그것을 만들어 낸 바로 그 컨텍스트와 설정 스냅숏에 묶이며, 결코 다른 곳으로 새지 않습니다.

출처, 위임, 브랜치

프로젝트가 실제로 진화하는 동안 정합성 레이어를 정직하게 유지해 주는 것이 세 가지 있습니다 — 어느 것도 재촉하지 않고, 모두 풀(pull) 방식입니다.

출처 복구. 파생 문서를 직접 손으로 편집하면 (VMark에서든 외부 편집기에서든), 그 편집은 기록된 입력을 당연히 잃습니다 — 예전의 의존성 엣지는 더 이상 새 텍스트를 설명하지 못합니다. 내역의 출처 불명 그룹이 그것을 복원하도록 제안합니다: 입력 제안 을 누르면 VMark가 그 문서의 가장 최근 이전 입력 집합을 (역할은 보존한 채) 미리 선택되고 편집 가능한 상태로 제안합니다. 출처 확정 은 새 리비전을 만들지 않고 엣지를 현재 버전에 다시 붙이므로, 그 문서 자신의 다운스트림은 엉뚱한 변경을 결코 보지 않습니다. 애초에 입력이 없었던 문서는 결코 나열되지 않습니다 — 복구할 것도 없고 재촉할 것도 없습니다.

에이전트 위임. 기본적으로는 오직 당신만 오래된 엣지를 해소할 수 있습니다. AI 에이전트가 당신을 대신해 최신 버전을 수용하거나 면제하도록 하고 싶다면 (coherence_resolve MCP 도구를 통해), 내역에서 기간 제한 위임 을 부여하세요: 에이전트의 이름을 정하고, 범위(최신 버전 수용 및/또는 면제)를 고르고, 만료를 설정합니다 (기본값 7일, 결코 "영구"는 아님). 위임된 모든 해소는 그 부여에 기록되므로, 감사 추적은 누구의 권한 아래 누가 행동했는지를 항상 보여 줍니다. 어떤 부여든 클릭 한 번으로 철회할 수 있습니다. 캐논 설정과 컨텍스트는 사람 전용으로 남습니다 — 에이전트는 결코 설정을 승격하거나 컨텍스트를 강제할 수 없습니다.

브랜치 컨텍스트. 컨텍스트는 git 브랜치에 매핑될 수 있습니다. 매핑된 브랜치를 체크아웃하면, 내역은 전환을 제안하는 후보 칩 을 보여 줍니다 — 스스로 전환하는 일은 결코 없습니다. 브랜치에 아직 컨텍스트가 없으면, 칩은 그 이름을 딴 컨텍스트를 만들자고 제안합니다. (fast-forward가 아닌) 진짜 병합이 들어오면, 닫을 수 있는 배너가 내역을 검토하라고 권합니다. 배너가 드러내는 분기와 오래됨은 내역의 정상적인 상태이므로, 새로 실행되는 것은 없습니다 — 그저 검토로 안내될 뿐입니다.

프런트매터 식별자

저장 시 식별 블록 기록 을 켜 두면, 파일이 처음 캡처될 때 VMark는 프런트매터에 작은 식별 블록을 추가합니다:

vmark:
  id: 018f3c7a-9f2e-7cc1-b302-5e9d4a6b21c7

이 ID 덕분에 문서는 이름 변경과 이동을 거쳐도 자신의 역사를 유지합니다. 콘텐츠 해싱에는 전혀 영향을 주지 않으며 (추가해도 "변경"이 생기지 않음), 프런트매터의 나머지는 그대로 유지됩니다. 파일을 복사하면 중복된 ID가 감지되어 직접 해결하도록 표시됩니다 — 자동으로 고쳐지지 않습니다.

VMark가 파일을 절대 건드리지 않기를 원한다면 저장 시 식별 블록 기록 을 끈 상태로 두세요 — 이것이 기본값입니다. 끈 상태에서는 파일이 어떤 방식으로 쓰이든, AI나 MCP 편집이 읽기만 한 파일이든, VMark가 이 블록을 추가하지 않습니다.

Git 상호 운용성

• .vmark/ 원장 파일은 git으로 추적되며 브랜치 간에 깔끔하게 병합됩니다 (append 전용, merge=union).
• 체크아웃, 브랜치 전환, 리셋은 탐색 으로 인식됩니다 — 유령 리비전을 만들지 않습니다.
• git revert와 새 콘텐츠를 만드는 병합은 git에 귀속된 변환으로 캡처됩니다.
• 파생 인덱스 (index.db)는 gitignore 처리되며 필요할 때마다 일반 텍스트 원장에서 다시 빌드됩니다.

AI 에이전트용 (MCP)

외부 에이전트는 VMark에서 연 워크스페이스에 대해 coherence MCP 도구 (status, edges, claims, contexts 액션)를 통해 정합성 상태를 조회할 수 있습니다. status는 순수 읽기입니다. edges는 먼저 조정을 수행합니다 — 워크스페이스 자체 원장에 출처 기록을 추가할 수는 있지만, 당신의 문서는 절대 건드리지 않습니다. 이 도구는 readOnlyHint: true를 선언하므로, 클라이언트가 자동으로 승인할 수 있습니다.

해결 (추인/면제)은 별도의 도구인 coherence_resolve에 있으며, 기본적으로 사람에게 남습니다: 에이전트는 당신이 그 특정 에이전트에게 기간 제한 위임을 부여한 뒤에만 이를 호출할 수 있고, 모든 해결은 그 부여에 대해 감사 기록으로 남습니다. 이 도구를 coherence와 분리해 두었기 때문에, 에이전트가 원장에 쓰는 능력을 몰래 얻지 않고도 읽기 도구를 자동 승인할 수 있습니다.

캐논 설정과 컨텍스트는 MCP를 통해서는 전혀 변경할 수 없습니다.