governance: repair matter-link and integration-state contradictions

[zackees]

Context

The merged corpus contains two confirmed internal-consistency failures:

1. COVERAGE.md says retrieval integration is complete and later says the case-gap audit was completed, but its acceptance table still says the separate case-gap lane is pending integration.
2. paralegal-research/AGENTS.md requires related matters to be linked in both directions. A deterministic scan finds 31 one-way relationships. Examples include PR-0002 -> PR-0001, PR-0003 -> PR-0001, PR-0016 -> PR-0019, and PR-0020 -> PR-0004, while the reverse card omits the relationship. PR-0001 currently has no related matters despite being referenced by many.

These are not legal disagreements. They are contradictory repository state that can make an AI miss relevant research or treat completed work as unavailable.

Proposal

Repair the current integration statement and relationship graph, then add a corpus-consistency validator covering reciprocal matter links, valid identifiers, integration-state vocabulary, and index coverage. Make generated reports derive from canonical metadata where practical.

Acceptance criteria

• COVERAGE.md no longer simultaneously describes the case-gap audit as completed and pending integration.
• Every related_matter_ids edge is reciprocal, or the schema is replaced with explicitly directed relation types such as depends_on, extends, or contrasts_with.
• PR-0001 and other hub matters expose all intended relationships without manual one-way omissions.
• A deterministic validator fails on missing targets, asymmetric reciprocal links, duplicate IDs, unindexed records, and contradictory integration states.
• The validator runs against all current matter records and reports zero unexplained failures.
• Agent instructions state which relationship types must be reciprocal and which may be directed.

Decisions

• Confirmed corpus contradiction, P1 retrieval integrity. No further legal research is required to prove the present inconsistency.
• Prefer explicit directed types if reciprocity is not semantically correct. Blindly mirroring every edge may destroy useful relationship meaning.
• No substantive legal or LICENSE change. This repairs navigation and status only.

Open questions

• Should broad hub matters list every inbound relationship, or should the schema support generated backlinks?
• Which document is canonical for audit-lane completion state so coverage text can be generated or checked?

Related issues

• Parent: audit: adversarially review the paralegal research corpus #19
• Corpus creation: docs: build a license-agnostic copyleft enforcement research corpus #17

[zackees]

Sol adversarial review - 2026-08-25

Verdict: confirmed; leave open. I found no duplicate or default-branch resolution. origin/main and this worktree are both 40ee710, and #26 has no closing PR. #19 is its parent; #24 is adjacent schema work, not a duplicate.

Integration-state finding. I tried to read the statements as different stages, but they concern the same case-gap lane in the same merged commit. COVERAGE.md:22-25 says retrieval integration is complete; line 47 says the case-gap lane is pending integration; lines 107-113 say that completed lane added four decisions. PROPOSITION-MAP.md:56-61 says it is incorporated in PR-0003/PR-0004; search-logs/README.md:15 registers that mapping; both census memos link the log and record the additions; authorities/INDEX.md:113-116 indexes AUTH-0150 through AUTH-0153. Source-access caveats remain valid, but "pending integration" is stale rather than a separate-stage qualification.

Graph reproduction. A PyYAML frontmatter parser over every matters/**/*.md file, independently checked with a syntax-level parser supporting the corpus's inline and block lists, reports:

matters=20 directed_edges=65 reciprocal_pairs=17
reciprocal_directed_edges=34 asymmetric_edges=31
missing_targets=0 self_edges=0

Reproducer core:

from pathlib import Path
import yaml
r = {}
for p in sorted(Path("paralegal-research/matters").rglob("*.md")):
    d = yaml.safe_load(p.read_text(encoding="utf-8").split("---", 2)[1])
    assert d["id"] not in r
    r[d["id"]] = tuple(d.get("related_matter_ids") or ())
e = {(s, t) for s, ts in r.items() for t in ts}
a = {(s, t) for s, t in e if t in r and (t, s) not in e}
print(len(r), len(e), len({(s,t) for s,t in e if s<t and (t,s) in e}),
      len(a), len({(s,t) for s,t in e if t not in r}), len({x for x in e if x[0]==x[1]}))
for x in sorted(a): print(*x, sep=" -> ")

Run with uv run --with pyyaml python path/to/script.py. The 31 asymmetric entries, grouped by source, are:

• PR-0002 -> {PR-0001}; PR-0003 -> {PR-0001}; PR-0004 -> {PR-0001}
• PR-0005 -> {PR-0002, PR-0010}; PR-0006 -> {PR-0001, PR-0005}; PR-0008 -> {PR-0001}
• PR-0009 -> {PR-0002, PR-0003, PR-0004}; PR-0010 -> {PR-0001, PR-0002, PR-0003}
• PR-0011 -> {PR-0001}; PR-0012 -> {PR-0001, PR-0011, PR-0013}; PR-0013 -> {PR-0001}
• PR-0014 -> {PR-0001, PR-0011}; PR-0015 -> {PR-0001, PR-0012, PR-0014}
• PR-0016 -> {PR-0019}; PR-0019 -> {PR-0001, PR-0017}
• PR-0020 -> {PR-0004, PR-0016, PR-0018, PR-0019}

PR-0001 has 12 inbound references and zero outbound references.

Ambiguity correction. Blindly mirroring all 31 is unsafe because some links plausibly mean depends-on, extends, or routes-to. But the schema only has generic related_matter_ids, keeps supersedes separate, and AGENTS.md:113 expressly requires related and superseded matters to be linked both ways; that rule predates this corpus expansion. Thus the current data violates the documented invariant unless directed relation types replace it. The ambiguity confirms a schema defect; it does not invalidate the issue.

Schema loopholes / improved acceptance.

1. Define related_matter_ids as symmetric or migrate each edge, after semantic review, to controlled directed types with explicit inverse/generated-backlink rules; define the inverse of supersedes.
2. Add schema versioning and a YAML-aware validator for duplicate/invalid IDs, duplicate/self/missing targets, reciprocal-field asymmetry, directed-type/inverse rules, and exact equality between record IDs and index rows.
3. Put audit-lane ID, controlled status (planned/in-progress/integrated/deferred), canonical matter targets, and produced authority IDs in one structured canonical record; generate or validate coverage prose from it. Free prose alone cannot support reliable contradiction checking.
4. Add RED-to-GREEN fixtures for every failure class, including the present 31-edge graph, an intentionally directed edge, index extras/omissions, and conflicting audit state. Run the validator in CI and require zero unexplained failures across all 20 matters.
5. Update the matter template and AGENTS.md in the same migration. Current CI only exercises license-header tooling; PR docs: add copyleft enforcement research corpus #18's corpus checks were ad hoc, not a committed validator.

This is retrieval/governance work only. It does not warrant a substantive legal change, a LICENSE edit, or weakening the LEGAL-REVIEW.md attorney gate.