docs: audit architecture and clarify README evidence boundaries

[sumitake]

Summary

Audit all nine existing public architecture pages and the root README against current source and release evidence. Correct logical-agent terminology, identify the public client's native-runtime process boundary, and document the actual scope of the optional package-README version check.

Closes #230. The package README stays the immutable tagged snapshot. No executable logic, runtime artifacts, generated skills, manifests, versions, or release tags change. The release checker change is module documentation/comments only; its executable AST is byte-equivalent after excluding the module docstring.

Boundaries and generated surfaces

• No executor source, invocation recipe, credential, private absolute path, retired package, downloader, or host preset added.
• Skills and marketplaces pass generator parity checks.
• Unique changelog fragment added; generated CHANGELOG.md unchanged.
• No version bump: repository documentation only, no distributed package-content or behavior change.

Verification

• Public tests: 275 passed.
• Script tests: 461 passed; focused release consistency regressions: 67 passed.
• Release consistency: passes, including exactly one 7.0.8 What's new showcase.
• Active-tree export safety, secret scan, local Markdown target checks, and diff whitespace check pass.
• Active-tree plus reachable-history export safety passes in a fresh full clone of the canonical public remote at exact head 29298893dbb45678ba9baab928a9611faec42670. The earlier partial-clone scan was cancelled while reading missing objects; this successful comparison does not clear that incomplete clone or prior exposure.
• Grok returned PROCEED on this exact head; raw content and adjudication: docs: audit architecture and clarify README evidence boundaries #231 (comment). Its model observation is configuration-scoped, so this remains advisory, not independent-family approval. No lineage-repair replay occurred.
• Code/security reviews completed at this head. Fully paginated reviews, conversation comments, inline threads, and all 48 check annotations were inventoried. No actionable findings or unresolved threads. Negative-fixture error annotations are informational: the corresponding suites intentionally exercise rejection paths and all checks succeeded. CodeRabbit explicitly skipped review and is not counted as approval.

Review and post-condition

Tier 1, prose/comment-only. Read-only Terra research is same-family research, not independent approval. Required CI and complete review-surface inventory must pass before ordinary merge. Verify exact remote-main contents after merge; no publication, restart, or host qualification is authorized or claimed by this PR.

author: codex
standing_directives: AGENTS.md, public-governance.md, source boundaries, fragment-only changelog, exact-source verification
tier: 1
cross_check: N/A — Tier 1 documentation and comment-only fast path
post_condition: verify merged remote-main documentation and latest-only README; package snapshot and executable logic unchanged
mcp_coverage_gap: NONE
contributor_rights: OWNER-AUTHORED
operator_reserved: no

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 365430a3-049d-4f52-99fd-c1669c301d0a

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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

• X
• Mastodon
• Reddit
• LinkedIn

---

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

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-11T00:19:47.589818Z	2929889	PR opened
🔒 Security Review	✅ Completed 2026-10-11T00:20:24.546074Z	2929889	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[sumitake]

Bounded Grok advisory review

Request 34605e77-fd59-4a61-b547-b23ce6af43c6, unit public-plugin, reviewed exact head 29298893dbb45678ba9baab928a9611faec42670. Native execution and cleanup succeeded. Native identity was grok-4.7-build-fast, source acp.session.model, scope initial_session_configuration; it is not response-correlated identity. This is useful advisory evidence, not independent-family governance approval. No replay was issued to improve lineage. Tier 1 does not require that approval.

Raw returned content

I'll review the exact head read-only: architecture claims, sanitization, source/release/host boundaries, and whether the checker comments leave executable logic unchanged.The checkout is exactly 29298893. Next I’ll compare the new prose with the checker, manifest, and runtime ownership sources.The checker diff is comments only so far. I’ll check the marker logic, the logical-agent error, and who owns the process group.PROCEED. Head 29298893 matches the sources I read. The checker change is comments and a docstring only. This session’s xAI lineage is configuration only; no response-correlated native evidence was observed, so this is not independent-family approval.

extract_plugin_readme_version still compares a legacy Current: **X.Y.Z** marker only when one is present. The package README has none (Current published release: **7.0.7** does not match). An absent marker still yields neither pass nor fail. The root README has one ## What's new - v7.0.8 showcase.

The manifest and tree agree with the audit: package 7.0.8, runtime 5.0.9, schema 4, protocol 5, native contract 4, wire 12, arm64 and x86_64, 12 logical actions, 8 logical agents, and 53 generated skills. The parent baseline is 86b883aa. Skills, manifests, the package README, and tags are untouched. Nine pre-existing handbook pages remain; the new audit is additive.

coordinator.py maps provider aliases onto logical agents and forwards an unknown explicit_target. The status page already records target_agent_unsupported. One client.invoke uses start_new_session=True, bounded streams, and killpg TERM/KILL/reap of that runtime group. Bounded streams, deadline, TERM/KILL/reap, and no hidden replay stay in the root README. The audit keeps the package snapshot immutable and claims no new release, host, or provider qualification.

The strongest counterargument is that the frozen package README and the 7.0.8 changelog still say “unsupported explicitly named provider,” and the package file still says publication is pending at 7.0.7. The new handbook text tells readers to compare the exact tag or archive and treats the regex as a marker check only. This clone has no v7.0.8 object, so that byte identity was not rechecked here.

killpg also signals descendants that remain in the runtime’s group. The public client still creates only the runtime process. “Deadline enforcement” sits beside the existing admitted-progress paragraph, which still says active work is not killed by a strict elapsed timer.

Unverified here: tag/archive byte equality, native emission of target_agent_unsupported (status evidence, absent from public Python), and whether “Terra” is a public-safe label. It appears only in the new audit, with no credential, path, or private implementation. Confidence is high on the diff, checker behavior, and inventory, and moderate on tag identity.

Primary adjudication

No blocking prose findings. The frozen reference's dated publication state is intentional; current status belongs in current repository docs. The primary confirmed the package README has no diff from the recorded release commit c9035d9c5e5d6e7771d00f740b5178e8f8dadbb9. No fresh archive or host qualification is claimed. Terra is the research model label, not an operator/private-system identifier. All counts were checked against the manifest/generated inventory; the checker AST comparison excludes only its module docstring and is unchanged. The reviewer’s lineage limitation is retained, not repaired by another call.

[sumitake]

Final review inventory cutoff: 2026-10-11 00:27:42 UTC, head 2929889. All formal reviews and issue comments paginated; inline threads and their comments exhausted (none); all 18 check runs and 48 annotations read. Codex code/security surfaces successfully completed. No actionable findings. CodeRabbit skipped (informational, not approval); runner notices and deliberate negative-fixture error annotations are informational. Grok advisory PROCEED is preserved with its configuration-only identity limitation. Ordinary Tier-1 merge only; no admin bypass.

[sumitake]

Post-merge readback: canonical remote main verified at fa79ada; GitHub verifies the merge signature. The root README has exactly one v7.0.8 showcase, the new audit exists, and distributed plugins/skills/marketplace trees are unchanged from the audited baseline. Issue #230 is closed. No release, installation, or native qualification was performed.