dctracker 1.0.0__tar.gz → 1.1.0__tar.gz

{dctracker-1.0.0/dctracker.egg-info → dctracker-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dctracker
-Version: 1.0.0
+Version: 1.1.0
 Summary: Deterministic Context Tracker (dct) — cross-project tracking, changelog, and release tooling for Claude Code.
 Author-email: fotodeveloper <dev@fotodeveloper.com>
 License-Expression: MIT
@@ -47,7 +47,7 @@ Dynamic: license-file
 [![CI](https://github.com/fotodeveloper/dct/actions/workflows/ci.yml/badge.svg)](https://github.com/fotodeveloper/dct/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Persistent, queryable memory for AI coding assistants — your assistant reads facts from a database instead of guessing. One user-scoped database tracks issues, todos, changelog entries, plans, sprints, and decisions across all your projects. Built for [Claude Code](https://claude.com/claude-code) (skills, hooks, 48 MCP tools); the MCP server and CLI work with any MCP-capable assistant.
+Persistent, queryable memory for AI coding assistants — your assistant reads facts from a database instead of guessing. One user-scoped database tracks issues, todos, changelog entries, plans, sprints, and decisions across all your projects. Built for [Claude Code](https://claude.com/claude-code) (skills, hooks, 49 MCP tools); the MCP server and CLI work with any MCP-capable assistant.
 
 Part of the **dc tools** family ([dctools.dev](https://dctools.dev)) — *deterministic context* for AI-assisted development.
 
@@ -121,7 +121,7 @@ markdown, and makes the release commit.
 - **Decision records** — ADRs, sprint amendments, inline plan decisions with multi-anchor linkage
 - **LLM-assisted classification** — uncertain plan sections auto-resolved via `claude --print` (haiku by default)
 - **Passive autoscan hook** — PostToolUse hook re-scans plan-like files in background on every edit
-- **MCP server** — native Claude Code integration via FastMCP, 48 tools
+- **MCP server** — native Claude Code integration via FastMCP, 49 tools
 - **CLI** — fast `dct` command for hooks and scripts
 - **Skills** — Claude Code slash commands (`/track`, `/clog`, `/dct-import`, `/plan-status`, …)
 - **Soft deletes** — ledger pattern, nothing is ever lost
@@ -200,6 +200,16 @@ happens in the conversation you're already having.
 - **MCP tools don't show up in Claude Code** — the MCP server is a per-session subprocess, so newly registered tools (or a reinstall) appear only after you **restart the Claude Code session**. Start a fresh session and they'll be there.
 - **Plans/decisions tools fail with `No module named 'ulid'`** — your installed tool environment predates the `python-ulid` dependency. Upgrade it: `uv tool upgrade dctracker` (or reinstall via your chosen option above).
 
+### Updating
+
+dct runs a passive, offline-safe update check — a cached PyPI probe (refreshed at most once a day, never blocking) surfaces a one-line "newer release available" nudge on the CLI and in the MCP server instructions. Opt out with `[update] check = false` in `~/.claude/dct.toml`. When a newer version exists:
+
+```bash
+dct upgrade    # detects install method (uv tool / pipx / pip), upgrades, re-links skills + hooks
+```
+
+`dct upgrade` refreshes the skill/hook symlinks and prunes any that the new package dropped. Editable/dev checkouts print `git pull` guidance instead (no package to upgrade). Run it at a session boundary — skill descriptions and the MCP server pick up the new code on the next session, migrations on the next engine bootstrap.
+
 ## Usage
 
 ### CLI
@@ -243,22 +253,22 @@ dct checkpoint reject 4               # Scope-change, keep in ledger
 
 ## MCP Tools
 
-dct ships **48 MCP tools**, registered at user scope so they're callable from any Claude Code session as `mcp__dct__<name>`. Zero-arg calls auto-detect the project from the session's working directory; pass `project=<slug>` to override. The daily drivers:
+dct ships **49 MCP tools**, registered at user scope so they're callable from any Claude Code session as `mcp__dct__<name>`. Zero-arg calls auto-detect the project from the session's working directory; pass `project=<slug>` to override. Write ops return a minimal ack (id + a few post-state scalars); fetch full context with `get_item(id)` / `get_handoff(id)`. Ten mid-session daily drivers are always resident (`alwaysLoad`); the rest of the catalogue loads on demand via ToolSearch:
 
 | Tool | Purpose |
 |---|---|
 | `create_item` | Create a tracked item (issue / todo / feature / idea / improvement) |
+| `get_item` | Full item dict — fields, notes, checkpoints, progress |
 | `list_items` | List / search items in compact `{cols, rows}` form |
 | `update_item` | Update fields on an existing item |
 | `resolve_item` | Close an item (terminal status), with gate-checkpoint guard |
+| `add_note` | Append a note to an item (append-only ledger) |
 | `add_checkpoint` | Add an acceptance criterion to an item |
 | `complete_checkpoint` | Mark a checkpoint done (real-time, never batched) |
+| `reject_checkpoint` | Mark a checkpoint rejected (scope change) — ledger-preserving |
 | `add_changelog` | Add an unreleased changelog entry |
-| `release_changelog` | Stamp unreleased entries with a version + bump `current_version` |
-| `set_sprint` | Atomically replace the current sprint's membership |
-| `create_handoff` | Leave a handoff draft for the next session |
 
-Full categorized catalogue of all 48 tools: **[docs/mcp-tools.md](docs/mcp-tools.md)**.
+Session-edge tools stay deferred: `get_handoff` (full handoff dict — untruncated prompt + context_summary), `create_handoff`, `set_sprint`, `release_changelog`, and more. Full categorized catalogue of all 49 tools: **[docs/mcp-tools.md](docs/mcp-tools.md)**.
 
 ## Plans, Roadmaps & Decisions
 

{dctracker-1.0.0 → dctracker-1.1.0}/README.md

@@ -5,7 +5,7 @@
 [![CI](https://github.com/fotodeveloper/dct/actions/workflows/ci.yml/badge.svg)](https://github.com/fotodeveloper/dct/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Persistent, queryable memory for AI coding assistants — your assistant reads facts from a database instead of guessing. One user-scoped database tracks issues, todos, changelog entries, plans, sprints, and decisions across all your projects. Built for [Claude Code](https://claude.com/claude-code) (skills, hooks, 48 MCP tools); the MCP server and CLI work with any MCP-capable assistant.
+Persistent, queryable memory for AI coding assistants — your assistant reads facts from a database instead of guessing. One user-scoped database tracks issues, todos, changelog entries, plans, sprints, and decisions across all your projects. Built for [Claude Code](https://claude.com/claude-code) (skills, hooks, 49 MCP tools); the MCP server and CLI work with any MCP-capable assistant.
 
 Part of the **dc tools** family ([dctools.dev](https://dctools.dev)) — *deterministic context* for AI-assisted development.
 
@@ -79,7 +79,7 @@ markdown, and makes the release commit.
 - **Decision records** — ADRs, sprint amendments, inline plan decisions with multi-anchor linkage
 - **LLM-assisted classification** — uncertain plan sections auto-resolved via `claude --print` (haiku by default)
 - **Passive autoscan hook** — PostToolUse hook re-scans plan-like files in background on every edit
-- **MCP server** — native Claude Code integration via FastMCP, 48 tools
+- **MCP server** — native Claude Code integration via FastMCP, 49 tools
 - **CLI** — fast `dct` command for hooks and scripts
 - **Skills** — Claude Code slash commands (`/track`, `/clog`, `/dct-import`, `/plan-status`, …)
 - **Soft deletes** — ledger pattern, nothing is ever lost
@@ -158,6 +158,16 @@ happens in the conversation you're already having.
 - **MCP tools don't show up in Claude Code** — the MCP server is a per-session subprocess, so newly registered tools (or a reinstall) appear only after you **restart the Claude Code session**. Start a fresh session and they'll be there.
 - **Plans/decisions tools fail with `No module named 'ulid'`** — your installed tool environment predates the `python-ulid` dependency. Upgrade it: `uv tool upgrade dctracker` (or reinstall via your chosen option above).
 
+### Updating
+
+dct runs a passive, offline-safe update check — a cached PyPI probe (refreshed at most once a day, never blocking) surfaces a one-line "newer release available" nudge on the CLI and in the MCP server instructions. Opt out with `[update] check = false` in `~/.claude/dct.toml`. When a newer version exists:
+
+```bash
+dct upgrade    # detects install method (uv tool / pipx / pip), upgrades, re-links skills + hooks
+```
+
+`dct upgrade` refreshes the skill/hook symlinks and prunes any that the new package dropped. Editable/dev checkouts print `git pull` guidance instead (no package to upgrade). Run it at a session boundary — skill descriptions and the MCP server pick up the new code on the next session, migrations on the next engine bootstrap.
+
 ## Usage
 
 ### CLI
@@ -201,22 +211,22 @@ dct checkpoint reject 4               # Scope-change, keep in ledger
 
 ## MCP Tools
 
-dct ships **48 MCP tools**, registered at user scope so they're callable from any Claude Code session as `mcp__dct__<name>`. Zero-arg calls auto-detect the project from the session's working directory; pass `project=<slug>` to override. The daily drivers:
+dct ships **49 MCP tools**, registered at user scope so they're callable from any Claude Code session as `mcp__dct__<name>`. Zero-arg calls auto-detect the project from the session's working directory; pass `project=<slug>` to override. Write ops return a minimal ack (id + a few post-state scalars); fetch full context with `get_item(id)` / `get_handoff(id)`. Ten mid-session daily drivers are always resident (`alwaysLoad`); the rest of the catalogue loads on demand via ToolSearch:
 
 | Tool | Purpose |
 |---|---|
 | `create_item` | Create a tracked item (issue / todo / feature / idea / improvement) |
+| `get_item` | Full item dict — fields, notes, checkpoints, progress |
 | `list_items` | List / search items in compact `{cols, rows}` form |
 | `update_item` | Update fields on an existing item |
 | `resolve_item` | Close an item (terminal status), with gate-checkpoint guard |
+| `add_note` | Append a note to an item (append-only ledger) |
 | `add_checkpoint` | Add an acceptance criterion to an item |
 | `complete_checkpoint` | Mark a checkpoint done (real-time, never batched) |
+| `reject_checkpoint` | Mark a checkpoint rejected (scope change) — ledger-preserving |
 | `add_changelog` | Add an unreleased changelog entry |
-| `release_changelog` | Stamp unreleased entries with a version + bump `current_version` |
-| `set_sprint` | Atomically replace the current sprint's membership |
-| `create_handoff` | Leave a handoff draft for the next session |
 
-Full categorized catalogue of all 48 tools: **[docs/mcp-tools.md](docs/mcp-tools.md)**.
+Session-edge tools stay deferred: `get_handoff` (full handoff dict — untruncated prompt + context_summary), `create_handoff`, `set_sprint`, `release_changelog`, and more. Full categorized catalogue of all 49 tools: **[docs/mcp-tools.md](docs/mcp-tools.md)**.
 
 ## Plans, Roadmaps & Decisions
 

{dctracker-1.0.0 → dctracker-1.1.0}/dct/__init__.py

@@ -3,4 +3,4 @@ from importlib.metadata import version, PackageNotFoundError
 try:
     __version__ = version("dctracker")
 except PackageNotFoundError:
-    __version__ = "1.0.0"
+    __version__ = "1.1.0"

{dctracker-1.0.0 → dctracker-1.1.0}/dct/cli.py

@@ -1,6 +1,7 @@
 """CLI entry point for dct (Deterministic Context Tracker)."""
 
 import argparse
+import atexit
 import os
 import signal
 import socket
@@ -749,21 +750,34 @@ def cmd_internal_task_mirror(args):
     appends each todo as a `kind='cc-task'` checkpoint. Non-blocking —
     safe to fail silently (hook is fire-and-forget).
 
+    Owns the config gate and project autodetect (the shell hook is a lean
+    dispatcher that only drains stdin and backgrounds this worker — #354):
+      - reads [mirror].task_to_dct; anything but 'auto' is a silent no-op;
+      - detects the project from CWD, silent no-op when the CWD is not a
+        registered dct project.
+
     Intentionally named with an underscore prefix — not user-facing, just
     the target of the task-mirror hook. Re-expose via the `dct` entry point
     so the venv-installed Python is used (hooks cannot reliably find it).
 
     Args:
-        session-id: Claude Code session_id (from hook payload .session_id).
+        session-id: Claude Code session_id. Empty → read payload .session_id.
         project: dct project slug. Empty → autodetect from CWD.
     """
     import json
+    from dct.config import load_config
 
     try:
         payload = json.load(sys.stdin)
     except json.JSONDecodeError:
         return  # fire-and-forget: swallow, exit clean
 
+    # Config gate (moved off the shell fast-path). auto → mirror; ask/off/
+    # anything else → silent no-op.
+    mode = getattr(load_config().mirror, "task_to_dct", "auto") or "auto"
+    if mode != "auto":
+        return
+
     tool_input = payload.get("tool_input") or {}
     todos: list[str] = []
     if isinstance(tool_input.get("todos"), list):
@@ -788,11 +802,22 @@ def cmd_internal_task_mirror(args):
 
     from dct.core.items import list_items, create_item
     from dct.core.checkpoints import add_checkpoint
+    from dct.core.projects import get_project_by_path
 
     engine = _get_engine()
 
-    project_slug = args.project or _detect_project(engine)
-    session_id = args.session_id or "unknown"
+    # Silent project autodetect — a fire-and-forget worker must never raise
+    # or exit non-zero when the CWD is not a registered project.
+    project_slug = args.project
+    if not project_slug:
+        import os
+
+        detected = get_project_by_path(engine, os.getcwd())
+        if not detected:
+            return
+        project_slug = detected["slug"]
+
+    session_id = args.session_id or payload.get("session_id") or "unknown"
     title = f"CC task list — session {session_id}"
 
     existing = [
@@ -1039,6 +1064,65 @@ def cmd_server(args):
     mcp.run()
 
 
+# ── Upgrade ──────────────────────────────────────────────────────────────────
+
+def cmd_upgrade(args):
+    """Upgrade the installed dct package and refresh its Claude Code symlinks.
+
+    Detects the install method (editable / uv tool / pipx / pip), runs the
+    matching upgrade, re-links skills + hooks (idempotent) and prunes dangling
+    links for skills/hooks dropped from the new package, then prints the effect
+    matrix so the user knows what takes effect when.
+    """
+    import subprocess
+    from dct.update import detect_install_method, upgrade_command, dist_pkg
+
+    method = detect_install_method()
+
+    if method == "editable":
+        print("dct is installed as an editable / dev checkout — no package upgrade to run.")
+        print("Pull the repo to update:")
+        print("    git -C <dct-repo> pull")
+        print("    uv pip install -e '<dct-repo>[mcp]'   # only if dependencies changed")
+    else:
+        cmd = upgrade_command(method)
+        print(f"Detected install method: {method}")
+        print(f"Upgrading {dist_pkg()} …  ({' '.join(cmd)})")
+        result = subprocess.run(cmd)
+        if result.returncode != 0:
+            print(f"✗ Upgrade command failed (exit {result.returncode})", file=sys.stderr)
+            sys.exit(result.returncode)
+
+    # Refresh Claude Code integration: re-link current skills/hooks (idempotent),
+    # then remove links to skills/hooks that the new package no longer ships.
+    from dct.setup import install_hook, install_skills, prune_dangling_symlinks
+
+    linked_ok = True
+    removed: list[str] = []
+    try:
+        install_skills()
+        install_hook()
+        removed = prune_dangling_symlinks()
+    except Exception as e:  # never let link maintenance abort the command
+        linked_ok = False
+        print(f"  ⚠ Skills/hooks re-link failed: {e}", file=sys.stderr)
+        print("    Run `dct init` to repair the Claude Code integration.", file=sys.stderr)
+
+    if linked_ok:
+        print("  ✓ Skills and hooks re-linked")
+        if removed:
+            print(f"  ✓ Removed {len(removed)} dangling link(s):")
+            for path in removed:
+                print(f"      - {path}")
+
+    print("\nWhat takes effect when:")
+    print("  Now (this shell):            dct CLI, hooks, skill bodies")
+    print("  Next session / /mcp reconnect: skill descriptions, MCP server code")
+    print("  Next engine bootstrap:       database schema migrations")
+    print("\nRecommend running `dct upgrade` at a session boundary — an old running")
+    print("MCP server against a freshly migrated schema is an edge best avoided.")
+
+
 # ── Project detect (for hooks) ───────────────────────────────────────────────
 
 def cmd_project_detect(args):
@@ -1254,6 +1338,13 @@ def build_parser() -> argparse.ArgumentParser:
     # server (MCP stdio entry point)
     sub.add_parser("server", help="Start the MCP server (stdio transport)")
 
+    # upgrade (self-update + symlink refresh — #356)
+    sub.add_parser(
+        "upgrade",
+        help="Upgrade dct (auto-detects uv tool / pipx / pip; guides editable installs) "
+             "and refresh skill/hook symlinks",
+    )
+
     # project
     p_project = sub.add_parser("project", help="Manage projects")
     p_proj_sub = p_project.add_subparsers(dest="project_command")
@@ -1512,6 +1603,7 @@ def build_parser() -> argparse.ArgumentParser:
 COMMAND_MAP = {
     "init": cmd_init,
     "server": cmd_server,
+    "upgrade": cmd_upgrade,
     "add": cmd_add,
     "list": cmd_list,
     "show": cmd_show,
@@ -1585,6 +1677,83 @@ SPRINT_COMMAND_MAP = {
 }
 
 
+# ── Passive update nudge (#356) ──────────────────────────────────────────────
+
+# (command, subcommand) pairs that hooks / tooling call non-interactively — a
+# nudge on stderr would corrupt their machine-read output, so never surface it.
+_NUDGE_HOOK_SUBCOMMANDS = frozenset({
+    ("project", "detect"),
+    ("project", "manages-changelog"),
+    ("clog", "count"),
+    ("config", "get"),
+})
+
+
+def _nudge_suppressed(args) -> bool:
+    """True when the passive update nudge must NOT be printed for this command.
+
+    Suppressed for: any underscore-prefixed command (internal, e.g. _task-mirror),
+    any underscore-prefixed subcommand, and the hook-driven machine-output pairs
+    in ``_NUDGE_HOOK_SUBCOMMANDS`` (project detect / manages-changelog, clog
+    count, config get). The caller additionally gates on ``stderr.isatty()``.
+    """
+    cmd = getattr(args, "command", None) or ""
+    if not cmd or cmd.startswith("_"):
+        return True
+    sub = (
+        getattr(args, "project_command", None)
+        or getattr(args, "clog_command", None)
+        or getattr(args, "config_command", None)
+    )
+    if isinstance(sub, str) and sub.startswith("_"):
+        return True
+    return (cmd, sub) in _NUDGE_HOOK_SUBCOMMANDS
+
+
+NUDGE_JOIN_TIMEOUT = 1.5  # bounded wait for the background PyPI probe at exit
+
+
+def _register_probe_join(thread) -> None:
+    """Join the background update probe (bounded) at interpreter exit.
+
+    The probe runs in a daemon thread, so a short-lived CLI command would
+    otherwise exit before it finishes and the cache would never populate. Joining
+    at ``atexit`` — AFTER the command's own work is done — lets quick commands
+    still warm the cache without the probe blocking the command. Offline worst
+    case is bounded by the probe's ``NETWORK_TIMEOUT`` (2s) racing this 1.5s join;
+    the daemon flag guarantees the process still exits either way. No-op when the
+    probe was not started this invocation (``thread is None``).
+    """
+    if thread is None:
+        return
+    atexit.register(thread.join, NUDGE_JOIN_TIMEOUT)
+
+
+def _maybe_nudge(args) -> None:
+    """Print the cached update notice to stderr for interactive human commands.
+
+    Also kicks off the non-blocking background cache refresh and registers a
+    bounded ``atexit`` join so a short command still populates the cache before
+    the interpreter exits. Entirely best-effort: any failure (or a non-tty,
+    suppressed, or opted-out command) is silent and never affects the command's
+    own output or exit code.
+    """
+    try:
+        if not sys.stderr.isatty() or _nudge_suppressed(args):
+            return
+        from dct.config import load_config
+        from dct.update import check_for_update, get_cached_notice
+
+        cfg = load_config()  # single load; both halves honor [update] check
+        thread = check_for_update(cfg)  # background refresh; returns immediately
+        _register_probe_join(thread)    # bounded join at exit, after command work
+        notice = get_cached_notice(config=cfg)
+        if notice:
+            print(notice, file=sys.stderr)
+    except Exception:
+        pass  # a passive nicety must never break a command
+
+
 def main():
     parser = build_parser()
     args = parser.parse_args()
@@ -1593,6 +1762,8 @@ def main():
         parser.print_help()
         sys.exit(0)
 
+    _maybe_nudge(args)
+
     if args.command == "project":
         handler = PROJECT_COMMAND_MAP.get(args.project_command)
         if not handler:

{dctracker-1.0.0 → dctracker-1.1.0}/dct/config.py

@@ -55,6 +55,16 @@ class WebConfig:
     refresh_poll_ms: int = 2000
 
 
+@dataclass
+class UpdateConfig:
+    """[update] section — #356 passive PyPI update check.
+
+    check  when False, disables BOTH the background version probe and the CLI
+           nudge. Offline-safe and non-blocking regardless; this is the opt-out.
+    """
+    check: bool = True
+
+
 @dataclass
 class Config:
     database_url: str = ""
@@ -62,6 +72,7 @@ class Config:
     plans: PlansConfig = field(default_factory=PlansConfig)
     mirror: MirrorConfig = field(default_factory=MirrorConfig)
     web: WebConfig = field(default_factory=WebConfig)
+    update: UpdateConfig = field(default_factory=UpdateConfig)
 
     def __post_init__(self):
         if not self.database_url:
@@ -107,12 +118,18 @@ def load_config(config_path: Path | None = None) -> Config:
         refresh_poll_ms=int(web_section.get("refresh_poll_ms", 2000)),
     )
 
+    update_section = data.get("update", {})
+    update = UpdateConfig(check=bool(update_section.get("check", True)))
+
     # Env var overrides config file
     env_url = os.environ.get("DCT_DATABASE_URL")
     if env_url:
         database_url = env_url
 
-    return Config(database_url=database_url, dct_root=dct_root, plans=plans, mirror=mirror, web=web)
+    return Config(
+        database_url=database_url, dct_root=dct_root,
+        plans=plans, mirror=mirror, web=web, update=update,
+    )
 
 
 def save_config(config: Config, config_path: Path | None = None) -> Path:
@@ -146,5 +163,8 @@ def save_config(config: Config, config_path: Path | None = None) -> Path:
     lines.append(f'open_browser = {str(config.web.open_browser).lower()}\n')
     lines.append(f'refresh_poll_ms = {config.web.refresh_poll_ms}\n')
 
+    lines.append('\n[update]\n')
+    lines.append(f'check = {str(config.update.check).lower()}\n')
+
     path.write_text("".join(lines))
     return path

{dctracker-1.0.0 → dctracker-1.1.0}/dct/core/engine.py

@@ -11,16 +11,19 @@ the schema (no create_tables, only SELECTs).
 import sqlalchemy as sa
 
 from dct.config import load_config
-from dct.db import get_engine, create_tables
+from dct.db import ensure_sqlite_dir, get_engine, create_tables
 
 
 def bootstrap_engine(create: bool = True) -> sa.Engine:
     """Build a SQLAlchemy Engine from dct config.
 
     Args:
-        create: when True (default) run idempotent DDL via create_tables so the
-            schema exists. When False, skip ALL DDL — caller guarantees the DB
-            already exists (read-only consumers such as the web viewer).
+        create: when True (default) provision the parent directory for
+            file-backed sqlite URLs (first run on a pristine machine, #360)
+            and run idempotent DDL via create_tables so the schema exists.
+            When False, skip ALL provisioning — no DDL, no directory creation;
+            caller guarantees the DB already exists (read-only consumers such
+            as the web viewer).
 
     Returns:
         A configured sqlalchemy.Engine.
@@ -28,5 +31,6 @@ def bootstrap_engine(create: bool = True) -> sa.Engine:
     cfg = load_config()
     engine = get_engine(cfg.database_url)
     if create:
+        ensure_sqlite_dir(cfg.database_url)
         create_tables(engine)  # idempotent
     return engine

{dctracker-1.0.0 → dctracker-1.1.0}/dct/db.py

@@ -4,6 +4,8 @@ Defines all tables, engine creation, and connection helpers.
 Uses Core (not ORM) for portability between PostgreSQL and SQLite.
 """
 
+from pathlib import Path
+
 import sqlalchemy as sa
 from sqlalchemy import event
 
@@ -323,6 +325,22 @@ def _set_sqlite_wal(dbapi_connection, _connection_record):
     cursor.close()
 
 
+def ensure_sqlite_dir(database_url: str) -> None:
+    """Create the parent directory of a file-backed sqlite URL if missing.
+
+    First run on a pristine machine: the default sqlite path lives under a
+    directory that may not exist yet, and sqlite fails to open the database
+    file with a raw OperationalError instead of creating it (#360). No-op for
+    non-sqlite dialects and for memory URLs ('sqlite://', 'sqlite:///:memory:').
+    """
+    url = sa.engine.make_url(database_url)
+    if url.get_backend_name() != "sqlite":
+        return
+    if not url.database or url.database == ":memory:":
+        return
+    Path(url.database).parent.mkdir(parents=True, exist_ok=True)
+
+
 def get_engine(database_url: str) -> sa.Engine:
     kwargs = {}
     if database_url.startswith("sqlite"):

dctracker-1.1.0/dct/hooks/check-changelog-on-stop.sh

@@ -0,0 +1,112 @@
+#!/bin/bash
+# dct global Stop hook — non-blocking reminder after every turn.
+# Checks if app files changed without unreleased changelog entries.
+# Install: ~/.claude/hooks/dct-check-changelog-on-stop.sh
+#
+# Latency design (#354): the cheap git change-detection runs FIRST, so the
+# common "nothing changed" and "only exempt files changed" turns exit with
+# ZERO Python cold starts. Only when un-exempt app files changed without a
+# changelog touch do we need the project verdict — and that verdict
+# (project detect + manages-changelog) is cached per project-root path for
+# an hour, so at most one detection per project per hour instead of two
+# Python starts every turn.
+
+# Rule 2: drain stdin (Claude Code supplies Stop-hook JSON there).
+input=$(cat 2>/dev/null || true)
+
+# Rule 3: graceful on missing deps. git gates the whole hook and is checked
+# first because change-detection is the cheapest possible short-circuit.
+command -v git >/dev/null || exit 0
+command -v dct >/dev/null || exit 0
+
+# ── Fast path 1: no changed files → nothing to remind about (0 Python). ──
+changed=$(git diff --name-only 2>/dev/null; git diff --cached --name-only 2>/dev/null; git ls-files --others --exclude-standard 2>/dev/null)
+[ -z "$changed" ] && exit 0
+changed=$(echo "$changed" | sort -u)
+
+# Exempt patterns — docs/tests/config/meta files never require a changelog.
+exempt_re="^\.(claude|github|cursor|vscode|gstack)/|^docs/|^scripts/|^tests/|^test_|conftest\.py$|CLAUDE\.md$|README\.md$|LICENSE|\.gitignore$|^changelog|^CHANGELOG|^VERSION$|pyproject\.toml$|Cargo\.toml$|package\.json$"
+
+# ── Fast path 2: every change is exempt → nothing to remind about (0 Python). ──
+app_files=$(echo "$changed" | grep -vE "$exempt_re")
+[ -z "$app_files" ] && exit 0
+
+# ── Fast path 3: changelog itself was touched → already satisfied (0 Python). ──
+changelog_changed=$(echo "$changed" | grep -iE "^changelog|^CHANGELOG" | head -1)
+[ -n "$changelog_changed" ] && exit 0
+
+# Un-exempt app files changed and no changelog touched. Only now do we need
+# to know whether this project opts into dct changelog enforcement (#222).
+# Cache that verdict per project-root path to avoid two Python cold starts
+# on every turn — key = checksum of the git top-level path, TTL 3600s.
+root=$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")
+key=$(printf '%s' "$root" | cksum | cut -d' ' -f1)
+cache_dir="${TMPDIR:-/tmp}"
+cache_file="${cache_dir%/}/dct-changelog-verdict-${key}"
+ttl_min=60   # 3600s
+
+# Security: the cache lives under a shared TMPDIR at a predictable path. A
+# pre-planted symlink there would make a through-write (`>`) follow the link and
+# truncate its target — any user-writable file. Remove a symlink before reading
+# (treat as a miss) and write via mktemp-in-same-dir + `mv -f`: rename REPLACES
+# the link itself, it never follows it. This also removes partial-read races.
+[ -L "$cache_file" ] && rm -f "$cache_file"
+
+# Atomic, symlink-safe verdict write (recompute path only — keeps the fast paths
+# free of any mktemp/rename cost). $1 = verdict line.
+write_verdict() {
+  local tmp
+  tmp=$(mktemp "${cache_file}.XXXXXX" 2>/dev/null) || return 0
+  printf '%s\n' "$1" >"$tmp" 2>/dev/null || { rm -f "$tmp"; return 0; }
+  mv -f "$tmp" "$cache_file" 2>/dev/null || rm -f "$tmp"
+}
+
+cached=""
+if [ -f "$cache_file" ] && [ -n "$(find "$cache_file" -mmin -"$ttl_min" 2>/dev/null)" ]; then
+  # Strip NUL bytes BEFORE the command substitution captures the output: a
+  # corrupted cache holding NULs would otherwise make bash >=4.4 emit a
+  # "command substitution: ignored null byte in input" warning on the Stop
+  # hook's stderr (head's 2>/dev/null does not suppress that shell-level note).
+  cached=$(tr -d '\0' <"$cache_file" 2>/dev/null | head -n1 || true)
+fi
+
+case "$cached" in
+  skip:*)     exit 0 ;;                    # cached: not a dct-managed project
+  manages:?*)
+    project="${cached#manages:}"
+    # Corrupted slug (invalid chars) → treat as a miss and recompute.
+    case "$project" in
+      *[!a-zA-Z0-9._-]*) cached="" ;;
+    esac
+    ;;
+  *)          cached="" ;;                 # miss / empty / corrupted → recompute
+esac
+
+if [ -z "$cached" ]; then
+  # Cache miss — run the real detection (≤ two Python starts, ≤ once/hour/project).
+  project=$(dct project detect 2>/dev/null || true)
+  if [ -z "$project" ]; then
+    write_verdict 'skip:'
+    exit 0
+  fi
+  if dct project manages-changelog "$project" 2>/dev/null; then
+    write_verdict "manages:${project}"
+  else
+    write_verdict 'skip:'
+    exit 0
+  fi
+fi
+
+# Project manages its changelog in dct. Check dct DB for unreleased entries.
+count=$(dct clog count --project "$project" 2>/dev/null)
+if [ "${count:-0}" -gt 0 ]; then
+  exit 0
+fi
+
+# Reminder (non-blocking — always exit 0)
+file_count=$(echo "$app_files" | wc -l | tr -d ' ')
+echo ""
+echo "📝 Reminder: ${file_count} app file(s) changed in ${project}/ but no changelog entry found."
+echo "   Use /clog to add an entry."
+echo ""
+exit 0