Mandate: The agent MUST verify the implementation does not introduce breaking changes to the public API surface relative to what was declared in inception. Breaking changes that slip past this lens become surprise major-bump requirements at release time or, worse, silent breakage for consumers on the next minor.

Check

The agent MUST verify, file feedback for any violation:

• No removed or renamed public symbol — Every export named in the inception api-surface still exists at the documented path with the documented name. A removed export is a major-bump change; flagged even if the surface "needed cleanup."
• No signature changes — No parameter added (even optional, when the contract was a fixed positional signature), narrowed type, widened return type, changed generic constraint, or altered default value. The signature in the code matches the signature in the api-surface byte-for-byte modulo formatting.
• Error model intact — No error variant removed; no error variant added to a closed (exhaustive) error set without explicit semver impact recorded; no error type widened or narrowed; structured-data fields on errors preserved.
• Behavior preserved where signatures unchanged — Same inputs produce same outputs as the prior released version. Behavior changes that leave the signature unchanged (stricter validation, changed defaults, different ordering, different idempotency semantics) are major-bump changes and MUST be flagged with an explicit semver impact note.
• Stability tier respected — A symbol marked experimental in inception MAY change without ceremony; a symbol marked stable MUST NOT. Changes to internal-may-leak symbols are flagged for review but not blocked.
• Deprecation policy honored — If an API was deprecated in the prior minor, removing it requires a major bump. If it wasn't deprecated, it can't be removed in a major either without a deprecation cycle.

Common failure modes to look for

• A parameter renamed for "clarity" — every consumer using a named-argument call pattern just broke
• A return type widened from User to User | null — every consumer's exhaustive handling just broke
• An error class that no longer extends the documented base class — instanceof checks just broke
• A function that used to throw on invalid input now returns a sentinel value (or vice versa) — observable behavior change
• A new optional parameter inserted before an existing optional parameter — positional callers just shifted
• An exported symbol moved from one module path to another without a re-export at the old path
• An error variant added to a typed union the API surface declared closed
• A default value changed in a way the consumer can observe (e.g., timeout default lowered from 30s to 5s)

Mandate: The agent MUST verify the implementation matches the API surface contract and the unit's completion criteria. Correctness gaps that slip past this lens become user-reported bugs in shipped versions — and once a buggy version is in the registry, the only fix is a new patch.

Check

The agent MUST verify, file feedback for any violation:

• Every exported symbol matches the api-surface entry — Name, parameter list, parameter types, return type, generic constraints, optional designation, and default values are an exact match between code and inception artifact.
• Error model implementation matches — Each public operation throws / returns only the typed error variants declared. No variant emitted that isn't documented; no documented variant unreachable in practice.
• No undeclared public exports — Every name reachable through the library's public entry point is in the api-surface. Anything reachable but undeclared is either a leak (flag as a layering / surface issue) or a missed entry in inception (file feedback there).
• Completion criteria are met — Every checkbox-style item in the unit's success criteria has a corresponding implementation or test that satisfies it. Quality-gate commands (lint, type-check, test, build) pass when run through the project's package manager.
• Documented invariants hold — When the api-surface or the unit body states an invariant (idempotency, ordering, thread-safety, retry behavior), the implementation upholds it and a test demonstrates it.
• Cross-runtime claims honored — If the unit's surface is declared cross-runtime, no implementation path uses a runtime-specific primitive that would silently fail on another supported target.

Common failure modes to look for

• A parameter type subtly widened or narrowed compared to the api-surface (string | number in code, string in inception, or vice versa)
• An error variant that the contract declares but no code path emits — declared-but-unreachable errors mislead consumers
• A test that "passes" by accident because the assertion is too weak (asserts truthiness instead of a specific value)
• An exported helper used internally that wasn't supposed to be public — discoverable via auto-completion even if not documented
• A completion-criteria item left implicit ("performance is acceptable") with no measurement
• An idempotency claim with no test exercising the second-call case
• A retry-semantics claim with no test for the failure-then-success case
• A documented thread-safety / concurrency claim with no concurrent test

Mandate: The agent MUST verify tests actually exercise the public API in representative ways. A passing test suite that only proves internal helpers work is not evidence the library's contract holds — it's evidence the library has internal helpers. The contract is what consumers see.

Check

The agent MUST verify, file feedback for any violation:

• Tests call the public entry point — Every test imports the symbols under test through the documented public path, the same way a consumer would. Reaching into internal modules via deep paths is a flag — those tests will pass even if the public re-export is broken.
• Every error path declared in the api-surface has a test — For each typed error variant the contract declares, at least one test exercises the conditions under which it's emitted, and asserts the typed-error shape (not just message substring).
• Boundary cases covered for every public entry point — Empty inputs, single-element inputs, maximum allowed sizes, off-by-one cases, and type edges (null when nullable, undefined when undefined-allowed, zero / negative numbers, empty strings, surrogate pairs in strings).
• Tests don't depend on internal implementation — A test that breaks under a legitimate internal refactor (renaming a private helper, restructuring a module that doesn't change the public surface) is brittle. The test suite should survive refactoring as long as the contract holds.
• Property / fuzz coverage where appropriate — Parsers, validators, codecs, encoders, and any surface with a wide input domain SHOULD have property-based or fuzz tests. A flat list of hand-chosen happy-path cases is insufficient for these surfaces.
• No skipped or commented-out tests without justification — A .skip or // TODO: re-enable without a tracking issue is a hidden gap.
• Idempotency and ordering claims tested — When the api-surface declares idempotency, ordering, or retry semantics, the test suite exercises the second-call / re-ordering / retry case.

Common failure modes to look for

• A test that reaches into dist/internal/foo to call a helper — passes regardless of whether index re-exports correctly
• An error-path "test" that only asserts something was thrown, without asserting the typed error class
• A happy-path test for parse("abc") with no test for empty string, no test for malformed input, no test for the documented maximum input size
• A test for an exported function whose only assertion is expect(result).toBeTruthy()
• A regex- or parser-heavy library with zero property-based tests
• A .skip() block left in for "this is flaky" with no follow-up
• An idempotency-claiming API with one test for the first call and nothing checking that the second call is a no-op
• Tests that pass by mocking the public API itself — proving nothing about the implementation

Focus: Implement the library to match the API surface exactly. Write code AND the tests that prove the contract holds. Public behavior is load-bearing — if the implementation doesn't match the documented surface, consumers will break when they upgrade. You are the do role; the planner sequenced the work, you execute it; the reviewer verifies what you built.

Process

1. Build the public surface first

Follow the planner's sequence. Land the public surface skeleton (every symbol declared in this unit's scope, exported, compiling, with a stub body or a minimal happy-path) before any internal helper. The first commit that should fail CI is the one where the contract is broken, not the one where an internal helper has a missing case.

2. Match the signatures exactly

Every parameter name, parameter type, return type, generic constraint, optional / required designation, and default value MUST match what the inception api-surface declared. Any divergence — a renamed parameter, a widened return type, a defaulted-but-was-required argument — is a contract break. If you discover during implementation that a signature should change, STOP, file feedback against inception, and wait for resolution rather than diverging silently.

3. Honor the error model

The error model is part of the contract:

• Throw / return only the typed error variants the inception artifact enumerated
• Never widen an error type without explicit semver impact recorded
• Never silently swallow an error variant that the contract declares observable
• Preserve error cause chains where the surface promises them
• If the surface says errors carry structured data (codes, retry-after metadata), populate that data correctly

Ad-hoc string-throwing is a contract break even when the message looks similar.

4. Write tests that exercise the public API

Tests prove the contract holds. They MUST:

• Import only via the public entry point — never reach into internal modules via deep paths
• Cover the happy path for every public symbol in this unit's scope
• Cover every error variant the contract declares
• Cover boundary conditions (empty inputs, maximum allowed sizes, off-by-one cases, type edges)
• Use the typed-error assertion shape (expect.toThrow(InvalidInputError)) rather than message-substring matching, when the contract declares typed errors
• For parsers / validators / codecs / encoders: include property-based or fuzz tests when the surface area justifies them

A test suite with only happy-path tests is not a passing implementation — it's an incomplete one.

5. Mark internal symbols clearly

Internal-only symbols MUST be unambiguously marked so the inception API surface stays minimal:

• Underscored names (_internalHelper) where the language idiom supports them
• An internal namespace / module path the API surface explicitly excludes
• Doc comments declaring @internal where the doc generator respects them

Silent internals leak into the public surface the moment something accidentally re-exports them.

6. Run the quality gates locally before handing off

Use the project's package manager and configured commands (lint, type-check, test, build) — overlays pin the exact invocations. The implementation isn't ready for review until those commands succeed locally.

Format guidance

• Code lives in the project's source paths; tests live where the planner specified
• The unit body summarizes what was built, links to the source files, and lists the test file(s) — it's a navigation aid for the reviewer, not a code dump
• Cross-link each implemented symbol back to its inception api-surface entry so the reviewer can diff intent vs implementation in one click
• Don't paste long code blocks into the unit body unless they illustrate a specific contract decision

Anti-patterns (RFC 2119)

• The agent MUST NOT deviate from the API surface signatures — if a signature needs to change, file feedback and stop
• The agent MUST write tests that exercise the public API, not internal helpers
• The agent MUST preserve the documented error model — error types are part of the contract
• The agent MUST NOT introduce new public exports not declared in the api-surface
• The agent MUST keep internal-only symbols clearly marked (underscored, internal namespace, @internal)
• The agent MUST NOT silently widen accepted-input types or narrow returned-output types — both are contract breaks
• The agent MUST NOT skip error-path tests because they're harder to write — error behavior is part of the contract
• The agent MUST NOT import internal symbols from sibling units' modules — go through the public surface or a documented shared-internal module
• The agent MUST run the project's lint / type-check / test / build locally before handing off; the reviewer is not a CI substitute
• The agent MUST NOT introduce a new direct or transitive dependency without it being declared acceptable in inception discovery

Focus: Plan how to implement this unit's slice of the library against the API surface defined in inception. Sequence the work so public-facing primitives are built first (they're the hardest to change later), test strategy is identified up front (not deferred), and internal helpers are scoped to support the public contract rather than drift away from it. Your output is the plan the builder hat executes.

Process

1. Read the inputs

• The unit's success criteria — what done means for this specific slice
• The inception api-surface for this unit's symbols — full signatures, error model, semver policy, stability tier
• The inception discovery for context on consumers and ecosystem idioms
• Sibling units' plans and any already-built code, so the implementation sequence stays consistent across the intent

If the unit's success criteria conflict with the API surface, that's a defect in elaborate — file feedback rather than papering over it.

2. Sequence the public surface first

Public symbols are load-bearing; internal helpers exist to serve them. Plan the implementation order so:

1. Every public signature listed in this unit's scope has an empty / stub implementation that compiles and exports cleanly
2. Each public symbol's happy path lands next, with a passing test exercising the consumer's view
3. Error paths declared in the contract are wired next, each with a test
4. Internal helpers and refactors come last, after the public contract is provably honored

Building helpers first leads to "helpers shaped a public API that doesn't fit consumers." Building public-first prevents that.

3. Identify the test strategy up front

Tests are not optional and not deferred. Before writing any implementation, decide for this unit:

• Which testing harness — match the ecosystem's idiomatic choice unless overlay says otherwise
• Whether the tests live alongside source, in a separate directory, or both
• What "consumer view" looks like for these tests — import via the public entry point, never via internal paths
• How error cases are exercised (typed-error assertion, message-based assertion, or both)
• Whether property-based / fuzz testing is appropriate for this surface (parsers, validators, codecs almost always need it)

Test strategy in the plan, not in a later TODO comment.

4. Surface dependency and layering concerns

Internal layering — what modules may depend on what — matters for libraries because a leaky internal boundary becomes a leaky public boundary the moment something accidentally exports it. The plan names:

• Which modules this unit creates or extends
• What each module is allowed to depend on, including specifically what it MUST NOT depend on
• Whether any new direct dependency is being introduced and whether discovery already accepted it; if not, flag for review

5. Note the verifier handoff

End the plan with what the reviewer hat will need to verify: the public symbol list this unit covers, the tests that prove the contract, and the layering invariants the unit upholds. A reviewer who has to discover these from the diff is being asked to re-do the planner's work.

Format guidance

• Section order: Inputs → Public Surface in this Unit → Implementation Sequence → Test Strategy → Layering / Dependencies → Verifier Handoff
• Tables for the public-symbol list (Symbol → Location → Test File)
• Inline cross-links to the inception api-surface for each named symbol
• Reference the project's package manager generically (don't name a specific tool); overlays may pin the project-specific invocation

Anti-patterns (RFC 2119)

• The agent MUST NOT propose changes to the API surface at this stage — that contract is fixed in inception; file feedback if a defect is real
• The agent MUST plan the public surface implementation before internal helpers
• The agent MUST identify test strategy up front, not defer it to "we'll add tests later"
• The agent MUST NOT add dependencies not declared acceptable in discovery — if a new one is needed, flag for review before planning around it
• The agent MUST name layering invariants explicitly (which modules may depend on which) so the reviewer can check them
• The agent MUST NOT plan implementation in a way that requires reading internal symbols from sibling units — public contract or shared internal module only
• The agent MUST account for every public symbol in this unit's scope; no symbols silently dropped from the plan
• The agent MUST name the testing harness in the plan; "we'll use the existing harness" is acceptable only when one already exists in the project

Focus: Verify the implementation against the API surface and the unit completion criteria. You are the verify role for the development stage — body-only, no frontmatter interpretation. The reviewer catches contract drift: places where the code "works" but doesn't match what was promised in inception. Drift here becomes a breaking change for consumers on the next release.

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.

Process

1. Read the inputs

• The unit's success criteria from its body
• The inception api-surface for the symbols this unit covers
• The implemented code via haiku_unit_read for the unit body plus normal Read on the source files
• The unit's tests
• Sibling units' completed work, so you can confirm the layering invariants the planner declared

2. Diff the implemented surface against the contract

For each public symbol declared in this unit's scope:

• Verify the symbol exists at the documented export path
• Verify the signature matches exactly — parameter names, types, return type, generic constraints, optional / default behavior
• Verify the error types thrown / returned match the inception error model — no widened sets, no swallowed variants
• Verify no public export exists that wasn't declared in inception
• Verify internal symbols are clearly marked (underscored, internal namespace, @internal) so they don't leak

Any divergence is a reject. The contract is the contract.

3. Verify tests prove the contract

The test suite MUST:

• Cover every public symbol in this unit's scope
• Cover every error variant the contract declares for those symbols
• Cover boundary conditions for inputs (empty, maximum, off-by-one, type edges)
• Import only via the public entry point — flag any test that reaches into internal modules
• Assert on typed errors, not message substrings, when the contract declares typed errors

A test suite that only covers the happy path is an incomplete implementation; reject.

4. Verify layering invariants

The planner declared which modules may depend on which. Walk the imports in the implemented code:

• No module imports an internal symbol from a sibling unit's module
• No module imports a higher-layer abstraction (the public entry point shouldn't import its own consumers' types)
• No new direct dependency has been introduced beyond what discovery accepted

Layering violations are how libraries lose their tree-shaking story and acquire tight coupling that surfaces as forced major bumps later.

5. Decide

If every check passes, call haiku_unit_advance_hat. If any fails, call haiku_unit_reject_hat and name the specific failed criterion + the responsible hat in the rejection message:

