Add the interface engine - verify a workflow's contract by name (#374, PR-B)

[ptr727]

Second of the fidelity series (#374). Consumes fidelity: interface: the audit now verifies a carried workflow honors its fixed contract by name and wiring, never the owned body — the virtual-function signature check.

Change

• spec/audit.py
  • split_jobs(text) — slices a workflow into {job_key: block} by the jobs-level indent, no YAML parser (stdlib), mirroring heading_texts.
  • check_interface(path, contract, text) — required job keys, the ruleset-bound check name:, the release-asset-<branch>-<target> handoff, and per-job required (pattern:/merge-multiple:) and forbidden (artifact-ids:) tokens. All findings DRIFT.
  • An interface unit's absence is DRIFT too (not a hard LETTER) — a workflow's naming varies more than a carried config, so everything here is advisory.
  • --selftest (no network) — 7 fixture cases.
• spec/files.json — two workflow interface entries: test-pull-request.yml (appliesTo: "*", the universal check-workflow-status job + its ruleset-bound name) and build-release-task.yml (build types, the get-version/github-release jobs + artifact handoff + no-artifact-ids: rule).
• AUDIT.md — notes the new check, and fixes pre-existing clause-joining semicolons in this file's comments/docstrings so they don't fester.

Verified

• python3 spec/audit.py --selftest → 7/7 (conformant, missing job+name, renamed check, artifact-ids fork, missing merge-multiple, owned extra-leaf-job no-finding, split_jobs).
• Positive control: the hub's own canonical test-pull-request.yml and build-release-task.yml are conformant (0 findings).
• validate.py green (contracts pass PR-A's value-type guards), lints clean.

Scoping of build-release-task.yml is best-effort (excludes source-only/docs to avoid false "absent" DRIFTs); any mis-scope only yields advisory DRIFTs to triage. It refines as downstreams are audited. Held on develop. PR-C adds the verbatim engine.

[Copilot]

Pull request overview

Adds an interface-fidelity audit path so workflow baseline entries can be verified by their contracted wiring (job keys, required job name:, artifact handoff conventions, and forbidden download patterns) without requiring verbatim workflow bodies. This fits the repo’s broader “carry model” governance by making workflow conformance checkable in a structured, low-false-positive way.

Changes:

• Extend spec/audit.py with a lightweight workflow “jobs” slicer (split_jobs) and an interface-contract checker (check_interface), plus a --selftest fixture suite.
• Add fidelity: interface entries to spec/files.json for test-pull-request.yml and build-release-task.yml with targeted contract fields.
• Update AUDIT.md to document the new interface-conformance check and its DRIFT-only semantics.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
spec/files.json	Adds two fidelity: interface baseline entries with workflow-specific contract fields.
spec/audit.py	Implements the interface engine (split_jobs, check_interface) and wires it into the audit with --selftest.
AUDIT.md	Documents the new workflow interface conformance check as part of the mechanized audit.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

spec/audit.py:205

• check_interface() treats requiredCheckName as a raw substring match across the whole workflow (minus comment-only lines). That can false-pass if the string appears in some other field (including the workflow-level name:) and does not actually appear as a job name: in the required job. Since the contract is about the ruleset-bound job check name, match it as a name: line (and prefer searching within the required job block when there is exactly one required job).

 name = contract.get("requiredCheckName")
if name and name not in code:
findings.append(("DRIFT", f"interface: {path} missing the ruleset-bound check name '{name}'"))
tok = contract.get("artifactNameToken")
if tok and tok not in code:
findings.append(("DRIFT", f"interface: {path} missing the '{tok}<branch>-<target>' artifact handoff"))

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

spec/audit.py:205

• check_interface()'s requiredCheckName scan matches any name: line anywhere in the workflow (including step-level name:). That can false-pass a workflow where the ruleset-bound job name is missing but a step happens to use the same name. Since the contract is explicitly about the ruleset-bound job name, restrict the match to job-level name: keys (the first-level keys inside each job block) and optionally add a selftest case where a step name: equals requiredCheckName but the job-level name is absent.

 name = contract.get("requiredCheckName")
if name and not re.search(r"^\s*name:\s*['\"]?" + re.escape(name) + r"['\"]?\s*$", code, re.M):
findings.append(("DRIFT", f"interface: {path} missing the ruleset-bound check name '{name}' as a job name"))
tok = contract.get("artifactNameToken")
if tok and tok not in code:
findings.append(("DRIFT", f"interface: {path} missing the '{tok}<branch>-<target>' artifact handoff"))

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.