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

README.md

@@ -210,6 +210,7 @@ core <- scanners/storage/llm/adapters <- cli/runtime
 - [프로젝트 개요와 추진 전략](docs/views/project-overview-and-strategy.md)
 - [시스템 구조와 실행 환경](docs/views/system-architecture-and-runtime.md)
 - [소스 스캔 결과 NoSQL Schema](docs/views/source-scan-results-nosql-schema.md)
+- [스캔 동작 방식과 메커니즘](docs/views/scan-behavior-and-mechanism.md)
 - [탐지 결과와 지표](docs/views/secret-detection-results-and-metrics.md)
 - [Local Scan Orchestration 목표 구조](docs/views/local-scan-orchestration-target-architecture.md)
 - [확장 경로와 운영 기준](docs/views/operations-transition-architecture.md)

docs/README.md

@@ -24,10 +24,12 @@
 1. [프로젝트 개요와 추진 전략](views/project-overview-and-strategy.md)
 2. [시스템 구조와 실행 환경](views/system-architecture-and-runtime.md)
 3. [소스 스캔 결과 NoSQL Schema](views/source-scan-results-nosql-schema.md)
-4. [탐지 결과와 지표](views/secret-detection-results-and-metrics.md)
-5. [Local Scan Orchestration 구조](views/local-scan-orchestration-target-architecture.md)
-6. [시작하기](views/getting-started.md)
-7. [progress dashboard](dashboards/progress.html)
+4. [스캔 동작 방식과 메커니즘](views/scan-behavior-and-mechanism.md)
+5. [탐지 결과와 지표](views/secret-detection-results-and-metrics.md)
+6. [Local Scan Orchestration 구조](views/local-scan-orchestration-target-architecture.md)
+7. [제품 카탈로그](views/product-catalog.md)
+8. [시작하기](views/getting-started.md)
+9. [progress dashboard](dashboards/progress.html)
 
 ## 공개 후보 문서
 
@@ -36,8 +38,10 @@
 | [project-overview-and-strategy.md](views/project-overview-and-strategy.md) | 이 프로젝트가 해결하려는 문제, 현재 지원 범위, 성공 기준 |
 | [system-architecture-and-runtime.md](views/system-architecture-and-runtime.md) | 전체 구조, 실행 흐름, codebase dependency boundary |
 | [source-scan-results-nosql-schema.md](views/source-scan-results-nosql-schema.md) | 스캔 결과를 어떻게 저장하고 어떤 질문에 답하려는지 |
+| [scan-behavior-and-mechanism.md](views/scan-behavior-and-mechanism.md) | local one-shot scan과 periodic queue/worker scan의 단계별 동작 방식 |
 | [secret-detection-results-and-metrics.md](views/secret-detection-results-and-metrics.md) | 어떤 결과를 공개할 수 있고, 지표를 어떻게 해석하는지 |
 | [local-scan-orchestration-target-architecture.md](views/local-scan-orchestration-target-architecture.md) | Local Scan Orchestration의 Python file 참조 관계와 runtime call chain |
+| [product-catalog.md](views/product-catalog.md) | 관리자 UX와 운영자 시나리오 관점에서 현재 제품 표면과 미완성 gap |
 | [operations-transition-architecture.md](views/operations-transition-architecture.md) | 로컬 실행 경로에서 반복 실행과 확장 adapter로 넘어가는 기준 |
 | [research-and-technical-decisions.md](views/research-and-technical-decisions.md) | 왜 Gitleaks-first인지, 다른 도구는 어떤 위치인지 |
 | [getting-started.md](views/getting-started.md) | 이미 클론된 로컬 저장소로 첫 스캔을 끝까지 돌리는 절차 |

docs/_harness/doc-map.yml

@@ -79,6 +79,16 @@ human_views:
       docs/workbench/context/legacy-source/02-local-db-and-dynamodb-compatible-schema.md: 57a1638a804eb21c4775f85d0657460cce25f5111635f28bfcf117d2f49eb006
     assets:
       - docs/assets/schema-access-patterns.svg
