Repository navigation
[finding] the generated upgrade guide wraps each semantic entry's surface in a single-backtick code span, so a surface that carries its own backticks (most of the ~516 entries) renders broken #27532
Description
Filing gate: ② a should-fix that a contract review marked as a follow-up sweep. Found by the contract review of PR #27527 (#27445, record 6495021350). Filed by domain:spec seat 1 · os-support-ai · session session_01WGufzfhobWEgUUrjz4rrbh. ⛔ Not a claim. No grade yet: triage sets the lane and grade.
Measured (origin/main)
packages/spec/scripts/build-upgrade-guide.ts:135renders each semantic entry as- **`${s.id}`** — `${s.surface}` → …. The surface sits inside a single-backtick code span. The conversion table row at:126does the same forc.surface.- Almost every
semantic/*.tsentry writes itssurfacewith backticks of its own (globalFilters, field names, key paths). In the rendered guide, those inner backticks close the span early, and the line reads as alternating code and prose fragments. - Only
18.visibility-predicate-has-argument-refused.tsavoids this, with a comment, by keeping backticks out of itssurface.
Wanted
- Fix it once, in the renderer, not in each entry. Render
surfaceas prose (no wrapping span), or wrap it in a code span whose fence is longer than any backtick run inside it. Then regenerate the upgrade guide. - Add a pin that the rendered guide has no broken surface spans, so a new entry cannot reintroduce the defect.
- The
18.visibility-predicate-…comment can then drop its workaround note.
Clause-②: likely no (generated docs and a build script). Metadata-protocol: likely none.
Dedupe
The open-issue titles were searched for "upgrade guide", "code span" and "backtick". New.
Generated by Claude Code
Activity
objectstack-fleet commentedon Oct 29, 2026
triage#1 · os-zhuang · session_01AavokzJ5DndAwitDXvKy4U
Path: 写给 AI 的文档与 skills 说错一句，等于产品缺陷 | none | P①
Triage: p3 ·
domain:spec·area:devpath· 2026-10-29T12:11Z⛔ Not a claim.
build-upgrade-guide.ts:126and:135wrap each entry'ssurfacein a single-backtick code span, but almost every semantic entry already writes backticks insidesurface. So the generated upgrade guide renders those lines as broken code and prose fragments. It is presentation in a generated guide, with no wrong fact, so p3.surfaceas prose, or escape inner backticks) and regenerate. The 516 entries are not hand-edited.documentation,pm:queue.pm:triageremoved.Generated by Claude Code
objectstack-fleet commentedon Oct 29, 2026
Release:
domain:specseat 1 (#6017) · sessionsession_01WGufzfhobWEgUUrjz4rrbh· 2026-10-29T15:25ZThis seat added
pm:dispatchedhere at 2026-10-29T12:44Z, but no dev was started: the order never reached the coordinator. NoClaim:comment, no branch and no PR exist. The maintainer has taken seat 1 off duty, so this seat starts no new work and releases the card:pm:dispatched→pm:queue, assignee cleared. Any spec seat may claim it under the full claim protocol.objectstack-fleet commentedon Oct 29, 2026
domain:spec#4 · marchtian · session_017ihL2fi9zfJhUTubyJYb6V
Claim: PM loop round 1 · 2026-10-29T15:37Z
Session:
session_017ihL2fi9zfJhUTubyJYb6VAccount:
marchtianBranch:
claude/project-thread-2ul8sb(card thread; the platform assigns the thread's branch and it can push only that one, written as measured instead ofclaude/issue-27532-<slug>)Worktree:
objectstack-issue-27532Domain:
domain:specSeat:
domain:spec#4Ruling-ref: triage 6496306402
File surface:
packages/spec/scripts/build-upgrade-guide.ts(the twosurfacerender sites),packages/spec/scripts/lib/upgrade-guide-docs.tsif the docs renderer shares the defect, the committed generated guide outputs, the workaround comment inpackages/spec/src/migrations/entries/semantic/18.visibility-predicate-has-argument-refused.ts, a pin test beside, a changeset if a published artifact moves (stop on breach; explain in the report)Container & model:
S,mode:thread(a card thread already open, re-pointed here after this seat yielded a p1 card to seat 3),model: fable — --tier: no path-derived mandate; reason: project standing rule, spec drafting runs on Fable,effort: xhigh(the thread's setting)Clause-②: no
Metadata-protocol: none
Responsibility: n/a — not a defect card
Thread-read: 6496306402
Premise: holds —
build-upgrade-guide.tsL126 and L135 wrapsurfacein a single-backtick span on178b5238Serial constraints cleared: none (no open PR touches these files; 47 open PRs' file lists read 15:31Z)
objectstack-fleet commentedon Oct 29, 2026
domain:spec#4 · marchtian · session_017ihL2fi9zfJhUTubyJYb6V
Claim amendment · 2026-10-29T19:41Z · ⛔ same claim, same seat, same branch
Container & model:
model: TIER_DEFAULT(opus) — the quota-exhaustion exemption:claude-fable-5-1answered HTTP 429 "You've reached your Fable limit" (measured on this seat's dev subagent, ~17:05Z). Maintainer, in the project thread: 「你没有fable了，使用 opus开发完之后等契约复审」. The card thread is stood down; an opus subagent in the seat thread takes over the same branchclaude/project-thread-2ul8sbfrom851518444f(mode:subagentfrom here on). The PR waits for theCONTRACT_REVIEW_TIERcontract review before any landing stroke; this seat cannot serve that tier now, so it hands the review over on the PR once the dev reports.objectstack-fleet commentedon Oct 29, 2026
domain:spec#4 · marchtian · session_017ihL2fi9zfJhUTubyJYb6V
os-dev-report
Reported 2026-10-29T20:50Z, on the maintainer's opus order of 2026-10-29T19:39Z.
{ "issue": 27532, "status": "done", "branch": "claude/project-thread-2ul8sb", "pr": "https://github.com/objectstack-ai/objectstack/pull/27724", "head": "34de285ecf266bc596a06dd76a5478ce4d32deb6", "session": "session_017ihL2fi9zfJhUTubyJYb6V", "premise_still_valid": true, "summary": "Took over the card thread's pushed branch at 851518444f and read its full diff against the order and triage 6496306402. The generator is fixed once: both render sites of an entry's surface go through one codeSpan door, which fences by CommonMark's rule (one backtick longer than the longest run inside, padded at a backtick or space edge), and the conversion row escapes the pipe in every cell. No entry was hand-edited, and the workaround note in 18.visibility-predicate-has-argument-refused is dropped. The diff needed no correction; the work here was one origin/main merge (a75ddba178, clean, no generated-file conflict), the three-leg ablation, the gates and the draft PR.", "tests": "At 34de285ecf: pnpm --filter @objectstack/spec test gave Test Files 754 passed (754), Tests 22406 passed and 1 todo, exit 0. pnpm --filter @objectstack/spec typecheck: exit 0, and tsconfig.scripts.json --listFiles compiles all three touched script files. The pin, the docs-page tests and the two edited sibling tests: Test Files 4 passed, Tests 47 passed. Ablation went through scripts/ablation-replace.mjs; each leg verified the anchor 1 to 0, the blob change, and the restore as blob == HEAD with an empty git diff HEAD. There is no dist leg, because the test imports ../src and spawns the script source by relative path. Leg 1, the semantic site reverted to a single-backtick span: 1 failed / 14 passed. Leg 2, the conversion site reverted to main's row: 1 failed / 14 passed (navigation-mode-overlay-values-removed gave 6 cells, not 4). Leg 3, the helper fence forced to one backtick: 5 failed / 10 passed. Independent renderers on the fixed guide: remark-gfm read 516/516 semantic spans and 104/104 rendered conversion rows verbatim; markdown-it read 516/516. Main's single-backtick wrapping broke 183 of 516 semantic lines under markdown-it.", "gates": "node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at 34de285ecf derived 86 commands, each run with its exit code captured before any pipe. 85 exited 0. check:doc-formula-expressions and check:lean-entry-closure first exited 3 (PREREQUISITE NOT MET, no dist) and exited 0 after their closures were built. check:dual-build-cjs-loads stayed at exit 3 and is NOT MEASURED: about 93 packages have no dist in this worktree, the diff moves no package's built output, and CI runs it after its build. The --ran reconciliation of the 'command :: exit N' file gave 86 derived, 85 run, 1 NOT-MEASURED (derived from the recorded exit 3), 0 UNRUN, exit 0. PR check-runs are in_progress at report time; CI convergence is the seat's.", "dogfood_battery": "n/a — no ! in the PR title and no (narrowing) arm", "line_budget": "7 files, +356 / -8 (364 changed lines), under the 3000 human-merge threshold; no skills/** touched", "files_changed": [ ".changeset/27532-upgrade-guide-surface-span.md", "packages/spec/scripts/build-upgrade-guide.ts", "packages/spec/scripts/lib/markdown-code-span.ts", "packages/spec/scripts/upgrade-guide-surface-span.test.ts", "packages/spec/src/api/export-job-family-retirement.test.ts", "packages/spec/src/kernel/package-upgrade-family-retirement.test.ts", "packages/spec/src/migrations/entries/semantic/18.visibility-predicate-has-argument-refused.ts" ], "changeset": "patch on @objectstack/spec: protocol-upgrade-guide.md is in the package's files[] and generated at publish, so the shipped bytes move. No committed rendered output exists to regenerate: packages/spec/protocol-upgrade-guide.md and content/docs/protocol-upgrade/ are gitignored.", "mcp_calls": "0 — no MCP GitHub tool called", "api_writes": "2 — both through the fleet-write relay (POST /repos/objectstack-ai/objectstack/dispatches): pr_create (POST /repos/objectstack-ai/objectstack/pulls, draft forced, no labels, no assignees, read back 7917 bytes sent and 7917 stored) and this os-dev-report comment (POST /repos/objectstack-ai/objectstack/issues/27532/comments via post-stamped.mjs). git push x1 (the merge commit), not a REST write.", "deviations": [ "The spec-rule Fable review in _common.md was not run, on the maintainer's order of 2026-10-29: the account's Fable quota is exhausted, and the PR body says the PR waits for the contract review. No substitute review was run.", "The PR body ends with the dispatcher-specified line '🤖 Generated with [Claude Code](https://claude.com/claude-code)' under a rule, not with AGENTS.md's session-URL footer form.", "The pre-existing branch commits 8e4d77a017 and d5876c748b were written by the earlier card thread; this run added only the merge commit 34de285ecf with the model-free trailer pair." ], "open_questions": [], "out_of_scope_findings": [ "carrier: none · noted in the PR's Acceptance notes, not filed: the card says 'most of ~516' semantic surfaces carry backticks; the measured count is 183 of 516." ] }objectstack-fleet commentedon Oct 29, 2026
domain:spec#4 · marchtian · session_017ihL2fi9zfJhUTubyJYb6V
ACCEPT → PR #27724 comment 6508068835 (lane part) + Contract review PASS 6508719840 (
CONTRACT_REVIEW_TIER, triage, head34de285e) · 2026-10-29T21:30Z · readied and auto-merge armed by the seat (every check green;check-expected-skipsOK, 16 skips in the roster);needs:contract-reviewremoved. The review's should-fix sweep (219 stale entry comments + one test assertion) is filed as #27731. Its prose should-fix (the model name in the PR body's review line) is not applied: the relay refuses a PR-body write whose line 1 is the attribution marker.objectstack-fleet commentedon Oct 29, 2026
domain:spec#4 · marchtian · session_017ihL2fi9zfJhUTubyJYb6V
Landed · 2026-10-29T21:54Z · PR #27724 merged by the queue at 2026-10-29T21:53Z as
3702be4070; the card closed byFixes. This seat stripspm:dispatchedin the same act. Follow-up sweep: #27731.