chore(docs): update docs

Author: orenlab

CONTRIBUTING.md

@@ -6,20 +6,20 @@ CodeClone is an **AST + CFG-based code clone detector** focused on architectural
 not textual similarity.
 
 Contributions are welcome — especially those that improve **signal quality**, **CFG semantics**,
-and **real-world usability**.
+and **real-world CI usability**.
 
 ---
 
 ## Project Philosophy
 
-Before contributing, please understand the core principles of the project:
+Core principles:
 
 - **Low noise over high recall**
 - **Structural and control-flow similarity**, not semantic equivalence
 - **Deterministic and explainable behavior**
-- Optimized for **CI usage and architectural analysis**
+- Optimized for **CI usage** and architectural analysis
 
-If a change increases false positives or reduces explainability,
+If a change increases false positives, reduces determinism, or weakens explainability,
 it is unlikely to be accepted.
 
 ---
@@ -42,14 +42,16 @@ We especially welcome contributions in the following areas:
 
 Please use the appropriate **GitHub Issue Template**.
 
-When reporting bugs related to clone detection, include:
+When reporting issues related to clone detection, include:
 
-- minimal reproducible code snippets;
-- the Python version used;
+- minimal reproducible code snippets (preferred over screenshots);
+- the CodeClone version;
+- the Python version (`python_tag`, e.g. `cp313`);
 - whether the issue is primarily:
-  - AST-related,
-  - CFG-related,
-  - reporting / UI-related.
+    - AST-related,
+    - CFG-related,
+    - normalization-related,
+    - reporting / UI-related.
 
 Screenshots alone are usually insufficient for analysis.
 
@@ -73,12 +75,13 @@ Well-argued false-positive reports are valuable and appreciated.
 
 CFG behavior in CodeClone is intentionally conservative in the 1.x series.
 
-If proposing changes to CFG semantics, please include:
+If proposing changes to CFG semantics, include:
 
 - a description of the current behavior;
 - the proposed new behavior;
-- the expected impact on clone detection quality;
-- concrete code examples.
+- the expected impact on clone detection quality (noise/recall);
+- concrete code examples;
+- a note on determinism implications.
 
 Such changes often require design-level discussion and may be staged across versions.
 
@@ -87,21 +90,42 @@ Such changes often require design-level discussion and may be staged across vers
 ## Security & Safety Expectations
 
 - Assume **untrusted input** (paths and source code).
-- Add **negative tests** for any normalization or CFG change.
-- Changes must preserve determinism and avoid new false positives.
+- Prefer **fail-closed in gating modes** and **fail-open in normal modes** only when explicitly intended.
+- Add **negative tests** for any normalization/CFG change.
+- Changes must preserve determinism and avoid introducing new false positives.
 
 ---
 
 ## Baseline & CI
 
-- Baselines are **versioned**. Regenerate with `codeclone . --update-baseline`
-  when `fingerprint_version` changes.
-- Baseline regeneration is not required for UI/report/CLI/cache/performance-only changes
+### Baseline contract (v1)
+
+- The baseline schema is versioned (`meta.schema_version`).
+- Compatibility/trust gates include `schema_version`, `fingerprint_version`, `python_tag`,
+  and `meta.generator.name`.
+- Integrity is tamper-evident via `meta.payload_sha256` over canonical payload:
+  `clones.functions`, `clones.blocks`, `meta.fingerprint_version`, `meta.python_tag`.
+  (`created_at` and `meta.generator.version` are informational only.)
+
+### When baseline regeneration is required
+
+- Regenerate baseline with `codeclone . --update-baseline` **only when `fingerprint_version` changes**.
+- Regeneration is **not** required for UI/report/CLI/cache/performance-only changes
   if `fingerprint_version` is unchanged.
