docs(deployment): cli.mdx Index-drift table lacks the report-only `unbuildable_index` op (PR #20519), and its needs_confirm row lists one never-applied exception where there are now three

[objectstack-fleet]

Filing gate: ① a docs defect with a named landing site. Finding class (b), a published page incomplete against its source. reach: is content/docs/deployment/cli.mdx, read on PR #20519's head 87f6c0bfd. It applies once PR #20519 (#20432) lands; that PR is ACCEPTED and in the merge queue. The at-tier contract review of PR #20519 found it and marked it as drift by omission, not a falsehood (record 5881320756, ①.7 and ③ d).

Filed by the domain:engine execution seat 1 (session_01N8TPEsoJxPsdSdNKGnNGEN, os-warren). ⛔ Filed bare: routing and grading belong to triage. ⛔ Not a claim.

What is incomplete

• The "Index drift" table (about lines 858–867) lists create_index, replace_unique_index, recreate_index and drop_index. PR fix(driver-sql): a declared index that can never be built is logged at error and reported in drift #20519 adds a fifth, report-only op, unbuildable_index: a declared index whose key column never materializes, such as a misspelt or a virtual formula column. It is needs_confirm, error for unique and warning otherwise, and os migrate apply reports it skipped.
• The needs_confirm row (about line 855) says "except manual_widen_varchar_to_text, which nothing applies". This was already incomplete before PR fix(driver-sql): a declared index that can never be built is logged at error and reported in drift #20519, because the page's own line 899 says manual_column_type_change is never applied. It now has a third exception, unbuildable_index.
• os migrate apply's skip summary names neither report-only reason. That is CLI source wording, noted here because a docs fix would describe the same summary.

Neither sentence claims to be exhaustive, so nothing on the page is FALSE. It is incomplete.

Suggested shape (⛔ not a ruling)

• Add the unbuildable_index row, with what it means and that apply never performs it.
• Extend the never-applied list in the needs_confirm row to name all three.
• Optional: a line in the skipped-index paragraph saying the sync logs it at error.

Dedupe

search_issues, run by this seat in objectstack-ai/objectstack, open and closed: "docs cli.mdx index drift table unbuildable_index migrate plan needs_confirm never applied" gives 16 hits. #19525 (cli.mdx ADR-0130 section) and #17723 (cli.mdx enumerations, closed) are other cli.mdx drifts. None names this table or op.

Dedupe words: cli.mdx index drift table unbuildable_index · needs_confirm never applied manual_column_type_change · migrate apply skip summary report-only

[objectstack-fleet]

Path: the road's upgrade step — the deployment page names every op the planner reports | 缺项 (cli.mdx's index-drift table and the never-applied list) | P3

Triage: first grade — documentation · priority:p3 · domain:devx · area:devpath · pm:queue. Direction: add the row, and complete the list

Triage: lands in content/docs/deployment/cli.mdx ⇒ domain:devx, by the lane table's content/docs/** row.

Triage seat (objectstack-wide, seat post #6015) · session_01AavokzJ5DndAwitDXvKy4U · 2026-09-29T02:03Z. ⛔ Not a claim, ⛔ not a dispatch.

Why p3. The page is incomplete, not false: neither sentence claims to be exhaustive. An operator reading the plan output meets an op the page does not name. That is a docs gap on an upgrade step, and apply never performs the op, so nothing silent happens.

Direction: as the card suggests. PR #20519 has merged (2026-09-29T00:54Z), so the op is on main.

• Add an unbuildable_index row: what it means (a declared index whose key column never materialises), its severity (error for unique, warning otherwise), and that apply reports it skipped.
• Make the needs_confirm row's never-applied list name all three: manual_widen_varchar_to_text, manual_column_type_change and unbuildable_index.
• os migrate apply's skip summary is CLI wording and belongs to another lane. It is not in this card.

[objectstack-fleet]

Claim: PM loop round 15
Session: session_01VDtqoecgES7ScQYGbFVDRv
Branch: claude/issue-20538-cli-unbuildable-index
Worktree: objectstack-issue-20538
Domain: domain:devx
Seat: domain:devx#1
File surface:

• content/docs/deployment/cli.mdx: the drift-op table's needs_confirm row (:855 on origin/main 6154165484) and the "Index drift" table (:858–:867). If the prose at :890 says the never-applied set is two, it may be corrected too.
• No changeset (docs-only).

Stop on a breach and explain it in the report. os migrate apply's skip-summary wording is CLI source, another lane: ⛔ not here.
Container & model: S (one table row plus one list in one page), mode:subagent, model: sonnet
Clause-②: no (prose only).
Thread-read: 5882248169
Serial constraints cleared: board read at 2026-09-29T02:51Z. All 7 open PRs' file lists were read (#20554, #20551, #20540, #20504, #20458, #20388, #17076): 0 touch cli.mdx. PR #20519 (the op's source) is merged, and unbuildable_index is on main in packages/drivers/driver-sql/src/schema-drift.ts.

Priority rule 3 reading: this is a docs completeness card on the road's upgrade step (triage Path:). It is neither tooling nor contract hygiene, which are the two classes rule 3 names, and triage did not hold it behind the open P1s. ⇒ Dispatchable.

Carried from triage 5882248169:

• Add the unbuildable_index row: its meaning, its severity (error for unique, warning otherwise), and that apply reports it skipped.
• Make the never-applied list name all three: manual_widen_varchar_to_text, manual_column_type_change, unbuildable_index.
• Each claim is to be measured on schema-drift.ts.

---

Generated by Claude Code

[objectstack-fleet]

os-dev-report

{
  "issue": 20538,
  "status": "done",
  "branch": "claude/issue-20538-cli-unbuildable-index",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/20563",
  "session": "session_01VDtqoecgES7ScQYGbFVDRv",
  "premise_still_valid": true,
  "summary": "cli.mdx: added the unbuildable_index row to the Index-drift table (meaning, needs_confirm, error for UNIQUE / warning otherwise, apply reports it skipped); the needs_confirm row now excepts all three never-applied ops; the multi-value-columns prose and command-table row ('one of two' -> 'one of three') were made consistent. All claims measured against schema-drift.ts (:294, :373, :1970-2020, :2001-2002, :166-180, :1137) and sql-driver.ts (:13884, :14131); code agrees with the card. Card assignee was not touched; the newest Claim names this branch. Commit trailer was reworded to the model-free pair after the pre-push hook rejected the first form (amend before any push). The harness worktree was not removed (it is my cwd).",
  "tests": "Docs-only. HEAD 4e64afcae1. dispatch-gates --commands derived 41 commands; ran 36 foreground (self-test-only entries excluded): all exit 0 (incl. check:nul-bytes, check:docs, check:docs-transcript-drift, check:doc-anchors, check:docs-single-h1, check:cli-examples-parity, check:doc-authoring, lint doc gates) after building lint and spec closures under os-verify-lock (VERDICT command-exit 0). NOT MEASURED: pnpm --filter @objectstack/spec run check:skill-examples exit 3, PREREQUISITE NOT MET (needs @objectstack/client-react build; not a finding). dispatch-gates --ran reconciliation: 36 run, 5 UNRUN (the checker-health self-test-only entries; my record carries no exit codes). Path-scheduled CI (Build Docs, Test Core), type-check lanes and 14 changeset-dependent families are CI-owned. No ablation.",
  "mcp_calls": "2 - mcp__github__list_pull_requests (find PR number), mcp__github__issue_read get_comments (verify newest Claim); no write tools",
  "api_writes": "3 - git push (first rejected by pre-push hook, second landed), fleet-write dispatch.mjs pr_create (POST /repos/objectstack-ai/objectstack/pulls, draft, run 36515230175), post-stamped --comment=20538 (this report). No label writes, no PR body edit.",
  "open_questions": [
    {
      "question": "Also changed the one-of-two wording at cli.mdx:766 (command table row for multi-value-columns), which the brief did not name; it stated an incomplete never-applied set. Keep?",
      "options": ["A keep (same never-applied set, one word)", "B revert to keep strictly to the named surface"],
      "recommendation": "A, because leaving 'two' contradicts the row three lines above the new set; smallest reversible edit within the never-applied prose."
    }
  ],
  "out_of_scope_findings": []
}

[objectstack-fleet]

Landed: PR #20563 → dee9b26f6c (single-parent, parent 199002b3e4)

Verified on origin/main by content at 2026-09-29T03:50Z, not by the merge event:

• content/docs/deployment/cli.mdx:868 carries the new unbuildable_index row.
• :855 (the needs_confirm row) now separates manual_column_type_change from the other two never-applied ops: only os migrate multi-value-columns --apply runs it, while manual_widen_varchar_to_text and unbuildable_index are applied by nothing.

PM review (seat domain:devx#1):

• The unbuildable_index claims are anchored in schema-drift.ts (:294, :1970-2020: needs_confirm, error for UNIQUE / warning otherwise) and in sql-driver.ts:13884 (apply returns skipped).
• The first revision put manual_column_type_change under "which nothing applies". That contradicted the page's own os migrate multi-value-columns --apply section. It was sent back and fixed in b982ca1c1b, and the fix was checked against packages/cli/src/commands/migrate/multi-value-columns.ts:105-107.
• The :766 "one of three" edit was accepted as the same never-applied set.

CLI source and the skip-summary wording are untouched (another lane). pm:dispatched removed.

_{PM seat domain:devx#1 · session session_01VDtqoecgES7ScQYGbFVDRv · round 15}

---

Generated by Claude Code