kibi-cli 0.16.1 → 0.18.1

package/src/public/skills/kibi-usage/resources/logic-ir.md

@@ -0,0 +1,43 @@
+# Typed Logic IR and Proposition Coverage
+
+Kibi stores human prose as readable requirement text, but verifiable meaning belongs in typed facts and `kibi.logic.v1` rule facts. The host agent may propose an interpretation; Kibi validates, canonicalizes, hashes, persists, and reasons over it. Never submit a Prolog source string, goal, module, or function symbol. Rendered Prolog is an inspection preview only.
+
+## Two-pass extraction
+
+1. Run `kb_semantic_advisor` over the complete text. Supply explicit `clauses` when sentence splitting could hide a condition, exception, definition, descriptive assertion, threshold, quantity, or temporal qualifier.
+2. Audit the returned `propositions` against the original UTF-8 text. Every assertive span must be `modeled`, `ambiguous`, `ontology_gap`, or `missing`; rationale, examples, and subjective commentary are `nonlogical` and remain readable prose.
+3. For each assertive proposition, submit up to three typed `interpretations` when alternatives are plausible. Kibi compares canonical semantic keys; materially different valid interpretations remain unresolved regardless of confidence.
+4. Apply only a validated plan, then read back the requirement, rule schema, rule fact, and all relationship targets. Run `rule-safety`, `rule-verifiability`, `semantic-completeness`, `logic-coverage`, and `domain-contradictions` before the final unfiltered check.
+
+When a project-local schema names several ordered arguments, those arguments are facets of one relation, not separate propositions. Preserve the advisor claim key for the complete relation and do not manufacture clauses for each argument. Supporting `predicate_schema` facts carry the declared signature only; the ground predicate fact carries the claim provenance. Apply the exact `kb_suggest_predicates`/`kb_model_requirement` plan, reducing a rejected schema payload through `kb_validate_upsert` rather than silently downgrading a fitting declared relation to an observation.
+
+## Logic IR shape
+
+The supported v1 forms are:
+
+- `kind: atom` with a ground `head`;
+- `kind: rule` with a range-restricted `head` and `body`;
+- `kind: constraint` with a body and no head.
+
+Terms are typed `const`, `var`, `number`, `duration`, or ISO `timestamp`. Variables are explicitly declared as `forall` (the default) or body-local `exists`; an existential variable may not occur in a rule head. Bodies use `all`, `any`, closed-world `not`, comparisons, bounded `count`, and bounded temporal expressions. Modalities are `assert`, `deny`, `oblige`, `permit`, and `forbid`.
+
+Every head and body variable must be bound by a positive atom. Negation is allowed only on an atom with `closedWorld: true`, and only when its variables are also positively bound. Function symbols, raw goals, cuts, meta-calls, dynamic predicates, I/O, unbounded aggregation, unsafe variables, and unstratified negation are rejected before persistence.
+
+Example (inspection data, not executable input):
+
+```json
+{
+  "version": "kibi.logic.v1",
+  "kind": "rule",
+  "modality": "oblige",
+  "variables": [{"name": "U", "type": "user", "quantifier": "forall"}],
+  "head": {"kind": "atom", "name": "audit", "args": [{"kind": "var", "name": "U", "type": "user"}]},
+  "body": {"kind": "atom", "name": "admin_action", "args": [{"kind": "var", "name": "U", "type": "user"}]}
+}
+```
+
+Use `rule_schema` facts for stable predicate signatures and link a requirement to a `rule` fact with `requires_rule`. Keep `logic_claims` as the exact current assertive key set; `semantic_inventory` is the complete proposition ledger, anchored by `semantic_inventory_version`, `semantic_source_field`, and `semantic_source_hash`. Prefer requirement-only `semantic_text` as the semantic source for normalized authored prose so `text_ref` can remain independent code or document evidence; retain `text_ref` and `title` only as legacy semantic-source choices. A manifest is not proof until each modeled key is linked to exactly one same-key fact and the rule checks pass.
+
+## Contradictions and uncertainty
+
+Kibi compares opposing modalities over matching heads and overlapping authority, scope, and validity intervals. `assert`/`deny`, `oblige`/`forbid`, and overlapping `permit`/`forbid` pairs can be contradictory. Different conditions, unresolved interpretations, unsupported ontology terms, analysis limits, and incomplete closure produce `unresolved`, never a false consistency proof. Preserve superseding requirements rather than deleting historical claims.

package/src/public/skills/kibi-usage/resources/operation-access.md

@@ -2,26 +2,26 @@
 
 This table is the machine-readable interface map for Kibi's shared operation catalog. Every CLI route shown is dedicated; there is no generic operation runner. `--input JSON or flags` means the route supports exact MCP-shaped JSON from a file or stdin as well as its established human flags. `--input JSON` means the dedicated parity route is JSON-only.
 
-| MCP tool name | CLI route | Input mode | Mutability | Requires Prolog | Effects | Capability preference |
+| MCP tool name | CLI route | Input mode | Mutability | Requires Prolog | Effects | Interface |
 |---|---|---|---|---|---|---|
-| `kb_skills_list` | `skills-list` | `--input JSON` | read | no | `local-read` | MCP-first; CLI-fallback |
-| `kb_skills_load` | `skills-load` | `--input JSON` | read | no | `local-read` | MCP-first; CLI-fallback |
-| `kb_skills_read` | `skills-read` | `--input JSON` | read | no | `local-read` | MCP-first; CLI-fallback |
-| `kb_query` | `query` | `--input JSON or flags` | read | yes | `kb-read` | MCP-first; CLI-fallback |
-| `kb_search` | `search` | `--input JSON or flags` | read | yes | `kb-read` | MCP-first; CLI-fallback |
-| `kb_status` | `status` | `--input JSON or flags` | read | yes | `kb-read, workspace-read` | MCP-first; CLI-fallback |
-| `kb_find_gaps` | `find-gaps` | `--input JSON or flags` | read | yes | `kb-read` | MCP-first; CLI-fallback |
-| `kb_coverage` | `coverage` | `--input JSON or flags` | read | yes | `kb-read` | MCP-first; CLI-fallback |
-| `kb_graph` | `graph` | `--input JSON or flags` | read | yes | `kb-read` | MCP-first; CLI-fallback |
-| `kb_semantic_advisor` | `semantic-advisor` | `--input JSON` | read | no | `local-read` | MCP-first; CLI-fallback |
-| `kb_model_requirement` | `model-requirement` | `--input JSON` | read | yes | `kb-read` | MCP-first; CLI-fallback |
-| `kb_suggest_predicates` | `suggest-predicates` | `--input JSON` | read | yes | `kb-read` | MCP-first; CLI-fallback |
-| `kb_autopilot_generate` | `autopilot-generate` | `--input JSON` | read | no | `workspace-read` | MCP-first; CLI-fallback |
-| `kb_validate_upsert` | `validate-upsert` | `--input JSON` | read | yes | `kb-read` | MCP-first; CLI-fallback |
-| `kb_upsert` | `upsert` | `--input JSON` | write | yes | `kb-write, workspace-write` | MCP-first; CLI-fallback |
-| `kb_delete` | `delete` | `--input JSON` | write | yes | `kb-write, workspace-write` | MCP-first; CLI-fallback |
-| `kb_check` | `check` | `--input JSON or flags` | read | yes | `kb-read, workspace-read` | MCP-first; CLI-fallback |
-| `kb_sparql_remote` | `sparql-remote` | `--input JSON` | read | no | `network-read` | MCP-first; CLI-fallback |
+| `kb_skills_list` | `skills-list` | `--input JSON` | read | no | `local-read` | peer; capability-selected |
+| `kb_skills_load` | `skills-load` | `--input JSON` | read | no | `local-read` | peer; capability-selected |
+| `kb_skills_read` | `skills-read` | `--input JSON` | read | no | `local-read` | peer; capability-selected |
+| `kb_query` | `query` | `--input JSON or flags` | read | yes | `kb-read` | peer; capability-selected |
+| `kb_search` | `search` | `--input JSON or flags` | read | yes | `kb-read` | peer; capability-selected |
+| `kb_status` | `status` | `--input JSON or flags` | read | yes | `kb-read, workspace-read` | peer; capability-selected |
+| `kb_find_gaps` | `find-gaps` | `--input JSON or flags` | read | yes | `kb-read` | peer; capability-selected |
+| `kb_coverage` | `coverage` | `--input JSON or flags` | read | yes | `kb-read` | peer; capability-selected |
+| `kb_graph` | `graph` | `--input JSON or flags` | read | yes | `kb-read` | peer; capability-selected |
+| `kb_semantic_advisor` | `semantic-advisor` | `--input JSON` | read | no | `local-read` | peer; capability-selected |
+| `kb_model_requirement` | `model-requirement` | `--input JSON` | read | yes | `kb-read` | peer; capability-selected |
+| `kb_suggest_predicates` | `suggest-predicates` | `--input JSON` | read | yes | `kb-read` | peer; capability-selected |
+| `kb_autopilot_generate` | `autopilot-generate` | `--input JSON` | read | no | `workspace-read` | peer; capability-selected |
+| `kb_validate_upsert` | `validate-upsert` | `--input JSON` | read | yes | `kb-read` | peer; capability-selected |
+| `kb_upsert` | `upsert` | `--input JSON` | write | yes | `kb-write, workspace-write` | peer; capability-selected |
+| `kb_delete` | `delete` | `--input JSON` | write | yes | `kb-write, workspace-write` | peer; capability-selected |
+| `kb_check` | `check` | `--input JSON or flags` | read | yes | `kb-read, workspace-read` | peer; capability-selected |
+| `kb_sparql_remote` | `sparql-remote` | `--input JSON` | read | no | `network-read` | peer; capability-selected |
 
 ## JSON execution recipes
 

package/src/public/skills/kibi-usage/resources/ui-requirements.md

@@ -0,0 +1,96 @@
+# UI / Visual Requirement Modeling
+
+Optional, per-project lane for recording what the screen should look like so UI edits cannot
+silently drift from the spec. Non-UI projects skip it entirely; no check rule requires it.
+
+## Three layers
+
+1. **Prose `req`** — the full on-screen description lives in the requirement body as the
+   searchable anchor agents discover with `kb_search` / `kb_query`.
+2. **Strict facts** — checkable visual invariants as `fact_kind: subject` (`subject_key`,
+   linked `constrains`) plus `fact_kind: property_value` (`property_key`, `operator`, typed
+   `value_*`, linked `requires_property`). Incompatible values on the same subject/property
+   from two current requirements are rejected on write unless `supersedes`.
+3. **Relational predicates** — ground `fact_kind: predicate` linked with `requires_predicate`.
+   The built-in `visual_layout_rule(subject, relation, target)` covers "X must remain visually
+   aligned with Y" (relation `aligned_with`). Other relational layout claims need a
+   project-local `predicate_schema` when the task authorizes ontology extension.
+
+Kibi enforces stated facts and links, not pixels. Freeform spatial prose is stored and
+searchable but is not machine-checked.
+
+## Button position
+
+```yaml
+id: FACT-UI-SUBMIT-REGION
+fact_kind: subject
+subject_key: settings.screen.submit_button
+```
+
+```yaml
+id: FACT-UI-SUBMIT-POSITION
+fact_kind: property_value
+subject_key: settings.screen.submit_button
+property_key: position
+operator: eq
+value_type: string
+value_string: bottom_right
+canonical_key: settings.screen.submit_button.position.eq.bottom_right
+```
+
+Link both facts from the requirement:
+
+```yaml
+id: REQ-UI-SETTINGS
+relationships:
+  - type: constrains
+    from: REQ-UI-SETTINGS
+    to: FACT-UI-SUBMIT-REGION
+  - type: requires_property
+    from: REQ-UI-SETTINGS
+    to: FACT-UI-SUBMIT-POSITION
+```
+
+A later requirement writing `position: top_left` on the same subject is rejected on write.
+
+## Header item order
+
+Use one indexed `property_key` per slot against the same subject region:
+`nav_order_1: home`, `nav_order_2: search`, `nav_order_3: profile`, each as a separate
+`property_value` fact linked with `requires_property`. This makes each slot independently
+contradiction-checkable.
+
+## Relational alignment
+
+```yaml
+id: FACT-UI-NAV-ALIGN
+fact_kind: predicate
+predicate_name: visual_layout_rule
+predicate_args: [navigation_rail, aligned_with, header]
+polarity: assert
+canonical_key: visual_layout_rule(navigation_rail,aligned_with,header)
+```
+
+Link with `requires_predicate`. An `assert`/`deny` pair over the same predicate namespace,
+name, and ordered arguments is a blocking `domain-contradictions` conflict.
+
+## UI component traceability
+
+Model the component as a `symbol` with `sourceFile` and `symbol_role: behavioral`, linked
+`implements` to the requirement, so component edits surface the visual spec in impact
+diagnostics (`symbol_semantic_review_needed`).
+
+## Workflow
+
+1. `kb_semantic_advisor` on the full description; audit or supply `clauses`.
+2. Relational clauses: `kb_suggest_predicates`, apply the predicate plan and
+   `requires_predicate`.
+3. Scalar placement/alignment/order clauses: `kb_model_requirement`, apply the strict
+   subject/property plan and `constrains` / `requires_property`.
+4. Preserve `claim_key` / `claim_text`; merge every key into the requirement
+   `logic_claims` manifest.
+5. `kb_validate_upsert`, create endpoints first, then sequential `kb_upsert`.
+6. `kb_check` with `logic-coverage`, `predicate-verifiability`, `domain-contradictions`,
+   then a final unfiltered `kb_check`.
+
+Non-UI projects: declare `has_ui: false` during bootstrap and no UI entities are proposed.

