vibeops-tracker 0.1.0

package/AUTHORS

@@ -0,0 +1,10 @@
+VibeOps Tracker authors and maintainers
+
+Created and maintained by:
+  Igor Gembitsky  <https://github.com/igembitsky>
+
+VibeOps Tracker is an original project by Igor Gembitsky. A local-first issue
+tracker and triage board for solo builders juggling many projects at once.
+
+Contributions are welcome; contributors who land changes will be listed here.
+See CONTRIBUTING.md to get started.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Gembitsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,209 @@
+# VibeOps Tracker
+
+**A local-first issue tracker for builders juggling a dozen projects at once.**
+Capture a bug or idea the moment you spot it, prioritize it on a Kanban board,
+and hand it to AI coding agents. Everything runs on your machine, nothing in the
+cloud.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/vibeops-tracker?style=flat-square)](https://www.npmjs.com/package/vibeops-tracker)
+[![CI](https://github.com/igembitsky/vibeops-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/igembitsky/vibeops-tracker/actions/workflows/ci.yml)
+![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](CONTRIBUTING.md)
+
+When you build several things at once, the work that breaks your flow isn't the
+big feature. It's the steady drip of small ones. You're testing a side project,
+you notice a misaligned button, a missing validation, a "wouldn't it be nice."
+Stop to fix each one and you never finish anything; open a tab to track it and
+the idea rots in a list you never reopen. VibeOps Tracker is the place to **put
+it down and keep moving**, then pick it up, prioritize it, and ship it (or let
+an agent ship it) when the time is right.
+
+It runs entirely on your machine. No account, no telemetry, no cloud. Your
+issues are plain markdown files in a folder you control.
+
+![The board](docs/screenshots/board.png)
+
+## Quickstart
+
+```bash
+npx vibeops-tracker          # board at http://localhost:4400
+```
+
+That's it. No install, no config, no database. Prefer to clone it?
+
+```bash
+git clone https://github.com/igembitsky/vibeops-tracker.git
+cd vibeops-tracker
+npm install
+npm start                    # board at http://localhost:4400
+```
+
+Requires Node 20+. Your data lives in a local `data/` folder (when cloned) or
+your OS app-data directory (when installed globally). Run `vibeops where` to
+see exactly where.
+
+## Three ways to capture
+
+The whole point is to make capturing an issue cheaper than the urge to ignore
+it. So there are three on-ramps, and you can mix them freely:
+
+**1. From any running app, with the widget.** Drop one line into a project's HTML:
+
+```html
+<script src="http://localhost:4400/widget.js" data-project="my-app" defer></script>
+```
+
+A floating 🐞 button appears. Highlight the thing you're talking about, click
+the button, and the issue is captured with the selected text plus a context
+snapshot: the URL, the viewport, and (for bugs) an activity trail of your last
+clicks, network calls, and JavaScript errors. The widget never breaks the host
+app: if the tracker is down, it fails quietly and keeps your typed text.
+
+![Capturing from the widget](docs/screenshots/widget-dialog.png)
+
+**2. From a Claude Code session, over MCP.** Register the tracker once as an
+MCP server (below), and any agent session can file an issue mid-task when it
+notices something out of scope. Or you can just say "add that to the backlog."
+
+**3. From the board itself.** Click **+ New issue** to file something directly,
+no widget required.
+
+## The board
+
+Open `http://localhost:4400` and you get a Kanban board across all your
+projects, with a switcher to move between them:
+
+- **Four columns:** Backlog → In Progress → In Review → Done.
+- **Drag to prioritize.** Card order is saved to each issue's file, so agents
+  see the same priority you do.
+- **Real-time search** filters cards as you type.
+- **Click to edit** an issue's type or severity right on the card detail.
+- **Sweep** finished work into a searchable **Archive**, and **delete** stale or
+  test issues outright (with a two-step confirm).
+- **Copy Prompt** turns any issue into a paste-ready Claude Code prompt: the
+  full description, the captured context, the repo path, and the workflow.
+
+## Let agents work the backlog
+
+This is the part that makes it *ops*, not just a list. Register the tracker as
+an MCP server, available in every Claude Code session:
+
+```bash
+claude mcp add vibeops -- npx -y -p vibeops-tracker vibeops-mcp
+```
+
+Now your agents can read and drive the board directly. The intended loop:
+
+1. You stack and prioritize a backlog during the day.
+2. When you step away, you point an agent at it: *"Work the top items in the
+   `my-app` backlog and stop for my review."*
+3. The agent calls `list_issues`, picks the highest-priority one, marks it
+   **In Progress**, does the work, and moves it to **In Review** with a
+   summary of what it changed and which files it touched.
+4. You come back to a board that shows exactly what got done, ready to verify.
+
+Agents set every status except **Done**. That one is yours, so nothing ships
+without your sign-off. The MCP server reads the markdown store directly, so it
+works even when the web UI isn't running.
+
+**Tools:** `get_tracker_instructions`, `list_projects`, `list_issues`,
+`search_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment`,
+`resolve_issue`, `delete_issue`.
+
+## How it stores things
+
+One issue is one markdown file under `data/<project>/issues/`:
+
+```markdown
+---
+id: my-app-7
+project: my-app
+title: Login button does nothing on mobile
+status: backlog
+type: bug
+severity: 4
+tags: [auth, mobile]
+---
+
+## Seeing
+Tapping "Log in" on iOS Safari does nothing.
+
+## Expecting
+It submits the form and signs me in.
+
+## Context
+The captured snapshot (URL, selected text, recent errors), stored as JSON.
+```
+
+Human-readable, AI-readable, greppable, and versionable. The store handles
+concurrent writes from the web server and the MCP server with file locks, so the
+board and your agents never corrupt each other's edits.
+
+## Configuration
+
+Everything has a sensible default; override only what you need.
+
+| Setting    | Default                              | How to set                          |
+| ---------- | ------------------------------------ | ----------------------------------- |
+| Port       | `4400`                               | `--port 5000` or `PORT=5000`        |
+| Data dir   | `./data` (clone) or OS app-data dir  | `--data <dir>` or `DATA_DIR=<dir>`  |
+
+```bash
+vibeops                 # start the board (default command)
+vibeops --port 5000     # on a different port
+vibeops where           # print the data directory
+vibeops mcp             # run the MCP stdio server directly
+vibeops --help
+```
+
+## FAQ
+
+**Is my data private?** Yes, completely. Everything lives on your machine in
+local files. There's no account, no server you don't run, and no telemetry. The
+board binds to `localhost` only, so don't expose its port to an untrusted network
+(see [SECURITY.md](SECURITY.md)).
+
+**Do I have to use AI agents?** No. The widget, the board, and the Copy Prompt
+button are useful on their own. MCP is opt-in.
+
+**Does it lock me into one project?** No. It's built for the opposite. One
+tracker holds all your projects, each with its own board, and the widget installs
+into any of them with a single line.
+
+**What does a project need to integrate?** One `<script>` tag. That's the only
+tracker code that ever lives in your project; everything else stays here.
+
+**Why markdown files instead of a database?** So your backlog is readable,
+greppable, diffable, and yours. No migration, no lock-in, no service to keep
+alive.
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md)
+for setup and the project layout, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+for the ground rules. It's a small, dependency-light codebase (plain ESM, no
+build step), meant to be easy to read and easy to change.
+
+## License
+
+[MIT](LICENSE) © Igor Gembitsky
+
+---
+
+## Why I built this
+
+I build a lot of things at once. Testing them locally, I'd constantly trip over
+small bugs and half-formed ideas at the worst possible moment, mid-flow on
+something else. Fixing each one on the spot wrecked my focus. Spinning up a
+separate session for every one wasn't worth it when I'm the only one driving.
+What I wanted was somewhere to *triage*: drop the bug, the feature, the
+"improve this later," keep building, and come back to a prioritized stack I could
+work through myself or hand to an agent on a coffee break.
+
+I looked at the existing tools and they were all built for teams, for the cloud,
+or for ceremony I didn't want. So I built the small, local, private thing that
+fit how I actually work, and figured other people building solo might want it
+too. That's what this is: my "vibe ops," a lightweight backbone for managing
+the work behind a pile of side projects. Take it, use it, change it, and tell me
+how to make it better.

package/bin/cli.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// VibeOps Tracker CLI — start the board/API server (default) or the MCP stdio server.
+// A thin, dependency-free dispatcher.
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+import { resolveDataDir, ROOT } from '../lib/data-dir.mjs';
+
+const args = process.argv.slice(2);
+
+function opt(names, takesValue) {
+  for (const name of names) {
+    const i = args.indexOf(name);
+    if (i !== -1) return takesValue ? args[i + 1] : true;
+  }
+  return undefined;
+}
+
+const pkg = JSON.parse(readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+
+function help() {
+  console.log(`VibeOps Tracker ${pkg.version} — local-first issue tracker
+
+Usage:
+  vibeops [start]        Start the board + API + capture widget (default)
+  vibeops mcp            Start the MCP stdio server (for AI agent hosts)
+  vibeops where          Print the data directory and exit
+
+Options:
+  -p, --port <n>      Server port (default 4400, or $PORT)
+  -d, --data <dir>    Data directory (default: ./data in a clone, otherwise your
+                      OS app-data dir; or set $DATA_DIR)
+  -h, --help          Show this help
+  -v, --version       Print the version
+
+Everything runs locally. Docs: ${pkg.homepage || 'https://github.com/igembitsky/vibeops-tracker'}`);
+}
+
+if (opt(['-v', '--version'])) {
+  console.log(pkg.version);
+  process.exit(0);
+}
+if (opt(['-h', '--help'])) {
+  help();
+  process.exit(0);
+}
+
+const cmd = args.find((a) => !a.startsWith('-')) || 'start';
+const dataDir = resolveDataDir({ flag: opt(['-d', '--data'], true) });
+
+if (cmd === 'where') {
+  console.log(dataDir);
+} else if (cmd === 'mcp') {
+  process.env.DATA_DIR = dataDir; // mcp-server.mjs resolves DATA_DIR at import time
+  await import('../mcp-server.mjs');
+} else if (cmd === 'start') {
+  const port = Number(opt(['-p', '--port'], true) || process.env.PORT) || 4400;
+  const { startServer } = await import('../server.mjs');
+  try {
+    await startServer({ port, dataDir });
+    console.log('VibeOps Tracker is running.');
+    console.log(`  Board:  http://localhost:${port}`);
+    console.log(`  Data:   ${dataDir}`);
+    console.log('Press Ctrl+C to stop.');
+  } catch (err) {
+    if (err && err.code === 'EADDRINUSE') {
+      console.error(`Port ${port} is already in use. Try: vibeops --port <other-port>`);
+      process.exit(1);
+    }
+    throw err;
+  }
+} else {
+  console.error(`Unknown command: ${cmd}\n`);
+  help();
+  process.exit(1);
+}

package/lib/api.mjs

@@ -0,0 +1,140 @@
+// REST API router. handleApi returns true when the request was an /api route.
+import {
+  listProjects,
+  ensureProject,
+  getProject,
+  createIssue,
+  getIssue,
+  listIssues,
+  updateIssue,
+  addComment,
+  resolveIssue,
+  sweepDone,
+  listClosed,
+  deleteIssue,
+} from './store.mjs';
+import { buildPrompt } from './prompt.mjs';
+
+export function setCors(res) {
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PATCH, DELETE, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+}
+
+// CSRF guard for destructive, board-only mutations. The capture widget POSTs
+// cross-origin (that must stay allowed), but DELETE/PATCH are only ever issued
+// by the same-origin board UI or by header-less callers (curl, MCP). A browser
+// always attaches a truthful Origin on cross-origin unsafe requests, so any
+// request whose Origin doesn't match this server is a drive-by and is refused.
+// Header-less callers (no Origin) pass — they aren't the CSRF threat.
+function isSameOrigin(req) {
+  const origin = req.headers.origin;
+  if (!origin) return true;
+  return origin === `http://${req.headers.host}`;
+}
+
+function sendJson(res, status, body) {
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(body, null, 2));
+}
+
+function sendText(res, status, body) {
+  res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8' });
+  res.end(body);
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    req.on('data', (chunk) => {
+      data += chunk;
+      if (data.length > 5 * 1024 * 1024) {
+        const err = new Error('body too large');
+        err.statusCode = 400;
+        req.destroy(err);
+        reject(err);
+      }
+    });
+    req.on('end', () => resolve(data));
+    req.on('error', reject);
+  });
+}
+
+async function readJsonBody(req) {
+  const raw = await readBody(req);
+  try {
+    return JSON.parse(raw || '{}');
+  } catch {
+    const err = new Error('invalid JSON body');
+    err.statusCode = 400;
+    throw err;
+  }
+}
+
+export async function handleApi(req, res, { dataDir }) {
+  const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+  const pathname = url.pathname;
+  if (!pathname.startsWith('/api/')) return false;
+
+  setCors(res);
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204);
+    res.end();
+    return true;
+  }
+
+  if ((req.method === 'DELETE' || req.method === 'PATCH') && !isSameOrigin(req)) {
+    sendJson(res, 403, { error: 'cross-origin mutation refused' });
+    return true;
+  }
+
+  const route = `${req.method} ${pathname}`;
+  let match;
+  try {
+    if (route === 'GET /api/projects') {
+      sendJson(res, 200, listProjects(dataDir));
+    } else if (route === 'POST /api/projects') {
+      const body = await readJsonBody(req);
+      sendJson(res, 201, ensureProject(dataDir, body.key, body.name, body.repo_path));
+    } else if ((match = /^GET \/api\/projects\/([^/]+)\/issues$/.exec(route))) {
+      const status = url.searchParams.get('status') || undefined;
+      sendJson(res, 200, listIssues(dataDir, decodeURIComponent(match[1]), { status }));
+    } else if ((match = /^GET \/api\/projects\/([^/]+)\/closed$/.exec(route))) {
+      sendJson(res, 200, listClosed(dataDir, decodeURIComponent(match[1])));
+    } else if ((match = /^POST \/api\/projects\/([^/]+)\/sweep$/.exec(route))) {
+      sendJson(res, 200, sweepDone(dataDir, decodeURIComponent(match[1])));
+    } else if (route === 'POST /api/issues') {
+      const body = await readJsonBody(req);
+      sendJson(res, 201, createIssue(dataDir, body));
+    } else if ((match = /^GET \/api\/issues\/([^/]+)\/prompt$/.exec(route))) {
+      const issue = getIssue(dataDir, decodeURIComponent(match[1]));
+      if (!issue) return sendJson(res, 404, { error: `Issue not found: ${match[1]}` }), true;
+      const project = getProject(dataDir, issue.project);
+      sendText(res, 200, buildPrompt(issue, { apiBase: `http://${req.headers.host}`, project }));
+    } else if ((match = /^POST \/api\/issues\/([^/]+)\/resolve$/.exec(route))) {
+      const body = await readJsonBody(req);
+      sendJson(res, 200, resolveIssue(dataDir, decodeURIComponent(match[1]), body));
+    } else if ((match = /^GET \/api\/issues\/([^/]+)$/.exec(route))) {
+      const issue = getIssue(dataDir, decodeURIComponent(match[1]));
+      if (!issue) return sendJson(res, 404, { error: `Issue not found: ${match[1]}` }), true;
+      sendJson(res, 200, issue);
+    } else if ((match = /^PATCH \/api\/issues\/([^/]+)$/.exec(route))) {
+      const body = await readJsonBody(req);
+      sendJson(res, 200, updateIssue(dataDir, decodeURIComponent(match[1]), body));
+    } else if ((match = /^DELETE \/api\/issues\/([^/]+)$/.exec(route))) {
+      sendJson(res, 200, deleteIssue(dataDir, decodeURIComponent(match[1])));
+    } else if ((match = /^POST \/api\/issues\/([^/]+)\/comments$/.exec(route))) {
+      const body = await readJsonBody(req);
+      sendJson(res, 200, addComment(dataDir, decodeURIComponent(match[1]), body));
+    } else {
+      sendJson(res, 404, { error: `No route: ${route}` });
+    }
+  } catch (err) {
+    if (err.code === 'NOT_FOUND') sendJson(res, 404, { error: err.message });
+    else if (err.code === 'CLOSED') sendJson(res, 409, { error: err.message });
+    else if (err.statusCode) sendJson(res, err.statusCode, { error: err.message });
+    else if (err.name === 'Error') sendJson(res, 400, { error: err.message }); // validation throws are plain Errors
+    else sendJson(res, 500, { error: err.message });
+  }
+  return true;
+}

package/lib/data-dir.mjs

@@ -0,0 +1,46 @@
+// Resolve where VibeOps Tracker stores its data — used by the HTTP server, the CLI,
+// and the MCP server alike, so a human (board UI) and an agent (MCP) always read
+// and write the same store.
+//
+// Precedence:
+//   1. an explicit --data flag (passed in by the CLI)       — caller wins
+//   2. the DATA_DIR environment variable                     — host / MCP config
+//   3. running from a git clone  →  <repoRoot>/data          — gitignored, local
+//   4. installed globally or via npx (lives in node_modules) →  OS app-data dir
+//
+// Rationale: a cloned repo keeps its data beside the code (familiar, easy to
+// back up). A globally-installed tool must persist data across upgrades and keep
+// it private to the user, which is exactly what the per-user OS app-data dir
+// gives you — never inside node_modules, where a reinstall would wipe it.
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const APP = 'vibeops-tracker';
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url)); // <root>/lib
+export const ROOT = path.dirname(MODULE_DIR); // package root
+
+export function appDataDir() {
+  if (process.platform === 'win32') {
+    const base = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    return path.join(base, APP);
+  }
+  if (process.platform === 'darwin') {
+    return path.join(os.homedir(), 'Library', 'Application Support', APP);
+  }
+  const base = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share');
+  return path.join(base, APP);
+}
+
+// True when this package lives inside a node_modules tree (global install / npx
+// cache) rather than a developer's clone.
+function isInstalledPackage() {
+  return ROOT.split(path.sep).includes('node_modules');
+}
+
+export function resolveDataDir({ flag } = {}) {
+  if (flag) return path.resolve(flag);
+  if (process.env.DATA_DIR) return path.resolve(process.env.DATA_DIR);
+  if (!isInstalledPackage()) return path.join(ROOT, 'data'); // clone → ./data
+  return appDataDir();
+}

package/lib/prompt.mjs

@@ -0,0 +1,96 @@
+// Build a paste-ready Claude Code prompt for working an issue.
+
+function selectionBlock(context) {
+  if (!context?.selectedText) return '';
+  const quoted = String(context.selectedText)
+    .trimEnd()
+    .split('\n')
+    .map((l) => `> ${l}`)
+    .join('\n');
+  return [
+    '',
+    '## What I highlighted',
+    '',
+    'I had this text selected on the page when I filed this — it is likely the exact thing I am referring to:',
+    '',
+    quoted,
+    '',
+  ].join('\n');
+}
+
+function contextBlock(context) {
+  if (!context) return '';
+  const lines = ['', '## Captured context', ''];
+  if (context.url) lines.push(`- URL when reported: ${context.url}`);
+  if (context.viewport?.w) lines.push(`- Viewport: ${context.viewport.w}x${context.viewport.h}`);
+  if (context.userAgent) lines.push(`- User agent: ${context.userAgent}`);
+  const errors = context.recentErrors || [];
+  if (errors.length) {
+    lines.push('', `Recent JS errors (${errors.length}):`);
+    for (const e of errors) lines.push(`- ${e.message}`);
+  }
+  const failures = context.recentFetchFailures || [];
+  if (failures.length) {
+    lines.push('', `Recent failed requests (${failures.length}):`);
+    for (const f of failures) lines.push(`- ${f.method} ${f.url} -> ${f.status}`);
+  }
+  const git = context.git || context.app?.git;
+  if (git && (git.branch || git.commit || git.worktree)) {
+    lines.push('', 'Environment as of capture (may have changed since — verify against the current state of the repo before relying on it):');
+    if (git.branch) lines.push(`- Branch: ${git.branch}`);
+    if (git.commit) lines.push(`- Commit: ${git.commit}`);
+    if (git.worktree) lines.push(`- Worktree: ${git.worktree}`);
+  }
+  return lines.join('\n');
+}
+
+function repoBlock(project) {
+  if (!project?.repo_path) return '';
+  return `
+## Repository
+
+This issue belongs to the "${project.name || project.key}" project:
+${project.repo_path}
+
+Work in that repository (check its current branch/worktree state first — the capture-time environment above may be stale).
+`;
+}
+
+export function buildPrompt(issue, { apiBase, project } = {}) {
+  const title = issue.title || issue.id;
+  const tags = (issue.tags || []).length ? ` | tags: ${issue.tags.join(', ')}` : '';
+
+  return `Work on this issue from my issue tracker.
+
+# ${issue.id}: ${title}
+
+Type: ${issue.type} | Severity: ${issue.severity}/5${tags} | Project: ${issue.project}
+
+## What I'm seeing
+
+${issue.seeing}
+
+## What I expect
+
+${issue.expecting}
+${selectionBlock(issue.context)}${contextBlock(issue.context)}
+${repoBlock(project)}
+## Issue file
+
+The full issue (including the complete context snapshot JSON and comments) lives at:
+${issue.file}
+
+## Tracker workflow
+
+The tracker API runs at ${apiBase}. As you work:
+
+1. Mark the issue in-progress when you start:
+   curl -X PATCH ${apiBase}/api/issues/${issue.id} -H 'Content-Type: application/json' -d '{"status": "in-progress"}'
+2. Leave comments for anything notable along the way:
+   curl -X POST ${apiBase}/api/issues/${issue.id}/comments -H 'Content-Type: application/json' -d '{"author": "claude", "text": "<note>"}'
+3. When the fix is ready, resolve it (this records your summary + touched files and moves it to in-review for me to verify):
+   curl -X POST ${apiBase}/api/issues/${issue.id}/resolve -H 'Content-Type: application/json' -d '{"resolution": "<what you changed, why, and how it was tested>", "modifiedFiles": ["path/one", "path/two"]}'
+
+If this project's issue-tracker MCP server is connected, prefer its tools (update_issue, add_comment, resolve_issue) over curl. If the tracker server is down, you can edit the issue file's frontmatter directly (status: in-progress | in-review) and append to its ## Comments section (format: "### <author> — <ISO timestamp>").
+`;
+}