---
id: 12294
title: 'Mechanical guard: block ticket-ref archaeology in durable .mjs comments/JSDoc'
state: CLOSED
labels:
  - enhancement
  - ai
  - architecture
assignees:
  - neo-opus-ada
createdAt: '2026-06-01T08:16:01Z'
updatedAt: '2026-06-01T09:26:39Z'
githubUrl: 'https://github.com/neomjs/neo/issues/12294'
author: neo-opus-ada
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-06-01T09:26:39Z'
---
# Mechanical guard: block ticket-ref archaeology in durable .mjs comments/JSDoc

## Context

The "no decay-prone ticket/Epic/Discussion/ADR refs in durable SHIPPED artifacts (.mjs JSDoc/comments, learn/ docs, Dockerfile/config)" discipline has recurred as a **repeat violation** despite being captured in agent memory (empirical: #11940 / #12113 / #12151, and again across this session in #12290 spec comments + #12209 base/view comments). The discriminator is sound — durable-shipped prose vs tracking-coordination (PR bodies, commit subjects `(#TICKET)`, ticket/A2A/Discussion bodies, `test.describe(...)` anchors are load-bearing and stay) — but enforcement is **discipline-only**, and discipline loses to the authoring reflex of "cite the motivating ticket as the reason" at every comment.

Per `AGENTS.md §self_evolving_systems` ("mechanical guard > discipline-only") + §friction_to_gold, a recurring discipline-slip is a substrate signal for a **mechanical guard**, not another memory reminder.

## The Problem

When tickets close / rename / get superseded, ticket refs embedded in durable code comments rot into dangling archaeology that poisons KB ingestion and misleads future readers. A passive memory entry cannot prevent this — it requires the author to remember + judge at every comment.

## The Fix

Add `buildScripts/util/check-ticket-archaeology.mjs` (mirroring `check-shorthand.mjs`): a check script that, given staged `[files...]` (or a default-dir scan), flags ticket-ref patterns (`#\d{4,}`, `Epic #N`, `Discussion #N`, `ADR-?\d{3,4}`) appearing in **comment context** within `.mjs` source, and exits non-zero.

- **Comment-context detection:** line/block comments (`//`, `/* */`, JSDoc `* `) — NOT string literals, so `test.describe('... (#11645)')` and other load-bearing string anchors stay exempt.
- **Escape hatch:** an inline `ticket-ref-ok` marker exempts a genuinely load-bearing line (judgment-call relief valve, not a blanket bypass).
- **Wiring:** add to `lint-staged` `"*.mjs"` (alongside `check-shorthand`) — staged-files scan → **incremental adoption** (only flags a file when it is touched; no big-bang repo cleanup required).
- **Self-test:** a unit spec proving it flags a JSDoc/`//` ticket ref, exempts a `test.describe` string ref, and honors the escape marker.

## Substrate-Accretion Defense

Adds the guard script + lint-staged entry, but enables **compressing/retiring the passive MEMORY.md `jsdoc_archaeology_self_audit` entry** — the discipline moves from fragile-memory to reliable-mechanism. Decay-mitigation: prevents the recurring rot directly.

## Acceptance Criteria

- [ ] `check-ticket-archaeology.mjs` flags `#\d{4,}` / Epic / Discussion / ADR refs in `.mjs` comment context.
- [ ] String-literal refs (e.g. `test.describe('...(#11645)')`) are NOT flagged.
- [ ] `ticket-ref-ok` inline marker exempts a line.
- [ ] Wired into `lint-staged` `*.mjs` (staged-files, incremental).
- [ ] Self-test spec covers flag / string-exempt / escape cases.

## Out of Scope (follow-up)

- `.md` / `learn/` + Dockerfile/compose scanning (more legit-ref edge cases; stage after the .mjs guard proves out).
- Repo-wide CI gate (needs a full pre-existing-violation sweep first).
- Retiring the MEMORY.md entry (do once the guard is merged + proven).

## Timeline

- 2026-06-01T08:16:02Z @neo-opus-ada assigned to @neo-opus-ada
- 2026-06-01T08:16:02Z @neo-opus-ada added the `enhancement` label
- 2026-06-01T08:16:03Z @neo-opus-ada added the `ai` label
- 2026-06-01T08:16:03Z @neo-opus-ada added the `architecture` label
- 2026-06-01T08:23:42Z @neo-opus-ada cross-referenced by PR #12295
- 2026-06-01T09:26:39Z @tobiu referenced in commit `9f812f2` - "feat(tooling): mechanical guard against ticket-ref archaeology in .mjs comments (#12294) (#12295)

Adds buildScripts/util/check-ticket-archaeology.mjs + wires it into lint-staged (*.mjs), turning the
discipline-only 'no decay-prone ticket/Epic/Discussion/ADR refs in durable comments' rule into a
mechanical pre-commit gate. A string-aware line scanner flags refs only in true comment context, so
load-bearing string anchors (test describe titles, issue URLs) stay exempt; an inline ticket-ref-ok
marker is the judgment-call escape. Staged-files scan = incremental adoption (no big-bang cleanup).
Self-test spec covers flag / string-exempt / escape / named-form / hex-non-false-positive / block-close.

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-01T09:26:39Z @tobiu closed this issue

