change visibility

make intended work visible in specifications and non-code artifacts before implementation, then in the code file itself before its implementation changes. the next human or agent must open the contract and the file and immediately learn what is in flight.

in a shared checkout with concurrent agents, an invisible change is a silent conflict: two edits assume different structure and merge into a broken state. visibility before implementation gives every later reader a coordination point costing one heading row and one specification update. the invariant: the contract and the file always disclose what is in flight, so no agent edits against a hidden boundary.

1. update the owning specification, design, API contract, data decision, runbook, or other non-code artifact first.
2. identify every authored code file that will change.
3. read each file's complete top heading before editing it.
4. add an ongoing row stating the concrete change and its owner or boundary.
5. change the implementation, verify, then resolve or remove the row with concise evidence.

the non-code record explains why and what; the file heading explains what is currently changing here. neither replaces the other. code does not link outward to that record; the documentation names code symbols one way.

every authored code file starts with this JSDoc block. a mandated shebang, framework directive, or generated/tool-owned header stays first; put the block immediately after it. generated files stay tool-owned: record the change in their generator contract instead of editing them.

/**
 * ongoing:
 * - add deterministic workflow-step handoff persistence.
 */

• ongoing is compulsory before modifying implementation; it names an exact responsibility, not "refactor" or "updates".
• keep only active, useful completed, and unresolved rows; remove stale history once the owning specification or changelog preserves it.
• never hide a material decision in the heading — document it outside code when the change affects behavior, data, security, or an API.
• do not edit a code file until its existing heading has been read in full.
• a code file without a heading is brought into this standard as the first change: add the header before implementation.

when several agents can edit the same codebase, do not immediately delete an active implementation surface another agent may still be reading or changing. comment it out temporarily with a compact lower-case marker naming the replacement and the change in progress. this is coordination evidence, not a compatibility path.

// retiring: replace this projection with `build_account_summary` in the active
// summary migration. remove this block after the new path is verified.
// const summary = build_legacy_summary(record);

the replacement's owner must remove the commented-out code and marker after verification. never leave commented-out implementation as a fallback, historical archive, or undecided option; the owning specification, slice, or change record preserves the durable reasoning, and code returns to one current implementation.

this temporary exception protects collaboration visibility. it does not weaken forward-only change: once the active change completes, only the latest correct implementation remains.

bad

agent A changes buildReceipt and removes buildLegacyReceipt without updating the file heading. agent B concurrently edits the same file, still calling buildLegacyReceipt. they merge: A's deletion + B's call to the deleted function silently breaks the build.

// buildReceipt.ts — BEFORE (agent A's view, no heading)
export function buildLegacyReceipt(data: Data) {
  return { items: data.items };
}

export function buildReceipt(data: Data) {
  return { items: data.items, total: data.total };
}

after agent A's edit without a heading:

// buildReceipt.ts — AFTER A's edit (no heading = no visibility)
export function buildReceipt(data: Data) {
  return { items: data.items, total: data.total };
}
// buildLegacyReceipt deleted with no marker

agent B's concurrent change still calls the retired function:

// elsewhere.ts — agent B's edit
import { buildLegacyReceipt } from "./buildReceipt";

export function oldFlow(data: Data) {
  return buildLegacyReceipt(data); // breaks when merged
}

failure mode: silent breakage discovered late — deletion plus stale call site is textually clean, so git reports no conflict while the merged code no longer runs. cost: a broken shared checkout both agents must repair, plus lost trust in the file surface as a map of what is in flight.

good

agent A reads the heading, adds an ongoing row, and leaves the retired call behind a temporary marker so agent B can see the change boundary and coordinate.

/**
 * ongoing:
 * - replace buildLegacyReceipt with buildReceipt; retire deprecated projection.
 *
 * completed:
 * - none.
 */

export function buildReceipt(data: Data) {
  return { items: data.items, total: data.total };
}

// retiring: replaced by `buildReceipt` projection in active receipt refactor.
// remove this block after all callers use the new projection.
// export function buildLegacyReceipt(data: Data) {
//   return { items: data.items };
// }

agent B sees the ongoing marker, locates the retired function, and updates their call before merging. after the new projection is verified, agent A removes both the retired block and the marker in a completing change.

specification-first · layered source organization · forward-only change · verification evidence · live boundary evidence