docs: establish canonical DiskSage product requirements

[seonghobae]

Purpose

Canonical product/public documentation owner for DiskSage. Keep PRD, architecture summary, public README/index, standards traceability, operator guidance, and docs/product-technical-gap-baseline.md aligned with live runtime ownership without moving runtime authority into documentation.

Current authority — 2026-09-07 KST

• protected main: 0e90f9cebadbd7f59606baaec4ca1d2f178c899a;
• release/Test foundation fix: verify Windows release artifact namespace #264: 3e33229b4157a084a1985a1c7e952f98a64f25e3; Test/Release/Security/SAST are terminal success while CodeQL remains failed at the canonical .github live-PR metadata-binding owner path;
• reusable filesystem owner security: restore object-bound private evidence publication #344: 736da6db1fb0918d998b3f4d240c63936c91b11d, exact Test 34050767861 terminal success on Ubuntu test 101533855512, Windows windows-home-resolution 101533855641, and Ubuntu llm-engine-build 101533855661;
• provider-OAuth security: reject unknown OAuth connection authority fields #339 now inherits exact security: restore object-bound private evidence publication #344 through ordinary non-force ancestry at f8ddd5444b09496c893063dc806a95d478163cea; exact Test 34053995024 is current and non-terminal;
• provider-cache feat: evidence-bound provider cache reclaim #303 now inherits exact security: restore object-bound private evidence publication #344 through ordinary non-force ancestry at 5164b847ed95661a4b40a69c66b520639f58d970; exact Test 34054137067 is current and non-terminal;
• operational CLI fix: make cloud operational help a successful terminal action #212 remains 7f51536f22dc3605edfb8db2269c8f37a1dd4079 and is held until post-adoption security: reject unknown OAuth connection authority fields #339 earns unchanged-head terminal GREEN;
• exact docs: establish canonical DiskSage product requirements #315 head after the current projection update: 069ceffb99612db5a6792efc3da59a3ed8012727; exact Test 34054582580 is current and non-terminal.

Code-current projection

docs/product-technical-gap-baseline.md is updated on this branch at 069ceffb.... It no longer reports #344 as pending or #339/#303 as 19 commits behind. It records #344 exact GREEN, ordinary non-force owner adoption by #339/#303, their fresh non-terminal consumer Tests, #212's remaining dependency, #264's canonical CodeQL blocker, and the remaining Windows native-handle / same-object deletion / durable recovery gaps.

#344 retains descriptor-relative create-new authority and fail-closed existing-record replacement. Final visible-record reads are bounded at encoded.len()+1, raw trailing Unix / destinations fail before filesystem authority is acquired, public private-JSON serialization enforces the 8 MiB encoded budget during serialization, and the production core shim does not expose the legacy materialize-then-check JSON writer as a crate-level capability. Exact hosted Test on current #344 is GREEN.

#339/#303 now inherit current #344 through ordinary ancestry, but owner GREEN is not consumer GREEN. Their current exact Tests must terminate successfully on unchanged heads before any downstream restack or merge. #212 remains held until post-adoption #339 GREEN.

#264 remains separately blocked by the canonical .github CodeQL metadata-binding owner path. Windows private publication/replacement parity, exact-source existing-record replacement, broader same-object Trash/future irreversible deletion, durable journal, crash/power-loss recovery, and undo remain open P0 work under #170/#342. macOS durability claims must distinguish exercised fsync behavior from stronger F_FULLFSYNC semantics.

Documentation contract

DiskSage runtime domain truth stays with runtime owners. Optional ecosystem capabilities consume released/versioned owner contracts through ports/ACLs; docs do not authorize mutable cross-repository source coupling, cross-service SQL, model override of deterministic safety evidence, or irreversible purge. Live GitHub refs/checks remain more authoritative than a dated projection.

Keep Draft until applicable current-head documentation/review/ruleset gates and upstream protected-lineage prerequisites are satisfied. No self-approval, force-push, destructive rebase, gate weakening, or stale-head readiness claim.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

제품 계약, 아키텍처 색인, gap baseline을 추가하거나 갱신했습니다. README와 GitHub Pages 문서를 재구성했습니다. 캐시 purge를 읽기 전용 검토로 제한하고, 비가역 작업의 향후 승인 기준을 정의했습니다.

