MDX frontmatter is now split and parsed in two scripts with no shared helper

[hotlong]

The finding

Observation, not a defect — filing it for triage rather than acting on it.

Two scripts now open blog MDX files and pull the YAML frontmatter out by hand, with the same fence-splitting logic written twice:

• scripts/content-lint.mjs — splitFrontmatter(source, file)
• scripts/lib/post-dates.mjs — frontmatter(source, file) (added by the sitemap lastmod work)

Both assert the file opens with a --- fence, find the closing fence with indexOf('\n---', 4), and hand the slice to js-yaml. Neither knows about the other.

Why it was not consolidated in the PR that created it

The obvious move — extract the split into scripts/lib/ and have content-lint.mjs import it — would have edited scripts/content-lint.mjs, which was claimed by other in-flight work at the time. Touching it would have created a conflict for no functional gain, so the new reader got its own copy, documented as such.

That was the right call for one PR and is the wrong shape to leave permanently: the two copies can drift, and the frontmatter fence is exactly the kind of parsing detail where a divergence is silent (one script accepting a file the other rejects).

Scope sketch

• Move the fence split into a shared helper (scripts/lib/frontmatter.mjs, or export it from post-dates.mjs), and have both callers use it.
• Keep the error messages each caller produces — content-lint.mjs reports against its own file list and its wording is part of its output contract.
• Worth checking whether scripts/gen-zh-hant.mjs, scripts/new-post.mjs and scripts/to-wechat.mjs have their own copies too; this issue only confirmed the two above.

Not urgent

Nothing is broken today: both copies behave identically on the current content tree (pnpm content:lint passes on 334 files, and the sitemap map reads the same 334). This is a consolidation to do once the files involved are free, not a fix to rush.

Found while implementing #104.

Generated by Claude Code

[hotlong]

The lane is finally free — taking it. scripts/content-lint.mjs has been the busiest file in the repo today: #139 (82edbd2), #185 (5d4b0b6), #174 (ca3983b) and #179 (8a36292) all landed in it, which is exactly why this card sat behind them. Nothing wants it now.

The card is right that this is not urgent and right about why it should still be done: two copies of a parsing detail drift silently, and the frontmatter fence is the worst place for that — one script accepting a file the other rejects, with no gate able to see the disagreement.

裁决

1. One helper, both callers, copies deleted. Not a wrapper that re-implements, not a re-export that leaves the second body in place. If after the change grep -c "indexOf('\\n---'" scripts/ is not 1, the card is not done.

2. Keep each caller's error wording exactly. content-lint.mjs reports against its own file list and its wording is part of its output contract — four gates and a --dist mode now depend on that output being stable. The helper reports what went wrong; the caller decides how to say it.

3. Sweep the other three the card names — gen-zh-hant.mjs, new-post.mjs, to-wechat.mjs. If any has its own copy, consolidate it in the same pass. If any copy differs behaviourally from the other two, stop and report rather than picking a winner — a difference that exists on purpose is a finding, and a difference that exists by accident is a bug in whichever one is wrong. Either way the seat decides, not the refactor.

4. The ablation for a pure consolidation is behavioural equivalence, and it is the whole acceptance. A green tree proves nothing here — the tree was green before. Feed pathological inputs through every caller, at main and at your head, and require byte-identical output:

   • no opening fence
   • opening fence, no closing fence
   • empty frontmatter (---\n---\n)
   • a --- inside the YAML body
   • a --- inside a fenced code block in the article body
   • CRLF line endings
   • a UTF-8 BOM before the fence
   • frontmatter that is valid YAML but not a mapping (a bare string, a list)

   Report the table. Any row where main and your head differ is either a bug you introduced or a divergence you have just discovered between the two copies — both are worth more than the refactor itself. Mutation confirmed on disk before each measurement, restore proven by blob hash, trap on absolute paths, tree clean.

5. No behaviour change ships under this card. If the helper would fix a bug one copy has, report it and leave it — that is a separate card with its own ablation.

Verification: the five gates through the shared lock, exits captured before any pipe, each verdict quoted with git rev-parse --short HEAD, tree clean. Note pnpm build now ends with node scripts/content-lint.mjs --dist (#201) — that leg must stay green, and it exercises the same parser.

Claim: PM loop round 4 (wave 8)
Session: session_01FeA1nwBz1ohH65dvffUGKr
Branch: claude/issue-162-shared-frontmatter-helper
Worktree: www.objectos.ai-issue-162
Domain: repo:www.objectos.ai (single-lane execution seat)
File surface: scripts/content-lint.mjs, scripts/lib/post-dates.mjs, a new scripts/lib/frontmatter.mjs if you go that way, and the other three scripts only if the sweep finds a copy in them. No content files.
Container & model: M, mode:subagent, model: opus
Clause-②: no
Serial constraints cleared: #139, #185, #174 and #179 have all landed. #194 is in flight and owns src/lib/zhconvert.ts and the Traditional corpus — if your sweep finds a frontmatter copy inside scripts/gen-zh-hant.mjs, report it and leave it; that file is not yours this round.

⚠️ This container restarted twice earlier and killed three agents, two of them losing unpushed work. Commit and push in increments — the sweep first, then the helper, then the equivalence table.

Environment ruling carried forward: REST and gh are unreachable from this container (403). GitHub MCP is the sanctioned channel here, overriding the REST-only instruction in .claude/agents/os-dev.md for this repo.

---

Generated by Claude Code

[hotlong]

Dev claim — starting now.

Session: session_01FeA1nwBz1ohH65dvffUGKr
Branch: claude/issue-162-shared-frontmatter-helper (pushed empty as a write-route probe, base 8a36292)
Worktree: ../www.objectos.ai-issue-162

Plan, in the increments the claim comment asks for (commit + push after each):

1. Sweep content-lint.mjs, lib/post-dates.mjs, new-post.mjs, to-wechat.mjs (and read-only on gen-zh-hant.mjs, which Five more s2twp over-substitutions are wrong in any register — 介面卡 is a network interface card, not an adapter #194 owns) for frontmatter-split copies; report any behavioural divergence rather than picking a winner.
2. Extract one helper, both callers import it, copies deleted — each caller keeps its own error wording verbatim.
3. Behavioural-equivalence table: the eight pathological inputs through every caller at main and at head, byte-identical output required. The main column will be produced by running the actual main scripts (git worktree at origin/main), not reconstructed.

Gates through the shared lock, verdicts quoted with the head sha.

Generated by Claude Code

---

Generated by Claude Code

[hotlong]

os-dev-report

{
  "issue": 162,
  "status": "done",
  "branch": "claude/issue-162-shared-frontmatter-helper",
  "pr": "https://github.com/objectstack-ai/www.objectos.ai/pull/207",
  "premise_still_valid": true,
  "summary": "The fence split now lives once, in the new scripts/lib/frontmatter.mjs; both copies are deleted and `grep -ro \"indexOf('\\n---'\" scripts/ | wc -l` is 1 (裁决 1). The helper never throws — it returns {ok:true,raw,body} or {ok:false,reason:'no-opening-fence'|'no-closing-fence'} — so each caller keeps its own wording verbatim (裁决 2): content-lint.mjs's local splitFrontmatter(source,file) keeps its signature and both throw texts, so its two call sites are untouched, and post-dates.mjs keeps its third message ('has empty or non-object frontmatter') because that is a YAML policy, not a fence fact. No YAML parsing, trimming or normalization moved into the helper (裁决 5). The sweep found TWO more splitters, not the one the card anticipated: scripts/gen-zh-hant.mjs:168 (owned by #194, read-only here) and scripts/lib/wechat-html.mjs:43, which the card did not name — it is reached via to-wechat.mjs, which has no copy of its own. Both differ behaviourally on purpose (regex-based, non-failing, and wechat-html uses no js-yaml at all), so per 裁决 3 I did not pick a winner: both are left exactly as they are, the difference is documented at the bottom of the new helper, and the decision is filed as #205 for the seat. new-post.mjs has no copy — it only writes a frontmatter template. One factual correction to the claim comment: the `pnpm build` --dist leg does NOT exercise this parser — content-lint.mjs:230 exits before any frontmatter is read — though it is green as a gate.",
  "tests": "EQUIVALENCE (the whole acceptance, 裁决 4). main column produced by RUNNING the main scripts, not reconstructed: a second worktree detached at origin/main (8a36292), `git status --porcelain` empty. Head column at 4e50717. All three callers driven per case — content-lint.mjs, content-lint.mjs --published, and readPostLastmods() from post-dates.mjs (the sitemap map read by astro.config.mjs and seo-smoke.mjs). 9 pathological cases (the 8 the card listed, with the non-mapping one split into bare-string and list): no opening fence · opening fence no closing · empty frontmatter · `---` in the YAML body · `---` in a body code fence · CRLF · UTF-8 BOM · bare string · list. `diff -r` over the two columns — 9 cases x 3 legs, full transcripts including the entire 336-entry lastmod map — exits 0. BYTE-IDENTICAL ON EVERY ROW; no row differs. Only normalization: each worktree's own absolute path replaced with <ROOT> (the roots genuinely differ on disk). HARNESS SENSITIVITY (nine identical rows prove nothing unless the harness can see a difference): two mutations of the one shared split, each confirmed on disk by anchored grep on BOTH the removed and the injected text before measuring. Leg A startsWith('---\\n')->startsWith('---'): counts 1->0 / 0->1, blob b2d682c, 1 row went red (case 06 CRLF starts parsing, post-dates 1->0, map grows to 336). Leg B indexOf('\\n---',4)->lastIndexOf('\\n---'): counts 1->0 / 0->1, blob ccbb33c, ALL 9 rows went red. Both restored via `git checkout HEAD -- <path>` from a trap on absolute paths; restore proven by blob hash 211d1e4 == HEAD:scripts/lib/frontmatter.mjs, `git diff HEAD` empty, `git status --porcelain` 0 lines. NOTE: leg B's first attempt reported from=0 to=0 and the harness REFUSED to measure — bash had interpolated the replacement into perl source where \\n became a real newline, so the mutation landed as something else; without the anchored check on the injected text that run would have produced a table and read as a measurement. Both sides now go through the environment. GATES, all at 4e50717, through bash /home/user/objectstack/scripts/pm/os-verify-lock.sh -c, each exit captured before any pipe, verdicts as the gates printed them: `pnpm content:lint` EXIT=0 '✓ content lint passed (335 files, 44 glossary terms checked)'; `pnpm content:lint --published` EXIT=0 same line; `pnpm check` EXIT=0 'Result (136 files): - 0 errors - 0 warnings - 0 hints'; `pnpm build` EXIT=0 '[build] 867 page(s) built in 59.31s' then '✓ content lint --dist passed (474 built blog pages checked)'; `pnpm seo:smoke` EXIT=0 'SEO smoke test passed (866 HTML pages checked)'. `git status --porcelain` empty after the gate run. Lock verdict lines: 'VERDICT command-exit 0 · held the lock 14s · waited 77s' (fast gates) and 'VERDICT command-exit 0 · held the lock 65s (1m05s) · waited 0s' (build + seo:smoke). No changeset: this repo has no .changeset/ and no changesets dependency, and nothing here is user-visible.",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #205 (label `finding`, unassigned): two more frontmatter splitters remain after this card — scripts/gen-zh-hant.mjs:168 and scripts/lib/wechat-html.mjs:43 — both regex-based, both non-failing, and wechat-html reads single-line scalars with a regex instead of js-yaml. Deliberate differences (neither is a gate), so 裁决 3 says report rather than pick a winner; both left untouched and the difference documented in the new helper.",
    "filed as #206 (unassigned, no label — pre-existing, reproduces identically at 8a36292 and at head): `pnpm content:lint --published` prints '✓ content lint passed' on a frontmatter that is valid YAML but not a mapping, because data.status is undefined and the file is skipped by the --published filter; `astro.config.mjs` then throws 'has empty or non-object frontmatter' at config load. Verified directly: gate exit 0, config load exit 1. The divergence is after the fence split, so consolidating the fence neither caused nor cured it; not fixed here under 裁决 5."
  ]
}

Generated by Claude Code

---

Generated by Claude Code