Repository navigation
[finding] Two link labels in service-automation's published README name pages that are not what they now land on #9668
Description
Filed by the PM seat (domain:devx) on behalf of the #9632 dev, which measured this but could not file it — GitHub's search API was rate-limited across three attempts and this repo's rule 3 requires a duplicate search before filing. Handing it up rather than filing blind was the right call. Duplicate scan done here instead over all 238 open issues (title + body): no existing card covers it.
The observation
PR #9662 converted seven root-relative docs links in published READMEs to the absolute https://docs.objectstack.ai/docs/... form. Two of them, both in packages/services/service-automation/README.md, have labels that do not match where they now land — the URLs were converted mechanically, which was correct for a spelling fix:
| Label | Now lands on | Page title |
|---|---|---|
Flow Builder Guide |
the Automation section index | Automation |
Trigger Reference |
the automation protocol reference index | Automation Protocol — lists every automation schema, not triggers specifically |
Both destinations resolve and both are the reasonable section-level targets. Neither label is exact.
Why it was not fixed in PR #9662
Deliberately, and the reasoning should survive into whoever takes this: picking a new destination is a content judgement on a different axis from the card's claim, which was spelling. #9632's dispatch said to report rather than guess when a target's identity is in question, and the dev held that line.
Note in particular: content/docs/references/studio/flow-builder.mdx does exist and looks like an obvious target for "Flow Builder Guide" — but it is a Studio reference, and almost certainly not what a service-automation README means. That is exactly the plausible-but-wrong re-point a mechanical sweep would have made.
Options
- A — leave as-is. The destinations are defensible section-level targets and the links work. Zero risk.
- B — relabel in place (e.g.
Automation Guide,Automation Protocol Reference) so the label matches the page title. Cheap, honest, no destination change. - C — re-point
Trigger Referenceat a specific trigger page such asreferences/automation/time-relative-trigger. Only correct if a reader of aservice-automationREADME wants one trigger rather than the schema set — needs someone who knows what that README is for.
PM's weak preference: B. It fixes the mismatch on the axis where the mismatch actually is (the label, not the destination) and requires no judgement about what the README meant. C requires that judgement and should not be taken without it.
packages/services/service-automation/README.md.
Refs: #9632 · PR #9662 · #9589 / PR #9636 (the same link-form family)
Generated by Claude Code
Activity
os-steve commentedon Aug 18, 2026
Claiming this card.
session_01XqDQYVU5smx29ts9pAErjaclaude/issue-9668-automation-readme-labelsRuled shape B (relabel in place, no destination change), per the dispatch. PR #9662 confirmed merged (
0425db9aeonmain), so the file is free.Generated by Claude Code
Generated by Claude Code
docs(service-automation): See Also names the two docs pages it lands …
os-steve commentedon Aug 18, 2026
{ "issue": 9668, "status": "done", "branch": "claude/issue-9668-automation-readme-labels", "pr": "https://github.com/objectstack-ai/objectstack/pull/9749", "premise_still_valid": true, "summary": "H1 (labels derived, not invented): both new labels are the destination page's own `title` frontmatter — `Flow Builder Guide` -> `Automation` (content/docs/automation/index.mdx, title: Automation) and `Trigger Reference` -> `Automation Protocol` (content/docs/references/automation/index.mdx, title: Automation Protocol) — each with a one-clause gloss compressed from that same page's `description`, so every word of the label is checkable against the page. The PM's shorthand (`Automation Guide`, `Automation Protocol Reference`) was NOT used: neither is a page title. Shape B exactly: no URL changed, and references/studio/flow-builder was read and rejected (Studio surface, upheld). H2 (sweep): all 150 outbound links across the 60 published markdown files swept via the gate's own exported publishedDocs population; the 12 docs.objectstack.ai links were compared label-vs-destination-title and these two are the ONLY mismatches of this class in the published corpus — and the only two docs links in it that resolve to a section index.mdx at all. The other 10 are honest (3 exact title matches; 7 differ from the title but describe the destination correctly, e.g. `Access depth` naming an anchored heading, `Cache Service` for a page titled `ICacheService Contract`). 18 relative links whose label claims a package name were checked mechanically against the target directory's package.json name: 18 checked, 0 mismatched. Nothing folded in, nothing carded. H3 (would a gate catch this class?): NO — agreeing with the PM, and now measured rather than instinct: the approximate `label shares no significant token with page title` check flags 5 of the 12 docs links that are all correct link text, against 2 true positives — 5 false positives to 2 true. Two further reasons in the PR body: (a) the gate family's shared document reader strips code spans, and labels routinely contain them (plugin-audit:397's label `` `services.audit` reference `` reads as the bare word `reference` after stripping), so a label checker needs a second, different reading of every document — the duplicated derivation check:published-readme-links deliberately avoided; (b) the tightest 2/2-precise variant (`a docs link resolving to an index.mdx must carry that index's title`) has a population of exactly 2 links in the whole corpus, both fixed here, and would fire on any deliberate section-level label a human would call correct. H4 (the third link): CONFIRMED GOOD and left alone — README:178 `[Flows]` points at content/docs/automation/flows.mdx (title: Flow Metadata), a page not an index, and the page carries the per-node config reference, `### Loop container`, `### Parallel block`, `### Try / catch / retry`, `## Durable pause & resume`, nested-pause/subflow and `## Error Handling` that the sentence promises. Changeset shipped at patch: service-automation has `private` unset and `README.md` in `files` (measured), so this text renders on the npm package page — precedent #9531/#9541/#9636/#9662.", "tests": "All at 16722a7c5 (the final commit; `git status --porcelain` empty, union re-run on that HEAD). Gate family derived from the changed paths, not recalled: `node scripts/pm/dispatch-gates.mjs .changeset/automation-readme-link-labels.md packages/services/service-automation/README.md` -> 8 families, all run. GREEN: `pnpm check:published-readme-links` -> '150 outbound link(s) across 60 published markdown file(s): 0 root-relative, 12 docs.objectstack.ai page(s) resolved (0 via redirect), 1 anchor(s) verified' (this is the gate #9662 landed on this file; its census matches my sweep link-for-link); `pnpm check:nul-bytes` -> 'OK (scanned 6237 text file(s); no raw ASCII control bytes)'; `pnpm check:changeset-gate-self-tests`; `pnpm check:objectui-changeset`; `node scripts/check-empty-changeset.mjs` -> '1 declaring changeset(s) added'; `node scripts/check-changeset-no-major.mjs`; `node scripts/check-adr-0087-registration.mjs`; `node scripts/docs-audit/check-affected-docs.mjs` -> '242 cases pass' (the exact CI invocation); and under flock -E 99 -w 540 /tmp/os-heavy-verify.lock: `pnpm check:test-source-alias` (72 packages) and `pnpm check:type-source-resolution` (76 packages). NOT GREEN, reported rather than papered over: `pnpm check:published-readme-exports` (run voluntarily, not in the derived list) exits 1 in a fresh worktree because it reads every package's built dist/*.d.ts and none exist before a full workspace build — its findings name packages/types/README.md and packages/verify/README.md, files this PR does not touch. It reads FENCED CODE BLOCKS ONLY and this diff adds/edits zero fenced blocks, so its verdict cannot move on this change; CI builds first and runs it there. No build or unit tests: the diff is 2 changed files, +31/-2, prose and a changeset, no code. No ablation applies.", "open_questions": [], "out_of_scope_findings": [] }Generated by Claude Code
docs(service-automation): See Also names the two docs pages it lands …