@adhd/backlog 0.1.1 → 0.1.3

package/install-skill.d.ts

@@ -1,5 +1,12 @@
 export type SkillHost = 'claude' | 'codex' | 'opencode';
 export type SkillScope = 'user' | 'project';
+export declare const ALL_HOSTS: readonly SkillHost[];
+/** Exported so `install.ts`'s codex MCP-registration path (which needs the
+ *  SAME `~/.codex` (or `$CODEX_HOME`) root as the skill installer, but the
+ *  file `config.toml` rather than a `skills/` subdirectory) never
+ *  re-derives — and risks desyncing from — this resolution rule. */
+export declare function resolveCodexHomeDir(home: string, homeOverride?: string): string;
+export declare function hostSkillsDir(host: SkillHost, scope: SkillScope, cwd: string, homeOverride?: string): string;
 export interface InstallSkillResult {
     host: SkillHost;
     scope: SkillScope;
@@ -20,6 +27,14 @@ export interface InstallSkillResult {
  * always resolves the genuine machine home directory for `--scope user`.
  */
 export declare function installSkill(argv: string[], cwd?: string, homeOverride?: string): InstallSkillResult[];
+/**
+ * The actual filesystem work behind `installSkill` — pulled out so
+ * `install.ts`'s richer `backlog install` parser (which additionally
+ * accepts `--skill-only`/`--mcp-only`) can drive it directly with an
+ * already-parsed `{ hosts, scope }` instead of re-parsing (and risking a
+ * DIFFERENT `--host`/`--scope` grammar from) a raw argv a second time.
+ */
+export declare function installSkillToHosts(hosts: SkillHost[], scope: SkillScope, cwd: string, homeOverride?: string): InstallSkillResult[];
 /** CLI entry — parses argv, runs the install, prints the same
  *  `console.log(JSON.stringify(...))` shape every other CLI command uses
  *  (BUG-APIGEN-015 parity), so scripting `backlog install-skill` composes

package/install.d.ts

@@ -0,0 +1,59 @@
+import { InstallSkillResult, SkillHost, SkillScope } from './install-skill.js';
+
+export type McpHost = SkillHost;
+export type McpScope = SkillScope;
+/** The one, portable invocation every host's registration entry points at —
+ *  `npx -y @adhd/backlog@latest serve --transport mcp` — so a written config
+ *  works on any machine with `npx` and network access, never tied to this
+ *  monorepo's own local `dist/index.js` path (that local-path form is what
+ *  THIS repo's own checked-in `.mcp.json` uses for its own dev loop, which is
+ *  deliberately NOT what a published `install` command should write for a
+ *  third-party consumer). */
+export declare const BACKLOG_MCP_NPX_ARGS: readonly string[];
+export type McpInstallStatus = 'written' | 'manual';
+export interface McpInstallResult {
+    host: McpHost;
+    scope: McpScope;
+    configPath: string;
+    status: McpInstallStatus;
+    note?: string;
+}
+/**
+ * Replaces (or appends) exactly one `[tableHeader]` table in a TOML
+ * document's text, leaving every other line — including every OTHER
+ * table — byte-for-byte untouched. Scoped deliberately narrow (see this
+ * file's header doc): it finds the line matching `[tableHeader]` exactly,
+ * then treats everything up to (but not including) the next line that
+ * starts a new table (`[...`) — or end of file — as "this table's body",
+ * and swaps that whole span for `newBodyLines`. If the table doesn't exist
+ * yet, the new table is appended at the end (separated by a single blank
+ * line from any existing content).
+ *
+ * This is intentionally NOT a general TOML parser/editor — it only
+ * recognizes bracketed table headers on their own line, which is exactly
+ * (and only) the shape this file ever writes or looks for.
+ */
+export declare function upsertTomlTable(text: string, tableHeader: string, newBodyLines: readonly string[]): string;
+export declare const INSTALL_HELP_TEXT = "backlog install [--host claude|opencode|codex|all] [--scope user|project] [--skill-only | --mcp-only]\n\nInstalls the backlog skill AND registers the backlog MCP server into an agent\nhost's config, in one step.\n\n  --host <name>   claude | opencode | codex | all (default: all)\n  --scope <name>  user | project (default: user)\n  --skill-only    only install the skill \u2014 never touch any MCP config\n  --mcp-only      only register the MCP server \u2014 never touch any skill dir\n\nExamples:\n  backlog install\n  backlog install --host claude --scope project\n  backlog install --mcp-only --host opencode\n\nBack-compat: `backlog install-skill` remains available and behaves exactly\nlike `backlog install --skill-only` (original --host/--scope grammar only).\n";
+export interface InstallResult {
+    skill: InstallSkillResult[];
+    mcp: McpInstallResult[];
+}
+/**
+ * Installs the backlog skill and/or registers the `backlog` MCP server into
+ * the requested host config(s), per `--host`/`--scope`/`--skill-only`/
+ * `--mcp-only`. Both halves are idempotent and non-destructive: re-running
+ * overwrites only the `backlog` skill files / the `backlog` MCP entry,
+ * never touching anything else already present.
+ *
+ * `homeOverride` is a TEST-ISOLATION ESCAPE HATCH ONLY, mirroring
+ * `installSkill`'s own parameter — never passed by `runInstallCommand`/the
+ * real CLI.
+ */
+export declare function install(argv: string[], cwd?: string, homeOverride?: string): InstallResult;
+/** CLI entry for `backlog install` — same `console.log(JSON.stringify(...))`
+ *  output convention as `install-skill`, plus a short human-readable summary
+ *  of what was written where (this command's own explicit DoD requirement),
+ *  printed to stderr so it never disturbs the machine-readable stdout JSON
+ *  a script might parse. */
+export declare function runInstallCommand(argv: string[]): Promise<void>;

package/model.d.ts

@@ -90,6 +90,41 @@ export declare class DependencyCycleError extends Error {
     readonly cycle: string[];
     constructor(cycle: string[]);
 }
+/**
+ * BUG-BACKLOG-HUMANID-COLLISION-001 (fix #1 — write-time guard):
+ * `createItemNode` rejects a `family` that is missing/empty/whitespace-only
+ * UNLESS `idOverride` is also given (SPEC.md §5.1's `CreateItemInput.family`
+ * contract: "required unless idOverride given"). Thrown BEFORE
+ * `allocateHumanIdAndInsert`/`computeNextHumanId` ever run, so a caller that
+ * omits `family` (previously silently coerced to the literal string
+ * `"undefined"` by `computeNextHumanId`'s template literal, producing
+ * `humanId: "undefined-001"` and colliding with every other item that hit
+ * the same bug) now fails loudly instead of minting a collision. This is
+ * defense in depth: it must hold regardless of whether an upstream caller's
+ * own input-schema validation (e.g. apigen-core-client's extracted
+ * `CreateItemInput` schema, BUG-APIGEN-CORE-CLIENT-001) enforces `family` as
+ * required — the store's own write path must never trust the caller alone.
+ */
+export declare class InvalidArgumentError extends Error {
+    readonly argument: string;
+    constructor(argument: string, message: string);
+}
+/**
+ * BUG-BACKLOG-HUMANID-COLLISION-001 (fix #2 — read-time guard): every
+ * `(repo, humanId)`-keyed lookup used to silently resolve to "whichever
+ * live node is found first" when more than one live node shared the same
+ * key (the exact shape of the pre-existing `"undefined-001"` collisions,
+ * and the root cause of a real mis-transition this session — see the
+ * backlog item's body). Any lookup that finds >1 live match now throws this
+ * instead of guessing, listing every colliding `nodeId` so a caller can
+ * disambiguate (there is no tool-level nodeId-addressed path yet — the
+ * caller must go through the store's own repair primitives, e.g.
+ * `renameHumanId`, to resolve the collision).
+ */
+export declare class AmbiguousHumanIdError extends Error {
+    readonly nodeIds: number[];
+    constructor(repo: string, humanId: string, nodeIds: number[]);
+}
 export interface DedupeScanInput {
     symbol?: string;
     path?: string;

package/package.json

@@ -1,25 +1,28 @@
 {
   "name": "@adhd/backlog",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "bin": {
     "backlog": "index.js"
   },
   "dependencies": {
     "@adhd/sox-graph-store": "^0.3.0",
     "better-sqlite3": "^12.10.0",
-    "@adhd/environment": "^0.1.1",
+    "@adhd/environment": "^0.1.3",
     "@adhd/environment-base-spec": "^0.1.0",
-    "@adhd/apigen-core-client": "^0.2.1",
-    "@adhd/apigen-plugin-api-fastify": "^0.2.1",
+    "@adhd/apigen-core-client": "^0.2.2",
+    "@adhd/apigen-plugin-api-fastify": "^0.2.2",
     "@adhd/apigen-plugin-openapi": "^0.2.1",
-    "@adhd/apigen-plugin-mcp": "^0.2.1",
-    "@adhd/apigen-plugin-batch": "^0.2.0",
-    "@adhd/apigen-plugin-cli-output": "^0.2.1",
+    "@adhd/apigen-plugin-mcp": "^0.2.2",
+    "@adhd/apigen-plugin-batch": "^0.2.1",
+    "@adhd/apigen-plugin-cli-output": "^0.2.2",
     "@adhd/apigen-engine-naming": "^0.2.1",
     "yaml": "1.10.3",
     "pino": "10.3.1",
     "pino-pretty": "13.1.3"
   },
+  "assets": [
+    "skill"
+  ],
   "main": "./index.js",
   "module": "./index.mjs",
   "typings": "./index.d.ts",

package/skill/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: backlog-usage
+description: "Use whenever filing, claiming, transitioning, or resolving a backlog item (bug/debt/feature/investigation) in ANY repo on this machine — via the `backlog` CLI/MCP, never by hand-editing a BACKLOG.md file. Also use to check current migration status before assuming markdown vs. the tool is authoritative. Examples: \"log this bug\", \"file a debt item for the flaky test\", \"claim BUG-042\", \"what's still open in this repo\", \"is BACKLOG.md still the source of truth here\"."
+---
+
+# `@adhd/backlog` usage
+
+`@adhd/backlog` is a graph-backed, multi-agent, cross-repo backlog tool. It is
+migrating every repo on this machine off hand-edited `BACKLOG.md` files onto
+itself as the source of truth, with `BACKLOG.md` demoted to a generated,
+git-visible *projection* of the graph. This skill is the ONLY place the
+command surface, protocol, and migration-state mechanism are documented —
+the global `CLAUDE.md`/`AGENTS.md` carry just one pointer line to this file.
+
+## 1. Check migration status FIRST, every time
+
+Never trust a hardcoded phase number in this document — it goes stale the
+moment a phase advances. Before deciding whether `BACKLOG.md` or the tool is
+authoritative for the CURRENT repo, run:
+
+```
+backlog migration-status
+```
+
+It reports `{ phase, description, toolIsAuthoritative }`. While
+`toolIsAuthoritative` is `false` (phases `not-started`/`phase-1`/`phase-2`),
+`BACKLOG.md` (root, per-plan, per-package) is still the real source of truth
+in this repo — read/file there by hand as usual, but still prefer `backlog
+list-items`/`backlog create-item` for querying and filing so items are
+visible cross-repo and get FTS/symbol dedup for free. Once `toolIsAuthoritative`
+is `true` (`phase-3` and later), **never hand-edit a `BACKLOG.md` file** —
+every one is a generated projection at that point, and a hand-edit will be
+silently overwritten (or, once the parity gate is blocking, rejected in CI).
+
+## 2. Command surface — 36 ops, one CLI convention
+
+Every op takes `ctx` as an implicit first argument (never pass it — the CLI/
+MCP host supplies it). The CLI's own parameter-naming convention (verified
+against real spawned-binary tests, `cli.spec.ts`):
+
+- **Scalar parameters** get individual kebab-case flags, named after the
+  parameter itself: `getItem(ctx, repo, humanId)` → `backlog get-item --repo
+  <repo> --human-id <id>`.
+- **Object-shaped parameters** get a single JSON-blob flag, named after the
+  parameter's own name, kebab-cased: `createItem(ctx, input)` → `backlog
+  create-item --input '<json>'`.
+- The bin name is never part of `argv` — a bare `create-item …`/`get-item …`
+  resolves without any manual namespace prefix.
+- Failures use real process exit codes (never `0` on error — unknown command
+  → exit `4`, bad flag → exit `2`); errors are JSON on the last stderr line.
+- Every op is also available as an MCP tool, named `backlog_client_d_<snake_case_op>`
+  (e.g. `backlog_client_d_create_item`), once `.mcp.json` wires the server —
+  same parameters, same semantics.
+
+| `client.ts` export | CLI form |
+|---|---|
+| `createItem(ctx, input)` | `backlog create-item --input '<CreateItemInput json>'` |
+| `getItem(ctx, repo, humanId)` | `backlog get-item --repo <repo> --human-id <id>` |
+| `updateItem(ctx, repo, humanId, patch)` | `backlog update-item --repo <repo> --human-id <id> --patch '<UpdateItemInput json>'` |
+| `listItems(ctx, filter?)` | `backlog list-items --filter '<BacklogFilter json>'` |
+| `softDeleteItem(ctx, repo, humanId, reason)` | `backlog soft-delete-item --repo <repo> --human-id <id> --reason <text>` |
+| `stats(ctx, scope?)` | `backlog stats --scope '<StatsScope json>'` |
+| `spotlight(ctx, scope?, limit?)` | `backlog spotlight --scope '<json>' --limit <n>` |
+| `readyItems(ctx, scope?)` | `backlog ready-items --scope '<json>'` |
+| `blockers(ctx, repo, humanId)` | `backlog blockers --repo <repo> --human-id <id>` |
+| `dependencyGraph(ctx, scope?)` | `backlog dependency-graph --scope '<json>'` |
+| `topoOrder(ctx, scope?)` | `backlog topo-order --scope '<json>'` |
+| `staleClaims(ctx, maxAgeMin, scope?)` | `backlog stale-claims --max-age-min <n> --scope '<json>'` |
+| `claimItem(ctx, repo, humanId, by, opts?)` | `backlog claim-item --repo <repo> --human-id <id> --by <identity> --opts '<ClaimOpts json>'` |
+| `renewClaim(ctx, repo, humanId, by)` | `backlog renew-claim --repo <repo> --human-id <id> --by <identity>` |
+| `releaseClaim(ctx, repo, humanId, by, opts?)` | `backlog release-claim --repo <repo> --human-id <id> --by <identity> --opts '<json>'` |
+| `assignItem(ctx, repo, humanId, to, by)` | `backlog assign-item --repo <repo> --human-id <id> --to <identity> --by <identity>` |
+| `startWork(ctx, repo, humanId, by)` | `backlog start-work --repo <repo> --human-id <id> --by <identity>` |
+| `transitionStatus(ctx, repo, humanId, status, opts)` | `backlog transition-status --repo <repo> --human-id <id> --status <STATUS> --opts '<TransitionOpts json>'` |
+| `addCitation(ctx, repo, humanId, citation)` | `backlog add-citation --repo <repo> --human-id <id> --citation '<Citation json>'` |
+| `appendNote(ctx, repo, humanId, by, text)` | `backlog append-note --repo <repo> --human-id <id> --by <identity> --text <note>` |
+| `resolveItem(ctx, repo, humanId, status, opts)` | `backlog resolve-item --repo <repo> --human-id <id> --status <STATUS> --opts '<json>'` |
+| `archiveResolved(ctx, scope, opts?)` | `backlog archive-resolved --scope '<StatsScope json>' --opts '<ArchiveOpts json>'` |
+| `addDependency(ctx, repo, humanId, dependsOnHumanId)` | `backlog add-dependency --repo <repo> --human-id <id> --depends-on-human-id <id2>` |
+| `removeDependency(ctx, repo, humanId, dependsOnHumanId)` | `backlog remove-dependency --repo <repo> --human-id <id> --depends-on-human-id <id2>` |
+| `linkRelated(ctx, repo, humanIdA, humanIdB)` | `backlog link-related --repo <repo> --human-id-a <id1> --human-id-b <id2>` |
+| `supersedeItem(ctx, repo, oldHumanId, newInput, reason)` | `backlog supersede-item --repo <repo> --old-human-id <id> --new-input '<CreateItemInput json>' --reason <text>` |
+| `splitItem(ctx, repo, parentHumanId, children)` | `backlog split-item --repo <repo> --parent-human-id <id> --children '<CreateItemInput[] json>'` |
+| `mergeItems(ctx, repo, keepHumanId, dropHumanId, reason)` | `backlog merge-items --repo <repo> --keep-human-id <id1> --drop-human-id <id2> --reason <text>` |
+| `setPriority(ctx, repo, humanId, priority)` | `backlog set-priority --repo <repo> --human-id <id> --priority <PRIORITY>` |
+| `attachToPlan(ctx, repo, humanId, planSlug)` | `backlog attach-to-plan --repo <repo> --human-id <id> --plan-slug <slug>` |
+| `importFromMarkdown(ctx, input)` | `backlog import-from-markdown --input '<ImportMarkdownInput json>'` |
+| `renderToMarkdown(ctx, filter?)` | `backlog render-to-markdown --filter '<BacklogFilter json>'` |
+| `exportJson(ctx, filter?)` | `backlog export-json --filter '<json>'` |
+| `auditTrail(ctx, repo, humanId)` | `backlog audit-trail --repo <repo> --human-id <id>` |
+| `migrationStatus(ctx)` | `backlog migration-status` |
+| `setMigrationPhase(ctx, phase)` | `backlog set-migration-phase --phase <PHASE>` (admin-only — only whoever just verified a phase's DoD should call this) |
+
+Every `<repo>` value is this machine's stable git-remote-derived slug (e.g.
+`PseudoSky/adhd`) — never a bare directory name. A worktree agent
+(`<repo>/.worktrees/*`) resolves to the SAME main-repo `repo` slug, not a
+phantom per-worktree repo.
+
+## 3. Claim/renew/release protocol (multi-agent use)
+
+- Identity is always `${agentName}:${instanceId}` — NEVER a bare role literal
+  like `"agent"`. Two concurrent agents both claiming as `"implementer"`
+  defeats the CAS protocol entirely.
+- `claimItem` is idempotent for the SAME claimant — always `renewed`, no
+  contention check.
+- A long-running task must call `renewClaim` periodically (default
+  staleness: 30 minutes).
+- Every exit path (done/error/abandoned) calls `releaseClaim`
+  unconditionally — it is a no-op on an already-unclaimed item, never an
+  error. Never leave an item claimed after you stop working on it.
+
+## 4. Citations — via tool calls, never hand-typed markdown
+
+The `Citation` type (`{ file, lines?, context? }`) is the structured form of
+one bracketed citation entry in the old hand-edited convention. Instead of
+typing a `Citations: [...]` line by hand:
+
+- Call `transitionStatus`/`resolveItem` with `{ citations: [...] }` when
+  moving into any terminal-done/terminal-workaround status — this is
+  REQUIRED and enforced (a status transition without citations there is
+  rejected).
+- Call `addCitation` to attach evidence without a status change.
+
+## 5. Dedupe before filing — via the tool, not eyeballing
+
+`createItem` runs a dedupe scan (FTS over title+body, plus exact
+symbol/path/errorText metadata match) BEFORE writing, and returns
+`duplicateCandidates` alongside `created: false` when a likely match exists.
+**Always inspect `duplicateCandidates` first.** Only pass `force: true` after
+confirming the candidates are genuinely a distinct issue — never as a way to
+skip reading them.
+
+## 6. Filing a new item — worked example
+
+```
+backlog create-item --input '{
+  "family": "BUG-MYAREA",
+  "title": "Short, specific summary",
+  "body": "Full description, root cause if known, evidence.",
+  "repo": "PseudoSky/adhd",
+  "projectPath": "packages/domain/my-package",
+  "priority": "HIGH"
+}'
+```
+
+If the response has `created: false` with non-empty `duplicateCandidates`,
+read them before deciding whether to `force: true` or update the existing
+item instead (`updateItem`/`appendNote`).

package/store/query.d.ts

@@ -6,6 +6,20 @@ import { NodeRecord } from '@adhd/sox-graph-store';
 /** Raw NodeRecord query — used internally where the full node (not just the mapped BacklogItem) is needed. */
 export declare function queryItemNodes(store: GraphBacklogStore, filter?: BacklogFilter): NodeRecord[];
 export declare function listItems(store: GraphBacklogStore, filter?: BacklogFilter): BacklogItem[];
+/**
+ * BUG-BACKLOG-HUMANID-COLLISION-001 fix #2: this is THE shared `(repo,
+ * humanId) -> NodeRecord` lookup every store module funnels through
+ * (`crud.ts`/`lifecycle.ts`/`structure.ts`/`client.ts`'s `requireItem*`
+ * helpers all call this, directly or via `buildNotFoundError`'s sibling
+ * miss path). It used to silently resolve to "whichever live node happens
+ * to match `name`, else whichever is first" when more than one live node
+ * shared the same `(repo, humanId)` key — the exact shape of the
+ * pre-existing `"undefined-001"` collisions, and the root cause of a real
+ * mis-transition (see the backlog item body: a `resolveItem` call intended
+ * for one node silently landed on a different, unrelated one). Any lookup
+ * that finds >1 live match now throws `AmbiguousHumanIdError` instead of
+ * guessing.
+ */
 export declare function findItemNode(store: GraphBacklogStore, repo: string, humanId: string): NodeRecord | null;
 /**
  * Finds every LIVE node carrying this `humanId`, across ALL repos (no

package/store/structure.d.ts

@@ -33,3 +33,32 @@ export declare function mergeItemsNode(store: GraphBacklogStore, repo: string, k
 export declare function setPriorityNode(store: GraphBacklogStore, repo: string, humanId: string, priority: Priority): BacklogItem;
 export declare function attachToPlanNode(store: GraphBacklogStore, repo: string, humanId: string, planSlug: string): void;
 export declare function assignItemNode(store: GraphBacklogStore, repo: string, humanId: string, to: string, by: string): BacklogItem;
+/**
+ * BUG-BACKLOG-HUMANID-COLLISION-001 fix #3 (repair primitive): re-ids a
+ * single, `nodeId`-scoped live backlog item to a new `humanId` within the
+ * same `repo`. `nodeId`-scoped (not `(repo, oldHumanId)`-keyed) so this is
+ * unambiguous EVEN under the exact collision it exists to repair — every
+ * other `(repo, humanId)`-keyed lookup in this file would throw
+ * `AmbiguousHumanIdError` on a colliding key (fix #2, `findItemNode`), so a
+ * repair tool needs a way in that doesn't go through that same lookup.
+ *
+ * There is no tool-level rename/re-id operation exposed anywhere in this
+ * store today (the backlog item's fix direction #5 explicitly calls this
+ * gap out) — this is that primitive, added as part of this fix, kept
+ * store-internal (not wired to `client.ts`/the MCP surface) since it is a
+ * narrow one-off repair tool, not a general-purpose end-user operation.
+ *
+ * Guards:
+ *  - the node at `nodeId` must be live and its CURRENT `metadata.humanId`
+ *    must equal `oldHumanId` (sanity check — refuses to rename the wrong
+ *    node out from under a caller who mis-copied a nodeId).
+ *  - `newHumanId` must not already resolve to a DIFFERENT live node in this
+ *    `repo` (refuses to rename INTO a fresh collision).
+ *  - re-derives `kind`/`family` from `newHumanId`, rebuilds `tags` (swapping
+ *    the old kind/family tags for the new ones, preserving every other
+ *    user tag) and the node `name`/`content`/`content_hash` (which both bake
+ *    in `repo::humanId` — DESIGN.md §2.2, mapping.ts's `buildNodeName`/
+ *    `buildNodeContent`) so the renamed node is indistinguishable from one
+ *    that was always minted under `newHumanId`.
+ */
+export declare function renameHumanIdNode(store: GraphBacklogStore, repo: string, nodeId: number, oldHumanId: string, newHumanId: string): BacklogItem;