@adhd/backlog 1.0.4 → 1.0.6

package/CHANGELOG.md

@@ -1,3 +1,72 @@
+## 1.0.6 (2026-09-29)
+
+### 🚀 Features
+
+- **backlog:** first-class citation verbs + one citation contract ([e46a0490](https://github.com/PseudoSky/adhd/commit/e46a0490))
+
+### 🩹 Fixes
+
+- **workspace:** restore the publish gate's heavy lane and canonicalise the gate ([45532731](https://github.com/PseudoSky/adhd/commit/45532731))
+- **backlog:** drop banned prior-version/current-version tokens from the cross-repo attestation spec ([acf53458](https://github.com/PseudoSky/adhd/commit/acf53458))
+- **backlog:** read verdict applies the write gate's close-predictor skip ([13e7c870](https://github.com/PseudoSky/adhd/commit/13e7c870))
+- **backlog:** a terminal-scoped obligation gates the close, not the claim (demo 3.3) ([5db10040](https://github.com/PseudoSky/adhd/commit/5db10040))
+- **backlog:** resolve a cross-repo anchor against the sibling project root that owns it (demo 2.4) ([068e554c](https://github.com/PseudoSky/adhd/commit/068e554c))
+
+### ❤️ Thank You
+
+- pseudosky
+
+## 1.1.0 (2026-09-28)
+
+### 🚀 Features
+
+- **backlog:** deterministic dependent-weight tiebreak in view:"order" (C2 AC4) ([15dc77ba](https://github.com/PseudoSky/adhd/commit/15dc77ba))
+- **backlog:** C6 verdict — derived actionability with reasons; claim refuses live blockers ([c0c0ea5c](https://github.com/PseudoSky/adhd/commit/c0c0ea5c))
+- **backlog:** C5 closure gate — terminal transitions require satisfied obligations ([a49ec889](https://github.com/PseudoSky/adhd/commit/a49ec889))
+- **backlog:** C10 — a spec is a revision of its ticket (store-citizen documents) ([02a969ba](https://github.com/PseudoSky/adhd/commit/02a969ba))
+- **backlog:** C4 obligation — obligate/unobligate + closed predicate core ([72ddafbe](https://github.com/PseudoSky/adhd/commit/72ddafbe))
+- **backlog:** C8 — closed primitives, readable catalogs, self-describing surface ([5e8cb041](https://github.com/PseudoSky/adhd/commit/5e8cb041))
+- **backlog:** C3 attestation — attest/recheck, anchors, citation roots ([f675393b](https://github.com/PseudoSky/adhd/commit/f675393b))
+- **backlog:** C9 cross-project similarity detection and reviewed linking ([f9e1eb96](https://github.com/PseudoSky/adhd/commit/f9e1eb96))
+- **backlog:** D-A trustworthy service layer — readiness, config-drift gate, retry+breaker ([aa894690](https://github.com/PseudoSky/adhd/commit/aa894690))
+- **backlog:** foundation — attestation/obligation node kinds + attests/has_obligation/satisfies edges (69632883) ([cc7eae49](https://github.com/PseudoSky/adhd/commit/cc7eae49))
+- **backlog:** C1 reference — prefix resolution, redirect, merge/rm-project ([2780b433](https://github.com/PseudoSky/adhd/commit/2780b433))
+- **backlog:** C7 honest envelopes, score provenance, bounded sub-collections, report ([8fa60ffd](https://github.com/PseudoSky/adhd/commit/8fa60ffd))
+- **backlog:** C2 kind-scope — related exposes all rel types, order spans member kinds ([f02e8d23](https://github.com/PseudoSky/adhd/commit/f02e8d23))
+
+### 🩹 Fixes
+
+- **backlog:** collapse the kind case-fragments in the repair CLI, pin the transition-path refusal ([16b42095](https://github.com/PseudoSky/adhd/commit/16b42095))
+- **backlog:** C10 spec discovery sees declared-kind SPECs, not only raw kind (603737c2) ([e4a6b51d](https://github.com/PseudoSky/adhd/commit/e4a6b51d))
+- **backlog:** C10 reconcile discovers live kind:SPEC items, not only raw node kind ([9c87e1d4](https://github.com/PseudoSky/adhd/commit/9c87e1d4))
+- **backlog:** C9 wire the cross-project structural second signal (A-side) ([c01ef514](https://github.com/PseudoSky/adhd/commit/c01ef514))
+- **backlog:** D-A apply the resolved service.* config (port/transport/host/resilience) ([4405e717](https://github.com/PseudoSky/adhd/commit/4405e717))
+- **backlog:** rename create partOf input to dedupeExcludeUid (c5460239; 081facec) ([7584a847](https://github.com/PseudoSky/adhd/commit/7584a847))
+- **backlog:** C1 lookup — match issue name, not body, so the registry is not shadowed ([46b3165d](https://github.com/PseudoSky/adhd/commit/46b3165d))
+- **backlog:** C7 — reconcile _score_kind doc/code vocabulary ([3c111d80](https://github.com/PseudoSky/adhd/commit/3c111d80))
+- **backlog:** create dedupe excludes a declared parent + its part_of ancestors (c5460239) ([dfb5aca9](https://github.com/PseudoSky/adhd/commit/dfb5aca9))
+- **backlog:** create dedupe gate fails closed, not open, on a degraded scan (BUG 4e8fce2a; cc2b5b87) ([04dd0283](https://github.com/PseudoSky/adhd/commit/04dd0283))
+
+### ❤️ Thank You
+
+- pseudosky
+
+## 1.0.5 (2026-09-27)
+
+### 🩹 Fixes
+
+- **backlog:** lock-serialise the shared dist across build/e2e/test ([02a33e33](https://github.com/PseudoSky/adhd/commit/02a33e33))
+- **backlog:** stop the catalog-invariant guard from gating writes ([dea2e476](https://github.com/PseudoSky/adhd/commit/dea2e476))
+- **backlog:** scope e2e-lane serialization to the e2e config ([b441d93c](https://github.com/PseudoSky/adhd/commit/b441d93c))
+- **nx-build:** make three verification gates actually fail when broken ([c4dc8ae0](https://github.com/PseudoSky/adhd/commit/c4dc8ae0))
+- **backlog:** stop the catalog-invariant guard from aborting reads ([7c941505](https://github.com/PseudoSky/adhd/commit/7c941505))
+- **backlog:** resolve uid prefixes with loud ambiguity refusal ([c9491ed4](https://github.com/PseudoSky/adhd/commit/c9491ed4))
+- **backlog:** normalize ETL status vocabulary to canonical lowercase ([8809de97](https://github.com/PseudoSky/adhd/commit/8809de97))
+
+### ❤️ Thank You
+
+- pseudosky
+
 ## 1.0.4 (2026-09-27)
 
 ### 🩹 Fixes

package/README.md

@@ -60,11 +60,20 @@ adhd-backlog create --input '{
 ```
 
 ```json
-{ "ok": true, "data": { "created": true, "uid": "b3b2da0e-…", "item": { "uid": "b3b2da0e-…", "title": "Query pagination drops the last page under offset paging", "kind": "issue", "status": "open", "priority": "HIGH", "project": "49ec673b-…", "component": "65c4e373-…", "createdAt": "2026-09-24T00:14:38.802Z", "author": "agent:worker-1", "gitContext": "feat/backlog-hard-replacement @ 4bf902fc" } } }
+{ "ok": true, "data": { "created": true, "uid": "b3b2da0e-…", "item": { "uid": "b3b2da0e-…", "title": "Query pagination drops the last page under offset paging", "kind": "issue", "status": "open", "priority": "HIGH", "project": "49ec673b-…", "component": "65c4e373-…", "createdAt": "2026-09-24T00:14:38.802Z", "author": "agent:worker-1", "gitContext": "feat/backlog-hard-replacement @ 4bf902fc" }, "placementResolved": "default-root" } }
 ```
 
 > `project` and `component` in the result are `uid`s, not names. `gitContext`
 > is described under [Citations & git context](#citations--git-context).
+> `placementResolved` is `"default-root"` when the omitted `component` fell
+> back to the project's reserved `(root)` component, or `"explicit"` when a
+> supplied one resolved — a `default-root` item is invisible to
+> component-scoped scans. A create result may additionally carry
+> `duplicateScanDegraded: true` plus `duplicateScanDegradedReason`
+> (`"no-search-backend"` / `"no-embed-query"` / `"no-vector-scores"`) when the
+> pre-write dedupe scan could not run a calibrated comparison; both are absent
+> on a healthy scan and never imply the write failed. Full field notes are in
+> [`skill/SKILL.md` §3](skill/SKILL.md).
 
 Query for it:
 
@@ -187,11 +196,94 @@ resolve to the wrong record.
 { "ok": false, "error": { "code": "conflict", "message": "Issue \"63c2f57e-…\" was superseded by a body edit and is no longer the live issue; it now lives under \"e3b32183-…\"", "details": { "retryable": false } } }
 ```
 
+### 8. Obligation-gated transitions and the actionability verdict
+
+Declare a typed requirement on an issue with `obligate`; the store then refuses
+any transition that would violate it until the requirement is met. A
+`block`-severity `evidence` obligation, for example, keeps a `closed`
+transition refused until a matching verified attestation exists.
+
+An obligation is scoped by `applies_to.to` to the **transition** it guards — a
+close-scoped obligation gates the close, **not** claimability. So `get` reports
+the item actionable (the same answer `claim` gives), and the close is what gets
+refused:
+
+```bash
+adhd-backlog get --input '{"uid":"1d9b77e5-…","fields":["verdict","obligations"]}'
+```
+
+```json
+{ "ok": true, "data": { "uid": "1d9b77e5-…", "obligations": [{ "uid": "fbcee200-…", "applies_to": { "to": "closed" }, "requirement": { "op": "evidence", "kind": "published-artifact", "min": 1 }, "on_fail": "block" }], "verdict": { "actionable": true, "evaluated_at": "…", "revision": 0, "conditions": [] } } }
+```
+
+Only an obligation scoped to a **non-terminal** transition (e.g.
+`applies_to:{to:"in_progress"}`) is due at claim time, and only then does it
+appear as a rung-2 block condition in the verdict.
+
+Attempt the close and the gate refuses with a typed `precondition_failed`,
+writing nothing:
+
+```json
+{ "ok": false, "error": { "code": "precondition_failed", "message": "Transition refused: EvidenceUnverified (requires \"published-artifact\") — no verified attestation of kind \"published-artifact\" satisfies this obligation", "details": { "retryable": false } } }
+```
+
+`actionable` is tri-state (`true` / `false` / `"unknown"`) — `"unknown"` is
+never a green light. The full declare → read → refuse → attest → close
+workflow, the closed predicate grammar, and the permitted-override path are in
+[`skill/SKILL.md` §4](skill/SKILL.md).
+
+### 9. Compare-and-swap spec revisions
+
+A ticket's work product is a sequence of immutable spec revisions.
+`spec-append` appends a fragment and advances the pointer in place, and its
+required `base_revision` makes the append a compare-and-swap: a stale base is
+refused with `precondition_failed` and nothing is written. `spec-check` tells a
+reader whether the token it holds is still current — an absent token is
+`stale`, never `fresh` — and `attest` records a comment keyed to an exact
+revision (never to the ticket body) via a `SPEC` subject + a `revision:` anchor:
+
+```bash
+adhd-backlog spec-check --input '{"uid":"c79b52b0-…"}'
+```
+
+```json
+{ "ok": true, "data": { "current_revision": "58b5dfd8-…", "current_token": "sha256:d0bcba4a…", "state": "stale", "method": "none", "reason": "no-token-supplied" } }
+```
+
+See [`skill/SKILL.md` §5](skill/SKILL.md) for the append/check worked example.
+
+### 10. Live catalogs and dependency-ordered plans
+
+`query --input '{"view":"catalogs"}'` returns every vocabulary the store
+enforces (kinds, statuses, priorities, relations, fields, error codes, location
+types, and the mounted verbs), each term naming the in-code source it was
+generated from. Note that **`kind` is open/free-form, not an enumerable
+allowlist**: `create` accepts any `kind` string and the `kind` catalog is a
+usage census (`source: "store"`), so it is **empty on a fresh store** and then
+lists what has actually been filed (`"issue"` is the default; `"plan"` is the
+conventional parent kind). `filter.kind` is validated against that live census,
+so filtering by a never-used kind is a `validation` error naming the values
+that do exist. This mirrors `status`, which is likewise an open catalog.
+
+`query --input '{"view":"order","filter":{"plan":"<uid>"}}'`
+returns a plan's members topologically ordered by their `blocks` edges. Note
+the trap: the `catalog` selector is honoured only with `view:"catalogs"` —
+`{"catalog":"status"}` without it silently returns the ordinary `list` view
+(never catalog `terms`). See
+[`skill/SKILL.md` §6](skill/SKILL.md).
+
 ## Command surface
 
 Every verb but `embedding-status` takes a single `--input` flag carrying one JSON
-object; there are no per-field flags. Nineteen operations (the 18 verbs plus
-`batch`):
+object; `embedding-status` takes **no** options at all. **There are no per-field
+flags** — a per-field option (`get --uid …`, `query --view list`, `create
+--title …`, `batch action --operation …`) fails with `invalid_argument` (exit 2)
+and `Unknown option: --<field>. Available: --input`. (`--help` prints a
+"per-field flags are also accepted" footer line; it is generated boilerplate
+that does not hold for these commands — `--input` is the only option they
+accept. The special commands `serve`, `install-skill`, and `search` are the
+exception: they take argv flags and no `--input`.) Thirty operations (the
+29 verbs plus `batch`):
 
 | Verb              | CLI                             | MCP tool                   |
 | ----------------- | ------------------------------- | -------------------------- |
@@ -200,11 +292,20 @@ object; there are no per-field flags. Nineteen operations (the 18 verbs plus
 | `priorityMatrix`  | `adhd-backlog priority-matrix`  | `backlog_priority_matrix`  |
 | `partOfRollup`    | `adhd-backlog part-of-rollup`   | `backlog_part_of_rollup`   |
 | `openCurve`       | `adhd-backlog open-curve`       | `backlog_open_curve`       |
+| `report`          | `adhd-backlog report`           | `backlog_report`           |
 | `embeddingStatus` | `adhd-backlog embedding-status` | `backlog_embedding_status` |
 | `lookup`          | `adhd-backlog lookup`           | `backlog_lookup`           |
 | `create`          | `adhd-backlog create`           | `backlog_create`           |
 | `update`          | `adhd-backlog update`           | `backlog_update`           |
+| `addCitation`     | `adhd-backlog add-citation`     | `backlog_add_citation`     |
+| `removeCitation`  | `adhd-backlog remove-citation`  | `backlog_remove_citation`  |
 | `transition`      | `adhd-backlog transition`       | `backlog_transition`       |
+| `attest`          | `adhd-backlog attest`           | `backlog_attest`           |
+| `recheck`         | `adhd-backlog recheck`          | `backlog_recheck`          |
+| `obligate`        | `adhd-backlog obligate`         | `backlog_obligate`         |
+| `unobligate`      | `adhd-backlog unobligate`       | `backlog_unobligate`       |
+| `specAppend`      | `adhd-backlog spec-append`      | `backlog_spec_append`      |
+| `specCheck`       | `adhd-backlog spec-check`       | `backlog_spec_check`       |
 | `claim`           | `adhd-backlog claim`            | `backlog_claim`            |
 | `relate`          | `adhd-backlog relate`           | `backlog_relate`           |
 | `move`            | `adhd-backlog move`             | `backlog_move`             |
@@ -213,15 +314,24 @@ object; there are no per-field flags. Nineteen operations (the 18 verbs plus
 | `upsertComponent` | `adhd-backlog upsert-component` | `backlog_upsert_component` |
 | `upsertLocation`  | `adhd-backlog upsert-location`  | `backlog_upsert_location`  |
 | `rmLocation`      | `adhd-backlog rm-location`      | `backlog_rm_location`      |
+| `mergeProject`    | `adhd-backlog merge-project`    | `backlog_merge_project`    |
+| `rmProject`       | `adhd-backlog rm-project`       | `backlog_rm_project`       |
 | `batch`           | `adhd-backlog batch action`     | `batch_action`             |
 
 `--help` prints these as `backlog <verb>`; the CLI also accepts the bare
 `adhd-backlog <verb>` form shown above, and accepts the explicit namespace
-prefix at any position. `get`/`query`/`lookup`/`embedding-status` are reads.
-`create`/`update`/`transition`/`claim`/`relate`/`move`/`delete` mutate one
-issue. The four `upsert*`/`rmLocation` verbs manage the **registry** —
-projects, components, and locations. `batch action` fans any one of them out
-over many items.
+prefix at any position. `get`/`query`/`lookup`/`embedding-status` and the four
+stats/rollup ops are reads. `create`/`update`/`add-citation`/`remove-citation`/
+`transition`/`claim`/`relate`/`move`/`delete` mutate one issue;
+`attest`/`recheck` record anchored evidence,
+and `obligate`/`unobligate` declare or retire a typed requirement that gates a
+transition ([SKILL.md §4](skill/SKILL.md)); `specAppend`/`specCheck` advance
+and verify a ticket's spec revisions, and a revision is annotated through
+`attest` with a `SPEC` subject + a `revision:` anchor ([SKILL.md
+§5](skill/SKILL.md)). The
+`upsert*`/`rmLocation` verbs manage the **registry** (projects, components,
+locations), and `mergeProject`/`rmProject` collapse or retire project rows.
+`batch action` fans any one of them out over many items.
 
 ## Transports
 
@@ -239,14 +349,45 @@ simultaneously true everywhere:
 Every verb call returns one of two shapes, on every transport:
 
 ```ts
-{ ok: true,  data: T, warnings?: string[], meta?: { total, returned, limit?, offset?, truncated? } }
+{ ok: true,  data: T, warnings?: string[],
+  meta?: { total, returned, limit?, offset?, truncated?, total_relation?, has_more?, next_cursor? } }
 { ok: false, error: { code, message, details? }, warnings?: string[] }
 ```
 
-`meta` is present on list-shaped reads (`query`) and its `total` is the true
-match count _before_ `limit`/`offset` are applied; a truncated page sets
-`data.hasMore: true` and `data.nextCursor`, so a short result never silently
-looks complete.
+`meta` is present on the four **item-list** reads (`query`'s `list`/`ready`/
+`stale`/`similar` views). `total` is the match count; on `list` it is the exact
+count _before_ `limit`/`offset`, while on `ready`/`stale`/`similar` a true
+pre-limit total is unknowable at bounded cost, so `meta` reports
+`has_more` (derived by fetching one row beyond the page) and labels `total`
+with `total_relation: 'gte'` — a lower bound, never a fabricated exact number
+(`'eq'` means exact). `graph`/`order`/`overlap` are a graph, a topological
+order, and an axis grouping — they deliberately carry **no** `meta`, because
+none of them is a filtered row set with an honest "how many matched" count.
+
+> **`view:"ready"` is not an actionability filter.** It selects the `open`
+> issues that are unclaimed and whose every live incoming `blocks` blocker is
+> terminal — a pure claim/`blocks` predicate that never evaluates obligations
+> or evidence. An item with an unsatisfied `block`-severity obligation
+> (`fields:["verdict"]` reports `actionable:false`) still appears in `ready`.
+> To find actionable work, read `fields:["verdict"]`; do not use `ready`.
+> Full definition: [`skill/SKILL.md` §3](skill/SKILL.md).
+
+A derived `_score` always carries its provenance: `_score_kind` is `'rrf'`
+(the fused text+vec rank `view:'similar'` and semantic list reads use),
+`'bm25'` (a grep-only FTS score), `'cosine'`, `'rank'`, or `'priority'`. A
+rank-derived `_score` is **ordinal** — never read it as a similarity or a
+confidence.
+
+Sub-collections can be bounded: `get { fields:["auditTrail"], lastN:5 }`
+returns at most the newest 5 audit rows (oldest-first order preserved);
+`part-of-rollup { uid, countOnly:true }` returns the counts and omits
+`childrenOpenUids` entirely, while `part-of-rollup { uid, limit, after }` pages
+the open-descendant uid list (`nextCursor`/`hasMore`).
+
+The `report` verb is a grouped rollup whose every number is computed from the
+store in that call: `byKind`, `byPriority` (composed from `priority-matrix`),
+`byStatus`, and `avgAgeDays` of open in-scope items, with `statusScope` naming
+exactly what was counted (`'open'` when the filter omits `status`).
 
 ### Error codes
 
@@ -269,11 +410,20 @@ code alone.
 
 ### Citations & git context
 
-A citation is `{ file, lines?, context?, symbol? }`. Pass `citations` on
-`create`, or on the `transition` that moves an issue into a terminal status
-when the project's policy requires it. `file` must name a file, not a
-directory: a directory target is rejected as a non-retryable `validation`
-error.
+A citation is `{ file, lines?, context?, symbol?, blastRadius?, revision? }`.
+Pass `citations` on `create`, or on the `transition` that moves an issue into a
+terminal status when the project's policy requires it. Add one to an existing
+issue with `add-citation` and retire one with `remove-citation` (addressed by
+the citation's **own uid**, never by re-specifying `(file, lines)`). `update`
+carries `citations` as a **diff-emitter** — it adds what's new and removes what's
+gone against the live set, in the same transaction, and never mints a new issue
+uid (only a `body` edit supersedes). `file` must name a file, not a directory: a
+directory target is rejected as a non-retryable `validation` error.
+
+Pin a citation to a git revision with `revision` (a branch, tag, or sha) to cite
+a file that exists **only on an unmerged branch** — the target is read from
+`git show <revision>:<path>` rather than the working tree, so the sha is a real
+content hash even though the file is not checked out.
 
 The item-level **`gitContext`** is separate from a citation's own `context`:
 it records the repo disclosure contract's `<active git context>` — the first
@@ -284,15 +434,17 @@ the item's `Citations:` block. Omit it and nothing is stored.
 
 ### Which build these docs describe
 
-These docs describe `entrypoint/backlog/dist/index.js` built from revision
-`9df2a5c7`, whose `create`/`transition` inputs include `gitContext`. A
-**globally installed** `adhd-backlog` may be an older build (it is whatever was
-last published/installed); on such a build `gitContext` is not in the schema
-and is rejected with `invalid_argument`, and the stats/rollup ops
-(`priority-matrix` / `part-of-rollup` / `open-curve`) are absent. Run
-`adhd-backlog --help` and compare the `backlog create` / `backlog
-priority-matrix` lines against this page if a documented field or verb is
-refused.
+These docs describe `entrypoint/backlog/dist/index.js` built from the revision
+captured here, which mounts 29 verbs — including the citation
+(`add-citation`/`remove-citation`), obligation
+(`obligate`/`unobligate`), spec-pointer (`spec-append`/`spec-check`),
+and catalog (`query --input '{"view":"catalogs"}'`) surfaces. A **globally
+installed** `adhd-backlog` may be an older build (it is whatever was last
+published/installed); on such a build `gitContext` may be rejected with
+`invalid_argument`, and the stats/rollup ops (`priority-matrix` /
+`part-of-rollup` / `open-curve` / `report`) and the obligation/spec verbs may be
+absent. Run `adhd-backlog --help` and compare it against
+[§1 of SKILL.md](skill/SKILL.md) if a documented field or verb is refused.
 
 ## Build & startup
 
@@ -322,29 +474,32 @@ the extract-stage IR cache, which persists the result for the next run.
 and store-free (it never opens the graph store and never writes under
 `~/.adhd`).
 
-| Setting          | Env var                    | Default                              | Notes                                                                                                                                    |
-| ---------------- | -------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| IR cache enabled | `APIGEN_IR_CACHE_ENABLED`  | `1`                                  | Governs ONLY the **runtime fallback** cache. It does **not** bypass the baked `api.ir.json` artifact — that artifact is the startup path, not a cache |
-| IR cache file    | `APIGEN_IR_CACHE_FILE`     | a machine-global path under `~/.adhd` | Where a fallback extraction's result is cached                                                                                            |
+| Setting          | Env var                   | Default                               | Notes                                                                                                                                                 |
+| ---------------- | ------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| IR cache enabled | `APIGEN_IR_CACHE_ENABLED` | `1`                                   | Governs ONLY the **runtime fallback** cache. It does **not** bypass the baked `api.ir.json` artifact — that artifact is the startup path, not a cache |
+| IR cache file    | `APIGEN_IR_CACHE_FILE`    | a machine-global path under `~/.adhd` | Where a fallback extraction's result is cached                                                                                                        |
 
 ## Library API
 
 Beyond the CLI/MCP/HTTP surface, the package exports its query layer
-(`src/query/index.ts`), including three rollup/stats read views that are **not**
+(`src/query/index.ts`), including four rollup/stats read ops that are **not**
 members of `query.view`:
 
 - `priorityMatrix(handle, { filter? })` — a status-aware per-priority count
   breakdown (defaults to open work; `filter.status` may be `'open'`, `'closed'`,
   `'all'`, or a status name).
-- `partOfRollup(handle, { uid })` — transitive `part_of` descendants of an
-  issue, counted once each regardless of chain depth.
+- `partOfRollup(handle, { uid, countOnly?, limit?, after? })` — transitive
+  `part_of` descendants of an issue, counted once each regardless of chain
+  depth; `countOnly` omits the uid list, `limit`/`after` page it.
 - `openCurve(handle, { filter?, at })` — per-sampled-instant counts of issues
   that existed and how many were open, reconstructed from the audit trail.
+- `report(handle, { filter? })` — a grouped rollup (`byKind`/`byPriority`/
+  `byStatus`/`avgAgeDays`) composed from live reads in the same call.
 
-Reach them by importing `@adhd/backlog` in-process. The same three are also
-mounted as operations — `priority-matrix` / `part-of-rollup` / `open-curve` on
-the CLI (`backlog_priority_matrix` / `backlog_part_of_rollup` /
-`backlog_open_curve` on MCP); see the command surface above.
+Reach them by importing `@adhd/backlog` in-process. The same four are also
+mounted as operations — `priority-matrix` / `part-of-rollup` / `open-curve` /
+`report` on the CLI (`backlog_priority_matrix` / `backlog_part_of_rollup` /
+`backlog_open_curve` / `backlog_report` on MCP); see the command surface above.
 
 ## Configuration
 
@@ -361,7 +516,7 @@ into a narrower scope.
 | Write busy timeout | `ADHD_BACKLOG_DATABASE_BUSY_TIMEOUT_MS`               | `5000`                        | How long a write waits on a contended lock before giving up                                                                                                                                                                                                                                                                                                                                             |
 | Log level          | `ADHD_BACKLOG_LOG_LEVEL`                              | `info`                        | `trace`\|`debug`\|`info`\|`warn`\|`error`\|`fatal`\|`silent`                                                                                                                                                                                                                                                                                                                                            |
 | Scope              | `ADHD_BACKLOG_SCOPE` (falls back to `ADHD_ENV_SCOPE`) | `global`                      | Which store root to resolve against                                                                                                                                                                                                                                                                                                                                                                     |
-| Namespace          | `--namespace <value>` CLI flag (no env var)           | `production`                  | Which path segment under the scope root to resolve against (`<root>/backlog/<namespace>/…`) — one of `production`\|`test`\|`sandbox`. `--namespace sandbox` ALSO mints a fresh throwaway root and writes a real `config.yaml` there with `embedding.enabled: false`, so a sandboxed invocation is isolated along two independent axes plus a deliberate config, never an accident of an empty directory |
+| Namespace          | `--namespace <value>` CLI flag (no env var)           | `production`                  | Which path segment under the scope root to resolve against (`<root>/backlog/<namespace>/…`) — one of `production`\|`test`\|`sandbox`. `--namespace sandbox` ALSO mints a fresh throwaway root and writes a real `config.yaml` there with `embedding.enabled: false`, so a sandboxed invocation is isolated along two independent axes plus a deliberate config, never an accident of an empty directory. It also **ignores a foreign `ADHD_ROOT`**: if the variable names a path this tool did not mint as a sandbox it warns `… is not a sandbox this tool created — ignoring it …` and mints a fresh store instead, so a stray `ADHD_ROOT` can never redirect a sandboxed run into an unrecognized location. `adhd-backlog sandbox-path` reports the resolved store without opening it; its `adhdRoot` key is present only when a root was explicitly resolved (`ADHD_ROOT` set, or `--namespace sandbox`) and is omitted for the default `production`/`test` namespaces |
 | Semantic search    | `ADHD_BACKLOG_EMBEDDING_ENABLED`                      | `false`                       | See below                                                                                                                                                                                                                                                                                                                                                                                               |
 | Embedding provider | `ADHD_BACKLOG_EMBEDDING_PROVIDER`                     | `fastembed`                   | Only consulted when embedding is enabled                                                                                                                                                                                                                                                                                                                                                                |
 | Embedding model    | `ADHD_BACKLOG_EMBEDDING_MODEL`                        | `bge-base-en-v1.5` (768-dim)  | Only consulted when embedding is enabled                                                                                                                                                                                                                                                                                                                                                                |

package/api.d.ts

@@ -1,3 +1,4 @@
+import { IMergeProjectInput, IMergeProjectOutcome, IRmProjectInput } from './write/merge-project.js';
 import { IUpsertProjectInput, IUpsertProjectOutcome, IUpsertComponentInput, IUpsertComponentOutcome, IUpsertLocationInput, IUpsertLocationOutcome, IRmLocationInput, IRmLocationOutcome } from './write/catalog.js';
 import { IDeleteIssueInput, IDeleteIssueOutcome } from './write/delete.js';
 import { IMoveIssueInput, IMoveIssueOutcome } from './write/move.js';
@@ -7,6 +8,12 @@ import { ITransitionInput, ITransitionOutcome } from './write/transition.js';
 import { IUpdateIssueInput, IUpdateIssueOutcome } from './write/update.js';
 import { ICreateIssueInput, ICreateIssueResult } from './write/create-issue.js';
 import { IIssueGetInput, IIssueGetResult, IIssueQueryInput, IIssueQueryResult, ILookupResult } from './query/types.js';
+import { ISpecCheckInput, ISpecCheckOutcome } from './query/spec-staleness.js';
+import { ISpecAppendInput, ISpecAppendOutcome } from './write/spec-revision.js';
+import { IObligateInput, IObligateOutcome, IUnobligateInput, IUnobligateOutcome } from './write/obligation.js';
+import { IAttestInput, IAttestOutcome, IRecheckInput, IRecheckOutcome } from './write/attestation.js';
+import { IAddCitationInput, IAddCitationOutcome, IRemoveCitationInput, IRemoveCitationOutcome } from './write/citation.js';
+import { IReportInput, IReportResult } from './query/views/report.js';
 import { IPriorityMatrixInput, IPriorityMatrixResult, IPartOfRollupInput, IPartOfRollupResult, IOpenCurveInput, IOpenCurveResult } from './query/views/stats.js';
 import { EmbeddingLiveConfig } from './write/embedding-config.js';
 import { IOutcomeEnvelope } from './envelope.js';
@@ -93,6 +100,17 @@ export declare function partOfRollup(ctx: BacklogCtx, input: IPartOfRollupInput)
  * `queryHandle` gates.
  */
 export declare function openCurve(ctx: BacklogCtx, input: IOpenCurveInput): Promise<IOutcomeEnvelope<IOpenCurveResult>>;
+/**
+ * SPEC.md §5 / DESIGN §5 AC7's grouped rollup — counts by kind, by priority
+ * (composed from `priorityMatrix`), and by status, plus the average age of
+ * open in-scope items, every number computed from the store in THIS call.
+ *
+ * A read op, NOT a `query.view` member: it returns a named-scope aggregate
+ * (`statusScope` names what was counted) keyed by no list cursor. Uses only
+ * `handle.graph` — see {@link priorityMatrix}'s note on the `queryHandle`
+ * gates.
+ */
+export declare function report(ctx: BacklogCtx, input: IReportInput): Promise<IOutcomeEnvelope<IReportResult>>;
 /** The `embedding_status` read op's payload (see {@link embeddingStatus}). */
 export interface IEmbeddingStatusResult {
     /** The on-disk `embedding.enabled` (observed from the config layers). */
@@ -136,6 +154,7 @@ export declare function embeddingStatus(ctx: BacklogCtx): Promise<IOutcomeEnvelo
  */
 export declare function lookup(ctx: BacklogCtx, input: {
     q: string;
+    kind?: string;
 }): Promise<IOutcomeEnvelope<ILookupResult>>;
 /** File a new issue, minting its `uid` and linking it to a project component. */
 export declare function create(ctx: BacklogCtx, input: ICreateIssueInput): Promise<IOutcomeEnvelope<ICreateIssueResult>>;
@@ -147,8 +166,60 @@ export declare function create(ctx: BacklogCtx, input: ICreateIssueInput): Promi
  * use `transition`.
  */
 export declare function update(ctx: BacklogCtx, input: IUpdateIssueInput): Promise<IOutcomeEnvelope<IUpdateIssueOutcome>>;
+/**
+ * Add one first-class citation to an existing issue.
+ *
+ * Mints a `citation` node + its `has_citation` edge + an audit row, atomically.
+ * The citation may pin a git `revision` to cite evidence that exists only on an
+ * unmerged branch. `update` carries citations as a diff; this is the single-add
+ * form.
+ */
+export declare function addCitation(ctx: BacklogCtx, input: IAddCitationInput): Promise<IOutcomeEnvelope<IAddCitationOutcome>>;
+/**
+ * Soft-remove one citation by the citation's OWN `uid` (never a
+ * `(target,line)` re-specification). Bi-temporally invalidates the citation
+ * node and its `has_citation` edge; the issue's uid is untouched.
+ */
+export declare function removeCitation(ctx: BacklogCtx, input: IRemoveCitationInput): Promise<IOutcomeEnvelope<IRemoveCitationOutcome>>;
 /** Move an issue to a new status, recording the transition in its audit trail. */
 export declare function transition(ctx: BacklogCtx, input: ITransitionInput): Promise<IOutcomeEnvelope<ITransitionOutcome>>;
+/**
+ * Create a first-class attestation — a separate record keyed to an issue by
+ * `{id, revision}`, never written into the issue. The subject's `uid` and
+ * revision are unchanged.
+ */
+export declare function attest(ctx: BacklogCtx, input: IAttestInput): Promise<IOutcomeEnvelope<IAttestOutcome>>;
+/**
+ * Re-run an attestation's anchor ladder and APPEND the new check to its
+ * append-only `checks[]` history (never overwriting earlier checks).
+ */
+export declare function recheck(ctx: BacklogCtx, input: IRecheckInput): Promise<IOutcomeEnvelope<IRecheckOutcome>>;
+/**
+ * Declare a typed requirement on an issue.
+ *
+ * The requirement is drawn from a closed predicate core
+ * (`evidence`/`blockers_terminal`/`relation`/`all_of`/`any_of`/`not`);
+ * `applies_to.to` is required. Nothing is evaluated here — the C5 gate reads
+ * it at a transition and the C6 verdict predicts it on read.
+ */
+export declare function obligate(ctx: BacklogCtx, input: IObligateInput): Promise<IOutcomeEnvelope<IObligateOutcome>>;
+/** Retire an obligation (bi-temporal; never a hard delete). */
+export declare function unobligate(ctx: BacklogCtx, input: IUnobligateInput): Promise<IOutcomeEnvelope<IUnobligateOutcome>>;
+/**
+ * Append a spec REVISION to a ticket (C10, DESIGN §12). A work product is a
+ * revision of its ticket: this mints a NEW immutable `SPEC` node holding the
+ * fragment and advances the ticket's `meta.spec_revision` pointer IN PLACE —
+ * the ticket's uid is preserved and no prior revision is rewritten. The
+ * required `base_revision` is a CAS token: a stale value is refused with
+ * `precondition_failed` and nothing is written.
+ */
+export declare function specAppend(ctx: BacklogCtx, input: ISpecAppendInput): Promise<IOutcomeEnvelope<ISpecAppendOutcome>>;
+/**
+ * Check whether a spec-revision `token` is still current for a ticket (C10).
+ * An ABSENT token is `stale` (`method:'none'`, `reason:'no-token-supplied'`),
+ * never `fresh`.
+ */
+export declare function specCheck(ctx: BacklogCtx, input: ISpecCheckInput): Promise<IOutcomeEnvelope<ISpecCheckOutcome>>;
 /** Take, renew or release an exclusive working lease on an issue. */
 export declare function claim(ctx: BacklogCtx, input: IClaimInput): Promise<IOutcomeEnvelope<IClaimOutcome>>;
 /** Create or remove a typed relationship between two issues. */
@@ -180,6 +251,22 @@ export declare function upsertComponent(ctx: BacklogCtx, input: IUpsertComponent
 export declare function upsertLocation(ctx: BacklogCtx, input: IUpsertLocationInput): Promise<IOutcomeEnvelope<IUpsertLocationOutcome>>;
 /** Soft-remove a location by `uid`. */
 export declare function rmLocation(ctx: BacklogCtx, input: IRmLocationInput): Promise<IOutcomeEnvelope<IRmLocationOutcome>>;
+/**
+ * Merge duplicate project `fromUid` into the canonical survivor `toUid` (C1).
+ *
+ * One `BEGIN IMMEDIATE` transaction re-points every component the duplicate
+ * owned onto the survivor, soft-retires the duplicate with a one-hop
+ * `meta.redirectTo`, and audits. Idempotent on a repeat `(from,to)` call.
+ */
+export declare function mergeProject(ctx: BacklogCtx, input: IMergeProjectInput): Promise<IOutcomeEnvelope<IMergeProjectOutcome>>;
+/**
+ * Soft-retire a project by `uid` WITHOUT a survivor (C1): stamps `t_invalid`
+ * with a reason and audits; no `redirectTo` is written.
+ */
+export declare function rmProject(ctx: BacklogCtx, input: IRmProjectInput): Promise<IOutcomeEnvelope<{
+    uid: string;
+    retired: true;
+}>>;
 /**
  * SPEC §6.7 names this verb `delete` on every mount (`backlog_delete`,
  * `backlog delete`, `DELETE /issue`). `export async function delete` is a