package/src/public/skills/kibi-usage/resources/workflows.md

@@ -8,13 +8,20 @@ The canonical workflow for any KB operation follows this pattern:
 2. **Confirm**: `kb_query` for exact IDs and state
 3. **Inspect**: `kb_status` when freshness matters
 4. **Decompose**: `kb_semantic_advisor` on the complete normative prose; verify or supply every atomic clause
-5. **Choose per-clause lanes**: `kb_suggest_predicates` for relational clauses; `kb_model_requirement` for strict scalar clauses; observation review for ambiguity, false positives, and ontology gaps
+5. **Choose per-clause lanes**: strict facts for scalar claims; `kb_suggest_predicates` for approved ground ontology relations; `kb_model_requirement` with `kibi.logic.v1` for conditions, exceptions, modalities, quantifiers, cardinality, and bounded temporal rules; observation review for ambiguity, nonlogical prose, and ontology gaps
 6. **Preflight**: `kb_validate_upsert` for every intended entity or relationship payload
 7. **Create endpoints**: validated `kb_upsert` for new entities, sequentially
-8. **Link**: validated `kb_upsert` with `requires_predicate`, `constrains`, or `requires_property`, sequentially
-9. **Validate coverage and consistency**: targeted `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then final full `kb_check`
+8. **Link**: validated `kb_upsert` with `requires_rule`, `requires_predicate`, `constrains`, or `requires_property`, sequentially
+9. **Validate coverage and consistency**: targeted `rule-safety`, `rule-verifiability`, `semantic-completeness`, `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then final full `kb_check`
+10. **Prove execution**: read `kb_status.verificationSnapshot`, run each scenario-backed E2E command, append its `kibi.verification-receipt.v1`, and re-run `kb_coverage`; never promote durable test status into fresh evidence
+11. **Repair incrementally**: require `kb_coverage.repairPlan.scope.complete`, apply only one `ready` dependency batch per requirement, validate before every sequential write, and rerun coverage before selecting the next batch
+12. **Gate workflow evidence**: when `.kb/usage.log` exists, run `kibi usage-metrics --format json --require-acceptance`; repair ranked telemetry diagnostics and never treat stale or insufficient evidence as a pass
 
-Every current requirement without `logic_claims` remains visible as non-blocking backfill debt. Once a manifest exists, the default unfiltered check enforces its correspondence to linked ground facts.
+Every current requirement without `logic_claims` remains visible as non-blocking backfill debt. Once a manifest and `semantic_inventory` exist, the unfiltered check enforces correspondence to linked ground facts/rules and rejects silently missing assertive propositions.
+
+`kibi.repair-plan.v1` is a deterministic read-only plan, not a mutation script. Its phase order keeps source and proposition analysis ahead of ground endpoints, endpoints ahead of manifests/links, logic ahead of contradictions, scenarios ahead of tests and receipts, and production ownership ahead of coverage and coordinate refresh. A `blocked` batch is waiting on every listed `dependsOn` batch. If pagination makes the plan partial, increase the requirement coverage limit rather than applying an incomplete project view.
+
+`kibi.telemetry-acceptance.v1` evaluates the latest 200 usage events and keeps process health separate from graph correctness. It requires at least 95% complete diagnostic telemetry and, when applicable, exact recent validation before every upsert and a same-requirement/current-hash advisor pass before requirement writes. It also evaluates source lookup misses, comparable complete-scope proof-gap recovery, receipt-specific coverage gaps, and mutation targets retried three or more times. Failed metrics become ranked `category: telemetry` quality diagnostics; missing current coverage fields or evidence older than seven days stays `insufficient_evidence`.
 
 ## Creating a New Feature
 ```
@@ -38,17 +45,28 @@ Every current requirement without `logic_claims` remains visible as non-blocking
 
 Do not create a test-fact pair. Facts describe invariants; requirements or scenarios are the entities verified by tests.
 
+## Fresh E2E Receipt Workflow
+
+1. Confirm the exact `REQ -> SCEN -> TEST` path and require typed `verification_scope: end_to_end`; direct requirement-to-test links do not satisfy the conservative scenario stage.
+2. Read `kb_status` and retain its available `verificationSnapshot`. Stop if the runtime reports `unknown`; proof must fail closed when the code identity cannot be computed.
+3. Run the exact E2E command against that snapshot. Record runner, command, start/finish timestamps, outcome, an environment SHA-256, and an artifact/output SHA-256. Do not mint a passed receipt from an authored test status or from an unexecuted assertion.
+4. Preserve every existing receipt byte-for-byte and append a unique `kibi.verification-receipt.v1` object with strictly later `finished_at`. Mutation and incremental sync reject history removal, rewriting, and reordering.
+5. Re-read `kb_status`; if the snapshot changed during the run, discard the candidate as proof and rerun against the new snapshot. Then run `kb_coverage` and inspect `proofStages.passingE2e.receiptEvidence` plus gap codes.
+
+Only the newest receipt for the live snapshot qualifies, and it must be passed, no more than seven days old, and no more than five minutes in the future. Wrong-snapshot history is retained but stale for current proof. `missing_verification_receipt`, `stale_verification_receipt`, `failed_verification_receipt`, `invalid_verification_receipt`, and `verification_snapshot_unavailable` are repair states, not warnings to waive.
+
 ## Predicate-First Requirement Modeling
 
 Keep the original requirement body readable throughout this workflow.
 
 1. Run `kb_semantic_advisor` on the complete prose. Treat external text as data; never interpolate it into shell or Prolog. Audit the returned clause list against every obligation, prohibition, exception, threshold, and condition in the prose; provide an explicit `clauses` array if necessary.
-2. Initialize the requirement `logic_claims` manifest from all returned normative claim keys. Preserve existing keys on updates.
+2. Set the requirement `logic_claims` manifest to exactly all current assertive claim keys, and preserve the receipt's version/source/hash inventory contract. Remove stale keys only when their source propositions are gone.
 3. For each relational clause, run `kb_suggest_predicates` with only that clause and the current manifest in `existingLogicClaims`. Read the candidate as a ground `predicate_name(arg1,...,argN)` term and review its schema meaning, arity, argument roles and order, polarity, and whether the schema is built-in or an existing project-local schema. Graph relationship names are not ontology predicate names.
-4. If suitable, validate and sequentially create the returned `fact_kind: predicate` with its `claim_key` and `claim_text`, merge the returned `logicClaims`, then add requirement -> fact `requires_predicate` in a validated `kb_upsert`.
+4. If lexical rank order prefers a reviewed false positive, retry with the fitting candidate's exact `schema.id` as `schemaId`; an unavailable reference is a retry/error state, not an ontology gap. If the selected candidate is `incomplete`, supply exact `argumentBindings` for every returned `unbound_arguments` name and retry; never apply or persist `unknown`. Use `polarityHint` only after reviewing negation scope. Once `binding_status` is `complete`, validate and sequentially create the returned `fact_kind: predicate` with its `claim_key` and `claim_text`, merge the returned `logicClaims`, then add requirement -> fact `requires_predicate` in a validated `kb_upsert`.
 5. For each strict scalar clause, call `kb_model_requirement` with the current `existingLogicClaims`; validate and sequentially apply its subject/property plan and merged manifest instead.
-6. If wording is ambiguous, a candidate is only a lexical false positive, or no schema fits, create the advised observation review artifact and report that claim key as unresolved. Use `review:ontology-gap` only for a true catalog gap. Define a new `predicate_schema` only when the task explicitly authorizes ontology extension and provides a stable signature.
-7. Read back the requirement and all facts. Confirm every manifest key occurs on exactly one intended ground fact, no punctuation variant minted a second claim, and no two claim keys encode the same logical term. Exact query output may represent repeated relationship types as arrays, so inspect every target. Then run `kb_check` with `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`. Finish with an unfiltered `kb_check`.
+6. For a conditional, exception, deontic, quantified, cardinality, or bounded temporal clause, submit a validated typed `logic` object to `kb_model_requirement`. Apply its `rule_schema` and `rule` facts sequentially and link the requirement with `requires_rule`; rendered Prolog is for inspection only.
+7. If wording is ambiguous, a candidate is only a lexical false positive, or no schema/IR interpretation fits, create the advised observation review artifact and apply its returned `relates_to` review anchor when present; report that claim key as unresolved. Use `review:ambiguity` for unresolved interpretation, `review:keyword-false-positive` for a vocabulary match that is not a domain assertion, and `review:ontology-gap` only for a true catalog gap. Define a new `predicate_schema` only when the task explicitly authorizes ontology extension and provides a stable signature.
+8. Read back the requirement, proposition ledger, and all facts. Confirm every manifest key occurs on exactly one intended ground fact/rule, no punctuation variant minted a second claim, and no two claim keys encode the same logical term. Exact query output may represent repeated relationship types as arrays, so inspect every target. Then run `kb_check` with `rule-safety`, `rule-verifiability`, `semantic-completeness`, `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`. Finish with an unfiltered `kb_check`.
 
 Do not treat the manifest itself as proof of grounding. The advisor keeps readiness partial while there are fewer logical edge slots than normative claims; final readback and `logic-coverage` bind those slots to exact claim keys and ground terms.
 
@@ -56,6 +74,20 @@ Examples: built-in permission and deny claims use the suggested `permission_rule
 
 On resume after interruption, repeat `kb_query` for exact endpoints and apply only missing validated writes. Keep `kb_upsert` concurrency at one.
 