+  - view_id: scan-behavior-and-mechanism
+    title: 스캔 동작 방식과 메커니즘
+    path: docs/views/scan-behavior-and-mechanism.md
+    output_path: confluence://프로젝트-개요-및-추진-전략/스캔-동작-방식-및-메커니즘
+    generated_by: human_doc_curator
+    generated_at: 2026-06-21
+    safety_class: public
+    source_docs: []
+    source_hashes: {}
+    assets: []
   - view_id: secret-detection-results-and-metrics
     title: 탐지 결과와 지표
     path: docs/views/secret-detection-results-and-metrics.md
@@ -116,6 +126,34 @@ human_views:
       - docs/assets/local-scan-target-runtime-flow.drawio
       - docs/assets/local-scan-target-scenario-seams.svg
       - docs/assets/local-scan-target-scenario-seams.drawio
+  - view_id: product-catalog
+    title: 제품 카탈로그
+    path: docs/views/product-catalog.md
+    output_path: confluence://프로젝트-개요-및-추진-전략/제품-카탈로그
+    generated_by: human_doc_curator
+    generated_at: 2026-06-21
+    safety_class: public
+    source_docs:
+      - src/security_scanner/runtime/read_api.py
+      - src/security_scanner/cli/commands/read_api.py
+      - src/security_scanner/cli/commands/scan.py
+      - src/security_scanner/cli/commands/scan_health.py
+      - src/security_scanner/cli/commands/disposition.py
+      - tests/test_read_api.py
+      - tests/test_queue_status.py
+      - tests/test_cli_disposition.py
+      - docs/workbench/context/legacy-source/08-milestones.md
+    source_hashes:
+      src/security_scanner/runtime/read_api.py: f5af4a9840239078647c81a5bc3381316f81c12b54f3145a3d9e91fb8051fe9d
+      src/security_scanner/cli/commands/read_api.py: 83f77aa0223619f00de6ccc82ecc7de70dc94d0016f492ba2f8701cc6ea9aa68
+      src/security_scanner/cli/commands/scan.py: 2d03278acbb08dd56a0c79c7e390cb2375a7b41dbefde777ee7c4e79bdc274cd
+      src/security_scanner/cli/commands/scan_health.py: 255b6243d2f05a4b6c59e0f5056b0b27f1db15e52ac0d77219a97586d3621b61
+      src/security_scanner/cli/commands/disposition.py: 200a9198f8bcf8d7c80afc77e103bb22bdcc4d1169441d5451375ce0caf36bb5
+      tests/test_read_api.py: ac327e19be8dec2f525701a54115d74d707e2c553f768b31ca4e0b6663a840eb
+      tests/test_queue_status.py: 448b89ce7d8aba6abfa9a71206aba827814087b3b2c3c0d5413c11104ce82fc3
+      tests/test_cli_disposition.py: 7c9027b821521b3336e2c0da4ce0c2bb498a2e80e038d2b4e137070f0998225e
+      docs/workbench/context/legacy-source/08-milestones.md: 121170acde8ccdb4ca8ba50e22faf7ae5ecd79c33b76294ba852e1e7a1675c1b
+    assets: []
   - view_id: operations-transition-architecture
     title: 확장 경로와 운영 기준
     path: docs/views/operations-transition-architecture.md

docs/views/product-catalog.md

