[v0.3.0] docs — write ADR-006 (Serialization)

[ayhammouda]

Closes #49

Acceptance criteria

• docs/architecture/ADR-006-serialization.md exists and fills every section of the template embedded below (no placeholder text left). — test -f docs/architecture/ADR-006-serialization.md passed; rg -n "<!--|TODO|TBD|placeholder|\.\.\." docs/architecture/ADR-006-serialization.md returned no matches.
• Status is Accepted (decisions 5.4/5.5 are already locked) with date 2026-05-29 and decider @ayhammouda. — ADR header contains Status: Accepted, Date: 2026-05-29, and Deciders: @ayhammouda.
• The "Decision Outcome" states verbatim the locked shape: compact JSON is the default; format="toon" is opt-in and gated by the v0.3.0 empirical study (5.4); the format parameter exists on search_docs, list_versions, compare_versions only; get_docs stays markdown (5.5); TOON-as-storage is rejected (5.3). — Verified in docs/architecture/ADR-006-serialization.md Decision Outcome.
• The "Layer Contract" section names the serializer as one of the eight layers (principle 2.7) and states its inputs (structured tool result model), outputs (wire string), and invariant (serialization is a pure function of the result + chosen format; no behavior change for clients that don't opt in). — Verified with targeted rg checks for the inputs, outputs, invariants, and eight-layer sentence.
• "Considered Options" includes at least: JSON-only, JSON-default-with-TOON-opt-in (chosen), and TOON-as-storage (rejected, ref 5.3); and notes that the win must hold after client-side rewrap (5.8), not just on raw payload. — Verified in the Considered Options and Decision Outcome sections.
• uv run python-docs-mcp-server doctor passes (this is a docs-only change; no code touched). — Doctor passed with all checks green.

Validation gate output

$ uv run ruff check src/ tests/
All checks passed!

$ uv run pyright src/
0 errors, 0 warnings, 0 informations

$ uv run pytest --tb=short -q
298 passed in 26.59s

$ uv run python-docs-mcp-server doctor
All checks passed.

Issue-specific ADR/link/path checks:

$ test -f docs/architecture/ADR-006-serialization.md
# passed

$ rg -n "<!--|TODO|TBD|placeholder|\.\.\." docs/architecture/ADR-006-serialization.md
# no matches

$ rg -n 'Status:\*\* Accepted|Date:\*\* 2026-05-29|Deciders:\*\* @ayhammouda|compact JSON is the default|format="toon"|search_docs|list_versions|compare_versions|get_docs` stays markdown|TOON-as-storage is rejected|client-side rewrap|serializer is one of the eight|Inputs:\*\* Structured tool result model|Outputs:\*\* Wire string|Invariants:\*\* Serialization is a pure function' docs/architecture/ADR-006-serialization.md
# required terms found

$ rg -n 'Final file path: `docs/architecture/ADR-006-serialization.md`|TOKEN-STUDY.md' .planning/agent-context/adr-006-serialization.md
# required context decision-log entries found

$ git diff --check
# passed

GitHub checks after PR open:

CI matrix: pass
Security Audit / Dependency audit: pass
CodeQL / Analyze: pass
CodeRabbit: pass

CodeRabbit review

• Blocking: None
• Follow-up: None
• False positive: None

CodeRabbit status check passed with no required code changes.

Why this approach

The issue prescribed the ADR skeleton and the locked serialization decisions; this PR records those decisions without adding implementation or new architecture choices.

Why this triggered supervisor review

None.

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (2)

• .planning/agent-context/adr-006-serialization.md is excluded by none and included by none
• docs/architecture/ADR-006-serialization.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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 70c53451-71e0-4ebd-bd9d-197dfb8db531

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 agent/49-adr-006-serialization

---

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 and usage tips.}

[ayhammouda]

Heimdall verification passed for PR #55 at head 98b183c48b1f19170dc6f1be10ac90e7ece79b3e.

Independent checkout: /tmp/heimdall-pr55-iVoye7/repo, fetched from pull/55/head.

Scope verified:

• Diff only touches .planning/agent-context/adr-006-serialization.md and adds docs/architecture/ADR-006-serialization.md.
• No source, tests, tool signatures, workflows, dependency metadata, or other forbidden-territory files changed.
• Issue [v0.3.0] docs — write ADR-006 (Serialization) #49 docs-only ADR acceptance criteria are covered: ADR sections present, status/date/decider match, locked serialization shape is stated, layer contract names serializer inputs/outputs/invariant, considered options include JSON-only / JSON-default+TOON-opt-in / TOON-as-storage rejected, and context decision log links the final ADR path plus future token study.

Commands run:

uv sync --dev
uv run ruff check src/ tests/
uv run pyright src/
uv run pytest --tb=short -q
uv run python-docs-mcp-server doctor
git diff --name-status origin/main...HEAD
git diff --check origin/main...HEAD
rg -n "<!--|TODO|TBD|placeholder|\.\.\." docs/architecture/ADR-006-serialization.md
rg -n 'Status:\*\* Accepted|Date:\*\* 2026-05-29|Deciders:\*\* @ayhammouda|compact JSON is the default|format="toon"|search_docs|list_versions|compare_versions|get_docs` stays markdown|TOON-as-storage is rejected|client-side rewrap|serializer is one of the eight|Inputs:\*\* Structured tool result model|Outputs:\*\* Wire string|Invariants:\*\* Serialization is a pure function' docs/architecture/ADR-006-serialization.md
rg -n 'Final file path: `docs/architecture/ADR-006-serialization.md`|TOKEN-STUDY.md' .planning/agent-context/adr-006-serialization.md
gh pr checks 55 --repo ayhammouda/python-docs-mcp-server
gh api graphql ... reviewThreads/reviews for PR #55

Evidence:

ruff: All checks passed!
pyright: 0 errors, 0 warnings, 0 informations
pytest: 298 passed in 24.25s
doctor: All checks passed.
git diff --check: passed
placeholder scan: no matches
GitHub checks: CI matrix pass, Security Audit pass, CodeQL pass, CodeRabbit pass
CodeRabbit review threads: none

CodeRabbit triage: no blocking or follow-up findings. CodeRabbit's status is green; it skipped review due to repository path filters for the docs/planning files, so there were no inline findings to resolve.

Label action: replacing verification-needed with verified. No merge or approval performed.