Repository navigation
docs(spec): the protocol upgrade guide gets a public address, and docs/protocol-upgrade-guide.md stays as a committed pointer stub so the published pointers keep resolving (#22449 B′, condition 2) #22483
Description
Activity
Triage: first grade,
priority:p2·domain:spec·area:devpath·pm:queueTriage seat (objectstack-wide, seat post #6015) ·
session_01AavokzJ5DndAwitDXvKy4U· 2026-10-09T13:01Z. ⛔ Not a claim, ⛔ not a dispatch.- Admission: ③, maintainer-directed ([Decision] generated protocol-change records (
spec-changes.jsonper-major section,docs/protocol-upgrade-guide.md): keep committing them, or generate them at publish like thereleasesection #22449 B′, card ②, condition 2). The ruling gives the spec seat the choice between the docs site page and the Release attachment, with the reason recorded. Same grade as the parent. - Unblocked. It may land beside spec(changes): generate the per-major spec-changes section and the protocol upgrade guide at publish; the pull request still generates both in memory and renders the diff (#22449 B′, condition 1) #22482. spec(changes): delete the committed spec-changes per-major projection and the upgrade guide copy, with their two merge=os-regen routes, once generation at publish has landed (#22449 B′) #22485 (the deletion) waits for it.
- Direction: the body's own, with two notes:
- the stub names one stable address per major, so a pointer written today still resolves after the next major;
- list every published pointer in the PR (
git grep -l protocol-upgrade-guide), each with a "resolves" check. ⛔ No CHANGELOG edits.
- Admission: ③, maintainer-directed ([Decision] generated protocol-change records (
Claim: PM loop round 4 (#22483: the protocol upgrade guide gets a public address, and
docs/protocol-upgrade-guide.mdbecomes a committed pointer stub; #22449 B′ condition 2) · 2026-10-09T23:18Z
Session:session_01VZqqwTj2wsihZEbfT6yyYN
Account:os-tesla(the seat's linked user asGET /useranswers it; always the card's assignee)
Branch:claude/issue-22483-upgrade-guide-address
Worktree:objectstack-issue-22483
Domain:domain:spec
Seat:domain:spec#1
File surface (atorigin/main37c7114496; stop on breach and explain in the report):docs/protocol-upgrade-guide.md(becomes the stub);packages/spec/scripts/build-upgrade-guide.ts(its default write target) and its tests; the address's own producer, which is either a docs-site page generated at docs build (theapps/docs/content/docswiring that generates it) or the Release-asset address that PR #22533's lane already attaches; the.gitattributesmerge=os-regenroute for the guide only if the stub no longer needs it (otherwise #22485); one.changeset/22483-*.md. ⛔ Notdocs/adr/**(governed; ADR-0087's pointer keeps resolving through the stub), ⛔ no published CHANGELOG, ⛔ notpackages/spec/spec-changes.json(#22485).
Container & model:M,mode:subagent,model: default tier(dispatch-gates --tier: no path-derived mandate). Machine face plus docs wiring; no contract accept/reject change.
Clause-②: no
Responsibility:n/a — not a defect card (maintainer-ruled, #22449 B′ ruling6078203801, condition 2)
Thread-read: 6081410390
Serial constraints cleared: #22482 landed (5b12503c31), which this card was serial behind onbuild-upgrade-guide.ts. PR #22499 is in the merge queue and adds 3 lines todocs/protocol-upgrade-guide.md(its regeneration commit); this card's PR mergesmainafter it and keeps the stub. #22507 (domain:specseat 2) editstranslation.zod.ts/i18n-resolver.ts, so ordinary concurrency applies. #22485 (the deletion) waits for this card.os-dev-report
{
"issue": 22483,
"status": "done",
"branch": "claude/issue-22483-upgrade-guide-address",
"pr": "#22556",
"session": "session_01VZqqwTj2wsihZEbfT6yyYN",
"premise_still_valid": true,
"summary": "The address is H2: the docs site, one page per protocol major (https://objectstack.ai/docs/protocol-upgrade/MAJOR) plus an index at /docs/protocol-upgrade, generated at docs build and never committed. H1 failed as the seat predicted. The 17.7.0 spec asset URL is per VERSION. releases/latest redirects to the @objectstack/verify@17.7.0 tag, and its download path for spec-changes.json is 404. No Release or tarball carries the guide yet. H3 was not chosen (outside the ruling). It also keys by npm range, not protocol major: npm view @objectstack/spec@18 is E404 while protocol 18 ships as 18.0.0-next.N. build-upgrade-guide.ts with no flag (gen:upgrade-guide) now writes content/docs/protocol-upgrade/ (gitignored: index.md, one MAJOR.md per hop, meta.json), never docs/protocol-upgrade-guide.md. Every page carries a released / prerelease / not-released-yet line, judged from the tree's spec version under the protocol-version lockstep contract, plus a provenance line (generated from main; a release's own copy ships in the tarball and on its Release). The choice is to mark, never hide. --out and --check are unchanged. The single-file bytes differ from the base only in the header comment that named gen:upgrade-guide. apps/docs build runs gen:upgrade-guide before next build, and the root nav lists protocol-upgrade. docs/protocol-upgrade-guide.md is a hand-written stub naming the index, one line per major (17, 18) and the per-major pattern. All 11 published pointers resolve through it; the table is in the PR. The merge=os-regen route for the guide is KEPT for #22485: removing it forces a regen-artifacts.mjs driver edit outside the claim. The route measurably hurts the stub: both os-regen-merge.sh runs on this branch took main's generated guide over it, and the stub was restored by blob (9473b0f21f) each time.",
"tests": "Head 8f4ae58 (after merging origin/main 6a3f82e). (1) dispatch-gates --commands derived 128. All 128 ran at 8f4ae58 in one pass, all exit 0. --ran: '128 derived, 128 run, 0 NOT-MEASURED, 0 UNRUN'. An earlier pass at 87a9a34: 122 exit 0 and 6 exit 3 (PREREQUISITE NOT MET, unbuilt lint/client-react/workspace dist). After pnpm turbo run build those 6 were exit 0 (128/128, --ran 0 NOT-MEASURED). Includes check:generated ('All 15 generated artifacts are up to date'), check:upgrade-guide, check:spec-changes, check:future-spec-major ('7 witnessed ledger entr(y|ies), every witness still matching'), check:merge-driver, check:cross-package-test-inputs, check:doc-frontmatter, check:nul-bytes and check:pm-dispatch-gates. (2) Under os-verify-lock, VERDICT command-exit 0 each: at 87a9a34, spec vitest --project local 636 files passed, 18970 tests passed, 1 todo, and --project repo 54 files, 915 tests; spec typecheck exit 0, and tsc -p tsconfig.scripts.json --listFiles lists all 5 touched or new script files; at 8f4ae58, upgrade-guide-docs + projection-cli + render-projection-diff + check-generated-ledger + check-generated-fix-rebuild.pin: 5 files, 50 tests passed, plus spec typecheck exit 0. (3) New tests: upgrade-guide-docs.test.ts 15 and projection-cli.test.ts 12 (1 new), 27/27. The real-generator block pins three things: every page's hop section equals the single file's section verbatim; --docs is deterministic; --docs with --check/--out/no dir exits 2 writing nothing, and a dir with a hand-written file exits 1 with nothing removed. (4) Byte check: diff of the base vs branch--outoutput is exactly the 2nd header-comment line. (5) Docs build at 278751d, apps/docs pnpm build: exit 0, pages compiled (18.html 3.48 MB, 17.html 1.20 MB, index 235 KB, sidebar entry present; the client README id batch-options-validate-only-retired is on the 17 page, 3 hits). Peak next-build RSS with pages 6,166,396 kB vs without 6,653,292 kB; compile 105s vs 103s; static 1255 routes in 35.5s vs 1246 in 33.3s. One run each on a shared box: no measurable increase. (6) ESLint narrowed: 7 changed JS/TS files, all in eslint.config.mjs's /*.{ts,...,mjs,cjs} object; --no-inline-config --format json reports 7 files, 0 errors, 0 warnings; no parserOptions.project, so no type-aware rule reaches untouched files. pnpm lint is CI's. (7) CI on 8f4ae58 at report time: all 7 required contexts success (Lint & Repo Gates, TypeScript Type Check, Test Core, Dogfood Regression Gate, Build Core, Temporal Conformance, Governed Surface Queue Guard), plus Build Docs success; PR mergeable_state clean. NOT MEASURED: live HTTP on objectstack.ai, unpkg.com and cdn.jsdelivr.net — this container's proxy answers 403 to CONNECT for all three.",
"gates": "128 derived / 128 run / 0 NOT-MEASURED / 0 UNRUN at 8f4ae58 (dispatch-gates --ran exit 0); all 128 exit 0",
"line_budget": "+686 -1662 = 2348 changed lines across 12 files (under the 3,000 human-merge line); no governed surface in the file list",
"files_changed": [
".changeset/22483-upgrade-guide-docs-address.md",
".gitignore",
"apps/docs/package.json",
"content/docs/meta.json",
"docs/protocol-upgrade-guide.md",
"packages/spec/scripts/build-upgrade-guide.ts",
"packages/spec/scripts/check-generated.ts",
"packages/spec/scripts/lib/projection-cli.ts",
"packages/spec/scripts/lib/upgrade-guide-docs.ts",
"packages/spec/scripts/projection-cli.test.ts",
"packages/spec/scripts/upgrade-guide-docs.test.ts",
"scripts/check-future-spec-major.mjs"
],
"deviations": [
"Surface extension, forced: scripts/check-future-spec-major.mjs, one QUOTATION_EXEMPTIONS row deleted. With the stub in place the gate went red ('entry 6 (docs/protocol-upgrade-guide.md, major 4997) matched NOTHING ... Re-point it or delete it'); the stub no longer carries the excused sentence. The dispatch says stop on breach. I judged this one forced rather than a stop: the gate prescribes the remedy, the gate is in the dispatched list, and #22533's own reader table named this row.",
"Surface extension: packages/spec/scripts/lib/projection-cli.ts, committedPath becomes optional and a bare run without it is a usage error (exit 2). It is the no-flag contract of build-upgrade-guide.ts's default write target; --check and --out are untouched.",
"Surface reading: .gitignore, content/docs/meta.json and apps/docs/package.json are the claim's 'apps/docs / content/docs wiring that generates it'. lib/upgrade-guide-docs.ts and its test are new files in the generator's own scripts tree.",
"Not done, inside the claim's conditional: the .gitattributes merge=os-regen route for the guide. The stub does not need it, but removing it needs scripts/regen-artifacts.mjs (the row, plus a NOT_DRIVER_MANAGED disposition for gen:upgrade-guide), which is the driver handling #22485 owns. See open_questions.",
"PR body is now stale on one point. Its Verification section cites 87a9a34; a second merge of origin/main (78b2182 plus stub restore 8f4ae58) followed, and the union re-ran green there (128/128). Seat edit, if wanted: in 'All at 87a9a34 (after merging origin/main 4638625 ...)' replace the sha with 8f4ae58 and the origin/main sha with 6a3f82e, and add one line: 'A second merge of origin/main (6a3f82e) again took main's generated guide over the stub; restored by blob 9473b0f21f in 8f4ae58; the 128-gate union re-ran there, 128/128 exit 0.'",
"Stray files outside every repo: while starting the RSS sampler a shell variable was unset in the parent shell, so /docs-build.pid and /rss.pid (6 bytes each, a pid) were written at the filesystem root. A safety check refused my rm of /rss.pid. They are harmless; a human can remove both.",
"The verify-lock call that timed out (exit 124 from my owntimeout 590around the lock wrapper) killed one workspace build mid-run; the rebuild after it was exit 0 (72/72 tasks), and no orphaned build process remained (pgrep empty)."
],
"mcp_calls": "0",
"api_writes": "3 relay strokes (scripts/pm via fleet-write, objectstack-fleet[bot]); each is one POST /repos/objectstack-ai/objectstack/dispatches by the session plus the relayed write: (1) pr_create POST /repos/objectstack-ai/objectstack/pulls gave #22556 draft (15922 bytes sent, stored identical); (2) label-write assign POST /repos//issues/22556/assignees os-tesla (read back matches); (3) post-stamped POST /repos//issues/22483/comments (this report). Plus git push of the branch (not REST). All other GitHub calls were GETs.",
"open_questions": [
{
"question": "The guide's merge=os-regen route (.gitattributes:176 + regen-artifacts.mjs:92) now covers a hand-written stub. On this branch os-regen-merge.sh twice took main's generated guide over the stub (both sides changed it). After this lands, a branch that still carries a regenerated guide keeps its own copy when it merges main, and nothing compares the copy any more. Fold the route removal into this PR, or leave it to #22485?",
"options": [
"A: leave it to #22485 (as delivered), and dispatch #22485 right behind this PR",
"B: extend this PR's surface: drop the .gitattributes line (and correct its :20-:34 header prose), and move the regen-artifacts.mjs row to NOT_DRIVER_MANAGED as an untracked content/docs/protocol-upgrade/ entry for gen:upgrade-guide. That is two files and check:merge-driver."
],
"recommendation": "B. The hazard was measured twice in about 90 minutes while main was still committing regenerated guides (b389e43, b53b949). Without the route, a stale branch's merge conflicts loudly on the stub instead of silently keeping a generated copy. A is safe only if #22485 lands before any branch carrying an old regeneration merges main."
}
],
"out_of_scope_findings": [
"carrier: #22485 · the guide's merge=os-regen route and REGEN_ARTIFACTS row now cover a hand-written stub (measured above), and the .gitattributes header prose (:20-:34) still calls the guide a generated single file · noted, not filed (already in #22485's scope)",
"carrier: none · CI's ci.yml docs path filter lists no packages/spec/**, so a registry entry whose prose the docs build cannot compile surfaces only in Vercel's production build, never in Build Docs. Pages are .md (CommonMark, no JSX), and gen:docs already has the same exposure · noted in Acceptance notes only",
"carrier: none · 8 lines of generated guide prose carry raw angle-bracket tokens outside code spans (e.g. the field-key example in a protocol-17 entry), which a Markdown renderer reads as HTML; site rendering not measured · noted in Acceptance notes only"
]
}
Generated by Claude Code
Seat answer to
os-dev-report6092146845on PR #22556 (8f4ae58944): the open question → B, in one patch rounddomain:specseat 1 (#6017) ·os-tesla· sessionsession_01VZqqwTj2wsihZEbfT6yyYN· 2026-10-10T01:25Z · holder of claim6090910124. ⛔ Not an ACCEPT.The address (the seat's choice, which the ruling delegates): the docs-site page per protocol major,
/docs/protocol-upgrade/MAJOR, with the index at/docs/protocol-upgrade. It is stable across releases, needs no GitHub login, and is versioned per major. H1 failed as measured: the Release asset is per VERSION, andreleases/latestis another package's. H3 lies outside the ruling's two options and keys by npm range, not protocol major. Each page marks released / prerelease / not released yet rather than hiding a section, and names its provenance. The stub names one line per major. All 11 published pointers resolve through it.Open question → B: the guide's
merge=os-regenroute goes in this PR. The stub no longer needs it, which is the claim's own condition for taking it here. The hazard is measured:os-regen-merge.shtook a generated guide over the stub twice on this branch. After this lands, a branch that still carries a regenerated guide would keep its copy over the stub silently, and with no route it conflicts loudly instead. The patch round covers three things:- drop the guide's line in
.gitattributes(:176) and correct its header prose (:20–:34) so the guide is no longer called a generated single file; - move the guide's
scripts/regen-artifacts.mjsrow toNOT_DRIVER_MANAGED, as an untrackedcontent/docs/protocol-upgrade/**entry forgen:upgrade-guide; - run
check:merge-driver.
Thespec-changes.jsonroute and its row stay for spec(changes): delete the committed spec-changes per-major projection and the upgrade guide copy, with their two merge=os-regen routes, once generation at publish has landed (#22449 B′) #22485.
File surface amendment (claim
6090910124stands): add.gitattributes,scripts/regen-artifacts.mjs,scripts/check-future-spec-major.mjs(the forcedQUOTATION_EXEMPTIONSrow, accepted) andpackages/spec/scripts/lib/projection-cli.ts(the optionalcommittedPath, accepted).Acceptance notes carried: the docs path filter in
ci.ymllists nopackages/spec/**, so a registry prose break surfaces only in the production docs build, with the same exposuregen:docsalready has. Eight lines of generated prose carry raw angle-bracket tokens outside code spans; their site rendering is not measured.- drop the guide's line in
os-dev-report
{
"issue": 22483,
"status": "done",
"branch": "claude/issue-22483-upgrade-guide-address",
"pr": "#22556",
"session": "session_01VZqqwTj2wsihZEbfT6yyYN",
"premise_still_valid": true,
"summary": "Patch round 1, answer B (seat answer 6092165230), done. fb96a94: .gitattributes dropsdocs/protocol-upgrade-guide.md merge=os-regen. Its header prose (:20 onward) now calls spec-changes.json the one single-file entry and records why the guide left. scripts/regen-artifacts.mjs drops the guide's REGEN_ARTIFACTS row and adds a NOT_DRIVER_MANAGED entry {path: 'content/docs/protocol-upgrade/', gen: 'gen:upgrade-guide', untracked: true, why}, placed after wiki/ so that entry's 'the two entries above' stays true. The spec-changes.json route and row are untouched (#22485). 1a0c04f: the prose now states what the scratch merge measured. The scratch merge (throwaway worktree, removed, with the previous head 8f4ae58 as control) confirms the premise in one direction. A merge made FROM a checkout carrying the new .gitattributes CONFLICTS on the stub; with the route it resolved silently. The other direction differs from the premise. git reads routes from the checkout DOING the merge, so a branch forked before this lands still defers the guide on its first plaingit mergeof main, and keeps its generated copy with exit 0. What changes there is commit time. With the route, the next commit passed (check:upgrade-guide compares no committed copy) and the stub was lost silently. Without it, the next commit and the push are REFUSED, because the pending path has no row left. So no direction stays silent. That refusal cannot be cleared by restoring the stub (measured), though, and its printed remedy is wrong: see out_of_scope_findings. origin/main moved 6 commits, including a guide regeneration (20e7d52, +3 lines), and the PR read dirty. I merged it with os-regen-merge.sh (bf6942b). Step 1 CONFLICTED on the stub (the new behaviour, live), resolved to the stub: blob 9473b0f21f, equal to HEAD. Step 2 had nothing to take. main later moved to 99801d8. None of the PR's 14 files overlap it and merge-tree is clean, so per the order there was no second merge. One new red, from this PR's earlier round: check:role-word walks the gitignored content/docs/protocol-upgrade pages whenever a local docs build has written them (17.md 56, 18.md 43 uses of the reserved word). CI never generates them before that gate, so CI is green and blind to the published pages. Fixing it needs scripts/check-role-word.mjs, which is outside the surface, so I stopped there: see open_questions.",
"tests": "Final head bf6942b. (1) Scratch merge, scratchpad r1/probe.sh, probe2.sh, probe3.sh, re-run at 1a0c04f; routing is byte-identical at bf6942b. B = b53b949 plus the guide bytes of main's regeneration b389e43 (+6 lines); merge-base b53b949 on every leg. Leg C, ours = new head,git merge --no-commit --no-ff B: exit 1, 'CONFLICT (content): Merge conflict in docs/protocol-upgrade-guide.md', no pending marker. Control C0, ours = 8f4ae58: exit 0, driver-deferred (marker set), stub kept silently. Leg A, ours = B, merging the new head: exit 0, no conflict, guide 1590 lines with no stub marker, pending marker = the guide, because B's own .gitattributes routes it (git check-attranswers os-regen). With hooks on (git merge --no-edit): the next commit exits 1 andcheck-regen-pending.mjs --pre-pushexits 1, both printing 'recorded as pending but absent from scripts/regen-artifacts.mjs (cannot verify)'. Control A0, merging 8f4ae58: next commit exit 0 ('✓ docs/protocol-upgrade-guide.md — current', marker cleared), pre-push exit 0, generated guide committed over the stub. Probe 3: after leg A, restoring the stub byte-identical (hash equals the head blob) and committing still exits 1, and the marker remains. (2) pnpm check:merge-driver exit 0 at 1a0c04f and in the battery at bf6942b: '.gitattributes ↔ regen-artifacts.mjs agree on 17 path(s)', 'all 34 gen:/check: names resolve', 'all 42 generator(s) across 81 manifest(s) have a recorded disposition', '4 untracked disposition(s) still hold'. Ablation (one-time, committed state, scripts/ablation-replace.mjs --delete, wrap mode): removing the new entry's gen line landed (anchor 1 to 0, blob c313aab460 to 87b2663ec2). git-merge-regen --self-test then exits 1 with 'generator(s) with NO recorded merge disposition: gen:upgrade-guide [@objectstack/spec]'. Restore proven: blob equals HEAD c313aab460, git diff HEAD empty. Direction: red, as predicted. (3) pnpm turbo run build --concurrency=2 under os-verify-lock, VERDICT command-exit 0, 73/73 tasks, @objectstack/docs#build included: at 1a0c04f (0 cached, 8m37s) and at bf6942b (6m23s). regen-artifacts.mjs is a declared input of @objectstack/spec#build, so this edit invalidates the spec build cache and everything downstream. (4) Spec tests under os-verify-lock, VERDICT command-exit 0 at both 1a0c04f and bf6942b: --project local upgrade-guide-docs, projection-cli, render-projection-diff, check-generated-ledger and check-generated-fix-rebuild.pin, 5 files, 50/50. --project repo build-schemas-check-mode.test.ts, 88/88. That file is the one same-package test naming regen-artifacts.mjs (rule 5). (5) Gates: dispatch-gates --commands at bf6942b derived 128, the same set as last round. All 128 ran: 127 exit 0, including check:generated ('All 15 generated artifacts are up to date'), check:upgrade-guide, check:future-spec-major, check:doc-authoring, check:nul-bytes and check:pm-dispatch-gates. check:role-word exit 1 with the pages on disk (walk 257 files); with them removed, CI's tree, exit 0 (walk 254). --ran: '128 derived, 128 run, 0 NOT-MEASURED, 0 UNRUN', exit 0. Same result at 1a0c04f. (6) ESLint narrowed at bf6942b: the 8 changed JS/TS files (the 7 from last round plus scripts/regen-artifacts.mjs), all in eslint.config.mjs's /*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} object. --no-inline-config --format json reports 8 files, 0 errors, 0 warnings. No parserOptions.project is set, so no type-aware rule reaches untouched files. pnpm lint is CI's. NOT MEASURED: os-regen-merge.sh run from a pre-existing branch (its routed list is read from the pre-merge .gitattributes, so by reading it would take main's stub, but that was not run); the full spec suites (last measured at 87a9a34). (7) CI on bf6942b at report time: 36 check runs, 34 success and 2 skipped. All 7 required contexts and Build Docs are success, and the PR reads mergeable_state clean against origin/main 99801d8.",
"gates": "128 derived / 128 run / 0 NOT-MEASURED / 0 UNRUN at bf6942b (dispatch-gates --ran exit 0). 127 exit 0; check:role-word exit 1 while the gitignored content/docs/protocol-upgrade pages are on disk, exit 0 without them (CI's fresh tree).",
"line_budget": "PR: +728 -1679 = 2407 changed lines across 14 files (under the 3,000 human-merge line). This round's own commits: .gitattributes +27 -13, scripts/regen-artifacts.mjs +15 -1. No governed surface in the file list.",
"files_changed": [
".changeset/22483-upgrade-guide-docs-address.md",
".gitattributes",
".gitignore",
"apps/docs/package.json",
"content/docs/meta.json",
"docs/protocol-upgrade-guide.md",
"packages/spec/scripts/build-upgrade-guide.ts",
"packages/spec/scripts/check-generated.ts",
"packages/spec/scripts/lib/projection-cli.ts",
"packages/spec/scripts/lib/upgrade-guide-docs.ts",
"packages/spec/scripts/projection-cli.test.ts",
"packages/spec/scripts/upgrade-guide-docs.test.ts",
"scripts/check-future-spec-major.mjs",
"scripts/regen-artifacts.mjs"
],
"deviations": [
"Premise partly false, measured: 'with no route it conflicts loudly instead' holds for a merge made from a checkout carrying the new .gitattributes. A branch forked before this lands still defers on its own route at merge time. It is caught at its next commit and push, not by a conflict. The .gitattributes prose says exactly that.",
"Probe hygiene: the probe's setup commit and leg 1's --no-commit merges ran with core.hooksPath=/dev/null (the subject was the merge machinery); legs 2 and 3 ran with the real hooks. The probe-2 worktree tookpnpm install --frozen-lockfile --ignore-scripts, sopreparenever rewrote the shared git config. All three probe worktrees were removed without --force;git worktree listshows none.",
"The changeset is untouched: .gitattributes and scripts/regen-artifacts.mjs are repo-root tooling that publishes nothing.",
"PR body not edited, per the order. The exact edits are in open_questions[0].",
"Cleanup done before this post: node_modules removed first, thengit worktree remove /home/user/objectstack-issue-22483without --force. The local branch ref is kept, equal to origin at bf6942b."
],
"mcp_calls": "0",
"api_writes": "1 relay stroke: post-stamped POST /repos//issues/22483/comments (this report), via fleet-write as objectstack-fleet[bot]. Plus 3 git pushes of the branch (fb96a94, 1a0c04f, bf6942b), which are not REST. Every other GitHub call was a GET (claim, report and answer comments, PR state, #22485).",
"open_questions": [
{
"question": "PR body edits for the seat to make (the body cites stale heads and the old route decision).",
"options": [
"E1 '## File surface', 'Beyond it': add.gitattributes(the guide's route line and the header prose from :20) andscripts/regen-artifacts.mjs(row to NOT_DRIVER_MANAGED), per seat answer 6092165230.",
"E2 Replace the paragraph opening 'Kept, and handed to #22485: the guide'smerge=os-regenroute' with: 'Removed here (seat answer 6092165230, option B). .gitattributes drops the guide's route and its header no longer calls the guide a generated single file; regen-artifacts.mjs drops the row and records gen:upgrade-guide as NOT_DRIVER_MANAGEDcontent/docs/protocol-upgrade/**(untracked). check:merge-driver: 17 routed paths, 42 generators with a disposition, 4 untracked dispositions. The spec-changes.json route stays for #22485.'",
"E3 Replace the paragraph opening 'Until #22485 lands, a branch that still carries a regenerated guide' with the scratch-merge result. From a checkout carrying this PR, a merge with a regenerated guide CONFLICTS on the stub; with the route, 8f4ae58, it was silent. A branch forked before this PR still defers on its first plaingit mergeof main. Its next commit and push are then refused, where with the route they passed and the stub was lost. bf6942b's own merge of main conflicted on the stub and kept it.",
"E4 '## Verification' first line: replace 'All at87a9a3435e(after mergingorigin/main4638625e07, which brought #22499's 3 guide lines; the stub was kept)' with 'All atbf6942b723(after mergingorigin/main96e4be4829, whose20e7d52097regenerated the guide; the merge conflicted on the stub, which was kept, blob9473b0f21f)'. Prefix the two full spec-suite numbers with 'at87a9a3435e:', and add 'atbf6942b723, under the lock: the five generator and ledger test files 50/50, andbuild-schemas-check-mode.test.ts(repo project) 88/88'.",
"E5 Gates bullet: replace the '122 exited 0' and '6 exited 3' sub-bullets with: '128 derived atbf6942b723, all run; --ran 0 NOT-MEASURED, 0 UNRUN; 127 exit 0;check:role-wordexit 1 with the gitignored docs pages on disk, exit 0 without them, which is CI's tree (see Acceptance notes)'.",
"E6 ESLint bullet: '7 changed JS/TS files' becomes '8' (adds scripts/regen-artifacts.mjs), measured at bf6942b: 8 files, 0 errors, 0 warnings.",
"E7 Docs build bullet: append '; andpnpm turbo run build --concurrency=2atbf6942b723: 73/73 tasks,@objectstack/docs#buildincluded, exit 0'.",
"E8 Acceptance notes: replace the 'The route window (for #22485)' bullet with the residual from out_of_scope_findings[0], and add the role-word and ADR-0087 notes from open_questions[1] and [2]."
],
"recommendation": "Apply E1–E8 as written. The old Verification line names 87a9a34 / 4638625, and the old Gates bullet reports 6 PREREQUISITE NOT MET, which is no longer the reading."
},
{
"question": "check:role-word goes red locally after any docs build. The gitignored content/docs/protocol-upgrade/{17,18,index}.md that this PR's docs wiring generates sit under its ROOTS ('content/docs'), and its SKIP_SUBTREES names only content/docs/references: 99 NEW uses of the reserved word. CI's Lint job never generates the pages, so CI is green and the gate never reads what the docs site publishes. The uses come from the ADR-0087 registry prose, much of it about retired role-named keys. Fixing it needs scripts/check-role-word.mjs, outside this round's surface, so I did not touch it.",
"options": [
"A: amend the surface and add 'content/docs/protocol-upgrade' to SKIP_SUBTREES in this PR, with the self-test's generated-tree pin extended. That is the gate's own recorded rule for content/docs/references: generated prose whose fix site, the registry .ts, this markdown gate cannot reach. It makes local equal CI.",
"B: leave it. CI stays green, but every local docs build reds the dispatch-gates battery, and agents will read that as a real finding.",
"C: a follow-up card: decide whether registry prose that names the reserved word is quoted history, and gate it at the registry instead."
],
"recommendation": "A. This PR creates the tree. The gate's header gives the fix-site argument that excludes content/docs/references, and it applies here unchanged. One Set entry plus a self-test pin, inside the same family of change. C is the right question only if the maintainer wants the published guide itself held to ADR-0090 D3."
},
{
"question": "Conflict to note, nothing changed: ADR-0087's true-up note landed with main's 40735ea (#22561) at 01:30:28Z, four minutes after the seat's answer B at 01:26:15Z. It says the deletion of 'their two merge=os-regen routes in .gitattributes' is #22485's, and that until #22485 lands 'the generators' no-flag mode (gen:spec-changes, gen:upgrade-guide) still writes them'. With this PR, the guide's route is gone, and gen:upgrade-guide has not written the committed copy since last round. The ruled end state is unchanged; only the note's progress text goes stale. docs/adr/ is Tier H and outside the surface.",
"options": [
"A: #22485, which lands last and has to amend this note anyway, also corrects these two clauses",
"B: a docs-only ADR amendment PR now (Tier H, maintainer approval)"
],
"recommendation": "A: one governed edit instead of two, and the note already defers the end state to #22485."
}
],
"out_of_scope_findings": [
"carrier: #22485 · scripts/check-regen-pending.mjs: a pending path whose REGEN_ARTIFACTS row is gone blocks every later commit and push. It prints 'recorded as pending but absent from scripts/regen-artifacts.mjs (cannot verify)' plus a remedy that cannot apply ('Regenerate ... This check clears itself the moment they are current — nothing to reset by hand'). Restoring the stub byte-identical leaves it refused (probe 3); only deleting the marker by hand clears it. It is reached by any branch forked before this PR that carries a regenerated guide and merges main with plaingit merge. #22485 removes the spec-changes.json route and will create the same state. · dedupe words: os-regen-pending unknown path, absent from regen-artifacts, route removal stale branch, cannot verify marker · noted, not filed",
"carrier: #22485 · scripts/git-merge-regen.mjs comments at :642, :703 and :836 say the table holds '18 paths' / '18 rows — 16 defaulted'. This PR makes it 17 rows, 15 defaulted, and #22485 moves it again. Comment drift, no gate reads it · noted, not filed",
"carrier: none · Acceptance notes carried from the seat's answer, unchanged: ci.yml's docs path filter lists no packages/spec/**, and 8 lines of generated prose carry raw angle-bracket tokens outside code spans (site rendering not measured)"
]
}
Generated by Claude Code
Seat answers to
os-dev-report6093132901on PR #22556 (bf6942b723): Q1 the seat edits the body, Q2 → A (one more patch round), Q3 → Adomain:specseat 1 (#6017) ·os-tesla· sessionsession_01VZqqwTj2wsihZEbfT6yyYN· 2026-10-10T03:07Z · holder of claim6090910124. ⛔ Not an ACCEPT.Q1, the PR body (E1–E8): the seat applies them after patch round 2, together with that round's own readings, in one edit.
Q2,
check:role-word→ A. Addcontent/docs/protocol-upgradetoSKIP_SUBTREESinscripts/check-role-word.mjs, and extend the self-test's generated-tree pin to it. This is the gate's own recorded rule forcontent/docs/references: generated prose whose fix site, the registry.ts, this markdown gate cannot reach. It loses no CI coverage, because CI never generates these pages. It makes a local run equal CI's, so a local docs build no longer reds the battery with 99 findings that are not the reader's to fix. If the maintainer later wants the published guide held to ADR-0090 D3, that is option C's question at the registry, not here. File surface amendment: addscripts/check-role-word.mjs.Q3, the ADR-0087 progress note → A. #22485 lands last and has to amend that note anyway, so it also corrects the two clauses this PR makes stale: the guide's route, and
gen:upgrade-guidewriting the committed copy. That keeps it to one governed edit. A pointer is posted on #22485.Carried to #22485 (pointer there):
check-regen-pending.mjsblocks every later commit and push on a pending path whoseREGEN_ARTIFACTSrow is gone, and prints a remedy that cannot apply (probe 3);- the
git-merge-regen.mjscomment counts (:642,:703,:836).
os-dev-report
{
"issue": 22483,
"status": "done",
"branch": "claude/issue-22483-upgrade-guide-address",
"pr": "#22556",
"session": "session_01VZqqwTj2wsihZEbfT6yyYN",
"premise_still_valid": true,
"summary": "Patch round 2, answer Q2 = A (seat answers 6093145489), done. Final head 7bc190c. scripts/check-role-word.mjs:content/docs/protocol-upgradejoins SKIP_SUBTREES besidecontent/docs/references. The docblock gives the reason in that entry's voice: generated prose whose fix site, the registry.ts, this markdown gate cannot reach. It adds that the tree is untracked, so CI never reads it, and that whether the published guide should meet ADR-0090 D3 is a question for the registry. One forced consequence: the self-test's existing pin required every SKIP_SUBTREES entry to EXIST. A gitignored tree is absent from CI's fresh checkout, so that pin would have gone red in CI. It now accepts an entry that is either on disk or an untracked tree declared in NOT_DRIVER_MANAGED (scripts/regen-artifacts.mjs, imported read-only, not edited). Two new cases in the scan-population battery (floor 5 to 7). (a) The walk reaches no page under any tree that must be skipped; that union is SKIP_SUBTREES plus the register's untracked trees under a ROOT. (b) Every untracked tree the register places under a ROOT is in SKIP_SUBTREES, and the register names at least one. New battery 'Every skipped subtree, at the PROGRAM level' (floor 7; roster 13 to 14). For each tree in that union it runs the gate as a child process over one fixture page, proven to carry the word once: inside the tree, exit 0 with nothing read; one level up under content/docs, a NEW use, exit 1; and in a sibling directory sharing the name prefix, a NEW use, exit 1. Both directions hold at the committed state. With the generated pages on disk, check:role-word exits 0. A planted violation in a hand-written content/docs page still exits 1 and is the only problem reported. The ablation (drop the entry) goes red and restores to blob == HEAD. On its first run, at db7c9ea, the walk case stayed green with pages on disk, because it read the mutated set itself. 7bc190c judges it against the union, and the re-run reds 3 cases with pages and 2 without. origin/main has not moved since round 1 (99801d8), and GitHub reports the PR mergeable, so no merge.",
"tests": "All at 7bc190c unless stated. (1) Before the change, at bf6942b: gen:upgrade-guide wrote content/docs/protocol-upgrade/{17,18,index}.md + meta.json, and check:role-word exited 1 with 2 problems: 17.md 56 and 18.md 43 NEW uses. Without the pages it exited 0. (2) Direction A, at 7bc190c (and before that at db7c9ea), pages regenerated first ('Wrote 4 docs file(s)'): pnpm check:role-word EXIT=0, 'Scanned: 254 .md/.mdx file(s) read across 2 root(s) — content/docs 201, skills 53', and the self-test line reads '0 under the generated subtrees (content/docs/references, content/docs/protocol-upgrade)'. (3) Direction B, at 7bc190c (and before that at db7c9ea), pages still on disk: scripts/ablation-replace.mjs wrap mode planted ', whatever your role.' into content/docs/build-without-code.mdx, which is not in the baseline (anchor x1 to x0, blob 7b5a79bdfa to fd7a3fcb52). pnpm check:role-word then exited 1 with 'check-role-word: 1 problem(s)' and 'content/docs/build-without-code.mdx: NEW use of the reserved word "role" (1 occurrence(s))'. No protocol-upgrade page was named; the only mention of that tree is the self-test's own line. Restored: blob 7b5a79bdfa == HEAD, git diff HEAD empty. (4) CI's tree (pages removed): pnpm check:role-word EXIT=0, walk 254. (5) Ablation, one time, on committed state, wrap mode: SKIP_SUBTREES rewritten to the references entry alone (anchor x1 to x0, blob 5943f2a1f2 to 365ed90dd5), then node scripts/check-role-word.mjs --self-test. With pages on disk: exit 1, 3 failures: the union walk case, the register case, and 'content/docs/protocol-upgrade/ — a page inside it is SKIPPED'. Without pages: exit 1, 2 failures (the register and program-level cases). Restore proven both times: blob 5943f2a1f2 == HEAD, git diff HEAD empty. Direction: red, as predicted. First run of the same ablation at db7c9ea: 2 failures with pages on disk; the walk case stayed green, because it filtered by the mutated set. Fixed in 7bc190c and re-run as above. Second ablation: the walk's path match turned into a string-prefix match. Exit 1, 2 failures, the sibling leg for each tree ('the exclusion is a path, never a string prefix'); restored to blob == HEAD. (6) Gates: dispatch-gates --commands --repo objectstack-ai/objectstack at 7bc190c derived 128, the same set as last round (sorted diff empty), over 15 paths, +860 -1693. All 128 ran with the pages on disk; all 128 exit 0, check:role-word included. --ran: '128 derived, 128 run, 0 NOT-MEASURED, 0 UNRUN', exit 0. Readings from that run: check:merge-driver ('agree on 17 path(s)', '42 generator(s) across 81 manifest(s) have a recorded disposition', '4 untracked disposition(s) still hold'); check:generated ('All 15 generated artifacts are up to date'); check:upgrade-guide (1607820 bytes, 2 major hop sections); check:pm-dispatch-gates ('fast tier: 1825 cases pass', the self-test that reads check-role-word.mjs's watch hints); check:ratchet-remedy-authority ('275 scripts swept'); check:nul-bytes (10578 tracked files, no raw control bytes); check:doc-authoring clean. (7) Build prerequisite: pnpm turbo run build --concurrency=2 under os-verify-lock, 'VERDICT command-exit 0', 73/73 tasks, all 73 cached (check-role-word.mjs is no build input). (8) Spec, under the lock, 'VERDICT command-exit 0': vitest --project local, the 5 generator and ledger files, 50/50. Unchanged this round; rerun for the head's counts. build-schemas-check-mode.test.ts (88/88 at bf6942b) was not rerun: no test names check-role-word.mjs except scripts/pm/dispatch-gates.self-test.mjs, which check:pm-dispatch-gates ran. (9) ESLint, narrowed: the 9 changed JS/TS files, the 8 from last round plus scripts/check-role-word.mjs. All are in eslint.config.mjs's /*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} object. --no-inline-config --format json: 9 files, 0 errors, 0 warnings. No parserOptions.project is set, so no type-aware rule reaches untouched files. pnpm lint is CI's. (10) CI on 7bc190c at report time: 36 check runs, 33 success, 2 skipped, 1 in_progress (Lint & Repo Gates). Test Core, TypeScript Type Check, Dogfood Regression Gate, Build Core, Temporal Conformance, Governed Surface Queue Guard and Build Docs are success. Not waited on.",
"gates": "128 derived / 128 run / 0 NOT-MEASURED / 0 UNRUN at 7bc190c (dispatch-gates --ran exit 0); all 128 exit 0 with the gitignored content/docs/protocol-upgrade pages on disk; check:role-word also exit 0 without them",
"line_budget": "PR: +860 -1693 = 2553 changed lines across 15 files (under the 3,000 human-merge line). This round: scripts/check-role-word.mjs +132 -14. No governed surface in the file list.",
"files_changed": [
".changeset/22483-upgrade-guide-docs-address.md",
".gitattributes",
".gitignore",
"apps/docs/package.json",
"content/docs/meta.json",
"docs/protocol-upgrade-guide.md",
"packages/spec/scripts/build-upgrade-guide.ts",
"packages/spec/scripts/check-generated.ts",
"packages/spec/scripts/lib/projection-cli.ts",
"packages/spec/scripts/lib/upgrade-guide-docs.ts",
"packages/spec/scripts/projection-cli.test.ts",
"packages/spec/scripts/upgrade-guide-docs.test.ts",
"scripts/check-future-spec-major.mjs",
"scripts/check-role-word.mjs",
"scripts/regen-artifacts.mjs"
],
"deviations": [
"Beyond the letter of the order, forced: the existing pin 'every SKIP_SUBTREES entry lies under a configured ROOT and EXISTS' would red in CI for a gitignored tree. It now also accepts an untracked tree declared in NOT_DRIVER_MANAGED. That register is held against git and against its generator's name by check:merge-driver, so dead configuration is still caught.",
"Design choice: check-role-word.mjs now imports NOT_DRIVER_MANAGED from ./regen-artifacts.mjs. It is a pure data module that check-regen-pending.mjs and setup-git-hooks.mjs already import, and it is not edited. The coupling is read-only: deriving which trees must be skipped from it means a dropped SKIP_SUBTREES entry reds on every checkout, not only on one that holds the pages. The alternative was a second hand-kept list in the gate, or agit check-ignorecall.",
"My first commit (db7c9ea) carried a walk case that could not fail for the dropped entry. The ablation exposed it, 7bc190c fixed it, and the ablation was re-run (tests 5). Both commits are pushed; history is not rewritten.",
"Scratch hygiene: the generated pages were written and removed several times (gitignored; none remain). The planted violation and both ablations went through scripts/ablation-replace.mjs wrap mode, each restored to blob == HEAD. git status is clean at 7bc190c.",
"PR body not edited, per the order. The readings for E1–E8 plus this round are in open_questions[0].",
"Cleanup before this post: node_modules removed first, thengit worktree remove /home/user/objectstack-issue-22483without --force. The local branch ref is kept, equal to origin at 7bc190c."
],
"mcp_calls": "0",
"api_writes": "1 relay stroke: post-stamped POST /repos//issues/22483/comments (this report), via fleet-write as objectstack-fleet[bot]. Plus 2 git pushes of the branch (db7c9ea, 7bc190c), which are not REST. Every other GitHub call was a GET: #22483 comments, PR #22556 state and body, and check runs.",
"open_questions": [
{
"question": "PR body readings for the seat's single edit (E1–E8 from report 6093132901, updated to the final head, plus this round). Nothing here needs a decision; it is the text to apply.",
"options": [
"E1 (as before, plus one bullet) '## File surface', 'Beyond it': add.gitattributesandscripts/regen-artifacts.mjs(seat answer 6092165230). Also add: 'scripts/check-role-word.mjs** (seat answer 6093145489, Q2 → A):content/docs/protocol-upgradejoinsSKIP_SUBTREESbesidecontent/docs/references, for the same reason: generated prose whose fix site, the registry.ts, this markdown gate cannot reach. The tree is gitignored, so CI never read it, and a local docs build made the gate report 99 NEW uses (17.md 56, 18.md 43) that CI never saw.'",
"E2, E3: unchanged from report 6093132901.",
"E4 (superseded) '## Verification' first line: 'All at7bc190c714unless a line says otherwise. The last merge oforigin/mainisbf6942b723(96e4be4829, whose20e7d52097regenerated the guide; it conflicted on the stub, which was kept, blob9473b0f21f).origin/mainhas stayed at99801d831fsince, and GitHub reports the PR mergeable.' Prefix the two full spec-suite numbers with 'at87a9a3435e:'. Add: 'atbf6942b723, under the lock:build-schemas-check-mode.test.ts(repo project) 88/88; at7bc190c714, under the lock: the five generator and ledger test files, 50/50'.",
"E5 (superseded) Gates bullet: replace the '122 exited 0' and '6 exited 3' sub-bullets with: '128 derived at7bc190c714, all run with the gitignored docs pages on disk (gen:upgrade-guidefirst);--ran128 derived, 128 run, 0 NOT-MEASURED, 0 UNRUN; all 128 exit 0,check:role-wordincluded. Without the pages (CI's tree)check:role-wordalso exits 0, 254 files read either way.'",
"E6 (superseded) ESLint bullet: '7 changed JS/TS files' becomes '9' (adds scripts/regen-artifacts.mjs and scripts/check-role-word.mjs), measured at7bc190c714: 9 files, 0 errors, 0 warnings.",
"E7 (superseded) Docs build bullet: append ';pnpm turbo run build --concurrency=2: 73/73 tasks with@objectstack/docs#buildatbf6942b723(6m23s), and 73/73, all cached, at7bc190c714'.",
"E8 (superseded) Acceptance notes: replace 'The route window (for #22485)' with the residual from report 6093132901's out_of_scope_findings[0]. Add the ADR-0087 progress-note line (seat answer Q3 → A: #22485 corrects it). Add no role-word note: it is resolved here (E9).",
"E9 (new) '## What changed', one bullet: 'scripts/check-role-word.mjs:content/docs/protocol-upgradeis inSKIP_SUBTREES. The self-test now accepts an untracked tree thatNOT_DRIVER_MANAGEDdeclares where it required one on disk, and it requires every such tree under a ROOT to be skipped. A new program-level battery runs the gate over a fixture page inside each skipped tree (exit 0, nothing read), one level up (NEW use, exit 1), and in a sibling directory sharing the prefix (NEW use, exit 1). Both directions: with the pages on disk the gate exits 0; a violation planted incontent/docs/build-without-code.mdxstill exits 1, and it is the only problem reported. Ablation, dropping the entry: exit 1 with 3 failures with pages and 2 without, restored to blob == HEAD.'"
],
"recommendation": "Apply E1–E9 as written in one edit. The body still cites 87a9a34 and the 6 PREREQUISITE NOT MET gates, which are no longer the reading."
}
],
"out_of_scope_findings": [
"None new this round. Round 1's three (check-regen-pending.mjs refusing on a route-less pending path, the git-merge-regen.mjs comment counts, and the two carried Acceptance notes) stand as the seat routed them: the first two to #22485, the third into the body."
]
}
Generated by Claude Code
✅ ACCEPT — PR #22556 at
7bc190c714(Fixes #22483). Machine face plus docs wiring, seat review; enqueued once CI settlesdomain:specseat 1 (#6017) ·os-tesla· sessionsession_01VZqqwTj2wsihZEbfT6yyYN· 2026-10-10T03:50Z · holder of claim6090910124. Reports:6092146845, patch round 16093132901, patch round 26093449412. Seat answers:6092165230,6093145489.Checked in the diff, not from the reports:
- The address (the seat's choice, which ruling
6078203801delegates): the docs-site page per protocol major,/docs/protocol-upgrade/MAJOR, with the index at/docs/protocol-upgrade. The pages are generated at docs build from the ADR-0087 registries (apps/docsbuildrunsgen:upgrade-guide), are gitignored, and are never committed. Each page marks released / prerelease / not released yet, and names its provenance. H1 (per-version Release URLs) and H3 (outside the ruling; keyed by npm range) are measured and not taken. - The stub:
docs/protocol-upgrade-guide.mdis hand-written, names the index, has one line per major, and gives the pattern for the next. All 11 published pointers resolve through it, each with a check in the PR, and no CHANGELOG is edited. - The generator: no flag writes the docs tree, never the stub.
--out/--checkare unchanged, and the single-file bytes differ from the base by one header-comment line. - The guide's
merge=os-regenroute is removed (answer B):.gitattributesand theregen-artifacts.mjsrow, nowNOT_DRIVER_MANAGED(untracked). A scratch merge shows that a regenerated guide now CONFLICTS on the stub where it was silent, and this PR's own merge ofmainconflicted and kept the stub. Thespec-changes.jsonroute stays for spec(changes): delete the committed spec-changes per-major projection and the upgrade guide copy, with their two merge=os-regen routes, once generation at publish has landed (#22449 B′) #22485. check:role-wordskipscontent/docs/protocol-upgrade, besidecontent/docs/referencesand for the same fix-site reason, so a local run equals CI's. Its self-test ties the skip list to the register's untracked trees and runs the gate at the program level, inside, beside and above each skipped tree. A planted violation elsewhere still fails the gate.- Forced crossings, accepted:
check-future-spec-major.mjs(a quotation exemption the stub no longer needs) andprojection-cli.ts(an optionalcommittedPath). - Semver:
@objectstack/specpatch (the shipped guide's header comment),Clause-②: no. No package export or accept set moves. - Gates: 128 / 128 exit 0 at
7bc190c714, with the docs pages on disk. - Paths: 15 files, +860 / −1693 (2553 < 3000), with the 1662-line committed guide becoming the stub. No governed path; ADR-0087's pointer resolves through the stub.
Out-of-scope findings:
check-regen-pending.mjsrefuses on a route-less pending path with a remedy that cannot apply, and thegit-merge-regen.mjscomment counts drift → carried to spec(changes): delete the committed spec-changes per-major projection and the upgrade guide copy, with their two merge=os-regen routes, once generation at publish has landed (#22449 B′) #22485 (6093148255).- ADR-0087's progress note goes stale → spec(changes): delete the committed spec-changes per-major projection and the upgrade guide copy, with their two merge=os-regen routes, once generation at publish has landed (#22449 B′) #22485's governed edit (answer Q3 → A).
- CI's docs path filter, and raw angle brackets in the generated prose → Acceptance notes.
Landing: ready + auto-merge once the two running checks on
7bc190c714settle green. #22485 is then unblocked.- The address (the seat's choice, which ruling
Merge hop, read off the committed trees ·
domain:specseat 1 (#6017) ·os-tesla· sessionsession_01VZqqwTj2wsihZEbfT6yyYN· 2026-10-10T05:13Z · holder of claim6090910124. The ACCEPT6093474323was at7bc190c714.PR #22556 read conflicted after
main's3e72f9391b(#22569) regenerateddocs/protocol-upgrade-guide.mdthe old way. The merge round's dev pushed42ddb8a3b2, then was stopped by an API access error before it posted a report, so this note is the seat's reading:42ddb8a3b2has parents7bc190c714and3e72f9391b: a merge ofmain, no other commit.docs/protocol-upgrade-guide.mdis byte-identical to7bc190c714's stub (git diff 7bc190c714 42ddb8a3b2on that path is empty). The conflict resolved to the stub, which is the behaviour this PR's route removal makes possible.- Over the PR's 15 paths, the +/- lines of
3e72f9391b..42ddb8a3b2equal those of the reviewed range for 14 paths. The 15th, the stub, differs only in the deleted side, becausemain's guide text moved; its resulting bytes are unchanged. - CI on
42ddb8a3b2: 36 runs, 34 success, 2 skipped (expected-skip roster OK), 0 failure.
So the ACCEPT carries to
42ddb8a3b2. The PR is made ready and enqueued.Landed: PR #22556 →
514bf3c101(the protocol upgrade guide's public address is the docs site, one page per major;docs/protocol-upgrade-guide.mdis a pointer stub).Fixes #22483closed this carddomain:specseat 1 (#6017) ·os-tesla· sessionsession_01VZqqwTj2wsihZEbfT6yyYN· 2026-10-10T05:40Z · holder of claim6090910124, released by this act.- Landed: merged through the merge queue as
514bf3c101(2026-10-10T05:38Z). It has one parent,874a38d8d9, and is an ancestor oforigin/main. - Content check: all 15 PR paths on
514bf3c101are blob-equal to the reviewed head42ddb8a3b2. That is the ACCEPT6093474323at7bc190c714, carried over a plain merge ofmainby6094102331, with the stub byte-identical. - What now holds (
@objectstack/specpatch):- The guide's public address is
https://objectstack.ai/docs/protocol-upgrade/MAJOR, with an index at/docs/protocol-upgrade. The pages are generated at docs build, gitignored, and each marks itself released, prerelease or not released yet. docs/protocol-upgrade-guide.mdis the hand-written stub, and the 11 published pointers resolve through it.- The guide's
merge=os-regenroute is gone, so a regenerated copy now conflicts on the stub instead of overwriting it. check:role-wordskips the generated tree.
- The guide's public address is
- Unblocks: spec(changes): delete the committed spec-changes per-major projection and the upgrade guide copy, with their two merge=os-regen routes, once generation at publish has landed (#22449 B′) #22485 (the deletion). Both of its
Blocked-by:lines are now closed. It carries pointers6089010791and6093148255: the parser witness,check-regen-pending's stuck marker, the comment drift, ADR-0087's progress note, andspec-property-retirementSKILL.md:336. Its PR edits a governed ADR, so it needs a maintainer's approval.
Release:
session_01VZqqwTj2wsihZEbfT6yyYN· why: the card is delivered and closed byFixes #22483· to: closed, unassigned. This act removespm:dispatchedand the assigneeos-tesla.- Landed: merged through the merge queue as
- added a commit that references this issue
on Oct 10, 2026
Filing gate: ③ a maintainer-directed task. Ruling
6078203801on #22449 (B′). Filed bydomain:specseat 1 (#6017) ·os-tesla· sessionsession_01VZqqwTj2wsihZEbfT6yyYN, as the ruling's card ② and triage6078734415item 2. Parent: #22449. ⛔ Not a claim.What the ruling sets
Condition (2): "
docs/protocol-upgrade-guide.mdstays at its path as a committed pointer stub naming the generated guide's public address (the docs site page or the Release attachment; the spec seat fixes which), so the eleven published pointers keep resolving and no published CHANGELOG is edited."This card
docs/protocol-upgrade-guide.mdinto a short pointer stub naming that address, so it no longer carries the guide.packages/client/README.md:141and the package CHANGELOGs that namedocs/protocol-upgrade-guide.md(git grep -l protocol-upgrade-guide). ⛔ No published CHANGELOG is edited.packages/spec/scripts/build-upgrade-guide.tswrites to the new address in card ①'s publish lane, not to the committed path.Order
This card can land beside card ①, and card ③ (the deletion) waits for both.