cc-session-tools 3.7.1__tar.gz → 3.8.0__tar.gz

{cc_session_tools-3.7.1/src/cc_session_tools.egg-info → cc_session_tools-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 3.7.1
+Version: 3.8.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
@@ -928,6 +928,25 @@ ccst context-override off      # re-enable the warnings
 ccst context-override status   # report the current state
 ```
 
+### `ccst pdata readiness-scan`
+
+A read-only scan of a project's CSV files for the mechanical blockers to a `ccst pdata init`
+migration, used by the `pm-pdata-do-audit-and-prepare-to-migrate` skill and useful on its own:
+
+```sh
+ccst pdata readiness-scan --project myproject                 # compact Markdown report
+ccst pdata readiness-scan --project myproject --format json   # machine-readable
+ccst pdata readiness-scan --project myproject --path notes/ --findings-only   # one folder's findings
+```
+
+It reports ragged rows, empty/duplicate headers, mixed date formats, mixed `|`/`;` separators,
+machine-specific paths, null-like placeholder strings, duplicate rows, comment rows, repeated
+header rows, byte-order marks, CRLF line endings and unreadable files, plus a per-file inventory
+and the columns that are unique on every row. Findings carry counts and row numbers, never cell
+text, and a unique column is a fact rather than a recommended key. It exits 0 whenever the scan
+ran (findings are not failures), and 2 when the project directory does not exist. It scans exactly
+the CSVs `ccst pdata init` would classify.
+
 ### `ccst skills install`
 
 > You normally don't need this: `ccst install-everything --apply` runs it, and `ccst` runs that

{cc_session_tools-3.7.1 → cc_session_tools-3.8.0}/README.md

@@ -871,6 +871,25 @@ ccst context-override off      # re-enable the warnings
 ccst context-override status   # report the current state
 ```
 
+### `ccst pdata readiness-scan`
+
+A read-only scan of a project's CSV files for the mechanical blockers to a `ccst pdata init`
+migration, used by the `pm-pdata-do-audit-and-prepare-to-migrate` skill and useful on its own:
+
+```sh
+ccst pdata readiness-scan --project myproject                 # compact Markdown report
+ccst pdata readiness-scan --project myproject --format json   # machine-readable
+ccst pdata readiness-scan --project myproject --path notes/ --findings-only   # one folder's findings
+```
+
+It reports ragged rows, empty/duplicate headers, mixed date formats, mixed `|`/`;` separators,
+machine-specific paths, null-like placeholder strings, duplicate rows, comment rows, repeated
+header rows, byte-order marks, CRLF line endings and unreadable files, plus a per-file inventory
+and the columns that are unique on every row. Findings carry counts and row numbers, never cell
+text, and a unique column is a fact rather than a recommended key. It exits 0 whenever the scan
+ran (findings are not failures), and 2 when the project directory does not exist. It scans exactly
+the CSVs `ccst pdata init` would classify.
+
 ### `ccst skills install`
 
 > You normally don't need this: `ccst install-everything --apply` runs it, and `ccst` runs that

{cc_session_tools-3.7.1 → cc_session_tools-3.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-session-tools"
-version = "3.7.1"
+version = "3.8.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.7.1 → cc_session_tools-3.8.0}/src/cc_session_tools/cli/ccst.py

@@ -1858,6 +1858,28 @@ def _cmd_pdata_resolve(args: argparse.Namespace) -> int:
     return 1 if outstanding else 0
 
 
+def _cmd_pdata_readiness_scan(args: argparse.Namespace) -> int:
+    from cc_session_tools.lib.pdata import readiness, store
+
+    try:
+        root = store.project_root(args.project)
+    except ValueError as exc:
+        print(f"ccst pdata readiness-scan: {exc}", file=sys.stderr)
+        return 2
+    if not root.is_dir():
+        print(
+            f"ccst pdata readiness-scan: project directory does not exist: {root}",
+            file=sys.stderr,
+        )
+        return 2
+    report = readiness.scan_project(root, path_prefix=args.path)
+    if args.format == "json":
+        print(readiness.format_json(report))
+    else:
+        print(readiness.format_markdown(report, findings_only=args.findings_only))
+    return 0
+
+
 def _cmd_pdata_sync_check(args: argparse.Namespace) -> int:
     """The spec's "Hourly `ccsched` job" trigger: per project, rehydrate-check and - only if no
     rehydrate happened - dump-check. The whole decision lives in `pdata.sync_check` (shared with
@@ -3256,6 +3278,24 @@ def _build_parser() -> argparse.ArgumentParser:
              "the default one-line summary (--project always prints full detail)",
     )
 
+    pdata_readiness_parser = pdata_sub.add_parser(
+        "readiness-scan",
+        help="Scan a project's CSVs for pdata-migration blockers (read-only)",
+    )
+    pdata_readiness_parser.add_argument("--project", metavar="NAME", required=True)
+    pdata_readiness_parser.add_argument(
+        "--format", choices=("markdown", "json"), default="markdown",
+        help="Output format (default: markdown)",
+    )
+    pdata_readiness_parser.add_argument(
+        "--path", metavar="PREFIX", default=None,
+        help="Only scan CSVs whose project-relative path starts with PREFIX",
+    )
+    pdata_readiness_parser.add_argument(
+        "--findings-only", action="store_true",
+        help="Omit the per-file inventory from the Markdown report",
+    )
+
     pdata_dump_parser = pdata_sub.add_parser(
         "dump", help="Publish the current local DB state to .pdata-db-dump/latest.sql"
     )
@@ -3659,6 +3699,8 @@ def main() -> None:
             sys.exit(_cmd_pdata_reconcile_session_output(args))
         if args.verb == "verify":
             sys.exit(_cmd_pdata_verify(args))
+        if args.verb == "readiness-scan":
+            sys.exit(_cmd_pdata_readiness_scan(args))
         if args.verb == "dump":
             sys.exit(_cmd_pdata_dump(args))
         if args.verb == "rehydrate":

cc_session_tools-3.8.0/src/cc_session_tools/lib/pdata/readiness.py

@@ -0,0 +1,319 @@
+"""Deterministic pdata-readiness scan of a project's CSV files (`ccst pdata readiness-scan`).
+
+Reports the mechanical blockers a migration audit would otherwise find by reading: ragged rows,
+mixed date formats, mixed separators, machine-specific paths, fake nulls, duplicates, BOM/CRLF and
+unreadable files, plus a per-file inventory and unique-column facts. Read-only: the scan never
+writes. Findings carry counts and 1-based data-record numbers (header excluded), never cell text;
+`unreadable` reasons are a fixed vocabulary, so file content cannot reach a report.
+"""
+from __future__ import annotations
+
+import csv
+import io
+import json
+import os
+import re
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from cc_session_tools.lib.pdata.init_paths import EXCLUDED_DIR_NAMES
+
+FINDING_KINDS: tuple[str, ...] = (
+    "ragged-rows", "machine-paths", "null-strings", "duplicate-rows", "comment-rows",
+    "repeated-header", "mixed-date-formats", "mixed-separators", "bad-header",
+    "no-unique-column", "unreadable", "bom", "crlf",
+)
+
+MAX_EXAMPLE_ROWS = 3
+FREE_TEXT_MEAN_LENGTH = 64
+NULL_STRINGS = frozenset({"NO DATA", "N/A", "NA", "NULL", "NONE", "TBD", "UNKNOWN", "-", "--", "?"})
+_MACHINE_PATH = re.compile(r"/Users/[^/\s]+|/home/[^/\s]+|/mnt/[a-z]/|[A-Za-z]:\\Users\\")
+_DATE_FORMATS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("iso-datetime", re.compile(r"^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}")),
+    ("iso-date", re.compile(r"^\d{4}-\d{2}-\d{2}$")),
+    ("slash", re.compile(r"^\d{1,2}/\d{1,2}/\d{2,4}$")),
+    ("d-month-yyyy", re.compile(r"^\d{1,2} [A-Za-z]{3,9} \d{4}$")),
+    ("month-d-yyyy", re.compile(r"^[A-Za-z]{3,9} \d{1,2},? \d{4}$")),
+)
+_BOM = b"\xef\xbb\xbf"
+
+
+@dataclass(frozen=True)
+class Finding:
+    kind: str
+    file: str
+    column: str | None = None
+    count: int | None = None
+    rows: tuple[int, ...] = ()
+    detail: tuple[tuple[str, int | str], ...] = ()
+
+
+@dataclass(frozen=True)
+class UniqueColumn:
+    name: str
+    labels: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class FileReport:
+    path: str
+    rows: int
+    columns: int
+    header: tuple[str, ...]
+    unique_columns: tuple[UniqueColumn, ...]
+
+
+@dataclass(frozen=True)
+class ReadinessReport:
+    files: tuple[FileReport, ...]
+    findings: tuple[Finding, ...]
+    not_scanned: dict[str, int]
+
+
+class _Unreadable(Exception):
+    def __init__(self, reason: str) -> None:
+        super().__init__(reason)
+        self.reason = reason
+
+
+def _is_real_yyyymmdd(value: str) -> bool:
+    if not re.fullmatch(r"\d{8}", value):
+        return False
+    try:
+        parsed = datetime.strptime(value, "%Y%m%d")
+    except ValueError:
+        return False
+    return 1900 <= parsed.year <= 2100
+
+
+def _date_format(value: str) -> str | None:
+    for name, pattern in _DATE_FORMATS:
+        if pattern.match(value):
+            return name
+    return "yyyymmdd" if _is_real_yyyymmdd(value) else None
+
+
+def _walk(root: Path) -> list[Path]:
+    """Every file under root outside EXCLUDED_DIR_NAMES, without following directory symlinks -
+    the same exclusion set `ccst pdata init`'s classifier uses, so coverage matches migration."""
+    found: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
+        dirnames[:] = sorted(d for d in dirnames if d not in EXCLUDED_DIR_NAMES)
+        found.extend(Path(dirpath) / name for name in sorted(filenames))
+    return found
+
+
+def _parse(raw: bytes) -> tuple[list[list[str]], bool, bool]:
+    if not raw:
+        raise _Unreadable("empty-file")
+    try:
+        text = raw.decode("utf-8-sig")
+    except UnicodeDecodeError:
+        raise _Unreadable("not-utf8") from None
+    if not text.strip():
+        raise _Unreadable("empty-file")
+    try:
+        records = list(csv.reader(io.StringIO(text, newline=""), strict=True))
+    except csv.Error as exc:
+        raise _Unreadable(
+            "field-too-large" if "field larger" in str(exc) else "csv-parse-error"
+        ) from None
+    return records, raw.startswith(_BOM), b"\r\n" in raw
+
+
+def _scan_file(rel: str, raw: bytes) -> tuple[FileReport | None, list[Finding]]:
+    try:
+        records, has_bom, has_crlf = _parse(raw)
+    except _Unreadable as exc:
+        return None, [Finding("unreadable", rel, detail=(("reason", exc.reason),))]
+
+    findings: list[Finding] = []
+    if has_bom:
+        findings.append(Finding("bom", rel))
+    if has_crlf:
+        findings.append(Finding("crlf", rel))
+
+    header = records[0]
+    ncols = len(header)
+    if any(not h.strip() for h in header) or len(set(header)) != ncols:
+        findings.append(Finding("bad-header", rel))
+
+    data = [r for r in records[1:] if r]
+    nonempty = [0] * ncols
+    lengths = [0] * ncols
+    distinct: list[set[str]] = [set() for _ in range(ncols)]
+    all_int = [True] * ncols
+    dates: list[dict[str, int]] = [{} for _ in range(ncols)]
+    seps: list[dict[str, int]] = [{} for _ in range(ncols)]
+    nulls: list[dict[str, int]] = [{} for _ in range(ncols)]
+    null_rows: list[list[int]] = [[] for _ in range(ncols)]
+    path_rows: list[list[int]] = [[] for _ in range(ncols)]
+    ragged: list[int] = []
+    dup_rows: list[int] = []
+    comment_rows: list[int] = []
+    header_rows: list[int] = []
+    seen_rows: set[tuple[str, ...]] = set()
+
+    for number, row in enumerate(data, start=1):
+        if row == header:
+            header_rows.append(number)
+        if row[0].startswith("#"):
+            comment_rows.append(number)
+        if len(row) != ncols:
+            ragged.append(number)
+        key = tuple(row)
+        if key in seen_rows:
+            dup_rows.append(number)
+        seen_rows.add(key)
+        for i, value in enumerate(row[:ncols]):
+            if not value.strip():
+                continue
+            nonempty[i] += 1
+            lengths[i] += len(value)
+            distinct[i].add(value)
+            if not re.fullmatch(r"-?\d+", value.strip()):
+                all_int[i] = False
+            fmt = _date_format(value.strip())
+            if fmt:
+                dates[i][fmt] = dates[i].get(fmt, 0) + 1
+            for sep in ("|", ";"):
+                if sep in value:
+                    seps[i][sep] = seps[i].get(sep, 0) + 1
+            token = value.strip().upper()
+            if token in NULL_STRINGS:
+                nulls[i][token] = nulls[i].get(token, 0) + 1
+                null_rows[i].append(number)
+            if _MACHINE_PATH.search(value):
+                path_rows[i].append(number)
+
+    def row_finding(kind: str, rows: list[int], column: str | None = None,
+                    detail: tuple[tuple[str, int | str], ...] = ()) -> Finding:
+        return Finding(kind, rel, column, len(rows), tuple(rows[:MAX_EXAMPLE_ROWS]), detail)
+
+    if ragged:
+        findings.append(row_finding("ragged-rows", ragged))
+    if dup_rows:
+        findings.append(row_finding("duplicate-rows", dup_rows))
+    if comment_rows:
+        findings.append(row_finding("comment-rows", comment_rows))
+    if header_rows:
+        findings.append(row_finding("repeated-header", header_rows))
+    for i, name in enumerate(header):
+        if len(dates[i]) >= 2:
+            findings.append(Finding("mixed-date-formats", rel, name,
+                                    detail=tuple(sorted(dates[i].items()))))
+        if len(seps[i]) == 2:
+            findings.append(Finding("mixed-separators", rel, name,
+                                    detail=tuple(sorted(seps[i].items()))))
+        if path_rows[i]:
+            findings.append(row_finding("machine-paths", path_rows[i], name))
+        if null_rows[i]:
+            findings.append(row_finding("null-strings", null_rows[i], name,
+                                        tuple(sorted(nulls[i].items()))))
+
+    unique: list[UniqueColumn] = []
+    if len(data) >= 2:
+        for i, name in enumerate(header):
+            if nonempty[i] == len(data) and len(distinct[i]) == len(data):
+                labels: list[str] = []
+                if all_int[i]:
+                    labels.append("integer-like")
+                if lengths[i] / len(data) > FREE_TEXT_MEAN_LENGTH:
+                    labels.append("free-text")
+                unique.append(UniqueColumn(name, tuple(labels)))
+        if not unique:
+            findings.append(Finding("no-unique-column", rel))
+
+    return FileReport(rel, len(data), ncols, tuple(header), tuple(unique)), findings
+
+
+def scan_project(root: Path, *, path_prefix: str | None = None) -> ReadinessReport:
+    files: list[FileReport] = []
+    findings: list[Finding] = []
+    not_scanned = {"json": 0, "markdown": 0, "other": 0}
+    for abs_path in _walk(root):
+        rel = abs_path.relative_to(root).as_posix()
+        if path_prefix and not rel.startswith(path_prefix):
+            continue
+        suffix = abs_path.suffix.lower()
+        if suffix != ".csv":
+            bucket = {".json": "json", ".md": "markdown", ".markdown": "markdown"}.get(suffix, "other")
+            not_scanned[bucket] += 1
+            continue
+        report, file_findings = _scan_file(rel, abs_path.read_bytes())
+        if report is not None:
+            files.append(report)
+        findings.extend(file_findings)
+    findings.sort(key=lambda f: (f.file, FINDING_KINDS.index(f.kind), f.column or ""))
+    return ReadinessReport(tuple(files), tuple(findings), not_scanned)
+
+
+def _finding_line(f: Finding) -> str:
+    parts = [f"- {f.kind}: {f.file}"]
+    if f.column is not None:
+        parts.append(f"column {f.column!r}")
+    if f.count is not None:
+        parts.append(f"count={f.count}")
+    if f.rows:
+        parts.append("rows=" + ",".join(str(r) for r in f.rows))
+    if f.detail:
+        parts.append(", ".join(f"{k}={v}" for k, v in f.detail))
+    return "  ".join(parts)
+
+
+def format_markdown(report: ReadinessReport, *, findings_only: bool = False) -> str:
+    ns = report.not_scanned
+    lines = [
+        "# pdata readiness scan",
+        "",
+        "Row numbers are 1-based data records (header excluded), not line numbers: a quoted "
+        "multiline cell makes them differ.",
+        f"Scanned {len(report.files)} CSV file(s); not scanned: {ns['json']} JSON, "
+        f"{ns['markdown']} Markdown, {ns['other']} other.",
+    ]
+    if not report.files and not any(f.kind == "unreadable" for f in report.findings):
+        lines += ["", "No CSV files found."]
+    lines += ["", "## Findings"]
+    lines += [_finding_line(f) for f in report.findings] or ["No findings."]
+    if not findings_only and report.files:
+        lines += [
+            "",
+            "## Inventory",
+            "A unique column is a fact, not a recommended key: it is not a stable key until a "
+            "human has confirmed its values are not re-numbered per session or machine.",
+        ]
+        for f in report.files:
+            unique = ", ".join(
+                u.name + (f" ({'/'.join(u.labels)})" if u.labels else "") for u in f.unique_columns
+            )
+            lines.append(
+                f"- {f.path}: {f.rows} rows, {f.columns} columns"
+                + (f"; unique: {unique}" if unique else "")
+            )
+    return "\n".join(lines)
+
+
+def format_json(report: ReadinessReport) -> str:
+    return json.dumps(
+        {
+            "files": [
+                {
+                    "path": f.path, "rows": f.rows, "columns": f.columns,
+                    "header": list(f.header),
+                    "unique_columns": [{"name": u.name, "labels": list(u.labels)}
+                                       for u in f.unique_columns],
+                }
+                for f in report.files
+            ],
+            "findings": [
+                {
+                    "kind": f.kind, "file": f.file, "column": f.column, "count": f.count,
+                    "rows": list(f.rows), "detail": dict(f.detail),
+                }
+                for f in report.findings
+            ],
+            "not_scanned": report.not_scanned,
+        },
+        indent=2,
+    )

cc_session_tools-3.8.0/src/cc_session_tools/skills/pm-pdata-do-audit-and-prepare-to-migrate/SKILL.md

@@ -0,0 +1,162 @@
+---
+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 feeds `ccst pdata init` (via `pm-pdata-do-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 (Phase 5)
+> is a pre-flight pass for `ccst pdata init` (driven by `pm-pdata-do-init`), the default migration
+> mechanism. `pm-pdata-do-manual-migration` is a deprecated fallback for record shapes `ccst pdata
+> init` cannot express, not the default next step.
+
+## When to use this vs. `pm-update-central-files`
+
+`pm-update-central-files` is a single-session wrap-up (WORKLOG, memory, registering new `out/`
+files). This skill is a project-wide sweep of every central file (indexes, logs, registers, CSVs),
+run on demand, that can span a session or more. Use it when the whole project's recordkeeping needs
+a health check, not just today's session tidied up.
+
+## Overview
+
+Five phases, each leaving a durable artefact. Four things called "readiness" are distinct:
+the scan (`ccst pdata readiness-scan`, computed on demand), `pdata-readiness-notes.md` (Phase 4's
+findings list), the Phase 5 manifest (`analysis/pdata-readiness.md` or equivalent), and
+`.pdata-migration-manifest.json` (`ccst pdata init`'s own classification, not written here).
+
+1. **OneDrive sync-conflict cleanup** (synced folders only).
+2. **Readiness scan, then judgement audit** of each central-file domain.
+3. **Consolidated report + checkpoint table.**
+4. **pdata-readiness pass:** every blocker, file by file.
+5. **Readiness manifest** for `ccst pdata init`.
+
+Nothing destructive happens without the user's go-ahead. Deletions are always handed over as a
+reviewable `rm` script, per `resolve-onedrive-conflicts`; never run `rm` yourself, even after
+approval.
+
+## Phase 1: OneDrive sync-conflict cleanup
+
+Invoke `resolve-onedrive-conflicts` and run its scanner across the project tree; run it before
+anything else so stale device-suffixed copies do not pollute later phases. Treat a
+disproportionate `true_conflict` count as a scanner false-positive to investigate (the hyphen
+heuristic can match a project's own multi-hyphen naming) and filter to genuine device-suffix
+conflicts before trusting it. Split them into **central/index files** (a handful, reviewable
+directly) and **bulk content files** (dozens or hundreds; give them their own agent with the
+file list).
+
+## Phase 2: readiness scan, then judgement audit
+
+**Step 1 - run the scan before any per-domain checking or agent dispatch:**
+
+```
+ccst pdata readiness-scan --project <name>            # whole project, compact Markdown
+ccst pdata readiness-scan --project <name> --format json
+ccst pdata readiness-scan --project <name> --path <domain-dir>/ --findings-only   # one domain's slice
+```
+
+It is read-only and deterministic. It reports, per CSV, `ragged-rows`, `bad-header`,
+`mixed-date-formats`, `mixed-separators` (`|` with `;` only), `machine-paths`, `null-strings`,
+`duplicate-rows`, `comment-rows`, `repeated-header`, `no-unique-column`, `bom`, `crlf` and
+`unreadable`, plus row counts and unique columns. Treat findings as leads to verify, not facts to
+act on (a lone `-` may be a real dash). Its scanned set equals what `ccst pdata init` will
+classify. Row numbers are data records, not line numbers.
+
+A **unique column is not a stable key.** Whether it is one is a judgement, and the scan is input
+to that judgement, not its answer: watch especially for `row_id`-style columns numbered
+independently by different sessions or machines - these are NOT stable keys even though they look
+like them. A `bom` is what turns a header garbled
+under `ccst pdata init`; `crlf` is worth normalising first.
+
+**Step 2 - judgement audit.** Group the central files the project's own instructions document,
+plus anything on disk that is not documented (itself a gap), into domains (usually one per
+top-level folder with its own index). With **three or fewer domains**, audit them yourself in one
+pass. With **more than three**, dispatch one Sonnet-tier agent per domain in parallel, per
+`dispatching-parallel-agents` and `select-agent-model`, giving each only its own domain's scan
+slice (`--path`, `--findings-only`). Agents check, with concrete evidence for every claim:
+
+- **File-to-index correspondence:** every file an index describes exists; every file that should be
+  indexed has a row.
+- **Controlled vocabularies:** any documented enum column uses only documented values.
+- **Cross-reference integrity:** every row_id or back-reference resolves.
+- **Documented but missing:** every file or folder the project's instructions describe exists. This
+  rot is common and durable because a merely-referenced file that is absent breaks nothing loudly.
+- **Derived-artefact completeness:** each source has its documented mirror, and no mirror is
+  silently empty.
+- **Own-documentation accuracy:** every path, count and reference in an atlas or index-of-indexes
+  checked against the live filesystem.
+- **The scan's blind spots:** multi-schema single files (comment banners, section headers, a second
+  table under one file - `repeated-header` and `comment-rows` are only hints) and
+  comma-versus-semicolon list columns.
+- **Key stability:** whether each unique column is really a stable key.
+
+Agents work read-only unless a fix is unambiguous and mechanical (merging two non-overlapping logs);
+anything needing editorial judgement is a recommendation. Use `resolve-onedrive-conflicts`'s
+`DELETE-SAFE` / `MERGE-NEEDED` / `RENAME` / `NO ACTION` verdicts for consistency.
+
+## Phase 3: consolidated report + checkpoint table
+
+Write one consolidated report to the session's `out/` covering every domain and the scan, and give
+the user a checkpoint table split into:
+
+- **Unambiguous fixes** ready on a single approval (documentation corrections, verified merges).
+- **Genuine judgement calls** to weigh individually (ambiguous ownership, prune-vs-keep, which of
+  two diverged forks is authoritative).
+- **Real gaps** found but not fixed (missing extractions, undersized indexes, structural drift):
+  recommend a project TODO entry or a prompt file for a dedicated session.
+
+Hand back one reviewable delete script for every confirmed-safe deletion, exactly per
+`resolve-onedrive-conflicts` (comment header with each item's evidence, `set -e`, one `rm --` per
+line, told to the user as "review, then run yourself").
+
+## Phase 4: pdata-readiness pass
+
+Compile `pdata-readiness-notes.md` (or equivalent): fold in the scan's findings and add what it
+cannot see, listing file by file every blocker a `pm-pdata-design-schema` session would hit:
+
+- Inconsistent separators within one logical column (including comma/semicolon).
+- No safe, durable, cross-session-stable natural key - especially independently-numbered `row_id`
+  columns.
+- Mixed date/timestamp formats.
+- A file that is really several differently-shaped tables: needs a "split into multiple record
+  collections" decision, not a naive single-table import.
+- Machine-specific or session-relative paths in a column.
+- Null conventions that are not real nulls (`"NO DATA"`, an empty cell that means something else).
+- A `bom` or `crlf` file that will need normalising.
+
+This file is a findings list, not a migration plan.
+
+## Phase 5: write the readiness manifest (for `ccst pdata init` / `pm-pdata-do-init`)
+
+Once the audit settles (typically two consecutive clean verification rounds, or a documented
+pragmatic stop), write one manifest at a stable location (`analysis/pdata-readiness.md` for
+projects with an `analysis/`-style folder, else the project's own top-level docs location), and
+record its location in the project's instructions file. Sections, in this order, so `pm-pdata-do-init`
+(or 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 (e.g. "stale
+   if any file below was edited after `<date>`").
+2. **File inventory:** every central/index/recordkeeping file covered, with full path, row/entry
+   count, last-verified-clean date, and role (`index`, `register`, `log`, `narrative`,
+   `derived-artefact`).
+3. **Per-file migration blockers:** Phase 4's content, in the shape `pm-pdata-design-schema` and
+   `pm-pdata-do-init` consume.
+4. **Recommended natural key per file** where one exists cleanly, else an explicit "no stable key
+   found, needs a synthetic id".
+5. **Known-acceptable duplication:** anything duplicate by design, so a migration does not re-flag
+   it or silently drop one copy.
+6. **Open decisions:** anything needing the owner's judgement and not resolved; a later session must
+   not treat an unresolved item as settled.
+
+## Common mistakes
+
+- Trusting the conflict scanner's raw `true_conflict` count without checking for the naming-pattern
+  false positive.
+- Treating the scan's unique columns as recommended keys, or its findings as facts to fix blindly.
+- Assuming documentation implies existence: check every documented path.
+- Running `rm` yourself after approval instead of handing back a reviewable script.
+- Dispatching one do-everything agent, or a fleet for a three-domain project: use one agent per
+  domain only above three domains.
+- Skipping the readiness pass because "the project isn't migrating yet": if a `.pdata-db-dump/` or a
+  pdata mention exists, it earns its cost early.
+- Silently fixing a judgement call an agent flagged: "safe to apply" and "needs a human decision" are
+  different buckets even when both are technically fixable.

{cc_session_tools-3.7.1 → cc_session_tools-3.8.0/src/cc_session_tools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 3.7.1
+Version: 3.8.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
@@ -928,6 +928,25 @@ ccst context-override off      # re-enable the warnings
 ccst context-override status   # report the current state
 ```
 
+### `ccst pdata readiness-scan`
+
+A read-only scan of a project's CSV files for the mechanical blockers to a `ccst pdata init`
+migration, used by the `pm-pdata-do-audit-and-prepare-to-migrate` skill and useful on its own:
+
+```sh
+ccst pdata readiness-scan --project myproject                 # compact Markdown report
+ccst pdata readiness-scan --project myproject --format json   # machine-readable
+ccst pdata readiness-scan --project myproject --path notes/ --findings-only   # one folder's findings
+```
+
+It reports ragged rows, empty/duplicate headers, mixed date formats, mixed `|`/`;` separators,
+machine-specific paths, null-like placeholder strings, duplicate rows, comment rows, repeated
+header rows, byte-order marks, CRLF line endings and unreadable files, plus a per-file inventory
+and the columns that are unique on every row. Findings carry counts and row numbers, never cell
+text, and a unique column is a fact rather than a recommended key. It exits 0 whenever the scan
+ran (findings are not failures), and 2 when the project directory does not exist. It scans exactly
+the CSVs `ccst pdata init` would classify.
+
 ### `ccst skills install`
 
 > You normally don't need this: `ccst install-everything --apply` runs it, and `ccst` runs that

{cc_session_tools-3.7.1 → cc_session_tools-3.8.0}/src/cc_session_tools.egg-info/SOURCES.txt

@@ -71,6 +71,7 @@ src/cc_session_tools/lib/pdata/init_paths.py
 src/cc_session_tools/lib/pdata/init_service.py
 src/cc_session_tools/lib/pdata/manifest.py
 src/cc_session_tools/lib/pdata/naming.py
+src/cc_session_tools/lib/pdata/readiness.py
 src/cc_session_tools/lib/pdata/rehydrate.py
 src/cc_session_tools/lib/pdata/rename_group.py
 src/cc_session_tools/lib/pdata/reorganize.py
@@ -218,6 +219,7 @@ tests/test_ccst_machine_identity_cli.py
 tests/test_ccst_main_gate.py
 tests/test_ccst_pdata_cli.py
 tests/test_ccst_pdata_init_cli.py
+tests/test_ccst_pdata_readiness_cli.py
 tests/test_ccst_pdata_reconcile_cli.py
 tests/test_ccst_pdata_rename_group_cli.py
 tests/test_ccst_pdata_reorganize_cli.py
@@ -264,6 +266,7 @@ tests/test_occupancy.py
 tests/test_parent_inference.py
 tests/test_parser.py
 tests/test_paths.py
+tests/test_pdata_audit_skill.py
 tests/test_pending_migration_hook.py
 tests/test_picker.py
 tests/test_pricing.py