retrieval: align matter schema with doctrine, remedy, and time taxonomy

[zackees]

Context

TAXONOMY.md says every matter should identify controlled doctrine, remedy, and time dimensions. templates/MATTER.md does not provide doctrines, remedies, or a substantive time-scope field, and all 20 current matter memos omit the first two fields.

Today those dimensions are scattered across free-form topics, prose, and filenames. That makes it difficult for an AI to prove that a retrieved memo matches the requested remedy, license version, jurisdiction, and relevant dates. For example, prohibitory injunction, mandatory injunction, specific performance, discovery production, and settlement-only source publication can collapse into the same source-disclosure keyword.

Proposal

Align matter frontmatter with the taxonomy. Add controlled doctrines, remedies, and time_scope metadata; migrate all current matters; retain topics only for supplementary search synonyms. Generate or validate retrieval/index data from those fields.

Acceptance criteria

• templates/MATTER.md contains required doctrines, remedies, and structured time_scope fields with documented allowed forms.
• All 20 current matters populate those fields using TAXONOMY.md values.
• Prohibitory injunction, mandatory injunction, specific performance, discovery production, settlement-only performance, and post-judgment enforcement are independently retrievable.
• A validator rejects missing/unknown controlled values and duplicate incompatible encodings.
• A routing test refuses to call a memo an exact match when jurisdiction, license/version, remedy, actor, conduct, or time scope materially differs.
• Human-facing titles and substantive analysis remain unchanged unless separate research review requires correction.

Decisions

• Confirmed schema defect, P1 retrieval control. The taxonomy and template currently disagree.
• Structured fields supplement prose. They do not replace the facts, assumptions, or counsel questions in each memo.
• No legal conclusion or LICENSE change. This is a retrieval and validation issue.

Open questions

• Should time_scope be a normalized date range, event fields, or both?
• Should the canonical index display every routing dimension or point to a generated machine-readable manifest?
• Which combined remedy values are invalid versus legitimately cumulative?

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

Leave open; the machine-readable schema gap is real, but narrow the issue from ?missing dimensions? to ?non-canonical and unenforced dimensions.? The literal count is confirmed: all 20 matter files omit top-level doctrines, remedies, and time_scope keys. The information itself is not uniformly absent: controlled doctrine/remedy terms already appear in topics, titles, scope prose, and PROPOSITION-MAP.md, and every matter has last_verified. No merged or open PR resolves #23, no duplicate issue was found, and main remains at 40ee7108f4b46b6b8fb1976f5c8b3cd996bdfb42.

This is a retrieval/schema defect, not a substantive legal correction. It should remain behind the existing attorney-review gate.

Reproducible evidence and corrected counts

At origin/main/HEAD 40ee7108:

$matters = @(rg --files paralegal-research/matters -g '*.md')
$matters.Count
# 20

foreach ($key in 'doctrines','remedies','time_scope','last_verified') {
  "${key}=$(@(rg -l "^${key}:" $matters).Count)"
}
# doctrines=0
# remedies=0
# time_scope=0
# last_verified=20

@(rg -l '^licenses: \[\]$' $matters).Count
# 5 (therefore 15 have non-empty license metadata)

Inspecting only the topics frontmatter block against the exact tokens listed in TAXONOMY.md finds:

matters with >=1 exact doctrine token in topics: 9/20
matters with >=1 exact remedy token in topics:   7/20

The doctrine hits are PR-0005, 0006, 0007, 0008, 0009, 0010, 0011, 0014, and 0016. The remedy hits are PR-0001, 0004, 0010, 0012, 0013, 0014, and 0019. These are discoverable with:

rg -n 'topics:.*(formation|condition-covenant|copyright-nexus|preemption|ownership|standing|scope|termination|registration|limitations|defenses|evidence|procedure|conflicts)|^  - (formation|condition-covenant|copyright-nexus|preemption|ownership|standing|scope|termination|registration|limitations|defenses|evidence|procedure|conflicts)$' paralegal-research/matters
rg -n 'topics:.*(prohibitory-injunction|mandatory-injunction|specific-performance|source-disclosure|impoundment|destruction|actual-damages|profits|statutory-damages|fees|declaratory-relief|contempt|settlement-only)|^  - (prohibitory-injunction|mandatory-injunction|specific-performance|source-disclosure|impoundment|destruction|actual-damages|profits|statutory-damages|fees|declaratory-relief|contempt|settlement-only)$' paralegal-research/matters

