dctracker 1.0.0__py3-none-any.whl

dct/skills/release/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: release
+description: |
+  Bump project version and release changelog entries.
+  Use when: "release", "/release", "bump version", "nowa wersja",
+  "release X.Y", "wypuść wersję", "zamknij wersję".
+---
+
+# /release — Version Bump & Changelog Release
+
+Zero-argument workflow. Auto-detects project from CWD.
+
+## Workflow
+
+### Step 0: Ensure a clean working tree (auto-commit WIP first)
+
+Run `git status --porcelain` in the project root.
+
+**Clean (empty output)** → continue to Step 1.
+
+**Dirty** → do NOT stop. The release commit (Step 7) must still contain ONLY the
+changelog file + version-synced files, so auto-commit the working changes as
+their OWN separate commit first, then continue. This preserves the reason the
+gate existed — a clean release commit is a clean revert target — while removing
+the manual interruption. The WIP simply lands in its own commit *below* the
+release commit.
+
+> Why a separate commit, not mixed in: mixing WIP code with a version bump
+> pollutes `git log` and makes rollback risky. Committing the WIP first keeps the
+> release commit changelog-only with zero friction.
+
+Auto-commit procedure (same safety rules as `/commit` — never lose history,
+never leak secrets):
+
+1. **Only genuinely-unsafe state stops the flow.** If a merge / rebase /
+   cherry-pick is in progress (`.git/MERGE_HEAD`, `.git/rebase-merge/`,
+   `.git/CHERRY_PICK_HEAD`), STOP and report — an auto-commit mid-operation is
+   unsafe. This is the ONLY hard stop in Step 0.
+2. **Stage explicitly — never `git add -A` / `git add .`.** Stage tracked
+   modifications and safe untracked files by path. EXCLUDE secrets and junk:
+   anything matching `.env*`, `*.pem`, `*.key`, `id_rsa*`, `*.p12`,
+   credential/token files, or large binaries. If such a file is dirty/untracked,
+   leave it unstaged and note it in the Step 9 report — do not commit it, do not
+   stop. Split into multiple logical commits when the changes cleanly separate by
+   file/concern (mirrors `/commit`); one commit is fine when they don't.
+3. **Message** — follow the `/commit` conventions: conventional-commit subject
+   `<type>(<scope>): <description> (v<current_version>)` derived from the staged
+   diff, with the `Co-Authored-By` trailer. If the changes span too many concerns
+   to summarize, use `chore: commit work in progress before release
+   (v<current_version>)`.
+4. **Commit.** If the pre-commit hook rejects, fix the underlying issue, re-stage,
+   and make a NEW commit (never `--amend`, never `--no-verify`).
+5. Re-run `git status --porcelain`; it MUST now be empty (modulo any
+   intentionally-skipped secret/junk files from step 2). Then continue to Step 1.
+
+### Step 1: Gather state
+Call `mcp__dct__list_projects()` and match CWD to a registered project.
+Call `mcp__dct__count_unreleased_changelog(project)`.
+Call `mcp__dct__list_changelog(project, unreleased_only=true)`.
+
+Present the state:
+```
+Project: myproj (My Project)
+Current version: 1.0
+Unreleased entries: 5
+
+  [added] New Python parser support
+  [added] Incremental indexing
+  [fixed] Parser crash on empty files
+  [fixed] Memory leak in watcher
+  [changed] Refactored graph schema
+```
+
+If there are no unreleased entries, inform the user and stop.
+
+### Step 2: Offer changelog review before bumping
+
+After showing the unreleased entries in Step 1, ask via `AskUserQuestion`:
+- question: "Ready to release, or review entries first?"
+- options:
+  - `"Go ahead — entries look correct"` → proceed to Step 2b
+  - `"Amend one entry"` → free-text `AskUserQuestion` asking which (id) and the new text, call `mcp__dct__add_changelog` for the replacement and mark the old one via `/clog` amend flow; then re-show the list
+  - `"Drop one entry"` → free-text `AskUserQuestion` for id, soft-delete via direct DB update (or flag for post-release removal); re-show the list
+  - `"Cancel release"` → stop
+
+This is the pre-stamp safety net — once Step 4 stamps, reverting requires
+manual SQL. Offering an explicit review step prevents regret.
+
+### Step 2b: Ask bump type
+
+The bump type MUST be chosen through `AskUserQuestion` — do NOT substitute a
+plain-text prompt, and do NOT infer it from the user's earlier words, even if
+they seem decided. The bump is effectively irreversible once Step 4 stamps
+(reverting needs manual SQL), so the structured options must show the semver
+implication AND the concrete resulting version number before committing to it.
+This overrides any general "a plain-text answer is fine" preference.
+
+Compute the concrete next version from `current_version` (vX.Y.Z) for each label:
+- question: `"What type of release? (current: v<current_version>)"`
+- options:
+  - `"patch — v<X.Y.(Z+1)> (bug fixes only)"`
+  - `"minor — v<X.(Y+1).0> (new features, backward compatible)"`
+  - `"major — v<(X+1).0.0> (breaking changes)"`
+  - `"explicit version — I'll type one"` → follow-up free-text AskUserQuestion
+
+### Step 3: Confirm
+```
+Release myproj 1.1?
+  5 changelog entries will be stamped
+  Version: 1.0 → 1.1
+```
+Wait for confirmation.
+
+### Step 4: Stamp version in DB
+
+Call `mcp__dct__release_changelog(project, version=<version>)`. This:
+- Updates all unreleased changelog entries with the new `version`.
+- Updates the project's `current_version` field.
+- After this call, `count_unreleased_changelog(project)` will return 0.
+
+### Step 5: Append the new version's section to the changelog file
+
+The changelog file (`F`, resolved below) is an **append-only archive**. /release ADDS the just-released
+version's section to the top of the existing file — it does NOT regenerate the
+whole file from the DB.
+
+> **Why append, not regenerate:** a full `export_changelog`
+> renders the file from DB rows only. For a project that adopted dct mid-life,
+> the DB holds only post-adoption versions, so overwriting `changelog.md`
+> silently DROPS every pre-adoption section (one such project lost 18 versions
+> / ~536 lines this way). An operation that only ever inserts cannot lose history.
+
+Let `V` = the version just stamped in Step 4 and `F` = the project's changelog
+file. **Resolve `F` via the project's `changelog_path`, do NOT hardcode
+`changelog.md`:** `F = {project.path}/{changelog_path}`, where `changelog_path`
+comes from the Step 1 `list_projects` result (default `changelog.md` when the
+field is absent — e.g. a not-yet-restarted MCP server). A project that keeps its
+changelog in a subdirectory (e.g. a monorepo with `packages/core/changelog.md`) is then
+handled transparently. Authoritative cross-check, always live:
+`dct project changelog-path <slug>` prints the resolved absolute path on its
+`→` line.
+
+**Case A — F does not exist (bootstrap / from-scratch project):**
+Call `mcp__dct__export_changelog(project, include_unreleased=false)` and write
+the full result to F. For a from-scratch project the full render equals the
+incremental one, so this is safe. Then continue to Step 6.
+
+**Case B — F already exists (the normal path):**
+
+1. Render ONLY the new section:
+   `section = mcp__dct__export_changelog(project, version=V)`.
+   - If `isinstance(section, dict)` → it is an error: do NOT touch F, report it,
+     stop (the DB was already stamped in Step 4, so either fix the export error
+     and re-run Step 5, or manually revert the stamped entries).
+   - If `section == ""` → V has no entries (unexpected after Step 4): STOP and
+     report rather than writing an empty section.
+2. Read F. Count its existing version-section markers — **lines that start with** `## [` (`grep -c '^## \['`) — call it `N`. Anchor to line start; an entry body may contain `## [` mid-text and MUST NOT be counted.
+3. **Idempotency guard:** if a **line starting with** `## [V]` already appears in F (anchored — `grep -q '^## \[V\]'`), the section is
+   already archived (e.g. a re-run after a partial release). Do NOT write —
+   report "changelog.md already contains [V]" and continue to Step 6.
+4. Insert `section` directly **below the `# Changelog` header** (keep exactly
+   one blank line after the header) so it becomes the TOP version section.
+   Every existing section MUST stay byte-for-byte unchanged below it.
+   - Preferred mechanism: an Edit whose `old_string` is the current top
+     `## [...] - ...` line and whose `new_string` is `section` + that same line
+     (i.e. prepend the new section in front of the previous top version).
+   - If F has only the `# Changelog` header and no version sections yet,
+     append `section` after the header instead.
+5. **Safety check (mandatory):** re-read F and re-count **lines starting with** `## [` (`grep -c '^## \['`). The new
+   count MUST be exactly `N + 1` — one section added, zero lost. If it is not,
+   STOP, restore F to its pre-write contents, and report. NEVER commit a
+   changelog that lost history.
+
+The DB stays the source of truth for the NEXT release's unreleased entries;
+the FILE is the source of truth for shipped history.
+
+### Step 6: Sync version-bearing files
+
+If `{project.path}/scripts/dct-version-sync.sh` exists, run it:
+```bash
+bash scripts/dct-version-sync.sh <version>
+```
+
+The sync script is **project-specific** — each project uncomments the
+relevant block in the template. Canonical patterns by project kind:
+
+| Project kind | Files to bump | sed/jq snippet |
+|---|---|---|
+| Python package | `pyproject.toml` `[project].version` | `sed -i '' "s/^version = \".*\"/version = \"$VERSION\"/" pyproject.toml` |
+| Python package (fallback) | `<pkg>/__init__.py` `__version__` | `sed -i '' "s/__version__ = \".*\"/__version__ = \"$VERSION\"/" dct/__init__.py` |
+| Rust | `Cargo.toml` `[package].version` | `sed -i '' "s/^version = \".*\"/version = \"$VERSION\"/" Cargo.toml` |
+| Node (npm/yarn) | `package.json` `.version` | `jq --arg v "$VERSION" '.version = $v' package.json > tmp && mv tmp package.json` |
+| Tauri | `src-tauri/tauri.conf.json` `.version` | `jq --arg v "$VERSION" '.version = $v' src-tauri/tauri.conf.json > tmp && mv tmp src-tauri/tauri.conf.json` |
+| Claude Code plugin | `plugin.json` `.version` | `jq --arg v "$VERSION" '.version = $v' plugin.json > tmp && mv tmp plugin.json` |
+| Swift (Info.plist) | `CFBundleShortVersionString` | `/usr/libexec/PlistBuddy -c "Set :CFBundleShortVersionString $VERSION" Info.plist` |
+
+For **monorepos** with independently-versioned sub-packages, wrap each
+block in `if has_changes "<path>"; then ... fi` so only sub-packages that
+actually changed get bumped. `has_changes` is provided by the template.
+
+For **dct itself** (Python package, single-version), the sync script is
+uncommented to always bump `pyproject.toml` + `dct/__init__.py` fallback.
+
+If the sync script doesn't exist, skip this step — DB is the source of
+truth. Inform the user so they can add one if they have build files that
+need sync.
+
+### Step 7: Commit the release
+
+Stage ONLY the artifacts touched by Steps 5 and 6:
+- `changelog.md`
+- Any files modified by `scripts/dct-version-sync.sh` (check `git status --porcelain` after Step 6)
+
+Then commit with the **literal** release message format:
+```bash
+git commit -m "release: v<version>"
+```
+
+No type, no scope, no version suffix — just `release: v1.1`. The dct global hook
+recognizes this prefix and bypasses the changelog-presence check (which would otherwise
+fail because all entries were just stamped).
+
+### Step 8: Tag the release (mandatory)
+
+Tag HEAD with the `v<version>` prefix:
+```bash
+git tag v<version>
+```
+
+Rationale: the tag is the canonical marker of "this commit = this release"
+for git log, GitHub, and future `git describe` output. Conventional `v`
+prefix matches npm, PyPI, Cargo, and GitHub release UI expectations.
+
+**Do NOT `git push --tags`** automatically — pushing to remote is a
+separate, user-confirmed action. Inform the user the tag is local; if
+they want it on the remote, they run `git push origin v<version>` or
+`git push --tags` themselves.
+
+If a tag `v<version>` already exists (rare — usually indicates a failed
+earlier release), ask the user via `AskUserQuestion`:
+  - "Tag v<version> exists. Move it to the new commit, or fail?"
+  - `"Move tag to new HEAD (--force)"`
+  - `"Leave tag alone, don't tag this commit"`
+  - `"Abort — the existing tag is correct, something is wrong with this release"`
+
+### Step 9: Report
+```
+✓ myproj released as 1.1
+  5 entries stamped
+  changelog.md: [1.1] section prepended (older history preserved)
+  Version-synced files: pyproject.toml, myproj/__init__.py
+  Commit: release: v1.1 (abc1234)
+  Tag: v1.1 (local only — run `git push origin v1.1` to push)
+```
+
+## Rules
+- NEVER release without user confirmation.
+- NEVER skip the bump type question, and NEVER substitute a plain-text prompt
+  for it — the bump type MUST be an AskUserQuestion (Step 2b). The pre-stamp
+  structured choice is the last reversible point.
+- If `current_version` is not set, ask for explicit version instead of bump type.
+- `changelog.md` is an **append-only archive**: /release only PREPENDS the new
+  version's section (Step 5 Case B), it does NOT regenerate the whole file.
+  Full-DB export is bootstrap-only (Case A, when no file exists yet). Rationale:
+  regenerating from the DB drops pre-adoption history.
+- Editing an already-released entry in the DB will NOT re-render the file —
+  shipped history lives in `changelog.md`; correct it there directly.
+- The release commit's `changelog.md` diff MUST be purely additive (one new
+  `## [vX]` section on top). If `git diff` shows deletions of older sections,
+  the append-only flow failed — STOP and investigate before committing.
+- Release commit message MUST be exactly `release: vX.Y.Z` (no scope, no description).
+  The hook's release bypass depends on this prefix.
+- The release commit contains ONLY changelog.md + version-synced files — no app
+  code. Step 0 guarantees this by auto-committing any WIP as a SEPARATE commit
+  first, so the release commit stays a clean revert target.
+- Tag is **mandatory** — every release commit gets a `v<version>` tag (Step 8).
+  A release without a tag is not a release — it's a commit that happens to bump
+  `pyproject.toml`. Tags are the git-native marker for `git describe`,
+  `git log --decorate`, GitHub's release UI, and `pip install <pkg>==<version>`.
+- Pushing the tag to remote is NOT automatic — inform the user the tag is local
+  and suggest `git push origin v<version>` (or `git push --tags`) as a separate step.

