rcf-lite 0.27.0 → 0.28.0

package/blueprints/platform-docker-compose-host/contributions/probes/compose-config-lint.mjs

@@ -1,52 +1,54 @@
-// Probe: compose-config-lint.
+// Probe: compose-config-lint (v1.1.8).
 //
-// anchorAcId list (multi): AC-composeHost-healthcheckLint (primary),
-// AC-composeHost-restartClassification, AC-composeHost-logDriverClassification.
-// accountBound: false.
+// This is an offline validator: it parses the shipped compose.yaml
+// and (when a Docker daemon is reachable) shells out to
+// `docker compose config`. It has no engine-minted identifier - the
+// sha256 of compose.yaml is computed by this probe with Node's
+// `createHash` and the service names are Compose's own choices, not
+// engine-returned identities. Every result row is a
+// `conformanceOnly` de-claim naming the shipped AC clause the
+// offline check does not observe; the live observation for each
+// property lives on the account-bound probes that stand a real
+// compose stack up.
+//
+// Splits per-property observations into their own result rows:
+//   - AC-composeHost-healthcheckLint  per HTTP-terminating service.
+//   - AC-composeHost-restartClassification  per service.
+//   - AC-composeHost-logDriverClassification  per service, and one
+//     top-level check that every service uses the single elicited
+//     driver (LOG_DRIVER env, default journald).
+//   - AC-composeHost-healthcheckLint  one summary docker-compose-config
+//     exit row when the daemon is reachable.
 //
-// Passes when:
-// - docker compose config exits 0 against the applied fixture compose.yaml
-//   (the daemon must be reachable; when the docker CLI is missing, the
-//   lint stage records a warn result so the source-tree assertions still
-//   surface).
-// - every HTTP-terminating service (web) declares a healthcheck block.
-// - every service declares a restart policy whose value is unless-stopped
-//   or on-failure.
-// - every service declares a logging driver whose value is journald or loki.
-// - a scan of the composeStackReady lifecycle event body captured by the
-//   in-process facade proves no secret literal leaks.
+// The compose.yaml bytes hash and the observed values (driver,
+// restart policy, healthcheck keys, docker compose config exit)
+// stay on the row as derived context.
 //
-// Mutations (each fails; each names the offending service or literal):
-// - SIMULATE_MISSING_HEALTHCHECK=true strips the healthcheck: block from
-//   the web service before the compose-config-lint scan.
-// - SIMULATE_UNCLASSIFIED_RESTART=true rewrites restart: unless-stopped
-//   on the web service to restart: always.
-// - SIMULATE_UNCLASSIFIED_LOG_DRIVER=true rewrites the web service
-//   logging.driver from journald to syslog.
-// - SIMULATE_EVENT_SECRECY_LEAK=true injects the fixture web-token value
-//   into the composeStackReady event body; the event-secrecy scan FAILS.
+// accountBound: false.
 
 import { spawnSync } from 'node:child_process';
-import { readFile, readdir } from 'node:fs/promises';
-import { resolve } from 'node:path';
-import { runShim, readCompose, COMPOSE_PATH, FIXTURE_DIR, SECRET_PATH, whichDocker } from './probe-utils.mjs';
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { runShim, readCompose, COMPOSE_PATH, FIXTURE_DIR, whichDocker, parseComposeYaml } from './probe-utils.mjs';
+
+function sha256(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}
 
-export const anchorAcIds = [
-  'AC-composeHost-healthcheckLint',
-  'AC-composeHost-restartClassification',
-  'AC-composeHost-logDriverClassification',
-];
+export const anchorAcIds = [];
 export const accountBound = false;
 
 const HTTP_SERVICES = new Set(['web', 'caddy']);
 const ALLOWED_RESTART = new Set(['unless-stopped', 'on-failure']);
 const ALLOWED_LOG_DRIVER = new Set(['journald', 'loki']);
 
+const LIMIT_HC = 'AC-composeHost-healthcheckLint: healthcheck presence is validated offline against the shipped compose.yaml; the live observation (a healthy compose service reporting healthy in `docker compose ps`) is carried by real-account-minimal-stack-up.';
+const LIMIT_RESTART = 'AC-composeHost-restartClassification: restart-policy classification is validated offline against the shipped compose.yaml; the live observation (a compose stack applying and honouring the policy) is carried by real-account-minimal-stack-up.';
+const LIMIT_LOG = 'AC-composeHost-logDriverClassification: log-driver classification is validated offline against the shipped compose.yaml against the elicited LOG_DRIVER; the live observation (a compose stack routing logs through the applied driver) lives on the account-bound branch.';
+
 function applyMutations(text) {
   let out = text;
   if (process.env.SIMULATE_MISSING_HEALTHCHECK === 'true') {
-    // Strip the healthcheck: block from the web service by removing
-    // the healthcheck: line and its indented children.
     const lines = out.split('\n');
     const trimmed = [];
     let stripping = false;
@@ -58,7 +60,6 @@ function applyMutations(text) {
         if (line.trim() === '' || indent > stripIndent) continue;
         stripping = false;
       }
-      // Only strip inside the web service, not caddy.
       if (line.match(/^\s{4}healthcheck:\s*$/) && trimmed.slice(-30).some((l) => l.match(/^\s{2}web:\s*$/))) {
         const m = line.match(/^(\s*)/);
         stripIndent = m ? m[1].length : 0;
@@ -78,50 +79,139 @@ function applyMutations(text) {
   return out;
 }
 
-function scanServices(doc) {
+function scanHealthchecks(doc, extra, composeSha256) {
   const results = [];
   const services = doc.services ?? {};
-  const names = Object.keys(services);
-  for (const name of names) {
+  const httpNames = Object.keys(services).filter((n) => HTTP_SERVICES.has(n));
+  for (const name of httpNames) {
     const svc = services[name] ?? {};
-    if (HTTP_SERVICES.has(name)) {
-      if (!svc.healthcheck) {
-        results.push({
-          anchorAcId: 'AC-composeHost-healthcheckLint',
-          verdict: 'fail',
-          detail: `HTTP-terminating service '${name}' is missing a healthcheck: block`,
-        });
-      }
+    if (!svc.healthcheck) {
+      results.push({
+        anchorAcId: null,
+        conformanceOnly: true,
+        limitation: LIMIT_HC,
+        verdict: 'fail',
+        detail: `offline compose-config-lint: HTTP-terminating service '${name}' is missing a healthcheck: block`,
+        evidence: { composeSha256, serviceName: name, missingServices: [name], expectedShape: 'healthcheck block', observedShape: 'absent' },
+      });
+    } else {
+      results.push({
+        anchorAcId: null,
+        conformanceOnly: true,
+        limitation: LIMIT_HC,
+        verdict: 'pass',
+        detail: `offline compose-config-lint: HTTP-terminating service '${name}' carries a healthcheck: block`,
+        evidence: {
+          composeSha256,
+          serviceName: name,
+          healthcheckKeys: Object.keys(svc.healthcheck || {}).sort(),
+        },
+      });
     }
+  }
+  return results;
+}
+
+function scanRestart(doc, composeSha256) {
+  const results = [];
+  const services = doc.services ?? {};
+  for (const name of Object.keys(services)) {
+    const svc = services[name] ?? {};
     const restart = svc.restart;
     if (!restart) {
       results.push({
-        anchorAcId: 'AC-composeHost-restartClassification',
+        anchorAcId: null,
+        conformanceOnly: true,
+        limitation: LIMIT_RESTART,
         verdict: 'fail',
-        detail: `service '${name}' declares no restart policy; allowed: unless-stopped, on-failure`,
+        detail: `offline compose-config-lint: service '${name}' declares no restart policy; allowed: unless-stopped, on-failure`,
+        evidence: { composeSha256, serviceName: name, restart: null },
       });
     } else if (!ALLOWED_RESTART.has(String(restart))) {
       results.push({
-        anchorAcId: 'AC-composeHost-restartClassification',
+        anchorAcId: null,
+        conformanceOnly: true,
+        limitation: LIMIT_RESTART,
         verdict: 'fail',
-        detail: `service '${name}' declares restart: ${restart}; allowed: unless-stopped, on-failure`,
+        detail: `offline compose-config-lint: service '${name}' declares restart: ${restart}; allowed: unless-stopped, on-failure`,
+        evidence: { composeSha256, serviceName: name, restart: String(restart), allowed: ['unless-stopped', 'on-failure'] },
+      });
+    } else {
+      results.push({
+        anchorAcId: null,
+        conformanceOnly: true,
+        limitation: LIMIT_RESTART,
+        verdict: 'pass',
+        detail: `offline compose-config-lint: service '${name}' declares restart: ${restart}`,
+        evidence: { composeSha256, serviceName: name, restart: String(restart) },
       });
     }
-    const logging = svc.logging;
-    const driver = logging && logging.driver;
+  }
+  return results;
+}
+
+function scanLogging(doc, composeSha256) {
+  const results = [];
+  const services = doc.services ?? {};
+  const elicitedDriver = process.env.LOG_DRIVER || 'journald';
+  const observedDrivers = [];
+  for (const name of Object.keys(services)) {
+    const svc = services[name] ?? {};
+    const driver = svc.logging && svc.logging.driver;
     if (!driver) {
       results.push({
-        anchorAcId: 'AC-composeHost-logDriverClassification',
+        anchorAcId: null,
+        conformanceOnly: true,
+        limitation: LIMIT_LOG,
         verdict: 'fail',
-        detail: `service '${name}' declares no logging driver; allowed: journald, loki`,
+        detail: `offline compose-config-lint: service '${name}' declares no logging driver; allowed: journald, loki`,
+        evidence: { composeSha256, serviceName: name, driver: null },
       });
-    } else if (!ALLOWED_LOG_DRIVER.has(String(driver))) {
+      observedDrivers.push(null);
+      continue;
+    }
+    if (!ALLOWED_LOG_DRIVER.has(String(driver))) {
       results.push({
-        anchorAcId: 'AC-composeHost-logDriverClassification',
+        anchorAcId: null,
+        conformanceOnly: true,
+        limitation: LIMIT_LOG,
         verdict: 'fail',
-        detail: `service '${name}' declares logging driver '${driver}'; allowed: journald, loki`,
+        detail: `offline compose-config-lint: service '${name}' declares logging driver '${driver}'; allowed: journald, loki`,
+        evidence: { composeSha256, serviceName: name, driver: String(driver), allowed: ['journald', 'loki'] },
       });
+      observedDrivers.push(String(driver));
+      continue;
     }
+    observedDrivers.push(String(driver));
+  }
+  const distinct = new Set(observedDrivers.filter(Boolean));
+  if (distinct.size > 1) {
+    results.push({
+      anchorAcId: null,
+      conformanceOnly: true,
+      limitation: LIMIT_LOG,
+      verdict: 'fail',
+      detail: `offline compose-config-lint: services declare more than one log driver (${[...distinct].join(', ')}); the elicited log-driver=${elicitedDriver} requires every service to match`,
+      evidence: { composeSha256, composeFile: 'compose.yaml', elicitedDriver, observedDrivers, distinct: [...distinct] },
+    });
+  } else if (distinct.size === 1 && !distinct.has(elicitedDriver)) {
+    results.push({
+      anchorAcId: null,
+      conformanceOnly: true,
+      limitation: LIMIT_LOG,
+      verdict: 'fail',
+      detail: `offline compose-config-lint: services declare log driver ${[...distinct][0]} but the elicited log-driver is ${elicitedDriver}`,
+      evidence: { composeSha256, composeFile: 'compose.yaml', elicitedDriver, observedDrivers },
+    });
+  } else if (distinct.size === 1) {
+    results.push({
+      anchorAcId: null,
+      conformanceOnly: true,
+      limitation: LIMIT_LOG,
+      verdict: 'pass',
+      detail: `offline compose-config-lint: every service uses the elicited log driver ${[...distinct][0]}`,
+      evidence: { composeSha256, composeFile: 'compose.yaml', elicitedDriver, observedDrivers },
+    });
   }
   return results;
 }
@@ -129,44 +219,43 @@ function scanServices(doc) {
 export default async function runProbe() {
   const results = [];
   const extra = {};
-  // Source-tree scan on the (possibly mutated) compose file.
   const originalText = await readFile(COMPOSE_PATH, 'utf8');
   const mutatedText = applyMutations(originalText);
-  const { doc: origDoc } = await readCompose();
-  const { parseComposeYaml } = await import('./probe-utils.mjs');
+  const composeSha256 = sha256(mutatedText);
+  extra.composeSha256 = composeSha256;
   const mutatedDoc = parseComposeYaml(mutatedText);
-  const scanResults = scanServices(mutatedDoc);
-  results.push(...scanResults);
   extra.serviceNames = Object.keys(mutatedDoc.services ?? {});
   extra.mutations = {
     missingHealthcheck: process.env.SIMULATE_MISSING_HEALTHCHECK === 'true',
     unclassifiedRestart: process.env.SIMULATE_UNCLASSIFIED_RESTART === 'true',
     unclassifiedLogDriver: process.env.SIMULATE_UNCLASSIFIED_LOG_DRIVER === 'true',
-    eventSecrecyLeak: process.env.SIMULATE_EVENT_SECRECY_LEAK === 'true',
   };
-  // docker compose config lint (on the mutated text, via a scratch file).
+  results.push(...scanHealthchecks(mutatedDoc, extra, composeSha256));
+  results.push(...scanRestart(mutatedDoc, composeSha256));
+  results.push(...scanLogging(mutatedDoc, composeSha256));
   const dockerVersion = whichDocker();
   extra.dockerVersion = dockerVersion;
   if (dockerVersion === null) {
     results.push({
-      anchorAcId: 'AC-composeHost-healthcheckLint',
+      anchorAcId: null,
+      conformanceOnly: true,
+      limitation: LIMIT_HC,
       verdict: 'warn',
-      detail: 'docker CLI absent on PATH; source-tree assertions ran but docker compose config was not exercised',
+      detail: 'offline compose-config-lint: docker CLI absent on PATH; source-tree assertions ran but docker compose config was not exercised',
+      evidence: { composeSha256, dockerLocal: null },
     });
   } else {
-    const { writeFile, mkdir } = await import('node:fs/promises');
+    const { writeFile, mkdir, cp } = await import('node:fs/promises');
     const { tmpdir } = await import('node:os');
     const { join } = await import('node:path');
     const scratch = join(tmpdir(), `rcf-lite-t2-compose-config-lint-${Date.now()}`);
     await mkdir(scratch, { recursive: true });
     await writeFile(join(scratch, 'compose.yaml'), mutatedText, 'utf8');
-    // Copy .env, caddy/, secrets/, src/ so docker compose config can resolve references
-    const { cp } = await import('node:fs/promises');
     for (const rel of ['.env', 'caddy', 'secrets', 'src']) {
       try {
         await cp(join(FIXTURE_DIR, rel), join(scratch, rel), { recursive: true });
       } catch (err) {
-        // best-effort; docker compose config still validates syntax
+        // best-effort
       }
     }
     const cfg = spawnSync('docker', ['compose', '-f', join(scratch, 'compose.yaml'), 'config'], {
@@ -174,54 +263,37 @@ export default async function runProbe() {
     });
     if (cfg.status === 0) {
       results.push({
-        anchorAcId: 'AC-composeHost-healthcheckLint',
+        anchorAcId: null,
+        conformanceOnly: true,
+        limitation: LIMIT_HC,
         verdict: 'pass',
-        detail: 'docker compose config exit 0 on the applied compose.yaml',
+        detail: `offline compose-config-lint: docker compose config exit 0 (docker ${dockerVersion})`,
+        evidence: {
+          composeSha256,
+          composeFile: 'compose.yaml',
+          dockerVersion,
+          engineNote: 'Docker Engine (compose sub-command); vendor documentation https://docs.docker.com/compose/compose-file/, verifiedOn 2026-09-11',
+          exitStatus: 0,
+        },
       });
     } else {
       results.push({
-        anchorAcId: 'AC-composeHost-healthcheckLint',
+        anchorAcId: null,
+        conformanceOnly: true,
+        limitation: LIMIT_HC,
         verdict: 'fail',
-        detail: `docker compose config exit ${cfg.status}: ${(cfg.stderr || cfg.stdout || '').slice(0, 400)}`,
+        detail: `offline compose-config-lint: docker compose config exit ${cfg.status}: ${(cfg.stderr || cfg.stdout || '').slice(0, 400)}`,
+        evidence: {
+          composeSha256,
+          composeFile: 'compose.yaml',
+          dockerVersion,
+          exitStatus: cfg.status,
+          stderr: (cfg.stderr || '').slice(0, 400),
+        },
       });
     }
     extra.dockerComposeConfigExit = cfg.status;
   }
-  // Event-secrecy scan: capture a composeStackReady event body and assert
-  // no secret literal appears; SIMULATE_EVENT_SECRECY_LEAK injects one.
-  const secretValue = (await readFile(SECRET_PATH, 'utf8')).trim();
-  const event = {
-    kind: 'composeStackReady',
-    services: extra.serviceNames,
-    imageDigests: extra.serviceNames.map((n) => `sha256:fixture-${n}`),
-    healthTimesMs: extra.serviceNames.map(() => 42),
-  };
-  if (process.env.SIMULATE_EVENT_SECRECY_LEAK === 'true') {
-    event.debug = { boundToken: secretValue };
-  }
-  const eventBody = JSON.stringify(event);
-  if (eventBody.includes(secretValue)) {
-    results.push({
-      anchorAcId: 'AC-composeHost-healthcheckLint',
-      verdict: 'fail',
-      detail: `composeStackReady event body carries the fixture secret literal (event-secrecy leak): ${eventBody.slice(0, 200)}`,
-    });
-  } else {
-    results.push({
-      anchorAcId: 'AC-composeHost-healthcheckLint',
-      verdict: 'pass',
-      detail: 'composeStackReady event body carries no secret literal (event-secrecy scan clean)',
-    });
-  }
-  extra.eventBodyByteLength = eventBody.length;
-  // Passing summary line when nothing failed.
-  if (!results.some((r) => r.verdict === 'fail')) {
-    results.push({
-      anchorAcId: 'AC-composeHost-healthcheckLint',
-      verdict: 'pass',
-      detail: `compose-config-lint pass: services ${extra.serviceNames.join(', ')}; healthcheck + restart + logging + event-secrecy scans all clean`,
-    });
-  }
   return { results, extra };
 }
 

package/blueprints/platform-docker-compose-host/contributions/probes/probe-utils.mjs

@@ -1,19 +1,32 @@
-// Shared helpers for platform-docker-compose-host probes.
-//
+// Shared helpers for platform-docker-compose-host probes (v1.1.4,
+// v1.1.5, 2026-09-11).
+
+// Every result row a probe returns MUST carry either an `evidence`
+// object naming the observed artefact (compose service list, on-server
+// response body excerpt, burst counters, event body sample) OR
+// `accountBoundSkipped: true` with a `reason` field naming exactly
+// one unset variable (the shape rule). Empty or null probe outcomes
+// FAIL with detail exactly `no checks ran`.
+
 // Runtime-dependency posture:
 // - compose-config-lint shells to docker compose config against the applied
 //   fixture compose.yaml; the docker daemon must be reachable locally for
 //   the lint stage (skipped-with-warn when the CLI is absent so a
 //   review machine without docker can still see the source-tree assertions).
 // - secrets-as-files-scan runs in-process against the fixture; no external
-//   engine required.
+//   engine required. Scans compose.yaml, .env, every service config
+//   under caddy/, secrets/ metadata and the compose secret-shape.
 // - caddyfile-validate shells to caddy validate. When a local caddy binary
 //   is not on PATH the probe runs the vendor container caddy:2 via docker
-//   run --rm; when docker is also absent it skips-with-warn.
+//   run --rm; when docker is also absent it skips-with-warn. The probe
+//   also asserts the compose file bind-mounts the Caddyfile read-only.
 // - real-account-* probes call the fixture's provision.mjs, drive docker
 //   compose over ssh against the throwaway server, and tear down in
-//   always(). Without CI_HAS_HETZNER_ACCOUNT they record accountBoundSkipped:
-//   true and the aggregate flips to pass per the real-account gate contract, section 3.5.
+//   always(). Without CI_HAS_HETZNER_ACCOUNT set to exactly the string
+//   "true" the probe records accountBoundSkipped: true and a reason
+//   naming CI_HAS_HETZNER_ACCOUNT (set-but-not-true reported as such,
+//   distinguished from unset). A second-tier HCLOUD_TOKEN unset once
+//   past the first-tier gate has its own honest skip row.
 
 import { mkdir, writeFile, readFile } from 'node:fs/promises';
 import { dirname, resolve, join } from 'node:path';
@@ -30,31 +43,75 @@ export const COMPOSE_PATH = resolve(FIXTURE_DIR, 'compose.yaml');
 export const CADDYFILE_PATH = resolve(FIXTURE_DIR, 'caddy/Caddyfile');
 export const SECRET_PATH = resolve(FIXTURE_DIR, 'secrets/web-token');
 export const ENV_PATH = resolve(FIXTURE_DIR, '.env');
-export const REPORT_DIR = resolve(
-  PROJECT_ROOT,
-  '.rcf/reports/blueprints/platform-docker-compose-host',
-);
+export const REPORT_DIR = process.env.RCF_REPORT_DIR_OVERRIDE
+  ? resolve(process.env.RCF_REPORT_DIR_OVERRIDE, 'blueprints/platform-docker-compose-host')
+  : resolve(PROJECT_ROOT, '.rcf/reports/blueprints/platform-docker-compose-host');
+export const BLUEPRINT_JSON_PATH = resolve(HERE, '..', '..', 'blueprint.json');
+
+// The report's `version` field is read from the blueprint's own
+// blueprint.json at write time; every regenerated record therefore
+// carries the version the shipped code was at when the record was
+// written. The strict walker compares each record's `version` to
+// blueprint.json's `version` and FAILS on any mismatch (a record
+// at an older version fails the walk). The read is deliberately
+// per-call so a version bump between two writes in one process is
+// picked up honestly.
+async function readBlueprintVersion() {
+  const raw = await readFile(BLUEPRINT_JSON_PATH, 'utf8');
+  const doc = JSON.parse(raw);
+  if (typeof doc.version !== 'string' || doc.version.length === 0) {
+    throw new Error(`blueprint.json at ${BLUEPRINT_JSON_PATH} carries no string version`);
+  }
+  return doc.version;
+}
 
 export function aggregate(results) {
+  if (!Array.isArray(results) || results.length === 0) return 'fail';
   if (results.some((r) => r.verdict === 'fail')) return 'fail';
   if (results.some((r) => r.verdict === 'warn')) return 'warn';
   return 'pass';
 }
 
+// An empty results array is an honest failure of the probe: no anchor
+// can be manufactured. Callers that KNOW the anchor may pass it in;
+// otherwise the row carries anchorAcId: null so downstream tallies do
+// not see an invented AC id.
+export function emptyResultsFail(anchorAcId = null) {
+  return {
+    anchorAcId: anchorAcId ?? null,
+    verdict: 'fail',
+    detail: 'no checks ran',
+    evidence: { reason: 'the probe returned zero result rows', probeName: '(unknown at empty-fail construction)' },
+  };
+}
+
 export function isSkipped(results) {
-  return results.length > 0 && results.every((r) => r.accountBoundSkipped === true);
+  return Array.isArray(results) && results.length > 0 && results.every((r) => r.accountBoundSkipped === true);
 }
 
 export async function writeReport({ probeName, engine, results, extra }) {
   await mkdir(REPORT_DIR, { recursive: true });
-  const rawVerdict = aggregate(results);
-  const aggregateVerdict = isSkipped(results) ? 'pass' : rawVerdict;
+  const rows = Array.isArray(results) && results.length > 0 ? results : [emptyResultsFail()];
+  // the anchor-prefix rule: every row's detail starts with the first eight
+  // words of the anchored AC text. The prepend is idempotent so a
+  // caller that already wrapped its detail via `anchored()` does not
+  // double up.
+  for (const r of rows) {
+    const prefix = r && r.anchorAcId && AC_ANCHOR_PREFIX[r.anchorAcId];
+    if (prefix && typeof r.detail === 'string' && !r.detail.startsWith(prefix)) {
+      r.detail = `${prefix}. ${r.detail}`;
+    }
+  }
+  const rawVerdict = aggregate(rows);
+  const aggregateVerdict = isSkipped(rows) ? 'pass' : rawVerdict;
+  const version = await readBlueprintVersion();
   const report = {
     slug: 'platform-docker-compose-host',
     probeName,
+    version,
     runAt: new Date().toISOString(),
     engine,
-    results,
+    results: rows,
     aggregateVerdict,
     ...(extra ?? {}),
   };
@@ -65,17 +122,26 @@ export async function writeReport({ probeName, engine, results, extra }) {
 
 export async function runShim(probeName, engine, mainFn) {
   try {
-    const outcome = (await mainFn()) ?? { results: [] };
-    const { results, extra } = outcome;
-    const { report, path } = await writeReport({ probeName, engine, results, extra });
+    const outcome = await mainFn();
+    const results = (outcome && Array.isArray(outcome.results)) ? outcome.results : null;
+    const extra = outcome && outcome.extra;
+    const rows = results && results.length > 0 ? results : [emptyResultsFail()];
+    const { report, path } = await writeReport({ probeName, engine, results: rows, extra });
     process.stdout.write(JSON.stringify(report, null, 2) + '\n');
     process.stdout.write(`report written to ${path}\n`);
     if (report.aggregateVerdict === 'fail') process.exitCode = 1;
   } catch (err) {
+    // A probe that throws has no known anchor at this layer; use null
+    // rather than the invented "unknown" fallback (defect).
     const results = [{
-      anchorAcId: 'unknown',
+      anchorAcId: null,
       verdict: 'fail',
       detail: `probe threw: ${err && err.message ? err.message : String(err)}`,
+      evidence: {
+        probeName,
+        errorMessage: err && err.message ? err.message : String(err),
+        errorStack: (err && err.stack ? err.stack : String(err)).slice(0, 800),
+      },
     }];
     const { report, path } = await writeReport({ probeName, engine, results });
     process.stdout.write(JSON.stringify(report, null, 2) + '\n');
@@ -85,21 +151,46 @@ export async function runShim(probeName, engine, mainFn) {
   }
 }
 
-export function accountBoundSkippedResult(anchorAcId, note) {
+// Skip helper (the shape rule): the reason field names exactly one
+// unset variable; the gateState field distinguishes unset from
+// set-but-not-true, so a variable set to `false` is never reported as
+// unset. Callers hand the anchor plus a short note.
+export function firstTierGateSkipResult(anchorAcId, varName = 'CI_HAS_HETZNER_ACCOUNT', note = '') {
+  const observed = process.env[varName];
+  const state = observed === undefined
+    ? `unset`
+    : `set-but-not-true (observed value ${JSON.stringify(observed)})`;
   return {
     anchorAcId,
     verdict: 'skipped',
     accountBoundSkipped: true,
-    detail: `accountBound: CI_HAS_HETZNER_ACCOUNT unset; ${note}`,
+    reason: varName,
+    gateState: state,
+    detail: `accountBoundSkipped: gate variable ${varName} ${state}; ${note || 'run with CI_HAS_HETZNER_ACCOUNT=true to exercise the account-bound branch.'}`,
   };
 }
 
+// Second-tier skip helper (the shape rule): the account-bound branch
+// requires HCLOUD_TOKEN once the first-tier gate is true. When only the
+// second-tier is missing the skip row names HCLOUD_TOKEN literally and
+// still aggregates to pass; missing configuration is a skip, not a
+// failure.
+export function secondTierMissingSkipResult(anchorAcId, varName, note = '') {
+  return {
+    anchorAcId,
+    verdict: 'skipped',
+    accountBoundSkipped: true,
+    reason: varName,
+    gateState: 'unset',
+    detail: `accountBoundSkipped: second-tier variable ${varName} unset while CI_HAS_HETZNER_ACCOUNT=true; ${note || 'the probe cannot open the vendor client.'}`,
+  };
+}
+
+export function accountBoundSkippedResult(anchorAcId, note) {
+  return firstTierGateSkipResult(anchorAcId, 'CI_HAS_HETZNER_ACCOUNT', note);
+}
+
 // Small YAML subset parser tuned for the fixture compose.yaml shape.
-// The fixture keeps compose.yaml intentionally simple (two-space indent,
-// no anchors, no flow-style scalars) so the probes stay dependency-free.
-// If a probe needs a full parser later, this returns a shape sufficient
-// for the assertions the ACs make (services, networks, volumes, secrets,
-// env_file, healthcheck presence, restart, logging.driver).
 export function parseComposeYaml(text) {
   const doc = {};
   const lines = text.split(/\r?\n/);
@@ -135,6 +226,15 @@ export function parseComposeYaml(text) {
         } else {
           obj[key] = decodeScalar(val.trim());
           parent.push(obj);
+          // Push the list-item object onto the stack so subsequent
+          // lines indented deeper than the list marker are added as
+          // sibling fields on the same object (e.g. the compose
+          // long-form service-secret entry:
+          //   - source: web-token
+          //     target: web-token
+          //     mode: 0400
+          // must land as {source, target, mode} on one item).
+          stack.push({ indent, node: obj });
         }
       } else {
         parent.push(decodeScalar(rest.trim()));
@@ -145,7 +245,6 @@ export function parseComposeYaml(text) {
     if (!kv) continue;
     const [, key, val] = kv;
     if (val === '') {
-      // Peek: next non-empty non-comment line starting with '- ' means list.
       let peekIsList = false;
       for (let j = lines.indexOf(raw) + 1; j < lines.length; j++) {
         const nxt = lines[j];
@@ -183,3 +282,24 @@ export function whichCaddy() {
   const r = spawnSync('caddy', ['version'], { encoding: 'utf8' });
   return r.status === 0 ? (r.stdout || '').trim() : null;
 }
+
+// the anchor-prefix rule: every result row's detail starts with the first
+// eight words of the anchored AC text. This map holds those prefixes
+// for the platform-docker-compose-host ACs; callers wrap their detail
+// via `anchored(anchorAcId, detail)`.
+export const AC_ANCHOR_PREFIX = {
+  'AC-composeHost-upClean': 'The real-account-minimal-stack-up probe, when CI_HAS_HETZNER_ACCOUNT is set, scps the',
+  'AC-composeHost-zeroDowntimeReload': 'The real-account-reload-burst probe, when CI_HAS_HETZNER_ACCOUNT is set, runs undici',
+  'AC-composeHost-healthcheckLint': 'The compose-config-lint probe shells to docker compose config against',
+  'AC-composeHost-restartClassification': 'The compose-config-lint probe asserts every service in the compose.yaml',
+  'AC-composeHost-logDriverClassification': 'Every service in the applied compose.yaml declares a logging',
+  'AC-composeHost-reverseProxyArtefactValid': 'The applied fixture ships caddy/Caddyfile under a caddy/ directory',
+  'AC-composeHost-secretsAreFiles': 'The secrets-as-files-scan probe walks compose.yaml plus every referenced service',
+  'AC-composeHost-secretShape': 'The applied compose.yaml declares at least one secret under',
+  'AC-38107-4': 'Read-only bind-mount: the reverse-proxy config bind-mount in compose.yaml is',
+};
+
+export function anchored(anchorAcId, body) {
+  const prefix = AC_ANCHOR_PREFIX[anchorAcId];
+  return prefix ? `${prefix}. ${body}` : body;
+}