vision: standalone CLI use is a supported front door

[Kiran01bm]

Summary

Broadens the vision's positioning: pg-sprite is GitOps-ready, not GitOps-required.
Standalone CLI use — an engineer with nothing but a DSN — is a supported front door, not a
demo mode. Docs-only.

What

Three edits to docs/vision.md:

• Tagline — adds "and a standalone CLI any engineer can pick up today, no GitOps layer
  required" alongside the SchemaBot execution-layer framing.
• Pillar 2 — new paragraph: the same properties that make the engine drivable by an
  orchestrator (deterministic plans, typed verdicts, bounded locks, idempotent crash-resume,
  no mid-flight operator judgment) make it a safe direct tool without adopting SchemaBot
  first.
• "What go-to means" — new success criterion: an engineer reaches for the pg-sprite CLI
  instead of a raw psql session — for teams without a GitOps layer, and for the urgent
  mid-incident change where bounded locks, a verdict, and crash-resume matter most.

Why

The previous framing measured success exclusively through SchemaBot. That undersells a real
user class: teams that want safe schema changes today without standing up GitOps
orchestration, and operators who must run an urgent change during an incident — exactly when
hand-typed DDL (unbounded locks, no verdict, no resume) is most dangerous. The safe path
should also be the path of least resistance. Nothing in scope changes: SchemaBot remains the
fleet story ("What pg-sprite is not" is untouched); this adds the direct-use audience the
engine already serves by construction.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[aparajon]

🤖 Review requested by Armand and performed by his agent — same two lenses used across this stack (#15, #14, #13, #9, #8, #7, #2): pg-sprite as an OSS-first, best-in-class Postgres DDL tool, and pg-sprite as a clean integration target for an orchestrator. Reviewed at head 6f1b682. No separate adversarial comment on this one — it's sixteen lines of prose with no executable surface, so the correctness pass is "do the claims match the code", and it's folded in below.

This is the right change and it closes the exact gap I raised on #2 — the vision had no standalone user, only an orchestrated one, which quietly made every adoption story depend on adopting something else first. "GitOps-ready, not GitOps-required" is a better line than most projects manage, and the argument behind it is the strong form: the properties that make an engine drivable by a machine are the same ones that make it safe in a human's hands. That's true, non-obvious, and worth leading with.

Claims checked against the code

The new paragraph is the one place in vision.md that speaks in the present tense about capabilities the repo doesn't have yet — which matters more here than anywhere else in the doc, because this is the section whose whole point is the word today. #2 credited the status sweep that put "Enforced today" and "Planned enforcement (Phase N)" markers throughout; this text doesn't carry them.

Checked at this head:

• "gets the full engine (lint, diff, execution)" — migrate does execute, but only the optimistic attempt: AttemptNative under a 3s lock_timeout and a 30s statement_timeout, behind a --max-table-size guard defaulting to 1 GiB. Anything that isn't effectively instant on a table under a gigabyte ends in a refusal verdict, and the concurrent index build from executor: native CREATE INDEX CONCURRENTLY with fail-closed invalid-index recovery #15 isn't wired to a command at all. "The full engine" is roughly a quarter of it right now.
• "idempotent crash-resume" — pkg/checkpoint is marked planned (Phase 8) in SAFETY.md. And status.go's own comment says it plainly: "Phase 1 has no durable migration state", so status is a view over pg_stat_activity that can only see a change while its session is alive.
• "deterministic plans, typed verdicts, bounded locks" — these three are real today, and they're the load-bearing ones.

The sharper point is that the incident framing currently sells the weakest case. An urgent mid-incident change is, almost by definition, the one that isn't instant — add an index on the hot table, backfill a column — which is precisely the shape migrate refuses today. Meanwhile the thing pg-sprite genuinely does better than psql at 3am is already true and not claimed: it refuses in three seconds with a typed reason and a bounded lock, instead of leaving an ACCESS EXCLUSIVE lock sitting on the table for forty minutes because someone pasted an ALTER into a session with no lock_timeout. That's a stronger sentence than "gets the full engine", and it doesn't have to be walked back at any point in Phases 3–8. I'd write the paragraph around what's enforced today and let the phase markers carry the rest — the same discipline the rest of this doc already applies.

OSS lens

1. The audience is added to the document a newcomer reads last. The vision now has a standalone user; the README — the actual front door for someone arriving with a DSN — still doesn't. If standalone use is a supported front door rather than a demo mode, the change that proves it is a quickstart: install, one lint, one diff, one migrate --dry-run, with real output. Sixteen lines in docs/vision.md are a commitment; the README is where it becomes discoverable.

2. Recommending a pre-1.0 tool for incident use is a real decision, worth making deliberately. A tool a team first reaches for during an incident is a tool whose failure modes are discovered during an incident, by someone who has no attention to spare for them. The claim is right eventually and I wouldn't drop it — but I'd order it so day-to-day use comes first and the incident case reads as the payoff once the tool is already trusted, rather than as an entry point. Right now it's the more vivid half of the paragraph, so it's the half people will remember.

3. This raises the bar on every operator-facing message in the stack, and that's worth saying out loud somewhere. An orchestrated user has an operator team, a runbook, and a PR thread between them and a confusing error. A solo engineer with a DSN has the error string. That directly sharpens findings already open on this stack: executor: native CREATE INDEX CONCURRENTLY with fail-closed invalid-index recovery #15's InvalidIndexError hands out a DROP INDEX CONCURRENTLY instruction that isn't always safe to follow, Add pkg/lint: offline typed findings replacing the CLI lint stub #9's lint findings carry no line numbers to jump to, and docs+lint: safer forms are not semantic equivalents #13's advice cites a docs/ path that isn't in the release archive. Each of those is a papercut for an orchestrated user and a dead end for a standalone one. If this PR is the moment standalone use becomes supported, the error-message quality bar moves with it.

Integration lens

4. "GitOps-ready, not GitOps-required" has a design consequence the doc should claim, because it's the thing that will otherwise erode. Supporting both front doors properly means the CLI and an orchestrator consume the same contracts — pkg/plan, pkg/lint, and Add pkg/suggest: advisory safer-form rewrites with typed caveats #14's pkg/suggest — rather than the CLI becoming a thin demo over an API shaped for the orchestrator, or (the more common drift) the orchestrator growing a private path the CLI never exercises. Add pkg/plan: one versioned dry-run report for both front doors #8 already did this right by unifying both front doors onto one report, and that was invisible discipline at the time; this paragraph is the place to name it as policy, so the next person adding a surface knows which way to build it. A concrete version: "every capability is reachable from the CLI, and the CLI consumes the same contracts an orchestrator would."

5. A standalone user needs a place to see what's supported without reading the phase plan. The refusal wall is genuinely good — I probed twenty statement shapes on Phase 2.3-2.4: classifier and router seam #7 and it held — but from the outside it's discovered one unsupported-operation at a time. If the standalone engineer is a first-class user, a supported-operations table in docs/ (or pg-sprite lint --list-codes) is what turns the refusal wall from a wall into a map. That's also the artifact an orchestrator author reads to decide what to route here.

Verified solid

The pillar-2 paragraph sits in the right place and doesn't disturb the SchemaBot framing around it — "What pg-sprite is not" is untouched, and the fleet story still reads as the fleet story rather than being demoted. The new success criterion is measurable in the way the surrounding bullets are ("reaches for the pg-sprite CLI instead of a raw psql session" is an observable behavior, not a feeling), and it correctly ends on "the same engine and the same guarantees as the fleet", which forecloses the two-tier outcome where the standalone path quietly gets a weaker one. The tagline edit keeps the Spirit parallel intact instead of trading it away for the new clause. Docs-only: no code paths touched, and CGO_ENABLED=0 go build ./... passes at this head.

This review was generated by Claude Code (claude-fable-5).

[aparajon]

🤖 Approving on Armand's behalf. My two-lens review and adversarial correctness pass are posted above — the findings there are for follow-up, not fix-before-merge blockers.

This approval was submitted by Claude Code (claude-fable-5) at Armand's direction.

[Kiran01bm]

Review response from Kiran's (@Kiran01bm) AI code review assessment agent (Amp, Claude Opus 4.5)

One-line summary: the two substantive prose findings (present-tense over-claiming, incident framing) are fixed in this PR; the two artifact requests (README quickstart, supported-operations map) are accepted as follow-ups.

#	Finding	Status	Explanation
1	"Full engine" / "idempotent crash-resume" claimed in present tense	fixed	Pillar-2 paragraph rewritten around what's enforced today — bounded lock_timeout on every session, typed refusal in seconds — with copy-and-swap, the checksum gate, and durable resume named as phased capabilities that reach the direct user when they ship.
2	Incident framing sells the weakest case; the true-today claim goes unmade	fixed	The paragraph now leads with the 3-am contrast that is already true (typed refusal vs. a hand-typed ALTER holding ACCESS EXCLUSIVE); the success bullet reorders day-to-day use first, with the incident case as earned trust.
4	"GitOps-ready, not GitOps-required" should claim its design consequence	fixed	Added verbatim as policy: every capability is reachable from the CLI, and the CLI consumes the same plan, verdict, and lint contracts an orchestrator would.
3	README quickstart for the standalone user	deferred	Agreed — the README is the front door and needs install → lint → diff → migrate --dry-run with real output. Tracked as an internal follow-up; kept out of this PR to keep it a vision-only change.
5	Supported-operations map (lint --list-codes or a docs table)	deferred	Agreed — the refusal wall needs a map. Tracked as an internal follow-up alongside the README quickstart.
6	Standalone support raises the error-message bar stack-wide	no action here	Agreed as a principle; the concrete instances cited (#15 InvalidIndexError advice, #9 lint line numbers, #13 docs path) are being addressed on their own PRs.