History confirms this was introduced as one incomplete schema expansion, not later repaired drift:

git log --follow -p -- paralegal-research/templates/MATTER.md
# 40ee710 added licenses/actors/conduct/confidence, but not doctrine/remedy/time.

git log --follow -p -- paralegal-research/TAXONOMY.md
# TAXONOMY.md, its required dimensions, and the 20-matter corpus arrived in 40ee710.

There is no executable research-schema validator. The only validator is tools/license_headers.py; tests/test_license_headers.py and .github/workflows/test.yml test that unrelated header/tooling contract. GitHub checks found no comments or resolving PR on #23 before this review, no later default-branch commit, and no matching issue/PR beyond parent #19. Issue #22 overlaps only verification freshness; #24 is proposition-level authority metadata; neither resolves matter routing metadata. PR #18 created the mismatch and had no substantive review (CodeRabbit skipped the 140-file PR).

What is already represented equivalently?and what is not

• PR-0012 already lists prohibitory-injunction, mandatory-injunction, specific-performance, source-disclosure, impoundment, discovery, and contempt separately in topics, and its short answer/scope explicitly says they are not interchangeable. The proposition map also routes injunction/performance/discovery/contempt separately. The issue's example therefore demonstrates a lack of enforced canonical fields, not an observed collapse in that memo.
• PR-0019 separately treats settlement, consent decrees, contempt, and post-judgment enforcement in topics and prose; PR-0017 separately treats protected discovery. Again, retrieval currently depends on synonym/prose matching rather than a validated dimension.
• All 20 matters have last_verified; 15 have non-empty license/version metadata. PR-0002 expressly states its time/version scope and PR-0004 states its census cutoff. Thus ?time is absent? is too broad. What is absent is a structured representation of substantive applicability dates distinct from verification freshness.
• Titles, directories, question, short_answer, Scope sections, and PROPOSITION-MAP.md often provide doctrine/remedy equivalents. They are human-usable but cannot prove consistent exact-match behavior, detect unknown values, or prevent contradictory duplicates.

Schema loopholes and overengineering risks

1. time_scope conflates four different owners. TAXONOMY.md calls out license-version date, conduct dates, decision date, and verification date. Verification already belongs to last_verified and the freshness work in governance: make stale-source handling operational #22. Decision dates normally belong to authority cards. Conduct dates are often unknown hypothetical inputs, not properties of a general matter. License identity/version is already in licenses. One required time_scope object can duplicate all four and silently disagree with them.
2. Several requested retrieval values are not taxonomy remedy values. ?Discovery production,? ?settlement-only performance,? and ?post-judgment enforcement? appear in retrieval: align matter schema with doctrine, remedy, and time taxonomy #23's acceptance criteria but not in the current remedies list. Discovery may be procedure/evidence; settlement and post-judgment state may be outcome/lifecycle dimensions. TAXONOMY.md itself says ?settlement-only terms,? which is not a syntactically unambiguous identifier.
3. A remedies tag must mean ?analyzed/requested dimension,? never ?legally available or awarded.? PR-0001/0012 analyze source performance partly to reject automatic availability. A bare tag can be promoted into a legal conclusion unless the schema documents coverage semantics and proposition treatment remains separate.
4. Required population can manufacture false precision. PR-0002, 0016, 0017, 0018, 0019, and 0020 deliberately use licenses: [] because they are license-agnostic or comparative. Some matters deliberately exclude a remedy. The schema needs distinct meanings for [], unknown, not-applicable, and wildcard/general coverage; otherwise ?populate all 20? encourages filler values.
5. Existing controlled dimensions already contain aliases/extensions. Conduct uses both continue-after-termination and post-termination-conduct, plus values absent from the listed vocabulary (aggregate, import, preserve, provide-hosted-service, provide-source). Actors include beneficiary, defendant, investigator, and licensee; the ?other material role? escape hatch makes unknown-value rejection impossible unless extensions are registered. License identifiers also vary between names such as GNU GPL versions 2 and 3 and SPDX-like GPL-2.0/GPL-3.0.
6. Exact matching is not string equality. US-federal, US-Ninth-Circuit, California contract law, and license-agnostic baselines have hierarchy/wildcard semantics. A query can be a subset of a broad memo yet still only be analogous because a material fact is unresolved. Multi-valued remedies can be alternatives, cumulative requests, contrasts, or explicit exclusions.
7. Generated retrieval data can become a second source of truth. Matter frontmatter should remain canonical; any manifest/index should be derived or deterministically checked, not independently maintained.

