quality-gate

name	quality-gate
description	Check whether a service crate passes the publication quality gate, then fix all failures. Reads the crate's source files, runs build/clippy/test, reports pass/fail for each gate check, creates a TODO list of failures, and works through them until the crate passes.
argument-hint	<service-name>
user_invocable	true

Quality Gate Check and Fix

Evaluate a single service crate against the publication quality gate defined in .agents/docs/QUALITY_GATE.md, then fix every failure until the crate passes.

Arguments

• $0 — Service name matching the winterbaume crate suffix (e.g., s3, iam, dynamodb, sqs). The crate directory is crates/winterbaume-{service}/.

---

Procedure

Work through the gate sections below in order. For each check, emit a verdict line:

✅ QG-{N}.{M}: {short description}
⚠️  QG-{N}.{M}: {short description} — {reason}
❌ QG-{N}.{M}: {short description} — {reason}

Use ✅ for pass, ⚠️ for non-blocking observation, ❌ for fail. At the end, print a summary table.

Some gate sections (9 Terraform E2E, 13 Coverage Reporting, 14 Server and Examples, 15 Workspace-Level) are workspace-wide and cannot be evaluated per-crate. Skip those sections with a note.

---

Step 1: Read the quality gate document

Read .agents/docs/QUALITY_GATE.md to load the full gate criteria.

Step 2: Read the crate source files

Read all of these files (some may not exist — that itself is a finding):

crates/winterbaume-{service}/src/lib.rs
crates/winterbaume-{service}/src/handlers.rs
crates/winterbaume-{service}/src/state.rs
crates/winterbaume-{service}/src/types.rs
crates/winterbaume-{service}/src/views.rs
crates/winterbaume-{service}/src/model.rs   (first 20 lines only — check header)
crates/winterbaume-{service}/src/wire.rs    (first 20 lines only — check header)
crates/winterbaume-{service}/src/backend.rs (if exists)
crates/winterbaume-{service}/Cargo.toml

Also check whether the integration test file exists:

crates/winterbaume-{service}/tests/integration_test.rs

Step 3: Run build, clippy, and format checks (QG §1)

Run these commands and report results:

cargo check -p winterbaume-{service} 2>&1
cargo clippy -p winterbaume-{service} -- -D warnings 2>&1
cargo fmt -p winterbaume-{service} -- --check 2>&1

For generated files (model.rs, wire.rs):

• Check that the file header says //! Do not edit manually.
• Check that model.rs carries #![allow(non_camel_case_types, clippy::upper_case_acronyms)] if present.
• Check that wire.rs carries #![allow(dead_code)] if the crate has STUB handlers.

Step 4: Crate structure conformance (QG §2)

Verify the canonical module layout in lib.rs:

• pub mod handlers;
• pub mod state;
• pub mod types;
• pub mod views;
• pub mod model; and pub mod wire; (when generated files exist)
• optionally pub mod backend;

§2 cross-call invariant inventory check

Per the canonical QUALITY_GATE.md §2 rule, tests/scenario_test.rs is mandatory and must contain at least one scenario per non-N/A row of the invariant inventory recorded by /write-tests ( Step 1d ).

1. Confirm tests/scenario_test.rs exists. If missing → ❌ FAIL ( fix: invoke /write-tests {service} ).
2. Locate the most recent Test plan: {service} section in .agents/docs/JOURNAL.md. Inside that section, find the Cross-call invariant inventory table.
   • If the inventory is missing → ❌ FAIL. The crate has not been processed by the current /write-tests skill version. Fix: re-run /write-tests {service} to generate it.
3. For every row of the inventory whose value is not N/A — <reason>, search tests/scenario_test.rs for a scenario whose doc comment names that row's category ( for example Invariant: toggle propagation ). Each non-N/A row must have ≥ 1 covering scenario.
   • Missing rows → ❌ FAIL. The fix is to author the scenarios; do not flip rows to N/A as a workaround unless the row is genuinely undocumented in AWS, in which case justify with a doc URL.
4. Stateless services may have all-N/A inventories; the inventory is still required, with one-line reasons + doc URLs per row. An empty / absent inventory is never acceptable.

Lifecycle tests in tests/integration_test.rs do not substitute. Invariant coverage is the property this gate enforces, and lifecycle coverage does not exercise cross-call invariants. The previous "5-resource lifecycle test may substitute" carve-out is removed.

§2 handler HTTP-binding audit