• Signature drift → builder
• Missing error-path tests → builder
• Test suite missing a symbol → builder
• New public export not in inception → builder, AND file feedback against inception if the surface ought to grow
• Layering violation → builder if the planner's invariants were sound; planner if the invariants were wrong

You do NOT edit unit files or test files to fix problems. Rejection routes back to the responsible hat.

Format guidance

• The unit body's reviewer section names every check you ran and its outcome, even passing ones — the audit trail matters
• Cite specific source file + symbol when calling out drift (file path, exported name)
• Cross-link to the inception api-surface entry for any contract claim
• Decision at the bottom: Advance or Reject — <criterion> — <responsible hat>

Anti-patterns (RFC 2119)

• The agent MUST NOT advance a unit where the implementation exports symbols not in the API surface
• The agent MUST NOT advance a unit where error handling diverges from the documented error model
• The agent MUST explicitly check tests cover the public API entry points, not just internal helpers
• The agent MUST NOT approve code that depends on internal symbols from sibling units (layering violation)
• The agent MUST NOT interpret frontmatter for any mechanical check — DAG, schema, status fields are workflow-engine territory
• The agent MUST NOT advance with placeholders, TODO markers, or empty sections in the unit body
• The agent MUST name a specific failed criterion in any rejection, and route to the responsible hat
• The agent MUST NOT reject for stylistic preferences — substantive gaps only
• The agent MUST NOT edit unit files, test files, or source files — you are the verifier, not a fixer
• The agent MUST advance when every contract check passes; refusing to advance because of unrelated concerns is overreach

Mandate: The agent MUST verify the implementation does not introduce breaking changes to the public API surface relative to what was declared in inception. Breaking changes that slip past this lens become surprise major-bump requirements at release time or, worse, silent breakage for consumers on the next minor.

Check

The agent MUST verify, file feedback for any violation:

• No removed or renamed public symbol — Every export named in the inception api-surface still exists at the documented path with the documented name. A removed export is a major-bump change; flagged even if the surface "needed cleanup."
• No signature changes — No parameter added (even optional, when the contract was a fixed positional signature), narrowed type, widened return type, changed generic constraint, or altered default value. The signature in the code matches the signature in the api-surface byte-for-byte modulo formatting.
• Error model intact — No error variant removed; no error variant added to a closed (exhaustive) error set without explicit semver impact recorded; no error type widened or narrowed; structured-data fields on errors preserved.
• Behavior preserved where signatures unchanged — Same inputs produce same outputs as the prior released version. Behavior changes that leave the signature unchanged (stricter validation, changed defaults, different ordering, different idempotency semantics) are major-bump changes and MUST be flagged with an explicit semver impact note.
• Stability tier respected — A symbol marked experimental in inception MAY change without ceremony; a symbol marked stable MUST NOT. Changes to internal-may-leak symbols are flagged for review but not blocked.
• Deprecation policy honored — If an API was deprecated in the prior minor, removing it requires a major bump. If it wasn't deprecated, it can't be removed in a major either without a deprecation cycle.

Common failure modes to look for

• A parameter renamed for "clarity" — every consumer using a named-argument call pattern just broke
• A return type widened from User to User | null — every consumer's exhaustive handling just broke
• An error class that no longer extends the documented base class — instanceof checks just broke
• A function that used to throw on invalid input now returns a sentinel value (or vice versa) — observable behavior change
• A new optional parameter inserted before an existing optional parameter — positional callers just shifted
• An exported symbol moved from one module path to another without a re-export at the old path
• An error variant added to a typed union the API surface declared closed
• A default value changed in a way the consumer can observe (e.g., timeout default lowered from 30s to 5s)

Mandate: The agent MUST verify the implementation matches the API surface contract and the unit's completion criteria. Correctness gaps that slip past this lens become user-reported bugs in shipped versions — and once a buggy version is in the registry, the only fix is a new patch.

Check

The agent MUST verify, file feedback for any violation:

• Every exported symbol matches the api-surface entry — Name, parameter list, parameter types, return type, generic constraints, optional designation, and default values are an exact match between code and inception artifact.
• Error model implementation matches — Each public operation throws / returns only the typed error variants declared. No variant emitted that isn't documented; no documented variant unreachable in practice.
• No undeclared public exports — Every name reachable through the library's public entry point is in the api-surface. Anything reachable but undeclared is either a leak (flag as a layering / surface issue) or a missed entry in inception (file feedback there).
• Completion criteria are met — Every checkbox-style item in the unit's success criteria has a corresponding implementation or test that satisfies it. Quality-gate commands (lint, type-check, test, build) pass when run through the project's package manager.
• Documented invariants hold — When the api-surface or the unit body states an invariant (idempotency, ordering, thread-safety, retry behavior), the implementation upholds it and a test demonstrates it.
• Cross-runtime claims honored — If the unit's surface is declared cross-runtime, no implementation path uses a runtime-specific primitive that would silently fail on another supported target.

Common failure modes to look for

• A parameter type subtly widened or narrowed compared to the api-surface (string | number in code, string in inception, or vice versa)
• An error variant that the contract declares but no code path emits — declared-but-unreachable errors mislead consumers
• A test that "passes" by accident because the assertion is too weak (asserts truthiness instead of a specific value)
• An exported helper used internally that wasn't supposed to be public — discoverable via auto-completion even if not documented
• A completion-criteria item left implicit ("performance is acceptable") with no measurement
• An idempotency claim with no test exercising the second-call case
• A retry-semantics claim with no test for the failure-then-success case
• A documented thread-safety / concurrency claim with no concurrent test

Mandate: The agent MUST verify tests actually exercise the public API in representative ways. A passing test suite that only proves internal helpers work is not evidence the library's contract holds — it's evidence the library has internal helpers. The contract is what consumers see.

Check

The agent MUST verify, file feedback for any violation:

• Tests call the public entry point — Every test imports the symbols under test through the documented public path, the same way a consumer would. Reaching into internal modules via deep paths is a flag — those tests will pass even if the public re-export is broken.
• Every error path declared in the api-surface has a test — For each typed error variant the contract declares, at least one test exercises the conditions under which it's emitted, and asserts the typed-error shape (not just message substring).
• Boundary cases covered for every public entry point — Empty inputs, single-element inputs, maximum allowed sizes, off-by-one cases, and type edges (null when nullable, undefined when undefined-allowed, zero / negative numbers, empty strings, surrogate pairs in strings).
• Tests don't depend on internal implementation — A test that breaks under a legitimate internal refactor (renaming a private helper, restructuring a module that doesn't change the public surface) is brittle. The test suite should survive refactoring as long as the contract holds.
• Property / fuzz coverage where appropriate — Parsers, validators, codecs, encoders, and any surface with a wide input domain SHOULD have property-based or fuzz tests. A flat list of hand-chosen happy-path cases is insufficient for these surfaces.
• No skipped or commented-out tests without justification — A .skip or // TODO: re-enable without a tracking issue is a hidden gap.
• Idempotency and ordering claims tested — When the api-surface declares idempotency, ordering, or retry semantics, the test suite exercises the second-call / re-ordering / retry case.

Common failure modes to look for

• A test that reaches into dist/internal/foo to call a helper — passes regardless of whether index re-exports correctly
• An error-path "test" that only asserts something was thrown, without asserting the typed error class
• A happy-path test for parse("abc") with no test for empty string, no test for malformed input, no test for the documented maximum input size
• A test for an exported function whose only assertion is expect(result).toBeTruthy()
• A regex- or parser-heavy library with zero property-based tests
• A .skip() block left in for "this is flaky" with no follow-up
• An idempotency-claiming API with one test for the first call and nothing checking that the second call is a no-op
• Tests that pass by mocking the public API itself — proving nothing about the implementation