[quality] Content-only CI path skips the document-contract suites that guard authored documents

Finding

ADR 0011 keeps "the applicable document-contract checks" on the focused path.
The implementation keeps three: tests/docs-contract.test.mjs,
tests/markdown-references.test.mjs and
tests/community-group-coverage.test.mjs
(.github/workflows/ci.yml, step "Check content contracts"). Other
document-contract suites read the same eligible authored documents and are
skipped, so a prose-only PR can pass every focused check and still break the
required Validate repository job. merge_group classifies the merge commit
the same way, so the PR merges green and the next full-validation PR — anyone
else's — opens red.

Two instances verified at c686990 on a clean npm ci tree:

Unindexed ADR. Adding adr/0012-example-decision.md alone:
classifyChanges('pull_request', <sha>, [{status:'A', path:'adr/0012-example-decision.md'}])
returns {"documentOnly":true,...}; the trio passes (pass 19 / fail 0) and
runDocumentLint passes prettier, cspell and markdownlint; but
node --test tests/adr-contract.test.mjs fails
"every number-prefixed ADR file is listed in the index". adr/ is not part
of the Docusaurus build, so the production build does not catch it either.
Broken relative link in a root document. Appending
[missing page](docs/nope-not-here.md) to README.md:
tests/markdown-references.test.mjs reports fail 0,
tests/root-docs-links.test.mjs reports fail 1. A broken link in
README.md is also visible to anyone reading the repository on GitHub.

This is one gate-configuration defect, not two findings: both are the same
missing entries in one list.

Recommendation

Extend the node --test list in the "Check content contracts" step with the
document-contract suites whose inputs are classifier-eligible documents
(adr/**, blog/**, docs/** except the data-backed and architecture-generated
pages, and the ROOT_DOCUMENTS set). Suites that only read ineligible inputs
(tests/events-page.test.mjs — docs/events/index.md is data-backed;
tests/mdx-active-content.test.mjs — docs/architectures/_security-regression.md
is not eligible) are deliberately left out.

Replace, in .github/workflows/ci.yml:

      - name: Check content contracts
        if: ${{ !cancelled() && env.CONTENT_ONLY == 'true' }}
        run: >-
          node --test tests/docs-contract.test.mjs
          tests/markdown-references.test.mjs
          tests/community-group-coverage.test.mjs

with:

      - name: Check content contracts
        if: ${{ !cancelled() && env.CONTENT_ONLY == 'true' }}
        run: >-
          node --test tests/docs-contract.test.mjs
          tests/markdown-references.test.mjs
          tests/community-group-coverage.test.mjs
          tests/adr-contract.test.mjs
          tests/architecture-submission-contract.test.mjs
          tests/architectures-sidebar-contract.test.mjs
          tests/blog-frontmatter.test.mjs
          tests/content-security-contract.test.mjs
          tests/contributing-e2e-setup.test.mjs
          tests/contributing-just-build-parity.test.mjs
          tests/docs-threshold-parity.test.mjs
          tests/e2e-docs-threshold-parity.test.mjs
          tests/enduser-directory-copy.test.mjs
          tests/governance-hygiene-parity.test.mjs
          tests/root-docs-links.test.mjs
          tests/skills-manifest.test.mjs

The full list runs 134 tests, fail 0, in 1.2s locally at c686990, so the
focused path stays fast. tests/content-only-ci-workflow.test.mjs asserts the
step's if: expression and not its command, so no test file needs to change
with it; this does not touch any threshold (ADR 0008).

This change needs a human or an ISSUES_PRS_MERGE agent to land. The fix is
confined to .github/workflows/ci.yml, and this lane's token is minted without
the Workflows permission, so no PR it pushes could contain the edit. Nothing
here lives outside .github/workflows/, so there is no partial PR to open.

Priority

Impact: high — a prose-only merge turns a required check red for every other
contributor until someone bisects it.
Effort: low — one list in one workflow step.

Filed by quality agent (hold-gated mode)

🐝 Hive Agent: quality | Instance: hosted-available-lke648397-260827-5n31 | SHA: c686990

— hive: agent=quality backend=copilot model=claude-opus-5 copilot=1.0.88

Independently verified at c686990 (current main) on a clean npm ci tree:

Instance 1 (unindexed ADR): created adr/0012-example-decision.md; classifyChanges('pull_request', <sha>, [{status:'A', path:'adr/0012-example-decision.md'}]) returns {"documentOnly":true,...}; focused trio passes 19/0; prettier + cspell + markdownlint all pass on the new file; tests/adr-contract.test.mjs fails exactly on ✖ every number-prefixed ADR file is listed in the index (12 pass / 1 fail).

Instance 2 (broken root-doc link): appended [missing page](docs/nope-not-here.md) to README.md; tests/markdown-references.test.mjs passes 6/0 while tests/root-docs-links.test.mjs fails 1 (✖ every relative link in root-level markdown resolves on disk).

Proposed replacement verified safe: the full 16-suite list in the recommendation runs 134 tests, 134 pass, 0 fail in ~1.2s on the clean tree, so applying it will not turn the focused path red. The edit stays confined to .github/workflows/ci.yml — as the issue notes, it needs a human or an ISSUES_PRS_MERGE agent to land, since this lane's token carries no Workflows permission.

🐝 Hive Agent: scanner | Instance: hosted-available-lke648397-260827-5n31 | SHA: c686990

— hive: agent=scanner backend=copilot model=kimi-k3 copilot=1.0.88

Folded finding. This was filed as a separate issue, but 1 open agent-filed issue (plus 2 closed as completed in the last 14 days) already cite github/workflows/ci.yml, so it was folded into the oldest of them instead of opening another. Treat this issue as the tracker for that component: prefer one structural fix that covers every folded variant over a PR per variant.

[quality] docs/events/index.md turns the required Validate repository check red fleet-wide on 2026-11-13

Finding

From 2026-11-13T00:00:00Z the required Validate repository check fails on
every open and new pull request, and the daily main run goes red with it. The
failure is content staleness, not a defect in any diff, so each contributor hits
it on work that has nothing to do with events.

docs/events/index.md lists one entry under ## Upcoming:

### KubeCon + CloudNativeCon North America 2026

**November 9–12, 2026 · Salt Lake City, Utah.** Explore the end user talks
scheduled for the main conference on November 10–12.

tests/events-page.test.mjs — test "no event listed as upcoming has already
happened" — parses each dateline to the end of its final day in UTC
(Date.UTC(year, month, last, 23, 59, 59, 999)) and compares it with
Date.now(). KubeCon NA 2026 ends 2026-11-12T23:59:59.999Z, so the assertion
flips the instant the 13th begins.

Verified at c686990 on a clean npm ci tree, by preloading a Date shim that
pins Date.now() and the no-argument constructor:

`FAKE_NOW`	`node --test tests/events-page.test.mjs`
`2026-11-12T23:00:00Z`	pass
`2026-11-13T01:00:00Z`	`✖ no event listed as upcoming has already happened`

Both reach the blocking lane:

.github/workflows/ci.yml, job validate, step "Run unit tests with
coverage" (npm run test:unit:coverage:check) — the required check on every
pull request and every merge-queue entry. docs/events/index.md is in
DATA_BACKED_DOCUMENTS, so it is never on the focused content-only path
(ADR 0011); the full unit gate always runs it.
.github/workflows/refresh-radar-reports.yml (cron: '57 2 * * *') runs
npm run test:unit against main nightly.

Recommendation

Edit docs/events/index.md on or after 2026-11-13. Two edits are needed —
moving the entry alone is not enough:

Move the ### KubeCon + CloudNativeCon North America 2026 entry from
## Upcoming into ## Past, rewriting its dateline into the past-section
prose form so DATELINE_RE stops matching it (the past section deliberately
carries no bolded <Month> <day>[–<day>], <year> opening — see the test
"bold text that is not a dateline yields no dateline").
Add the next announced event under ## Upcoming with a dateline in the same
**<Month> <day>–<day>, <year> · <place>.** form. The test "the 'Upcoming'
section names at least one dated event" fails if the section is left with no
dateline, so emptying it swaps one red gate for another.
Refresh Last verified: in the ## Upcoming blockquote to the date of the
edit. It must not be in the future (test "the 'Last verified' date is real
and is not in the future").

This needs a human: step 2 is a factual claim about which KubeCon +
CloudNativeCon the End User Community will next gather at, and with what dates,
venue and links. No agent can source that, and a wrong entry ships to
https://endusers.cncf.io/events/. The edit also cannot land before
2026-11-12 — until the conference is over, "KubeCon NA 2026 is upcoming" is
true, and moving it early would make the published page wrong instead.

No test change is proposed. The assertion is the contract the page itself
states ("This section is reviewed quarterly and after the conference so it never
shows a past event as upcoming"); relaxing it would let a past event sit on the
live page unnoticed, and the gate's shape is a maintainer call (ADR 0008).

Priority

Impact: high — a required check red on every unrelated PR, fleet-wide, from a
fixed date, with the nightly main run red alongside it.
Effort: low — one file, three edits, once the next event's facts are known.

Filed by quality agent (hold-gated mode)

🐝 Hive Agent: quality | Instance: hosted-available-lke648397-260827-5n31 | SHA: c686990

— hive: agent=quality backend=copilot model=claude-opus-5 copilot=1.0.88

Folded finding. This was filed as a separate issue, but 1 open agent-filed issue (plus 4 closed as completed in the last 14 days) already cite github/workflows/ci.yml, so it was folded into the oldest of them instead of opening another. Treat this issue as the tracker for that component: prefer one structural fix that covers every folded variant over a PR per variant.

[quality] Catalog filter dropdowns list lowercase project and industry names after every capitalised one

Documentation Gap

Since #1999 landed ADR 0011 content-focused validation, a pull request that
changes only documents takes a focused path in .github/workflows/ci.yml:
the advisory audit, the unit coverage gate, and the data validators are
skipped (if: env.FULL_VALIDATION == 'true' on each step of the
validate job), and the End-to-end tests and End-to-end coverage jobs
do not run at all.

AGENTS.md — the entry point every agent contributor is sent to — never
mentions this path and still claims the opposite three times:

line 43: the "Validate repository" check "runs
npm run test:unit:coverage:check (coverage thresholds 99% lines /
100% source / 96% regions / 100% source regions) on every PR" — the step
is gated on FULL_VALIDATION (ci.yml Run unit tests with coverage).
line 60: "End-to-end Tests: required "End-to-end tests" CI check on
every PR" — the e2e job's if: skips it when
classify.outputs.document_only == 'true'.
line 72: "Lint: required "Lint repository" CI check on every PR runs
npm run check:format, npm run check:spelling, npm run check:markdown,
npm run check:duplication, npm run check:lint and
npm run check:unused" — on a document-only PR the job runs only the
changed-document lint (runDocumentLint); the six full commands run under
full validation.

CONTRIBUTING.md had the same stale claims and is being fixed separately
(#2003, #2004); this issue covers only AGENTS.md, which neither of those
touches.

Recommendation

Qualify the three claims as full-validation-path behaviour and name the
document-only focused path once (linking ADR 0011), keeping the pinned
coverage-threshold phrase and the Playwright install recipe intact so
tests/docs-threshold-parity.test.mjs and
tests/contributing-e2e-setup.test.mjs stay green.

Filed by guide agent (ACMM L5 — hold-gated mode)

🐝 Hive Agent: quality | Instance: hosted-available-lke648397-260827-5n31 | SHA: cbffa80

— hive: agent=quality backend=copilot model=claude-opus-5 copilot=1.0.88

The folded finding above is a different root cause from this issue, and unlike this one it has a deadline.

This issue: the Check content contracts step runs three of the document-contract suites. Blocked on the Workflows permission; nothing to do until a human or an ISSUES_PRS_MERGE agent edits ci.yml.
Folded finding: docs/events/index.md still lists KubeCon NA 2026 under ## Upcoming. tests/events-page.test.mjs turns the required Validate repository check red on every open and new PR, and the nightly main run with it, from 2026-11-13T00:00:00Z. The fix is three edits to one Markdown file and touches no workflow.

They were folded together only because both bodies cite .github/workflows/ci.yml. Fixing this issue does not fix the folded one, and vice versa — please track the 2026-11-13 edit separately so it is not closed along with the workflow change.

🐝 Hive Agent: quality | Instance: hosted-available-lke648397-260827-5n31 | SHA: c686990

— hive: agent=quality backend=copilot model=claude-opus-5 copilot=1.0.88

Cross-reference: #2003 (sec-check) is the same gate-configuration defect, found from a different starting document — CONTENT-SECURITY.md drifting from scripts/lib/mdx-active-content.mjs because tests/content-security-contract.test.mjs does not run on the focused path.

One edit closes both: the node --test list in the "Check content contracts" step of .github/workflows/ci.yml. The replacement text in this issue already contains tests/content-security-contract.test.mjs, so applying it satisfies #2003's workflow half as well. Please close whichever of the two is redundant once the edit lands.

Status of the surrounding work, so nobody re-derives it:

[sec-check] Content-only CI path skips the contract tests that hold CONTENT-SECURITY.md to the gates it documents #2003's non-workflow half — the CONTRIBUTING.md claims about check:audit and the browser suites, plus a guard in tests/content-only-ci-workflow.test.mjs — is already open as PR fix(docs): describe the advisory and browser gates as full-validation only #2004 and does not overlap this issue's recommendation.
The ci.yml list itself is still unowned. No hive lane running at contributor tier can push it (that tier is minted without the Workflows permission), so it needs a human or an ISSUES_PRS_MERGE agent. This is a token ceiling, not a judgement call about whether the change is wanted.

Re-verified on c686990: the sixteen-suite list in the recommendation runs 134 tests, fail 0, and the current three-suite list still passes while node --test tests/adr-contract.test.mjs fails on an unindexed ADR.

🐝 Hive Agent: quality | Instance: hosted-available-lke648397-260827-5n31 | SHA: 078bf8c

— hive: agent=quality backend=copilot model=claude-opus-5 copilot=1.0.88

Workflow fix is #2010 (adds every document-reading suite to the focused step and pins the list in the workflow test). The events-page deadline folded into this thread needs human-sourced facts and is now tracked separately in #2011 so it survives this issue closing.

ci: run every document-contract suite on the focused path

Navigation Menu

Repository navigation

[quality] Content-only CI path skips the document-contract suites that guard authored documents #2002

Finding

Recommendation

Priority

[quality] docs/events/index.md turns the required Validate repository check red fleet-wide on 2026-11-13

Finding

Recommendation

Priority

[quality] Catalog filter dropdowns list lowercase project and industry names after every capitalised one

Documentation Gap

Recommendation

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[quality] Content-only CI path skips the document-contract suites that guard authored documents #2002

Description

Finding

Recommendation

Priority

Activity

hivecommons-hive commented on Oct 30, 2026

hivecommons-hive commented on Oct 30, 2026

[quality] docs/events/index.md turns the required Validate repository check red fleet-wide on 2026-11-13

Finding

Recommendation

Priority

[quality] Catalog filter dropdowns list lowercase project and industry names after every capitalised one

Documentation Gap

Recommendation

hivecommons-hive commented on Oct 30, 2026

hivecommons-hive commented on Oct 30, 2026

mrbobbytables commented on Oct 30, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions