`content-lint`: warn when a post body links to a different locale than the file it lives in

[hotlong]

Split out of #142 by seat ruling, and sequenced behind #139 because both want scripts/content-lint.mjs.

Why

#142 fixes the generated side: gen-zh-hant.mjs will rewrite /zh-Hans/ link targets to /zh-Hant/ when it converts a post, so Traditional readers stop being sent to Simplified pages. That fix cannot reach the hand-written locales — index.ja.mdx, .ko, .de, .es, .fr are authored by people and agents, and each can carry the same defect with no generator to blame.

A cross-locale link is invisible to every gate today. #137's validator resolves the target and finds it perfectly real — it just belongs to another locale. The page renders, the link works, and the reader is quietly moved out of the language they were reading in, at which point the language switcher offers to "switch" them to the locale they were already in.

Scope

In resolveInternalLink() (or beside it), compare the locale segment of a body link against the locale of the file the link lives in. Mismatch → a finding.

Severity is the design question and it belongs to whoever picks this up. A deliberate cross-locale link is a real thing — an English-only companion post linked from a translated article is exactly what PR #168 does, on purpose, and #137 already makes the alternative a hard 404. So a blanket error would be wrong. Candidate shapes, decide and record the reasoning on this issue:

1. Warn always. Simple; every intentional cross-locale link becomes a permanent warning, which trains people to ignore warnings.
2. Error only when the same-locale target exists. Sharper: if /zh-Hant/blog/x/ is built and the file says /zh-Hans/blog/x/, that is unambiguously a mistake. If the target exists only in English, the link is the author's only option and passes silently. This is the rule the gen-zh-hant.mjs leaves /zh-Hans/ body links intact, so Traditional readers are sent to Simplified pages #142 generator fix already implements on its side.
3. Warn only when the same-locale target exists, as a softer version of 2 while the corpus is cleaned up.

Option 2 mirrors the generator, which is a point in its favour: one rule, two enforcement points.

Measure first

Count what exists before choosing: how many cross-locale body links are in the hand-written locales today, and how many of those have a same-locale target that is actually built. If the answer is "a handful, all with same-locale targets", option 2 is free.

Acceptance

Rule chosen with the reasoning recorded here; ablation showing a mistake caught and an intentional cross-locale link not falsely flagged; pnpm content:lint, pnpm content:lint --published, pnpm check, pnpm build, pnpm seo:smoke green on the current tree.

[hotlong]

Seat ruling on the severity question the card correctly refused to decide: option 2 — error only when the same-locale target exists.

Option 1 is rejected for the reason the card itself gives: a permanent warning on every deliberate cross-locale link trains people to ignore warnings, and this repo's gates are only worth having because they are believed. Option 3 is option 2 wearing a costume — a warning nobody acts on is a finding nobody fixes, and there is no backlog to soften for, because (see below) the corpus is already clean.

Option 2 is right on its own terms, and one point in its favour is decisive: it is the same rule the generator already enforces. #187 rewrites a /zh-Hans/ link to /zh-Hant/ only when the Traditional target is provably built, and withholds the rewrite otherwise because a manufactured 404 is worse than a cross-locale link. That is exactly "wrong when the same-locale target exists, acceptable when it does not". One rule, two enforcement points — the generator repairs what it can, this check catches what it cannot reach. If the two ever disagree, that is a bug in one of them, and a shared rule makes the disagreement visible instead of arguable.

The measurement the card asks for already exists — but re-take it. The #142 dev swept the hand-written locales as an out-of-scope check and reported: all 20 non-self-locale links in ja/ko/de/es/fr are /en/blog/… pointing at three posts that exist only in English (enterprise-ontology-platform-comparison, ontology-vs-semantic-layer-vs-knowledge-graph, forward-deployed-engineer-trap). Under option 2 every one of those passes — the author had no same-locale target to link to. So the rule is free today, exactly as the card predicted.

Do not take that on trust. The corpus has moved since: #196 rewrote three index.ja.mdx files, #201 touched 18 authored files across ja/ko/zh-Hans, and #189 records that there are now seven English-only posts, not three. Re-measure at your own head and report the number. If the rule turns any existing link red, stop and report — that is a content finding, and whether the link or the rule is wrong is a call for the seat, not a thing to fix under this card.

Ablate both directions. The card names them and they are the whole acceptance:

1. A mistake is caught — a ja post linking /zh-Hans/blog/x/ where /ja/blog/x/ is built → error naming both the link and the target that exists.
2. An intentional cross-locale link is not flagged — a ja post linking /en/blog/forward-deployed-engineer-trap/, which exists only in English → passes silently.

Leg 2 is the one that matters. A check that cannot tell the difference is worse than no check, because it would make PR #168's deliberate links permanently red. Mutation confirmed on disk by anchored grep before each measurement, restore proven by blob hash against HEAD (empty hash is a failure, not a pass), trap on absolute paths, git status --porcelain empty afterwards.

Error wording matters here more than usual. The author reading it needs to know which of the two situations they are in. Say what locale the file is, what locale the link points at, and that the same-locale target does exist — because the repair is to change the locale segment, not to delete the link.

Claim: PM loop round 4 (wave 8)
Session: session_01FeA1nwBz1ohH65dvffUGKr
Branch: claude/issue-179-cross-locale-link-check
Worktree: www.objectos.ai-issue-179
Domain: repo:www.objectos.ai (single-lane execution seat)
File surface: scripts/content-lint.mjs. Content files only if the measurement turns something red — and then you stop and report rather than editing.
Container & model: M, mode:subagent, model: opus
Clause-②: no
Serial constraints cleared: #139 (82edbd2), #185 (5d4b0b6) and #174 (ca3983b) have all landed and released scripts/content-lint.mjs. #162 is held behind you — it wants the same file. #194 owns src/lib/zhconvert.ts and the Traditional corpus and does not collide.

⚠️ This container has restarted twice in the last hour and killed three agents, two of them losing unpushed work. Commit and push in increments — the measurement first, then the rule, then the ablation. A restart must cost one step, not the card.

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 implementation of the seat ruling (option 2: error only when the same-locale target exists).

Session: session_01FeA1nwBz1ohH65dvffUGKr
Branch: claude/issue-179-cross-locale-link-check (pushed empty at ca3983b as a write-route probe before the first edit)
Worktree: ../www.objectos.ai-issue-179
Base: ca3983bc7cb950fb20cf929b90137619799fdff5 (origin/main)
File surface: scripts/content-lint.mjs. Assignee untouched.

Plan, pushed in increments per the container-restart warning: (1) re-measure the cross-locale link corpus at this head and report the count, (2) the rule in/beside resolveInternalLink(), (3) both ablation legs with on-disk mutation proof and blob-hash restore.

---

Generated by Claude Code

---

Generated by Claude Code

[hotlong]

os-dev-report

