feat: add runtime overlays and MCP patch tools

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Something isn't working as documented.
+title: ""
+labels: bug
+---
+
+## Summary
+
+<!-- One sentence. -->
+
+## Reproduction
+
+Commands run, expected result, actual result.
+
+```
+$ llm-tracker ...
+```
+
+## Environment
+
+- OS:
+- Node version (`node --version`):
+- llm-tracker version (`npm list -g llm-tracker` or the CLI's output):
+
+## Logs
+
+<!-- Daemon log, hub output, or the JSON payload of a failing request. Redact tokens. -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Suggest a capability or change.
+title: ""
+labels: enhancement
+---
+
+## Problem
+
+<!-- What are you trying to do that the tracker doesn't support today? -->
+
+## Proposed solution
+
+## Alternatives considered
+
+## Additional context
+
+<!-- Related tickets, prior art, or agent/LLM workflow details. -->

.github/pull_request_template.md

@@ -0,0 +1,24 @@
+## Summary
+
+<!-- What does this PR do, in one or two sentences? -->
+
+## Motivation
+
+<!-- Why is this change needed? Link related issues. -->
+
+## Test plan
+
+- [ ] `npm test` passes locally
+- [ ] New behavior has a test under `test/`
+
+## Docs
+
+- [ ] `README.md` updated if user-facing CLI/HTTP contract changed
+- [ ] `workspace-template/README.md` updated if the agent contract (served at `/help`) changed
+- [ ] `ARCHITECTURE.md` updated if internals changed materially
+- [ ] `MIGRATING.md` updated if the change is breaking
+
+## Checklist
+
+- [ ] PR title follows [Conventional Commits](https://www.conventionalcommits.org/) (`feat`, `fix`, `perf`, `revert`, `docs`, `refactor`, `build`, `ci`, `chore`, `test`)
+- [ ] I have NOT hand-edited `CHANGELOG.md` (release-please owns it)

.github/workflows/ci.yml

@@ -29,3 +29,5 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm test
+      - run: npm pack --dry-run
+        name: Verify package contents

.gitignore

@@ -10,3 +10,4 @@ coverage/
 
 # Project-local scratch
 initial prompt.txt
+.llm-tracker/

AGENTS.md

@@ -0,0 +1,43 @@
+# AGENTS.md
+
+When you are working against a running `llm-tracker` hub, fetch `GET /help` first.
+
+Why:
+
+- `/help` is the current agent contract for that workspace.
+- It serves the workspace `README.md`, which is copied from [`workspace-template/README.md`](./workspace-template/README.md).
+- It is the endpoint LLMs should use instead of guessing paths, write modes, or status vocabulary.
+
+If you change any agent-facing behavior, keep these in sync:
+
+- `workspace-template/README.md` because `/help` serves it
+- `README.md` for human-facing usage and reminders
+- `AGENTS.md` when the repo-level workflow changes
+- the MCP layer (`llm-tracker mcp`) when the HTTP/CLI contract changes, including tools, resources, and prompts
+
+For this repo specifically:
+
+- keep `/help` accurate when you add or change agent-facing endpoints or commands
+- prefer additive updates to the contract rather than silent behavior changes
+- if MCP is available, prefer `tracker_help`, `tracker_projects_status`, `tracker_project_status`, `tracker_next`, `tracker_search`, `tracker_fuzzy_search`, `tracker_brief`, `tracker_why`, `tracker_decisions`, `tracker_execute`, `tracker_verify`, `tracker_blockers`, `tracker_changed`, `tracker_history`, `tracker_patch`, `tracker_pick`, `tracker_undo`, `tracker_redo`, and `tracker_reload` over raw `curl`
+- if MCP resources are available, prefer `tracker://help` for the contract and `tracker://workspace/runtime` for daemon + patch workflow details before rereading the full README
+- if MCP prompts are available, start with `tracker_start_here` and use the workflow prompts instead of inventing your own tool order
+- remember the MCP daemon rule: read tools work directly from workspace files; write tools (`tracker_patch`, `tracker_pick`, `tracker_undo`, `tracker_redo`, `tracker_reload`) require the hub or daemon to be reachable
+- remind agents to use `/help`, `next`, `search` or `fuzzy-search`, `brief`, `why`, `decisions`, `execute`, `verify`, `blockers`, `changed`, and `pick` before they fall back to broad file reads
+- if the human wants direct zero-token terminal shortcuts in Codex or Claude, use `llm-tracker shortcuts`; prompt/skill helpers still spend model tokens
+- when adding tasks through patch mode, only append genuinely open work; brand-new patch tasks must start as `not_started` or `in_progress`, not `complete` or `deferred`
+- if an idea is already folded into an existing owning row, update that row instead of appending a standalone docs/workflow task and retiring it immediately
+- treat bare URLs in `reference` / `references[]` as invalid; use repo-relative `path:line` or `path:line-line`
+- if `/search` returns a warning, treat that as a degraded local semantic runtime, not as a tracker-data failure; the hub now tries native semantic, then local WASM semantic, then a bundled offline hash semantic runtime, and only then fuzzy fallback
+- if `/search` returns `backend: "semantic_hash_fallback"`, continue with the returned matches; that means the local model runtime is unavailable but the bundled offline semantic fallback is still working
+- if `/search` returns `backend: "fuzzy_fallback"`, continue with the returned matches or call `fuzzy-search` explicitly instead of blaming tracker data
+- if a slug exists on disk but 404s from the hub, retry once first because the hub auto-reloads missing slugs on demand, then prefer `reload` before asking for a daemon restart
+- for metadata backfills on existing projects, prefer bounded active tasks before broad roadmap rows, verify with `next` / `brief` / `execute` / `verify` / `search`, and stop before commit or PR refresh unless the human explicitly asked for that step
+- do not call a patch that only adds `references[]`, `effort`, `related`, or `comment` a complete migration batch for active work; that is retrieval-only enrichment unless execution-contract fields were intentionally out of scope
+- if the human explicitly asks you to relink a shared symlinked project registration to a different branch/worktree file and the slug is already registered, the safe sequence is: verify target -> `DELETE /api/projects/<slug>` to remove only the workspace symlink registration -> re-link the slug -> `reload` -> verify a read call before writing patches
+- for linked shared-workspace projects, `GET /api/projects/<slug>` and successful `POST /api/projects/<slug>/patch` responses include `file`, the effective tracker JSON path the hub writes; use that instead of guessing whether a linked repo file will get dirtied
+- for linked shared-workspace projects, high-churn runtime fields (`status`, `assignee`, `blocker_reason`, `meta.scratchpad`, `updatedAt`, `rev`) now live in `<shared-workspace>/.runtime/overlays/<slug>.json`; durable tracker edits still write through to the linked repo-local file
+- for active-task backfills, evaluate the whole author-owned field set, not just the obvious subset: `goal`, `references[]`, `related`, `comment`, `context.tags`, `context.notes`, `context.files_touched`, `blocker_reason`, `effort`, `definition_of_done`, `constraints`, `expected_changes`, `allowed_paths`, and `approval_required_for`
+- the migration guide's field order is a sequence, not permission to ignore the rest of the author-owned fields when evidence exists
+- for linked repo-local trackers such as `<repo>/.llm-tracker/trackers/<slug>.json` or `<repo>/.phalanx/<slug>.json`, keep repo file references portable and relative to the repo root; do not rewrite them into machine-specific absolute paths just to force snippet extraction
+- if a valid repo-relative reference is not producing snippets, verify the shared workspace link and use `reload`; treat persistent misses as a resolver/runtime issue to report, not as a reason to bake absolute paths into tracker data