feat(briefing): add explainable materiality routing

[bartytime4life]

Status

PROPOSED / DRAFT. This pull request completes the previously partial BriefingSignal materiality-and-routing branch as one deterministic, fixture-first, no-network review slice. It performs no GitHub issue mutation, source activation or retrieval, evidence construction, policy or review decision, lifecycle promotion, proof emission, release, deployment, publication, or repository-setting change.

Authoring merge base: main@6c13e45d11aede489af6e11eef67d096fe3869c7
Hosted comparison base: main@fd04e0aa578e1da5cf6b9b36f3b002ddc01dad63
Exact branch head: d597536c7e4bd70c9338b208f2a421fb5ee447f2
Tested pull-request merge ref: 13a9cd1fabd076d5ff071a4e584845c17ba56b69

Goal

Make BriefingSignal priority and proposed issue routing reproducible from explicit dimensions, finite reason codes, bounded mandatory overrides, current deduplication state, official-support posture, dependency state, safety state, and modeling readiness—without letting the signal create authority or perform the proposed operation.

Why this repair was required

The branch already contained 1.2 fixtures, materiality tests, documentation, workflow wiring, and route_briefing_signals.py, but it was not dependency-closed:

• the canonical schema still declared profile 1.1.0 and the older four-field materiality object;
• the route tool imported compute_materiality_score, compute_materiality_priority, compute_materiality_reason_codes, and compute_routing_disposition, but those functions did not exist in the validator;
• existing core tests still expected two valid fixtures and schema 1.1.0; and
• the two worked examples still used the old materiality representation.

This pull request closes those exact gaps rather than opening a second branch or parallel contract/schema family.

Source and doctrine basis

The supplied KFM_Briefing_to_System_Integration_Architecture.docx treats daily briefing prose as a non-authoritative discovery input, identifies materiality and routing as deterministic control-plane behavior, requires duplicate suppression and finite dispositions, and explicitly forbids a direct path from briefing narrative to evidence, release, publication, or public truth.

Placement follows existing responsibility roots and accepted ADR-0029:

• contracts/governance/ — semantic meaning;
• schemas/contracts/v1/governance/ — machine shape;
• fixtures/contracts/v1/governance/briefing_signal/ — exact synthetic candidates;
• tools/validators/governance/ — deterministic validation and dry-run tooling;
• tests/governance/ — enforceability;
• examples/briefing_integration/ — bounded worked examples;
• .github/workflows/briefing-integration.yml — existing read-only orchestration;
• data/receipts/generated/ — authoring provenance.

No new responsibility root, policy authority, source registry, lifecycle store, proof lane, release family, or public surface is created.

Implemented

• Advances the proposed BriefingSignal machine profile to 1.2.0.
• Adds ten closed 0–5 materiality dimensions:
  • public safety;
  • repository integrity;
  • geospatial relevance;
  • recurrence;
  • reuse value;
  • authority quality;
  • time sensitivity;
  • rights/sensitivity risk;
  • identity uncertainty; and
  • implementation readiness.
• Adds deterministic weighted scoring with a finite -20..80 range.
• Adds explicit thresholds:
  • P0 >= 55 or valid mandatory override;
  • P1 = 35..54;
  • P2 = 20..34;
  • P3 = 1..19;
  • IGNORE <= 0.
• Adds exact ordered reason-code reproduction.
• Adds bounded mandatory overrides for:
  • ACTIVE_PUBLIC_SAFETY_CONFLICT;
  • UNEXPECTED_REPOSITORY_MERGE; and
  • PUBLIC_INTERNAL_STORE_BYPASS.
• Adds deterministic route precedence for:
  • existing-issue updates;
  • duplicate no-action;
  • unsafe rejection;
  • dependency hold;
  • corrective issue candidates;
  • source-discovery issue candidates;
  • object-model issue candidates; and
  • low-priority/no-routable-work no-action.
• Expands finite dispositions without granting mutation permission.
• Adds five schema-invalid fixtures and six schema-valid semantic-negative fixtures.
• Adds six explicit valid routing profiles.
• Migrates the Hays worked example to score 26 / P2 and the GMD inventory to score 37 / P1; both still resolve to UPDATE_EXISTING_ISSUE because issue Model Kansas water-planning, grant, and regional-governance events #1647 already owns the bounded work.
• Adds generated provenance covering the completed schema, validator, direct tests, examples, and the hosted-test correction.

Validation before hosted execution

Check	Outcome
Draft 2020-12 meta-schema validation of the closed 1.2 schema	PASS
Python compilation for the completed validator and updated core test	PASS
Hays and GMD example validation against the completed schema/validator	PASS
Hays materiality/routing reproduction	PASS — score 26, P2, existing-issue update
GMD materiality/routing reproduction	PASS — score 37, P1, existing-issue update
Exact score mismatch finding	PASS
Exact priority mismatch finding	PASS
Exact reason-code mismatch finding	PASS
Exact routing disposition mismatch finding	PASS
Exact routing reason-code mismatch finding	PASS
Generated receipt path/hash/truth-label self-check	PASS

