This file is the authoritative reference for the project's source-code citation rules. The short form lives in CLAUDE.md.

Rule 1: in-tree line citations are FORBIDDEN

Comments must not reference other files in this repository by <file>:<line> (e.g. libs/ra8_hal/src/ra8_drw.c:776). Line numbers go stale the moment any agent reformats or edits the target file, and they are not searchable – a reader cannot grep for :776 and find anything useful.

Use the function or symbol name instead:

priv_ra8_drw_internal_rect_below_min
ra8_dmac::priv_ra8_dmac_internal_mode_disables_dts
see priv_ra8_dmac_internal_mode_disables_dts in libs/ra8_hal/src/ra8_dmac.c

The pre-commit gate scripts/checks/check_line_citations.py enforces this rule strictly: any new in-tree <file>:<line> reference inside a C/C++ comment, Markdown doc, or plain-text doc is rejected at commit time. The // CITES-OK: <reason> per-line marker is the only opt-out.

Rule 2: external / vendor citations are MANDATORY

Every HAL register access, ISR, and driver path must cite the source of truth so a future reader can verify the implementation against the spec without guessing. Acceptable forms:

/* HUM section 11.2.7 PWPR write-protect register */
/* FSP r_sci_b/r_sci_b.c @ commit 8b3f2c1 */
/* RFC 791 section 3.2 IPv4 header layout */
/* Datasheet R01DS0493EJ table 6.4 */

References to anything under docs/reference/ (the committed PDFs), libs/third_party/, or apps/shared_libs/third_party/ (SOUP) are exempt from rule 1 – those line numbers belong to artifacts we do not edit.

Per-line opt-out: CITES-OK: <reason>

In rare cases an in-tree line citation is the right call (e.g. a historical migration note describing exactly which old line moved where). Add // CITES-OK: <reason> to that line; the gate skips any line containing a non-empty reason after the marker.

/* moved from libs/<old-module>/src/foo.c:412 -- CITES-OK: source file deleted */

/* to libs/ra8_hal/src/ra8_cgc.c::ra8_cgc_init */

CHANGELOG-style "moved from <file>:NNN to ..." snippets are also exempt automatically.

Tooling

Gate: scripts/checks/check_line_citations.py – pre-commit enforcement, and a whole-tree scan on demand.
Extractor: scripts/checks/extract_line_citations.py – emits CSV of every violation with the enclosing function and a suggested <file>::<func> replacement. Used by cleanup agents.