cc-session-tools 2.8.0__tar.gz → 2.8.2__tar.gz

{cc_session_tools-2.8.0/src/cc_session_tools.egg-info → cc_session_tools-2.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 2.8.0
+Version: 2.8.2
 Summary: Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (cccs_hooks)
 Author: raffishquartan
 License: MIT License

{cc_session_tools-2.8.0 → cc_session_tools-2.8.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-session-tools"
-version = "2.8.0"
+version = "2.8.2"
 description = "Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (cccs_hooks)"
 readme = "README.md"
 license = { file = "LICENSE" }

{cc_session_tools-2.8.0 → cc_session_tools-2.8.2}/src/cc_session_tools/cli/ccst.py

@@ -137,9 +137,18 @@ def _discover_prompts_dir() -> Path:
     )
 
 
-def _print_migration_prompt_reminders(*labeled_filenames: tuple[str, str]) -> None:
+def _print_migration_prompt_reminders(
+    project_root: Path, *labeled_filenames: tuple[str, str]
+) -> None:
     """Print one "<label>: <path>" reminder line per (label, filename) pair, for the bundled
-    prompts/ directory.
+    prompts/ directory, followed by a line telling the user to run it in a fresh Claude Code
+    session started in project_root.
+
+    Each prompt's own "Run it via" section already spells out the `cd <project> && claude -p
+    ...` invocation (see e.g. pdata-migration-skills-update.md) - that only works if the
+    session's cwd is the project root, since every prompt's Step 1 checks for it and aborts
+    otherwise. Printing the reminder without saying so reads as "open this file", which invites
+    running it inline in whatever session called `ccst pdata init` - the wrong cwd entirely.
 
     Best-effort, deliberately swallowing a missing prompts/ directory: these reminders are a
     nicety layered on top of an otherwise-already-completed classification or migration, not
@@ -154,6 +163,10 @@ def _print_migration_prompt_reminders(*labeled_filenames: tuple[str, str]) -> No
         return
     for label, filename in labeled_filenames:
         print(f"{label}: {prompts_dir / filename}")
+        print(
+            f"  Run in a new Claude Code session started in {project_root} (its own "
+            f"\"Run it via\" section has the exact command) - not in this session."
+        )
 
 
 # ---------- skills install ----------
@@ -875,14 +888,19 @@ def _cmd_gc_report(args: argparse.Namespace) -> int:
 # ---------- pdata ----------
 
 
-def _parse_field_assignment(raw: str) -> tuple[str, str]:
-    """Parse "k=v" into (k, v). Raises ValueError on malformed input."""
+def _parse_field_assignment(raw: str) -> tuple[str, str | None]:
+    """Parse "k=v" into (k, v). The literal token `null` (unquoted, lowercase) is interpreted
+    as SQL NULL rather than the four-character string "null" - this is the documented way to
+    clear/unset a field via --field (see check-tesco-shop-due's SKILL.md for a real caller that
+    relies on it). A field genuinely needing to store the text "null" cannot be written via
+    --field; there's no escape hatch for that case since --field has no quoting syntax at all.
+    Raises ValueError on malformed input."""
     if "=" not in raw:
         raise ValueError(f"malformed --field assignment (want name=value): {raw!r}")
     name, value = raw.split("=", 1)
     if not name:
         raise ValueError(f"malformed --field assignment (want name=value): {raw!r}")
-    return name, value
+    return name, (None if value == "null" else value)
 
 
 def _cmd_pdata_add(args: argparse.Namespace) -> int:
@@ -1091,6 +1109,7 @@ def _cmd_pdata_init(args: argparse.Namespace) -> int:
         print(result.report)
         print(f"\nProposal: {result.proposal_path}")
         _print_migration_prompt_reminders(
+            result.proposal_path.parent,
             ("After a successful --write, update project docs", "pdata-migration-claude-md-update.md"),
         )
         return 0
@@ -1129,6 +1148,7 @@ def _cmd_pdata_init(args: argparse.Namespace) -> int:
         print(write_result.report)  # spec §7.1 step 4's diff report, for review
         print(f"\nVerify: ccst pdata verify --project {args.project} --full")
         _print_migration_prompt_reminders(
+            project_root,
             ("Update project docs", "pdata-migration-claude-md-update.md"),
             ("Update consuming skills", "pdata-migration-skills-update.md"),
         )
@@ -1136,6 +1156,67 @@ def _cmd_pdata_init(args: argparse.Namespace) -> int:
         return 0
 
 
+def _cmd_pdata_reorganize(args: argparse.Namespace) -> int:
+    from cc_session_tools.lib.pdata import init_paths, reorganize, write_log
+
+    try:
+        project_root = init_paths.resolve_project_root(args.project, rehearse=None)
+    except ValueError as exc:
+        # Matches _cmd_pdata_init's own handling of the identical resolve_project_root() call -
+        # a bad --project name (e.g. containing '/') must give the same clean exit-2 message
+        # every other pdata command gives, not an uncaught traceback.
+        print(f"ccst pdata: {exc}", file=sys.stderr)
+        return 2
+
+    if not args.write:
+        try:
+            plan = reorganize.dry_run(
+                project=args.project, project_root=project_root,
+                folder=args.folder, strategy=args.strategy,
+            )
+        except (FileNotFoundError, ValueError) as exc:
+            print(f"ccst pdata: {exc}", file=sys.stderr)
+            return 2
+        for move in plan.moves:
+            print(f"{move.old_relative} -> {move.new_relative}")
+        for matched in plan.matched_records:
+            print(f"  pdata record {matched.record.id} (group={matched.record.record_group}): "
+                  f"file_path -> {matched.new_file_path}")
+        for ref in plan.external_references:
+            print(f"  external reference: {ref.file}:{ref.line_number}: {ref.line_text}")
+        if not plan.moves:
+            print(f"no files found directly under {args.folder}/")
+        return 0
+
+    # --write can move many files over a long-running, potentially flaky I/O path - durably
+    # logged the same way `ccst pdata init --write` is, under this operation's own filename so
+    # the two never truncate each other's log (see reorganize.REORGANIZE_WRITE_LOG_FILENAME).
+    with write_log.WriteLog(project_root, log_filename=reorganize.REORGANIZE_WRITE_LOG_FILENAME):
+        try:
+            result = reorganize.write(
+                project=args.project, project_root=project_root,
+                folder=args.folder, strategy=args.strategy,
+            )
+        except (FileNotFoundError, ValueError) as exc:
+            print(f"ccst pdata: {exc}", file=sys.stderr)
+            print(f"ERROR: {exc}")
+            return 2
+
+        if result.failure is not None:
+            print("ccst pdata reorganize: failed, rolled back:", file=sys.stderr)
+            for reason in result.failure.reasons:
+                print(f"  - {reason}", file=sys.stderr)
+            print(f"ERROR: failed, rolled back ({len(result.failure.reasons)} reason(s))")
+            return 1
+
+        print(f"Moved {len(result.plan.moves)} file(s) under {args.folder}/")
+        print(f"Backup: {result.backup_path}")
+        for ref in result.plan.external_references:
+            print(f"  still needs manual review: {ref.file}:{ref.line_number}: {ref.line_text}")
+        print("SUCCESS")
+        return 0
+
+
 def _cmd_pdata_reconcile_session_output(args: argparse.Namespace) -> int:
     from cc_session_tools.lib import roots
     from cc_session_tools.lib.pdata import session_output
@@ -2038,7 +2119,8 @@ def _build_parser() -> argparse.ArgumentParser:
     pdata_add_parser.add_argument(
         "--field", action="append", default=[], metavar="NAME=VALUE",
         help="Extension field assignment; may repeat. Field must already be registered via "
-             "'ccst pdata schema add-field'.",
+             "'ccst pdata schema add-field'. VALUE of the literal token 'null' sets SQL NULL "
+             "rather than the string \"null\".",
     )
 
     pdata_schema_parser = pdata_sub.add_parser("schema", help="Schema discovery and evolution")
@@ -2107,13 +2189,19 @@ def _build_parser() -> argparse.ArgumentParser:
     pdata_update_parser.add_argument(
         "--content", default=None,
         help="New content. Omit to leave content unchanged (at least one of --content, "
-             "--file, --field is required)",
+             "--file, --field is required). Never re-derived from --field - if a record's "
+             "content is meant to mirror its fields, pass a matching --content on every "
+             "--field update yourself.",
     )
     pdata_update_parser.add_argument(
         "--file", default=None, metavar="PATH",
         help="New relative file path. Omit to leave the existing file_path unchanged.",
     )
-    pdata_update_parser.add_argument("--field", action="append", default=[], metavar="NAME=VALUE")
+    pdata_update_parser.add_argument(
+        "--field", action="append", default=[], metavar="NAME=VALUE",
+        help="Extension field assignment; may repeat. Never updates content (see --content). "
+             "VALUE of the literal token 'null' sets SQL NULL rather than the string \"null\".",
+    )
     pdata_update_parser.add_argument(
         "--format", choices=("table", "json"), default="table",
         help="Format used only for the conflict diff on a version mismatch",
@@ -2146,6 +2234,19 @@ def _build_parser() -> argparse.ArgumentParser:
         ),
     )
 
+    pdata_reorganize_parser = pdata_sub.add_parser(
+        "reorganize", help="Split a flat folder into a nested (by-year or by-year-month) structure"
+    )
+    pdata_reorganize_parser.add_argument("--project", required=True, metavar="NAME")
+    pdata_reorganize_parser.add_argument("--folder", required=True, metavar="RELATIVE_PATH")
+    pdata_reorganize_parser.add_argument(
+        "--strategy", required=True, choices=("by-year", "by-year-month"),
+    )
+    pdata_reorganize_parser.add_argument(
+        "--write", action="store_true",
+        help="Perform the move and update matching pdata records (default: dry-run only)",
+    )
+
     pdata_reconcile_parser = pdata_sub.add_parser(
         "reconcile-session-output",
         help="Backfill the session-output index from cc-sessions/*/out/ on disk (idempotent)",
@@ -2450,6 +2551,8 @@ def main() -> None:
             sys.exit(_cmd_pdata_restore(args))
         if args.verb == "init":
             sys.exit(_cmd_pdata_init(args))
+        if args.verb == "reorganize":
+            sys.exit(_cmd_pdata_reorganize(args))
         if args.verb == "reconcile-session-output":
             sys.exit(_cmd_pdata_reconcile_session_output(args))
         if args.verb == "verify":

cc_session_tools-2.8.2/src/cc_session_tools/lib/pdata/reorganize.py

@@ -0,0 +1,367 @@
+"""Flat-to-nested folder restructuring for `ccst pdata reorganize` (design spec
+2026-08-21-pm-project-layout-reference-design.md, §3). Scoped to exactly one operation:
+splitting a flat folder into year or year/month subfolders once it's grown past the
+`pm-project-layout-reference` skill's 500-file guidance - not general-purpose reorganisation.
+
+dry_run() never touches the filesystem or the database; write() (a later task) performs the
+moves and DB updates dry_run() planned, reusing backup.create_backup() as its safety net
+exactly the way `ccst pdata init --write` does.
+"""
+from __future__ import annotations
+
+import re
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from cc_session_tools.lib.pdata import backup, init_paths, service
+from cc_session_tools.lib.pdata.init_paths import PROPOSAL_FILENAME
+from cc_session_tools.lib.pdata.service import Record
+from cc_session_tools.lib.pdata.write_log import LOG_FILENAME as WRITE_LOG_FILENAME
+
+_LEADING_DATE_RE = re.compile(r"^(?P<year>\d{4})\.(?P<month>\d{2})\.(?P<day>\d{2})-")
+
+_STRATEGIES = frozenset({"by-year", "by-year-month"})
+
+# This operation's own durable per-run log (mirrors ccst-pdata-init-write.log, but under its
+# own name so a reorganize run never truncates - or gets excluded/included alongside - an
+# unrelated pdata init run's log). Named here, not in write_log.py, since it's this module's
+# own concern; the CLI layer imports it to pass to write_log.WriteLog(log_filename=...).
+REORGANIZE_WRITE_LOG_FILENAME = "ccst-pdata-reorganize-write.log"
+
+# Filenames excluded from the external-reference scan by name, not just by directory - all
+# three persist at the project root indefinitely (classify.py excludes the first two from
+# classification for the same reason) and can literally contain the file_path of every
+# classified/moved entry, including files under whatever folder is being reorganized. Without
+# this, a project that has ever run `ccst pdata init` or a previous `ccst pdata reorganize`
+# would get a spurious "external reference" hit inside its own bookkeeping every time
+# dry_run() runs.
+_EXCLUDED_FILENAMES = frozenset({
+    PROPOSAL_FILENAME, WRITE_LOG_FILENAME, REORGANIZE_WRITE_LOG_FILENAME,
+})
+
+
+@dataclass(frozen=True, slots=True)
+class Move:
+    old_relative: str
+    new_relative: str
+
+
+@dataclass(frozen=True, slots=True)
+class ExternalReference:
+    file: Path
+    line_number: int
+    line_text: str
+
+
+@dataclass(frozen=True, slots=True)
+class MatchedRecord:
+    record: Record
+    new_file_path: str
+
+
+@dataclass(frozen=True, slots=True)
+class ReorganizePlan:
+    project: str
+    project_root: Path
+    folder: str
+    strategy: str
+    moves: list[Move]
+    matched_records: list[MatchedRecord]
+    external_references: list[ExternalReference]
+
+
+def _year_and_month_for(path: Path) -> tuple[str, str]:
+    """(year, month) for path - from a leading YYYY.MM.DD- date in the filename if present
+    (this codebase's own naming convention, e.g. archive-correspondence's output), else the
+    file's mtime. Shared by _year_for/_year_month_for so the date-vs-mtime decision and the
+    regex match happen exactly once, not twice with the same logic duplicated between them.
+
+    No validation that a regex-matched month is actually 01-12 (or day 01-31) - a malformed
+    but shape-matching date in a filename (e.g. "2025.13.99-foo.md") is accepted at face value.
+    Low-risk for a dry-run/planning tool whose output is reviewed before any --write, but worth
+    knowing if this is ever reused somewhere the plan isn't reviewed first."""
+    match = _LEADING_DATE_RE.match(path.name)
+    if match:
+        return match.group("year"), match.group("month")
+    localtime = time.localtime(path.stat().st_mtime)
+    return time.strftime("%Y", localtime), time.strftime("%m", localtime)
+
+
+def _year_for(path: Path) -> str:
+    year, _month = _year_and_month_for(path)
+    return year
+
+
+def _year_month_for(path: Path) -> str:
+    year, month = _year_and_month_for(path)
+    return f"{year}/{month}"
+
+
+def _new_relative(folder: str, entry: Path, strategy: str) -> str:
+    subdir = _year_for(entry) if strategy == "by-year" else _year_month_for(entry)
+    return f"{folder}/{subdir}/{entry.name}"
+
+
+def _scan_external_references(
+    *, project_root: Path, folder: str, old_relatives: list[str],
+) -> list[ExternalReference]:
+    """Grep every text file in project_root (excluding folder itself and the usual
+    ccst/git bookkeeping dirs) for a literal occurrence of any old_relatives entry - reported
+    only, never edited (design spec §3: rewriting prose isn't safe to automate).
+
+    folder is excluded by path-prefix comparison, not single-component name matching - folder
+    can itself be multi-segment (e.g. "workstreams/ws-01"), which a plain
+    `part in excluded_names` check would never match against any single path component.
+
+    Reuses init_paths.EXCLUDED_DIR_NAMES - the same set classify.py's own directory walk
+    already excludes - rather than hardcoding a second, incomplete copy: a hardcoded
+    ".pdata-migrated" literal here would also miss REHEARSAL_DB_DIRNAME/
+    REHEARSAL_BACKUP_DIRNAME, walking into a rehearsal sandbox's own contents on any project
+    that has ever used --rehearse and reporting spurious matches from inside it."""
+    excluded_dir_names = init_paths.EXCLUDED_DIR_NAMES
+    folder_parts = Path(folder).parts
+    refs: list[ExternalReference] = []
+    for candidate in sorted(project_root.rglob("*")):
+        if not candidate.is_file():
+            continue
+        rel_parts = candidate.relative_to(project_root).parts
+        if rel_parts[:len(folder_parts)] == folder_parts:
+            continue  # inside the folder being reorganized itself
+        if any(part in excluded_dir_names for part in rel_parts[:-1]):
+            continue
+        if candidate.name in _EXCLUDED_FILENAMES:
+            continue  # ccst's own bookkeeping - see _EXCLUDED_FILENAMES's comment
+        try:
+            text = candidate.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError):
+            continue
+        for line_number, line in enumerate(text.splitlines(), start=1):
+            for old_relative in old_relatives:
+                if old_relative in line:
+                    refs.append(ExternalReference(
+                        file=candidate, line_number=line_number, line_text=line.strip(),
+                    ))
+    return refs
+
+
+def _validate_relative_folder(folder: str) -> None:
+    """A separate check from (not a call to) service._validate_relative_file_path - similar in
+    spirit, but folder has two failure modes file_path doesn't need to guard against, since
+    file_path is never joined with mkdir() to build a new directory tree the way folder is here:
+
+    - An absolute path silently discards project_root entirely when joined with `/` (pathlib's
+      own behaviour, not a bug in this code - `Path("/a") / "/etc"` is `Path("/etc")`), and a
+      '..' segment can escape project_root the same way a crafted --file could.
+    - An EMPTY folder ("") makes old_relative/new_relative leading-slash strings
+      (f"{folder}/{name}" -> "/name"), which then trigger the exact same absolute-path escape
+      above once project_root / new_relative is evaluated - so empty must be rejected as its
+      own case, before the absolute-path check ever sees it (an empty string doesn't start with
+      "/", so that check alone wouldn't catch it). A trailing or doubled slash
+      ("correspondence/", "a//b") produces a doubled-slash old_relative/new_relative that no
+      longer matches the single-slash file_path values pdata records and project docs actually
+      use - write() would then silently update zero matching records and report success while
+      every affected record's file_path goes stale, instead of erroring loudly."""
+    if folder.startswith("/"):
+        raise ValueError(f"--folder must be relative to the project root, got absolute path: {folder!r}")
+    segments = folder.split("/")
+    if not folder or any(not segment for segment in segments):
+        raise ValueError(
+            f"--folder must not be empty or contain empty/trailing path segments: {folder!r}"
+        )
+    if any(segment == ".." for segment in segments):
+        raise ValueError(f"--folder must not contain '..' path-traversal segments: {folder!r}")
+
+
+def dry_run(*, project: str, project_root: Path, folder: str, strategy: str) -> ReorganizePlan:
+    if strategy not in _STRATEGIES:
+        raise ValueError(f"unknown strategy {strategy!r} - must be one of {sorted(_STRATEGIES)}")
+    _validate_relative_folder(folder)
+    folder_path = project_root / folder
+    if not folder_path.is_dir():
+        raise FileNotFoundError(f"no such folder to reorganize: {folder_path}")
+
+    entries = sorted(p for p in folder_path.iterdir() if p.is_file())
+    moves = [
+        Move(
+            old_relative=f"{folder}/{entry.name}",
+            new_relative=_new_relative(folder, entry, strategy),
+        )
+        for entry in entries
+    ]
+
+    matched = service.find_records_by_file_path_prefix(project=project, prefix=f"{folder}/")
+    move_by_old = {m.old_relative: m.new_relative for m in moves}
+    matched_records = [
+        MatchedRecord(record=record, new_file_path=move_by_old[record.file_path])
+        for record in matched
+        if record.file_path is not None and record.file_path in move_by_old
+    ]
+
+    external_references = _scan_external_references(
+        project_root=project_root, folder=folder,
+        old_relatives=[m.old_relative for m in moves],
+    )
+
+    return ReorganizePlan(
+        project=project, project_root=project_root, folder=folder, strategy=strategy,
+        moves=moves, matched_records=matched_records, external_references=external_references,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class ReorganizeFailure:
+    reasons: list[str]
+
+
+@dataclass(frozen=True, slots=True)
+class ReorganizeResult:
+    plan: ReorganizePlan
+    backup_path: Path | None
+    failure: ReorganizeFailure | None
+
+
+def _is_git_repo(project_root: Path) -> bool:
+    return (project_root / ".git").exists()
+
+
+def _remove_empty_dirs_up_to(*, start: Path, boundary: Path) -> None:
+    """Remove start and each successive empty parent directory, stopping at (never removing)
+    boundary itself. Shared by _move_file's own failure cleanup and _move_file_back's rollback
+    cleanup - both need to walk back up through however many nesting levels by-year-month left
+    (two - correspondence/2025/06/) without ever deleting the folder being reorganized."""
+    current = start
+    while current != boundary and current.is_dir() and not any(current.iterdir()):
+        current.rmdir()
+        current = current.parent
+
+
+def _first_missing_ancestor(*, start: Path, boundary: Path) -> Path | None:
+    """Walking from start up towards (not including) boundary, the shallowest directory that
+    does not yet exist - exactly the topmost directory `start.mkdir(parents=True)` would
+    actually create. None if start already exists (mkdir would be a complete no-op).
+
+    Used so _move_file's failure-cleanup only ever removes directories its own mkdir call
+    genuinely created, never one that already existed before it - e.g. left over from an
+    earlier partial/crashed run, or present for an unrelated reason. Without this, cleanup
+    would delete any empty directory sitting at the destination path regardless of whether
+    this call was the one that created it."""
+    if start.exists():
+        return None
+    missing = start
+    while missing.parent != boundary and not missing.parent.exists():
+        missing = missing.parent
+    return missing
+
+
+def _move_file(*, project_root: Path, move: Move, folder: str, use_git: bool) -> None:
+    src = project_root / move.old_relative
+    dest = project_root / move.new_relative
+    folder_path = project_root / folder
+    newly_created_root = _first_missing_ancestor(start=dest.parent, boundary=folder_path)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        if use_git:
+            subprocess.run(
+                ["git", "mv", move.old_relative, move.new_relative],
+                cwd=project_root, check=True, capture_output=True, text=True,
+            )
+        else:
+            src.rename(dest)
+    except (OSError, subprocess.CalledProcessError):
+        # The mkdir above may have just created dest.parent (and its own new parents, for
+        # by-year-month) - if the move itself then failed, that directory was never populated
+        # and would otherwise be left behind as debris: write()'s own rollback only knows
+        # about *completed* moves (this one was never added to `moved`), so nothing else
+        # would ever clean it up. newly_created_root is None when dest.parent already existed
+        # before this call (nothing to clean up - it wasn't ours to remove).
+        if newly_created_root is not None:
+            _remove_empty_dirs_up_to(start=dest.parent, boundary=newly_created_root.parent)
+        raise
+
+
+def _move_file_back(*, project_root: Path, move: Move, folder: str, use_git: bool) -> None:
+    """Undo _move_file - used by write()'s rollback path only."""
+    dest_parent = (project_root / move.new_relative).parent
+    if use_git:
+        subprocess.run(
+            ["git", "mv", move.new_relative, move.old_relative],
+            cwd=project_root, check=True, capture_output=True, text=True,
+        )
+    else:
+        (project_root / move.new_relative).rename(project_root / move.old_relative)
+    _remove_empty_dirs_up_to(start=dest_parent, boundary=project_root / folder)
+
+
+def write(*, project: str, project_root: Path, folder: str, strategy: str) -> ReorganizeResult:
+    plan = dry_run(project=project, project_root=project_root, folder=folder, strategy=strategy)
+    use_git = _is_git_repo(project_root)
+
+    # Matches init_service.write()'s own handling of this exact call (init_service.py
+    # ~lines 220-232): create_backup() can exhaust its retries and raise BackupError, which
+    # must become a structured failure here too, not an uncaught crash before anything has
+    # been moved.
+    try:
+        backup_path = backup.create_backup(project=project, project_root=project_root)
+    except backup.BackupError as exc:
+        return ReorganizeResult(plan=plan, backup_path=None, failure=ReorganizeFailure(reasons=[str(exc)]))
+
+    moved: list[Move] = []
+    # (matched, post-update Record incl. its bumped version) for every update_record() call
+    # that succeeded so far - needed to reverse them in the right order on failure, each with
+    # the expected_version its OWN update actually left the row at, not its pre-update version.
+    updated: list[tuple[MatchedRecord, Record]] = []
+    try:
+        for move in plan.moves:
+            _move_file(project_root=project_root, move=move, folder=folder, use_git=use_git)
+            moved.append(move)
+
+        for matched in plan.matched_records:
+            updated_record = service.update_record(
+                project=project, record_id=matched.record.id,
+                expected_version=matched.record.version,
+                content=None, file_path=matched.new_file_path, fields={},
+            )
+            updated.append((matched, updated_record))
+    except (OSError, subprocess.CalledProcessError, service.VersionConflictError,
+            service.RecordNotFoundError) as exc:
+        reasons = [str(exc)]
+        # Roll back each moved file and its matching DB update (if any) as one paired unit,
+        # in reverse order - move the file back FIRST, then revert its record, so the two
+        # can never end up disagreeing about where the file actually is:
+        #   - if the move-back fails, the record is left un-reverted too (still pointing at
+        #     the new path) - consistent, since the file is still physically there.
+        #   - if the move-back succeeds but the reversal update_record() call then fails,
+        #     that's flagged explicitly rather than silently diverging - matched.record is
+        #     filtered upstream (dry_run) to always have a non-None file_path, so the
+        #     reversal always restores a real prior value, never a no-op None.
+        # Each step is wrapped individually, matching init_service._rollback()'s own contract:
+        # an unwrapped raise here would abort the rest of the rollback (and this whole
+        # function) instead of returning a ReorganizeResult at all.
+        updated_by_new_path = {m.new_file_path: (m, r) for m, r in updated}
+        for move in reversed(moved):
+            pair = updated_by_new_path.get(move.new_relative)
+            try:
+                _move_file_back(project_root=project_root, move=move, folder=folder, use_git=use_git)
+            except (OSError, subprocess.CalledProcessError) as rollback_exc:
+                reasons.append(f"{move.new_relative}: rollback failed: {rollback_exc}")
+                continue  # file never moved back - its record (if any) must keep the new path
+            if pair is None:
+                continue
+            matched, updated_record = pair
+            try:
+                service.update_record(
+                    project=project, record_id=matched.record.id,
+                    expected_version=updated_record.version,
+                    content=None, file_path=matched.record.file_path, fields={},
+                )
+            except (service.VersionConflictError, service.RecordNotFoundError) as rollback_exc:
+                reasons.append(f"record {matched.record.id}: rollback failed: {rollback_exc}")
+
+        return ReorganizeResult(
+            plan=plan, backup_path=backup_path,
+            failure=ReorganizeFailure(reasons=reasons),
+        )
+
+    return ReorganizeResult(plan=plan, backup_path=backup_path, failure=None)