[rasokiwayami]

Summary

Makes the repository easier for both humans and AI agents to understand and
change, without changing what it does. Every runtime behaviour is preserved
byte-for-byte; the one executable change is a de-duplication inside
evidence_graph.py.

The package is ~1,440 lines of source and ~1,400 of tests. It did not have a
structural problem — it had a legibility problem and a decay problem. The work
is deliberately documentation-heavy and code-light.

What changed

Phase	Commit	Change
1	feb8ef0	New docs/architecture.md (module map, entrypoints, platform limits, validation conventions, boundary coverage) and CLAUDE.md; AGENTS.md upgraded to a real steering document; module docstrings across the package
2	5f01f1d	Corrected docs/project-notes.md, which claimed "No CLI is included in the initial release" while the repo ships two console scripts; added a harness pointer to docs/ja.md
3	f79d71e	README reordered so the fastest path (Copy-Paste Prompt) comes first; new ## Documentation index. No heading text changed — anchors are a public contract
4	d518f03	Moved the 24 KB historical build record to docs/implementation-record.md. The name implementation-notes.md previously meant three different things at once
5	4ffe814	The only executable change. The kind/decision validation rule was written twice in evidence_graph.py — once in _validate_event, once in append_event. Extracted to one private helper
6	75e2ffd	pyproject.toml metadata (readme, dependencies, urls, classifiers) and a CONTRIBUTING.md
7	a060974	Minimal CI: the existing test suite on Python 3.10–3.13
8	0817a80	Golden files pinning the exact public CLI output, plus four documentation-consistency assertions

Behaviour preservation

• CLI golden hashes unchanged from origin/main:
  • typed-rejection → b0da9e30e75a49216df2c3f3b00f756647255d580e34353d83cc9de2cbf5cba0, exit 2
  • adjudication → 506913d4b6e2af907488719fe9d889466e75069d1d5af802d5155c2969f7774d, exit 0
• No change to package, module, or function names; CLI names or flags; exit
  codes; JSON keys or key ordering; error strings; the eight skills; the six
  templates; either plugin manifest; or any README heading.
• No existing test was modified. Tests went 60 → 66; all six additions are in
  Phase 8.
• pyproject.toml changes are additive only.

What was deliberately not done

• evidence_graph.py was not split despite being 401 lines across five
  concerns — no demonstrated maintenance failure, and the diff would land in the
  most safety-relevant file for zero behaviour change. The seam is documented in
  docs/architecture.md instead, with the condition that should trigger it.
• No formatter, type checker, or repository-wide reformat.
• No renames, no repository split, no new runtime dependency (still stdlib-only).
• An earlier draft added a shared boundary-assertion helper across the
  serializers. It was cut on review: it bans three key names while appearing to
  prove absence of authority, and it is machinery built to prove an existing
  boundary. docs/architecture.md now states honestly what is and is not
  mechanically checked.

Test plan

• python3 -m unittest discover -s tests -q — 66 tests, OK
• Both plugin manifests validate as JSON
• git diff --check
• Both CLI golden hashes match the pre-refactor baseline
• Offline install into a fresh virtualenv; installed console scripts run
• Every relative Markdown link resolves; every docs/*.md reachable from
  README (2 of 6 → 8 of 8)
• Phase 5: 3,584-case comparison of the old and new validation paths — zero
  error-code or precedence mismatches
• Phase 4: moved file body is byte-identical (SHA-256 verified)
• Phase 8: new tests confirmed to fail when the contract they pin is broken
• CI has not run on a GitHub-hosted runner yet — this PR is its first
  execution

Reviewed independently before this PR was opened; the reviewer's priority was
Phase 5's behavioural equivalence and Phase 4's rename purity.

🤖 Generated with Claude Code