livedocs 0.1.0__tar.gz

livedocs-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# macOS
+.DS_Store
+
+# Obsidian: per-machine UI state (shared vault config in .obsidian/ is versioned)
+live-docs-vault/.obsidian/workspace.json
+live-docs-vault/.obsidian/workspace-mobile.json
+live-docs-vault/.trash/
+
+# Claude Code: local session state
+.claude/scheduled_tasks.lock
+.claude/settings.local.json
+
+# Phase 1 testbench: detached clone of a real project, never committed here
+testbench/
+
+# Python
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+
+# 1a run artefacts: keep the compressed copies, regenerate the rest
+results/*/rows.jsonl
+results/*/items.jsonl
+results/*/batches/
+results/*.log
+dist/

livedocs-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,9 @@
+# For repositories using the pre-commit framework (https://pre-commit.com).
+# Requires `livedocs` and `drift` on PATH (see README). The hook itself is the same gate as
+# `livedocs init` installs through .githooks.
+- id: livedocs-gate
+  name: livedocs gate (notes reconciled with the code they mention)
+  entry: livedocs hook pre-commit
+  language: system
+  pass_filenames: false
+  always_run: true

livedocs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gus Ellerm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

livedocs-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.5
+Name: livedocs
+Version: 0.1.0
+Summary: Notes that know when the code moved on: hash-anchored live docs with a git commit gate, over Fiberplane drift.
+Project-URL: Repository, https://github.com/GusEllerm/vault-drift
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,documentation,drift,git-hooks,obsidian
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# livedocs
+
+Notes that know when the code moved on.
+
+`livedocs` binds Markdown notes (an Obsidian vault, or any folder of `.md` files inside a repo) to the
+code they mention, and makes the git commit the place where notes and code are reconciled. It is a
+thin layer over [Fiberplane drift](https://github.com/fiberplane/drift) (which fingerprints symbols)
+that adds what an agent-written vault needs:
+
+- **Anchors derived from the note's own backtick mentions** — nothing to declare by hand.
+- **A note hash and member-level hashes in append-only stamps**, so "this note was verified against
+  this code" is a recorded fact, and only changes to what the note actually mentions count.
+- **A git pre-commit gate**: a commit that changes code a note mentions is blocked until the note is
+  updated or acked with a reason. Provably benign changes (comment-only edits, pure moves, changes to
+  members the note doesn't mention) are acked mechanically. `unknown` never blocks.
+- **A read-time report** for agents: `CHANGED` with *was / now* pinned to the note lines that mention
+  the symbol — a fact, not a verdict. The agent that made the change decides what the note should say.
+- **Coverage**: which of a note's code claims are anchored, and which names it uses that no longer exist.
+
+The guarantee is a mechanism of the development framework (git), not a capability of any agent:
+it holds for Claude Code, Codex, a human at a terminal, or anything else that commits.
+
+## New project? One command
+
+```sh
+livedocs new-vault docs/vault --scaffold-modules
+```
+
+creates an Obsidian vault (`Home.md`, `Modules/ Concepts/ Reference/ Sessions/ Templates/`, a minimal
+`.obsidian/`), one empty note per source module, the livedocs config (sessions, reviews and templates
+are snapshots), the git gate, the Claude Code adapter, and an `AGENTS.md` block — then commit. Open the
+folder in Obsidian as a vault. From there: write notes, commit, reconcile when the gate says so.
+
+## Install
+
+```sh
+brew install fiberplane/tap/drift          # or: curl -fsSL https://drift.fp.dev/install.sh | sh
+```
+
+Then `livedocs` itself (stdlib only, no Python dependencies). While this repository is private, install
+from a checkout or the built wheel; `git+https://…` needs GitHub credentials (`gh auth setup-git` makes
+git use your `gh` login):
+
+```sh
+uv tool install /path/to/vault-drift               # from a local checkout (add --editable to hack on it)
+uv tool install /path/to/livedocs-0.1.0-py3-none-any.whl   # from `uv build` output
+uv tool install git+https://github.com/GusEllerm/vault-drift   # with GitHub access
+```
+
+Then, in the repository that holds the vault:
+
+```sh
+livedocs init --vault docs/vault           # git gate (.githooks + core.hooksPath), .livedocs/config.json,
+                                           # Claude Code Stop heads-up (settings.local.json), AGENTS.md block
+```
+
+That is the whole setup. Notes are stamped by the commit that adds or edits them: write a note, commit
+it, and the gate binds its code mentions and records the stamp in the same commit. For an existing vault,
+`git add` the notes and commit once (or run `livedocs stamp <note>` per note to see what each binds).
+Each clone activates the versioned hook with `git config core.hooksPath .githooks` (`init` does it).
+`--repo` defaults to the current git repository and `--vault` to the configured one, so inside the repo
+the commands need no arguments.
+
+## The commit flow
+
+```
+edit code ──► git commit
+              │  gate: notes that mention the changed code, not yet reconciled?
+              ├─ none / benign ────────────────────────────────► commit passes (benign ones auto-acked;
+              │                                                   new or edited notes stamped)
+              └─ some ──► "CHANGED: <note> … was: … now: … note lines 13, 30"
+                          edit the note and commit again          (the commit stamps it)
+                          or, still correct:  livedocs stamp <note> --ack --reason "…"; git add -A; commit
+```
+
+`livedocs affected` lists the notes your uncommitted changes touch before you get there.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `livedocs new-vault <path> [--scaffold-modules]` | scaffold an Obsidian vault and wire everything in |
+| `livedocs init --vault <path> [--read-gate] [--shared]` | install the gate, config and harness adapter for an existing vault |
+| `livedocs stamp <note> [--ack --reason R]` | bind a note's mentions with drift and record a stamp |
+| `livedocs check <note> [--json]` | one note's state: `fresh`, `changed`, `broken`, `unknown`, `snapshot` |
+| `livedocs affected [--cached]` | notes bound to files changed in the working tree (or the index) |
+| `livedocs verify` | CI: every stamped note against the checked-out tree; exit 1 on changed/broken |
+| `livedocs coverage` | per-note anchored / dangling mentions |
+| `livedocs survey` | resolution statistics over a vault (diagnostics) |
+
+## Snapshot notes
+
+Dated records — reviews, session logs, reports — describe the code as it *was*. Mark them with
+`livedocs: snapshot` in the frontmatter, or list globs in `.livedocs/config.json`:
+
+```json
+{ "vault": "docs/vault", "snapshot_globs": ["Reference/Review *", "Sessions/*"] }
+```
+
+They bind nothing, report `snapshot`, and never block.
+
+## CI
+
+Pre-commit is skipped by `--no-verify`, merges and rebases. Run the same check in CI:
+
+```yaml
+# .github/workflows/livedocs.yml
+name: livedocs
+on: [push, pull_request]
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: curl -fsSL https://drift.fp.dev/install.sh | sh && echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - uses: astral-sh/setup-uv@v5
+      - run: uv tool install git+https://github.com/GusEllerm/vault-drift
+      - run: livedocs verify --repo . --vault docs/vault
+```
+
+Or with the [pre-commit](https://pre-commit.com) framework, add to `.pre-commit-config.yaml`:
+
+```yaml
+- repo: https://github.com/GusEllerm/vault-drift
+  rev: v0.1.0
+  hooks: [{ id: livedocs-gate }]
+```
+
+## What it can and cannot guarantee
+
+- It guarantees that a *committed* note has been vouched for against the code it mentions, at that
+  commit. A read-time `changed` means the working tree has moved since.
+- It sees code the note names in backticks. A prose claim with nothing to anchor ("tokens rotate every
+  15 minutes") is reported `unknown`, never `fresh`. `livedocs coverage` shows how much of each note that is.
+- It does not follow the call graph: a note's claim about what a function *does* can go stale when a
+  callee changes. That is the residual miss class, measured at about 1 in 20 real changes on the
+  reference history.
+- Python only, for now (symbol resolution uses `ast`; drift fingerprints six languages).
+
+## Background
+
+Design, decisions and the measurements behind every choice live in the vault at `live-docs-vault/`
+(start at `Start Here.md`). The short version: on a real 141-commit history, the hash flagged 22 of the
+23 note-invalidating changes an anchor covered; only ~5% of flags marked a change that made a note wrong
+— which is why the signal is delivered as a fact at commit time, to the agent that has the context, and
+never as a verdict.

livedocs-0.1.0/README.md

@@ -0,0 +1,146 @@
+# livedocs
+
+Notes that know when the code moved on.
+
+`livedocs` binds Markdown notes (an Obsidian vault, or any folder of `.md` files inside a repo) to the
+code they mention, and makes the git commit the place where notes and code are reconciled. It is a
+thin layer over [Fiberplane drift](https://github.com/fiberplane/drift) (which fingerprints symbols)
+that adds what an agent-written vault needs:
+
+- **Anchors derived from the note's own backtick mentions** — nothing to declare by hand.
+- **A note hash and member-level hashes in append-only stamps**, so "this note was verified against
+  this code" is a recorded fact, and only changes to what the note actually mentions count.
+- **A git pre-commit gate**: a commit that changes code a note mentions is blocked until the note is
+  updated or acked with a reason. Provably benign changes (comment-only edits, pure moves, changes to
+  members the note doesn't mention) are acked mechanically. `unknown` never blocks.
+- **A read-time report** for agents: `CHANGED` with *was / now* pinned to the note lines that mention
+  the symbol — a fact, not a verdict. The agent that made the change decides what the note should say.
+- **Coverage**: which of a note's code claims are anchored, and which names it uses that no longer exist.
+
+The guarantee is a mechanism of the development framework (git), not a capability of any agent:
+it holds for Claude Code, Codex, a human at a terminal, or anything else that commits.
+
+## New project? One command
+
+```sh
+livedocs new-vault docs/vault --scaffold-modules
+```
+
+creates an Obsidian vault (`Home.md`, `Modules/ Concepts/ Reference/ Sessions/ Templates/`, a minimal
+`.obsidian/`), one empty note per source module, the livedocs config (sessions, reviews and templates
+are snapshots), the git gate, the Claude Code adapter, and an `AGENTS.md` block — then commit. Open the
+folder in Obsidian as a vault. From there: write notes, commit, reconcile when the gate says so.
+
+## Install
+
+```sh
+brew install fiberplane/tap/drift          # or: curl -fsSL https://drift.fp.dev/install.sh | sh
+```
+
+Then `livedocs` itself (stdlib only, no Python dependencies). While this repository is private, install
+from a checkout or the built wheel; `git+https://…` needs GitHub credentials (`gh auth setup-git` makes
+git use your `gh` login):
+
+```sh
+uv tool install /path/to/vault-drift               # from a local checkout (add --editable to hack on it)
+uv tool install /path/to/livedocs-0.1.0-py3-none-any.whl   # from `uv build` output
+uv tool install git+https://github.com/GusEllerm/vault-drift   # with GitHub access
+```
+
+Then, in the repository that holds the vault:
+
+```sh
+livedocs init --vault docs/vault           # git gate (.githooks + core.hooksPath), .livedocs/config.json,
+                                           # Claude Code Stop heads-up (settings.local.json), AGENTS.md block
+```
+
+That is the whole setup. Notes are stamped by the commit that adds or edits them: write a note, commit
+it, and the gate binds its code mentions and records the stamp in the same commit. For an existing vault,
+`git add` the notes and commit once (or run `livedocs stamp <note>` per note to see what each binds).
+Each clone activates the versioned hook with `git config core.hooksPath .githooks` (`init` does it).
+`--repo` defaults to the current git repository and `--vault` to the configured one, so inside the repo
+the commands need no arguments.
+
+## The commit flow
+
+```
+edit code ──► git commit
+              │  gate: notes that mention the changed code, not yet reconciled?
+              ├─ none / benign ────────────────────────────────► commit passes (benign ones auto-acked;
+              │                                                   new or edited notes stamped)
+              └─ some ──► "CHANGED: <note> … was: … now: … note lines 13, 30"
+                          edit the note and commit again          (the commit stamps it)
+                          or, still correct:  livedocs stamp <note> --ack --reason "…"; git add -A; commit
+```
+
+`livedocs affected` lists the notes your uncommitted changes touch before you get there.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `livedocs new-vault <path> [--scaffold-modules]` | scaffold an Obsidian vault and wire everything in |
+| `livedocs init --vault <path> [--read-gate] [--shared]` | install the gate, config and harness adapter for an existing vault |
+| `livedocs stamp <note> [--ack --reason R]` | bind a note's mentions with drift and record a stamp |
+| `livedocs check <note> [--json]` | one note's state: `fresh`, `changed`, `broken`, `unknown`, `snapshot` |
+| `livedocs affected [--cached]` | notes bound to files changed in the working tree (or the index) |
+| `livedocs verify` | CI: every stamped note against the checked-out tree; exit 1 on changed/broken |
+| `livedocs coverage` | per-note anchored / dangling mentions |
+| `livedocs survey` | resolution statistics over a vault (diagnostics) |
+
+## Snapshot notes
+
+Dated records — reviews, session logs, reports — describe the code as it *was*. Mark them with
+`livedocs: snapshot` in the frontmatter, or list globs in `.livedocs/config.json`:
+
+```json
+{ "vault": "docs/vault", "snapshot_globs": ["Reference/Review *", "Sessions/*"] }
+```
+
+They bind nothing, report `snapshot`, and never block.
+
+## CI
+
+Pre-commit is skipped by `--no-verify`, merges and rebases. Run the same check in CI:
+
+```yaml
+# .github/workflows/livedocs.yml
+name: livedocs
+on: [push, pull_request]
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: curl -fsSL https://drift.fp.dev/install.sh | sh && echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - uses: astral-sh/setup-uv@v5
+      - run: uv tool install git+https://github.com/GusEllerm/vault-drift
+      - run: livedocs verify --repo . --vault docs/vault
+```
+
+Or with the [pre-commit](https://pre-commit.com) framework, add to `.pre-commit-config.yaml`:
+
+```yaml
+- repo: https://github.com/GusEllerm/vault-drift
+  rev: v0.1.0
+  hooks: [{ id: livedocs-gate }]
+```
+
+## What it can and cannot guarantee
+
+- It guarantees that a *committed* note has been vouched for against the code it mentions, at that
+  commit. A read-time `changed` means the working tree has moved since.
+- It sees code the note names in backticks. A prose claim with nothing to anchor ("tokens rotate every
+  15 minutes") is reported `unknown`, never `fresh`. `livedocs coverage` shows how much of each note that is.
+- It does not follow the call graph: a note's claim about what a function *does* can go stale when a
+  callee changes. That is the residual miss class, measured at about 1 in 20 real changes on the
+  reference history.
+- Python only, for now (symbol resolution uses `ast`; drift fingerprints six languages).
+
+## Background
+
+Design, decisions and the measurements behind every choice live in the vault at `live-docs-vault/`
+(start at `Start Here.md`). The short version: on a real 141-commit history, the hash flagged 22 of the
+23 note-invalidating changes an anchor covered; only ~5% of flags marked a change that made a note wrong
+— which is why the signal is delivered as a fact at commit time, to the agent that has the context, and
+never as a verdict.

livedocs-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "livedocs"
+version = "0.1.0"
+description = "Notes that know when the code moved on: hash-anchored live docs with a git commit gate, over Fiberplane drift."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = []
+keywords = ["documentation", "drift", "agents", "obsidian", "git-hooks"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Documentation",
+  "Topic :: Software Development :: Version Control :: Git",
+]
+
+[project.urls]
+Repository = "https://github.com/GusEllerm/vault-drift"
+
+[project.scripts]
+livedocs = "livedocs.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/livedocs"]
+
+[tool.hatch.build.targets.sdist]
+# The package is the tool; the vault, results and testbench stay in the repository.
+only-include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml", ".pre-commit-hooks.yaml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

livedocs-0.1.0/src/livedocs/__init__.py

@@ -0,0 +1,3 @@
+"""livedocs: a thin wrapper over drift that binds notes to code and tells agents when a note is out of date."""
+
+__version__ = "0.0.1"

livedocs-0.1.0/src/livedocs/affected.py

@@ -0,0 +1,69 @@
+"""Which notes does a code change touch? Changed files → bindings in drift.lock → notes → check."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from . import check as ck, drift_io, gitx, stamps as st
+
+
+def affected_notes(repo: str | Path, vault_rel: str, changed: list[str]) -> list[str]:
+    """Notes (vault-relative) with a binding whose path is in `changed`."""
+    repo = Path(repo)
+    changed_set = set(changed)
+    notes: set[str] = set()
+    prefix = f"{vault_rel}/" if vault_rel else ""
+    for (doc, target), _sig in drift_io.lock(repo).items():
+        if target.split("#", 1)[0] in changed_set and doc.startswith(prefix):
+            notes.add(doc[len(prefix):])
+    return sorted(notes)
+
+
+def affected(repo: str | Path, vault_rel: str, *, cached: bool = False, base: str = "HEAD",
+             changed: list[str] | None = None, snapshot: str | Path | None = None,
+             refine: bool = False) -> list[ck.Report]:
+    """Reports for every note bound to a changed file. `snapshot` runs the checks against a
+    checkout-index copy (the pre-commit gate) while git operations use `repo`."""
+    repo = Path(repo)
+    if changed is None:
+        changed = gitx.changed_files(repo, cached=cached, base=base)
+    files_root = Path(snapshot) if snapshot else repo
+    notes = affected_notes(files_root, vault_rel, changed)
+    if not notes:
+        return []
+    try:
+        dj = drift_io.check_json(files_root)
+    except drift_io.DriftError as e:
+        return [ck.Report(n, ck.UNKNOWN, [f"checker-error: {e}"]) for n in notes]
+    all_stamps = st.load(files_root / vault_rel)
+    return [ck.check(files_root, vault_rel, n, drift_json=dj, all_stamps=all_stamps, refine=refine, git_repo=repo) for n in notes]
+
+
+def verify(repo: str | Path, vault_rel: str, *, refine: bool = False) -> list[ck.Report]:
+    """CI check: every stamped, non-snapshot note against the tree as checked out. Catches commits
+    made with --no-verify, merges and rebases, which pre-commit never sees."""
+    repo = Path(repo)
+    vault = repo / vault_rel
+    all_stamps = st.load(vault)
+    notes = sorted({s.note for s in all_stamps})
+    if not notes:
+        return []
+    try:
+        dj = drift_io.check_json(repo)
+    except drift_io.DriftError as e:
+        return [ck.Report(n, ck.UNKNOWN, [f"checker-error: {e}"]) for n in notes]
+    return [ck.check(repo, vault_rel, n, drift_json=dj, all_stamps=all_stamps, refine=refine) for n in notes]
+
+
+def summary_lines(reports: list[ck.Report]) -> list[str]:
+    out = []
+    for r in reports:
+        if r.state in (ck.FRESH, ck.SNAPSHOT):
+            continue
+        if ck.mechanically_benign(r):
+            extra = " (benign: the members it mentions are unchanged — will be auto-acked at commit)"
+        else:
+            kinds = sorted({f.kind for f in r.findings} - {"unchanged"})
+            extra = f" ({', '.join(kinds)})" if kinds else (f" ({'; '.join(r.reasons)})" if r.reasons else "")
+        out.append(f"{r.state.upper():8} {r.note}{extra}")
+    return out

livedocs-0.1.0/src/livedocs/astdiff.py

@@ -0,0 +1,186 @@
+"""Symbol source at two versions of a file, and what kind of change happened.
+
+Kinds: signature | decorator | body | comment-or-docstring-only | unchanged | removed | added
+"""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+from dataclasses import dataclass
+
+SIGNATURE, DECORATOR, BODY, COMMENT_ONLY, UNCHANGED, REMOVED, ADDED, UNPARSEABLE = (
+    "signature", "decorator", "body", "comment-or-docstring-only", "unchanged", "removed", "added", "unparseable",
+)
+
+
+def parses(source: str | None) -> bool:
+    if source is None:
+        return False
+    try:
+        ast.parse(source)
+        return True
+    except SyntaxError:
+        return False
+
+
+def _find(tree: ast.Module, qualname: str) -> ast.AST | None:
+    parts = qualname.split(".")
+    scope: list[ast.stmt] = tree.body
+    node: ast.AST | None = None
+    for i, part in enumerate(parts):
+        node = None
+        for n in scope:
+            if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)) and n.name == part:
+                node = n
+                break
+            if isinstance(n, ast.Assign) and any(isinstance(t, ast.Name) and t.id == part for t in n.targets):
+                node = n
+                break
+            if isinstance(n, ast.AnnAssign) and isinstance(n.target, ast.Name) and n.target.id == part:
+                node = n
+                break
+        if node is None:
+            return None
+        if i < len(parts) - 1:
+            if not isinstance(node, ast.ClassDef):
+                return None
+            scope = node.body
+    return node
+
+
+def symbol_source(source: str, qualname: str) -> str | None:
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return None
+    node = _find(tree, qualname)
+    if node is None:
+        return None
+    seg = ast.get_source_segment(source, node, padded=True)
+    if seg is None:
+        return None
+    decos = getattr(node, "decorator_list", ())
+    if decos:  # get_source_segment starts at `def`; include decorator lines
+        lines = source.splitlines()
+        start = min(d.lineno for d in decos) - 1
+        end = (node.end_lineno or node.lineno)
+        seg = "\n".join(lines[start:end])
+    return seg
+
+
+def decorator_hash(source: str, top_level_name: str) -> str:
+    """Hash of a top-level symbol's decorators (empty string if none or unparseable)."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return ""
+    node = _find(tree, top_level_name)
+    decos = getattr(node, "decorator_list", ()) if node is not None else ()
+    if not decos:
+        return ""
+    return hashlib.sha256("\n".join(ast.unparse(d) for d in decos).encode()).hexdigest()[:16]
+
+
+def _strip_docstrings(node: ast.AST) -> ast.AST:
+    for n in ast.walk(node):
+        body = getattr(n, "body", None)
+        if isinstance(body, list) and body and isinstance(body[0], ast.Expr) and isinstance(getattr(body[0], "value", None), ast.Constant) and isinstance(body[0].value.value, str):
+            n.body = body[1:] or [ast.Pass()]
+    return node
+
+
+def _dump(node: ast.AST) -> str:
+    return ast.dump(node, include_attributes=False)
+
+
+def _sig_dump(node: ast.AST) -> str:
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        # sync→async is a signature change: callers must await it
+        return type(node).__name__ + node.name + _dump(node.args) + (_dump(node.returns) if node.returns else "")
+    if isinstance(node, ast.ClassDef):
+        return node.name + "".join(_dump(b) for b in node.bases) + "".join(_dump(k) for k in node.keywords)
+    return ""
+
+
+@dataclass(frozen=True)
+class Change:
+    kind: str
+    was: str | None
+    now: str | None
+
+
+def classify(old_source: str | None, new_source: str | None, qualname: str) -> Change:
+    if new_source is not None and not parses(new_source):
+        return Change(UNPARSEABLE, symbol_source(old_source, qualname) if old_source else None, None)
+    old = symbol_source(old_source, qualname) if old_source is not None else None
+    new = symbol_source(new_source, qualname) if new_source is not None else None
+    if old is None and new is None:
+        return Change(REMOVED, None, None)
+    if old is None:
+        return Change(ADDED, None, new)
+    if new is None:
+        return Change(REMOVED, old, None)
+    if old == new:
+        return Change(UNCHANGED, old, new)
+    on, nn = _find(ast.parse(old_source), qualname), _find(ast.parse(new_source), qualname)
+    if _sig_dump(on) != _sig_dump(nn):
+        return Change(SIGNATURE, old, new)
+    if [ast.unparse(d) for d in getattr(on, "decorator_list", ())] != [ast.unparse(d) for d in getattr(nn, "decorator_list", ())]:
+        return Change(DECORATOR, old, new)
+    if _dump(_strip_docstrings(on)) == _dump(_strip_docstrings(nn)):
+        return Change(COMMENT_ONLY, old, new)
+    return Change(BODY, old, new)
+
+
+def member_hash(source: str | None, qualname: str) -> str | None:
+    """Content hash of what a note mentions, insensitive to comments, docstrings and formatting.
+
+    function/method: the whole node (args, returns, decorators, body) with docstrings stripped.
+    class: its shell — bases, keywords, decorators, member names, and field/attribute definitions —
+           but not method bodies (a note that mentions the class, not the method, doesn't depend on them).
+    attribute/constant: the assignment node.
+    None if the source doesn't parse or the symbol isn't there.
+    """
+    if source is None:
+        return None
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return None
+    node = _find(tree, qualname)
+    if node is None:
+        return None
+    import copy
+    node = copy.deepcopy(node)
+    if isinstance(node, ast.ClassDef):
+        parts = [
+            "class", node.name,
+            *(ast.unparse(b) for b in node.bases), *(ast.unparse(k) for k in node.keywords),
+            *(ast.unparse(d) for d in node.decorator_list),
+        ]
+        for n in node.body:
+            if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                parts.append(f"def {n.name}")
+            elif isinstance(n, ast.ClassDef):
+                parts.append(f"class {n.name}")
+            elif isinstance(n, (ast.Assign, ast.AnnAssign)):
+                parts.append(_dump(n))
+        payload = "\n".join(parts)
+    else:
+        payload = _dump(_strip_docstrings(node))
+        decos = getattr(node, "decorator_list", ())
+        if decos:
+            payload += "\n" + "\n".join(ast.unparse(d) for d in decos)
+    return hashlib.sha256(payload.encode()).hexdigest()[:16]
+
+
+def first_line(src: str | None) -> str:
+    """The def/class line (after decorators), for compact was/now output."""
+    if not src:
+        return ""
+    for l in src.splitlines():
+        s = l.strip()
+        if s and not s.startswith("@"):
+            return s
+    return src.splitlines()[0].strip()