@sensigo/realm 0.41.0 → 0.42.0

package/dist/workflow/yaml-loader.js

@@ -4,7 +4,7 @@ import { dirname, resolve, join, isAbsolute } from 'node:path';
 import { createHash } from 'node:crypto';
 import { load } from 'js-yaml';
 import { Ajv } from 'ajv';
-import { KNOWN_STEP_KEYS, KNOWN_WORKFLOW_KEYS, KNOWN_RETRY_KEYS, KNOWN_GATE_KEYS, } from '../types/workflow-definition.js';
+import { KNOWN_STEP_KEYS, KNOWN_WORKFLOW_KEYS, KNOWN_RETRY_KEYS, KNOWN_GATE_KEYS, SERVICE_TRUST_LEVELS, isGateTrust, classifyStepTrust, buildTrustRefusal, renderTrustValue, } from '../types/workflow-definition.js';
 import { WorkflowError } from '../types/workflow-error.js';
 import { findUnknownKeys, renderLoaderWarning, resolveSeverity, closestKey, } from './diagnostics.js';
 import { createSourcePositionCollector } from './source-positions.js';
@@ -14,12 +14,39 @@ import { splitComparison, isPathShaped } from '../engine/comparison-expr.js';
 import { DEFAULT_EXECUTION_TIMEOUT_SECONDS } from '../engine/claim-liveness.js';
 import { validateOutputSchema } from '../validation/input-schema.js';
 import { assessStructuredOutputEligibility, renderIneligibleMessage, } from './structured-output-eligibility.js';
+import { STEP_KEY_REGISTRY, CONSUMED_HOME, prohibitedKeysFor, consumedKindsFor, homeText, } from './step-key-registry.js';
+/** #517 (the drive-flip): render ONE minted kind-prohibition from registry data. message_data
+ *  cells render their recorded bespoke text verbatim (byte-identical to the pre-flip checks —
+ *  golden-proven at the flip). Generic cells render the per-cell FRONT clause (the two-shape
+ *  truth: 'not_valid' keeps the old loop grammar against THIS kind; 'only_valid' keeps the old
+ *  twin grammar against the DERIVED consumed-kind set) and append the rung-2 consequence clause
+ *  from CONSUMED_HOME — witness-backed message truth (its claims are conformance-tested data). */
+function renderRegistryProhibition(key, kind, cell) {
+    if (cell.message_data !== undefined)
+        return cell.message_data;
+    const home = CONSUMED_HOME[key];
+    /* istanbul ignore next -- conformance guarantees totality over generic minted keys */
+    if (home === undefined)
+        return `'${key}' is not valid on execution: ${kind} steps`;
+    const front = cell.front === 'only_valid'
+        ? `'${key}' is only valid on execution: ${consumedKindsFor(key).join('/')} steps`
+        : `'${key}' is not valid on execution: ${kind} steps`;
+    return `${front} — ${homeText(home.mechanism, kind)} ${homeText(home.remedy, kind)}`;
+}
 /**
  * Validate one condition leaf at load time using the shared quote-aware splitter (the SAME split
  * used at runtime). Rejects compound `and`/`or`, multiple operators, and non-path LHS. For `when`,
  * also enforces the direct-`depends_on` reference check (Change 2). Pushes actionable errors.
  */