dct/skills/track/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: track
+description: |
+  Create a tracked item (issue, todo, feature, idea, improvement) in dct.
+  Use when: "track", "add issue", "add todo", "dodaj issue", "zanotuj",
+  "śledź", "track this", "new issue", "nowy issue", "zgłoś",
+  "dodaj jako problem", "problem", "bug", "błąd", "crash", "nie działa",
+  "dodaj feature", "ficzer", "dodaj ficzer", "dodaj todo",
+  "pomysł", "idea", "a może", "rozważ",
+  "poprawa", "ulepszenie", "poprawmy", "refactor", "cleanup".
+---
+
+# /track — Create Tracked Item
+
+## Type triggers — natural language → item_type
+
+Map the phrase the user actually used to the closest type. Do NOT ask
+about type unless the phrase is genuinely ambiguous. When in doubt, prefer
+`todo` (the most neutral bucket).
+
+| User says (EN / PL) | item_type | When to pick |
+|---|---|---|
+| "problem", "bug", "issue", "crash", "broken", "error", "doesn't work", "regression" / "problem", "błąd", "bug", "crash", "nie działa", "popsute", "zepsute" | **issue** | Observable defect in existing code/system. Reproducible wrong behavior. |
+| "todo", "task", "action item", "need to", "must do" / "todo", "zadanie", "zrobić", "do zrobienia", "trzeba" | **todo** | Concrete work that's neither a bug nor a new user-visible capability. Generic "stuff to do". |
+| "feature", "add X", "new capability", "let's build", "we should have" / "feature", "ficzer", "funkcja", "dodajmy", "zbudujmy", "nowa funkcja" | **feature** | New user-visible capability that doesn't exist yet. |
+| "idea", "maybe", "what if", "consider", "brainstorm", "explore" / "pomysł", "idea", "a może", "rozważ", "zastanów się", "pomyślmy" | **idea** | Exploratory — not yet decided to build. May become a feature later. |
+| "improvement", "refactor", "polish", "cleanup", "tidy up", "make X nicer" / "ulepszenie", "poprawa", "poprawmy", "polerka", "cleanup", "refactor", "uporządkuj" | **improvement** | Existing thing works but could be better (refactor, UX polish, perf, docs). |
+
+### Examples
+
+| Phrase | item_type | Why |
+|---|---|---|
+| "dodaj jako problem że parser się wywala na pustych plikach" | issue | "problem" + observable broken behavior |
+| "dodaj ficzer, chcę zrobić dark mode" | feature | "ficzer" + new capability |
+| "a może pomyślmy nad wtyczkami?" | idea | "a może" + exploratory |
+| "trzeba uporządkować ten moduł parsera" | improvement | "uporządkować" + existing code |
+| "dodaj todo — wysłać PR do review" | todo | explicit "todo", generic task |
+
+## Workflow
+
+### Step 1: Infer type, then gather rest
+
+From the conversation context, determine:
+
+- **project**: Detect from CWD using `mcp__dct__list_projects()` (longest path prefix), or ask if ambiguous
+- **item_type**: Infer from the user's phrasing per the table above
+- **title**: Concise summary (max ~80 chars)
+- **priority**: P1 (blocks work / data loss / security), P2 (important — default), P3 (backlog), future (post-v1)
+- **description**: Details, context, steps to reproduce (for issues) — prose, not checkbox lists
+- **component**: Module or subsystem (optional)
+- **source_file**: Relative path where the item lives (optional)
+- **source_lines**: Line range, e.g. "42-58" (optional)
+- **tags**: Comma-separated labels (optional)
+
+### Step 2: Confirm with user
+
+Present the proposed item (short form — no wall of JSON):
+
+```
+Track this?
+  Type:     issue
+  Priority: P1
+  Title:    Parser crashes on empty files
+  File:     cmd/parse.go:42-58
+  Tags:     parser, crash
+```
+
+Wait for confirmation or corrections. If user said "just add it" or similar,
+skip confirmation.
+
+### Step 3: Create
+
+Call `mcp__dct__create_item(project, item_type, title, ...)` with all fields.
+**REMEMBER the returned `id`** — needed for any follow-up (add_checkpoint,
+update_item, resolve_item).
+
+### Step 4: Sketch checkpoints (feature / improvement only)
+
+If `item_type` ∈ {feature, improvement}, IMMEDIATELY after create_item,
+call `add_checkpoint` 3-7 times to break the work into concrete steps.
+Do this BEFORE starting any code. Remember each checkpoint id.
+
+Skip for `issue`, `todo`, `idea` unless the user explicitly asks for a
+checkpoint breakdown.
+
+### Step 5: Report
+
+```
+✓ #42 issue/P1 — Parser crashes on empty files
+```
+
+For feature/improvement with checkpoints:
+```
+✓ #43 feature/P2 — Dark mode
+  Checkpoints: 5 (ready to track)
+```
+
+## Priority mapping
+
+P2 is the fallback ONLY when the user gives no priority cue. Read their
+language first — urgency words trump the default.
+
+| User phrasing | priority |
+|---|---|
+| "blocker", "blokuje", "data loss", "security", "critical", "pilne", "urgent", "krytyczne", "ważne" | **P1** |
+| No urgency cue, neutral report | P2 (default) |
+| "kiedyś", "backlog", "eventually", "nice to have", "low prio", "niski priorytet" | **P3** |
+| "post-v1", "long-term", "someday", "może w przyszłości", "future" | **future** |
+
+Never silently default to P2 when the user said "ważne" or "pilne" — that
+would bury a P1 in the backlog.
+
+## Rules
+
+- **Never ask about type** if the phrase maps cleanly per the table. Claude's
+  job is to read the language, not interrogate the user.
+- **Never silently create** — always show the draft and wait for confirmation
+  (exception: user explicitly waived with "just add it", "szybko", "don't ask").
+- **REMEMBER the returned id** — it's the handle for every future operation.
+- **Checkpoints are mandatory for feature/improvement** — the visible
+  plan is the contract. No "I'll add them later" — add before coding.

