dctracker 1.0.0__tar.gz → 1.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dctracker
-Version: 1.0.0
+Version: 1.2.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
@@ -21,6 +21,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: sqlalchemy>=2.0
 Requires-Dist: python-ulid>=2.0
+Requires-Dist: platformdirs>=4.9.6; sys_platform == "win32"
 Provides-Extra: pg
 Requires-Dist: psycopg[binary]; extra == "pg"
 Provides-Extra: mcp
@@ -47,7 +48,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.
 
@@ -104,9 +105,9 @@ release day the changelog is already written:
 
 ```text
 > /release
-15 unreleased entries → stamped as 1.1.0
+15 unreleased entries → stamped as 1.4.0
 changelog.md regenerated (Keep a Changelog format)
-release: v1.1.0 committed, project version bumped
+release: v1.4.0 committed, project version bumped
 ```
 
 One command stamps the version, exports [Keep a Changelog](https://keepachangelog.com)
@@ -121,7 +122,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
@@ -165,13 +166,13 @@ dct init
 
 The interactive wizard walks through the one-time global bootstrap:
 
-1. **Database backend** — `sqlite` (default, zero setup at `~/.claude/dct.db`) or `postgresql` (you supply the URL). It test-connects before saving.
+1. **Database backend** — `sqlite` (default, zero setup at the platform data dir, e.g. `~/.local/share/dctools/dct.db`) or `postgresql` (you supply the URL). It test-connects before saving.
 2. **Register projects** — for each project it asks slug / path / name, then **auto-detects the version** from `VERSION`, `pyproject.toml`, `package.json`, `Cargo.toml`, or `src-tauri/tauri.conf.json`. If none matches, you get an interactive prompt (`0.0.1` / `0.1.0` / `1.0.0` shortcuts); in non-tty contexts it stores `current_version=NULL` and reminds you to set it later. Register more any time with `dct project add`.
 3. **MCP server** — registered at **user scope** in `~/.claude.json` (via `claude mcp add --scope user`, with a direct-edit fallback), so `/track`, `/clog`, `/release`, and the MCP tools are available in **every** Claude Code session, from any directory.
 4. **Skills + hooks** — symlinks the skills into `~/.claude/skills/` and the four hooks into `~/.claude/hooks/`. Both ship inside the package; with an editable/dev install the symlinks point at the repo, so a fix goes live without reinstall.
 5. **Hook wiring** — with your consent, merges the hooks into `~/.claude/settings.json`. The merge is idempotent, backs up the file before the first write, and never touches hooks you already have. Re-run any time with `dct hooks wire`.
 
-`dct init` writes `~/.claude/dct.toml`, `~/.claude.json` (MCP entry), the skill/hook symlinks, and (opt-in) the settings.json wiring — see [docs/architecture.md](docs/architecture.md) for the full config reference and scope model.
+`dct init` writes the config to the platform config dir (`~/.config/dctools/dct.toml`; existing `~/.claude/dct.toml` installs keep working — `dct migrate-home` moves them), `~/.claude.json` (MCP entry), the skill/hook symlinks, and (opt-in) the settings.json wiring — see [docs/architecture.md](docs/architecture.md) for the full config reference and scope model.
 
 ### Your first session
 
@@ -200,6 +201,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 the dct config file (`dct config path` shows where it lives). 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
@@ -239,26 +250,39 @@ dct checkpoint add 42 "Write parser"
 dct checkpoint list 42
 dct checkpoint done 3                 # Mark CP #3 as done
 dct checkpoint reject 4               # Scope-change, keep in ledger
+
+# Sprints (first-class, named units of work; /handoff manages the current-sprint set)
+dct sprint list --status active
+dct sprint create "Payments hardening" --code pay-1 --goal "Close the P1 backlog"
+dct sprint show 3                     # Details + linked items
+dct sprint activate 3                 # Shortcuts: activate / complete / defer
+
+# Handoffs (amend an unconsumed handoff in place; creation is /handoff or MCP)
+dct handoff update 12 --prompt "Wire the toggle into settings next"
+
+# Config
+dct config get integrations.claude.task_mirror   # Read a dotted config key
+dct config path                       # Show resolved config/data locations
 ```
 
 ## 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
 
@@ -278,7 +302,7 @@ dct web status              # show pid + URL
 dct web stop                # SIGTERM the daemon
 ```
 
-If the preferred port (default `8787`) is busy, the daemon auto-selects the next free port (disable with `--no-fallback`). Configure defaults under `[web]` in `~/.claude/dct.toml`.
+If the preferred port (default `8787`) is busy, the daemon auto-selects the next free port (disable with `--no-fallback`). Configure defaults under `[web]` in the dct config file.
 
 ![dct web viewer — read-only dashboard over all registered projects](docs/assets/web-viewer.png)
 
@@ -323,26 +347,26 @@ Manual wiring reference (full JSON) and the five rules every dct hook follows: [
 
 ## Configuration
 
-dct reads `~/.claude/dct.toml`. The minimal config is just the database URL:
+dct reads its config from the platform config dir — `~/.config/dctools/dct.toml` on Linux and macOS, `%LOCALAPPDATA%\dctools\dct.toml` on Windows — with a permanent fallback to a legacy `~/.claude/dct.toml` (run `dct migrate-home` to move an old install). The minimal config is just the database URL:
 
 ```toml
 [database]
-url = "sqlite:////Users/you/.claude/dct.db"
+url = "sqlite:////home/you/.local/share/dctools/dct.db"
 # or: url = "postgresql+psycopg://localhost:5432/dct"
 ```
 
-The `DCT_DATABASE_URL` environment variable overrides `[database].url`. For the full reference (`[plans]`, `[mirror]`, `[web]` sections), the database schema, MCP scope precedence, and project auto-detection mechanics, see **[docs/architecture.md](docs/architecture.md)**.
+The `DCT_DATABASE_URL` environment variable overrides `[database].url`. For the full reference (`[classification]`, `[integrations.claude]`, `[web]` sections), the database schema, MCP scope precedence, and project auto-detection mechanics, see **[docs/architecture.md](docs/architecture.md)**.
 
 ## Testing
 
 ```bash
-.venv/bin/pytest -q                    # All tests (670)
+.venv/bin/pytest -q                    # All tests (938)
 .venv/bin/pytest tests/test_plan_parser.py -v          # Parser only
 .venv/bin/pytest tests/test_plan_ingest.py -v          # Ingest + sticky-resolved semantics
 
 # MCP server smoke (boot + tool list)
 uv run --no-project --with 'mcp[cli]' --with sqlalchemy --with 'psycopg[binary]' \
-  python -c "import asyncio; from dct.server import mcp; \
+  python -c "import asyncio; from dct.mcp.server import mcp; \
   print(len(asyncio.run(mcp.list_tools())), 'tools')"
 ```
 

{dctracker-1.0.0 → dctracker-1.2.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.
 
@@ -62,9 +62,9 @@ release day the changelog is already written:
 
 ```text
 > /release
-15 unreleased entries → stamped as 1.1.0
+15 unreleased entries → stamped as 1.4.0
 changelog.md regenerated (Keep a Changelog format)
-release: v1.1.0 committed, project version bumped
+release: v1.4.0 committed, project version bumped
 ```
 
 One command stamps the version, exports [Keep a Changelog](https://keepachangelog.com)
@@ -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
@@ -123,13 +123,13 @@ dct init
 
 The interactive wizard walks through the one-time global bootstrap:
 
-1. **Database backend** — `sqlite` (default, zero setup at `~/.claude/dct.db`) or `postgresql` (you supply the URL). It test-connects before saving.
+1. **Database backend** — `sqlite` (default, zero setup at the platform data dir, e.g. `~/.local/share/dctools/dct.db`) or `postgresql` (you supply the URL). It test-connects before saving.
 2. **Register projects** — for each project it asks slug / path / name, then **auto-detects the version** from `VERSION`, `pyproject.toml`, `package.json`, `Cargo.toml`, or `src-tauri/tauri.conf.json`. If none matches, you get an interactive prompt (`0.0.1` / `0.1.0` / `1.0.0` shortcuts); in non-tty contexts it stores `current_version=NULL` and reminds you to set it later. Register more any time with `dct project add`.
 3. **MCP server** — registered at **user scope** in `~/.claude.json` (via `claude mcp add --scope user`, with a direct-edit fallback), so `/track`, `/clog`, `/release`, and the MCP tools are available in **every** Claude Code session, from any directory.
 4. **Skills + hooks** — symlinks the skills into `~/.claude/skills/` and the four hooks into `~/.claude/hooks/`. Both ship inside the package; with an editable/dev install the symlinks point at the repo, so a fix goes live without reinstall.
 5. **Hook wiring** — with your consent, merges the hooks into `~/.claude/settings.json`. The merge is idempotent, backs up the file before the first write, and never touches hooks you already have. Re-run any time with `dct hooks wire`.
 
-`dct init` writes `~/.claude/dct.toml`, `~/.claude.json` (MCP entry), the skill/hook symlinks, and (opt-in) the settings.json wiring — see [docs/architecture.md](docs/architecture.md) for the full config reference and scope model.
+`dct init` writes the config to the platform config dir (`~/.config/dctools/dct.toml`; existing `~/.claude/dct.toml` installs keep working — `dct migrate-home` moves them), `~/.claude.json` (MCP entry), the skill/hook symlinks, and (opt-in) the settings.json wiring — see [docs/architecture.md](docs/architecture.md) for the full config reference and scope model.
 
 ### Your first session
 
@@ -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 the dct config file (`dct config path` shows where it lives). 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
@@ -197,26 +207,39 @@ dct checkpoint add 42 "Write parser"
 dct checkpoint list 42
 dct checkpoint done 3                 # Mark CP #3 as done
 dct checkpoint reject 4               # Scope-change, keep in ledger
+
+# Sprints (first-class, named units of work; /handoff manages the current-sprint set)
+dct sprint list --status active
+dct sprint create "Payments hardening" --code pay-1 --goal "Close the P1 backlog"
+dct sprint show 3                     # Details + linked items
+dct sprint activate 3                 # Shortcuts: activate / complete / defer
+
+# Handoffs (amend an unconsumed handoff in place; creation is /handoff or MCP)
+dct handoff update 12 --prompt "Wire the toggle into settings next"
+
+# Config
+dct config get integrations.claude.task_mirror   # Read a dotted config key
+dct config path                       # Show resolved config/data locations
 ```
 
 ## 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
 
@@ -236,7 +259,7 @@ dct web status              # show pid + URL
 dct web stop                # SIGTERM the daemon
 ```
 
-If the preferred port (default `8787`) is busy, the daemon auto-selects the next free port (disable with `--no-fallback`). Configure defaults under `[web]` in `~/.claude/dct.toml`.
+If the preferred port (default `8787`) is busy, the daemon auto-selects the next free port (disable with `--no-fallback`). Configure defaults under `[web]` in the dct config file.
 
 ![dct web viewer — read-only dashboard over all registered projects](docs/assets/web-viewer.png)
 
@@ -281,26 +304,26 @@ Manual wiring reference (full JSON) and the five rules every dct hook follows: [
 
 ## Configuration
 
-dct reads `~/.claude/dct.toml`. The minimal config is just the database URL:
+dct reads its config from the platform config dir — `~/.config/dctools/dct.toml` on Linux and macOS, `%LOCALAPPDATA%\dctools\dct.toml` on Windows — with a permanent fallback to a legacy `~/.claude/dct.toml` (run `dct migrate-home` to move an old install). The minimal config is just the database URL:
 
 ```toml
 [database]
-url = "sqlite:////Users/you/.claude/dct.db"
+url = "sqlite:////home/you/.local/share/dctools/dct.db"
 # or: url = "postgresql+psycopg://localhost:5432/dct"
 ```
 
-The `DCT_DATABASE_URL` environment variable overrides `[database].url`. For the full reference (`[plans]`, `[mirror]`, `[web]` sections), the database schema, MCP scope precedence, and project auto-detection mechanics, see **[docs/architecture.md](docs/architecture.md)**.
+The `DCT_DATABASE_URL` environment variable overrides `[database].url`. For the full reference (`[classification]`, `[integrations.claude]`, `[web]` sections), the database schema, MCP scope precedence, and project auto-detection mechanics, see **[docs/architecture.md](docs/architecture.md)**.
 
 ## Testing
 
 ```bash
-.venv/bin/pytest -q                    # All tests (670)
+.venv/bin/pytest -q                    # All tests (938)
 .venv/bin/pytest tests/test_plan_parser.py -v          # Parser only
 .venv/bin/pytest tests/test_plan_ingest.py -v          # Ingest + sticky-resolved semantics
 
 # MCP server smoke (boot + tool list)
 uv run --no-project --with 'mcp[cli]' --with sqlalchemy --with 'psycopg[binary]' \
-  python -c "import asyncio; from dct.server import mcp; \
+  python -c "import asyncio; from dct.mcp.server import mcp; \
   print(len(asyncio.run(mcp.list_tools())), 'tools')"
 ```
 

{dctracker-1.0.0 → dctracker-1.2.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.2.0"

dctracker-1.2.0/dct/assets/__init__.py

@@ -0,0 +1,19 @@
+"""Packaged asset locations — the single indirection for skill/hook dirs.
+
+The PHYSICAL directories stay at dct/skills and dct/hooks: the host's
+~/.claude symlinks point into them, so moving them is a breaking change
+reserved for 2.0.0 (ADR #52 froze every public surface for 1.2.0). When
+that window opens, this module is the one place that changes.
+"""
+
+from pathlib import Path
+
+_PKG_ROOT = Path(__file__).resolve().parent.parent
+
+
+def skills_dir() -> Path:
+    return _PKG_ROOT / "skills"
+
+
+def hooks_dir() -> Path:
+    return _PKG_ROOT / "hooks"