The dossier at .agents/docs/services/<slug>.md carries a ## HTTP Bindings table per operation, surfacing every input member that binds to @httpHeader, @httpQuery, @httpPrefixHeaders, or @httpPayload. Optional members do not appear in the operation matrix's Required input column, so hand-written handlers routinely drop them ( GitHub issue #4 on S3 was exactly this anti-pattern: If-Match / If-None-Match were modelled, parsed by the dispatcher, then thrown away ). See the memory entry handler-signatures-drop-modelled-fields and the dossier-handler-binding-audit TODO.

Audit each operation:

• For every row in the dossier's ## HTTP Bindings table that lists Header / Query / Prefix headers / Payload entries, confirm the corresponding handler either (a) plumbs the member into a state call, (b) explicitly drops it with a one-line rationale comment naming the AWS behaviour it forgoes, or (c) is fully wired by codegen ( wire::deserialize_<op>_request returns the field on the typed input struct and the handler consumes it ).
• Pay extra attention to RFC 7232 conditional headers (If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since) and service-specific modifier headers (x-amz-*, x-amzn-*). These are the most common silent-drop offenders.
• The dossier's "Conditional-write/read coverage" trailer auto-enumerates every operation modelling RFC 7232 headers; cross-check it against the crate's actual enforcement.

Step 5: State error shaping (QG §3)

Inspect state.rs:

• Check whether there is a thiserror-derived error enum.
• Search for error_type: or status: field constructions inside state.rs — these indicate the old anti-pattern.
• Search for fn error_type or fn status methods on the error enum.
• In handlers.rs, check that the error-shaping function uses a match on the enum and calls err.to_string().

rg 'error_type:|status:\s*\d' crates/winterbaume-{service}/src/state.rs
rg 'fn error_type|fn status\b' crates/winterbaume-{service}/src/state.rs
rg 'err\.to_string\(\)' crates/winterbaume-{service}/src/handlers.rs

• Audit the modelled errors: list against the AWS API Reference. The Smithy errors: list is a lower bound, not the full set: documented HTTP error codes ( 412 PreconditionFailed and 409 ConditionalRequestConflict on conditional writes, 304 Not Modified on conditional reads, throttling and quota variants ) are routinely absent from errors: but still need to be emitted with the correct HTTP status and ErrorMetadata.code. Cross-reference the dossier's ## Behavioural Model Notes against the API Reference's "Errors" / "Response" sections per operation. Pair with the dossier-modelled-errors-lower-bound-sweep TODO and the handler-signatures-drop-modelled-fields memory.

Step 6: StatefulService contract and state views (QG §4)

Inspect views.rs:

• Confirm a *StateView type exists and implements Serialize + DeserializeOwned.
• Confirm StatefulService is implemented (snapshot, restore, merge).
• Check for #[serde(default)] on collection fields.
• In handlers.rs, search for .await calls that might hold lock guards:

rg 'notify_state_changed' crates/winterbaume-{service}/src/handlers.rs

Step 7: Stub handler discipline (QG §5)

Search for stub patterns:

rg 'STUB\[' crates/winterbaume-{service}/src/handlers.rs --count
rg 'Default::default\(\)' crates/winterbaume-{service}/src/handlers.rs -n
rg 'next-token-placeholder' crates/winterbaume-{service}/src/handlers.rs

• Every Default::default() in a handler response should either be preceded by a // STUB[category] comment or be part of a _to_model conversion.
• No placeholder pagination tokens.

Step 8: Pluggable backend conformance (QG §6)

Only applicable if src/backend.rs exists. If it does:

• Confirm the trait is object-safe (returns Pin<Box<dyn Future<...> + Send>>).
• Confirm new() uses the in-memory adapter.
• Confirm with_backend(...) or with_query_backend(...) exists.

Step 9: Smithy codegen integrity (QG §7)

• Verify model.rs and wire.rs have the //! Do not edit manually. header.
• Search handlers.rs for hand-written JSON or XML response construction:

rg 'json!\(\{' crates/winterbaume-{service}/src/handlers.rs
rg 'xml_response\(' crates/winterbaume-{service}/src/handlers.rs
rg 'format!.*<.*Response>' crates/winterbaume-{service}/src/handlers.rs

Report any remaining hand-written responses where generated wire::serialize_* functions should be used instead.