+## UI / Visual Requirement Modeling
+
+Optional per-project workflow for recording what the screen should look like. Non-UI projects skip this lane entirely.
+
+1. Create a prose `req` holding the full visual description; it is the searchable anchor agents discover before touching a UI file.
+2. Run `kb_semantic_advisor` on the description; audit or supply `clauses`.
+3. For relational layout clauses ("X must remain visually aligned with Y"), call `kb_suggest_predicates`, apply the returned `fact_kind: predicate` plan with `predicate_name: visual_layout_rule` and `requires_predicate`.
+4. For scalar placement, alignment, and ordering clauses, call `kb_model_requirement` and apply strict `fact_kind: subject` / `fact_kind: property_value` facts linked with `constrains` / `requires_property`. Model header order as indexed property keys (`nav_order_1`, `nav_order_2`, ...) against one subject region.
+5. Preserve `claim_key` / `claim_text` on every ground fact and merge every key into the requirement `logic_claims` manifest.
+6. Model UI components as `symbol` entities with `sourceFile` and `symbol_role: behavioral`, linked `implements` to the requirement.
+7. `kb_validate_upsert`, create endpoints first, then sequential `kb_upsert`. Run `kb_check` with `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then a final unfiltered `kb_check`.
+
+Incompatible values on the same subject/property from two current requirements are rejected on write; change an intentional value via a replacement requirement linked with `supersedes`. Full payloads are in `resources/ui-requirements.md`.
+
 ## Fixing a Traceability Gap
 ```
 1. kb_query --sourceFile <code-file> to find linked entities

