Give Markdown its own job

[sehkone]

Closes #995. Follow-up to #994, which is merged.

Run Markdown Lint was the thirteenth step of check, behind cargo clippy, cargo doc, ruff format, ruff check and biome ci. Any of those failing hid the Markdown result — the lint never ran, and a pull request that broke two things was told about one. #994 put the shared drift check at the end of that same twenty-step job, where its if: ${{ !cancelled() && … }} guard rescued the drift check specifically and nothing rescued the lint above it.

What changed

A markdown job, matching the one every other consumer of aicers/agent-instructions already has:

  markdown:
    name: Markdown
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        id: checkout
      - name: Run Markdown Lint
        uses: DavidAnson/markdownlint-cli2-action@v24
        with:
          globs: "**/*.md"
      - uses: aicers/agent-instructions/check-drift@main
        if: ${{ !cancelled() && steps.checkout.outcome == 'success' }}

Both steps leave check, along with the drift step's comment block — which argued at length for a placement this change reverses, including a sentence saying there was no Markdown job here to use instead. check's id: checkout goes too, nothing reading it any more.

This is not a new convention, and the second half of it already applies here

aicers/multifold's copy of the job writes down the reason:

Ungated and standalone, matching aicers/roxyd and aicers/agentcoop. Kept out of check so a clippy failure cannot hide the Markdown result, and so the lint survives if the expensive jobs are ever put behind a path filter.

In most consumers that second clause is a precaution. Here the path filter already exists: changes gates test-core and the Docker E2E matrix on docs_only != 'true', so on a documentation-only change check is the only job that reports at all — and today it reports the Markdown lint only if a dozen Rust and Python steps happen to pass first.

This repository and aicers/aimer are the two that never adopted the standalone job. #994 chose check because it was then the only job with no if: — correct given the file as it stood, and superseded now. aicers/aimer#590 does the same there.

No needs: and no if: — here that is the point, not a precaution

changes counts **/*.md as documentation and AGENTS.md matches it, so a pull request confined to a generated region is docs-only. Both gated directions would lose the check: test-core and the E2E matrix skip on docs-only, and test-registrar-redteam-docs is gated the other way and skips on everything that touches code.

What stays in check

biome ci, ruff and ./scripts/check-docs.sh. Keeping biome there matches agentcoop, aice-web-next and aimer-web, which all run it in check beside a separate Markdown job; check-docs.sh builds the manual and is not a lint. Swatinem/rust-cache, actions/setup-python and the validation scripts are untouched — each is its own question and folding one in would bury this change.

Runner

ubuntu-latest, like every other job here. Not a runner move: the self-hosted fleet is for the private repositories, where hosted minutes cost money. Actions is free on this public repository, so the new job costs a scheduling slot and about thirty seconds that run in parallel with a check measured in minutes.

Verification

actionlint reports the same three shellcheck findings as main — SC2129, SC2155, SC2034, at lines 225, 333 and 418 here against 223, 331 and 416 before, the difference being the lines this change moved. Nothing new, and they are left alone.

Runs are posted below, including the one that matters most: a change that breaks clippy and the Markdown lint at once, which before this would have reported only the first.

[sehkone]

Test plan results

The test that matters: clippy and the Markdown lint broken at once

Run 34435062898 (a trailing-space violation in README.md and an identity_op in src/main.rs, placed at the end of the file so cargo fmt stays clean and clippy is what catches it):

Change Filter  = success
Markdown       = failure    failed step: Run Markdown Lint
Quality Check  = failure    failed step: Check Rust Lints (Clippy)
Unit & CLI Smoke / Docker E2E / Registrar Redteam = skipped

Both defects reported, each from its own job. Within Quality Check the clippy failure still swallows everything after it — Check Rustdoc, Check Python Lints, Setup Biome and Run Biome all skipped — which is exactly the behaviour the Markdown lint used to be subject to, and no longer is.

And the control — this is what it looked like before

Not an argument, an observation. Run 33467653299, read out of the API:

Check Rust Lints (Clippy) = failure
Run Markdown Lint         = skipped

That pull request was told about clippy and nothing about its Markdown, whatever state it was in.

On reading the skipped jobs in that run

Unit & CLI Smoke and Registrar Redteam (docs-only) are both skipped, and that is not the change filter — they are needs: [check, changes] and check failed. The two are gated in opposite directions, so the filter can never skip both; both skipped always means a dependency failed. The same pattern appeared in #994's drift run and is worth not misreading.

Green after the revert

Posted as soon as the revert run finishes, Docker E2E matrix included.

[sehkone]

The revert goes green. Run 34435336770 (c08f7ca) — Change Filter, Markdown, Quality Check, Unit & CLI Smoke and all 14 Docker E2E scenarios success. Registrar Redteam (docs-only) is skipped, correctly: this branch is not docs-only, and that job is gated to run only when it is.

Worth contrasting with the drift run above, where that same job was also skipped — there because check had failed and it is needs:-blocked, here because the filter did its job. Same word in the UI, two different reasons.