dct/skills/track-list/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: track-list
+description: |
+  List and search tracked items across projects. Supports priority grouping,
+  file hotspots, and cross-project aggregation.
+  Use when: "list issues", "show todos", "what's open", "pokaż issues",
+  "co mamy", "backlog", "track-list", "all items", "open issues".
+---
+
+# /track-list — List Tracked Items
+
+Default: open items in the current project (auto-detected from CWD), grouped
+by priority (P1 → P2 → P3 → future), compact `{cols, rows}` format. Resolved
+items are hidden unless explicitly requested.
+
+## Routing — direct vs subagent
+
+Pick based on cost, not habit. Main context is precious.
+
+**Run directly (main context)** when:
+- Single project, ≤50 open items expected
+- Single #ID lookup (`/track-list #42` → `mcp__dct__get_item(42)`)
+- Simple filter (priority / type / component / in_sprint)
+
+**Delegate to subagent** (`Agent` tool with `subagent_type=Explore` or `general-purpose`) when:
+- **Cross-project aggregation** (no `project` filter, >1 registered project with >20 items each)
+- **Hotspot detection** (needs to group by `source_file` across items — Python-side work, not SQL)
+- **Cross-source matching** (e.g. "which items share a changelog entry? which are in the sprint AND have stale checkpoints?")
+- Expected output >200 rows
+- Long free-text search across large description bodies
+
+Subagent returns a concise summary. You relay that summary, not the raw rows — keeps your context lean.
+
+## Workflow
+
+### Step 1: Parse user intent
+
+Extract from the request:
+- **project**: explicit slug, `--all`/"all"/"cross-project" → empty (cross-project), otherwise auto-detect from CWD via `mcp__dct__list_projects` longest-prefix match
+- **status**: default `"open"`. Accepts `"in_progress"`, `"resolved"`, `"wont_fix"`, or `""` for all. Convenience aliases: `--all-statuses`, `--include-resolved`
+- **item_type**: `issue`/`todo`/`feature`/`idea`/`improvement`, or empty
+- **priority**: `P1`/`P2`/`P3`/`future`, or empty
+- **component**: match exact component name
+- **in_current_sprint**: `"true"` (only sprint), `"false"` (exclude sprint), or empty
+- **search**: free-text, searched in `title` + `description`
+- **limit**: default 50
+
+ID normalization (from `#42`, `42`, `ITEM-42`, `item-42`, `ITEM_42`, `item_42`, `0042` → `42`): regex `^(#|ITEM-|item-|ITEM_|item_)?0*(\d+)$` — case-insensitive prefix strip, leading-zero strip, cast int. Uniform with /track-update and /track-resolve. If a single ID is given, skip listing and go to `mcp__dct__get_item(id)`.
+
+### Step 2: Query
+
+Call `mcp__dct__list_items(project, status, item_type, priority, component, in_current_sprint, search, limit, format="structured")`.
+
+Response shape:
+```
+{"cols": ["id","item_type","priority","status","in_current_sprint","cp","component","tags","created_at","title","description"],
+ "rows": [[22,"improvement","P2","open",false,[0,0],"server",["mcp"],"2026-04-17","Optimize...","..."]]}
+```
+
+### Step 3: Present — priority grouping
+
+Group rows by priority (P1 → P2 → P3 → future). Within each group sort by `cp` progress descending (most-done first), then by `created_at` ascending (oldest first).
+
+Render as markdown:
+
+```
+## P1 — blocking (2)
+| #   | Type  | Sprint | cp    | Component | Title                         |
+|-----|-------|--------|-------|-----------|-------------------------------|
+| 42  | issue | ●      | 2/3   | parser    | Crash on empty files          |
+| 88  | todo  |        | 0/0   | auth      | Rotate session tokens         |
+
+## P2 — important (11)
+...
+
+## P3 — backlog (4)
+...
+```
+
+Use `●` for `in_current_sprint=true`, blank for false. Use `cp` as `done/total` string (e.g. `2/5`) from the raw `[2,5]` array.
+
+### Step 4: Hotspots (only if explicitly asked OR >1 hotspot auto-detected)
+
+A **hotspot** is a file/component with ≥2 open items. Run Python-side aggregation on the rows (no extra DB call).
+
+Trigger automatically when rows.length ≥ 20 AND at least one file has ≥2 items. The thresholds are empirical — below 20 items a hotspot section is noise (few rows, hotspots self-evident); above 20, the extra section reveals structural debt clusters. Otherwise show only on request (`/track-list --hotspots`).
+
+```
+## Hotspots (top 3 files by open-item count)
+| Path                     | Open | P1 | Titles                              |
+|--------------------------|------|----|-------------------------------------|
+| dct/server.py            | 4    | 0  | #22, #6, #14, #20                   |
+| dct/skills/track-list/SKILL.md | 3 | 0 | #6, #14, #19                      |
+| dct/core/items.py        | 2    | 0  | #4, #23 (resolved)                  |
+```
+
+If no source_file on items, skip this section.
+
+### Step 5: Cross-project summary (only when no project filter)
+
+When `project` is empty (cross-project mode), prepend a summary line:
+
+```
+Cross-project: 37 open items in 4 projects (dct: 13, proj-a: 87, proj-b: 63, proj-c: 35)
+```
+
+Then show **top 3 priorities cross-project**, skipping detailed rows (delegate full listings to subagent if user asks).
+
+### Step 6: Final summary line
+
+Always end with a count:
+```
+Showing 13 open items in dct. Use /track-list --include-resolved to show closed.
+```
+
+## Shortcuts
+
+- `/track-list` — open items in current project
+- `/track-list #42` — direct `get_item(42)` (skips list)
+- `/track-list proj-a` — items in project `proj-a`
+- `/track-list --all` — cross-project (delegate to subagent if >100 expected)
+- `/track-list P1` — P1-only filter
+- `/track-list parser` — search "parser" in title/description
+- `/track-list --sprint` — only `in_current_sprint=true`
+- `/track-list --hotspots` — force hotspot section
+- `/track-list --include-resolved` — include resolved + wont_fix
+
+## Rules
+
+- **Always parse with ID normalization regex**. Do not reject `#42` because of the hash sign.
+- **Default hides resolved** — do not surprise the user with closed items unless they ask.
+- **Prefer subagent for cross-project** when ≥2 projects have ≥20 open items each. Tell the user: "Cross-project aggregation — delegating to subagent".
+- **`cp` column is authoritative** — do not re-query per-item to compute progress (N+1).
+- **Don't show `description` in the table** (it's in cols but too long for a grid row). Keep it available for follow-up `get_item` calls. Render only `title` in the grid.

