docs: reconcile architecture documentation fitness - #44
Open
seonghobae wants to merge 103 commits into
Open
Conversation
|
Note Reviews pausedIt 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 Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthrough문서 적합성 평가와 ADR 거버넌스 규칙을 확장했습니다. PRD, TRD, 추적성 문서에서 protected-main과 active-PR 상태를 분리했습니다. MV3 권한, 프로토콜, freshness 요구사항을 문서화했습니다. 문서 계약 테스트를 추가·확장했습니다. Changes문서 거버넌스 정합성
Estimated code review effort: 4 (Complex) | ~45 minutes Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
docs/adr/README.md (1)
13-15: 📐 Maintainability & Code Quality | 🔵 Trivial | 🏗️ Heavy liftADR 수락 거버넌스를 전용 ADR에 기록하세요.
docs/adr/README.md의Accepted독립 승인 요구 조건과solo-maintainer예외는 새로운 구속력 있는 거버넌스 결정입니다. 지침에 따라 이 결정, 근거, 취소 조건을 기존 ADR 0002 또는 전용 ADR에 기록하고 해당 ADR을 인덱스에 연결하지 않고 여기서만 정의하지 마세요.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/adr/README.md` around lines 13 - 15, Move the binding Accepted-ADR governance rules from docs/adr/README.md into an existing ADR 0002 or a new dedicated ADR, including the independent non-author approval requirement, solo-maintainer exception, supporting rationale, and reversal conditions. Link the selected ADR from the README index and retain only a concise reference here; do not define these rules solely in the README.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/adr/README.md`:
- Line 47: Synchronize the ADR 0109 title between the index entry and the H1 in
0109-hourly-automation-operational-closure.md. Update either the index title or
the ADR header so both use the same wording, while preserving the existing ADR
0109 link and status.
In `@docs/DOCUMENTATION_FITNESS.md`:
- Line 34: Update the standards-evidence documentation referenced by
DOCUMENTATION_FITNESS, especially the WARC/PROV, WebDriver BiDi, CDP, WebMCP,
MCP, and Manifest V3 claims, by linking each to primary specifications or
official documentation and corresponding APA 7 references in docs/doctoring.md.
If any source is missing, add it there while preserving the explicit separation
between experimental browser interfaces and final normative standards.
In `@tests/test_documentation_fitness_contract.py`:
- Around line 36-51: Update the documentation fitness test around accepted_paths
and proposed_paths to derive the ADR file set from ADR_ROOT instead of fixed
lists. Parse both docs_index and adr_index into path-to-status mappings, reject
duplicates and missing entries in either index, and compare each index’s status
against the ADR file metadata, including accepted ADRs; preserve the documented
accepted/proposed status requirements from docs/README.md and
docs/adr/README.md.
---
Nitpick comments:
In `@docs/adr/README.md`:
- Around line 13-15: Move the binding Accepted-ADR governance rules from
docs/adr/README.md into an existing ADR 0002 or a new dedicated ADR, including
the independent non-author approval requirement, solo-maintainer exception,
supporting rationale, and reversal conditions. Link the selected ADR from the
README index and retain only a concise reference here; do not define these rules
solely in the README.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: f03ac9cb-b23a-48d5-8ada-ecd6f3f00bbc
📒 Files selected for processing (4)
docs/DOCUMENTATION_FITNESS.mddocs/README.mddocs/adr/README.mdtests/test_documentation_fitness_contract.py
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
OriginWeave already had a broad PRD/TRD/Architecture/ADR/UML/ERD/security/operability/traceability graph, but protected-main documentation had semantic drift: incomplete ADR discovery, historical implementation lineage presented too prominently, active-PR behavior that could be mistaken for shipped truth, and authority boundaries that lacked machine-checkable reconciliation.
Current semantic verdict
DESIGN-SUFFICIENT / PROTECTED-MAIN-PARTIAL.
The design graph is sufficiently broad to reconstruct product intent, trust boundaries, conceptual data model, operational/release expectations and accepted/planned capability boundaries without chat history. It is not protected-main/as-built closure: active implementation branches remain non-shipped evidence until dependency-ordered integration and fresh protected-main acceptance.
Current exact branch scope
Current exact head is
9e2be616b261e45aaac5bf875a637020976e4c80against unchanged protected main67af7c87589edc2039545af335c95064d9b8391c.This canonical documentation line now:
IMPLEMENTED_ON_PROTECTED_MAIN,IMPLEMENTED_ON_ACTIVE_PR,PARTIAL,ACCEPTED_ARCHITECTURE,PLANNED,RESEARCH_ONLY,SUPERSEDEDandOUT_OF_SCOPEmaturity;Acceptedlifecycle authority;docs/traceability/extension-authority-security.md, recording PR test(policy): prove extension grants cannot widen Agent authority #62 and test(policy): prove extension grants cannot bypass secret authority #63 as active composition evidence that extension proposal authority cannot widen Agent origin/capability/instruction/secret/approval authority.The extension-security dossier explicitly preserves the non-transitive chain from Chromium permission to an exact extension grant to typed-action proposal, while forbidding that proposal permission from becoming Agent capability, broader origin authority, trusted instruction source, secret-delivery authority, approval or protected-value resolution. It does not close issue #27 or issue #10.
Documentation fitness finding
Latest RCA and exact-head evidence
The first extension-security traceability contract failed on exact head
6e71663ab3099a669af29655ab007c056c1eb21dbecause the test asserted a literal plain-text phrase while the canonical dossier emphasizednotwith Markdown. The production documentation semantics were correct; the test was presentation-coupled. Commit9e2be616b261e45aaac5bf875a637020976e4c80fixes the contract by normalizing Markdown emphasis before the semantic assertion rather than weakening the required meaning.On unchanged exact head
9e2be616b261e45aaac5bf875a637020976e4c80:31437209714: success;31437209773: success;31437209715: success;31437209741: success;No predecessor-head result is transferred to this exact head.
Truth boundary
This PR does not claim the browser/runtime product is complete, any active feature branch is shipped, a Proposed ADR is Accepted, a trusted sensitive-data broker exists, or a green documentation branch equals release readiness. Even after this documentation PR integrates, PROTECTED-MAIN-SUFFICIENT may be claimed only after protected-main documentation is re-evaluated against the feature heads that actually integrated and corresponding protected-main acceptance exists.