@nextcommerce/campaigns-os 1.33.0

package/docs/versioning.md

@@ -0,0 +1,55 @@
+# Versioning
+
+This repo uses independent compatibility versions:
+
+- package version: `1.33.0` — equals `surface_version` in
+  `contracts/supported-surface.json` (`check:supported-surface` enforces it)
+  and is the version published to the npm registry; `+agent.N` changelog
+  sections are same-surface changes and are not published on their own
+- Build Packet: `campaign-runtime-build-packet/v0`
+- Build Context: `campaign-runtime-build-context/v0`
+- Assembly Report: `campaign-runtime-assembly-report/v0`
+- Design Source Package: `campaign-design-source-package/v0`
+- Workflow Finding: `campaigns-os-workflow-finding/v0`
+- QA Verdict: `campaigns-os-qa-verdict/v0` (JSON Schema:
+  `schemas/campaigns-os-qa-verdict.v0.schema.json`; the emitted
+  `schema_version` field is the literal `"1.0"` — it predates the
+  slash-versioned naming and the portal receiver validates that same literal,
+  so the emitted value cannot change without a breaking shape change)
+- QA Verdict sidecar projection: same `"1.0"` literal, projection guarantees in
+  `schemas/campaigns-os-qa-verdict-sidecar.v0.schema.json` (one contract, two
+  schema files — the sidecar is an allowlist projection, never a second lineage)
+- CampaignSpec: `4.2`–`4.3` (JSON Schema: `schemas/campaign-spec.v4.schema.json`)
+- starter-template agent contract: `1`
+- commerce surface catalog: `2`
+- Tooling Orientation: `campaigns-os-tooling-orientation/v1`
+- Release Ledger: `campaigns-os-release-ledger/v1`
+- agent-relevant change policy: `1.0.0` (`contracts/agent-relevant-change-policy.v1.json`)
+- orientation reason-code vocabulary: `1.0.0` (`contracts/orientation-reason-codes.v1.json`)
+- orientation limits: `1.0.0` (`contracts/orientation-limits.v1.json`)
+- Runtime Recipe: `campaigns-os-runtime-recipe/v1` (JSON Schema:
+  `schemas/campaigns-os-runtime-recipe.v1.schema.json`)
+- runtime recipe kind: `campaigns-os-node-v1`, revision `1.0.0`
+  (`contracts/runtime-recipe.campaigns-os-node-v1.json`)
+
+The orientation line is separate from the supported-surface line on purpose: a
+consumer needs to know about an agent-relevant change even when
+`surface_version` did not move. `contracts/release-ledger.json` records those,
+`CHANGELOG.md` narrates them, and the two are checked against each other in both
+directions. Reason codes and semantic classes are append-only vocabularies —
+renaming or removing one is a breaking change. Raising a limit advances
+`limits_version` and owes its own ledger entry.
+
+The runtime recipe carries two version identifiers because they gate different
+things. The **kind** names what an installed consumer must already understand in
+order to execute the document at all — its commands, its package manager, the
+shape of its network policy, the kinds of output check it declares. A new kind
+needs a consumer release first, and an older consumer must fail closed on it.
+The **revision** re-parameterises fields an existing consumer already
+understands: accepted tool ranges, timeout and output bounds, the enumerated
+input set, the expected output inventory. An older consumer runs a revision
+correctly, with different numbers. Both owe a ledger entry; only a new kind gates
+on a consumer release. The recipe and its schema are hashed surface entries, so
+either changing also advances `surface_version` in the same change.
+
+Breaking packet semantics should create a new packet schema version. Non-breaking doctor warnings can ship in package patch/minor releases during developer preview.

package/docs/workflow-findings-sidecar.md

@@ -0,0 +1,588 @@
+# Run Telemetry
+
+Status: Implemented v0 — Run Records, consent/remit, packet-associated ambient sessions, QA repair-loop closeout, lifecycle timing, and repair-loop aggregation are live.
+Date: 2026-06-08
+
+> Supersedes the v0 "Workflow Findings Sidecar" framing. The sidecar was
+> local-only and never remitted; Run Telemetry keeps local capture but adds a
+> consented, opt-out remit so each run can improve the product. Workflow
+> Findings are now one channel inside a per-run Run Record. (Filename retained
+> for now to avoid link churn; the surface is "Run Telemetry".)
+
+## Purpose
+
+Every Campaigns OS run produces signal about how the build went — what the
+doctor flagged, which spec rules fired, which adapter decisions were taken, how
+QA resolved, plus anything an operator or agent noticed. Today that signal is
+discarded at the end of the run.
+
+Run Telemetry captures that signal as a structured **Run Record** and, when the
+operator has opted in, remits it to Next Commerce so the toolchain can improve
+over time — better skills, tools, templates, and design sources. The goal is a
+loop: a real run surfaces friction, the friction is analyzed, the fix ships, the
+next run is smoother.
+
+This is the "share usage data to improve the product" pattern, made explicit and
+asked once, up front.
+
+## What Changed From v0
+
+The Workflow Findings Sidecar was deliberately local-only. Run Telemetry keeps
+the local trail but changes the contribution model:
+
+- **Capture is always local.** The Run Record is written regardless of consent.
+- **Consent gates remit, not capture.** A machine-level opt-out decides only
+  whether records are sent (default ON for the canonical NEXT endpoint,
+  announced at remit time). Opt-outs lose nothing locally.
+- **The unit is the Run Record, not a single finding.** Findings (manual and
+  harvested) are one channel within it.
+
+## The Run Record (manifest model)
+
+The Run Record is a per-run **manifest**, not a giant unified artifact. It is
+keyed by one canonical `run_id` and is written to:
+
+```text
+.campaign-runtime/run-records/<run_id>.json
+```
+
+It does **not** re-embed the full bodies of other artifacts (those have their
+own schemas and evolve independently). Instead it carries:
+
+- **Stable envelope** — `schema_version` (`campaigns-os-run-record/v0`),
+  `run_id`, package version, the command that ran, an `argv` *shape* (flag names
+  present, not raw values), `created_at`, consent state, and remit status.
+- **Run identity** — `map_id`, `campaign_slug`, `template_family`,
+  `entry_point_shape`. (Best-effort; missing identity never blocks capture.)
+- **Source artifact refs** — for the Build Packet, Build Context, Assembly
+  Report, Page Kit build summary, QA verdict, and findings journal: `{ path,
+  schema_version, sha256 }`. References, not copies. This is what survives
+  upstream schema drift.
+- **Normalized observation arrays** — the extracted signal: doctor issue codes
+  (error/warning/ready), `spec.validation` rule IDs that fired, adapter
+  decisions, QA verdict disposition + gap classes, and the **finding IDs** for
+  this run.
+- **Findings snapshot** — this run's Workflow Findings (see channel below).
+
+### Run identity
+
+A single canonical `campaigns_os_run_id` is minted at the run boundary and
+threaded through the run so every artifact and finding correlates. It is also
+the **idempotency key**, enforced by refusal: the receiver holds one record per
+`run_id` and answers a second POST for an id it already stores with `409
+run_record_conflict`. Retrying a send that never landed is safe; the record that
+did land cannot be revised, so the id must not be spent on an interim record
+before the one that closes the run.
+
+Stage timings and repair-loop count are captured from the command lifecycle
+journal when a run session or explicit lifecycle journal is active. They remain
+best-effort signal: telemetry records the commands Campaigns OS can observe, not
+every thought, browser click, or external editor action in an agent session.
+
+### Validation
+
+Hand-rolled validator + JSON Schema doc, matching the existing
+`campaigns-os-workflow-finding` pair. **No AJV** (repo convention). The
+validator checks the envelope + observation-array shapes; it does **not**
+re-validate nested artifact bodies (those are referenced by hash, not embedded).
+
+## Improvement-Surface Taxonomy
+
+Each observation can map to the surface it should improve. Real signal is rarely
+one surface, so the field is a list, not an enum:
+
+- `surfaces: []` — any of `skill | cli | template | design-source | docs |
+  spec-rule | platform`
+- `primary_surface` — optional, the best single guess
+- `surface_confidence` — optional
+
+A best-effort tag travels with the signal; internal analysis refines and
+clusters. This is the grown-up form of the v0 `suggested_owner` field.
+
+## Consent
+
+Consent is a **machine/user-level** setting (consent belongs to the operator,
+not the campaign), resolved through one shared resolver that **every remitting
+command calls** — not a one-time `start` prompt that later commands bypass.
+
+- **Stored** at user level (`$XDG_CONFIG_HOME/campaigns-os/config.json`, else
+  `~/.config/campaigns-os/config.json`) with its own `schema_version`, the
+  package name, the proxy/endpoint scope, a timestamp, and the value source.
+- **Scoped to one endpoint.** A stored grant names the endpoint it was given
+  for and applies to remits that go there, not to any other base.
+  `campaigns-os telemetry on` grants the canonical NEXT endpoint;
+  `campaigns-os telemetry on --proxy-base <url>` grants that receiver instead
+  (a loopback or staging receiver; the base must be https or a loopback host,
+  the same rule the remit rail applies). The file holds one grant at a time,
+  so granting a staging receiver leaves the canonical endpoint OFF until
+  `telemetry on` is run again without the flag. A remit whose `--proxy-base`
+  does not match the stored scope stays OFF and the warning names the command
+  that would grant it. `campaigns-os telemetry status` prints the stored scope
+  and checks it against the canonical endpoint, or against `--proxy-base <url>`
+  when given (the same https-or-loopback rule applies). `campaigns-os
+  telemetry off` takes no `--proxy-base`: an OFF choice applies to every
+  endpoint, and the record it writes carries no scope.
+- **Prompted once, up front** — the first interactive command that would remit
+  asks plainly: "Campaigns OS can send build telemetry to Next Commerce to
+  improve templates, tools, and guidance. Share telemetry from this machine?
+  [Y/n] (change any time)."
+- **`campaigns-os telemetry status | on | off`** — explicit control without
+  hunting for the config file.
+- **Env override** — `CAMPAIGNS_OS_TELEMETRY` accepts `1|true|on` /
+  `0|false|off`; it beats the file (CI/automation). An **unknown** value
+  fails closed (no remit) with a warning, never a silent guess. `on` has no
+  scope: it applies to whatever endpoint the command names, so a remit to a
+  non-canonical `--proxy-base` under it warns that the override bypasses scope
+  checking and names the scoped `telemetry on --proxy-base` grant instead.
+- **No file, no env** → **ON for the canonical NEXT endpoint only**, announced
+  at remit time with the endpoint and the opt-out command. A non-canonical
+  `--proxy-base` (staging, self-hosted) stays **OFF** until explicitly
+  consented, and a malformed config file resolves **OFF** — the default never
+  overrides an unreadable prior choice.
+
+Consent gates **remit only**. With consent off, runs still write the local Run
+Record and `findings`/`export` still work. No run is ever blocked on telemetry,
+and telemetry is never shown to shoppers or merchant-facing approval viewers.
+
+## Data Boundary
+
+Run Telemetry carries the run's structure and identity, not raw artifact bodies,
+and applies light minimization to identifying-but-non-essential fields.
+
+Included:
+
+- run identity (`map_id`, `campaign_slug`, `template_family`) — these are the
+  join keys that make the telemetry useful;
+- structural signal (doctor codes, spec-rule IDs, adapter decisions, QA
+  disposition, finding IDs);
+- artifact refs (`path`, `schema_version`, `sha256`), counts, classifications.
+
+Minimized / excluded:
+
+- **Absolute local paths** → relativized or hashed (no contributor filesystem
+  layout). **OS username** → omitted.
+- **Raw artifact bodies** → never (full CampaignSpec JSON, source HTML,
+  full QA verdict / doctor / report bodies). Excluded for **size and noise** —
+  the value is the structured signal, not raw dumps.
+
+This is minimization, not a security allowlist: campaigns-os runs use a fixed
+synthetic test customer and a publishable client-side API key, so there is no
+secret/PII exposure to defend against. The path/username scrub is hygiene for a
+public package any agency may run.
+
+## Capture Surfaces
+
+The Run Record is assembled from several local inputs, all correlated by
+`run_id`:
+
+- **System signal** — extracted from this run's doctor output, Assembly Report,
+  and QA verdict (reusing the same artifact readers `findings harvest` uses).
+- **`findings harvest`** — proposes Workflow Findings from doctor blockers,
+  selected warnings, and report blockers; `--write` appends them. Under an
+  active run session, written findings inherit the session `run_id`; explicit
+  `--run-id` still wins. Harvested system findings default to
+  `safe_to_share: false` because raw doctor/report messages can contain
+  merchant URLs, source-copy snippets, or local artifact references. An operator
+  or redaction pass must approve sharing.
+- **`findings add`** — flags-first manual capture for operators and agents.
+  Under an active run session, new findings inherit the session `run_id`;
+  explicit `--run-id` still wins.
+- **Tiny Prompts** — skippable one-line stage-boundary prompts. Skipped prompts
+  record nothing.
+
+The findings journal stays `.campaign-runtime/workflow-findings.jsonl`, append-
+only and the **single writer** for findings. New findings carry an optional
+`run_id` (backward-compatible schema addition) so the Run Record's snapshot of
+"this run's findings" is exact rather than inferred from timestamps.
+
+## Remit Channel
+
+Remit reuses the QA-verdict publishing rails. Extract one shared helper rather
+than duplicate the fetch/try-catch:
+
+```text
+remit(path, payload, proxyBase)   // mirrors qa-node.mjs postVerdict
+```
+
+- **Consent-gated** — only sends when the resolver says yes.
+- **Non-fatal** — a failed POST never blocks or fails the run (mirrors "never
+  fail the run if publish is unreachable").
+- **Keyed on `run_id`** — the payload carries it and the receiver stores one
+  record per id, rejecting a repeat POST for a stored id with 409. This client
+  POSTs only; there is no replace verb. So a failed send may be retried and a
+  succeeded one may not be re-sent. Endpoint: `/api/runs` (implemented; receives
+  at the canonical remit scope).
+- **Durable status** — the local Run Record records `remit_attempted`,
+  `remit_ok`, `remit_error` and `remit_state` so a dropped send is visible,
+  not silent. No background retry daemon. The outcome is classified by what
+  the receiver answered, not by whether the transport threw:
+  - a parsed 2xx is `ok` (`stored`);
+  - a **409** is `ok` (`already_stored`): the receiver already holds this
+    `run_id`, which is the outcome the send was for — reached by an earlier
+    send whose answer was lost, or by a re-run. The body's error token does
+    not change this; 409 on this endpoint means exactly one thing;
+  - a 2xx whose body is not JSON is `ok` (`ok_unparsed_ack`) with
+    `remit_error` set to `Remit POST <status>: acknowledged with a body that
+    is not JSON: <excerpt>`, so the anomaly stays on the record;
+  - any other non-2xx is `failed` (`refused`) with `remit_error` `Remit POST
+    <status>: <statusText> <body>`; a transport failure (refused connection,
+    timeout, the proxy-base gate) is `failed` (`transport_error`).
+
+  The classification and the resolved base — as a kind, `canonical` /
+  `loopback` / `proxy`, never the host — are on the record itself since
+  surface 1.28.0 as `remit_result` (one of the five outcomes above, or null
+  when no send was attempted) and `remit_base_kind` (null when no send was
+  attempted); a prior outcome carried forward keeps both. They also travel,
+  with the HTTP status, in the `run-record --json` summary under `remit`
+  (`result`, `http_status`, `base_kind`, `sent`, `preserved`) and in the text
+  `Remit:` line. The summary's `result` is additionally `not_contacted` when
+  the record on disk was already `ok` and the receiver was not asked (below),
+  or null when nothing was sent and nothing is known (`--no-remit`, consent
+  off).
+- **The QA verdict publish is recorded beside the remit** — since surface
+  1.33.0 a record carries an optional `qa_verdict_publish` block: the
+  verdict's own `run_id` (the publish idempotency key — distinct from the
+  record's), the `publisher` (`qa run` for the run's own post, `qa publish`
+  for a later post of the stored verdict), `attempted` / `ok` / `error` /
+  `endpoint` (`/api/qa/verdicts`), a `state` (`skipped` when the run's
+  publish was off, `ok`, `failed`), the `result` in the same vocabulary as
+  `remit_result`, the `base_kind`, and `published_at`. `qa run` hands the
+  block to the session through its QA attempt, so `run end` and the auto-end
+  stamp it; `qa publish` stamps the record whose `qa_verdict` artifact
+  references the verdict, reads `state: "ok"` as already published, and
+  refuses without `--republish`. A stored `ok` is never downgraded by a later
+  failed send or by a reassembly. Absent on records written before the field
+  existed and on runs that produced no verdict.
+- **Re-runs never downgrade a durable outcome** — `run-record` is keyed on
+  `run_id`, and `run end`, the QA auto-end and the recovery action `next`
+  prints all go through it. Before writing, it reads the record already under
+  that id. A record whose remit is `ok` is final: it is neither re-sent (the
+  receiver would refuse it) nor rewritten (a reassembly is at best thinner
+  than what the session wrote, and would then disagree with the stored copy);
+  the command reports `written: false`, `remit.result: "not_contacted"`
+  (distinct from `already_stored`, which is a 409 the receiver answered),
+  `remit.sent: false`, and the text line `Remit: ok (already stored at the
+  receiver for this run id; not re-sent)`. A prior counts only when it is a
+  valid Run Record — the same validator that gates `writeRunRecord` — so a
+  file that merely says `remit_state: "ok"` is replaced like a corrupt one. A prior `failed` or `pending`
+  send is retried when the run may send, and carried forward unchanged
+  (`remit.preserved: true`) when it may not — `--no-remit` or consent off
+  over a failed remit does not file it as `skipped`. Only a `--no-write` run
+  reads nothing, because it writes and sends nothing.
+- **Which `run_id` a run-record is keyed on** — `--run-id` names it; without
+  one the active run session's id is used; without a session, the most recent
+  Run Record on disk for this packet's campaign (same `identity.map_id` and
+  `identity.campaign_slug` as the packet — the closeout-recognition match
+  below, newest `created_at` first) is re-emitted under **its** id; only when
+  no such record exists is a fresh id minted. `run end` clears the session,
+  so before this every run-record after close minted, and the closeout
+  action `next` prints or a re-emit after a sidecar fix filed a second Run
+  Record for a run that already had one. The summary says which happened:
+  `run_id_source` is `explicit`, `session`, `latest_record` or `minted`, in
+  `--json` and on the text `Run ID: <id> (<source>)` line, and a
+  `latest_record` run first prints `Run ID <id> is the most recent Run Record
+  for this campaign; re-emitting it in place. Pass --new-run to start a new
+  run under a fresh id, or --list to see every record for this packet.` The
+  source is on the command's envelope only, never on the record. `--new-run`
+  mints regardless of what is on disk (it is refused beside `--run-id`).
+  `--list` is inspection: it prints, newest first, every record for this
+  packet's campaign (`run_id`, `created_at`, `remit_state`, `remit_result`,
+  `remit_endpoint`, `record_path`), then the id the next plain run would use
+  and its source, and — like `--no-write` — assembles, writes and sends
+  nothing (`list: true`, `written: false`, `remit.sent: false` in `--json`).
+- **The stored copy states its outcome** — the record the receiver holds is,
+  by construction, one whose send landed, so the body sent carries
+  `remit_state: "ok"`, `remit_attempted: true`, `remit_ok: true`, the
+  endpoint, `remit_result: "stored"` and the `remit_base_kind` the send
+  resolved to. The local file carries the `pending` sentinel only between its
+  first write and the answer.
+- **Tenant-scoped** — the remit sends the packet's Campaigns API key (packet,
+  then the packet-local CampaignSpec, then the declared `env:` source) as the
+  `X-Campaign-Key` header. The receiver hashes it server-side into
+  `campaign_key_hash`, which its tenant-scoped `GET /api/runs` joins on. A
+  record remitted without the header is stored but reachable only through the
+  cross-tenant admin listing or by known `run_id` — every record this CLI
+  remitted before 2026-09-10 is in that state. The key never enters the record.
+- **Readable back** — `campaigns-os telemetry list --packet <json>` lists the
+  tenant scope; `campaigns-os telemetry list` with `CAMPAIGN_OPS_ADMIN_KEY` set
+  (or `--admin-key-env <VAR>`) lists cross-tenant, unscoped records included.
+  A 2xx is a listing only when its body carries `runs[]`: any other body (a
+  maintenance page, an intermediary's HTML) is an error naming the status and
+  an excerpt, and exits non-zero, rather than "showing 0 of 0 returned".
+- **Shape-checked before it leaves the machine** — a credential is validated,
+  and its destination vetted, before a socket is opened:
+  - The resolved campaign key must look like a campaign key: 8-256 characters
+    of letters, digits, dot, dash, and underscore, one line, no whitespace.
+    A value that is *present but malformed* (a quoted key, a pasted JSON blob,
+    a URL) is refused, and the refusal names its **source** — the env var, the
+    packet field, or the CampaignSpec — and never its value. `telemetry list
+    --packet` fails fast on such a value and sends nothing; the remit rail,
+    which is non-fatal by contract, warns on stderr and sends without a tenant
+    scope. That is now distinguishable in the output from "no key was
+    configured". Consent gates the whole thing: with no send attempted
+    (consent off, or `--no-remit`) the key is never read and nothing is said.
+    `api_key_source` must additionally name a variable matching
+    `^(?=[A-Z])[A-Z0-9_]*CAMPAIGN[A-Z0-9_]*$` — upper-case, starting with a
+    letter, containing `CAMPAIGN` anywhere, so the documented default
+    `CAMPAIGNS_API_KEY` qualifies — so a packet cannot route an arbitrary
+    secret into the header; a variable outside that shape is refused by name
+    and its value is never read. `campaigns-os doctor` reads the key through
+    the same resolver: a refused value is its `campaign.api_key_rejected`
+    warning, naming the source, while a key that is simply not configured
+    stays `campaign.api_key_source`.
+  - `--proxy-base` must be `https:`. A loopback host (`localhost`,
+    `127.0.0.1`, `[::1]`) may be plain http for a local receiver, and each
+    such request prints one stderr warning that the credential travels in
+    clear. Any other plain-http base is refused before the request — so a
+    remit or verdict publish aimed at a plain-http remote proxy now fails
+    (non-fatally, recorded in `remit_error`) instead of sending the key in the
+    clear. The ops admin key keeps its stricter rule on top of this: it goes
+    only to the canonical scope, a loopback receiver, or a base the operator
+    vouched for with `--trust-proxy-base`.
+
+The public package only emits and remits; it does not cluster, route, summarize
+across runs, or create issues.
+
+## Public / Internal Boundary
+
+- **Public `campaigns-os`** owns: the Run Record schema, local capture, the
+  consent resolver, and the remit channel. Capturing or opting out must never
+  require internal Next Commerce access.
+- **Internal tooling** owns: ingestion, clustering, surface-mapping, trend
+  analysis, and turning the backlog into improvement candidates. The loop closes
+  through normal development — the system does not edit itself.
+
+## Non-Goals
+
+- Do not replace the Build Packet, Assembly Report, doctor output, or QA
+  Verdicts — the Run Record references the proof trail, it is not the proof
+  trail.
+- Do not auto-run QA or typed-card test orders.
+- Do not edit skills, templates, or rules automatically (no auto-codegen).
+- Do not ship raw artifact bodies, absolute local paths, or OS usernames.
+- Do not block a build on telemetry, and do not expose telemetry to shoppers or
+  merchant-facing approval viewers.
+- Do not record skipped Tiny Prompts.
+- Do not add a background retry daemon for failed remit.
+
+## Implementation Sequence
+
+The core implementation is landed. This sequence is retained as an orientation
+map for the code paths and tests that own each slice.
+
+1. **Run Record schema** (`campaigns-os-run-record/v0`): envelope + canonical
+   `run_id` + artifact-ref shape + normalized observation arrays + `surfaces[]`
+   taxonomy. Add optional `run_id` to the Workflow Finding schema.
+2. **Run identity + local capture**: mint/thread `run_id`; assemble the manifest
+   in `src/run-record.mjs` from existing artifact readers + `readJournal`;
+   write `.campaign-runtime/run-records/<run_id>.json`. cli.mjs stays thin
+   dispatch.
+3. **Consent resolver + `telemetry` command**: user-level config, env override
+   with fail-closed parsing, shared resolver called by every remitting command.
+4. **Remit**: shared `remit()` helper, consent-gated, non-fatal, idempotent on
+   `run_id`, with local remit status.
+
+`findings add` / `harvest` / `export` remain local-first and become the findings
+channel of the Run Record.
+
+## Run Sessions (ambient capture)
+
+Operators (and the agents driving them) should not have to thread `--run-id` /
+`--lifecycle-journal` on every command. A **run session** makes capture ambient:
+
+- `campaigns-os run start [--packet <p>]` mints one `run_id`, picks the
+  lifecycle journal, and writes `.campaign-runtime/run-session.json`. With
+  `--packet` the session (and the managed `.gitignore` block) lands in the
+  packet's target repo — `assembly.target_repo` resolved from the packet's
+  directory, else that directory — whatever the cwd, the same root the
+  auto-opener behind `start` / `prepare-build` uses; without it, at cwd. A
+  packet that exists but does not parse is refused (no session is opened on a
+  guessed root); one not written yet roots on its own directory with a warning.
+- Every command then auto-discovers that session (walking up from cwd, or
+  from the `--packet` it was handed) and shares its `run_id` + journal **with
+  no per-command flags**. `start` / `prepare-build` / `build` take a
+  `--target`, not a packet: the first opens the target's session, and a
+  repeated one against the same target joins it from any cwd, so every intake
+  attempt lands in the same journal (a session bound to a different packet is
+  a conflict to end, not one to write into). Findings commands
+  also inherit the active `run_id` when writing findings. Explicit `--run-id` /
+  `--lifecycle-journal` still wins; `CAMPAIGNS_OS_TELEMETRY` consent still gates
+  remit.
+- Each `campaigns-os qa run` records its full local verdict path on the active
+  session. A blocked verdict keeps that session open for repair and another QA
+  attempt. A ready or ready-with-exceptions verdict auto-assembles the
+  aggregated Run Record with references to every attempt, then clears the
+  session. Pass `--no-remit` to skip remit for that local Run Record.
+  Because the session's close is what remits the session's `run_id`, the
+  `run-record` closeout command a QA run prints carries `--no-remit` whenever
+  the attempt does not end the session — a **blocked** verdict, or a disposition
+  the toolkit does not recognise: the session stays open, so that command would
+  share its id, and assembling an interim record is useful while spending the
+  session's one accepted POST on it is not. A session-ending verdict auto-ends
+  in the same process, before the printed command can run, so there the command
+  finds no session and resolves the `run_id` the way any sessionless run does
+  (below): to the record the auto-end just wrote, which it re-emits in place —
+  and leaves as written when its remit landed. One exported set decides which
+  dispositions end a session, read by both
+  the auto-end and the closeout, so the two cannot disagree about who owns the
+  `run_id`. When
+  an auto-end's own remit does not close, the auto-end says so and names the
+  local record to keep. It does not print a re-send command: `run-record
+  --run-id` reassembles rather than reloads (see below), and the session whose
+  attempt references the record carries is already cleared.
+- An explicit `--packet` associates commands, `run status`, and `run end` with
+  the target campaign session even from the toolkit or another project
+  directory, and `run start --packet` opens it there.
+  If cwd and packet resolve to different active sessions, the command fails
+  with both run IDs instead of silently cross-writing lifecycle evidence.
+- `campaigns-os run end` remains the manual close path for non-QA or interrupted
+  sessions. `run status` reports the active session.
+- Sessions older than 12 hours are treated as stale and are not auto-discovered,
+  so a later work session does not inherit an old `run_id` or lifecycle journal.
+  A stale session is closed out, not abandoned: the next `start`,
+  `prepare-build`, or `build` at that `--target`, or `run start` / `run end`
+  (at the `--packet`'s target repo, else at cwd), assembles its Run Record
+  from the lifecycle journal (remit under the
+  usual consent) and removes the file before opening a new session. A stale
+  session whose packet is gone is cleared with a stderr note and no record.
+  `run status` reports a stale file but never sweeps it.
+
+The session file is transient, machine-local, and lives under the
+scrubber-ignored `.campaign-runtime/`.
+
+## Closeout recognition (`next` reads the records it demands)
+
+Nothing in the CLI used to read `.campaign-runtime/run-records/`, so `next` at
+stage `done` demanded a Run Record unconditionally — including for runs that had
+already assembled, closed, and remitted one. `next` now reads that directory and
+decides whether a **matching, current, successfully closed** record exists for
+the packet it was called with.
+
+The reading is deliberately conservative. Records are machine-local (they are in
+the managed `.gitignore` block), so an absent directory is the normal case and
+never an error; the scan is bounded and wrapped, and a slow, unreadable, or
+corrupt records directory can never fail or stall orchestration. **Any doubt
+emits the closeout.** A false demand costs one idempotent command; false silence
+loses the run's durable record.
+
+A record satisfies closeout only when all of these hold:
+
+1. **Identity** — its `identity.map_id` and `identity.campaign_slug` equal the
+   packet's `spec.map_id` and `campaign.public_route_slug`. Both sides must
+   assert an identity; a record that names neither is not evidence about this
+   campaign.
+2. **Currency** — its `created_at` is not earlier than the newest `checked_at` /
+   `completed_at` on the report's `doctor` and `qa` stages. An older report that
+   carries no such timestamps contributes no floor rather than a fabricated one.
+3. **Artifacts** — when the report's `qa` stage points at a QA verdict, one of
+   the record's `qa_verdict` artifact references must carry that verdict's
+   current SHA-256. (A record may reference several verdicts: a session retains
+   each blocked repair attempt alongside the one that passed.) Verdict identity
+   only — the assembly report's own hash drifts the instant a producer writes a
+   stage, so including it would make every record instantly outdated.
+4. **Closure** — `remit_state` is `ok`, or `skipped`. **`skipped` counts as
+   closed**: it is the consent-off / `--no-remit` / local-only path, a deliberate
+   non-remit rather than a failure.
+
+The newest matching record decides, so an older good record can never mask a
+newer broken one.
+
+### Reason codes
+
+| Code | `next` emits |
+|---|---|
+| `satisfied` | a non-required `run_record_present` action naming the record and its path |
+| `no_record` | the required `run_record_closeout` (the plain command; with no record for this campaign, `run-record` mints) |
+| `foreign_campaign` | the required `run_record_closeout` (plain; the records on disk belong to other campaigns and are never reused) |
+| `stale_predates_evidence` | the required `run_record_closeout` carrying `--new-run`: the superseded record is the newest one for the campaign, so the plain command would re-emit it in place |
+| `outdated_artifacts` | the required `run_record_closeout` carrying `--new-run`, for the same reason |
+| `remit_failed` | the required `run_record_remit_recovery` |
+| `remit_incomplete` | the required `run_record_remit_recovery` |
+
+A failed or never-finished remit is **not** a missing record, and must not be
+answered by minting a second one — that would fork the run's identity. Recovery
+re-runs `run-record` against the record already on disk:
+
+```bash
+campaigns-os run-record --packet <packet> --run-id <existing-run-id> --json
+```
+
+The receiver may or may not hold the id already (a send whose answer was lost
+after the store, say). Either answer closes the record: a 2xx stores it, and a
+409 is read as `already_stored` — `remit_state: ok` — so the recovery converges
+instead of stamping `failed` over the record and being demanded again. A record
+whose remit is already `ok` on disk is never re-sent and never rewritten by this
+command; it reports `not_contacted` and leaves the file as written.
+
+Read the command for what it is on a record that is not yet stored: it
+**reassembles** the record under that `run_id`, it does not reload and re-send
+the file already written. Anything the record held that came only from the run
+session — the QA attempt references a repaired run collects across several
+attempts — is gone once the session is cleared, so on a multi-attempt run this
+replaces the unsent record with a thinner one and sends that. Re-sending the
+persisted record is not implemented. Until it is, treat the local file as the
+durable artifact and recover the remit only for a run whose record the current
+disk state can still reproduce.
+
+The plain closeout command (no `--run-id`) is not a way around this: with no
+session it resolves to the same newest record and re-emits it in place, so it
+reaches a new id only through `--new-run` or when no record for the campaign
+exists. `run-record --list` shows which ids exist before choosing.
+
+An active run session still wins: with an ambient session open, `done` emits the
+required `run end` exactly as before, satisfied or not.
+
+`campaigns-os qa run`'s own closeout action is unchanged. It fires while the
+record for that verdict cannot exist yet, so it is correctly unconditional.
+
+### Latest QA identity cannot disagree with latest QA status
+
+The QA producer owns `stages.qa.verdict_run_id`, `stages.qa.evidence`, and
+`stages.qa.purchase_proof`. Before this, only the canonical fields
+(status/outputs/timestamps) refreshed, and hand-authored extension fields
+survived untouched — so a stage could carry a passing status and today's output
+links beside a previous run's id and an `evidence.remaining_blocker` describing
+a bug that had since been fixed.
+
+Prior evidence is **preserved, not deleted**: the previous `verdict_run_id` /
+`evidence` pair moves into a bounded `history[]` on the same stage, oldest first,
+carrying its **own original status and `checked_at`**. A stage that had no
+`checked_at` yields a history entry with no `checked_at` — an absent timestamp
+stays absent rather than being stamped with now, because manufactured provenance
+is worse than the stale field it replaces. Re-recording the same verdict does not
+grow history. `evidence` has two schema-legal shapes, object and array, and both
+archive — an array of operator notes is preserved as history rather than dropped
+on the next producer write. Every other extension field on the stage (`waivers`,
+and anything an out-of-repo consumer writes) passes through a producer write
+verbatim.
+
+These fields are additive under the assembly-report stage definition, which
+already permits additional properties; no schema and no surface version moved.
+
+## Deferred (not v0)
+
+- Command-lifecycle instrumentation — **landed (T6).** A `withCommandLifecycle`
+  wrapper times every command and captures its command name, argv shape, and
+  exit status. Persistence is active when an explicit `--lifecycle-journal` /
+  env `CAMPAIGNS_OS_LIFECYCLE_LOG`, or an ambient run session, is present;
+  entries append to `.campaign-runtime/command-lifecycle.jsonl`.
+- Stage timings and repair-loop count — **landed.** `run-record` aggregates the
+  whole lifecycle journal for a `run_id` (Tier 1): each command invocation
+  becomes a `lifecycle.stages[]` entry (with per-stage `exit_status`),
+  `repair_loop_count` counts command re-runs, and run-level `duration_ms` sums
+  active command time instead of idle wall-clock gaps between invocations;
+  `wall_clock_duration_ms` reports that full outer span separately.
+  `started_at` / `completed_at` preserve the observed bounds. Heavy
+  commands mark their own sub-phases (Tier 2), which aggregate into
+  `command:phase` stages. The cross-command `run_id` is threaded automatically
+  by the run session (Tier 3), so these fields populate with real data from a
+  normal "talk to your agent and build" flow — no manual flag bookkeeping.
+- Internal ingestion / clustering / surface-mapping — internal tooling
+  (ADR-019), not this package.
+
+## Open Questions
+
+- Final envelope field list + exact observation-array shapes (resolved when the
+  schema is authored against current packet / report / verdict artifacts).
+- `/api/runs` payload envelope + upsert semantics (aligned with the QA verdict
+  publishing rails).