cc-session-tools 3.9.2__tar.gz → 3.10.1__tar.gz

{cc_session_tools-3.9.2/src/cc_session_tools.egg-info → cc_session_tools-3.10.1}/PKG-INFO

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

{cc_session_tools-3.9.2 → cc_session_tools-3.10.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-session-tools"
-version = "3.9.2"
+version = "3.10.1"
 description = "Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (hooks package)"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -62,11 +62,11 @@ where = ["src"]
 # only filters within the file's *own* discovered package, and a wrongly
 # auto-discovered "cc_session_tools.skills.<name>.tests" package was never
 # covered by an exclude-package-data entry keyed just "cc_session_tools").
-exclude = ["cc_session_tools.skills", "cc_session_tools.skills.*", "cc_session_tools.config", "cc_session_tools.config.*", "cc_session_tools.prompts", "cc_session_tools.prompts.*"]
+exclude = ["cc_session_tools.skills", "cc_session_tools.skills.*", "cc_session_tools.config", "cc_session_tools.config.*"]
 
 [tool.setuptools.package-data]
 claude_code_usage = ["data/*.json"]
-cc_session_tools = ["skills/**/*", "config/*", "prompts/**/*"]
+cc_session_tools = ["skills/**/*", "config/*"]
 
 [tool.setuptools.exclude-package-data]
 cc_session_tools = ["**/tests/*", "**/__pycache__/*"]

{cc_session_tools-3.9.2 → cc_session_tools-3.10.1}/src/cc_session_tools/cli/ccst.py

@@ -160,56 +160,25 @@ def _discover_bundle() -> Path:
     )
 
 
-def _discover_prompts_dir() -> Path:
-    """Return the bundled prompts/ directory (pdata-migration follow-up prompts).
-
-    prompts/ is packaged inside cc_session_tools the same way skills/ and config/ are (see
-    _discover_source_dir) - src/cc_session_tools/cli/ccst.py -> ../prompts. No install-location
-    fallback, same reasoning as the other two: a fallback here would just mask a broken install.
-    """
-    candidate = Path(__file__).resolve().parent.parent / "prompts"
-    if candidate.is_dir():
-        return candidate
-    raise FileNotFoundError(
-        "Cannot locate bundled prompts/ directory. Run from the source tree or reinstall ccst."
-    )
-
-
-def _print_migration_prompt_reminders(
-    project_root: Path, *labeled_filenames: tuple[str, str]
+def _print_post_migration_skill_reminders(
+    project_root: Path, *labeled_skills: tuple[str, str]
 ) -> None:
-    """Print one "<label>: <path>" reminder line per (label, filename) pair, for the bundled
-    prompts/ directory, followed by a line telling the user to run it in a fresh context (a new
-    Claude Code session, or a dispatched Agent subagent) 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. What the fresh-context requirement is actually protecting against is an
-    orchestrating session rationalizing away a stale reference it half-remembers writing
-    earlier in the same conversation - a dispatched Agent subagent (same cwd) gets that same
-    benefit without shelling out to a literal second process, so both are offered here rather
-    than only the `claude -p` invocation. 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
-    the operation itself — a broken/partial install must never turn a successful --write (rows
-    already written, files already cut over) or dry-run (proposal already written) into a
-    reported failure just because this follow-up reminder couldn't be printed.
+    """Print one "<label>: <skill-name>" reminder per (label, skill) pair, each followed by a
+    line telling the user to run it in a fresh context rooted at project_root.
+
+    Each skill's Step 1 checks that cwd is the project root and aborts otherwise, so a bare skill
+    name invites running it inline in whatever session called `ccst pdata init` - the wrong cwd,
+    and the wrong context: the fresh-context requirement protects against an orchestrating
+    session rationalizing away a stale reference it half-remembers writing earlier in the same
+    conversation. A dispatched Agent subagent whose prompt starts with a `cd` into project_root
+    gets that same benefit as a new Claude Code session, so both are offered.
     """
-    try:
-        prompts_dir = _discover_prompts_dir()
-    except FileNotFoundError as exc:
-        print(f"({exc})", file=sys.stderr)
-        return
-    for label, filename in labeled_filenames:
-        print(f"{label}: {prompts_dir / filename}")
+    for label, skill in labeled_skills:
+        print(f"{label}: {skill}")
         print(
-            f"  Run in a new Claude Code session started in {project_root} (its own "
-            f"\"Run it via\" section has the exact command), or dispatch it as an Agent "
-            f"subagent with the same cwd - not inline in this session."
+            f"  Run it in a fresh context rooted at {project_root}: dispatch an Agent subagent "
+            f"whose prompt starts with `cd {project_root}`, or start a new Claude Code session "
+            f"there - not inline in this session."
         )
 
 
@@ -1236,9 +1205,9 @@ def _cmd_pdata_init(args: argparse.Namespace) -> int:
             # apply here.
             return 0
         print(f"\nProposal: {result.proposal_path}")
-        _print_migration_prompt_reminders(
+        _print_post_migration_skill_reminders(
             result.proposal_path.parent,
-            ("After a successful --write, update project docs", "pdata-migration-claude-md-update.md"),
+            ("After a successful --write, update project docs", "pm-pdata-do-update-project-docs"),
         )
         return 0
 
@@ -1286,10 +1255,10 @@ def _cmd_pdata_init(args: argparse.Namespace) -> int:
         print()
         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(
+        _print_post_migration_skill_reminders(
             project_root,
-            ("Update project docs", "pdata-migration-claude-md-update.md"),
-            ("Update consuming skills", "pdata-migration-skills-update.md"),
+            ("Update project docs", "pm-pdata-do-update-project-docs"),
+            ("Update consuming skills", "pm-pdata-do-update-consuming-skills"),
         )
         print("SUCCESS")
         return 0

{cc_session_tools-3.9.2 → cc_session_tools-3.10.1}/src/cc_session_tools/lib/pdata/cutover.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import time
+from collections.abc import Callable
 from pathlib import Path
 
 from cc_session_tools.lib.pdata.init_paths import (
@@ -59,6 +60,7 @@ def _write_pointer_file(*, project_root: Path, project: str, entry: ManifestEntr
 def archive_entries(
     *, project_root: Path, entries: list[ManifestEntry], project: str,
     write_pointer_files: bool = True,
+    on_archived: Callable[[ManifestEntry], None] | None = None,
 ) -> None:
     """Move every db-owned entry's source file into project_root/.pdata-migrated/,
     preserving its relative path, and append one line per entry to MANIFEST.md.
@@ -69,7 +71,11 @@ def archive_entries(
     Markdown pointer file back at each entry's original path so anything else in the
     project that cites the old path by name finds a live signpost instead of a silent
     404. Pass write_pointer_files=False (--leave-no-pointer-files at the CLI) to
-    suppress this."""
+    suppress this.
+
+    `on_archived`, if given, is called with each entry immediately after its source has been
+    moved (before its log line and pointer file are written), so a caller that sees this
+    function raise part-way knows exactly which entries were already cut over."""
     if not entries:
         return
     archive_root = project_root / MIGRATED_ARCHIVE_DIRNAME
@@ -82,6 +88,8 @@ def archive_entries(
             destination = archive_root / entry.path
             destination.parent.mkdir(parents=True, exist_ok=True)
             source.rename(destination)
+            if on_archived is not None:
+                on_archived(entry)
             log.write(
                 f"- {now} — {entry.path} — migrated source, superseded by ccst pdata "
                 f"(record_group={entry.db_group()})\n"

{cc_session_tools-3.9.2 → cc_session_tools-3.10.1}/src/cc_session_tools/lib/pdata/init_service.py

@@ -213,6 +213,69 @@ def _rollback(*, project: str, created_ids: list[int]) -> list[str]:
     return rollback_failures
 
 
+def _rollback_after_error(
+    exc: BaseException, *, project: str, created_ids: list[int],
+    on_progress: Callable[[str], None] | None,
+) -> None:
+    """Roll back `created_ids` after an error `write()` did not anticipate, without ever
+    replacing `exc` (the caller re-raises it): a rollback that itself fails is reported through
+    `on_progress` and attached to `exc` as a note naming every record id still live, so the
+    manual cleanup the failure implies is not a hunt."""
+    if not created_ids:
+        return
+    try:
+        failures = _rollback(project=project, created_ids=created_ids)
+    except Exception as rollback_exc:
+        note = (
+            f"rollback of {len(created_ids)} inserted row(s) aborted: {rollback_exc!r} - rows "
+            f"from this run may still be live; record ids: {created_ids}"
+        )
+        exc.add_note(note)
+        _emit(on_progress, note)
+        return
+    rolled_back = len(created_ids) - len(failures)
+    _emit(
+        on_progress,
+        f"Unexpected {type(exc).__name__} - rolled back {rolled_back} of "
+        f"{len(created_ids)} inserted row(s)",
+    )
+    if failures:
+        exc.add_note("rows from this run still live:\n" + "\n".join(failures))
+        for failure in failures:
+            _emit(on_progress, f"  {failure}")
+
+
+def _recover_from_failed_cutover(
+    exc: BaseException, *, project: str, m: Manifest, proposal_path: Path,
+    written_entries: list[ManifestEntry], archived: list[ManifestEntry],
+    entry_rows: dict[str, list[tuple[int, ImportRow]]],
+    on_progress: Callable[[str], None] | None,
+) -> None:
+    """Cutover failed part-way. An entry whose source was already moved into the archive is cut
+    over: its rows are its live copy, so they stay and the entry is marked migrated (a rerun then
+    skips it). An entry still in place has its rows rolled back, so a rerun imports it once
+    rather than twice."""
+    if archived:
+        stamp = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+        for entry in archived:
+            entry.migrated_at = stamp
+        try:
+            manifest.save(m, proposal_path)
+        except Exception as save_exc:
+            exc.add_note(
+                f"could not record {len(archived)} already cut-over entr(ies) as migrated in "
+                f"{proposal_path}: {save_exc!r}; mark these migrated by hand before re-running: "
+                f"{', '.join(e.path for e in archived)}"
+            )
+    archived_paths = {e.path for e in archived}
+    pending_ids = [
+        record_id
+        for entry in written_entries if entry.path not in archived_paths
+        for record_id, _ in entry_rows[entry.path]
+    ]
+    _rollback_after_error(exc, project=project, created_ids=pending_ids, on_progress=on_progress)
+
+
 def _check_db_not_locked(project: str) -> None:
     """Pre-flight concurrency guard (inter-session message 20260819T114156Z-3ec7,
     gap #2): refuse to start --write if another connection already holds a write
@@ -432,105 +495,125 @@ def write(
         db_owned = [e for e in m.entries if e.classification == "db-owned"]
         already_migrated = [e for e in db_owned if e.migrated_at is not None]
         to_import = [e for e in db_owned if e.migrated_at is None]
-        _emit(on_progress, f"Importing {len(to_import)} file(s)...")
-        if already_migrated:
-            _emit(
-                on_progress,
-                f"  skipping {len(already_migrated)} already-migrated file(s): "
-                f"{', '.join(e.path for e in already_migrated)}",
+        # Everything from the first insert through the backup either returns a WriteResult
+        # (rolling back by hand) or, for any exception this code did not anticipate, rolls the
+        # inserted rows back here before re-raising - never leaves them live with the manifest
+        # unmarked and cutover unrun.
+        try:
+            _emit(on_progress, f"Importing {len(to_import)} file(s)...")
+            if already_migrated:
+                _emit(
+                    on_progress,
+                    f"  skipping {len(already_migrated)} already-migrated file(s): "
+                    f"{', '.join(e.path for e in already_migrated)}",
+                )
+            for entry in to_import:
+                try:
+                    source_path = project_root / entry.path
+                    if not source_path.exists():
+                        # entry.migrated_at is None here (to_import excludes already-migrated
+                        # entries above), so this is not the ordinary "already cut over by an
+                        # earlier --write" case — the source is genuinely missing for an entry
+                        # this run believes still needs importing. Fail with a specific,
+                        # actionable message (still caught by this loop's own except clause
+                        # below, so it contributes to `reasons`/rollback exactly like any other
+                        # per-entry import failure) instead of a bare FileNotFoundError only
+                        # discoverable via the rollback reasons list.
+                        raise ValueError(
+                            f"{entry.path}: marked db-owned with no migrated_at, but its source "
+                            f"file does not exist at {source_path} — if this entry was already "
+                            f"migrated by another means, set its classification to folder-owned "
+                            f"(or otherwise correct the manifest) before running --write again"
+                        )
+                    _emit(on_progress, f"  importing {entry.path} -> group={entry.db_group()}...")
+                    for spec in entry.fields:
+                        service.schema_add_field(
+                            project=project, record_group=entry.db_group(),
+                            field_name=spec.name, sql_type=spec.sql_type,
+                            description=spec.description, default=spec.default,
+                        )
+                    rows_for_entry: list[tuple[int, ImportRow]] = []
+                    for row in import_entry(project_root, entry):
+                        record = service.add_record(
+                            project=project, record_group=entry.db_group(),
+                            content=row.content, file_path=row.file_path,
+                            fields=row.fields, created_at=row.created_at,
+                        )
+                        created_ids.append(record.id)
+                        rows_for_entry.append((record.id, row))
+                    entry_rows[entry.path] = rows_for_entry
+                    _emit(on_progress, f"    {len(rows_for_entry)} row(s) imported")
+                    written_entries.append(entry)
+                except (ValueError, OSError, csv.Error) as exc:
+                    reasons.append(f"{entry.path}: {exc}")
+
+            _emit(on_progress, "Verifying imported rows...")
+            reasons.extend(
+                _verify(project=project, project_root=project_root,
+                        written_entries=written_entries, entry_rows=entry_rows)
             )
-        for entry in to_import:
-            try:
-                source_path = project_root / entry.path
-                if not source_path.exists():
-                    # entry.migrated_at is None here (to_import excludes already-migrated
-                    # entries above), so this is not the ordinary "already cut over by an
-                    # earlier --write" case — the source is genuinely missing for an entry
-                    # this run believes still needs importing. Fail with a specific,
-                    # actionable message (still caught by this loop's own except clause
-                    # below, so it contributes to `reasons`/rollback exactly like any other
-                    # per-entry import failure) instead of a bare FileNotFoundError only
-                    # discoverable via the rollback reasons list.
-                    raise ValueError(
-                        f"{entry.path}: marked db-owned with no migrated_at, but its source "
-                        f"file does not exist at {source_path} — if this entry was already "
-                        f"migrated by another means, set its classification to folder-owned "
-                        f"(or otherwise correct the manifest) before running --write again"
-                    )
-                _emit(on_progress, f"  importing {entry.path} -> group={entry.db_group()}...")
-                for spec in entry.fields:
-                    service.schema_add_field(
-                        project=project, record_group=entry.db_group(),
-                        field_name=spec.name, sql_type=spec.sql_type,
-                        description=spec.description, default=spec.default,
-                    )
-                rows_for_entry: list[tuple[int, ImportRow]] = []
-                for row in import_entry(project_root, entry):
-                    record = service.add_record(
-                        project=project, record_group=entry.db_group(),
-                        content=row.content, file_path=row.file_path,
-                        fields=row.fields, created_at=row.created_at,
-                    )
-                    created_ids.append(record.id)
-                    rows_for_entry.append((record.id, row))
-                entry_rows[entry.path] = rows_for_entry
-                _emit(on_progress, f"    {len(rows_for_entry)} row(s) imported")
-                written_entries.append(entry)
-            except (ValueError, OSError, csv.Error) as exc:
-                reasons.append(f"{entry.path}: {exc}")
-
-        _emit(on_progress, "Verifying imported rows...")
-        reasons.extend(
-            _verify(project=project, project_root=project_root,
-                    written_entries=written_entries, entry_rows=entry_rows)
-        )
 
-        if reasons:
-            _emit(on_progress, "Verification failed — rolling back inserted rows...")
-            return WriteResult(
-                created_record_ids=[], entries_written=[], backup_path=None,
-                failure=WriteFailure(
-                    reasons=reasons + _rollback(project=project, created_ids=created_ids)
-                ),
+            if reasons:
+                _emit(on_progress, "Verification failed — rolling back inserted rows...")
+                return WriteResult(
+                    created_record_ids=[], entries_written=[], backup_path=None,
+                    failure=WriteFailure(
+                        reasons=reasons + _rollback(project=project, created_ids=created_ids)
+                    ),
+                )
+
+            # Still inside both overrides: a rehearsed run's backup must land in the
+            # rehearsal sandbox (backup_dir_override), never in the real backup dir.
+            _emit(on_progress, "Backing up project and database before cutover...")
+            try:
+                backup_path = backup.create_backup(
+                    project=project, project_root=project_root, on_progress=on_progress,
+                )
+                _emit(on_progress, f"Backup written: {backup_path}")
+            except backup.BackupError as exc:
+                _emit(on_progress, "Backup failed — rolling back inserted rows...")
+                return WriteResult(
+                    created_record_ids=[], entries_written=[], backup_path=None,
+                    failure=WriteFailure(
+                        reasons=[str(exc)] + _rollback(project=project, created_ids=created_ids)
+                    ),
+                )
+        except BaseException as exc:
+            _rollback_after_error(
+                exc, project=project, created_ids=created_ids, on_progress=on_progress,
             )
+            raise
 
-        # Still inside both overrides: a rehearsed run's backup must land in the
-        # rehearsal sandbox (backup_dir_override), never in the real backup dir.
-        _emit(on_progress, "Backing up project and database before cutover...")
+        _emit(on_progress, f"Cutting over {len(written_entries)} file(s)...")
+        archived: list[ManifestEntry] = []
         try:
-            backup_path = backup.create_backup(
-                project=project, project_root=project_root, on_progress=on_progress,
+            cutover.archive_entries(
+                project_root=project_root, entries=written_entries, project=project,
+                write_pointer_files=not leave_no_pointer_files, on_archived=archived.append,
             )
-            _emit(on_progress, f"Backup written: {backup_path}")
-        except backup.BackupError as exc:
-            _emit(on_progress, "Backup failed — rolling back inserted rows...")
-            return WriteResult(
-                created_record_ids=[], entries_written=[], backup_path=None,
-                failure=WriteFailure(
-                    reasons=[str(exc)] + _rollback(project=project, created_ids=created_ids)
-                ),
+            # Mark every entry this run actually cut over as migrated, and persist that back to
+            # the manifest — write() only ever `manifest.load`s otherwise, so without this a
+            # later --write would re-attempt (and, pre-fix, roll back) these same now-archived
+            # entries. written_entries holds the same ManifestEntry objects m.entries does (see
+            # the `to_import`/`written_entries.append(entry)` loop above), so mutating here
+            # mutates m.
+            migrated_at = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+            for entry in written_entries:
+                entry.migrated_at = migrated_at
+            manifest.save(m, proposal_path)
+        except BaseException as exc:
+            _recover_from_failed_cutover(
+                exc, project=project, m=m, proposal_path=proposal_path,
+                written_entries=written_entries, archived=archived, entry_rows=entry_rows,
+                on_progress=on_progress,
             )
-
-    _emit(on_progress, f"Cutting over {len(written_entries)} file(s)...")
-    cutover.archive_entries(
-        project_root=project_root, entries=written_entries, project=project,
-        write_pointer_files=not leave_no_pointer_files,
-    )
-    # Mark every entry this run actually cut over as migrated, and persist that back to
-    # the manifest — write() only ever `manifest.load`s otherwise, so without this a later
-    # --write would re-attempt (and, pre-fix, roll back) these same now-archived entries.
-    # written_entries holds the same ManifestEntry objects m.entries does (see the
-    # `to_import`/`written_entries.append(entry)` loop above), so mutating here mutates m.
-    migrated_at = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
-    for entry in written_entries:
-        entry.migrated_at = migrated_at
-    manifest.save(m, proposal_path)
-    return WriteResult(
-        created_record_ids=created_ids,
-        entries_written=[e.path for e in written_entries],
-        backup_path=backup_path, failure=None,
-        report=_render_diff_report(written_entries=written_entries, entry_rows=entry_rows),
-    )
+            raise
+        return WriteResult(
+            created_record_ids=created_ids,
+            entries_written=[e.path for e in written_entries],
+            backup_path=backup_path, failure=None,
+            report=_render_diff_report(written_entries=written_entries, entry_rows=entry_rows),
+        )
 
 
 def _verify(
@@ -544,12 +627,18 @@ def _verify(
     reasons: list[str] = []
     for entry in written_entries:
         rows = entry_rows[entry.path]
-        expected_count = count_source_rows(project_root, entry)
-        if len(rows) != expected_count:
+        try:
+            expected_count = count_source_rows(project_root, entry)
+        except (ValueError, OSError, csv.Error) as exc:
             reasons.append(
-                f"{entry.path}: imported {len(rows)} row(s) but re-counting the source "
-                f"gives {expected_count} — entry-count parity check failed"
+                f"{entry.path}: could not re-count the source rows for the parity check: {exc}"
             )
+        else:
+            if len(rows) != expected_count:
+                reasons.append(
+                    f"{entry.path}: imported {len(rows)} row(s) but re-counting the source "
+                    f"gives {expected_count} — entry-count parity check failed"
+                )
         for record_id, import_row in rows:
             record = service.get_record(project=project, record_id=record_id)
             assert record is not None, (
@@ -562,7 +651,17 @@ def _verify(
                 )
             if record.file_path:
                 target = project_root / record.file_path
-                if not target.exists():
+                try:
+                    resolves = target.exists()
+                except OSError as exc:
+                    # A string the OS rejects outright (e.g. "File name too long") raises
+                    # instead of returning False; it is the same "does not resolve" outcome.
+                    reasons.append(
+                        f"{entry.path}: record {record_id} file_path "
+                        f"{record.file_path!r} cannot be checked under {project_root}: {exc}"
+                    )
+                    continue
+                if not resolves:
                     reasons.append(
                         f"{entry.path}: record {record_id} file_path "
                         f"{record.file_path!r} does not resolve under {project_root}"

{cc_session_tools-3.9.2 → cc_session_tools-3.10.1}/src/cc_session_tools/skills/pm-pdata-do-init/SKILL.md

@@ -210,6 +210,22 @@ Step 3's garbled-header recipe) - so anything else in the project citing the old
 a live signpost instead of a silent 404. Pass `--leave-no-pointer-files` if this run shouldn't
 leave one (e.g. a rehearsal, or a project convention against extra files at migrated paths).
 
+### Then run both post-migration skills
+
+After a successful `--write` (not after a dry-run or a rehearsal), update everything that still
+describes or uses the old flat-file layout. Run these in order, each in its own fresh-context
+`Agent` subagent whose prompt begins with `cd ~/cc/<project>` - not inline in this session, which
+has just written the migration and would rationalize away stale references it remembers:
+
+1. `pm-pdata-do-update-project-docs` - rewrites the project's `CLAUDE.md` and other top-level docs
+   to name the pdata record_groups and `ccst pdata` commands, and reports folder-layout drift.
+2. `pm-pdata-do-update-consuming-skills` - finds skills that literally reference the old paths and
+   rewrites direct reads/writes to `ccst pdata` commands, flagging anything it cannot rewrite
+   mechanically.
+
+Relay each subagent's report to the user, including anything flagged for a human decision. If a
+later `--write` round adds more record groups, run both again; they are safe to re-run.
+
 ## 8. Rollback, if something's found wrong post-cutover
 
 There is no `--rollback` flag. Recover by hand:

cc_session_tools-3.10.1/src/cc_session_tools/skills/pm-pdata-do-update-consuming-skills/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: pm-pdata-do-update-consuming-skills
+description: Use after `ccst pdata init --write` has migrated a ~/cc/<project>'s flat files into its pdata store - finds Claude Code skills under ~/.claude/skills/ that literally reference the project's old flat-file paths, rewrites direct reads/writes to the equivalent `ccst pdata` commands, and flags anything that cannot be rewritten mechanically for a human decision. Matches by literal path only. Triggers - "update the skills that read the old <project> files", "fix skills that use the old paths after the pdata migration", "/pm-pdata-do-update-consuming-skills"; also run automatically as a step of pm-pdata-do-init. Do NOT use for the project's own docs (pm-pdata-do-update-project-docs) or the migration itself (pm-pdata-do-init).
+---
+
+# pm-pdata-do-update-consuming-skills
+
+Finds skills that read or write a project's old flat-file paths directly and switches them to the
+equivalent `ccst pdata` command. Run it after `ccst pdata init --write` has cut a project's data
+over.
+
+## Run this in a fresh context
+
+Run this skill in a fresh context, not inline in the session that just ran `ccst pdata init
+--write`. The point of a fresh read is that it cannot rationalize away a stale reference it
+half-remembers writing earlier in the same conversation. Either is acceptable:
+
+- An orchestrating session dispatches it as an `Agent` subagent. The Agent tool cannot set a cwd,
+  so the subagent's prompt must begin by changing into the project root (`cd ~/cc/<project>`).
+- A new Claude Code session started in `~/cc/<project>`.
+
+Running it inline in the migrating session is not acceptable.
+
+## Step 1 - Verify project context
+
+Check the cwd is a `~/cc/<project>` project directory with a `CLAUDE.md`:
+
+```sh
+pwd && basename "$(pwd)" && ls CLAUDE.md 2>/dev/null && echo "project CLAUDE.md confirmed"
+```
+
+If `CLAUDE.md` is present, the `basename` output is the project name to search for in Step 2. If
+not, print the following and stop:
+
+> ERROR: This skill must be run from a `~/cc/<project>` directory containing a `CLAUDE.md`.
+> Aborting without touching any skills.
+
+## Step 2 - Find every skill referencing this project's old flat-file paths
+
+Search every skill's `SKILL.md` and any scripts under its directory for literal mentions of this
+project's pre-migration paths:
+
+```sh
+grep -rl "~/cc/<project>/<old-path>" ~/.claude/skills/*/ 2>/dev/null
+grep -rl "cc/<project>/<old-path>" ~/.claude/skills/*/ 2>/dev/null   # relative-path equivalents
+```
+
+Substitute the project's actual name and the pre-migration path(s) from the project's
+`ccst-pdata-init-write.log`, or from the classification report `ccst pdata init` produced. If
+neither is available, check `<project-root>/.pdata-migrated/`: the migration archives the
+original pre-cutover files there, unchanged, under their original relative paths. For example, a
+project `home` that migrated its Tesco order history would search for `~/cc/home/data/tesco/*.csv`
+or `home/data/tesco` across every skill's `SKILL.md` and scripts.
+
+Match by literal path only. Do not widen the search to skills whose name merely sounds related to
+the project or its domain: a skill named `do-tesco-shop` is not evidence on its own that it
+touches this project's files. Only a literal path match is.
+
+If Step 2 finds no matches at all, say so in the report and stop. There is nothing to do.
+
+## Step 3 - Classify each match
+
+For each skill with a literal path match, read the matching lines and enough surrounding
+code or prose to be sure which category applies. Do not guess from the skill's name or its
+one-line description.
+
+- **Direct read/write** - the skill's script (or its documented instructions) opens, parses,
+  appends to, or otherwise operates on the file at that path as part of normal execution. This
+  needs rewriting.
+- **Passing mention** - the path appears only in prose (an example, a comment about history, a
+  reference to "where this used to live") and no code path touches the file. This may not need
+  changing; leave it alone.
+
+## Step 4 - Rewrite direct read/write matches
+
+For each direct read/write, rewrite the file I/O to use the equivalent `ccst pdata` command:
+
+- Reading to list or browse records: `ccst pdata list --project <name> --group <record_group>
+  [--format json]`.
+- Reading one record: `ccst pdata get --project <name> --id <id>`.
+- Filtering or searching: `ccst pdata query --project <name> --group <record_group> --where
+  '<field> <op> <value>'`.
+- Appending a record: `ccst pdata add` (check `ccst pdata add --help` for the record shape the
+  target record_group expects).
+- Editing a record: `ccst pdata update` (version-checked; check `ccst pdata update --help`).
+
+Keep the rewrite mechanical and narrow: change the I/O call to go through `ccst pdata`, and do not
+otherwise restructure the skill's logic or prose beyond what reflects the new access path. If the
+skill's script parsed CSV columns or JSON keys directly, map them to the pdata record fields using
+`ccst pdata schema show --project <name> --group <record_group>` (it lists the group's registered
+extension fields) rather than guessing field names.
+
+Do not touch skills unrelated to this project. A match that on closer reading references a
+different project's similarly-named folder is not this skill's concern - skip it.
+
+## Step 5 - Flag anything unsafe to rewrite mechanically
+
+Some direct matches do more than read a file or append a row: custom locking, multi-file
+transactions, format transformations that do not map onto one `ccst pdata` command, or logic that
+depends on file-level properties (mtime, file size, row order) that pdata does not expose the same
+way.
+
+Do not attempt to rewrite these. List each in the report as needing a human decision, with enough
+detail (skill name, file, what it does, why it does not map cleanly) for the user to decide.
+Silently skipping a match is not acceptable: every match found in Step 2 must appear in the
+report as "updated", "left alone (passing mention only)", or "needs a human decision".
+
+## Step 6 - Report
+
+Summarise for the user:
+
+1. Which skills had a literal path match (Step 2).
+2. For each, its category (Step 3) and outcome: updated, left alone, or needs a human decision.
+3. If there were no matches at all, say so plainly. That is a valid and complete outcome.