@adhd/backlog 0.0.1 → 0.1.0

package/CHANGELOG.md

@@ -1 +1,54 @@
+## 0.0.3 (2026-07-25)
+
+
+### 🩹 Fixes
+
+- **apigen,backlog:** killable serve, configurable namespace, flaky test + log spam
+
+- **backlog:** match archived-item exclusion between render and its verify
+
+
+### ❤️  Thank You
+
+- pseudosky
+
+## 0.0.2 (2026-07-24)
+
+
+### 🚀 Features
+
+- **backlog:** add CLI entrypoint + bin (live apigen cli-output mount)
+
+- **backlog:** add migration.phase signal + migrationStatus op (MIGRATION.md §4.4)
+
+- **backlog:** Phase 1/2 apigen import + CI parity gate + durable migration.phase admin write
+
+- **backlog:** author backlog-usage skill + install-skill CLI (MIGRATION.md sec 4.2/4.3)
+
+- **backlog:** add `serve` CLI command so .mcp.json has a real entry to spawn (MIGRATION.md sec 4.5)
+
+- **backlog:** rootLevel projection filter so new tool items reach root
+
+
+### 🩹 Fixes
+
+- **backlog:** close Phase-3 migration gate — CI Node floor, content-hash collision verified, FTS content immutability, bounded busy-retry; plus import provenance/silent-drop fixes
+
+- **backlog:** runBacklogCli no longer eagerly opens the store for --help/no-args (DEBT-BACKLOG-CLI-EAGER-STORE-OPEN-001)
+
+- **backlog:** concurrent createItem id-collision + FTS sanitizer gap (MIGRATION.md sec 3.3 scale test)
+
+- **backlog:** implement real transition/claim audit-log (DEBT-BACKLOG-AUDIT-TRAIL-PARTIAL-001)
+
+- **backlog:** importFromMarkdown upserts on re-import instead of insert-only
+
+- **backlog:** sourcepath-ownership gate for importFromMarkdown (DEBT-BACKLOG-IMPORT-SCOPE-CROSSFILE-001)
+
+- **backlog:** re-import backfills ownership + resurrects superseded ids
+
+
+### ❤️  Thank You
+
+- pseudosky
+
 ## Unreleased

package/README.md

