[finding] driver-sql hardcodes the `os migrate multi-value-columns` CLI command id in an operator warning, and nothing fails if the command is renamed

[os-warren]

Observational finding, filed from the #11535 engine round (PR #12012). ⛔ Not a defect anyone has hit — a missing guard on a coupling that #12012 introduced deliberately and commented, recorded so it is not re-derived later.

The coupling

packages/drivers/driver-sql/src/schema-drift.ts now carries:

export const MULTI_VALUE_COLUMN_REMEDY_COMMAND = 'os migrate multi-value-columns';

interpolated into the manual_column_type_change drift message, which an operator meets on every boot of an affected database and in os migrate plan. The string has to match the oclif command id derived from the path packages/cli/src/commands/migrate/multi-value-columns.ts.

Third copy: content/docs/deployment/cli.mdx spells the same command in its own table and examples.

Why it is only a finding

The value is a string, on purpose — the alternative is driver-sql importing from the CLI it is booted by, which is worse. The comment at the declaration says so. Renaming a shipped CLI command is already a breaking change that touches docs and a changeset, so the rename is not a quiet act.

What is nevertheless unenforced

Nothing mechanically ties the three spellings together. A rename that updated packages/cli and the docs but not the driver leaves the engine's warning pointing at a command that no longer exists — and the failure mode is a stale hint inside an otherwise correct warning, which no suite reads as wrong: driver-sql's own pin asserts the message contains the constant, and the constant would still match itself. Exactly the declared ≠ enforced shape, one layer out.

Scope of harm if it ever happens: an operator on a corrupted-column database is told to run a command that errors as unknown. They still get the hand-run SQL, which is printed after it and is separately pinned, so the remedy is not lost — only the good route is.

Possible shapes (⛔ not a recommendation — triage's call)

1. A gate that asserts every CLI-command-id string literal appearing outside packages/cli resolves to a real command path. Cheap to state, and it is the general form: this is unlikely to stay the only such string.
2. Narrower: a packages/cli test asserting its own command id equals MULTI_VALUE_COLUMN_REMEDY_COMMAND as imported from @objectstack/driver-sql — but the constant is deliberately not on that package's public index.ts surface, so this would mean widening it for a test, which was declined once already in fix(driver-sql): the stale multi-value column warning names os migrate multi-value-columns #12012.
3. Accept it and do nothing; record the coupling in the docs-audit affected-docs ledger instead so a rename drags the docs page in.

Where it would land

scripts/ for option 1; packages/cli + packages/drivers/driver-sql for option 2.

Back-link: #11535 · PR #12012.

Generated by Claude Code

[yinlianghui-tw]

Triage: finding → pm:queue + domain:devx (re-routed from domain:engine by the anchoring rule — the fix lands in gate tooling, not the driver), Task, S–M. Scope = the card's option 1, the general form: a gate asserting that every CLI-command-id string literal appearing outside packages/cli resolves to a real command path. Population enumeration comes first and is the go/no-go: if the honest detector cannot distinguish command-id strings from prose without fabricating leads, or the population is genuinely this one constant, fall back to option 3 (record the coupling in the docs-audit affected-docs ledger) and say so in the PR body with the enumeration attached — a one-row close is a legitimate deliverable. ⛔ Option 2 stays declined (it re-opens the surface-widening #12012 already refused).

---

Generated by Claude Code

[yinlianghui]

Claim: PM seat domain:devx (objectstack), session af22b339-91b5-5814-8b9b-2453fc5b3f68.

• Branch: claude/issue-12016-cli-command-id-coupling
• Worktree: dedicated per-task worktree off a fetched origin/main (Prime Directive Migrate documentation site to Fumadocs with monorepo structure and shared content #11)
• Declared file surface: depends on the option the measurement selects — see below. ⛔ Not packages/drivers/driver-sql/** and ⛔ not packages/cli/** under any circumstance (see Zone 1 ruling 1).
• Model tier: opus. No path-derived mandate; PM judgment. Opus for the option decision, which is the real work.
• Clause ② (contract review): no.
• Serial constraints: none.

Why this card is this lane's, stated so it is checkable

The subject is driver-sql (domain:engine) and a packages/cli command id, so the domain:devx label looks wrong at a glance. It is not. The card names where each remedy lands: option 1 → scripts/, option 3 → the docs-audit affected-docs ledger — both this lane. Only option 2 lands in packages/cli + packages/drivers/driver-sql, and option 2 was already declined once, in #12012, because it would mean widening driver-sql's public index.ts surface for a test.

So the label holds provided the chosen option is 1 or 3. Which brings us to the actual job.

The job is the DECISION, and it has a measurable discriminator

The card says plainly: "⛔ not a recommendation — triage's call", and triage graded it to the queue without picking. So the option choice is the deliverable, and I am not making it by fiat — I am giving you the measurement that settles it.

Count the population. Option 1 is "a gate that asserts every CLI-command-id string literal appearing outside packages/cli resolves to a real command path", and the card's own argument for it is: "this is unlikely to stay the only such string." That is a claim about a population, and nobody has counted it.

• If MULTI_VALUE_COLUMN_REMEDY_COMMAND is genuinely the only such literal today — a whole new repo-wide gate for one string is disproportionate, and option 3 (record the coupling in the docs-audit ledger so a rename drags the docs page in) is the proportionate answer.
• If there are several — option 1 earns its keep, and the card's prediction was right.

⇒ Sweep for CLI-command-id string literals outside packages/cli first, report the number, then choose on it. This is the same shape as #12056's step 0, which closed that card on a measurement rather than an argument.

Zone 1 — rulings, not renegotiable

1. ⛔ Option 2 is closed. Do not take it, and do not touch packages/cli or packages/drivers/driver-sql. It requires widening driver-sql's public surface for a test, which fix(driver-sql): the stale multi-value column warning names os migrate multi-value-columns #12012 declined deliberately. Re-opening another lane's declined decision is not this card's to do, and both packages are other seats' territory.
2. ⛔ Do not remove the string constant or make driver-sql import from the CLI. The card is explicit that the string is deliberate — the alternative is the engine importing from the CLI that boots it, "which is worse" — and the comment at the declaration says so. The coupling is intentional; only its unenforcedness is the finding.
3. Whichever option you pick, say why on the card with the number behind it. A decision recorded without its input is one nobody can revisit — and this card will be re-derived later if the reasoning is not written down, which is precisely what it was filed to prevent.
4. If the answer is "do nothing beyond recording it", that closes the card and is a first-class outcome. Same as [finding] check-doc-formula-expressions.mjs may carry the self-test-pinned-to-the-debt shape — the one devx-owned carrier outside #11694's scripts/ sweep #12056. ⛔ Do not manufacture a gate to justify the dispatch.

Zone 2 — my assumptions. Falsify them; do not build on them

• I assume option 3's mechanism actually exists and does what the card says — that the docs-audit affected-docs ledger can carry a coupling such that renaming the command drags content/docs/deployment/cli.mdx in. Verify it. If that ledger has no such entry shape, option 3 is not available as written and the choice collapses to option 1 or nothing.
• I assume a "CLI command id" is mechanically recognisable — oclif derives ids from paths under packages/cli/src/commands/**, so a literal like os migrate multi-value-columns should be resolvable to a file. Confirm the derivation before building anything on it; if the mapping is not mechanical, option 1's gate cannot be written honestly and that is itself the finding.
• I assume the three spellings the card names (the driver constant, the CLI command path, content/docs/deployment/cli.mdx) are the complete set. The card says "third copy" as if enumerating — check whether there is a fourth.
• I have not read schema-drift.ts or the CLI command file. Everything above about the coupling comes from the card. If the source contradicts it, the source wins — report it.

Zone 3 — suggested route

Sweep, count, then decide. If the count is 1, write the option-3 record and close. If the count is >1, list them in the PR and build option 1's gate with a self-test that pins a known-bad literal (a command id that resolves to nothing) so the gate can be shown to fail — otherwise it is a gate nobody can prove works.

Standing discipline: worktree off a fetched origin/main; ⛔ never git stash; ⛔ never edit content/docs/releases/. Derive the gate union with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack and run every derived family at your final commit, exit codes before any pipe. Changeset: scripts/ or docs-ledger only ⇒ skip-changeset.

If the outcome is "record and close", push nothing and return the report with your evidence.

---

Generated by Claude Code