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` fencesconstopen=lines[i].match(/^```(ts|typescript)\s*$/);
...
// lines 249-253 — the orphan scan walks EVERY line, with no notion of being inside a fenceconstorphans: number[]=[];for(leti=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
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.tstreats a misplacedos:checkmarker 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:
claimedonly ever holds marker lines sitting directly above ats/typescriptfence. A```mdfence 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:checkconvention cannot be documented insidecontent/docs/**orskills/**— the tworoots 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:checkmarkers in the tree sit at top level; none isinside 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.mjsdoes exactly this forits own marker as of #10533 (
analyzeVendorWire, plus a self-test leg pinning that this gate's ownconvention 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