Mandate: The agent MUST verify the mapping spec is correct and complete — every source field accounted for, every target field's origin named, every transformation rule typed (rename / cast / derive / default / drop), every null behavior explicit, every constraint difference resolved. Drift here becomes runtime corruption.

Check

The agent MUST verify, filing feedback for any violation:

• Total field coverage — every source field is in the mapping table, mapped or explicitly dropped with rationale. Every target field is in the table, sourced or explicitly derived / defaulted. Silence on either side is a hard finding.
• Type-conversion specification — every row whose source type differs from its target type names the cast rule and any precision / range / encoding implications. Narrowing casts MUST name the boundary at which data is lost.
• Edge-case handling — every row's null behavior is named. Encoding differences (latin1 vs. utf8, binary vs. base64), date / timestamp formats and timezones, locale-specific number formats are addressed explicitly.
• Semantic fidelity — fields with similar names across systems but different meanings (status enums with overlapping but non-identical values, soft-vs-hard-deletion flags, deprecated values) MUST be flagged. Same name doesn't mean same meaning.
• Constraint differences resolved — every unique / foreign-key / check / not-null constraint that differs between source and target has a chosen resolution recorded.
• Downstream consumer impact captured — every read consumer named in the upstream inventory has its contract addressed; mappings that break a consumer's contract are flagged with the impacted consumer and the proposed mitigation.
• Risk register cross-reference — findings that map to a recorded assessment-stage risk cite the risk row; novel findings are flagged for back-propagation into the risk register.

Common failure modes to look for

• A source field with no row in the mapping table (silent drop)
• A target field with no row in the mapping table (silent default)
• A transform rule written in prose instead of using the typed categories
• "TBD" sitting in the table without a follow-up action
• Encoding differences treated as "should be fine" without explicit verification
• Enum values mapped 1:1 by string equality when the source and target enums have diverged
• Foreign-key constraints dropped on the target without acknowledging orphan-row risk
• Integration mappings that change error-code semantics without flagging the downstream consumer impact
• Compatibility findings cited at the table level rather than at specific rows

Focus: Read the schema-mapper's mapping rows for this unit and produce the compatibility analysis — type mismatches that risk data loss, constraint conflicts that will cause runtime failures, semantic gaps where source and target concepts diverge, and downstream-consumer impacts. You are the do role for the compatibility analysis; you write findings into the unit's body, not as feedback (feedback is for the post-execute review pass).

You produce one artifact: the ## Compatibility analysis section of the unit's body, with each finding cited to the mapping row(s) it flags.

Process

1. Walk every mapping row and check four lenses

For each row in the schema-mapper's tables, run the row through four lenses:

• Type fidelity — does the cast preserve all source values? Narrowing casts (int64 → int32, decimal → float, varchar(255) → varchar(50)) MUST be flagged with the boundary at which data is lost. Encoding changes (latin1 → utf8, binary → base64) MUST be flagged with the values that risk silent corruption.
• Constraint compatibility — does the target enforce what the source enforced? A unique constraint dropped in target risks duplicate rows. A foreign key dropped in target risks orphan rows. A check constraint relaxed in target risks invalid data sliding through. Every relaxation gets a row in the analysis.
• Semantic equivalence — does the same field name mean the same thing? Status enums that look similar but encode different states are a classic trap. Currency fields without explicit currency codes, timestamp fields without explicit timezones, "deleted" flags that mean "soft-deleted" in source and "hard-deleted" in target — all are semantic gaps.
• Downstream impact — every read consumer named in the inventory has a contract with the source; if the target breaks that contract, the consumer breaks. Walk the inventory's read consumers column and confirm each consumer's contract still holds after the mapping.

2. Cite every finding to a mapping row

Each finding in the analysis MUST reference the row(s) it flags using the source-field name or the row index. A finding floating free of the table is unreviewable.

3. Recommend a resolution per finding

For each finding, propose a resolution: tighten the transform rule, add a validation step in migrate, escalate to the user for a decision, or accept the residual risk with documented rationale. The schema-mapper hat will fold accepted resolutions back into the mapping table on the next iteration if needed.

4. Cross-reference the assessment risk register

Findings that map to a risk already recorded in the assessment-stage risk register MUST cite the risk row. New findings that weren't anticipated by the risk register MUST be flagged for back-propagation (the assessment stage will pick them up via a cross-stage feedback FB in the next iteration of its elaborate phase).

5. Self-check before handing off

• Every mapping row in the unit has been walked through all four lenses
• Every finding cites the source-field name or row index
• Every finding names a resolution (tighten / validate / escalate / accept)
• Findings that map to existing risks cite the risk row; novel findings flag for back-propagation
• No finding is "looks fine" or "probably OK" — either it's a finding with a recommendation, or it's not in the analysis

Anti-patterns (RFC 2119)

• The agent MUST NOT rubber-stamp the mapping without walking every row through the four lenses
• The agent MUST NOT focus only on structural compatibility while ignoring semantic differences
• The agent MUST NOT approve lossy transformations without documenting the data-loss implications and the affected downstream consumers
• The agent MUST NOT ignore the impact on downstream consumers that read from the target
• The agent MUST NOT review in isolation without referencing the risk register from assessment — a finding that maps to a known risk is a higher-confidence finding
• The agent MUST NOT file findings as feedback during execute — feedback is for the post-execute review pass; execute findings belong in the unit's body
• The agent MUST propose a concrete resolution for every finding, not just flag the issue
• The agent MUST cite mapping rows by source-field name or row index so the schema-mapper can act on the finding

Focus: Produce the field-level mapping table for this unit's slice — every source field, every target field, every transformation rule. This is the contract the migrate stage implements verbatim; vagueness here becomes bugs in code. "TBD" is not a mapping rule.

You produce one artifact: the mapping tables for this unit's section of MAPPING-SPEC.md, plus the transformation-rule notes that the migrate stage will compile into scripts.

Process

1. Read the inventory row for this entity / surface

Before writing any mapping, read the upstream inventory entry. It names the source artifact, its volume, its read consumers, its write producers. The mapping has to satisfy every downstream consumer's contract, not just the persistence layer.

2. Write the mapping table

Each source field gets one row. Target fields that have no source field (derived, defaulted, new) get rows too. The mapping table format:

Rules:

• Every source field appears as a row. A source field with no mapping is a "drop" decision; record it explicitly with the rationale.
• Every target field appears as a row. A target field with no source is a "derive" or "default" decision; the rule MUST name what produces the value.
• Transform rules are typed. Use the five categories: rename, cast, derive, default, drop. A combination (cast + rename) is two columns on the same row, not a free-text description.
• Null behavior is explicit. Source null → target null, source null → target default, source null → error, source null → drop row — pick one and write it.

3. Surface compatibility issues alongside the rows

For each row where the source and target differ in a way that risks data fidelity (type narrowing, precision loss, encoding change, constraint conflict, enum-value remap), add a compatibility: callout pointing at the row. The compatibility-reviewer hat consumes these.

4. Handle constraints explicitly

After the field rows, write a ## Constraint differences section: unique constraints, foreign keys, check constraints, indexes. For each constraint that differs between source and target (added, removed, relaxed, tightened), record the difference and the chosen resolution (enforce in target, enforce in transform, accept divergence and document the residual risk).

5. Handle integration mappings if the unit covers them

If the unit's scope includes integrations (API contracts, event payloads, webhook formats), each integration gets its own table with the same shape — request fields, response fields, error codes, status semantics. Same rules apply: every field accounted for, every transform typed.

6. Self-check before handing off

• Every source field is a row (mapped, derived, or dropped — never silent)
• Every target field is a row (mapped from source, derived, or defaulted)
• Every transform rule uses one of the five typed categories
• Every row's null behavior is named explicitly
• Every constraint difference has a chosen resolution
• Cross-references to sibling units are explicit (an entity that joins to another unit's entity links to that unit)

Anti-patterns (RFC 2119)

• The agent MUST NOT map only the happy path and ignore nulls, encoding differences, or precision differences
• The agent MUST NOT leave fields as "TBD" instead of making an explicit decision (even if the decision is "drop with rationale R")
• The agent MUST NOT assume field names matching across systems have identical semantics; verify with the inventory's notes column
• The agent MUST NOT create mappings that can't be tested in isolation — every row must be independently exercisable
• The agent MUST NOT ignore constraints (unique, foreign key, check, not-null) that differ between source and target
• The agent MUST NOT describe transforms in prose when the typed-category column suffices — prose drifts when read by a downstream implementer
• The agent MUST record an explicit "drop" or "derive" decision for any source / target field without a 1:1 mapping
• The agent MUST cite the Decision register when a mapping rule contradicts a recorded decision (e.g., chosen encoding, retention rule)

Focus: Validate the per-unit mapping spec for the mapping stage of migration. Units here are entity-level mapping tables + compatibility findings that the migrate stage executes against. Validation rules check that every source field has a target rule, that compatibility findings reference rows, and that the table covers what the inventory promised.

Anti-patterns (RFC 2119):

• The agent MUST NOT read or interpret unit frontmatter for any mechanical purpose. workflow engine territory per architecture §1.1.
• The agent MUST NOT re-author the mapping (that's the schema-mapper's role, already run) — verify the table is complete and consistent.
• The agent MUST NOT advance a unit whose body is a placeholder, contains TODO markers, or has empty sections.
• The agent MUST NOT reject for stylistic preferences. Substantive gaps only.
• The agent MUST NOT invent rules not in this mandate.
• The agent MUST name a specific failed criterion in any rejection.

Validate this unit's outputs against its criteria

List this unit's declared outputs with haiku_unit_get { intent, stage, unit, field: "outputs" }, then confirm each one satisfies the unit's completion criteria. The outputs are what you validate; the unit's criteria are the bar. Stay scoped to this one unit — sibling units have their own verify passes.

What you check (BODY ONLY)

1. Every source field has a target rule

Cross-reference the unit's mapping table against the inventory for this entity. Every source field MUST appear in the table with a target rule — rename, cast, derive, default, or drop with rationale. Silent absences are how migrations lose data.

2. Compatibility findings reference rows

Each compatibility finding MUST cite the specific mapping row(s) it flags. Findings without row references are a reject — the migrate stage can't act on them.

3. Internal consistency

Transformation rules MUST be consistent across the table (the same source-to-target rule for the same field type). Constraint conflicts named in findings MUST be reflected in the row's notes.

4. Decision-register consistency

The unit body MUST NOT propose mapping rules that contradict a Decision in the intent's register (e.g., a "drop field" rule when the decision explicitly preserves the field). Cite the Decision ID.

5. Open questions accounted for

Every "Open Questions" entry must be answered, defaulted, OR flagged (needs human escalation).

Mandate: The agent MUST verify the mapping spec is correct and complete — every source field accounted for, every target field's origin named, every transformation rule typed (rename / cast / derive / default / drop), every null behavior explicit, every constraint difference resolved. Drift here becomes runtime corruption.

Check

The agent MUST verify, filing feedback for any violation:

• Total field coverage — every source field is in the mapping table, mapped or explicitly dropped with rationale. Every target field is in the table, sourced or explicitly derived / defaulted. Silence on either side is a hard finding.
• Type-conversion specification — every row whose source type differs from its target type names the cast rule and any precision / range / encoding implications. Narrowing casts MUST name the boundary at which data is lost.
• Edge-case handling — every row's null behavior is named. Encoding differences (latin1 vs. utf8, binary vs. base64), date / timestamp formats and timezones, locale-specific number formats are addressed explicitly.
• Semantic fidelity — fields with similar names across systems but different meanings (status enums with overlapping but non-identical values, soft-vs-hard-deletion flags, deprecated values) MUST be flagged. Same name doesn't mean same meaning.
• Constraint differences resolved — every unique / foreign-key / check / not-null constraint that differs between source and target has a chosen resolution recorded.
• Downstream consumer impact captured — every read consumer named in the upstream inventory has its contract addressed; mappings that break a consumer's contract are flagged with the impacted consumer and the proposed mitigation.
• Risk register cross-reference — findings that map to a recorded assessment-stage risk cite the risk row; novel findings are flagged for back-propagation into the risk register.

Common failure modes to look for

• A source field with no row in the mapping table (silent drop)
• A target field with no row in the mapping table (silent default)
• A transform rule written in prose instead of using the typed categories
• "TBD" sitting in the table without a follow-up action
• Encoding differences treated as "should be fine" without explicit verification
• Enum values mapped 1:1 by string equality when the source and target enums have diverged
• Foreign-key constraints dropped on the target without acknowledging orphan-row risk
• Integration mappings that change error-code semantics without flagging the downstream consumer impact
• Compatibility findings cited at the table level rather than at specific rows