Skip to content

fix(ci): lint the whole repository in the docs-phase gate - #6

Merged
forkwright merged 1 commit into
mainfrom
fix/1-whole-repo-lint-gate
Jul 29, 2026
Merged

fix(ci): lint the whole repository in the docs-phase gate#6
forkwright merged 1 commit into
mainfrom
fix/1-whole-repo-lint-gate

Conversation

@forkwright

Copy link
Copy Markdown
Owner

Refs #1

What was wrong

The pipeline ran two scoped commands:

stages = ["ci-config-lint", "readme-lint"]
cmd = "kanon lint --workflow .kanon-ci.toml"
cmd = "kanon lint --writing README.md"

They certify the CI file and the README — the two files least likely to have drifted — and nothing else. kanon lint . reported four violations the gate never looked at. A required check that samples is not a proof surface.

Change

repo-lint runs kanon lint ., which subsumes the scoped workflow check. readme-lint stays, because --writing applies prose rules the default pass does not; it is additive, not substitutive.

Turning the gate on surfaces the four violations it was hiding, all fixed here:

rule file
CONTEXT/preamble-required AGENTS.md — no defers_to, no tightens
CONTEXT/preamble-required CLAUDE.md — no preamble at all
YAML/missing-permissions .github/workflows/gate-attestation.yml
YAML/missing-concurrency .github/workflows/gate-attestation.yml

The preambles use the fleet's prose form (defers_to: kanon standards for universal engineering policy), matching dioptron and zetesis rather than inventing a third shape. The workflow gains permissions: contents: read and a concurrency group — the reusable it calls declares the former for its own job but no concurrency group at all, so without the caller's group a rapid re-push left the superseded run to run to completion.

Verification — the gate was watched going red

A gate that has only ever been green is not evidence. Run on this box with a branch-built kanon 0.1.12:

1. Clean treekanon gate --tier full --force .:

PASS  repo-lint
PASS  readme-lint

2. Preamble stripped from CLAUDE.md, nothing else changed — the same command:

CLAUDE.md:1 [CONTEXT/preamble-required] context file missing preamble with scope, defers_to, and tightens
FAIL  repo-lint
PASS  readme-lint
GATE FAILED  1 step(s) failed: repo-lint

Against the previous pipeline that same tree passed. That difference is the fix.

3. Restoredkanon lint . --summary: No violations found.

Not fixed here, deliberately

The emitted trailer still reads +stages:fmt,check,clippy,nextest,lint — stage names from config rather than the stages that actually ran, in a repo with no Cargo workspace for four of the five to mean anything. That is a kanon substrate defect (forkwright/kanon#2555), not something this repo can correct, and #1's finding already names it.

The scaffold-side half of #1's desired correction — deriving this pipeline from one fleet scaffold with a fitness fixture — also lives in kanon. This PR fixes the instance; the generator that produced two identical copies of the defect is a kanon change and is called out on the issue.

`Refs #1`

The pipeline ran `kanon lint --workflow .kanon-ci.toml` and
`kanon lint --writing README.md`, which certified this file and the README and
nothing else. The gate reported PASS while `kanon lint .` reported violations in
AGENTS.md, CLAUDE.md and the gate-attestation workflow — it sampled the files
least likely to have drifted and excluded the ones that had, so a green branch
was weaker evidence than running the canonical linter by hand.

`kanon lint .` replaces the scoped workflow check, which it subsumes. The
README writing check stays because `--writing` applies prose rules the default
pass does not.

Turning the gate on surfaces the four violations it was hiding, fixed here:

- AGENTS.md / CLAUDE.md carried no `defers_to` or `tightens`
  (CONTEXT/preamble-required). Both now use the fleet's prose form, matching
  dioptron and zetesis.
- gate-attestation.yml declared neither `permissions` nor `concurrency`
  (YAML/missing-permissions, YAML/missing-concurrency). The reusable it calls
  declares `contents: read` for its own job but no concurrency group, so without
  the caller's group a rapid re-push left the superseded run to completion.

Gate-Passed: kanon 0.1.12 +stages:fmt,check,clippy,nextest,lint sha:b6bf9031c587ac8d593fb4d73da689cc8b4a92bf
@forkwright
forkwright merged commit 5349a75 into main Jul 29, 2026
1 check passed
@forkwright
forkwright deleted the fix/1-whole-repo-lint-gate branch July 29, 2026 08:38
forkwright pushed a commit that referenced this pull request Jul 30, 2026
🤖 I have created a release *beep* *boop*
---


## [0.0.2](v0.0.1...v0.0.2)
(2026-07-30)


### Bug Fixes

* **ci:** grant reusable workflow permissions to unblock release-please
([#4](#4))
([52603fc](52603fc))
* **ci:** lint the whole repository in the docs-phase gate
([#6](#6))
([5349a75](5349a75))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant