@juzser/blacksmith 0.1.0

package/factory/orchestrator/dist/dispatchAudit.js

@@ -0,0 +1,275 @@
+import { eventTaskId } from './events.js';
+import { taskIdsMatch } from './taskId.js';
+/**
+ * Critic work that reaches the event log without a `dispatch_decision`.
+ *
+ * `key` is the payload field naming the role that did the work, and `label`
+ * is how the operator hears it in a detail line. Adding an entry widens the
+ * audit's domain; leaving one off is how D-124 happened, so a new event type
+ * that records a critic's output belongs here at the moment it is written.
+ */
+const CRITIC_WORK_EVENTS = {
+    'spec-review-recorded': { key: 'reviewed_by', label: 'spec review' },
+    // `smith epic goal-check` reaches the log the same way `epic spec-review`
+    // does — a judge's verdict on the planner's output, written by a command
+    // rather than by a dispatch — so it is in the domain for the same reason,
+    // and listed here at the moment it was written rather than after a D-124.
+    'goal-check-recorded': { key: 'checked_by', label: 'spec-vs-goal check' },
+};
+function payloadString(payload, key) {
+    const value = payload[key];
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+/**
+ * Whether two task scopes can answer for each other.
+ *
+ * They disagree only when both are named and differ. A dispatch with no task
+ * id answers for anything: pre-task-id history is on disk and unrewritable,
+ * and refusing it would turn every one of those runs into a wall of false
+ * alarms rather than a finding anyone can act on.
+ *
+ * D-181: "differ" is taskIdsMatch's question, not `===`'s. The log writes one
+ * task both qualified and bare, so a raw comparison here un-pairs a critic
+ * from the very finder it ran against whenever the two dispatches were
+ * spelled differently -- and the report says `unverifiable` about a pair it
+ * holds both halves of. taskIdsMatch keeps this function's own guarantee: two
+ * DIFFERENT qualified ids stay different tasks even when their bare halves
+ * collide, which is the whole point of scoping the finder search.
+ */
+function scopesAgree(a, b) {
+    return a === null || b === null || taskIdsMatch(a, b);
+}
+/**
+ * Flatten a session's events down to its dispatch records, in log order.
+ *
+ * Pre-P9-23 events are kept with `model: null` rather than filtered out.
+ * They are on disk and are never rewritten (the log is append-only), and
+ * dropping them would turn "this dispatch cannot be checked" into "no such
+ * dispatch happened" — the report would look emptier and cleaner than the
+ * history it describes.
+ */
+export function readDispatchRecords(events) {
+    const records = [];
+    for (const stored of events) {
+        const record = stored.record;
+        if (record.event_type !== 'dispatch_decision')
+            continue;
+        const payload = (record.payload ?? {});
+        const role = payloadString(payload, 'agent_role');
+        if (!role)
+            continue;
+        records.push({
+            eventId: stored.event_id,
+            ts: record.ts ?? '',
+            taskId: eventTaskId(record),
+            role,
+            provider: payloadString(payload, 'provider') ?? '',
+            model: payloadString(payload, 'model'),
+            modelTier: payloadString(payload, 'model_tier'),
+            agentId: typeof record.agent_id === 'string' && record.agent_id ? record.agent_id : null,
+        });
+    }
+    return records;
+}
+/**
+ * Flatten a session's events down to its critic-work records, in log order.
+ *
+ * The mirror of readDispatchRecords for the other route into the log. A
+ * record here is a claim that a critic role produced something; it carries no
+ * model, because no dispatch chose one, which is exactly why an uncovered
+ * record can only ever be `unverifiable`.
+ */
+export function readCriticWorkRecords(events) {
+    const records = [];
+    for (const stored of events) {
+        const record = stored.record;
+        const spec = CRITIC_WORK_EVENTS[record.event_type];
+        if (!spec)
+            continue;
+        const payload = (record.payload ?? {});
+        const role = payloadString(payload, spec.key);
+        if (!role)
+            continue;
+        records.push({
+            eventId: stored.event_id,
+            ts: record.ts ?? '',
+            taskId: eventTaskId(record),
+            role,
+            label: spec.label,
+        });
+    }
+    return records;
+}
+/**
+ * The critic-work records no dispatch of that role can answer for.
+ *
+ * A record is covered when a dispatch of the same role falls in the window
+ * (previous record of that role, this record] — since the last time this
+ * critic recorded something, and no later than the record itself.
+ *
+ * The window is the whole check. Treating dispatches as fungible tokens —
+ * five spec-reviewer dispatches, so the next five recorded reviews are fine —
+ * is exactly the laundering `precedingFinder` refuses on the finder side, and
+ * it is not hypothetical: dogfood-mcp-1 dispatched five spec-reviewers across
+ * two days and then recorded two more reviews by hand three days later, which
+ * a fungible count would have passed. A dispatch that predates the previous
+ * record already answered for that one; it cannot answer twice.
+ */
+function uncoveredCriticWork(work, dispatches) {
+    const uncovered = [];
+    let since = '';
+    for (const record of [...work].sort((a, b) => a.ts.localeCompare(b.ts))) {
+        if (!dispatches.some((d) => d.ts > since && d.ts <= record.ts))
+            uncovered.push(record);
+        since = record.ts;
+    }
+    return uncovered;
+}
+/**
+ * The finder dispatch a given critic dispatch was reviewing: the latest one
+ * at or before the critic's timestamp, on the critic's own task.
+ *
+ * "At or before" is the whole point. A later re-plan on a different model
+ * cannot retroactively make an earlier review adversarial, and comparing a
+ * critic against the newest finder dispatch in the session would let exactly
+ * that launder a violation into a pass.
+ *
+ * The task axis is the same argument on the other coordinate, and it is not
+ * hypothetical: on dogfood-mcp-1 four `integration` verifiers were answered
+ * for by a task-4 reviewer dispatched three days earlier, on a task with no
+ * reviewer dispatch of its own anywhere in the log. Different code, different
+ * finding, reported ok. Evidence about one task vouches for nothing about
+ * another (D-172).
+ */
+function precedingFinder(finders, critic) {
+    let best = null;
+    for (const finder of finders) {
+        if (finder.ts > critic.ts)
+            continue;
+        if (!scopesAgree(finder.taskId, critic.taskId))
+            continue;
+        if (!best || finder.ts >= best.ts)
+            best = finder;
+    }
+    return best;
+}
+function checkOneCritic(pair, critic, finders) {
+    const finder = precedingFinder(finders, critic);
+    const base = {
+        finder: pair.finder,
+        critic: pair.critic,
+        criticEventId: critic.eventId,
+        criticModel: critic.model,
+        finderEventId: finder?.eventId ?? null,
+        finderModel: finder?.model ?? null,
+    };
+    if (!finder) {
+        return {
+            ...base,
+            status: 'unverifiable',
+            detail: `${pair.critic} ran at ${critic.ts}${critic.taskId ? ` on ${critic.taskId}` : ''} with no preceding ${pair.finder} dispatch to compare against.`,
+        };
+    }
+    if (!critic.model || !finder.model) {
+        const missing = !critic.model ? pair.critic : pair.finder;
+        return {
+            ...base,
+            status: 'unverifiable',
+            detail: `The ${missing} dispatch records no model, so finder_ne_critic cannot be evaluated.`,
+        };
+    }
+    if (critic.model === finder.model) {
+        return {
+            ...base,
+            status: 'violation',
+            detail: `${pair.critic} ran on ${critic.model}, the same model as the ${pair.finder} dispatch it followed.`,
+        };
+    }
+    return {
+        ...base,
+        status: 'ok',
+        detail: `${pair.critic} ran on ${critic.model}; ${pair.finder} ran on ${finder.model}.`,
+    };
+}
+/**
+ * Assert crosscheck.yml's finder_ne_critic against what the log actually
+ * records. Every critic dispatch is checked, not just the last one: a session
+ * that got it wrong once and right afterwards did get it wrong once.
+ */
+export function checkDispatchAsymmetry(events, pairs, options) {
+    const taskId = options.taskId ?? null;
+    const all = readDispatchRecords(events);
+    // D-181: `--task` is answered across both spellings of the id. The log
+    // writes one task both qualified and bare, so a raw `===` here answered the
+    // operator with the subset that happened to be spelled their way — and a
+    // dropped critic dispatch reads as a critic that never ran.
+    const inScope = (scope) => (r) => r.taskId !== null && taskIdsMatch(r.taskId, scope);
+    const records = taskId ? all.filter(inScope(taskId)) : all;
+    const allWork = readCriticWorkRecords(events);
+    const criticWork = taskId ? allWork.filter(inScope(taskId)) : allWork;
+    // A policy that declares no pairs cannot be satisfied OR violated, and
+    // reporting that as a pass would advertise an audit nobody configured.
+    if (pairs.length === 0) {
+        return {
+            sessionId: options.sessionId,
+            taskId,
+            dispatchesExamined: records.length,
+            criticWorkExamined: criticWork.length,
+            checks: [
+                {
+                    finder: '*',
+                    critic: '*',
+                    status: 'unverifiable',
+                    criticEventId: null,
+                    criticModel: null,
+                    finderEventId: null,
+                    finderModel: null,
+                    detail: 'crosscheck.yml declares no asymmetric_roles.pairs, so finder_ne_critic asserts nothing.',
+                },
+            ],
+            ok: false,
+        };
+    }
+    const checks = [];
+    for (const pair of pairs) {
+        const critics = records.filter((r) => r.role === pair.critic);
+        const work = criticWork.filter((r) => r.role === pair.critic);
+        if (critics.length === 0 && work.length === 0) {
+            checks.push({
+                finder: pair.finder,
+                critic: pair.critic,
+                status: 'not-applicable',
+                criticEventId: null,
+                criticModel: null,
+                finderEventId: null,
+                finderModel: null,
+                detail: `No ${pair.critic} dispatch in scope; the pair had nothing to check.`,
+            });
+            continue;
+        }
+        const finders = records.filter((r) => r.role === pair.finder);
+        for (const critic of critics) {
+            checks.push(checkOneCritic(pair, critic, finders));
+        }
+        for (const record of uncoveredCriticWork(work, critics)) {
+            checks.push({
+                finder: pair.finder,
+                critic: pair.critic,
+                status: 'unverifiable',
+                criticEventId: record.eventId,
+                criticModel: null,
+                finderEventId: null,
+                finderModel: null,
+                detail: `${pair.critic} recorded a ${record.label} at ${record.ts} with no ${pair.critic} dispatch behind it, so no model is on record and finder_ne_critic cannot be evaluated.`,
+            });
+        }
+    }
+    return {
+        sessionId: options.sessionId,
+        taskId,
+        dispatchesExamined: records.length,
+        criticWorkExamined: criticWork.length,
+        checks,
+        ok: checks.every((c) => c.status === 'ok' || c.status === 'not-applicable'),
+    };
+}

package/factory/orchestrator/dist/dotenv.js

@@ -0,0 +1,72 @@
+// The join between where the runbook tells an operator to put a key and where
+// the code looks for one.
+//
+// `docs/runbooks/providers.md` says: set `DEEPSEEK_API_KEY` in `.env`
+// (gitignored, per `docs/standards/guardrails.md`). `preconditions.ts` reads
+// `process.env` and nothing else. Both were true for months and nothing joined
+// them, so a key placed exactly where the repo asked for it resolved
+// `enabled: auto` to off and `smith judge preflight` reported it unset. This
+// module is that join and nothing more.
+//
+// Two decisions worth stating, because both are the kind that get "fixed"
+// later by someone who did not know they were chosen:
+//
+// **A file never beats the runner.** CI and the daemon export secrets into the
+// environment; `.env` is a convenience for a developer's box. A convenience
+// that silently replaces the real thing is how a run spends a stale key and
+// nobody can see why. So an already-set name is left exactly as it is, and is
+// not reported as loaded.
+//
+// **Not `node --env-file`.** Node can do this at the flag, but the binary is
+// reached by more than one road -- `smith`, `node dist/cli.js`, a daemon
+// spawn, the UI server importing a module -- and a flag on one road covers one
+// road. Doing it in-process at the entry covers all of them.
+//
+// Nothing here ever returns, throws, or logs a value: the return is the list
+// of names, which is the same discipline `smith judge preflight` already
+// keeps.
+import { readFileSync } from 'node:fs';
+/** `KEY=value`, with an optional `export` and space either side of the `=`. */
+const ASSIGNMENT = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/;
+/** Strip one layer of matching quotes, and only a matching pair. */
+function unquote(raw) {
+    const value = raw.trim();
+    const first = value.slice(0, 1);
+    const quoted = value.length >= 2 && (first === '"' || first === "'") && value.endsWith(first);
+    // Inside quotes every character is the operator's: a `#` is part of the key,
+    // not the start of a comment, and trailing space was typed on purpose.
+    return quoted ? value.slice(1, -1) : value;
+}
+/**
+ * Read `file` into `env`, setting only names it does not already hold.
+ *
+ * Returns the names it set -- never the values, and never anything about the
+ * names it skipped. A missing or unreadable file is nothing to do, not an
+ * error: most boxes have no `.env` and the factory runs fine on them.
+ */
+export function loadDotEnv(file, env = process.env) {
+    let contents;
+    try {
+        contents = readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const named = [];
+    for (const line of contents.split('\n')) {
+        if (/^\s*(?:#|$)/.test(line))
+            continue;
+        const match = ASSIGNMENT.exec(line);
+        if (match === null)
+            continue;
+        const name = match[1];
+        const raw = match[2];
+        if (name === undefined || raw === undefined)
+            continue;
+        if (env[name] !== undefined)
+            continue;
+        env[name] = unquote(raw);
+        named.push(name);
+    }
+    return named;
+}

package/factory/orchestrator/dist/effort.js

@@ -0,0 +1,202 @@
+import { readFileSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+import { SmithError } from './errors.js';
+import { EFFORT_POLICY_PATH } from './paths.js';
+import { EFFORT_TIERS, isEffortTier } from './plan.js';
+import { evaluatePlanSecurityTriggers } from './planQuorum.js';
+/**
+ * How much judgment an epic buys — factory/policies/effort.yml's host.
+ *
+ * An internal tool and a payments rewrite were running the same sixteen-step
+ * loop, because the loop was the only one there was. Making a small epic cheap
+ * meant skipping steps by hand and remembering which ones, which is the
+ * "recall, do not ask" failure sensitive-paths.yml and crosscheck.yml were
+ * each written to end. This module ends it for step count: the tiers are
+ * declared in the policy file, the plan file names one, and
+ * `smith effort show` answers so the `/bs` playbooks never have to
+ * decide twice.
+ *
+ * Two invariants make the feature safe to ship:
+ *
+ * 1. **`huge` is today's flow, unchanged.** Nothing about black-smith's own
+ *    behaviour moves until an epic is assigned a lower tier — effort.test.ts
+ *    pins every `huge` knob to what the `/bs` playbooks already write, so a
+ *    future tune of `huge` has to be a deliberate edit to a red test rather
+ *    than a quiet regression for every epic that never asked for a tier.
+ * 2. **A tier scales judgment steps only.** Never a mechanical oracle, never a
+ *    guardrail: gates, coverage, claim disjointness, worktree isolation, the
+ *    security-reviewer's own dispatch triggers, operator sign-off, and the
+ *    event log run identically at every tier. The policy file's `invariants:`
+ *    list says so in prose and `resolveEffort` returns it verbatim beside
+ *    every profile, so a caller reading the cheap answer reads the limit of it
+ *    in the same breath. A `small` tier that skipped tests would not be cheap,
+ *    it would be unverified.
+ *
+ * The tier is per EPIC, not per project (the operator's call): it is chosen at
+ * `/bs plan` time and stored on the plan file, so one project runs a `small`
+ * epic and a `huge` one without re-configuring anything.
+ */
+export class EffortError extends SmithError {
+}
+/**
+ * The tier names, ordered cheapest-first — the index is the rank the security
+ * floor compares on. Declared in plan.ts (beside the `PlanFile.effort` field
+ * that carries them, so `validatePlan` can check one without importing this
+ * module) and re-exported here, which is where callers should read it from:
+ * this file is what gives the names meaning.
+ */
+export { EFFORT_TIERS, isEffortTier } from './plan.js';
+/** Cheapest = 0. Only ever compared, never persisted — the names are the contract. */
+function tierRank(tier) {
+    return EFFORT_TIERS.indexOf(tier);
+}
+const PRE_CODE_RESEARCH = ['when-needed', 'never'];
+const PRE_CODE_UIUX = ['always', 'when-ui-criterion', 'never'];
+const SPEC_REVIEW_ROUNDS = ['until-clean', 'single-pass'];
+const PLAN_QUORUM = ['always', 'when-triggered'];
+const CLOSING_SPEC_REVIEW = ['always', 'when-plan-amended'];
+// --- parsing ---------------------------------------------------------------
+// Every reader below rejects rather than defaults. A policy file that half
+// parses is worse than one that fails: the missing half becomes an unstated
+// tier assignment, which is exactly the thing this module exists to end.
+function requireNode(node, what) {
+    if (typeof node !== 'object' || node === null || Array.isArray(node)) {
+        throw new EffortError('effort.policy-invalid', `effort.yml: ${what} must be a mapping.`);
+    }
+    return node;
+}
+function requireEnum(value, allowed, where) {
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        throw new EffortError('effort.policy-invalid', `effort.yml: ${where} is ${JSON.stringify(value)}; allowed: ${allowed.join(', ')}.`, { where, value, allowed: [...allowed] });
+    }
+    return value;
+}
+function requireNumber(value, where, min, max) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
+        throw new EffortError('effort.policy-invalid', `effort.yml: ${where} is ${JSON.stringify(value)}; expected a number in [${min}, ${max}].`, { where, value });
+    }
+    return value;
+}
+function requireStringList(value, where, minLength) {
+    if (!Array.isArray(value) || value.some((v) => typeof v !== 'string' || v.trim() === '')) {
+        throw new EffortError('effort.policy-invalid', `effort.yml: ${where} must be a list of non-empty strings.`, { where });
+    }
+    if (value.length < minLength) {
+        throw new EffortError('effort.policy-invalid', `effort.yml: ${where} needs at least ${minLength} entr${minLength === 1 ? 'y' : 'ies'}.`, { where });
+    }
+    return value.map(String);
+}
+function parseProfile(node, tier) {
+    const t = requireNode(node, `tiers.${tier}`);
+    const summary = typeof t.summary === 'string' ? t.summary.trim() : '';
+    const graderRounds = requireNumber(t.grader_rounds, `tiers.${tier}.grader_rounds`, 1, 2);
+    if (!Number.isInteger(graderRounds)) {
+        throw new EffortError('effort.policy-invalid', `effort.yml: tiers.${tier}.grader_rounds must be a whole number of rounds.`);
+    }
+    const verifierSeverities = requireStringList(t.verifier_severities, `tiers.${tier}.verifier_severities`, 1);
+    // S1 is not a tier's to drop: a stop-the-line finding reaching the coder
+    // unrefuted is the round trip the adversarial pass exists to prevent, and it
+    // costs the same at every scale.
+    if (!verifierSeverities.includes('S1-stop-the-line')) {
+        throw new EffortError('effort.policy-invalid', `effort.yml: tiers.${tier}.verifier_severities must keep "S1-stop-the-line" — no tier may leave a stop-the-line finding unverified.`, { tier });
+    }
+    return {
+        summary,
+        preCodeResearch: requireEnum(t.pre_code_research, PRE_CODE_RESEARCH, `tiers.${tier}.pre_code_research`),
+        preCodeUiux: requireEnum(t.pre_code_uiux, PRE_CODE_UIUX, `tiers.${tier}.pre_code_uiux`),
+        specReviewRounds: requireEnum(t.spec_review_rounds, SPEC_REVIEW_ROUNDS, `tiers.${tier}.spec_review_rounds`),
+        planQuorum: requireEnum(t.plan_quorum, PLAN_QUORUM, `tiers.${tier}.plan_quorum`),
+        graderRounds,
+        verifierSeverities,
+        verifierS3SpotCheckRatio: requireNumber(t.verifier_s3_spot_check_ratio, `tiers.${tier}.verifier_s3_spot_check_ratio`, 0, 1),
+        closingSpecReview: requireEnum(t.closing_spec_review, CLOSING_SPEC_REVIEW, `tiers.${tier}.closing_spec_review`),
+    };
+}
+export function parseEffortPolicy(yamlText) {
+    const doc = requireNode(parseYaml(yamlText), 'the document');
+    const tiersNode = requireNode(doc.tiers, 'tiers');
+    // Presence of the whole table first, then each profile: an operator who
+    // deleted two tiers should be told that, not handed the first missing knob
+    // of the one tier they kept.
+    const missing = EFFORT_TIERS.filter((tier) => !(tier in tiersNode));
+    if (missing.length > 0) {
+        throw new EffortError('effort.policy-invalid', `effort.yml: tiers is missing ${missing.map((t) => `"${t}"`).join(', ')}. All of ${EFFORT_TIERS.join(', ')} must be declared — a missing tier is a silent default.`, { missing });
+    }
+    const tiers = {};
+    for (const tier of EFFORT_TIERS) {
+        tiers[tier] = parseProfile(tiersNode[tier], tier);
+    }
+    return {
+        version: typeof doc.version === 'number' ? doc.version : 1,
+        defaultTier: requireEnum(doc.default_tier, EFFORT_TIERS, 'default_tier'),
+        securityFloor: requireEnum(doc.security_floor, EFFORT_TIERS, 'security_floor'),
+        tiers,
+        invariants: requireStringList(doc.invariants, 'invariants', 1),
+    };
+}
+export function loadEffortPolicy(filePath = EFFORT_POLICY_PATH) {
+    return parseEffortPolicy(readFileSync(filePath, 'utf8'));
+}
+/**
+ * Pure, no I/O: decide which tier an epic runs at and hand back the profile
+ * plus the evidence for the decision.
+ *
+ * The floor only ever raises. An operator who asks for `huge` on a
+ * security-sensitive epic gets `huge`; one who asks for `small` gets the
+ * floor, and `floorApplied` says so rather than leaving them to notice their
+ * request was overridden by comparing two tables. Security sensitivity is read
+ * from the plan's LIVE tasks (D-113/D-185), never `plan.tasks`: a superseded
+ * task is history, and an epic must not be held at a higher tier by an ask it
+ * has already withdrawn.
+ */
+export function resolveEffort(policy, securityPolicy, opts = {}) {
+    // A typo'd --effort must not degrade into the default: that is the same
+    // silence validatePlan rejects a typo'd plan field for.
+    if (opts.override !== undefined && !isEffortTier(opts.override)) {
+        throw new EffortError('effort.unknown-tier', `Effort tier "${opts.override}" is not one of ${EFFORT_TIERS.join(', ')} (factory/policies/effort.yml).`, { tier: opts.override, allowed: [...EFFORT_TIERS] });
+    }
+    const fromPlan = isEffortTier(opts.plan?.effort) ? opts.plan.effort : null;
+    const requested = opts.override ?? fromPlan;
+    const requestedFrom = opts.override !== undefined ? 'flag' : fromPlan !== null ? 'plan' : 'default';
+    const base = requested ?? policy.defaultTier;
+    const securityFloorEvaluated = opts.plan !== undefined;
+    const securityTriggers = opts.plan ? evaluatePlanSecurityTriggers(opts.plan, securityPolicy) : [];
+    const floorApplied = securityTriggers.length > 0 && tierRank(base) < tierRank(policy.securityFloor);
+    const effective = floorApplied ? policy.securityFloor : base;
+    return {
+        requested,
+        requestedFrom,
+        defaultTier: policy.defaultTier,
+        effective,
+        floorApplied,
+        securityFloor: policy.securityFloor,
+        securityFloorEvaluated,
+        securityTriggers,
+        reason: explain({
+            base,
+            effective,
+            floorApplied,
+            requestedFrom,
+            securityFloor: policy.securityFloor,
+            securityFloorEvaluated,
+            triggerCount: securityTriggers.length,
+        }),
+        profile: policy.tiers[effective],
+        invariants: policy.invariants,
+    };
+}
+function explain(facts) {
+    const source = facts.requestedFrom === 'default'
+        ? `nobody named a tier, so the policy default "${facts.base}" applies`
+        : `the ${facts.requestedFrom} asked for "${facts.base}"`;
+    if (!facts.securityFloorEvaluated) {
+        return `${source}; the security floor was not evaluated — no plan was supplied, so this is the tier's profile and not a decision about a specific epic.`;
+    }
+    if (facts.floorApplied) {
+        return `${source}; raised to "${facts.effective}" by the security floor — ${facts.triggerCount} security trigger(s) fired on this plan's live tasks (crosscheck.yml plan_quorum).`;
+    }
+    if (facts.triggerCount === 0) {
+        return `${source}; no security trigger fired on this plan's live tasks, so the floor changed nothing.`;
+    }
+    return `${source}; ${facts.triggerCount} security trigger(s) fired, but "${facts.base}" is already at or above the "${facts.securityFloor}" floor.`;
+}