ci(policy): require every published contract to trace to a governing requirement

docs/explain/reference/README.md

@@ -24,6 +24,9 @@ themselves normative specifications or ADRs.
 - [published-schema-coverage.md](published-schema-coverage.md)
   - The `ASR-501` rule requiring every published schema to carry corpus,
     formal, or declared coverage evidence
+- [published-contract-requirement-tracing.md](published-contract-requirement-tracing.md)
+  - The rule requiring every published schema to trace to a live governing
+    requirement through an `IMPLEMENTS → SPEC` link
 - [assessment-semantics.md](assessment-semantics.md)
   - Architecture guardrails for `SEM-206` assessment semantics work
 - [objective-semantics.md](objective-semantics.md)

docs/explain/reference/published-contract-requirement-tracing.md

@@ -0,0 +1,101 @@
+# Published-contract requirement tracing
+
+Every schema under `contracts/schemas/` is a normative published contract
+(`ADR-009` §7). `tools/check_schema_publication.py` proves the inventory and
+`tools/check_schema_coverage.py` proves that something exercises each contract.
+Neither names the requirement that governs a contract, so a schema could be
+published with no owner. `experiment-authoring-input-v1` was linked to `EXP-736`
+only after review (issue #675, PR #711).
+
+`tools/check_contract_requirement_tracing.py` closes that gap. It runs as the
+`policy / published contract requirement tracing` stage of `nox -s policy` and
+reads the whole published inventory on every run, not the changed-file set.
+
+## The rule
+
+A published contract is **traced** when at least one requirement record under
+`docs/requirements/<UID>/requirement.md` whose status is `ACTIVE` or `DRAFT`
+carries this link to the contract's exact schema path:
+
+```markdown
+- IMPLEMENTS → SPEC `contracts/schemas/<family>/<contract-id>.json` (<contract-id> published schema)
+```
+
+- **Only `IMPLEMENTS → SPEC` counts.** `CONSTRAINS`, `DOCUMENTS`, `TESTS`, and
+  `VERIFIES` links record a relation other than ownership. An `IMPLEMENTS` link
+  to a schema path typed as `CONFIG`, `SCHEMA`, or `DOCUMENTATION` does not
+  count as ownership either. Retype it to `SPEC` only where it records that the
+  requirement owns the contract. Some such links record a narrower relation,
+  such as the vocabulary or temporal rules one requirement adds to a shared SDL
+  schema; leave those as they are.
+- **`CODE_FILE` links never count.** A module link cannot say which contract a
+  requirement governs. `raes_contracts/contracts/bundle.py` generates every
+  published contract and several requirements link it as a `CODE_FILE`, so
+  accepting module links would mark every contract traced.
+- **The path must match exactly.** A link to a document beside the schema,
+  such as the catalog `contracts/concept-authority/behavioral-relations-v1.json`,
+  does not trace `contracts/schemas/concept-authority/behavioral-relations-v1.json`.
+- **`DRAFT` owners qualify.** Requirement governance admits a `DRAFT`
+  requirement for implementation work, and the owning requirements of several
+  contract families, such as the time and participant-budget contracts, are
+  still `DRAFT`. Requiring an `ACTIVE` owner would force a link to a less
+  precise requirement.
+- **`DEPRECATED` and `ARCHIVED` owners never count.** These are the statuses
+  `tools/policy/requirement_governance.py` rejects for implementation work. A
+  contract whose only owner is retired is untraced until a live requirement
+  owns it.
+- **One live owner is enough.** A contract may have several.
+
+The gate reads requirement records offline through
+`RepositoryRequirementClient`, the parser behind the repository requirement
+source that `tools/policy/requirement_order.yaml` selects. It makes no Ground
+Control request, so it runs on every CI policy run. A record that the parser
+rejects, including a malformed traceability line, a symlinked record, or a
+directory that is not a canonical requirement UID, fails closed as
+`[contract-requirement-record-unreadable]` and owns nothing.
+
+## The inventory
+
+The denominator is every `contracts/schemas/**/*.json` file. The contracts lane
+already fails when that tree disagrees with `schema_bundle()`
+(`tools/check_generated_schemas.py`) or with the publication manifest
+(`tools/check_schema_publication.py`), so the gate reads the tree rather than
+regenerating the bundle. `test_issue_712_contract_requirement_tracing.py` pins
+the three inventories to one set. A removed schema leaves the tree, so its
+tombstone needs no owner.
+
+## Repairing a finding
+
+`[contract-requirement-trace-missing]` names the schema path that has no live
+owner. Add the `IMPLEMENTS → SPEC` line to the Traceability section of the
+requirement that governs the contract, in the same pull request that publishes
+a new schema. Choose the owner by evidence, strongest first:
+
+1. A live requirement already records the exact schema path under another link
+   or artifact type, or links the contract's own catalog or publication record.
+2. The pull request or commit that published the schema, or its issue,
+   declared the requirement.
+3. The requirement's statement names the contract's subject. Prefer a
+   requirement that also links the contract's defining module, tests, or
+   governing ADR.
+
+On a branch that requirement governance checks, the edited record is a changed
+file like any other. Where `tools/policy/requirement_order.yaml` maps ownership
+roots to the phase of a requirement governing the branch, including one a scope
+file binds the record to, the record must fall inside them. Otherwise
+governance reports `requirement-ownership-mismatch`. Some phases, such as
+`runtime-core`, own schema paths but not their own requirement records.
+
+Do not link a requirement only to turn the gate green. Do not waive a finding
+through `tools/policy/exceptions.yaml` because a repair is inconvenient. The
+waiver mechanism exists for a finding that is factually wrong.
+
+## Reporting
+
+```console
+$ uv run --project implementations/python --frozen \
+    python tools/check_contract_requirement_tracing.py --report
+```
+
+The report lists every published contract with its live owners, marks a
+contract without one as `UNTRACED`, and never gates.

docs/requirements/ACT-605/requirement.md

@@ -34,3 +34,5 @@ Requirement inventory expansion. Realistic scenarios require first-class specifi
 - TESTS → TEST `implementations/python/tests/test_dsl_437_snapshot_durability_conformance.py` (Autonomous participant durability and conformance coverage)
 - IMPLEMENTS → CODE_FILE `implementations/python/packages/raes_processor/compiler/participant_autonomous_execution.py` (Autonomous participant runtime compilation)
 - IMPLEMENTS → CODE_FILE `implementations/python/packages/raes/semantics/participant_behavior/__init__.py` (Autonomous participant semantic validation)
+- IMPLEMENTS → SPEC `contracts/schemas/participant-runtime/participant-execution-control-v1.json` (participant-execution-control-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/participant-runtime/participant-execution-service-state-v1.json` (participant-execution-service-state-v1 published schema)

docs/requirements/ACT-610/requirement.md

@@ -23,7 +23,7 @@ Requirement inventory expansion. Defensive behavior needs its own expressible vo
 
 - IMPLEMENTS → GITHUB_ISSUE `210` (Defensive Behavior Vocabularies (ACT-610))
 - IMPLEMENTS → CONFIG `contracts/concept-authority/controlled-vocabularies-v1.json` (Governed participant defensive behavior vocabulary)
-- IMPLEMENTS → CONFIG `contracts/schemas/concept-authority/nist-csf-defensive-categories-source-v1.json` (NIST CSF defensive category source schema)
+- IMPLEMENTS → SPEC `contracts/schemas/concept-authority/nist-csf-defensive-categories-source-v1.json` (NIST CSF defensive category source schema)
 - IMPLEMENTS → CONFIG `contracts/concept-authority/nist-csf-defensive-categories-source-v1.json` (Pinned NIST CSF 2.0 defensive category source)
 - IMPLEMENTS → SPEC `contracts/schemas/concept-authority/external-concept-bindings-v1.json` (Generic authored defensive behavior classification contract)
 - IMPLEMENTS → CODE_FILE `implementations/python/packages/raes_contracts/external_concept_bindings.py` (Neutral NIST CSF source snapshot adapter)

docs/requirements/ACT-611/requirement.md

@@ -30,3 +30,5 @@ Requirement inventory expansion. Scenarios need to describe autonomous system be
 - IMPLEMENTS → GITHUB_ISSUE `211` (Autonomous Service And Agent Behavior Vocabularies (ACT-611))
 - TESTS → TEST `implementations/python/tests/test_external_concept_bindings.py` (External concept binding production-path tests)
 - TESTS → TEST `tools/check_autonomous_behavior_vocabularies.py` (Autonomous behavior vocabulary source integrity checker)
+- IMPLEMENTS → SPEC `contracts/schemas/concept-authority/fipa-communicative-acts-source-v1.json` (fipa-communicative-acts-source-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/concept-authority/w3c-activitystreams-activity-types-source-v1.json` (w3c-activitystreams-activity-types-source-v1 published schema)

docs/requirements/ACT-614/requirement.md

@@ -91,3 +91,4 @@ Requirement inventory expansion. Participant behavior over time is a first-class
 - TESTS → TEST `implementations/python/tests/test_issue_898_participant_execution_control.py` (Execution-control regression)
 - TESTS → TEST `implementations/python/tests/test_issue_1181_unified_control_plane_mutations.py` (Control-plane mutation regression)
 - TESTS → TEST `implementations/python/tests/test_participant_concurrent_batch_reservations.py` (Concurrent reservation regression)
+- IMPLEMENTS → SPEC `contracts/schemas/participant-runtime/participant-execution-binding-v1.json` (participant-execution-binding-v1 published schema)

docs/requirements/API-402/requirement.md

@@ -57,3 +57,11 @@ Current state: implemented. Portable live-execution contracts are required so in
 - IMPLEMENTS → CODE_FILE `implementations/python/packages/raes_contracts/contracts/_backend_operation_exports.py` (Public operation contract facade exports)
 - IMPLEMENTS → CODE_FILE `implementations/python/packages/raes_backend_stubs/manifest.py` (Keep operation supervision opt-in; legacy stub does not advertise an unimplemented provider)
 - IMPLEMENTS → CODE_FILE `implementations/python/packages/raes_reference_backend/manifest.py` (Keep operation supervision opt-in for reference emulation)
+- IMPLEMENTS → SPEC `contracts/schemas/control-plane/backend-operation-capabilities-v1.json` (backend-operation-capabilities-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/control-plane/backend-operation-control-v1.json` (backend-operation-control-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/control-plane/backend-operation-request-v1.json` (backend-operation-request-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/control-plane/backend-operation-response-v1.json` (backend-operation-response-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/control-plane/evaluation-history-event-stream-v1.json` (evaluation-history-event-stream-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/control-plane/evaluation-result-envelope-v1.json` (evaluation-result-envelope-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/control-plane/workflow-history-event-stream-v1.json` (workflow-history-event-stream-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/control-plane/workflow-result-envelope-v1.json` (workflow-result-envelope-v1 published schema)

docs/requirements/API-403/requirement.md

@@ -29,3 +29,4 @@ Current state: implemented. A per-target control-plane contract is required so r
 - CONSTRAINS → SPEC `contracts/schemas/control-plane/workflow-cancellation-request-v1.json` (Workflow Cancellation Request Schema)
 - TESTS → TEST `implementations/python/tests/test_runtime_control_plane.py` (Runtime Control Plane Tests)
 - TESTS → TEST `implementations/python/tests/test_runtime_control_plane_api.py` (Runtime Control Plane API Tests)
+- IMPLEMENTS → SPEC `contracts/schemas/control-plane/workflow-cancellation-request-v1.json` (workflow-cancellation-request-v1 published schema)

docs/requirements/API-406/requirement.md

@@ -29,3 +29,5 @@ Requirement inventory expansion. Participant behavior requires portable external
 - TESTS → TEST `implementations/python/tests/test_participant_backend_contracts.py` (Participant backend-contract carrier fixture and schema tests)
 - IMPLEMENTS → CONFIG `contracts/profiles/backend/full-remote-control-plane.json` (Full remote control-plane backend profile API-406 carrier requirements)
 - TESTS → TEST `implementations/python/tests/test_runtime_conformance.py` (API-406 carrier profile and fixture-suite conformance tests)
+- IMPLEMENTS → SPEC `contracts/schemas/participant-runtime/participant-lifecycle-event-v1.json` (participant-lifecycle-event-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/participant-runtime/participant-observation-envelope-v1.json` (participant-observation-envelope-v1 published schema)

docs/requirements/API-407/requirement.md

@@ -79,3 +79,5 @@ Requirement inventory expansion. Participant-feature boundaries need to be expli
 - IMPLEMENTS → CODE_FILE `implementations/python/packages/raes_runtime/mixed_runtime_handoff_execution.py` (Effective native transfer and time-service readback enforcement)
 - IMPLEMENTS → CODE_FILE `implementations/python/packages/raes_runtime/mixed_runtime_result.py` (Evidence-bounded outcome settlement)
 - TESTS → TEST `implementations/python/tests/test_issue_1355_mixed_mapping_time.py` (Missing support, stale time, mapped execution, and evidenced stage witnesses)
+- IMPLEMENTS → SPEC `contracts/schemas/control-plane/mixed-backend-execution-binding-v1.json` (mixed-backend-execution-binding-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/control-plane/mixed-backend-stage-report-v1.json` (mixed-backend-stage-report-v1 published schema)

docs/requirements/API-408/requirement.md

@@ -30,3 +30,5 @@ Requirement inventory expansion. Participant execution must be observable throug
 - TESTS → TEST `implementations/python/tests/test_runtime_control_plane.py` (Runtime participant retrieval projection tests)
 - TESTS → TEST `implementations/python/tests/test_runtime_control_plane_api.py` (HTTP participant retrieval route tests)
 - TESTS → TEST `implementations/python/tests/test_act_614_temporal_durability.py` (Temporal assessments through history retrieval and durable readback)
+- IMPLEMENTS → SPEC `contracts/schemas/control-plane/participant-history-view-v1.json` (participant-history-view-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/control-plane/participant-status-view-v1.json` (participant-status-view-v1 published schema)

docs/requirements/API-411/requirement.md

@@ -25,3 +25,4 @@ Requirement inventory expansion. Participant-local outcomes need portable extern
 - DOCUMENTS → SPEC `specs/formal/runtime-contracts/participant-backend-contracts.md` (Participant backend-facing contracts formal design (API-411 outcome reports))
 - DOCUMENTS → SPEC `contracts/schemas/participant-runtime/participant-outcome-report-v1.json` (Generated participant outcome report schema)
 - TESTS → TEST `implementations/python/tests/test_participant_backend_contracts.py` (Participant outcome-report fixture and schema tests)
+- IMPLEMENTS → SPEC `contracts/schemas/participant-runtime/participant-outcome-report-v1.json` (participant-outcome-report-v1 published schema)

docs/requirements/API-412/requirement.md

@@ -27,3 +27,4 @@ Current state: implemented. Processor manifests now publish a processor-specific
 - DOCUMENTS → DOCUMENTATION `contracts/schemas/README.md` (Published Contract Schemas Overview)
 - DOCUMENTS → DOCUMENTATION `docs/explain/sdl/runtime-architecture.md` (SDL Runtime Architecture)
 - CONSTRAINS → SPEC `contracts/schemas/processor-manifest/processor-manifest-v2.json` (Processor Manifest Schema v2)
+- IMPLEMENTS → SPEC `contracts/schemas/processor-manifest/processor-manifest-v2.json` (processor-manifest-v2 published schema)

docs/requirements/API-417/requirement.md

@@ -17,3 +17,8 @@ The ecosystem shall define plain-data contracts for participant episode initiali
 ## Rationale
 
 Primary-source refresh shows that episode lifecycle handling needs portable external contracts rather than backend-local conventions.
+
+## Traceability
+
+- IMPLEMENTS → SPEC `contracts/schemas/control-plane/participant-episode-history-event-stream-v1.json` (participant-episode-history-event-stream-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/control-plane/participant-episode-state-envelope-v1.json` (participant-episode-state-envelope-v1 published schema)

docs/requirements/API-418/requirement.md

@@ -17,3 +17,10 @@ The ecosystem shall define plain-data contracts for participant budgets, quotas,
 ## Rationale
 
 Primary-source refresh shows that participant budgets and quota consumption need portable reporting surfaces if runs and benchmarks are to remain comparable.
+
+## Traceability
+
+- IMPLEMENTS → SPEC `contracts/schemas/participant-runtime/participant-resource-budget-event-v1.json` (participant-resource-budget-event-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/participant-runtime/participant-resource-budget-policy-v1.json` (participant-resource-budget-policy-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/participant-runtime/participant-resource-budget-state-v1.json` (participant-resource-budget-state-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/participant-runtime/participant-resource-pool-capacity-v1.json` (participant-resource-pool-capacity-v1 published schema)

docs/requirements/API-421/requirement.md

@@ -21,3 +21,6 @@ Independent processors and backends need explicit external declarations for how
 ## Traceability
 
 - DOCUMENTS → SPEC `https://fmi-standard.org/docs/3.0.2/` (FMI 3.0.2 Specification)
+- IMPLEMENTS → SPEC `contracts/schemas/time/realized-time-model-v1.json` (realized-time-model-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/time/time-model-v1.json` (time-model-v1 published schema)
+- IMPLEMENTS → SPEC `contracts/schemas/time/time-runtime-state-v1.json` (time-runtime-state-v1 published schema)

docs/requirements/API-423/requirement.md

@@ -67,3 +67,4 @@ API-406 and API-409 provide adjacent carriers, but no common contract records th
 - IMPLEMENTS → DOCUMENTATION `docs/migration/participant-information-flow-control.md` (Participant information-flow control migration guide)
 - TESTS → TEST `implementations/python/tests/test_public_docs_policy.py` (Executable participant-control public guide claim example)
 - DOCUMENTS → DOCUMENTATION `docs/public/participant-control.md` (Participant input and output control guide)
+- IMPLEMENTS → SPEC `contracts/schemas/profiles/participant-boundary-flow-policy-v1.json` (participant-boundary-flow-policy-v1 published schema)

docs/requirements/ASR-501/requirement.md

@@ -51,3 +51,4 @@ Current state: partially implemented. Checked-in normative schemas exist under c
 - IMPLEMENTS → CODE_FILE `tools/schema_coverage/_classify.py` (Published inventory to covering-leg join)
 - TESTS → TEST `implementations/python/tests/test_issue_1330_schema_coverage.py` (Published-schema coverage gate and backfilled contract corpora tests)
 - IMPLEMENTS → GITHUB_ISSUE `1330` (Issue #1330 detect missing fixture or formal coverage for published schemas)
+- IMPLEMENTS → SPEC `contracts/schemas/profiles/raes-semantic-invariants-v1.json` (raes-semantic-invariants-v1 published schema)

docs/requirements/ASR-511/requirement.md

@@ -24,7 +24,7 @@ Requirement inventory expansion. Mature ecosystems need explicit validation-stre
 - IMPLEMENTS → ADR `docs/decisions/adrs/adr-072-validation-and-admission-profiles.md` (ADR-072 validation and admission profiles)
 - IMPLEMENTS → SPEC `specs/formal/validation-admission-profiles/README.md` (Validation and admission profiles formal specification)
 - IMPLEMENTS → CONFIG `contracts/profiles/validation/validation-profile-catalog-v1.json` (Validation profile catalog v1)
-- IMPLEMENTS → CONFIG `contracts/schemas/profiles/validation-profile-catalog-v1.json` (Published validation profile catalog schema v1)
+- IMPLEMENTS → SPEC `contracts/schemas/profiles/validation-profile-catalog-v1.json` (Published validation profile catalog schema v1)
 - TESTS → TEST `implementations/python/tests/test_validation_profiles.py` (Validation profile catalog tests)
 - DOCUMENTS → DOCUMENTATION `docs/decisions/issue-258-asr-511-layered-validation-profiles-preflight.md` (ASR-511 layered validation profiles design boundary)
 - DOCUMENTS → DOCUMENTATION `contracts/README.md` (Validation profile catalog contract documentation)