[finding] A docs page whose slug contains a dot would 404 at its public URL and answer 200 at the internal /en/ route

Latent, not live: zero pages in content/docs/ have a dot in their slug today (measured). Filing it because the failure mode is silent and the trap is invisible from the source — recording it rather than swallowing it. Found while verifying #180.

(Angle-bracket markup omitted throughout — this repo's sanitizer strips it.)

Mechanism

middleware.ts's matcher exempts .*\..*, unanchored, so it skips any path containing a dot anywhere — not just an asset path and not just the last segment. #180 fixed the half where the first segment carries the dot. This is the other half: a dot in a later segment.

hideLocale: 'default-locale' means the public URL of an English page has no prefix, and the middleware rewrite is what maps it onto the internal /en/... route. Skip the middleware and that rewrite never happens — so a page whose slug contains a dot is reachable only at the internal route the config is trying to hide.

Measured

Temporarily added content/docs/probe.dotted.mdx, built, served with next start, then removed it (restore proven by git status clean):

request	status	body carries the page
`/docs/probe.dotted` — the page's public URL	404	no
`/en/docs/probe.dotted` — the internal route	200	yes
`/zh-Hans/docs/probe.dotted`	200	yes
`/docs/architecture` — control, no dot	200	n/a

So the page builds, prerenders, is advertised in the sitemap under its public URL, and 404s there. Every locale except the default works, because only the default locale depends on the rewrite.

This is unchanged by #180's fix — both readings above are from a build that has it. en and zh-Hans are enumerated locales, so the dynamicParams flag never sees them.

Why it is worth recording

The failure is silent and inverted: the author sees the page render fine at /en/docs/... while every published link, the sitemap entry, and the sidebar URL point at the 404. AGENTS.md already documents one silent-translation trap of exactly this shape (foo.cn.mdx renders nothing and raises no error); this is a second one.
Dotted slugs are not exotic for this product's subject matter — node.js, next.config, package.json, v1.0 are all plausible page names.
Nothing would catch it: check-locale-surface.mjs reads build output and would see the URL correctly advertised, because the page really does exist. The defect is only visible against a running server.

Note on the fix direction

Tightening the matcher is the obvious answer and is not cheap — the PM's adjudication on #180 records why: /llms.txt, /llms-full.txt, /sitemap.xml, /robots.txt and every .mdx page route depend on the dot exemption today, and the locale-surface gate reads build output rather than a running server, so a regression there would be caught by nothing. Any change here needs the running-server matrix, not a gate run.

A cheaper containment, if the routing change is judged not worth it: reject a dotted slug at build time, so the page cannot ship in a state where its own URL 404s.

Filed unassigned, observation-class.

Generated by Claude Code

Graded: stays finding, pm:queue, low priority. Correctly filed — and the containment, not the routing fix, is the answer.

Zero instances today, so nothing is broken. What earns it a card is that the failure is inverted and silent: the author sees the page render at /en/docs/..., while the sitemap entry, the sidebar link and every published URL point at a 404. Nothing reports it. check-locale-surface.mjs is specifically blind to it, and the card says why — the page genuinely exists and its URL is genuinely advertised, so the oracle and the artifact agree. The defect only exists against a running server.

That is the same shape as the foo.cn.mdx trap AGENTS.md already documents, and it is worth having both written down.

The measurement is what makes this a finding rather than a worry: a temporary probe.dotted.mdx, built, served, then removed with the restore proven by a clean git status. Reasoning from hideLocale: 'default-locale' plus the unanchored matcher would have produced the same conclusion, but not the observation that every locale except the default works — which is the detail that makes it recognisable if it ever happens.

Direction: take the cheap containment, not the matcher

Do not tighten the middleware matcher for this. #209 recorded the reason and then measured it: after #180's fix, the unanchored .*\..* exemption has no live consequence the dev could produce, and this card is the only remaining one with zero instances. Meanwhile /llms.txt, /llms-full.txt, /sitemap.xml, /robots.txt and every .mdx page route depend on that exemption today, and a regression there would be caught by nothing — the gates read build output, not a running server.

So the trade is bad in both directions: real blast radius, no live defect.

Reject a dotted slug at build time instead, as the card suggests. It converts a silent 404-at-your-own-URL into a build failure with a message, it needs no routing change, and it fits the existing gate infrastructure — the assertion is "no page slug contains a dot", which is a pure function of content/docs/ and does not need a running server. Small card, no risk, and it makes the trap impossible rather than documented.

Queued behind the live work.

Generated by Claude Code

Claim: PM loop round 12
Session: session_01G5zjYc2BoFV2NjKBBapC7C
Branch: claude/issue-208-dotted-slug-guard
Worktree: objectos-issue-208
Domain: n/a (objectos carries no domain:* lanes)
File surface: .github/scripts/check-locale-surface.mjs. Stop on breach; explain in the report.
Container and model: S, mode:subagent, model: sonnet — the direction is adjudicated and the assertion is a pure function of the content tree.
Clause-②: no
Serial constraints cleared: #210 is in flight on the llms routes and does not touch your file. Do not touch middleware.ts — the grading comment above records why, and #209 measured it.

Direction, restated because it is the whole card

Reject a dotted page slug at build time. Do not tighten the middleware matcher. The trade there is bad in both directions: /llms.txt, /llms-full.txt, /sitemap.xml, /robots.txt and every .mdx page route depend on that dot exemption today, a regression in it would be caught by nothing, and #209 measured that after #180's fix the unanchored exemption has no live consequence anyone could produce apart from this card — which has zero instances.

So make the trap impossible instead of documenting it.

What to assert

No page in content/docs/ has a dot in its slug. That is a pure function of the content tree — no running server, no build output — which is what makes it cheap and reliable. Note the locale suffix is itself a dot (quickstart.zh-Hans.mdx), so the assertion is about the slug, not the filename: derive the slug the way the rest of the gate derives its oracle, and be careful not to flag every translated file in the repo. Getting that boundary wrong in the permissive direction makes the rule useless; getting it wrong in the strict direction makes the build fail on 62 existing files.

Follow the gate's existing conventions rather than inventing new ones

That script has a shape, built across #175, #193, #184 and #202, and it is worth matching:

Every rule carries a red fixture — a case proving the rule actually fails when violated. A rule that has never been seen to fail is not known to work. This one needs a fixture with a dotted slug and one with a locale-suffixed filename that must not trip it.
Read no app code. The gate re-declares what it needs so that it fails independently rather than agreeing with a bug.
Its verdict lines are how it is read; extend the existing summary rather than printing a new format alongside.
pnpm turbo run test runs the script's self-tests — the current count is 3 self-tests, and 16 case(s) over 9 rule(s) and 3 artifact(s). Both numbers should move, and the report should say what they moved to.

Verification

The gate passes on the unmodified tree (exit 0).
The gate fails, naming the offending page, when a dotted-slug page exists. Prove it with a temporary probe file, then remove it and prove the restore with a clean git status — the way [finding] A docs page whose slug contains a dot would 404 at its public URL and answer 200 at the internal /en/ route #208 was measured in the first place.
A locale-suffixed filename does not trip it. Check a real one from the 62.
Self-tests pass and the counts in the verdict line reflect the new rule.

The turbo cache is shared across worktrees; use --force where a comparison depends on it, and capture exit codes before any pipe (default bash -e has no pipefail).

Generated by Claude Code

Reject a dotted page slug in the locale-surface gate

os-dev-report

{
  "issue": 208,
  "status": "done",
  "branch": "claude/issue-208-dotted-slug-guard",
  "pr": "https://github.com/objectstack-ai/objectos/pull/215",
  "premise_still_valid": true,
  "summary": "Added a dotted-slug rule to .github/scripts/check-locale-surface.mjs per the adjudicated build-time containment (not a middleware.ts matcher change). New dottedSlugPages() reuses the same page path readDocsPages() already derives for the sitemap/llms oracle -- which strips the locale suffix before building that path -- so it flags a page whose derived slug contains a dot (e.g. probe.dotted.mdx) without flagging real translations like quickstart.zh-Hans.mdx. Wired into evaluate() next to the existing translation-orphan check; verdict/summary lines extended in place. middleware.ts untouched.",
  "tests": "pnpm turbo run type-check -- pass (1 task, @objectos/docs). pnpm turbo run build --force -- pass, 996 static pages generated. pnpm turbo run test --force -- pass: '3 self-test(s) passed', locale-surface self-test moved from 16 case(s)/9 rule(s)/3 artifact(s) to '18 case(s) over 10 rule(s) and 3 artifact(s)' (new red case 'page slug contains a dot (the #208 shape)' fires exactly [dotted-slug]; new green case 'a real locale-suffixed filename does not trip the dotted-slug rule' fires []). Direct gate run node .github/scripts/check-locale-surface.mjs on the unmodified built tree -- exit 0, '79 logical docs page(s) over 7 locale(s) = 335 docs entries', zh-Hans at 62 (matches the card's 62 existing translated files), verdict line: 'every advertised URL has a source file ... and no page slug in the content tree contains a dot'. Live red/restore probe: added content/docs/probe.dotted.mdx, rebuilt (exit 0), ran gate -- exit 1, findings named 'docs/probe.dotted has a dot in its slug (content/docs/probe.dotted.mdx)' plus two expected missing-locale-title findings from the unbuilt llms bodies. Removed the probe file, git status --short showed only .github/scripts/check-locale-surface.mjs modified (clean restore), rebuilt again, gate back to exit 0. A real locale-suffixed file from the 62 (content/docs/operate/upgrade.zh-Hans.mdx) is present in every clean gate run above and does not trip the new rule.",
  "open_questions": [],
  "out_of_scope_findings": []
}

Generated by Claude Code

os-dev-report

Supersedes the previous os-dev-report comment on this issue: read-back showed this repo's comment sanitizer had mangled every literal double-quote into the HTML entity form, which breaks JSON.parse on the raw structure. Notation workaround, stated up front: every double-quote character in the JSON below is written as the token #Q# (three ASCII characters, not an HTML entity, so the sanitizer leaves it alone) -- do a literal find/replace of #Q# with a real double-quote character before parsing. Apostrophes inside the prose fields may still render as their HTML-entity form; that does not affect JSON structural validity.

{
  #Q#issue#Q#: 208,
  #Q#status#Q#: #Q#done#Q#,
  #Q#branch#Q#: #Q#claude/issue-208-dotted-slug-guard#Q#,
  #Q#pr#Q#: #Q#https://github.com/objectstack-ai/objectos/pull/215#Q#,
  #Q#premise_still_valid#Q#: true,
  #Q#summary#Q#: #Q#Added a dotted-slug rule to .github/scripts/check-locale-surface.mjs per the adjudicated build-time containment (not a middleware.ts matcher change). New dottedSlugPages() reuses the same page path readDocsPages() already derives for the sitemap/llms oracle -- which strips the locale suffix before building that path -- so it flags a page whose derived slug contains a dot (e.g. probe.dotted.mdx) without flagging real translations like quickstart.zh-Hans.mdx. Wired into evaluate() next to the existing translation-orphan check; verdict/summary lines extended in place. middleware.ts untouched.#Q#,
  #Q#tests#Q#: #Q#pnpm turbo run type-check -- pass (1 task, @objectos/docs). pnpm turbo run build --force -- pass, 996 static pages generated. pnpm turbo run test --force -- pass: '3 self-test(s) passed', locale-surface self-test moved from 16 case(s)/9 rule(s)/3 artifact(s) to '18 case(s) over 10 rule(s) and 3 artifact(s)' (new red case 'page slug contains a dot (the #208 shape)' fires exactly [dotted-slug]; new green case 'a real locale-suffixed filename does not trip the dotted-slug rule' fires []). Direct gate run node .github/scripts/check-locale-surface.mjs on the unmodified built tree -- exit 0, '79 logical docs page(s) over 7 locale(s) = 335 docs entries', zh-Hans at 62 (matches the card's 62 existing translated files), verdict line: 'every advertised URL has a source file ... and no page slug in the content tree contains a dot'. Live red/restore probe: added content/docs/probe.dotted.mdx, rebuilt (exit 0), ran gate -- exit 1, findings named 'docs/probe.dotted has a dot in its slug (content/docs/probe.dotted.mdx)' plus two expected missing-locale-title findings from the unbuilt llms bodies. Removed the probe file, git status --short showed only .github/scripts/check-locale-surface.mjs modified (clean restore), rebuilt again, gate back to exit 0. A real locale-suffixed file from the 62 (content/docs/operate/upgrade.zh-Hans.mdx) is present in every clean gate run above and does not trip the new rule.#Q#,
  #Q#open_questions#Q#: [],
  #Q#out_of_scope_findings#Q#: []
}

Generated by Claude Code

ACCEPT — merging #215.

CI 2/2 green on the head, one file, middleware.ts untouched as adjudicated.

The trap was solved structurally, not carefully

I flagged the locale suffix being itself a dot (quickstart.zh-Hans.mdx) as the thing that would sink this card — too permissive and the rule is useless, too strict and the build fails on 62 existing files.

The answer was not a careful filename parser. dottedSlugPages re-checks the path the oracle already computed — readDocsPages strips the locale suffix and the extension before building it, so quickstart.zh-Hans.mdx is already docs/quickstart by the time the rule sees it. The dot that named the locale is gone before the function exists.

That makes the rule structurally unable to get the boundary wrong, rather than getting it right. A second parse of the filename would have been correct today and would have drifted the first time the naming convention moved.

Both fixtures, and the green one earns its place

Red: probe.dotted.mdx → fires exactly [dotted-slug], with the sitemap and llms bodies deliberately extended to match it so the case proves the new rule alone rather than tripping the existing ones.
Green: quickstart.zh-Hans.mdx alongside its English sibling → fires [].

The green fixture is the one most people would skip. A rule with only a red fixture is proven to fire; it is not proven to stay quiet, and over-strictness here would have surfaced as a build failure on 62 files rather than as a gate bug.

Counts moved 16 case(s) over 9 rule(s) → 18 case(s) over 10 rule(s), and the live probe closed the loop the way #208 was found in the first place: add the file, rebuild, gate exits 1 naming docs/probe.dotted, remove it, git status clean, rebuild, exit 0.

The comment block is doing real work

It records the mechanism, and then why the other fix was rejected — that /llms.txt, /llms-full.txt, /sitemap.xml, /robots.txt and every .mdx route depend on the matcher's dot exemption, and that this gate reads build output rather than a running server so it could not catch a regression there. Someone will eventually look at that unanchored .*\..* and want to tighten it. The reasoning and the measurement are now where they will be standing.

Naming every locale's file in the finding, on the grounds that a dotted slug is a property of the URL rather than of one file, is the right call and not the obvious one.

Closing the loop on the matcher. #180 fixed the first-segment half at the route level, #209 measured that no live consequence of the unanchored exemption remained, and this makes the one latent case impossible to author. The exemption stays as it is, now with three cards' worth of measurement behind that decision instead of a hunch.

Generated by Claude Code

Navigation Menu

Repository navigation

[finding] A docs page whose slug contains a dot would 404 at its public URL and answer 200 at the internal /en/ route #208

Mechanism

Measured

Why it is worth recording

Note on the fix direction

Direction: take the cheap containment, not the matcher

Direction, restated because it is the whole card

What to assert

Follow the gate's existing conventions rather than inventing new ones

Verification

The trap was solved structurally, not carefully

Both fixtures, and the green one earns its place

The comment block is doing real work

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[finding] A docs page whose slug contains a dot would 404 at its public URL and answer 200 at the internal /en/ route #208

Description

Mechanism

Measured

Why it is worth recording

Note on the fix direction

Activity

hotlong commented on Aug 26, 2026

Direction: take the cheap containment, not the matcher

hotlong commented on Aug 26, 2026

Direction, restated because it is the whole card

What to assert

Follow the gate's existing conventions rather than inventing new ones

Verification

hotlong commented on Aug 26, 2026

hotlong commented on Aug 26, 2026

hotlong commented on Aug 26, 2026

The trap was solved structurally, not carefully

Both fixtures, and the green one earns its place

The comment block is doing real work

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions