cc-session-tools 3.2.1__tar.gz → 3.3.1__tar.gz

{cc_session_tools-3.2.1/src/cc_session_tools.egg-info → cc_session_tools-3.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 3.2.1
+Version: 3.3.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.2.1 → cc_session_tools-3.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-session-tools"
-version = "3.2.1"
+version = "3.3.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" }

{cc_session_tools-3.2.1 → cc_session_tools-3.3.1}/src/cc_session_tools/cli/ccst.py

@@ -173,14 +173,19 @@ 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, followed by a line telling the user to run it in a fresh Claude Code
-    session started in project_root.
+    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. 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.
+    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
@@ -197,7 +202,8 @@ def _print_migration_prompt_reminders(
         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."
+            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."
         )
 
 
@@ -1178,6 +1184,7 @@ def _cmd_pdata_init(args: argparse.Namespace) -> int:
         try:
             write_result = init_service.write(
                 project=args.project, rehearse=rehearse, on_progress=print,
+                leave_no_pointer_files=args.leave_no_pointer_files,
             )
         except (FileNotFoundError, ValueError) as exc:
             print(f"ccst pdata: {exc}", file=sys.stderr)
@@ -3035,6 +3042,14 @@ def _build_parser() -> argparse.ArgumentParser:
             "<project>/ccst-pdata-init-write.log"
         ),
     )
+    pdata_init_parser.add_argument(
+        "--leave-no-pointer-files", action="store_true",
+        help=(
+            "By default, --write leaves a Markdown pointer file at each migrated entry's "
+            "original path (record_group, schema, an example query command). Pass this "
+            "flag to suppress that and leave nothing behind at the original path."
+        ),
+    )
 
     pdata_reorganize_parser = pdata_sub.add_parser(
         "reorganize", help="Split a flat folder into a nested (by-year or by-year-month) structure"

cc_session_tools-3.3.1/src/cc_session_tools/lib/pdata/cutover.py

@@ -0,0 +1,90 @@
+"""Cutover: archive migrated-source originals, never delete them (spec §7.1 steps 6-7)."""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from cc_session_tools.lib.pdata.init_paths import (
+    MIGRATED_ARCHIVE_DIRNAME,
+    MIGRATED_MANIFEST_FILENAME,
+)
+from cc_session_tools.lib.pdata.manifest import ManifestEntry
+
+
+def _pointer_file_content(*, project: str, entry: ManifestEntry) -> str:
+    """Generic pointer content (spec pdata/init-pointer-files): the record_group now
+    holding this file's data, its field/schema table, and an example query — plus,
+    when the entry carries preface_text (set by hand per pm-project-init's
+    garbled-CSV-header fix recipe), that text verbatim under its own heading."""
+    lines = [
+        f"# {Path(entry.path).name} — migrated to pdata",
+        "",
+        f"This file's data now lives in pdata record group `{entry.db_group()}` for "
+        f"project `{project}`. The original was moved to "
+        f"`{MIGRATED_ARCHIVE_DIRNAME}/{entry.path}` and is no longer read from here.",
+        "",
+        "## Schema",
+        "",
+        "| field | sql_type | description |",
+        "| --- | --- | --- |",
+    ]
+    for spec in entry.fields:
+        lines.append(f"| {spec.name} | {spec.sql_type} | {spec.description or ''} |")
+    lines += [
+        "",
+        "## Example query",
+        "",
+        "```sh",
+        f"ccst pdata list --project {project} --group {entry.db_group()}",
+        "```",
+    ]
+    if entry.preface_text:
+        lines += [
+            "",
+            "## Preserved preface text (removed from the original file before migration)",
+            "",
+            entry.preface_text,
+        ]
+    return "\n".join(lines) + "\n"
+
+
+def _write_pointer_file(*, project_root: Path, project: str, entry: ManifestEntry) -> None:
+    pointer_path = project_root / Path(entry.path).with_suffix(".md")
+    pointer_path.parent.mkdir(parents=True, exist_ok=True)
+    pointer_path.write_text(
+        _pointer_file_content(project=project, entry=entry), encoding="utf-8",
+    )
+
+
+def archive_entries(
+    *, project_root: Path, entries: list[ManifestEntry], project: str,
+    write_pointer_files: bool = True,
+) -> 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.
+    Never deletes — cutover only relocates within project_root (spec §7.1 step 6);
+    deleting the archive is a manual, human-directed action (step 7).
+
+    By default (write_pointer_files=True, spec pdata/init-pointer-files), also writes a
+    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."""
+    if not entries:
+        return
+    archive_root = project_root / MIGRATED_ARCHIVE_DIRNAME
+    archive_root.mkdir(parents=True, exist_ok=True)
+    manifest_path = archive_root / MIGRATED_MANIFEST_FILENAME
+    now = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    with manifest_path.open("a", encoding="utf-8") as log:
+        for entry in entries:
+            source = project_root / entry.path
+            destination = archive_root / entry.path
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            source.rename(destination)
+            log.write(
+                f"- {now} — {entry.path} — migrated source, superseded by ccst pdata "
+                f"(record_group={entry.db_group()})\n"
+            )
+            if write_pointer_files:
+                _write_pointer_file(project_root=project_root, project=project, entry=entry)

{cc_session_tools-3.2.1 → cc_session_tools-3.3.1}/src/cc_session_tools/lib/pdata/init_service.py

@@ -8,7 +8,7 @@ import csv
 import sqlite3
 from collections.abc import Callable
 from dataclasses import dataclass
-from datetime import datetime
+from datetime import UTC, datetime
 from pathlib import Path
 
 from cc_session_tools.lib import db
@@ -96,6 +96,29 @@ def dry_run(*, project: str, rehearse: Path | None = None) -> DryRunResult:
     return DryRunResult(manifest=m, report=_render_report(m), proposal_path=proposal_path)
 
 
+# A field name proposed by _classify_csv is derived from a real CSV header cell (see
+# classify._slugify_field_name) — an ordinary column name slugifies to something short.
+# A garbled header (prose/provenance text on the "header" row, spec pdata/
+# init-classification-report) instead produces long, many-word sentence-fragment names
+# like `pending_chris_s_manual_review`. Neither threshold alone is exact, but a name
+# tripping either is worth a reviewer's second look.
+_SUSPICIOUS_FIELD_NAME_CHAR_THRESHOLD = 40
+_SUSPICIOUS_FIELD_NAME_WORD_THRESHOLD = 5
+
+
+def _looks_like_garbled_header(field_names: list[str]) -> bool:
+    """True when multiple proposed field names read as sentence fragments rather than
+    short domain nouns — see spec pdata/init-classification-report. A single long name
+    isn't enough on its own (a legitimately verbose but real column header shouldn't be
+    flagged); this looks for the pattern repeating across an entry's fields."""
+    suspicious = sum(
+        1 for name in field_names
+        if len(name) > _SUSPICIOUS_FIELD_NAME_CHAR_THRESHOLD
+        or name.count("_") + 1 >= _SUSPICIOUS_FIELD_NAME_WORD_THRESHOLD
+    )
+    return suspicious >= 2
+
+
 def _render_report(m: Manifest) -> str:
     if not m.entries:
         return f"ccst pdata init — {m.project}: no files found, empty base schema created."
@@ -109,6 +132,12 @@ def _render_report(m: Manifest) -> str:
                 f"  [db-owned]     {e.path} -> group={e.record_group} "
                 f"strategy={e.strategy} fields={field_names}"
             )
+            if _looks_like_garbled_header(field_names):
+                lines.append(
+                    "    ⚠ worth double-checking — these field names read as sentence "
+                    "fragments, not column names; this file's header may not be what it "
+                    "looks like (see pm-project-init's garbled-CSV-header caveat)"
+                )
     lines.append(
         "Review/override entries in the proposal file listed below before running --write."
     )
@@ -352,6 +381,7 @@ def _adopt_from_dump(
 def write(
     *, project: str, rehearse: Path | None = None,
     on_progress: Callable[[str], None] | None = None,
+    leave_no_pointer_files: bool = False,
 ) -> WriteResult:
     project_root = init_paths.resolve_project_root(project, rehearse=rehearse)
 
@@ -396,11 +426,33 @@ def write(
         _check_db_not_locked(project)
 
         db_owned = [e for e in m.entries if e.classification == "db-owned"]
-        _emit(on_progress, f"Importing {len(db_owned)} file(s)...")
-        for entry in m.entries:
-            if entry.classification != "db-owned":
-                continue
+        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)}",
+            )
+        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(
@@ -456,7 +508,19 @@ def write(
             )
 
     _emit(on_progress, f"Cutting over {len(written_entries)} file(s)...")
-    cutover.archive_entries(project_root=project_root, entries=written_entries)
+    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],

{cc_session_tools-3.2.1 → cc_session_tools-3.3.1}/src/cc_session_tools/lib/pdata/manifest.py

