Skip to content

P1: Bind Every WORKFLOW.md Section 4 Guarantee to an Audit Check, or Mark It Guidance #1318

Description

@ptr727

Part of #1311. Priority: next. One pull request for the binding and validator, then the section 4 and 5 sweep.

Why

WORKFLOW.md is 12,500 words, and 32 open issues touch it. Most are one shape: a section 4 guarantee that the shipped workflows falsify or that a reader cannot act on (#1200, #1202, #1219, #1242), a section 5 audit step that checks something no section 4 guarantee states (#1227), or a condensed catalog item that dropped the clause carrying the meaning (#1212, #1250). The coupling between the contract text and spec/audit.py is entirely in prose, so the two drift and only a whole read notices.

Scope

  • Give every D-item in section 4 a stable id (they have one) and a check: binding naming the spec/audit.py check or checks that measure it, or the word guidance where no mechanical check exists or can exist.
  • Extend spec/validate.py to fail when a D-item names a check that does not exist, when a check names a D-item that does not exist, and when a D-item has neither a check nor guidance. Add the test that watches each fail.
  • Make section 5A's static audit list derived from the bindings rather than hand-written, or reduce it to a pointer at the bindings, so it cannot state a check no guarantee owns (Two controls WORKFLOW.md 5A audits that no section 4 guarantee states #1227, Fifteen pre-existing WORKFLOW.md section 5 defects a whole-unit read surfaced #1231).
  • Sweep sections 4 and 5 once, applying the binding, and settle each open claim as one of: the workflow is right and the text moves to match (fix), the text is right and the workflow moves (file against the workflow), or the claim was rationale and becomes non-normative under the format from the normative-statement sub-issue.
  • Generate the d-guarantees catalog in workflow-ci-contract from section 4 through the include mechanism from the one-home sub-issue, or reduce it to a pointer.

Rules that bind this task

  • A guarantee with no check is not a defect, it is guidance, and it is labeled so a reader knows nothing measures it.
  • Section 4 stays the home of the contract. Section 5 and the catalog derive from it.
  • One pull request per section after the mechanism lands.

Acceptance

  • spec/validate.py fails on an orphan in either direction.
  • Every open issue against sections 4 and 5 is closed by the sweep or moved to the section's tracker with a stated reason.

Closes #1227, #1245, #1204, #1217. Relates #1200, #1202, #1219, #1231, #1242, #1212, #1205, #1250, #1206.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgateA rule with no mechanical check, or a check that misses a shapegithub_actionsPull requests that update GitHub Actions code

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions