Replace dashed separator comments with headings or region folds

[williamthorsen]

Problem

Noisy boxed and rulered separator comments have accumulated throughout the codebase — roughly 347 occurrences across ~37 files (snapshot 2026-04-19). The dominant form is a 3-line ASCII-art box, but three variants also appear:

// ---------------------------------------------------------------------------
// Canvas / engine dimensions (4:3 aspect ratio)
// ---------------------------------------------------------------------------

// ================================================================
// Section
// ================================================================

// --- Agent state opacities ---

// -- fixtures ----------------------------------------------------------------

All carry the same structural-heading purpose but wrap awkwardly in narrow viewports and add visual noise without information a single-line heading does not already convey.

Context

This is a comment-only refactor — no runtime behavior changes. Labels like Helpers, Test helpers, Sub-function X, Types, and Styles signal collapsible supporting code; most other labels are primary-content headings. The // region | Label fold pattern is already in use in config/build.ts.

Solution

A scripted sweep recognizes four comment-separator forms and replaces each with one of two canonical outputs.

Recognized forms:

• 3-line box with ≥8 dashes or ≥8 equals bounding a label line
• Single-line symmetric: // --- Label --- (≥3 dashes both sides)
• Single-line asymmetric rulered: // -- Label -----… (2 dashes left, ≥3 right)

Outputs:

1. Inline heading (default):

   // -- Canvas / engine dimensions --

2. Region fold (when the label matches the foldable classifier):

   // region | Helpers
   function findAgent(...) { ... }
   // endregion | Helpers

Foldable classifier (case-insensitive match against label text):

• \bhelpers?\b
• \bsub-function\b
• \btype guards?\b
• \btypes?\b
• \bstyles?\b
• \bgetters?\b

Region end is the next separator (boxed, inline, rulered, or existing region) at the same indent, or end-of-file.

Exemption mechanism: a file can opt out with a file-level // separator-sweep: skip comment. No path-based exemptions (pattern precision keeps the vendored prose-delimiter content untouched).

After the scripted pass, a manual review verifies region boundaries — a helper block at the end of a section may need an endregion inserted before non-helper code.

The convention is recorded in packages/agents/content/skills/code-patterns/SKILL.md as a new ### Section separators subsection inside the existing ## Documentation section.

Acceptance criteria

• All four recognized separator forms in TypeScript source are replaced by the inline-heading or region-fold output.
• Repo-wide grep for any of the four source patterns returns zero matches in TypeScript source files (outside files using the // separator-sweep: skip opt-out, if any).
• The prose-delimiter content in packages/agents/content/skills/_platforms/rovodev/systematic-debugging/condition-based-waiting-example.ts is unchanged.
• code-patterns skill documents the separator convention (inline heading + region fold forms) under ## Documentation.
• Existing test suite passes with no test changes beyond comment updates.
• Follow-up ticket filed for an optional CI lint rule preventing reintroduction of the pattern.