@@ -0,0 +1,24 @@
+---
+'@objectstack/lint': minor
+---
+
+`os validate` refuses an `api` flow with no per-flow secret, the flow the automation engine already refuses to register (#20553).
+
+Clause-②: yes (accept/reject: `os validate` newly refuses a secretless `api` flow)
+
+`validate-flow-trigger-readiness` gains one rule id, `flow-api-trigger-secret-missing`, at `error`. It names a flow whose binding resolves to the inbound `api` trigger when that flow's start node carries no usable `config.secret`. A usable secret is a string that is non-empty after trimming. The rule fires for a missing, blank or non-string secret, and for an `api` flow with no start node.
+
+**Why.** ADR-0041's `trigger-api` acceptance criteria require a per-flow secret with HMAC verification. In the same release, the automation engine refuses such a flow in `registerFlow`, whatever its `status`: the `/automation` write doors answer `400`, and a boot skips the flow with a warning. `ApiTrigger.start()` also refuses to arm it. `os validate` builds neither, so it answered `✓ Validation passed` for a flow no runtime would register. It now exits non-zero and names the flow.
+
+**Which flows count as `api`-bound.** The rule uses the engine's own binding, `deriveTriggerBinding`. An array-form record `triggerType` goes to the record-change trigger first. Otherwise the flow gets the kind `resolveFlowTriggerKind` answers, which is a flow declaring `type: 'api'` or a start-node `triggerType: 'api'`. The engine gives the record-change, time-relative and schedule triggers precedence over `api`. So a `type: 'api'` flow whose start node also carries a `record-*` token, a `timeRelative` descriptor or a `config.schedule` binds that other trigger. The engine never asks that flow for a secret, and the rule stays silent on it.
+
+**Where the refusal surfaces.** The rule is `CLI_AND_RUNTIME`, so it gates in two places:
+
+- `os validate`, `os build` and `os lint`.
+- The runtime metadata publish gate. A `state: 'active'` write of a secretless `api` flow now carries this `error`, so the gate refuses it before the flow is stored. Before this change the gate passed that write.
+
+The gate judges only the item being written, so existing stored flows are not re-judged.
+
+**Fix.** Set a non-blank `config.secret` on the flow's start node, and sign each post with it in the `x-objectstack-signature` header. A flow that is only ever started explicitly and never receives inbound posts is `type: 'autolaunched'`, with no `triggerType: 'api'` on its start node, and it needs no secret.
+
+`FLOW_API_TRIGGER_SECRET_MISSING` is exported from `@objectstack/lint`.
@@ -1107,7 +1107,9 @@ export const AUTHORING_RULES: readonly AuthoringRule[] = [
   // predicate cannot route at all, a `record-*` triggerType outside the
   // closed token grammar `triggerTypeToHookEvents` maps, and (#6637) a
   // `type: 'record_change'` flow whose triggerType the engine's binding resolver
-  // routes nowhere, silently demoting it to a manual flow. None of those verdicts
+  // routes nowhere, silently demoting it to a manual flow. #20553 made it five: an
+  // `api`-bound flow with no usable `config.secret`, which the engine's own
+  // `registerFlow` refuses (ADR-0041). None of those verdicts
   // can be changed by installing a package, so there is no reading under which
   // the flow fires. `flow-trigger-unknown-object` deliberately stayed `warning`
   // (the object may come from another installed package — a hedge this rule
 
@@ -132,6 +132,7 @@ export {
   FLOW_TIME_RELATIVE_DESCRIPTOR_INVALID,
   FLOW_TIME_RELATIVE_DESCRIPTOR_UNROUTABLE,
   FLOW_TRIGGER_UNROUTABLE,
+  FLOW_API_TRIGGER_SECRET_MISSING,
 } from './validate-flow-trigger-readiness.js';
 export type {
   FlowTriggerReadinessFinding,
 
@@ -10,6 +10,7 @@ import {
   FLOW_TIME_RELATIVE_DESCRIPTOR_INVALID,
   FLOW_TIME_RELATIVE_DESCRIPTOR_UNROUTABLE,
   FLOW_TRIGGER_UNROUTABLE,
+  FLOW_API_TRIGGER_SECRET_MISSING,
 } from './validate-flow-trigger-readiness.js';
 
 function recordFlow(overrides: Record<string, unknown> = {}) {
@@ -1008,6 +1009,143 @@ describe('validateFlowTriggerReadiness', () => {
     });
   });
 
+  // ── #20553 — an `api`-bound flow with no usable secret (ADR-0041) ─────────
+  //
+  // The engine refuses such a flow in `registerFlow`; `os validate` builds no
+  // engine, so this rule is the only thing at authoring time that says so. The
+  // cases pin the three things the rule has to get right, each against the
+  // engine's MEASURED answer rather than a reading of `type`: which flows are
+  // `api`-bound, what counts as a usable secret, and that a flow the engine
+  // registers is never named.
+  describe('api trigger secret (ADR-0041)', () => {
+    function apiFlow(
+      config: Record<string, unknown>,
+      overrides: Record<string, unknown> = {},
+    ): Record<string, unknown> {
+      return {
+        name: 'inbound_order',
+        type: 'api',
+        status: 'active',
+        nodes: [
+          { id: 'start', type: 'start', config },
+          { id: 'end', type: 'end' },
+        ],
+        edges: [{ id: 'e1', source: 'start', target: 'end' }],
+        ...overrides,
+      };
+    }
+    const judge = (flow: Record<string, unknown>) =>
+      validateFlowTriggerReadiness({ objects: [candidateObject], flows: [flow] });
+
+    it('fails a secretless `type: api` flow, naming the flow and the key', () => {
+      const findings = judge(apiFlow({ hookId: 'intake' }));
+      // Exhaustive: the flow is active and otherwise well-formed, so this id is
+      // the ONLY thing wrong with it.
+      expect(findings.map((f) => f.rule)).toEqual([FLOW_API_TRIGGER_SECRET_MISSING]);
+      const [f] = findings;
+      expect(f.severity).toBe('error');
+      expect(f.where).toBe('flow "inbound_order" › start node');
+      expect(f.path).toBe('flows[0].nodes[0].config.secret');
+      expect(f.message).toContain(`type: 'api'`);
+      expect(f.message).toContain('config.secret');
+    });
+
+    it('passes the same flow once it carries a secret', () => {
+      expect(judge(apiFlow({ hookId: 'intake', secret: 'whsec_4f9a' }))).toEqual([]);
+    });
+
+    it('passes an `autolaunched` flow — the explicit-only form needs no secret', () => {
+      expect(judge(apiFlow({}, { type: 'autolaunched' }))).toEqual([]);
+      // …and the same flow flipped to `api` with nothing else changed fails.
+      expect(judge(apiFlow({}, { type: 'api' })).map((f) => f.rule)).toEqual([
+        FLOW_API_TRIGGER_SECRET_MISSING,
+      ]);
+    });
+
+    it('judges a start-node `triggerType: api` on any other flow type exactly like `type: api`', () => {
+      for (const type of ['autolaunched', 'screen', 'record_change']) {
+        const secretless = judge(apiFlow({ triggerType: 'api' }, { type }));
+        expect(secretless.map((f) => f.rule), type).toEqual([FLOW_API_TRIGGER_SECRET_MISSING]);
+        expect(secretless[0].path, type).toBe('flows[0].nodes[0].config.secret');
+        expect(secretless[0].message, type).toContain(`start-node triggerType: 'api'`);
+        expect(secretless[0].message, type).not.toContain(`type: 'api' and`);
+        expect(judge(apiFlow({ triggerType: 'api', secret: 's3cret' }, { type })), type).toEqual([]);
+      }
+      // Both declarations at once: still one finding, naming both.
+      const both = judge(apiFlow({ triggerType: 'api' }));
+      expect(both.map((f) => f.rule)).toEqual([FLOW_API_TRIGGER_SECRET_MISSING]);
+      expect(both[0].message).toContain(`type: 'api' and start-node triggerType: 'api'`);
+    });
+
+    it('fails a blank secret, and every non-string one, without echoing the value', () => {
+      for (const secret of ['  ', '', '\t\n', 12345, true, null, ['s3cret'], { value: 's3cret' }]) {
+        const findings = judge(apiFlow({ secret }));
+        expect(findings.map((f) => f.rule), JSON.stringify(secret)).toEqual([FLOW_API_TRIGGER_SECRET_MISSING]);
+        // Only the TYPE is rendered — a finding travels into CI logs and
+        // publish-gate responses.
+        expect(findings[0].message, JSON.stringify(secret)).not.toContain('12345');
+        expect(findings[0].message, JSON.stringify(secret)).not.toContain('s3cret');
+      }
+      expect(judge(apiFlow({ secret: '  ' }))[0].message).toContain('blank');
+      expect(judge(apiFlow({ secret: 12345 }))[0].message).toContain('a number, not a string');
+      // The runtime trims before judging; a padded real secret is usable.
+      expect(judge(apiFlow({ secret: '  s3cret  ' }))).toEqual([]);
+    });
+
+    it('judges a disabled flow too — the engine refuses it whatever its status', () => {
+      for (const status of ['obsolete', 'draft']) {
+        expect(
+          judge(apiFlow({}, { status })).map((f) => f.rule),
+          status,
+        ).toContain(FLOW_API_TRIGGER_SECRET_MISSING);
+      }
+    });
+
+    it('judges a flow with no start node, located at `nodes`', () => {
+      const findings = judge({ name: 'no_start_api', type: 'api', status: 'active', nodes: [{ id: 'end', type: 'end' }] });
+      expect(findings.map((f) => f.rule)).toEqual([FLOW_API_TRIGGER_SECRET_MISSING]);
+      expect(findings[0].where).toBe('flow "no_start_api"');
+      expect(findings[0].path).toBe('flows[0].nodes');
+      expect(findings[0].message).toContain('no start node');
+    });
+
+    it('matches the engine where precedence binds another trigger — each paired with the shape that fires', () => {
+      // Measured against the BUILT `AutomationEngine.registerFlow` at
+      // f11b5f20a2: each of these registers with no secret, because
+      // `deriveTriggerBinding` binds the higher-precedence trigger and never
+      // asks for one. The `type === 'api' || triggerType === 'api'` disjunction
+      // would refuse all five.
+      const boundElsewhere: Array<[string, Record<string, unknown>]> = [
+        ['api + config.schedule', apiFlow({ schedule: { type: 'interval', intervalMs: 60000 } })],
+        ['api + record-* token', apiFlow({ objectName: 'app_candidate', triggerType: 'record-after-create' })],
+        ['api + array record token', apiFlow({ objectName: 'app_candidate', triggerType: ['record-after-create'] })],
+        [
+          'api + timeRelative descriptor',
+          apiFlow({ timeRelative: { object: 'app_candidate', dateField: 'due_at', withinDays: 3 } }),
+        ],
+        [
+          'schedule + triggerType api',
+          apiFlow({ triggerType: 'api', schedule: { type: 'interval', intervalMs: 60000 } }, { type: 'schedule' }),
+        ],
+      ];
+      for (const [label, flow] of boundElsewhere) {
+        expect(judge(flow).map((f) => f.rule), label).not.toContain(FLOW_API_TRIGGER_SECRET_MISSING);
+      }
+      // A SCALAR `timeRelative` is not routed to the sweep, so the flow falls
+      // through to `api` — measured REFUSED by the engine — and both facts are
+      // reported, at two paths.
+      const scalar = judge(apiFlow({ timeRelative: 'daily' })).map((f) => f.rule);
+      expect(scalar).toContain(FLOW_API_TRIGGER_SECRET_MISSING);
+      expect(scalar).toContain(FLOW_TIME_RELATIVE_DESCRIPTOR_UNROUTABLE);
+      // Remove the higher-precedence sibling and the same flow is refused again.
+      expect(judge(apiFlow({})).map((f) => f.rule)).toEqual([FLOW_API_TRIGGER_SECRET_MISSING]);
+    });
+
+    it('the id is the published slug', () => {
+      expect(FLOW_API_TRIGGER_SECRET_MISSING).toBe('flow-api-trigger-secret-missing');
+    });
+  });
+
   // ── #5762 — the family's severity map ────────────────────────────────────
   //
   // The rules in this file were reviewed as ONE family and split on a single
@@ -1109,6 +1247,21 @@ describe('validateFlowTriggerReadiness', () => {
           ],
         },
       ],
+      [
+        FLOW_API_TRIGGER_SECRET_MISSING,
+        'error',
+        {
+          objects: [candidateObject],
+          flows: [
+            {
+              name: 'unsigned_hook',
+              type: 'api',
+              status: 'active',
+              nodes: [{ id: 'start', type: 'start', config: { hookId: 'intake' } }],
+            },
+          ],
+        },
+      ],
       // ── The controls. Both are hedged, and the hedge is the whole reason the
       //    promotion above is not "everything in this file is an error now".
       [
@@ -1199,6 +1352,16 @@ describe('validateFlowTriggerReadiness', () => {
                 },
               ],
             },
+            // [#20553] A signed inbound flow is what a correct `api` flow looks
+            // like — the secret rule must not move this floor.
+            {
+              name: 'order_intake',
+              type: 'api',
+              status: 'active',
+              nodes: [
+                { id: 'start', type: 'start', config: { hookId: 'intake', secret: 'whsec_4f9a' } },
+              ],
+            },
           ],
         }),
       ).toEqual([]);