Codify why-first source-code documentation contract

Context

Discussion #11889 converged on a source-code documentation contract after operator feedback that recent comments/JSDoc were drifting into stale ticket, lane, AC, and line-number archaeology instead of explaining durable intent.

This ticket graduates Discussion #11889 after:

• OpenAI author signal in the Discussion body.
• Anthropic non-author approval at https://github.com/neomjs/neo/discussions/11889#discussioncomment-17039502.
• Non-author STEP_BACK sweep at https://github.com/neomjs/neo/discussions/11889#discussioncomment-17039468 with 3 pass / 5 partial / 0 blocker.
• Gemini is operator-benched in ai/graph/identityRoots.mjs; no active-family wait remains for this scope.

Duplicate sweep:

• gh issue list --state all --search "code comments JSDoc ticket references line numbers archaeology" returned no equivalent ticket.
• Exact follow-up searches for "why-first" "code comments" and "line-number" JSDoc comments returned no matches.
• Exact "ticket references" JSDoc surfaced #10341, which is related but narrower: MCP OpenAPI tool-description budget, not source-code comments/JSDoc.
• Local rg across resources/content/issues, resources/content/discussions, .agents/skills, and learn/agentos found related archaeology/reference-classification discussions (#11557, #11577), but no equivalent why-first source-code comment contract.
• The Knowledge Base semantic ticket query errored with Error finding id; the fallback exact sweeps above were used per ticket-create fallback discipline.

The Problem

Neo evolves quickly enough that source-code comments pointing at tickets, PR cycles, lane names, AC text, or line numbers decay into misleading archaeology. After a month, the ticket may be closed, the architecture may have changed, and the line range almost certainly shifted.

The durable direction should normally be one-way:

• Tickets, PRs, commits, and Discussions may mention code because they are snapshot and graph-ingestion artifacts.
• Source code should not mention tickets, lanes, ACs, PR cycles, or line ranges by default because source comments are read in the living architecture.

A second failure mode is comment duplication of generic Neo patterns. Consumers should not re-explain framework concepts like initAsync() semantics or entrypoint-local dotenv ownership in every class. Owning primitives and canonical docs should carry those explanations; consumers should document only their local boundary or exception.

The Architectural Reality

Current authority and adjacent substrate:

• AGENTS.md already requires Contextual Completeness / Anchor & Echo JSDoc, but does not define a source-code archaeology filter.
• learn/agentos/AGENTS_ATLAS.md states the intended flow as adding intent-driven comments that enrich the Knowledge Base.
• .agents/skills/pr-review/references/pr-review-guide.md already has rhetorical-drift checks for architectural prose, but does not include a why-first source-code anchor rule.
• .agents/skills/pr-review/assets/pr-review-template.md already has an Anchor & Echo checklist slot that can carry the reviewer-facing check.
• ai/scripts/lint/lint-agents.mjs and ai/scripts/lint/lint-skill-manifest.mjs establish an ai/scripts/lint/ sibling pattern if this ticket adds a diagnostic script. Structural fast-path: a source-comment archaeology diagnostic belongs there if implemented as a lint/diagnostic script; sibling-file-lift applies and no new structural inventory row is needed.

Progressive Disclosure sweep:

• .agents/skills/create-skill/references/skill-authoring-guide.md confirms skill routers must stay lightweight and heavy guidance belongs in reference payloads.
• This ticket must not bloat pr-review/SKILL.md; put reviewer guidance in the reference payload and, if needed, one short checklist line in the review template.

The Fix

Codify the why-first contract as forward-looking substrate:

1. Add reviewer guidance to .agents/skills/pr-review/references/pr-review-guide.md that source-code comments/JSDoc default to no ticket, PR, lane, AC, cycle, or line-number anchors.
2. Add or refine the review-template checklist in .agents/skills/pr-review/assets/pr-review-template.md so reviewers check source-code Anchor & Echo comments for why-first intent, stable symbols, and no snapshot archaeology.
3. Add a compact learn/agentos/AGENTS_ATLAS.md note so architectural sweeps and future substrate work can find the rule without loading PR-review skill context.
4. Prefer no AGENTS.md expansion. If a PR adds one, it must be a short trigger and must satisfy substrate-accretion defense.
5. Add diagnostic-first support: either a documented command or a non-failing script/report that surfaces candidate source-code archaeology markers without making CI hard-fail in v1.

Contract Ledger Matrix

Decision Record Impact

Aligned with ADR 0005: ADRs are the lean executable authority target; Discussions remain archaeology. This ticket applies that separation to source-code comments.

Aligned with ADR 0008 / Progressive Disclosure: if PR-review skill guidance changes, it belongs in reference payloads, not in the lightweight SKILL.md router.

No ADR amendment is expected unless implementation discovers that the rule needs a broader cross-substrate decision record beyond PR-review + AGENTS_ATLAS guidance.

Signal Ledger

Unresolved Dissent

None recorded.

Unresolved Liveness

Gemini / @neo-gemini-pro is operator-benched per ai/graph/identityRoots.mjs. This ticket is treated as non-Tier-2 guidance substrate scoped to PR-review / AGENTS_ATLAS / diagnostics, so no Tier-2 revalidationTrigger AC is required. If implementation expands into AGENTS.md core-rule or critical-gate mutation, add Tier-2 liveness handling before merge.

Discussion Criteria Mapping

• [RESOLVED_TO_AC] Default source-code rule: comments/JSDoc explain durable intent and avoid tickets, PRs, lanes, ACs, cycles, and line-number anchors by default. Covered by AC1, AC2, AC3.
• [RESOLVED_TO_AC] Promotion path: still-relevant historical decisions move to ADR / AGENTS_ATLAS / learn docs / owning primitive docs before code cites them. Covered by AC2 and AC4.
• [RESOLVED_TO_AC] Generic Neo pattern repetition: consumers do not re-explain initAsync(), dotenv, or other framework primitives. Covered by AC3 and AC8.
• [RESOLVED_TO_AC] Test-description carve-out: test titles may cite ticket/AC only when serving as AC-verification surface; test-body comments remain strict. Covered by AC5.
• [RESOLVED_TO_AC] Step-Back partials: substrate placement, KB compatibility, accretion calculus, forward-only migration, and diagnostic/ESLint audit must be acknowledged. Covered by AC6-AC11.

Acceptance Criteria

• AC1: PR-review guidance defines the source-code why-first contract: comments/JSDoc default to no ticket, PR, lane, AC, cycle, or line-number anchors.
• AC2: Guidance defines the promotion path for rare durable historical decisions: promote to ADR, AGENTS/Atlas, learn doc, or owning primitive docs; cite that stable surface or symbol, not the original ticket.
• AC3: Guidance explicitly treats repeated explanations of generic Neo/framework patterns in consumers as an anti-pattern; owning primitives/canonical docs carry those explanations.
• AC4: The review template or checklist includes a concise reviewer check for why-first source-code comments and stable-symbol references.
• AC5: Test-description carve-out is documented: describe() / it() titles may carry ticket/AC anchors when they are AC-verification artifacts; comments inside test bodies follow the strict source-comment rule.
• AC6: Substrate-tier placement is explicit in the PR body. Default target: pr-review-guide.md + AGENTS_ATLAS.md; avoid AGENTS.md unless a short trigger is justified.
• AC7: KB ingestion compatibility is checked with a concrete command or source review; implementation must state whether any KB/JSDoc pipeline depends on ticket IDs in source comments.
• AC8: Substrate-accretion defense is satisfied: net byte impact is declared, and any added loaded substrate includes future-decay mitigation or retirement trigger.
• AC9: Migration strategy is forward-only for v1: new/modified comments comply; existing comments are not actively swept unless touched.
• AC10: Existing lint/diagnostic primitives are audited, including eslint/jsdoc-adjacent options and ai/scripts/lint/ sibling scripts; hard CI enforcement is deferred unless false positives are proven low.
• AC11: Diagnostic-first support exists as a non-failing report or documented command that surfaces candidate source-code archaeology markers on a PR diff or current tree.
• AC12: Canonical allow/avoid examples include line-number references, ticket/lane/AC archaeology, SwarmHeartbeatService-style ownership boundaries, credential separation, dotenv ownership, and initAsync()/ready() consumer-boundary guidance.

Out of Scope

• No active cleanup sweep across the 1,823 broad-match lines found during Discussion #11889. Cleanup is forward-only / lazy-on-touch for v1.
• No hard CI failure in v1 unless the implementation proves diagnostic false positives are low and reviewers agree.
• No rewrite requirement for already-open PRs #11876 / #11877 beyond any new comments added after this ticket is picked up.
• No global ban on history in PR bodies, commits, tickets, Discussions, or ADR provenance sections.
• No new skill unless implementation proves existing PR-review + AGENTS_ATLAS substrate cannot carry the rule without bloat.

Avoided Traps

• Rejected: treating all historical references as invalid. Snapshot artifacts and graph-ingestion surfaces need archaeology.
• Rejected: allowing source comments to cite tickets when they pass a loose subjective test. The cycle-3 rule is default-deny for source-code snapshot anchors.
• Rejected: line-number citations in code comments. They decay silently and are less stable than symbols or canonical docs.
• Rejected: explaining framework primitives in every consumer. That duplicates ownership and makes future framework changes expensive.
• Rejected: immediate CI hard-fail. The diagnostic should measure before enforcement.

Related

• Discussion #11889: https://github.com/orgs/neomjs/discussions/11889
• Related but not duplicate: #10341 (MCP OpenAPI tool-description budget)
• Related substrate precedent: Discussion #11577 / #11557 around reference classification and archaeology placement

Origin Session ID: 967e325b-d90a-43f4-9e91-c212e9bda746

Handoff Retrieval Hints:

• Query Memory Core for Discussion #11889 why-first source-code documentation contract.
• Query Memory Core for tickets should mention code code should not mention tickets line numbers GOTO initAsync dotenv consumers.
• Discussion anchors: DC_kwDODSospM4BBABs (STEP_BACK) and DC_kwDODSospM4BBACO (cycle-3 reconfirmation).