code file headings

• every authored code file opens with one compact JSDoc-style heading block.
• it is operational change metadata, not implementation explanation.
• runtime requires a first line (shebang, directive, generated header)? heading goes immediately after it.

• shared checkout + concurrent work: the heading is the only reliable signal that a file is actively changing and who owns the change.
• without it, an agent silently edits a file another agent is refactoring — a merge conflict one read block would have prevented.
• invariant: read-before-edit — the change boundary is disclosed at the top of the file before any implementation edit.
• code stays the primary explanation: exact names, small responsibilities, typed boundaries, direct control flow. comments can lie or go stale; never compensate for unclear code with them.

/**
 * ongoing:
 * - replace the retired response projection with the canonical contract.
 *
 * completed:
 * - none.
 */

• lower-case prose in headings.
• state only the current ongoing change plus a short resolved record when it helps a future edit.
• remove stale rows in the same forward-only change — not a permanent file history.

every repository AGENTS.md must require, before an agent edits an authored code file:

1. open and read the complete file heading.
2. stop if the heading says the file is protected, generated, or owned by an active change outside the task.
3. add or update the lower-case ongoing row before changing implementation.
4. make the code self-explanatory; no explanatory inline comments.
5. resolve or remove the row after verification.

• a heading is never optional context — it is the file's active edit contract.
• nearest directory instructions may add an exact heading schema, never remove the read-before-edit requirement.

• code never points to documentation: no see docs comments, decision-record links, tutorial paragraphs, no restating symbols the implementation names directly.
• documentation may point to code symbols, file paths, contracts, verification commands — docs explain code from outside the runtime boundary.

bad

// this turns a response into a view model for the sidebar.
// see docs/response-projection.mdx for the design.
export function map(response: Response) {
  return { title: response.name };
}

• duplicates weak code names, points out of the codebase, reveals nothing about active changes.
• concurrent agent gets no coordination signal, edits against whatever it finds, produces the merge conflict the heading exists to prevent.
• prose rots independently of the code; next reader must decide which is lying.

good

/**
 * ongoing:
 * - replace the retired sidebar projection with `mapSidebarResponse`.
 */

export function mapSidebarResponse(response: Response) {
  return { title: response.name };
}

• heading coordinates the active edit; the symbol explains its own responsibility.
• one block at the top buys read-before-edit: every agent learns what is in flight before touching implementation — concurrency coordinates by reading, not by repairing a broken merge.
• kept up across a codebase, the heading is the routine disclosure surface that makes shared-checkout concurrency safe without locking.

• narrate obvious control flow line by line.
• comment a vague name, a large mixed-responsibility function, or a hidden alias — improve the code instead.
• retain stale heading rows, task transcripts, old decisions, changelog history in code files.
• add TODO, FIXME, or documentation-link comments as a substitute for an owned task or specification decision.
• place a heading before a framework-mandated first directive or generated provenance header.

1. every changed authored code file: one valid heading after any mandated first line.
2. read the code with the heading hidden — names, types, control flow must still explain the behavior.
3. search changed code for documentation URLs, see docs, stale task names, explanatory comment growth; remove unsupported commentary.
4. owning docs name the symbols and behavior changed in code — not the reverse.

layered source organization · change visibility · clean code density · slices · domain-keyword organization