@adhd/backlog 0.0.1 → 0.0.2

package/dist/install-skill.d.ts

@@ -0,0 +1,28 @@
+export type SkillHost = 'claude' | 'codex' | 'opencode';
+export type SkillScope = 'user' | 'project';
+export interface InstallSkillResult {
+    host: SkillHost;
+    scope: SkillScope;
+    path: string;
+}
+/**
+ * Copies the packaged `SKILL.md` into every requested host's skill
+ * directory, under a `backlog/` subdirectory (matching the `memory-usage`
+ * precedent's per-skill-named-directory shape). Also drops a thin
+ * `extension.json` (`{ name, version, type: "skill", entrypoint: "SKILL.md"
+ * }`) alongside it, matching that same precedent's shape for hosts that
+ * consume it — additive, never required for Claude Code's own
+ * description-based auto-surfacing to work.
+ *
+ * `homeOverride` is a TEST-ISOLATION ESCAPE HATCH ONLY (mirrors
+ * `BuildBacklogEnvOptions.adhdRoot`/`BacklogCtx.adhdRoot` elsewhere in this
+ * package) — never passed by `runInstallSkillCommand`/the real CLI, which
+ * always resolves the genuine machine home directory for `--scope user`.
+ */
+export declare function installSkill(argv: string[], 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
+ *  with the rest of the CLI's output convention despite bypassing apigen
+ *  dispatch entirely. */
+export declare function runInstallSkillCommand(argv: string[]): Promise<void>;

package/{markdown.d.ts → dist/markdown.d.ts}

@@ -1,4 +1,4 @@
-import { BacklogFilter, BacklogItem, BacklogStatus, Priority } from './model.js';
+import { BacklogFilter, BacklogItem, BacklogStatus, MalformedHeaderInfo, Priority } from './model.js';
 
 declare const LEGACY_TERMINAL_DONE: string[];
 declare const LEGACY_TERMINAL_WORKAROUND: string[];
@@ -36,8 +36,19 @@ export interface ParsedMarkdownItem {
     priority: string;
     body: string;
 }
+export interface ParseWithDiagnosticsResult {
+    items: ParsedMarkdownItem[];
+    malformedHeaders: MalformedHeaderInfo[];
+}
 /** Ported (structure preserved) from tools/util/backlog.mjs:106-155 (`parse`). */
 export declare function parseBacklogMarkdown(text: string): ParsedMarkdownItem[];
+/**
+ * Same parse as {@link parseBacklogMarkdown}, plus `malformedHeaders` — every
+ * `##`/`###` line that looks like a corrupted/typo'd id header and was
+ * dropped instead of parsed into an item (DEBT-BACKLOG-IMPORT-SILENT-DROP-001).
+ * `importFromMarkdown` (client.ts) uses this to populate `ImportResult.malformedHeaders`.
+ */
+export declare function parseBacklogMarkdownWithDiagnostics(text: string): ParseWithDiagnosticsResult;
 /**
  * SPEC.md §5.6 `renderToMarkdown` — one `###` block per item. Archived-item
  * exclusion (SPEC.md §5.4 `archiveResolved`'s "renderToMarkdown's default

package/dist/migration-admin.d.ts

@@ -0,0 +1,26 @@
+import { MigrationPhase } from './model.js';
+import { BacklogConfig } from './env.js';
+import { Environment } from '@adhd/environment';
+
+/**
+ * Mirrors `@adhd/environment-builder`'s own internal `roots.ts` global-root
+ * formula (`~/.<orgNamespace>/<project>/<namespace>/config.yaml`) using ONLY
+ * the public fields the `@adhd/environment` `Environment` instance exposes
+ * (`orgNamespace`/`project`/`namespace`) — `@adhd/backlog` does not depend on
+ * the internal `environment-builder` package directly, so this is a
+ * deliberate, narrow re-derivation, not an import of a private module.
+ * `adhdRootOverride` mirrors `EnvironmentOptions.adhdRoot`'s own test-isolation
+ * escape hatch (see `BuildBacklogEnvOptions`) for tests that must never touch
+ * the real machine-global `~/.adhd`.
+ */
+export declare function globalConfigPath(env: Environment<BacklogConfig>, adhdRootOverride?: string): string;
+/**
+ * Reads the existing global `config.yaml` (if any), deep-merges in
+ * `migration.phase`, and writes it back — preserving every OTHER key already
+ * in the file (e.g. a previously-set `db.busyTimeoutMs` override) rather than
+ * clobbering the whole file. A missing or malformed existing file is treated
+ * as empty (never fatal for a write), mirroring
+ * `@adhd/environment-builder`'s own `readLayerFile` tolerance for a corrupt
+ * layer. Returns the absolute path written, for caller confirmation.
+ */
+export declare function writeMigrationPhase(env: Environment<BacklogConfig>, phase: MigrationPhase, adhdRootOverride?: string): string;

package/{model.d.ts → dist/model.d.ts}

@@ -48,6 +48,8 @@ export interface BacklogItem {
     projectPath?: string;
     /** Plan slug this item is attached to, if any — e.g. "agent-registry-schema". */
     plan?: string;
+    /** Source markdown path this item was imported from, if any (DEBT-BACKLOG-IMPORT-PLAN-PROVENANCE-001). */
+    importedFrom?: string;
     /** Durable ownership — who this item is assigned to (may differ from the active claimant). */
     assignee?: string;
     /** Ephemeral claim lease — see SPEC.md §5. */
@@ -92,6 +94,8 @@ export interface CreateItemInput {
     priority?: Priority;
     tags?: string[];
     plan?: string;
+    /** Source markdown path this item is being imported from, if any (DEBT-BACKLOG-IMPORT-PLAN-PROVENANCE-001). */
+    importedFrom?: string;
     dedupeScan?: DedupeScanInput;
     /** Skip the dedupe gate and file anyway (planner override after reviewing candidates). */
     force?: boolean;
@@ -106,6 +110,14 @@ export interface UpdateItemInput {
     body?: string;
     tags?: string[];
     projectPath?: string;
+    /**
+     * Provenance owner of this item (the source-file path that authored it).
+     * Only ever set to BACKFILL a legacy row whose `importedFrom` was never
+     * stamped (created before the provenance field existed) — see
+     * `importFromMarkdown`'s owning-import branch. An already-stamped owner is
+     * immutable and must never be reassigned via this patch.
+     */
+    importedFrom?: string;
 }
 export interface BacklogFilter {
     repo?: string;
@@ -119,6 +131,30 @@ export interface BacklogFilter {
     claimedBy?: string;
     tags?: string[];
     grep?: string;
+    /**
+     * Exact-match on `BacklogItem.importedFrom` — the sourcePath that OWNS an
+     * item's canonical content (DEBT-BACKLOG-IMPORT-SCOPE-CROSSFILE-001).
+     * Needed for a root-level `BACKLOG.md` projection: filtering by bare
+     * `{repo}` alone would also surface every item cross-referenced FROM root
+     * by a plan/package file (which correctly carries a `plan`/`projectPath`
+     * of its own once ownership-gating lands) — `importedFrom` is the only
+     * field that reliably answers "does THIS file own this item's content",
+     * independent of which OTHER files also cite the same id.
+     */
+    importedFrom?: string;
+    /**
+     * Repo-level projection selector (MIGRATION.md §2.2 "root BACKLOG.md =
+     * repo-only, no projectPath/plan"). When true, returns only items that carry
+     * NEITHER a `projectPath` NOR a `plan` — i.e. items owned by the repo root
+     * rather than a package or plan projection. Unlike the `importedFrom`
+     * workaround it does not depend on provenance, so a freshly tool-created
+     * repo-level item (which has no `importedFrom`) still appears in the root
+     * projection — the Phase-3 DoD ("a fresh create-item appears in the
+     * regenerated BACKLOG.md") requires this. Cross-referenced items that carry a
+     * `plan`/`projectPath` render in that plan/package projection instead, never
+     * duplicated into root.
+     */
+    rootLevel?: boolean;
     limit?: number;
     offset?: number;
 }
@@ -194,16 +230,45 @@ export interface ImportMarkdownInput {
     path: string;
     repo: string;
     projectPath?: string;
+    /** Plan slug to attach every imported item to (DEBT-BACKLOG-IMPORT-PLAN-PROVENANCE-001) — replaces the post-import attachToPlan-per-id workaround. */
+    plan?: string;
+    /**
+     * Provenance path recorded on each imported node's `importedFrom` field
+     * (DEBT-BACKLOG-IMPORT-PLAN-PROVENANCE-001). Defaults to `path` when
+     * omitted — the file actually read IS the source, so a caller only needs
+     * to set this explicitly when it differs (e.g. importing from a scratch
+     * copy but wanting the ORIGINAL path recorded).
+     */
+    sourcePath?: string;
     dryRun?: boolean;
 }
+/** A `##`/`###` header line that failed the strict `HEADER_RE` id pattern but looks like an attempted id (DEBT-BACKLOG-IMPORT-SILENT-DROP-001). */
+export interface MalformedHeaderInfo {
+    /** 1-based line number in the source file. */
+    line: number;
+    headerLine: string;
+}
 export interface ImportResult {
     parsed: number;
     created: number;
     skippedDuplicates: number;
+    /**
+     * Of `skippedDuplicates` (an already-existing humanId), how many had a
+     * title/body/priority/status that DIFFERED from the graph's current copy
+     * and were refreshed to match the re-imported source
+     * (BUG-BACKLOG-IMPORT-INSERT-ONLY-NO-UPDATE-001 — re-importing used to be
+     * pure insert-only: a status/content change made directly in a
+     * `BACKLOG.md` file after the first import was silently never reflected
+     * in the graph on a later re-import). An unchanged existing item is a
+     * true no-op — never counted here.
+     */
+    updated: number;
     errors: Array<{
         humanId: string;
         message: string;
     }>;
+    /** Headers that look like a corrupted/typo'd id and were dropped instead of parsed — never silent (DEBT-BACKLOG-IMPORT-SILENT-DROP-001). */
+    malformedHeaders: MalformedHeaderInfo[];
 }
 export interface AuditTrailEntry {
     at: string;
@@ -218,3 +283,18 @@ export interface AuditTrailResult {
         supersededBy?: string;
     };
 }
+export type MigrationPhase = 'not-started' | 'phase-1' | 'phase-2' | 'phase-3' | 'phase-4' | 'phase-5' | 'complete';
+export interface MigrationStatusResult {
+    phase: MigrationPhase;
+    /** One-line human-readable meaning of `phase`, e.g. "phase-2: BACKLOG.md is still authoritative; the tool is shadow-running in parity-check mode." */
+    description: string;
+    /** True once the graph (not hand-edited markdown) is authoritative — phase-3 and later. */
+    toolIsAuthoritative: boolean;
+}
+/** `setMigrationPhase`'s result — `MigrationStatusResult` plus the absolute
+ *  path of the GLOBAL `config.yaml` the new phase was persisted to (so a
+ *  caller can confirm this was a durable, cross-process write, not merely an
+ *  in-memory value). */
+export interface SetMigrationPhaseResult extends MigrationStatusResult {
+    configPath: string;
+}

package/dist/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@adhd/backlog",
+  "version": "0.0.2",
+  "bin": {
+    "backlog": "./dist/index.js"
+  },
+  "dependencies": {
+    "@adhd/sox-graph-store": "^0.3.0",
+    "better-sqlite3": "^12.10.0",
+    "@adhd/environment": "0.0.2",
+    "@adhd/environment-base-spec": "0.0.3",
+    "@adhd/apigen-core-client": "^0.1.1",
+    "@adhd/apigen-plugin-api-fastify": "^0.1.2",
+    "@adhd/apigen-plugin-openapi": "^0.1.3",
+    "@adhd/apigen-plugin-mcp": "^0.1.2",
+    "@adhd/apigen-plugin-cli-output": "^0.1.3",
+    "@adhd/apigen-engine-naming": "^0.1.3",
+    "yaml": "1.10.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "typings": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "skill"
+  ]
+}

package/dist/serve.d.ts

@@ -0,0 +1,12 @@
+import { Scope } from '@adhd/environment-base-spec';
+
+export interface RunServeCommandOpts {
+    scope?: Scope;
+    /** Test-only override — see `buildBacklogEnv`'s `BuildBacklogEnvOptions`. */
+    adhdRoot?: string;
+    cwd?: string;
+}
+/** Runs until the process receives SIGTERM/SIGINT (the normal way a host
+ *  process manager — or `.mcp.json`'s own stdio transport lifecycle — stops
+ *  a long-lived MCP/HTTP server), then resolves cleanly. */
+export declare function runServeCommand(argv: string[], opts?: RunServeCommandOpts): Promise<void>;

package/dist/server.d.ts

@@ -0,0 +1,54 @@
+import { BacklogCtx } from './client.js';
+import { composeSchemas, Operation, OutputPlugin, RunInput } from '@adhd/apigen-core-client';
+import { Scope } from '@adhd/environment-base-spec';
+
+/**
+ * Guards a live-mount `plugin.run()` call. Exported (not local to this file)
+ * because `cli.ts`'s `runBacklogCli` — the third transport, mounting
+ * `@adhd/apigen-plugin-cli-output` the exact same way this file mounts
+ * fastify/mcp — needs the identical guard; duplicating a 3-line assertion
+ * across two files in the SAME package isn't worth a new `packages/`
+ * extraction (CLAUDE.md's "Two-Use Refactor Rule" targets logic reusable
+ * ACROSS packages, not an in-package private helper), so it's shared via a
+ * plain re-export instead.
+ */
+export declare function requireRun(plugin: OutputPlugin): (input: RunInput) => Promise<void>;
+export interface StartOpts {
+    transport: 'http' | 'mcp' | 'both';
+    port?: number;
+    host?: string;
+    scope?: Scope;
+    /** Test-only override — see `buildBacklogEnv`'s `BuildBacklogEnvOptions`. */
+    adhdRoot?: string;
+    cwd?: string;
+    signal: AbortSignal;
+}
+/**
+ * Builds the composed, apigen-ready package descriptor for `client.ts`'s
+ * exports. `ctx` may be a plain `BacklogCtx` (the store is already open —
+ * `startBacklogServer`'s case, where a long-lived server needs its store
+ * immediately regardless of what request comes first) OR a LAZY `() =>
+ * BacklogCtx` thunk (`runBacklogCli`'s case) — `createClient` only calls it
+ * when a dispatched command actually reaches the real function, which never
+ * happens for `--help`/no-args/an unknown command. This is what closes
+ * DEBT-BACKLOG-CLI-EAGER-STORE-OPEN-001: `operations`/`schemas` below are
+ * computed purely from the built `client.d.ts` (via `extractClientOperations`)
+ * and never touch `ctx` at all, so a lazy caller can defer opening the real
+ * backing store until a command that actually needs it is dispatched.
+ */
+export declare function buildBacklogApigenPackage(ctx: BacklogCtx | (() => BacklogCtx)): Promise<{
+    pkg: {
+        id: string;
+        schemas: ReturnType<typeof composeSchemas>;
+        importPath: string;
+        fns: Record<string, (...args: unknown[]) => unknown>;
+        createClient: () => Promise<BacklogCtx>;
+    };
+    operations: Operation[];
+}>;
+/**
+ * Opens (or reuses) the backlog store + env, mounts every `client.ts` export
+ * live via `@adhd/apigen-plugin-api-fastify` and/or `@adhd/apigen-plugin-mcp`
+ * — no code generation.
+ */
+export declare function startBacklogServer(opts: StartOpts): Promise<void>;

package/dist/store/audit-log.d.ts

@@ -0,0 +1,16 @@
+import { GraphBacklogStore } from './graph-backlog-store.js';
+import { AuditTrailEntry } from '../model.js';
+
+export declare const BACKLOG_AUDIT_EVENT_TAG = "backlog-audit-event";
+/**
+ * Records one `transition`/`claim` event for the item at `itemNodeId`.
+ * `content` is a uniqueness-marker string (mirrors `buildNodeContent()`'s
+ * own reasoning, `mapping.ts`) — `@adhd/sox-graph-store`'s global
+ * content-hash dedup would otherwise be free to collapse two
+ * byte-identical events (e.g. two items independently transitioning
+ * `OPEN`→`IN_PROGRESS` with no `by`/`reason` at all) into ONE node.
+ */
+export declare function writeAuditEvent(store: GraphBacklogStore, itemNodeId: number, repo: string, humanId: string, kind: AuditTrailEntry['kind'], detail: Record<string, unknown>): void;
+/** Every persisted event for `itemNodeId`, oldest first — ready to merge
+ *  straight into `auditTrail()`'s `history` array. */
+export declare function queryAuditEvents(store: GraphBacklogStore, itemNodeId: number): AuditTrailEntry[];

package/{store → dist/store}/crud.d.ts

@@ -5,15 +5,22 @@ declare function dedupeScan(store: GraphBacklogStore, repo: string, input: Creat
 export declare function createItemNode(store: GraphBacklogStore, input: CreateItemInput): CreateItemResult;
 export declare function getItemNode(store: GraphBacklogStore, repo: string, humanId: string): BacklogItem | null;
 /**
- * DEVIATION: `@adhd/sox-graph-store` exposes no primitive to update a node's
- * `content` column after creation (`touch()`'s `Partial<NodeMeta>` covers
+ * DEVIATION (mitigated — DEBT-BACKLOG-CONTENT-IMMUTABLE-001): `@adhd/sox-graph-store`
+ * exposes no PUBLIC primitive to update a node's `content` column after
+ * creation (`touch()`'s `Partial<NodeMeta>` covers
  * name/summary/topic/tags/importance/confidence/tExpires/metadata — never
  * `content`; verified against the real source). `title` updates the `summary`
  * column (source of truth for the API) AND `metadata.title`; `body` updates
- * ONLY `metadata.body` (source of truth for the API). The underlying FTS
- * `content` (set once at `createItem` time) therefore does not reflect a
- * later body edit — `listItems({ grep })` may miss a post-edit body term
- * until the item is superseded. Filed as DEBT-BACKLOG-CONTENT-IMMUTABLE-001.
+ * `metadata.body` (source of truth for the API). Below, a title/body change
+ * ALSO re-synchronizes the FTS-indexed `content`/`content_hash` columns
+ * directly via raw SQL on the store-owned `db` handle — the same DESIGN.md
+ * §14-sanctioned escape hatch `structure.ts`'s `removeDependencyNode` already
+ * uses for the one other gap (`edge` deletion) the `GraphBackend` API lacks.
+ * This is safe specifically because `fts_node_au` (the real schema's `AFTER
+ * UPDATE ON node` trigger — `~/dev/ai/sox-ecosystem/libs/data/graph/graph-store/
+ * src/index.ts`'s `FTS_TRIGGERS`) re-indexes `fts_node` automatically on
+ * ANY write to `node.content`/`name`/`summary`, so no separate FTS statement
+ * is needed here.
  */
 export declare function updateItemNode(store: GraphBacklogStore, repo: string, humanId: string, patch: UpdateItemInput): BacklogItem;
 export declare function softDeleteItemNode(store: GraphBacklogStore, repo: string, humanId: string, reason: string): void;

package/dist/store/graph-backlog-store.d.ts

@@ -0,0 +1,20 @@
+import { GraphBackend } from '@adhd/sox-graph-store';
+import { default as Database } from 'better-sqlite3';
+
+export interface GraphBacklogStore {
+    /** Raw handle — ONLY for the CAS transaction wrapper (mutate-metadata.ts / ids.ts). */
+    readonly db: Database.Database;
+    /** All non-CAS reads/writes go through this. */
+    readonly graph: GraphBackend;
+}
+/**
+ * @param busyTimeoutMs SQLite `busy_timeout` (ms) — how long a blocked
+ *   `.immediate()` waits for a contended lock before throwing `SQLITE_BUSY`
+ *   (DEBT-BACKLOG-CONCURRENCY-BUSY-RETRY-001). Callers reading from
+ *   `BacklogConfig` should pass `env.config.db.busyTimeoutMs`; the default
+ *   here (5000) matches that config field's own default, for callers (tests,
+ *   ad-hoc scripts) that open a store directly without going through
+ *   `buildBacklogEnv`.
+ */
+export declare function openGraphBacklogStore(dbPath: string, busyTimeoutMs?: number): GraphBacklogStore;
+export declare function closeGraphBacklogStore(store: GraphBacklogStore): void;

package/dist/store/ids.d.ts

@@ -0,0 +1,24 @@
+import { GraphBacklogStore } from './graph-backlog-store.js';
+import { NodeRecord } from '@adhd/sox-graph-store';
+
+/**
+ * Resolves the humanId to insert under (either `idOverride`, re-verified for
+ * an already-live node, or the next auto-allocated `family-NNN`) and invokes
+ * `insert(humanId, existing)` — ALL inside one retried `.immediate()`
+ * transaction, so no other concurrent `.immediate()`-wrapped write can
+ * interleave between "the id was resolved" and "a node claiming it landed".
+ * `existing` is the already-live node under `idOverride` (re-checked HERE,
+ * not just by an earlier, racy caller-side check) — `insert` is expected to
+ * short-circuit on a non-null `existing` exactly like `createItemNode`'s
+ * documented idempotent-reimport behavior, but now race-free.
+ */
+export declare function allocateHumanIdAndInsert<T>(store: GraphBacklogStore, repo: string, family: string, idOverride: string | undefined, insert: (humanId: string, existing: NodeRecord | null) => T): T;
+/**
+ * @deprecated kept ONLY as a standalone id-generator for any caller that does
+ * not need an atomic insert alongside it. `createItemNode`/
+ * `supersedeItemNode` no longer use this (see `allocateHumanIdAndInsert`'s
+ * doc comment for why splitting allocate-then-insert-later is unsafe under
+ * concurrency). Still correct in isolation — just NOT TOCTOU-safe when the
+ * caller's own insert happens in a separate, later transaction.
+ */
+export declare function allocateHumanId(store: GraphBacklogStore, repo: string, family: string): string;

package/dist/store/immediate-retry.d.ts

@@ -0,0 +1,27 @@
+/**
+ * immediate-retry.ts — bounded, jittered exponential-backoff retry wrapper
+ * around a `db.transaction(fn).immediate()` call (DEBT-BACKLOG-CONCURRENCY-
+ * BUSY-RETRY-001). `mutate-metadata.ts` / `ids.ts` are the ONLY two write
+ * paths that call `.immediate()` directly (DESIGN.md §3/§4.3) and both funnel
+ * through this wrapper — retrying ONLY the specific `SQLITE_BUSY`/
+ * `SQLITE_BUSY_TIMEOUT`/`SQLITE_BUSY_SNAPSHOT` error `better-sqlite3` throws
+ * when a `BEGIN IMMEDIATE`'s wait exceeds `busy_timeout`. Any other thrown
+ * error (including `NotFoundError`, `ClaimContentionError`) propagates
+ * immediately, unretried — and the semantic `'held'` claim-contention RESULT
+ * (claim.ts) is a normal RETURN VALUE, never an exception, so it is never
+ * touched by this wrapper either.
+ */
+export interface ImmediateRetryOpts {
+    /** Total attempts (first try + retries). Default 5. */
+    maxAttempts?: number;
+}
+/**
+ * Runs `attempt()` (expected to be `() => db.transaction(fn).immediate()`),
+ * retrying up to `maxAttempts` times ONLY when it throws a SQLITE_BUSY-shaped
+ * error, with jittered exponential backoff between attempts (20ms, 40ms,
+ * 80ms, 160ms, capped at 500ms). Any other error propagates immediately.
+ * After the final attempt still fails, the last SQLITE_BUSY error is
+ * re-thrown (a genuine, sustained pileup is still a real failure — this
+ * bounds the wait, it doesn't hide contention forever).
+ */
+export declare function withImmediateRetry<T>(attempt: () => T, opts?: ImmediateRetryOpts): T;

package/dist/store/mapping.d.ts

@@ -0,0 +1,101 @@
+import { BacklogItem, BacklogStatus, Citation, Note, Priority } from '../model.js';
+import { NodeRecord } from '@adhd/sox-graph-store';
+
+export declare const BACKLOG_ITEM_TAG = "backlog-item";
+export declare const BACKLOG_PLAN_TAG = "backlog-plan";
+export declare const BACKLOG_ASSIGNEE_TAG = "backlog-assignee";
+/**
+ * Mirrors `@adhd/sox-graph-store`'s PRIVATE (unexported) `hashContent()`
+ * (`sha256(content.trim().toLowerCase())`) exactly. Needed only by
+ * `updateItemNode` (crud.ts), which writes `node.content`/`node.content_hash`
+ * directly via raw SQL (DESIGN.md §14's sanctioned escape hatch for the one
+ * gap `touch()` doesn't cover — DEBT-BACKLOG-CONTENT-IMMUTABLE-001) and must
+ * keep `content_hash` consistent with the `content` it just wrote, exactly as
+ * `writeNode()` would have. If upstream ever changes its normalization, this
+ * copy must change with it — there is no shared primitive to import instead.
+ */
+export declare function computeContentHash(content: string): string;
+/**
+ * `@adhd/sox-graph-store`'s `searchNodes(query)` binds `query` DIRECTLY as an
+ * FTS5 `MATCH` argument, parsed by FTS5's own boolean/column-filter query
+ * grammar — NOT a plain-text search. `searchNodes`'s own `query.replace(/"/g,
+ * '""')` cannot make this safe for arbitrary text: doubling an EXISTING `"`
+ * always yields an EVEN number of quote characters in the output, so a
+ * caller can never end up with a validly single-quoted phrase this way
+ * (verified empirically — wrapping a title in quotes before calling
+ * `searchNodes` still throws). A title containing a bare `-`, `:`, `(`, `)`,
+ * or `"` (all real English titles — "off-by-one", "fix: the thing" — not
+ * edge cases) crashes `createItemNode`'s dedupe scan outright with a raw
+ * `SqliteError`, since `force:true` (the only path that SKIPS the dedupe
+ * scan) is not the default. `dedupeScan` (crud.ts) uses this to strip every
+ * FTS5-syntax-significant character to a space before searching — this is
+ * BEHAVIOR-PRESERVING for the already-working case (a title with no special
+ * characters passes through unchanged, still an implicit-AND bareword
+ * query), and merely prevents the CRASH for the common case that hits one.
+ */
+/**
+ * Strips every FTS5-syntax-significant character to a space before a title/
+ * grep term ever reaches `searchNodes`'s raw MATCH bind (dedupeScan and
+ * `queryItemNodes`'s grep path, BUG-BACKLOG-DEDUPE-FTS-SYNTAX-CRASH-001).
+ *
+ * The original fix (2026-07) only stripped the small set of characters found
+ * in the reported crash: `"():^*-`. `#` (an entirely ordinary character in a
+ * real title, e.g. "Fixes #123" or this file's own regression test) was
+ * discovered independently to ALSO crash `searchNodes` with `fts5: syntax
+ * error near "#"` — and probing FTS5's actual grammar directly (not
+ * guessing) turned up a much longer list that crashes the same way: `. { }
+ * ~ [ ] @ ! $ % & = < > ? / \ ; ,` — `{` is the most dangerous of these
+ * (`no such column: create` — it gets parsed as column-filter syntax rather
+ * than merely erroring, a correctness risk beyond a crash). A second
+ * whack-a-mole char-by-char addition would leave the same class of gap open
+ * for whatever punctuation mark comes up next, so this strips every
+ * character that is NOT a Unicode letter, number, underscore, or whitespace
+ * — the complete, non-enumerable-by-hand safe set for an FTS5 bareword
+ * query — rather than continuing to enumerate a denylist.
+ */
+export declare function sanitizeFtsQuery(text: string): string;
+/**
+ * The JSON shape persisted in `node.meta` (DESIGN.md §2.2/§4.1). Every
+ * mutating store operation reads the CURRENT full object, computes a new
+ * COMPLETE object, and writes it back via `mutateMetadata` — `touch()`
+ * replaces `meta` wholesale (verified, DESIGN.md §14 point 4), so a partial
+ * write here would silently drop every other field.
+ */
+export interface BacklogNodeMeta {
+    humanId: string;
+    kind: string;
+    family: string;
+    title: string;
+    body: string;
+    status: BacklogStatus;
+    priority?: Priority;
+    repo: string;
+    projectPath?: string;
+    plan?: string;
+    /** Source markdown path this item was imported from, if any (DEBT-BACKLOG-IMPORT-PLAN-PROVENANCE-001). */
+    importedFrom?: string;
+    assignee?: string;
+    claimedBy?: string;
+    claimedAt?: string;
+    citations: Citation[];
+    notes: Note[];
+    createdAt: string;
+    updatedAt: string;
+    /** Set by archiveResolved — excludes the item from renderToMarkdown's default view. */
+    archivedAt?: string;
+    /** Dedupe-scan exact-match fields (DESIGN.md §2.4). */
+    dedupeSymbol?: string;
+    dedupePath?: string;
+    dedupeErrorText?: string;
+}
+export declare function humanIdKind(humanId: string): string;
+export declare function humanIdFamily(humanId: string): string;
+/** See the file-level DEVIATION doc comment for why the marker is appended. */
+export declare function buildNodeContent(repo: string, humanId: string, title: string, body: string): string;
+export declare function buildNodeName(repo: string, humanId: string): string;
+/** DESIGN.md §2.2 — importance derived deterministically from priority. */
+export declare function importanceForPriority(priority: Priority | undefined): number;
+export declare function buildTags(kind: string, family: string, userTags?: readonly string[]): string[];
+/** A node counts as a live backlog item iff it carries the tag AND is not superseded (DESIGN.md §14). */
+export declare function isLiveBacklogItemNode(node: NodeRecord): boolean;
+export declare function toBacklogItem(node: NodeRecord): BacklogItem;

package/package.json

@@ -1,20 +1,34 @@
 {
   "name": "@adhd/backlog",
-  "version": "0.0.1",
+  "version": "0.0.2",
+  "bin": {
+    "backlog": "./dist/index.js"
+  },
   "dependencies": {
     "@adhd/sox-graph-store": "^0.3.0",
     "better-sqlite3": "^12.10.0",
-    "@adhd/environment": "^0.0.2",
-    "@adhd/environment-base-spec": "^0.0.3",
-    "@adhd/apigen-core-client": "^0.1.2",
-    "@adhd/apigen-plugin-api-fastify": "^0.1.3",
-    "@adhd/apigen-plugin-openapi": "^0.1.4",
-    "@adhd/apigen-plugin-mcp": "^0.1.3"
+    "@adhd/environment": "0.0.2",
+    "@adhd/environment-base-spec": "0.0.3",
+    "@adhd/apigen-core-client": "^0.1.1",
+    "@adhd/apigen-plugin-api-fastify": "^0.1.2",
+    "@adhd/apigen-plugin-openapi": "^0.1.3",
+    "@adhd/apigen-plugin-mcp": "^0.1.2",
+    "@adhd/apigen-plugin-cli-output": "^0.1.3",
+    "@adhd/apigen-engine-naming": "^0.1.3",
+    "yaml": "1.10.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13"
   },
-  "main": "./index.js",
-  "module": "./index.mjs",
-  "typings": "./index.d.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "typings": "./dist/index.d.ts",
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "skill"
+  ]
 }