# Dark Factory Build — Self-Contained Priming Doc (for skill-less agents)

> **TL;DR** — Paste this whole document into a capable agent that has **no skill system**
> (ChatGPT, Gemini, or any plain LLM), give it a one-paragraph intent and dev-environment
> autonomy, and it can run a complete Dark Factory build: **intent → semantics → design →
> tests → code → infra → live proof → shipped + documented.** This file inlines the full
> content of all 10 Dark Factory skills (`dark-factory-build` + 9 `df-*`) so the agent needs
> nothing else. It is the conductor's score *and* every player's part, in one page.

**Audience:** an LLM agent **without** Claude Code skills (ChatGPT / Gemini / API). If you
*do* have the `df-*` skills installed, use them directly and work through the stage guides in
[`stages/`](../stages/) instead — this doc is the skill-less substitute.

**What this replaces:** the skill files in [`skills/`](../skills/)
(`dark-factory-build/SKILL.md`, `df-*/SKILL.md`). Their normative content is inlined below.
The [`reference/`](../reference/) folder holds optional deep-dives; you do **not** need
them to run a build from this doc.

**How to use it:** read Parts 0–2 once (the model + the cross-cutting disciplines), then run
Part 3 stage by stage, gating each stage with Part 2's adversary gate, ticking off Part 4's
checklist. Part 5 tells you how to emulate the things a skill-less runtime lacks (parallel
sub-agents, the Skill/Task tools). Part 6 is a worked example; the Appendix is copy-paste
prompts.

---

## Part 0 — The mental model: the data-transform lens

> *This is the vocabulary every later part is written in. If a later section says `effect`,
> `LOCAL`, or `authority`, it means exactly what is defined here. Read this first.*

An application is **not** a machine with features; it is a **data-transformation algorithm**:
input data → transforms → output data, carrying state forward in time. Modelling a system this
way collapses the design space and concentrates effort where the risk actually lives. Every
stage below is this one model applied at one point in the pipeline.

### Two primitives + two tags

- **Data node** = a schema + its single-datum invariants, carrying four context fields:
  - `location` — which store/system holds it now. *Not* a trust signal.
  - `origin` — where it came from (web / mobile / scan / 3rd-party API / another service).
    Travels for audit only; **never** a trust signal.
  - `authority` — is this the **system-of-record** for this fact? A ranking; the conflict
    resolver. (A bank owns "balance"; you may cache it, but the bank wins.)
  - `governance` — security class (PHI/PII), retention, residency. Travels with the datum.
- **Transform** = `(state, inputs) → (state', outputs)`, tagged one of:
  - `pure` — replayable, no side effect, no marker needed.
  - `effect` — an **irreversible world-change** (send / charge / publish / notify / external
    write). **Must** carry an **idempotency key** (retry ≠ double-action) **and** a
    **compensation** path (the hand-written un-transform / saga rollback).
- **Validation rule** = a predicate over data that must hold. The only axis that changes the
  architecture is its **enforcement locus**:
  - `LOCAL` — checkable at **one** ingress/commit with all operands present → **reject at the
    door**.
  - `GLOBAL` — ranges across records / systems / time → **flag, then reconcile by `authority`**.
- **Authority** = the resolution policy a GLOBAL failure appeals to (who wins on conflict;
  drives reconciliation).

### The two rules that are the heart of the model

1. **The boundary is the data.** Every input edge of every unit (function, service, DB, queue)
   is a trust boundary. Data crossing in is **untrusted until validated *here***. Trust is
   **non-transitive and does not travel** — it is re-earned at every crossing. Your own
   services can be corrupt; a message off your own bus still gets validated.
2. **Authority ≠ origin.** A 3rd-party (bank, exchange) can be the authoritative source-of-truth
   that overrides your own well-formed cached copy. "Ours vs theirs" carries zero trust signal.

### Why `pure | effect` earns its keep

Mechanically everything is data transformation — but that reduction loses **reversibility**.
Proof it's real: idempotency keys, at-least-once delivery, and saga compensation exist **only
because** effects are not reversible. So tag every transform: `pure` gets a schema and moves on;
`effect` gets an idempotency key + a compensation path. **That is where all the engineering
goes.**

### Lens anti-patterns (catch these in every stage)

- **Sticky trust** — a `trusted` flag that travels downstream so consumers skip their own
  ingress validation.
- **Origin-as-trust** — "it's from our own service, so it's safe." Internal can be corrupt.
- **Authority-by-convenience** — treating the local cache as truth because it's local.
- **Effects modelled as pure outputs** — discovered only when a retry double-acts.
- **Validation by location guess** — enforcing a GLOBAL rule at one edge, or deferring a LOCAL
  rule to async reconcile.

---

## Part 1 — The pipeline

Run the stages in order. Each stage has a concrete **artifact**, an **exit gate**, and a
**ticket**. Earlier stages gate later ones: *a cold reader must be able to build the next stage
from the previous artifact alone.*

| # | Stage | Artifact (commit it) | Gate |
|---|---|---|---|
| 0 | **Frame** | the shared model (data nodes, transforms `pure\|effect`, validation rules, authority) | the lens is applied, not skipped |
| 1 | **Product Owner** | `docs/dark-factory/01-product-owner.md` — Vision, Requirements as data contracts + validation rules, Test Scenarios, non-goals | cold-SA test |
| 2 | **Solution Architect** | `02-solution-architect.md` — Data Model, Data Flow (transform graph; idempotency + compensation per effect), Service Map, enforcement loci (LOCAL/GLOBAL) | cold-Dev / cold-Infra + coverage |
| 3 | **Infrastructure** | `03-infrastructure.md` — DTAP, where data lives, trust boundaries → mechanisms, secrets, deploy/live-test runbook | renders live data, no implicit trust |
| 4 | **Observability** | `04-observability.md` — the consumable surface (dashboards + queryable traces keyed to scenarios) | **verified rendering live data** |
| 5 | **Developer (TDD)** | the code — RED→GREEN→REFACTOR; test list = PO rules + scenarios | asserting tests green (+`-race`) |
| 6 | **Adversary gate** | a blind verifier's evidence (fuzz/holdout + exit code), re-run by you | evidence ⊢ promise |
| 7 | **QA** | `05-qa-*.md` — Works? verdict + unforgeable evidence per scenario (by correlationId / tx hash), holdout result | evidence-backed, holdout run |

**The single source of truth:** the PO **Requirements (validation rules) + Test Scenarios** flow
through every later stage. SA assigns each rule an enforcement locus; the developer's test list
**is** those rules; QA's evidence standard **is** those scenarios. **Never invent acceptance
criteria or a test list downstream — always derive them from the PO outputs.** Note: Stages 3
(Infra) and 5 (Dev) are **parallel lanes** — they don't depend on each other, only on Stage 2.

---

## Part 2 — Cross-cutting disciplines (apply at every stage)

### 2.1 Promise Theory — how to dispatch and trust *any* worker (sub-agent, separate chat, or yourself-in-a-fresh-pass)

A worker you delegate to is an **autonomous promiser**: it makes a **best-effort** promise, not
a guarantee, and lives in its own context. You don't command it — you specify a promise and
**assess the evidence** it returns. Apply this **every time** you delegate, including to a fresh
reasoning pass of yourself.

**Before you dispatch:**
1. **State the promise precisely** — the exact deliverable **and** the **unforgeable evidence**
   it must return. Not "do X and tell me it's done", but "return the file path + `wc -l`, the
   test exit code + counts, the commit SHA, the quoted result." Evidence the worker can
   fabricate (its own "I did it") is worthless.
2. **Blind synthesis (anti-Goodhart)** — give a *build* worker the **spec**, **not** the
   acceptance/holdout cases it will be judged against. Otherwise it optimises for the cases, not
   the spec (`if input == known_case: return known_answer`). Hold the acceptance evidence on the
   dispatcher side.
3. **Bound it** — scope, budget/turn caps, a clear definition of done.
4. **Pin context, not just the prompt** — name the exact tools/files it needs so the result is
   reproducible.

**On return — the seam is a trust boundary:**
5. **Its output is untrusted input.** Error and prompt-injection cross the wrap. A self-report
   ("done / all passing") is a **claim**, not an assessment.
6. **Verify evidence ⊢ promise** (§2.2). If the deliverable arrives without the unforgeable
   evidence you asked for, treat it as **UNVERIFIED** — re-dispatch with a tighter ask or check
   it yourself.
7. **One worker never vouches for another.** Each result is verified independently; a failed /
   empty result is dropped, not assumed-good.

> **The one-line discipline:** make the evidence unforgeable and pre-specified, then verify the
> evidence proves the promise. Never accept the self-report.

### 2.2 The adversary gate — the verification primitive used at every stage exit

Every stage handoff is a **promise**; every gate is an **observer**. The agent that did the work
is the *promiser*; whether the promise was kept is decided by the *observer*, **never** the
promiser.

- **The verifier validates only that the evidence proves the promise — it does NOT redo the
  work.** That asymmetry is what lets one cheap observer police many expensive workers.
- **Trust the evidence *less* than the promise.** Evidence the promiser fully controls is weak.
  Demand evidence that is **independent and unforgeable** — produced by the *environment* or
  *another agent*: exit codes from asserting tests, dashboards rendering live data,
  reconciliation against an external authority, immutable audit/tx entries — never a self-printed
  "PASSED".
- **Blind synthesis** — the worker must **not** have seen the acceptance cases, or it games the
  test. Verify against cases it never saw.
- **Two checks, never conflated:** (a) `evidence ⊢ promise P` — was the declared promise kept?
  (the gate's job); (b) `P = the needed promise` — was it the *right* promise? (guaranteed by
  correct upstream specification; a perfectly-kept *wrong* promise still fails the mission).
- **A gate that never fails is not a gate.** In real runs, gates failed something real at ~4 of
  6 stage exits. If your gate keeps rubber-stamping, you are not attacking hard enough.

**How to run a gate (4 steps):** (1) restate the promise + the **pre-declared** evidence
standard (fixed with the task, not negotiated now); (2) demand the unforgeable evidence — if
it's a self-report or self-produced artifact, mark **unverified**; (3) prefer a **mechanism**
over a judgment, and if the verifier is itself an agent, use **independence + diversity** (an
adversarial panel), never one agent vouching for another; (4) verdict **Pass / Conditional /
Fail**, with the evidence cited.

### 2.3 Autonomy + hard stops

**Default is action in dev / test / local / non-prod.** Resolve ambiguity via the toolchain
(memory → codebase → internet → docs) **before** asking. Pushing to a **feature branch / your
own project repo** is fine.

**HARD-STOP and ask for explicit, scoped go-ahead before any irreversible real-world action:**
prod-DB writes, prod deploys, merging PRs / pushing to a protected branch, outbound email /
public posts, customer-visible config, **and any financial transaction or on-chain spend.** A
live test with real funds requires explicit authorization (e.g. "spend from this burner, small
amounts") — and even then, run preflight checks first (verify balances, decimals, that you're
not clobbering existing state). Authorization granted **once for one action does not generalize**
to the next.

### 2.4 Documentation — everything, at every stage

The build is **not done** until it is documented in (at least) two places (three if you have a
memory system):
1. **DF spec docs** in `docs/dark-factory/` (01–05) — committed *with* the code.
2. **Tickets** (§2.5) — status moved + evidence (commit SHAs, tx hashes, test counts) recorded
   per stage.
3. **Memory** (if available) — a durable record at each meaningful checkpoint, not just at the
   end. Long builds outlive a context window; checkpoint or lose state.

**Commit cadence:** one commit per TDD unit / per stage, pushed frequently to a feature branch.
Each commit message states **what was verified** (build / vet / test / `-race` green, etc.).

### 2.5 Ticketing + story points

Pick the tracker the user names (Jira, Monday, GitHub Issues, or a markdown table if none).
If unspecified, **ask once** which tracker + project/board.

**Structure:** one **epic** for the build; one **story per stage** (and per TDD unit when units
are independent). Move each ticket through the workflow as you go (Ready → Doing → Review/
Need-Input → Done), and on completion fill the evidence fields (**Refs** = commit SHAs / file
paths / memory IDs; **Verification** = the exact command + result that proves done).

**Story points — calibrate at `2 SP = 1 day of work for a human`** (this is the standing rule).
This is a **human-effort** estimate (what the work would take a skilled human), **not** how fast
the agent does it. Only for trackers that record points.

| SP | Human effort | Examples |
|---|---|---|
| 1 | ~½ day | small doc, one validation rule + tests, a config/wiring change |
| 2 | ~1 day | a DF stage doc, a self-contained TDD unit (engine/client), a service skeleton |
| 3 | ~1.5 days | cross-cutting change, multi-file refactor, a new integration leg |
| 5 | ~2.5 days | a new subsystem, the correctness-critical core + its adversarial gate |
| 8 | ~4 days | architectural change / new pattern with extensive testing |
| 13 | ~6.5 days | **too big — break into smaller stories** |

Rules: every points-tracked ticket gets an estimate; anything above 8 is decomposed; if you
can't estimate, ask.

---

## Part 3 — The stages, fully inlined

> Each stage: **purpose · what it produces · instructions · exit gate · don'ts.** Run them in
> order; gate each with §2.2 before trusting it; ticket each per §2.5.

### Stage 1 — Product Owner (define the *semantics*)

**Purpose.** Turn messy intent into a self-contained, testable target. The PO owns the
*semantics* (domain truth); the Solution Architect formalizes them. Through the lens:
**Requirements = data contracts + validation rules; Test Scenarios = those rules as cases.**

**Produces** (`01-product-owner.md`): **Vision · Requirements · Test Scenarios** (+ non-goals).

**Per capability, capture the data and the rules over it:**

| Field | What to capture |
|---|---|
| **Data (schema)** | the fields collected, conceptually |
| `origin` | real-world source: web form · mobile · scanned doc · 3rd-party API · another service (audit only — never a trust signal) |
| `authority` | who is system-of-record for this fact (a domain fact, e.g. "the bank owns balance") |
| `governance` | PHI/PII class, retention, residency |
| **Validation rules** | the business predicate + its **scope** (holds within one record, or must agree across systems/time) |
| **Effect?** | does the acceptance criterion touch the outside world (send/charge/notify/write-external)? Flag it so SA assigns idempotency + compensation |

You state **what must be true and who is authoritative**; the SA decides **where it's checked
and how**.

**Instructions.**
1. **Vision** — why / what / who / value, and the **non-goals** ("what this is *not*").
2. **Requirements** — capabilities + testable acceptance criteria, each as a data contract +
   validation rule (table above).
3. **Test Scenarios** — concrete real-life situations, not screen assertions. Frame each as a
   **state change**: `State 0 (precondition) → Trigger (input) → State 1 (end state)`, with
   happy path + edge + failure modes. These are the executable evidence standard downstream.
4. **Label every claim** Confirmed / Inferred / Assumption / Open — never silently invent product
   facts.
5. Mark any outside-world trigger as an **effect**.

**Exit gate (the cold-SA test).** Could a Solution Architect who knows nothing about the product
design the right architecture from Vision + Requirements + Test Scenarios **alone**? Is there any
way to build the **wrong thing** and still satisfy the package? If yes, clarify before handoff.

**Don't.** Don't formalize schemas / Avro / enforcement locus (SA's job). Don't write scenarios
that test screens instead of real work. Don't omit non-goals (the biggest scope-creep guard).

### Stage 2 — Solution Architect (formalize the transform graph)

**Purpose.** Answer **how**. The PO defined the semantics; the SA **formalizes** — turns each into
a schema/contract, assigns each rule its enforcement locus + mechanism, tags transforms.

**Produces** (`02-solution-architect.md`): **Data Model · Data Flow · Service Map.**

- **Data Model = data nodes.** Each entity's schema + single-datum invariants + context
  (`location`, `origin`, `authority`, `governance`) + the **message contracts** (e.g. Avro)
  between services. Declare the `authority` (system-of-record) for **every** fact that exists in
  more than one place.
- **Data Flow = the transform graph.** Each step `(state, in) → (state', out)`, tagged
  `pure | effect`. Every `effect` carries an **idempotency key + compensation** in the flow.
  Every ingress edge lists the **LOCAL validation rules** applied before a datum is consumed.
  **One path per PO Test Scenario.**
- **Service Map = transform ownership + boundaries.** Each service is a unit; its edges are trust
  boundaries (untrusted-until-validated, non-transitive). **Also name the Observability Surface**
  — the required dashboards/panels mapped to PO scenarios (Stage 4).

**Formalization handoff (PO → SA):** for each validation rule, assign its **locus** (`LOCAL` →
reject at an edge; `GLOBAL` → reconcile by `authority`) and its **mechanism** (XSD / Schematron /
DB constraint / reconciliation job). Tag transforms `pure`/`effect` with idempotency +
compensation. Do **not** re-decide domain facts — if one is missing or wrong, loop back to PO.

**Instructions.**
1. Decompose requirements into single-responsibility services. If a service needs "and" to
   describe it, split it.
2. Draft the **Data Model** (entities, ownership, PHI/PII class, retention, authority, contracts).
3. Draw the **Data Flow** — one path per PO scenario: in → transform → store → out; **pub/sub +
   async by default**; every sync hop gets an ADR (architecture decision record).
4. Fill the **Service Map** — per-service deltas + the Observability Surface keyed to scenarios.
5. Tag every transform; give effects idempotency + compensation. Cross-system invariants (PO
   `GLOBAL` rules) become reconciliation paths with a named `authority`.

**Exit gate.** **Cold-Developer test** (a fresh dev can build every service from these three docs
alone, no invented contracts) · **Cold-Infra test** (a fresh infra architect can deploy across
DTAP, no guessed trust boundaries) · **Coverage** (every PO scenario has a Data Flow path; every
effect has idempotency + compensation; every cross-system fact has a declared authority).

### Stage 3 — Infrastructure (where data lives + the boundaries)

> Runs **in parallel** with Stage 5 (Developer); both depend only on Stage 2.

**Purpose.** Decide **where** the architecture runs and make it deployable across all
environments. Places the **data nodes** and draws the **boundaries**.

**Produces** (`03-infrastructure.md`): the **Deployment & Infrastructure Spec**.

**What Infra does.**
- **`location` per data node** → storage class, region, residency. The `governance` tag
  (PHI/PII, residency) is enforced by **where** you put the data.
- **Every unit edge is a trust boundary.** "Inside the cluster is trusted" is the sticky-trust
  anti-pattern. **Secrets/IAM enforce the boundary, not network position.** Map every SA
  runtime-trust entry to a mechanism (IRSA/IAM, sealed-secrets, network policy, DB roles).
- **Build + verify the Observability Surface** — stand up dashboards + datasources + log/trace
  sinks and **verify they render live data** (Stage 4's acceptance bar). Ship dashboards **as
  code** (`deployments/grafana/…`), not hand-clicked.
- **Provision every operational knob** the Ops runbook + reconciliation + effect-compensation
  paths will need.

**Reversibility (the autonomy gate).** Building manifests is reversible and high-autonomy;
**applying them to production is irreversible** → a **human gate** regardless of how green the
evidence is (§2.3). A production change requires a ticket + announcement.

**Instructions.** (1) Start from the platform's standard environment progression (Dev → Test →
Acceptance → Production), base + overlays; record per-product **deltas** only. (2) Map every SA
runtime-trust entry → enforcement; every observability entry → a sink; every knob → a
provisioning step. (3) Verify dashboards render live data and the `$correlationId` query returns
real cross-service results. (4) Write the deploy procedure QA will follow.

**Exit gate.** Every service has an overlay per target cluster; every secret a source + rotation;
every alert a sink; every knob a provisioning step; **no implicit trust**; ≥3 replicas on
data-path services; the Observability Surface **verified rendering live data**.

### Stage 4 — Observability (the agents' eyes)

**Purpose.** Observability is the **sensory apparatus the agents use to build, deploy, and test**
— not optional garnish. Emitting telemetry is necessary but **not sufficient**: a
`:9090/metrics` endpoint nobody can *see* is not observability. Make the **consumable surface** a
named, verified deliverable.

**Produces** (`04-observability.md`): the dashboards + queryable log/trace views, keyed to PO
scenarios.

> **Rule of thumb:** if an agent cannot answer *"did scenario TS-0x run, and where did it succeed
> or fail?"* by looking at a dashboard or running **one** query, the system is not observable
> yet — no matter how many metrics it emits.

**The three legs — Emit → Surface → Act.**

| Leg | Question | Owner | Artifact |
|---|---|---|---|
| **Emit** | Is telemetry produced? | Developer | `:9090/metrics`, JSON logs w/ `correlationId`, `:8080/healthz`, DLQ depth |
| **Surface** | Can a human/agent *see and query* it? | SA designs · Infra builds · QA verifies | dashboards + queryable log/trace views that render live data *(the historically missing leg)* |
| **Act** | Does it fire before customers notice? | SA names · Infra wires | alerts → a sink |

**Required baseline dashboard set (the floor):** Flow/saga (end-to-end path of each PO scenario)
· Throughput · **Tiered failure log filtered by the log *level field* (`"level":"ERROR"`), NOT a
substring `(?i)error`** (substring matching floods false positives) · Correlation/trace lookup
(a `$correlationId` variable pulling every log + span across services) · DLQ + queue depth ·
Latency (p50/p95/p99) · System health. Panels keyed to PO scenarios.

**The acceptance bar — "verified rendering live data."** A dashboard that POSTs valid JSON but
shows "No data" is **not** delivered. Every view reachable at a known URL; every panel renders
live data (against the datasource, not just schema-valid); `$correlationId` returns real
cross-service results; every alert rule evaluates. **Verification is by observation, not
assertion.**

**Don't.** Emit-only · schema-valid-but-no-data · substring failure filters · hand-clicked
dashboards (lost on rebuild) · human-only access with no programmatic path for the QA/Dev agent
in dev/test.

### Stage 5 — Developer, test-first (TDD)

> Runs **in parallel** with Stage 3 (Infrastructure).

**Purpose.** Build every service **test-first**: RED → GREEN → REFACTOR, one case at a time. Each
test is an executable validation rule. The Developer owns **unit + integration** tests (green
before handoff); QA owns E2E + holdout.

**The loop.**

| Step | Do | Done when |
|---|---|---|
| **RED** | Pick one case. Write the smallest test that encodes it. Run it — it fails. | Fails for the *right reason* (missing behaviour, not a typo). |
| **GREEN** | Write the **minimal** code to pass. Honour the contract; no extra features. | New test passes, all existing tests still green. |
| **REFACTOR** | Improve *structure* (names, duplication, size) without changing *behaviour*. Re-run after each change. | Still green, cleaner. A red test = you changed behaviour → undo. |

**Where the test list comes from (don't invent it).**
- **LOCAL validation rule** → unit test: feed bad input at the edge, assert it is **rejected**.
- **GLOBAL validation rule** → integration/reconciliation test: assert the invariant + the
  `authority` tie-break.
- **PO Test Scenario** (`State 0 → Trigger → State 1`) → unit/integration test asserting the end
  state (happy/edge/failure).
- **effect** transform → **idempotency test** (replay → one action) + **compensation test**
  (failure → clean rollback).
- **pure** transform → plain input → output unit test.

**Blind synthesis (anti-Goodhart).** Your own tests drive your build loop, but the **acceptance
evidence (PO Test Scenarios, the QA holdout) is withheld** — you're verified against cases you
never saw, which proves you built the *spec*, not your own test. Don't build to the holdout:
`if known_input: return known_answer` is the lookup-degeneration failure.

**GREEN discipline.** Minimal code only; honour the exact contracts (no invented schemas);
**config over code**; language gotchas matter (in this stack's shared messaging library, `Log.Error` panics — use `Log.Warn`;
use **decimal** types for money, never floats).

**Worked example — a LOCAL validation rule (Go + Python).** Rule: a vitals reading with no
`correlationId`, or heart rate outside 0–300, is rejected.

```go
// RED — failing test first (table-driven)
func TestIngestVitals_Validation(t *testing.T) {
    cases := []struct{ name string; in VitalsReading; wantErr error }{
        {"missing id", VitalsReading{HeartRate: 80}, ErrNoCorrelationID},
        {"hr too high", VitalsReading{CorrelationID: "abc", HeartRate: 350}, ErrHeartRateRange},
        {"valid", VitalsReading{CorrelationID: "abc", HeartRate: 80}, nil},
    }
    for _, c := range cases {
        t.Run(c.name, func(t *testing.T) {
            if _, err := IngestVitals(c.in); !errors.Is(err, c.wantErr) {
                t.Fatalf("got %v, want %v", err, c.wantErr)
            }
        })
    }
}
// GREEN — smallest code that passes
func IngestVitals(v VitalsReading) (Accepted, error) {
    if v.CorrelationID == "" { return Accepted{}, ErrNoCorrelationID }
    if v.HeartRate < 0 || v.HeartRate > 300 { return Accepted{}, ErrHeartRateRange }
    return Accepted{ID: v.CorrelationID}, nil
}
```
```python
import pytest
from vitals import ingest_vitals, NoCorrelationID, HeartRateRange

@pytest.mark.parametrize("reading, expected", [
    ({"heart_rate": 80}, NoCorrelationID),
    ({"correlation_id": "abc", "heart_rate": 350}, HeartRateRange),
    ({"correlation_id": "abc", "heart_rate": 80}, None),
])
def test_ingest_vitals(reading, expected):
    if expected is None:
        assert ingest_vitals(reading)["id"] == "abc"
    else:
        with pytest.raises(expected):
            ingest_vitals(reading)
```

**Exit gate.** Every validation rule + scenario touching this service has a green test; every
effect has idempotency + compensation tests; `go test ./... -race` / `pytest` all green.

**Don't.** Assertion-free tests · testing the framework/bus instead of your transform ·
code-before-test · tests bound to internals instead of the rule · skipping `-race`.

### Stage 6 — Adversary gate (blind verification of the build)

This is §2.2 applied to the build output. Dispatch a **blind verifier** (a separate context /
chat / fresh pass) that **never saw your tests**, give it the **spec only**, and have it derive
its own attack — a fuzz, a holdout suite, an edge battery. **Re-run its evidence yourself**
(the exit code, the case count). A missing piece of promised evidence ⇒ **UNVERIFIED** ⇒
re-dispatch or check independently. Commit the verifier's test as a **regression guard**.

### Stage 7 — QA (validation rules executed; the observer)

**Purpose.** Deploy the built system, run the PO's real-life scenarios **against the deployed
system**, and return a **Works?** verdict backed by **unforgeable evidence**. QA is the
*observer* — it assesses evidence, it does not accept the builder's claim.

**Produces** (`05-qa-*.md`): the verdict + per-scenario evidence.

**What QA does.**
- Each PO acceptance criterion is a validation rule → a test. **LOCAL** rules → feed bad input at
  an edge, assert **rejected**. **GLOBAL** rules → **reconciliation tests** across systems/time,
  asserting the invariant + the `authority` tie-break.
- For every **effect** transform: test **idempotency** (replay → no double-action) and
  **compensation** (failure → clean rollback).
- **Capture evidence by correlationId** — a scenario "passed" only if its run is traceable in
  observability (metric/log/trace/tx hash). **Observation, not assertion.**

**The holdout = the anti-Goodhart firewall.** QA holds the acceptance/holdout cases the Developer
**never saw**. Verifying the build against held-back cases is what proves it implemented the
*spec*. **Never hand the holdout to the builder.**

**Pre-test gate (the eyes must work first).** Before running scenarios, confirm the Observability
Surface renders live data and the `$correlationId` query resolves (Stage 4). Broken eyes block
the verdict — evidence capture is impossible without them.

**Instructions.** (1) **Map, don't invent** — every test case starts from a PO scenario (one
scenario → ≥1 case). (2) Run the pyramid in order: unit (from Dev) → integration → E2E → holdout;
stop at the first quality-gate breach. (3) Capture evidence by correlationId; record failures too
(publish bad alongside good). (4) **Verdict: Pass / Conditional / Fail.** A "pass" with no
observability evidence is not earned. Route a Fail to the owning lane (code → Developer, deploy →
Infra, requirement → PO).

**Don't.** Accept "done / tests pass" as the verdict · skip the holdout · auto-promote past the
human gate in regulated (HIPAA) contexts.

---

## Part 4 — End-to-end checklist (track these as you go)

- [ ] Recall + frame the work through the data-transform lens (Part 0); confirm tracker +
      project/board.
- [ ] Create the epic + per-stage stories (points at 2 SP = 1 human-day where tracked).
- [ ] **Stage 1 PO** doc → gate (cold-SA test) → ticket Done + committed.
- [ ] **Stages 2–4** (SA / Infra / Observability) — produce artifacts; gate each (file +
      citations) before trusting; tickets Done. *(Infra and Dev are parallel lanes off SA.)*
- [ ] **Stage 5 TDD** — RED→GREEN→REFACTOR per unit; **keep the correctness-critical core
      in-house** (money math, security logic — never delegated); commit + push per unit; tickets
      Done.
- [ ] **Stage 6 adversary gate** — blind verifier, withheld holdout; **re-run its evidence
      yourself**; commit the regression test.
- [ ] **Stage 7 QA** — execute scenarios, capture unforgeable evidence (correlationId / tx hash),
      write `05-qa-*.md`, verdict.
- [ ] **Full gate:** build + vet + tests (+ `-race` / static where applicable) green; deploy/live
      artifacts render.
- [ ] **HARD-STOP check** before any prod / financial / outbound action — ask if crossed (§2.3).
- [ ] Save to memory (if available); **close the epic.**

---

## Part 5 — Adaptation notes for skill-less agents (ChatGPT / Gemini / plain API)

The skills assume a Claude Code runtime with a `Skill` tool and a `Task` tool for parallel
sub-agents. You have neither. Translate as follows.

| Skill-runtime feature | How to emulate it without skills |
|---|---|
| **The `Skill` tool** (load a stage's instructions) | This document **is** every skill, inlined. Re-read the relevant Part 3 section when you enter a stage. |
| **Parallel sub-agents** (Task tool) | Do the lanes **sequentially** in one thread, **or** open a **separate chat window/session per lane** and have the human relay artifacts between them. Either way, keep each lane's context isolated so blind synthesis holds. |
| **A blind verifier sub-agent** (adversary gate) | Start a **fresh conversation** (or a clearly demarcated new reasoning pass) that is given the **spec only** — never your tests. Ask it to *refute*, not confirm. Its output is untrusted until you re-run its evidence. |
| **Blind synthesis** (withheld holdout) | Physically keep the holdout/acceptance cases in a section you do **not** paste into the builder context. If you are both builder and verifier in one thread, write the build **first and commit it**, *then* reveal the holdout and test against it — order enforces the firewall. |
| **Memory / [Engram](../starter-kit/instance/AUTHENTICATION.md#engram) checkpoints** | Write a running `docs/dark-factory/00-build-log.md` (or have the human keep a scratchpad) and re-read it when context gets long. |
| **Jira/Monday MCP tickets** | If no tracker is wired, keep a **markdown ticket table** in `docs/dark-factory/tickets.md` (Epic + one row per stage: ID, title, status, SP, Refs, Verification). Same discipline, plain file. |
| **Shell/test execution** | If you can run code (Code Interpreter / a local runner), run the real test commands and paste the **real** output as evidence. If you **cannot** execute, you **cannot** produce unforgeable evidence — say so explicitly, mark those gates "code-evidenced, not executed", and have the human run the commands and paste results back. **Do not claim a test passed you did not run.** |

**The non-negotiables survive translation:** semantics-first (PO before SA), derive-don't-invent
(test list = PO rules), blind synthesis, verify-don't-trust (re-run evidence), and the hard-stop
boundaries (§2.3). If your runtime can't honour one of these, **flag it to the human rather than
silently dropping it.**

**Keep the correctness-critical core yourself.** Even when you delegate lanes, money math,
security logic, and the load-bearing algorithm are built and owned by the conductor — never
handed to an untrusted worker.

---

## Part 6 — Worked example (fully fictional)

> **This example is invented.** Nothing here is drawn from a real engagement, and nothing in
> this document should be. A worked example built from real work is how a public repo leaks —
> the shape teaches, the identity only exposes. If you adapt this doc, keep your examples
> fictional too, and run the publish gate before you push.

**"MeterSync" — reconcile smart-meter readings against a billing ledger. One session.**

**1 — Frame it with the lens.** Two data nodes: the meter feed (`origin` = device, `authority`
= the meter itself) and the billing ledger (`authority` = finance). The centrepiece validation
rule writes itself once you name the authority: **VR-1 — a reading may correct a ledger line,
but a ledger line may never rewrite a reading.** That single sentence decides the whole design.

**2 — PO defines semantics, not solutions.** Vision, the data contract for both nodes, six
validation rules, and eleven test scenarios — including the three nobody wants to think about:
a duplicate reading, a reading that arrives out of order, and a meter that reports a value it
already reported at a different timestamp. The scenarios are the spec. No later stage invents
a test.

**3 — SA formalises the transform graph.** Ingest (`pure`) → normalise (`pure`) → reconcile
(`pure`) → post-adjustment (`effect`). Exactly one `effect` in the chain, and it is idempotent
on `(meter_id, reading_ts)`. Each of the six validation rules is assigned an enforcement locus.
Rules with no locus are the finding — two were unenforceable as written and went back to PO.

**4 — Fan out under Promise Theory.** Infra and Observability specs to parallel workers. Each
promise named its evidence: the file path, the line count, and `file:line` citations resolving
to real code. Both returns were re-checked against the repo. One had invented a service that
did not exist — caught by reading the citation, not by reading the summary.

**5 — TDD the core in-house.** The reconciliation maths is the part where being wrong is
expensive and a test can prove you right, so it is not delegated. RED → GREEN → REFACTOR, one
commit per unit, the test list taken verbatim from the PO scenarios.

**6 — Adversary gate, blind.** A verifier that never saw the tests derived its own edge cases
from the spec and found an ordering assumption the suite had missed: two readings sharing a
timestamp. The conductor re-ran that evidence rather than accepting the report, confirmed it,
and committed the case as a regression guard.

**7 — QA executes the rules.** Eleven scenarios, raw evidence per scenario keyed by
correlationId, pulled from the dashboards built in stage 4. Verdict recorded against evidence,
not against confidence. The deploy step stopped at the environment boundary and asked.

**What the discipline bought.** Every artifact was checked against something that does not
flatter it: the PO package against a cold reader, the design against the as-built code, each
worker against a re-run of its own cited evidence, the QA table against raw transcripts, and
the final verdict against the evidence rather than the summary. Four of those five checks found
something. The one that found nothing was the one where the work had been done in-house.

## Appendix A — Kickoff prompt template (paste, adapt)

```text
Design and build <FEATURE> for <PRODUCT>. Run it as a Dark Factory build, autonomously,
following the Dark Factory priming doc you have been given.

1. Write all stage docs (PO, SA, Infra, Observability, QA) under docs/dark-factory/.
2. Apply the data-transform lens throughout (data nodes + pure/effect transforms +
   LOCAL/GLOBAL validation rules + authority).
3. Develop test-first (TDD: RED→GREEN→REFACTOR) from the doc specs.
4. Deploy to <DEV ENV> and test.
5. Tests = unit + integration + live E2E (<real auth mechanism> + browser automation
   against the actual page; you may use my <test user>).

Dispatch the parallel lanes / the blind verifier under Promise Theory (spec in, unforgeable
evidence out, self-reports never trusted; withhold the holdout from builders).
Keep the correctness-critical core yourself.

Work on branch <branch>. <ENV> is a dev environment — full autonomy there; HARD-STOP and ask
me before anything prod / financial / outbound / irreversible.

Track work as <tracker, or a markdown ticket table> with points at 2 SP = 1 human-day.

Any operator decisions you need from me before you start? Put them to me in one shot.
```

The closing question matters: surface **operator decision points** (authority model, placement,
key choice, capacity trade-off) **before** starting, not mid-build.

## Appendix B — Reusable gate / verify prompts

**Adversary gate over a stage package:**
```text
You are the Dark Factory ADVERSARY GATE for the <stage> package at <path>. Your job is to
REFUTE it, not confirm it. Audit <package> against <ground truth: PO docs / as-built code /
raw evidence files>. For every claim, quote the exact line(s) that back or contradict it
(with file path). Specifically attack: <the 3-5 load-bearing claims>. Return: per-item
verdict-supported YES/NO with quotes; gate decision UPHELD / UPHELD-WITH-NOTES / REFUTED +
defect list. Read-only; no fixes.
```

**Verifying a returned worker (do this yourself, every time):**
```text
Re-run their exact test command and build command verbatim; grep for the quoted code lines;
only then commit, with a message that records the verified counts. A self-report is not
evidence.
```

**Live QA scenario with a typed-rejection edge:**
```text
State 0: <precondition + how you'll prove it>. Trigger: <exact request/click>.
State 1: <expected outcome + the exact typed error body for the edge variant>.
Evidence: <transcript file + DB readback + metric delta>, filed by correlationId.
```

---

## Appendix C — Glossary (one-liners)

- **Data node** — a schema + invariants + `location`/`origin`/`authority`/`governance` context.
- **`pure` / `effect`** — replayable transform / irreversible world-change (needs idempotency +
  compensation).
- **LOCAL / GLOBAL** — validation checkable at one edge (reject) / across systems-time (reconcile
  by authority).
- **`authority`** — the system-of-record that wins on conflict. **Never** implied by `origin`.
- **Promise Theory** — workers make best-effort promises; you verify unforgeable evidence, never
  the self-report.
- **Blind synthesis** — withhold the acceptance/holdout cases from the builder so it builds the
  spec, not the test.
- **Adversary gate** — an observer that checks `evidence ⊢ promise`, never redoes the work.
- **Unforgeable evidence** — produced by the environment or another agent (exit codes, live
  dashboards, tx hashes), not self-printed.
- **Observability Surface** — dashboards + queryable traces that **render live data**; a verified
  deliverable, not telemetry emission.
- **Hard stop** — an irreversible real-world boundary (prod / money / outbound) where autonomy
  ends and you ask.

---

*This priming doc inlines: `dark-factory-build`, `df-data-transform-lens`, `df-product-owner`,
`df-solution-architect`, `df-infrastructure`, `df-observability`, `df-tdd-developer`,
`df-dispatch-subagents`, `df-adversary-gate`, `df-qa`. The authoritative skill sources live
alongside this file in `skills/`. Last synced from those sources on 2026-06-13.*