specsmith 0.15.3.dev570__tar.gz → 0.15.3.dev573__tar.gz

{specsmith-0.15.3.dev570/src/specsmith.egg-info → specsmith-0.15.3.dev573}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.15.3.dev570
+Version: 0.15.3.dev573
 Summary: AEE governance toolkit for AI-assisted development — session preflight gates, multi-agent dispatch, requirements↔test traceability, ESDB persistence, MCP server, and skills for Warp, Cursor, Claude Code, Copilot, Windsurf, and Aider.
 Author: Layer1Labs Silicon, Inc.
 License-Expression: MIT
@@ -40,7 +40,7 @@ Requires-Dist: pre-commit>=3.0; extra == "dev"
 Requires-Dist: types-pyyaml>=6.0; extra == "dev"
 Requires-Dist: cryptography>=42.0; extra == "dev"
 Provides-Extra: esdb
-Requires-Dist: chronomemory>=0.1.7; extra == "esdb"
+Requires-Dist: chronomemory>=0.1.8; extra == "esdb"
 Requires-Dist: cryptography>=42.0; extra == "esdb"
 Provides-Extra: docs
 Requires-Dist: mkdocs>=1.6; extra == "docs"

{specsmith-0.15.3.dev570 → specsmith-0.15.3.dev573}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.15.3.dev570"
+version = "0.15.3.dev573"
 description = "AEE governance toolkit for AI-assisted development — session preflight gates, multi-agent dispatch, requirements↔test traceability, ESDB persistence, MCP server, and skills for Warp, Cursor, Claude Code, Copilot, Windsurf, and Aider."
 readme = "README.md"
 license = "MIT"
@@ -60,7 +60,7 @@ dev = [
 # Install: pip install specsmith[esdb]
 # Activate: specsmith esdb enable --key-file /path/to/your.esdb.key
 esdb = [
-    "chronomemory>=0.1.7",   # proprietary commercial — see chronomemory LICENSE
+    "chronomemory>=0.1.8",   # proprietary commercial — see chronomemory LICENSE
     "cryptography>=42.0",
 ]
 docs = [

{specsmith-0.15.3.dev570 → specsmith-0.15.3.dev573}/src/specsmith/auditor.py

@@ -1130,7 +1130,11 @@ def check_industrial_artifacts(root: Path) -> list[AuditResult]:
     raw = _read_scaffold_raw(root)
     declared: dict[str, Any] = raw.get("industrial_artifacts", {}) or {}
     declared_eds = declared.get("canopen_eds", []) or []
-    declared_paths = {e.get("path", "") for e in declared_eds if isinstance(e, dict)}
+    # Normalise declared paths to forward slashes and lowercase so they match
+    # on Windows where YAML uses '/' but Path.relative_to() returns '\\' (#251).
+    declared_paths = {
+        e.get("path", "").replace("\\", "/").lower() for e in declared_eds if isinstance(e, dict)
+    }
 
     # Scan for .eds and .xdd files — respect scan_exclude_dirs and
     # scan_exclude_patterns from scaffold.yml (#175).
@@ -1158,9 +1162,12 @@ def check_industrial_artifacts(root: Path) -> list[AuditResult]:
     if not found_eds:
         return results  # No industrial artifacts found
 
-    # Use as_posix() for cross-platform comparison — avoids single-backslash
-    # mismatch on Windows where str(Path) uses '\' but declared paths use '/' (#173).
-    undeclared = [f for f in found_eds if f.relative_to(root).as_posix() not in declared_paths]
+    # Use as_posix().lower() for cross-platform comparison — avoids backslash
+    # mismatch on Windows where str(Path) uses '\' but YAML paths use '/' (#173,
+    # #251). Both sides are lowercased so Windows case-insensitive FS is handled.
+    undeclared = [
+        f for f in found_eds if f.relative_to(root).as_posix().lower() not in declared_paths
+    ]
 
     if undeclared:
         results.append(

{specsmith-0.15.3.dev570 → specsmith-0.15.3.dev573}/src/specsmith/cli.py

@@ -445,8 +445,17 @@ def _interactive_config(no_git: bool) -> ProjectConfig:
 def audit(fix: bool, project_dir: str) -> None:
     """Run drift and health checks (Section 23 + 26)."""
     from specsmith.auditor import run_audit
+    from specsmith.sync import auto_migrate_if_needed
 
     root = Path(project_dir).resolve()
+    auto_counts = auto_migrate_if_needed(root)
+    if auto_counts:
+        console.print(
+            "  [cyan]⟳[/cyan] ESDB auto-migrate: "
+            f"{auto_counts.get('requirements', 0)} requirements + "
+            f"{auto_counts.get('testcases', 0)} testcases "
+            f"({auto_counts.get('skipped', 0)} skipped)"
+        )
     console.print(f"[bold]Auditing[/bold] {root}\n")
     report = run_audit(root)
 
@@ -1489,14 +1498,20 @@ def diff(project_dir: str, html_output: str | None) -> None:
     default=False,
     help="Run the new-user onboarding checklist (REQ-127).",
 )
-def doctor(project_dir: str, onboarding: bool) -> None:
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    default=False,
+    help="Emit machine-readable health report JSON.",
+)
+def doctor(project_dir: str, onboarding: bool, as_json: bool) -> None:
     """Check if verification tools are installed locally.
 
     With --onboarding, walks through a 6-step checklist for new users that
     confirms scaffold.yml, governance files, agent provider setup, optional
     Nexus broker availability, and prints next-step commands (REQ-127).
     """
-    from specsmith.doctor import run_doctor
 
     root = Path(project_dir).resolve()
 
@@ -1572,28 +1587,108 @@ def doctor(project_dir: str, onboarding: bool) -> None:
             )
         return
 
