LearnNewsExamplesServices
Frontmatter
id17574
titlelint-guides hard-fails ticket ids in learn/guides — operator rule: guides describe, trackers decide
stateClosed
labels
enhancementai
assigneesneo-gpt-emmy
createdAtAug 22, 2026, 10:20 PM
updatedAtAug 25, 2026, 10:48 AM
githubUrlhttps://github.com/neomjs/neo/issues/17574
authorneo-fable
commentsCount4
parentIssue17540
subIssues[]
subIssuesCompleted0
subIssuesTotal0
contentTrust
projected
quarantined0
signals[]
blockedBy[]
blocking[]
closedAtAug 25, 2026, 10:48 AM

lint-guides hard-fails ticket ids in learn/guides — operator rule: guides describe, trackers decide

Closed Backlog/active-chunk-18 enhancementai
neo-fable
neo-fable commented on Aug 22, 2026, 10:20 PM

Context

Operator rule (2026-08-22, verbatim): "please NEVER use ticket ids in guides. they rot." The two dock guides were swept to zero ids the same evening (PR #17572, commit efc1552391); the rule currently lives only in that PR's history and in agent memory — nothing enforces it for the next guide author.

The Problem

A guide that cites #12345 reads as evidence today and as archaeology in a year: the id re-targets nothing in the prose when the ticket closes, migrates, or is renamed, and the reader cannot tell load-bearing citation from decoration.

Fresh intake on 2026-08-25 found 10 actual ticket references across three files:

  • learn/guides/fundamentals/CodebaseOverview.md
  • learn/guides/specificfeatures/TearOutPortabilityMatrix.md
  • learn/guides/testing/ComponentTesting.md

The same scan also exposed the required negative boundary: a bare #[0-9]{4,} regex partially matches CSS/Mermaid colors such as #3498db and fully matches the valid color #282829. Color literals are not ticket references and must remain green.

The Fix

  1. Mechanize the rule: ai/scripts/lint/lint-guides.mjs gains a HARD ticket-id rule for ticket-style #[0-9]{4,} references under learn/guides/**/*.md, including references inside inline and fenced code. Syntactic CSS/Mermaid hex-color values remain green; the rule must not turn color literals into tracker references.
  2. Give the rule the right discovery surface: recursively discover learn/guides/**/*.md for this rule only. Keep every pre-existing guide-quality rule on its current top-level learn/agentos/*.md + learn/benefits/*.md surface so unrelated legacy debt does not become a new hard gate.
  3. Sweep the current three files above in the same PR, rephrasing each tracker pointer as timeless prose. War stories keep their mechanisms and measurements; tracker ids leave the guide.
  4. Scope boundary: learn/agentos/ decision records and contract docs cite tickets by design; the ticket-id rule must not fire there.

Contract Ledger

Target Surface Source of Authority Proposed Behavior Fallback / Edge Case Docs Evidence
Default ai:lint-guides discovery lint-guides.mjs#discoverGuides + #17540 guide-series tree Keep the complete existing rule set on top-level learn/agentos/*.md and learn/benefits/*.md; additionally recurse through learn/guides/**/*.md for the ticket-id rule only The current 56-file legacy guide corpus has one unrelated dead-link HARD and must not be absorbed into this ticket Script JSDoc scope and CLI help Default CLI scans a known nested guide for ticket ids while preserving the existing-rule file count
Ticket-id rule Operator rule recorded here + merged manual sweep efc1552391 Ticket-style #[0-9]{4,} references in learn/guides/** are HARD, including inline/fenced code Valid CSS/Mermaid hex colors remain green; no tracker lookup or network dependency Rule JSDoc Pure positive/negative units plus a default-CLI scratch-guide RED
Diagnostic output Existing lint finding schema Emit rule name, exact file/line, and a bounded remedy explaining that ticket ids rot in guides Multiple references report independently CLI help and rule JSDoc stdout/stderr assertion
Existing guide corpus Current learn/guides tree Sweep the three measured files to timeless prose Do not absorb unrelated dead-link or warning debt Edited guide prose Complete local scan returns zero ticket-id findings while color controls remain green

Acceptance Criteria

  • The default guides lint recursively applies the ticket-id HARD rule to learn/guides/**/*.md and nowhere else.
  • Existing rules retain their current top-level learn/agentos/*.md + learn/benefits/*.md discovery surface.
  • The three measured files are swept to timeless prose; a complete ticket-reference scan returns zero true hits.
  • Positive controls cover prose, inline-code, fenced-code, and multiple references with exact line diagnostics.
  • Negative controls cover shorter numeric fragments and valid CSS/Mermaid colors, including an all-numeric six-digit color.
  • A real default-CLI scratch guide containing a ticket reference fails; removing the reference makes that same route green.
  • ai:lint-guides remains green repo-wide on its default surface.

Related

PR #17572 (the manual sweep this mechanizes) · #17540 (the guide series the rule landed during).

Live duplicate/successor re-check on 2026-08-25 found no PR targeting #17574 and no equivalent ticket. Parent #17540 has an independent epic review: https://github.com/neomjs/neo/issues/17540#issuecomment-5384238248

Unassigned — pool, self-select.

Origin Session ID: bd272031-6109-449d-8a0c-38230064a8f3

Retrieval Hint: query_raw_memories("ticket ids rot guides lint hard rule describe trackers decide")

Mnemosyne (Claude Fable 5, Claude Code) 🪢

tobiu referenced in commit 86ab9e2 - "fix(ai): narrow guide color exemption (#17574)" on Aug 25, 2026, 10:35 AM
tobiu referenced in commit 3f0b7b5 - "feat(ai): reject ticket ids in narrative guides (#17574) (#17747) on Aug 25, 2026, 10:48 AM
tobiu closed this issue on Aug 25, 2026, 10:48 AM