@1aboveio/skills 0.10.0

package/skills/engineering/smoke/scripts/smoke.mjs

@@ -0,0 +1,713 @@
+// smoke — the curated E2E happy-path GATE runner. Loads the smoke manifest (the
+// small "if these flows work, the build is alive" set), selects the paths safe
+// for the target, and reduces drive results into a single ALIVE / DEAD verdict.
+//
+// This is the mechanized version of the manual QA pass that catches integrated
+// runtime bugs a green unit/functional suite sails past (the #237 invisible
+// button / Feishu-QR crash class). It does NOT author or run the full suite — the driving
+// is runtime observation of the REAL running app (browser paths via e2e-test's
+// Playwright runner; api/cli paths via /verify-style capture). This script owns
+// the decidable shell: validate the manifest, pick the target-safe subset, and
+// compute the gate verdict from drive results.
+//
+//   node smoke.mjs validate --manifest smoke.manifest.json [--journeys e2e/journeys]
+//     (--journeys reconciles browser paths against the @smoke tags in the specs:
+//      a referenced journey that isn't @smoke-tagged, or an @smoke journey missing
+//      from the manifest (a silent false-ALIVE), fails validation.)
+//   node smoke.mjs plan     --manifest smoke.manifest.json --profile pr-local
+//   node smoke.mjs plan     --manifest smoke.manifest.json --profile prod-preview --target https://rev-xyz.run.app
+//     (--profile names a Validation Profile from the manifest's `profiles` registry. The
+//      profile — not the caller — decides WHICH paths run and WHETHER writes are allowed:
+//      each profile binds a gate/environment/endpoint plus a mutationPolicy. Production
+//      profiles (prod-preview/prod-active) are mechanically read-only, so a synthetic
+//      tenant grants nothing there; local profiles allow isolated writes; dev-active
+//      allows a registered synthetic tenant. --target is just the ADDRESS to drive against
+//      (the candidate URL), and it no longer participates in selection — the profile does.)
+//   node smoke.mjs suggest  --inventory docs/tests/_generated/surface-inventory.json [--out smoke.candidates.json]
+//   node smoke.mjs verdict  --manifest smoke.manifest.json --profile <name> --results smoke-results.json [--target <url>] [--out summary.json]
+//     (pass the SAME --profile the run used. Selection is a pure function of the profile
+//      name + the manifest, so the run and the verdict cannot disagree about the selected
+//      path set — the old --target/--no-mutations mismatch is unrepresentable. The verdict
+//      stamps the `profile` it selected under and the `noMutations` flag DERIVED from that
+//      profile's mutationPolicy (read-only ⇒ true), which resolve-release's green-gate reads.)
+//     (`generatedAt` dates the VERDICT, not the RUN. This subcommand reduces a results file
+//      of any age and stamps the current instant over it, so re-running `verdict` alone
+//      re-mints freshness without re-validating anything. A consumer bounding the evidence's
+//      age (resolve-release's shift gate) is bounding the mint; re-drive the paths into a new
+//      smoke-results.json whenever what you need is fresh OBSERVATIONS, not a fresh stamp.)
+//
+// The manifest is JSON (a repo may author in YAML and project to JSON, the same
+// way e2e-test's route-manifest is generated). Results is a JSON array of
+// { id, status: pass|fail|blocked, evidence?, note? } produced by the drive step.
+
+import fs from 'node:fs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// ---- pure, unit-testable core (no browser, no network) ----
+
+export const SURFACES = ['browser', 'api', 'cli']
+const GOLDEN_KEYWORDS = [
+  'checkout', 'pay', 'payment', 'billing', 'invoice', 'subscribe', 'subscription',
+  'order', 'purchase', 'refund', 'login', 'log-in', 'signin', 'sign-in', 'signup',
+  'sign-up', 'register', 'sso', 'oauth', 'auth', 'onboard', 'invite', 'admin',
+  'settings', 'connect', 'connector', 'create', 'new',
+]
+
+// ---- Validation Profiles (issue #440) ----
+//
+// A Validation Profile is a NAMED binding of three axes plus policy, so a caller
+// selects one name instead of assembling free-form targeting flags. The three axes
+// the old single `--target` string conflated:
+//   - gate        WHY evidence is required (the lifecycle moment)
+//   - environment WHERE the app runs
+//   - endpoint    WHICH revision (a distinction that only exists once deployed)
+// plus `prerequisites` (what the profile needs in place), `evidencePolicy` (what
+// evidence it demands), and `mutationPolicy` (attached to the PROFILE, not the run).
+//
+// The core fix this delivers: selection becomes a pure function of the profile name
+// + the manifest, so the run and the verdict cannot disagree about the selected path
+// set (the old --target/--no-mutations mismatch is unrepresentable), and production
+// read-only-ness is enforced by the profile rather than by a flag the caller must
+// remember (resolve-release principle 4).
+export const GATES = ['pull-request', 'merge-queue', 'trunk-integration', 'pre-promotion', 'post-promotion']
+export const ENVIRONMENTS = ['local', 'dev', 'prod']
+export const ENDPOINTS = ['local', 'preview', 'active']
+export const MUTATION_POLICIES = ['isolated-writes', 'synthetic-tenant', 'read-only']
+
+// Each gate pins exactly one valid (environment, endpoint) pair — the coherence table
+// the "invalid gate/environment/endpoint combination fails closed" rule checks against.
+// The reasoning, not an arbitrary enumeration: the PR and merge-queue gates run the app
+// locally (endpoint `local`); trunk-integration runs against the dev environment's live
+// (100%-traffic → `active`) revision; pre-promotion validates the production candidate at
+// 0% traffic (a `preview` revision); post-promotion validates the live production service
+// (`active`). A local environment never has a preview/active split, and a deployed
+// environment never uses the `local` endpoint — so a bad pairing (e.g. pull-request in
+// prod, or pre-promotion against `active`) is rejected rather than silently accepted.
+const GATE_AXES = {
+  'pull-request': { environment: 'local', endpoint: 'local' },
+  'merge-queue': { environment: 'local', endpoint: 'local' },
+  'trunk-integration': { environment: 'dev', endpoint: 'active' },
+  'pre-promotion': { environment: 'prod', endpoint: 'preview' },
+  'post-promotion': { environment: 'prod', endpoint: 'active' },
+}
+
+// Reserved profile NAMES → the gate they MUST bind. These names are consumed by
+// `resolve-release` (and the other lanes) by HARDCODED string, not by their binding
+// — step 4a drives `--profile prod-preview`, 4b drives `prod-active` — so the name is
+// itself a safety-bearing key. Without this pin, a registry entry NAMED `prod-preview`
+// but bound to `{gate:"trunk-integration", environment:"dev", mutationPolicy:"synthetic-tenant"}`
+// validates clean (its binding is internally coherent) and `plan --profile prod-preview`
+// then selects a tenant-ful WRITE path against the production candidate. Pinning the gate
+// cascades through GATE_AXES (environment + endpoint) and the prod-read-only rule
+// (mutationPolicy), so a rename-and-rebind of a reserved name fails closed. See the
+// `prod-profile-name-drift` hazard (references/manifest.md).
+export const RESERVED_PROFILE_GATES = {
+  'pr-local': 'pull-request',
+  'queue-local': 'merge-queue',
+  'dev-active': 'trunk-integration',
+  'prod-preview': 'pre-promotion',
+  'prod-active': 'post-promotion',
+}
+
+// Validate ONE profile's shape and axis/policy coherence. Decidable, fail-closed:
+// returns an array of error strings (empty = valid). The load-bearing rule is that a
+// production profile is mechanically read-only regardless of any declared tenant.
+export function validateProfile(name, profile) {
+  const at = `profiles.${name}`
+  if (!profile || typeof profile !== 'object' || Array.isArray(profile)) return [`${at}: must be an object`]
+  const errors = []
+  if (!GATES.includes(profile.gate)) errors.push(`${at}: gate must be one of ${GATES.join('/')}`)
+  if (!ENVIRONMENTS.includes(profile.environment)) errors.push(`${at}: environment must be one of ${ENVIRONMENTS.join('/')}`)
+  if (!ENDPOINTS.includes(profile.endpoint)) errors.push(`${at}: endpoint must be one of ${ENDPOINTS.join('/')}`)
+  if (!MUTATION_POLICIES.includes(profile.mutationPolicy)) errors.push(`${at}: mutationPolicy must be one of ${MUTATION_POLICIES.join('/')}`)
+  // Reserved-name binding. A name another lane consumes by hardcoded string MUST bind its
+  // reserved gate; from that gate, GATE_AXES + the prod-read-only rule below force the
+  // environment/endpoint/read-only-ness. So a rename-and-rebind attack (name `prod-preview`,
+  // bind it to a writable dev gate) fails HERE, before selection can inherit the wrong policy.
+  const reservedGate = RESERVED_PROFILE_GATES[name]
+  if (reservedGate && profile.gate !== reservedGate) {
+    errors.push(`${at}: "${name}" is a reserved profile name consumed by another lane by name — it MUST bind gate "${reservedGate}", not "${profile.gate}". A safety property (production read-only-ness) is keyed to this name, so rebinding it would let the consumer silently inherit the wrong policy.`)
+  }
+  // Axis coherence — only when the gate is a known one (an unknown gate already errored).
+  const axes = GATE_AXES[profile.gate]
+  if (axes) {
+    if (ENVIRONMENTS.includes(profile.environment) && profile.environment !== axes.environment) {
+      errors.push(`${at}: gate "${profile.gate}" runs in environment "${axes.environment}", not "${profile.environment}"`)
+    }
+    if (ENDPOINTS.includes(profile.endpoint) && profile.endpoint !== axes.endpoint) {
+      errors.push(`${at}: gate "${profile.gate}" targets the "${axes.endpoint}" endpoint, not "${profile.endpoint}"`)
+    }
+  }
+  // Mutation-policy coherence. Production is read-only, full stop (principle 4): the
+  // candidate/service is wired to the real production database, so a synthetic tenant
+  // grants nothing. Isolated writes only make sense on a disposable local store; a
+  // synthetic tenant only on a shared deployed dev store.
+  if (profile.environment === 'prod' && MUTATION_POLICIES.includes(profile.mutationPolicy) && profile.mutationPolicy !== 'read-only') {
+    errors.push(`${at}: a prod profile must be read-only (mutationPolicy "read-only"), not "${profile.mutationPolicy}" — production is read-only regardless of any declared tenant`)
+  }
+  if (profile.mutationPolicy === 'isolated-writes' && ENVIRONMENTS.includes(profile.environment) && profile.environment !== 'local') {
+    errors.push(`${at}: mutationPolicy "isolated-writes" is only valid in the local environment, not "${profile.environment}"`)
+  }
+  if (profile.mutationPolicy === 'synthetic-tenant' && ENVIRONMENTS.includes(profile.environment) && profile.environment !== 'dev') {
+    errors.push(`${at}: mutationPolicy "synthetic-tenant" is only valid in the dev environment, not "${profile.environment}"`)
+  }
+  if (!Array.isArray(profile.prerequisites) || profile.prerequisites.some((x) => typeof x !== 'string')) {
+    errors.push(`${at}: prerequisites must be an array of strings (the set the profile requires)`)
+  }
+  if (!profile.evidencePolicy || typeof profile.evidencePolicy !== 'string') {
+    errors.push(`${at}: evidencePolicy must be a string (what evidence this profile demands)`)
+  }
+  return errors
+}
+
+// Validate the whole `profiles` registry and each path's profile membership. A missing
+// registry is a WARNING (legacy manifests still parse) — but the moment a registry is
+// present, every path must declare a non-empty `profiles` array of DECLARED profile
+// names, or the path is a silent non-runner (a false ALIVE). Fail closed on both an
+// invalid profile and a dangling path→profile reference.
+export function validateProfiles(manifest, paths, errors, warnings) {
+  const registry = manifest && manifest.profiles
+  if (registry === undefined) {
+    warnings.push('no `profiles` registry — selection is by named Validation Profile (references/manifest.md). Without one, `plan`/`verdict --profile` cannot run. Add a `profiles` block binding gate + environment + endpoint + prerequisites + evidencePolicy + mutationPolicy.')
+    return
+  }
+  if (!registry || typeof registry !== 'object' || Array.isArray(registry)) {
+    errors.push('profiles: must be an object mapping a profile name to its binding — see references/manifest.md')
+    return
+  }
+  const names = new Set(Object.keys(registry))
+  if (names.size === 0) errors.push('profiles: the registry is empty — declare at least one Validation Profile, or drop the `profiles` key to run in legacy mode')
+  for (const name of names) errors.push(...validateProfile(name, registry[name]))
+  // With a registry present, path membership is mandatory and must resolve.
+  for (const p of paths) {
+    if (!p || !p.id) continue
+    if (!Array.isArray(p.profiles) || p.profiles.length === 0) {
+      errors.push(`paths (${p.id}): with a profiles registry present, a path must declare a non-empty "profiles" array — the profiles it is required in — or it silently never runs (a false ALIVE)`)
+      continue
+    }
+    for (const ref of p.profiles) {
+      if (!names.has(ref)) errors.push(`paths (${p.id}): profile "${ref}" is not in the profiles registry (${[...names].join(', ') || 'empty'})`)
+    }
+  }
+}
+
+// Validate the manifest shape. Decidable, ~zero-judgment: structural rules only,
+// so a malformed gate fails loudly instead of passing vacuously. Returns
+// `errors` (block the gate) and `warnings` (surfaced gaps that don't fail it —
+// e.g. a missing `setup` block, which leaves the prerequisites undeclared).
+export function validateManifest(manifest) {
+  const errors = []
+  const warnings = []
+  const paths = manifest && manifest.paths
+  if (!Array.isArray(paths) || paths.length === 0) {
+    return { ok: false, errors: ['manifest.paths must be a non-empty array — a smoke gate with no golden paths proves nothing'], warnings }
+  }
+  const seen = new Set()
+  for (const [i, p] of paths.entries()) {
+    const at = `paths[${i}]${p && p.id ? ` (${p.id})` : ''}`
+    if (!p || typeof p !== 'object') { errors.push(`${at}: not an object`); continue }
+    if (!p.id) errors.push(`${at}: missing id`)
+    else if (seen.has(p.id)) errors.push(`${at}: duplicate id "${p.id}"`)
+    else seen.add(p.id)
+    if (!SURFACES.includes(p.surface)) errors.push(`${at}: surface must be one of ${SURFACES.join('/')}`)
+    // A browser path does NOT re-specify the flow — it references the @smoke-tagged
+    // e2e Tier-3 journey that already drives it; that spec owns the steps and the
+    // asserted observable. api/cli surfaces (which e2e-test doesn't cover) carry
+    // their own start/command + observable.
+    if (p.surface === 'browser') {
+      if (!p.journey || typeof p.journey !== 'string') errors.push(`${at}: a browser path needs a "journey" — the @smoke-tagged e2e Tier-3 journey (its @covers id) that drives it; don't re-specify start/observable here`)
+    } else {
+      if (!p.start && !p.command) errors.push(`${at}: needs a "start" (route/request) or "command" to drive`)
+      if (!p.observable || typeof p.observable !== 'string') errors.push(`${at}: needs an "observable" — the concrete thing that proves the path worked`)
+    }
+    // Prod-safety: a path that mutates durable state must declare a synthetic
+    // test tenant, or it can never run against a deployed/prod target.
+    if (p.mutates === true && !p.tenant) errors.push(`${at}: mutates:true requires "tenant" (a synthetic/test tenant) so it is safe off-local`)
+  }
+  validateSetup(manifest.setup, paths, errors, warnings)
+  validateProfiles(manifest, paths, errors, warnings)
+  // The e2e-* naming convention: synthetic tenants (and the test accounts they hold)
+  // carry an `e2e-` prefix so test data is identifiable at a glance, bulk-cleanable
+  // (`… WHERE tenant LIKE 'e2e-%'`), and mechanically distinguishable from live data
+  // (e2e-test references/authoring/auth-flows.md). A warning, not an error — legacy
+  // manifests still gate — but an unprefixed tenant is the one that gets mistaken for real.
+  const tenantIds = new Set([
+    ...paths.filter((p) => p && typeof p.tenant === 'string').map((p) => p.tenant),
+    ...(manifest.setup && Array.isArray(manifest.setup.tenants) ? manifest.setup.tenants.filter((t) => typeof t === 'string') : []),
+  ])
+  for (const t of tenantIds) {
+    if (!t.startsWith('e2e-')) {
+      warnings.push(`tenant "${t}": name synthetic tenants with the e2e- prefix (e.g. "e2e-${t}") so test data is identifiable, bulk-cleanable, and never mistaken for live data`)
+    }
+  }
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+// Validate the (recommended) `setup` block — the co-located prerequisites a run
+// needs *before* it can drive a path: how to boot the app, env/secrets, the
+// auth-bypass, seed commands, and the synthetic-tenant registry. Keeping these
+// in the manifest (not in prose elsewhere) makes them checkable and keeps them
+// next to the gate that consumes them. A missing block is a *warning*, not an
+// error — legacy manifests still validate — but a present block is shape-checked,
+// and any path tenant the registry doesn't list is flagged so it can't drift.
+export function validateSetup(setup, paths, errors, warnings) {
+  if (setup === undefined) {
+    warnings.push('no `setup` block — the gate does not record how to boot/seed the app, the auth-bypass, or which tenants are synthetic. Add one (references/manifest.md) so the prerequisites live next to the gate and are checkable, instead of in prose elsewhere.')
+    return
+  }
+  // Reject falsy (incl. `setup: null`, which is valid JSON and `typeof === 'object'`)
+  // as a malformed block, not a missing one — before reading any property off it.
+  if (!setup || typeof setup !== 'object' || Array.isArray(setup)) { errors.push('setup: must be an object — see references/manifest.md'); return }
+  if (!setup.boot || typeof setup.boot !== 'string') {
+    errors.push('setup.boot: needs a string — how to start the app for a `local` run (a command, or "use the run skill")')
+  }
+  for (const f of ['authBypass', 'seed', 'fixtures']) {
+    if (f in setup && typeof setup[f] !== 'string') errors.push(`setup.${f}: must be a string`)
+  }
+  for (const f of ['env', 'tenants']) {
+    if (f in setup && (!Array.isArray(setup[f]) || setup[f].some((x) => typeof x !== 'string'))) {
+      errors.push(`setup.${f}: must be an array of strings`)
+    }
+  }
+  // The synthetic-tenant registry must cover every tenant a path declares, or a
+  // mutating path could run off-local against a tenant nobody vetted as synthetic.
+  const declared = new Set(Array.isArray(setup.tenants) ? setup.tenants : [])
+  for (const p of paths) {
+    if (p && p.tenant && !declared.has(p.tenant)) {
+      warnings.push(`paths (${p.id}): tenant "${p.tenant}" is not listed in setup.tenants — add it so the synthetic-tenant registry is complete`)
+    }
+  }
+}
+
+// Select the paths to run FOR A NAMED PROFILE, and the ones excluded (with why).
+// Selection is a pure function of the profile name + the manifest — no target/flag
+// assembly — so the run and the verdict, both driven by the same name, cannot
+// disagree about the selected set (the old mismatch is unrepresentable).
+//
+// A path runs iff it declares this profile in its `profiles` array AND the profile's
+// mutationPolicy admits it:
+//   - read-only      → every mutating path is excluded, tenant or not (principle 4:
+//                      the production profiles, wired to the real prod DB, never write)
+//   - synthetic-tenant → a mutating path runs only if it declares a synthetic `tenant`
+//   - isolated-writes  → mutating paths run (a disposable local store)
+// Read-only paths always run when they declare the profile.
+//
+// Throws on an unknown profile name — fail closed: an unnamed profile selects nothing
+// safe to reason about, so it is a hard stop, not a silent empty set.
+export function selectPathsForProfile(manifest, profileName) {
+  const registry = (manifest && manifest.profiles) || {}
+  const profile = registry[profileName]
+  if (!profile) {
+    const known = Object.keys(registry)
+    throw new Error(`unknown profile "${profileName}" — not in the manifest's profiles registry (${known.length ? known.join(', ') : 'no registry'})`)
+  }
+  const run = []
+  const excluded = []
+  for (const p of (manifest.paths || [])) {
+    if (!Array.isArray(p.profiles) || !p.profiles.includes(profileName)) {
+      excluded.push({ id: p.id, reason: `not required in profile "${profileName}"` })
+      continue
+    }
+    if (p.mutates === true) {
+      if (profile.mutationPolicy === 'read-only') {
+        excluded.push({ id: p.id, reason: `mutating path excluded — profile "${profileName}" is read-only (${profile.environment} is never written by this lane, tenant or not)` })
+      } else if (profile.mutationPolicy === 'synthetic-tenant') {
+        if (p.tenant) run.push(p)
+        else excluded.push({ id: p.id, reason: `mutating path excluded — profile "${profileName}" requires a synthetic tenant and this path declares none` })
+      } else {
+        run.push(p) // isolated-writes
+      }
+    } else {
+      run.push(p)
+    }
+  }
+  return { profile: { name: profileName, ...profile }, run, excluded }
+}
+
+// Reduce drive results into the gate verdict.
+//
+// Issue #823: only a `fail` is evidence that the CANDIDATE is broken (DEAD). Every other
+// non-pass status means the GATE could not produce an observation: `blocked` (surface
+// unreachable), `cannot-run` (runner/secret/auth/fixture failure), or `missing` (no result
+// reported). Those must be CANNOT-RUN, not DEAD, so a misconfigured secret does not discard
+// a healthy candidate.
+export function computeVerdict(selected, results) {
+  const byId = new Map((results || []).map((r) => [r.id, r]))
+  const rows = selected.map((p) => {
+    const r = byId.get(p.id)
+    const status = r ? r.status : 'missing'
+    return {
+      id: p.id, surface: p.surface, status,
+      evidence: r && r.evidence,
+      note: r ? r.note : 'no result reported for this path — it was not driven',
+    }
+  })
+
+  // An EMPTY selection is not a pass. "Every selected path passed" is vacuously true when
+  // nothing was selected, and that vacuous truth is reachable in the one place it does the
+  // most damage: a production run under a read-only profile over a golden-path set that is
+  // mostly mutating — which is the normal shape, since golden paths are signup / checkout / purchase.
+  // The gate would then subtract itself to nothing, emit a well-formed ALIVE verdict having
+  // driven zero paths, and hand a green light to whatever shifts traffic next. A gate that
+  // proves nothing must not be indistinguishable from a gate that proved everything.
+  if (rows.length === 0) {
+    return {
+      verdict: 'EMPTY',
+      ok: false,
+      total: 0,
+      broken: [],
+      rows: [],
+      note: 'no paths were selected, so nothing was proven — check the manifest and the selected profile (its `profiles` membership on the paths, and its mutationPolicy: a read-only profile excludes every mutating path)',
+    }
+  }
+
+  const failedPaths = rows.filter((r) => r.status === 'fail')
+  const cannotRunPaths = rows.filter((r) => r.status !== 'pass' && r.status !== 'fail')
+
+  // CANNOT-RUN takes precedence: if the gate itself could not run, the verdict is about the
+  // gate, not the candidate. DEAD means the candidate was reached and failed.
+  if (cannotRunPaths.length > 0) {
+    return {
+      verdict: 'CANNOT-RUN',
+      ok: false,
+      total: rows.length,
+      broken: cannotRunPaths.map((r) => ({ id: r.id, status: r.status, note: r.note })),
+      rows,
+      note: 'the gate could not run for at least one path — the failure is in the gate environment (credential, secret, auth, fixture, driver, or a missing result) and must be repaired before the candidate can be judged. This is not a DEAD candidate.',
+    }
+  }
+
+  return {
+    verdict: failedPaths.length === 0 ? 'ALIVE' : 'DEAD',
+    ok: failedPaths.length === 0,
+    total: rows.length,
+    broken: failedPaths.map((r) => ({ id: r.id, status: r.status, note: r.note })),
+    rows,
+  }
+}
+
+// Stamp the verdict with WHAT it was run against, and WHEN.
+//
+// A bare {verdict, ok, rows} says a gate passed but not what it passed on, so any consumer
+// asking "is this ALIVE for the revision I am about to expose?" can only take the runner's
+// word for it. That is fine for a human reading output and wrong for an automated gate:
+// `resolve-release`'s auto-when-green shifts production traffic on condition (e), "an ALIVE
+// verdict on THAT EXACT candidate", which is unfalsifiable unless the verdict names its
+// target. Recording it turns an assertion into a check.
+//
+// `generatedAt` is the same argument in the time dimension (issue #431). "On that exact
+// candidate" bounds WHICH revision the evidence covers; it does not bound HOW OLD the
+// evidence is — and the release lane validates at 0% traffic, then waits for a human
+// authorization that may arrive hours later, by which time the coordinates may have moved.
+// A consumer can only bound that age if the artifact carries its generation time, so the
+// field is stamped unconditionally (after `extra`, so no caller can suppress it): an
+// unstamped verdict must be impossible to produce, not merely discouraged. Consumers treat
+// its absence as NOT-fresh — absent evidence is not fresh evidence.
+//
+// WHAT IT DATES: the VERDICT, not the RUN. This function stamps when the reduction happened,
+// and the reduction reads a results file of any age — so `verdict --results <old file>` mints
+// a gate-fresh verdict over stale observations, and no consumer can tell. That is deliberate
+// scope, not an oversight: this script owns the decidable shell and never drives the app, so
+// it has no run time to carry. The freshness contract it therefore supports is "this verdict
+// was computed just now," which is only evidence of live coordinates when the results were
+// driven just now. Re-minting a verdict is not re-validation; re-drive the paths.
+export function stampTarget(verdict, target, extra = {}) {
+  return { ...verdict, target: target || 'local', ...extra, generatedAt: new Date().toISOString() }
+}
+
+// A browser path's `journey` field points at the Tier-3 spec that drives it,
+// written as "@smoke <covers-id>" (or a bare id). Pull the @covers id out — that's
+// the key both sides reconcile on. Mirrors the ledger's `route:` stripping.
+export function journeyCoversId(journey) {
+  if (!journey || typeof journey !== 'string') return null
+  const id = journey.trim().replace(/^@smoke\b[:\s]*/i, '').replace(/^route:/, '').trim()
+  return id || null
+}
+
+// Reconcile the manifest's browser paths against the authoritative set of @smoke
+// @covers ids (scanned from the specs). BOTH directions matter and BOTH are errors:
+//  - a manifest path pointing at a journey that isn't @smoke-tagged → the gate
+//    can't drive it (fail-closed, but a broken gate).
+//  - a @smoke-tagged journey missing from the manifest → it silently never runs,
+//    so the gate reports ALIVE while a do-not-ship flow went unchecked (a FALSE
+//    ALIVE — the exact hole the browser=journey reference otherwise leaves open).
+// This is the mechanical backstop for the "make sure the @smoke journey exists"
+// prose: a described precondition degrades to a lookalike, a checked one doesn't.
+export function reconcileJourneys(manifest, smokeCoversIds) {
+  const errors = []
+  const warnings = []
+  const smoke = new Set(smokeCoversIds || [])
+  const referenced = new Set()
+  for (const p of (manifest && manifest.paths) || []) {
+    if (!p || p.surface !== 'browser') continue
+    const id = journeyCoversId(p.journey)
+    if (!id) { warnings.push(`paths (${p.id}): could not read a @covers id from journey "${p.journey}" — can't reconcile it against the @smoke tags`); continue }
+    referenced.add(id)
+    if (!smoke.has(id)) errors.push(`paths (${p.id}): journey "${id}" is not @smoke-tagged in the scanned specs — the gate can't drive it (tag that Tier-3 journey @smoke, or fix the reference)`)
+  }
+  for (const id of smoke) {
+    if (!referenced.has(id)) errors.push(`@smoke journey "${id}" is tagged do-not-ship but absent from the smoke manifest — it would silently never gate (a false ALIVE). Add a browser path referencing it, or drop the @smoke tag.`)
+  }
+  return { errors, warnings }
+}
+
+function normalizeInventory(inventory) {
+  if (!inventory || typeof inventory !== 'object') return []
+  if (Array.isArray(inventory.surfaces)) return inventory.surfaces
+  const grouped = []
+  const groups = [
+    ['routes', 'route'],
+    ['apis', 'api'],
+    ['tables', 'table'],
+    ['events', 'event'],
+    ['jobs', 'job'],
+    ['permissions', 'permission'],
+    ['integrations', 'integration'],
+  ]
+  for (const [key, kind] of groups) {
+    for (const id of inventory[key] || []) grouped.push({ id, kind })
+  }
+  return grouped
+}
+
+function scoreSurface(surface) {
+  const id = String(surface.id || '')
+  const haystack = id.toLowerCase()
+  let score = 0
+  const reasons = []
+
+  if (surface.kind === 'route') {
+    score += 20
+    reasons.push('browser route')
+    if (surface.reachability === 'reachable' || surface.reachability === 'guarded') {
+      score += 20
+      reasons.push(`${surface.reachability} route`)
+    }
+    if (surface.class === 'mutation') {
+      score += 55
+      reasons.push('mutation route')
+    } else if (surface.class === 'detail') {
+      score += 20
+      reasons.push('detail route')
+    }
+  } else if (surface.kind === 'api') {
+    if (/health|ready|live/.test(haystack)) {
+      score += 45
+      reasons.push('health/liveness endpoint')
+    }
+    if (surface.class === 'mutation') {
+      score += 25
+      reasons.push('mutation API')
+    }
+  }
+
+  for (const keyword of GOLDEN_KEYWORDS) {
+    if (haystack.includes(keyword)) {
+      score += 30
+      reasons.push(`keyword:${keyword}`)
+      break
+    }
+  }
+
+  if (/about|help|docs|terms|privacy|status/.test(haystack)) score -= 60
+  return { score, reasons }
+}
+
+export function suggestCandidates(inventory, options = {}) {
+  const limit = Number.isFinite(options.limit) ? options.limit : 8
+  const surfaces = normalizeInventory(inventory)
+  const scored = surfaces
+    .map((surface) => ({ surface, ...scoreSurface(surface) }))
+    .filter(({ score }) => score > 0)
+    .sort((a, b) => b.score - a.score || String(a.surface.id).localeCompare(String(b.surface.id)))
+    .slice(0, limit)
+
+  return {
+    _comment: 'CANDIDATES ONLY. Code can suggest likely golden paths from routes/APIs, but only product/release judgment can decide the smoke manifest. Promote curated entries into smoke.manifest.json paths by writing concrete observables and synthetic tenant data.',
+    candidates: scored.map(({ surface, score, reasons }) => {
+      const isRoute = surface.kind === 'route'
+      const mutates = surface.class === 'mutation'
+      return {
+        id: String(surface.id || '').replace(/^\/+/, '').replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-|-$/g, '') || 'root',
+        surface: isRoute ? 'browser' : 'api',
+        start: isRoute ? surface.id : `${surface.method || (mutates ? 'POST' : 'GET')} ${surface.id}`,
+        mutates,
+        score,
+        reasons,
+        observable: 'TODO: replace with the concrete user-visible/API evidence that proves this critical path worked',
+        tenant: mutates ? 'TODO: synthetic test tenant if this candidate is promoted' : undefined,
+      }
+    }),
+  }
+}
+
+// ---- CLI ----
+
+function parseArgs(argv) {
+  const f = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--manifest') f.manifest = argv[++i]
+    else if (a === '--results') f.results = argv[++i]
+    else if (a === '--target') f.target = argv[++i]
+    else if (a === '--inventory') f.inventory = argv[++i]
+    else if (a === '--journeys') f.journeys = argv[++i]
+    else if (a === '--profile') f.profile = argv[++i]
+    else if (a === '--limit') f.limit = Number(argv[++i])
+    else if (a === '--out') f.out = argv[++i]
+    else if (a === '--json') f.json = true
+    // `--no-mutations` was removed (issue #440): mutation policy is now a property of the
+    // selected profile, not a run flag. Refuse it LOUDLY rather than swallow it — a caller
+    // following the old doctrine would otherwise get silently weaker exclusion (the flag does
+    // nothing) with no warning. Name the replacement so the fix is obvious.
+    else if (a === '--no-mutations') {
+      if (!f._error) f._error = { code: 2, message: 'smoke: --no-mutations was removed — mutation policy is now a profile property, not a run flag. Select a read-only production profile instead (--profile prod-preview / prod-active); production profiles exclude every mutating path regardless of tenant. (see references/manifest.md)' }
+    }
+    // Reject any other unknown flag by name instead of silently ignoring it — a swallowed
+    // flag is a footgun (the caller believes it took effect). This closes the whole class,
+    // not just the one removed flag.
+    else if (a.startsWith('--')) {
+      if (!f._error) f._error = { code: 2, message: `smoke: unknown flag "${a}" — valid flags are --manifest --profile --target --results --inventory --journeys --out --limit --json (see references/manifest.md)` }
+    }
+    else if (!f.cmd) f.cmd = a
+  }
+  return f
+}
+
+function readJson(p) {
+  return JSON.parse(fs.readFileSync(p, 'utf8'))
+}
+
+// Scan a journeys dir for the authoritative @smoke set: any spec file carrying an
+// @smoke marker contributes its @covers ids (same `@covers <id>` regex the ledger
+// uses). File-level association — journey specs are one-journey-per-file by
+// e2e-test convention; a multi-journey file contributes all its ids.
+function scanSmokeTags(dir) {
+  const ids = new Set()
+  const noCovers = []
+  const walk = (d) => {
+    for (const ent of fs.readdirSync(d, { withFileTypes: true })) {
+      const full = `${d}/${ent.name}`
+      if (ent.isDirectory()) { if (ent.name !== 'node_modules') walk(full); continue }
+      if (!/\.(spec|test)\.[cm]?[jt]sx?$/.test(ent.name)) continue
+      const text = fs.readFileSync(full, 'utf8')
+      if (!/@smoke\b/.test(text)) continue
+      const covers = [...text.matchAll(/@covers\s+(\S+)/g)].map((m) => m[1].replace(/^route:/, ''))
+      if (covers.length === 0) noCovers.push(full)
+      for (const c of covers) ids.add(c)
+    }
+  }
+  if (fs.existsSync(dir)) walk(dir)
+  return { ids: [...ids], noCovers }
+}
+
+// Reconcile browser paths against the @smoke tags when a --journeys dir is given.
+// Without it, only warn (and only if there ARE browser paths to reconcile) — an
+// api/cli-only repo has nothing to check, and forcing the flag would break every
+// existing call. With it, drift is an error (see reconcileJourneys).
+function reconcile(manifest, journeysDir) {
+  const hasBrowser = ((manifest && manifest.paths) || []).some((p) => p && p.surface === 'browser')
+  if (!journeysDir) {
+    return hasBrowser
+      ? { errors: [], warnings: ['browser paths not reconciled against @smoke tags — pass --journeys <dir> so a manifest/tag drift is caught (a @smoke journey missing from the manifest is a silent false-ALIVE)'] }
+      : { errors: [], warnings: [] }
+  }
+  const { ids, noCovers } = scanSmokeTags(journeysDir)
+  const r = reconcileJourneys(manifest, ids)
+  for (const f of noCovers) r.warnings.push(`spec tagged @smoke has no @covers id to key on: ${f}`)
+  return r
+}
+
+export function runCli(argv) {
+  const f = parseArgs(argv)
+  if (f._error) { console.error(f._error.message); return f._error.code }
+  if (!f.cmd) { console.error('usage: smoke <validate|plan|suggest|verdict> --manifest <f> [--profile <name>] [--target <url>] [--results <f>]'); return 2 }
+
+  if (f.cmd === 'suggest') {
+    if (!f.inventory) { console.error('--inventory is required for suggest'); return 2 }
+    const candidates = suggestCandidates(readJson(f.inventory), { limit: f.limit })
+    if (f.out) fs.writeFileSync(f.out, JSON.stringify(candidates, null, 2))
+    console.log(JSON.stringify(candidates, null, 2))
+    return 0
+  }
+
+  if (!f.manifest) { console.error('--manifest is required'); return 2 }
+  // A *missing* manifest is not an *invalid* one — it means no golden-path set
+  // has been curated yet. Route to bootstrap instead of crashing with ENOENT, so
+  // "ensure a manifest exists" is a clear next step rather than a stack trace.
+  if (!fs.existsSync(f.manifest)) {
+    console.error(`smoke: no manifest at ${f.manifest} — there is no curated golden-path set yet.`)
+    console.error('  ensure one before gating: seed candidates from the surface inventory, then curate per product judgment:')
+    console.error('    node smoke.mjs suggest --inventory docs/tests/_generated/surface-inventory.json --out smoke.candidates.json')
+    console.error('  promote only the release-blocking candidates into smoke.manifest.json (concrete observables, synthetic tenants), then `validate`.')
+    console.error('  (see references/manifest.md — the skill ships no default set; you author it per app.)')
+    return 2
+  }
+  const manifest = readJson(f.manifest)
+
+  if (f.cmd === 'validate') {
+    const shape = validateManifest(manifest)
+    const rec = reconcile(manifest, f.journeys)
+    const errors = [...shape.errors, ...rec.errors]
+    const warnings = [...shape.warnings, ...rec.warnings]
+    const ok = errors.length === 0
+    if (f.json) console.log(JSON.stringify({ ok, errors, warnings }, null, 2))
+    else {
+      if (ok) console.log(`smoke: ✓ manifest valid (${manifest.paths.length} golden path(s))`)
+      else { console.log('smoke: ✗ manifest invalid:'); errors.forEach((e) => console.log(`  - ${e}`)) }
+      warnings.forEach((w) => console.log(`  ⚠ ${w}`))
+    }
+    return ok ? 0 : 1
+  }
+
+  const { ok, errors, warnings } = validateManifest(manifest)
+  if (!ok) { console.error('smoke: manifest invalid — fix it before plan/verdict:'); errors.forEach((e) => console.error(`  - ${e}`)); return 1 }
+  warnings.forEach((w) => console.error(`smoke: ⚠ ${w}`))
+  const rec = reconcile(manifest, f.journeys)
+  if (rec.errors.length) { console.error('smoke: manifest/@smoke reconciliation failed — fix before plan/verdict:'); rec.errors.forEach((e) => console.error(`  - ${e}`)); return 1 }
+  rec.warnings.forEach((w) => console.error(`smoke: ⚠ ${w}`))
+
+  if (f.cmd === 'plan') {
+    if (!f.profile) { console.error('--profile is required for plan (selection is by named Validation Profile — see references/manifest.md)'); return 2 }
+    let sel
+    try { sel = selectPathsForProfile(manifest, f.profile) } catch (e) { console.error(`smoke: ${e.message}`); return 1 }
+    const { profile, run, excluded } = sel
+    const target = f.target || 'local'
+    const plan = { profile, target, run: run.map((p) => ({ id: p.id, surface: p.surface, drive: p.journey || p.start || p.command, observable: p.observable })), excluded }
+    if (f.json) console.log(JSON.stringify(plan, null, 2))
+    else {
+      console.log(`smoke plan — profile: ${profile.name} (${profile.gate} · ${profile.environment}/${profile.endpoint} · ${profile.mutationPolicy}) — target: ${target}`)
+      run.forEach((p) => console.log(`  ▶ ${p.id} [${p.surface}] — ${p.observable || p.journey}`))
+      excluded.forEach((e) => console.log(`  ⤫ ${e.id} — ${e.reason}`))
+    }
+    return 0
+  }
+
+  if (f.cmd === 'verdict') {
+    if (!f.profile) { console.error('--profile is required for verdict (the SAME profile the run used, so run and verdict select one set)'); return 2 }
+    if (!f.results) { console.error('--results is required for verdict'); return 2 }
+    let sel
+    try { sel = selectPathsForProfile(manifest, f.profile) } catch (e) { console.error(`smoke: ${e.message}`); return 1 }
+    const { profile, run } = sel
+    // The read-only flag green-gate.mjs reads is DERIVED from the profile, not passed by the
+    // caller: a production (read-only) profile ⇒ noMutations:true, mechanically enforcing
+    // principle 4 without a flag anyone has to remember.
+    const noMutations = profile.mutationPolicy === 'read-only'
+    const v = stampTarget(computeVerdict(run, readJson(f.results)), f.target, { profile: f.profile, noMutations })
+    if (f.out) fs.writeFileSync(f.out, JSON.stringify(v, null, 2))
+    if (f.json) console.log(JSON.stringify(v, null, 2))
+    else if (v.verdict === 'EMPTY') {
+      console.log('smoke: ⚠ EMPTY — 0 golden paths selected, so this run proves nothing')
+      console.log(`  ${v.note}`)
+    } else {
+      console.log(`smoke: ${v.ok ? '✅ ALIVE' : '❌ DEAD'} — ${v.total - v.broken.length}/${v.total} golden path(s) passed`)
+      v.broken.forEach((b) => console.log(`  ✗ ${b.id} [${b.status}] — ${b.note}`))
+    }
+    return v.ok ? 0 : 1
+  }
+
+  console.error(`unknown command: ${f.cmd}`)
+  return 2
+}
+
+if (isMainModule(import.meta.url)) process.exit(runCli(process.argv.slice(2)))