@gobing-ai/spur 0.3.41 → 0.3.42

package/plugins/sp/skills/code-verification/references/verdict-schema.md

@@ -0,0 +1,141 @@
+---
+name: verdict-schema
+description: "The VerifyVerdict artifact shape and per-requirement aggregation rule"
+see_also:
+  - sp:code-verification
+---
+
+# Verdict Schema
+
+The verify mode emits `.spur/run/<wbs>-verdict.json` — the machine contract between
+`sp:code-verification` and the `task-pipeline.yaml` completion gate.
+
+```typescript
+interface VerifyVerdict {
+  /** The task this verdict certifies. */
+  wbs: string;
+  /** Aggregate verdict. Only PASS clears the pipeline gate. */
+  verdict: 'PASS' | 'PARTIAL' | 'FAIL';
+  /** Per-requirement traceability result. */
+  requirements: Array<{
+    id: string;                                // e.g. "R1"
+    status: 'MET' | 'PARTIAL' | 'UNMET';
+    evidence: string;                          // file:line, test name, or "no evidence found"
+  }>;
+  /** Per-Acceptance Criteria result. Present when the task has non-empty AC. */
+  acceptanceCriteria?: Array<{
+    id: string;                                // checklist label or "Scenario: <title>"
+    status: 'MET' | 'PARTIAL' | 'UNMET' | 'N/A';
+    evidenceType: 'test' | 'command' | 'static-ref' | 'manual-review' | 'llm-judge' | 'n/a';
+    evidence: string;                          // evidence or explicit N/A justification
+  }>;
+  /** Discrete gate checks (sections populated, tests pass, lint clean, …). */
+  checks: Array<{
+    name: string;                              // e.g. "tests-pass", "lint-clean"
+    status: 'pass' | 'fail' | 'warn';
+    evidence: string;
+  }>;
+}
+```
+
+## Compatibility alias: `scenario` row key
+
+Task 0410 hardened the verdict reader. Producers SHOULD use the canonical `id` field for every
+requirement and AC row. Consumers (the feature-check L4 traceability layer) ALSO accept `scenario`
+as a compatibility alias for the row identifier, with these rules:
+
+- Row with `id` only → canonical; accepted as-is.
+- Row with `scenario` only → accepted; normalized to `{ id: scenario, … }`.
+- Row with both `id` and `scenario` where they are EQUAL → `id` is authoritative; accepted.
+- Row with both `id` and `scenario` where they DIFFER or either value is not a string → **rejected**
+  (conflict); the rejected row
+  count and invalid fields surface as a bounded `L4.malformed-verdict-artifact` warning naming the
+  task WBS and artifact path.
+- Row missing both `id` and `scenario`, or missing `status`, or not an object → rejected and warned.
+
+Empty `requirements` / `acceptanceCriteria` arrays are valid and produce no warning. The required
+`requirements` array being absent, either coverage field being a non-array value, a missing artifact,
+malformed JSON, and a non-object JSON root are distinct diagnostic outcomes. Each emits one bounded
+`L4.malformed-verdict-artifact` warning per task/artifact whose message names the failure mode;
+optional `acceptanceCriteria` may remain absent.
+
+Canonical producers and docs continue to use `id`. The `scenario` alias exists so older or
+third-party verdict emitters keyed on scenario titles are not silently dropped.
+
+## Aggregation rule
+
+The aggregate `verdict` is derived from the per-requirement, per-AC, and blocking review statuses:
+
+```
+any core requirement UNMET                         → FAIL
+any core Acceptance Criteria UNMET                 → FAIL
+any blocker correctness/security check             → FAIL
+any core requirement or AC PARTIAL (no FAIL)       → PARTIAL
+any unresolved major quality check (no FAIL)       → PARTIAL
+all core requirements and AC MET or justified N/A  → PASS
+```
+
+There is no "good enough" — `PARTIAL` blocks the gate exactly like `FAIL`. The distinction exists
+only to tell the operator *how far off* delivery is (UNMET = nothing there; PARTIAL = half there).
+
+## Acceptance Criteria evidence
+
+When a task has non-empty Acceptance Criteria, `acceptanceCriteria` must be populated. Evidence type
+is part of the contract so weak proof is visible to the pipeline and to reviewers:
+
+- `test` / `command`: deterministic evidence.
+- `static-ref`: source, configuration, or documentation reference evidence.
+- `manual-review`: reviewer reasoning with cited files.
+- `llm-judge`: qualitative judgment only; it cannot alone certify objective AC.
+- `n/a`: explicitly justified non-applicability.
+
+Every CORE behavior-bearing AC requires executable evidence: at least one `test` or `command` row.
+`spur task verdict` treats AC rows as core and behavior-bearing by default; add `[advisory]`,
+`[non-core]`, `[non-behavior]`, or `[docs-only]` in the AC id only when that weaker rule is
+intentional. A MET behavior AC with only `static-ref`, `manual-review`, or `llm-judge` evidence is
+downgraded to `PARTIAL` and emits an `evidence-rule-failed` check. CLI-surface changes should also
+emit a `cli-golden-path-present` check backed by a golden-path `--json` command invocation.
+
+For answer files, emit a matching parseable table:
+
+```markdown
+### Acceptance Criteria Verification
+
+| AC | Status | Evidence Type | Evidence |
+|----|--------|---------------|----------|
+| Scenario: CLI emits JSON | MET | test | `apps/cli/tests/foo.test.ts:42` |
+```
+
+## Checks evidence
+
+Wave C verification can emit the following additive `checks[]` rows:
+
+| Check | Meaning |
+| ----- | ------- |
+| `design-conformance` | Task `### Design` claims were classified DONE / PARTIAL / NOT DONE / CHANGED against the diff. |
+| `scope-creep` | Diff hunks did not map to Requirements / AC / Design / Plan items. Informational unless SECUA raises it. |
+| `evidence-rule-pass` | All behavior-bearing AC rows had executable evidence or were explicitly non-behavioral. |
+| `evidence-rule-failed` | One or more MET behavior-bearing AC rows lacked `test` / `command` evidence and were downgraded to PARTIAL. |
+| `cli-golden-path-present` | CLI-surface tasks supplied, or failed to supply, one golden-path command evidence row. |
+
+## How the gate reads it
+
+`.spur/workflows/task-pipeline.yaml`, transition `verify → record`:
+
+```yaml
+guard:
+  kind: shell
+  options:
+    command: 'test "$(jq -r .verdict .spur/run/${vars.wbs}-verdict.json)" = PASS'
+```
+
+with a sibling `verify → failed` guarded on the negation. So a missing file, malformed JSON, or any
+non-`PASS` verdict routes the run to `failed` rather than `done` — the pipeline cannot certify
+completion without an explicit PASS artifact.
+
+## Lifecycle
+
+- **Written:** Step 9 of verify mode, *after* the verdict is final (never partially).
+- **Read:** by the workflow gate on the `verify → record` transition.
+- **Location:** `.spur/run/` (the run-scratch dir the pipeline's `record` step also uses).
+- **Lifetime:** per execution attempt; overwritten on the next verify of the same WBS.

package/plugins/sp/skills/conflict-finding/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: conflict-finding
+description: "Authority-aware semantic audit across source, task files, feature files, and project authority files — detect conflicts, resolve claim-specific authority, collect reproducible evidence, and route confirmed repairs through owner surfaces. Triggers: find conflict, conflict audit, semantic conflict, authority mismatch, stale projection."
+license: Apache-2.0
+version: 1.0.0
+metadata:
+  author: spur
+  platforms: "claude-code,codex,openclaw,opencode,antigravity,pi"
+  category: analysis-core
+  interactions:
+    - audit
+    - remediation
+  pipeline_steps:
+    - discover
+    - compare
+    - resolve
+    - report
+    - remediate
+  openclaw:
+    emoji: "🧭"
+see_also:
+  - sp:doc-evolve
+  - sp:spur-cli
+  - sp:code-verification
+  - sp:spur-dev
+---
+
+# sp:conflict-finding — Authority-Aware Indexed Conflict Audit
+
+A prompt-first, authority-aware audit across the four pillars — **source code**, **task files**,
+**feature files**, and **project authority files** — that discovers conflicts, resolves claim-specific
+authority, collects reproducible evidence, and routes confirmed repairs through each artifact owner's
+existing harness surface.
+
+**Honesty contract:** v1 is prompt-first. The model performs subject clustering, claim-specific
+authority reasoning, and semantic comparison; existing deterministic tools (`git`, `rg`,
+`spur task/feature --json`, `spur … check`, `sp:doc-evolve` audit surfaces) gather facts. V1 adds no
+TypeScript analyzer, database, vector index, embedding pipeline, persistent cache, new runtime
+dependency, or dedicated subagent.
+
+## When to Use
+
+**Trigger phrases:** "find conflict", "conflict audit", "semantic conflict", "authority mismatch",
+"stale projection", "do the docs and code agree", "audit the corpus"
+
+**Use PROACTIVELY when:**
+
+- A claim in one pillar appears to contradict another pillar (source↔task, source↔feature,
+  source↔authority, task↔feature, task↔authority, feature↔authority).
+- A task or feature's status, AC, or requirements may have drifted from the implemented surface.
+- A derived projection (architecture/design/docs) may have diverged from its authority (ADR/PRD).
+- The operator wants a reproducible evidence envelope before authorizing any repair.
+
+**Do NOT use for:**
+
+- Debugging a specific runtime failure — use `sp:sys-debugging`.
+- Code review — use `sp:code-review` / `sp:code-verification`.
+- General documentation drift maintenance — use `sp:doc-evolve`.
+- Performing repairs automatically — this skill only audits and (with `--resolve`) proposes
+  confirmed, owner-routed repairs; it never mutates without explicit confirmation.
+
+## Arguments
+
+| Argument                                             | Description                                                                                                                                          | Default         |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
+| `[scope]`                                            | Optional path, WBS, feature ID, symbol, command, config key, or free-form subject to scope the audit.                                                | current project |
+| `--pillar <source\|tasks\|features\|authority\|all>` | Limit the internal audit to one pillar; the minimum authorities needed to judge it still load.                                                       | `all`           |
+| `--mode <adaptive\|full>`                            | Scan protocol — `adaptive` reuses fresh, provenance-verifiable indexed context and discloses skipped areas; `full` forces a cold comprehensive scan. | `adaptive`      |
+| `--resolve`                                          | Enable the proposal, confirmation, and owner-routed remediation workflow. Its absence guarantees no source/corpus/numbered-doc mutation.             | off             |
+| `--agent <inline\|auto\|name>`                       | Who runs the model-bearing analysis. `inline` is the default; `--agent auto`/a named executor isolates the analysis. Not a dedicated subagent.       | `inline`        |
+| `--json`                                             | Emit the same result envelope as Markdown as JSON. Never implies deterministic semantic reasoning.                                                   | off             |
+
+## The 10-Step Audit Protocol
+
+```
+scope + flags
+  → PARSE & GUARD     resolve scope/flags; confirm repository root; set audit-only vs resolve mode
+  → DISCOVER AUTHORITY  read entry/process rules; build the claim-specific authority matrix
+  → PREFLIGHT         git, rg, spur task/feature --json, relevant spur … check, doc-evolve audit
+  → INVENTORY         four-pillar inventory: pillar, identity, path, anchor, freshness, scan status
+  → CANDIDATE GRAPH   join claims via explicit links, WBS/feature IDs, AC titles, symbols, commands,
+                      flags, schemas, config keys, normalized domain terms
+  → WITHIN-PILLAR     contradictions, stale projections, duplicates, omissions, orphans, ambiguity
+  → CROSS-PILLAR      all six applicable boundaries
+  → CLASSIFY          lifecycle, supersession, abstraction-level, intentional-deprecation challenges
+  → REPORT            order by severity then confidence; coverage, unresolved authority, scan cost
+  → REMEDIATE         only with --resolve and explicit confirmation + freshness recheck
+```
+
+### Step 1 — Parse and guard
+
+Resolve `<scope>` and `--pillar`; confirm the repository root; establish **audit-only** versus
+`--resolve` mode. Without `--resolve`, the run is strictly read-only: no source, corpus, or
+numbered-document mutation of any kind. With `--resolve`, no write happens until a repair set is
+presented, explicitly confirmed, and freshness-revalidated.
+
+### Step 2 — Discover local authority
+
+Read entry/process rules (`AGENTS.md`, `docs/99_PROJECT_CONSTITUTION.md`) before interpreting any
+difference. Build the claim-specific authority matrix — authority is resolved for a **subject +
+claim type**, never for a whole file. The default 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; absent optional files are reported without blocking
+the audit. Full matrix and fallback rules: [references/authority-resolution.md](references/authority-resolution.md).
+
+### Step 3 — Run deterministic preflight
+
+Use `git`, `rg`, `spur task/feature … --json`, relevant `spur … check`, and `sp:doc-evolve` audit
+surfaces when available. Tool failures become **coverage evidence**, never silent omission; record
+them in `errors` and degrade `coverage.complete` accordingly.
+
+### Step 4 — Build inventories
+
+For each pillar record: identity, path, anchor, provenance/freshness, and scan status. Optional
+files may be absent; a selected pillar may **not** be silently omitted. Unavailable line numbers
+must be replaced with a stable structural anchor (heading, symbol, WBS, feature ID, command), never
+fabricated.
+
+### Step 5 — Build the candidate graph
+
+Join claims using explicit links, WBS/feature IDs, dependencies, AC titles, paths, symbols,
+command/flag names, DTO/schema/config keys, and normalized domain terms. **Do not compare every
+artifact with every other artifact** — an unbounded all-pairs comparison is prohibited. See
+[references/comparison-protocol.md](references/comparison-protocol.md).
+
+### Step 6 — Audit within each pillar
+
+- **Source**: contracts/implementations/tests/config/registrations.
+- **Tasks**: requirements/AC/dependencies/status/solution.
+- **Features**: hierarchy/AC/status/index projections.
+- **Authority**: ownership/decision/scope/process projections.
+
+### Step 7 — Audit all applicable cross-pillar boundaries
+
+source↔task, source↔feature, source↔authority, task↔feature, task↔authority, feature↔authority —
+every boundary applicable to the selected scope.
+
+### Step 8 — Classify and challenge
+
+Before asserting a conflict, test each candidate against lifecycle, supersession,
+abstraction-level, and intentional-deprecation explanations. Mere wording or abstraction-level
+difference is **not** a conflict. Low confidence never disappears — it is reported as a candidate or
+unresolved item, not promoted to a definitive conflict.
+
+### Step 9 — Report
+
+Order findings by severity then confidence. Show clean boundaries, unresolved authority, coverage
+gaps, reused context, scan cost, and the recommended owner. Markdown and `--json` carry the same
+findings, evidence, authority provenance, coverage, unresolved decisions, and remediation state. See
+[references/finding-contract.md](references/finding-contract.md).
+
+### Step 10 — Remediate only when requested
+
+With `--resolve`: present the proposed repair set, obtain explicit confirmation, revalidate evidence
+freshness, then route each approved repair through its verified owner surface. Report the completed,
+failed, and untouched sets; never silently roll forward past a partial failure. See
+[references/remediation-routing.md](references/remediation-routing.md).
+
+## Output
+
+**Default:** a Markdown audit report with ordered findings, coverage accounting, and unresolved
+items; no mutation.
+
+**With `--json`:** the same envelope as machine-readable JSON.
+
+```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": []
+}
+```
+
+Top-level JSON keys: `schema_version, command, scope, mode, pillars, authority_map, inventory,
+findings, unresolved, coverage, cost, remediation, errors`.
+
+## Integration
+
+- **Authority matrix + fallback** — [references/authority-resolution.md](references/authority-resolution.md)
+- **Comparison protocol + token controls** — [references/comparison-protocol.md](references/comparison-protocol.md)
+- **Finding/result contracts + false-positive rules** — [references/finding-contract.md](references/finding-contract.md)
+- **Confirmed remediation routing** — [references/remediation-routing.md](references/remediation-routing.md)
+
+## Required Permissions
+
+| Capability      | Purpose                                                                                  |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| `Read`          | Authority files, task/feature files, source, numbered docs                               |
+| `Grep` / `Glob` | Pattern search and scope discovery                                                       |
+| `Bash`          | `git`, `rg`, `spur task/feature ... --json`, `spur ... check`, `sp:doc-evolve` audit     |
+| `Write`         | Only for temp files / owner-routed repair payloads after confirmation (with `--resolve`) |
+
+## Platform Notes
+
+### Claude Code
+
+- Invoke via `/sp:dev-find-conflict …` or `Skill(skill="sp:conflict-finding", args="…")`.
+- Prefer structured tools for discovery; read full artifacts only for candidate subjects.
+
+### Codex / OpenClaw / OpenCode / Antigravity / Pi
+
+- Read this skill and follow the 10-step protocol (slash commands adapted at install time).
+- Prefer `rg` for scanning; expand globs carefully; treat `.spur/context/` as optional, freshness-gated evidence.
+
+## Shipped command
+
+### `/sp:dev-find-conflict`
+
+Thin wrapper: `Skill(skill="sp:conflict-finding", args="$ARGUMENTS")`.
+
+```
+/sp:dev-find-conflict
+/sp:dev-find-conflict docs/00_ADR.md
+/sp:dev-find-conflict --pillar tasks --mode full
+/sp:dev-find-conflict 0486 --resolve
+/sp:dev-find-conflict "command surface" --json
+```
+
+## Common rationalizations
+
+| Rationalization                            | Reality                                                                                                                                                         |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "A textual difference is a conflict."      | Only contradiction, stale, duplicate, omission, orphan, or ambiguous-authority supported by evidence counts; wording/abstraction differences are not conflicts. |
+| "Lower-numbered docs always win."          | Authority is claim-specific; the constitution's precedence applies only within its stated boundary.                                                             |
+| "Code is always right."                    | Code is authoritative for what currently happens, not automatically for what should happen.                                                                     |
+| "`--resolve` authorizes automatic repair." | It opens the proposal/confirmation workflow; every repair still needs explicit confirmation and a freshness check, then the owner surface.                      |
+| "Adaptive can reuse any context."          | Reuse requires freshness + verifiable provenance; absent/stale/unverifiable context degrades to a cold scan or an explicit incomplete-coverage result.          |
+
+## Red flags
+
+- Asserting a conflict from wording alone or an unbounded all-pairs comparison.
+- Forcing an ambiguous/missing authority through a global ranking instead of an unresolved HITL item.
+- Silently omitting a selected pillar or a tool failure (no coverage accounting).
+- Claiming "comprehensive" when `coverage.complete` is false.
+- Any mutation in audit mode, or automatic mutation merely because `--resolve` is present.
+- Editing a derived projection before its authority.
+- Adding a production analyzer, index/cache/database, dependency, or dedicated subagent in v1.
+
+## Reference files
+
+- **[references/authority-resolution.md](references/authority-resolution.md)** — authority discovery, claim taxonomy, fallback matrix, ambiguity protocol
+- **[references/comparison-protocol.md](references/comparison-protocol.md)** — inventories, subject clustering, internal/cross-pillar comparisons, token controls
+- **[references/finding-contract.md](references/finding-contract.md)** — classifications, evidence rules, Markdown/JSON schemas, severity/confidence/coverage
+- **[references/remediation-routing.md](references/remediation-routing.md)** — HITL, freshness recheck, owner routing, partial-failure/idempotency behavior

package/plugins/sp/skills/conflict-finding/references/authority-resolution.md

@@ -0,0 +1,258 @@
+---
+name: authority-resolution
+description: "Authority discovery, claim taxonomy, fallback authority matrix, precedence rules, and the ambiguity protocol for sp:conflict-finding."
+see_also:
+  - conflict-finding
+---
+
+# Authority resolution — subject + claim type, never a whole file
+
+The hard problem of conflict finding is not text matching; it is deciding **which artifact is
+authoritative for a given claim**. Authority is resolved for a **subject + claim type**, never for
+a whole file. Two files can disagree without any conflict if they claim different kinds of things
+about different subjects, and a single file can be authoritative for one claim type and merely a
+projection for another.
+
+This file is the SSOT for **Step 2 — Discover local authority** of the audit protocol. It defines
+(a) how authority is discovered, (b) the claim taxonomy and fallback matrix, (c) the precedence
+rules that resolve edges, and (d) the ambiguity protocol that stops rather than fabricates a
+winner. It pairs with:
+
+- [comparison-protocol.md](./comparison-protocol.md) — how subjects and claims are clustered and
+  compared once authority is known.
+- [finding-contract.md](./finding-contract.md) — the `status`/`conflict_type` fields a finding
+  carries, including `needs-authority-decision`.
+- [remediation-routing.md](./remediation-routing.md) — how a resolved authority routes a confirmed
+  repair through its owner, and how ambiguous authority halts mutation.
+
+## 1. Authority discovery
+
+Authority is discovered in two passes, and the second pass can only override the first when the
+project is **explicit** about it.
+
+### 1.1 Entry / process pass (always first)
+
+Read in order, before interpreting any difference:
+
+1. `AGENTS.md` (project root or nearest ancestor) — project entry, routing, and any project-local
+   override rules.
+2. `docs/99_PROJECT_CONSTITUTION.md` (when present) — the process SSOT. Per the Spur documentation
+   map, **lower-numbered numbered docs win on content; `99` owns process**. It may declare
+   precedence boundaries, ownership, and change authority that the fallback matrix must respect.
+
+`AGENTS.md` and the constitution declare **project-local rules**. When those rules are explicit
+about a claim type, they win over the fallback matrix in §2. When they are silent or merely restate
+defaults, apply the documented fallback matrix.
+
+### 1.2 Default authority set
+
+The default authority set is the union of these files **when present**:
+
+| Path | Role in the model |
+|------|-------------------|
+| `AGENTS.md` | project entry, routing, project-local overrides |
+| `docs/00_ADR.md` | structural decisions and rationale |
+| `docs/01_PRD.md` | product scope and non-goals |
+| `docs/03_ARCHITECTURE.md` | current architecture contract |
+| `docs/04_DESIGN.md` | command/API/schema surface |
+| `docs/05_FEATURES.md` | feature status projections |
+| `docs/99_PROJECT_CONSTITUTION.md` | process and contribution rules |
+
+Absent optional files are **reported without blocking the audit**. Their absence is itself an
+omission candidate for the `authority` pillar, but it does not halt discovery or comparison of the
+present authorities.
+
+### 1.3 Authority is resolved for a subject + claim type
+
+Never ask "which file wins?" in the abstract. Always ask:
+
+```
+For this SUBJECT, and this CLAIM TYPE, which artifact is normative?
+```
+
+A subject is a concrete named thing under audit — a WBS id, a feature id, a symbol, a command, a
+config key, a path, a domain term, or a free-form concept the operator scoped. A claim type is one
+of the eight rows of §2. The same pair of files may be ordered differently for different claim
+types: `docs/01_PRD.md` is normative for product scope but only a projection for implementation
+behavior.
+
+## 2. Claim taxonomy and fallback authority matrix
+
+The fallback matrix applies when the project declares no explicit rule. Each row names the
+**normative authority** (what the claim *should* be), the **constraint / projection** artifacts
+(what derives from or must not contradict it), and the **observed reality** (what currently *is*,
+recorded separately).
+
+| Claim type | Normative authority | Constraint / projection | Observed reality |
+| --- | --- | --- | --- |
+| Process and contribution rules | `docs/99_PROJECT_CONSTITUTION.md` | `AGENTS.md`, templates, workflows | actual harness behavior and gate output |
+| Structural decision / rationale | accepted `docs/00_ADR.md` entry | architecture/design docs | source/module topology |
+| Product scope and non-goals | `docs/01_PRD.md` | feature tree and roadmap | shipped surface |
+| Feature goal and AC | feature file, within PRD/ADR bounds | tasks and `docs/05_FEATURES.md` | implementation and verification evidence |
+| Task obligation/status | task Requirements/AC plus lifecycle verdict | feature AC and task Solution/Testing | code, tests, gate output |
+| Architecture mechanism | ADR when it decides the seam; otherwise current architecture contract | `docs/03_ARCHITECTURE.md` | code dependency/topology |
+| Command/API/schema surface | owning command/contract/schema source under existing ADRs | `docs/04_DESIGN.md` | registered runtime behavior and tests |
+| Implementation behavior | applicable task/feature/doc obligation defines "should" | tests as executable projection | source and runtime behavior define "is" |
+
+### 2.1 Reading the matrix
+
+- **Normative authority** is the source of truth for what *should* be true about the claim. A
+  difference between a projection and its authority is a **stale projection**; a difference between
+  two normative authorities for the same subject+claim type is a candidate **contradiction**.
+- **Constraint / projection** artifacts derive from, or must stay within, the authority. They are
+  judged *against* their authority, not as independent truth.
+- **Observed reality** is never merged into the normative column. Code/tests/runtime output are
+  recorded as what *is*, and the gap between "should" (normative) and "is" (observed) is the
+  conflict surface — but the two are always reported separately (see §5).
+
+## 3. Precedence rules
+
+These five rules resolve an authority edge once the claim type is known. Every precedence
+decision in a finding must cite the project rule or documented fallback that justifies it
+(requirement R3).
+
+### Rule 1 — Lower-numbered docs do not globally beat everything
+
+A lower-numbered numbered document (e.g. `docs/00_ADR.md` vs `docs/04_DESIGN.md`) does **not**
+automatically win every argument. The constitution's documented precedence applies **only within
+its stated boundary** (typically "lower number wins on content; `99` owns process"). Outside that
+boundary the fallback matrix (§2) decides by claim type. Do not map "lower number ⇒ more
+authoritative" as a global ranking.
+
+### Rule 2 — Code is authoritative for what happens, not what should happen
+
+Source and runtime behavior define the **observed reality** ("is"). They are authoritative for
+*what currently happens*. They are **not** automatically authoritative for *what should happen*:
+that is defined by the applicable obligation (task/feature/doc), per the `Implementation behavior`
+row. A gap where code diverges from its obligation is a conflict candidate; it is not resolved by
+"code wins."
+
+### Rule 3 — A todo feature/task differing from code is planned work, not stale code
+
+When a feature/task is still `todo` (or its lifecycle/supersession metadata does not say otherwise)
+and the code does not yet reflect it, the difference is **planned work**, not stale code or a
+contradiction. The project intends to ship it later. Treat it as stale only when the lifecycle or
+supersession metadata indicates the obligation was abandoned, superseded, or already-resolved.
+This is the classic false-positive guard: distinguishing "not yet implemented" from "implemented
+differently."
+
+### Rule 4 — Accepted ADRs beat derived projections; superseded ADRs are historical
+
+An **accepted** `docs/00_ADR.md` entry is normative for the structural decision and architecture
+mechanism it decides, and beats derived architecture/design projections that contradict it. A
+**superseded** ADR is historical evidence, not current authority: it documents what was decided
+and later replaced, and must not be treated as governing. When auditing, check supersession
+metadata before asserting that an older ADR contradicts current code or docs.
+
+### Rule 5 — Incomparable authorities ⇒ needs-authority-decision
+
+If two authorities for the same subject+claim type are **incomparable** (no project rule and no
+fallback row orders them; neither supersedes the other within a stated boundary), the finding
+status is `needs-authority-decision`. **No repair is proposed as settled fact.** See §4. This rule
+is the anti-pattern boundary: never force a winner through a global ranking detached from claim
+type and local process rules.
+
+## 4. Ambiguity protocol
+
+### 4.1 What counts as ambiguous
+
+Authority is ambiguous — and must stop rather than fabricate — in three cases:
+
+| Case | Meaning |
+|------|---------|
+| **Missing** | No normative authority exists for the subject+claim type (e.g. no ADR decides a seam, no PRD line covers a scope question), and no fallback row supplies one |
+| **Incomparable** | Two authorities exist but no rule or fallback row orders them (Rule 5) |
+| **Genuinely ambiguous** | An authority is self-contradictory, underspecified, or its boundary cannot be determined from the artifacts |
+
+### 4.2 What ambiguity means for a finding
+
+- The finding's `status` is `needs-authority-decision` (per [finding-contract.md](./finding-contract.md)).
+- It is an **unresolved HITL item**: it surfaces for the operator to decide, and is never silently
+  resolved by a heuristic or global ranking.
+- `proposed_repair` is left as **none / pending decision** — the skill must not propose a repair as
+  settled fact when authority is unresolved.
+- The finding still records the candidate authorities, the claim paraphrase, and the evidence for
+  both sides, so the operator has everything needed to decide. Uncertainty is preserved, not erased.
+- Low confidence never disappears: ambiguous/missing authority is reported as an unresolved item,
+  not promoted to a definitive conflict and not dropped.
+
+### 4.3 Remediation consequence
+
+Per [remediation-routing.md](./remediation-routing.md), ambiguous authority means **stop for an
+operator decision; do not mutate either side**. The operator decides which authority governs (or
+that an authority needs to be created/updated through its owner surface), and only then can a
+confirmed repair proceed. See §6 for owner surfaces.
+
+## 5. Normative authority vs observed reality
+
+Every finding records **normative authority** and **observed reality** as separate fields, never
+merged:
+
+| Field | What it holds | Example |
+|-------|---------------|---------|
+| `normative_authority` | The claim as the governing artifact states it ("should") | PRD §3: "no background sync" |
+| `observed_reality` | The claim as source/runtime/tests currently show it ("is") | `src/sync.ts` implements background sync |
+
+Keeping them separate is what makes a stale-projection finding legible: the projection says one
+thing, the authority another, the code a third — and collapsing them hides the direction of drift.
+The conflict surface is the **gap** between normative and observed, not either value alone.
+
+## 6. Owner routing for a resolved authority
+
+Once authority is resolved (not ambiguous), a confirmed repair routes through the owning surface.
+This table mirrors [remediation-routing.md](./remediation-routing.md) and ties each owner to the
+authority it governs:
+
+| Owner | Repair route | Governs (claim types) |
+|-------|--------------|----------------------|
+| Task/feature corpus | `sp:spur-cli` / `spur task` / `spur feature`; never direct file writes | Task obligation/status, feature goal and AC |
+| Numbered docs and AGENTS projections | `sp:doc-evolve`; authority first, derived projections second | Process rules, structural decision, product scope, architecture, command surface |
+| Source/tests | create/use a Spur task and route through `sp:spur-dev` / build competencies | Implementation behavior, architecture mechanism |
+| Command/skill capability source | Superskill command/skill lifecycle in the owning plugin source | Command/API/schema surface |
+| Ambiguous authority | **stop** for an operator decision; do not mutate either side | (all, when unresolved) |
+
+Never edit a derived projection before its authority. The authority column of §2 is always the
+owner surface's source of truth; a projection is brought into line with it, not the reverse.
+
+## 7. Worked examples
+
+### Example A — task AC vs code (planned work vs contradiction)
+
+- Subject: `0486` · Claim type: `Task obligation/status`
+- Task `status: todo`, AC not yet implemented in code.
+- Rule 3 applies: the difference is **planned work**, not a contradiction.
+- Normative: task AC states the obligation. Observed: code lacks the feature.
+- Verdict: no conflict (or an informational note), not a `stale`/`contradiction` finding.
+
+### Example B — PRD non-goal vs shipped surface
+
+- Subject: "background sync" · Claim type: `Product scope and non-goals`
+- PRD §3: "no background sync" (normative). `src/sync.ts` implements it (observed).
+- Rule 2 applies: code is authoritative for *what happens*, PRD for *what should happen*.
+- Normative ≠ observed ⇒ gap is a conflict candidate; PRD is the authority, so this is a
+  **contradiction** (shipped surface outside scope) unless a later ADR superseded the non-goal.
+
+### Example C — two ADRs, one superseded
+
+- Subject: "sync seam" · Claim type: `Architecture mechanism`
+- `docs/00_ADR.md`: ADR-014 decides X; ADR-021 supersedes ADR-014 and decides Y.
+- Rule 4 applies: ADR-021 is current authority; ADR-014 is historical evidence.
+- Code implementing X is **stale** against the current authority (ADR-021 → Y), not a contradiction
+  with ADR-014.
+
+### Example D — incomparable authorities
+
+- Subject: "command surface" · Claim type: `Command/API/schema surface`
+- Owning command source and `docs/04_DESIGN.md` disagree, and no ADR/rule orders them, and they are
+  not related as authority↔projection.
+- Rule 5 applies: **incomparable** ⇒ `needs-authority-decision`, unresolved HITL item, no proposed
+  repair, no fabricated winner.
+
+## 8. Related
+
+- Skill entry: [../SKILL.md](../SKILL.md)
+- Comparison and clustering: [comparison-protocol.md](./comparison-protocol.md)
+- Finding/status schema: [finding-contract.md](./finding-contract.md)
+- Owner routing and HITL: [remediation-routing.md](./remediation-routing.md)
+- Process authority: `sp:doc-evolve` · Corpus ownership: `sp:spur-cli` · Lifecycle: `sp:spur-dev` ·
+  Verification: `sp:code-verification`