@@ -0,0 +1,45 @@
+# 제품 카탈로그
+
+`security-scanner`는 local-first Secret Detection 파이프라인을 운영자가 반복 실행, 관찰, 분류할 수 있게 만드는 제품입니다. 현재 제품 표면은 CLI와 read API 중심이며, 전체 관리자 콘솔보다는 dashboard data contract와 운영 판단 신호를 먼저 안정화하고 있습니다.
+
+## 관리자 UX/운영자 시나리오
+
+관리자 UX의 목적은 "스캔이 돌았는가"를 넘어서, 어느 대상이 빠졌고, 어떤 finding이 아직 판단되지 않았으며, 운영자가 지금 어떤 조치를 해야 하는지 알려주는 것입니다. 현재 구현은 health, coverage, backlog, freshness, disposition-filtered findings를 읽는 기반을 제공합니다. 다음 단계는 그 신호를 ack, suppress, assign, dispatch, drilldown, RBAC가 있는 action UX로 묶는 일입니다.
+
+### 사용자 여정 단계
+
+| 단계 | 운영자가 확인하는 질문 | 필요한 화면/정보 | 현재 상태 |
+| --- | --- | --- | --- |
+| 1. 범위 확인 | 어떤 repository가 관리 대상이고, 무엇이 빠졌는가? | 전체 대상 수, 포함/제외 수, covered count, coverage gap | `read-api` coverage panel이 org total, included, excluded, covered, gap을 제공합니다. |
+| 2. 신선도 판단 | 최근 스캔이 SLA 안에 들어왔는가? | incremental/baseline breach count, evaluated time, repo별 stale signal | `scan-health`, `freshness-eval`, `read-api` freshness rollup이 집계 신호를 제공합니다. |
+| 3. 작업량 파악 | 워커가 밀렸는가, 실패가 누적되는가? | pending, leased, completed, dead-letter, expired lease, backlog 추세 | `queue-status`와 `read-api` backlog panel이 queue 상태를 제공합니다. |
+| 4. finding 분류 | 무엇이 verified, false positive, unreviewed인가? | disposition filter, severity, confidence, rule, repo, redacted location, secret hash | `read-api --include-findings --disposition ...`가 public-safe finding DTO를 제공합니다. |
+| 5. 조치 기록 | 사람이 어떤 판단을 남겼는가? | true positive / false positive 판정, reason, actor/source, audit event | `disposition set`이 human/manual 판정을 `FINDING_STATE`와 `STATE_EVENT`에 기록합니다. |
+| 6. 후속 작업 연결 | 누가 rotation, suppression, exception review를 맡는가? | assignee, due date, acknowledgement, dispatch target, reopen rule | 아직 제품 UX로 묶이지 않았습니다. |
+
+### 현재 UI 기능
+
+- **Dashboard/read API**: `read-api`는 한 번의 dashboard refresh payload로 freshness, coverage, backlog를 반환하고, 요청 시 disposition-filtered findings를 포함합니다.
+- **Health와 freshness**: `scan-health`는 stale repo가 있으면 fail-closed gate로 동작합니다. `freshness-eval`은 freshness breach를 평가하고 `BREACH_COUNTER` rollup을 materialize합니다.
+- **Coverage**: catalog와 repo health를 비교해 포함 대상 중 아직 스캔되지 않은 coverage gap을 보여줍니다.
+- **Queue 상태**: `queue-status`는 pending, leased, completed, dead-letter와 expired lease count를 사람이 읽는 형식으로 보여줍니다. read API backlog panel은 poll-friendly count를 제공합니다.
+- **Finding disposition**: findings DTO는 raw secret과 scanner match를 노출하지 않고 repo, rule, severity, confidence, status, disposition, redacted location, salted secret hash만 제공합니다. `disposition set`은 human/manual true positive 또는 false positive 판정을 기록합니다.
+- **Alert dispatch substrate**: freshness evaluator는 notification-log sink와 de-dup/re-notify window를 갖춘 alert dispatcher를 경유합니다. 실제 Slack, email, webhook 같은 delivery channel은 deploy-gated입니다.
+
+### 미완성 UX gap
+
+| Gap | 현재 한계 | 카탈로그상 의미 |
+| --- | --- | --- |
+| Action UX | read API는 상태를 보여주지만, dashboard 안에서 ack, suppress, reopen, bulk action을 수행하는 화면은 없습니다. | "관찰 가능" 단계이며 "운영 워크벤치"는 다음 제품 slice입니다. |
+| Ack | alert나 stale 상태를 사람이 확인했다는 별도 acknowledgement state가 없습니다. | 반복 알림 억제는 시간 기반 de-dup이고, 사람의 확인 행위와 분리되어 있지 않습니다. |
+| Suppress | false positive disposition과 match-key suppression 기반은 있으나, 만료일, 범위, 승인자, 사유 템플릿을 가진 suppression policy UX는 없습니다. | 억제 메커니즘은 존재하지만 exception management UX는 미완성입니다. |
+| Dispatch | notification-log sink와 dispatcher seam은 있으나, 실제 외부 채널 routing, escalation, delivery status 화면은 deploy-gated입니다. | 알림 연결 지점은 준비됐고, 운영 채널 제품화는 별도 결정이 필요합니다. |
+| Assign | finding이나 stale repo를 담당자에게 배정하는 assignee, due date, ownership model이 없습니다. | 개인 작업 관리가 아니라 scanner state 관찰에 머물러 있습니다. |
+| Drilldown | public-safe finding row는 제공하지만, repo history, scan run, lifecycle event, queue job을 한 화면에서 연결하는 상세 화면은 없습니다. | 원인 추적은 CLI와 저장소 조회 조합에 의존합니다. |
+| RBAC/Auth | read API는 loopback 기본값과 non-loopback auth gate만 검증합니다. 사용자, 역할, 권한, audit session 모델은 없습니다. | co-located admin UI 전제의 read-only contract이며 multi-user admin console은 아닙니다. |
+
+### 카탈로그용 concise copy
+
+관리자 UX는 local-first scanner를 운영자가 믿고 반복 실행할 수 있게 하는 관찰·판단 계층입니다. 현재 제품은 dashboard/read API로 freshness, coverage, queue backlog, disposition-filtered findings를 public-safe JSON으로 제공하고, `scan-health`, `freshness-eval`, `queue-status`, `disposition set`으로 운영자가 stale 상태와 queue 정체, human triage를 확인할 수 있게 합니다.
+
+아직 완성된 관리자 콘솔은 아닙니다. 다음 UX slice는 read-only dashboard를 action workspace로 확장해 ack, scoped suppression, alert dispatch, assignee, drilldown, RBAC를 연결하는 것입니다. 이 전환이 끝나면 운영자는 단순히 "문제가 있다"를 보는 데서 멈추지 않고, 누가 무엇을 판단했고 다음 조치가 어디에 걸려 있는지 한 화면에서 확인할 수 있습니다.