Hosted correction and exact-head validation

The first pull-request run at prior head b9c4bc7ca34315ced60ec4387013ffa00d9b4b63 exposed one feature-specific test drift. The multi-file dedup test changed a candidate from DUPLICATE to UNRESOLVED but retained the old duplicate-only routing reason, so the single-file 1.2 validator correctly rejected it before the intended cluster-level negative could run.

The correction updates that synthetic mutation to LOW_PRIORITY_NO_ACTION, preserving per-file validity while still proving DUPLICATE_CLASSIFICATION_REQUIRED and PRIMARY_SIGNAL_REFERENCE_REQUIRED at the multi-file boundary. No validator, schema, or workflow check was weakened.

At exact head d597536c7e4bd70c9338b208f2a421fb5ee447f2, GitHub tested merge ref 13a9cd1fabd076d5ff071a4e584845c17ba56b69:

• 35 of 38 pull-request workflows succeeded.
• briefing-integration succeeded in both jobs.
• The focused BriefingSignal suite ran 30 tests, all passing.
• Six valid fixtures plus two worked examples passed the completed validator.
• All five structural negatives failed closed as expected.
• All six schema-valid semantic negatives failed closed with their exact reviewed findings.
• The clustering dry run emitted five deterministic clusters and six proposed operations without mutation authority.
• The materiality/routing dry run evaluated eight signals and reproduced Hays 26/P2, GMD 37/P1, mandatory P0 correction, P1 source discovery, dependency hold, unsafe rejection, duplicate no-action, and low-priority no-action.
• The 13-test TemporalAuthorityEnvelope regression passed, as did its positive and exact-negative fixture run.
• The water-planning anti-collapse and RAC-registry job succeeded.
• schema-validation, validator-suite, contracts-validate, contract-drift, link-check, codeql, promotion-gate, ui-build, e2e-smoke, policy-test, and the other successful domain/regression workflows passed.

Unrelated inherited failures

Three workflows remain red, all outside this pull request's 42-path scope:

1. domain-roads-rail-trade / validate-roads-rail-trade fails its remaining-scaffold readiness call with no_python_files; the proof and publish-dry-run jobs succeed. This PR changes no Roads/Rail/Trade path or readiness command.
2. rollback-drill / simulate-rollback fails because the current release RollbackCard x-kfm metadata no longer matches that workflow's frozen placeholder expectation.
3. release-dry-run / rollback-card-presence fails on the same current RollbackCard metadata mismatch; its candidate-assembly and promotion-gate jobs succeed.

This pull request changes no RollbackCard schema, contract, validator, workflow, fixture, release card, Roads/Rail/Trade file, or related policy path. These are inherited repository-readiness findings, not BriefingSignal regressions. No check was bypassed, approved, manually rerun, or weakened.

Workflow safety

The existing briefing-integration workflow retains:

• ordinary pull_request, push to main, and manual dispatch triggers;
• permissions: contents: read;
• immutable checkout and Python action SHAs;
• GitHub-hosted runners;
• no secrets, OIDC, comments, artifacts, deployment, release, publication, or write permission;
• stable workflow and job identities.

The workflow runs the full BriefingSignal identity/dedup/materiality/routing suite, current fixtures/examples, both dry-run tools, structural negatives, semantic negatives, TemporalAuthorityEnvelope regressions, and the existing water-planning anti-collapse suite.

Trust boundary

A green result proves only the proposed schema, parser, identity, materiality, override, routing, fixture, deterministic-output, and no-network behavior. It does not prove a briefing claim, source authority, current real-world status, GitHub authorization, EvidenceBundle closure, policy approval, human review, issue mutation, promotion, release readiness, deployment, or publication safety.

Every dry-run report retains:

{
  "authority_created": false,
  "repository_mutation_allowed": false
}

Base drift and remote verification

The branch is intentionally not force-rebased. GitHub successfully constructed and tested a conflict-free merge ref against main@fd04e0aa578e1da5cf6b9b36f3b002ddc01dad63; the pull request remains mergeable. The final changed-path inventory contains exactly 42 briefing-governance, fixture, test, tool, workflow, example, documentation, and generated-receipt paths—none from the three inherited failure families.

Generated receipt

data/receipts/generated/genrec-briefing-materiality-routing-20260804.json

Human review state remains pending. The receipt is provenance only and is not approval or merge authority.

Rollback

Before merge, close this draft and abandon agent/briefing-materiality-routing-20260804. After an authorized merge, revert the scoped materiality-routing commits through a reviewed corrective pull request. No live source, GitHub issue, lifecycle object, evidence object, policy decision, proof, release, deployment, or published state requires restoration.

Reviewer disposition

DRAFT — READY FOR HUMAN REVIEW OF THE BOUNDED FEATURE, WITH THREE INHERITED REPOSITORY READINESS FAILURES RECORDED. Do not mark ready, merge, release, deploy, publish, activate a source, mutate an issue, or change repository settings from this pull request.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.