dev-memory-cli 0.18.2

package/lib/dev_memory_tidy.py

@@ -0,0 +1,1622 @@
+#!/usr/bin/env python3
+"""
+dev-memory-tidy: review and groom existing memory entries.
+
+Setup turns lazy-init lumps into structured files (no order → ordered).
+Tidy is the second pass that runs periodically: structured files drift
+over time (stale items, duplicates, mistakes), and tidy lets the user
+review every entry, mark keep/delete/edit, and write the result back.
+
+Workflow:
+  1. `prepare` — scan the target scope (branch + optional repo), parse
+     each .md file into top-level bullet entries, optionally inject
+     agent hints (STALE/DUP/OK/UNCLEAR + reason), render a static
+     review.html the user opens locally and exports a plan.json from.
+  2. `apply` — read the user's plan.json, snapshot the current scope
+     into tidy_backup_<ts>/, then rewrite each file according to the
+     keep/delete/edit actions per entry.
+
+Skipped on purpose:
+  - Auto-sync blocks (between AUTO-GENERATED-START/END) are never
+    surfaced — they're regenerated by other commands.
+  - Manifest.json is not a tidy target; it's structured data, not prose.
+"""
+
+import argparse
+import hashlib
+import json
+import shutil
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from dev_memory_common import (
+    AUTO_END,
+    AUTO_START,
+    append_log_event,
+    ensure_branch_paths_exist,
+    join_sections,
+    split_sections,
+    template_decisions,
+    template_glossary,
+    template_overview,
+    template_pending_promotion,
+    template_progress,
+    template_repo_decisions,
+    template_repo_glossary,
+    template_repo_overview,
+    template_risks,
+    template_unsorted,
+)
+
+HTML_TEMPLATE_PATH = Path(__file__).resolve().parent / "assets" / "tidy_review.html"
+
+# Map file_key -> callable that produces a fresh v2 template body. Used by
+# the reset-file proposal action when an entry-level cleanup is too coarse
+# (e.g. v1 → v2 left H3 skeleton sections that tidy can't surgically remove).
+def _template_for(file_key, branch_name, repo_name):
+    table = {
+        "overview": lambda: template_overview(branch_name),
+        "decisions": lambda: template_decisions(branch_name),
+        "progress": lambda: template_progress(branch_name),
+        "risks": lambda: template_risks(branch_name),
+        "glossary": lambda: template_glossary(branch_name),
+        "unsorted": lambda: template_unsorted(),
+        "pending_promotion": lambda: template_pending_promotion(),
+        "repo_overview": lambda: template_repo_overview(repo_name),
+        "repo_decisions": lambda: template_repo_decisions(repo_name),
+        "repo_glossary": lambda: template_repo_glossary(repo_name),
+    }
+    fn = table.get(file_key)
+    return fn() if fn else None
+
+# Files we tidy. Keys map to dev_memory_common.asset_paths() entries.
+BRANCH_FILE_KEYS = (
+    "overview",
+    "decisions",
+    "progress",
+    "risks",
+    "glossary",
+    "unsorted",
+    "pending_promotion",
+)
+REPO_FILE_KEYS = (
+    "repo_overview",
+    "repo_decisions",
+    "repo_glossary",
+)
+
+VALID_HINTS = {"STALE", "DUP", "OK", "UNCLEAR", "ORPHAN"}
+
+# Default age (days) past which a file is considered "untouched" — entries
+# inside such files get auto-tagged with hint=STALE so the user reviews them.
+# Pulled from log.md's per-action timestamps. Tunable via the CLI flag
+# `--stale-after-days`; the default is conservative because false STALEs
+# annoy users more than missed ones.
+AUTO_STALE_THRESHOLD_DAYS = 30
+
+# Minimum token length for ORPHAN detection. Shorter tokens (e.g. "API",
+# "git") match too much across the codebase and produce false negatives —
+# the hint becomes useless. Tunable but rarely worth it.
+AUTO_ORPHAN_MIN_TOKEN_LEN = 4
+VALID_ENTRY_ACTIONS = {"keep", "delete", "edit"}
+VALID_PROPOSAL_TYPES = {"delete-entries", "delete-section", "reset-file", "edit-entries", "delete-block"}
+VALID_PRIORITIES = {"P0", "P1", "P2", "P3", "P4"}
+
+# Heuristic: lines like `**Why:** ...`, `**How to apply:** ...`, or
+# `**xxx**：...` are "orphan paragraphs" — narrative attached to the
+# previous bullet but not itself in any bullet list. _parse_blocks absorbs
+# them into the preceding block so a single delete-block takes them out
+# together with the bullets they explain. Two accepted shapes:
+#   1. `**Foo:** rest`   — colon inside the bold span (common in CN/EN)
+#   2. `**Foo**: rest`   — colon (half- or full-width) outside the bold span
+import re as _re_block
+_ORPHAN_PARAGRAPH_RE = _re_block.compile(
+    r"^\s*\*\*[^*\n]+[:：]\*\*\s|^\s*\*\*[^*\n]+\*\*\s*[:：]"
+)
+
+
+def _now_stamp():
+    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+
+
+def _strip_auto_block(body):
+    """Remove the AUTO-GENERATED block from a section body so tidy
+    doesn't show machine-managed state to the user. Returns the body
+    with the block (and surrounding blank lines) removed."""
+    if AUTO_START not in body or AUTO_END not in body:
+        return body
+    start = body.index(AUTO_START)
+    end = body.index(AUTO_END) + len(AUTO_END)
+    return (body[:start].rstrip() + "\n" + body[end:].lstrip()).strip()
+
+
+def _parse_entries(body):
+    """Split a section body into top-level bullet entries. A continuation
+    line (indented or non-bullet) is appended to the previous entry. Returns
+    a list of {entry_idx, text} dicts. Entries that match placeholder
+    markers (待补充 etc.) are returned with `is_placeholder=True` so the
+    UI can render them faded but still allow delete/edit."""
+    entries = []
+    current = None
+    for line in body.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            if current is not None:
+                entries.append(current)
+                current = None
+            continue
+        if stripped.startswith("- "):
+            if current is not None:
+                entries.append(current)
+            current = {"text": stripped[2:].strip(), "raw_lines": [line]}
+        elif current is not None:
+            # Continuation: keep the original indentation when reconstructing.
+            current["text"] = current["text"] + "\n" + stripped
+            current["raw_lines"].append(line)
+        # Lines before any bullet (free-form prose) are ignored — tidy
+        # only operates on bullet-style entries to keep the action set
+        # finite. Free-form prose stays untouched in the file.
+    if current is not None:
+        entries.append(current)
+    indexed = []
+    for idx, ent in enumerate(entries):
+        text = ent["text"].strip()
+        is_placeholder = text in ("待补充", "待刷新")
+        indexed.append({
+            "entry_idx": idx,
+            "text": text,
+            "is_placeholder": is_placeholder,
+        })
+    return indexed
+
+
+def _parse_blocks(body):
+    """Group a section body into semantic 'blocks'. A block is the smallest
+    unit an agent typically wants to delete or move as a whole: a top-level
+    bullet plus its indented sub-bullets, optionally trailed by bold
+    paragraph(s) like `**Why:** ...` that explain it.
+
+    Why this layer exists: `_parse_entries` treats every bullet line —
+    including indented sub-bullets — as a separate entry. That gives
+    surgical edits but loses the parent/child relationship. Block parsing
+    keeps `_parse_entries` intact and adds a second view that re-groups
+    those entries into the semantic unit an agent actually reasons about.
+
+    Block boundary rules:
+      - A top-level `- xxx` (no leading whitespace) starts a new block.
+      - Indented bullets `  - yyy` join the current block — they are still
+        entries (`_parse_entries` counts them), but they belong to the
+        same semantic unit as the top-level bullet above them. The block's
+        `entry_idx_range` therefore spans 1 top-level entry + N sub-bullet
+        entries.
+      - A bold-prefixed paragraph (`**Why:** ...`) immediately following
+        the last bullet — possibly across a single blank line — is
+        absorbed as the block's tail. Two consecutive blank lines, or any
+        other top-level bullet, terminates the tail. Paragraph lines do
+        NOT count as entries.
+      - Lines before the first bullet are not part of any block (mirrors
+        `_parse_entries` which also ignores them).
+
+    Invariant: every entry produced by `_parse_entries` on the same body
+    falls inside exactly one block. `entry_idx_range` is `[start, end]`
+    inclusive over those entry indices.
+    """
+    lines = body.splitlines()
+    blocks = []
+    current = None
+    pending_blank = False
+    entry_counter = -1  # increments on every bullet line (top-level or sub)
+
+    def push_current():
+        nonlocal current
+        if current is None:
+            return
+        while current["raw_lines"] and not current["raw_lines"][-1].strip():
+            current["raw_lines"].pop()
+        blocks.append(current)
+        current = None
+
+    def is_bullet_line(s):
+        return s.startswith("- ") or s == "-"
+
+    for raw in lines:
+        stripped = raw.strip()
+        if not stripped:
+            if current is not None:
+                if pending_blank:
+                    push_current()
+                    pending_blank = False
+                else:
+                    pending_blank = True
+                    current["raw_lines"].append(raw)
+            continue
+
+        is_top_bullet = is_bullet_line(stripped) and not (raw.startswith(" ") or raw.startswith("\t"))
+        is_sub_bullet = is_bullet_line(stripped) and (raw.startswith(" ") or raw.startswith("\t"))
+
+        if is_top_bullet:
+            push_current()
+            entry_counter += 1
+            current = {
+                "block_idx": len(blocks),
+                "entry_idx_start": entry_counter,
+                "entry_idx_end": entry_counter,
+                "first_line_preview": stripped[2:].strip()[:160] if stripped.startswith("- ") else stripped[:160],
+                "has_orphan_paragraphs": False,
+                "raw_lines": [raw],
+            }
+            pending_blank = False
+            continue
+
+        if current is None:
+            # Free-form prose before any bullet — drop (mirrors _parse_entries).
+            continue
+
+        if is_sub_bullet:
+            entry_counter += 1
+            current["entry_idx_end"] = entry_counter
+            current["raw_lines"].append(raw)
+            pending_blank = False
+            continue
+
+        # Indented non-bullet continuation (wrapped text under a bullet).
+        # _parse_entries treats this as continuation of the previous entry,
+        # so it doesn't advance entry_counter — neither do we.
+        if raw.startswith(" ") or raw.startswith("\t"):
+            current["raw_lines"].append(raw)
+            pending_blank = False
+            continue
+
+        # Non-indented, non-blank, not a bullet → candidate orphan paragraph.
+        # Absorb if it looks like `**Foo:** ...`. _parse_entries treats it
+        # as continuation of the previous (still-open) entry, but only when
+        # no blank line has separated them. If a single blank line came
+        # between bullet and paragraph, _parse_entries already closed the
+        # previous entry — but we still attach to the block (the paragraph
+        # belongs to the unit semantically).
+        if _ORPHAN_PARAGRAPH_RE.match(raw):
+            current["raw_lines"].append(raw)
+            current["has_orphan_paragraphs"] = True
+            pending_blank = False
+            continue
+
+        # Some other non-bullet prose between bullets — close the current
+        # block; this prose is not owned by anything.
+        push_current()
+        pending_blank = False
+
+    push_current()
+
+    return [
+        {
+            "block_idx": b["block_idx"],
+            "entry_idx_range": [b["entry_idx_start"], b["entry_idx_end"]],
+            "first_line_preview": b["first_line_preview"],
+            "has_orphan_paragraphs": b["has_orphan_paragraphs"],
+            "raw_lines": b["raw_lines"],
+        }
+        for b in blocks
+    ]
+
+
+def _block_id(file_key, section_idx, block_idx):
+    return f"{file_key}::{section_idx}::block-{block_idx}"
+
+
+def _block_content_hash(raw_lines):
+    """Compute a deterministic 16-char hex hash of a block's content.
+
+    `raw_lines` is the list of original source lines that make up the block
+    (top-level bullet + sub-bullets + absorbed orphan paragraphs, as captured
+    by `_parse_blocks`; `push_current` has already trimmed trailing blanks).
+    Joined with `\n` to form a stable byte sequence, SHA-256'd, then
+    truncated to 16 hex chars — long enough to keep collisions astronomically
+    unlikely across one section, short enough to keep plan.json readable.
+
+    Used by `apply` to detect that a block's content drifted between
+    `prepare` and `apply` (e.g. user edited a bullet but block_idx stayed
+    the same), so delete-block can refuse to nuke the wrong unit.
+    """
+    raw_text = "\n".join(raw_lines)
+    return hashlib.sha256(raw_text.encode("utf-8")).hexdigest()[:16]
+
+
+def _parse_block_id(bid):
+    """Return (file_key, section_idx, block_idx) or None on bad input."""
+    if not isinstance(bid, str):
+        return None
+    parts = bid.split("::")
+    if len(parts) != 3 or not parts[2].startswith("block-"):
+        return None
+    try:
+        return parts[0], int(parts[1]), int(parts[2][len("block-"):])
+    except ValueError:
+        return None
+
+
+def _file_label(file_key):
+    if file_key.startswith("repo_"):
+        return f"repo/{file_key[5:]}.md"
+    return f"branch/{file_key}.md"
+
+
+def _scope_paths(paths, include_repo):
+    """Return ordered (file_key, path) tuples that exist."""
+    out = []
+    for key in BRANCH_FILE_KEYS:
+        p = paths.get(key)
+        if p and p.exists():
+            out.append((key, p))
+    if include_repo:
+        for key in REPO_FILE_KEYS:
+            p = paths.get(key)
+            if p and p.exists():
+                out.append((key, p))
+    return out
+
+
+def _scan_scope(paths, include_repo):
+    """Scan target files into a tree of {file, sections, entries}."""
+    files = []
+    for file_key, path in _scope_paths(paths, include_repo):
+        content = path.read_text(encoding="utf-8")
+        prefix, sections = split_sections(content)
+        section_records = []
+        for section_idx, (title, body) in enumerate(sections):
+            cleaned = _strip_auto_block(body)
+            entries = _parse_entries(cleaned)
+            if not entries:
+                continue
+            section_records.append({
+                "section_idx": section_idx,
+                "title": title,
+                "entries": entries,
+            })
+        if not section_records:
+            continue
+        files.append({
+            "file_key": file_key,
+            "label": _file_label(file_key),
+            "path": str(path),
+            "sections": section_records,
+        })
+    return files
+
+
+def _entry_id(file_key, section_idx, entry_idx):
+    return f"{file_key}::{section_idx}::{entry_idx}"
+
+
+def _flatten_entries(files):
+    """Yield every entry with its stable ID for hint/plan lookup."""
+    for f in files:
+        for s in f["sections"]:
+            for e in s["entries"]:
+                yield _entry_id(f["file_key"], s["section_idx"], e["entry_idx"]), f, s, e
+
+
+def _validate_hints(hints):
+    """Ensure each value is {label: ..., reason: ...} with valid label."""
+    if hints is None:
+        return {}
+    if not isinstance(hints, dict):
+        raise ValueError("hints must be a JSON object keyed by entry id")
+    cleaned = {}
+    for k, v in hints.items():
+        if not isinstance(v, dict):
+            raise ValueError(f"hint for {k} must be an object")
+        label = (v.get("label") or "").strip().upper()
+        reason = (v.get("reason") or "").strip()
+        if label and label not in VALID_HINTS:
+            raise ValueError(f"hint label for {k} must be one of {sorted(VALID_HINTS)}")
+        cleaned[k] = {"label": label, "reason": reason}
+    return cleaned
+
+
+def _validate_proposals(raw):
+    """Each proposal: {id, title, reason, actions: [...]}.
+    Each action variant: delete-entries / delete-section / reset-file /
+    edit-entries. We only sanitise here — actual semantics are interpreted
+    at apply time after the user accepts via the HTML."""
+    if raw is None:
+        return []
+    if not isinstance(raw, list):
+        raise ValueError("proposals must be a JSON array")
+    cleaned = []
+    seen_ids = set()
+    for i, p in enumerate(raw):
+        if not isinstance(p, dict):
+            raise ValueError(f"proposal #{i} must be an object")
+        pid = (p.get("id") or f"p{i}").strip()
+        if pid in seen_ids:
+            raise ValueError(f"duplicate proposal id {pid!r}")
+        seen_ids.add(pid)
+        title = (p.get("title") or "").strip()
+        reason = (p.get("reason") or "").strip()
+        actions = p.get("actions") or []
+        if not title:
+            raise ValueError(f"proposal {pid} missing title")
+        if not actions:
+            raise ValueError(f"proposal {pid} has no actions")
+        cleaned_actions = []
+        for j, a in enumerate(actions):
+            if not isinstance(a, dict):
+                raise ValueError(f"proposal {pid} action #{j} must be an object")
+            atype = (a.get("type") or "").strip()
+            if atype not in VALID_PROPOSAL_TYPES:
+                raise ValueError(
+                    f"proposal {pid} action #{j} has invalid type {atype!r}; "
+                    f"must be one of {sorted(VALID_PROPOSAL_TYPES)}"
+                )
+            if atype == "delete-block":
+                bid = (a.get("block_id") or "").strip()
+                if not bid or _parse_block_id(bid) is None:
+                    raise ValueError(
+                        f"proposal {pid} action #{j} delete-block needs block_id of form "
+                        f"'<file_key>::<section_idx>::block-<N>' (got {bid!r})"
+                    )
+                # Optional content fingerprint. apply will re-hash the block
+                # at the resolved location and refuse to delete if the value
+                # drifted; absent means "skip the content check".
+                ech = a.get("expected_content_hash")
+                if ech is not None and not isinstance(ech, str):
+                    raise ValueError(
+                        f"proposal {pid} action #{j} delete-block expected_content_hash "
+                        f"must be a string if provided (got {type(ech).__name__})"
+                    )
+            cleaned_actions.append(a)
+        priority = (p.get("priority") or "").strip().upper()
+        if priority and priority not in VALID_PRIORITIES:
+            raise ValueError(
+                f"proposal {pid} priority must be one of {sorted(VALID_PRIORITIES)} or empty, got {priority!r}"
+            )
+        cleaned.append({
+            "id": pid,
+            "title": title,
+            "reason": reason,
+            "priority": priority,
+            "actions": cleaned_actions,
+        })
+    return cleaned
+
+
+def _collect_blocks(files):
+    """Re-parse each scanned section into blocks. Returns a tuple of
+    (blocks_by_file_section, flat_block_index) where:
+
+      - blocks_by_file_section: {file_key: {section_idx: [block, ...]}}
+        with each block carrying its raw_lines (kept internally — not
+        emitted in the public JSON to keep that payload light).
+      - flat_block_index: list of public block dicts safe to dump as JSON,
+        each shaped {id, file, section, first_line_preview, entry_ids,
+        has_orphan_paragraphs}.
+
+    Re-parses on each call rather than threading block info through
+    `_scan_scope` so the existing `_scan_scope` shape stays untouched
+    (and downstream callers — html template — still see the same JSON).
+    """
+    by_fs = {}
+    flat = []
+    for f in files:
+        fk = f["file_key"]
+        by_fs[fk] = {}
+        # Re-read the section bodies (post _strip_auto_block) to get raw_lines.
+        # We can reconstruct them from the file because _scan_scope already
+        # filtered out empty sections — but we still need the original body,
+        # so re-read the file and re-split.
+        content = Path(f["path"]).read_text(encoding="utf-8")
+        _, sections = split_sections(content)
+        for s in f["sections"]:
+            sidx = s["section_idx"]
+            if sidx >= len(sections):
+                by_fs[fk][sidx] = []
+                continue
+            _title, body = sections[sidx]
+            cleaned = _strip_auto_block(body)
+            blocks = _parse_blocks(cleaned)
+            by_fs[fk][sidx] = blocks
+            for b in blocks:
+                start, end = b["entry_idx_range"]
+                entry_ids = [_entry_id(fk, sidx, i) for i in range(start, end + 1)]
+                flat.append({
+                    "id": _block_id(fk, sidx, b["block_idx"]),
+                    "file": f["label"],
+                    "file_key": fk,
+                    "section": s["title"],
+                    "section_idx": sidx,
+                    "first_line_preview": b["first_line_preview"],
+                    "entry_ids": entry_ids,
+                    "has_orphan_paragraphs": b["has_orphan_paragraphs"],
+                    # 16-char fingerprint of the block's raw source bytes —
+                    # agent copies this verbatim into plan.json's delete-block
+                    # action as `expected_content_hash`; apply re-hashes the
+                    # current file and refuses to delete if the value drifted.
+                    "content_hash": _block_content_hash(b["raw_lines"]),
+                })
+    return by_fs, flat
+
+
+def _render_annotated_md(files, blocks_by_fs, scope_meta, output_path):
+    """Write a single .md mirror with id / block / orphan comment markers
+    so an agent can read one file and recover entry id + block boundaries
+    without parsing the original markdown twice.
+
+    Format (see design §1.1):
+      # Tidy entries · <branch> · <timestamp>
+      ## 📄 branch/<file>.md
+      ### <section title>
+      <!-- block: <id> -->
+      - bullet  <!-- id: <entry-id> -->
+        - sub          (no id comment — continuation of the entry above)
+      **Why:** ...  <!-- orphan: paragraph -->
+      <!-- /block -->
+
+    Placeholder entries (`- 待补充` / `- 待刷新`) get an extra
+    `<!-- placeholder -->` so the agent can ignore them at a glance.
+    AUTO-GENERATED blocks are not surfaced (already stripped upstream).
+    """
+    lines = [
+        f"# Tidy entries · {scope_meta['branch']} · {scope_meta['generated_at']}",
+        "",
+    ]
+    for f in files:
+        fk = f["file_key"]
+        lines.append(f"<!-- file: {fk} / {f['label']} -->")
+        lines.append(f"## 📄 {f['label']}")
+        lines.append("")
+        for s in f["sections"]:
+            sidx = s["section_idx"]
+            lines.append(f"<!-- section: {sidx} / {s['title']} -->")
+            lines.append(f"### {s['title']}")
+            blocks = blocks_by_fs.get(fk, {}).get(sidx, [])
+            if not blocks:
+                lines.append("")
+                continue
+            # Build a quick lookup: which entry_idx is the top-level bullet
+            # on each raw_line, so we know which line to tag with `<!-- id -->`.
+            entry_text_by_idx = {e["entry_idx"]: e for e in s["entries"]}
+            for b in blocks:
+                lines.append("")
+                lines.append(f"<!-- block: {_block_id(fk, sidx, b['block_idx'])} -->")
+                start, _end = b["entry_idx_range"]
+                # Walk raw_lines, tagging the first top-level bullet with the
+                # entry id. Sub-bullets and continuation lines are emitted
+                # bare. Orphan paragraph lines get `<!-- orphan: paragraph -->`.
+                seen_top_bullet = False
+                cur_entry_idx = start
+                for raw in b["raw_lines"]:
+                    stripped = raw.strip()
+                    if not stripped:
+                        lines.append(raw)
+                        continue
+                    is_top_bullet = (
+                        stripped.startswith("- ")
+                        and not (raw.startswith(" ") or raw.startswith("\t"))
+                    )
+                    if is_top_bullet:
+                        if seen_top_bullet:
+                            cur_entry_idx += 1
+                        seen_top_bullet = True
+                        ent = entry_text_by_idx.get(cur_entry_idx, {})
+                        eid = _entry_id(fk, sidx, cur_entry_idx)
+                        suffix = f"  <!-- id: {eid} -->"
+                        if ent.get("is_placeholder"):
+                            suffix += " <!-- placeholder -->"
+                        lines.append(f"{raw}{suffix}")
+                    elif _ORPHAN_PARAGRAPH_RE.match(raw):
+                        lines.append(f"{raw}  <!-- orphan: paragraph -->")
+                    else:
+                        # Sub-bullet or wrapped continuation — emit bare.
+                        lines.append(raw)
+                lines.append("<!-- /block -->")
+            lines.append("")
+        lines.append("")
+    output_path.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
+
+
+def _render_html(files, hints, proposals, scope_meta, output_path):
+    """Inject scan + hints + proposals into the HTML template and write to disk."""
+    template = HTML_TEMPLATE_PATH.read_text(encoding="utf-8")
+    payload = {
+        "scope": scope_meta,
+        "files": files,
+        "hints": hints,
+        "proposals": proposals,
+    }
+    payload_json = json.dumps(payload, ensure_ascii=False, indent=2)
+    rendered = template.replace("__TIDY_DATA_PLACEHOLDER__", payload_json)
+    rendered = rendered.replace("__SCOPE_LABEL_PLACEHOLDER__",
+                                f"{scope_meta['repo_key']} · {scope_meta['branch']}")
+    output_path.write_text(rendered, encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Auto-hint generators (Karpathy lint pattern)
+# ---------------------------------------------------------------------------
+#
+# tidy prepare can run two cheap "positive-signal" passes that bake hints into
+# the review payload before the user opens the HTML:
+#
+#   - STALE-by-log : files whose last log.md mention is older than the
+#                    configured threshold get their entries hinted STALE.
+#                    Pulls timestamps + targets from log.md, so it costs one
+#                    file read + a regex scan; no external state.
+#   - ORPHAN-glossary : glossary entries whose key phrase doesn't appear
+#                       anywhere else in the wiki get hinted ORPHAN — the
+#                       term is dangling, not load-bearing.
+#
+# Both signals are intentionally conservative — false positives waste user
+# attention more than misses. ORPHAN skips tokens shorter than
+# AUTO_ORPHAN_MIN_TOKEN_LEN (short tokens like "API"/"hook" match too much
+# elsewhere); STALE only fires when log.md has a timestamp, never on
+# "file never seen" (cold-start would carpet-bomb the UI).
+
+
+# Reverse of capture's _label(): "branch/decisions.md" / "repo/glossary.md"
+# → file_key. Order matters: pending-promotion has a custom shape, repo_*
+# prefix wins over branch/, and we tolerate the `(mode)` trailer.
+def _file_label_to_key(label):
+    if not label:
+        return None
+    label = label.strip()
+    paren = label.find("(")
+    if paren > 0:
+        label = label[:paren].strip()
+    if label == "branch/pending-promotion.md":
+        return "pending_promotion"
+    if label.startswith("repo/") and label.endswith(".md"):
+        return "repo_" + label[len("repo/"):-len(".md")]
+    if label.startswith("branch/") and label.endswith(".md"):
+        return label[len("branch/"):-len(".md")]
+    return None
+
+
+_LOG_HEADER_RE = __import__("re").compile(r"^## \[(?P<ts>[^\]]+)\]")
+_LOG_TARGETS_RE = __import__("re").compile(r"^- targets:\s*(?P<rest>.+)$")
+
+
+def _parse_log_last_touched(log_path):
+    """Return {file_key: latest_iso_timestamp} by walking log.md once.
+
+    Algorithm: a log entry block is `## [...]` followed by a few `- key:
+    value` lines until the next H2 or EOF. We only care about the `targets`
+    detail; each comma-separated file label gets its file_key resolved and
+    the block's timestamp recorded. Later timestamps for the same file_key
+    overwrite (entries are append-only so later = file position later =
+    nothing; we still compare lexicographically since ISO sorts).
+    """
+    if log_path is None or not log_path.exists():
+        return {}
+    last_seen = {}
+    current_ts = None
+    for raw in log_path.read_text(encoding="utf-8").splitlines():
+        m = _LOG_HEADER_RE.match(raw)
+        if m:
+            current_ts = m.group("ts").strip()
+            continue
+        if current_ts is None:
+            continue
+        m = _LOG_TARGETS_RE.match(raw)
+        if not m:
+            continue
+        rest = m.group("rest").strip()
+        for chunk in rest.split(","):
+            file_key = _file_label_to_key(chunk)
+            if not file_key:
+                continue
+            prev = last_seen.get(file_key)
+            if prev is None or current_ts > prev:
+                last_seen[file_key] = current_ts
+    return last_seen
+
+
+def _iso_to_age_days(iso_ts):
+    """Best-effort: parse an ISO timestamp string into "days ago" relative
+    to now. Returns None on parse failure so callers can skip cleanly."""
+    if not iso_ts:
+        return None
+    try:
+        # datetime.fromisoformat handles "+00:00" suffixes from now_iso();
+        # the Z suffix some legacy callers emit is normalized first.
+        s = iso_ts.replace("Z", "+00:00")
+        dt = datetime.fromisoformat(s)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        delta = datetime.now(timezone.utc) - dt
+        return max(0, delta.days)
+    except (ValueError, TypeError):
+        return None
+
+
+def _stale_hints_from_log(files, log_paths, *, threshold_days):
+    """Return {entry_id: {label, reason}} for entries inside files whose log
+    last-touched age exceeds threshold_days. log_paths is an iterable of
+    branch/repo log.md paths — we union them so a file touched recently in
+    either layer is considered fresh."""
+    last_seen = {}
+    for lp in log_paths:
+        for fk, ts in _parse_log_last_touched(lp).items():
+            prev = last_seen.get(fk)
+            if prev is None or ts > prev:
+                last_seen[fk] = ts
+
+    out = {}
+    for f in files:
+        fk = f["file_key"]
+        ts = last_seen.get(fk)
+        age_days = _iso_to_age_days(ts)
+        if age_days is None or age_days < threshold_days:
+            continue
+        reason = f"log 上次提到 {age_days} 天前 (> {threshold_days})"
+        for s in f["sections"]:
+            for e in s["entries"]:
+                if e.get("is_placeholder"):
+                    continue
+                eid = _entry_id(fk, s["section_idx"], e["entry_idx"])
+                out[eid] = {"label": "STALE", "reason": reason}
+    return out
+
+
+_ORPHAN_KEY_PHRASE_TRIM_RE = __import__("re").compile(r"^[\s\-*`]+|[\s`*]+$")
+_ORPHAN_MARKDOWN_BOLD_RE = __import__("re").compile(r"\*\*([^*]+)\*\*")
+
+
+def _glossary_key_phrase(entry_text):
+    """Extract the "key phrase" of a glossary entry — the bit other files
+    would have to reference for the entry to be load-bearing.
+
+    Heuristic: take the first line, strip bullet/markdown markers, then take
+    the substring before the first `:` or `：` (half/full-width colon).
+    Falls back to the trimmed first line if no colon. Returns "" if nothing
+    extractable, so callers can skip cleanly.
+    """
+    if not entry_text:
+        return ""
+    first_line = entry_text.splitlines()[0] if entry_text else ""
+    s = first_line.strip()
+    if s.startswith(("- ", "* ")):
+        s = s[2:]
+    # Strip bold markdown wrappers if the whole token is wrapped.
+    m = _ORPHAN_MARKDOWN_BOLD_RE.match(s)
+    if m:
+        s = m.group(1) + s[m.end():]
+    for sep in (":", "："):
+        idx = s.find(sep)
+        if idx > 0:
+            s = s[:idx]
+            break
+    s = _ORPHAN_KEY_PHRASE_TRIM_RE.sub("", s).strip()
+    return s
+
+
+def _orphan_hints_from_glossary(files, paths):
+    """Return {entry_id: {label, reason}} for glossary entries whose key
+    phrase never appears in any other file in the wiki.
+
+    Why "never": we're after dangling terms, not under-referenced ones. A
+    term mentioned even once outside its definition is doing some work; an
+    entry that appears literally nowhere else is either superseded, never
+    actually used, or a private note that drifted in. Worth a user look.
+    """
+    # Build the haystack: full text of every non-glossary file in `paths`.
+    glossary_keys = {"glossary", "repo_glossary"}
+    haystack_chunks = []
+    for key, path in paths.items():
+        if key in glossary_keys:
+            continue
+        if not hasattr(path, "exists") or not path.exists():
+            continue
+        try:
+            haystack_chunks.append(path.read_text(encoding="utf-8"))
+        except OSError:
+            continue
+    haystack = "\n".join(haystack_chunks)
+
+    out = {}
+    for f in files:
+        if f["file_key"] not in glossary_keys:
+            continue
+        for s in f["sections"]:
+            for e in s["entries"]:
+                if e.get("is_placeholder"):
+                    continue
+                phrase = _glossary_key_phrase(e.get("text", ""))
+                if not phrase or len(phrase) < AUTO_ORPHAN_MIN_TOKEN_LEN:
+                    continue
+                if phrase in haystack:
+                    continue
+                eid = _entry_id(f["file_key"], s["section_idx"], e["entry_idx"])
+                out[eid] = {
+                    "label": "ORPHAN",
+                    "reason": f"术语 '{phrase}' 在其他文件零引用",
+                }
+    return out
+
+
+def _compute_auto_hints(files, paths, *, stale_threshold_days):
+    """Run both auto-hint passes and merge. ORPHAN wins over STALE on the
+    same entry — a never-referenced glossary term is a sharper signal than
+    "file hasn't been touched in a while" (which would tag the entire
+    glossary STALE on a cold log)."""
+    log_paths = []
+    if paths.get("log"):
+        log_paths.append(paths["log"])
+    if paths.get("repo_log") and paths.get("repo_log") != paths.get("log"):
+        log_paths.append(paths["repo_log"])
+
+    merged = _stale_hints_from_log(files, log_paths, threshold_days=stale_threshold_days)
+    orphan = _orphan_hints_from_glossary(files, paths)
+    merged.update(orphan)  # ORPHAN beats STALE per the docstring.
+    return merged
+
+
+def command_prepare(args):
+    repo_root, branch_name, branch_key, storage_root, repo_key, repo_dir, branch_dir, paths = ensure_branch_paths_exist(
+        args.repo, args.context_dir, args.branch
+    )
+    include_repo = args.scope == "branch+repo"
+    files = _scan_scope(paths, include_repo)
+
+    user_hints = {}
+    if args.hints_json:
+        user_hints = _validate_hints(json.loads(args.hints_json))
+    elif args.hints_file:
+        user_hints = _validate_hints(json.loads(Path(args.hints_file).read_text(encoding="utf-8")))
+
+    # Auto-hints: derived from log.md timestamps + glossary cross-references.
+    # User-supplied hints win on the same entry — user signals are explicit
+    # judgment calls and shouldn't be silently overridden by heuristics.
+    if args.auto_hints:
+        auto = _compute_auto_hints(
+            files, paths, stale_threshold_days=args.stale_after_days,
+        )
+    else:
+        auto = {}
+    hints = dict(auto)
+    hints.update(user_hints)
+
+    proposals = []
+    if args.proposals_json:
+        proposals = _validate_proposals(json.loads(args.proposals_json))
+    elif args.proposals_file:
+        proposals = _validate_proposals(json.loads(Path(args.proposals_file).read_text(encoding="utf-8")))
+
+    scope_meta = {
+        "repo_root": str(repo_root),
+        "repo_key": repo_key,
+        "branch": branch_name,
+        "branch_dir": str(branch_dir),
+        "include_repo": include_repo,
+        "generated_at": _now_stamp(),
+    }
+
+    review_dir = branch_dir / "tidy_review"
+    review_dir.mkdir(parents=True, exist_ok=True)
+    out_path = review_dir / f"review_{scope_meta['generated_at']}.html"
+    _render_html(files, hints, proposals, scope_meta, out_path)
+
+    # Build the annotated md mirror — agent reads this single file to recover
+    # entry id + block boundaries without re-parsing the original markdown.
+    blocks_by_fs, flat_blocks = _collect_blocks(files)
+    annotated_md_path = review_dir / f"entries_{scope_meta['generated_at']}.annotated.md"
+    _render_annotated_md(files, blocks_by_fs, scope_meta, annotated_md_path)
+
+    entry_index = []
+    for entry_id, f, s, e in _flatten_entries(files):
+        entry_index.append({
+            "id": entry_id,
+            "file": f["label"],
+            "section": s["title"],
+            "text": e["text"],
+            "is_placeholder": e["is_placeholder"],
+        })
+
+    section_index = []
+    for f in files:
+        for s in f["sections"]:
+            section_index.append({
+                "file_key": f["file_key"],
+                "file": f["label"],
+                "section_idx": s["section_idx"],
+                "title": s["title"],
+                "entry_count": len(s["entries"]),
+            })
+
+    hints_summary = {
+        "auto_enabled": bool(args.auto_hints),
+        "stale_after_days": args.stale_after_days,
+        "auto_count": len(auto),
+        "auto_by_label": {
+            label: sum(1 for v in auto.values() if v["label"] == label)
+            for label in sorted({v["label"] for v in auto.values()})
+        } if auto else {},
+        "user_count": len(user_hints),
+        "total_count": len(hints),
+    }
+
+    print(json.dumps({
+        "mode": "prepare",
+        "review_html": str(out_path),
+        "open_url": f"file://{out_path}",
+        "annotated_md": str(annotated_md_path),
+        "annotated_md_open": f"file://{annotated_md_path}",
+        "scope": scope_meta,
+        "hints_summary": hints_summary,
+        "entry_count": len(entry_index),
+        "entries": entry_index,
+        "section_count": len(section_index),
+        "sections": section_index,
+        "block_count": len(flat_blocks),
+        "blocks": flat_blocks,
+        "proposal_count": len(proposals),
+        "next_steps": [
+            "1) Read annotated_md (single Read) to recover entry id + block boundaries + orphan paragraph markers — don't re-read the raw .md files for structure.",
+            "2) Decide semantic 'fixes' to propose. Prefer `delete-block` over per-entry `delete-entries` when removing a full semantic unit (block ids are in `blocks[]`).",
+            "3) Re-run prepare with --proposals-json or --proposals-file to bake proposal cards into the HTML.",
+            "4) Tell the user to open open_url; default each proposal accept/reject; expand to inspect; export plan.json.",
+            "5) When plan.json is downloaded, run: dev-memory-cli tidy apply --plan-file <path>.",
+        ],
+    }, ensure_ascii=False, indent=2))
+    return 0
+
+
+def _backup_scope(branch_dir, paths, include_repo, stamp):
+    """Snapshot every file we may touch into tidy_backup_<stamp>/. Files
+    are stored under the same relative key naming used internally so
+    apply can self-document what was preserved."""
+    backup_dir = branch_dir / f"tidy_backup_{stamp}"
+    backup_dir.mkdir(parents=True, exist_ok=True)
+    saved = []
+    for file_key, path in _scope_paths(paths, include_repo):
+        dest = backup_dir / f"{file_key}.md"
+        shutil.copy2(path, dest)
+        saved.append({"file_key": file_key, "src": str(path), "backup": str(dest)})
+    (backup_dir / "manifest.json").write_text(
+        json.dumps({"saved_at": stamp, "files": saved}, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+    return backup_dir, saved
+
+
+def _apply_actions_to_section(body, entry_actions):
+    """Rewrite a section body so each entry is either kept, removed,
+    or replaced by its `new_text`. entry_actions is keyed by entry_idx.
+    Lines outside top-level bullets pass through unchanged."""
+    lines = body.splitlines()
+    out_blocks = []
+    current_block = []
+    current_idx = -1
+
+    def flush():
+        nonlocal current_block, current_idx
+        if not current_block:
+            return
+        action = entry_actions.get(current_idx, {"action": "keep"})
+        kind = action.get("action", "keep")
+        if kind == "delete":
+            pass
+        elif kind == "edit":
+            new_text = (action.get("new_text") or "").strip()
+            if new_text:
+                # Render edited text as a fresh bullet, splitting on
+                # newlines so multi-line edits stay a single entry with
+                # continuation lines indented to depth 2.
+                first, *rest = new_text.split("\n")
+                out_blocks.append("- " + first.strip())
+                for cont in rest:
+                    out_blocks.append("  " + cont.strip())
+        else:
+            out_blocks.extend(current_block)
+        current_block = []
+        current_idx = -1
+
+    entry_seen = -1
+    for raw in lines:
+        stripped = raw.strip()
+        if stripped.startswith("- "):
+            flush()
+            entry_seen += 1
+            current_idx = entry_seen
+            current_block = [raw]
+        elif current_block and stripped and (raw.startswith("  ") or raw.startswith("\t")):
+            current_block.append(raw)
+        elif not stripped:
+            flush()
+            out_blocks.append(raw)
+        else:
+            # Free-form prose between bullets — leave alone.
+            flush()
+            out_blocks.append(raw)
+    flush()
+
+    # Trim trailing blank lines for a tidy file.
+    while out_blocks and not out_blocks[-1].strip():
+        out_blocks.pop()
+    rebuilt = "\n".join(out_blocks).strip()
+    if not rebuilt:
+        # Section emptied out entirely — leave the placeholder so the
+        # file remains valid and capture's _section_is_placeholder_only
+        # logic can still detect it.
+        return "- 待补充"
+    return rebuilt
+
+
+def _rewrite_file(path, plan_actions_by_section):
+    """For a single file, apply per-section per-entry actions then
+    rewrite the file. Auto-sync blocks pass through untouched."""
+    content = path.read_text(encoding="utf-8")
+    prefix, sections = split_sections(content)
+    new_sections = []
+    for section_idx, (title, body) in enumerate(sections):
+        actions = plan_actions_by_section.get(section_idx)
+        if not actions:
+            new_sections.append((title, body))
+            continue
+        # Preserve auto-sync block: split body at AUTO_START, only tidy
+        # the part before; auto-block goes back as-is.
+        if AUTO_START in body and AUTO_END in body:
+            head_end = body.index(AUTO_START)
+            head = body[:head_end].rstrip()
+            tail = body[head_end:]
+            new_head = _apply_actions_to_section(head, actions)
+            new_body = (new_head + "\n\n" + tail).strip()
+        else:
+            new_body = _apply_actions_to_section(body, actions)
+        new_sections.append((title, new_body))
+    path.write_text(join_sections(prefix, new_sections), encoding="utf-8")
+
+
+def _delete_blocks_from_section(body, block_drops):
+    """Re-parse the section body into blocks (source of truth at apply
+    time — block_idx from prepare is informational) and drop the listed
+    block indices, returning the rewritten body. Block deletion takes the
+    block's full raw_lines: top-level bullet + any sub-bullets + absorbed
+    orphan paragraphs.
+
+    `block_drops` is a mapping `{block_idx: expected_content_hash | None}`.
+    A non-None hash is compared against the live block's hash after
+    re-parsing; mismatch lands in the invalid list with reason
+    `content_hash_mismatch` and the block is NOT deleted. None skips the
+    content check (back-compat for plans written before the guard existed).
+
+    Returns (rebuilt_body, invalid_entries) where each invalid entry is a
+    dict with at least `block_idx` and `reason`; mismatches also include
+    `expected` and `actual` hash fields for debugging.
+    """
+    blocks = _parse_blocks(body)
+    invalid = []
+    drop = set()
+    for bidx, expected_hash in block_drops.items():
+        if not (0 <= bidx < len(blocks)):
+            invalid.append({
+                "block_idx": bidx,
+                "reason": "block_idx out of range after re-parse",
+            })
+            continue
+        if expected_hash is not None:
+            actual_hash = _block_content_hash(blocks[bidx]["raw_lines"])
+            if actual_hash != expected_hash:
+                invalid.append({
+                    "block_idx": bidx,
+                    "reason": "content_hash_mismatch",
+                    "expected": expected_hash,
+                    "actual": actual_hash,
+                })
+                continue
+        drop.add(bidx)
+
+    # Strategy: replay the original body line-by-line, skipping lines that
+    # belong to a dropped block. Because raw_lines is captured verbatim
+    # from the body during parsing, we can identify the lines by their
+    # position within the body.
+    #
+    # _parse_blocks consumes lines in order; rebuild by walking the same
+    # loop and emitting lines for kept blocks only.
+    lines = body.splitlines()
+    # Re-derive line ownership: walk lines and mark which (if any) block
+    # each line ends up in, using the same logic as _parse_blocks. To
+    # avoid duplicating that logic, fall back to a simpler approach —
+    # re-walk lines and check membership against block raw_lines by index
+    # within the body.
+    #
+    # Trick: every raw line in a block's raw_lines is a verbatim slice of
+    # the original lines list in order. Concatenate kept blocks' raw_lines
+    # plus an explicit blank between them.
+    kept_blocks = [b for i, b in enumerate(blocks) if i not in drop]
+    if not kept_blocks:
+        # Section emptied — preserve any pre-bullet prose if present, else
+        # fall back to the placeholder so capture's
+        # _section_is_placeholder_only still detects it.
+        prefix_lines = []
+        for raw in lines:
+            stripped = raw.strip()
+            if stripped.startswith("- ") and not (raw.startswith(" ") or raw.startswith("\t")):
+                break
+            prefix_lines.append(raw)
+        while prefix_lines and not prefix_lines[-1].strip():
+            prefix_lines.pop()
+        rebuilt = "\n".join(prefix_lines).strip()
+        return (rebuilt + "\n\n- 待补充").strip() if rebuilt else "- 待补充", invalid
+
+    # Walk original lines, emit only those belonging to kept blocks or to
+    # the pre-bullet prefix. To know "belongs to a kept block", track block
+    # boundaries by replaying the parser inline.
+    keep_idx_set = {i for i in range(len(blocks)) if i not in drop}
+    out_lines = []
+    cur_block_idx = -1  # which block index we're currently inside (-1 = prefix)
+    pending_blank = False
+    in_block = False
+    saw_first_bullet = False
+
+    # Helper: emit prefix lines (before any bullet).
+    for raw in lines:
+        stripped = raw.strip()
+        if not saw_first_bullet:
+            # Prefix region — emit until we hit the first top-level bullet.
+            if stripped.startswith("- ") and not (raw.startswith(" ") or raw.startswith("\t")):
+                saw_first_bullet = True
+                cur_block_idx = 0
+                if cur_block_idx in keep_idx_set:
+                    out_lines.append(raw)
+                    in_block = True
+                else:
+                    in_block = False
+                continue
+            out_lines.append(raw)
+            continue
+
+        # We're past the first bullet — emit only if current block is kept.
+        if stripped.startswith("- ") and not (raw.startswith(" ") or raw.startswith("\t")):
+            # New top-level bullet → advance block idx.
+            cur_block_idx += 1
+            in_block = cur_block_idx in keep_idx_set
+            if in_block:
+                # If pending_blank was set inside a kept context, emit it now.
+                out_lines.append(raw)
+            pending_blank = False
+            continue
+
+        if not stripped:
+            # Blank line: emit if we're inside a kept block — but mark
+            # pending so we drop it if the block ends and goes elsewhere.
+            if in_block:
+                out_lines.append(raw)
+            continue
+
+        if in_block:
+            out_lines.append(raw)
+        # else: drop — line belongs to a deleted block (sub-bullet, orphan
+        # paragraph, etc.).
+
+    # Trim trailing blanks.
+    while out_lines and not out_lines[-1].strip():
+        out_lines.pop()
+    rebuilt = "\n".join(out_lines).strip()
+    if not rebuilt:
+        return "- 待补充", invalid
+    return rebuilt, invalid
+
+
+def _rewrite_file_delete_blocks(path, blocks_by_section):
+    """Apply delete-block actions to a single file. blocks_by_section is
+    {section_idx: {block_idx: expected_content_hash | None}}. Returns a list
+    of invalid entries (block_idx out of range, or content_hash drift) —
+    each entry is a dict the caller annotates with file_key + section_idx
+    before surfacing to the user."""
+    content = path.read_text(encoding="utf-8")
+    prefix, sections = split_sections(content)
+    invalid_all = []
+    new_sections = []
+    for section_idx, (title, body) in enumerate(sections):
+        drops = blocks_by_section.get(section_idx)
+        if not drops:
+            new_sections.append((title, body))
+            continue
+        if AUTO_START in body and AUTO_END in body:
+            head_end = body.index(AUTO_START)
+            head = body[:head_end].rstrip()
+            tail = body[head_end:]
+            new_head, invalid = _delete_blocks_from_section(head, drops)
+            new_body = (new_head + "\n\n" + tail).strip()
+        else:
+            new_body, invalid = _delete_blocks_from_section(body, drops)
+        for entry in invalid:
+            entry["section_idx"] = section_idx
+            invalid_all.append(entry)
+        new_sections.append((title, new_body))
+    path.write_text(join_sections(prefix, new_sections), encoding="utf-8")
+    return invalid_all
+
+
+def _delete_sections(path, section_indices):
+    """Drop the listed top-level (`## `) sections from a file."""
+    content = path.read_text(encoding="utf-8")
+    prefix, sections = split_sections(content)
+    drop = set(section_indices)
+    kept = [(t, b) for i, (t, b) in enumerate(sections) if i not in drop]
+    path.write_text(join_sections(prefix, kept), encoding="utf-8")
+
+
+def _reset_file(path, file_key, branch_name, repo_name):
+    body = _template_for(file_key, branch_name, repo_name)
+    if body is None:
+        raise ValueError(f"no v2 template registered for file_key {file_key!r}")
+    path.write_text(body, encoding="utf-8")
+
+
+def command_apply(args):
+    repo_root, branch_name, branch_key, storage_root, repo_key, repo_dir, branch_dir, paths = ensure_branch_paths_exist(
+        args.repo, args.context_dir, args.branch
+    )
+
+    plan = json.loads(Path(args.plan_file).read_text(encoding="utf-8"))
+    actions = plan.get("actions") or []
+    include_repo = (plan.get("scope") or {}).get("include_repo", False)
+
+    # Bucket the actions:
+    #   reset_files  : file_keys to fully reset (highest precedence)
+    #   delete_sections: file_key -> set(section_idx)
+    #   delete_blocks: file_key -> section_idx -> set(block_idx)
+    #   entry_actions: file_key -> section_idx -> entry_idx -> {action, new_text}
+    reset_files = set()
+    delete_sections = {}
+    delete_blocks = {}
+    entry_actions = {}
+    invalid = []
+
+    for item in actions:
+        # New action types use a "type" field; legacy entry-level actions
+        # use "id" + "action". Distinguish by which key is present.
+        atype = (item.get("type") or "").strip()
+        if atype:
+            if atype == "reset-file":
+                fk = item.get("file_key", "")
+                if fk not in paths:
+                    invalid.append({"action": item, "reason": f"unknown file_key {fk!r}"})
+                    continue
+                reset_files.add(fk)
+                continue
+            if atype == "delete-section":
+                fk = item.get("file_key", "")
+                if fk not in paths:
+                    invalid.append({"action": item, "reason": f"unknown file_key {fk!r}"})
+                    continue
+                try:
+                    sidx = int(item.get("section_idx"))
+                except (TypeError, ValueError):
+                    invalid.append({"action": item, "reason": "section_idx must be int"})
+                    continue
+                delete_sections.setdefault(fk, set()).add(sidx)
+                continue
+            if atype == "delete-block":
+                bid = (item.get("block_id") or "").strip()
+                parsed = _parse_block_id(bid)
+                if parsed is None:
+                    invalid.append({"action": item, "reason": f"malformed block_id {bid!r}"})
+                    continue
+                fk, sidx, bidx = parsed
+                if fk not in paths:
+                    invalid.append({"action": item, "reason": f"unknown file_key {fk!r}"})
+                    continue
+                # Optional content fingerprint — recorded by prepare and copied
+                # verbatim by the agent. None means "skip the content check"
+                # (back-compat with plans authored before this guard existed).
+                ech = item.get("expected_content_hash")
+                if ech is not None and not isinstance(ech, str):
+                    invalid.append({
+                        "action": item,
+                        "reason": "expected_content_hash must be a string if provided",
+                    })
+                    continue
+                # If the same block id appears twice with different expected
+                # hashes, the last write wins — that's fine for practical use
+                # (agent should never emit two delete-block actions on the
+                # same id; if they do, both want the block gone anyway).
+                delete_blocks.setdefault(fk, {}).setdefault(sidx, {})[bidx] = ech
+                continue
+            if atype in ("delete-entries", "edit-entries"):
+                # Either form expands to a list of {id, action[, new_text]}.
+                ids = item.get("ids") or []
+                edits = item.get("edits") or []
+                pairs = [(i, "delete", None) for i in ids] + [
+                    (e.get("id"), "edit", e.get("new_text")) for e in edits
+                ]
+                for eid, kind, new_text in pairs:
+                    parsed = _parse_entry_id(eid)
+                    if not parsed:
+                        invalid.append({"id": eid, "reason": "malformed id"})
+                        continue
+                    fk, sidx, eidx = parsed
+                    if fk not in paths:
+                        invalid.append({"id": eid, "reason": f"unknown file_key {fk!r}"})
+                        continue
+                    entry_actions.setdefault(fk, {}).setdefault(sidx, {})[eidx] = {
+                        "action": kind,
+                        "new_text": new_text,
+                    }
+                continue
+            invalid.append({"action": item, "reason": f"unknown type {atype!r}"})
+            continue
+
+        # Legacy entry-level form.
+        eid = item.get("id") or ""
+        kind = (item.get("action") or "").strip().lower()
+        if kind not in VALID_ENTRY_ACTIONS:
+            invalid.append({"id": eid, "reason": f"unknown action {kind!r}"})
+            continue
+        parsed = _parse_entry_id(eid)
+        if not parsed:
+            invalid.append({"id": eid, "reason": "malformed id"})
+            continue
+        fk, sidx, eidx = parsed
+        if fk not in paths:
+            invalid.append({"id": eid, "reason": f"unknown file_key {fk!r}"})
+            continue
+        if kind == "keep":
+            continue
+        entry_actions.setdefault(fk, {}).setdefault(sidx, {})[eidx] = {
+            "action": kind,
+            "new_text": item.get("new_text"),
+        }
+
+    stamp = _now_stamp()
+    backup_dir, _ = _backup_scope(branch_dir, paths, include_repo, stamp)
+
+    rewritten = []
+    # Apply reset-file first (other ops on the same file are then redundant).
+    for fk in reset_files:
+        path = paths[fk]
+        try:
+            _reset_file(path, fk, branch_name, repo_key.rsplit("-", 1)[0])
+            rewritten.append({"file_key": fk, "path": str(path), "op": "reset-file"})
+        except Exception as exc:
+            invalid.append({"file_key": fk, "op": "reset-file", "reason": str(exc)})
+        # Drop any other ops queued for this file — reset wins.
+        delete_sections.pop(fk, None)
+        delete_blocks.pop(fk, None)
+        entry_actions.pop(fk, None)
+
+    # Then delete-section per file (one rewrite per file).
+    for fk, sidx_set in delete_sections.items():
+        path = paths.get(fk)
+        if not path or not path.exists():
+            invalid.append({"file_key": fk, "op": "delete-section", "reason": "file missing"})
+            continue
+        _delete_sections(path, sidx_set)
+        rewritten.append({"file_key": fk, "path": str(path), "op": f"delete-sections:{sorted(sidx_set)}"})
+        # Block / entry actions targeting these sections are no-ops; prune.
+        if fk in delete_blocks:
+            for sidx in sidx_set:
+                delete_blocks[fk].pop(sidx, None)
+            if not delete_blocks[fk]:
+                delete_blocks.pop(fk, None)
+        if fk in entry_actions:
+            for sidx in sidx_set:
+                entry_actions[fk].pop(sidx, None)
+            if not entry_actions[fk]:
+                entry_actions.pop(fk, None)
+
+    # Then delete-block per file. We re-parse blocks at apply time (prepare's
+    # block_idx is informational); out-of-range block ids or content-hash
+    # mismatches land in `invalid`. Also prune entry-actions that would fall
+    # inside a deleted block so we don't double-touch lines that are already
+    # gone.
+    for fk, sec_blocks in delete_blocks.items():
+        path = paths.get(fk)
+        if not path or not path.exists():
+            invalid.append({"file_key": fk, "op": "delete-block", "reason": "file missing"})
+            continue
+        # Prune entry-actions that fall inside doomed blocks before we delete.
+        # sec_blocks values are now `{block_idx: expected_hash | None}` dicts;
+        # we just need the block_idx keys for the pruning step.
+        if fk in entry_actions:
+            content = path.read_text(encoding="utf-8")
+            _, sections = split_sections(content)
+            for sidx, bidx_map in sec_blocks.items():
+                if sidx >= len(sections):
+                    continue
+                body = sections[sidx][1]
+                cleaned = _strip_auto_block(body)
+                blks = _parse_blocks(cleaned)
+                doomed_entry_idx = set()
+                for bidx in bidx_map:
+                    if 0 <= bidx < len(blks):
+                        s, e = blks[bidx]["entry_idx_range"]
+                        for k in range(s, e + 1):
+                            doomed_entry_idx.add(k)
+                if sidx in entry_actions[fk]:
+                    for k in list(entry_actions[fk][sidx].keys()):
+                        if k in doomed_entry_idx:
+                            entry_actions[fk][sidx].pop(k, None)
+                    if not entry_actions[fk][sidx]:
+                        entry_actions[fk].pop(sidx, None)
+            if not entry_actions[fk]:
+                entry_actions.pop(fk, None)
+        invalid_blocks = _rewrite_file_delete_blocks(path, sec_blocks)
+        for entry in invalid_blocks:
+            invalid.append({
+                "op": "delete-block",
+                "file_key": fk,
+                **entry,
+            })
+        rewritten.append({
+            "file_key": fk,
+            "path": str(path),
+            "op": f"delete-blocks:{ {k: sorted(v.keys()) for k, v in sec_blocks.items()} }",
+        })
+
+    # Finally entry-level actions.
+    for fk, sec_actions in entry_actions.items():
+        path = paths.get(fk)
+        if not path or not path.exists():
+            invalid.append({"file_key": fk, "reason": "file missing at apply time"})
+            continue
+        _rewrite_file(path, sec_actions)
+        rewritten.append({"file_key": fk, "path": str(path), "op": "entry-actions"})
+
+    accepted = plan.get("accepted_proposals") or []
+    rejected = plan.get("rejected_proposals") or []
+    custom = plan.get("custom_proposals") or []
+
+    summary_path = branch_dir / "tidy_review" / f"summary_{stamp}.md"
+    summary_path.parent.mkdir(parents=True, exist_ok=True)
+    summary_lines = [
+        f"# Tidy summary {stamp}",
+        "",
+        f"- branch: `{branch_name}`",
+        f"- include_repo: `{include_repo}`",
+        f"- backup: `{backup_dir}`",
+        f"- accepted proposals: {len(accepted)}",
+        f"- rejected proposals: {len(rejected)}",
+        f"- custom proposals: {len(custom)}",
+        f"- actions applied: {len(actions)}",
+        f"- files rewritten: {len(rewritten)}",
+        f"- invalid items: {len(invalid)}",
+    ]
+    if plan.get("notes"):
+        summary_lines += ["", "## notes", "", plan["notes"]]
+    if rewritten:
+        summary_lines += ["", "## rewritten", ""]
+        summary_lines += [f"- {r['file_key']} ({r['op']})" for r in rewritten]
+    if custom:
+        summary_lines += [
+            "",
+            "## custom proposals (NOT applied — agent must read user feedback and re-propose)",
+            "",
+        ]
+        for c in custom:
+            pid = c.get("proposal_id") or c.get("id") or "?"
+            fb = (c.get("user_feedback") or "").strip()
+            summary_lines += [f"### {pid}", "", fb or "(empty feedback)", ""]
+    if invalid:
+        summary_lines += ["", "## invalid", ""]
+        summary_lines += [f"- {json.dumps(v, ensure_ascii=False)}" for v in invalid]
+    summary_path.write_text("\n".join(summary_lines) + "\n", encoding="utf-8")
+
+    # Event log: one row per apply. Mirror to repo_log if any rewritten file
+    # lives at the repo-shared layer (include_repo plan touched repo_*).
+    touches_repo = any(r["file_key"].startswith("repo_") for r in rewritten)
+    log_details = [
+        ("accepted", len(accepted)),
+        ("rejected", len(rejected)),
+        ("custom", len(custom)),
+        ("rewritten", len(rewritten)),
+        ("invalid", len(invalid)),
+        ("backup", backup_dir.name),
+    ]
+    log_summary = (
+        f"accepted={len(accepted)} rewritten={len(rewritten)}"
+        if rewritten or accepted else "no-op"
+    )
+    append_log_event(
+        paths.get("log"),
+        "tidy",
+        kind="apply",
+        summary=log_summary,
+        details=log_details,
+    )
+    if touches_repo and paths.get("repo_log") and paths.get("repo_log") != paths.get("log"):
+        append_log_event(
+            paths.get("repo_log"),
+            "tidy",
+            kind="apply",
+            summary=log_summary,
+            details=log_details,
+        )
+
+    print(json.dumps({
+        "mode": "apply",
+        "branch": branch_name,
+        "branch_dir": str(branch_dir),
+        "backup_dir": str(backup_dir),
+        "accepted_proposals": accepted,
+        "rejected_proposals": rejected,
+        "custom_proposals": custom,
+        "rewritten": rewritten,
+        "invalid": invalid,
+        "summary": str(summary_path),
+        "actions_count": len(actions),
+        "next_steps": (
+            [
+                "Read each custom_proposals user_feedback and decide how to handle it based on the content. "
+                "It is NOT automatic 're-run prepare' — depending on the feedback you may: act inline (capture/tidy subcommand), "
+                "ask the user to clarify, defer with a note, or only when the feedback genuinely calls for "
+                "fresh proposals run another `tidy prepare --proposals-file <revised>`."
+            ]
+            if custom else []
+        ),
+    }, ensure_ascii=False, indent=2))
+    return 0
+
+
+def _parse_entry_id(eid):
+    """Return (file_key, section_idx, entry_idx) or None on bad input."""
+    if not isinstance(eid, str):
+        return None
+    parts = eid.split("::")
+    if len(parts) != 3:
+        return None
+    try:
+        return parts[0], int(parts[1]), int(parts[2])
+    except ValueError:
+        return None
+
+
+def _add_common_args(p):
+    p.add_argument("--repo", default=".", help="Path inside the target Git repository")
+    p.add_argument("--context-dir", help="User-home storage root. Defaults to ~/.dev-memory/repos")
+    p.add_argument("--branch", help="Branch name. Defaults to the current checked-out branch")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Review and tidy existing dev-memory memory entries.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_prep = sub.add_parser("prepare", help="Scan scope, render review.html (with optional hints + proposals)")
+    _add_common_args(p_prep)
+    p_prep.add_argument("--scope", choices=("branch", "branch+repo"), default="branch")
+    hint_group = p_prep.add_mutually_exclusive_group()
+    hint_group.add_argument("--hints-json", help="Inline JSON object keyed by entry id with {label, reason}")
+    hint_group.add_argument("--hints-file", help="Path to JSON file with the same shape as --hints-json")
+    p_prep.add_argument(
+        "--no-auto-hints",
+        dest="auto_hints",
+        action="store_false",
+        help="Skip the built-in STALE-by-log + ORPHAN-glossary hint passes",
+    )
+    p_prep.add_argument(
+        "--stale-after-days",
+        type=int,
+        default=AUTO_STALE_THRESHOLD_DAYS,
+        help=f"Auto-hint STALE for files last seen in log >= this many days ago (default {AUTO_STALE_THRESHOLD_DAYS})",
+    )
+    p_prep.set_defaults(auto_hints=True)
+    proposal_group = p_prep.add_mutually_exclusive_group()
+    proposal_group.add_argument(
+        "--proposals-json",
+        help="Inline JSON array of proposals: [{id, title, reason, actions:[...]}]. "
+             "Action types: delete-entries (ids:[...]), delete-section (file_key, section_idx), "
+             "delete-block (block_id), reset-file (file_key), edit-entries (edits:[{id, new_text}]).",
+    )
+    proposal_group.add_argument("--proposals-file", help="Path to JSON file with the same shape as --proposals-json")
+
+    p_apply = sub.add_parser("apply", help="Apply a downloaded plan.json (with backup snapshot)")
+    _add_common_args(p_apply)
+    p_apply.add_argument("--plan-file", required=True)
+
+    args = parser.parse_args()
+    try:
+        return {
+            "prepare": command_prepare,
+            "apply": command_apply,
+        }[args.command](args)
+    except Exception as exc:
+        print(json.dumps({"error": str(exc)}, ensure_ascii=False), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())