공개 근거 관리 가이드

/5240lab은 저장소 원본을 런타임에 읽지 않는다. 관리자가 content/evidence.json에 공개 후보를 선별하면 빌드 전 검증기가 5240lab 워크스페이스의 실제 파일과 대조하고, 통과한 최소 필드만 content/generated/evidence.public.json에 원자적으로 생성한다. 페이지는 이 공개 스냅샷과 content/layers.ts만 가져온다.

근거 추가·수정 순서

입증하려는 주장 하나와 가장 짧은 원본 행 범위를 고른다. 근거 유형은 문서상 요구인 policy, 코드가 위반을 차단하는 enforced, 실제 수행 결과인 execution 중 하나여야 한다.
5240lab 루트 기준 POSIX 상대 sourcePath와 정확한 startLine, endLine을 기록한다. 절대 경로, .., 역슬래시, 심볼릭 링크 경계 이탈은 허용하지 않는다.
선택한 행 전체를 expectedExcerpt에 그대로 복사한다. 검증기는 원본과 manifest 양쪽의 CRLF와 단독 CR을 LF로 바꾼 뒤 선택 행 문자열의 완전 일치를 검사한다. 그 외 공백, 들여쓰기, Markdown 표기와 줄 끝은 보존한다. 선택 범위 앞뒤 각 2행도 공개 안전성만 검사하며 이 주변 내용은 snapshot에 노출하지 않는다.
summary에는 그 발췌가 직접 입증하는 범위만 쓴다. 정책을 자동 강제로, 한 번의 실행 기록을 루트 전체 적용으로 과장하지 않는다.
verifiedOn을 실제 대조일로 바꾸고 content/release.json의 evidenceStatus: verified, evidenceVerifiedOn을 같은 날짜로 선별 갱신한다.
npm run verify:evidence를 실행하고 생성 스냅샷을 직접 검토한다. 이어서 unit, integration, browser, typecheck, lint, build를 실행한다. npm run build도 verify:evidence를 선행 실행한다.

안정 ID는 kebab-case이며 재정렬이나 제목 변경만으로 바꾸지 않는다. 한 범위는 최대 40행, 공개 발췌는 최대 400자다. 같은 사실을 새 근거로 교체할 때 기존 ID를 유지할 수 있는지는 의미가 동일한지 먼저 판단한다.

공개 안전성 검토

자동 검사는 다음 항목을 거부한다.

사용자 홈, 시스템 설정, 애플리케이션 설치, 임시·로그 영역을 가리키는 서버 절대 경로. /guide 같은 공개 사이트 route는 허용한다.
private key marker, Authorization/Bearer 값
token, password, secret, API key, DATABASE_URL 형태의 값 할당
PostgreSQL, MySQL, MongoDB 연결 URL
이메일 주소, 사설·loopback IP, 외부·라이브 URL
400자를 넘는 과도한 발췌

개념을 설명하는 secrets 정책 같은 표현 자체는 금지하지 않는다. 자동 패턴에 걸리지 않아도 개인 이름, 고객 식별자, 내부 호스트명, 명령 출력의 자격 증명, 환경변수 값, 운영 URL이 없는지 사람이 생성 JSON을 다시 읽어야 한다. 원본 전체, 절대 원본 경로, GitHub 링크나 운영 링크를 공개 스냅샷에 추가하지 않는다.

실패와 복구

verify:evidence 실패 시 메시지의 안정 ID부터 찾는다.

원본 파일이 없거나 읽을 수 없습니다: 파일 이동 여부를 확인하고 상대 경로를 새 위치로 갱신한다.
발췌가 expectedExcerpt와 정확히 일치하지 않습니다: 원본 변경을 검토한다. 단순히 새 문자열을 복사하기 전에 기존 claim이 여전히 성립하는지 다시 판정한다.
워크스페이스 경계를 벗어납니다: 심볼릭 링크와 실경로를 확인한다. 경계 검사를 우회하지 말고 워크스페이스 안의 추적 가능한 원본을 고른다.
공개 안전 금지 패턴: 더 짧고 안전한 행을 고르거나 공개 claim을 제거한다. 실제 값을 마스킹한 가공 문장을 원본인 것처럼 만들지 않는다.
release 날짜 불일치: snapshot을 임의 편집하지 말고 manifest와 선별 release metadata를 같은 실제 검증일로 맞춘다.

검증기는 모든 항목과 release metadata가 통과하기 전에 임시 파일을 만들지 않으며, 쓰기 중 실패하면 임시 파일을 제거한다. 따라서 실패해도 기존 공개 snapshot은 유지된다. 생성 JSON을 수동 수정하지 말고 manifest 또는 원본을 고친 뒤 다시 생성한다.

생성된 snapshot과 각 item의 status는 모두 verified여야 한다. item status가 없거나 다른 값이면 런타임 콘텐츠 계약 검증도 실패한다.

계층 상태 검토

content/layers.ts는 정확히 여덟 계층을 유지한다. 각 상태는 applied 또는 partial이며 설명과 한계를 함께 써야 한다. 현재 실행 가드, 배포, 매뉴얼 동기화는 부분 적용이다. 루트 전체 CI 차단, 자동 롤백, 외부 헬스 검사, 완전 자동 의미 판정이 새 근거 없이 존재한다고 바꾸지 않는다.