reconcile(docs): codex catalog doc salvage 병합 (doc-map.yml·README union)

[pureliture]

요약

5개 codex worktree(admin-ux-catalog / finding-lifecycle-catalog / ghas-alt-matrix / product-catalog-db-schema / product-catalog-scan-flow)에 남아 있던 미커밋 docs 변경을 출처별 5커밋으로 salvage한 뒤, 출처별 분리로 인해 깨진 2개 registry 파일을 union으로 reconcile한 PR입니다.

이건 codex의 문서 작업입니다. 검토 후 머지 결정은 사람/codex가 합니다. 이 PR은 자동 머지하지 않습니다.

5개 salvage 출처

커밋	출처 worktree	변경 파일
81554b7	admin-ux-catalog	docs/README.md, docs/_harness/doc-map.yml, docs/views/product-catalog.md(신규)
8798ac5	finding-lifecycle-catalog	docs/views/secret-detection-results-and-metrics.md(Finding lifecycle/triage/quality loop 섹션 추가)
772e6dc	ghas-alt-matrix	docs/views/project-overview-and-strategy.md(GHAS 대체 매트릭스·카탈로그 요약 추가)
ebf65aa	product-catalog-db-schema	docs/views/source-scan-results-nosql-schema.md(스키마 본문 재작성)
20e5b29	product-catalog-scan-flow	README.md, docs/README.md, docs/_harness/doc-map.yml, docs/views/scan-behavior-and-mechanism.md(신규)

reconcile한 2파일 (union)

출처별 salvage라 마지막 커밋(20e5b29 scan-flow)이 앞 커밋(81554b7 admin-ux)의 product-catalog 등록을 덮어써, HEAD 트리에 product-catalog가 파일은 있으나 registry에서 사라진 정합성 위반이 있었습니다. reconcile 커밋 8f873e7에서 두 출처의 변경을 union으로 복원했습니다.

• docs/_harness/doc-map.yml: scan-behavior-and-mechanism(scan-flow) + product-catalog(admin-ux) 두 view 등록을 모두 보존. 등록 위치는 각 출처 원본과 동일(scan-behavior는 source-scan-nosql 뒤, product-catalog는 local-scan-orchestration 뒤).
• docs/README.md: scan-behavior와 product-catalog 줄을 번호 목록·공개후보 표 양쪽에 union으로 복원.

나머지 view 문서 4개(+신규 2개)는 출처별 고유 파일이라 그대로 유지했습니다.

registry 정합성 상태

• view 11개, view_id/path/output_path 중복 없음 (YAML 파싱·중복 검사 통과).
• registry ↔ filesystem 완전 일치: 등록된 모든 view path에 실제 파일 존재, docs/views/*.md 중 미등록 0건. (reconcile 전에는 docs/views/product-catalog.md가 미등록 상태였고, union으로 해소됨.)
• product-catalog source_docs 9개 모두 실제 존재.
• ⚠️ source-hash drift 1건 (강제하지 않고 보고): product-catalog의 source_hashes에 등록된 src/security_scanner/runtime/read_api.py 해시(3cfc5536…)가 현재 main 파일(f5af4a98…)과 불일치. admin-ux salvage 시점 이후 main에서 read_api.py가 변경된 결과로, 이번 reconcile이 만든 문제가 아니라 admin-ux salvage 자체의 staleness입니다. salvage 충실성을 위해 원본 해시를 그대로 보존했습니다. 정석은 doc-sync 경유 재생성으로 해시를 갱신하는 것입니다.

raw 편집 / doc-sync 계약 플래그

• 이 repo의 docs/_harness/doc-map.yml은 단순 v2 계약(path + source_hashes)으로, doc-sync 스킬이 기대하는 PAIR 구조(outputs.md/outputs.html/render_record, members.*.content_hash)와 scripts/docs/doc_doctor.py·scripts/harness/render.py validator가 이 repo엔 존재하지 않습니다. 그래서 doc-map 전용 자동 validator 대신 수동 정합성 검증을 했습니다.
• codex의 salvage 변경(신규 view 문서 + registry 등록)은 doc-sync/doc-bootstrap 스킬을 경유하지 않은 raw 편집으로 보입니다. registry-owned 생성물이라면, 정석은 doc-sync(또는 doc-bootstrap) 경유 재생성이며, raw 편집은 doc-sync 계약을 우회한 것일 수 있습니다. 검토 시 신규 view 2개(scan-behavior-and-mechanism, product-catalog)와 변경 view들을 doc-sync 경유로 재생성·해시 갱신할지 판단 필요(특히 위 read_api.py drift 동반).

게이트 결과 (reconcile 커밋 8f873e7 기준, 모두 green)

• uv run python -m governance.render --check → exit 0
• uv run python -m governance.render --validate → exit 0
• uv run pytest → 1310 passed, 4 skipped
• uv run python -m governance.public_safety --diff origin/main...HEAD → exit 0 (모든 salvage된 doc 변경 공개 안전 통과)

참고: governance.render는 governance/current.yml → CURRENT.md 렌더 도구로 doc-map.yml과 직접 관계는 없으나 지시대로 게이트로 실행함.

커밋 스택 (main 5547c6c 위)

8f873e7 reconcile(docs): codex catalog doc salvage 병합 — doc-map.yml·README union
20e5b29 salvage(product-catalog-scan-flow)
ebf65aa salvage(product-catalog-db-schema)
772e6dc salvage(ghas-alt-matrix)
8798ac5 salvage(finding-lifecycle-catalog)
81554b7 salvage(admin-ux-catalog)

🤖 Generated with Claude Code

https://claude.ai/code/session_0142Y1bKifAeeS8CkCnpbSLK

[gemini-code-assist]

Code Review

This pull request significantly expands and restructures the project's documentation, adding comprehensive guides on scan behavior and mechanisms, the product catalog, NoSQL database schema, and finding lifecycles. The feedback recommends fixing a minor typo in the lifecycle documentation and updating a drifted file hash in the document mapping configuration to ensure consistency.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[pureliture]

분류 후속: salvage 5세트를 freshness 판정함. **CURRENT 1종(secret-detection-results-and-metrics, finding-lifecycle 출처, 독립·해시 main 일치)**은 별도 PR #63으로 분리 반영(auto-merge). 이 PR(#60)에 남은 4종 — product-catalog 3종(#1/#4/#5, codex/product-catalog-sot 활성영역)·project-overview(#3, 08-milestones 해시 drift)·doc-map/README reconcile — 은 codex 소유자가 처리 권장. (#1 read_api.py 해시 drift, #3 08-milestones drift는 doc-sync 재생성·해시 갱신 필요.)