-- Baseline v1 is tamper-evident (`meta.generator`, `meta.payload_sha256`).
-- Baseline verification is pinned to `python_tag` (for example `cp313`).
-- In `--ci` (or explicit `--fail-on-new`), untrusted baseline states fail fast. Outside gating
-  mode, baseline is ignored with warning and comparison proceeds against an empty baseline.
+
+### Gating behavior
+
+- In `--ci` (or explicit gating flags), **untrusted baseline states fail fast** as a contract error (exit 2).
+- Outside gating mode, an untrusted/missing baseline is ignored with a warning and comparison proceeds
+  against an empty baseline.
+
+### Exit codes contract
+
+- **0** — success
+- **2** — contract error (e.g., missing/untrusted baseline in gating, invalid output path/extension, incompatible
+  versions)
+- **3** — gating failure (new clones detected, `--fail-threshold` exceeded)
+- **5** — internal error (unexpected exception; please report)
 
 ---
 
@@ -110,9 +134,7 @@ Such changes often require design-level discussion and may be staged across vers
 ```bash
 git clone https://github.com/orenlab/codeclone.git
 cd codeclone
-python -m venv .venv
-source .venv/bin/activate
-pip install -e .[dev]
+uv sync --all-extras --dev
 ```
 
 Run tests:
@@ -133,8 +155,9 @@ uv run ruff format .
 
 ## Code Style
 
-- Python 3.10+
+- Python **3.10–3.14**
 - Type annotations are required
+- `Any` should be minimized; prefer precise types and small typed helpers
 - `mypy` must pass
 - `ruff check` must pass
 - Code must be formatted with `ruff format`
@@ -147,11 +170,11 @@ uv run ruff format .
 CodeClone follows **semantic versioning**:
 
 - **MAJOR**: fundamental detection model changes
-- **MINOR**: new detection capabilities (for example, CFG improvements)
+- **MINOR**: new detection capabilities (e.g., new detectors or major CFG/normalization behavior shifts)
 - **PATCH**: bug fixes, performance improvements, and UI/UX polish
 
-Baselines are versioned. Any change to detection behavior must include documentation
-and tests, and may require baseline regeneration.
+Any change that affects detection behavior must include documentation and tests,
+and may require a `fingerprint_version` bump (and thus baseline regeneration).
 
 ---
 

SECURITY.md

@@ -3,7 +3,7 @@
 ## Supported Versions
 
 CodeClone is a static analysis tool and does not execute analyzed code at runtime.
-Nevertheless, security and robustness are treated as first‑class concerns.
+Nevertheless, security and robustness are treated as first-class concerns.
 
 The following versions currently receive security updates:
 
@@ -42,12 +42,14 @@ Additional safeguards:
 - Report explainability fields are generated in Python core; UI is rendering-only and does not infer semantics.
 - Scanner traversal is root-confined and prevents symlink-based path escape.
 - Baseline files are schema/type validated with size limits and tamper-evident integrity fields
-  (`generator`, `payload_sha256` for v1 baseline contract).
+  (`meta.generator`, `meta.payload_sha256` for v1 baseline contract).
 - Baseline integrity is tamper-evident (audit signal), not tamper-proof cryptographic signing.
   An actor who can rewrite baseline content and recompute `payload_sha256` can still alter it.
-- Baseline hash excludes non-semantic metadata (`created_at`, `generator.version`) and
-  covers canonical payload (`functions`, `blocks`, `python_tag`,
-  `fingerprint_version`, `schema_version`).
+- Baseline hash excludes non-semantic metadata (`created_at`, `meta.generator.version`) and
+  covers canonical payload (`clones.functions`, `clones.blocks`, `meta.python_tag`,
+  `meta.fingerprint_version`).
+- `meta.schema_version` and `meta.generator.name` are validated as compatibility/trust gates and are
+  intentionally excluded from `payload_sha256`.
 - In `--ci` (or explicit `--fail-on-new`), untrusted baseline states fail fast; otherwise baseline is ignored
   with explicit warning and comparison proceeds against an empty baseline.
 - Cache files are HMAC-signed (constant-time comparison), size-limited, and ignored on mismatch.
@@ -97,4 +99,4 @@ requests.
 
 ---
 
-Thank you for helping keep CodeClone secure, reliable, and trustworthy.
+Thank you for helping keep CodeClone secure, reliable, and trustworthy.