/knowledge-claim-consolidation

name: knowledge-claim-consolidation
description: Review and consolidate Knowledge claims over a chosen scope - the unlinked residue after relinking, the claims on one hub or over-budget page, or the claims about one subject since a date. File claims on their most specific subject page, create pages for substantial subjects, retire duplicates, supersede status snapshots and replaced claims by an existing claim, and fold durable outcomes into page State. Use for claim cleanup, consolidation, or the Knowledge Consolidation scribe.

Claim consolidation review

Read [shared conventions](references/conventions.md) and [publication](references/publication.md) before writes.

Claims accumulate faster than pages are curated. `knowledge_remember` saves a claim without a subject page when no name in it matches exactly one page, and scheduled maintenance's `knowledge_relink` links only claims whose source page is an entity page or whose text names exactly one page. Linked claims pile up too: a hub page collects status snapshots, duplicates and claims that belong on a more specific subject. This review runs one procedure over a chosen scope. Work in this order: choose the scope, link, then duplicates, replaced claims and snapshot series, then page prose.

1. Choose the scope and enumerate it

Call `knowledge_status` for the intended scope and `knowledge_ontology` for the current fingerprint. Then enumerate exactly one starting set:

• **Unlinked residue** (the default, and the only scope of scribe runs). Run

`knowledge_relink` without `dryRun` first so every remembered claim it can link is linked. Then list the residue with `knowledge_relink` `dryRun: true`, `include: "all"` and `limit: 10`, following `nextCursor`: every current claim with no linked page and no source page, whichever tool saved it. Each call reports at most 10 examples per outcome, so a limit of 10 returns every claim it examined.

• **One page**, for a hub page or a page over its size budget. List its

current claims with `knowledge_connections` `id`, `direction: "claims"`, `view: "full"` and `includeCards: true`, following `nextOffset` with the same filters. Restart when `snapshot` changes. On a hub, group from the cards first and work one group at a time; do not read every claim in full up front.

• **One subject, optionally since a date.** When the subject has a page, list

its claims with `knowledge_timeline` `entity`, `timeField: "recorded_at"` and `since`, following `nextOffset`. Also search for claims filed elsewhere or unlinked with `knowledge_grep` `kind: "claim"`, the subject's distinctive names (a PR number, a commit SHA, a feature name) and the same `since`/`timeField`. Keep only claims that are actually about the subject.

State the scope in the report. Read each claim you will change with `knowledge_record` and `metadataView: "full"`. Its `subject_hint`, when present, is the saver's own description of what the claim is about and the strongest clue to its subject. Group the claims by what they are about (one feature, PR, commit, decision thread, person or preference) before choosing pages. Most claims make sense only next to their neighbours: a series of status snapshots about one PR usually ends in an outcome claim.

2. Choose subject pages

For each group, find candidate pages with `knowledge_grep` and `knowledge_lookup`, and read their State. Ignore withdrawn pages and fixture pages.

• The **primary subject** is what the claim asserts something about; list it

first in `entities`. Add a secondary subject only when the claim also states something about that entity, such as the person who made the decision or the company whose product was configured. A passing mention is not a subject. Two or three subjects is usually enough.

• The primary subject is the **most specific** page the claim is about: a

claim about one PR belongs on that PR's page, not only on the project the PR belongs to. The broader page stays a subject only when the claim says something about it, such as a project-level decision, policy or release.

• A preference or decision stated by a person belongs on that person's page.

Do not turn one person's preference into a project or company policy.

• Match identity on evidence, not on similar names. When a claim names something

that might be an existing page (for example a product name that could be a different service), confirm it from evidence such as configuration, a URL or the page's own aliases. If it stays uncertain, leave the claim where it is and report it.

Link with `knowledge_annotate` `entities`, passing the complete list (it replaces the existing one) and the claim's current revision and hash. Assertion text, evidence and lifecycle stay unchanged. Link a claim before you supersede it: superseded claims cannot be relinked.

3. Create missing pages and relink to them

Linking every claim to the nearest existing page can bury a real subject in a broad page. Create a page when:

• a discrete subject (a feature, project, tool or substantial PR) has roughly

five or more claims, or has its own design, proof and outcome history; or

• a person or organisation authored, owns or decided something in the claims,

has no page, and has identity evidence (for example the PR author shown by `gh pr view`).

Do not create a page for a single mention or a one-off fix that a dated claim covers. Use `knowledge_save_page` with the ontology `type`, aliases, and the identity evidence as `source`. Person pages use `identity.status: partial` unless the identity is fully established. Write a short State that cites the claims; its Timeline is derived from them. Link the new page from its parent page.

Then relink the group's claims, including the snapshots step 4 will supersede. The new page becomes each claim's primary subject. Keep the broad page the claims were filed on (often the hub this review started from) only for claims that say something abo