prompt request: warn on stored data model changes

[osolmaz]

Motivation

ClawSweeper already has a related guard for config-surface additions in #171. Stored data model changes need the same kind of review visibility.

When a PR changes data stored in SQLite, Postgres, Durable Objects, vector stores, cache databases, migration files, or other persistent schemas, the change may be mechanically correct but still carry upgrade and compatibility risk. Examples include adding or removing columns, changing primary keys or uniqueness, changing serialized JSON shape, changing stored embedding/chunk identity, adding indexes that imply new query semantics, or changing migrations/doctor repair behavior.

These are product and operations decisions, not just code edits. ClawSweeper should make that risk explicit so maintainers can decide whether the migration and compatibility story is acceptable before automerge.

Request

Make ClawSweeper warn when a PR changes a stored data model for SQL or other persistent databases.

This should be both prompt-level and deterministic:

• Prompt-level: update review instructions so stored data model changes are treated as compatibility/upgrade-sensitive and included in review risk analysis.
• Deterministic guard: inspect PR files/patches for likely persistent schema changes and surface a data-model-change warning when detected.
• Persist the result in durable report frontmatter, for example data_model_change: true and, if practical, data_model_surfaces: [...].
• Include the warning in the public review comment when relevant, with enough detail for a maintainer to see what changed.
• For automerge/repair-loop pass reports, prevent a silent normal pass when the change is material and lacks migration/upgrade proof.

Suggested OpenClaw surfaces to cover:

• SQL schema strings and migrations, including CREATE TABLE, ALTER TABLE, DROP TABLE, CREATE INDEX, and ON CONFLICT behavior changes.
• Database helper modules and schema installers.
• Persistent cache schemas.
• Durable Object or other hosted storage schemas.
• Serialized JSON state written to disk or database rows.
• Vector/embedding store schemas and metadata used to decide query compatibility.
• Doctor/migration/repair code that changes or backfills persisted state.
• Docs that add or change a documented persisted schema or migration contract.

Desired review behavior

ClawSweeper should not automatically treat every detected data model change as a defect. The expected behavior is a warning/risk marker that asks for explicit evidence:

• What persisted shape changed?
• Is this new, shipped, or unreleased data?
• Does existing user data migrate automatically?
• Is there a doctor/fix path when automatic migration is not safe?
• Are old rows ignored, backfilled, deleted, or still queryable?
• Does search/query behavior change because rows are now filtered differently?
• Are tests covering both fresh databases and upgraded existing databases?

If the PR includes clear migration and regression proof, the warning can be informational. If the PR changes shipped user data without migration or compatibility proof, ClawSweeper should route it to maintainer review instead of a normal automerge pass.

Acceptance Criteria

• A PR adding/removing/changing a SQL table column triggers a data-model-change warning.
• A PR changing a stored JSON state shape triggers a data-model-change warning.
• A PR changing vector/embedding row identity or query compatibility metadata triggers a data-model-change warning.
• The durable report records data_model_change: true and identifies the likely surfaces.
• Public review comments summarize the data model change without overstating it as a bug.
• Automerge remains possible when the PR has adequate migration/upgrade proof and maintainer policy allows it.
• A material shipped-data change without migration/upgrade proof routes to clawsweeper-verdict:needs-human or the equivalent human-review path.
• Pure query-only refactors and non-semantic documentation wording changes do not trigger the warning.
• Tests cover SQL schema additions, stored JSON shape changes, vector/embedding schema metadata changes, and a negative case.

Related

• prompt request: require maintainer review for config value additions #171
• Example motivating class: OpenClaw memory/index PRs that change stored SQLite chunk or embedding metadata.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed May 29, 2026, 8:35 AM ET / 12:35 UTC.

Summary
Keep open: the request is still necessary because current main has only a generic prompt-level upgrade/schema warning and a deterministic config-surface guard, not a stored-data-model detector or durable data_model_change reporting. It is also maintainer-authored, so repository policy makes it non-closeable without explicit maintainer judgment.

Reproducibility: not applicable. this is a feature request for review automation, not a broken existing behavior report. Source inspection shows the requested deterministic data-model guard is absent on current main.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Include redacted logs or terminal output.

Next step
Queueable if a maintainer wants an implementation PR: the request is detailed, no linked PR owns it, and the closest existing config-surface guard gives a clear pattern.

Review details

Best possible solution:

Add a data-model-change guard parallel to the config-surface guard, with explicit prompt guidance, durable frontmatter, public warning text, automerge pass blocking for material unproven changes, and focused positive and negative tests.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a feature request for review automation, not a broken existing behavior report. Source inspection shows the requested deterministic data-model guard is absent on current main.

Is this the best way to solve the issue?

Yes: implementing this as a warning and human-review/pass-blocking signal is the narrow maintainable path, because the issue explicitly says not every detected data model change should become a defect.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The deterministic detector needs careful false-positive handling so pure query-only refactors and non-semantic documentation wording do not route PRs to human review.
• The requested surfaces span SQL, stored JSON, vector metadata, migrations, and repair code, so path and patch heuristics may need tuning against real OpenClaw PRs.

Codex review notes: model gpt-5.5, reasoning high; reviewed against beb50640445a.

Label changes

Label changes:

• add P2: This is a normal-priority automation safety improvement with clear acceptance criteria and limited repository blast radius.
• add impact:other: The issue concerns maintainer-visible review automation for persistent-schema upgrade risk, which is meaningful but not itself a direct data-loss or runtime failure report.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:queueable-fix: Current issue advisory state selects this label.
• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.

Label justifications:

• P2: This is a normal-priority automation safety improvement with clear acceptance criteria and limited repository blast radius.
• impact:other: The issue concerns maintainer-visible review automation for persistent-schema upgrade risk, which is meaningful but not itself a direct data-loss or runtime failure report.

Evidence reviewed

Acceptance criteria:

• pnpm run test:unit
• pnpm run check

What I checked:

• repository policy: AGENTS.md marks maintainer-authored items as non-closeable, and the GitHub context shows this issue's author association is MEMBER. (AGENTS.md:51, beb50640445a)
• current prompt coverage is generic: The review prompt already treats schemas, migrations, and stored values as upgrade-sensitive, but it does not explicitly define stored data model change detection or durable data_model_change fields. (prompts/review-item.md:323, beb50640445a)
• deterministic guard is config-only: The current deterministic detector is configSurfaceChangeFromContext and only matches OpenClaw config/plugin manifest/docs paths, so SQL, stored JSON, vector metadata, and database schema changes are not covered. (src/clawsweeper.ts:8473, beb50640445a)
• durable report fields are config-only: Generated report frontmatter persists config_surface_change and config_surface_keys, with no corresponding data_model_change or data_model_surfaces fields on current main. (src/clawsweeper.ts:12501, beb50640445a)
• automerge pass blocker is config-only: reviewAutomationMarkersFromReport routes config-surface reports to needs-human and isRepairLoopPassReport excludes configSurfaceReviewRequired, but there is no analogous stored data model check. (src/clawsweeper.ts:11725, beb50640445a)
• related config-surface precedent: The closest existing implementation is commit 9b8e913, which added the config-surface human-review guard and tests for the related request prompt request: require maintainer review for config value additions #171. (test/clawsweeper.test.ts:3240, 9b8e9132e774)

Likely related people:

• osolmaz: Authored the related config-surface guard commit that added deterministic detection, durable frontmatter, automerge routing, and tests for the closest existing review-policy guard. (role: recent area contributor; confidence: high; commits: 9b8e9132e774; files: src/clawsweeper.ts, test/clawsweeper.test.ts)
• Peter Steinberger: Git blame ties the current compatibility/upgrade prompt language and surrounding report frontmatter scaffolding to this contributor, and recent history shows multiple review automation changes in the same area. (role: prompt and report infrastructure contributor; confidence: medium; commits: 8482e5071867, 558017d3, d37dcfb8; files: prompts/review-item.md, src/clawsweeper.ts, test/clawsweeper.test.ts)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.