sea-last-mile

name	sea-last-mile
description	Use when a SEA context has valid specs and generated contracts but lacks handwritten logic, runtime wiring, persistence, integration, tests, or executable proof.

SEA Last-Mile

Turn valid generated contracts into a runnable slice. just last-mile <context> is only a gap-closure tool.

Core Rule

Generated scaffolding is not product behavior. A slice needs handwritten logic, a callable surface, honest effects, tests, and one acceptance command.

If handwritten code disagrees with generated contracts, switch to sea-generator-first, fix upstream, regenerate, then return.

Load Only What You Need

• references/workflow.md: sequence, commands, dependency recipes, imports, and runtime wiring.
• references/completion-standard.md: gates and non-proof examples.
• references/enterprise-shipping-gates.md: release evidence.
• references/common-failures.md: wiring, config, DTO/null, lifecycle, imports, review.
• scripts/last_mile_check.py: heuristic triage, not proof.
• assets/acceptance-test-template.md: acceptance command template.
• assets/implementation-log-template.md: verified slice log template.

When To Use

Use when:

• just pipeline <context> is green, but the context is not runnable
• just gap-report <context> shows missing adapters or environment requirements
• contracts exist but no runtime reaches behavior
• routes bypass generated contracts without a classified reason
• a context is stuck on in-memory adapters, placeholders, scaffolding, or fakes
• an audit says logic, persistence, entrypoint, integration, or proof is missing

Do not patch specs, generators, manifests, AST/IR, generated semantic fixtures, or src/gen.

Workflow

1. Pick one SDS slice.
2. Define the acceptance command and observable result before coding.
3. Inspect existing services, adapters, recipes, tests, contracts, composition, and logs.
4. Map the path: generated command/query/DTO -> handler/service -> route/app/job -> adapter/repository/integration.
5. Reuse existing code; add surfaces only when reuse is missing, wrong, or debt-producing.
6. Implement logic, wiring, adapters, validation, null guards, lifecycle, and error mapping.
7. Replace in-memory-only paths above local-confidence.
8. Run the smallest honest proof. Manage local services through just.
9. Record classification and, after proof passes, write an implementation log.

Generated-Contract Runtime Pattern

The runtime path has four layers:

1. generated contracts under src/gen
2. handwritten implementations
3. runtime surface under services/ or apps/
4. adapters/repositories/integrations outside generated zones

Routes construct commands/queries, call handlers, guard nullable results, and map response DTOs. Direct adapter calls require derived-view, legacy, or internal classification.

Quick Reference

Gap	First move
Contracts exist but no behavior	implement handwritten handler/service
Handler exists but nothing calls it	wire route, app, job, or composition root
Service works only in memory	add durable adapter before stronger claims
Route aliases fail request validation	align request DTO with public surface
DTO serialization crashes on nullable data	align DTO optionality and guards
Acceptance fails before logic	fix runner, dependency environment, metadata, or import path first
Routes mix handlers and direct adapters	create a route matrix and classify bypasses

Stop And Ask

Stop for generated edits, placeholders, fake production claims, skipped proof, duplicate surfaces, or release claims without live evidence.

When a request would require editing generated code, stop and open an "Implementation gap detected" escalation presenting two required options:

1. Update specs/generators and regenerate (recommended)
2. Clarify requirements before proceeding