Changes

제품 계약 및 추적 기준선

Layer / File(s)	Summary
제품 계약 및 추적 기준선 AGENTS.md, ARCHITECTURE.md, CHANGELOG.md, docs/product-technical-gap-baseline.md	에이전트 지침과 문서 색인을 추가했습니다. PRD를 제품 계약의 정본으로 명시했습니다. gap baseline의 역할과 변경 로그를 갱신했습니다.

승인 후보 및 purge 검증 경계

Layer / File(s)	Summary
승인 후보 및 purge 검증 경계 docs/PRD.md, docs/architecture/adr/0002-cache-cleanup-is-per-item-evidence-bound.md, docs/development/cache-cleanup-operator-runbook.md	proven-cache Trash purge를 읽기 전용 검토로 제한했습니다. 직접 자식, symlink-free 재검증, journal 증거, 후보 식별과 동시 변경 방지에 대한 기준을 정의했습니다. 레거시 비가역 실행 경로를 운영 지원 대상에서 제외했습니다.

제품 범위 및 운영 문서

Layer / File(s)	Summary
제품 범위 및 운영 문서 README.md, docs/index.md	README를 제품 범위, 안전 경계, 공급자 경계, 고객 상태, 개발 검증 절차 중심으로 재작성했습니다. GitHub Pages 색인을 추가하고 관련 문서와 릴리스 경계를 연결했습니다.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: 🟡 Moderate · up to 1ebfd

This documentation PR changes the published safety contract, but its canonical requirements still describe irreversible purge while the operator guidance calls that capability unsupported and the executable remains able to perform it; that inconsistency could lead to unsafe operator action. The runbook also lists preview fields that are not currently emitted. The PR is not merge-ready until these contracts are aligned or explicitly accepted by the responsible owners.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 28 functions across 4 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 docs: 접두사를 사용하고, docs/PRD.md를 정식 제품 요구사항으로 확립하는 PR의 주요 변경을 정확하고 간결하게 설명합니다.

Full details: Docstring Coverage

Explanation

Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 28 functions across 4 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/canonical-prd

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

Code-current projection correction for the next docs commit (2026-09-07 KST):

• protected main remains 0e90f9cebadbd7f59606baaec4ca1d2f178c899a;
• release/Test owner fix: verify Windows release artifact namespace #264 is no longer 3e33229b...; current exact head is fea9144a15234035fbdf37e9fa914e5fd51efdec. Exact Test 34064276663, Release 34064276679, Security Scan 34064276645, and SAST 34064276692 are terminal success. CodeQL remains non-passing, but the canonical .github#1929 cause has changed: the original dispatch-actor allowlist mismatch is repaired; remaining owner proof is unchanged-head scan/SARIF terminal receipt plus cross-repository commit-status publication HTTP 403 repair;
• provider-cache feat: evidence-bound provider cache reclaim #303 is now d278298850a1f41cb7b1e0acaef7d6592501aedf after repairing remaining stale public-plan exact_approval_phrase test accesses. Test 34078422774 is current; Windows is success and both Ubuntu jobs are executing at the latest sweep. No GREEN claim yet;
• provider-OAuth security: reject unknown OAuth connection authority fields #339 is now 1bfc2796cf96dfacc60f5a7f23a8554ad3816d59 after adapting first-publication coverage to security: restore object-bound private evidence publication #344's pre-existing-private-parent contract. Test 34078580933 is current; Windows is success and both Ubuntu jobs remain runner-unassigned queued at the latest sweep. No GREEN claim yet;
• both feat: evidence-bound provider cache reclaim #303 and security: reject unknown OAuth connection authority fields #339 remain two release-owner commits behind current fix: verify Windows release artifact namespace #264 (merge base 3e33229b...), so normal non-force owner restack/adoption remains required before final readiness; fix: make cloud operational help a successful terminal action #212 stays held behind security: reject unknown OAuth connection authority fields #339.

docs/product-technical-gap-baseline.md and this PR body currently retain older heads/status wording and therefore need a source-doc update; this comment records the verified correction without claiming the checked-in baseline is already current.