fix(plugin-security,spec): the grant remedy texts name the reviewed-plan ceremony; C7b wording follow-ups in cli, plugin-auth and the durability vocabularies (#23513)

[objectstack-fleet]

Fixes #23513
Clause-②: no

Item 1 of the card, the skills/objectstack-data/rules/security.md rule, is carried by #23615 under ruling D of #23579 (ruling of record 6184818831). #23615 remains open, and this PR touches nothing under skills/**. This PR carries items 2 and 3. Text only: no behaviour changes.

Item 2: the remedy texts name the reviewed-plan ceremony (commit 559a578)

Since S4 (f9b421716d), os migrate organization-ownership --apply refuses a run without --plan-file. Two texts from #23503 still told the operator to run --apply alone:

• packages/plugins/plugin-security/src/catalog-reference-report.ts, logReport: the boot error line for grants that name no permission set.
• packages/spec/src/migrations/entries/semantic/18.ups-permission-set-id-column-retired.ts: the entry's replacement, the row the upgrade guide prints.

Both now name the two steps. First plan, os migrate organization-ownership --out plan.json, and review the file it writes. Then run os migrate organization-ownership --apply --backup-taken --plan-file plan.json, which executes that plan, and restart. The line's level, its fields, and the entry's id, surface, reason and acceptanceCriteria are unchanged.

.changeset/23513-grant-remedy-plan-file.md releases both packages as a patch. Under the WHICH LEVEL rule this changes no public surface.

Spelling: the plan step is not --plan. The card and the dispatch spelled the plan step os migrate organization-ownership --plan. The CLI has no --plan flag. ADR-0131 calls the bare run "--plan", and the command's flags are --out, --json, --apply, --plan-file and the rest. Measured against the built CLI at this head:

• os migrate organization-ownership --plan exits 2 with Nonexistent flag: --plan. The command never ran.
• os migrate organization-ownership --apply --backup-taken exits 1 with Refused: --apply executes only a plan you reviewed. Run the plan first (os migrate organization-ownership, ...), review the file it writes, then re-run --apply with --plan-file FILE.

So both texts use --out plan.json for the plan step. That is the spelling of S4's own ADR-0087 entry, cli-organization-ownership-apply-plan-file-required. The dispatch's intent is kept: a plan step, then --apply --plan-file with the reviewed file.

Item 3: stale wording (commit 02ab85b)

• packages/cli/src/utils/organization-ownership-grants.ts (grantKey) and organization-ownership-plan.ts (GrantKeyPlan): these comments said a NULL organization is keyed "as the write door keys it". The write door is retired. The text now says it is keyed as the grant's unique: 'organization' index keys it, because the index's organization key part is NULL-safe (ADR-0120 D3).
• packages/cli/src/utils/organization-ownership-apply.test.ts: one test title said GROUP BY keys NULLs together "unlike the index". It now says "as the index's NULL-safe organization key part does". Only the title changes; the assertions are the same.
• packages/plugins/plugin-auth/src/grant-set-name.ts: the module header said C8 drops permission_set_id, and that a one-time boot backfill names legacy grants. It now says C7b retired the column, that no boot names a grant, and that the v18 ceremony's verified rewrite names one or lists it with its reason.
• scripts/check-durability-degradation-log-level.mjs (DURABILITY_CRITICAL_CALLEES) and scripts/measure-durability-swallow-family.mjs (WRITE_SHAPED_CALLEES): persistGrantNameBackfillRecord is removed from both. feat(plugin-security,cli,spec)!: retire sys_user_permission_set.permission_set_id; the grant key is unique per organization; the boot grant-name backfill is deleted (C7b S3) #23503 deleted its only definition. The two lists must change together, because the census cross-checks its copy against the gate's declaration.

Verification at head 02ab85b

• Build: turbo run build --concurrency=2 over @objectstack/cli..., @objectstack/plugin-security..., @objectstack/plugin-auth... and @objectstack/spec... (the packages and their upstream dependencies): 61 of 61 tasks passed.
• Typecheck: pnpm --filter PKG run typecheck for plugin-security, plugin-auth, cli and spec all exit 0. The test-layer typecheck is OK in all four.
• Tests:
  • plugin-security: 185 files, 3690 passed, 45 skipped.
  • plugin-auth: 145 files, 2845 passed, 10 skipped.
  • spec (--project local, after gen:migration-registry): 678 files, 20728 passed, 1 todo.
  • cli: organization-ownership-apply.test.ts and -column-drops.test.ts run under --project integration, the tier they belong to and the tier the edited test file is in: 2 files, 99 passed. The renamed test passes under its new title (-t 'NULL-safe organization key part', verbose). The cli unit tier was not run in full here: it went over the 10-minute foreground limit on a shared box, and CI runs it.
  • The tests that read the two edited scripts: metadata-protocol sys-metadata-repository.draft-drain.test.ts and protocol.metadata-store-outage.test.ts (43 passed), and runtime http-dispatcher.keys.test.ts (20 passed).
• The two durability scripts:
  • pnpm check:durability-log-level exits 0. Its self-tests pass: 68 log-level cases and 57 read-seam cases. Verdict: 46 durability-critical catch seams, all loud, rethrowing or propagating.
  • pnpm check:swallow-census-controls (--self-test=gated) and node scripts/measure-durability-swallow-family.mjs --self-test both exit 0, with "24 copied gate-vocabulary name(s) match the gate's own declaration".
• Derived gates: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derives 114 commands. All 114 were run, each exit code was recorded, and --ran reports: "114 run, 0 NOT-MEASURED (a DERIVED zero)".
  • These include check:adr-0087-registration, check:spec-changes, check:upgrade-guide, check:scripts-symbol-anchors, check:spec-docblock-symbol-anchors, check:doc-authoring, check:nul-bytes and check:pm-dispatch-gates (1841 cases).
  • check:dual-build-cjs-loads and check:i18n-coverage first answered exit 3, PREREQUISITE NOT MET: some packages outside this diff had no dist. A later gate in the same run built those packages. Both were re-run at this head and exit 0. The recorded codes are from the re-runs.
  • pnpm check:adr-anchors, which the derivation does not place, was also run: exit 0.
• Lint, narrowed to the 8 changed source files: pnpm exec eslint --no-inline-config --format json reports 0 errors and 0 warnings. Three facts show the narrowing leaves nothing out:
  • All 8 files are inside the config's lint set: ESLint.isPathIgnored answers false.
  • The JSON output counts 8 files.
  • eslint.config.mjs never enables type-aware linting (no parserOptions.project), so this diff cannot change the verdict on any file it does not touch.

Acceptance notes

• The pending feat(plugin-security,cli,spec)!: retire sys_user_permission_set.permission_set_id; the grant key is unique per organization; the boot grant-name backfill is deleted (C7b S3) #23503 note, .changeset/23430-grant-permission-set-id-retired.md, is corrected in commits 55725c1 and a618e17 (the PM's answer A). It is still pending in .changeset/, not .changeset/pre/. Exactly two sentences change. In the FROM → TO list, "→ os migrate organization-ownership --apply." becomes "→ the v18 ceremony: plan it with os migrate organization-ownership --out plan.json, review the file it writes, then run os migrate organization-ownership --apply --backup-taken --plan-file plan.json." Under "What else changes", "os migrate organization-ownership --plan reports a grants block" becomes "The plan run, os migrate organization-ownership --out plan.json, reports a grants block". Check Changeset stays red by design: this is a DELIBERATE CORRECTION of a pending note that another PR changed, and the seat confirms it at ACCEPT. Changeset checks at a618e17: check-empty-changeset --base origin/main exits 1 (expected), and its --self-test exits 0. check-changeset-no-major --base origin/main and its --self-test both exit 0.
• Left as written:
  • Comments and docs that name os migrate organization-ownership --apply as the step that performs the rewrite, not as a command to run: security-plugin.ts, two plugin-security test headers, the plugin-auth reader header, and content/docs/permissions/{permission-sets,capabilities}.mdx.
  • The same entry's acceptanceCriteria, which says what is true after --apply has run.
• No pin was added. No test asserts the text of the unnamed-grant line or the entry's replacement, so the dispatch's rule (pin only a text that a test asserts) adds none.
• Seat 1's S2 (feat(metadata-core,metadata-protocol)!: the sys_metadata family declares no organization column; indexes re-keyed (ADR-0131 D6/D7, C7b S2) #23469) may also edit organization-ownership-plan.ts. This PR changes only the GrantKeyPlan doc comment there, and main was not merged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ADzJtzYTLUfgrRZHxkagkX

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 4 changed package(s); no hand-written page names any of them. ⚠️ 3 changed file(s) yielded no anchor (packages/cli/src/utils/organization-ownership-grants.ts, packages/cli/src/utils/organization-ownership-plan.ts, packages/plugins/plugin-auth/src/grant-set-name.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

What this run could not see

• 3 changed file(s) yielded no anchor (packages/cli/src/utils/organization-ownership-grants.ts, packages/cli/src/utils/organization-ownership-plan.ts, packages/plugins/plugin-auth/src/grant-set-name.ts) — pages documenting those are invisible to this run
• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 154 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json dd29bbe60df87727664424521c3a0b9eed37e985 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from c8260f80f9cbfa722821af20316009fe4263ec37 — the merge of head 9f50f1887b0f47ed778b3bff7f261d23831569a2 into base dd29bbe60df87727664424521c3a0b9eed37e985, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin c8260f80f9cbfa722821af20316009fe4263ec37 && git checkout c8260f80f9cbfa722821af20316009fe4263ec37
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin dd29bbe60df87727664424521c3a0b9eed37e985 9f50f1887b0f47ed778b3bff7f261d23831569a2 && git checkout -B drift-repro dd29bbe60df87727664424521c3a0b9eed37e985 && git merge --no-ff 9f50f1887b0f47ed778b3bff7f261d23831569a2

node scripts/docs-audit/affected-docs.mjs --json dd29bbe60df87727664424521c3a0b9eed37e985

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 55725c1d79fc4f4cefd8b4d8af2bed06a63fadb9
Local-runs: none

PR #23624 at the head the brief named (it has not moved): merge base dd4ef38506, 3 commits, 10 files, +45/-28. The REST file list and git diff origin/main...head agree. Read through refs only.

① Derived judgments

Item 2: the remedy texts.

• The CLI's flags on origin/main (packages/cli/src/commands/migrate/organization-ownership.ts, static flags) are database-url, out, json, apply, plan-file, backup-taken, template-choice, metadata-choice and fate-supplement. None has an alias. There is no plan flag: "--plan" appears only in the docblock, as the ADR's name for the bare read-only mode. --out is the plan mode's file flag (with --apply it names the report). The dev's disproof holds.
• runApply refuses a run without --plan-file (plan-file-required). Both texts now give the shape the CLI accepts: plan with --out plan.json, review the file, run --apply --plan-file plan.json, then restart. That holds for the logReport line in catalog-reference-report.ts and for the replacement of ups-permission-set-id-column-retired.
• The spelling is identical to S4's entry only for the plan step. S4's entry cli-organization-ownership-apply-plan-file-required writes the plan step as os migrate organization-ownership --out plan.json and says "review the file it writes". This PR uses the same words. The apply step differs:
  • S4's entry, S4's pending note 15211-cli-apply-reviewed-plan.md and the CLI's examples all spell it --apply --backup-taken --plan-file plan.json.
  • This PR's three texts spell it --apply --plan-file plan.json.
  • The CLI still accepts the PR's spelling, but only at a terminal. Without --backup-taken, the CLI's local confirm asks the backup question and goes on after a yes. A run with no TTY, or with --json, is refused with backup-unacknowledged. That refusal comes before any write and names the flag.
  • The card's wanted text and the CLI's own plan-file-required remedy also leave the flag out.
  • The PR body's claim "the spelling of S4's own entry" covers only the plan step, and it is true for that step.
  • Non-blocking: see ③ flag 8.
• No plugin-security or spec test asserts either text, so no pin is owed. This matches the card.

The pending-note correction.

• .changeset/23430-grant-permission-set-id-retired.md sits in .changeset/ on both main and the head. It is not among the 582 files in .changeset/pre/. No CHANGELOG.md carries its text: runOneTimeGrantPermissionSetNameBackfill appears in none. It is pending.
• The diff to that note has numstat 2/2: line 21 (FROM → TO) and line 27 ("What else changes"). Both now say --out plan.json, and line 21 says --apply --plan-file plan.json. Nothing else changed: the frontmatter (three minor), Clause-②: yes (narrowing) and the adr-0087 marker are untouched.
• Check Changeset failed three times on this head (PR Automation runs 38691420251, 38691572183 and 38691702287). Each failed at step 12, "Reject an empty-frontmatter changeset added by this PR", with one file annotation, and every annotation names only .changeset/23430-grant-permission-set-id-retired.md (the finding: random changeset filenames collide silently across parallel agents — a round overwrote a sibling PR's minor changeset and every gate stayed green #17712 COLLISION vs DELIBERATE CORRECTION refusal).
  • Steps 11 (require a changeset), 13 (ADR-0087 disposition) and 15 (no major) pass.
  • It is not a COLLISION: the PR's own note has its own name, 23513-grant-remedy-plan-file.md.
  • The PR has no skip-changeset label, as [finding] the skip-changeset label suppresses the DELIBERATE-CORRECTION refusal whose own text says 「no label and no diff shape makes that safe」 — declared contract against enforced behaviour #18375 ruling D requires.
  • So the red names only the deliberate correction.

Item 3: is each reworded comment true on main plus this PR?

• grantKey (organization-ownership-grants.ts) and GrantKeyPlan (-plan.ts): true.
  • On main, the grant's index is { fields: ['user_id', 'permission_set', 'organization_id'], unique: 'organization' } (sys-user-permission-set.object.ts:267).
  • ADR-0120 D3 builds that index's organization key part as COALESCE(organization_id, '__global__'), so a NULL organization is one key. JSON.stringify([user, name, null]) keys it the same way.
  • Neither comment names the retired door any more.
• The apply-test title (:1981): true. The test inserts two NULL-organization grants of one set and asserts a column-drops blocker of 2 grants in 1 group. GROUP BY keys the NULLs together, as D3 says the index does. Only the title string changed, and "unlike the index" no longer appears anywhere on the head.
• The plugin-auth grant-set-name.ts header: true.
  • C7b S3 (feat(plugin-security,cli,spec)!: retire sys_user_permission_set.permission_set_id; the grant key is unique per organization; the boot grant-name backfill is deleted (C7b S3) #23503) retired the column.
  • The backfill has no definition or call left on the head. Two plugin-security test comments mention it only in the past tense.
  • "No boot names a grant" holds.
  • The rewrite does list each grant it does not name, with a reason: GrantRewritePlan.reasons is keyed by UnnamedReason, and collisions name both ids.
  • The header names os migrate organization-ownership --apply as the act that names a grant, not as a command to run. That is the PR's declared left-as-written class.
• The persistGrantNameBackfillRecord removal: complete.
  • git grep finds zero references anywhere on the head.
  • It left DURABILITY_CRITICAL_CALLEES and the census's WRITE_SHAPED_CALLEES gate-vocabulary copy together, so the copy-vs-declaration cross-check still matches.
  • Neither script nor any baseline hard-codes the count: both print copiedGateNames.length.
  • Since the merge base, main changed the gate only in a comment (9a6f790, feat(scripts): dispatch-gates names check:durability-log-level for a file holding a catch and a declared durability-critical callee #23612). It touches no map entry.

No behaviour change: confirmed. The only executable changes are:

• the logReport string literal (still logError, fields { count, organizations });
• the entry's replacement string (id, surface, reason and acceptanceCriteria unchanged);
• one test-title string;
• the two map entries for a callee that no longer exists.

Everything else is comments and changesets. Nothing under skills/** is touched.

② Semver level

patch for @objectstack/plugin-security (log text) and @objectstack/spec (one entry's prose value) is correct under WHICH LEVEL. The PR adds no export, key or accepted value, and "a fix( that changes no public surface stays patch". The PR body and the changeset both read Clause-②: no, so the level axis stands down. No major. @objectstack/cli and @objectstack/plugin-auth change only comments and a test title, and correctly release nothing.

③ Boundary flags

From 6185759753 and the patch round (55725c1):

1. --plan disproved, --out plan.json used. Confirmed from the flag definitions (①). Answered.
2. The "consumed or published" premise was false: the note is pending. Confirmed (①). The open question was answered A in the patch round, and the correction is limited to two sentences. Still owed: the DELIBERATE CORRECTION remedy needs the confirmation written on the PR. The body states it; the seat's ACCEPT must carry the confirmation (precedent Q-S4 → A, 6164948359).
3. NOT MEASURED locally: the cli unit tier. CI's Test Core: all six shards and the Test Core roll-up concluded success on this head. Measured by CI; closed.
4. check:dual-build-cjs-loads and check:i18n-coverage answered exit 3 first (prerequisite only), then 0. Not re-judged here. CI's Lint & Repo Gates is green on this head.
5. Zero label writes, and no skip-changeset. Correct under [finding] the skip-changeset label suppresses the DELIBERATE-CORRECTION refusal whose own text says 「no label and no diff shape makes that safe」 — declared contract against enforced behaviour #18375 ruling D.
6. The commit trailer. All three commits carry the model-free Co-authored-by: Claude with Claude-Session. No commit carries a model id.
7. Left as written. Comments and docs that name --apply as the act: I read the two mdx lines (permission-sets.mdx:397, capabilities.mdx:220). They describe the act and give no instruction. Agreed; no carrier needed.

New from this review:

8. The --backup-taken divergence (non-blocking; the seat rules). The three texts spell the apply step without --backup-taken. The S4 entry and S4's note spell it with the flag, and both will appear in the same CHANGELOG. What happens:

   • At a terminal, the CLI accepts the PR's spelling after the backup question.
   • In a script (no TTY), the run is refused with backup-unacknowledged, nothing is written, and the refusal names the flag.

   Either accept this as the interactive form at ACCEPT, or add one word in each of the three places in a patch round.

9. S2 feat(metadata-core,metadata-protocol)!: the sys_metadata family declares no organization column; indexes re-keyed (ADR-0131 D6/D7, C7b S2) #23469 is still open. It overlaps this PR only in the GrantKeyPlan doc comment in organization-ownership-plan.ts. Whichever lands second merges main. This head merges cleanly with main today.

10. The PR is still a draft. The seat flips it before the queue.

CI on this head: 55 check-runs, read at 2026-10-15T06:49Z: 42 success, 10 skipped, 3 failure, none running. The only failures are the three Check Changeset runs, by design (①). Test Core (1/6 to 6/6 and the roll-up), all four Type Check lanes (source gates, debt ledger, consumer gates, workspace), Build Core and Lint & Repo Gates with its lanes are green.

Seat adoption (2026-10-15T07:05Z). Adopted after an audit of the reviewer transcript: one Write, to this record; 52 Bash calls, all reads (git show, git diff, an in-memory git merge-tree, REST GETs); one Monitor polling the check-runs; no MCP call, no GitHub write, no worktree, build or test run.

The head moved after this record, and the seat verified the delta itself. git diff 55725c1d79 9f50f1887b touches 4 files, +7 / −7. The only change is --backup-taken inserted into the apply step in five places:

• catalog-reference-report.ts logReport, whose string is re-wrapped with its text otherwise unchanged;
• the ups-permission-set-id-column-retired entry's replacement;
• feat(plugin-security,cli,spec)!: retire sys_user_permission_set.permission_set_id; the grant key is unique per organization; the boot grant-name backfill is deleted (C7b S3) #23503's pending note, line 21;
• this PR's own changeset (title and line 15).

This aligns the apply step with S4's entry, S4's note and the CLI's examples, so a non-TTY caller is not refused backup-unacknowledged. That answers this record's non-blocking --backup-taken point.

The landing prechecks on 9f50f1887b:

• CI is green except Check Changeset. Its one annotation names only .changeset/23430-grant-permission-set-id-retired.md, under the DELIBERATE CORRECTION class.
• check-governed-merges.mjs reports no governed path.
• git merge-tree against origin/main exits 0.
• The only closing keyword is Fixes #23513.

The seat confirms the DELIBERATE CORRECTION. #23503's note is still pending (it is not in .changeset/pre/, and no CHANGELOG carries it). Its lines 21 and 27 named a bare --apply, which the CLI refuses, and a --plan flag, which does not exist. They now name the real ceremony: --out plan.json, review, then --apply --backup-taken --plan-file plan.json. The precedent is Q-S4 → A on #15211 (6164948359). Check Changeset is red by design for this alone: it is not a required queue context, and this comment records the gate and its reason.

Implemented-by: claude/issue-23513-grant-name-followups
Reviewed-by: session_01ADzJtzYTLUfgrRZHxkagkX

VERDICT: PASS