hatch3r 1.7.1 → 1.8.0

package/rules/hatch3r-i18n.md

@@ -93,3 +93,16 @@ ICU MessageFormat 2.0 reached Final Candidate status in CLDR 46.1 (January 2025)
 - **Migration strategy:** New translation keys should use MF2 syntax. Existing MF1 keys can be migrated incrementally — both syntaxes can coexist during transition.
 - **Tooling:** Verify that your translation management system (TMS) supports MF2 syntax before migrating. Test with a small key set first.
 - **Stability:** The MF2 specification has stability guarantees post-approval (mid-2025). Syntax and semantics will not change incompatibly after that point.
+
+## Microcopy and Tone
+
+Translation strings are user-facing copy — write them as product copy, not as technical labels.
+
+- Use plain language. Default to second person ("you", "your") for end-user surfaces.
+- Use a corrective verb in error messages: "Try again", "Reconnect", "Enter a valid email" — not "Error" or "Oops".
+- Never expose to end users: protocol acronyms ("FIDO2", "WebAuthn"), raw HTTP status codes ("500", "401"), language sentinel values (`null`, `undefined`), or internal record/ID strings. Translate these into a user-visible cause + recovery.
+- CTA labels are action-oriented and specific: "Save changes" beats "Submit"; "Delete project" beats "Confirm"; "Send invite" beats "OK".
+- Error tone explains the cause and offers a recovery path. Do not blame the user. Replace "You entered an invalid value" with "This field needs a valid email address — for example, name@example.com".
+- Use ICU MessageFormat (1.0 or 2.0 per the MF2 section above) for every plural, gender, and select pattern. Never concatenate translated fragments to build a sentence — each complete sentence is a single translation key with its own placeholders.
+- Tone source-of-truth: the GOV.UK Design System content style guide (https://design-system.service.gov.uk/styles/) and IBM Carbon Design System voice and tone guidance (https://carbondesignsystem.com/guidelines/content/general/) — cite both when reviewing tone or training a translator.
+- Cross-reference `rules/hatch3r-ux-states-and-flows.md` Microcopy subsection for the state-driven copy patterns (loading, empty, error, partial) that share this tone contract.

package/rules/hatch3r-i18n.mdc

@@ -88,3 +88,16 @@ ICU MessageFormat 2.0 reached Final Candidate status in CLDR 46.1 (January 2025)
 - **Migration strategy:** New translation keys should use MF2 syntax. Existing MF1 keys can be migrated incrementally — both syntaxes can coexist during transition.
 - **Tooling:** Verify that your translation management system (TMS) supports MF2 syntax before migrating. Test with a small key set first.
 - **Stability:** The MF2 specification has stability guarantees post-approval (mid-2025). Syntax and semantics will not change incompatibly after that point.
+
+## Microcopy and Tone
+
+Translation strings are user-facing copy — write them as product copy, not as technical labels.
+
+- Use plain language. Default to second person ("you", "your") for end-user surfaces.
+- Use a corrective verb in error messages: "Try again", "Reconnect", "Enter a valid email" — not "Error" or "Oops".
+- Never expose to end users: protocol acronyms ("FIDO2", "WebAuthn"), raw HTTP status codes ("500", "401"), language sentinel values (`null`, `undefined`), or internal record/ID strings. Translate these into a user-visible cause + recovery.
+- CTA labels are action-oriented and specific: "Save changes" beats "Submit"; "Delete project" beats "Confirm"; "Send invite" beats "OK".
+- Error tone explains the cause and offers a recovery path. Do not blame the user. Replace "You entered an invalid value" with "This field needs a valid email address — for example, name@example.com".
+- Use ICU MessageFormat (1.0 or 2.0 per the MF2 section above) for every plural, gender, and select pattern. Never concatenate translated fragments to build a sentence — each complete sentence is a single translation key with its own placeholders.
+- Tone source-of-truth: the GOV.UK Design System content style guide (https://design-system.service.gov.uk/styles/) and IBM Carbon Design System voice and tone guidance (https://carbondesignsystem.com/guidelines/content/general/) — cite both when reviewing tone or training a translator.
+- Cross-reference `rules/hatch3r-ux-states-and-flows.md` Microcopy subsection for the state-driven copy patterns (loading, empty, error, partial) that share this tone contract.

package/rules/hatch3r-iteration-summary.md

@@ -67,6 +67,8 @@ Append only when they carry information. Do not include empty headers.
 **Suggested Next Action:** {one line}
 ```
 
+The **End-of-Turn Delegation Attestation** (defined in `hatch3r-agent-orchestration` -> End-of-Turn Delegation Attestation) is conditionally required and appears immediately BEFORE this Iteration Summary block. It applies when the turn is on a Tier >= 2 tracked task AND caused at least one file mutation. The Iteration Summary's 5-field contract is unchanged — the Attestation lives in a separate block to preserve backward compatibility for the 15 adapter outputs.
+
 ## Field Semantics
 
 - **Outcome** is one sentence. The user should grasp what happened from this line alone.

package/rules/hatch3r-iteration-summary.mdc

@@ -62,6 +62,8 @@ Append only when they carry information. Do not include empty headers.
 **Suggested Next Action:** {one line}
 ```
 
+The **End-of-Turn Delegation Attestation** (defined in `hatch3r-agent-orchestration` -> End-of-Turn Delegation Attestation) is conditionally required and appears immediately BEFORE this Iteration Summary block. It applies when the turn is on a Tier >= 2 tracked task AND caused at least one file mutation. The Iteration Summary's 5-field contract is unchanged — the Attestation lives in a separate block to preserve backward compatibility for the 15 adapter outputs.
+
 ## Field Semantics
 
 - **Outcome** is one sentence. The user should grasp what happened from this line alone.

package/rules/hatch3r-migrations.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-migrations
 type: rule
-description: Database migration and schema change patterns for the project
+description: Database migration and schema change patterns — expand-contract, online DDL, backfills, compatibility windows, reversibility, multi-region, tooling
 scope: "**/migrations/**,**/*migration*,**/migrate/**,**/seeds/**,**/seeders/**,**/prisma/migrations/**,**/drizzle/**,**/knex/**"
 tags: [implementation, brownfield]
 quality_charter: agents/shared/quality-charter.md
@@ -9,23 +9,68 @@ cache_friendly: true
 ---
 # Migrations
 
-- Schema changes must be backward-compatible. Add fields with defaults; never remove or rename without migration.
 - Migration scripts live in a dedicated `migrations/` directory. One script per migration.
-- Every migration is idempotent. Safe to re-run. Use document version or `migratedAt` to skip.
-- Migration functions log progress and are resumable. Handle partial failures.
-- Test migrations against emulator or staging before deploying. Verify data integrity.
-- Order: deploy new code (handles old + new schema) → run migration → remove old schema handling.
-- Document schema changes in project data model spec.
-- Rollback plan required for every migration. Never run destructive migrations without backup verification.
-- Hot documents must stay within size limits after migration.
+- Every migration is idempotent (re-running produces the same result). Use a version column, `migratedAt` timestamp, or migration ledger row to skip already-applied work.
+- Test every migration against an emulator or staging dataset before production. Verify data integrity after each step, not just at the end.
+- Document the schema change in the project data model spec. Hot documents must stay within size limits after migration.
 
-## Data Validation During Migration
+## Expand-Contract Pattern (mandatory for non-trivial schema changes)
 
-- Validate data integrity after each migration step, not just at the end. Check that migrated records match the expected schema, required fields are populated, and no data was silently dropped.
-- Include count checks: the number of records processed should match the number of records in the source collection. Log discrepancies as errors, not warnings.
-- For large datasets, migrate in batches with progress checkpoints. If a batch fails, resume from the last checkpoint rather than restarting the entire migration.
+Non-trivial = anything beyond pure-additive nullable columns on small tables, or any rename/drop/type-change. Use a 3-deploy cadence; split Migrate into two deploys when dual-write is required (4 deploys total).
 
-## Migration Coordination in Multi-Service Environments
+1. **Deploy 1 — Expand.** Add new column nullable, add new table, or `CREATE INDEX CONCURRENTLY`. Add new constraints with `NOT VALID` first. Old code paths still work. No app behavior change in this deploy.
+2. **Deploy 2 — Migrate (backfill + dual-write).** Run a batched, idempotent, resumable backfill job. If the change is a column rename / type swap, app code writes to both old and new columns during this phase. Validate row counts and per-block checksums on the new shape before proceeding.
+3. **Deploy 3 — Contract.** Switch reads to the new shape (feature-flag-gated; flip is the rollback). Drop the old column, old table, or old index. Wait at least one full release cycle plus one on-call rotation between Expand and Contract — old code must remain executable to roll back inside the deploy window.
 
-- When a migration affects shared data (e.g., a schema used by multiple services), coordinate the migration order across services. The consuming services must be deployed with backward-compatible readers before the migration runs.
-- Never assume that all service instances will be running the same code version during a migration window. Design migrations to tolerate mixed-version reads and writes during the rollout period.
+Hard rules: never rename a column in a single step; never add a `NOT NULL` column to a populated table without a default or a deferred `SET NOT NULL NOT VALID` → `VALIDATE`; every phase must be valid in isolation so that any deploy is independently rollbackable.
+
+## Online Schema Changes
+
+Set `lock_timeout` and `statement_timeout` before every DDL statement to bound blast radius. Selection by engine:
+
+- **Postgres 18.x.** Use `CREATE INDEX CONCURRENTLY` (outside any transaction block — disable the migration tool's transaction wrapper). On failure, the index is left `INVALID`; emit a `DROP INDEX IF EXISTS` + retry step. For FK and CHECK constraints, use `ALTER TABLE ... ADD CONSTRAINT ... NOT VALID` followed later by `VALIDATE CONSTRAINT` (skips full scan, downgrades to `SHARE UPDATE EXCLUSIVE`). Postgres 18 also supports `SET NOT NULL NOT VALID` for column nullability. Use `pg_repack` 1.5.x for bloat removal instead of `VACUUM FULL`. Avoid `ALTER TABLE ... ADD COLUMN ... DEFAULT non_constant_expression` on large tables — it rewrites every row.
+- **MySQL 8.4 LTS.** `ALGORITHM=INSTANT` is the default for many metadata ops (ADD COLUMN at end, RENAME COLUMN, some index meta) — verify against the 8.4 online DDL operations matrix. Hard limit: 64 row versions per table in 8.4. When `INSTANT` is rejected, fall back to `ALGORITHM=INPLACE`. For `ALGORITHM=COPY` operations on large tables, use `gh-ost` v1.1.8 (trigger-free, binlog-based, checkpoint + resume + revert) when the table has no incoming FKs and the cluster is not Galera / Percona XtraDB. Use `pt-online-schema-change` when FKs are present (`--alter-foreign-keys-method`) or under Galera. `lhm` is unmaintained — do not propose it for new code.
+
+## Backfill Jobs
+
+Every backfill must be batched, idempotent, resumable, throttled, and observable.
+
+- **Batched.** Order by PK or a monotonic key. Chunk by `id BETWEEN ? AND ?` (range), not `LIMIT/OFFSET` — offsets drift under concurrent writes. Default chunk 1k–10k rows; tune by table width.
+- **Idempotent.** Write `UPDATE ... SET new = f(old) WHERE id = ? AND new IS NULL` (or upsert with a deterministic source-derived value). Re-running on the same range must produce the same final state.
+- **Resumable.** Persist the last-processed boundary (`last_id` or timestamp cursor) to a control table after each batch commit. Resume from the checkpoint on restart; never restart from zero on partial failure.
+- **Throttled.** Poll replication lag (`pg_stat_replication`, `SHOW REPLICA STATUS`) between batches; pause when lag exceeds 30 seconds or the SLO threshold. Cap concurrency at the IO budget of the slowest replica.
+- **Observable.** Emit `migration.backfill.rows_processed` (counter), `migration.backfill.error_rate` (counter), `migration.backfill.eta_seconds` (gauge), and `migration.backfill.current_boundary` (gauge). Wire dashboards before launch. Avoid single mega-DML — one `UPDATE` over 50M+ rows produces multi-hour locks and table bloat.
+
+## Compatibility Window
+
+Schema changes deploy before the code that depends on them when widening (add column, add table, add index). Schema changes deploy after the code that no longer depends on them when narrowing (drop column, drop table). During the window, app code reads both shapes — the new shape if populated, fall back to the old shape otherwise. Rollback compatibility (old code remains executable against the current schema) must hold for at least 1 full release cycle plus 1 on-call rotation — minimum 7 calendar days, longer when the on-call rotation is longer.
+
+## Reversibility
+
+Every migration ships a tested down-migration script. Forward-only migrations are permitted only when the operation is data-destructive (e.g., a `DROP COLUMN` after Contract) — these require an explicit `IRREVERSIBLE: <reason>` annotation in the migration header and reviewer sign-off. A compensating forward migration that restores the prior shape is acceptable in place of a down-script for tools that lack reversibility (Prisma Migrate, Drizzle Kit — surface the gap to the reviewer). Default for every migration: reversible.
+
+## Data Integrity Verification
+
+Apply layered verification from cheapest to most thorough; stop at the cheapest layer that detects no drift.
+
+1. **Pre-migration backup drill.** Full restore to staging plus a smoke query within 24 hours prior to a destructive migration. "Backup exists" is not verification.
+2. **Row-count parity per chunk.** Source rows processed equals target rows written. Log discrepancies as errors, not warnings.
+3. **Aggregate checks.** SUM, MIN, MAX, COUNT(DISTINCT) on numeric and date columns per partition or batch.
+4. **Per-block checksums.** SHA-256 or MD5 over concatenated key columns for blocks of N rows (e.g., `md5(string_agg(id::text || col::text, ',' ORDER BY id))`).
+5. **Cross-system diff.** Datafold Reconcile, dbt-data-diff, or a hand-rolled sample-then-drill comparison for value-level differences.
+6. **Canary dual-read.** Read both shapes in production for 24–72 hours before cutover; shadow-diff and alert on mismatch.
+7. **Reconciliation control table.** Per-batch row count plus checksum stored alongside the checkpoint; auto-stop the backfill on drift above the configured threshold.
+
+## Multi-Region & Replica Lag
+
+- Pause backfill writes when any replica lag exceeds 30 seconds (or the project's lag SLO, whichever is lower). Resume only after lag returns to baseline for 5 consecutive minutes.
+- Roll migrations across regions sequentially; never alter an active partition during the peak traffic window of any region.
+- FK validation (`VALIDATE CONSTRAINT`) reads the entire dependent table — schedule outside peak read windows on replica-heavy topologies.
+- For Postgres major-version upgrades, use native logical replication (PG17+ preserves slots through `pg_upgrade`); advance sequences manually at cutover — logical replication does not replicate sequences, DDL, or large objects.
+- For ongoing cross-system replication, prefer Debezium (when Kafka is already deployed) or AWS DMS (managed, AWS-native). DMS hard limit: 200 tasks per replication instance — relevant for schema-per-tenant designs.
+
+## Tooling Mandate
+
+Pick one schema-management tool per project and commit the schema declaration to the repo. Greenfield default: Atlas (50+ destructive/locking linters, auto-generated down migrations, GitHub Actions approval policies) or dbmate (plain-SQL portability with first-class `-- migrate:down`). Existing-project default: whatever already ships migrations in the repo. Acceptable tools: Atlas, Prisma Migrate (forward-only — surface to reviewer), Drizzle Kit (forward-only — surface), Flyway 11+, Liquibase 4.27+ Pro, sqitch, Alembic, Knex, dbmate, Bytebase. Run a migration linter in CI — Atlas analyze, `squawk` for raw Postgres SQL — fail the PR on destructive operations without an explicit `IRREVERSIBLE:` annotation.
+
+Cross-references: see `hatch3r-data-classification` (PII / encrypted-column migration requirements), `hatch3r-feature-flags` (read-path switchover gating), `hatch3r-observability-metrics` (backfill progress metrics).

package/rules/hatch3r-migrations.mdc

@@ -1,27 +1,72 @@
 ---
-description: Database migration and schema change patterns for the project
+description: Database migration and schema change patterns — expand-contract, online DDL, backfills, compatibility windows, reversibility, multi-region, tooling
 globs: ["**/migrations/**", "**/*migration*", "**/migrate/**", "**/seeds/**", "**/seeders/**", "**/prisma/migrations/**", "**/drizzle/**", "**/knex/**"]
 alwaysApply: false
 ---
 # Migrations
 
-- Schema changes must be backward-compatible. Add fields with defaults; never remove or rename without migration.
 - Migration scripts live in a dedicated `migrations/` directory. One script per migration.
-- Every migration is idempotent. Safe to re-run. Use document version or `migratedAt` to skip.
-- Migration functions log progress and are resumable. Handle partial failures.
-- Test migrations against emulator or staging before deploying. Verify data integrity.
-- Order: deploy new code (handles old + new schema) → run migration → remove old schema handling.
-- Document schema changes in project data model spec.
-- Rollback plan required for every migration. Never run destructive migrations without backup verification.
-- Hot documents must stay within size limits after migration.
+- Every migration is idempotent (re-running produces the same result). Use a version column, `migratedAt` timestamp, or migration ledger row to skip already-applied work.
+- Test every migration against an emulator or staging dataset before production. Verify data integrity after each step, not just at the end.
+- Document the schema change in the project data model spec. Hot documents must stay within size limits after migration.
 
-## Data Validation During Migration
+## Expand-Contract Pattern (mandatory for non-trivial schema changes)
 
-- Validate data integrity after each migration step, not just at the end. Check that migrated records match the expected schema, required fields are populated, and no data was silently dropped.
-- Include count checks: the number of records processed should match the number of records in the source collection. Log discrepancies as errors, not warnings.
-- For large datasets, migrate in batches with progress checkpoints. If a batch fails, resume from the last checkpoint rather than restarting the entire migration.
+Non-trivial = anything beyond pure-additive nullable columns on small tables, or any rename/drop/type-change. Use a 3-deploy cadence; split Migrate into two deploys when dual-write is required (4 deploys total).
 
-## Migration Coordination in Multi-Service Environments
+1. **Deploy 1 — Expand.** Add new column nullable, add new table, or `CREATE INDEX CONCURRENTLY`. Add new constraints with `NOT VALID` first. Old code paths still work. No app behavior change in this deploy.
+2. **Deploy 2 — Migrate (backfill + dual-write).** Run a batched, idempotent, resumable backfill job. If the change is a column rename / type swap, app code writes to both old and new columns during this phase. Validate row counts and per-block checksums on the new shape before proceeding.
+3. **Deploy 3 — Contract.** Switch reads to the new shape (feature-flag-gated; flip is the rollback). Drop the old column, old table, or old index. Wait at least one full release cycle plus one on-call rotation between Expand and Contract — old code must remain executable to roll back inside the deploy window.
 
-- When a migration affects shared data (e.g., a schema used by multiple services), coordinate the migration order across services. The consuming services must be deployed with backward-compatible readers before the migration runs.
-- Never assume that all service instances will be running the same code version during a migration window. Design migrations to tolerate mixed-version reads and writes during the rollout period.
+Hard rules: never rename a column in a single step; never add a `NOT NULL` column to a populated table without a default or a deferred `SET NOT NULL NOT VALID` → `VALIDATE`; every phase must be valid in isolation so that any deploy is independently rollbackable.
+
+## Online Schema Changes
+
+Set `lock_timeout` and `statement_timeout` before every DDL statement to bound blast radius. Selection by engine:
+
+- **Postgres 18.x.** Use `CREATE INDEX CONCURRENTLY` (outside any transaction block — disable the migration tool's transaction wrapper). On failure, the index is left `INVALID`; emit a `DROP INDEX IF EXISTS` + retry step. For FK and CHECK constraints, use `ALTER TABLE ... ADD CONSTRAINT ... NOT VALID` followed later by `VALIDATE CONSTRAINT` (skips full scan, downgrades to `SHARE UPDATE EXCLUSIVE`). Postgres 18 also supports `SET NOT NULL NOT VALID` for column nullability. Use `pg_repack` 1.5.x for bloat removal instead of `VACUUM FULL`. Avoid `ALTER TABLE ... ADD COLUMN ... DEFAULT non_constant_expression` on large tables — it rewrites every row.
+- **MySQL 8.4 LTS.** `ALGORITHM=INSTANT` is the default for many metadata ops (ADD COLUMN at end, RENAME COLUMN, some index meta) — verify against the 8.4 online DDL operations matrix. Hard limit: 64 row versions per table in 8.4. When `INSTANT` is rejected, fall back to `ALGORITHM=INPLACE`. For `ALGORITHM=COPY` operations on large tables, use `gh-ost` v1.1.8 (trigger-free, binlog-based, checkpoint + resume + revert) when the table has no incoming FKs and the cluster is not Galera / Percona XtraDB. Use `pt-online-schema-change` when FKs are present (`--alter-foreign-keys-method`) or under Galera. `lhm` is unmaintained — do not propose it for new code.
+
+## Backfill Jobs
+
+Every backfill must be batched, idempotent, resumable, throttled, and observable.
+
+- **Batched.** Order by PK or a monotonic key. Chunk by `id BETWEEN ? AND ?` (range), not `LIMIT/OFFSET` — offsets drift under concurrent writes. Default chunk 1k–10k rows; tune by table width.
+- **Idempotent.** Write `UPDATE ... SET new = f(old) WHERE id = ? AND new IS NULL` (or upsert with a deterministic source-derived value). Re-running on the same range must produce the same final state.
+- **Resumable.** Persist the last-processed boundary (`last_id` or timestamp cursor) to a control table after each batch commit. Resume from the checkpoint on restart; never restart from zero on partial failure.
+- **Throttled.** Poll replication lag (`pg_stat_replication`, `SHOW REPLICA STATUS`) between batches; pause when lag exceeds 30 seconds or the SLO threshold. Cap concurrency at the IO budget of the slowest replica.
+- **Observable.** Emit `migration.backfill.rows_processed` (counter), `migration.backfill.error_rate` (counter), `migration.backfill.eta_seconds` (gauge), and `migration.backfill.current_boundary` (gauge). Wire dashboards before launch. Avoid single mega-DML — one `UPDATE` over 50M+ rows produces multi-hour locks and table bloat.
+
+## Compatibility Window
+
+Schema changes deploy before the code that depends on them when widening (add column, add table, add index). Schema changes deploy after the code that no longer depends on them when narrowing (drop column, drop table). During the window, app code reads both shapes — the new shape if populated, fall back to the old shape otherwise. Rollback compatibility (old code remains executable against the current schema) must hold for at least 1 full release cycle plus 1 on-call rotation — minimum 7 calendar days, longer when the on-call rotation is longer.
+
+## Reversibility
+
+Every migration ships a tested down-migration script. Forward-only migrations are permitted only when the operation is data-destructive (e.g., a `DROP COLUMN` after Contract) — these require an explicit `IRREVERSIBLE: <reason>` annotation in the migration header and reviewer sign-off. A compensating forward migration that restores the prior shape is acceptable in place of a down-script for tools that lack reversibility (Prisma Migrate, Drizzle Kit — surface the gap to the reviewer). Default for every migration: reversible.
+
+## Data Integrity Verification
+
+Apply layered verification from cheapest to most thorough; stop at the cheapest layer that detects no drift.
+
+1. **Pre-migration backup drill.** Full restore to staging plus a smoke query within 24 hours prior to a destructive migration. "Backup exists" is not verification.
+2. **Row-count parity per chunk.** Source rows processed equals target rows written. Log discrepancies as errors, not warnings.
+3. **Aggregate checks.** SUM, MIN, MAX, COUNT(DISTINCT) on numeric and date columns per partition or batch.
+4. **Per-block checksums.** SHA-256 or MD5 over concatenated key columns for blocks of N rows (e.g., `md5(string_agg(id::text || col::text, ',' ORDER BY id))`).
+5. **Cross-system diff.** Datafold Reconcile, dbt-data-diff, or a hand-rolled sample-then-drill comparison for value-level differences.
+6. **Canary dual-read.** Read both shapes in production for 24–72 hours before cutover; shadow-diff and alert on mismatch.
+7. **Reconciliation control table.** Per-batch row count plus checksum stored alongside the checkpoint; auto-stop the backfill on drift above the configured threshold.
+
+## Multi-Region & Replica Lag
+
+- Pause backfill writes when any replica lag exceeds 30 seconds (or the project's lag SLO, whichever is lower). Resume only after lag returns to baseline for 5 consecutive minutes.
+- Roll migrations across regions sequentially; never alter an active partition during the peak traffic window of any region.
+- FK validation (`VALIDATE CONSTRAINT`) reads the entire dependent table — schedule outside peak read windows on replica-heavy topologies.
+- For Postgres major-version upgrades, use native logical replication (PG17+ preserves slots through `pg_upgrade`); advance sequences manually at cutover — logical replication does not replicate sequences, DDL, or large objects.
+- For ongoing cross-system replication, prefer Debezium (when Kafka is already deployed) or AWS DMS (managed, AWS-native). DMS hard limit: 200 tasks per replication instance — relevant for schema-per-tenant designs.
+
+## Tooling Mandate
+
+Pick one schema-management tool per project and commit the schema declaration to the repo. Greenfield default: Atlas (50+ destructive/locking linters, auto-generated down migrations, GitHub Actions approval policies) or dbmate (plain-SQL portability with first-class `-- migrate:down`). Existing-project default: whatever already ships migrations in the repo. Acceptable tools: Atlas, Prisma Migrate (forward-only — surface to reviewer), Drizzle Kit (forward-only — surface), Flyway 11+, Liquibase 4.27+ Pro, sqitch, Alembic, Knex, dbmate, Bytebase. Run a migration linter in CI — Atlas analyze, `squawk` for raw Postgres SQL — fail the PR on destructive operations without an explicit `IRREVERSIBLE:` annotation.
+
+Cross-references: see `hatch3r-data-classification` (PII / encrypted-column migration requirements), `hatch3r-feature-flags` (read-path switchover gating), `hatch3r-observability-metrics` (backfill progress metrics).

package/rules/hatch3r-observability-logging.md

@@ -3,7 +3,7 @@ id: hatch3r-observability-logging
 type: rule
 description: Structured logging and error reporting conventions for the project
 scope: conditional
-globs: "**/*log*,**/*logger*,**/*logging*,**/*error*,**/observability/**"
+globs: "**/*log*,**/*logger*,**/*logging*,**/*error*,**/observability/**,**/routes/**,**/handlers/**,**/services/**,**/api/**,**/middleware/**,**/controllers/**,**/lib/**"
 tags: [devops]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true

package/rules/hatch3r-observability-logging.mdc

@@ -1,6 +1,6 @@
 ---
 description: Structured logging and error reporting conventions for the project
-globs: ["**/*log*", "**/*logger*", "**/*logging*", "**/*error*", "**/observability/**"]
+globs: ["**/*log*", "**/*logger*", "**/*logging*", "**/*error*", "**/observability/**", "**/routes/**", "**/handlers/**", "**/services/**", "**/api/**", "**/middleware/**", "**/controllers/**", "**/lib/**"]
 alwaysApply: false
 ---
 # Observability -- Logging & Error Reporting

package/rules/hatch3r-observability-metrics.md

@@ -3,7 +3,7 @@ id: hatch3r-observability-metrics
 type: rule
 description: Metrics, SLO/SLI definitions, alerting, and dashboard conventions for the project
 scope: conditional
-globs: "**/*metric*,**/*slo*,**/*sli*,**/*alert*,**/*dashboard*,**/observability/**"
+globs: "**/*metric*,**/*slo*,**/*sli*,**/*alert*,**/*dashboard*,**/observability/**,**/routes/**,**/handlers/**,**/services/**,**/api/**,**/middleware/**,**/controllers/**,**/lib/**"
 tags: [devops]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true

package/rules/hatch3r-observability-metrics.mdc

@@ -1,6 +1,6 @@
 ---
 description: Metrics, SLO/SLI definitions, alerting, and dashboard conventions for the project
-globs: ["**/*metric*", "**/*slo*", "**/*sli*", "**/*alert*", "**/*dashboard*", "**/observability/**"]
+globs: ["**/*metric*", "**/*slo*", "**/*sli*", "**/*alert*", "**/*dashboard*", "**/observability/**", "**/routes/**", "**/handlers/**", "**/services/**", "**/api/**", "**/middleware/**", "**/controllers/**", "**/lib/**"]
 alwaysApply: false
 ---
 # Observability -- Metrics, SLOs & Alerting

package/rules/hatch3r-observability-tracing-detail.md

@@ -1,161 +1,20 @@
 ---
 id: hatch3r-observability-tracing-detail
 type: rule
-description: Extended tracing reference -- AI agent instrumentation, tool call audit trails, LLM request tracing, and correlation ID patterns
+description: "[Deprecated] AI agent tracing detail rule -- consolidated into hatch3r-observability-tracing's AI Agent Instrumentation section"
 scope: conditional
-globs: "**/*trac*,**/*span*,**/*telemetry*,**/*otel*,**/*agent*,**/observability/**"
+globs: "**/*trac*,**/*span*,**/*telemetry*,**/*otel*,**/*agent*,**/observability/**,**/routes/**,**/handlers/**,**/services/**,**/api/**,**/middleware/**,**/controllers/**,**/lib/**"
 tags: [devops]
 quality_charter: agents/shared/quality-charter.md
+deprecated: true
 cache_friendly: true
 ---
-# Observability -- Tracing Extended Reference
+# Observability -- Tracing Extended Reference (Deprecated Redirect)
 
-On-demand companion to `hatch3r-observability-tracing`. Load when instrumenting AI agent systems, implementing tool call audit trails, or setting up correlation IDs for multi-agent workflows.
+This rule has been merged into `hatch3r-observability-tracing`. Load that rule for AI agent instrumentation, tool call spans, LLM request/response tracing, tool call audit trails, and correlation ID patterns.
 
-## GenAI Span Attributes
+- See `hatch3r-observability-tracing` § "AI Agent Instrumentation" for: GenAI span attributes, agent invocation spans, tool call spans, LLM request/response tracing, tool call audit trail, correlation IDs for agent workflows.
 
-Use these attributes on all spans representing interactions with generative AI models:
+<!-- DEPRECATED-CONTENT-REMOVED -->
 
-| Attribute | Type | Description | Example |
-|-----------|------|-------------|---------|
-| `gen_ai.system` | string | GenAI provider system name | `openai`, `anthropic`, `azure_openai` |
-| `gen_ai.request.model` | string | Model name as specified in the request | `gpt-4o`, `claude-sonnet-4-20250514` |
-| `gen_ai.response.model` | string | Model name as returned in the response | `gpt-4o-2024-08-06` |
-| `gen_ai.request.max_tokens` | int | Maximum tokens requested for generation | `4096` |
-| `gen_ai.request.temperature` | float | Temperature parameter | `0.7` |
-| `gen_ai.response.finish_reasons` | string[] | Reasons the model stopped generating | `["stop"]`, `["length"]` |
-| `gen_ai.usage.input_tokens` | int | Tokens in the input/prompt | `1250` |
-| `gen_ai.usage.output_tokens` | int | Tokens in the generated output | `530` |
-
-- Always set `gen_ai.system` and `gen_ai.request.model` on every GenAI span.
-- Record `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens` from the API response for cost dashboards.
-- Use `gen_ai.response.finish_reasons` to detect truncated outputs (`length`) and trigger re-prompting.
-
-## Agent Invocation Spans
-
-Instrument the full lifecycle of an agent invocation with a dedicated span. This span is the parent for all LLM calls, tool executions, and sub-agent delegations.
-
-- **Span name pattern:** `agent.{agent_name}.invoke`
-- **Required attributes:** `agent.id`, `agent.name`, `agent.parent_id`, `agent.task`, `agent.framework`
-- **Span events for state transitions:** `agent.planning`, `agent.tool_selection`, `agent.awaiting_human`, `agent.delegating`, `agent.completed`, `agent.error`
-
-```typescript
-const agentSpan = tracer.startSpan('agent.code_reviewer.invoke', {
-  attributes: {
-    'agent.id': invocationId,
-    'agent.name': 'code_reviewer',
-    'agent.parent_id': parentAgentId ?? '',
-    'agent.task': `review PR #${prNumber}`,
-    'agent.framework': 'custom',
-  },
-});
-agentSpan.addEvent('agent.planning');
-// ... agent reasoning and tool calls happen as child spans ...
-agentSpan.addEvent('agent.completed');
-agentSpan.end();
-```
-
-## Tool Call Spans
-
-Every tool invocation by an agent creates a child span of the agent invocation span.
-
-- **Span name pattern:** `tool.{tool_name}.execute`
-- **Required attributes:** `tool.name`, `tool.input_hash` (SHA-256), `tool.output_status`, `tool.duration_ms`, `tool.parameters_count`
-- Tool spans must be children of the invoking agent span. Set span status to `ERROR` when `tool.output_status` is `error` or `timeout`.
-- For tools performing I/O, create nested child spans using appropriate semantic conventions (`http.*`, `db.*`).
-
-```typescript
-const toolSpan = tracer.startSpan(
-  'tool.git_diff.execute',
-  { attributes: { 'tool.name': 'git_diff' } },
-  trace.setSpan(context.active(), agentSpan),
-);
-try {
-  const result = await tools.gitDiff(params);
-  toolSpan.setAttributes({
-    'tool.output_status': 'success',
-    'tool.duration_ms': performance.now() - startTime,
-    'tool.input_hash': hashInput(params),
-  });
-} catch (err) {
-  toolSpan.setAttributes({ 'tool.output_status': 'error' });
-  toolSpan.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
-  toolSpan.recordException(err);
-  throw err;
-} finally {
-  toolSpan.end();
-}
-```
-
-## LLM Request/Response Tracing
-
-- **Span name pattern:** `gen_ai.{operation}` (e.g., `gen_ai.chat`, `gen_ai.completion`)
-- **Token tracking:** Capture `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens`. Aggregate in metrics: Counter `gen_ai.tokens_total` with labels `{direction, model, agent_name}`, Histogram `gen_ai.request_duration_ms`.
-- **Model version tracking:** Record both `gen_ai.request.model` and `gen_ai.response.model` for drift detection.
-- **Retry spans:** Each retry attempt is a separate child span. Set `gen_ai.request.retries` on the final span. Record `http.response.status_code` on failed spans (429 vs 500+).
-- Never log raw prompt content or full model responses as span attributes. Use token counts for cost tracking and correlated logs for prompt debugging in non-production environments.
-- Sample GenAI spans at 50-100% in production (higher than general spans) because each call is expensive and low volume.
-
-## Tool Call Audit Trail
-
-Maintain a structured audit log for every tool invocation in agentic workflows, separate from tracing spans.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `tool.name` | string | Name of the tool invoked |
-| `tool.input_hash` | string | SHA-256 hash of tool input (never log raw input) |
-| `tool.output_status` | string | `success`, `error`, `timeout`, or `denied` |
-| `tool.duration_ms` | float | Execution time in milliseconds |
-| `agent.id` | string | ID of the invoking agent |
-| `agent.name` | string | Human-readable agent name |
-| `correlation.id` | string | Trace correlation ID |
-| `timestamp` | string | ISO 8601 timestamp |
-| `session.id` | string | Session identifier |
-
-- Log tool invocations at `info` level, failures at `error` level with `error.type` and `error.message`.
-- Aggregate tool call counts per agent per session for anomaly detection.
-- Retain audit logs for a minimum of 90 days.
-
-## Correlation IDs for Agent Workflows
-
-- Use UUIDv4 with workflow-type prefix: `{workflow-type}-{uuid}` (e.g., `agent-run-550e8400-...`).
-- Generate at the workflow entry point. Propagate to all sub-agents and tool calls.
-- Every log entry, span, and metric must include `correlation.id`.
-- Cross-process: propagate via `X-Correlation-ID` header alongside W3C Trace Context.
-- Use OpenTelemetry `SpanLink` for cross-workflow references (e.g., agent run triggered by CI event).
-
-```typescript
-import { randomUUID } from 'node:crypto';
-import { context, trace, SpanStatusCode } from '@opentelemetry/api';
-
-function generateCorrelationId(workflowType: string): string {
-  return `${workflowType}-${randomUUID()}`;
-}
-
-async function runAgentWorkflow(task: string): Promise<void> {
-  const correlationId = generateCorrelationId('agent-run');
-  const tracer = trace.getTracer('agent-orchestrator');
-  const rootSpan = tracer.startSpan('agent.orchestrator.invoke', {
-    attributes: {
-      'correlation.id': correlationId,
-      'agent.name': 'orchestrator',
-      'agent.task': task,
-    },
-  });
-  try {
-    await context.with(trace.setSpan(context.active(), rootSpan), async () => {
-      await delegateToSubAgent('code_reviewer', {
-        correlationId,
-        parentSpanId: rootSpan.spanContext().spanId,
-        task: 'review changes',
-      });
-    });
-  } catch (err) {
-    rootSpan.setStatus({ code: SpanStatusCode.ERROR, message: (err as Error).message });
-    rootSpan.recordException(err as Error);
-    throw err;
-  } finally {
-    rootSpan.end();
-  }
-}
-```
+The full content has been migrated to `hatch3r-observability-tracing`.