@@ -40,6 +40,15 @@ class ManifestEntry:
     content_column: str | None = None
     file_path_column: str | None = None
     fields: list[FieldSpec] = field(default_factory=list)
+    # Set by init_service.write() on successful cutover (ISO-8601 UTC) — a later
+    # --write skips any entry that already carries one instead of re-importing it
+    # (spec pdata/init-write-idempotency). None for an entry never yet migrated.
+    migrated_at: str | None = None
+    # Hand-set during review (pm-project-init's garbled-CSV-header fix recipe):
+    # header/provenance text stripped from the source file before migration,
+    # preserved verbatim here so cutover.archive_entries can carry it into the
+    # entry's pointer file (spec pdata/init-pointer-files). None when not applicable.
+    preface_text: str | None = None
 
     def __post_init__(self) -> None:
         if self.classification not in _VALID_CLASSIFICATIONS:

{cc_session_tools-3.2.1 → cc_session_tools-3.3.1}/src/cc_session_tools/lib/pdata/resolve.py

@@ -8,7 +8,7 @@ overwrite (that is rehydrate.py's job for the clean fast-forward case; this modu
 
 Never auto-merges, never silently keeps one side and discards the other — every record surfaced
 here needs an explicit choice from the caller (ultimately Chris, via the CLI/skill), matching the
-existing `pm-pdata-conflict-resolution` skill's single-file-conflict framing exactly. Every
+existing `pm-pdata-resolve-conflicts` skill's single-file-conflict framing exactly. Every
 record: `apply_resolution` is all-or-nothing over the whole diff, for the reasons in its own
 docstring.
 
@@ -342,7 +342,7 @@ def _apply_resolution(
             f"record_id(s) {collisions}: id collision (the same id was independently assigned to "
             f"two unrelated records) — not resolvable as a local/dump choice, since either pick "
             f"would discard one side's real record; needs a manual, out-of-band fix (see the "
-            f"pm-pdata-conflict-resolution skill, point 4)"
+            f"pm-pdata-resolve-conflicts skill, point 4)"
         )
 
     group_mismatches = sorted(rid for rid, rd in by_id.items() if rd.group_mismatch)
@@ -351,7 +351,7 @@ def _apply_resolution(
             f"record_id(s) {group_mismatches}: group mismatch (same id and created_at, but the "
             f"two sides disagree on record_group) — not resolvable as a local/dump choice. "
             f"Compare each side's content/file_path before assuming a rename is safe (see the "
-            f"pm-pdata-conflict-resolution skill, point 5, for why it may instead be a "
+            f"pm-pdata-resolve-conflicts skill, point 5, for why it may instead be a "
             f"same-second id collision), then retry"
         )
 

{cc_session_tools-3.2.1 → cc_session_tools-3.3.1}/src/cc_session_tools/lib/pdata/service.py

@@ -310,7 +310,7 @@ def update_record(
     content and fields are independent — updating fields never re-serializes content, and vice
     versa. This is deliberate (it's what lets a --field-only update skip resending content), not
     a gap: a record group whose content is designed to mirror its fields is the caller's own
-    duplication to keep in sync, on every write, by passing both. See pm-pdata-schema-design
+    duplication to keep in sync, on every write, by passing both. See pm-pdata-design-schema
     SKILL.md's "content and extension fields are never auto-synced" section."""
     if content is None and file_path is None and not fields:
         raise ValueError(

{cc_session_tools-3.2.1 → cc_session_tools-3.3.1}/src/cc_session_tools/prompts/pdata-migration-claude-md-update.md

@@ -12,6 +12,15 @@ cd ~/cc/<project> && \
   claude -p "Check that you are executing with a ~/cc/<project> directory as your cwd, containing a CLAUDE.md. If you are not then exit. If you are then use this file as your prompt: <path-to-cc-session-tools>/src/cc_session_tools/prompts/pdata-migration-claude-md-update.md"
 ```
 
+**What matters is a fresh context, not literally a new process.** The reason this prompt asks
+for a new session is a genuinely fresh, unbiased read that won't rationalize away a stale
+reference it half-remembers writing earlier in the same conversation. An orchestrating session
+that just ran `ccst pdata init --write` can dispatch this prompt as an `Agent` subagent (with its
+cwd set to the project root) instead of shelling out to a literal `claude -p` process — a
+dispatched subagent gets the same fresh-context benefit without leaving the orchestrating
+session's control flow. Either is acceptable; what is not acceptable is running this prompt
+inline in the same context that just did the migration.
+
 ---
 
 ## Step 1 — Verify project context

{cc_session_tools-3.2.1 → cc_session_tools-3.3.1}/src/cc_session_tools/prompts/pdata-migration-skills-update.md

@@ -12,6 +12,15 @@ cd ~/cc/<project> && \
   claude -p "Check that you are executing with a ~/cc/<project> directory as your cwd. If you are not then exit. If you are then use this file as your prompt: <path-to-cc-session-tools>/src/cc_session_tools/prompts/pdata-migration-skills-update.md"
 ```
 
+**What matters is a fresh context, not literally a new process.** The reason this prompt asks
+for a new session is a genuinely fresh, unbiased read that won't rationalize away a stale
+reference it half-remembers writing earlier in the same conversation. An orchestrating session
+that just ran `ccst pdata init --write` can dispatch this prompt as an `Agent` subagent (with its
+cwd set to the project root) instead of shelling out to a literal `claude -p` process — a
+dispatched subagent gets the same fresh-context benefit without leaving the orchestrating
+session's control flow. Either is acceptable; what is not acceptable is running this prompt
+inline in the same context that just did the migration.
+
 ---
 
 ## Step 1 — Verify project context

{cc_session_tools-3.2.1/src/cc_session_tools/skills/pm-pdata-schema-design → cc_session_tools-3.3.1/src/cc_session_tools/skills/pm-pdata-design-schema}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pm-pdata-schema-design
+name: pm-pdata-design-schema
 description: Use before writing a genuinely new kind of structured data into any project's ccst pdata store - deciding whether it fits an existing record_group, needs a brand-new group, and whether that group needs an extension table or free-text content suffices. Triggers on "I need to track a new kind of record", "what record_group should this be", "does this need an extension table", "add a new field to ccst pdata", or any session about to call `ccst pdata add`/`schema add-field` for a record shape it hasn't used before. Prevents lazy catch-all groups (`notes`/`misc`) that silently recreate the EAV undifferentiated-bucket problem the schema deliberately rejected.
 ---
 

{cc_session_tools-3.2.1 → cc_session_tools-3.3.1}/src/cc_session_tools/skills/pm-pdata-do-audit-and-prepare-to-migrate/SKILL.md

@@ -1,10 +1,16 @@
 ---
 name: pm-pdata-do-audit-and-prepare-to-migrate
-description: Full consistency/completeness audit of a project's central and recordkeeping files - OneDrive sync-conflict cleanup, cross-checking every index/register/log against what it claims to describe, and a pdata-migration readiness pass. Ends by writing a readiness manifest file that the companion `pm-pdata-do-migrate` skill consumes to actually run the migration. Triggers on "review all my central files", "audit the project files", "check everything is up to date and consistent", "get this project ready for pdata", "/pm-pdata-do-audit-and-prepare-to-migrate", or any request for a thorough review/health-check of a project's index/log/register files (as opposed to a single-session wrap-up, which is pm-update-central-files). Especially relevant when a project is scheduled to migrate to pdata - this audit is the recommended prerequisite pass, since a schema design should not be built against files that still have unresolved sync-conflict duplicates or known dangling rows.
+description: Full consistency/completeness audit of a project's central and recordkeeping files - OneDrive sync-conflict cleanup, cross-checking every index/register/log against what it claims to describe, and a pdata-migration readiness pass. Ends by writing a readiness manifest file that feeds `ccst pdata init` (via `pm-project-init`) - the tool-native migration mechanism - and, only for the narrow record shapes it can't express, the deprecated `pm-pdata-do-manual-migration` fallback. Triggers on "review all my central files", "audit the project files", "check everything is up to date and consistent", "get this project ready for pdata", "/pm-pdata-do-audit-and-prepare-to-migrate", or any request for a thorough review/health-check of a project's index/log/register files (as opposed to a single-session wrap-up, which is pm-update-central-files). Especially relevant when a project is scheduled to migrate to pdata - this audit is the recommended prerequisite pass, since a schema design should not be built against files that still have unresolved sync-conflict duplicates or known dangling rows.
 ---
 
 # Audit central files
 
+> **This audit feeds `ccst pdata init`, not a manual migration.** The readiness manifest this
+> skill produces (Phase 5) is a pre-flight pass for `ccst pdata init` (driven by the
+> `pm-project-init` skill) - the tool-native, default migration mechanism. `pm-pdata-do-manual-migration`
+> is a deprecated fallback for record shapes `ccst pdata init` genuinely can't express; it is not
+> the default next step after this audit.
+
 ## When to use this vs. `pm-update-central-files`
 
 `pm-update-central-files` is a lightweight, single-session wrap-up: rewrite WORKLOG, apply
@@ -115,7 +121,7 @@ Give the user a single reviewable delete script for every confirmed-safe deletio
 ## Phase 4: pdata-readiness pass
 
 Compile a dedicated `pdata-readiness-notes.md` (or equivalent) listing, file by file, every
-blocker a future `pm-pdata-schema-design` session would hit if it tried to design a schema
+blocker a future `pm-pdata-design-schema` session would hit if it tried to design a schema
 against the file as it currently stands:
 
 - Inconsistent separator/delimiter use within one logical column.
@@ -131,10 +137,10 @@ against the file as it currently stands:
   means something different from a genuinely blank one).
 
 This file is deliberately NOT a migration plan - it's a findings list for whoever runs the actual
-`pm-pdata-schema-design` session next, so that work isn't designed against a still-messy
+`pm-pdata-design-schema` session next, so that work isn't designed against a still-messy
 substrate.
 
-## Phase 5: write the readiness manifest (for `pm-pdata-do-migrate` to consume)
+## Phase 5: write the readiness manifest (for `ccst pdata init`/`pm-project-init` to consume)
 
 Once the audit reaches a settled state (per your own stopping rule - typically two consecutive
 clean verification rounds, or a documented pragmatic stop), write one machine-and-human-readable
@@ -145,7 +151,9 @@ otherwise the project's own top-level docs location. Its existence and location
 recorded in the project's own instructions file (`CLAUDE.md`/`AGENTS.md`/equivalent) so a future
 session doesn't have to search for it.
 
-The manifest must have, in this order, so `pm-pdata-do-migrate` can parse it deterministically:
+The manifest must have, in this order, so a `pm-project-init` session running `ccst pdata init`
+(or, for the narrow record shapes it can't express, the deprecated `pm-pdata-do-manual-migration`
+fallback) can parse it deterministically:
 
 1. **Header**: audit date, session/agent identifier, and an explicit "STALE IF" note - state the
    condition that would invalidate this manifest (e.g. "stale if any of the files below have
@@ -153,8 +161,8 @@ The manifest must have, in this order, so `pm-pdata-do-migrate` can parse it det
 2. **File inventory**: every central/index/recordkeeping file the audit covered, with: full path,
    row/entry count, last-verified-clean date, and its role (`index`, `register`, `log`,
    `narrative`, `derived-artefact`).
-3. **Per-file migration blockers**, in the exact shape `pm-pdata-schema-design` and
-   `pm-pdata-do-migrate` expect to consume - this is the same content this skill's own Phase 4
+3. **Per-file migration blockers**, in the exact shape `pm-pdata-design-schema` and
+   `pm-project-init` expect to consume - this is the same content this skill's own Phase 4
    already produces, just formalised into the manifest rather than a standalone prose report:
    inconsistent separators, unstable/non-existent natural keys, mixed date formats, multi-schema
    single files, machine-specific paths, null-value conventions that aren't real nulls.
@@ -165,7 +173,8 @@ The manifest must have, in this order, so `pm-pdata-do-migrate` can parse it det
    a migration pass doesn't waste time re-flagging it or, worse, silently drops one copy.
 6. **Open decisions** - anything the audit found but explicitly did NOT resolve because it needed
    the project owner's judgement (scope calls, curation completeness, which of two forks is
-   canonical). List these plainly; `pm-pdata-do-migrate` must not treat an unresolved item as settled.
+   canonical). List these plainly; a later migration session must not treat an unresolved item as
+   settled.
 
 ## Common mistakes
 

{cc_session_tools-3.2.1/src/cc_session_tools/skills/pm-pdata-do-migrate → cc_session_tools-3.3.1/src/cc_session_tools/skills/pm-pdata-do-manual-migration}/SKILL.md

@@ -1,17 +1,33 @@
 ---
-name: pm-pdata-do-migrate
-description: Execute a project's actual migration from flat central/index files to a ccst pdata record store - build a migration plan, adversarially verify the plan itself, present it for the user's confirmation, then execute it and write a results file. Consumes the readiness manifest pm-pdata-do-audit-and-prepare-to-migrate produces if one exists, but always explores the project independently too, so it works even without that manifest. Triggers on "migrate this project to pdata", "run the pdata migration", "/pm-pdata-do-migrate", or any request to actually move a project's CSV/index/log files into pdata (as opposed to just auditing readiness, which is pm-pdata-do-audit-and-prepare-to-migrate, or designing the target schema in the abstract, which is pm-pdata-schema-design).
+name: pm-pdata-do-manual-migration
+description: Execute a project's actual migration from flat central/index files to a ccst pdata record store - build a migration plan, adversarially verify the plan itself, present it for the user's confirmation, then execute it and write a results file. Consumes the readiness manifest pm-pdata-do-audit-and-prepare-to-migrate produces if one exists, but always explores the project independently too, so it works even without that manifest. Triggers on "migrate this project to pdata", "run the pdata migration", "/pm-pdata-do-manual-migration", or any request to actually move a project's CSV/index/log files into pdata (as opposed to just auditing readiness, which is pm-pdata-do-audit-and-prepare-to-migrate, or designing the target schema in the abstract, which is pm-pdata-design-schema).
 ---
 
-# Migrate a project to pdata
+# Manually migrate a project to pdata (deprecated fallback)
+
+> **Deprecated fallback — `ccst pdata init` is the standard mechanism.** `ccst pdata init`
+> (driven by the `pm-project-init` skill) is the tool-native migration mechanism: classification,
+> a human-reviewable manifest, backup, verify, atomic cutover, and shipped post-write doc/skill-
+> update prompts. It is the default choice wherever it is available, and this skill is superseded
+> by it for any file `ccst pdata init`'s classifier can already handle (a normal CSV/JSON file
+> with a real header row). This skill remains only as a deprecated manual fallback for the narrow
+> case where the programmatic approach genuinely doesn't fit - e.g. a record shape none of `ccst
+> pdata init`'s five import strategies (`whole-file`, `delimited-sections`, `csv-rows`,
+> `json-array-rows`, `json-singleton`) can express.
+>
+> **Before doing anything else, stop and get the user's explicit confirmation** that: (a) they
+> understand `ccst pdata init` is the standard, tool-native mechanism and this skill is a
+> deprecated fallback; and (b) they have a specific reason the programmatic approach doesn't fit
+> this case. Do not proceed to Step 1, or any later step, without that confirmation - if the user
+> hasn't already stated a reason, ask them for one before continuing.
 
 ## When to use this vs. the other pm-pdata-* skills
 
 - `pm-pdata-do-audit-and-prepare-to-migrate` - readiness audit. Finds and fixes problems in the CURRENT flat files.
   Produces a readiness manifest. Does not touch pdata at all.
-- `pm-pdata-schema-design` - designs the TARGET record-group schema in the abstract (field names,
+- `pm-pdata-design-schema` - designs the TARGET record-group schema in the abstract (field names,
   types, groupings) before any data moves.
-- `pm-pdata-do-migrate` (this skill) - takes whatever schema exists (designed via the skill above,
+- `pm-pdata-do-manual-migration` (this skill) - takes whatever schema exists (designed via the skill above,
   or designed inline as part of this skill's own plan if no separate design session happened) and
   actually moves the data: `ccst pdata add`/`batch` calls, verification, and a results record.
 
@@ -43,7 +59,7 @@ audit pass would.
 
 ## Step 2: design or confirm the target schema
 
-For each central file being migrated, decide (or confirm, if `pm-pdata-schema-design` already
+For each central file being migrated, decide (or confirm, if `pm-pdata-design-schema` already
 ran):
 
 - **Record group name** - typically the file's own conceptual name (`correspondence-log`,

{cc_session_tools-3.2.1/src/cc_session_tools/skills/pm-pdata-conflict-resolution → cc_session_tools-3.3.1/src/cc_session_tools/skills/pm-pdata-resolve-conflicts}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pm-pdata-conflict-resolution
+name: pm-pdata-resolve-conflicts
 description: Use immediately when `ccst pdata update` or `ccst pdata delete` exits 3 (a version conflict) - takes the CLI's current-vs-attempted diff and presents it to Chris for reconciliation, per spec §6.2's "the session asks Chris how to reconcile" contract. Also use when `ccst pdata resolve` reports a cross-machine fork (a `.pdata-db-dump` conflict between two laptops), or phrasing like "pdata update conflict", "version conflict on a record", "someone else already updated this row", "sync conflict", "pdata fork between machines". Never auto-retries, never silently picks a side, never discards either version.
 ---