@@ -54,10 +54,46 @@ const abort = new AbortController();
 await startBacklogServer({ transport: 'both', port: 3400, signal: abort.signal });
 ```
 
-- `POST /backlog/createItem`, `GET /backlog/getItem`, ... — every `client.ts`
-  export, mounted live via `@adhd/apigen-plugin-api-fastify`.
-- Every export is also available as an MCP tool via `@adhd/apigen-plugin-mcp`
-  (stdio transport by default).
+- `POST /backlog/client-d/create-item`, `GET /backlog/client-d/get-item`, ... —
+  every `client.ts` export, mounted live via `@adhd/apigen-plugin-api-fastify`.
+  (The `client-d` route segment is not a typo — see `DESIGN.md` §7's CLI
+  section / `SPEC.md` §7's transport table for why it's there.)
+- Every export is also available as an MCP tool (e.g. `backlog_client_d_get_item`)
+  via `@adhd/apigen-plugin-mcp` (stdio transport by default).
+
+## CLI (`backlog`, live apigen mount — no codegen)
+
+```bash
+pnpm add -g @adhd/backlog   # installs the `backlog` bin
+backlog --help              # live-derived command listing
+backlog create-item --input '{"family":"BUG-EXAMPLE","title":"t","body":"b","repo":"org/repo"}'
+backlog get-item --repo org/repo --human-id BUG-EXAMPLE-001
+backlog list-items --filter '{"status":"OPEN"}'
+```
+
+- Same architecture as the HTTP/MCP transports above — `entrypoint/backlog/src/cli.ts`'s
+  `runBacklogCli()` reuses `buildBacklogApigenPackage()` and hands it straight
+  to `@adhd/apigen-plugin-cli-output`'s `run()`. No `apigen generate`, no
+  bespoke argument parsing — routing, flag parsing, validation, dispatch, and
+  exit codes all come from that plugin.
+- **You type `backlog <command>`, never the internal `client-d` segment.**
+  `runBacklogCli` derives the real command-table prefix from the live
+  `operations` list at runtime (`resolveCommandPrefix`) and prepends it before
+  dispatch — so `backlog get-item …` resolves even though the plugin's real
+  command table is keyed `backlog client-d get-item` internally (same
+  `client-d` artifact as the HTTP/MCP routes above; the CLI is the one
+  transport that hides it from the caller).
+- Flags are the schema's domain params, kebab-cased (`humanId` → `--human-id`);
+  object/array-typed params take a JSON string (`--input '{...}'`,
+  `--filter '{...}'`).
+- Exit codes follow `@adhd/apigen-base-errors`'s `CLI_EXIT_CODE` table: `0`
+  success, `2` invalid argument (bad/unknown flag, failed validation), `4`
+  unknown command, etc. Result is printed as JSON to stdout; errors as JSON to
+  stderr.
+- Honors the same `ADHD_BACKLOG_SCOPE`/`ADHD_ENV_SCOPE` scope env vars as the
+  library API (see Scope below) — there is no separate CLI-only config.
+- `runBacklogCli(argv?, opts?)` is also exported for in-process programmatic
+  use (e.g. a test harness), symmetric with `startBacklogServer`.
 
 ## Scope
 

package/cli.d.ts

@@ -0,0 +1,71 @@
+import { Operation } from '@adhd/apigen-core-client';
+import { Scope } from '@adhd/environment-base-spec';
+
+/**
+ * Derives the internal command-path PREFIX every `client.ts` operation
+ * shares in `@adhd/apigen-plugin-cli-output`'s command table
+ * (`buildCommandTable()`: `cliPath = project(op).cli.path`, and
+ * `project()`'s `cli.path = [namespace, ...path].map(toKebab)` —
+ * `@adhd/apigen-engine-naming`'s `naming.ts`).
+ *
+ * Currently simply `['backlog']`: `server.ts`'s `extractClientOperations()`
+ * calls `extract({ …, dropFileSegment: true })`, so every `client.ts`
+ * export's `path` is just `[exportSegment]` (no `client.d.ts`-derived
+ * `'client-d'` segment — see that call site's doc comment for why it's safe
+ * to drop here: one source file, no cross-file names to disambiguate), and
+ * `project(op).cli.path` is `['backlog', '<kebab-export-name>']`.
+ *
+ * This is still derived from the live `operations` list rather than
+ * hardcoded, on purpose: since every `client.ts` export shares the same
+ * namespace + same source, every operation's `cli.path` differs ONLY in its
+ * final (export) segment, so the shared prefix is simply "everything but the
+ * last segment" of any one operation's projected `cli.path`. Computed fresh
+ * on every call (never cached as a literal) so a future change to the
+ * extraction call site (e.g. re-enabling the file segment, or adding a
+ * second source file) can never silently desync this from the real command
+ * table the way a hardcoded `['backlog']` constant would.
+ */
+export declare function resolveCommandPrefix(operations: readonly Operation[]): string[];
+/**
+ * Prepends `prefix` (the real, namespace-qualified command path segments
+ * every `client.ts` export shares — see {@link resolveCommandPrefix}) to a
+ * user-typed argv, so `backlog get-item --repo … --human-id …` (what a
+ * consumer actually types — the bin's own name is never part of `argv`)
+ * resolves against the cli-output plugin's command table, which is keyed by
+ * the FULL internal path (`['backlog', 'get-item']`).
+ *
+ * Idempotent / defensive:
+ *  - Empty argv is returned unchanged — `run()` treats `argv.length === 0`
+ *    as the usage listing regardless of any prefix.
+ *  - Argv already starting with the full `prefix` (in order) is returned
+ *    unchanged — never double-prefixed.
+ *  - A leading flag (`--help`, `-h`, or any other top-level `-`-prefixed
+ *    token) is returned unchanged — `run()` special-cases `--help`/`-h`
+ *    BEFORE ever consulting the command table
+ *    (`if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h')`),
+ *    so prefixing here would shadow that check and break `backlog --help`.
+ */
+export declare function prefixCommand(userArgv: readonly string[], prefix: readonly string[]): string[];
+export interface RunBacklogCliOpts {
+    scope?: Scope;
+    /** Test-only override — see `buildBacklogEnv`'s `BuildBacklogEnvOptions`. */
+    adhdRoot?: string;
+    cwd?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Opens (or reuses) the backlog store + env, then dispatches EXACTLY ONE CLI
+ * command live through `@adhd/apigen-plugin-cli-output`'s `run()` — no code
+ * generation, no bespoke argument parsing. Mirrors `startBacklogServer`'s
+ * env→store→ctx→`buildBacklogApigenPackage` setup precisely; the only
+ * divergence is transport-specific: `cliPlugin.run()` is one-shot (it
+ * resolves after dispatching a single command rather than listening), so
+ * there is no `Promise.all` of long-lived transports to await here.
+ *
+ * @param argv Command + flags, WITHOUT the `backlog` bin name (e.g.
+ *   `['get-item', '--repo', 'org/repo', '--human-id', 'BUG-1']`). Defaults
+ *   to `process.argv.slice(2)` — the real CLI invocation's own argv — when
+ *   omitted, matching `cliPlugin.run()`'s own `resolveArgv()` fallback
+ *   convention.
+ */
+export declare function runBacklogCli(argv?: string[], opts?: RunBacklogCliOpts): Promise<void>;

package/client.d.ts

@@ -1,12 +1,24 @@
 import { GraphBacklogStore } from './store/graph-backlog-store.js';
 import { BacklogConfig } from './env.js';
-import { ArchiveOpts, ArchiveResult, AuditTrailResult, BacklogFilter, BacklogItem, BacklogStats, BacklogStatus, ClaimOpts, ClaimResult, Citation, CreateItemInput, CreateItemResult, DependencyGraph, ImportMarkdownInput, ImportResult, Priority, ReleaseResult, StatsScope, TopoOrderResult, TransitionOpts, UpdateItemInput } from './model.js';
+import { ArchiveOpts, ArchiveResult, AuditTrailResult, BacklogFilter, BacklogItem, BacklogStats, BacklogStatus, ClaimOpts, ClaimResult, Citation, CreateItemInput, CreateItemResult, DependencyGraph, ImportMarkdownInput, ImportResult, MigrationPhase, MigrationStatusResult, Priority, ReleaseResult, SetMigrationPhaseResult, StatsScope, TopoOrderResult, TransitionOpts, UpdateItemInput } from './model.js';
 import { Environment } from '@adhd/environment';
 
 /** The one type apigen special-cases via the `ctx-name-only` invariant. */
 export interface BacklogCtx {
     store: GraphBacklogStore;
     env: Environment<BacklogConfig>;
+    /**
+     * Test-isolation escape hatch ONLY — mirrors `BuildBacklogEnvOptions.adhdRoot`
+     * (the same value passed to `buildBacklogEnv({ adhdRoot })` when constructing
+     * `env`). NEVER set this in production code (`server.ts`/`cli.ts` never do).
+     * `setMigrationPhase` threads it through to `writeMigrationPhase` so a
+     * temp-rooted test `ctx` can never write to the real machine-global
+     * `~/.adhd` — omitting this on a real ctx write is exactly the bug
+     * `migration-admin.spec.ts`'s negative control caught (a test run wrote
+     * `phase-4` to the real `~/.adhd/backlog/production/config.yaml` before
+     * this field existed; reverted, see CHANGELOG).
+     */
+    adhdRoot?: string;
 }
 /**
  * Dedupe-scans (FTS + symbol/path/errorText metadata match) before writing.
@@ -65,8 +77,36 @@ export declare function setPriority(ctx: BacklogCtx, repo: string, humanId: stri
 /** MEMBER_OF edge to a plan node (auto-created if the plan slug hasn't been seen before). */
 export declare function attachToPlan(ctx: BacklogCtx, repo: string, humanId: string, planSlug: string): Promise<void>;
 export declare function importFromMarkdown(ctx: BacklogCtx, input: ImportMarkdownInput): Promise<ImportResult>;
-/** Excludes archived items (SPEC.md §5.4 archiveResolved) — see markdown.ts's renderItemsToMarkdown doc comment. */
+/**
+ * Excludes archived items (SPEC.md §5.4 archiveResolved) — see markdown.ts's
+ * renderItemsToMarkdown doc comment. Archival exclusion goes through
+ * `BacklogFilter.excludeArchived` (query.ts's `applyExcludeArchivedFilter`)
+ * rather than a private scan here, so a caller comparing this output
+ * against `listItems`/`queryItemNodes` for the SAME filter (e.g.
+ * `render-projections.mjs`'s round-trip verify) can reproduce this exact
+ * item set by passing `{ ...filter, excludeArchived: true }` themselves —
+ * see BUG-BACKLOG-RENDER-VERIFY-ARCHIVED-MISMATCH-001.
+ */
 export declare function renderToMarkdown(ctx: BacklogCtx, filter?: BacklogFilter): Promise<string>;
 export declare function exportJson(ctx: BacklogCtx, filter?: BacklogFilter): Promise<BacklogItem[]>;
 /** Bi-temporal history + supersession chain. */
 export declare function auditTrail(ctx: BacklogCtx, repo: string, humanId: string): Promise<AuditTrailResult>;
+/**
+ * MIGRATION.md §4.4 — a QUERIED signal, never hardcoded prose: reports the
+ * live `migration.phase` config value (`env.ts`, env-overridable via
+ * `ADHD_BACKLOG_MIGRATION_PHASE`) plus a human-readable meaning, so an agent
+ * (or the `backlog-usage` skill) always asks the tool which of BACKLOG.md or
+ * the tool is authoritative right now, instead of trusting a stale doc
+ * sentence. NOT yet per-repo-keyed (MIGRATION.md §9 open decision 6) — one
+ * global value for the whole machine.
+ */
+export declare function migrationStatus(ctx: BacklogCtx): Promise<MigrationStatusResult>;
+/**
+ * MIGRATION.md §4.4's "admin CLI call" half: writes `migration.phase`
+ * THROUGH to the GLOBAL layer's `config.yaml` (`migration-admin.ts`) so the
+ * new value is a durable, cross-process, cross-repo signal — not merely an
+ * env var scoped to whoever's shell happened to export it. Whoever executes
+ * a phase's Definition of Done calls this exactly once, after verifying the
+ * DoD, never speculatively.
+ */
+export declare function setMigrationPhase(ctx: BacklogCtx, phase: MigrationPhase): Promise<SetMigrationPhaseResult>;

package/env.d.ts

@@ -4,10 +4,14 @@ import { Environment } from '@adhd/environment';
 export interface BacklogConfig {
     readonly db: {
         readonly path: string | undefined;
+        readonly busyTimeoutMs: number;
     };
     readonly logging: {
         readonly level: string;
     };
+    readonly migration: {
+        readonly phase: string;
+    };
 }
 export declare const backlogEnvironmentSpec: EnvironmentSpec<BacklogConfig>;
 /**

package/index.d.ts

@@ -1,11 +1,17 @@
-export { addCitation, addDependency, appendNote, archiveResolved, assignItem, attachToPlan, auditTrail, blockers, claimItem, createItem, dependencyGraph, exportJson, getItem, importFromMarkdown, linkRelated, listItems, mergeItems, readyItems, releaseClaim, removeDependency, renderToMarkdown, renewClaim, resolveItem, setPriority, softDeleteItem, spotlight, splitItem, staleClaims, startWork, stats, supersedeItem, topoOrder, transitionStatus, updateItem, } from './client.js';
+export { addCitation, addDependency, appendNote, archiveResolved, assignItem, attachToPlan, auditTrail, blockers, claimItem, createItem, dependencyGraph, exportJson, getItem, importFromMarkdown, linkRelated, listItems, mergeItems, migrationStatus, readyItems, releaseClaim, removeDependency, renderToMarkdown, renewClaim, resolveItem, setMigrationPhase, setPriority, softDeleteItem, spotlight, splitItem, staleClaims, startWork, stats, supersedeItem, topoOrder, transitionStatus, updateItem, } from './client.js';
 export type { BacklogCtx } from './client.js';
 export { startBacklogServer, buildBacklogApigenPackage } from './server.js';
 export type { StartOpts } from './server.js';
+export { runBacklogCli, resolveCommandPrefix, prefixCommand } from './cli.js';
+export type { RunBacklogCliOpts } from './cli.js';
+export { installSkill, runInstallSkillCommand } from './install-skill.js';
+export type { InstallSkillResult, SkillHost, SkillScope } from './install-skill.js';
+export { runServeCommand } from './serve.js';
+export type { RunServeCommandOpts } from './serve.js';
 export { buildBacklogEnv, resolveBacklogScope, suggestClaimantIdentity, backlogEnvironmentSpec } from './env.js';
 export type { BacklogConfig, BuildBacklogEnvOptions } from './env.js';
 export { openGraphBacklogStore, closeGraphBacklogStore } from './store/graph-backlog-store.js';
 export type { GraphBacklogStore } from './store/graph-backlog-store.js';
-export { buildChangelogSection, classifyStatus, detectPriority, detectStatus, normalizeLegacyStatus, parseBacklogMarkdown, renderItemsToMarkdown, toImportItems, } from './markdown.js';
-export type { ParsedImportItem, ParsedMarkdownItem } from './markdown.js';
+export { buildChangelogSection, classifyStatus, detectPriority, detectStatus, normalizeLegacyStatus, parseBacklogMarkdown, parseBacklogMarkdownWithDiagnostics, renderItemsToMarkdown, toImportItems, } from './markdown.js';
+export type { ParsedImportItem, ParsedMarkdownItem, ParseWithDiagnosticsResult } from './markdown.js';
 export * from './model.js';