docs/views/project-overview-and-strategy.md

@@ -22,6 +22,7 @@ Secret scanner는 많은 후보를 찾아냅니다. 하지만 실제 운영에
 - 스캔 실행, finding, lifecycle 상태를 로컬 저장소에 남깁니다.
 - Synthetic corpus로 precision, recall, false negative를 측정합니다.
 - Ollama-compatible verifier는 redacted metadata만 받아 triage 상태를 보조합니다.
+- `code-vuln` category는 opt-in SARIF import와 Semgrep-compatible local adapter로 다룹니다.
 
 ## 현재 지원하지 않는 일
 
@@ -30,14 +31,31 @@ Secret scanner는 많은 후보를 찾아냅니다. 하지만 실제 운영에
 - 관리형 클라우드 실행 환경 연동.
 - 내부 endpoint 또는 알림 시스템 연동.
 - Gitleaks를 대체하는 primary scanner 도입.
-- SAST/SCA 확장.
+- 기본 Secret Detection 경로를 대체하는 SAST/SCA 확장.
 
 ## 현재 상태
 
 로컬 스캔 경로, 저장된 결과 재검토, synthetic 평가, verifier-assisted review flow는 public-safe fixture 기준으로 검증되어 있습니다.
 
 따라서 지금의 핵심 메시지는 “로컬 Secret Detection 파이프라인을 안정화하는 중”입니다. 현재 공개 기본 경로는 local scan, local store, report, gate, evaluation입니다.
 
