Skip to content

docs: establish canonical product architecture and evidence model - #105

Closed
seonghobae wants to merge 57 commits into
fix/atheris-interpreter-lockfrom
docs/canonical-product-architecture
Closed

docs: establish canonical product architecture and evidence model#105
seonghobae wants to merge 57 commits into
fix/atheris-interpreter-lockfrom
docs/canonical-product-architecture

Conversation

@seonghobae

@seonghobae seonghobae commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Status: canonical documentation stack — Draft on the #96 security line

This PR is the single documentation implementation authority for the product, technical, data, security, operability, governance, release, and acquisition-review graph. It does not claim certification, production readiness, independent approval, or that active-PR behavior has shipped.

Exact identity

  • base branch: fix/atheris-interpreter-lock
  • exact current base tip: c7d72824e5ecfc1086dfaad893709fede3175f27
  • branch: docs/canonical-product-architecture
  • exact contributor head: 2d93ee367f51eaa6874deed63c582533826c92bf
  • state: Draft
  • protected integration: absent

The branch contains a normal refresh onto the current #96 line. Every check, review, status, approval, and synthetic merge from another head/base pair is historical.

Canonical scope

  • root ARCHITECTURE.md and indexed docs/README.md;
  • PRD, TRD, UML, ERD, traceability, threat model, test strategy, operability, incident response, release/migration/rollback, references, and dated evidence appendices;
  • 16 indexed status-bearing ADRs covering orchestration, provider transport, workflow access, KV credentials, sync/batch, honest cost evidence, fallback, persistence, privacy, independent review, provenance, database naming, scientific-compute ownership, and complete coverage/docstrings;
  • machine contracts for canonical presence, discoverability, status vocabulary, ADR schema, Mermaid syntax, runtime/API/entity names, credential/host authority, implemented-versus-planned discipline, research licensing, local links, database naming, volatile-evidence separation, and live stack truth;
  • no unrelated production source change or suppression-only SAST annotation imported into this documentation line.

Latest test-first reconciliation

The exact GREEN blobs satisfy the new status predicates when evaluated against the canonical status lines. A local GitHub clone could not be used because the execution environment could not resolve github.com; that network failure is not test evidence. Hosted current-head workflows remain the acceptance authority.

Current exact-head evidence

For contributor head 2d93ee367f51eaa6874deed63c582533826c92bf:

  • Tests 31598248199: queued;
  • Security 31598248174: queued;
  • Fuzz 31598248113: queued.

Queued work is not success. Predecessor-head results do not transfer.

Review and merge boundary

Keep this PR Draft. After #96 reaches protected main, reconcile this graph onto the exact integrated result, regenerate every exact-head documentation, functional, security, fuzz, coverage/docstring, package/SBOM, and review gate, obtain zero valid unresolved findings plus qualifying independent approval, then merge through repository protection and run protected-main documentation/operational acceptance.

@coderabbitai

coderabbitai Bot commented Aug 9, 2026

Copy link
Copy Markdown

Review Change Stack

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0b94691b-4812-4876-aa27-4493e53040cd

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Contextual Orchestrator의 현재 아키텍처, 운영·보안 정책, 제품 요구사항, ADR, 추적성 문서를 추가했습니다. 문서 상태와 제품 명칭을 갱신하고, 문서 구조·Mermaid·링크·증거 상태를 검증하는 계약 테스트를 추가했습니다.

Changes

문서 권위와 제품 범위

