cc-session-tools 3.2.0__tar.gz → 3.3.0__tar.gz

{cc_session_tools-3.2.0/src/cc_session_tools.egg-info → cc_session_tools-3.3.0}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-session-tools"
-version = "3.2.0"
+version = "3.3.0"
 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.0 → cc_session_tools-3.3.0}/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.0/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.0 → cc_session_tools-3.3.0}/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.0 → cc_session_tools-3.3.0}/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.0 → cc_session_tools-3.3.0}/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.0 → cc_session_tools-3.3.0}/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.0 → cc_session_tools-3.3.0}/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-migrate` 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-migrate`
+> 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
@@ -134,7 +140,7 @@ This file is deliberately NOT a migration plan - it's a findings list for whoeve
 `pm-pdata-schema-design` 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-migrate`
+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
@@ -154,7 +162,7 @@ The manifest must have, in this order, so `pm-pdata-do-migrate` can parse it det
    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
+   `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.0 → cc_session_tools-3.3.0}/src/cc_session_tools/skills/pm-pdata-do-migrate/SKILL.md

@@ -5,6 +5,22 @@ description: Execute a project's actual migration from flat central/index files
 
 # Migrate a project to pdata
 
+> **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.

{cc_session_tools-3.2.0 → cc_session_tools-3.3.0}/src/cc_session_tools/skills/pm-project-init/SKILL.md

@@ -62,6 +62,51 @@ that renames a `record_group` to match an existing one is **not** re-checked. Be
 proposal, scan it yourself for two entries sharing a `record_group` that you did not deliberately
 intend to merge.
 
+### Watch for garbled CSV headers
+
+A CSV whose first row is actually prose/provenance text (a `#`-prefixed comment, or a multi-
+sentence caveat wrapped in CSV quoting) rather than real column names produces a `[db-owned]`
+entry whose proposed field names read as garbled sentence fragments (e.g.
+`pending_chris_s_manual_review`, `generated_2026_08_12_do_not_edit`) rather than short domain
+nouns - syntactically valid-looking identifiers that don't obviously scream "wrong" on a fast
+skim. The dry-run report flags a likely case of this automatically (a "worth double-checking"
+annotation on the entry's line), but always eyeball field-name **shape**, not just presence, for
+every `[db-owned]` entry - the annotation is a heuristic, not a guarantee.
+
+The content on a garbled header line is usually legitimate and valuable (provenance/caveat text a
+later reader genuinely needs), not junk to discard. Fix recipe:
+
+1. Read past the suspect first line to confirm a clean, comma-separated real header exists
+   further down (usually line 2).
+2. Strip the bad line(s) from the source CSV, preserving the removed text exactly - you'll need it
+   in step 4.
+3. Correct the manifest entry: fix `fields` to match the real header, set a real `content_column`,
+   confirm `classification: db-owned`.
+4. Set the entry's `preface_text` field (in `.pdata-migration-manifest.json`) to the exact text you
+   removed in step 2. `--write`'s cutover step carries this into the entry's pointer file (Step 7)
+   automatically, under its own heading - you don't need to compose that by hand.
+
+### Also check every `db-owned` entry against two deferred-file criteria
+
+Beyond field-name shape, review every `db-owned` entry (not just folder-owned markdown/text files)
+against two further questions before approving the proposal - a structurally clean CSV can still
+be a poor migration candidate for reasons the classifier has no way to know about:
+
+- **Does this file live somewhere the project's own docs say only a human should touch?** (e.g. a
+  `references/` folder documented as "only Chris adds/removes/reorganises files here"). Migrating
+  it moves the original out of that folder as part of cutover, which conflicts with the folder's
+  documented purpose. If so, flip the entry to `folder-owned` and flag it explicitly to Chris as a
+  real open decision - do not silently include or silently exclude it.
+- **How does this source file actually get updated going forward - incrementally appended, or
+  periodically replaced wholesale with a fresh full export?** An append-only file (new rows added
+  over time, however often) is a good migration candidate regardless of update frequency. A file
+  whose maintenance model is "drop in a new full export periodically" is a poor candidate under
+  the current tooling even if the CSV itself is clean: `ccst pdata` has no bulk-replace/upsert
+  verb, so every future refresh would mean soft-deleting every old record and individually
+  re-adding every new one, one CLI call per row. Flag this distinction explicitly to Chris rather
+  than deciding it unilaterally - the append-vs-wholesale-replacement axis, not update frequency,
+  is what actually matters here.
+
 ## 4. Hand-edit the proposal to encode overrides
 
 Edit `.pdata-migration-manifest.json` directly (or the legacy `.ccst-pdata-proposal.json` name,
@@ -90,6 +135,25 @@ Two entries may legitimately feed the same `record_group`, but if they share a f
 must give it the same `sql_type` - `--write` rejects a mismatched pair up front rather than
 silently dropping one side's type.
 
+**`file_path_column` pitfall:** don't map `file_path_column` directly to a column whose values are
+relative to a subfolder rather than the project root (e.g. an index-of-a-subfolder CSV like
+`references/INDEX.csv` whose own `file_path` column is relative to `references/`, not the project
+root) - `--write`'s file_path-resolution verification will fail with a bare "does not resolve
+under `<project_root>`" and no further guidance. Instead, map that column to a plain named field
+(e.g. `source_file_path`) and note in the field's `description` what path it's relative to.
+
+**`content_column: null` default caveat:** an entry with `content_column` left unset falls back to
+a raw `json.dumps(row)` dump as every record's content - rarely what you want for readable `ccst
+pdata list` output. Actively choose a real narrative column for every `db-owned` entry before
+`--write`; don't accept the JSON-blob default by omission.
+
+**Value transforms the generic importer can't express:** a computed field (e.g. an `is_canonical`
+flag for a known duplicate key) or splitting one source column into two has no 1:1 mapping in
+`csv-rows`. Don't try to force it into the manifest - import the entry normally via `csv-rows`
+first, then apply a post-`--write` `ccst pdata schema add-field` (to add the new field) followed
+by a per-record `ccst pdata update` pass (to populate it). This is the standard recipe for any
+field the source file doesn't already carry as its own column.
+
 Never delete the proposal file to "start over" without good reason - doing so discards every
 override made so far. If new files appear in the project after the first dry run, add entries for
 them by hand rather than deleting and reclassifying everything.
@@ -102,6 +166,14 @@ explicit approval. **Never invoke `--write` without it.**
 
 ## 6. Run the write phase
 
+A real migration of an existing, non-trivial project is typically **iterative, not a single
+terminal `--write`**: expect multiple `--write` rounds as source files get fixed (garbled
+headers), deferred decisions get resolved, and corrected entries get re-approved. Don't plan for
+or promise a one-shot `--write`. A `--write` round only ever imports entries with no `migrated_at`
+already set - entries already cut over by an earlier successful `--write` are skipped
+automatically, so a later round picking up newly-fixed or newly-added files is safe to run without
+re-touching what already migrated.
+
 ```sh
 ccst pdata init --project <project> [--rehearse <path>] --write
 ```
@@ -132,6 +204,12 @@ Archived originals live at `<project-root>/.pdata-migrated/` and are **never aut
 himself - that WARN is expected and not urgent. Do not delete the archive without his explicit
 instruction.
 
+By default, `--write` also leaves a `.md` pointer file at each cut-over entry's original path
+(record_group, field/schema table, an example query command, and any preserved preface text - see
+Step 3's garbled-header recipe) - so anything else in the project citing the old path by name finds
+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).
+
 ## 8. Rollback, if something's found wrong post-cutover
 
 There is no `--rollback` flag. Recover by hand:
@@ -149,6 +227,11 @@ There is no `--rollback` flag. Recover by hand:
 3. Fix whatever was wrong in the proposal (classification, strategy, field mapping) before
    re-attempting.
 
+A genuine intentional re-migration of an entry (e.g. after restoring the backup and deciding to
+redo it) also requires clearing that entry's `migrated_at` field by hand in the manifest, alongside
+the DB/proposal fixes above - `--write` otherwise skips any entry that already carries one (Step 6),
+by design, so it won't be re-imported until you do.
+
 ## Never do without explicit Chris approval
 
 - Invoke `--write` on an unreviewed proposal.

{cc_session_tools-3.2.0 → cc_session_tools-3.3.0}/src/cc_session_tools/skills/pm-project-layout-reference/SKILL.md

@@ -81,3 +81,25 @@ derivable per file. Topic-based splitting (`analysis/`, or any project-specific
 natural date) has no tool support and stays a manual `git mv`/`mv` pass, since grouping by topic
 needs human judgement the tool can't safely substitute for. Anything simpler than a split
 (renaming one folder, adding a new folder type) is also a plain `git mv`/`mv`.
+
+## 6. File-type-segment vocabulary for meetings-and-calls/
+
+Files within `meetings-and-calls/` follow a `--`-delimited naming convention:
+
+`<yyyy.MM.dd>-<HHmm>--<participants>--<purpose>--<file type>.<ext>`
+
+The `<file type>` segment recognises three core values, common enough to expect in any project
+with recorded meetings or calls:
+
+| File type | What it holds |
+|---|---|
+| `summary` | Auto-generated summary of the call (e.g. Plaud) |
+| `transcript` | Raw or auto-generated transcript of the call |
+| `audio` | The raw recording itself (`.mp3`/`.mp4`), before any transcription or summary exists |
+
+This isn't exhaustive - as with the five folders in §1, a project may extend the vocabulary with
+values for distinctions specific to its own work: `analysis` and `transcript-whisper` (maxella,
+for a session's own write-up of a meeting and a Whisper-generated transcript alongside the Plaud
+one), or `reasoning-summary` and `notes-email` (pbt, for a modelled reasoning summary and an
+emailed notes write-up). Promote a project-specific value to this shared list once it recurs
+across multiple projects - the same bar the five folders in §1 were held to.

{cc_session_tools-3.2.0 → cc_session_tools-3.3.0/src/cc_session_tools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 3.2.0
+Version: 3.3.0
 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.0 → cc_session_tools-3.3.0}/tests/test_ccst_pdata_init_cli.py

@@ -106,6 +106,35 @@ def test_pdata_init_write_end_to_end_imports_and_cuts_over(base_env, tmp_path):
     assert "first" in r_list.stdout and "second" in r_list.stdout
 
 
+def test_pdata_init_write_leaves_pointer_file_by_default(base_env, tmp_path):
+    project_dir = tmp_path / "projects" / "demo"
+    project_dir.mkdir(parents=True)
+    (project_dir / "ideas.csv").write_text("idea\nfirst\nsecond\n")
+    base_env["CCST_PDATA_BACKUP_DIR"] = str(tmp_path / "backups")
+
+    _run(base_env, "pdata", "init", "--project", "demo")
+    r_write = _run(base_env, "pdata", "init", "--project", "demo", "--write")
+
+    assert r_write.returncode == 0, r_write.stderr
+    pointer = project_dir / "ideas.md"
+    assert pointer.exists()
+    assert "ideas" in pointer.read_text()
+
+
+def test_pdata_init_write_leave_no_pointer_files_suppresses_pointer(base_env, tmp_path):
+    project_dir = tmp_path / "projects" / "demo"
+    project_dir.mkdir(parents=True)
+    (project_dir / "ideas.csv").write_text("idea\nfirst\nsecond\n")
+    base_env["CCST_PDATA_BACKUP_DIR"] = str(tmp_path / "backups")
+
+    _run(base_env, "pdata", "init", "--project", "demo")
+    r_write = _run(base_env, "pdata", "init", "--project", "demo", "--write",
+                   "--leave-no-pointer-files")
+
+    assert r_write.returncode == 0, r_write.stderr
+    assert not (project_dir / "ideas.md").exists()
+
+
 def test_pdata_init_write_without_prior_dry_run_errors(base_env, tmp_path):
     project_dir = tmp_path / "projects" / "demo"
     project_dir.mkdir(parents=True)

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

@@ -1,34 +0,0 @@
-"""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 archive_entries(*, project_root: Path, entries: list[ManifestEntry]) -> 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)."""
-    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"
-            )