dct/skills/track-resolve/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: track-resolve
+description: |
+  Resolve or close a tracked item in dct.
+  Use when: "resolve issue", "close item", "mark as done", "zamknij issue",
+  "track-resolve", "wont fix", "done with #42".
+---
+
+# /track-resolve — Resolve/Close Item
+
+## Workflow
+
+### Step 1: Identify item(s)
+
+**ID normalization** — accept all of these forms:
+- `#42`, `42`, `ITEM-42`, `item-42`, `0042`
+
+Parse by: strip leading `#`, strip `ITEM-` / `item-` prefix (case-insensitive), strip leading zeros, cast to integer.
+Regex: `^(#|ITEM-|item-|ITEM_|item_)?0*(\d+)$` — capture group 2 is the numeric id.
+
+**Batch resolution** — user may pass multiple IDs separated by whitespace or commas:
+```
+/track-resolve #42 #45 #51          ← three items in one call
+/track-resolve 42, 45, 51            ← comma form
+/track-resolve ITEM-42 #45           ← mixed forms
+```
+Split input on whitespace and commas, normalize each id, then call `resolve_item` once per id.
+
+Call `mcp__dct__get_item(item_id)` for each id to fetch current state.
+
+### Step 2: Determine resolution
+- **resolved**: Fixed, implemented, completed
+- **wont_fix**: Intentionally not addressing
+
+Build resolution note from context:
+- If a commit was just made: "Fixed in commit {hash}"
+- If decision: "Decision: {reason}"
+- Ask user if context is insufficient
+
+### Step 3: Confirm
+```
+Resolve #42 — Parser crashes on empty files?
+  Status:     open → resolved
+  Resolution: Fixed in commit abc1234
+```
+
+### Step 4: Execute
+Call `mcp__dct__resolve_item(item_id, status, resolution)`.
+
+### Step 5: Report
+```
+✓ #42 → resolved
+```