Skip to content

test(ci): make lint-readme-parity bidirectional (catch stale README rows)Β #204

@devantler

Description

@devantler

πŸ€– Generated by the Daily AI Assistant

Problem

The lint-readme-parity CI job (added for #185, closing the roadmap epic #181) verifies README ↔ action.yaml parity in one direction only: it fails if a declared input/output is missing from the README's ## Inputs / ## Outputs table.

It does not check the reverse β€” a README table row naming an input/output that no longer exists in action.yaml. That is precisely the drift a rename or removal leaves behind: you rename/drop an input in action.yaml, the forward check still passes (nothing newly undocumented), and the README keeps a now-phantom row that silently misleads consumers.

This repo has a history of exactly those changes β€” require-checks β†’ aggregate-job-checks (v3), setup-copilot-skills β†’ setup-agent-skills (v5), and the Codecov input/secret removal (v5) β€” so a stale-row guard is warranted, not speculative. Epic #181's stated goal was a library that is "mechanically inspectable for correctness, not just by social convention"; the forward-only check half-delivers that for READMEs.

Proposed direction

Make the existing lint-readme-parity job bidirectional:

  • forward (unchanged) β€” every declared input/output must be documented;
  • reverse (new) β€” every name in the README's ## Inputs / ## Outputs table first column must be a declared input/output in action.yaml.

Pure CI hardening β€” no new dependencies (yq is already preinstalled on the runner), no change to any action. The current tree passes the reverse check clean (verified locally), so it lands green and only guards future drift.

Acceptance criteria

  • The lint-readme-parity job fails when a README documents an input/output not declared in its action.yaml.
  • The forward direction is preserved unchanged.
  • The job passes on the current tree.
  • No false positives on prose code-spans (only the table's first column is read).

Size

XS β€” one run: block in .github/workflows/ci.yaml.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    Status

    βœ… Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions