원격 Vault 묶음 저장 계약
한 사용자 작업의 관련 변경을 한 묶음으로 검토하고 한 GitHub commit으로 확정한다. 생성·수정·삭제 모두 같은 절차를 사용한다. 운영 위치와 복구 자료는 원격 Vault 운영 전환에서 확인한다.
작업과 검토
- 최신 정본과 VAULT_RULES.md 및 해당 작업 계약을 읽고 작업 범위를 정한다.
- vault_batch_start에 고유 batch_id, 작업을 설명하는 title, 최신 expected_commit을 전달한다. title은 최종 commit 제목이다.
- vault_batch_stage로 create/update/delete를 누적한다. 한 호출에서 최대 20개 변경을 누적한다. expected_version과 고유 mutation_id를 사용하고, 응답 유실 시 동일 입력으로 재시도한다. 같은 문서를 여러 번 수정하면 최종 결과만 남는다. 새로 만든 문서를 삭제하면 그 변경은 사라진다. revert는 해당 문서의 초안만 취소한다.
- vault_batch_review의 next_cursor가 없어질 때까지 전체 diff와 삭제 링크 영향 페이지를 읽는다. 사용자에게 변경 목록·이유와 전체 diff를 검토할 수 있는 형태로 제시한다. 마지막 페이지에서 review_token을 받는다.
- 대화에서 승인된 범위와 버전을 vault_batch_commit으로 확정한다. 이미 구체적인 변경 범위의 실행 승인이 있으면 같은 승인을 반복 요청하지 않는다. 승인 후 대상·내용이 달라지면 변경점을 다시 보여준다.
- APPLIED의 실제 commit·diff와 정본 재조회로 저장을 확인한다. 초안 stage 성공을 정본 저장 완료라고 보고하지 않는다.
기술적 호출 제한 때문에 한 사용자 작업을 작은 commit들로 임의 분할하지 않는다. 최종 변경이 300개 경로 또는 새 본문 4 MiB를 넘으면 의미 있는 작업 경계를 사용자와 정한 뒤 분리한다.
review_token은 전체 검토 페이지의 조회와 내용 버전 일치를 확인한다. 사람이 실제로 읽었거나 승인했다는 서버 증명은 아니다. 사용자 승인은 대화에서 확인한다.
이어가기·충돌·취소
vault_batch_list로 묶음을 찾고 vault_batch_get으로 상태를 확인한다. path를 함께 지정하면 정본에 초안 변경을 적용한 본문을 읽으며 content:null은 초안에서 삭제된 문서다. 일반 vault_read/list/search는 계속 GitHub 정본을 읽는다. 다른 클라이언트에서도 같은 Auth0 사용자로 접근하면 같은 AWS 묶음을 이어갈 수 있다.
초안 버전 충돌이면 batch_get으로 최신 상태를 대조한다. 마지막 stage 또는 rebase의 동일 mutation_id·동일 입력은 재시도할 수 있으며, 더 나중 변경이 진행된 옛 버전은 다시 대조한다.
정본이 바뀌면 commit은 REVISION_CONFLICT로 거부한다. vault_batch_rebase에 최신 expected_commit을 전달한다. 같은 문서의 변경이 겹치면 REBASE_CONFLICT의 경로를 읽고 새 정본 기준 create/update/delete 해소안을 resolutions로 전달한다. 자동으로 덮어쓰지 않으며 rebase 후 전체 diff를 다시 검토한다.
draft는 vault_batch_cancel로 취소한다. committing 상태는 결과가 불확실할 수 있으므로 편집·취소하지 않고 같은 commit 입력으로 재시도한다. GitHub 영수증을 대조해 이미 반영된 commit을 재사용한다. 확정된 문서를 되돌릴 때는 새 작업 묶음으로 필요한 본문을 복원한다.
삭제와 복구
삭제 전 문서와 참조 관계를 읽고 삭제 이유·영향을 검토한다. 관련 링크 수정은 같은 묶음에 넣을 수 있다. 서버의 참조 검사는 허용 Markdown에서 해석되는 위키 링크 범위다. 학습자 성찰 본문(learner-owned/와 이전 learner-reflection.md), 일반 Markdown 링크, 단순 언급, 외부 Vault는 자동 검사 범위에 포함하지 않으며 결과에 검사 범위를 표시한다. 참조가 남았다는 이유만으로 자동 수정하거나 연쇄 삭제하지 않는다.
삭제 전 base_commit에서 본문을 읽고 새 묶음에 create하면 복구할 수 있다. 같은 경로에 문서가 생겼으면 덮어쓰지 않고 대조한다. 삭제된 본문은 Git 이력에 남으며, 이력까지 없애는 영구 삭제는 별도 관리자 작업이다.
저장과 운영 경계
초안은 비공개 AWS S3에 저장하고 GitHub에는 확정할 때만 기록한다. 문서당 새 본문 256 KiB, 최종 변경 300개 경로·4 MiB 제한과 허용 Markdown 경로를 유지한다. 생성은 기존 문서가 있으면, 수정·삭제는 대상이 없으면 거부한다. OAuth 읽기 권한으로 초안을 조회·검토하고, 생성·편집·취소·rebase·확정에는 읽기와 쓰기 권한을 요구한다.
초안을 자동 만료시키지 않는다. 취소는 초안 본문을 비우고 상태를 남긴다. 확정된 묶음은 같은 입력의 재시도 확인을 위해 보관한다. S3와 GitHub는 서로 다른 저장소이므로 GitHub 반영 후 S3 상태 기록이 실패할 수 있다. 이때 APPLIED commit과 상태 동기화 안내를 구분하고 같은 요청으로 동기화한다.
이전 즉시 저장 도구 vault_apply_changes를 사용하지 않는다. 오래 열린 클라이언트가 옛 도구 목록을 보이면 MCP 재연결 또는 새 대화에서 batch 도구 목록을 갱신한다. 구형 로컬 stdio 서버는 이 묶음 절차를 구현하지 않았으므로 일상 쓰기용으로 되돌리지 않는다.