docs: establish canonical product and architecture records - #25
Conversation
|
Warning Review limit reached
Next review available in: 35 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (11)
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:
📝 WalkthroughWalkthroughThreadWeave의 제품·기술·아키텍처 문서 기준선을 추가했습니다. 런타임과 호스트 경계, API 및 데이터 모델, 증분 처리 설계, 운영·보안·테스트 정책을 정의했습니다. 문서 색인과 계약 테스트도 추가했습니다. ChangesThreadWeave 문서 기준선
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1⚔️ Resolve merge conflicts 💡
📝 Generate docstrings
🧪 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: 6
🤖 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 `@ARCHITECTURE.md`:
- Around line 103-105: Unify the sort_by_sent_date sequence_number contract
across all three documents: in ARCHITECTURE.md lines 103-105, state that missing
explicit mailbox sequence numbers use input_position only as an internal
ordering fallback, never as public IMAP sequence numbers; in docs/TRD.md lines
75-83, require uniqueness only for exact ties or revise the implementation
contract consistently; in docs/adr/0003-optional-subject-date-policies.md lines
10-12, document the explicit metadata requirement and input-position fallback
policy.
In `@docs/PRD.md`:
- Around line 66-68: Update PRD-FR-005 to state that sort_by_sent_date=True
requires every input message to provide a unique positive mailbox sequence
number, regardless of whether dates tie, matching thread_messages validation via
_validated_sequence_number(...). Keep the existing ordering, date normalization,
fallback, and historical default requirements unchanged.
In `@docs/UML.md`:
- Around line 136-147: Update the UML relationship for IdentifierResolver so it
only represents providing identifiers to the serialization flow and does not
show a rendering dependency on ThreadResponse. Remove or replace the
“IdentifierResolver --> ThreadResponse : renders” association, while preserving
the existing ThreadForest and Container relationships.
In `@tests/test_architecture_documentation.py`:
- Around line 73-75: Update the ADR-0004 assertions in the architecture
documentation test to inspect the Markdown table row containing the
“0004-incremental-state-boundary.md” link and verify that row’s final status
cell is “Proposed.” Remove the broad “Proposed” in index assertion, while
preserving the decision-level “**Status:** Proposed” check.
- Around line 64-65: Update the ERD assertions in the architecture documentation
test to verify that PR `#20`’s incremental capability is explicitly marked as
canonical active-PR/proposed or “not protected-main,” not merely present with
its persistence description. Apply the documented unprotected-main contract
while preserving the existing PR `#20` and “persists no database entities” checks.
- Around line 47-50: Update the documentation-index test around
REQUIRED_DOCUMENTS to iterate over REQUIRED_DOCUMENTS[1:] and validate each path
as an actual Markdown link target in the index, not merely as raw text. Ensure
the test covers the ADR index and all remaining canonical documents, matching
the discoverability contract described in docs/TEST_STRATEGY.md.
🪄 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: e3980e2e-5dbc-4b37-b246-f3b38ddd1c84
📒 Files selected for processing (20)
ARCHITECTURE.mdCHANGELOG.mdDOCUMENTATION.mddocs/API_CONTRACT.mddocs/ERD.mddocs/OPERABILITY.mddocs/PRD.mddocs/SECURITY.mddocs/TEST_STRATEGY.mddocs/THREAT_MODEL.mddocs/TRACEABILITY.mddocs/TRD.mddocs/UML.mddocs/adr/0001-canonical-batch-oracle.mddocs/adr/0002-transport-neutral-core.mddocs/adr/0003-optional-subject-date-policies.mddocs/adr/0004-incremental-state-boundary.mddocs/adr/0005-automation-authority-separation.mddocs/adr/README.mdtests/test_architecture_documentation.py
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/API_CONTRACT.md (1)
97-100: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win100% 커버리지 기준을 계약에 명시하세요.
현재
exact focused and full test coverage문구는 owned production statement coverage와 branch coverage의 정확한 100% 기준을 보장하지 않습니다. 공개 API 변경 게이트에 이 기준을 명시하세요.수정 예시
- - exact focused and full test coverage; + - exact focused verification and full verification, including 100% owned production statement and branch coverage;As per coding guidelines, Python 변경은
100% owned production statement and branch coverage를 유지해야 합니다.🤖 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/API_CONTRACT.md` around lines 97 - 100, Update the “Public API changes require” section in API_CONTRACT.md to explicitly require 100% owned production statement coverage and 100% branch coverage, while preserving the existing focused/full test coverage and README/API synchronization requirements.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.
Outside diff comments:
In `@docs/API_CONTRACT.md`:
- Around line 97-100: Update the “Public API changes require” section in
API_CONTRACT.md to explicitly require 100% owned production statement coverage
and 100% branch coverage, while preserving the existing focused/full test
coverage and README/API synchronization requirements.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: f47ff999-cb06-4b7a-964a-70eaced3f546
📒 Files selected for processing (7)
CHANGELOG.mddocs/API_CONTRACT.mddocs/DOCUMENTATION_AUDIT.mddocs/INCIDENT_RUNBOOK.mddocs/PRD.mddocs/TRACEABILITY.mdtests/test_architecture_documentation.py
🚧 Files skipped from review as they are similar to previous changes (3)
- docs/TRACEABILITY.md
- CHANGELOG.md
- docs/PRD.md
|
@coderabbitai review |
|
Superseded by later contributor heads. This review evaluated f6a7be7 and blocked on coverage/documentation evidence that has since been corrected and re-proven by exact-head CI. Dismissal is not approval; current-head independent review remains required by live policy.
1 participant
Purpose
Persist ThreadWeave's product, technical, architecture, safety, evidence, governance, and autonomous-maintenance decisions into one canonical, machine-checkable repository documentation graph so protected GitHub state—not chat or PR-body archaeology—can reconstruct the product.
Canonical records
DOCUMENTATION.md; PRD/TRD; root Architecture; UML; conceptual ERD; API/version contract; Security; Threat Model; Data Governance; Test Strategy; Operability; Incident Runbook; Release/Provenance/Licensing; Traceability; Documentation Audit; seven status-bearing ADRs;CLAUDE.md; CHANGELOG; and machine-checkable documentation contracts.Sufficiency verdict
This line is DESIGN-SUFFICIENT only after its exact-head gates pass. The repository is PROTECTED-MAIN-INSUFFICIENT until this graph is integrated and re-proven on protected
main. Active PR and conversation-only behavior is never promoted to shipped truth.Protected-main reconciliation
PR base snapshot / incorporated live protected base:
4fa4caf86651193497002a3730ec19d8917f8818.The graph incorporates:
8af58f141dba00c7251c0ff4a5f7baf4563c8ebd: bulk stdlib iterable position is internal ordering fallback only; public sequence/UID identifiers are host authority and missing identifiers fail closed.ab4595f19bd94c83e15c934f96c4d05f90fbccf5: work-conserving hourly OpenCode continuation while preserving NVIDIA credential isolation, independent reverification, publisher separation, and one-proposal authority.4fa4caf86651193497002a3730ec19d8917f8818: Python 3.10–3.14 protected-main compatibility, including Python 3.14 package build/hash-install/outside-source smoke.Draft PR #20 incremental mailbox state, RFC 8474 identity handoff, payload-free snapshots, and mailbox-scale benchmark behavior remain IMPLEMENTED-ON-ACTIVE-PR / Proposed.
Current exact head
Contributor head:
f9c1b504802fd402e7dd4180d68ddfaf105dd51dThe latest CodeRabbit review identified that the API contract said “exact focused and full coverage” without explicitly binding public API changes to the repository’s exact 100% owned production statement/branch gates. The branch now contains a regression contract plus the explicit normative 100% statement and 100% branch wording. Earlier inline findings remain resolved.
Current-head CI/SAST/Security were re-triggered by this correction and must complete on this unchanged head before merge. Predecessor-head success is not transferred.
Architecture boundary
ThreadWeave remains a zero-runtime-dependency, transport-neutral in-process library. It owns metadata normalization, canonical batch threading, optional subject/date policy, and pure RFC presentation. Naruon/IMAP/archive hosts own authentication, tenancy, persistence, mailbox synchronization, distributed coordination, API lifecycle, PII purpose/retention policy, and audit. The ERD is conceptual because ThreadWeave owns no persistence.
Next handoff after integration
A documentation merge is an intermediate event. After protected-main integration, re-audit the graph, close the repository-owned portion of the
0.2.0release blocker, complete GitHub/PyPI Trusted Publisher account-side setup and public-artifact proof, then refresh Draft PR #20 onto the released protected main and reacquire exact-head Python 3.10–3.14, security, coverage/package, mailbox-scale parity/performance, and independent review evidence before any incremental-state merge.