Layer / File(s) Summary
거버넌스 및 제품 범위
AGENTS.md, CLAUDE.md, README.md, CHANGELOG.md, SECURITY.md, conductor/..., docs/analytics_spec.md, docs/library_research.md, docs/rest_api_design.md, docs/i18n_design.md
작성자 lease, 정확한 head 검증, KV 자격 증명, canonical 문서 갱신 규칙과 현재 제품·의존성 상태를 문서화했습니다.
아키텍처 및 데이터 계약
ARCHITECTURE.md, docs/PRD.md, docs/TRD.md, docs/ERD.md, docs/UML.md
런타임 구성, 실행 경로, 신뢰 경계, 저장 객체, 제품 요구사항과 현재 한계를 정의했습니다.
아키텍처 결정 기록
docs/adr/*
라우팅, 전송 보안, 접근 제어, 자격 증명, 배치, 비용, 저장, PII, 릴리스 및 독립 실행 경계를 16개 ADR로 추가했습니다.
운영 및 증거 문서
docs/README.md, docs/OPERABILITY.md, docs/INCIDENT_RUNBOOK.md, docs/RELEASE_GUIDE.md, docs/TEST_STRATEGY.md, docs/THREAT_MODEL.md, docs/TRACEABILITY.md, docs/REFERENCES.md
운영 신호, 사고 대응, 릴리스·롤백, 테스트 증거, 위협 모델, 참고문헌과 PR 추적성 규칙을 추가했습니다.
문서 계약 테스트
tests/test_documentation_contract.py, tests/test_plugin_driven_artifacts.py, tests/test_repository_security_metadata.py
필수 문서, 상태 어휘, Mermaid 문법, 링크, 최신 명칭, 저장 객체, 감사 증거와 에이전트 지침을 검증합니다.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related issues

  • ContextualWisdomLab/fast-mlsirm#621 — canonical 문서, 거버넌스와 기계 검증 가능한 문서 계약을 함께 다룹니다.
  • ContextualWisdomLab/life-os#148 — 문서 거버넌스, 자격 증명 경계, 연구 추적성과 계약 테스트가 연결됩니다.
  • ContextualWisdomLab/mightyETL#159 — canonical 아키텍처, live traceability, 상태 기반 문서 테스트와 writer safeguard가 관련됩니다.
  • ContextualWisdomLab/.github#895 — canonical 문서 그래프, 증거 지침, traceability와 문서 계약 테스트가 같은 목표를 다룹니다.
  • ContextualWisdomLab/EgressWeave#72 — buyer handoff, exact-head 증거와 자격 증명·네트워크 경계 문서가 관련됩니다.
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 75.86% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed 제목은 canonical 제품 아키텍처와 증거 모델을 수립하는 PR의 주요 변경 사항을 정확하고 간결하게 요약합니다.
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/canonical-product-architecture

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@seonghobae seonghobae changed the title docs: establish canonical product architecture docs: establish canonical product architecture and evidence model Aug 9, 2026
@seonghobae
seonghobae changed the base branch from main to fix/atheris-interpreter-lock August 9, 2026 14:05

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

Review exact current head 62a4983e4b5b237a8f5d30b0889cd5077d4ff356 against exact live base 3703d0da9823b8258a0be94f1801aa5d61bfad9f only; treat all predecessor-head evidence as stale. Focus on canonical-document status discipline, source-to-ADR/UML/ERD/test/operability traceability, current runtime/API/entity names, credential and host-authority boundaries, release/provenance claims, link and Mermaid integrity, and the machine-checkable documentation contract. Do not treat status-only evidence as approval, and report any actionable defect without changing the branch.

@coderabbitai

coderabbitai Bot commented Aug 11, 2026

Copy link
Copy Markdown

@seonghobae I will review PR #105 against the specified exact head and base. I will treat predecessor evidence and status-only evidence as non-acceptance evidence.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 8

🤖 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/0005-sync-batch-pg-llm-batch.md`:
- Around line 27-30: 두 ADR의 prompt-safe usage ledger 계약이 일관되지 않으므로, 모든 모드의
writer와 export 경로가 동일한 필수 계약을 따르도록 정렬하십시오.
docs/adr/0005-sync-batch-pg-llm-batch.md:27-30에서는 sync, batch retrieval,
passthrough, route streaming의 ledger row 및 evidence status 요구사항과
unknown/not_recorded 상태 및 cost comparison 제외 규칙을 명시하십시오.
docs/adr/0006-honest-cost-and-benchmark-evidence.md:24-31 및 62-66에서는 일곱
attribution dimension의 필드명·필수성·누락 규칙과 모든 writer/export 경로를 검증하는 mode별 완전성 테스트
요구사항을 추가하십시오. cost_router.py의 record_usage 호출 및 각 export 경로가 이 통합 계약을 충족하도록 구현과
문서를 검증하십시오.

In `@docs/ERD.md`:
- Around line 121-132: Update the WORKFLOW_STEP self-relationship in the ERD to
model access directionally: represent the consuming step pointing to the
previously authorized producer step, or introduce ACCESS_GRANT with explicit
consumer and producer step identifiers. Ensure producer_step_id is constrained
to reference only an earlier step and no longer imply bidirectional visibility.

In `@docs/i18n_design.md`:
- Around line 33-35: Update the dependency wording in the paragraph about
i18next and React-admin to use “planned adoption candidates” rather than
implying existing optional package extras. Preserve the statement that they
apply only to a separately built web client and do not own the current inline
admin call path; only document an actual extra name and ownership scope if such
an extra is confirmed to exist.

In `@docs/papers/README.md`:
- Line 11: Update the Hybrid LLM entry and its corresponding item in
docs/REFERENCES.md to link the licensing evidence to
https://arxiv.org/abs/2404.14618 or the applicable license URL, while retaining
the OpenReview URL as the paper source.

In `@docs/PRD.md`:
- Line 82: Align the coverage contract with ADR-0016 by adding function and line
coverage requirements alongside statement and branch coverage in PRD-010 at
docs/PRD.md lines 82-82, and apply the same function/line criteria to NFR-003 at
docs/TRD.md lines 50-55; keep both documents consistent with the ADR.

In `@docs/README.md`:
- Around line 33-41: Update docs/README.md lines 33-41 so every authority’s
State column uses only the defined state vocabulary; move non-state descriptions
such as “mixed, per ADR,” “dated audit,” and “repository policy” into the
appropriate separate description field. In tests/test_documentation_contract.py
lines 309-315, extend the canonical-set contract test to parse each State value
and reject any value outside the defined vocabulary.

In `@docs/UML.md`:
- Around line 139-142: Update the permanent caller/provider error branch in the
UML flow to terminate immediately without retrying or transitioning to Fallback.
Separate caller validation errors, transient failures, and explicitly permitted
provider failures into distinct branches, while preserving failover only for the
allowed provider-failure path and aligning the permanent-error behavior with the
architecture’s fail-fast contract.
- Around line 260-266: Update the UML dependency flow so credential lookup is
owned by a provider adapter: add a provider adapter node, replace the direct
policy --> kv edge with policy --> provider_adapter --> kv, and preserve the
existing policy orchestration connections.
🪄 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: 1173db1e-2c96-4809-8425-b74c24d3eefd

📥 Commits

Reviewing files that changed from the base of the PR and between 3703d0d and 62a4983.

⛔ Files ignored due to path filters (4)
  • docs/papers/frugalgpt-cost-2305.05176.pdf is excluded by !**/*.pdf
  • docs/papers/fuzzing-art-science-engineering-manes-2019.pdf is excluded by !**/*.pdf
  • docs/papers/hybrid-llm-query-routing-2404.14618.pdf is excluded by !**/*.pdf
  • docs/papers/routellm-routing-2406.18665.pdf is excluded by !**/*.pdf
📒 Files selected for processing (48)
  • AGENTS.md
  • ARCHITECTURE.md
  • CHANGELOG.md
  • CLAUDE.md
  • README.md
  • SECURITY.md
  • conductor/tech-stack.md
  • conductor/workflow.md
  • docs/ERD.md
  • docs/INCIDENT_RUNBOOK.md
  • docs/OPERABILITY.md
  • docs/PRD.md
  • docs/README.md
  • docs/REFERENCES.md
  • docs/RELEASE_GUIDE.md
  • docs/TEST_STRATEGY.md
  • docs/THREAT_MODEL.md
  • docs/TRACEABILITY.md
  • docs/TRD.md
  • docs/UML.md
  • docs/adr/0001-route-conduct-test-time-compute.md
  • docs/adr/0002-provider-neutral-transport-trust.md
  • docs/adr/0003-workflow-access-and-reasoning-control.md
  • docs/adr/0004-kv-credential-bootstrap.md
  • docs/adr/0005-sync-batch-pg-llm-batch.md
  • docs/adr/0006-honest-cost-and-benchmark-evidence.md
  • docs/adr/0007-free-first-fallback.md
  • docs/adr/0008-state-persistence-and-retention.md
  • docs/adr/0009-purpose-bound-pii-protection.md
  • docs/adr/0010-independent-review-and-evidence.md
  • docs/adr/0011-release-coverage-and-provenance.md
  • docs/adr/0012-standalone-and-cwl-boundary.md
  • docs/adr/0013-database-naming-and-migration.md
  • docs/adr/0014-scientific-computation-ownership.md
  • docs/adr/0015-provider-egress-response-trust.md
  • docs/adr/0016-complete-coverage-docstrings.md
  • docs/adr/README.md
  • docs/analytics_spec.md
  • docs/architecture.md
  • docs/fuzzing.md
  • docs/i18n_design.md
  • docs/library_research.md
  • docs/papers/README.md
  • docs/product_planning.md
  • docs/rest_api_design.md
  • tests/test_documentation_contract.py
  • tests/test_plugin_driven_artifacts.py
  • tests/test_repository_security_metadata.py

Comment thread docs/adr/0005-sync-batch-pg-llm-batch.md Outdated
Comment thread docs/ERD.md
Comment thread docs/i18n_design.md Outdated
Comment thread docs/papers/README.md Outdated
Comment thread docs/PRD.md Outdated
Comment thread docs/README.md Outdated
Comment thread docs/UML.md Outdated
Comment thread docs/UML.md

Copy link
Copy Markdown
Contributor Author

@opencode-agent @cwl-noema-review

Review exact current contributor head 3fce9bb61e9f48452dca1aba57541117dfdd4ef3 against exact live base 3703d0da9823b8258a0be94f1801aa5d61bfad9f. Treat all predecessor-head reviews and checks as historical. Report only current-head actionable findings; do not treat model review as independent human approval.

Copy link
Copy Markdown
Contributor Author

Addressed the valid current-head CodeRabbit finding from comment 5261787836 in exact head 5543d1b493ceb9dbac485e10347820929d6bee92. The dated audit now states 16 of 17 open PRs were Draft, and test_dated_open_pr_snapshot_matches_the_audited_inventory parses every row and fails closed when the aggregate total or Draft count differs from the table. RED reproduced as assert 17 == 16; focused GREEN passed, the documentation/security subset passed 39 tests, and the full local suite passed 597 tests with 100% production statement/line (3,667/3,667), branch (934/934), and public-docstring coverage. Hosted exact-head workflows and fresh automated review remain pending; this is not approval evidence.

Copy link
Copy Markdown
Contributor Author

@opencode-agent @cwl-noema-review

Review exact current contributor head 5543d1b493ceb9dbac485e10347820929d6bee92 against exact live base 3703d0da9823b8258a0be94f1801aa5d61bfad9f. The only delta from reviewed predecessor 3fce9bb61e9f48452dca1aba57541117dfdd4ef3 is the test-first Draft-inventory aggregate repair. Treat all predecessor-head reviews and checks as historical. Report only current-head actionable findings; do not treat model review as independent human approval.

Copy link
Copy Markdown
Contributor Author

@coderabbitai full review
@opencode-agent @cwl-noema-review

Review exact current contributor head 5e1505d500db0106961293404b4ab146024c9ae5 against exact live base 3703d0da9823b8258a0be94f1801aa5d61bfad9f. Treat every predecessor-head, status-only, author-only, dismissed, synthetic-merge, queued, or model result as non-transferable.

This bounded delta adds the indexed 2026-08-12 continuation evidence appendix, preserves the 2026-08-11 audit as immutable history, and adds a machine-checkable latest-appendix contract. Test-first RED produced four focused failures; exact-head Tests 31569432117 then checked out the contributor SHA directly and passed 598 tests with 100% production statement/branch and public-docstring coverage. Exact-head Security 31569432093 and Fuzz 31569432113 are terminal-success; their jobs also checked out this contributor SHA directly. Inline threads are zero.

Verify live-state accuracy and implemented/active/planned discipline; exact-head versus integration-evidence classification; required evidence-index discoverability; local-link and Markdown integrity; central read-only authority; and that no active PR, model review, certification, release, or protected-main acceptance is overstated. Report only current-head actionable findings. Do not treat any automated/model review as qualifying independent human approval.

@coderabbitai

coderabbitai Bot commented Aug 12, 2026

Copy link
Copy Markdown

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

head="5e1505d500db0106961293404b4ab146024c9ae5"
base="3703d0da9823b8258a0be94f1801aa5d61bfad9f"
repo="ContextualWisdomLab/contextual-orchestrator"

printf '%s\n' '== Exact revision verification =='
printf 'checked_out='; git rev-parse HEAD
printf 'head='; git rev-parse "$head"
printf 'base='; git rev-parse "$base"
git merge-base --is-ancestor "$base" "$head"
printf '%s\n' 'base_is_ancestor=true'
git diff --check "$base" "$head"

printf '%s\n' '== Exact-range changes =='
git diff --name-status "$base" "$head"
git log --format='%H %s' --reverse "$base..$head"
printf '%s\n' '== Delta from reviewed predecessor =='
git diff --name-status 5543d1b493ceb9dbac485e10347820929d6bee92 "$head" || true
git diff --unified=70 5543d1b493ceb9dbac485e10347820929d6bee92 "$head" -- \
  docs/evidence tests/test_documentation_contract.py docs/README.md docs/TRACEABILITY.md

printf '%s\n' '== Candidate file map =='
fd -t f . docs/evidence docs tests 2>/dev/null | sort | sed -n '1,240p'
ast-grep outline tests/test_documentation_contract.py --items all

printf '%s\n' '== Evidence and contract references =='
rg -n -C 12 \
  '2026-08-11|2026-08-12|continuation|appendix|latest|evidence index|evidence/|integration|exact-head|protected.main|approval|certif|model review|active_pr|implemented_on_protected_main|planned|read-only|central' \
  docs/evidence docs/README.md docs/TRACEABILITY.md tests/test_documentation_contract.py AGENTS.md CLAUDE.md 2>/dev/null || true

printf '%s\n' '== Changed evidence and index files with line numbers =='
for path in $(git diff --name-only "$base" "$head" -- '*.md' | grep -E '(^docs/evidence/|^docs/README\.md$|^docs/TRACEABILITY\.md$)' || true); do
  printf '\n-- %s --\n' "$path"
  nl -ba "$path"
done

printf '%s\n' '== Markdown-local-link inspection for changed Markdown files =='
python3 - <<'PY'
import pathlib
import re
import subprocess
from urllib.parse import unquote

base = "3703d0da9823b8258a0be94f1801aa5d61bfad9f"
head = "5e1505d500db0106961293404b4ab146024c9ae5"
changed = subprocess.check_output(
    ["git", "diff", "--name-only", base, head, "--", "*.md"], text=True
).splitlines()
pattern = re.compile(r'(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+["\'][^)]*["\'])?\)')
broken = []
for name in changed:
    path = pathlib.Path(name)
    for line_no, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
        for target in pattern.findall(line):
            if target.startswith(("#", "http://", "https://", "mailto:")):
                continue
            target_path = target.split("#", 1)[0]
            if target_path and not (path.parent / unquote(target_path)).resolve().exists():
                broken.append(f"{name}:{line_no}: {target}")
print("\n".join(broken) if broken else "PASS: no broken local Markdown targets in changed Markdown files.")
PY

printf '%s\n' '== Changed Markdown byte integrity =='
python3 - <<'PY'
import pathlib
import re
import subprocess

base = "3703d0da9823b8258a0be94f1801aa5d61bfad9f"
head = "5e1505d500db0106961293404b4ab146024c9ae5"
changed = subprocess.check_output(
    ["git", "diff", "--name-only", base, head, "--", "*.md"], text=True
).splitlines()
bad = []
for name in changed:
    data = pathlib.Path(name).read_bytes()
    trailing = [str(n) for n, line in enumerate(data.splitlines(), 1)
                if re.search(rb"[ \t]+$", line)]
    if trailing or data.endswith(b"\n\n"):
        bad.append(f"{name}: trailing_lines={','.join(trailing) or '-'} final_blank_line={data.endswith(b'\\n\\n')}")
print("\n".join(bad) if bad else "PASS: no changed Markdown trailing whitespace or final blank line.")
PY

printf '%s\n' '== Live PR state; informational only =='
gh pr view 105 --repo "$repo" \
  --json number,headRefOid,baseRefOid,state,isDraft,mergeStateStatus,reviewDecision,statusCheckRollup,reviews \
  2>&1 || true

printf '%s\n' '== Open PR inventory; compare against documentation only =='
gh pr list --repo "$repo" --state open --limit 100 \
  --json number,isDraft,headRefOid,baseRefOid,mergeStateStatus \
  2>&1 || true

Length of output: 151755


🏁 Script executed:

#!/bin/bash
set -euo pipefail

head="5e1505d500db0106961293404b4ab146024c9ae5"
prior="5543d1b493ceb9dbac485e10347820929d6bee92"
base="3703d0da9823b8258a0be94f1801aa5d61bfad9f"
repo="ContextualWisdomLab/contextual-orchestrator"

printf '%s\n' '== Identity relationship =='
git merge-base --is-ancestor "$prior" "$head" && echo 'prior_is_ancestor=true'
git merge-base "$prior" "$head"
git log --format='%H %P %s' -n 3 "$head"
printf '%s\n' '-- PR `#105` row and identity qualification --'
grep -n -C 5 -E '^\| `#105` |pre-write|post-write|current-head|historical|latest' \
  docs/evidence/2026-08-12-continuation-audit.md docs/evidence/README.md

printf '%s\n' '== Changed Markdown local links =='
python3 - <<'PY'
import pathlib
import re
import subprocess
from urllib.parse import unquote

base = "3703d0da9823b8258a0be94f1801aa5d61bfad9f"
head = "5e1505d500db0106961293404b4ab146024c9ae5"
files = subprocess.check_output(
    ["git", "diff", "--name-only", base, head, "--", "*.md"], text=True
).splitlines()
pattern = re.compile(r'(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+["\'][^)]*["\'])?\)')
broken = []
for name in files:
    path = pathlib.Path(name)
    for line_number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
        for target in pattern.findall(line):
            if target.startswith(("#", "http://", "https://", "mailto:")):
                continue
            destination = target.split("#", 1)[0]
            if destination and not (path.parent / unquote(destination)).resolve().exists():
                broken.append(f"{name}:{line_number}: {target}")
print("\n".join(broken) if broken else "PASS")
PY

printf '%s\n' '== Changed Markdown byte integrity =='
python3 - <<'PY'
import pathlib
import re
import subprocess

base = "3703d0da9823b8258a0be94f1801aa5d61bfad9f"
head = "5e1505d500db0106961293404b4ab146024c9ae5"
files = subprocess.check_output(
    ["git", "diff", "--name-only", base, head, "--", "*.md"], text=True
).splitlines()
violations = []
for name in files:
    data = pathlib.Path(name).read_bytes()
    trailing = [str(i) for i, line in enumerate(data.splitlines(), 1)
                if re.search(rb"[ \t]+$", line)]
    if trailing or data.endswith(b"\n\n"):
        violations.append(
            f"{name}: trailing_lines={','.join(trailing) or '-'} final_blank_line={data.endswith(b'\\n\\n')}"
        )
print("\n".join(violations) if violations else "PASS")
PY

printf '%s\n' '== Contract coverage for PR `#105` pre-write semantics =='
grep -n -C 6 -E 'LATEST_EVIDENCE_APPENDIX|latest|pre-write|post-write|`#105`|5543d1b' \
  tests/test_documentation_contract.py

printf '%s\n' '== Live PR `#105` metadata; not approval evidence =='
gh pr view 105 --repo "$repo" \
  --json number,headRefOid,baseRefOid,state,isDraft,mergeStateStatus,reviewDecision,statusCheckRollup,reviews \
  2>&1 || true

printf '%s\n' '== Live open PR numbers; compare only =='
gh pr list --repo "$repo" --state open --limit 100 --json number,isDraft,headRefOid \
  2>&1 || true

Length of output: 10832


🏁 Script executed:

#!/bin/bash
set -euo pipefail

base="3703d0da9823b8258a0be94f1801aa5d61bfad9f"
head="5e1505d500db0106961293404b4ab146024c9ae5"
repo="ContextualWisdomLab/contextual-orchestrator"

printf '%s\n' '== Diff integrity =='
git diff --check "$base" "$head"

printf '%s\n' '== Changed Markdown byte integrity =='
python3 - <<'PY'
import pathlib
import re
import subprocess

base = "3703d0da9823b8258a0be94f1801aa5d61bfad9f"
head = "5e1505d500db0106961293404b4ab146024c9ae5"
files = subprocess.check_output(
    ["git", "diff", "--name-only", base, head, "--", "*.md"], text=True
).splitlines()
violations = []
for name in files:
    data = pathlib.Path(name).read_bytes()
    trailing = [
        str(line_number)
        for line_number, line in enumerate(data.splitlines(), 1)
        if re.search(rb"[ \t]+$", line)
    ]
    final_blank_line = data.endswith(b"\n\n")
    if trailing or final_blank_line:
        violations.append(
            "{}: trailing_lines={} final_blank_line={}".format(
                name, ",".join(trailing) or "-", final_blank_line
            )
        )
print("\n".join(violations) if violations else "PASS")
PY

printf '%s\n' '== Live PR `#105` metadata; informational only =='
gh pr view 105 --repo "$repo" \
  --json number,headRefOid,baseRefOid,state,isDraft,mergeStateStatus,reviewDecision,statusCheckRollup,reviews \
  2>&1 || true

printf '%s\n' '== Live open PR inventory; informational only =='
gh pr list --repo "$repo" --state open --limit 100 --json number,isDraft,headRefOid \
  2>&1 || true

Length of output: 12848


@seonghobae Current-head finding

docs/evidence/2026-08-12-continuation-audit.md, Line 63 records PR #105 at 5543d1b493ceb9dbac485e10347820929d6bee92. That SHA is the direct parent of the reviewed head. The live PR #105 head is 5e1505d500db0106961293404b4ab146024c9ae5.

The continuation appendix does not state that its PR #105 row is a pre-write snapshot. The generic rule at Lines 9-12 says evidence becomes historical after a branch change. It does not state that the commit which adds this appendix changed the documented PR #105 branch. The index calls this appendix “Latest collected evidence.” A reader can therefore misclassify the Line 63 workflow evidence as evidence for the current PR #105 head.

Add an explicit pre-write rule for the appendix’s own PR #105 row. State that the appendix commit advances that branch and that the row is not current-head evidence after publication. Extend test_evidence_index_identifies_and_validates_the_latest_appendix to require this statement and reject a weakened version.

I verified the requested head and base. git diff --check is clean. The changed Markdown files have valid local links and no trailing whitespace or final blank lines.

Live GitHub state shows that PR #105 is Draft. Its aggregate reviewDecision is empty. The completed workflow checks are not qualifying independent human approval.

You are interacting with an AI system.

Copy link
Copy Markdown
Contributor Author

Addressed the current-head CodeRabbit finding from comment 5263151274 test-first in b62cc165b6c585cf4e03deca3d1236c630db64ef.

The documentation contract first failed RED because the appendix lacked a mutation-resistant identity statement. The repair now states that PR #105 is a pre-write snapshot, publishing advances the branch, and the recorded row must not be treated as current-head evidence after publication. The focused documentation suite passes 30 tests; the full local suite passes 598 tests with 100% production statement/branch and public-docstring coverage. Exact-head hosted Tests, Security, and Fuzz are queued and are not yet promoted to success.

Copy link
Copy Markdown
Contributor Author

Exact-head deterministic gates are now complete on b62cc165b6c585cf4e03deca3d1236c630db64ef: Tests 31570694025, Security 31570694022, and Fuzz 31570693969 are terminal-success, every relevant job checked out the contributor SHA directly, and the current CodeRabbit snapshot-identity finding is addressed test-first.

@coderabbitai full review
@opencode-agent
@cwl-noema-review

Please review only the unchanged current head. Automated/model review is evidence but is not substituted for the required eligible independent non-author approval.

@coderabbitai

coderabbitai Bot commented Aug 12, 2026

Copy link
Copy Markdown

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

head="b62cc165b6c585cf4e03deca3d1236c630db64ef"
base="3703d0da9823b8258a0be94f1801aa5d61bfad9f"
prior="5e1505d500db0106961293404b4ab146024c9ae5"
repo="ContextualWisdomLab/contextual-orchestrator"

printf '%s\n' '== Exact revision verification =='
printf 'checked_out='; git rev-parse HEAD
printf 'head='; git rev-parse "$head"
printf 'base='; git rev-parse "$base"
git merge-base --is-ancestor "$base" "$head"
printf '%s\n' 'base_is_ancestor=true'
git merge-base --is-ancestor "$prior" "$head"
printf '%s\n' 'prior_is_ancestor=true'

printf '%s\n' '== Exact range integrity =='
git diff --check "$base" "$head"
git diff --name-status "$base" "$head"
git log --format='%H %s' --reverse "$base..$head"

printf '%s\n' '== Delta since previously reviewed head =='
git diff --name-status "$prior" "$head"
git diff --unified=100 "$prior" "$head" -- \
  docs/evidence/2026-08-12-continuation-audit.md \
  docs/evidence/README.md \
  tests/test_documentation_contract.py

printf '%s\n' '== Relevant source maps =='
ast-grep outline tests/test_documentation_contract.py --items all

printf '%s\n' '== Evidence identity and contract semantics =='
rg -n -C 18 \
  'pre-write|post-write|publishing|advances the branch|current-head|current head|not.*current|`#105`|latest.*appendix|continuation|identity|mutation' \
  docs/evidence/2026-08-12-continuation-audit.md \
  docs/evidence/README.md \
  tests/test_documentation_contract.py

printf '%s\n' '== Local Markdown link and byte integrity for changed Markdown =='
python3 - <<'PY'
import pathlib
import re
import subprocess
from urllib.parse import unquote

base = "3703d0da9823b8258a0be94f1801aa5d61bfad9f"
head = "b62cc165b6c585cf4e03deca3d1236c630db64ef"
names = subprocess.check_output(
    ["git", "diff", "--name-only", base, head, "--", "*.md"], text=True
).splitlines()
pattern = re.compile(r'(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+["\'][^)]*["\'])?\)')
broken, byte_violations = [], []
for name in names:
    path = pathlib.Path(name)
    data = path.read_bytes()
    trailing = [str(i) for i, line in enumerate(data.splitlines(), 1)
                if re.search(rb"[ \t]+$", line)]
    if trailing or data.endswith(b"\n\n"):
        byte_violations.append(
            f"{name}: trailing={','.join(trailing) or '-'} final_blank={data.endswith(b'\\n\\n')}"
        )
    for line_number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
        for target in pattern.findall(line):
            if target.startswith(("#", "http://", "https://", "mailto:")):
                continue
            destination = target.split("#", 1)[0]
            if destination and not (path.parent / unquote(destination)).resolve().exists():
                broken.append(f"{name}:{line_number}: {target}")
print("broken_links=" + ("; ".join(broken) if broken else "none"))
print("byte_violations=" + ("; ".join(byte_violations) if byte_violations else "none"))
PY

printf '%s\n' '== Exact-head workflow runs =='
gh run view 31570694025 --repo "$repo" --json databaseId,headSha,status,conclusion,jobs 2>&1 || true
gh run view 31570694022 --repo "$repo" --json databaseId,headSha,status,conclusion,jobs 2>&1 || true
gh run view 31570693969 --repo "$repo" --json databaseId,headSha,status,conclusion,jobs 2>&1 || true

printf '%s\n' '== Live PR state; informational and not approval evidence =='
gh pr view 105 --repo "$repo" \
  --json number,headRefOid,baseRefOid,state,isDraft,mergeStateStatus,reviewDecision,reviews,statusCheckRollup \
  2>&1 || true

Length of output: 78363


🏁 Script executed:

#!/bin/bash
set -euo pipefail

head="b62cc165b6c585cf4e03deca3d1236c630db64ef"
base="3703d0da9823b8258a0be94f1801aa5d61bfad9f"
repo="ContextualWisdomLab/contextual-orchestrator"

printf '%s\n' '== Exact range whitespace diagnostics =='
git diff --check "$base" "$head"

printf '%s\n' '== Changed Markdown local links and byte integrity =='
python3 - <<'PY'
import pathlib
import re
import subprocess
from urllib.parse import unquote

base = "3703d0da9823b8258a0be94f1801aa5d61bfad9f"
head = "b62cc165b6c585cf4e03deca3d1236c630db64ef"
names = subprocess.check_output(
    ["git", "diff", "--name-only", base, head, "--", "*.md"], text=True
).splitlines()
pattern = re.compile(r'(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+["\'][^)]*["\'])?\)')
broken = []
byte_violations = []

for name in names:
    path = pathlib.Path(name)
    data = path.read_bytes()
    trailing = [
        str(i)
        for i, line in enumerate(data.splitlines(), 1)
        if re.search(rb"[ \t]+$", line)
    ]
    final_blank = data.endswith(b"\n\n")
    if trailing or final_blank:
        byte_violations.append(
            "{}: trailing={} final_blank={}".format(
                name, ",".join(trailing) if trailing else "-", final_blank
            )
        )
    for line_number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
        for target in pattern.findall(line):
            if target.startswith(("#", "http://", "https://", "mailto:")):
                continue
            destination = target.split("#", 1)[0]
            if destination and not (path.parent / unquote(destination)).resolve().exists():
                broken.append("{}:{}: {}".format(name, line_number, target))

print("broken_links=" + ("; ".join(broken) if broken else "none"))
print("byte_violations=" + ("; ".join(byte_violations) if byte_violations else "none"))
PY

printf '%s\n' '== Exact-head workflow runs =='
for run_id in 31570694025 31570694022 31570693969; do
  gh run view "$run_id" --repo "$repo" \
    --json databaseId,headSha,status,conclusion,jobs \
    --jq '{databaseId, headSha, status, conclusion, jobs: [.jobs[] | {name, status, conclusion}]}' \
    2>&1 || true
done

printf '%s\n' '== Live PR state; informational and not approval evidence =='
gh pr view 105 --repo "$repo" \
  --json number,headRefOid,baseRefOid,state,isDraft,mergeStateStatus,reviewDecision,reviews,statusCheckRollup \
  2>&1 || true

Length of output: 13124


@seonghobae I reviewed exact head b62cc165b6c585cf4e03deca3d1236c630db64ef against exact base 3703d0da9823b8258a0be94f1801aa5d61bfad9f.

I found no current-head actionable defect in the reviewed scope.

The prior snapshot-identity finding is addressed. docs/evidence/2026-08-12-continuation-audit.md now states that the PR #105 row is a pre-write snapshot, publication advances the branch, and the row cannot serve as current-head evidence after publication. tests/test_documentation_contract.py requires that complete statement.

The requested base and the prior reviewed head are ancestors of the reviewed head. git diff --check is clean. The changed Markdown files have no broken local links, trailing whitespace, or final blank lines.

Tests 31570694025, Security 31570694022, and Fuzz 31570693969 completed successfully on the requested head. PR #105 remains Draft and has no aggregate reviewDecision. The completed automated checks do not constitute eligible independent non-author approval.

You are interacting with an AI system.

* test(security): require coordinated disclosure lifecycle

* docs(security): define disclosure lifecycle and support boundary

* docs(doctoring): record disclosure standards evidence

* docs(doctoring): clarify advisory collaboration evidence

* test(security): match reporter-credit policy wording

* test(docs): bind SSDF draft authorship evidence

* docs(security): correct SSDF draft authorship citation

* test(docs): carry canonical changelog contract

* docs: carry canonical changelog entry

* docs(security): fail closed disclosure policy evidence

* test: enforce private reporting release gate
@seonghobae

Copy link
Copy Markdown
Contributor Author

Closed by autonomous commercial loop: PR targets non-main base fix/atheris-interpreter-lock (stack intermediate). Re-open against current main after #111#114 land if the product gap remains. (docs: establish canonical product architecture and evidence model)

@seonghobae seonghobae reopened this Aug 12, 2026
test_reopened_nim_scaffold_is_superseded_without_false_closed_state
correctly flags any TRACEABILITY.md line that mentions PR #115 (open,
reopened, classified superseded) alongside "closed-unmerged" wording
that actually describes predecessor PR #90's status, not #115's.

Split the two facts onto lines that don't co-occur: the #86 backlog
table row and prose paragraph now state PR #90's closed-unmerged
predecessor status separately from PR #115's open/superseded status.
No factual claim changes, only which physical line each claim sits on.
@seonghobae

Copy link
Copy Markdown
Contributor Author

Superseded: 98% file overlap (53/54) with #120 (canonical doc suite rebuild) and #113 (security disclosure lifecycle + repository security metadata test), both already open and green. The one remaining unique file (tests/test_documentation_current_truth.py) is not carried forward — #120's tests/test_documentation_contract.py (1022 lines) covers the same doc-truth-contract surface. Closing to avoid a stale duplicate sitting in the review queue.

@seonghobae seonghobae closed this Aug 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant