CLI Forge Data

Optimization: Load the shared invariant contract first, then only the PostgreSQL/SQLx references needed by the requested change.

Language rule: Write user-facing decisions and reports in the project's dominant language. Keep SQL, Rust identifiers, SQLSTATE values, and the mandatory uncertainty marker unchanged.

Forge Data — Safe PostgreSQL and SQLx Changes

Design or implement database changes whose safety comes from explicit invariants, PostgreSQL guarantees, short atomic operations, compatible evolution, and reproducible proof.

Read ../shared/data-invariants.md before acting. Read ../gotchas.md before producing output. Read ../shared/data-invariant-catalog.md when discovering domain rules, and ../shared/postgres-sqlx-patterns.md before writing non-trivial SQL.

Modes

Do not implement in design-only mode. In implementation or correction mode, inspect the existing schema and code before editing; never infer the database solely from Rust structs.

Non-negotiable rules

1. Give every business fact one authoritative owner.
2. Protect persistent invariants in PostgreSQL whenever a declarative guarantee exists.
3. Put every write belonging to one business decision in one explicit transaction.
4. Never perform network I/O while a PostgreSQL transaction is open.
5. Treat zero affected rows as a business result when the command is conditional.
6. Give every retryable command an explicit idempotency protocol.
7. Retry a whole failed transaction, never one middle statement.
8. Use a transactional outbox/inbox protocol for cross-system effects.
9. Design migrations for old code, new code, and mixed-version deployment.
10. Never edit an already-applied migration silently.
11. Include tenant scope in database keys and references, not only query filters.
12. Make derived facts reconstructible or provide auditable detection and repair.
13. Never use SQLite or mocks as proof of PostgreSQL concurrency behavior.
14. Never claim cross-system exactly-once behavior without a demonstrated protocol.

Workflow

1. Inspect existing truth

Inspect relevant migrations, tables, types, constraints, indexes, triggers, functions, views, RLS, extensions, SQLx queries, transaction boundaries, background jobs, messages, external effects, versions, migration runner, deployment order, and incident history.

Proceed with explicit assumptions when information is missing. Stop before destructive or irreversible work whose semantics cannot be safely inferred.

2. Classify scope and criticality

Choose S/M/L/XL from ../shared/tiering.md for output depth and L0-L3 from ../shared/data-invariants.md for proof depth. State both. Bias scope down and criticality up when uncertain.

3. Write the decision and invariants

Complete the database decision, source-of-truth map, invariant matrix, conservation laws, and state transition tables defined in ../shared/data-invariants.md.

For each invariant choose:

• a primary PostgreSQL guarantee;
• defense in depth where useful;
• an audit query and threshold;
• a repair or reconstruction path;
• an executable proof.

Do not accept an invariant enforced only by Rust validation when PostgreSQL can protect it.

4. Break concurrent and failure cases

Write concrete A/B interleavings for every read-before-write flow. Cover duplicate requests, stale writes, lost responses, crash boundaries, retries, old/new binaries, wrong tenant, cancellation, and deadlock or serialization failure.

Prefer, in order:

1. declarative constraint plus atomic DML;
2. INSERT ... ON CONFLICT or conditional UPDATE ... RETURNING;
3. targeted row locking in a short transaction;
4. SERIALIZABLE with bounded whole-transaction retry;
5. advisory locking only with a stable key and shared documented protocol.

5. Select PostgreSQL guarantees

Use named NOT NULL, CHECK, UNIQUE, partial unique indexes, foreign keys, composite tenant keys, exclusion constraints, conditional DML, or outbox/inbox as appropriate.

Choose every ON DELETE and ON UPDATE action. Do not claim a row CHECK protects a multi-row invariant. Justify indexes from real access paths and representative volumes. Use triggers only when their central guarantee outweighs hidden complexity and they are observable and tested.

6. Implement with SQLx

Prefer compile-time checked query!, query_as!, query_scalar!, and query_file! variants. Require explicit columns, bound values, allowlisted dynamic identifiers, justified nullability, RETURNING where it removes a second read, zero-row handling, and error mapping by SQLSTATE and named constraint.

Place the transaction boundary at the business use case and pass the same transaction or connection through participating functions. Do not reacquire from the pool inside the use case. Verify the exact SQLx Executor/Transaction API against the project's pinned version.

7. Evolve the schema compatibly

Classify the migration as additive, compatible transformation, backfill, destructive, locking, rewriting, extension-dependent, or version-incompatible.

For non-trivial changes use:

EXPAND -> MIGRATE -> SWITCH -> CONTRACT

Prove old/old, old/new, new/old, new/new, and old+new/new combinations where deployment overlap exists. Analyze locks, rewrite, disk, replication lag, pool impact, batch size, resumability, interruption recovery, and runner transaction behavior. Contract only after telemetry proves old representations and binaries are gone.

8. Build homeostasis

For critical invariants define audit query, frequency, metric, threshold, owner, dry-run repair, audited repair, and replay path. For eventual consistency define nominal and maximum lag, user-visible degraded behavior, retry limit, failed-item storage, and escalation.

9. Implement the proof ladder

Use the database T0-T4/M0 mapping in ../shared/data-invariants.md.

At minimum run the commands supported by the project version:

cargo fmt --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo sqlx prepare --workspace --check
cargo test --workspace

For L2+, use synchronized transactions against real PostgreSQL. For L3, add property-based or state-model proof, crash-boundary simulation, full replay, and repair testing. Never report a command as successful unless it ran.

10. Pass the done gate

Apply ../shared/done-gate.md: confirm the decision and baseline before editing, keep the change reversible during implementation, and capture reproducible post-verification. Apply ../shared/determinism.md to fixtures, IDs, clocks, retry schedules, and migration data.

Run /cli-audit-data after implementation for L1+ changes or whenever this skill was triggered by a database-safety finding.

Mandatory output

End with:

1. scope tier and data criticality;
2. database decision;
3. sources of truth and invariant matrix;
4. conservation laws and state machine;
5. concurrency and idempotency analysis;
6. PostgreSQL guarantees;
7. SQLx implementation notes;
8. migration compatibility matrix;
9. proof executed and not executed;
10. homeostasis and repair;
11. residual risks and rollback/forward-repair path;
12. every runtime-dependent claim as:

À PROUVER SUR POSTGRESQL RÉEL — ...

When running under cli-cycle, emit .claude/cli-forge-data.json using ../shared/result-schema.md.

Dynamic handoffs

Rule: recommend handoffs; do not execute them automatically outside cli-cycle.

Completion criterion

The change is complete only when its laws are explicit, PostgreSQL protects them as far as possible, concurrent and failure executions have concrete answers, old and new versions can coexist safely, proof is reproducible, and remaining drift is observable and repairable.