docs: update CHANGELOG and README for 0.10.0 — semantic freshness

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: silversurfer562

CHANGELOG.md

@@ -2,10 +2,34 @@
 
 All notable changes to `attune-help` are documented here.
 
-## 0.9.1 — 2026-04-30
+## 0.10.0 — 2026-04-30
 
 ### Added
 
+- **Phase 1 semantic freshness** — `attune_help.freshness` package with
+  `SymbolExtractor` and `SymbolRecord`. Extracts normalized public-symbol
+  signatures from Python source using `ast`; stable across docstring edits,
+  body rewrites, and formatter passes, but changes on parameter, return-type,
+  decorator, or base-class edits.
+
+- **`compute_semantic_hash`** in `attune_help.staleness` (also exported from
+  `attune_help`). For pure-Python features, hashes the aggregated
+  `signature_hash` values of every public symbol rather than raw file bytes.
+  Result: docstring-only edits and `black`/`ruff` formatter passes no longer
+  trigger spurious template regeneration. Non-Python files and features with
+  mixed content fall back to the existing byte-SHA path transparently.
+  `SyntaxError` in a `.py` file also falls back gracefully.
+
+- **`compute_source_hash` is now semantic-aware** — the function signature
+  is unchanged; pure-Python features automatically use semantic hashing from
+  this release. No frontmatter format changes; existing templates regenerate
+  exactly once on the next maintenance pass and then stabilize.
+
+- **`scripts/validate_against_corpus.py`** — 3-sweep dev harness (parse
+  integrity, determinism, HEAD vs HEAD^ drift classification). Validated
+  clean against the attune-ai corpus: 323 `.py` files across 24 features,
+  zero parse errors, 24/24 deterministic, zero signature drifts.
+
 - **`aliases` frontmatter** on three templates so the alias-weighted RAG
   retriever surfaces them on synonym queries:
   - `concepts/tool-refactor-plan.md` — aliases: technical debt, code cleanup
@@ -16,6 +40,14 @@ All notable changes to `attune-help` are documented here.
 
 - `.gitignore` now excludes `.pypirc` to prevent credential leaks.
 
+### Known limitations
+
+- Pure re-export shim modules (files that only contain `from pkg import …`
+  with no function or class definitions) produce zero symbols. Features whose
+  `files:` list points exclusively to shims will hash as if empty. Mitigation:
+  list the upstream implementation file alongside the shim in `features.yaml`.
+  Full per-symbol frontmatter (Option B) is deferred pending telemetry.
+
 ---
 
 ## 0.9.0 — 2026-04-24

README.md

@@ -223,6 +223,64 @@ class RedisStorage(SessionStorage):
     def save(self, user_id: str, state: dict) -> None: ...
 ```
 
+## Staleness Detection
+
+`attune-help` tracks whether your help templates are up to date with
+your source code using SHA-256 hashes stored in template frontmatter.
+
+### Basic usage
+
+```python
+from attune_help import load_manifest, check_staleness
+
+manifest = load_manifest(".help")
+report = check_staleness(manifest, help_dir=".help", project_root=".")
+
+for entry in report.stale_features:
+    print(f"{entry} is stale — regenerate with attune-ai")
+```
+
+### Semantic hashing (v0.10+)
+
+For pure-Python features, `compute_source_hash` automatically uses
+**semantic hashing**: only public-symbol *contracts* (parameters, return
+types, decorators, base classes) contribute to the hash. Docstring
+edits, body rewrites, and formatter passes (`black`, `ruff`) are
+ignored. This eliminates spurious template regenerations when nothing
+meaningful changed.
+
+```python
+from attune_help import compute_source_hash, compute_semantic_hash
+from attune_help.manifest import Feature
+
+feat = Feature(name="auth", description="", files=["src/auth/**"])
+
+# compute_source_hash uses semantic hashing automatically for .py-only features
+hash1, files = compute_source_hash(feat, project_root=".")
+
+# Call compute_semantic_hash directly when you need the semantic hash
+# regardless of file mix (e.g. for reporting)
+hash2, files = compute_semantic_hash(feat, project_root=".")
+```
+
+Mixed-content features (Python + Jinja, YAML, etc.) and features with
+syntax errors in their source files fall back to byte-level SHA
+automatically — no configuration required.
+
+### Corpus validation
+
+A 3-sweep validation harness ships in `scripts/validate_against_corpus.py`:
+
+```bash
+# Validate against any repo with a .help/features.yaml
+python scripts/validate_against_corpus.py --repo /path/to/your/repo
+```
+
+Sweeps: (1) parse integrity — all `.py` files parse cleanly; (2)
+determinism — identical hashes on two consecutive calls; (3) HEAD vs
+HEAD^ — classifies symbol changes as signature drift / body-only /
+add / remove.
+
 ## License
 
 Apache 2.0