[lengau]

Problem

canonical/starflow/.github/workflows/lint-python.yaml runs all code and
documentation linters in a single job. Link checking is slow and hits the
network, so it slows down every job that depends on it.

To split linting into separate CI jobs, linkcheck needs to be a standalone
Make target rather than part of docs-lint.

Changes

• Add a docs-linkcheck target that runs make -C docs linkcheck.
• Remove linkcheck from docs-lint, which keeps running sphinx-lint,
  spelling, and woke.
• Add docs-linkcheck as a prerequisite of lint, so make lint and local
  behaviour are unchanged.

Downstream repos get the new target automatically the next time they merge
from starbase/main.

Compatibility testing

This PR is only the starbase half. The starflow half that consumes it is
canonical/starflow#199.

The merge order matters, so both orders are tested by these draft PRs:

• Forwards compatible — starbase merged first, starflow still on main:
  ci: test starbase with starflow's split lint workflow #626. Based on this branch, points the lint job at
  starflow's work/separate-linkcheck.
• Backwards compatible — starflow merged first, starbase still on main:
  ci: test starbase main with starflow's split lint workflow #627. Based on main, points the lint job at starflow's
  work/separate-linkcheck. The linkcheck job is expected to fail, since
  docs-linkcheck does not exist on main.

If #627 fails, starbase has to land before starflow.

Each of those two test PRs also has a docs-only PR stacked on top of it,
to check the filter classifies a documentation-only change correctly and
skips the code linters:

• docs: add docs-linkcheck to the commands to test #628, stacked on ci: test starbase with starflow's split lint workflow #626.
• docs: add docs-linkcheck to the commands to test #630, stacked on ci: test starbase main with starflow's split lint workflow #627.

The same two stacks also each have a PR that changes a source file and a
documentation file together, to check that all three linting jobs run rather
than only one:

• test: touch a source file and a docs file together #632, stacked on docs: add docs-linkcheck to the commands to test #628.
• test: touch a source file and a docs file together #633, stacked on docs: add docs-linkcheck to the commands to test #630.

Test plan

• make format, make lint, make test-fast

[Copilot]

🟢 Approval recommended

No unresolved review issues remain.

0 open findings

What changed in this PR

Adds a standalone documentation link-check target while preserving aggregate lint behavior.

Changes:

• Adds docs-linkcheck for standalone link checking.
• Includes it in the aggregate lint target.
• Keeps other documentation checks separate.

File	Description
Makefile	Includes link checking in aggregate linting.
common.mk	Defines the standalone docs-linkcheck target.

🧠 Review effort: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.