docs: establish integrated PRD TRD ADR architecture UML and ERD baseline - #600
docs: establish integrated PRD TRD ADR architecture UML and ERD baseline#600seonghobae wants to merge 30 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 authoritative architecture, product, technical, persistence, governance, diagram, and documentation coverage baselines. Added tests that validate document presence, terminology, boundaries, Mermaid contracts, and governance requirements. ChangesArchitecture and governance baseline
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 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 |
|
Exact-head documentation architecture review requested for Review the PRD/TRD/Architecture/UML/ERD/coverage-matrix/ADR set as a coherent system contract, not as isolated prose. In particular check for: contradictions with protected-main code/README/AGENTS/CLAUDE; Draft/planned features presented as implemented; incorrect fast-mlsirm vs psychometrics-commons ownership; missing traceability for rubric→item→screening→calibration→bank, automated scoring, reference-free RAG, enterprise issue measurement, structural model selection, bifactor scoreability, rotation, recovery, hierarchy/time, Rust/PyO3 and release; invalid Mermaid/ERD semantics; inaccurate standards/scientific claims; and a stale/broken documentation link or test contract. Read-only review only; do not modify the branch or merge. @coderabbitai review |
🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
base='4d910ed650f384ff882c8b5fba6a8b08fd532236'
head='3f4409bba2d9e452832beb230546bc0d8d3d94bf'
echo '== Exact commits =='
git cat-file -e "${base}^{commit}"
git cat-file -e "${head}^{commit}"
git rev-parse "$base" "$head"
echo '== Changed files =='
git diff --name-status "$base" "$head"
echo '== Root and documentation guidance files at protected base =='
for path in README.md AGENTS.md CLAUDE.md; do
if git cat-file -e "${base}:${path}" 2>/dev/null; then
echo "--- ${path} @ base ---"
git show "${base}:${path}" | sed -n '1,260p'
fi
done
echo '== Baseline-document outlines and documentation test =='
for path in \
ARCHITECTURE.md \
docs/PRD.md \
docs/TRD.md \
docs/UML.md \
docs/ERD.md \
docs/documentation_coverage_matrix.md \
docs/adr/ADR-0001-product-boundaries-and-scientific-governance.md \
docs/prd_trd_summary.md \
tests/test_documentation_architecture_baseline.py \
CHANGELOG.md; do
if git cat-file -e "${head}:${path}" 2>/dev/null; then
echo "--- ${path} @ head ---"
git show "${head}:${path}" | sed -n '1,420p'
fi
done
echo '== Documentation-related diff =='
git diff --no-ext-diff --unified=40 "$base" "$head" -- \
ARCHITECTURE.md docs tests/test_documentation_architecture_baseline.py CHANGELOG.md \
| sed -n '1,2600p'
echo '== Repository file candidates for implementation-claim comparison =='
fd -HI -t f -E .git \
'^(Cargo\.toml|pyproject\.toml|README\.md|AGENTS\.md|CLAUDE\.md|.*\.(rs|py))$' \
| sed -n '1,700p'
echo '== Protected-base capability and boundary evidence =='
git grep -n -i -E \
'PyO3|Rust|bifactor|rotation|recovery|multilevel|longitudinal|time|CAT|ordinal|RAG|rubric|item.bank|calibrat|automated scor|enterprise issue|psychometrics-commons|release' \
"$base" -- README.md AGENTS.md CLAUDE.md '*.rs' '*.py' 2>/dev/null \
| sed -n '1,1800p' || trueLength of output: 202381 🏁 Script executed: #!/bin/bash
set -euo pipefail
base='4d910ed650f384ff882c8b5fba6a8b08fd532236'
head='3f4409bba2d9e452832beb230546bc0d8d3d94bf'
docs=(
ARCHITECTURE.md
docs/PRD.md
docs/TRD.md
docs/UML.md
docs/ERD.md
docs/documentation_coverage_matrix.md
docs/adr/ADR-0001-product-boundaries-and-scientific-governance.md
docs/prd_trd_summary.md
tests/test_documentation_architecture_baseline.py
)
echo '== Changed paths and change statistics =='
git diff --name-status "$base" "$head"
git diff --stat "$base" "$head"
echo '== Heading, status, ownership, traceability, and standards inventory =='
for path in "${docs[@]}"; do
echo "--- ${path} ---"
git show "${head}:${path}" \
| nl -ba \
| grep -E '^[[:space:]]*[0-9]+[[:space:]]+(#|.*\b(Draft|planned|implemented|fast-mlsirm|psychometrics-commons|rubric|item bank|screening|calibration|automated scoring|RAG|enterprise issue|model selection|bifactor|scoreability|rotation|recovery|multilevel|longitudinal|time|PyO3|Rust|release|ISO|NIST|Testing)\b)' \
| sed -n '1,850p' || true
done
echo '== Full new documentation files with line numbers =='
for path in "${docs[@]}"; do
echo "--- BEGIN ${path} ---"
git show "${head}:${path}" | nl -ba
echo "--- END ${path} ---"
done
echo '== Markdown link targets and anchors: static checks =='
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT
for path in "${docs[@]:0:8}"; do
mkdir -p "$tmp/$(dirname "$path")"
git show "${head}:${path}" > "$tmp/$path"
done
git archive "$head" | tar -x -C "$tmp"
python3 - "$tmp" "${docs[@]:0:8}" <<'PY'
import os, re, sys
root = sys.argv[1]
files = sys.argv[2:]
link_re = re.compile(r'(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+["\'][^)]*["\'])?\)')
for rel in files:
full = os.path.join(root, rel)
print(f"--- {rel} ---")
text = open(full, encoding="utf-8").read()
for target in link_re.findall(text):
if target.startswith(("#", "http://", "https://", "mailto:")):
continue
target = target.split("#", 1)[0]
if not target:
continue
candidate = os.path.normpath(os.path.join(os.path.dirname(full), target))
print(("OK " if os.path.exists(candidate) else "MISS ") + target)
PY
echo '== Mermaid fences and ERD relationship lines =='
for path in ARCHITECTURE.md docs/UML.md docs/ERD.md; do
echo "--- ${path} ---"
git show "${head}:${path}" | nl -ba \
| grep -E '```mermaid|```|classDiagram|sequenceDiagram|flowchart|C4Context|C4Container|erDiagram|^[[:space:]]*[A-Za-z_].*(\|\||\}\||o\||\|o|--|==)' \
| sed -n '1,1000p' || true
done
echo '== Exact protected-base evidence for explicit architecture claims =='
git grep -n -i -E \
'hosted|HTTP|session|consent|tenant|authorization|persistence|RAG|rubric|item.bank|enterprise.issue|automated.scor|recovery|longitudinal|multilevel|response.time|bifactor|rotation' \
"$base" -- README.md AGENTS.md CLAUDE.md 'crates/**/*.rs' 'python/**/*.py' 'src/**/*.py' \
| sed -n '1,1300p' || true
echo '== Documentation contract test assertions =='
git show "${head}:tests/test_documentation_architecture_baseline.py" | nl -ba | sed -n '1,900p'Length of output: 5382 🏁 Script executed: #!/bin/bash
set -euo pipefail
base='4d910ed650f384ff882c8b5fba6a8b08fd532236'
head='3f4409bba2d9e452832beb230546bc0d8d3d94bf'
docs='ARCHITECTURE.md docs/PRD.md docs/TRD.md docs/UML.md docs/ERD.md docs/documentation_coverage_matrix.md docs/adr/ADR-0001-product-boundaries-and-scientific-governance.md docs/prd_trd_summary.md tests/test_documentation_architecture_baseline.py docs/changelog.d/architecture-documentation-baseline.md'
number() { awk '{printf "%6d\t%s\n", NR, $0}'; }
echo '== Full changed baseline documents =='
for path in $docs; do
echo "--- BEGIN ${path} ---"
git show "${head}:${path}" | number
echo "--- END ${path} ---"
done
echo '== Mermaid and ERD source blocks =='
for path in ARCHITECTURE.md docs/UML.md docs/ERD.md; do
echo "--- ${path} ---"
git show "${head}:${path}" | awk '
/^```mermaid[[:space:]]*$/ {active=1; print NR ":" $0; next}
active {print NR ":" $0}
active && /^```[[:space:]]*$/ {active=0}
'
done
echo '== Static relative Markdown link checks =='
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT
git archive "$head" | tar -x -C "$tmp"
for path in $docs; do
case "$path" in
*.md)
echo "--- ${path} ---"
grep -oE '\]\(([^ )#]+)(#[^ )]+)?\)' "$tmp/$path" \
| sed -E 's/^\]\(//; s/\).*//' \
| while IFS= read -r target; do
case "$target" in
http:*|https:*|mailto:*|'') continue ;;
esac
candidate=$(dirname "$tmp/$path")/$target
if [ -e "$candidate" ]; then
printf 'OK %s\n' "$target"
else
printf 'MISS %s\n' "$target"
fi
done || true
;;
esac
done
echo '== Required cross-document terms and their line locations =='
for path in $docs; do
echo "--- ${path} ---"
git show "${head}:${path}" | awk '
BEGIN { IGNORECASE=1 }
/psychometrics-commons|hosted|HTTP|session|consent|tenant|persistence|rubric|item bank|screening|calibration|automated scoring|reference-free RAG|enterprise issue|structural model selection|bifactor|scoreability|rotation|recovery|multilevel|longitudinal|response-time|PyO3|Rust-first|release|ISO\/IEC 25010|ISO\/IEC 42001|NIST AI RMF|NIST AI 600-1/ {
printf "%d:%s\n", NR, $0
}' | sed -n '1,1000p'
done
echo '== Protected-base source evidence for planned boundary features =='
git grep -n -i -E \
'reference-free RAG|retrieval.augmented|rubric.*item|item.*bank|enterprise.issue|hosted HTTP|tenant authorization|session|consent|product persistence|longitudinal estimator|multilevel estimator' \
"$base" -- ':(glob)**/*.rs' ':(glob)**/*.py' README.md AGENTS.md CLAUDE.md \
| sed -n '1,700p' || true
echo '== Protected-base source evidence for implemented core claims =='
git grep -n -i -E \
'bifactor_indices|select_rotation_criterion|fit.*multilevel|fit_rt|automated.*scor|agreement|recovery|Vuong|cat_next_item' \
"$base" -- ':(glob)**/*.rs' ':(glob)**/*.py' README.md AGENTS.md CLAUDE.md \
| sed -n '1,1000p' || trueLength of output: 203503 🏁 Script executed: #!/bin/bash
set -euo pipefail
log=/tmp/coderabbit-shell-logs/shell-output-NKeCx5
echo '== Section locations in the successful inspection log =='
grep -n -E \
'^--- BEGIN |^--- END |^== Mermaid|^== Static relative|^== Required cross-document|^== Protected-base source evidence' \
"$log" | sed -n '1,260p'
echo '== Static link-check results =='
sed -n '/^== Static relative Markdown link checks ==$/,/^== Required cross-document terms and their line locations ==$/p' "$log"
echo '== Mermaid and ERD blocks =='
sed -n '/^== Mermaid and ERD source blocks ==$/,/^== Static relative Markdown link checks ==$/p' "$log"Length of output: 22134 🏁 Script executed: #!/bin/bash
set -euo pipefail
log=/tmp/coderabbit-shell-logs/shell-output-NKeCx5
echo '== ARCHITECTURE.md =='
sed -n '2,172p' "$log"
echo '== docs/PRD.md =='
sed -n '173,309p' "$log"
echo '== docs/TRD.md =='
sed -n '310,525p' "$log"
echo '== docs/ERD.md =='
sed -n '822,1101p' "$log"
echo '== Coverage matrix, ADR, legacy summary, documentation test, and changelog fragment =='
sed -n '1102,1526p' "$log"Length of output: 79398
The remaining baseline is coherent in this review. It consistently preserves the Rust-first boundary, the ✅ Action performedReview finished.
|
|
@jules address Finish the documentation baseline on this existing Draft branch only. Re-read the exact branch head and current protected After that merge, run |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
tests/test_documentation_architecture_baseline.py (1)
79-91: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick winAssert the ERD relationship contract.
This test checks Mermaid markers and entity names only. It accepts both incorrect edges currently present in
docs/ERD.md. Add positive assertions for the corrected edges and negative assertions for the obsolete forms so the documentation gate protects the logical schema.Proposed assertions
assert "release_bundle" in erd + assert "score_observation ||--o{ contextual_membership" in erd + assert "contextual_membership ||--o{ score_observation" not in erd + assert "generated_item_version ||--o{ item_bank_entry" in erd + assert "generated_item_version ||--o{ item_bank_version" not in erd + assert "calibration_run ||--o{ item_bank_entry" in erd🤖 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 `@tests/test_documentation_architecture_baseline.py` around lines 79 - 91, Extend test_uml_and_erd_contain_machine_renderable_mermaid_contracts with positive assertions for the corrected ERD relationship edges and negative assertions rejecting the obsolete edge forms, using the exact relationship text defined in docs/ERD.md. Keep the existing Mermaid marker and entity-name assertions unchanged.
🤖 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/ERD.md`:
- Around line 20-26: Update the ERD associations so score_observation is the
parent with zero or more contextual_membership rows, reversing the
contextual_membership—score_observation cardinality. Replace the direct
generated_item_version—item_bank_version promotion edge with associations
through item_bank_entry, preserving its item_version_id, item_bank_version_id,
and calibration_run_id relationships and calibration provenance.
---
Nitpick comments:
In `@tests/test_documentation_architecture_baseline.py`:
- Around line 79-91: Extend
test_uml_and_erd_contain_machine_renderable_mermaid_contracts with positive
assertions for the corrected ERD relationship edges and negative assertions
rejecting the obsolete edge forms, using the exact relationship text defined in
docs/ERD.md. Keep the existing Mermaid marker and entity-name assertions
unchanged.
🪄 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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 514f7a87-159e-4f56-a8e1-d199377b1787
📒 Files selected for processing (10)
ARCHITECTURE.mddocs/ERD.mddocs/PRD.mddocs/TRD.mddocs/UML.mddocs/adr/ADR-0001-product-boundaries-and-scientific-governance.mddocs/changelog.d/architecture-documentation-baseline.mddocs/documentation_coverage_matrix.mddocs/prd_trd_summary.mdtests/test_documentation_architecture_baseline.py
|
Closing as a competing documentation-baseline path. #604 is the designated canonical branch because it already includes current-base PRD/TRD, ten status-bearing ADRs, PlantUML component/sequence/state/deployment views, a logical ERD, requirements/research traceability, changelog material, and explicit retirement of the stale early PRD/TRD summary, and it now has one bounded OpenCode writer lease. The unique useful |
|
@jules address The documentation baseline PR was reopened because it was closed unmerged even though its branch remains mergeable and contains the requested PRD/TRD/Architecture/UML/ERD plus the more granular ADR-0001…0009, ADR template/index, capability-maturity and requirements-traceability documents. Re-read exact current head Merge protected python scripts/render_changelog_fragments.py --update CHANGELOG.md
python scripts/render_changelog_fragments.py --check CHANGELOG.md
python -m pytest -q tests/test_documentation_architecture_baseline.pyAlso run a bounded grep/contract check against current |
|
Closing this duplicate architecture-baseline branch in favor of #604, which is now the single canonical documentation authority after the #604/#605 writer-race was resolved. #604 has the broader maintained scope (separate status-bearing ADRs, PlantUML component/sequence/deployment/item-state views, logical ERD, threat model, traceability/research basis, canonical PyO3/export and purpose-limited data ADRs, changelog rendering path, and current OpenCode writer lease). Preserve this branch/history as design reference only; no checks/reviews/approvals transfer. Any genuinely unique requirement from this branch must be folded into #604 under its current lease rather than maintaining a competing PR. |
|
Closing this parallel documentation baseline as superseded by canonical PR #604. #604 now contains the broader durable architecture package and has explicitly absorbed the non-duplicative requirements identified here: current PRD/TRD/root architecture, status-bearing ADR corpus, canonical PyO3 registry decision, PlantUML component/sequence/deployment views, persistence-neutral ERD, reusable-core threat model, requirements/research traceability, implementation-maturity/documentation-completeness audit, stale-summary deprecation, changelog material, and a machine-checkable documentation contract. #604 is also the single branch currently held by the bounded OpenCode documentation writer. Preserve this branch/history for audit only; no checks/reviews transfer, and no further architecture edits belong here unless #604 is explicitly superseded by a later reviewed replacement. |
2 participants
Purpose
Establish one reviewable architecture/product baseline for the accepted fast-mlsirm research and product direction instead of relying on scattered RFCs and a stale early
docs/prd_trd_summary.md.This PR is documentation-first and repository-boundary preserving. It covers the reusable measurement core only; hosted HTTP/session/consent/product persistence/tenant authorization/UI/deployment remain owned by
ContextualWisdomLab/psychometrics-commonsor another downstream bounded context.Baseline included
ARCHITECTURE.mdwith C4-style context/container views, Rust↔PyO3↔Python ownership, model-selection hierarchy, rubric→item-bank lifecycle, automated scoring/RAG/enterprise-issue boundaries, multilevel/time contracts, privacy and release gates;docs/PRD.mdcovering users/JTBD, functional and non-functional requirements, commercial/scientific claim boundaries and acceptance gates;docs/TRD.mdmapping those requirements to Rust/PyO3/Python, model selection, scoreability, rotation, generated-item trust, scoring, RAG, multilevel/time, AI credential, CI and release requirements;docs/UML.mdwith text-reviewable Mermaid component/class/sequence/deployment views;docs/ERD.mdas a logical persistence-neutral artifact model, explicitly not a fast-mlsirm ORM/database ownership claim;docs/adr/ADR-0001-product-boundaries-and-scientific-governance.mdfor the major cross-cutting architecture/scientific decisions;docs/documentation_coverage_matrix.mdwith pre-baseline defects, current coverage, residual documentation gaps and explicit future update triggers;tests/test_documentation_architecture_baseline.pyto pin the required document set, Rust-first/hosted-product boundary, multilevel/time/recovery rules, Mermaid UML/ERD and governing standards;Documentation audit finding
Protected
mainhad strong topical doctoring plusAGENTS.md/CLAUDE.md, but it lacked a root architecture document and dedicated current PRD/TRD/UML/ERD/ADR baseline. The olddocs/prd_trd_summary.mddescribed NumPy as the default runtime backend and ordinal/CAT work as outside MVP, contradicting current README/AGENTS/CLAUDE and protected-main capabilities.The baseline now closes those system-level gaps while retaining method-specific RFCs/doctoring as the source of detailed formulas and implementation evidence.
Remaining documentation triggers, not omissions in this baseline
The coverage matrix deliberately records follow-up documents that should be created only when the relevant implementation stabilizes: a canonical composed PyO3 registry ADR; full Vuong distinguishability/boundary-comparison math contract; governed item-bank lifecycle state machine; canonical reference-free RAG observation schema; production multilevel/longitudinal estimator architecture; cross-repository CSAP/SOC 2 control mapping; and buyer workbench/Figma information architecture.
Scientific/standards boundary
Method-specific formulas remain governed by primary peer-reviewed psychometric sources and method-specific doctoring. ISO/IEC 25010:2023, ISO/IEC 42001:2023, NIST AI RMF 1.0/NIST AI 600-1 and the Standards for Educational and Psychological Testing inform product-quality, governance, TEVV, validity and fairness controls but do not constitute certification, validity or regulatory approval by themselves.
Merge gates
Keep Draft until the exact final head passes the documentation contract test and the repository's required CI/security gates,
CHANGELOG.mdis rendered from the new fragment, and current-head review finds no actionable contradiction. No product/scientific capability becomes available merely because its planned architecture is documented.Summary by CodeRabbit
Documentation
Tests