• Opaque @httpPayload blob check (QG §6 codegen-semantics assessment). For every @httpPayload member, confirm the generated type matches its target-shape kind: blob → bytes::Bytes deserialised via request.body.clone() with no std::str::from_utf8 / XML parse; structure → parsed; string → String. A blob payload run through UTF-8/XML validation 400s any binary body (issue #12):

# a blob @httpPayload deserialiser must NOT UTF-8-validate the body
rg -n 'from_utf8\(&request\.body\)' crates/winterbaume-{service}/src/wire.rs
./.agents/bin/cargo.sh test -p smithy-codegen http_payload_blobs_are_not_utf8_validated

Also confirm the handler treats the field as raw bytes and does not text-decode it as a gate, and that the dossier records the operation's true content contract (arbitrary binary vs format-constrained) per its "Opaque binary payloads" note.

Step 10: Integration test coverage (QG §8)

• Confirm tests/integration_test.rs exists and is non-empty.
• Search for FIX(terraform-e2e) markers in handler and state code and confirm corresponding tests exist:

rg 'FIX\(terraform-e2e\)' crates/winterbaume-{service}/src/ -n

• Audit error-path tests for typed-variant assertions. An expect_err(...) followed by format!("{err:?}").contains("...") is a fleet-wide anti-pattern -- the string check also accepts the SDK's Unhandled fallback, masking the exact aws-sdk-rust bug GitHub issue #3 reported against S3 ( see error-tests-must-assert-typed-variant in .claude memory and the error-tests-typed-variant-assertion-sweep TODO ). Flag every fuzzy-string error-path test in the crate:

rg -nB 0 -A 5 'expect_err\b' crates/winterbaume-{service}/tests/ | rg -B 1 'format!.*contains'

For each flagged test, the assertion should be either:

• assert!(matches!(err.as_service_error(), Some(<TypedVariant>::<Variant>(_)))) when the operation models a named error, or
• assert_eq!(err.as_service_error().unwrap().meta().code(), Some("<Code>")) when the operation has no typed variant for that error.

Permit the fuzzy form only when the operation's Smithy errors: list is empty AND the AWS API Reference does not document a specific HTTP error code for the scenario -- record that reasoning in a comment on the test.

• Run the integration tests:

cargo test -p winterbaume-{service} 2>&1

Report the test count and pass/fail status.

Step 11: Blob-backed service correctness (QG §10)

Only applicable if the service uses BlobStore (check for blob_store or BlobStore in the source). If it does:

• Verify state views reference blobs by key, not by embedding content.
• Verify BlobBackedService is implemented.

Step 12: State view fidelity (QG §11)

Inspect views.rs for:

• Whether views capture the full durable resource configuration or only a narrow subset.
• Proper serialisation conventions (Vec<u8> as hex, DateTime as RFC 3339, enums as stable strings).
• Whether serde_json::Value fields are justified (opaque wire-shaped blobs) or should be typed.

Step 13: Skip workspace-wide sections

The following sections are workspace-wide and not evaluated per-crate. Note them as skipped:

• §9 Terraform E2E Coverage
• §12 Rule Evaluator and Validator Crates (unless the crate IS one)
• §13 Coverage Reporting and Documentation
• §14 Server and Examples
• §15 Workspace-Level Checks

---

Phase A Output: Initial Report

After all checks, produce a summary:

# Quality Gate Report: winterbaume-{service}

## Summary

| Result | Count |
|--------|-------|
| ✅ Pass | N |
| ⚠️ Warning | N |
| ❌ Fail | N |
| ⏭️ Skipped | N |

## Verdict: PASS / FAIL

## Details

(all verdict lines from above, grouped by section)

---

Phase B: Remediation

If there are any ❌ failures, work through them until the crate passes.

Step 14: Create a TODO list

Create tasks for every ❌ failure, ordered by dependency (e.g., fix state error shaping before fixing handlers, fix compilation before running tests). Each task should be a concrete, actionable item:

TODO-1: [QG-3.1] Replace {Service}Error struct with thiserror enum in state.rs
TODO-2: [QG-3.2] Update error-shaping function in handlers.rs to match on enum
TODO-3: [QG-5.1] Add STUB[no-state] annotation to handle_foo, handle_bar
TODO-4: [QG-1.2] Fix clippy warning: unused variable in handle_baz
...

⚠️ warnings are informational and do not require fixes, but include them as low-priority items if they represent real improvements.

Step 15: Work through the TODO list

For each TODO item, in order:

1. Read the relevant source file(s) to understand the current state.
2. Fix the issue by editing the source file(s). Follow the conventions in QUALITY_GATE.md:
   • For state error shaping: follow the /refactor-state-errors pattern (thiserror enum in state.rs, exhaustive match in handlers.rs, err.to_string() for messages).
   • For stub annotations: add // STUB[category]: reason on the line before the fn declaration.
   • For clippy/fmt: apply the minimal fix.
   • For missing integration tests: add targeted tests that cover the gap.
   • For generated file issues: do not hand-edit model.rs or wire.rs. Fix the generator or re-run codegen.
3. Verify the fix compiles:

   cargo check -p winterbaume-{service} 2>&1
   

4. Mark the TODO as done and move to the next item.

Step 16: Re-run the gate

After all TODO items are resolved, re-run the full gate check (Steps 3–12) to confirm the crate now passes. If new failures emerge from the fixes, add them to the TODO list and repeat.

Step 17: Final verification

Run the full test suite one final time:

cargo clippy -p winterbaume-{service} -- -D warnings 2>&1
cargo test -p winterbaume-{service} 2>&1

Both must pass cleanly.

---

Phase B Output: Remediation Report

After all fixes, produce the final report:

# Quality Gate Remediation: winterbaume-{service}

## Changes Made

| TODO | Gate Check | Action Taken |
|------|-----------|--------------|
| TODO-1 | QG-3.1 | Replaced SesError struct with thiserror enum (5 variants) |
| TODO-2 | QG-3.2 | Updated ses_error_response with exhaustive match |
| ... | ... | ... |

## Final Gate Status

| Result | Count |
|--------|-------|
| ✅ Pass | N |
| ⚠️ Warning | N |
| ❌ Fail | 0 |
| ⏭️ Skipped | N |

## Verdict: PASS

If any ❌ failures remain that genuinely cannot be fixed (e.g., they require workspace-wide generator changes or upstream fixes), list them explicitly under Deferred Items with a reason and add them to .agents/docs/TODO.md.

---

Phase C: Record to JOURNAL.md

After Phase A (and Phase B if remediation was needed), append a dated entry to .agents/docs/JOURNAL.md. Do not edit existing sections — only append.

Step 18: Write the journal entry

Append a section to the end of .agents/docs/JOURNAL.md in this format:

## {YYYY-MM-DD} — Quality Gate: winterbaume-{service}

### Result: {PASS / FAIL (with N deferred)}

| Metric | Value |
|--------|-------|
| ✅ Pass | N |
| ⚠️ Warning | N |
| ❌ Fail | N |
| ⏭️ Skipped | N |
| Integration tests | N passed |

### Findings

(Bullet list of all ⚠️ and ❌ items with their QG codes and short descriptions. If the crate passed cleanly, write "No issues found.")

### Remediation

(If Phase B ran: summary table of changes made. If no remediation was needed: "No remediation required — crate passed on first check.")

### Deferred Items

(If any ❌ items were deferred to TODO.md: list them here with reasons. Otherwise omit this subsection.)

Use today's date. Keep the entry concise — the journal is a log, not a full report. The detailed verdict lines were already shown to the user in Phase A output.

---

Recurring failure modes

These are real, repeated failure patterns observed in past quality-gate sweeps. Check them explicitly during Phase A and add TODO items for any that apply.

• Missing chrono dependency. If any source file in the crate calls chrono::Utc::now() or any other chrono:: API, verify the crate's Cargo.toml declares chrono = { workspace = true } before declaring the change done. Recurring failure mode caught manually in the 2026-04-28 sweep ( elasticbeanstalk, panorama, workspaces ) — agents added the call without the dep, cascading to compile-time errors only after they returned.
• State-view literal drift. Every *StateView struct ( and its component view structs ) must #[derive(Default)], and any literal construction in tests, converters, or backend wrappers should use ..Default::default(). State-view literal drift is the largest cascade source in /tackle-todos sweeps; per-crate quality gates do not catch the breakage, only winterbaume-terraform integration tests do.
• State-shape change cascade. When a state-field type changes ( e.g. Vec<String> → HashMap<K, HashSet<V>> for inspector2's enabled_resource_types ), terraform converters that mirror that field also need updates. Per-crate quality gates do not catch the breakage; only winterbaume-terraform integration tests do. After changing a state-field type, grep the workspace for cross-crate consumers.
• --maxfail is pytest, not cargo. --maxfail is a pytest flag, not a Rust libtest flag. For Rust crate verification, use focused filters ( cargo test <pattern> ), --test-threads=N, --no-fail-fast, and per-crate gates instead. Do not pass --maxfail to cargo test.
• Write the report file before the final cargo invocation finishes. Always write your report file to disk before the final cargo invocation finishes, even if checks are still running. One agent ( transcribe, 2026-04-27 sweep ) hung on cargo and never wrote its report file, requiring a re-dispatch. The report's content can be amended in a final pass once the cargo command resolves; the file's mere existence is what tells the parent the agent didn't crash.