docs: reconcile architecture documentation fitness - #44
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
OpenCode Review Overview
--> Changed-File Evidence Mapflowchart LR
PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
Evidence --> S1["Docs (21 files)"]
S1 --> I1["operator or user guidance"]
I1 --> R1["Review risk: Docs (21 files)"]
R1 --> V1["docs review"]
Evidence --> S2["Test (7 files)"]
S2 --> I2["regression suite"]
I2 --> R2["Review risk: Test (7 files)"]
R2 --> V2["targeted test run"]
|
![opencode-agent[bot]](https://avatars.githubusercontent.com/in/1549082?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
OpenCode reviewed the current-head bounded evidence and found no blocking issues.
Findings
No blocking findings.
Summary
APPROVE PR #44 (docs: reconcile architecture documentation fitness). Changed-file evidence inspected: docs/DOCUMENTATION_FITNESS.md (new 276-line fitness assessment, hunk inlined), docs/adr/0013-manifest-v3-extension-authority.md and docs/adr/0014-architecture-decision-governance.md (new Proposed ADRs), docs/doctoring/mv3-compatibility.md, docs/traceability/, docs/evidence/, docs/uml/extension-authority.md, plus new contract tests tests/test_documentation_fitness_contract.py, tests/test_documentation_active_pr_evidence_contract.py, tests/test_documentation_discoverability_followup.py, tests/test_mv3_supported_capability_matrix_contract.py, tests/test_extension_authority_traceability_contract.py, tests/test_freshness_traceability_contract.py and modified tests/test_product_documentation_contract.py.
Approval sufficiency: evidence affirmatively supports PR intent — the branch separates protected-main shipped truth from volatile active-PR evidence, reserves non-colliding ADR identifiers 0013/0014 (active #37 already reserves 0011/0012), indexes every ADR by lifecycle, and adds deterministic doc-contract tests (6 new files plus a 302-line update to tests/test_product_documentation_contract.py). Verification posture: Coverage execution evidence Result PASS (supported repository test suites passed); docstring gates passed or advisory; Failed GitHub Check evidence: no completed failed checks at head 620e29b; mergeStateStatus clean, mergeable true.
Linter/static: no Rust sources changed; cargo clippy contract exists for the Rust workspace; the new Python tests follow the repository's manifest-free unittest convention. TDD/regression: the new contract tests encode RED->GREEN doc governance (e.g., lifecycle-state parser accepts leading supported states and rejects unknown ones per DOCUMENTATION_FITNESS.md §3.6). Coverage: supported repository test suites passed per Coverage execution evidence. Docstring coverage: configured repository docstring gates passed or advisory per Coverage execution evidence.
DAG: CodeGraph head tree (82 files, 1,580 nodes) plus source-backed base-to-head flowchart:
flowchart LR
A["docs/DOCUMENTATION_FITNESS.md"] --> B["docs/adr/0013 + 0014"]
A --> C["docs/traceability + evidence + uml lanes"]
B --> D["test_documentation_discoverability_followup.py"]
C --> E["test_documentation_fitness_contract.py + mv3 matrix contract"]
D --> F["Coverage gate: supported suites PASS"]
E --> F
F --> G["No failed checks at head 620e29bb"]
PoC/execution: no trusted OPENCODE_EXECUTION_RECEIPT tool=... lines exist for browser/Playwright tools, and none apply — this is a non-web docs/tests PR; the Coverage execution evidence is the execution record. DDD/domain: no domain code changed; ADR lifecycle states (Proposed vs Accepted) remain explicit and are never silently promoted. CDD/context: no context code changed; docs keep protected-main vs active-PR contexts distinct (e.g., §3.1 HTTP lineage, §3.3 MV3 compatibility). Similar issues: no numerical/formula/estimator surface, so no similar-issue or paper parity evidence is required. Claim/concept check: doc claims are enforced by the new contract tests and consistent with inlined hunks — the MV3 matrix separates PROTECTED_MAIN/ACTIVE_PR/PLANNED/security-gated/out-of-scope, the ERD stays conceptual, and the trusted broker remains Planned under issue #10. Standards search: docs cite RFC 9325/APA 7 and pinned browser-protocol evidence paths; no new normative claim is introduced in changed code. Compatibility/convention: no schema/API/DB/config objects changed; new doc and test identifiers are descriptive multi-word snake_case (e.g., test_documentation_fitness_contract.py), and ADR numbering 0013/0014 avoids collision with active reservations. Breaking-change/backcompat: docs-only plus additive tests; no public contract broken. Implementation completeness: new contract tests are executable unittest classes with real assertions (not pass/NotImplementedError stubs); no placeholder bodies in the changed test surface. Performance: no runtime path changed. Developer experience: DX surface classified is review/CI output — the new contract tests make documentation governance machine-checkable and failures surface as precise unittest assertions instead of prose review. User experience: UX surface classified is the docs/CI/review-comment output; no user-facing UI change. Visual/DOM: non-web change; no DOM surface reviewed (no Playwright/DOM receipts claimed). Accessibility/i18n: no interactive UI changed; not applicable to the docs/CI surface. Supply-chain/license: no dependency, manifest, or lockfile changes. Packaging: no new package contract required — unpackaged_source_surfaces flags the new Python tests, but the repository norm is manifest-free Python unittest contract tests (CodeGraph indexes 29 python files including pre-existing tests/test_tls_governance.py and tests/test_data_governance_documentation_contract.py with the identical pattern), and Coverage execution evidence reports PASS. Security/privacy: no auth/secrets/data-plane changes; docs explicitly state the audience string is not authentication, extension-proposal authority cannot widen Agent/secret approval, and no sequential-id exposure or identifier-enumeration surface is introduced.
Approval sufficiency: bounded evidence supplied affirmative approval evidence for changed files, coverage/docstring posture, risk surfaces, and current-head verification; approval is not based merely on the absence of known blockers.
Verification posture: CodeGraph evidence was initialized and bounded current-head evidence reviewed for changed-file evidence including docs/DOCUMENTATION_FITNESS.md, docs/PRD.md, docs/README.md, docs/TRD.md, docs/adr/0013-manifest-v3-extension-authority.md, and 23 more.
Linter/static: workflow/static review evidence is bounded by the current-head GitHub Checks gate and changed-file evidence.
TDD/regression: coverage execution evidence and focused changed hunks were reviewed from bounded-review-evidence.md.
Coverage: coverage execution evidence reports supported repository test suites passed.
Docstring coverage: coverage execution evidence reports configured repository docstring gates passed or docstring coverage was advisory.
DAG: CodeGraph/source-backed behavior map connects docs/DOCUMENTATION_FITNESS.md to the affected review, runtime, or workflow path and required checks.
PoC/execution: coverage-evidence job executed on the current head and reported PASS.
DDD/domain: workflow and repository-governance invariants were reviewed against changed files in bounded evidence.
CDD/context: CodeGraph evidence, changed-file history, and focused hunks were reviewed from bounded-review-evidence.md.
Similar issues: changed-file history evidence was reviewed for comparable local precedents.
Claim/concept check: bounded evidence, repository source, current-head workflow evidence, and, where numeric, scientific, statistical, or literature-backed claims are affected, original-paper/formula evidence and parameter-recovery expectations were used for claims.
Standards search: standards and external-source claims require trusted bounded source evidence prepared outside the isolated model process; no evidence-backed standards blocker is present in bounded evidence.
Compatibility/convention: changed workflow/script conventions, object naming, and reserved-word safety for schema/API/config/code surfaces were checked in bounded evidence.
Breaking-change/backcompat: deployment evidence and changed-file history were checked for backward-compatibility risk.
Performance: changed surfaces were checked for performance risk in bounded evidence.
Developer experience: changed automation, review, test, setup, and maintenance surfaces were checked for helpful or obstructive DX impact in bounded evidence.
User experience: connected user, operator, API, CLI, documentation, review-comment, status-check, rendering, and workflow-reader behavior was checked for contradictions against code, docs, and tests in bounded evidence.
Visual/DOM: deterministic repair does not infer browser runtime execution; source-backed DOM/UI evidence and trusted workflow receipts were reviewed when present, and non-web surfaces used API/CLI/log/docs/workflow evidence instead.
Accessibility/i18n: accessibility, localization, and human-readable text surfaces were checked where UI, CLI, API message, docs, logs, or review text changed.
Supply-chain/license: dependency, package, model, container, and external-tool changes were checked in bounded evidence.
Packaging: package, build, test, lint, and security contracts were checked in bounded evidence.
Security/privacy: workflow-token, review-gate, and repository-automation security/privacy boundaries were checked in bounded evidence.
Adversarial validation
{"status":"passed","probes":[{"path":"docs/adr/README.md","line":134,"hypothesis":"The branch-added Proposed ADRs 0013/0014 could break the ADR lifecycle/discoverability contract (unknown lifecycle state or index rows missing the new files) and leave the head red.","attack_or_counterexample":"Treat the new ADR files as malformed lifecycle metadata: feed a lifecycle value outside the supported set, or an index that omits 0013/0014, and check whether the discoverability contract rejects it.","evidence":"Trusted Changed docs repository tree evidence lists A docs/adr/0013-manifest-v3-extension-authority.md and A docs/adr/0014-architecture-decision-governance.md plus M docs/adr/README.md at head 620e29bb; the inlined DOCUMENTATION_FITNESS.md hunk states the branch 'indexes every ADR by lifecycle' and §3.5/§3.6 describe the parser accepting leading supported lifecycle states while rejecting unknown states; the new tests/test_documentation_discoverability_followup.py enforces index coverage; Coverage execution evidence reports Result PASS (supported repository test suites passed) and Failed GitHub Check evidence reports no completed failed checks at head — the lifecycle/discoverability break hypothesis was falsified at docs/adr/README.md:134. source-line-sha256=e619e0b06e7e6de5b0e9cc2b7f04f98b7b93b5dd19177939d8d81bec48f2fc43","outcome":"falsified"},{"path":"docs/doctoring/mv3-compatibility.md","line":4,"hypothesis":"The MV3 supported-capability matrix could overclaim active-PR browser capability (e.g., #59/#60/#61 isolated-world or extension-update results) as PROTECTED_MAIN shipped truth, defeating the PR's core purpose.","attack_or_counterexample":"Classify an ACTIVE_PR-only capability row (update migration or isolated-world sentinel evidence) as PROTECTED_MAIN and check whether the matrix contract and fitness assessment catch the promotion.","evidence":"Trusted inlined hunk of docs/DOCUMENTATION_FITNESS.md §3.3 states the matrix 'separates PROTECTED_MAIN, ACTIVE_PR, PLANNED, security-gated and out-of-scope claims', keeps update migration intentionally distinct from restart persistence, and isolated-world behavior distinct from injection alone; the new tests/test_mv3_supported_capability_matrix_contract.py (97 lines) and tests/test_documentation_active_pr_evidence_contract.py (196 lines) enforce the separation; Coverage execution evidence reports Result PASS and Failed GitHub Check evidence reports no failed checks at head 620e29bb — the overclaiming hypothesis was falsified at docs/doctoring/mv3-compatibility.md:4. source-line-sha256=5232a0f8e1d3e5be449164f428a38baaeec37cf5fdd3f6f05e3d910821fdea6b","outcome":"falsified"},{"path":"docs/DOCUMENTATION_FITNESS.md","line":1,"hypothesis":"The fitness assessment could fabricate architecture truth by inventing a persistence owner, physical database entity, or trusted-broker deployment that does not exist, contradicting the data-governance contract.","attack_or_counterexample":"Search the assessment for a concrete production database table or broker-process deployment claim and verify it against the contract tests that forbid such fabricated entities.","evidence":"Trusted inlined hunk §2 ERD row states 'The ERD remains explicitly conceptual until a real persistence owner/schema exists' and 'Manufacturing tables for in-memory state, value objects, browser fixtures or process samples would be false architecture'; §3.2 states the complete broker 'remains Planned under issue #10' and 'does not justify a fictitious broker process, KMS path, database table, transaction manager...'; existing tests/test_data_governance_documentation_contract.py and modified tests/test_product_documentation_contract.py enforce 'does not claim a production application database'; Coverage execution evidence reports Result PASS and Failed GitHub Check evidence reports no failed checks at head 620e29bb — the fabricated-architecture hypothesis was falsified at docs/DOCUMENTATION_FITNESS.md:1. source-line-sha256=2fe6dae27f885ac51a311332ce6426b9a985cdb3a7e667148a0fb96e5f780b08","outcome":"falsified"}],"residual_risk":"Docs/test-only PR: capability-matrix and maturity claims are self-descriptive and are guarded by contract tests plus the head PASS coverage gate rather than by runtime execution; referenced external PR/issue identifiers (#27/#28/#10/#37/#40-#66) are cited from branch documentation and were not independently verified against the live GitHub tracker. Focused changed hunks for the remaining 20+ doc files were truncated in the trusted evidence packet, so those files were reviewed via the changed-file list, docs tree evidence, and the contract tests that cover them."}- Result: APPROVE
- Reason: Docs/test-only reconciliation PR (#44); trusted current-head evidence affirmatively supports the intent (protected-main vs active-PR separation, ADR 0013/0014 reservation, machine-checkable doc contracts), supported repository test suites passed, no failed GitHub checks, no unresolved review threads, and all three adversarial probes were falsified.
- Head SHA:
620e29bbe84aab281a83c63cce2f9cb3893ababc - Workflow run: 31665828716
- Workflow attempt: 1
1 participant
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
548e13ab74e05416bd5b4d6f54908e2401ea95b9against unchanged protected main67af7c87589edc2039545af335c95064d9b8391c.The canonical closure at
docs/evidence/2026-08-11-active-pr-maturity-closure.mdrecords the larger volatile active graph through PR #106. The dated extensiondocs/evidence/2026-08-12-browser-protocol-active-pr-evidence.mdreconciles browser-protocol/lifetime work through PR #117: #107–#114 establish explicit capabilities, exact OriginWeave generation, canonical version parsing, pinned runtime revisions, atomic validation, runtime protocol family, credential-safe validation evidence and exact adapter-version binding; #115 binds validated protocol metadata to one same-call callback; #116 additionally requires current OriginWeave session/context ownership and document epoch; and #117 establishes canonical context origin before semantic-node discovery while preserving same-epoch origin-change rejection. All remainIMPLEMENTED_ON_ACTIVE_PR, not protected-main truth.PR #117 has since reached exact-green on unchanged head
4f5e9b0f81df48fb178eaafb7cf68a925071ce39: CI31588082784, Rust contracts94086457133, exact Production coverage94086457260, and Manifest V3 Compatibility31588082643all succeeded. Its preceding compile failure was a test-harness error-conversion defect (OriginErrordoes not implementstd::error::Error), not a production rejection. The dated evidence row remains volatile branch evidence: its earlier queued wording is historical under the file's explicit invalidation rule until a later documentation mutation refreshes that volatile row.The reconciliation preserves Proposed ADR 0107 lifecycle status and the conceptual ERD because these browser-protocol metadata/validation/evidence/session-context/origin lanes introduce neither a deployed trust domain nor an accepted OriginWeave-owned durable persistence schema. Any moved recorded head or prerequisite invalidates the corresponding branch-local evidence immediately.
Documentation fitness finding
Exact-head evidence
On unchanged exact documentation head
548e13ab74e05416bd5b4d6f54908e2401ea95b9:31588205034: success;31588205072: success;31588204943: success;31588204978: success;No predecessor-head check or review 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, a controlled fixture or compatibility runner is the production browser adapter, one browser-root PID or
/proclineage snapshot equals trusted whole-task resource attribution, extension/native-host/profile admission is an Agent action grant, absence of known extension influence proves high assurance, semantic policy authorization/current-state validation is browser execution, browser-protocol/session-context/origin metadata is authenticated transport or browser-attested state, model-policy metadata equals protected-value disclosure/provider execution, fresh resolution equals trusted DNS/clock provenance, or a documentation branch equals release readiness. PROTECTED-MAIN-SUFFICIENT remains unavailable until the feature heads that actually integrate are reconciled against fresh protected-main acceptance.