changelog → manual: precise per-feature descriptions (zero-token, no guessing)

.spine/changelog-manual.py aggregates the CHANGELOG's real descriptions per feature — but PRECISELY:
the feature must be the SUBJECT of a Feature/Improvement entry (its name leads the heading). Fuzzy
word-overlap produced wrong matches (Auto-Open → 'Toggle Mute/Unmute Tracks'), the exact bullshitting
we're killing — so it's precision over recall: 323 features genuinely described, the rest honestly
undocumented for the teach loop. Emits docs/FEATURE-DESCRIPTIONS.md; wired into functions.yml CI.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: esaruoho

.github/workflows/functions.yml

@@ -37,13 +37,16 @@ jobs:
       - name: Sync the manual (fill AUTO blocks zero-token, prose untouched)
         run: python3 .spine/manual-sync.py "$GITHUB_WORKSPACE"
 
+      - name: Feed the changelog into per-feature descriptions (precise, zero-token)
+        run: python3 .spine/changelog-manual.py "$GITHUB_WORKSPACE"
+
       - name: Commit the index + manual if they changed
         run: |
           git config user.email "action@github.com"
           git config user.name "GitHub Action"
           # -f: docs/ is gitignored (the .gitignore 'Docs/' rule is case-insensitive on macOS),
           # so the tracked docs (like FEATURE-MAP.md) are all force-added. manual/ is tracked normally.
-          git add -f docs/PAKETTI-FUNCTIONS.md docs/paketti-functions.json
+          git add -f docs/PAKETTI-FUNCTIONS.md docs/paketti-functions.json docs/FEATURE-DESCRIPTIONS.md
           git add manual/Experimental.md
           if git diff --cached --quiet; then
             echo "function index + manual unchanged — nothing to commit"

.spine/changelog-manual.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""changelog-manual.py — ZERO-TOKEN: feed the CHANGELOG's real descriptions into the manual.
+
+The auto-generated Experimental.md lists features but doesn't describe them, so the FAQ bot used to
+invent behaviour. The CHANGELOG *does* describe them (Esa writes what each feature does when he ships
+it) — but spread across Feature:/Improvement: entries under varying names. This aggregates every
+changelog entry that mentions a feature and emits, per feature, its dated real descriptions.
+
+Outputs:
+  docs/FEATURE-DESCRIPTIONS.md          — the full feature → changelog-descriptions map
+  fills <!-- AUTO:descriptions:TOPIC --> blocks in manual/Experimental.md (e.g. TOPIC=playerpro)
+
+  python3 .spine/changelog-manual.py [repo_root]
+"""
+import json
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("/Users/esaruoho/work/paketti")
+CHANGELOG = ROOT / "manual" / "CHANGESLOG.md"
+INDEX = ROOT / "docs" / "paketti-functions.json"
+MANUAL = ROOT / "manual" / "Experimental.md"
+OUT = ROOT / "docs" / "FEATURE-DESCRIPTIONS.md"
+
+GENERIC = {"dialog", "dialogs", "tool", "tools", "mode", "modes", "paketti", "renoise", "feature",
+           "features", "window", "panel", "button", "buttons", "menu", "the", "and", "for", "with",
+           "now", "this", "will", "that", "your", "from", "playerpro"}   # playerpro: too broad alone
+
+
+def changelog_entries():
+    entries, cur = [], None
+    for ln in CHANGELOG.read_text(encoding="utf-8").splitlines():
+        m = re.match(r"^### (\d{4}-\d{2}-\d{2}) - (Feature|Improvement|Fix|Change)?:?\s*(.*)", ln)
+        if m:
+            if cur:
+                entries.append(cur)
+            cur = {"date": m.group(1), "kind": (m.group(2) or "Note"), "head": m.group(3).strip(),
+                   "body": []}
+        elif cur and ln.strip():
+            cur["body"].append(ln.strip())
+    if cur:
+        entries.append(cur)
+    return entries
+
+
+def base_features():
+    """Distinct base feature names from the index (sub-action suffixes collapsed)."""
+    idx = json.loads(INDEX.read_text(encoding="utf-8"))
+    names = {f["function"] for fns in idx.values() for f in fns}
+    return sorted(names)
+
+
+def words_of(s):
+    return {w for w in re.findall(r"[a-z0-9]{3,}", s.lower()) if w not in GENERIC}
+
+
+def describe(feature, entries):
+    """PRECISE: the feature must be the SUBJECT of a Feature/Improvement entry — its name appears as a
+    near-exact phrase at the START of the heading. Fuzzy word-overlap produced wrong descriptions
+    (Auto-Open → 'Toggle Mute/Unmute Tracks'), which is the bullshitting we're killing. Precision over
+    recall: a feature with no confident match is honestly undocumented, for the teach loop to fill."""
+    core = re.sub(r"[.…]+$", "", feature).strip().lower()
+    relaxed = re.sub(r"^(paketti |playerpro )+", "", core)
+    cores = [core] + ([relaxed] if relaxed != core else [])
+    hits = []
+    for e in entries:
+        if e["kind"] not in ("Feature", "Improvement"):
+            continue
+        head = e["head"].lower()
+        pos = min((head.find(c) for c in cores if c in head), default=-1)
+        if 0 <= pos <= 30:                     # the feature LEADS the heading = it's the subject
+            rank = 0 if e["kind"] == "Feature" else 1
+            hits.append((rank, pos, e))
+    hits.sort(key=lambda x: (x[0], x[1], x[2]["date"]))
+    return [e for _, _, e in hits]
+
+
+def entry_text(e):
+    body = " ".join(l for l in e["body"] if not l.lstrip().startswith("![") and l.strip() not in ("--", "---"))
+    desc = (e["head"] + ((" — " + body) if body else "")).strip()
+    return f"- **{e['date']} ({e['kind']})** {desc[:400]}"
+
+
+def main():
+    entries = changelog_entries()
+    feats = base_features()
+    described, undoc = {}, []
+    for f in feats:
+        d = describe(f, entries)
+        if d:
+            described[f] = d
+        else:
+            undoc.append(f)
+
+    lines = ["# Paketti — Feature Descriptions (sourced from the CHANGELOG)", "",
+             f"*Zero-token, regenerated by `.spine/changelog-manual.py`. "
+             f"{len(described)} features have changelog descriptions; {len(undoc)} are undocumented "
+             f"(need a write-up). Never hand-edit — describe features in the CHANGELOG instead.*", ""]
+    for f in sorted(described):
+        lines.append(f"### {f}")
+        for e in described[f][:4]:
+            lines.append(entry_text(e))
+        lines.append("")
+    lines.append("## Undocumented (no changelog description yet)")
+    lines.append("")
+    for f in undoc:
+        lines.append(f"- {f}")
+    OUT.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    print(f"wrote {OUT} — {len(described)} described, {len(undoc)} undocumented")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())