package/src/public/symbol-granularity.ts

@@ -27,6 +27,22 @@ export const ALLOWED_GRANULARITY_REASONS = [
 
 export type GranularityReason = (typeof ALLOWED_GRANULARITY_REASONS)[number];
 
+/**
+ * Granularity reasons that document coarse file/module-level coverage for which
+ * generated per-symbol coordinates are not expected. These anchors legitimately
+ * carry no coordinate artifact entries. `legacy-link` is intentionally excluded:
+ * it is a canonical reason but still coordinates a real extractable symbol.
+ */
+export const COARSE_GRANULARITY_REASONS = [
+  "config-artifact",
+  "module-level-behavior",
+  "extractor-miss",
+  "test-suite",
+] as const;
+
+export type CoarseGranularityReason =
+  (typeof COARSE_GRANULARITY_REASONS)[number];
+
 export type SymbolKind =
   | "function"
   | "class"
@@ -53,6 +69,9 @@ const traceabilityRelationshipTypeSet: ReadonlySet<string> = new Set(
 const allowedGranularityReasonSet: ReadonlySet<string> = new Set(
   ALLOWED_GRANULARITY_REASONS,
 );
+const coarseGranularityReasonSet: ReadonlySet<string> = new Set(
+  COARSE_GRANULARITY_REASONS,
+);
 
 export function inferSymbolRole(kind: SymbolKind): SymbolRole {
   switch (kind) {
@@ -94,6 +113,12 @@ export function isAllowedGranularityReason(
   return typeof value === "string" && allowedGranularityReasonSet.has(value);
 }
 
+export function isCoarseGranularityReason(
+  value: unknown,
+): value is CoarseGranularityReason {
+  return typeof value === "string" && coarseGranularityReasonSet.has(value);
+}
+
 export function getSymbolRole(candidate: GranularSymbolCandidate): SymbolRole {
   if (candidate.role) return candidate.role;
   if (candidate.kind) return inferSymbolRole(candidate.kind);