Skip to content

docs: state "make mistakes hard to commit" as a design principle - #269

Merged
Kiran01bm merged 1 commit into
mainfrom
kiran01bm/docs-hard-to-mistake
Oct 28, 2026
Merged

Kiran01bm merged 1 commit into
mainfrom
kiran01bm/docs-hard-to-mistake

Conversation

@Kiran01bm

Copy link
Copy Markdown
Collaborator

Adds "Make mistakes hard to commit" to the guiding philosophy in docs/design-principles.md and cites it as the source of invariants RF-4 and RF-10.

Why

Several refusals rest on the same idea — a hard-to-undo action needs explicit, specific intent, and the engine refuses when it cannot tell intent from accident — but no principle says so. RF-4 (renames are never guessed) and RF-10 (destructive statements need a typed acknowledgement naming the table, and desired-state execution takes none) enforce it without a shared source, so a proposal such as letting migrate --desired accept --allow-destructive has no principle to be weighed against.

What

  • docs/design-principles.md: a new bullet after "Safety over speed", with the desired-file drop and the per-table acknowledgement as its examples.
  • docs/invariants.md: RF-4 and RF-10 cite the new principle in their Source. No invariant is added; the principle is a value, and RF-4 and RF-10 are its enforced runtime forms.

Before / after

Proposal under review: let migrate --desired accept --allow-destructive public.accounts.

Before                                        After

design-principles.md: "Safety over speed",     design-principles.md: adds "Make mistakes
  "Decisions, not options"                       hard to commit": hard-to-undo actions need
                                                 a typed acknowledgement naming the target,
RF-10 source: declarative review-first           never one inferred or granted broadly
  workflow                                     RF-4 and RF-10 cite it as their source
  → reviewer argues from RF-10's wording          → reviewer can reject the proposal on a
    alone                                           named principle: the acknowledgement
                                                    would approve drops the diff inferred

🤖 Generated with Amp (Claude Opus 4.6)

RF-4 and RF-10 already enforce it; naming the principle gives them a common
source and explains why desired-state execution takes no destructive override.
@Kiran01bm
Kiran01bm marked this pull request as ready for review October 28, 2026 01:25
@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ⚠️ Failed 2026-10-28T01:25:24.205299Z
We couldn’t complete this review. Comment @codex review to try again.
dd79aa3 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

Copy link
Copy Markdown

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

@Kiran01bm
Kiran01bm requested a review from morgo as a code owner October 28, 2026 01:25
@JashLal

JashLal commented Oct 28, 2026

Copy link
Copy Markdown
Collaborator

🤖 Review on Jash's behalf at dd79aa3128de71c1c327b51a6694b99d89603a7b.

Verdict: coherent documentation-only rationale; no actionable defect found in the full diff. The new principle explains explicit, target-specific intent for destructive operations, and RF-4/RF-10 now cite it without changing their invariant text or enforcement references. The desired-state example is consistent with the refusal described in the companion documentation review, rather than claiming this PR adds a new runtime guard.

Verified: inspected both changed files in the full diff, description and available issue comments; the explicit make-mistakes-hard-to-commit anchor matches both new links. No executable code, tests or assertions were removed or changed. Six reported CI checks succeeded, including unit tests/docs guards; six build/runtime/compatibility jobs were skipped. The separate automated Codex review failed due to usage limits. Exact-head surrounding source/AGENTS and inline discussion were not verified because API retrieval was unavailable during this run; no local build or tests ran. Runtime enforcement of the principle is outside the verified scope of this documentation review.

Generated by Codex.

@JashLal

JashLal commented Oct 28, 2026

Copy link
Copy Markdown
Collaborator

🤖 Product review at dd79aa3128de71c1c327b51a6694b99d89603a7b.

OSS adoption: The named principle and concrete omitted-column example make conservative refusal behavior easier to explain. The stable anchor also gives future CLI documentation and proposals a direct reference. No additional UX change is needed for this small documentation patch.

SchemaBot integration: The principle supports preserving explicit operator intent across library callers: an inferred destructive plan should not automatically become an acknowledged operation. This patch changes neither library APIs nor runtime enforcement, and makes no integration behavior newly available. No integration blocker found in the diff.

Generated by Codex.

@JashLal JashLal left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Approving on Jash’s behalf after the documentation review at dd79aa3. No actionable defect found in the full diff. Exact-head surrounding source and inline discussion were unavailable; no local build or tests ran, and runtime enforcement was not independently verified. Generated by Codex.

@Kiran01bm

Copy link
Copy Markdown
Collaborator Author

🤖 Adversarial review response — created by Kiran's code review agent (Amp, Claude Opus 4.6) — pull/269

No findings were raised, so nothing changes; the one verification gap, runtime enforcement of the principle, is closed below.

# Finding Status Explanation
C1 Runtime enforcement of the principle was outside the verified scope no action The PR cites the principle from invariants that are already enforced and tested; it adds no new guarantee. RF-10's Enforced line names the gate (destructiveOperations, checkAllowDestructiveAck, RunDesired's ErrAllowDestructiveNotSupported) and its tests (TestRunRefusesAnUnacknowledgedDropColumn, TestRunRejectsAMismatchedDestructiveAcknowledgement, and others); internal/cli/migrate_desired.go rejects --allow-destructive with --desired. RF-4's rename refusal is pinned by TestClassifyRejectsARename*.
C2 No API or runtime change, no integration blocker no action Confirmation; documentation only.

The "Verified" notes in C1 and the approval in review 5676806947 need no action.

Source: block/pg-sprite#269, review comments 6458497089 and 6458499619 and review 5676806947 at head dd79aa31

@Kiran01bm
Kiran01bm merged commit e876e9f into main Oct 28, 2026
12 checks passed
@Kiran01bm
Kiran01bm deleted the kiran01bm/docs-hard-to-mistake branch October 28, 2026 02:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants