Build a Production Vertical Slice

A vertical slice is small in breadth and complete in consequence.

It follows one user intent across the boundaries that will determine whether the deployment can become real: interface, data, identity, external dependency, policy or AI, human authority, audit, signals, configuration, failure, and support. It is not a thin screen over a thick pile of mocks. It is not every feature built shallowly. It is not a happy path renamed “production-grade.”

The purpose is to turn design assumptions into reviewable implementation evidence while the path is still small enough for one team to understand end to end.

Define the slice by a user intent

For fictional Orchid Assist, the slice begins with a technician opening a synthetic ticket and ends with a bounded ranked inspection suggestion ready for qualified review. The system must:

1. accept a ticket with correlation and intent identifiers;
2. reconcile equipment candidates and stop on missing/ambiguous identity;
3. validate the confirmed equipment’s structure and regional semantics;
4. retrieve approved evidence for the bound equipment/region;
5. query a synthetic inventory adapter with explicit completion state;
6. run a deterministic model double within budget;
7. apply deterministic policy outside the model;
8. require a qualified, tenant/region-scoped approval for the safety-relevant step;
9. emit a minimized audit event and inspectable metric;
10. return a visible state: ready for review, blocked, fallback, or reconciliation.

That sentence is the implementation contract. It includes the failure states, not just the successful result.

Apply the vertical-slice coverage test

A candidate slice is representative only if it crosses the constraints that could invalidate the outcome.

Coverage dimension	Orchid evidence
real user intent/state	technician ticket to reviewable next step
representative interface	versioned input/output/error meanings
representative data semantics	equipment ID, tenant, region, provenance, freshness
external boundary	inventory adapter with completed/rejected/unknown behavior
identity/authorization	resource/operation/tenant/region/qualification/expiry
AI/policy	deterministic double plus policy and approval outside model
audit/telemetry	allowlisted event and correlation-safe metric
environment/config	validated configuration, no embedded secret, feature default closed
controlled failure	dependency failure, rejection, ambiguity, timeout/budget, unknown completion
support/recovery	reason code, trace, reconciliation state, owner path
review/test	clean command, automated positive/negative tests, known non-proof

If a row is not relevant, record why. Do not delete difficult rows until the slice appears complete.

This coverage test is an original FDE synthesis, not a formal standard. [CLM-081]

Keep the slice small enough to review

The vertical slice should minimize parallel novelty. Orchid uses:

• Node.js built-ins and ECMAScript modules;
• in-memory synthetic fixtures;
• a deterministic model double;
• a small injected evidence store and inventory adapter;
• pure functions for contracts, reconciliation, policy, authorization, and evidence;
• Node’s built-in test runner;
• structured JSON output for inspection.

No paid service, secret, customer data, container, or provider account is required. This makes the path reproducible. It does not make it representative of production dependency latency, permissions, quotas, regional controls, failure distributions, or operational load.

Choose realism deliberately. A local double is appropriate for deterministic contract/failure tests. A representative customer integration environment is required before claiming the real adapter works.

Make the repository explain ownership

For every component, record purpose, owner, contract, configuration, signal, failure behavior, test, runbook, and debt.

The companion’s map is intentionally compact:

Component	Purpose	Failure state	Evidence
vertical-slice.mjs	orchestrate one intent	blocked/fallback/reconcile	end-to-end tests and trace
contracts.mjs	structural/semantic equipment validation	blocked	positive and regional negative tests
reconciliation.mjs	equipment and external completion truth	missing/ambiguous/unknown	state tests
environment.mjs	validate environment/secret-free config	blocked	configuration tests
synthetic-fixture.mjs	reproducible local dependencies/data	non-production proof only	fixture review
model-interface.mjs	bounded replaceable suggestion interface	abstain/fallback	budget/abstention tests
policy.mjs	deterministic control ladder	block/require approval	policy tests
authorization.mjs	scoped permission/qualification	denied	mismatch/expiry tests
control-evidence.mjs	evidence, authority, minimized audit	incomplete/pending	governance tests

A filename is not ownership. The production dossier names the customer/product/platform/support owners and change path. The map exists so a reviewer can find where behavior lives and who must respond when it fails.

Implement contracts before orchestration

The slice reuses Chapter 7’s contract and intent foundations. The equipment record requires:

• an OES- identifier pattern;
• supported region and lifecycle status;
• observation timestamp and source version;
• west-region data in west residency;
• semantic validation beyond JSON shape.

OpenAPI 3.2.0, AsyncAPI 3.0.0, and JSON Schema Draft 2020-12 can describe structures and make selected properties machine-testable. They do not establish workflow semantics, correct authorization, safe retry, reconciliation, support, or operations. [CLM-082]

In production, keep interface descriptions versioned near implementation and test providers/consumers against agreed examples and errors. In the companion, the small pure functions expose the same separation without generating a large specification artifact for a single local path.

Return states that preserve truth

The orchestrator returns four top-level states:

• ready-for-review: the bounded path completed and policy permits presentation;
• blocked: a precondition/control/dependency response makes continuation inappropriate;
• fallback: an expected dependency/model limitation requires the non-AI/manual path;
• reconcile: an external boundary may have accepted work but final completion is unknown.

Do not collapse them into success/error. Support, retry, UI, monitoring, and user guidance differ.

An HTTP timeout after an accepted request does not prove failure. Method-level idempotency does not preserve application intent by itself. The intent identifier, semantic fingerprint, completion record, reconciliation query, and late response behavior must agree. [CLM-083]

Bind configuration before dependency access

The slice validates environment, tenant, region, data residency, and release version before using stores or adapters. It rejects configuration that embeds secret values. The bounded-suggestion feature must be explicitly enabled; the default is closed.

This order prevents a disabled or invalid path from touching dependencies “just to see what happens.” It also makes the trace show which gate made the decision.

Configuration remains distinct from code and secret material, but code validates the configuration’s meaning. A syntactically correct region string can still violate residency or ownership requirements.

Treat feature controls as lifecycle artifacts

A feature flag is not a safety control by name. Record:

• owner and purpose;
• default and fail state;
• environment/tenant/region/cohort scope;
• prerequisites and incompatible flags;
• signal and support visibility;
• approval required to widen exposure;
• rollback/disable behavior;
• expiry/removal condition;
• tests for both states and material combinations.

Without these fields, a flag can create divergent paths, stale code, support confusion, and accidental exposure. [CLM-088]

Orchid’s local feature has one purpose: include or exclude the bounded suggestion path. When false, orchestration stops before equipment/evidence/inventory access. A production flag would additionally require external configuration ownership, audited change, cohort visibility, and removal.

Reconcile identity before retrieval

The ticket can contain zero, one, or multiple active equipment candidates. The slice:

• blocks missing and routes to evidence/customer correction;
• blocks ambiguous and asks for confirmation;
• continues only on confirmed;
• then validates the selected record’s semantics.

This is deliberately before evidence retrieval. Otherwise a system can retrieve a real manual for the wrong real equipment and produce a convincing wrong answer.

The trace includes the state but not the full ticket payload. The output exposes only identifiers/evidence needed by the review path.

Inject dependencies at explicit boundaries

The evidence store and inventory adapter are injected objects with narrow methods:

• findApproved({ equipmentId, region });
• check({ intentId, equipmentId, tenant, region }).

This shape supports deterministic testing and future provider adapters. It also makes contract review possible: inputs, outputs, errors, timeouts, identity, authorization, and completion meaning are visible.

State what the doubles do not prove

The synthetic evidence store proves only that the orchestrator:

• binds lookup to equipment and region;
• stops when approved evidence is absent;
• falls back on dependency failure;
• passes evidence identifiers rather than unrestricted content to the double.

It does not prove the real store’s authorization, tenant isolation, freshness, indexing, availability, latency, retention, audit, or source approval.

The inventory double proves completed/rejected/unknown branching. It does not prove real inventory semantics, reservation behavior, capacity, concurrency, rate limits, credentials, or reconciliation APIs.

A test double’s passing result is evidence about the code and encoded double, not the real dependency. [CLM-087]

Demonstrate upstream success followed by downstream rejection

In one test, approved evidence is found and then inventory rejects the request or reports unavailable. The orchestrator returns blocked, does not call the model, and does not produce suggestions.

This matters because “upstream succeeded” can tempt a workflow to continue with partial confidence. The correct state is determined by the full intent and control chain.

In another test, the adapter says it accepted the request but no response/final state arrived. The orchestrator returns reconcile with the original intent ID. It does not guess or blindly retry.

Keep model, policy, and authority separate

The deterministic model double receives a case ID and approved evidence IDs. It can suggest, abstain, or fail to a visible budget fallback. It never receives authority.

The deterministic policy then evaluates:

• confirmed equipment;
• suggestion state;
• prohibited-action marker;
• whether a safety-relevant step has qualified approval.

Authorization evaluates the principal against the safety-approval resource, operation, tenant, region, qualification/permission, and expiry. OAuth-specific designs, if later introduced, must follow the recorded flow and applicable RFC 9700 practices; the local double does not pretend to implement a full identity protocol.

The model is one replaceable component. Contracts, access, evidence, policy, audit, operation, and failure remain system responsibilities. [CLM-085]

Review the human path too

The companion stops at ready-for-review; it does not implement a production UI. OA-06 records UI requirements:

• confirmed equipment and ticket context;
• evidence identifiers/version/freshness;
• suggestion visibly distinct from fact;
• policy and approval state;
• uncertainty/fallback/reconciliation state;
• allowed review actions;
• no default approval or hidden evidence;
• keyboard/focus/error/accessibility behavior;
• correlation/support reference.

A backend test cannot prove that the user can perform the task. Chapter 12 will add task-based UAT and selected accessibility evidence.

Emit evidence, not sensitive exhaust

The slice emits:

• a trace of named steps and outcome codes;
• one completion metric with correlation ID, state, and reason;
• one allowlisted audit event for the consequential policy result.

It does not log the raw ticket, manual content, model prompt, secret, or free-text note. This makes the trace inspectable while preserving Chapter 10’s minimization boundary.

The trace is local evidence, not full production observability. Chapter 13 will define latency, dependency, workflow, segment, quality, cost, security, and support signals plus retention/cardinality/privacy constraints.

Use a review lens that crosses concerns

Review each change through seven lenses:

Contract

• Are structural and semantic rules explicit?
• Are error and completion states stable?
• Are compatibility/version/migration needs recorded?

Failure

• What happens on missing, ambiguous, denied, timeout, exception, partial success, duplicate, late response, and recovery?
• Is the user/system state truthful and actionable?

Security and governance

• Are identity, resource, tenant, region, operation, qualification, secrets, data, audit, and authority enforced at the right boundary?
• Which control evidence and owner disposition result?

Observability

• Can an operator find the request and decision without sensitive payloads?
• Does the signal distinguish blocked, fallback, reconcile, and ready?

Operation

• Who deploys, configures, supports, disables, reconciles, recovers, and removes the path?
• Which dependency/runbook/alert must exist?

Test evidence

• Which risk/requirement is each test challenging?
• What does the fixture/environment fail to prove?

Ownership and debt

• Is every compromise named, bounded, ownered, time-limited, and connected to an exit trigger?

Secure development and application verification belong inside implementation/review, not after functional completion. [CLM-084]

Debug across boundaries, not by component reputation

When the slice fails, begin with the externally visible state and correlation identifier. Follow evidence in sequence rather than assuming the newest or most complex component is responsible.

Symptom: no suggestion is shown

Ask:

1. Was the feature/environment gate accepted?
2. Was equipment missing, ambiguous, or semantically invalid?
3. Did approved evidence exist for the bound equipment and region?
4. Did inventory complete, reject, or become unknown?
5. Did the model suggest, abstain, time out, or exceed budget?
6. Did deterministic policy block a prohibited/missing state?
7. Did qualified approval succeed for the correct tenant/region and current permission?
8. Did the UI render the returned state and support reference correctly?

“The model failed” is not a diagnosis when the system correctly blocked ambiguous equipment before calling it. “The API failed” is not a diagnosis when an accepted request has unknown completion and requires reconciliation.

Symptom: a suggestion appears for the wrong context

This is more consequential. Preserve the trace and version bundle, restrict the feature/cohort if needed, and test:

• ticket-to-equipment binding;
• cache/search tenant and region keys;
• evidence source/provenance/freshness;
• model input construction;
• policy/equipment confirmation;
• UI display of selected context;
• audit/correlation consistency.

Do not repair only the final prompt. The fault may be retrieval, identity, stale data, UI state, or cache isolation.

Symptom: retries increase load

Separate new user demand from repeated attempts. Inspect timeout location, client retry policy, intent reuse, server completion state, downstream capacity, and reconciliation availability. A frontend polling loop can become a backend incident even when each request is individually valid. The UI belongs inside system performance and failure reasoning.

Record the diagnostic result

A useful debug record contains:

• symptom and user/cohort consequence;
• correlation/intent/release/config identifiers;
• first known good and first known bad boundary;
• evidence inspected and access constraints;
• competing hypotheses and falsification results;
• containment and recovery state;
• defect/control/debt classification;
• owner, follow-up test, and runbook update.

This turns one incident into reusable product/operating knowledge without copying sensitive payloads into a ticket.

Review change size and seams

A vertical slice can become unreviewable if it arrives as one enormous change. Sequence implementation so each checkpoint preserves a testable contract:

1. pure contracts and reconciliation states;
2. environment/configuration gates;
3. injected adapter interfaces and deterministic fixtures;
4. model/policy/authorization composition;
5. audit/metric/result state;
6. end-to-end positive and negative paths;
7. representative adapters/UI/exporters behind reviewed seams.

Do not merge knowingly insecure intermediate behavior into an exposed environment merely because a later change will add the control. Keep incomplete paths unreachable by default.

At each seam review:

• whether the abstraction represents a stable responsibility or only hides uncertainty;
• whether errors preserve dependency truth;
• whether timeouts/cancellation/retries/late results are defined;
• whether the adapter receives the minimum identity/data;
• whether test fixtures model the intended semantics, not just convenient output;
• how real integration evidence will replace the double’s non-proof;
• how a future implementation can be removed without rewriting domain logic.

A provider-neutral interface is useful only if it preserves the consequential differences that callers need. An over-generic execute(input) method can erase intent, authorization, completion, and failure semantics.

Define safe defaults at construction time

Safe defaults reduce the chance that a new environment, tenant, or operator accidentally widens exposure. For Orchid:

• bounded suggestion defaults disabled;
• missing evidence causes fallback, never invention;
• ambiguous equipment blocks retrieval/action;
• unknown completion requires reconciliation;
• safety-relevant work requires current qualified approval;
• secret values are rejected from configuration;
• audit uses an allowlist;
• no provider adapter is selected implicitly;
• synthetic fixtures are visibly named and cannot be confused with customer data.

Defaults are not enough. Test configuration drift, explicit override, environment promotion, failure of the configuration source, and visibility to support. A silent default that changes between environments creates a different system.

Keep migrations and compatibility visible even in the first slice

The current companion has in-memory state, so it does not execute a schema migration. OA-06 still identifies migration seams:

• equipment/source version changes;
• ticket/status vocabulary changes;
• intent-ledger retention/record format;
• policy/permission identifier changes;
• audit schema evolution;
• model/evidence bundle version changes.

For each future persistent change, define old/new readers and writers, compatibility window, backfill or dual-write decision, validation, rollback/roll-forward limits, and recovery evidence. “We can change the database later” is not a vertical-slice plan if the first customer data makes the shape irreversible.

Chapter 14 will execute migration and recovery fixtures. Chapter 11 creates the seams and version identifiers so that work is possible.

Make debt a decision

The slice intentionally carries debt:

Debt	Why accepted now	Consequence/non-proof	Exit trigger	Owner
in-memory stores	deterministic local run	no persistence/concurrency/integration proof	representative adapter test	integration owner
deterministic model	no paid dependency/uncertainty	no provider/model quality proof	bounded provider evaluation decision	AI owner
JSON trace only	inspectable local evidence	no production telemetry pipeline	Chapter 13 signal adapter	operations owner
no production UI	focus on orchestration	no task/accessibility/UAT evidence	review interface test	product owner
local timing	reproducible behavior	no capacity/latency evidence	representative load/soak plan	platform owner

An unowned TODO is not a debt decision. Preserve reason, consequence, owner, trigger, and exit condition. [CLM-090]

Generated code, if used later, receives the same review, tests, source/license/security checks, ownership, and maintenance expectations as human-written code. “The tool generated it” is not provenance sufficient for release.

Reproduce from a clean clone

The companion supports:

npm run test:companion
npm run demo:companion

The demo emits deterministic synthetic JSON. The tests cover contracts, authorization, environment, intent/reconciliation, bounded AI/evaluation, governance, and the end-to-end slice.

Automated setup and consistent release processes reduce manual variance. They do not replace representative verification, review, approval, or recovery. [CLM-086]

A clean local path is valuable reproducibility evidence and onboarding/support infrastructure. It is still separate from evidence in a customer-like environment. [CLM-089]

Trace the slice as a reviewer

Use one synthetic intent and read the trace in operational order:

1. Configuration is parsed and rejected if a secret field or wrong residency appears.
2. The feature control defaults closed; no dependency call occurs until explicitly enabled for the synthetic scope.
3. The ticket’s equipment candidates remain missing, confirmed, or ambiguous rather than being coerced into a match.
4. Contract validation checks structural and semantic equipment/region rules.
5. Evidence and inventory adapters receive only the confirmed, authorized context.
6. Unknown inventory completion preserves the intent and enters reconciliation rather than blind retry.
7. The deterministic model double suggests only when approved evidence exists and budget permits; otherwise it abstains/falls back.
8. Deterministic policy and qualified approval remain separate decisions.
9. The final state, minimized metric, and audit event share safe correlation identifiers.

At each step ask: what input was trusted, what state can emerge, what external effect can occur, what evidence is emitted, and who owns the next action? A function-level review can miss a semantic break between individually correct components.

Run the consequential failure drill

Execute the happy path once to establish the trace shape. Then inject:

• ambiguous equipment before evidence access;
• successful evidence retrieval followed by inventory rejection;
• missing response after external inventory acceptance;
• expired or wrong-region authorization;
• model budget exhaustion;
• prohibited policy result;
• feature disabled at construction.

For each injection, record expected and observed state, dependencies contacted, external effects, audit/metric evidence, user/fallback behavior, owner, and non-proof. The test passes only when failure remains truthful and bounded. Error returned is insufficient if an external effect may already have happened or sensitive work continued after a failed boundary.

Review supportability from a clean checkout

Give the repository to a reviewer who has not run it. They should locate setup, commands, module boundaries, configuration schema, synthetic fixtures, tests, failure injections, evidence output, and debt without private instructions.

Record every hidden step: assumed runtime, global package, missing environment value, undocumented port, stale command, secret request, or unclear owner. Repair the repository or add an explicit prerequisite. The original author succeeding from a warmed environment does not prove reproducibility.

This exercise also tests the repository map. If the reviewer cannot identify where a contract, policy, adapter, test, signal, or debt is owned, the structure does not yet support handoff.

Failure modes and repairs

Happy path becomes production proof

Repair: inject consequential failures, preserve explicit states, and record the real integration/UI/environment/performance evidence still missing.

Mock becomes the dependency contract

Repair: state what the double encodes and does not prove; validate representative adapter semantics and failures later. [CLM-087]

Orchestration hides contract meaning

Repair: implement/validate semantic contracts first and keep intent, finality, error, authorization, and reconciliation visible.

Feature flag becomes permanent architecture

Repair: owner, default, scope, interaction tests, evidence, expiry, and removal. [CLM-088]

Local setup depends on the author

Repair: clean-checkout reproduction with documented runtime, deterministic fixtures, no secrets, and inspectable failures. [CLM-089]

TODO hides accepted risk

Repair: debt reason, consequence, owner, trigger, exit, and release effect. [CLM-090]

Production quality is a portfolio of evidence

Functional correctness competes and cooperates with reliability, security, performance, cost, usability/accessibility, maintainability, operational support, and recovery. Provider architecture guidance and ISO’s quality-model record help enumerate concerns, but no provider checklist decides Orchid’s tradeoffs. [CLM-080]

For example:

• stricter authorization can increase dependency/recovery complexity;
• richer audit can increase privacy/cost exposure;
• aggressive retries can increase downstream overload and duplicate work;
• a fast model can reduce review time while increasing unsupported suggestions;
• a feature flag can reduce exposure while multiplying configuration paths;
• a sophisticated integration can increase realism while reducing local reproducibility.

Record the tradeoff, evidence, owner, and stop/exit condition. Do not hide it in “non-functional requirements.” These qualities determine whether the function produces a supportable outcome.

Complete OA-06

The vertical-slice artifact now contains:

• synthetic ticket/equipment/evidence/inventory fixtures;
• environment and feature-control record;
• equipment contract and reconciliation;
• evidence and inventory adapters;
• deterministic model interface and budget fallback;
• policy and qualified approval;
• minimized audit and metric;
• end-to-end trace and explicit states;
• repository/supportability map;
• review lens and debt register;
• clean run/test commands;
• known non-proof for every double.

It also records future production seams: real stores/adapters, workload identity, external config/secret manager, review UI, telemetry exporter, support/reconciliation API, representative environment tests, and release pipeline.

The Chapter 11 gate

Before expanding the feature surface, the slice must:

• cross one real user intent end to end;
• validate environment/config before access;
• preserve tenant/region/equipment binding;
• use explicit contracts and completion meanings;
• stop early on missing/ambiguous/denied states;
• demonstrate downstream rejection after upstream success;
• route unknown completion to reconciliation;
• keep model, policy, authorization, and authority separate;
• emit minimized audit/trace/metric evidence;
• default the feature closed;
• run from a clean clone without secret/paid service/customer data;
• pass positive and consequential negative tests;
• state what every double does not prove;
• link owners, runbooks, and debt exit conditions.

The gate passes when a reviewer can trace one intent across every consequential boundary, reproduce its safe failure behavior, and identify the evidence still required before production.

Chapter 12, Prove Behavior Before Production, will connect every material risk and acceptance claim to the cheapest credible verification method, representative data, observed result, limitation, and release disposition.