From 54cc2f5d63bdf49b6d1a7f47529fbae1cb6d96fc Mon Sep 17 00:00:00 2001 From: zolizoli Date: Mon, 29 Jun 2026 17:52:42 +0200 Subject: [PATCH] Add CHANGES_SUMMARY.md: triage guide for the docs/design/test review queue Summarises the three phase PRs (docs #2, design #3, tests #4), what is safe to merge, the behaviour-changing items left for a human decision, proposed features (kenon.paths helper; Nelson/SWOW norm comparison), and what was deliberately not touched (main, the third-party skills, the uv.lock drift). Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGES_SUMMARY.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 CHANGES_SUMMARY.md diff --git a/CHANGES_SUMMARY.md b/CHANGES_SUMMARY.md new file mode 100644 index 0000000..3bd2d3c --- /dev/null +++ b/CHANGES_SUMMARY.md @@ -0,0 +1,98 @@ +# Changes summary — kenon hardening pass + +A review queue, not merged changes. Three phase PRs (docs / design / tests) plus +this summary, all opened against `main`, **none merged**. `main` was never +touched. Triage at your leisure. + +## The PRs + +| PR | Branch | What it does | Risk | +|----|--------|--------------|------| +| [#2](https://github.com/crow-intelligence/kenon/pull/2) | `docs-overhaul` | Docs overhaul: fixes a package-wide example-rendering bug, rebuilds quickstart/tutorial/troubleshooting, enables strict docs builds | Low — docstring + docs only, no behaviour change | +| [#3](https://github.com/crow-intelligence/kenon/pull/3) | `design-review` | `PRE-MORTEM.md` fragility map + two safe type/exception tightenings | Low — annotation/comment only | +| [#4](https://github.com/crow-intelligence/kenon/pull/4) | `test-hardening` | Property-based tests on the math core + mutation testing (~82%) | Low — tests + dev tooling only | + +All three are green: `make ci` passes (118 → 132 tests), and #2 builds docs with +`mkdocs build --strict` warning-free. + +### Safe to merge as-is +- **#2 (docs)** — highest priority, this is what users complained about. The + root cause was real: every `Example:` docstring section rendered as nested + blockquotes (griffe only treats the plural `Examples:` as code), which also + broke strict builds. Fixed package-wide. The quickstart and tutorial were + executed in a clean venv before committing. +- **#3 (design)** — the only code changes are a stale `# type: ignore` removal + and one annotation tightening. The substance is `PRE-MORTEM.md`. +- **#4 (tests)** — pure additions. Adds `mutmut` to the `dev` extra and a + `[tool.mutmut]` config; mutation is dev-only and **not** wired into CI. + +## Needs your decision (behaviour-changing — deliberately not applied) + +From `PRE-MORTEM.md` (full detail there) and the test pass: + +1. **Degenerate word similarity on few-document corpora** *(highest impact)* — + `cosine_similarity_matrix` builds word vectors whose dimensionality equals the + document count, so `build_semantic_graph` over a short corpus returns an + artifactually dense graph. Decide: warn below a minimum doc count, document + the limitation, or steer small-corpus users to `build_cooccurrence_graph`. +2. **sklearn embedders densify** (`.toarray()`) — OOM risk on large corpora, + contradicting the memory-efficient positioning. Decide: keep sparse / cap + vocab / document. +3. **`transform()` before `fit()`** raises sklearn's `NotFittedError`, not the + documented `RuntimeError`. One-line guard would fix it, but it changes the + observed exception type. +4. **`build_semantic_graph(k_neighbors=...)`** re-fits the embedder and silently + degrades to a threshold graph if a shape check fails. Decide: reuse the fitted + embedder; warn/raise instead of silently degrading. +5. **`detect_collocations` propagates NLTK crashes on degenerate corpora** + *(surfaced by the new property tests)* — `metric="chi_sq"` raises + `ZeroDivisionError` and `metric="likelihood"` raises a math-domain + `ValueError` on all-identical tokens (e.g. `["a"] * 12`). Only `"pmi"` is + robust. Decide: guard and raise a kenon-level error, or document the + constraint. (The property test sidesteps it by using `pmi`.) +6. **`get_stopwords` runtime NLTK download + unwrapped language error** — fails + at runtime offline, and an unsupported `lang` surfaces a raw NLTK error + instead of a helpful one like the spaCy path. Decide: wrap the error. + +Lower priority (also in `PRE-MORTEM.md`): unguarded `disparity_integral` public +helper, in-place mutation in `apply_disparity_filter`, pickle-load RCE surface, +percentile tie-bias. + +## Proposed features (not built — your call) + +From the kenon tutorial brief in the runbook: + +- **`kenon.paths` helper** — the docs tutorial demonstrates concept-to-concept + pathfinding using networkx directly on the `SemanticGraph` (no new API). If you + want this as first-class kenon surface, a small module wrapping + `nx.shortest_path` / `nx.all_simple_paths` with co-occurrence-weight→distance + inversion and weight-threshold filtering would be a clean, well-scoped addition. +- **Human-norm comparison (Nelson norms / Small World of Words)** — comparing a + text-derived network against human free-association norms needs external, + licensed datasets and a graph-comparison helper. Too large/risky for an + unattended pass; the tutorial describes the methodology conceptually. Worth a + dedicated feature branch if you want it. + +## What I deliberately did not touch, and why + +- **`main`** — never checked out, committed to, or merged into. Untouched. +- **The Honnibal skills** — the runbook's Part A (download → review the raw + `.md.txt` → activate) is the one step it says a human must not skip under + bypass mode, because a skill runs with full shell/git access. Only + `hypothesis.md` was installed. Rather than auto-download and activate + third-party skills unattended, I replicated each skill's *intent* by hand. To + use the genuine commands, run Part A yourself and re-run. +- **`uv.lock` version drift** — the repo had a pre-existing stale lock + (`0.1.0` vs `pyproject`'s `0.1.1`). I left it alone on the docs and design + branches; #4 regenerates the lock (for the `mutmut` dev dep), which also + corrects that drift. +- **Any behaviour-changing fix** — per the guardrails, everything that would + alter the public API or runtime behaviour is written up above rather than + applied. + +## Artifacts + +- `PRE-MORTEM.md` (on `design-review`) — the fragility map. +- `MUTATION-TESTING.md` (on `test-hardening`) — score (~82%, 362/442) + survivor + triage. +- This file.