/nw-distill-port-treatment-policy

name: nw-distill-port-treatment-policy
description: "Port-to-port acceptance criteria + the Architecture of Reference (port-class → test treatment) + the Project Infrastructure Policy (concrete mechanism per port) + the walking-skeleton canonical definition and not-applicable exemptions. Consult while classifying a port's test treatment and the concrete mechanism for this codebase."
user-invocable: false
disable-model-invocation: true

DISTILL Port Treatment + Infrastructure Policy (KNOWLEDGE)

**Kind**: KNOWLEDGE (reference). No forced sequence — consulted on its trigger.

**Trigger**: you are classifying a port → test treatment (real vs fake) and choosing the concrete mechanism for THIS codebase (Testcontainers vs dedicated env vs in-memory; which fake class), or determining walking-skeleton applicability. Composed by `nw-distill`.

Reasoning Mandate (Caveman)

Verdict-first, tables over prose, evidence-dense, zero narrative. Depth comes from rigor, not padding. State the conclusion, then the supporting evidence; never bury the verdict under exposition.

Acceptance Criteria: Port-to-Port Principle

Every AC MUST name the driving port (entry point) exercising the behavior → port-to-port ATs → TBU (Tested But Unwired) defects structurally impossible.

Each AC: 1. **Observable outcome**: what user/system sees 2. **Driving port**: entry point triggering the behavior (service, handler, endpoint, CLI command)

No driving port → crafter can write correct code never wired into the system.

**Features**: "When user {action} via {driving_port}, {observable_outcome}" **Bug fixes**: "When {trigger}, {modified_code_path} produces {correct_outcome} instead of {current_broken_behavior}"

Architecture of Reference (ports & adapters — project-level defaults)

Three port classes, each with default test treatment. Table = PROJECT-LEVEL: decided once per project (DESIGN of first feature, or framework adoption). NOT renegotiated per feature. Agent applies defaults; per-feature decision = MECHANISM (Project Infrastructure Policy below), not treatment.

| Port type | Examples | Default in test | |---|---|---| | **Driving** (entry point) | HTTP API, CLI, in-process call, hook | **In-process via the `OutputPort`** — drive the real entry (`cli main(argv)` / application-service method) IN-PROCESS with a fake output port, no interpreter fork. The ONE selected `@walking_skeleton` proves installed wiring; additional real-boundary observations require a separately declared integration need. | | **Driven internal** (shared state) | Repository, read model, application cache | **In-memory fake for focused acceptance scenarios.** The feature's one explicitly selected walking skeleton uses the real adapter; separately declared adapter-integration tests also exercise real I/O under `nw-tdd-methodology-walking-skeleton`. A project config selects the concrete real mechanism for those observations, not a real-I/O alternative for every focused scenario. | | **Driven external / non-deterministic** | Clock, email, SMS, push, payment, LLM, third-party API | Fake/stub with output capture (so a `Then` can observe the side effect) |

Replaces the earlier per-feature Walking Skeleton Strategy A/B/C/D choice. Decision is structural — port CLASS implies port TREATMENT; per-project Infrastructure Policy specializes the mechanism per treatment.

Port unclassifiable by agent → ask the user with a soft prompt. Do NOT improvise the classification.

The inverted Driving default — in-process, not subprocess (the speed default)

The Driving default INVERTS the old "CLI = subprocess runner" assumption. A new acceptance test drives the entry point **in-process** by default: it calls the real `cli main(argv)` (or an application-service method) directly, threading a fake `OutputPort` that captures the terminal output a `Then` asserts on. No `subprocess.run([sys.executable, ...])` fork — the same Mandate-13 driving-port semantics, 10–100× faster. (Language-agnostic: the rule is "call the shipped entry in-process with a captured output sink"; the `cli main(argv)` form is the Python illustration.)

**The feature has ONE `@walking_skeleton` subprocess-E2E, reused and extended by its slices** (canonical policy: `nw-tdd-methodology-walking-skeleton`). That scenario proves the installed artifact is wired end-to-end. Additional E2E scenarios require distinct observable integration needs; they are not additional walking skeletons. Every other AT defaults to in-process/in-memory. Wiring coverage beyond it comes from the independent Examiner exercising charter observables through the real surface and the final whole-slice verification; never multiply E2E scenarios to imitate confidence.

The "CLI = e2e by construction" caveat is DISSOLVED

The old caveat held that a CLI command can only be tested end-to-end (subprocess) because the terminal is intrinsic to the command. That conflation dissolves under the hexagonal cure: **the terminal is an external system behind the `OutputPort`.** The CLI surface SPLITS into two:

| Facet | What it proves | Default treatment | |---|---|---| | **output-content / behaviour** | the command computes + emits the right output | **in-process** via the `OutputPort` (captured, asserted on the fake's buffer) | | **terminal-wiring** | the installed binary actually reaches a real terminal | **exactly one `@walking_skeleton`** per FEATURE (subprocess-e2e) |

The content facet (the bulk of the ATs) drives in-process; the wiring facet is the single WS. Do not multiply subprocess ATs per scenario, slice or command. A separately declared adapter-integration observation may require another real process when the skeleton cannot observe the promised boundary property; it is not another walking skeleton.

Config-switch — in-memory local default / testcontainers prod-like

Driven-internal ports use an **in-memory fake** in focused acceptance scenarios. Within feature acceptance scenarios, real driven-internal I/O