-function validateConditionLeaf(surface, leaf, stepName, dependsOn, errors, 
+function validateConditionLeaf(surface, leaf, stepName, dependsOn, 
+/**
+ * The step's declared `execution` kind (undefined when missing/malformed — those steps are
+ * already refused by the invalid-execution error, and the remedy below keeps its generic
+ * form). Threaded through so `validateWhenReference` can fork its remedy tail on the
+ * registry's own `depends_on` cell — a kind where `depends_on` is prohibited must never be
+ * told to add one (the wrong-remedy composition class this correction fixes).
+ */
+kind, errors, 
 /**
  * Appends the step's source line to a message (issue #392). REQUIRED rather than optional so
  * the compiler names every call site if this ever gains another one — an omitted resolver
@@ -68,7 +95,7 @@ withLine) {
             return;
         }
         if (surface === 'when')
-            validateWhenReference(split.path, stepName, dependsOn, errors, withLine);
+            validateWhenReference(split.path, stepName, dependsOn, kind, errors, withLine);
         return;
     }
     // comparison
@@ -81,7 +108,7 @@ withLine) {
         return;
     }
     if (surface === 'when')
-        validateWhenReference(split.lhsPath, stepName, dependsOn, errors, withLine);
+        validateWhenReference(split.lhsPath, stepName, dependsOn, kind, errors, withLine);
 }
 /**
  * issue #220 §4c (PR-3): validates a `$settlement.<dep>.<field>` reference reached from ANY of
@@ -133,7 +160,9 @@ withLine) {
  * step in this step's DIRECT `depends_on` (one-hop membership — no graph traversal). Field names are
  * not checked (agent-step outputs aren't statically declared).
  */
-function validateWhenReference(path, stepName, dependsOn, errors, 
+function validateWhenReference(path, stepName, dependsOn, 
+/** @see validateConditionLeaf — forks the remedy tail on the registry's `depends_on` cell. */
+kind, errors, 
 /**
  * Appends the step's source line to a message (issue #392). REQUIRED rather than optional so
  * the compiler names every call site if this ever gains another one — an omitted resolver
@@ -149,7 +178,16 @@ withLine) {
         return;
     }
     if (!dependsOn.includes(first)) {
-        errors.push(withLine(stepName, `Step '${stepName}': 'when' references step '${first}' which is not in its depends_on [${dependsOn.join(', ')}]. Add it to depends_on or use 'run.params.*'.`));
+        // The remedy's first arm is forked on the registry's own depends_on cell: on a kind where
+        // depends_on is prohibited (today exactly finalizer), 'Add it to depends_on' is a dead
+        // pointer — following it mints a second refusal (probe-executed; the wrong-remedy
+        // composition class this correction fixes). Derived from the cell so the fork can never
+        // drift from the mint.
+        const dependsOnLegal = kind === undefined || STEP_KEY_REGISTRY.depends_on[kind].c === 'consumed';
+        const remedyTail = dependsOnLegal
+            ? `Add it to depends_on or use 'run.params.*'.`
+            : `Use 'run.params.*' — 'depends_on' is not valid on this step's kind.`;
+        errors.push(withLine(stepName, `Step '${stepName}': 'when' references step '${first}' which is not in its depends_on [${dependsOn.join(', ')}]. ${remedyTail}`));
     }
 }
 /** Bumped on every breaking change to WorkflowDefinition's serialized format. */
@@ -166,11 +204,20 @@ const SERVICE_ENTRY_JSON_SCHEMA = {
     required: ['adapter'],
     properties: {
         adapter: { type: 'string', minLength: 1 },
-        trust: { enum: ['engine_delivered', 'engine_managed', 'agent_provided'] },
+        trust: { enum: [...SERVICE_TRUST_LEVELS] },
         rate_limit: { type: 'object' },
     },
 };
 const VALID_EXECUTIONS = new Set(['auto', 'agent', 'guard', 'finalizer']);
+// issue #517 (the drive-flip): the two kind-prohibition sets are DERIVED from the consumption
+// registry — every key whose cell on the kind is prohibited WITHOUT an except arm. Their meaning
+// upgraded with #517 from "the loop's array" to "the prohibited set": they now also carry the
+// keys whose refusals used to live in per-key only-valid-on checks (guard 12→20 members,
+// finalizer 13→19), and their declared type widened from a literal tuple to a computed readonly
+// array — both disclosed in the changelog. The prohibition loops that consumed the old literal
+// arrays are deleted; the registry-driven mint below is the single enforcement mechanism.
+export const FINALIZER_PROHIBITED_STEP_KEYS = prohibitedKeysFor('finalizer');
+export const GUARD_PROHIBITED_STEP_KEYS = prohibitedKeysFor('guard');
 const VALID_FINALIZER_TRIGGERS = new Set([
     'complete',
     'fail',
@@ -269,6 +316,58 @@ export function attachLoaderWarnings(err, warnings) {
         return;
     err.warnings = warnings;
 }
+/**
+ * Resolves every `agent_profile` a definition declares against `<workflowDir>/<profiles_dir>`
+ * (default `profiles/`), stamping `resolved_profiles` on the definition and refusing — one
+ * `Invalid workflow:` error, one entry per missing profile (issue #425) — when any is absent.
+ *
+ * Exported (issue #553) because this is the ONE check a workflow's text cannot answer: it needs
+ * the source tree. `loadWorkflowFromFileCore` calls it with the file's directory; `validate
+ * --registered` calls it with the `source_dir` the registrar recorded, so the stored copy is
+ * audited by the same rule instead of by a synthesized file path (#493's snapshot doctrine: a
+ * synthesized path would audit the FILE, not the stored copy). Semantics are those of the
+ * former inline loop, byte for byte — the `Searched: <path>` sentence included.
+ * @throws WorkflowError (`VALIDATION_WORKFLOW_SCHEMA`) naming every missing profile.
+ */
+export function resolveAgentProfiles(definition, workflowDir) {
+    const profilesDir = definition.profiles_dir !== undefined
+        ? resolve(workflowDir, definition.profiles_dir)
+        : join(workflowDir, 'profiles');
+    const resolvedProfiles = {};
+    const profileErrors = [];
+    for (const [stepName, step] of Object.entries(definition.steps)) {
+        if (step.agent_profile === undefined)
+            continue;
+        const profileName = step.agent_profile;
+        if (profileName in resolvedProfiles)
+            continue;
+        const profilePath = join(profilesDir, `${profileName}.md`);
+        let profileContent;
+        try {
+            profileContent = readFileSync(profilePath, 'utf8');
+        }
+        catch {
+            profileErrors.push(`Step '${stepName}': agent_profile '${profileName}' not found. Searched: ${profilePath}`);
+            continue;
+        }
+        const contentHash = createHash('sha256').update(profileContent).digest('hex');
+        resolvedProfiles[profileName] = { content: profileContent, content_hash: contentHash };
+    }
+    if (profileErrors.length > 0) {
+        throw new WorkflowError(`Invalid workflow: ${profileErrors.join('; ')}`, {
+            // issue #425: the pre-join strings, so a render can list them one per line. Two missing
+            // profiles are two problems, not one long sentence.
+            errors: [...profileErrors],
+            code: 'VALIDATION_WORKFLOW_SCHEMA',
+            category: 'VALIDATION',
+            agentAction: 'report_to_user',
+            retryable: false,
+        });
+    }
+    if (Object.keys(resolvedProfiles).length > 0) {
+        definition.resolved_profiles = resolvedProfiles;
+    }
+}
 /**
  * Pure core of loadWorkflowFromFile (issue #169): parses + resolves everything a file-based load
  * needs, but never prints and never chooses between the two public presentations — it always
@@ -307,88 +406,20 @@ function loadWorkflowFromFileCore(filePath, registry) {
     // `parseWorkflowString` owns those throws and has already attached, and attach-once means its
     // richer set survives.
     try {
-        // Resolve agent profiles — only possible when we have a file path.
+        // Resolve agent profiles — only possible when we have a source tree. Every check in this
+        // file-only block is DELEGATED to a named exported resolver (issue #553): `validate
+        // --registered` supplies the recorded source tree to the same function, so the stored copy
+        // is audited by the rule register applied, not by a paraphrase. An inline `throw` here is
+        // exactly what admission-context.test.ts (cli) refuses.
         const workflowDir = dirname(resolve(filePath));
-        const profilesDir = definition.profiles_dir !== undefined
-            ? resolve(workflowDir, definition.profiles_dir)
-            : join(workflowDir, 'profiles');
-        const resolvedProfiles = {};
-        const profileErrors = [];
-        for (const [stepName, step] of Object.entries(definition.steps)) {
-            if (step.agent_profile === undefined)
-                continue;
-            const profileName = step.agent_profile;
-            if (profileName in resolvedProfiles)
-                continue;
-            const profilePath = join(profilesDir, `${profileName}.md`);
-            let profileContent;
-            try {
-                profileContent = readFileSync(profilePath, 'utf8');
-            }
-            catch {
-                profileErrors.push(`Step '${stepName}': agent_profile '${profileName}' not found. Searched: ${profilePath}`);
-                continue;
-            }
-            const contentHash = createHash('sha256').update(profileContent).digest('hex');
-            resolvedProfiles[profileName] = { content: profileContent, content_hash: contentHash };
-        }
-        if (profileErrors.length > 0) {
-            throw new WorkflowError(`Invalid workflow: ${profileErrors.join('; ')}`, {
-                // issue #425: the pre-join strings, so a render can list them one per line. Two missing
-                // profiles are two problems, not one long sentence.
-                errors: [...profileErrors],
-                code: 'VALIDATION_WORKFLOW_SCHEMA',
-                category: 'VALIDATION',
-                agentAction: 'report_to_user',
-                retryable: false,
-            });
-        }
-        if (Object.keys(resolvedProfiles).length > 0) {
-            definition.resolved_profiles = resolvedProfiles;
-        }
-        // Validate context_wrapper if present.
-        if (definition.context_wrapper !== undefined) {
-            const VALID_WRAPPER_FORMATS = new Set(['xml', 'brackets', 'none']);
-            if (!VALID_WRAPPER_FORMATS.has(definition.context_wrapper)) {
-                throw new WorkflowError(`Invalid context_wrapper '${String(definition.context_wrapper)}'; must be 'xml', 'brackets', or 'none'`, {
-                    code: 'VALIDATION_WORKFLOW_SCHEMA',
-                    category: 'VALIDATION',
-                    agentAction: 'report_to_user',
-                    retryable: false,
-                });
-            }
-        }
-        // Validate and resolve workflow_context entry paths.
+        resolveAgentProfiles(definition, workflowDir);
+        // Resolve workflow_context entry paths. The four context-free rules (context_wrapper enum,
+        // `.raw` names, the name charset, `source.path` required) live in `parseWorkflowString`
+        // Step 3c since issue #553 — every surface, file or string, refuses them identically. Only
+        // the TRANSFORM needs `workflowDir`, so only the transform is here.
         if (definition.workflow_context !== undefined) {
-            for (const [name, entry] of Object.entries(definition.workflow_context)) {
-                if (name.endsWith('.raw')) {
-                    throw new WorkflowError(`workflow_context entry names must not end with '.raw' (found: '${name}')`, {
-                        code: 'VALIDATION_WORKFLOW_SCHEMA',
-                        category: 'VALIDATION',
-                        agentAction: 'report_to_user',
-                        retryable: false,
-                    });
-                }
-                if (!/^[\w.]+$/.test(name)) {
-                    throw new WorkflowError(`workflow_context entry name '${name}' is invalid; names must match [\\w.]+ (underscores and dots only — no hyphens)`, {
-                        code: 'VALIDATION_WORKFLOW_SCHEMA',
-                        category: 'VALIDATION',
-                        agentAction: 'report_to_user',
-                        retryable: false,
-                    });
-                }
-                const rawEntry = entry;
-                const rawSource = rawEntry['source'];
-                if (rawSource === undefined || typeof rawSource['path'] !== 'string') {
-                    throw new WorkflowError(`workflow_context.${name}.source.path is required`, {
-                        code: 'VALIDATION_WORKFLOW_SCHEMA',
-                        category: 'VALIDATION',
-                        agentAction: 'report_to_user',
-                        retryable: false,
-                    });
-                }
-                // Resolve relative path to absolute.
-                entry.source.path = resolve(workflowDir, rawSource['path']);
+            for (const entry of Object.values(definition.workflow_context)) {
+                entry.source.path = resolve(workflowDir, entry.source.path);
             }
         }
         // Auto-register schema.json if present and not explicitly declared.
@@ -404,6 +435,8 @@ function loadWorkflowFromFileCore(filePath, registry) {
         // the deployment-manifest anchor (`<trust_root>/realm.yaml`), needed by extension-free
         // workflows that consume manifest-constructed adapters by name. Core resolves/stores
         // PATHS only — it never imports modules or reads the manifest; that is the CLI's job.
+        // `validate --registered` reads these two back to supply the source tree the stored copy's
+        // context-dependent checks need (issue #553).
         definition.source_dir = workflowDir;
         definition.trust_root = findTrustRoot(workflowDir);
         if (definition.extensions !== undefined) {
@@ -623,6 +656,16 @@ function parseWorkflowString(content, registry, opts) {
                 return `${message} (step at line ${stepLine})`;
             return message;
         };
+        /**
+         * The TOP-LEVEL sibling of `withStepLine`/`withKeyLine` (issue #553): names the line of a
+         * workflow-level key such as `context_wrapper` or `workflow_context.<name>`. No step
+         * fallback — there is no step — and no position at all when the key cannot be placed:
+         * absent-never-wrong, the loader's standing cite doctrine.
+         */
+        const withTopLevelLine = (path, message) => {
+            const line = sourceMap.posOf(path)?.line;
+            return line !== undefined ? `${message} (line ${line})` : message;
+        };
         // Step 2: Top-level validation
         if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
             throw new WorkflowError('Invalid workflow: Workflow must be a non-null object', {
@@ -712,6 +755,11 @@ function parseWorkflowString(content, registry, opts) {
             // at all); the legacy when-only depends_on/run.params check (validateWhenReference) is
             // UNCHANGED — it still fires ONLY for `surface === 'when'`. This is a LIFT, not a new
             // computation — byte-identical to the previous block-local `dependsOn` for `when`'s own use.
+            // The step's kind, once, for every kind-forked check below (undefined = malformed or
+            // missing execution — already refused by the invalid-execution/required error).
+            const stepKind = VALID_EXECUTIONS.has(step['execution'])
+                ? step['execution']
+                : undefined;
             const dependsOn = Array.isArray(step['depends_on'])
                 ? step['depends_on'].filter((d) => typeof d === 'string')
                 : [];
@@ -746,31 +794,77 @@ function parseWorkflowString(content, registry, opts) {
             if ('execution' in step && !VALID_EXECUTIONS.has(step['execution'])) {
                 errors.push(withStepLine(stepName, `Step '${stepName}': invalid execution value '${String(step['execution'])}'; must be 'auto', 'agent', 'guard', or 'finalizer'`));
             }
+            // issue #517 (the drive-flip): ONE registry-driven walk mints every kind-prohibition —
+            // for each declared key × the step's kind, a `prohibited` cell WITHOUT an except arm
+            // mints exactly one refusal, message text per-cell data (renderRegistryProhibition).
+            // Sits at the sequence position of the EARLIEST check it replaced (the old finalizer
+            // prohibited-field loop), so minted refusals still precede the structural finalizer/guard
+            // requirements below. Multi-fire is dead by construction (one lookup, one refusal per
+            // key×kind), and a multi-bad-key step now errors in YAML declaration order.
+            //
+            // Except-bearing cells are SKIPPED — their value-conditional checks stay hand-written
+            // (today exactly trust×finalizer, below). Companion/value/sub-key rules are not minted at
+            // all (the clang line): toolsMissing, the tools agent+handler clause, the gate block,
+            // retry E1-E3, structured_output literal+eligibility, trace_schema compile, pos-int
+            // checks all stay hand-written further down.
+            //
+            // The kind gate is deliberate: on a step whose `execution` is missing or not one of the
+            // four kinds, the registry has no row to consult, so NO per-key kind refusal is minted —
+            // the invalid-execution/missing-required error above is the whole verdict. (Pre-#517 the
+            // per-key `!== '<kind>'` twins ALSO fired on malformed kinds; that was per-key advice
+            // keyed to a kind nobody declared. The workflow is refused either way — the refusal
+            // POPULATION is unchanged; disclosed in the changelog.)
+            if (VALID_EXECUTIONS.has(step['execution'])) {
+                const kind = step['execution'];
+                for (const key of Object.keys(step)) {
+                    // Unknown keys are UNKNOWN_STEP_KEY's business (warned above), never a registry row.
+                    const row = STEP_KEY_REGISTRY[key];
+                    if (row === undefined || step[key] === undefined)
+                        continue;
+                    const cell = row[kind];
+                    if (cell.c !== 'prohibited' || cell.except !== undefined)
+                        continue;
+                    errors.push(withKeyLine(stepName, key, `Step '${stepName}': ${renderRegistryProhibition(key, kind, cell)}`));
+                }
+            }
             // Finalizer step constraints (a workflow-level try/catch/finally). handler-only in v1.
             if (step['execution'] === 'finalizer') {
-                const prohibited = [
-                    'depends_on',
-                    'trigger_rule',
-                    'abort_unless',
-                    'abort_message',
-                    'output_schema',
-                    'agent_profile',
-                    'tools',
-                    'uses_service',
-                    'service_method',
-                    'operation',
-                    'input_map',
-                    'when',
-                    'retry',
-                ];
-                for (const field of prohibited) {
-                    if (step[field] !== undefined) {
-                        errors.push(withStepLine(stepName, `Step '${stepName}': '${field}' is not valid on execution: finalizer steps`));
-                    }
-                }
-                // A finalizer must not gate — reject any human-gate trust level.
+                // A finalizer must not gate — reject any human-gate trust level. Value-conditional
+                // (`trust: 'auto'` is lawful), which is why this is the registry's except-bearing cell
+                // and stays hand-written rather than minted (#517).
                 if (step['trust'] !== undefined && step['trust'] !== 'auto') {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'trust: ${String(step['trust'])}' is not valid on execution: finalizer steps (a finalizer must not gate)`));
+                    // issue #508: the reason forks on whether the declared value is actually a GATE
+                    // literal — "a finalizer must not gate" is only true THEN. Any other value (an
+                    // unrecognized trust, a service-trust literal, the retired human_notified) was never
+                    // an attempt to gate at all, so that reason would be false for it — the #523 class,
+                    // caught before shipping rather than after. `isGateTrust` is the pure-value question
+                    // (no kind involved, since this branch already knows the kind and has already
+                    // excluded 'auto'); the leading `'trust:` is kept exactly as before so the registry
+                    // conformance runner's `namesKey` (`error.includes("'trust")`) still matches this arm
+                    // — `namesKey` needs the quote BEFORE `trust`, not around the value, so switching the
+                    // value's own rendering below does not touch it.
+                    //
+                    // issue #508 (final correction): the gate-literal arm stays a hand-written KIND
+                    // prohibition (the key is the offense, not the value — #517's own boundary), but now
+                    // shares `renderTrustValue` with every other arm — a previous ruling to "keep
+                    // `String()` here to satisfy `namesKey`" was wrong (verified above) and there was
+                    // never a real reason for two renderers, even though `isGateTrust` only ever admits
+                    // the two known-string gate literals here in practice. The non-gate branch (an
+                    // unrecognized trust, a service-trust literal, the retired human_notified) routes
+                    // through the SAME composer every other refusal surface uses — no second hand-built
+                    // arm-selector, no second value renderer. The conformance fixture (`buildFixture`)
+                    // exercises only the gate-literal branch (`human_confirmed`), so the composer's three
+                    // sub-arms are unreached by it — verified by grepping the fixture builder for this key.
+                    const rawFinalizerTrust = step['trust'];
+                    const finalizerMessage = isGateTrust(rawFinalizerTrust)
+                        ? `Step '${stepName}': 'trust: ${renderTrustValue(rawFinalizerTrust)}' is not valid on execution: finalizer steps (a finalizer must not gate)`
+                        : buildTrustRefusal({
+                            kind: 'finalizer',
+                            value: rawFinalizerTrust,
+                            step: stepName,
+                            surface: 'load',
+                        });
+                    errors.push(withStepLine(stepName, finalizerMessage));
                 }
                 // v1 is handler-only.
                 if (step['handler'] === undefined) {
@@ -793,141 +887,56 @@ function parseWorkflowString(content, registry, opts) {
                     }
                 }
             }
-            // on_outcome is only valid on execution: finalizer steps.
-            if (step['on_outcome'] !== undefined && step['execution'] !== 'finalizer') {
-                errors.push(
-                // Consumer: settlement.ts:145 (`finalizerTriggers`) — it is read only when selecting
-                // which finalizers a run's outcome should fire.
-                withKeyLine(stepName, 'on_outcome', `Step '${stepName}': 'on_outcome' is only valid on execution: finalizer steps — it ` +
-                    'selects which finalizers run for a given outcome, and only finalizers are selected ' +
-                    'that way, so here it would decide nothing. Move it to the finalizer that should ' +
-                    'react to the outcome, or remove it.'));
+            // issue #508 (L1) — trust VALUE validation, auto/agent only. Before this check, an
+            // unrecognized or kind-inert `trust` (a typo, a service-trust literal, the retired
+            // `human_notified`) loaded clean, warned nothing, and ran with NO gate — the step's own
+            // declared human-approval control was silently disabled. Presence-keyed (`'trust' in
+            // step`, the same convention `trigger_rule` and `retry.backoff` already use below) so
+            // `trust:`/`trust: ~` (a null value, which loads clean today) is caught too — a blank
+            // declaration of a safety control is itself a false statement, not a no-op. `trust:`
+            // absent entirely is lawful (nothing was declared) and never reaches this block.
+            //
+            // Guard's OWN trust prohibition is minted by the #517 walk above (every value refused,
+            // no except arm); finalizer's is the hand-written except-cell just above (only 'auto' is
+            // lawful there). This block is what closes the remaining two kinds — the ones where a
+            // RECOGNIZED gate literal is meaningful, so an unrecognized one needs a VALUE verdict,
+            // not a kind verdict.
+            //
+            // issue #508 (final correction) — this whole value-refusal composition, for every kind and
+            // every surface, is now `buildTrustRefusal` (types/workflow-definition.ts, beside
+            // `classifyStepTrust`). Three prior rounds each hand-composed this text independently on
+            // this surface, execution-loop.ts's dispatch refusal, run-health.ts's finding, and the
+            // protocol generator's briefing — and every defect those rounds found (arm divergence, a
+            // String()-rendered array printing as its own first element, a grammar seam) fell out of
+            // that duplication. No site chooses an arm or renders a value on its own again; see the
+            // composer's own doc for the arm/mood/rendering contract in full.
+            if ((stepKind === 'auto' || stepKind === 'agent') &&
+                'trust' in step &&
+                classifyStepTrust(stepKind, step['trust']) === 'refuse') {
+                errors.push(withKeyLine(stepName, 'trust', buildTrustRefusal({
+                    kind: stepKind,
+                    value: step['trust'],
+                    step: stepName,
+                    surface: 'load',
+                })));
             }
-            // Guard step constraints.
+            // Guard step constraints (the guard kind-prohibitions, including `preconditions` — issue
+            // #369's own bespoke message, message_data-preserved — are minted by the #517 walk above).
             if (step['execution'] === 'guard') {
-                const prohibited = [
-                    'uses_service',
-                    'handler',
-                    'input_schema',
-                    'output_schema',
-                    'trust',
-                    'agent_profile',
-                    'trigger_rule',
-                    'timeout_seconds',
-                    'service_method',
-                    'operation',
-                    'input_map',
-                    'tools',
-                ];
-                for (const field of prohibited) {
-                    if (step[field] !== undefined) {
-                        errors.push(withStepLine(stepName, `Step '${stepName}': '${field}' is not valid on execution: guard steps`));
-                    }
-                }
                 if (step['abort_unless'] === undefined) {
                     errors.push(withStepLine(stepName, `Step '${stepName}': execution: guard requires 'abort_unless'`));
                 }
-                // issue #369: `preconditions` gets its OWN error rather than joining `prohibited` above,
-                // because the generic message ("'x' is not valid on execution: guard steps") would not say
-                // the thing that matters — this field was ACCEPTED and INERT before this check existed, so
-                // an author who wrote one has a workflow that looks guarded and never was. The generic
-                // list's own message style is issue #366's territory; the other twelve are left alone.
-                //
-                // The claim "never evaluates it there" rests on `checkPreconditions` having exactly one
-                // engine call site (execution-loop.ts:1380, inside `executeStep`), which `executeGuardStep`
-                // never reaches. A test pins that count so a second call site reds this message.
-                if (step['preconditions'] !== undefined) {
-                    errors.push(withKeyLine(stepName, 'preconditions', `Step '${stepName}': 'preconditions' is not valid on execution: guard steps — the ` +
-                        `engine never evaluates it there (a guard's execution evaluates only 'abort_unless'), ` +
-                        `so the run would LOOK guarded while the declared check never ran. Move the condition ` +
-                        `into 'abort_unless'. Whether guards gain a live condition surface is an open design ` +
-                        `question (issue #366) — if admitted later, existing workflows are unaffected.`));
-                }
-            }
-            // abort_unless and abort_message are only valid on execution: guard steps.
-            if (step['abort_unless'] !== undefined && step['execution'] !== 'guard') {
-                errors.push(
-                // Consumer: execution-loop.ts:4828 — the condition list a guard evaluates before the
-                // run is allowed to continue.
-                withKeyLine(stepName, 'abort_unless', `Step '${stepName}': 'abort_unless' is only valid on execution: guard steps — it is ` +
-                    'the condition list a guard evaluates before letting the run continue, and only ' +
-                    'guard steps are evaluated that way, so here it would gate nothing. Put the check ' +
-                    'on a guard step, or remove it.'));
-            }
-            if (step['abort_message'] !== undefined && step['execution'] !== 'guard') {
-                errors.push(
-                // Consumer: execution-loop.ts:4943 — the text reported when a guard aborts the run.
-                // The clause is about READERSHIP, not about who aborts: `handler_abort` and
-                // `gate_expiry_abort` are seal arms too (types/run-record.ts:603-617), so "only a guard
-                // aborts" would be false. What is true is that every reader of this key is a guard path.
-                withKeyLine(stepName, 'abort_message', `Step '${stepName}': 'abort_message' is only valid on execution: guard steps — it is ` +
-                    'the text reported when a guard aborts the run, and nothing but a guard reads it, ' +
-                    'so here it would never be read. Move it to the guard that performs the abort, or ' +
-                    'remove it.'));
             }
-            // agent_profile is only valid on agent steps.
-            if ('agent_profile' in step && step['execution'] !== 'agent') {
-                errors.push(
-                // Consumer: run-agent.ts:584 — resolved into the model prompt for the step.
-                withKeyLine(stepName, 'agent_profile', `Step '${stepName}': 'agent_profile' is only valid on execution: agent steps — its ` +
-                    'content is resolved into the model prompt, and only an agent step makes a model ' +
-                    'request, so here it would reach no model. Move it to the agent step whose prompt ' +
-                    'it should shape, or remove it.'));
-            }
-            // llm_timeout_seconds (issue #401) is only valid on agent steps — no other execution kind
-            // makes a model request, so the key would be silently inert anywhere else. One `!== 'agent'`
-            // check covers auto/guard/finalizer.
-            if (step['llm_timeout_seconds'] !== undefined && step['execution'] !== 'agent') {
-                errors.push(
-                // Consumer: run-agent.ts:501-507 — the per-step clock resolution, which is the
-                // per-attempt bound on the step's model request. The range names the resolution rather
-                // than each read: :501 and :507 read the KEY, :503 reads the CLI flag it overrides.
-                withKeyLine(stepName, 'llm_timeout_seconds', `Step '${stepName}': 'llm_timeout_seconds' is only valid on execution: agent steps — ` +
-                    'it bounds one model request, and no other kind makes one, so here it would bound ' +
-                    'nothing. Move it to the agent step whose request it should bound, or remove it. ' +
-                    "An auto step's dispatch is bounded by 'timeout_seconds', and a " +
-                    "finalizer's handler by its own 'timeout_seconds'."));
-            }
-            // ...and when present it must be a positive integer (the same convention as
-            // retry.total_timeout_seconds and gate.timeout_seconds).
+            // llm_timeout_seconds must be a positive integer when present (the same convention as
+            // retry.total_timeout_seconds and gate.timeout_seconds). Deliberately kind-BLIND, which
+            // makes it the pinned DOUBLE-fire control for #517: on a wrong-kind step BOTH the minted
+            // prohibition and this shape error fire — this check was never else-if-suppressed, unlike
+            // structured_output/validation_exhaustion/input_map's value checks below.
             if (step['llm_timeout_seconds'] !== undefined &&
                 (!Number.isInteger(step['llm_timeout_seconds']) ||
                     step['llm_timeout_seconds'] <= 0)) {
                 errors.push(withStepLine(stepName, `Step '${stepName}': 'llm_timeout_seconds' must be a positive integer`));
             }
-            // timeout_seconds is NOT valid on an agent step (issue #402). Nothing enforces it there:
-            // `shouldEnforceTimeout` is `execution === 'auto'`, and agent dispatch is never wrapped in
-            // `withTimeout` at all. The key is now inert as well as unenforced — issue #412 deleted the
-            // `expected_timeout` display that used to render it into the NextAction, which is what made
-            // it actively misleading rather than merely useless. The error stays: an author who writes a
-            // bound should be told it does nothing, not left to find out. The message names both bounds
-            // that DO exist, scoped to realm's own drive (an externally driven step gets neither), on
-            // the RETRY_INERT_NON_AUTO precedent below.
-            //
-            // `=== 'agent'` EXACTLY, never `!== 'auto'`: finalizers consume this key twice — the drain
-            // lease (execution-loop.ts:5226) and the handler's own bound (:5030) — and guards already
-            // reject it in the prohibited-fields list above.
-            if (step['timeout_seconds'] !== undefined && step['execution'] === 'agent') {
-                errors.push(withKeyLine(stepName, 'timeout_seconds', `Step '${stepName}': 'timeout_seconds' is not valid on execution: agent steps — ` +
-                    'the engine never enforces it there (agent dispatch is never wrapped in a timeout), ' +
-                    'so the step would LOOK time-bounded while nothing enforced the bound. ' +
-                    "In realm's own drive the model request is bounded by 'llm_timeout_seconds' " +
-                    "(or --llm-timeout) and tool calls by 'tool_timeout'."));
-            }
-            // idempotent (issue #101 Phase 2) is only valid on execution: auto steps — the reliably
-            // time-boundable, deadline-carrying class. It is inert (no concrete deadline is ever written)
-            // on agent/guard/finalizer, so it is rejected there rather than silently ignored.
-            if (step['idempotent'] !== undefined && step['execution'] !== 'auto') {
-                errors.push(
-                // Consumers: execution-loop.ts:2526 (the `willRetry` conjunct gating `retry.on_timeout`;
-                // the :2115 advisory mirrors the rule for loader-bypassing definitions and, by its own
-                // header, never gates) and reclaim.ts:73 (reclaim eligibility) — both act on auto
-                // dispatch.
-                withKeyLine(stepName, 'idempotent', `Step '${stepName}': 'idempotent' is only valid on execution: auto steps — it gates ` +
-                    "'retry.on_timeout' and reclaim eligibility, and both act on auto dispatch, so here " +
-                    'it would gate nothing. Remove it, or move the work to an auto step if you need ' +
-                    'either.'));
-            }
             // WARN (do not reject): an idempotent auto step in a finalizer-bearing workflow gets
             // `deadline: null` (issue #101), so the RECLAIM function is inert — `realm run reclaim --all`
             // can never select it. The author should know it stays per-step-manual-reclaim-only.
@@ -956,21 +965,16 @@ function parseWorkflowString(content, registry, opts) {
                             : ''),
                 });
             }
-            // output_schema is only valid on execution: agent steps.
-            if (step['output_schema'] !== undefined && step['execution'] !== 'agent') {
-                errors.push(withStepLine(stepName, `Step '${stepName}': 'output_schema' is only valid on execution: agent steps`));
-            }
-            // issue #236 (L0 prevention layer): structured_output is only valid on execution: agent
-            // steps (mirrors output_schema's rule above), and its only legal value is the literal
+            // issue #236 (L0 prevention layer): structured_output's only legal value is the literal
             // 'strict'. On an opted-in step, Phase A REJECTS an ineligible verdict at load time — the
             // API provably rejects some legal schemas and silently weakens others, so authoring never
             // ships a schema the gate already knows is unsafe. Caveats are NOT rejected (informational
             // only, surfaced by validate's nudge — Deliverable 7); this loader block only ever REJECTS.
-            if (step['structured_output'] !== undefined) {
-                if (step['execution'] !== 'agent') {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'structured_output' is only valid on execution: agent steps`));
-                }
-                else if (step['structured_output'] !== 'strict') {
+            // #517 re-gate: the kind half is minted by the registry walk above; the value checks
+            // below keep their old else-branch semantics via an explicit valid-kind conjunct — a
+            // wrong-kind step gets ONLY the minted refusal, never the value noise.
+            if (step['structured_output'] !== undefined && step['execution'] === 'agent') {
+                if (step['structured_output'] !== 'strict') {
                     errors.push(withStepLine(stepName, `Step '${stepName}': 'structured_output' must be the literal string 'strict' (got ${JSON.stringify(step['structured_output'])})`));
                 }
                 else {
@@ -998,11 +1002,9 @@ function parseWorkflowString(content, registry, opts) {
             // then AJV-proven AT LOAD TIME (REFUSE — B10, reusing the runtime validator so load-time and
             // runtime verdicts can never diverge); `default_output` present without `mode: 'default'` WARNS
             // as dead config (never rejects — it's simply inert); an unknown sub-key WARNS.
-            if (step['validation_exhaustion'] !== undefined) {
-                if (step['execution'] !== 'agent') {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion' is only valid on execution: agent steps`));
-                }
-                else if (typeof step['validation_exhaustion'] !== 'object' ||
+            // #517 re-gate: kind half minted above; else-semantics preserved by the explicit conjunct.
+            if (step['validation_exhaustion'] !== undefined && step['execution'] === 'agent') {
+                if (typeof step['validation_exhaustion'] !== 'object' ||
                     step['validation_exhaustion'] === null) {
                     errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion' must be an object`));
                 }
@@ -1097,26 +1099,85 @@ function parseWorkflowString(content, registry, opts) {
                         `output is validated against both — prefer one to avoid divergence.`,
                 });
             }
-            // trace_schema is only valid on execution: agent steps.
-            if (step['trace_schema'] !== undefined && step['execution'] !== 'agent') {
-                errors.push(withStepLine(stepName, `Step '${stepName}': 'trace_schema' is only valid on execution: agent steps`));
-            }
-            // trace_validation_mode is only valid on execution: agent steps.
-            if (step['trace_validation_mode'] !== undefined && step['execution'] !== 'agent') {
-                errors.push(withStepLine(stepName, `Step '${stepName}': 'trace_validation_mode' is only valid on execution: agent steps`));
-            }
             // trace_validation_mode must be 'warn' or 'enforce' when provided.
             if (step['trace_validation_mode'] !== undefined &&
                 step['trace_validation_mode'] !== 'warn' &&
                 step['trace_validation_mode'] !== 'enforce') {
                 errors.push(withStepLine(stepName, `Step '${stepName}': invalid trace_validation_mode '${String(step['trace_validation_mode'])}'; must be 'warn' or 'enforce'`));
             }
+            // issue #433: the effective STATIC gate choice source, hoisted per-step BEFORE the
+            // `gate:`-block-only region below. Member (b) below must fire even when there is NO `gate:`
+            // key at all (the executed g433b shape: a gate-trusted step with no gate block but an
+            // empty `input_schema.properties.choice.enum`), and the entire #291 region beneath this one
+            // is gated on `step['gate'] !== undefined` — it cannot host a check that must fire without
+            // one. Pure reads; the existing E2/membership cells (below) pin messages, not evaluation
+            // order, so hoisting these three declarations ahead of them is safe.
+            const gateObj = typeof step['gate'] === 'object' && step['gate'] !== null
+                ? step['gate']
+                : undefined;
+            const declaredGateChoices = gateObj?.['choices'];
+            const declaredChoiceEnum = step['input_schema']?.properties?.['choice']?.enum;
+            // Renders the OFFENDING KEY's own line via its full nested path, falling back to the
+            // step's line and then to no position — the same two-rung univocal vocabulary
+            // `withKeyLine` documents above (issue #420: `(line N)` for the key, `(step at line N)`
+            // for the step; never conflated). `withKeyLine` itself is single-segment
+            // (`['steps', stepName, key]`) and cannot express a nested path like
+            // `['steps', stepName, 'gate', 'choices']`, so this is a local sibling rather than a call
+            // to it — no existing `withKeyLine` call site is touched.
+            const withPathLine = (path, message) => {
+                const keyLine = sourceMap.posOf(path)?.line;
+                if (keyLine !== undefined)
+                    return `${message} (line ${keyLine})`;
+                const stepLine = sourceMap.posOf(['steps', stepName])?.line;
+                if (stepLine !== undefined)
+                    return `${message} (step at line ${stepLine})`;
+                return message;
+            };
+            // Member (a) (issue #433): a DECLARED `gate.choices` list that is empty is never right, on
+            // ANY step — gate-trusted or not (the #291 block's own posture just below: a `gate:` key
+            // is validated "regardless of trust"; the #417 strict-on-known-key policy agrees). An empty
+            // list on a gate-trusted step mints an unanswerable gate (every response is refused against
+            // an empty expected set) with no disposal path short of an authored expiry — on an ungated
+            // step it is dead weight either way, so the message is deliberately population-invariant
+            // rather than false for the ungated population.
+            if (Array.isArray(declaredGateChoices) && declaredGateChoices.length === 0) {
+                errors.push(withPathLine(['steps', stepName, 'gate', 'choices'], `Step '${stepName}': 'gate.choices', when declared, must be non-empty — an empty ` +
+                    'list is never right: on a gate-trusted step (trust: human_confirmed/human_reviewed) ' +
+                    'it mints a gate NO response can ever resolve (every submission is refused against ' +
+                    'an empty expected list, and the live run wedges with no disposal path: abandon ' +
+                    'refuses a pending gate; purge and drain refuse a live run; only an authored ' +
+                    "'gate.timeout_seconds' + 'on_expiry' expiry could ever clear it). Declare at least " +
+                    "one choice, or remove the key to fall back to 'input_schema.properties.choice.enum' " +
+                    'or the default pair (approve/reject).'));
+            }
+            // Member (b) (issue #433): for a GATE-TRUSTED step with no `gate.choices` list declared
+            // (NULLISH — the mint's own `??` semantics; `gate: {choices:}` with a YAML-null value is
+            // the third executed wedge shape, and presence-keying would let it escape this check), a
+            // DECLARED-and-empty `input_schema.properties.choice.enum` is the effective choice source
+            // and the same class of error, under its own key. `choices: null` with no `enum` at all
+            // stays legal — the mint defaults to ['approve', 'reject'].
+            if (isGateTrust(step['trust']) &&
+                declaredGateChoices == null &&
+                Array.isArray(declaredChoiceEnum) &&
+                declaredChoiceEnum.length === 0) {
+                errors.push(withPathLine(['steps', stepName, 'input_schema', 'properties', 'choice', 'enum'], `Step '${stepName}': 'input_schema.properties.choice.enum' is this gate's effective ` +
+                    "choice source (no 'gate.choices' list declared) and, when declared, must be " +
+                    'non-empty — an empty list mints a gate NO response can ever resolve (every ' +
+                    'submission is refused against an empty expected list, and the live run wedges ' +
+                    'with no disposal path: abandon refuses a pending gate; purge and drain refuse a ' +
+                    "live run; only an authored 'gate.timeout_seconds' + 'on_expiry' expiry could ever " +
+                    "clear it). Declare at least one enum value, or remove 'enum' to get the default " +
+                    'pair (approve/reject).'));
+            }
             // issue #291 (authorable gate timeout — the FIRST validation the `gate:` block has ever had):
             // the E2 positive-integer checks on timeout_seconds/reminder_seconds/reminder_max, the
             // on_expiry enum, default_choice's required-iff + choice-set validation, and the dead-config
-            // warn cells. Runs regardless of `trust` (a `gate:` block with no gate trust is already inert
-            // — no separate rejection needed; the existing render/mint paths never read it without a
-            // trust value).
+            // warn cells. The hard-error checks run regardless of `trust` (a shape/enum mistake is a
+            // mistake whether or not this step can ever gate). The dead-config ADVISORIES fork on
+            // `isGateTrust` (issue #524): the engine mints a gate only where trust requires human
+            // confirmation (Step 5b, `execution-loop.ts`) — on any other step the WHOLE block is inert,
+            // so a per-member remedy ("set a timeout") would be false: following it never makes the key
+            // live, it only silences the one diagnostic that said so.
             if (step['gate'] !== undefined) {
                 if (typeof step['gate'] !== 'object' || step['gate'] === null) {
                     errors.push(withStepLine(stepName, `Step '${stepName}': 'gate' must be an object`));
@@ -1156,17 +1217,22 @@ function parseWorkflowString(content, registry, opts) {
                     // mirroring validation_exhaustion.mode:'default' requiring default_output); validated
                     // against the step's own EFFECTIVE STATIC choice set — the EXACT same three-source
                     // derivation the engine mints PendingGate.choices from (execution-loop.ts's gate-open
-                    // site: gate.choices ?? input_schema.properties.choice.enum ?? ['approve','reject']) —
-                    // so a load-time-legal default_choice can NEVER fail at enactment time.
+                    // site: gate.choices ?? input_schema.properties.choice.enum ?? ['approve','reject']),
+                    // sourced from the issue #433 hoist above (`declaredGateChoices ?? declaredChoiceEnum`
+                    // — one chain, so this can never drift from the mint's) — so a load-time-legal
+                    // default_choice can NEVER fail at enactment time.
                     const hasDefaultChoice = 'default_choice' in gate;
+                    // issue #524: the one place this block's dead-config ADVISORIES fork. The mint only
+                    // ever reads `gate.*` where `isGateTrust(trust)` holds (execution-loop.ts:3302,
+                    // `W_GATE_MINT_TRUST`) — computed once so the three sites below can never disagree.
+                    const gateTrusted = isGateTrust(step['trust']);
                     if (onExpiry === 'settle_default') {
                         if (!hasDefaultChoice) {
                             errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.on_expiry: settle_default' requires 'gate.default_choice' ` +
                                 `(nothing to resolve the gate with on expiry)`));
                         }
                         else {
-                            const choicesRaw = gate['choices'] ??
-                                step['input_schema']?.properties?.['choice']?.enum;
+                            const choicesRaw = declaredGateChoices ?? declaredChoiceEnum;
                             const effectiveChoices = Array.isArray(choicesRaw)
                                 ? choicesRaw
                                 : ['approve', 'reject'];
@@ -1176,9 +1242,10 @@ function parseWorkflowString(content, registry, opts) {
                             }
                         }
                     }
-                    else if (hasDefaultChoice) {
+                    else if (hasDefaultChoice && gateTrusted) {
                         // default_choice with on_expiry:'abort' or with no on_expiry at all — inert, not an
                         // error: WARN as dead config (the #220 DEAD_VALIDATION_EXHAUSTION_CONFIG precedent).
+                        // Gate-trusted only (issue #524) — off gate trust the block advisory below covers it.
                         warnings.push({
                             code: 'DEAD_GATE_CONFIG',
                             severity: resolveSeverity('DEAD_GATE_CONFIG'),
@@ -1188,31 +1255,69 @@ function parseWorkflowString(content, registry, opts) {
                                 `'gate.on_expiry: settle_default' — set it, or remove 'gate.default_choice'.`,
                         });
                     }
-                    // Dead config: on_expiry declared but no timeout_seconds — nothing will ever trigger the
-                    // enforce clock, so the declared disposition can never enact.
-                    if (onExpiry !== undefined && gate['timeout_seconds'] === undefined) {
-                        warnings.push({
-                            code: 'DEAD_GATE_CONFIG',
-                            severity: resolveSeverity('DEAD_GATE_CONFIG'),
-                            scope: 'step',
-                            step: stepName,
-                            message: `Step '${stepName}': 'gate.on_expiry' is ignored without 'gate.timeout_seconds' — ` +
-                                `set a timeout, or remove 'gate.on_expiry'.`,
-                        });
+                    if (gateTrusted) {
+                        // Dead config: on_expiry declared but no timeout_seconds — nothing will ever trigger
+                        // the enforce clock, so the declared disposition can never enact. Gate-trusted only
+                        // (issue #524): off gate trust the block advisory below covers it.
+                        if (onExpiry !== undefined && gate['timeout_seconds'] === undefined) {
+                            warnings.push({
+                                code: 'DEAD_GATE_CONFIG',
+                                severity: resolveSeverity('DEAD_GATE_CONFIG'),
+                                scope: 'step',
+                                step: stepName,
+                                message: `Step '${stepName}': 'gate.on_expiry' is ignored without 'gate.timeout_seconds' ` +
+                                    `— set a timeout, or remove 'gate.on_expiry'.`,
+                            });
+                        }
+                        // Dead notification ([F-A2-5]): reminder_seconds >= timeout_seconds means the FIRST
+                        // reminder occurrence would never fire before the enforce clock expires. Gate-trusted
+                        // only (issue #524): off gate trust the block advisory below covers it.
+                        if (typeof gate['reminder_seconds'] === 'number' &&
+                            typeof gate['timeout_seconds'] === 'number' &&
+                            gate['reminder_seconds'] >= gate['timeout_seconds']) {
+                            warnings.push({
+                                code: 'DEAD_GATE_CONFIG',
+                                severity: resolveSeverity('DEAD_GATE_CONFIG'),
+                                scope: 'step',
+                                step: stepName,
+                                message: `Step '${stepName}': 'gate.reminder_seconds' (${String(gate['reminder_seconds'])}) ` +
+                                    `>= 'gate.timeout_seconds' (${String(gate['timeout_seconds'])}) — the first ` +
+                                    `reminder would never fire before the gate expires.`,
+                            });
+                        }
                     }
-                    // Dead notification ([F-A2-5]): reminder_seconds >= timeout_seconds means the FIRST
-                    // reminder occurrence would never fire before the enforce clock expires.
-                    if (typeof gate['reminder_seconds'] === 'number' &&
-                        typeof gate['timeout_seconds'] === 'number' &&
-                        gate['reminder_seconds'] >= gate['timeout_seconds']) {
+                    else {
+                        // issue #524 (the gate-remedy silence): without gate trust the mint never reads ANY
+                        // key in this block, so a per-member remedy ("set a timeout") is false — following it
+                        // would silence the diagnostic while the whole block stays exactly as dead. ONE
+                        // advisory naming the true cause, unconditional on which keys are set (the block is
+                        // equally inert whichever ones are). Position on the STRUCTURED channel only
+                        // (`withKeyLine`/`withPathLine` are the ERROR-string helpers, consumed only by
+                        // `errors.push` — no loader advisory carries a position today, and this one follows
+                        // that convention: `renderLoaderWarning` prints `⚠ ${message}` alone). The kind list
+                        // is DERIVED from the registry (`consumedKindsFor('trust')`, the #517
+                        // `consumed_home.kinds` pattern) so the remedy can never drift from the vocabulary
+                        // that actually gates it.
+                        const gatePos = sourceMap.posOf(['steps', stepName, 'gate']);
+                        const trustKinds = consumedKindsFor('trust');
                         warnings.push({
                             code: 'DEAD_GATE_CONFIG',
                             severity: resolveSeverity('DEAD_GATE_CONFIG'),
                             scope: 'step',
                             step: stepName,
-                            message: `Step '${stepName}': 'gate.reminder_seconds' (${String(gate['reminder_seconds'])}) ` +
-                                `>= 'gate.timeout_seconds' (${String(gate['timeout_seconds'])}) — the first reminder ` +
-                                `would never fire before the gate expires.`,
+                            key: 'gate',
+                            ...(gatePos !== undefined
+                                ? {
+                                    line: gatePos.line,
+                                    column: gatePos.column,
+                                    endLine: gatePos.endLine,
+                                    endColumn: gatePos.endColumn,
+                                }
+                                : {}),
+                            message: `Step '${stepName}': the 'gate:' block is inert — this step declares no gate ` +
+                                `trust ('trust: human_confirmed' or 'trust: human_reviewed'), so no gate is ever ` +
+                                `minted and none of its keys are read. Remove the block, or (on an ` +
+                                `${trustKinds.join(' or ')} step) declare that trust.`,
                         });
                     }
                 }
@@ -1232,6 +1337,13 @@ function parseWorkflowString(content, registry, opts) {
                 }
                 else {
                     const retry = step['retry'];
+                    // The one population gate both retry advisories (W5 + RETRY_INERT_NON_AUTO) share:
+                    // the registry's own retry cell for this step's kind. `inert` = admitted-but-unread
+                    // (agent/guard). On `consumed` (auto) neither advisory applies; on `prohibited`
+                    // (finalizer) the #517 refusal above is the whole story and an advisory beside it
+                    // would contradict it; on a malformed kind the invalid-execution error is the verdict.
+                    const retryCellIsInert = VALID_EXECUTIONS.has(step['execution']) &&
+                        STEP_KEY_REGISTRY.retry[step['execution']].c === 'inert';
                     // WARN (do not reject) on an unknown retry-block key — same non-breaking posture as the
                     // step/workflow-level checks (issue #140). Noun overridden to 'retry' (not 'step') since
                     // this is a nested block, not the step itself.
@@ -1284,8 +1396,11 @@ function parseWorkflowString(content, registry, opts) {
                     }
                     // W5 (CAP-ONLY advisory — the on_timeout half of this is already an E1 hard error, so
                     // it never reaches here as a warning): the total-time cap only bounds `execution: 'auto'`
-                    // dispatch — inert on any other step type that legally declares `retry:` today.
-                    if (step['execution'] !== 'auto' && retry['total_timeout_seconds'] !== undefined) {
+                    // dispatch — inert on any other step type that LEGALLY declares `retry:`. The gate is
+                    // the registry's own retry cell: the advisory fires only where retry is admitted-but-
+                    // inert (agent/guard), never beside the finalizer refusal it would contradict, and
+                    // never on a malformed kind (already refused by the invalid-execution error).
+                    if (retryCellIsInert && retry['total_timeout_seconds'] !== undefined) {
                         warnings.push({
                             code: 'TOTAL_TIMEOUT_NON_AUTO',
                             severity: resolveSeverity('TOTAL_TIMEOUT_NON_AUTO'),
@@ -1293,19 +1408,21 @@ function parseWorkflowString(content, registry, opts) {
                             step: stepName,
                             message: `Step '${stepName}': 'retry.total_timeout_seconds' is inert on execution: ` +
                                 `'${String(step['execution'])}' steps — the cap only bounds 'execution: auto' ` +
-                                `dispatch, which is the only dispatch ever wrapped in a timeout.`,
+                                `dispatch; no other kind's dispatch ever consumes it.`,
                         });
                     }
                     // issue #218 (extends the W5 family): the BARE-KEYS advisory — no explicit
-                    // total_timeout_seconds (that shape is W5's, above), but retry: is present on a step the
-                    // built-in dispatch path never wraps in a throwing retry loop at all. Complementary to
-                    // W5's own `!== undefined` conjunct on the SAME `execution !== 'auto'` gate, so for any
-                    // non-auto retry block that reaches this point (finalizer+retry and invalid-cap shapes
-                    // already hard-errored above; on_timeout: true already hard-errored via E1 unless
-                    // idempotent is also declared, which is itself rejected by the pre-existing
-                    // idempotent-non-auto check) exactly ONE of {W5, RETRY_INERT_NON_AUTO} ever fires — never
-                    // both, never neither.
-                    if (step['execution'] !== 'auto' && retry['total_timeout_seconds'] === undefined) {
+                    // total_timeout_seconds (that shape is W5's, above), but retry: is present on a step no
+                    // dispatching retry loop ever consumes it on. Complementary to W5's own `!== undefined`
+                    // conjunct on the SAME registry-derived inert gate, so for any admitted-but-inert retry
+                    // block exactly ONE of {W5, RETRY_INERT_NON_AUTO} ever fires — never both, never
+                    // neither. The gate EXCLUDES the prohibited kind (finalizer): errors accumulate rather
+                    // than halt, so the old `!== 'auto'` gate leaked this advisory beside the finalizer
+                    // refusal, where every clause of it was false ("never throws" — the drain throws
+                    // routinely; "may still consume" — no dispatcher can reach a finalizer's retry;
+                    // "not an invalid one" — the co-fired error says it IS invalid). Registry-derived:
+                    // it fires exactly where the retry cell is inert (agent/guard).
+                    if (retryCellIsInert && retry['total_timeout_seconds'] === undefined) {
                         const isAgent = step['execution'] === 'agent';
                         const message = isAgent
                             ? `Step '${stepName}': 'retry' is inert on execution: 'agent' steps — the built-in ` +
@@ -1314,9 +1431,9 @@ function parseWorkflowString(content, registry, opts) {
                                 `flag instead). An embedder-supplied throwing dispatcher may still consume this ` +
                                 `config — a deliberate public-API capability, not an invalid one.`
                             : `Step '${stepName}': 'retry' is inert on execution: '${String(step['execution'])}' ` +
-                                `steps — the built-in dispatch path never throws for these steps, so this block can ` +
-                                `never mint a second attempt here. An embedder-supplied throwing dispatcher may ` +
-                                `still consume this config — a deliberate public-API capability, not an invalid one.`;
+                                `steps — a guard's evaluation never traverses the dispatch path (its conditions ` +
+                                `are evaluated inline, with no dispatcher and no retry read), so this block can ` +
+                                `never mint a second attempt here.`;
                         warnings.push({
                             code: 'RETRY_INERT_NON_AUTO',
                             severity: resolveSeverity('RETRY_INERT_NON_AUTO'),
@@ -1339,13 +1456,16 @@ function parseWorkflowString(content, registry, opts) {
                                 `'max_attempts' of 1 — there is no second attempt to retry into.`,
                         });
                     }
-                    // W2: the cap can never cover even a single full-length attempt — (a) an EXPLICIT cap
-                    // below an EXPLICIT timeout_seconds, or (b) on_timeout: true with a cap at-or-below the
-                    // effective per-attempt timeout (retry-defeating: the opt-in can never yield a viable
-                    // second attempt). Both conditions require an EXPLICIT total_timeout_seconds — the
-                    // AMENDED default cap (the worst-case schedule) is, by construction, never below a
-                    // single attempt for max_attempts ≥ 2, so this never fires on the bare 3600s-default
-                    // population.
+                    // W2 (issue #524 correction): the declared cap is at or below the per-attempt timeout —
+                    // (a) an EXPLICIT cap below an EXPLICIT timeout_seconds, or (b) on_timeout: true with a
+                    // cap at-or-below the effective per-attempt timeout. This does NOT mean "no retry can
+                    // ever occur": `willRetry`'s first disjunct (execution-loop.ts) has no cap conjunct, so
+                    // a retryable failure that returns faster than the (clipped) attempt bound still retries
+                    // while 'max_attempts' allows another attempt — only an attempt that runs OUT its full
+                    // bound exhausts the cap with nothing left for a retry. Both arms require an EXPLICIT
+                    // total_timeout_seconds — the AMENDED default cap (the worst-case schedule) is, by
+                    // construction, never below a single attempt for max_attempts ≥ 2, so this never fires
+                    // on the bare 3600s-default population.
                     const explicitCapSeconds = typeof retry['total_timeout_seconds'] === 'number'
                         ? retry['total_timeout_seconds']
                         : undefined;
@@ -1361,9 +1481,11 @@ function parseWorkflowString(content, registry, opts) {
                                 scope: 'step',
                                 step: stepName,
                                 message: `Step '${stepName}': 'retry.total_timeout_seconds: ${explicitCapSeconds}' is at ` +
-                                    `or below its own effective per-attempt timeout (${effectivePerAttemptSeconds}s) ` +
-                                    `— the cap can never cover a single full-length attempt, so a retry can never ` +
-                                    `occur before the cap fires.`,
+                                    `or below its per-attempt timeout (${effectivePerAttemptSeconds}s` +
+                                    `${explicitTimeoutSeconds === undefined ? ', the default' : ''}) — each attempt ` +
+                                    `is bounded by what remains of the cap, so an attempt that runs to its bound ` +
+                                    `exhausts the cap with no retry; a faster failure still retries while ` +
+                                    `'max_attempts' allows another attempt and its backoff wait fits the remaining cap.`,
                             });
                         }
                     }
@@ -1373,21 +1495,18 @@ function parseWorkflowString(content, registry, opts) {
                 !VALID_SERVICE_METHODS.has(step['service_method'])) {
                 errors.push(withStepLine(stepName, `Step '${stepName}': invalid service_method '${String(step['service_method'])}'; must be 'fetch', 'create', 'update', or 'delete'`));
             }
-            // Validate input_map: only valid on execution: auto steps (both uses_service and handler).
-            if (step['input_map'] !== undefined) {
-                if (step['execution'] !== 'auto') {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'input_map' is only valid on execution: auto steps`));
-                }
-                else {
-                    // issue #392: input_map's errors are minted deep inside a recursive walk that knows only
-                    // its path string, not the step's position. Collected here and suffixed on the way out,
-                    // so ONE step's error list never mixes positioned and bare messages — a reader seeing
-                    // "(step at line 12)" on three of five errors would reasonably wonder what is different about
-                    // the other two, and nothing is.
-                    const inputMapErrors = [];
-                    validateInputMapNode(step['input_map'], `Step '${stepName}': input_map`, inputMapErrors, 0);
-                    errors.push(...inputMapErrors.map((e) => withStepLine(stepName, e)));
-                }
+            // Validate input_map VALUES (auto only — the kind half is minted by the #517 walk; the
+            // explicit conjunct preserves the old else-branch: a wrong-kind step gets only the minted
+            // refusal, never the value noise).
+            if (step['input_map'] !== undefined && step['execution'] === 'auto') {
+                // issue #392: input_map's errors are minted deep inside a recursive walk that knows only
+                // its path string, not the step's position. Collected here and suffixed on the way out,
+                // so ONE step's error list never mixes positioned and bare messages — a reader seeing
+                // "(step at line 12)" on three of five errors would reasonably wonder what is different about
+                // the other two, and nothing is.
+                const inputMapErrors = [];
+                validateInputMapNode(step['input_map'], `Step '${stepName}': input_map`, inputMapErrors, 0);
+                errors.push(...inputMapErrors.map((e) => withStepLine(stepName, e)));
             }
             // Step config may hold any JSON value (scalars, arrays, nested objects). It is passed through
             // opaquely to handlers (context.config) and merged into adapter config for uses_service steps;
@@ -1464,7 +1583,7 @@ function parseWorkflowString(content, registry, opts) {
                         errors.push(withStepLine(stepName, `Step '${stepName}': 'when' must be a non-empty string`));
                     }
                     else {
-                        validateConditionLeaf('when', rawWhen, stepName, dependsOn, errors, withStepLine);
+                        validateConditionLeaf('when', rawWhen, stepName, dependsOn, stepKind, errors, withStepLine);
                     }
                 }
                 else if (Array.isArray(rawWhen)) {
@@ -1477,7 +1596,7 @@ function parseWorkflowString(content, registry, opts) {
                                 errors.push(withStepLine(stepName, `Step '${stepName}': 'when' array entries must be non-empty strings`));
                             }
                             else {
-                                validateConditionLeaf('when', leaf, stepName, dependsOn, errors, withStepLine);
+                                validateConditionLeaf('when', leaf, stepName, dependsOn, stepKind, errors, withStepLine);
                             }
                         }
                     }
@@ -1496,7 +1615,7 @@ function parseWorkflowString(content, registry, opts) {
                         errors.push(withStepLine(stepName, `Step '${stepName}': 'abort_unless' must be a non-empty string`));
                     }
                     else {
-                        validateConditionLeaf('abort_unless', rawAbort, stepName, dependsOn, errors, withStepLine);
+                        validateConditionLeaf('abort_unless', rawAbort, stepName, dependsOn, stepKind, errors, withStepLine);
                     }
                 }
                 else if (Array.isArray(rawAbort)) {
@@ -1509,7 +1628,7 @@ function parseWorkflowString(content, registry, opts) {
                                 errors.push(withStepLine(stepName, `Step '${stepName}': 'abort_unless' array entries must be non-empty strings`));
                             }
                             else {
-                                validateConditionLeaf('abort_unless', leaf, stepName, dependsOn, errors, withStepLine);
+                                validateConditionLeaf('abort_unless', leaf, stepName, dependsOn, stepKind, errors, withStepLine);
                             }
                         }
                     }
@@ -1532,7 +1651,7 @@ function parseWorkflowString(content, registry, opts) {
                             errors.push(withStepLine(stepName, `Step '${stepName}': 'preconditions' entries must be non-empty strings`));
                         }
                         else {
-                            validateConditionLeaf('preconditions', leaf, stepName, dependsOn, errors, withStepLine);
+                            validateConditionLeaf('preconditions', leaf, stepName, dependsOn, stepKind, errors, withStepLine);
                         }
                     }
                 }
@@ -1578,9 +1697,9 @@ function parseWorkflowString(content, registry, opts) {
                     // guard arm's consequence below is forked — collapsing it back into one shared string
                     // would make the error claim a wedge that cannot happen.
                     //
-                    // Post-#369 a guard declaring `preconditions` is REFUSED outright by the guard block
-                    // above, so this arm now only ever fires ALONGSIDE that refusal: errors accumulate rather
-                    // than short-circuit, and the guard block runs first, so both messages reach the author
+                    // Post-#369 a guard declaring `preconditions` is REFUSED outright — since #517, by
+                    // the registry mint near the top of Step 3 — so this arm now only ever fires ALONGSIDE
+                    // that refusal: errors accumulate rather than short-circuit, and the mint runs first, so both messages reach the author
                     // with the prohibition printed above this one. The arm is kept, not deleted — it is what
                     // stops the dead-condition message from claiming a wedge that a guard cannot have, and a
                     // definition reaching this code by any path other than a fresh YAML load (a
@@ -1656,9 +1775,14 @@ function parseWorkflowString(content, registry, opts) {
                     }
                 }
             }
-            // Validate tools: only valid on execution: agent steps without handler.
+            // Validate tools × handler (the COMPOUND half of the old tools rule — #517 split it: the
+            // non-agent kinds are minted from the registry above; this hand-written check keeps ONLY
+            // the agent-with-handler arm, whose predicate is a companion conflict, not a kind rule).
+            // Populations are disjoint by construction (this fires only on execution: 'agent'; the
+            // mint only on non-agent kinds), so the old multi-fire cannot re-appear.
             if (step['tools'] !== undefined &&
-                (step['execution'] !== 'agent' || step['handler'] !== undefined)) {
+                step['execution'] === 'agent' &&
+                step['handler'] !== undefined) {
                 errors.push(withStepLine(stepName, `Step '${stepName}': 'tools' is only valid on execution: agent steps without 'handler' defined`));
             }
             // issue #413: `tool_timeout` requires `tools`. It bounds ONE tool call inside the agentic
@@ -1741,12 +1865,11 @@ function parseWorkflowString(content, registry, opts) {
                 errors.push(withStepLine(stepName, `Step '${stepName}': 'tool_timeout' must be a positive integer`));
             }
             // Validate timeout_seconds: must be a positive integer (issue A3). Skipped on
-            // execution: guard — the guard-prohibited-fields check above already flatly rejects
-            // 'timeout_seconds' there ('is not valid on execution: guard steps'); re-checking its
-            // shape here would double-report the same root cause under a second, confusing message.
-            // Same suppression for the agent prohibition (issue #402), for the same reason: an author
-            // told BOTH that the key is invalid here and that its value has the wrong shape is being
-            // pointed at the shape, which is not the problem.
+            // execution: guard and agent — the #517 registry mint already flatly rejects
+            // 'timeout_seconds' on both kinds; re-checking its shape here would double-report the
+            // same root cause under a second, confusing message (an author told BOTH that the key is
+            // invalid here and that its value has the wrong shape is being pointed at the shape,
+            // which is not the problem).
             if (step['timeout_seconds'] !== undefined &&
                 step['execution'] !== 'guard' &&
                 step['execution'] !== 'agent' &&
@@ -1864,6 +1987,37 @@ function parseWorkflowString(content, registry, opts) {
             normalizeTriggerFilter(triggerRaw); // canonicalise shorthand BEFORE validation
             errors.push(...validateTriggerStructure(triggerRaw));
         }
+        // Step 3c: workflow-level context blocks (issue #553). These four rules need nothing but the
+        // text, so they belong to every surface — file, string, `validate --registered`, the public
+        // `loadWorkflowFromString`. They lived in the file loader until #553 and were therefore
+        // invisible to `validate` (which parsed extension-free workflows from string) and to
+        // `--registered`; the public string loader silently accepted all four shapes. Pushed, never
+        // thrown: the accumulator mints `Invalid workflow:` once and the #425 per-line grammar composes.
+        const contextWrapperRaw = doc['context_wrapper'];
+        if (contextWrapperRaw !== undefined) {
+            const VALID_WRAPPER_FORMATS = new Set(['xml', 'brackets', 'none']);
+            if (!VALID_WRAPPER_FORMATS.has(contextWrapperRaw)) {
+                errors.push(withTopLevelLine(['context_wrapper'], `'context_wrapper' must be 'xml', 'brackets', or 'none' (found: '${String(contextWrapperRaw)}')`));
+            }
+        }
+        const workflowContextRaw = doc['workflow_context'];
+        if (workflowContextRaw !== undefined) {
+            for (const [name, entry] of Object.entries(workflowContextRaw)) {
+                if (name.endsWith('.raw')) {
+                    errors.push(withTopLevelLine(['workflow_context', name], `workflow_context entry '${name}' must not end with '.raw'`));
+                }
+                if (!/^[\w.]+$/.test(name)) {
+                    errors.push(withTopLevelLine(['workflow_context', name], `workflow_context entry '${name}' must match [\\w.]+ (underscores and dots only — no hyphens)`));
+                }
+                const rawEntry = entry;
+                const rawSource = rawEntry?.['source'];
+                if (rawSource === undefined || typeof rawSource['path'] !== 'string') {
+                    // The ENTRY's line: the missing key has no line, and a cite must never name an absent
+                    // key.
+                    errors.push(withTopLevelLine(['workflow_context', name], `workflow_context.${name}.source.path is required`));
+                }
+            }
+        }
         if (errors.length > 0) {
             throw new WorkflowError(`Invalid workflow: ${errors.join('; ')}`, {
                 // issue #425: the pre-join strings — see the profile collector above.