Skip to content

docs: guide README readers from use case to architecture - #23

Merged
aDragon0707 merged 1 commit into
mainfrom
codex/readme-reader-journey
Oct 15, 2026
Merged

aDragon0707 merged 1 commit into
mainfrom
codex/readme-reader-journey

Conversation

@aDragon0707

@aDragon0707 aDragon0707 commented Oct 15, 2026 •

Copy link
Copy Markdown
Owner

Summary

The README introduced internal components and test inventories before showing an end-to-end use case. Both language versions now follow the same reading path:

Use case → release decision → runnable demo → three-layer architecture
         → repository PR practice → integration paths → evidence and boundaries

Keep the protocol, online engine and offline harness visible in the framework diagram. Move detailed suite commands and contracts behind existing documentation links, retain material trust limits, and link a verified PR/main run as a concrete example. Only README.md and README.zh-CN.md change.

Evidence

  • Before: quick start began with the breaker harness; source-role and suite tables preceded the repository's own use case.
  • After: python -m examples.github_release_gate prints False / True / False as documented; python -m sacp_harness reports 8/8 breakers, 3/3 positive controls and 49/49 strict-valid documents. Both commands exit 0.
  • python .local/check-docs.py and git diff --check pass. The linked historical main run was freshly checked: success at 48ba192.
  • No runtime, protocol, workflow or dependency changes. Counts describe the linked run, not a new independent benchmark. Current-head CI and the formal receipt will be checked before merge.

Review at base 48ba19209b7ea6f9d833193f92319cee0eed291a, head f5f9f48dc5e79d3db6e398612607a53bd07e3113: no blocking findings. Bilingual chapter order and diagrams match; the diagram separates protocol validity, runtime projection and offline evaluation. Example outcomes and limits match implementation. PR CI 38677927509 passed all eight required jobs. Receipt 38677993395 is COMPLETE/200, strict PASS, bound to this head, with no policy warnings or evidence errors. Proceed with manual squash merge at this head and inspect the resulting main verification.

Post-merge: main e4dd99c292ae797b0e7e4e0a86c75fc1c8e5acbb, run 38678076325, all seven jobs success. Downloaded all six suite artifacts and receipt; verified exact counts, zero failures/errors/skips, SHA/run binding and independently recomputed tree fingerprint. Main receipt COMPLETE/200, strict PASS. No branch deletion.

Merge Danger

Door: two-way

Documentation-only changes can be reverted in a subsequent PR.

Blast Radius: documentation

Review bilingual consistency, runnable commands, links, diagram relationships and public claim boundaries. Actual fork E2E remains unverified; writer authentication and side-effect execution stay with integrations.

@aDragon0707
aDragon0707 merged commit e4dd99c into main Oct 15, 2026
8 checks passed
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