[finding] check:skill-examples flags an os:check marker shown INSIDE a fenced example as an orphan, so the convention cannot be documented in the roots it governs #10791

Found while working #10533, which adds a sibling marker convention to the same two roots and had to
solve this case to stay documentable.

packages/spec/scripts/check-skill-examples.ts treats a misplaced os:check marker as a hard error
— correctly, and for a good reason stated in its own comments ("a placed-but-inert marker is worse
than no marker, because it looks intentional"). But the orphan scan has no fence awareness:

// line 228 — a block is only OPENED for `ts`/`typescript` fences
const open = lines[i].match(/^```(ts|typescript)\s*$/);
...
// lines 249-253 — the orphan scan walks EVERY line, with no notion of being inside a fence
const orphans: number[] = [];
for (let i = 0; i < lines.length; i++) {
  if (ALL_MARKERS.includes(lines[i].trim()) && !claimed.has(i)) orphans.push(i + 1);
}

claimed only ever holds marker lines sitting directly above a ts/typescript fence. A ```md
fence is never opened by the walk, so its contents are scanned as top-level markdown — and a marker
line shown inside it is reported as an orphan and fails the gate.

Consequence

The os:check convention cannot be documented inside content/docs/** or skills/** — the two
roots it governs — because writing the marker into an illustrative fenced block trips the gate that
enforces it. Any page explaining "mark a block like this" has to describe the marker without showing
it, which is the same quality cost #10533 was filed for one class over.

Status

Latent today, not breaking. All 192 os:check markers in the tree sit at top level; none is
inside a fence, so the gate is green. This is source-derived (read at the line numbers above), not
executed — worth a confirming run before acting.

Suggested shape

Record the fence spans during the walk and skip the orphan check inside them, so a marker shown as
example text claims nothing and is not an orphan. scripts/check-role-word.mjs does exactly this for
its own marker as of #10533 (analyzeVendorWire, plus a self-test leg pinning that this gate's own
convention stays documentable in the roots it governs) — the shape can be lifted directly.

Not fixed in #10533's PR: different gate, different package, and out of that card's scope.

Generated by Claude Code

Generated by Claude Code