@adhd/backlog 0.0.1

package/CHANGELOG.md

@@ -0,0 +1 @@
+## Unreleased

package/README.md

@@ -0,0 +1,67 @@
+# @adhd/backlog
+
+A structured, queryable, multi-agent-safe **graph store** for backlog items (bugs,
+debt, features, investigations, plans) — a replacement for ad-hoc `BACKLOG.md`
+editing that stays compatible with the existing markdown convention this repo
+already uses.
+
+Built on `@adhd/sox-graph-store` (bi-temporal nodes/edges over SQLite) and mounted
+live via `@adhd/apigen-core-client` (no code generation — `extract()` →
+`composeSchemas()` → `plugin.run()`).
+
+See `SPEC.md` (functional spec: personas, data model, status vocabulary,
+operation surface) and `DESIGN.md` (technical design: graph mapping, claim
+protocol, env/apigen wiring) in this package for the full contract.
+
+```bash
+pnpm add @adhd/backlog
+```
+
+## Usage
+
+```ts
+import { createItem, listItems, claimItem, transitionStatus } from '@adhd/backlog';
+import { buildBacklogEnv } from '@adhd/backlog';
+import { openGraphBacklogStore } from '@adhd/backlog';
+
+const env = buildBacklogEnv();
+env.ensureDirs();
+const store = openGraphBacklogStore(env.files.db);
+const ctx = { store, env };
+
+const { item } = await createItem(ctx, {
+  family: 'BUG-EXAMPLE',
+  title: 'Example bug',
+  body: 'Something is broken.',
+  repo: 'PseudoSky/adhd',
+});
+
+await claimItem(ctx, item.repo, item.humanId, 'implementer:abc123');
+await transitionStatus(ctx, item.repo, item.humanId, 'FIXED', {
+  by: 'implementer:abc123',
+  citations: [{ file: 'entrypoint/backlog/src/client.ts' }],
+});
+
+const open = await listItems(ctx, { repo: item.repo, status: 'open' });
+```
+
+## Running as a live server (no codegen)
+
+```ts
+import { startBacklogServer } from '@adhd/backlog';
+
+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).
+
+## Scope
+
+Resolved via `@adhd/environment` (see `env.ts`): `global` (default —
+`~/.adhd/backlog/<namespace>/data/backlog.db`, spans every repo on the
+machine), `project` (`<projectRoot>/.adhd/backlog/<namespace>/data/backlog.db`,
+one repo), or `system`. See `SPEC.md` §3 for the full resolution order.

package/client.d.ts

@@ -0,0 +1,72 @@
+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 { Environment } from '@adhd/environment';
+
+/** The one type apigen special-cases via the `ctx-name-only` invariant. */
+export interface BacklogCtx {
+    store: GraphBacklogStore;
+    env: Environment<BacklogConfig>;
+}
+/**
+ * Dedupe-scans (FTS + symbol/path/errorText metadata match) before writing.
+ * Allocates humanId as family + next number within (repo, family) unless
+ * idOverride is given.
+ */
+export declare function createItem(ctx: BacklogCtx, input: CreateItemInput): Promise<CreateItemResult>;
+/** repo is required — humanId alone is not globally unique. */
+export declare function getItem(ctx: BacklogCtx, repo: string, humanId: string): Promise<BacklogItem | null>;
+export declare function updateItem(ctx: BacklogCtx, repo: string, humanId: string, patch: UpdateItemInput): Promise<BacklogItem>;
+export declare function listItems(ctx: BacklogCtx, filter?: BacklogFilter): Promise<BacklogItem[]>;
+/** Invalidates the node (bi-temporal — never a hard delete). */
+export declare function softDeleteItem(ctx: BacklogCtx, repo: string, humanId: string, reason: string): Promise<void>;
+export declare function stats(ctx: BacklogCtx, scope?: StatsScope): Promise<BacklogStats>;
+/** Open + prioritized, most-severe first. */
+export declare function spotlight(ctx: BacklogCtx, scope?: StatsScope, limit?: number): Promise<BacklogItem[]>;
+/** Open items whose every DEPENDS_ON target is a terminal status AND which are not currently claimed. */
+export declare function readyItems(ctx: BacklogCtx, scope?: StatsScope): Promise<BacklogItem[]>;
+/** The DEPENDS_ON set of `humanId` that is NOT yet terminal. */
+export declare function blockers(ctx: BacklogCtx, repo: string, humanId: string): Promise<BacklogItem[]>;
+export declare function dependencyGraph(ctx: BacklogCtx, scope?: StatsScope): Promise<DependencyGraph>;
+export declare function topoOrder(ctx: BacklogCtx, scope?: StatsScope): Promise<TopoOrderResult>;
+/** Items whose claim lease is older than maxAgeMin with no renewal — candidates for --force reclaim. */
+export declare function staleClaims(ctx: BacklogCtx, maxAgeMin: number, scope?: StatsScope): Promise<BacklogItem[]>;
+export declare function claimItem(ctx: BacklogCtx, repo: string, humanId: string, by: string, opts?: ClaimOpts): Promise<ClaimResult>;
+/** Same-claimant renewal — always succeeds (bumps claimedAt), no contention check. */
+export declare function renewClaim(ctx: BacklogCtx, repo: string, humanId: string, by: string): Promise<ClaimResult>;
+export declare function releaseClaim(ctx: BacklogCtx, repo: string, humanId: string, by: string, opts?: {
+    force?: boolean;
+}): Promise<ReleaseResult>;
+/** Durable ownership (planner decision) — distinct from the ephemeral claim lease. */
+export declare function assignItem(ctx: BacklogCtx, repo: string, humanId: string, to: string, by: string): Promise<BacklogItem>;
+/** transitionStatus(id, 'IN_PROGRESS', ...) + an implicit claimItem(id, by) — a no-op claim-wise if already held by `by`. */
+export declare function startWork(ctx: BacklogCtx, repo: string, humanId: string, by: string): Promise<BacklogItem>;
+export declare function transitionStatus(ctx: BacklogCtx, repo: string, humanId: string, status: BacklogStatus, opts: TransitionOpts): Promise<BacklogItem>;
+export declare function addCitation(ctx: BacklogCtx, repo: string, humanId: string, citation: Citation): Promise<BacklogItem>;
+export declare function appendNote(ctx: BacklogCtx, repo: string, humanId: string, by: string, text: string): Promise<BacklogItem>;
+/** Sugar for transitionStatus into any terminal status. */
+export declare function resolveItem(ctx: BacklogCtx, repo: string, humanId: string, status: BacklogStatus, opts: TransitionOpts): Promise<BacklogItem>;
+/**
+ * Renders terminal items to CHANGELOG.md-formatted markdown and marks them
+ * archived (metadata.archivedAt set) so renderToMarkdown's default view
+ * excludes them — the graph node itself is NEVER deleted.
+ */
+export declare function archiveResolved(ctx: BacklogCtx, scope: StatsScope, opts?: ArchiveOpts): Promise<ArchiveResult>;
+export declare function addDependency(ctx: BacklogCtx, repo: string, humanId: string, dependsOnHumanId: string): Promise<void>;
+export declare function removeDependency(ctx: BacklogCtx, repo: string, humanId: string, dependsOnHumanId: string): Promise<void>;
+export declare function linkRelated(ctx: BacklogCtx, repo: string, humanIdA: string, humanIdB: string): Promise<void>;
+/** Mints a new item, links new SUPERSEDES old, invalidates old with reason. */
+export declare function supersedeItem(ctx: BacklogCtx, repo: string, oldHumanId: string, newInput: CreateItemInput, reason: string): Promise<BacklogItem>;
+/** Creates N children linked child PART_OF parent. Parent is left open. */
+export declare function splitItem(ctx: BacklogCtx, repo: string, parentHumanId: string, children: CreateItemInput[]): Promise<BacklogItem[]>;
+/** SAME_AS(drop -> keep), invalidates drop with an auto-generated reason. */
+export declare function mergeItems(ctx: BacklogCtx, repo: string, keepHumanId: string, dropHumanId: string, reason: string): Promise<BacklogItem>;
+export declare function setPriority(ctx: BacklogCtx, repo: string, humanId: string, priority: Priority): Promise<BacklogItem>;
+/** 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. */
+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>;

package/env.d.ts

@@ -0,0 +1,36 @@
+import { EnvironmentSpec, Scope } from '@adhd/environment-base-spec';
+import { Environment } from '@adhd/environment';
+
+export interface BacklogConfig {
+    readonly db: {
+        readonly path: string | undefined;
+    };
+    readonly logging: {
+        readonly level: string;
+    };
+}
+export declare const backlogEnvironmentSpec: EnvironmentSpec<BacklogConfig>;
+/**
+ * Resolves scope per SPEC.md §3 (highest precedence first): explicit option →
+ * `ADHD_BACKLOG_SCOPE` → generic `ADHD_ENV_SCOPE` → default `'global'`.
+ */
+export declare function resolveBacklogScope(explicit?: Scope): Scope;
+/**
+ * Options accepted by `buildBacklogEnv`, beyond scope — `adhdRoot`/`cwd`/
+ * `instanceId` exist purely for test isolation (constructing an `Environment`
+ * rooted at a temp directory instead of the real machine's `~/.adhd`), mirror
+ * `EnvironmentOptions`'s own test-isolation fields.
+ */
+export interface BuildBacklogEnvOptions {
+    scope?: Scope;
+    adhdRoot?: string;
+    cwd?: string;
+    instanceId?: string;
+}
+export declare function buildBacklogEnv(options?: BuildBacklogEnvOptions): Environment<BacklogConfig>;
+/**
+ * DESIGN.md §4.4 — the recommended (not enforced) claimant identity shape:
+ * `${agentName}:${instanceId}`. Exposed as a plain helper, never baked into
+ * `claimItem` itself.
+ */
+export declare function suggestClaimantIdentity(agentName: string, instanceId: string): string;

package/index.d.ts

@@ -0,0 +1,11 @@
+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 type { BacklogCtx } from './client.js';
+export { startBacklogServer, buildBacklogApigenPackage } from './server.js';
+export type { StartOpts } from './server.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 * from './model.js';