docs: 로컬 체크아웃 대상 시작하기 가이드 추가

[pureliture]

Summary

• docs/views/getting-started.md 신규 작성. 현재 배포 패키지 없이 security-scanner source checkout에서 CLI를 실행하는 전제를 명시.
• README의 "빠른 시작"은 명령 5줄만 남기고 상세는 시작하기 가이드로 링크.
• 시작하기 가이드에 Ubuntu-local Ollama verifier 선택 단계를 추가. Gitleaks finding을 별도 verified artifact로 쓰고 report/gate에 사용할 수 있는 흐름을 문서화.
• Ollama verifier 요청을 JSON schema response format으로 제한하고, redacted metadata prompt에 safe pathRole과 matched triage decision을 추가.
• 오탐 감소 검증용 public-safe eval/verifier-corpus/를 추가.
• docs/views/ 공개 view 파일명에서 00-, 01- 같은 numeric prefix를 제거하고 README, docs/README.md, docs/_harness/doc-map.yml 링크를 새 파일명으로 정리.

Why

README의 "빠른 시작"은 명령 나열만 있어서 manifest 필드 의미, include_history trade-off, 자주 막히는 지점이 빠져 있었습니다. 처음 도구를 실행하는 사용자가 따라가기 어려운 상태였습니다. 가장 흔한 시나리오인 "이미 클론된 로컬 레포 대상 스캔"을 별도 view로 분리합니다.

현재는 installable release가 아니라 source checkout 기준 PoC이므로, 문서에서 두 checkout을 분리했습니다.

• security-scanner checkout: 명령을 실행하는 도구 저장소
• 스캔 대상 checkout: targets.local.yaml에 적는 별도 로컬 저장소

Verifier도 같은 원칙으로 정리했습니다. 실제 운영 테스트에서는 scanner와 Ollama가 같은 Ubuntu host에 있다고 보고 http://127.0.0.1:11434를 기본 host로 둡니다. Verifier는 detector가 아니라 triage 보조층이며, input finding을 덮어쓰지 않고 별도 output artifact를 만듭니다.

처음 live smoke에서 모델이 confidence를 문자열로 반환하거나 raw secret이 redacted라는 이유로 needs_review로 회피했습니다. 그래서 schema로 응답 타입을 제한하고, prompt에는 현재 finding의 safe path role과 matched decision을 명시했습니다.

문서명 변경

docs/views/의 공개 view 9개는 numeric prefix 없는 파일명으로 변경했습니다.

• 00-project-overview-and-strategy.md → project-overview-and-strategy.md
• 01-system-architecture-and-runtime.md → system-architecture-and-runtime.md
• 02-source-scan-results-nosql-schema.md → source-scan-results-nosql-schema.md
• 03-secret-detection-results-and-metrics.md → secret-detection-results-and-metrics.md
• 04-local-scan-orchestration-target-architecture.md → local-scan-orchestration-target-architecture.md
• 05-operations-transition-architecture.md → operations-transition-architecture.md
• 06-research-and-technical-decisions.md → research-and-technical-decisions.md
• 07-getting-started.md → getting-started.md
• 09-public-repo-safety-policy.md → public-repo-safety-policy.md

함께 갱신한 참조:

• README의 문서 링크와 시작하기 링크
• docs/README.md의 먼저 읽을 문서 목록과 공개 후보 문서 표
• docs/_harness/doc-map.yml의 human_views[].path
• getting-started.md 내부 관련 문서 링크

시작하기 가이드 구성

• 실행 위치 — security-scanner source checkout과 스캔 대상 checkout 구분
• 사전 확인 — uv, gitleaks v8, security-scanner source checkout, target working tree 체크 표
• 6단계 기본 명령 — uv sync → manifest 복사 → private 디렉터리 → scan → report → gate
• Ollama verifier 선택 단계 — Ubuntu-local Ollama host/model 설정 → verified artifact 생성 → verified report/gate
• manifest 필드 표 — name/path/enabled/include_history/exclude/gitleaks_config
• 자주 막히는 지점 — Gitleaks, Ollama verifier 설정, target path, severity, scan volume, history-only finding, JSONL overwrite
• 다음 단계 — synthetic 평가, DynamoDB 백엔드, 공개 안전 정책

Verifier corpus

eval/verifier-corpus/는 public-safe synthetic data만 포함합니다.

• expected positive: configuration-style synthetic candidate
• expected false positive: documentation-style synthetic example
• goal: verifier가 true positive를 보존하면서 documentation false positive를 clear하는지 확인

공개 안전성

사내 시스템·회사명·내부 호스트 키워드 일체 미포함을 확인했습니다. 예시 경로·이름은 /home/user/repos/repo-a, org/repo-a 같은 generic placeholder만 사용했습니다. Live verifier proof의 endpoint detail과 generated artifacts는 public repo 밖에만 두었습니다.

검증 결과

• Ubuntu fresh sandbox에서 PR head 896ea61 기준 source checkout 전제와 시작하기 기본 흐름이 끝까지 실행됨.
• Synthetic clean repository 1개를 별도 스캔 대상으로 두고 scan 완료, report 출력, gate 통과.
• 잘못된 manifest path를 넣었을 때 문서의 troubleshooting과 같은 local path does not exist 진단 확인.
• Ubuntu scanner runtime에서 eval/verifier-corpus/ finding 2건을 생성하고 Ollama-compatible verifier로 별도 verified artifact 생성 확인.
• Verifier 결과: configuration candidate는 true positive로 보존, documentation candidate는 false positive로 clear.
• Verifier before/after: false positive 1 → 0, precision 0.5000 → 1.0000, recall 1.0000 유지.
• docs/views/에 numeric-prefix Markdown 파일이 남아 있지 않음.
• README, docs/README.md, docs/_harness/doc-map.yml, docs/views/*.md, eval/verifier-corpus/README.md Markdown link check 통과: files=13 checked=72.
• Full test suite 통과: 270 passed, 이후 prompt test 추가 후 271 passed.
• Whitespace check 통과: git diff --check HEAD --.

Test plan

• Ubuntu fresh sandbox에서 security-scanner source checkout을 만든 뒤 docs/views/getting-started.md의 기본 명령을 위에서 아래로 실행해 첫 스캔이 끝까지 도는지 확인
• Ubuntu fresh sandbox에서 스캔 대상 checkout을 별도로 만들고 targets.local.yaml이 그 경로를 가리키는지 확인
• Ubuntu fresh sandbox에서 의도적으로 manifest path를 잘못 적었을 때 "자주 막히는 지점" 표의 안내가 실제 에러 메시지와 일치하는지 확인
• Ubuntu scanner runtime에서 verifier corpus를 스캔하고 Ollama-compatible verifier가 별도 verified JSONL artifact를 쓰는지 확인
• Ollama verifier가 configuration candidate를 true positive로 보존하고 documentation candidate를 false positive로 clear하는지 확인
• Verifier before/after report에서 false positive reduction 1, recall preserved true 확인
• docs/README.md의 "먼저 읽을 문서"와 "공개 후보 문서" 표에서 시작하기 링크가 동작하는지 확인
• README의 "빠른 시작" 마지막 줄 시작하기 링크가 동작하는지 확인
• docs/views/ numeric-prefix 제거 후 local Markdown link check 통과
• uv run pytest -q
• git diff --check HEAD --

[pureliture]

@codex 코드리뷰