More precise acceptance criteria

Repository defects, testable without making legal conclusions:

• Define one versioned, machine-readable matter schema and one canonical vocabulary source. Document each field as ?issues analyzed/routing coverage,? not outcome or availability.
• Add doctrines and a remedy-routing field (prefer an explicit name such as remedy_questions or document remedies equally clearly). Define whether each key is required and give non-overlapping semantics for empty, unknown, not-applicable, and general/wildcard coverage.
• Replace the single vague time_scope requirement with typed, non-duplicative semantics. At minimum separate research verification (last_verified/governance: make stale-source handling operational #22) from matter applicability facts. Keep authority decision dates on authority cards; represent query-supplied conduct intervals as required match inputs when the memo itself has no fixed dates.
• Resolve the taxonomy/acceptance mismatch for discovery, settlement-only terms, consent decrees, and post-judgment enforcement. Decide whether they are remedy, procedure, proposition treatment, or lifecycle values before migration.
• Migrate all 20 matters, but permit a validated explicit empty/not-applicable state where the memo deliberately does not address a dimension. Migration must preserve prose qualifications and must not infer remedy availability.
• Normalize or formally register existing actor, conduct, jurisdiction, and license values as part of the validator rollout. At minimum reject the existing duplicate encoding post-termination-conduct versus continue-after-termination; do not report schema success while old routing dimensions remain unconstrained.
• Add a read-only validator with stable machine-readable output that rejects missing keys, unknown values, duplicate aliases, contradictory wildcard/specific values, malformed dates/intervals, and drift between generated retrieval output and matter frontmatter.
• Define candidate-match semantics and test observable classifications such as exact, analogous, and no-match. Tests must cover: jurisdiction hierarchy/conflict; exact license/version mismatch; license-agnostic versus unspecified; requested actor/conduct subset; unknown dates; disjoint/inclusive date ranges; remedies analyzed versus remedies excluded; and a broad memo with a material unresolved fact that cannot be called exact.
• Add the validator/tests to CI. Generate any manifest/index solely from canonical frontmatter or validate a committed artifact byte-for-byte against deterministic output.
• Keep human-facing titles and analysis unchanged except through a separate research/attorney review. No schema value may imply legal_review: approved or turn requested/settlement relief into awarded relief.

Suggested RED -> GREEN focused repro: first add fixtures showing that the current parser/validator accepts a missing remedy key, unknown doctrine, aliased post-termination conduct, AGPL-3.0 versus GPL-3.0 mismatch, specific-license query against licenses: [], discovery-as-awarded-remedy misuse, and disjoint conduct dates; then implement the schema/matcher so those fixtures produce the documented non-exact/error states.

Attorney/retrieval-owner questions

• Does a remedy field mean merely ?this memo analyzes the question,? and is that wording sufficient to prevent users or downstream agents from treating the tag as an available/awarded remedy?
• Should discovery, consent-decree obligations, settlements, and post-judgment enforcement be separate procedural/outcome dimensions rather than remedies?
• Which time facts are legally material for routing each matter, and which belong only to the query or authority record? Who resolves conflicting license, conduct, decision, and verification dates?
• May a license-agnostic or nationwide baseline ever be an exact match for a license-/circuit-specific question, or must it always be analogous until the specific text/forum is checked?
• Are multiple remedy values cumulative, alternative, contrasted, or excluded, and does the schema need relation/polarity rather than a flat list?
• Who owns and approves the controlled vocabulary and alias migrations, and should counsel review changes that alter retrieval coverage even when prose remains unchanged?
• Is the intended consumer a CI validator, a generated manifest, or executable answer-routing code? ?Refuses to call exact? needs a named consumer and testable output contract.