docs: establish canonical product and architecture baseline - #604
docs: establish canonical product and architecture baseline#604seonghobae wants to merge 61 commits into
Conversation
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughAdded the canonical architecture, requirements, ADR, domain-model, security, traceability, UML, and documentation-contract baseline for ChangesArchitecture and governance baseline
Estimated code review effort: 4 (Complex) | ~45 minutes Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
📝 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 |
|
@opencode-agent address Take a bounded writer lease on this Draft documentation branch only. Current docs head at handoff is
Do not change numerical formulas, runtime public APIs, dependencies, model credentials, release version, or unrelated product code. |
|
@opencode-agent While holding the existing bounded writer lease, please fold in the non-duplicative architecture gaps identified by the parallel conversation audit before declaring this canonical baseline complete. Preserve your current PRD/TRD/PlantUML/ERD/changelog/old-summary deprecation work; add only what is genuinely missing:
Do not duplicate hosted-product threat/persistence ownership: product HTTP/session/consent/tenant/RBAC/UI/database remains Psychometrics Commons/downstream. Keep exact protected-main vs active/planned status honest. These are documentation-only convergence requirements; do not change runtime source, dependencies, workflows, credentials, formulas, or version. |
|
@opencode-agent address Reacquire the sole canonical #604 documentation-writer lease only if a final refetch still shows exact Draft head Fresh compare is Revalidate the canonical fitness requirements already tracked by #621 rather than assuming the older body is current: PRD/TRD/root Architecture/ADR status and supersession; Rust/PyO3 numerical ownership versus explicit reference-only Python; public schema/serialization/fingerprint/version contracts; logical ERD cardinality/immutability and no invented hosted DB; domain/public-contract UML plus diagram inventory/hygiene; threat/security/data-governance and PII alternatives; V&V/Test Strategy; operability/recovery; release/migration/rollback/SBOM/provenance/licensing indexing; exact Preserve ADR-0013's RCA→feasibility→action, waiting-is-local, single-writer and no-early-stop decisions. Update current standards-watch facts only from official published/primary sources and keep drafts/revisions as watch items. Run focused documentation/traceability/UML/ERD/changelog tests plus |
|
@opencode-agent address Fresh sole-canonical documentation lease for Draft #604 after protected-main movement invalidated the prior handoff. Final pre-write guard is mandatory: refetch #604 head, live protected Use #621 as the whole-conversation acceptance backlog, but recalculate every statement from the integrated tree rather than copying historical PR lists. First reconcile protected main non-destructively, preserving all accepted changes through #723/#724/#725/#726 and earlier integration. Specifically: #723 Rust fail-closed chi2/BH and #724 governed validation policy are protected-main behavior; #725 non-finite inference uncertainty correction is protected-main behavior, with #729 only a test/doctoring evidence-completeness follow-up; #726 ATA semantic-control type validation is protected-main behavior, while #728 is a residual finite-domain/exclusion RED; #719 is now superseded-in-flight by Ready #727 but neither is protected-main behavior yet; #717/#721/#663 remain active Rust-ownership work. Do not present any active Draft/Ready PR as shipped. Repair the known documentation-fitness problems only in this canonical line: separate document availability ( Extend machine-checkable docs fitness so stale PRD/TRD routing, authoritative NumPy-production-fallback wording, active-PR→main promotion, duplicate ADR authority, broken UML/ERD links/cardinality, stale product names, missing canonical references, and false document-status maturity fail deterministically. Run focused architecture/ADR/UML/ERD/traceability/changelog tests, render/check managed CHANGELOG, |
|
@opencode-agent address Reacquire the sole canonical #604 documentation writer lease only after a final refetch confirms exact Draft head First reconcile protected main non-destructively, preserving all accepted product/runtime/docs history including #727's ranking live-CSR contract and #730's signed non-finite uncertainty evidence/doctoring. Then recalculate all document-availability and capability-maturity claims from the integrated tree using #621 plus its newest reconciliation comment as the acceptance backlog. In particular #727/#730 are After reconciliation, close only still-real canonical fitness gaps already tracked by #621: two-axis document/capability maturity, Rust/PyO3 production numerical ownership, versioned serialization/fingerprint/interfaces, public/domain UML inventory and logical ERD cardinality/immutability, threat/data governance, V&V/Test Strategy, package operability/recovery, release/migration/rollback/SBOM/provenance/licensing navigation, exact |
|
@opencode-agent address Fresh sole-canonical documentation writer lease after protected main moved through #728. Immediately before any write, refetch Draft #604 exact head First reconcile live protected main non-destructively, preserving all protected behavior through #728, including merged Rust/fail-closed inference/fit-stat/RT/CAT and ATA semantic-preflight slices, while preserving only #604's canonical documentation package. Recalculate every maturity and traceability row from the integrated tree before editing prose; active work must not be presented as shipped. In particular #728/#683 is now protected-main behavior, #731 is closed superseded, #732 is the sole active top-1 CSR implementation line, and #733 is active LLM-judge/IRT contract work with unresolved review findings. Re-read #621 rather than copying its stale protected-head identifiers. Then close only still-current documentation-fitness gaps: two-axis document availability vs capability maturity; exact Rust/PyO3 production numerical ownership versus explicit reference/test Python; public schema/serialization/fingerprint/version/deprecation contracts; exact Extend machine-checkable contracts so stale/superseded PR numbers, ACTIVE_PR→protected-main promotion, normative Python-production fallback/NumPy-first wording, duplicate UML authority, broken local links/cardinalities, stale product/repository names and deterministic changelog drift fail closed. Run focused architecture/ADR/UML/ERD/traceability/changelog checks, render/check managed CHANGELOG, |
|
@opencode-agent address Fresh sole-canonical documentation reconciliation lease after protected Fresh compare is Use #621 as the whole-conversation documentation-fitness backlog but revalidate its stale protected-head/PR statements from current GitHub evidence. Close only still-real gaps in the sole canonical line: two-axis document availability versus capability maturity; Rust/PyO3 production numerical ownership with Python numerical code explicitly reference/test-only or tracked active migration; versioned public serialization/fingerprint/interface/deprecation contracts; exact Extend machine-checkable contracts so stale/superseded PR numbers, ACTIVE_PR→protected-main promotion, normative Python-production-fallback/NumPy-first wording, duplicate UML authority, broken local links/cardinalities, stale product/repository names and deterministic changelog drift fail closed. Run focused architecture/ADR/UML/ERD/traceability/changelog contracts plus renderer check and |
|
@opencode-agent address Reacquire the sole canonical #604 documentation-writer lease only after a final refetch confirms exact Draft head Use freshly updated issue #621 as the acceptance backlog. First reconcile current protected main non-destructively, preserving all accepted behavior through #733 and only #604's unique canonical documentation changes. Recalculate document availability, capability maturity and traceability from the integrated tree before editing prose. In particular #732 and #733 are protected-main behavior; #739 is active-PR-only judge error normalization; #738 replaces closed #717; #737 replaces closed #663; #735/#736/#734 remain active; #611/#564/#579/#558 require exact-current ancestry revalidation. Do not retain stale predecessor PRs as active authorities. Then close only still-real #621 gaps: two-axis document/capability maturity, Rust/PyO3 production numerical ownership vs explicit reference-only Python, versioned serialization/fingerprint/public interface/deprecation, exact Extend machine-checkable fitness rather than prose-only claims. Run focused architecture/ADR/UML/ERD/traceability/changelog contracts, renderer check, |
|
@opencode-agent address Reacquire the sole canonical documentation writer lease only after a final refetch confirms #604 exact head Use freshly updated #621 as the canonical acceptance backlog. First reconcile current protected main non-destructively and recalculate document availability, capability maturity and requirements-to-evidence from the integrated tree. Protected main now includes #733 and #739; #740/#738/#737/#735/#734 remain active-PR-only and closed predecessor branches are not authorities. Then close only still-real #621 semantic/fitness gaps and extend machine-checkable contracts rather than prose-only claims. Run focused architecture/ADR/UML/ERD/traceability/changelog checks, deterministic CHANGELOG renderer check and |
|
Superseded by surgical GREEN re-apply on current main (#docs baseline + ADR-0013 links). |
Land PRD/TRD, ADR corpus through ADR-0013, UML/ERD, threat model, and documentation contracts on current main. Cross-link continuous-execution governance (ADR-0013) and re-render authoritative CHANGELOG fragments. Supersedes conflicting draft #604.
* docs: establish canonical product and architecture baseline Land PRD/TRD, ADR corpus through ADR-0013, UML/ERD, threat model, and documentation contracts on current main. Cross-link continuous-execution governance (ADR-0013) and re-render authoritative CHANGELOG fragments. Supersedes conflicting draft #604. * fix(docs): align architecture title with baseline contract Keep the living architecture H1 and explicit Rust/recovery section phrases required by test_architecture_baseline_contract.
1 participant
Problem
The repository's architecture documentation outgrew the original
docs/prd_trd_summary.md. Protected main already contains governed assessment/scoring contracts, rubric generation/audit/pilot modules, automated-scoring adapters, Rust-first numerical ownership, release evidence, and downstream Psychometrics Commons boundaries, but the durable system design was fragmented across feature docs, research notes, PRs, and agent guidance.The legacy summary is materially stale: it describes an early NumPy-first MLS2PLM MVP and treats capabilities now present on protected main as future/out of scope. It is retained only as historical context and deprecated as an authoritative requirements source.
Canonical documentation baseline
This is the sole active cross-cutting documentation writer and establishes one canonical architecture package:
docs/PRD.md— current product requirements/non-goals;docs/TRD.md— Rust/PyO3/contracts/security/scientific/resource/release technical requirements;ARCHITECTURE.md— ownership, component, contract/data-flow, model-selection, lifecycle, numerical, security and deployment/composition views;docs/README.md— documentation authority/navigation;docs/adr/README.mdplus 13 status-bearing ADRs covering domain boundary, Rust numerical ownership, content-addressed contracts, governed rubric/item-bank lifecycle, fallible automated/human raters, relation-safe model selection, multilevel/time, true-parameter recovery CI, adaptive rotation, LLM orchestration/credentials, canonical PyO3/public-export registration, purpose-limited sensitive-data handling, and continuous execution/canonical-documentation governance;No parallel PRD/TRD/Architecture/ADR/UML/ERD authority should be created while this PR remains active.
Durable scientific/product decisions preserved
The baseline records, without promoting unmerged work to shipped behavior:
fast-mlsirmremains the standalone reusable measurement core while hosted HTTP/session/consent/tenant/RBAC/UI/database/deployment lifecycle remains downstream/Psychometrics Commons.Exact-current identity and RCA
Freshly revalidated:
main:8db4bf358b0a469915d6c5e336054f4a4f9c6b46;02569a3d6a7295c95b599e8b5c25f5c8eb69a63a;Status: **Accepted**;docs/TRD.mddoes not yet state thepsychometrics-commonshosted-product boundary required by the canonical contract;ARCHITECTURE.mddoes not yet link ADR-0013 continuous-execution/canonical-writer governance;CHANGELOG.mdis stale relative to authoritative fragments.A bounded exact-current OpenCode handoff already owns only those five repairs. Do not race or duplicate that source writer while head/main remain unchanged. Older comments/body identities such as
fe402bc...or protected main7516031...are predecessor evidence only.Remaining Draft gate
Keep Draft. The next documentation mutation is constrained to the five exact defects above: make the ADR-index parser tolerate only horizontal trailing whitespace rather than weakening status validation; state the hosted-product boundary in TRD; link/preserve ADR-0013 governance in Architecture/TRD; render/check
CHANGELOG.md; then require focused documentation contracts and a fresh unchanged-head full relevant CI/Security/SAST cycle.After that, require fresh current-head automated/independent review, zero valid unresolved architecture/scientific findings, and the repository's actual approval/branch-protection policy. This PR changes no numerical formula, runtime public API, physical DB schema, dependency, provider/reviewer credential authority or release version.