{
  "issue": 179,
  "status": "done",
  "branch": "claude/issue-179-cross-locale-link-check",
  "pr": "https://github.com/objectstack-ai/www.objectos.ai/pull/202",
  "premise_still_valid": true,
  "summary": "Implemented the seat ruling's option 2 in scripts/content-lint.mjs: a body link naming a locale the file is not written in is a blocking error ONLY when the same-locale target is built. New crossLocaleMiss() sits beside resolveInternalLink() and answers 'does the same-locale target exist' by calling resolveInternalLink() on the locale-swapped URL rather than re-deriving existence per surface -- one producer of that fact, so this check and the #187 generator rewrite cannot drift into disagreement. A link that already fails to resolve keeps exactly one finding (the accurate one) instead of a second one about its locale segment. A warn verdict (the noindexed English fallback the glossary/marketing registries serve) deliberately does NOT count as existing, so the rule fires only on the unambiguous case. Re-measured at ca3983b before writing anything: 335 authored files, 187 internal links carrying a routable locale segment, 28 cross-locale, and 0 of them have a same-locale target -- the rule turns NOTHING in the corpus red, so no content file is touched. All 28 are /en/blog/... links from de/es/fr/ja/ko/zh-Hans/zh-Hant copies of enterprise-ontology-race-open-vs-closed to three English-only posts (enterprise-ontology-platform-comparison, ontology-vs-semantic-layer-vs-knowledge-graph, forward-deployed-engineer-trap). The prior number of 20 moved to 28 only because the same four links now also exist in that post's zh-Hans and zh-Hant copies; the target set is unchanged, and the English-only slug count is 7, matching #189. One commit, one file, +95 lines, no changeset (this repo has no .changeset/ and no skip-changeset label mechanism).",
  "tests": "All gates through bash /home/user/objectstack/scripts/pm/os-verify-lock.sh -c '<cmd>', exit captured before any pipe, at git rev-parse --short HEAD = 015d9ab, git status --porcelain empty afterwards. (1) pnpm content:lint -> '✓ content lint passed (335 files, 44 glossary terms checked)', lock 'VERDICT command-exit 0'. (2) pnpm content:lint --published -> same verdict line, 'VERDICT command-exit 0'. (3) pnpm check -> 'Result (135 files): 0 errors, 0 warnings, 0 hints', 'VERDICT command-exit 0'. (4) pnpm build -> '✓ zh-Hant: generated 46, kept 0 hand-maintained, 5 with body links pointed at /zh-Hant/' then '[build] 867 page(s) built in 61.85s' then '✓ content lint --dist passed (474 built blog pages checked)' (the #201 --dist leg), 'VERDICT command-exit 0 · held the lock 66s'; gen:zh-hant left the tree unchanged. (5) pnpm seo:smoke -> 'SEO smoke test passed (866 HTML pages checked)', 'VERDICT command-exit 0'. ABLATION, three legs, one script with trap '<restore>' EXIT INT TERM on absolute paths; fixture content/blog/ai-agent-workbench/index.ja.mdx, HEAD blob a9762c22cedcfc82ac8664fecc31064f147a6eff read via git rev-parse HEAD:<path> and asserted non-empty before anything ran. Each leg: mutation appended, then proven on disk by anchored grep -cF of the exact inserted link (count asserted == 1) BEFORE the measurement; restore via git checkout HEAD -- <abs path> then proven by git hash-object == the HEAD blob (an empty hash aborts the run as a failure) plus git diff --quiet HEAD. LEG 1 (mistake caught): appended [コンプライアンス統制](/zh-Hans/blog/ai-compliance-control/) to the ja file, grep -cF = 1, content-lint exit 1, '✗ content lint failed (1 blocking issue)', message names both the link and /ja/blog/ai-compliance-control/. LEG 2 (deliberate link NOT flagged -- the leg that matters): appended [FDE の罠](/en/blog/forward-deployed-engineer-trap/) to the same ja file, grep -cF = 1, exit 0, '✓ content lint passed (335 files, 44 glossary terms checked)', 0 findings naming the fixture -- PR #168's links stay green. LEG 3 (rule ablated, to prove leg 1's finding comes from the new code): the SAME leg-1 mutated tree linted by the ca3983b copy of the script, asserted not to contain crossLocaleMiss, exit 0, '✓ content lint passed', 0 findings naming the fixture. Final 'git status --porcelain' printed empty; the temporary base-script copy was removed by the trap. No build/dist rebuild leg is involved -- content-lint.mjs is executed directly from source by the pnpm script, so there is no dist/ artifact that could serve a stale mutation.",
  "open_questions": [],
  "out_of_scope_findings": []
}

Notes for the seat, outside the JSON:

• Nothing turned red, so rule 3 of the ruling ("if the rule turns any existing link red, STOP and report") did not trigger. The measurement was taken with a standalone script that copies only the small helpers from content-lint.mjs, so it could not be shaped by the rule it was measuring for; the implemented rule then agreed with it (pnpm content:lint green on the untouched corpus).
• The two enforcement points visibly agree on this tree. pnpm build reports 5 with body links pointed at /zh-Hant/ — five /zh-Hans/ links the generator rewrote — and the new check then finds zero cross-locale links left in the generated Traditional files. Had the generator withheld any of those five, this check would have named them.
• One judgement call worth recording: a warn-level same-locale resolution (the noindexed English fallback served for glossary terms and marketing pages) is treated as not existing, so it does not raise an error. Choosing the real /en/ page over a noindexed English-bodied duplicate is a defensible authoring call, and option 2's discipline is to fire only on the unambiguous case. There are zero such links in the corpus today, so this decision is currently free either way — but it is the one place where this check is deliberately narrower than "any locale mismatch".

---

Generated by Claude Code

---

Generated by Claude Code

[hotlong]

Correction to the os-dev-report above — the JSON is unchanged and still parses; this is only about four angle-bracket placeholders the body sanitizer stripped after the comment was stored. Three of them invert or blank a meaning, so re-spelled here with square brackets:

stored as	was written, and is what actually ran
trap '' EXIT INT TERM	trap '[restore]' EXIT INT TERM — a real restore handler, not the shell's ignore-the-signal form that trap '' means
os-verify-lock.sh -c ''	os-verify-lock.sh -c '[command]'
git rev-parse HEAD:	git rev-parse HEAD:[path]
git checkout HEAD --	git checkout HEAD -- [absolute path]

Nothing else in the report is affected, and the numbers, verdict lines and leg results all stand as written. Recording it because a reader of the stored text would otherwise see trap '' and reasonably conclude the ablation had no restore leg at all.

---

Generated by Claude Code

---

Generated by Claude Code