@gobing-ai/spur 0.3.40 → 0.3.42

package/plugins/sp/skills/conflict-finding/references/comparison-protocol.md

@@ -0,0 +1,277 @@
+---
+name: comparison-protocol
+description: "Four-pillar inventory, candidate graph construction, within-pillar and cross-pillar audit protocol, and token/cost controls for sp:conflict-finding."
+see_also:
+  - conflict-finding
+  - spur-cli
+  - spur-dev
+  - doc-evolve
+  - code-verification
+---
+
+# Comparison protocol — inventories, subject clustering, and token controls
+
+This file is the SSOT for **Design §4 steps 4–8** of task 0486 (inventory → candidate graph →
+within-pillar audit → cross-pillar audit → classify-and-challenge) and **Design §6** (token and cost
+controls), satisfying Requirements **R4** (cross-pillar comparison with reproducible anchors and no
+all-pairs explosion) and **R5** (honest, token-aware scan protocol with freshness-verifiable context
+reuse). Authority reasoning itself lives in
+[authority-resolution.md](authority-resolution.md); finding shapes and evidence rules live in
+[finding-contract.md](finding-contract.md); repair routing lives in
+[remediation-routing.md](remediation-routing.md). Skill entry point: [../SKILL.md](../SKILL.md).
+
+**Governing principle:** the audit is _subject- and claim-driven_, never _text-driven_ and never
+_file-vs-file_. The hard problem is deciding which artifacts are semantically related to the same
+subject + claim type, then comparing only those — not computing a similarity over every pair in the
+corpus.
+
+## Four-pillar inventory (Design §4 step 4)
+
+Discovery materializes an **inventory** of exactly the selected pillars. Every inventory entry is a
+row with six mandatory fields. An entry records **what was found and how fresh it is** — absence of
+an _optional_ file is a reported fact, not an error, but a _selected_ pillar that produced no
+entries is never silently dropped.
+
+| Pillar      | Identity                                                     | Path                          | Anchor                               | Provenance / freshness                  | Scan status                       |
+| ----------- | ------------------------------------------------------------ | ----------------------------- | ------------------------------------ | --------------------------------------- | --------------------------------- |
+| `source`    | module / symbol / command / flag / DTO / schema / config key | repo-relative file            | symbol, heading, line, command name  | git commit/date, blame, change cone     | `scanned` / `sampled` / `skipped` |
+| `tasks`     | WBS id, task file id                                         | `docs/tasks3/<wbs>_<slug>.md` | WBS number, Requirement/AC heading   | `git log` mtime, spur lifecycle verdict | `scanned` / `sampled` / `skipped` |
+| `features`  | feature id (e.g. `H11`)                                      | feature file path             | feature id, AC title, status section | git mtime, feature-tree status          | `scanned` / `sampled` / `skipped` |
+| `authority` | document id (e.g. `00_ADR`, `99_CONSTITUTION`)               | `AGENTS.md`, `docs/0*.md`     | heading, ADR entry, decision id      | git mtime, last-touched commit          | `scanned` / `sampled` / `skipped` |
+
+Rules:
+
+1. **Optional absence is reported, not fatal.** An authority set is `AGENTS.md`,
+   `docs/00_ADR.md`, `docs/01_PRD.md`, `docs/03_ARCHITECTURE.md`, `docs/04_DESIGN.md`,
+   `docs/05_FEATURES.md`, `docs/99_PROJECT_CONSTITUTION.md` _when present_. A missing optional file
+   yields an inventory row with scan status `absent` and does not block the audit.
+2. **A selected pillar is never silently omitted.** If `--pillar tasks` yields no entries, that is
+   itself a finding (an empty/absent pillar) with an explicit inventory row — never a gap in the
+   report.
+3. **Anchors must be stable and real.** Unavailable line numbers are replaced by a stable
+   structural anchor — heading, symbol, WBS number, feature id, command name, ADR entry. Anchors are
+   **never fabricated**: if no anchor is verifiable, the entry records `anchor: unavailable` with an
+   explicit note rather than inventing one.
+4. **Freshness is provenance, not presence.** Every entry carries how the fact was obtained (git
+   mtime, blame, `spur … --json`, `rg` hit line) so the reader can judge whether the entry can be
+   reused or must be re-read.
+
+## Building the candidate graph (Design §4 step 5)
+
+The candidate graph is the set of **semantically related subject pairs** to compare. It is built
+from _explicit_ links and _shared identifiers_ — never from an unbounded all-pairs comparison.
+
+Join keys, in priority order:
+
+| Key                        | Source → target                                              | Example                                              |
+| -------------------------- | ------------------------------------------------------------ | ---------------------------------------------------- |
+| Explicit links             | markdown links / cross-refs between artifacts                | task file links a feature id; doc cites an ADR entry |
+| WBS / feature ids          | `0486`, `H11`                                                | task ↔ task deps, feature tree rollup, doc scope     |
+| Dependencies               | declared deps in task/feature                                | task depends-on another task                         |
+| AC titles                  | acceptance-criteria titles shared between task/feature       | feature AC title repeated in task AC                 |
+| Paths                      | same file or dir referenced in multiple pillars              | `docs/04_DESIGN.md` mentioned in task Solution       |
+| Symbols / commands / flags | same symbol, command, flag name                              | `dev-find-conflict`, `--resolve`                     |
+| DTO / schema / config keys | same key name across config + source + docs                  | `--pillar`, a config field                           |
+| Normalized domain terms    | a normalized term (case/plural-insensitive) shared by claims | `authority`, `freshness`, `coverage`                 |
+
+Construction protocol:
+
+1. **Seed from scope.** If `<scope>` is a path/WBS/feature-id/symbol/command/config-key, seed the
+   graph with every artifact whose identity or content references that scope.
+2. **Grow by shared keys.** For each seed, add an edge to any artifact sharing one of the keys
+   above for the _same subject_. A key matches only when it refers to the same subject, not merely
+   the same string in an unrelated context (see normalize).
+3. **Normalize before matching.** Domain terms are matched after lowercasing and plural/case
+   folding (e.g. `AC`/`ac`, `WBS`/`wbs`); identifiers (`0486`, `H11`) and paths are matched
+   verbatim. Do not fuzzy-match identifiers.
+4. **Bound the graph.** The graph is the union of seed-reachable edges. Artifacts that share no key
+   and are not seed-reachable are excluded. **An unbounded all-pairs comparison is explicitly
+   forbidden** — if a scope would touch every artifact, that is a _coverage_ concern, not license to
+   compare everything.
+5. **Record edge provenance.** Each edge records which key(s) joined it so the candidate set is
+   reproducible (a reviewer can rerun the join and get the same pairs).
+
+## Within-pillar audit (Design §4 step 6)
+
+For each pillar, compare only claims that share a subject within the pillar.
+
+### Source code (`--pillar source`)
+
+| Claim cluster               | Compare                                                         | Conflict types       |
+| --------------------------- | --------------------------------------------------------------- | -------------------- |
+| contracts / implementations | exported signature vs body; interface vs impl                   | contradiction, stale |
+| tests                       | test expectation vs implementation                              | contradiction, stale |
+| config / registrations      | config key vs parser; registered command/flag vs parsed surface | omission, orphan     |
+| symbols / commands          | command wrapper vs its delegation target                        | stale, duplicate     |
+
+### Task files (`--pillar tasks`)
+
+| Claim cluster     | Compare                                                                       |
+| ----------------- | ----------------------------------------------------------------------------- |
+| requirements / AC | Requirement vs AC text; AC title vs body                                      |
+| dependencies      | declared dependency vs referenced WBS existing                                |
+| status / solution | `status` field vs what Solution/Testing describe; lifecycle verdict vs status |
+| orphans           | task whose parent feature is gone, or WBS referenced nowhere                  |
+
+### Feature files (`--pillar features`)
+
+| Claim cluster | Compare                                                       |
+| ------------- | ------------------------------------------------------------- |
+| hierarchy     | child feature id vs parent references                         |
+| AC / status   | AC titles vs status section; index projection vs actual files |
+| orphans       | feature referenced by no task and no doc                      |
+
+### Authority files (`--pillar authority`)
+
+| Claim cluster    | Compare                                      |
+| ---------------- | -------------------------------------------- |
+| ownership        | who owns a subject vs who is referenced      |
+| decision / scope | ADR decision vs its scope statement          |
+| process          | process rule vs referenced workflow/template |
+
+Within-pillar finding rules: a claim must have **at least two opposing anchors** for
+contradiction/stale. Low-confidence differences become candidates, never definitive conflicts (see
+[finding-contract.md](finding-contract.md)).
+
+## Cross-pillar audit (Design §4 step 7)
+
+Audit every boundary applicable to the selected scope. Default scope (`all`) audits all six:
+
+| Boundary            | What is compared                            | Typical conflict                                |
+| ------------------- | ------------------------------------------- | ----------------------------------------------- |
+| source ↔ task       | task AC/requirements vs implemented surface | stale projection (code shipped, task says todo) |
+| source ↔ feature    | feature AC vs shipped surface               | feature AC unmet or over-shipped                |
+| source ↔ authority  | authority "should" vs source "is"           | architecture/design doc vs module topology      |
+| task ↔ feature      | task AC/deps vs feature AC/status           | AC mismatch, orphan task                        |
+| task ↔ authority    | task obligation vs PRD/ADR scope            | task outside documented scope                   |
+| feature ↔ authority | feature goal vs PRD/ADR bounds              | feature contradicts PRD non-goal                |
+
+Per-boundary protocol:
+
+1. Restrict to candidate-graph edges that cross the two pillars.
+2. For each edge, resolve the **normative authority** and **observed reality** for the _subject +
+   claim type_ (authority matrix: [authority-resolution.md](authority-resolution.md)).
+3. Compare only **comparable** claims. Incomparable, missing, or ambiguous authority yields an
+   unresolved `needs-authority-decision` item — never a forced winner.
+4. Emit reproducible anchors from **both** sides (at least two opposing anchors for
+   contradiction/stale).
+
+## Classify and challenge (Design §4 step 8)
+
+Before asserting any candidate as a conflict, run the **four-challenge filter**. A candidate that
+survives all applicable challenges is a real finding; one explained by any challenge is not a
+conflict (or is a _different_ conflict type).
+
+| Challenge               | Question                                                                                              | If true                       |
+| ----------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------- |
+| Lifecycle               | Is the difference planned work (todo task/feature whose lifecycle says not-yet-done)?                 | Not a conflict — planned work |
+| Supersession            | Is one artifact superseded (accepted ADR beats derived doc; superseded ADR is historical)?            | Not a conflict — supersession |
+| Abstraction-level       | Is the difference merely a different level of abstraction (design doc generalizes, code specializes)? | Not a conflict                |
+| Intentional deprecation | Is one side explicitly marked deprecated / intentionally divergent?                                   | Not a conflict — intentional  |
+
+Rules:
+
+1. **Mere wording or abstraction-level difference is NOT a conflict.** Only
+   `contradiction`, `stale`, `duplicate`, `omission`, `orphan`, or `ambiguous-authority` supported by
+   evidence counts.
+2. **A todo task/feature differing from current code is planned work**, not stale code, unless its
+   lifecycle or supersession metadata says otherwise.
+3. **Challenge before classify, then classify exactly.** Run the challenges first; only survivors
+   get a conflict type and severity/confidence.
+4. **Never promote.** A low-confidence candidate stays a candidate or unresolved item; it is never
+   promoted to a definitive conflict (see [finding-contract.md](finding-contract.md)).
+5. **Every asserted finding names the challenge that failed** in its false-positive check, so the
+   reader sees why lifecycle/supersession/abstraction/deprecation did not excuse it.
+
+## Token and cost controls (Design §6)
+
+The audit is **token-aware**: it reads the minimum to be honest, and it reports what it did not
+read. It never claims comprehensiveness it cannot defend.
+
+### Read order (cheap first)
+
+1. **Authority rules and indexes first.** Read `AGENTS.md`, `docs/99_PROJECT_CONSTITUTION.md`, and
+   any reusable index (`.spur/context/anatomy.md`, task/feature metadata) before any full artifact.
+   These establish the claim-specific authority matrix and the candidate seed set without opening
+   bodies.
+2. **Deterministic discovery, batched.** Batch `git`, `rg`, `spur task/feature … --json`, relevant
+   `spur … check`, and `sp:doc-evolve` audit surfaces into as few calls as possible. Retain results
+   in a compact **in-memory evidence manifest** for the run — never persist it.
+
+   > **`rg` skips dot-directories and ignored paths by default.** A bare `rg <pattern> .` will not
+   > search `.spur/context/`, `.github/`, or anything matched by `.gitignore`, and returns **no
+   > hits** rather than an error — a silent false negative that reads exactly like a clean boundary.
+   > When the scan must cover indexed context, dotted config, or ignored trees, use `rg -uu`
+   > (or `--hidden --no-ignore`) and say which you used. A "no conflicts found" result produced by a
+   > default-scoped `rg` over a dotted path is not evidence of absence, and must not be reported as
+   > a cleared boundary.
+
+3. **Open full artifacts only for candidate subjects.** A file is read in full only when it is a
+   seed or a candidate-graph subject that survived the classify-challenge filter (or when coverage
+   demands it). Non-candidates are inventoried by metadata, not read.
+
+### Adaptive vs full mode
+
+| Mode                 | Behavior                                                                                                                                                                                                                                                       | Coverage guarantee                                                     |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `adaptive` (default) | Always scan the complete authority/task/feature metadata surfaces needed for traceability; narrow source reads to the Git change cone and linked symbols. Reuse `.spur/context/` **only** when freshness + provenance are verifiable against the current tree. | Disclosed change cone + skipped areas; `complete` only when defensible |
+| `full`               | Cold comprehensive scan; no reuse of indexed context; read every selected-pillar artifact needed to establish completeness.                                                                                                                                    | Intended `complete: true` unless a tool fails                          |
+
+Adaptive reuse decision:
+
+1. **Verify provenance.** The `.spur/context/` artifact must state its source tree (paths, commit,
+   or mtime) and that source must match the current tree.
+2. **Verify freshness.** Compare the artifact's recorded freshness against current git state. If any
+   authority/task/feature metadata it relies on is newer, the reused index is **stale**.
+3. **Verify the change cone.** In adaptive mode, always scan the full authority/task/feature
+   metadata surfaces; only _source_ reads are narrowed to the change cone. If the cone is empty or
+   unverifiable, escalate to the full source scan.
+4. **Degrade honestly.** Absent, stale, or unverifiable context → **cold full scan** **or** an
+   **explicit incomplete-coverage result**. Never silent omission. When links are missing, context
+   is stale, or coverage cannot be defended, escalate to the full scan.
+
+### Reporting cost and coverage
+
+The report (Markdown and `--json`) records:
+
+- **Files inspected / skipped** per pillar, with skip reasons.
+- **Claims inspected / skipped** (candidate edges examined vs left unexamined).
+- **Tokens** (estimated) consumed by reads.
+- **Change cone** (in adaptive mode): which paths were narrowed.
+- **Reused context**: which `.spur/context/` artifact, and the provenance/freshness evidence.
+- **`coverage.complete`**: `true` only when every selected pillar was scanned without a tool failure
+  that prevented coverage.
+
+Rules:
+
+1. **Do not claim "comprehensive" when `coverage.complete` is false.** If a tool failed, coverage is
+   degraded and reported in `errors` (tool failure is distinct from semantic uncertainty).
+2. **Tool failures are coverage evidence, not silence.** A failing `git`/`rg`/`spur` call is
+   recorded; the affected pillar's scan status is `skipped` with the reason, and `coverage.complete`
+   reflects it.
+3. **No hidden state.** Adaptive reuse is a read of an existing `.spur/context/` artifact; the audit
+   itself creates no persistent cache, database, vector index, embedding pipeline, background
+   daemon, or custom parser in v1. The in-memory evidence manifest dies with the run.
+
+## Anti-patterns and boundaries
+
+| Anti-pattern                                              | Correct behavior                                                |
+| --------------------------------------------------------- | --------------------------------------------------------------- |
+| Unbounded all-pairs comparison                            | Compare only candidate-graph edges joined by explicit keys      |
+| Asserting conflict from wording alone                     | Run the four-challenge filter; only evidence-backed types count |
+| Forcing ambiguous authority through a global ranking      | Emit unresolved `needs-authority-decision` HITL item            |
+| Silently omitting a selected pillar or a tool failure     | Record scan status `absent`/`skipped` and degrade coverage      |
+| Claiming "comprehensive" with `coverage.complete=false`   | Report incomplete coverage explicitly                           |
+| Reusing any context without freshness/provenance check    | Verify provenance+freshness against the current tree or degrade |
+| Reading full artifacts for non-candidates                 | Open full files only for candidates / coverage demands          |
+| Fabricating a line-number anchor                          | Use a stable structural anchor or `anchor: unavailable`         |
+| Creating persistent cache / index / daemon / parser in v1 | Keep the in-memory evidence manifest run-local only             |
+
+## Related
+
+- Skill entry: [../SKILL.md](../SKILL.md)
+- Authority matrix and ambiguity protocol: [authority-resolution.md](authority-resolution.md)
+- Finding schema, severity, confidence, coverage: [finding-contract.md](finding-contract.md)
+- Confirmed repair routing and freshness recheck: [remediation-routing.md](remediation-routing.md)
+- Deterministic discovery: `spur task … --json`, `spur feature … --json`, `sp:spur-cli`,
+  `sp:spur-dev`, `sp:doc-evolve`, `sp:code-verification`

package/plugins/sp/skills/conflict-finding/references/finding-contract.md

@@ -0,0 +1,346 @@
+---
+name: finding-contract
+description: "Finding classifications, evidence rules, severity/confidence semantics, and the stable Markdown/JSON result envelope for sp:conflict-finding."
+see_also:
+  - conflict-finding
+  - authority-resolution
+  - comparison-protocol
+  - remediation-routing
+---
+
+# Finding and result contracts
+
+`sp:conflict-finding` reports every asserted conflict as a **finding** carrying a fixed field
+envelope, and packages the whole audit run into a **result** with a fixed top-level shape. This
+file is the SSOT for both: what a finding may say, what evidence must back it, how severity and
+confidence are graded, and how Markdown and `--json` stay the same information in two renderings.
+
+Two rules bind everything below:
+
+1. **A conflict is a claim about claims, not about text.** Only `contradiction`, `stale`,
+   `duplicate`, `omission`, `orphan`, or `ambiguous-authority` supported by reproducible evidence
+   count. Wording or abstraction-level differences are never asserted as conflicts (R2).
+2. **The envelope is stable, the reasoning is not.** `--json` stabilizes the evidence envelope so
+   results can be inspected or composed; it never implies deterministic semantic reasoning.
+
+## 1. Finding classifications
+
+### `conflict_type`
+
+Exactly one of six values. The value states _what kind of disagreement_ the evidence establishes —
+not what the auditor suspects, and never merely what text differs.
+
+| `conflict_type`       | Meaning                                                                                                                                  | Minimum evidence posture                                                      |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `contradiction`       | Two live claims about the same subject + claim type assert incompatible facts and neither is superseded.                                 | ≥ 2 opposing anchors, both current                                            |
+| `stale`               | A projection (derived doc, feature/task status, doc surface) describes a state that its authority or observed reality has moved past.    | ≥ 2 opposing anchors (current authority/observation vs. the stale projection) |
+| `duplicate`           | The same claim is stated in ≥ 2 places as if independent, risking drift and split edits.                                                 | ≥ 2 anchors for the same subject+claim                                        |
+| `omission`            | A required claim is absent where the authority or an explicit link implies it must exist.                                                | 1 anchor proving the obligation + 1 anchor showing the gap                    |
+| `orphan`              | A claim references a subject, symbol, WBS, feature ID, or command that no longer exists or is no longer reachable.                       | 1 anchor for the dangling reference + 1 anchor showing the target is gone     |
+| `ambiguous-authority` | Two or more authorities claim the same subject+claim but are incomparable (or authority is missing), so no precedence edge can be drawn. | ≥ 2 candidate authorities, none provably dominant                             |
+
+Rules:
+
+- A `contradiction` between a normative source and observed reality is recorded as _both_ sides —
+  the precedence reason names which side is normative and which is observed, without deleting the
+  observed one (see [./authority-resolution.md](authority-resolution.md)).
+- A `stale` finding never mutates the source of truth; it names which projection lags and which
+  artifact is authoritative.
+- When classification is uncertain, default to `ambiguous-authority` (an unresolved HITL item) or
+  to a low-confidence candidate — never to a definitive `contradiction` you cannot defend.
+
+### `status`
+
+Exactly one of six lifecycle states. It tracks where the finding sits between discovery and
+resolution, and it is what the remediation workflow reads to decide the next action.
+
+| `status`                   | Meaning                                                                                                | Who advances it                               |
+| -------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------- |
+| `open`                     | Reported with evidence; no decision or repair yet.                                                     | default after audit                           |
+| `needs-authority-decision` | Authority is incomparable/missing; requires a human decision before any repair is proposed as settled. | audit, when authority ambiguity is unresolved |
+| `confirmed`                | Evidence revalidated (freshness recheck) and the finding is accepted as real.                          | confirmation gate                             |
+| `repairing`                | A repair is in flight through the owner surface.                                                       | remediation routing                           |
+| `resolved`                 | Repair applied, or the artifacts now match (idempotent), and freshness revalidated.                    | remediation completion                        |
+| `failed`                   | A repair attempt failed or hit ambiguous authority mid-repair and was not silently rolled forward.     | remediation failure                           |
+
+Transition rules:
+
+- `open` → `needs-authority-decision` happens during audit when no precedence edge can be drawn.
+- `open`/`needs-authority-decision` → `confirmed` only through the explicit confirmation step in
+  `--resolve` mode after a freshness recheck.
+- A `failed` finding may be re-audited (back to `open`) but is never silently reported as
+  `resolved`.
+
+## 2. Required finding fields
+
+Every finding carries all of these fields, in **both** Markdown and JSON. The field set is fixed;
+absent information is represented by an explicit sentinel (`null`, `"unknown"`, or `[]`), never by
+dropping the key.
+
+| Field                  | Type           | Content                                                                                                                                                                                   |
+| ---------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                   | string         | Stable identifier for this finding in this run, e.g. `F-0001`. Used to key remediation and stale-evidence checks.                                                                         |
+| `subject`              | string         | The shared identity the conflicting claims are about (path, WBS, feature ID, symbol, command, config key, or normalized domain term).                                                     |
+| `claim_type`           | string         | The claim dimension being judged (process, structural-decision, product-scope, feature-ac, task-obligation, architecture-mechanism, command/api/schema-surface, implementation-behavior). |
+| `conflict_type`        | string         | One of the six values in §1.                                                                                                                                                              |
+| `pillars`              | string[]       | The pillar(s) involved, from `source`, `tasks`, `features`, `authority`.                                                                                                                  |
+| `artifacts`            | string[]       | Repo-relative paths of every artifact participating in the conflict.                                                                                                                      |
+| `normative_authority`  | string \| null | The artifact/rule that defines what _should_ be true for this subject+claim, if resolvable.                                                                                               |
+| `observed_reality`     | string \| null | What currently _is_ true (runtime behavior, code topology, gate output), if observable.                                                                                                   |
+| `precedence_reason`    | string         | The project rule or documented fallback that justifies the authority edge — or an explicit statement that none exists (for `ambiguous-authority`).                                        |
+| `evidence`             | array          | Reproducible evidence items per §3.                                                                                                                                                       |
+| `freshness`            | object         | Per-anchor staleness: `{ revalidated: bool, rechecked_at: ISO8601\|null, anchors_stale: string[] }`.                                                                                      |
+| `severity`             | string         | Impact grade: `critical` \| `high` \| `medium` \| `low` (§4).                                                                                                                             |
+| `confidence`           | string         | Evidence-strength grade: `high` \| `medium` \| `low` (§4).                                                                                                                                |
+| `false_positive_check` | string         | The explicit reasoning that rules out lifecycle, supersession, abstraction-level, and intentional-deprecation explanations before asserting conflict (R2).                                |
+| `proposed_repair`      | string \| null | The minimal repair that would reconcile the claims, when one can be proposed without forcing ambiguous authority.                                                                         |
+| `repair_owner`         | string \| null | The artifact owner / route responsible for the repair (`spur task/feature`, `sp:doc-evolve`, source lifecycle, command/skill superskill).                                                 |
+| `status`               | string         | One of the six values in §1.                                                                                                                                                              |
+
+### The `false_positive_check` is mandatory
+
+Every finding must show its work against the four challenge classes (R2). The check is a short
+statement, not a placeholder:
+
+| Challenge               | Ask                                                                                    | If it explains the difference |
+| ----------------------- | -------------------------------------------------------------------------------------- | ----------------------------- |
+| Lifecycle               | Is one claim planned/future work rather than a present contradiction?                  | Not a conflict                |
+| Supersession            | Is the older artifact superseded/historical?                                           | Not a current conflict        |
+| Abstraction level       | Are the claims at different intended levels (design intent vs. implementation detail)? | Not a conflict                |
+| Intentional deprecation | Is the divergence deliberate and documented?                                           | Not a conflict                |
+
+A finding with an empty or hand-wavy `false_positive_check` must be demoted to low-confidence
+candidate or dropped — it has not met the bar for a definitive conflict.
+
+## 3. Evidence rules
+
+Each item in `evidence` is a reproducible, self-contained anchor. The same shape appears in
+Markdown (as a bulleted evidence block) and JSON (as an object in the `evidence` array).
+
+```json
+{
+  "path": "docs/04_DESIGN.md",
+  "anchor": { "kind": "line", "value": 141 },
+  "claim_paraphrase": "DESIGN says the flag default is --mode adaptive",
+  "provenance": { "source": "git blame", "freshness": "2026-08-08" },
+  "reproduced_by": "rg '--mode' docs/04_DESIGN.md; read docs/04_DESIGN.md:141"
+}
+```
+
+### Anchor kinds
+
+`anchor.kind` is one of a fixed set — never a bare, unverifiable line number.
+
+| `kind`    | `value` example                | When to use                                                            |
+| --------- | ------------------------------ | ---------------------------------------------------------------------- |
+| `line`    | `141`                          | A specific line, when a stable line number exists in the current tree. |
+| `heading` | `## Design`                    | A section that can move line numbers across edits.                     |
+| `symbol`  | `findconflict`                 | A function/type/command/flag/config-key name.                          |
+| `wbs`     | `0486`                         | A task WBS identifier.                                                 |
+| `feature` | `H11`                          | A feature ID.                                                          |
+| `command` | `/sp:dev-find-conflict --json` | A command or flag invocation / contract.                               |
+
+### Mandatory rules
+
+1. **Repo-relative path.** `path` is always relative to the repository root; never an absolute
+   path, never an invented location.
+2. **Claim paraphrase.** Every anchor restates the claim it supports in the auditor's own words so
+   the reader need not re-open the artifact to know what was asserted.
+3. **Provenance and freshness.** Record where the value came from (`git`, `rg`, `spur task --json`,
+   `sp:doc-evolve` audit, direct read) and when it was observed, so revalidation can detect drift.
+4. **Reproduction step.** `reproduced_by` names the exact command or reasoning step that produced
+   the anchor, so a fresh session can re-run it.
+5. **Two opposing anchors for `contradiction`/`stale`.** These conflict types are not asserted on a
+   single artifact: `evidence` must contain at least two anchors on opposite sides, each with its
+   own path/paraphrase/reproduction.
+6. **Never fabricate line numbers.** If a line number is unavailable or unstable, use a stable
+   structural anchor (`heading`, `symbol`, `wbs`, `feature`, `command`). A made-up line number is a
+   hard violation; prefer a structural anchor and note `line` as `null`.
+7. **Opposing anchors must be current.** For `contradiction`, both sides must be live; a superseded
+   or historical anchor is not opposition. For `stale`, the current authority/observation is one
+   side and the lagging projection the other.
+
+### Unavailable anchors
+
+When a claim cannot be pinned to a stable anchor, record the best structural anchor and set
+`confidence` accordingly — never fabricate, never silently drop the evidence item. An evidence item
+with no reproducible anchor cannot support a `contradiction`/`stale` finding.
+
+## 4. Severity and confidence
+
+Severity and confidence answer two different questions and must never be conflated:
+
+- **`severity`** = impact _if the conflict is real_ (blast radius, wrongness, cost of not fixing).
+- **`confidence`** = strength of the evidence that the conflict _is real_.
+
+### Severity — impact-based
+
+| `severity` | Meaning                                                                                                                                                                                                   |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `critical` | The conflict misdirects or corrupts a load-bearing decision/contract: e.g. an AC that contradicts shipped behavior of a core command, or an ADR superseded while derived docs still assert it as current. |
+| `high`     | A materially wrong projection that likely causes incorrect work (stale task status, feature AC drift, surface doc contradicting a schema).                                                                |
+| `medium`   | A real but bounded divergence; correctable with local, confirmed repair.                                                                                                                                  |
+| `low`      | A cosmetic or low-blast-radius inconsistency; tracked but not urgent.                                                                                                                                     |
+
+Severity is judged from impact, _not_ from how easy the conflict was to spot. A `critical` finding
+with weak evidence still reports `severity: critical` but `confidence: low` (see below).
+
+### Confidence — evidence strength
+
+| `confidence` | Meaning                                                                                                                        |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `high`       | ≥ 2 reproducible, current, opposing anchors; precedence edge is explicit and challenge-free.                                   |
+| `medium`     | Reproducible anchor(s) present, but one side is weaker (stale provenance, single indirect anchor, or a non-trivial inference). |
+| `low`        | A plausible candidate supported by partial/indirect evidence; could not be fully defended.                                     |
+
+### Low confidence never disappears
+
+A low-confidence candidate is **never promoted to a definitive conflict**, and it is **never
+dropped**:
+
+- It is reported with `confidence: low` and `status: open` (or `needs-authority-decision`), placed
+  after higher-confidence findings in the report.
+- It is NOT given `status: confirmed` and is NOT routed for repair in `--resolve` mode without
+  human revalidation.
+- The report lists it under **candidates / unresolved**, distinct from confirmed findings, so
+  nothing is silently lost.
+
+## 5. Top-level result envelope
+
+The whole run is a single result object. Top-level keys are fixed:
+
+```text
+schema_version, command, scope, mode, pillars, authority_map,
+inventory, findings, unresolved, coverage, cost, remediation, errors
+```
+
+```json
+{
+  "schema_version": 1,
+  "command": "dev-find-conflict",
+  "scope": "docs/00_ADR.md",
+  "mode": "adaptive",
+  "pillars": ["authority"],
+  "authority_map": {},
+  "inventory": [],
+  "findings": [],
+  "unresolved": [],
+  "coverage": { "complete": true },
+  "cost": {},
+  "remediation": {},
+  "errors": []
+}
+```
+
+| Key              | Content                                                                                                                                                                     |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schema_version` | integer, `1`. The envelope contract version — not a semantic-reasoning version.                                                                                             |
+| `command`        | string, `dev-find-conflict`.                                                                                                                                                |
+| `scope`          | string. The resolved audit scope (path, WBS, feature ID, symbol, command, or `"<project>"`).                                                                                |
+| `mode`           | string, `adaptive` \| `full`.                                                                                                                                               |
+| `pillars`        | string[]. The pillars actually audited (subset of `source`, `tasks`, `features`, `authority`).                                                                              |
+| `authority_map`  | object. Claim-type → authoritative artifact/rule, with each precedence edge citing its project rule or fallback (see [./authority-resolution.md](authority-resolution.md)). |
+| `inventory`      | array. Four-pillar inventory entries: `{ pillar, identity, path, anchor, freshness, scan_status }`.                                                                         |
+| `findings`       | array. Confirmed findings with the fixed field set of §2.                                                                                                                   |
+| `unresolved`     | array. Ambiguous-authority and low-confidence candidates awaiting a human decision; never empty-hiding real uncertainty.                                                    |
+| `coverage`       | object. Intended/discovered/scanned/skipped per pillar, skipped reasons, reused context, change cone, `complete: boolean` (§6).                                             |
+| `cost`           | object. Estimated files/claims/tokens inspected vs. skipped; never claims "comprehensive" when `coverage.complete` is false (§6).                                           |
+| `remediation`    | object. The confirmed/declined repair set keyed by finding ID + evidence fingerprint, with per-item outcome (see [./remediation-routing.md](remediation-routing.md)).       |
+| `errors`         | array. Distinctly typed failures — see below.                                                                                                                               |
+
+### `errors` — tool failure vs. semantic uncertainty
+
+`errors` distinguishes two failure classes so a consumer never mistakes a broken tool for a
+genuinely ambiguous claim:
+
+| Error type             | Meaning                                                                                                                                           | Example |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `tool_failure`         | A deterministic step (git, rg, `spur task --json`, check) failed or was unavailable. Recorded as coverage evidence; degrades `coverage.complete`. |
+| `semantic_uncertainty` | The model could not defensibly classify/comparify a subject+claim. Recorded as an unresolved candidate, never forced to a definitive conflict.    |
+
+Both types carry `{ kind, subject, message }`. A `tool_failure` never becomes a finding; a
+`semantic_uncertainty` never becomes a confirmed conflict.
+
+### `coverage` — honesty contract
+
+```json
+{
+  "complete": false,
+  "pillars": {
+    "source": {
+      "intended": 120,
+      "discovered": 120,
+      "scanned": 80,
+      "skipped": 40,
+      "skipped_reasons": ["stale_context", "unlinked_symbols"]
+    },
+    "tasks": {
+      "intended": 60,
+      "discovered": 60,
+      "scanned": 60,
+      "skipped": 0,
+      "skipped_reasons": []
+    }
+  },
+  "reused_context": [".spur/context/anatomy.md"],
+  "change_cone": "git diff main..HEAD -- src/",
+  "complete": false
+}
+```
+
+- `complete: true` is claimed **only** when every intended pillar entry was scanned and every
+  tool step succeeded.
+- Adaptive mode must disclose `skipped` and `skipped_reasons` (stale context, unverifiable
+  provenance, unlinked symbols) and, when reuse is used, the `reused_context` paths plus the
+  `change_cone` it relied on.
+- Absent/stale/unverifiable context degrades to a cold full scan **or** an explicit
+  `complete: false` result — never a silent reduced-coverage claim.
+
+### Markdown carries the same information
+
+The Markdown report is the same envelope rendered as readable sections, with no information loss:
+
+- A **Coverage** section mirrors `coverage` (per-pillar scanned/skipped + reasons, reused context,
+  change cone, completeness statement).
+- A **Findings** section lists every finding with all fields of §2; ordering by `severity` then
+  `confidence`.
+- An **Unresolved / candidates** section mirrors `unresolved`, including low-confidence candidates
+  and ambiguous authority.
+- An **Errors** section distinguishes `tool_failure` from `semantic_uncertainty`.
+- An **Authority** section mirrors `authority_map` with each precedence edge's rule citation.
+- **Cost** is reported plainly and never overstated when coverage is incomplete.
+
+## 6. Stable JSON vs. non-deterministic reasoning
+
+`--json` emits the same envelope as Markdown, but stability is scoped deliberately:
+
+- **Stable:** the _evidence envelope_ — schema_version, field names and shapes, evidence anchor
+  kinds, classification vocabulary (`conflict_type`, `status`), coverage accounting, error typing.
+- **Not stable / never implied deterministic:** the _semantic reasoning_ — which candidates were
+  generated, how subject clustering was done, which comparisons were drawn, and the prose
+  justifications. Two runs over the same tree may name different candidates; that is expected and
+  must not be presented as a classifier regression.
+
+Consumers (tests, automation, downstream tools) may rely on the envelope contract and on
+reproducible anchors; they must not rely on candidate-set identity or on any claim of
+deterministic semantic output. This is why `schema_version` is an envelope version only.
+
+## 7. Cross-cutting rules (R2)
+
+- Only the six `conflict_type` values are asserted; everything else is a candidate or unresolved.
+- Every finding names the subject, claim type, artifacts, authority path, and reproducible
+  anchors (R4).
+- A selected pillar is never silently omitted; absence of an optional authority file is reported
+  but does not block the audit (R1).
+- No unbounded all-pairs comparison; candidates come only from the explicit-link candidate graph
+  (see [./comparison-protocol.md](comparison-protocol.md)).
+- Audit mode produces findings only; mutation requires `--resolve` + confirmation + freshness
+  recheck, routed by owner (see [./remediation-routing.md](remediation-routing.md)).
+
+## Related
+
+- Skill entry: [../SKILL.md](../SKILL.md)
+- Authority matrix + fallback: [./authority-resolution.md](authority-resolution.md)
+- Candidate graph + comparison protocol: [./comparison-protocol.md](comparison-protocol.md)
+- Confirmed remediation routing: [./remediation-routing.md](remediation-routing.md)
+- Verification of findings against requirements: `sp:code-verification`