LearnNewsExamplesConnect
Frontmatter
assigneesneo-opus-ada
createdAtOct 30, 2026, 12:46 AM
updatedAtOct 30, 2026, 2:37 AM
githubUrlhttps://github.com/neomjs/neo/issues/20177
authorneo-opus-ada
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
contentTrust
projected
quarantined0
signals[]
blockedBy[x] 1366 lint-guides lints a caller-supplied repository root
blocking[]
closedAtOct 30, 2026, 2:37 AM

neo's CI runs the guide-quality lint over its guides again

Closed v13.4.0/archive-v13-4-0-chunk-3 documentationenhancementai
neo-opus-ada
neo-opus-ada commented on Oct 30, 2026, 12:46 AM

Context

The guide-quality lint (#14354) hard-fails Mermaid reserved words and self-loops, dead local links, dead ai:* script refs, tool-table refs that resolve to no OpenAPI operationId, and ticket ids in learn/guides. The ticket-id rule is the operator's "guides describe, trackers decide" (#17574). Before the split, this repository ran it as ai:lint-guides. #17806 removed that script along with the received Brain code. The cut manifest gives ai/scripts/lint/lint-guides.mjs to the Brain (disposition edge), and no repository has run it since (defect-note a03b68c6). Only check-relative-links still guards these guides.

The Problem

Measured 2026-10-29 with the Brain's lint (--root from neomjs/neo-agent-brain#1366) against dev@cc24c59e0d, it scans 10 full guides and 63 guide-series files. There are 5 warnings and 3 hard findings, all ticket ids that accumulated while nothing ran:

  • learn/guides/datahandling/PooledGridAnimation.md:38 and :59 (#6858);
  • learn/guides/testing/WhiteboxE2E.md:69 (#19655). That sentence is also stale: it describes a retry bridge that BRAIN_RETRY_BRIDGE (buildScripts/util/e2eCiSelection.mjs) ended on 2026-10-25.

The Fix

  1. .github/workflows/lint-guides.yml: on dev pull requests and pushes that touch learn/** or the workflow, check out this repository and neomjs/neo-agent-brain at dev, as test-e2e-brain.yml already does for the Brain, then run node <brain>/ai/scripts/lint/lint-guides.mjs --root .. No npm ci is needed, because the lint uses only Node built-ins.
  2. The three findings, rewritten to describe the mechanism. The WhiteboxE2E.md paragraph states today's behaviour: the tier runs without retries.

Acceptance Criteria

  • AC-1: a dev PR touching learn/** runs the guide lint over this repository's guides and fails on a hard finding.
  • AC-2: the lint is green on this PR's head (0 hard findings).
  • AC-3: WhiteboxE2E.md describes the tier's current retry behaviour and cites e2eCiSelection.mjs, not a ticket.

Out of Scope

  • The 5 warnings (no-mermaid in two guides, "framework" wording in Introduction.md). They are report-only, and each is an authoring call.

Related

Blocked by neomjs/neo-agent-brain#1366 (PR neomjs/neo-agent-brain#1367), which adds --root. Prior: #14354, #17574, #17806.

Live latest-open + closed sweep: latest 12 open neo issues + a search for guide lint workflow / lint-guides CI at 2026-10-29T23:46:31Z, with no equivalent; #17809 is the link-guard precedent. A2A: no claim. Structure map: N/A, since this adds one workflow and edits two guides.

Retrieval Hint: "neo guide-quality lint workflow lint-guides --root Brain checkout ticket ids learn/guides restored"

tobiu closed this issue on Oct 30, 2026, 2:37 AM
tobiu referenced in commit 677a1f0 - "ci(workflows): run the Brain's guide lint over neo's guides again (#20177) (#20180) on Oct 30, 2026, 2:37 AM