feat: complete spec 2.0.0 architecture and UX updates

Author: orenlab

.gitignore

@@ -32,4 +32,7 @@ htmlcov/
 .DS_Store
 
 # Logs
-*.log
+*.log
+/.claude/
+/docs/SPEC-2.0.0.md
+/.uv-cache/

AGENTS.md

@@ -3,37 +3,44 @@
 This document is the **source of truth** for how AI agents should work in this repository.
 It is optimized for **determinism**, **CI stability**, and **reproducible changes**.
 
-> Repository goal: maximize **honesty**, **reproducibility**, **determinism**, and **precision** for real‑world CI usage.
+> Repository goal: maximize **honesty**, **reproducibility**, **determinism**, and **precision** for real‑world CI
+> usage.
 
 ---
 
 ## 1) Operating principles (non‑negotiable)
 
 1. **Do not break CI contracts.**
-   - Treat baseline, cache, and report formats as **public APIs**.
-   - Any contract change must be **versioned**, documented, and accompanied by tests.
+    - Treat baseline, cache, and report formats as **public APIs**.
+    - Any contract change must be **versioned**, documented, and accompanied by tests.
 
 2. **Determinism > cleverness.**
-   - Outputs must be stable across runs given identical inputs (same repo, tool version, python tag).
+    - Outputs must be stable across runs given identical inputs (same repo, tool version, python tag).
 
 3. **Evidence-based explainability.**
-   - The core engine produces **facts/metrics**.
-   - HTML/UI **renders facts**, it must not invent interpretations.
+    - The core engine produces **facts/metrics**.
+    - HTML/UI **renders facts**, it must not invent interpretations.
 
 4. **Safety first.**
-   - Never delete or overwrite user files outside repo.
-   - Any write must be atomic where relevant (e.g., baseline `.tmp` + `os.replace`).
+    - Never delete or overwrite user files outside repo.
+    - Any write must be atomic where relevant (e.g., baseline `.tmp` + `os.replace`).
+
+5. **Golden tests are contract sentinels.**
+    - Do not update golden snapshots to “fix” failing tests unless the contract change is intentional, versioned where
+      required, documented, and explicitly approved.
 
 ---
 
 ## 2) Quick orientation
 
 CodeClone is an AST/CFG-informed clone detector for Python. It supports:
+
 - **function clones** (strongest signal)
 - **block clones** (sliding window of statements, may be noisy on boilerplate)
 - **segment clones** (report-only unless explicitly gated)
 
 Key artifacts:
+
 - `codeclone.baseline.json` — trusted baseline snapshot (for CI comparisons)
 - `.cache/codeclone/cache.json` — analysis cache (integrity-checked)
 - `.cache/codeclone/report.html|report.json|report.txt` — reports
@@ -54,15 +61,18 @@ If you touched baseline/cache/report contracts, also run the repo’s audit runn
 
 ---
 
-## 4) Baseline contract (v1, stable)
+## 4) Baseline contract (v2, stable)
 
 ### Baseline file structure (canonical)
 
 ```json
 {
   "meta": {
-    "generator": { "name": "codeclone", "version": "X.Y.Z" },
-    "schema_version": "1.0",
+    "generator": {
+      "name": "codeclone",
+      "version": "X.Y.Z"
+    },
+    "schema_version": "2.0",
     "fingerprint_version": "1",
     "python_tag": "cp313",
     "created_at": "2026-02-08T14:20:15Z",
@@ -71,32 +81,37 @@ If you touched baseline/cache/report contracts, also run the repo’s audit runn
   "clones": {
     "functions": [],
     "blocks": []
+  },
+  "metrics": {
+    "...": "optional embedded snapshot"
   }
 }
 ```
 
 ### Rules
 
 - `schema_version` is **baseline schema**, not package version.
+- Runtime writes baseline schema `2.0`.
+- Runtime accepts baseline schema `1.x` and `2.x` for compatibility checks.
 - Compatibility is tied to:
-  - `fingerprint_version`
-  - `python_tag`
-  - `generator.name == "codeclone"`
+    - `fingerprint_version`
+    - `python_tag`
+    - `generator.name == "codeclone"`
 - `payload_sha256` is computed from a **canonical payload**:
-  - stable key order
-  - clone id lists are **sorted and unique**
-  - integrity check uses constant‑time compare (e.g., `hmac.compare_digest`)
+    - stable key order
+    - clone id lists are **sorted and unique**
+    - integrity check uses constant‑time compare (e.g., `hmac.compare_digest`)
 
 ### Trust model
 
 - A baseline is either **trusted** (`baseline_status = ok`) or **untrusted**.
 - **Normal mode**:
-  - warn
-  - ignore untrusted baseline
-  - compare vs empty baseline
+    - warn
+    - ignore untrusted baseline
+    - compare vs empty baseline
 - **CI gating mode** (`--ci` / `--fail-on-new`):
-  - fail‑fast if baseline untrusted
-  - exit code **2** for untrusted baseline
+    - fail‑fast if baseline untrusted
+    - exit code **2** for untrusted baseline
 
 ### Legacy behavior
 
@@ -108,9 +123,9 @@ If you touched baseline/cache/report contracts, also run the repo’s audit runn
 
 - Cache is an **optimization**, never a source of truth.
 - If cache is invalid or too large:
-  - warn
-  - proceed without cache
-  - ensure report meta reflects `cache_used=false`
+    - warn
+    - proceed without cache
+    - ensure report meta reflects `cache_used=false`
 
 Never “fix” cache by silently mutating it; prefer regenerate.
 
@@ -119,6 +134,7 @@ Never “fix” cache by silently mutating it; prefer regenerate.
 ## 6) Reports and explainability
 
 Reports come in:
+
 - HTML (`--html`)
 - JSON (`--json`)
 - Text (`--text`)
@@ -127,10 +143,10 @@ Reports come in:
 
 - Ordering must be deterministic (stable sort keys).
 - All provenance fields must be consistent across formats:
-  - baseline loaded / status
-  - baseline fingerprint + schema versions
-  - baseline generator version
-  - cache path / cache used
+    - baseline loaded / status
+    - baseline fingerprint + schema versions
+    - baseline generator version
+    - cache path / cache used
 
 ### Explainability contract (core owns facts)
 
@@ -147,6 +163,7 @@ For each clone group (especially block clones), the **core** should be able to p
 - `max_consecutive_<type>` (e.g., consecutive asserts)
 
 UI can show **hints** only when the predicate is **formal & exact** (100% confidence), e.g.:
+
 - `assert_only_block` (assert_ratio == 1.0 and consecutive_asserts == block_len)
 - `repeated_stmt_hash` (single stmt hash repeated across window)
 
@@ -157,19 +174,22 @@ No UI-only heuristics that affect gating.
 ## 7) Noise policy (what is and isn’t a “fix”)
 
 ### Acceptable fixes
+
 - Merge/report-layer improvements (e.g., merge sliding windows into maximal regions) **without changing gating**.
 - Better evidence surfaced in HTML to explain matches.
 
 ### Not acceptable as a “quick fix”
+
 - Weakening detection rules to hide noisy test patterns, unless:
-  - it is configurable
-  - default remains honest
-  - the change is justified by real-world repos
-  - it includes tests for false-negative risk
+    - it is configurable
+    - default remains honest
+    - the change is justified by real-world repos
+    - it includes tests for false-negative risk
 
 ### Preferred remediation for test-only FPs
+
 - Refactor tests to avoid long repetitive statement sequences:
-  - replace chains of `assert "... in html"` with loops or aggregated checks.
+    - replace chains of `assert "... in html"` with loops or aggregated checks.
 
 ---
 
@@ -180,15 +200,15 @@ When you implement something:
 1. **State the intent** (what user-visible issue does it solve?)
 2. **List files touched** and why.
 3. **Call out contracts affected**:
-   - baseline / cache / report schema
-   - CLI exit codes / messages
+    - baseline / cache / report schema
+    - CLI exit codes / messages
 4. **Add/adjust tests** for:
-   - normal-mode behavior
-   - CI gating behavior
-   - determinism (identical output on rerun)
-   - legacy/untrusted scenarios where applicable
+    - normal-mode behavior
+    - CI gating behavior
+    - determinism (identical output on rerun)
+    - legacy/untrusted scenarios where applicable
 5. Run:
-   - `ruff`, `mypy`, `pytest`
+    - `ruff`, `mypy`, `pytest`
 
 Avoid changing unrelated files (locks, roadmap) unless required.
 
@@ -199,7 +219,8 @@ Avoid changing unrelated files (locks, roadmap) unless required.
 Agents must preserve these semantics:
 
 - **0** — success (including “new clones detected” in non-gating mode)
-- **2** — baseline gating failure (untrusted/missing baseline when CI requires trusted baseline; invalid output extension, etc.)
+- **2** — baseline gating failure (untrusted/missing baseline when CI requires trusted baseline; invalid output
+  extension, etc.)
 - **3** — analysis gating failure (e.g., `--fail-threshold` exceeded or new clones in `--ci` as designed)
 
 If you introduce a new exit reason, document it and add tests.
@@ -212,13 +233,13 @@ Before cutting a release:
 
 - Confirm baseline schema compatibility is unchanged, or properly versioned.
 - Ensure changelog has:
-  - user-facing changes
-  - migration notes if any
+    - user-facing changes
+    - migration notes if any
 - Validate `twine check dist/*` for built artifacts.
 - Smoke test install in a clean venv:
-  - `pip install dist/*.whl`
-  - `codeclone --version`
-  - `codeclone . --ci` in a sample repo with baseline.
+    - `pip install dist/*.whl`
+    - `codeclone --version`
+    - `codeclone . --ci` in a sample repo with baseline.
 
 ---
 
@@ -239,64 +260,70 @@ Before cutting a release:
 These rules are **repo policy**. If you need to violate one, you must explain why in the PR.
 
 ### Supported Python versions
+
 - **Must run on Python 3.10, 3.11, 3.12, 3.13, 3.14**.
 - Do not rely on behavior that is new to only the latest version unless you provide a fallback.
 - Prefer **standard library** features that exist in 3.10+.
 
 ### Modern syntax (allowed / preferred)
+
 Use modern syntax when it stays compatible with 3.10+:
+
 - `X | Y` unions, `list[str]` / `dict[str, int]` generics (PEP 604 / PEP 585)
 - `from __future__ import annotations` is allowed, but keep behavior consistent across 3.10–3.14.
 - `match/case` (PEP 634) is allowed, but only if it keeps determinism/readability.
 - `typing.Self` (3.11+) **avoid** in public APIs unless you gate it with `typing_extensions`.
 - Prefer `pathlib.Path` over `os.path` for new code (but keep hot paths pragmatic).
 
 ### Typing standards
+
 - **Type hints are required** for all public functions, core pipeline surfaces, and any code that touches:
   baseline, cache, fingerprints, report models, serialization, CLI exit behavior.
 - Keep **`Any` to an absolute minimum**:
-  - `Any` is allowed only at IO boundaries (JSON parsing, `argparse`, `subprocess`) and must be
-    *narrowed immediately* into typed structures (dataclasses / TypedDict / Protocol / enums).
-  - If `Any` appears in “core/domain” code, add a comment: `# Any: <reason>` and a TODO to remove.
+    - `Any` is allowed only at IO boundaries (JSON parsing, `argparse`, `subprocess`) and must be
+      *narrowed immediately* into typed structures (dataclasses / TypedDict / Protocol / enums).
+    - If `Any` appears in “core/domain” code, add a comment: `# Any: <reason>` and a TODO to remove.
 - Prefer **`Literal` / enums** for finite sets (e.g., status codes, kinds).
 - Prefer **`dataclasses`** (frozen where reasonable) for data models; keep models JSON‑serializable.
 - Use `collections.abc` types (`Iterable`, `Sequence`, `Mapping`) for inputs where appropriate.
 - Avoid `cast()` unless you also add an invariant check nearby.
 
 ### Dataclasses / models
+
 - Models that cross module boundaries should be:
-  - explicitly typed
-  - immutable when possible (`frozen=True`)
-  - validated at construction (or via a dedicated `validate_*` function) if they are user‑provided.
+    - explicitly typed
+    - immutable when possible (`frozen=True`)
+    - validated at construction (or via a dedicated `validate_*` function) if they are user‑provided.
 
 ### Error handling
+
 - Prefer explicit, typed error types over stringly‑typed errors.
 - Exit codes are part of the public contract; do not change them without updating tests + docs.
 
 ### Determinism requirements (language-level)
+
 - Never iterate over unordered containers (`set`, `dict`) without sorting first when it affects:
   hashes, IDs, report ordering, baseline payloads, or UI output.
 - Use stable formatting (sorted keys, stable ordering) in JSON output.
 
 ### Key PEPs to keep in mind
+
 - PEP 8, PEP 484 (typing), PEP 526 (variable annotations)
 - PEP 563 / PEP 649 (annotation evaluation changes across versions) — avoid relying on evaluation timing
 - PEP 585 (built-in generics), PEP 604 (X | Y unions)
 - PEP 634 (structural pattern matching)
 - PEP 612 (ParamSpec) / PEP 646 (TypeVarTuple) — only if it clearly helps, don’t overcomplicate
 
-
-
 Prefer these rules:
 
 - **Domain / contracts / enums** live near the domain owner (baseline statuses in baseline domain).
 - **Core logic** should not depend on HTML.
 - **Render** depends on report model, never the other way around.
 - If a module becomes a “god module”, split by:
-  - model (types)
-  - io/serialization
-  - rules/validation
-  - ui rendering
+    - model (types)
+    - io/serialization
+    - rules/validation
+    - ui rendering
 
 Avoid deep package hierarchies unless they clearly reduce coupling.
 
@@ -310,7 +337,10 @@ Avoid deep package hierarchies unless they clearly reduce coupling.
 - [ ] `ruff`, `mypy`, `pytest` green.
 - [ ] CLI messages remain helpful and stable (don’t break scripts).
 - [ ] Reports contain provenance fields and reflect trust model correctly.
+- [ ] Golden snapshots were **not** updated just to satisfy failing tests.
+- [ ] If any golden snapshot changed, the corresponding contract change is intentional, documented, and approved.
 
 ---
 
-If you are an AI agent and something here conflicts with an instruction from a maintainer in the PR/issue thread, **ask for clarification in the thread** and default to this document until resolved.
+If you are an AI agent and something here conflicts with an instruction from a maintainer in the PR/issue thread, **ask
+for clarification in the thread** and default to this document until resolved.