-    report = run_doctor(root)
+    import importlib.metadata
+    import json as _json
+    import shutil
+    import subprocess
+    import sys
 
-    if not report.checks:
-        console.print("[yellow]No scaffold.yml found — cannot determine tools.[/yellow]")
-        return
+    from specsmith.auditor import run_audit
+    from specsmith.esdb import ESDB_BACKEND, open_default_store
+    from specsmith.phase import read_phase
 
-    console.print(f"[bold]Doctor[/bold] — checking {len(report.checks)} tools\n")
-    for check in report.checks:
-        if check.installed:
-            ver = f" ({check.version})" if check.version else ""
-            console.print(f"  [green]✓[/green] {check.category}: {check.name}{ver}")
-        else:
-            console.print(f"  [red]✗[/red] {check.category}: {check.name} — not found")
+    def _tool_version(cmd: str) -> tuple[bool, str]:
+        exe = shutil.which(cmd)
+        if not exe:
+            return False, "not found"
+        try:
+            proc = subprocess.run(
+                [exe, "--version"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=False,
+            )
+            out = (proc.stdout or proc.stderr or "").strip().splitlines()
+            if out:
+                return True, out[0]
+            return True, "installed"
+        except (OSError, subprocess.TimeoutExpired):
+            return True, "installed"
+
+    checks: list[dict[str, str]] = []
+
+    def _add(name: str, passed: bool, detail: str, warn: bool = False) -> None:
+        status = "warn" if warn else ("pass" if passed else "fail")
+        checks.append({"name": name, "status": status, "detail": detail})
+
+    py_ok = sys.version_info >= (3, 10)
+    _add(
+        "python",
+        py_ok,
+        f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
+    )
 
-    console.print()
-    if report.missing_count == 0:
-        console.print(f"[bold green]All {report.installed_count} tools available.[/bold green]")
-    else:
-        console.print(
-            f"[bold red]{report.missing_count} tool(s) missing.[/bold red] "
-            f"{report.installed_count} installed."
+    git_ok, git_detail = _tool_version("git")
+    _add("git", git_ok, git_detail)
+
+    _add("specsmith", True, __version__)
+
+    try:
+        chrono_ver = importlib.metadata.version("chronomemory")
+        _add("chronomemory", True, chrono_ver)
+    except importlib.metadata.PackageNotFoundError:
+        _add("chronomemory", False, "not installed")
+
+    esdb_open = False
+    chain_ok = False
+    record_count = 0
+    try:
+        with open_default_store(root, warn=False) as store:  # type: ignore[attr-defined]
+            esdb_open = True
+            record_count = int(store.record_count())
+            chain_ok = store.chain_valid() is not False
+    except Exception as exc:  # noqa: BLE001
+        _add("esdb backend", False, f"open failed: {exc}")
+    if esdb_open:
+        _add("esdb backend", True, f"{ESDB_BACKEND} open")
+        _add(
+            "esdb chain",
+            chain_ok,
+            f"{'valid' if chain_ok else 'invalid'} ({record_count} records)",
         )
+        _add("esdb record count", True, str(record_count))
+
+    audit_report = run_audit(root)
+    _add(
+        "audit",
+        audit_report.healthy,
+        "clean" if audit_report.healthy else f"{audit_report.failed} issue(s)",
+    )
+
+    phase_key = read_phase(root)
+    _add("phase", True, phase_key)
+
+    for tool in ("ruff", "pytest", "pipx"):
+        ok, detail = _tool_version(tool)
+        _add(tool, ok, detail)
+
+    overall = "pass" if all(c["status"] != "fail" for c in checks) else "fail"
+
+    if as_json:
+        click.echo(_json.dumps({"checks": checks, "overall": overall}, indent=2))
+        return
+
+    icon = {"pass": "✅", "fail": "❌", "warn": "⚠️"}
+    console.print("specsmith doctor")
+    console.print("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+    for c in checks:
+        console.print(f"  {c['name']:<14} {icon[c['status']]}  {c['detail']}")
+    console.print("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+    if overall == "pass":
+        console.print("All checks passed.")
+    else:
+        console.print("One or more checks failed.")
 
 
 @main.command()
@@ -2577,30 +2672,47 @@ def save_cmd(project_dir: str, message: str, no_push: bool, force: bool, as_json
     """
     import json as _json
 
-    from specsmith.esdb.bridge import EsdbBridge
+    from specsmith import esdb as esdb_mod
+    from specsmith.sync import normalize_esdb_gitignore_policy
     from specsmith.vcs_commands import has_uncommitted_changes, run_commit, run_push
 
     root = Path(project_dir).resolve()
     steps: list[dict[str, Any]] = []
+    # 0. Normalize ESDB policy for legacy projects
+    try:
+        changed = normalize_esdb_gitignore_policy(root)
+        steps.append(
+            {
+                "step": "gitignore_policy",
+                "ok": True,
+                "note": "normalized legacy ESDB policy" if changed else "already compliant",
+            }
+        )
+    except Exception as exc:  # noqa: BLE001
+        steps.append({"step": "gitignore_policy", "ok": False, "error": str(exc)})
 
     # 1. ESDB backup
     try:
-        bridge = EsdbBridge(str(root))
-        store = bridge._get_store()  # noqa: SLF001
-        if store is not None:
-            backup_path = store.backup()
-            steps.append({"step": "esdb_backup", "ok": True, "path": str(backup_path)})
-        else:
-            steps.append(
-                {"step": "esdb_backup", "ok": True, "note": "JSON fallback (no WAL to backup)"}
-            )
-    except ImportError:
-        # chronomemory not installed — non-fatal; commit and push still proceed.
-        # Install with: pipx inject specsmith
-        #   "chronomemory @ git+https://github.com/layer1labs/chronomemory.git@v0.1.1"
-        from specsmith.esdb import _INSTALL_HINT  # noqa: PLC0415
-
-        steps.append({"step": "esdb_backup", "ok": True, "note": f"skipped — {_INSTALL_HINT}"})
+        with esdb_mod.open_default_store(root, warn=False) as store:  # type: ignore[attr-defined]
+            backup_fn = getattr(store, "backup", None)
+            if callable(backup_fn):
+                backup_path = backup_fn()
+                steps.append(
+                    {
+                        "step": "esdb_backup",
+                        "ok": True,
+                        "path": str(backup_path),
+                        "backend": esdb_mod.ESDB_BACKEND,
+                    }
+                )
+            else:
+                steps.append(
+                    {
+                        "step": "esdb_backup",
+                        "ok": True,
+                        "note": f"{esdb_mod.ESDB_BACKEND} backend has no native backup method",
+                    }
+                )
     except Exception as exc:  # noqa: BLE001
         steps.append({"step": "esdb_backup", "ok": False, "error": str(exc)})
 
@@ -5653,7 +5765,8 @@ def phase_next(project_dir: str, force: bool) -> None:
     """Advance to the next AEE workflow phase.
 
     Performs readiness checks on the current phase first.
-    Use --force to skip checks.
+    Use --force to skip checks.  Phases listed in ``suppressed_phases`` in the
+    scaffold config (docs/SPECSMITH.yml) are automatically skipped (#254).
     """
     from specsmith.phase import PHASE_MAP, evaluate_phase, read_phase, write_phase
 
@@ -5679,12 +5792,45 @@ def phase_next(project_dir: str, force: bool) -> None:
         )
         return
 
-    write_phase(root, phase.next_phase)
-    next_phase = PHASE_MAP[phase.next_phase]
+    # Read suppressed_phases from the scaffold config (#254).
+    suppressed: list[str] = []
+    try:
+        import yaml as _yaml
+
+        from specsmith.paths import find_scaffold
+
+        sp = find_scaffold(root)
+        if sp:
+            _raw = _yaml.safe_load(sp.read_text(encoding="utf-8")) or {}
+            suppressed = [str(p) for p in (_raw.get("suppressed_phases") or [])]
+    except Exception:  # noqa: BLE001
+        pass  # Never block phase advance on config parse errors
+
+    # Walk the phase chain until we find a non-suppressed next phase.
+    target_key: str | None = phase.next_phase
+    skipped: list[str] = []
+    while target_key and target_key in suppressed:
+        skipped.append(target_key)
+        target_phase = PHASE_MAP.get(target_key)
+        target_key = target_phase.next_phase if target_phase else None
+
+    if not target_key:
+        console.print(
+            f"[bold]{phase.emoji} {phase.label}[/bold] is the effective final phase "
+            "(all remaining phases are suppressed)."
+        )
+        if skipped:
+            console.print(f"  [dim]Suppressed: {', '.join(skipped)}[/dim]")
+        return
+
+    write_phase(root, target_key)
+    next_phase = PHASE_MAP[target_key]
     console.print(
         f"[green]\u2713[/green] Advanced from [bold]{phase.label}[/bold] "
         f"to [bold]{next_phase.emoji} {next_phase.label}[/bold]."
     )
+    if skipped:
+        console.print(f"  [dim]Skipped suppressed phase(s): {', '.join(skipped)}[/dim]")
     console.print(f"  {next_phase.description}")
     if next_phase.commands:
         console.print("\n  [bold]Next steps:[/bold]")
@@ -5693,14 +5839,14 @@ def phase_next(project_dir: str, force: bool) -> None:
 
     # G3: keep the agents routing table aligned with the active phase.
     # We pin a synthetic ``phase:active`` route so the runner can flip the
-    # whole session to the new phase’s preferred profile without the user
+    # whole session to the new phase's preferred profile without the user
     # having to run `specsmith agents route set` themselves.
     try:
         from specsmith.agent.profiles import ProfileStore
 
         agents_store = ProfileStore.load()
         if agents_store.profiles:
-            phase_key_target = f"phase:{phase.next_phase}"
+            phase_key_target = f"phase:{target_key}"
             target_id = agents_store.routes.get(phase_key_target) or (
                 agents_store.default_profile_id
             )
@@ -5968,10 +6114,11 @@ def sync_cmd(project_dir: str, check_only: bool, as_json: bool) -> None:
     """
     import json as _json
 
-    from specsmith.sync import run_sync
+    from specsmith.sync import auto_migrate_if_needed, run_sync
 
     root = Path(project_dir).resolve()
     result = run_sync(root, dry_run=check_only)
+    auto_counts = {} if check_only else auto_migrate_if_needed(root)
 
     if as_json:
         click.echo(
@@ -5985,6 +6132,8 @@ def sync_cmd(project_dir: str, check_only: bool, as_json: bool) -> None:
                     "tests_changed": result.tests_changed,
                     "in_sync": not result.changed,
                     "dry_run": result.dry_run,
+                    "auto_migrated": bool(auto_counts),
+                    "auto_migrate_counts": auto_counts,
                 },
                 indent=2,
             )
@@ -5998,6 +6147,13 @@ def sync_cmd(project_dir: str, check_only: bool, as_json: bool) -> None:
                 console.print(f"[green]\u2713[/green] {result.message}")
         else:
             console.print("[green]\u2713[/green] Machine state already in sync.")
+        if auto_counts:
+            console.print(
+                "  [cyan]⟳[/cyan] ESDB auto-migrate: "
+                f"{auto_counts.get('requirements', 0)} requirements + "
+                f"{auto_counts.get('testcases', 0)} testcases "
+                f"({auto_counts.get('skipped', 0)} skipped)"
+            )
 
     if check_only and result.changed:
         raise SystemExit(1)
@@ -10424,8 +10580,10 @@ def esdb_status_cmd(project_dir: str, as_json: bool) -> None:
 
     from specsmith.esdb import CHRONO_AVAILABLE, open_default_store
     from specsmith.esdb._license import check_license, resolve_license_path
+    from specsmith.sync import auto_migrate_if_needed
 
     root = Path(project_dir).resolve()
+    auto_counts = auto_migrate_if_needed(root)
 
     # Determine license status without side-effect warnings
     lic_path = resolve_license_path()
@@ -10491,6 +10649,8 @@ def esdb_status_cmd(project_dir: str, as_json: bool) -> None:
                     "chain_valid": chain_ok,
                     "counts": counts,
                     "license": license_info,
+                    "auto_migrated": bool(auto_counts),
+                    "auto_migrate_counts": auto_counts,
                 },
                 indent=2,
             )
@@ -10521,6 +10681,13 @@ def esdb_status_cmd(project_dir: str, as_json: bool) -> None:
         console.print(
             "  [dim]Use 'specsmith esdb enable --key-file <path>' to activate ChronoStore.[/dim]"
         )
+    if auto_counts:
+        console.print(
+            "  [cyan]⟳[/cyan] Auto-migrated from legacy JSON: "
+            f"{auto_counts.get('requirements', 0)} requirements + "
+            f"{auto_counts.get('testcases', 0)} testcases "
+            f"({auto_counts.get('skipped', 0)} skipped)"
+        )
 
 
 @esdb_group.command(name="enable")
@@ -10554,9 +10721,15 @@ def esdb_enable_cmd(key_file: str, as_json: bool) -> None:
             console.print("[dim]Contact licensing@layer1labs.com to obtain a valid license.[/dim]")
         raise SystemExit(1)
 
+    import os
+
     dest = Path.home() / ".specsmith" / "esdb.key"
     dest.parent.mkdir(parents=True, exist_ok=True)
-    shutil.copy2(key_file, dest)
+    # Skip the copy when source and destination are the same file (#249).
+    # On Windows, shutil.copy2(src, dst) raises PermissionError / WinError 32
+    # when src == dst (file is already at the expected location).
+    if os.path.realpath(str(key_file)) != os.path.realpath(str(dest)):
+        shutil.copy2(key_file, dest)
 
     if as_json:
         click.echo(

{specsmith-0.15.3.dev570 → specsmith-0.15.3.dev573}/src/specsmith/esdb/sqlite_store.py

@@ -289,6 +289,22 @@ class SqliteStore:
         row = conn.execute("SELECT MAX(rowid) FROM records").fetchone()
         return int(row[0]) if row and row[0] is not None else 0
 
+    def backup(self, backup_dir: str | Path | None = None) -> Path:
+        """Create a timestamped SQLite snapshot and return its path."""
+        conn = self._require_open()
+        ts = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime())
+        dest_dir = Path(backup_dir) if backup_dir else self._db_path.parent / "backups"
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        dest = dest_dir / f"esdb_sqlite_backup_{ts}.sqlite3"
+
+        backup_conn = sqlite3.connect(str(dest))
+        try:
+            conn.backup(backup_conn)
+        finally:
+            backup_conn.close()
+
+        return dest
+
     def chain_valid(self) -> bool:
         """Always True — SQLite ACID guarantees integrity (no SHA-256 WAL chain)."""
         return True

{specsmith-0.15.3.dev570 → specsmith-0.15.3.dev573}/src/specsmith/sync.py

@@ -207,6 +207,88 @@ class SyncResult:
         return "Machine state already in sync."
 
 
+# ---------------------------------------------------------------------------
+# ESDB legacy policy normalization (.gitignore)
+# ---------------------------------------------------------------------------
+
+_ESDB_GITIGNORE_FORBIDDEN = frozenset(
+    {
+        ".specsmith/",
+        ".chronomemory/",
+    }
+)
+
+_ESDB_GITIGNORE_REQUIRED = (
+    "!.specsmith/config.yml",
+    "!.specsmith/requirements.json",
+    "!.specsmith/testcases.json",
+    "!.specsmith/esdb.sqlite3",
+    "!.chronomemory/events.wal",
+    "!.chronomemory/snapshot.json",
+    ".chronomemory/backup/",
+    ".specsmith/workitems.json",
+    ".specsmith/runs/",
+    ".specsmith/chat/",
+    ".specsmith/perf/",
+    ".specsmith/recovery/",
+    ".specsmith/ledger.jsonl",
+    ".specsmith/ledger-chain.txt",
+    ".specsmith/trace.jsonl",
+    ".specsmith/credit-budget.json",
+    ".specsmith/credits.json",
+    ".specsmith/model-rate-limits.json",
+    ".specsmith/pids/",
+    ".specsmith/logs/",
+    ".specsmith/sessions/",
+    ".specsmith/agent-reports/",
+    ".specsmith/dispatch/",
+    ".specsmith/esdb_migration_manifest.json",
+)
+
+
+def normalize_esdb_gitignore_policy(root: Path, *, dry_run: bool = False) -> bool:
+    """Normalize ESDB gitignore policy for legacy projects.
+
+    Ensures broad ignores that hide canonical ESDB state are removed and that
+    explicit policy lines are present so SQLite/Chrono canonical artifacts are
+    always tracked while runtime files stay ignored.
+    """
+    gitignore_path = root / ".gitignore"
+    if gitignore_path.exists():
+        original_lines = gitignore_path.read_text(encoding="utf-8").splitlines()
+    else:
+        original_lines = []
+
+    normalized_lines: list[str] = []
+    removed_forbidden = False
+    for line in original_lines:
+        if line.strip() in _ESDB_GITIGNORE_FORBIDDEN:
+            removed_forbidden = True
+            continue
+        normalized_lines.append(line)
+
+    existing = {line.strip() for line in normalized_lines if line.strip()}
+    missing = [entry for entry in _ESDB_GITIGNORE_REQUIRED if entry not in existing]
+    changed = removed_forbidden or bool(missing)
+
+    if not changed:
+        return False
+
+    if normalized_lines and normalized_lines[-1].strip():
+        normalized_lines.append("")
+    if missing:
+        normalized_lines.append("# specsmith ESDB policy (auto-normalized)")
+        normalized_lines.extend(missing)
+
+    if not dry_run:
+        rendered = "\n".join(normalized_lines)
+        if rendered and not rendered.endswith("\n"):
+            rendered += "\n"
+        gitignore_path.write_text(rendered, encoding="utf-8")
+
+    return True
+
+
 # ---------------------------------------------------------------------------
 # Core sync
 # ---------------------------------------------------------------------------
@@ -244,6 +326,8 @@ def run_sync(root: Path, *, dry_run: bool = False) -> SyncResult:
     tests_md_path = root / "docs" / "TESTS.md"
     reqs_json_path = state_dir / "requirements.json"
     tests_json_path = state_dir / "testcases.json"
+    if not dry_run:
+        normalize_esdb_gitignore_policy(root)
 
     if is_yaml_mode(root):
         # ── YAML-first mode ─────────────────────────────────────────────────
@@ -469,6 +553,65 @@ def _sync_esdb(root: Path, state_dir: Path) -> None:
         pass
 
 
+def _json_file_has_content(path: Path) -> bool:
+    """Return True when *path* exists and contains a non-empty JSON list.
+
+    Falls back to a small size heuristic for malformed JSON so we still treat
+    legacy state files with obvious content as migratable.
+    """
+    if not path.is_file():
+        return False
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        return isinstance(payload, list) and len(payload) > 0
+    except (OSError, ValueError):
+        with contextlib.suppress(OSError):
+            return path.stat().st_size > 2
+        return False
+
+
+def _should_auto_migrate(store: Any, specsmith_dir: Path) -> bool:
+    """Return True when ESDB is empty and legacy JSON sources have content.
+
+    This is used by CLI surfaces (`sync`, `audit`, `esdb status`) to
+    opportunistically bootstrap ESDB from `.specsmith/*.json` exactly once.
+    """
+    if store.record_count() > 0:
+        return False
+    candidates = (
+        specsmith_dir / "requirements.json",
+        specsmith_dir / "testcases.json",
+    )
+    return any(_json_file_has_content(path) for path in candidates)
+
+
+def auto_migrate_if_needed(root: Path) -> dict[str, int]:
+    """Best-effort ESDB bootstrap from legacy JSON when the store is empty.
+
+    Returns migration counts on success, or an empty dict when no migration was
+    needed or if any backend error occurred.
+    """
+    from specsmith.esdb import open_default_store
+
+    specsmith_dir = root / ".specsmith"
+    if not specsmith_dir.exists():
+        return {}
+    try:
+        with open_default_store(root, warn=False) as store:  # type: ignore[attr-defined]
+            if not _should_auto_migrate(store, specsmith_dir):
+                return {}
+            counts = store.migrate_from_json(specsmith_dir)
+            if isinstance(counts, dict):
+                return {
+                    "requirements": int(counts.get("requirements", 0)),
+                    "testcases": int(counts.get("testcases", 0)),
+                    "skipped": int(counts.get("skipped", 0)),
+                }
+            return {}
+    except Exception:  # noqa: BLE001 - never block caller commands
+        return {}
+
+
 def check_sync(root: Path) -> SyncResult:
     """Check whether machine state is in sync without writing anything.
 

{specsmith-0.15.3.dev570 → specsmith-0.15.3.dev573}/src/specsmith/templates/gitignore.j2

@@ -45,6 +45,13 @@ htmlcov/
 # - .specsmith/esdb.sqlite3
 # - .chronomemory/events.wal
 # - .chronomemory/snapshot.json
+# Always track these even if broader ignore rules are added later:
+!.specsmith/config.yml
+!.specsmith/requirements.json
+!.specsmith/testcases.json
+!.specsmith/esdb.sqlite3
+!.chronomemory/events.wal
+!.chronomemory/snapshot.json
 #
 # Ignore runtime-only / regeneratable artifacts:
 .chronomemory/backup/