+## 카탈로그용 요약
+
+`security-scanner`는 GHAS 전체를 대체하는 managed SaaS가 아니라, local-first 환경에서 Secret Detection 결과를 재현 가능하게 만들고 GHAS Secret Scanning 품질에 가까워지도록 보정하는 제품입니다.
+
+PR #58 이후 자율층 M0~M5는 synthetic fixture 기준으로 GHAS parity harness, 인라인 FP 억제, LLM tier disposition 배선, non-GHAS drift monitor, report-only parity SLO gate까지 갖췄습니다. 다만 실 GHAS snapshot 취득, baseline 측정, threshold 커밋, enforce 전환은 human-gated H1~H3로 남아 있습니다.
+
+## GHAS 대체 매트릭스
+
+| 영역 | 우리 제품 기능 | 현재 성숙도 | gap |
+| --- | --- | --- | --- |
+| GHAS Secret Scanning | Gitleaks-first local checkout scan, `Finding` 표준화, local store, report/gate/evaluate, read-only GHAS Secret Scanning alert/location fetch, redacted `GHAS_ALERT` 비교 input, incomplete metadata bucket | **부분 대체 + 보완.** Local secret detection과 redacted GHAS 비교는 가능하고, PR #58 이후 GHAS `secret_type` ↔ gitleaks `rule_id` 정규화, state-aware truth, line tolerance가 parity harness에 반영됨 | GitHub native push protection, secret validity/revocation, alert mutation, org-level managed rollout, GHAS scan trigger는 제공하지 않음. 실 GHAS snapshot 기반 enforce는 H1~H3 대기 |
+| GHAS Code Scanning | `code-vuln` opt-in 경로: SARIF import, `VULN_FINDING` JSONL artifact, Semgrep-compatible local adapter, code-vuln report/gate/evaluate, vulnerability verifier/explainer | **보완.** SARIF-compatible local slice는 있으나 기본 경로가 아니며 GHAS Code Scanning alert lifecycle과 분리됨 | GHAS Code Scanning alert fetch/comparison, SARIF upload, code scanning alert mutation, security campaign, SCA/SBOM/dependency vulnerability는 future track |
+| Alert lifecycle | Secret finding은 `FINDING_STATE`와 disposition ledger로 재검토 상태를 보존하고, verifier terminal verdict를 disposition으로 반영. `NEEDS_REVIEW`는 fail-closed review-needed 상태로 남김 | **부분 대체.** Local triage lifecycle은 갖췄고 PR #58 M3에서 `scan_all` + `scan_worker`의 LLM tier disposition/async verify queue가 배선됨 | GHAS alert open/resolved/dismissed 상태를 원격으로 변경하지 않음. GitHub UI와 양방향 lifecycle sync, assignment, dismissal comment, notification workflow는 미대체 |
+| Dashboard / overview | Read API와 read-only dashboard/admin UI로 catalog, scan status, findings, repo health, backlog 상태를 보는 운영 화면 제공 | **보완.** M8 dashboard가 merged되어 local 운영 가시성은 강화됨 | GHAS organization security overview, enterprise dashboard, cross-org trend, native GitHub permission model, managed notification UX는 미대체 |
+| Quality / parity | GHAS parity SLO 모델, per-repo 1:1 macro precision/recall, synthetic GHAS parity corpus, type coverage, GHAS-confirmed-FP bucket, report-only `governance.parity_slo --check`, stale-degraded 표시 | **보완에서 enforce 전 단계.** PR #58 M0~M5 완료로 측정/품질 자율층은 존재. Drift monitor는 GHAS-calibrated baseline을 쓰지만 non-GHAS에서는 early-warning일 뿐 SLO가 아님 | Threshold file 부재 시 parity gate는 report-only라 차단하지 않음. 실 baseline 측정과 목표 확정, enforce 전환, fixture-vs-real divergence 보고는 human-gated H-track 필요 |
+| Managed SaaS | Local-first CLI/runtime, DynamoDB-compatible local storage pattern, systemd-oriented personal runtime, public-safe synthetic fixtures | **미대체.** 운영자가 소유하는 로컬/자체 실행 제품 | Hosted multi-tenant service, GitHub-native entitlement, managed scaling, SLA, billing, centralized secrets/revocation, enterprise policy management는 제공하지 않음 |
+
 ## 성공 기준
 
 - 같은 입력에서 같은 report와 gate 결과를 다시 만들 수 있습니다.