CodeClone Contracts Book¶

This book is the contract-level documentation for CodeClone v2.x.

All guarantees here are derived from code and locked tests. If a statement is not enforced by code/tests, it is explicitly marked as non-contractual.

How to read¶

• Start with Terminology → Architecture map → Intro.
• Then read the pipeline spine: Core pipeline → CFG → Report → HTML render → Baseline → Cache.
• Change control (Structural Change Controller, Engineering Memory, Claim Guard) is the governance layer.
• Everything else is supporting detail, invariants, and reference.

Table of Contents¶

Foundations¶

• 00-intro.md — book charter and goals
• 01-terminology.md — glossary
• 02-architecture-map.md — authoritative module table

Pipeline and data¶

• 03-core-pipeline.md — canonical pipeline contract
• 04-cfg-semantics.md — CFG design and semantics
• 05-report.md — report contract (schema v2.11)
• 06-html-render.md — HTML rendering contract
• 07-baseline.md — baseline contract (schema v2.1)
• 08-cache.md — cache contract (schema v2.10)

Contracts and config¶

• 09-exit-codes.md — exit codes and failure policy
• 10-config-and-defaults.md — config reference
• 11-cli.md — CLI behavior and modes

Change control¶

• 12-structural-change-controller/index.md — overview
• 12-structural-change-controller/finish-controlled-change.md — finish pipeline
• 12-structural-change-controller/finish-hygiene.md — hygiene blocking vs advisory
• 12-structural-change-controller/patch-trail.md — Patch Trail
• 13-engineering-memory/index.md — evidence-linked repository memory
• 14-claim-guard.md — review claim validation

Quality signals¶

• 15-health-score.md — health score model
• 16-metrics-and-quality-gates.md — metrics mode and gate flags
• 17-dead-code-contract.md — dead-code detection and test-boundary policy
• 18-suggestions-and-clone-typing.md — suggestions and clone typing
• 19-inline-suppressions.md — # codeclone: ignore[...]
• 20-benchmarking.md — reproducible Docker benchmarking

System properties¶

• 21-security-model.md — security model and threat boundaries
• 22-determinism.md — determinism policy
• 23-testing-as-spec.md — tests as specification
• 24-compatibility-and-versioning.md — compatibility and versioning rules
• 26-platform-observability.md — local diagnostics for CodeClone's own runtime
• 27-corpus-analytics.md — offline intent corpus clustering (optional [analytics])

MCP interface¶

• 25-mcp-interface/index.md — MCP interface contract
• 25-mcp-interface/tools/workflow.md — workflow tools
• 25-mcp-interface/resources.md — resource URIs
• 25-mcp-interface/tools/platform-observability.md — bounded diagnostics tool

Integrations¶

• integrations/vs-code-extension.md — VS Code extension contract
• integrations/cursor-plugin.md — Cursor plugin contract
• integrations/claude-code-plugin.md — Claude Code plugin contract
• integrations/codex-plugin.md — Codex plugin contract
• integrations/claude-desktop-bundle.md — Claude Desktop bundle contract
• integrations/sarif.md — SARIF projection contract

Appendix¶

• appendix/a-status-enums.md — status enums and typed contracts
• appendix/b-schema-layouts.md — schema layouts (baseline/cache/report)
• appendix/c-error-catalog.md — error catalog (contract vs internal)