docs: consolidate process/meta docs for cohesion and accuracy

[mazze93]

Summary

A docs-only cohesion pass: one clear role per document, and a single source of truth for version, known issues, history, and architecture decisions. No source code is touched. Net −182 lines.

What changed

• CHANGELOG.md (new) — folds the still-accurate content of IMPROVEMENTS.md and REVIEW.md into a conventional Keep-a-Changelog history, dropping their drifted line-number citations and the mislabeled "v1.1".
• Removed IMPROVEMENTS.md and REVIEW.md — superseded by CHANGELOG.md. They had drifted into inaccuracy (a v1.1 label on a v0.3.0 project, stale SynapseCore.swift:NNN line refs, "7 tests" when there are now 10, and an offer to "create a GitHub Actions CI" that already exists).
• AGENTS.md — rewritten as a thin, accurate pointer to CLAUDE.md. Removes a leaked personal local path (/Users/daedalus/…) and a reference to a non-existent ContextRegion type (the real type is Region).
• docs/adr/README.md (new) — a single ADR index that disambiguates the two ADR tracks that historically reuse the numbers 002–004: foundational/ethics (referee, consent boundaries) vs. bedrock/circuit (prediction-error, lighthouse floor, decay amplifier). Non-breaking — no source-code comments were renumbered; the index explains how to read an ADR-00X reference by domain.
• ROADMAP.md — replaced the inline ADR log with a pointer to the index; corrected the "shipped" file list (SynapseContent/DecayConstants live in InteractionRecord.swift, not separate files), added Edgar + the bedrock circuit, marked assemblePrompt resolved, and refreshed the date.
• SECURITY.md, Resources/docs/INSTALL.md — dropped the phantom "v1.1" label and the dangling REVIEW.md link.

Notes for the reviewer

• The ADR-number collision is real and baked into source comments (ADR-002 means "operational-context boundary" in SynapseReferee.swift but "prediction-error propagation" in the circuit code). I deliberately did not renumber — that should be a deliberate, atomic change you own. The new index makes the current state legible in the meantime.
• The remaining REVIEW.md links in README.md/INSTALL.md are removed by docs: tighter value proposition, accuracy fixes, maintenance posture #11's rewrite of those files, so no dangling links remain once both PRs land. If this merges before docs: tighter value proposition, accuracy fixes, maintenance posture #11, there's a brief window where the old README/INSTALL link to the removed REVIEW.md; merging docs: tighter value proposition, accuracy fixes, maintenance posture #11 (or this) closes it.

Test plan

• Build, test, and guardrails green (docs-only; required files all still present)
• ADR index links resolve; ROADMAP no longer duplicates the ADR log or the Known-Issues drift

https://claude.ai/code/session_01BBeeaADak63VbvE7kuYw96

---

Generated by Claude Code

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (8)

• AGENTS.md is excluded by none and included by none
• CHANGELOG.md is excluded by none and included by none
• IMPROVEMENTS.md is excluded by none and included by none
• REVIEW.md is excluded by none and included by none
• ROADMAP.md is excluded by none and included by none
• Resources/docs/INSTALL.md is excluded by none and included by none
• SECURITY.md is excluded by none and included by none
• docs/adr/README.md is excluded by none and included by none

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 84fd570b-032d-4d97-b7d2-45ef19885833

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/docs-cohesion

---

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

[mazze93]

Bringing you up to date
@claude we should plan another thorough review of all documentation, address key bugs, prepare a reliable stage, and begin work on the decay layer. I have some exciting updates to share about that! Also, could we commit the arxiv paper here so versions align with the build?