diff --git a/‎.changeset/22161-lint-slice-10-one-line.md‎
Lines changed: 22 additions & 0 deletions b/‎.changeset/22161-lint-slice-10-one-line.md‎
Lines changed: 22 additions & 0 deletions
diff --git a/‎packages/lint/src/lint-flow-credential-literals.test.ts‎
Lines changed: 119 additions & 7 deletions b/‎packages/lint/src/lint-flow-credential-literals.test.ts‎
Lines changed: 119 additions & 7 deletions
diff --git a/‎packages/lint/src/lint-flow-credential-literals.ts‎
Lines changed: 20 additions & 20 deletions b/‎packages/lint/src/lint-flow-credential-literals.ts‎
Lines changed: 20 additions & 20 deletions
@@ -0,0 +1,22 @@
+---
+"@objectstack/lint": patch
+---
+
+fix(lint): the flow-credential, AI skill, flow-filter-token, managed-object API method, organization-axis business-unit grant, retired permission residue, seed and semantic-role provenance findings print one verdict line, `os explain <rule-id>` carries their reasoning, and `field-no-consumers` stops listing every object that shares a field name
+
+Clause-②: no
+
+- **Shorter verdicts.** Each finding of these 10 rule ids now prints a `message` of one verdict sentence. Every finding the rules' own test suites fire is at most 194 characters, and the runtime publish gate's suite at most 181; before, the longest of each ran from 222 to 441 characters. The ids:
+  - flows: `flow-credential-literal` (a literal credential in an `http` node's headers or url query, or in a `connectorConfig.input`) and `flow-filter-token-unknown` (a `{NAME()}` filter token neither the flow template dialect nor the filter placeholders define);
+  - AI agents and skills: `ai-skill-surface-mismatch` and `ai-skill-tool-unresolved`;
+  - managed objects: `object/managed-api-method-unaffordable`;
+  - sharing rules: `org-axis-cross-org-bu-grant` (its sibling `org-axis-permission-inheritance` already printed one sentence of at most 174 characters and is unchanged);
+  - permission sets: `permission-retired-lifecycle-residue`;
+  - seed datasets: `seed-insert-mode-duplicates-on-replay` and `seed-value-outside-state-machine`;
+  - semantic roles: `semantic-role-field-unprovisioned`.
+
+  A verdict no longer repeats what the finding's `where` already names: the skill (`ai-skill-tool-unresolved` now opens on the tool), the managed object, the sharing rule's object and the semantic-role object. `flow-credential-literal` keeps a short route (`move it to a connector's \`auth.credentialRef\``, or `drop it` for a connector input) because `os lint` prints the fix only under `--fix`; the route by auth variant stays the fix line's. `seed-value-outside-state-machine` names the first three declared states, then `(and N more)`. `object/managed-api-method-unaffordable` no longer appends the spec's `describeManagedApiMethodConflicts` sentence; it names the refused verbs, the `managedBy` bucket and the affordances they need. The `fix` (the CLI's `fix:` line, the runtime issue's `hint`), every rule id, severity and `path`, and what each rule accepts or refuses are unchanged. A tool that matched the old message text should match on `rule` and `path` instead.
+- **`field-no-consumers`** names the first other object that declares a field of the same name and counts the rest (`a consumer of the same name on "showcase_account" (and 9 more) does not count`), where it listed every one. On `os validate` of the showcase app its longest finding drops from 341 characters to 199, and that 341-character one, which named ten objects, now prints 143. Its `inert` and `carrier-only` verdicts and its explanation are otherwise unchanged.
+- **`os explain <rule-id>` takes these 10 ids**, for example `os explain flow-credential-literal`. It prints the reasoning the verdicts no longer carry: which flow positions are served to every flow reader and where a credential belongs, by auth variant; how an agent's and a skill's surfaces must match, and why an unresolved skill name is skipped; how a skill's tool name resolves and when an action materialises as a tool; the two vocabularies a flow filter token resolves in, and why a miss stops the node; which affordance each write verb needs and what the registry does with a refused one; why business-unit trees stay inside one organization and which recipients may share a platform-global object; why the retired `allowRestore` / `allowPurge` default is accepted in silence and which channels miss it; why seeds must be safe to replay and which states a seeded value may name; and why an injected column on an external object is blank. The `rule:` line under each of these findings now ends with `` — `os explain <rule-id>` for … ``. The no-argument listing and its `--json` `rules` array list the 10 ids, and so does the unknown-id error's `Rules with an explanation:` line. `RULE_EXPLANATIONS` in `@objectstack/lint` gains the 10 entries.
+- **Where the new text prints.** On the CLI, all 11 ids: `os validate`, `os build` (and `os compile`, which `os dev` runs when it compiles at startup, and on each watch recompile under `--verbose`), `os lint` (as `where: message`) and the scaffold check `os init` runs print the new `message` on the text face, and `os validate --json` and `os build --json` carry it in their `errors` and author-time `issues`. `os verify` prints the error-severity ids' new text in its refusal list (`ai-skill-surface-mismatch`, `flow-filter-token-unknown`, `object/managed-api-method-unaffordable`, `org-axis-cross-org-bu-grant`) and counts the warnings without printing them. At the runtime publish gate (Studio, REST `/meta`, MCP): a `flow` write's `flow-filter-token-unknown` and an `object` write's `object/managed-api-method-unaffordable` change the 422 issue's `message` and the refusal log line under `OS_ALLOW_UNLINTED_METADATA_WRITES`; a `flow` write's `flow-credential-literal` and a `permission` write's `permission-retired-lifecycle-residue` change the 2xx `advisories` entry and the `[Protocol] authoring advisory` log line. Each issue's `hint` is unchanged.
+- **Never at the runtime gate:** `org-axis-cross-org-bu-grant`, the two seed ids, `semantic-role-field-unprovisioned` and `field-no-consumers` (CLI-only rules), and the two AI ids, whose rules run at that door only for a `flow` write, whose snapshot carries no agents or skills of their own.
@@ -27,10 +27,27 @@ import {
   authoringRulesFor,
   runAuthoringRules,
 } from './authoring-rules.js';
-import { FLOW_CREDENTIAL_LITERAL, lintFlowCredentialLiterals } from './lint-flow-credential-literals.js';
+import {
+  FLOW_CREDENTIAL_LITERAL,
+  lintFlowCredentialLiterals as lintFlowCredentialLiteralsUnrecorded,
+} from './lint-flow-credential-literals.js';
+import { explainRule } from './rule-explanations.js';
 import { runRuntimeAuthoringRules, runtimeAuthoringRulesFor } from './runtime-gate.js';
 import * as barrel from './index.js';
 
+// [#22161] Each finding is one verdict sentence; the reasoning it used to
+// carry is `os explain flow-credential-literal`. Every direct call below
+// records what it fired, and the last cases in this file hold each recorded
+// verdict to one line of at most 200 characters — every firing variant this
+// suite exercises, not a chosen few. Run the whole file: those cases read what
+// the cases above fired.
+const fired: Array<{ rule: string; message: string }> = [];
+const lintFlowCredentialLiterals: typeof lintFlowCredentialLiteralsUnrecorded = (...args) => {
+  const findings = lintFlowCredentialLiteralsUnrecorded(...args);
+  fired.push(...findings);
+  return findings;
+};
+
 /** The probe sentinels. Each names the position it stands in. */
 const S = {
   controlHeader1: 'control-header-literal-1',
@@ -201,21 +218,23 @@ describe('flow-credential-literal — the pin set', () => {
     expect(header.where).toBe("flow 'scan_control' · node 'h' (http)");
     expect(header.message).toContain("header 'X-Api-Key'");
     expect(header.message).toContain('every member who can read flows');
-    // The route rides the MESSAGE: the CLI text faces print `where: message`
-    // and leave the hint to `--json`.
+    // [#22161] A short route rides the MESSAGE: `os lint`'s text face prints
+    // the hint only under `--fix`. The route by auth variant is the hint's
+    // (the `fix:` line `os validate` and `os build` print).
+    expect(header.message).toContain("move it to a connector's `auth.credentialRef`");
     // Routed by shape, to an auth variant the connector schema really has.
-    expect(header.message).toContain('`bearer` or `api-key` (a header), with `auth.credentialRef`');
+    expect(header.hint).toContain("type: 'bearer', credentialRef");
     expect(header.hint).toContain("type: 'api-key', headerName, credentialRef");
     expect(header.hint).toContain('connector_action');
 
     const url = byPath.get('flows[2].nodes[1].config.url')!;
     expect(url.message).toContain("query parameter 'api_key'");
-    expect(url.message).toContain('`api-key` with `paramName`');
+    expect(url.message).toContain("move it to a connector's `auth.credentialRef`");
     expect(url.hint).toContain("type: 'api-key', paramName, credentialRef");
 
     const input = byPath.get('flows[2].nodes[3].connectorConfig.input.auth.clientSecret')!;
     expect(input.message).toContain("connector input 'auth.clientSecret'");
-    expect(input.message).toContain('authenticates through its own `auth.credentialRef`');
+    expect(input.message).toContain('the connector authenticates through `auth.credentialRef`');
     expect(input.hint).toContain('credentialRef');
 
     const nested = byPath.get('flows[2].nodes[2].config.try.nodes[0].config.headers.Authorization')!;
@@ -358,7 +377,100 @@ describe('flow-credential-literal — registered once, at every door, as an advi
 
   it('exports the rule and its id from the package entry', () => {
     const b = barrel as Record<string, unknown>;
-    expect(b.lintFlowCredentialLiterals).toBe(lintFlowCredentialLiterals);
+    expect(b.lintFlowCredentialLiterals).toBe(lintFlowCredentialLiteralsUnrecorded);
     expect(b.FLOW_CREDENTIAL_LITERAL).toBe(FLOW_CREDENTIAL_LITERAL);
   });
 });
+
+describe('[#22161] one-line verdicts — flow-credential-literal', () => {
+  it('reads as one sentence per position, the short route included', () => {
+    const byPath = new Map(lintFlowCredentialLiterals(controlStack()).map((f) => [f.path, f.message]));
+    expect(byPath.get('flows[0].nodes[0].config.headers["X-Api-Key"]')).toBe(
+      "header 'X-Api-Key' holds a credential-shaped literal, readable by every member who can read flows; "
+        + "move it to a connector's `auth.credentialRef`",
+    );
+    expect(byPath.get('flows[2].nodes[1].config.url')).toBe(
+      "url query parameter 'api_key' holds a credential-shaped literal, readable by every member who can read "
+        + "flows; move it to a connector's `auth.credentialRef`",
+    );
+    expect(byPath.get('flows[2].nodes[3].connectorConfig.input.auth.clientSecret')).toBe(
+      "connector input 'auth.clientSecret' holds a credential-shaped literal, readable by every member who can "
+        + 'read flows; drop it: the connector authenticates through `auth.credentialRef`',
+    );
+  });
+
+  it('`os explain` carries what the verdict no longer says', () => {
+    const entry = explainRule(FLOW_CREDENTIAL_LITERAL);
+    expect(entry, 'no `os explain flow-credential-literal` entry').toBeDefined();
+    const text = entry!.paragraphs.join('\n');
+    for (const fact of [
+      'served, as authored, to every member who can read flows',
+      'cannot withhold a value here',
+      'ADR-0097 §3',
+      '`bearer` or a header `api-key`',
+      '`api-key` with `paramName`',
+      'No variant carries a secret in a url path',
+      'a heuristic',
+      'A `{variable}` template is not a literal',
+      'never the value itself',
+    ]) {
+      expect(text, `explanation names ${fact}`).toContain(fact);
+    }
+  });
+
+  it('each position and each region kind the explanation names fires', () => {
+    // The explanation module imports nothing, so its positions are held to the
+    // rule by running the rule: one probe per position, top level and inside
+    // each region kind it names.
+    const text = explainRule(FLOW_CREDENTIAL_LITERAL)!.paragraphs.join('\n');
+    for (const named of ['`config.headers`', '`config.url`', '`connectorConfig.input`', '`try_catch`', '`loop`', '`parallel`']) {
+      expect(text, named).toContain(named);
+    }
+    const call = (id: string) => ({
+      id,
+      type: 'http',
+      config: { url: 'https://x.invalid/p?api_key=probe-url-sentinel', headers: { Authorization: 'Bearer probe-sentinel' } },
+    });
+    const stack = {
+      flows: [
+        {
+          name: 'regions',
+          nodes: [
+            { id: 'loop', type: 'loop', config: { collection: '{items}', body: { nodes: [call('in_loop')], edges: [] } } },
+            {
+              id: 'par',
+              type: 'parallel',
+              config: { branches: [{ nodes: [call('in_branch')], edges: [] }] },
+            },
+            {
+              id: 'conn',
+              type: 'connector_action',
+              connectorConfig: { connectorId: 'rest', actionId: 'request', input: { token: 'probe-input-sentinel' } },
+            },
+          ],
+          edges: [],
+        },
+      ],
+    };
+    const paths = lintFlowCredentialLiterals(stack).map((f) => f.path);
+    expect(paths).toEqual([
+      'flows[0].nodes[0].config.body.nodes[0].config.headers.Authorization',
+      'flows[0].nodes[0].config.body.nodes[0].config.url',
+      'flows[0].nodes[1].config.branches[0].nodes[0].config.headers.Authorization',
+      'flows[0].nodes[1].config.branches[0].nodes[0].config.url',
+      'flows[0].nodes[2].connectorConfig.input.token',
+    ]);
+  });
+
+  it('every verdict the cases in this file fired is one line of at most 200 characters', () => {
+    const converted = fired.filter((f) => f.rule === FLOW_CREDENTIAL_LITERAL);
+    // The coverage control first: all three positions fired.
+    for (const opening of ['header ', 'url query parameter ', 'connector input ']) {
+      expect(converted.some((f) => f.message.startsWith(opening)), opening).toBe(true);
+    }
+    for (const f of converted) {
+      expect(f.message, f.rule).not.toContain('\n');
+      expect(f.message.length, `${f.rule}: ${f.message}`).toBeLessThanOrEqual(200);
+    }
+  });
+});
@@ -68,30 +68,27 @@ export interface FlowCredentialLiteralFinding {
   hint: string;
 }
 
-/** Why the value is exposed — the same sentence for all three positions. */
-const SERVED =
-  'A flow definition is served, as authored, to every member who can read flows, so this value is ' +
-  'readable by all of them';
+/**
+ * [#22161] Who can read the value — the one clause all three positions share.
+ * Why the read path cannot withhold it is `os explain flow-credential-literal`.
+ */
+const SERVED = 'readable by every member who can read flows';
 
 /**
- * The route, in the MESSAGE and not only in the hint: `os validate` and `os lint`
- * print `where: message` on their text faces and leave the hint to `--json`, so
- * a route stated only in the hint never reaches the author who reads the terminal.
+ * The route, short, in the VERDICT as well as in the hint: `os validate` and
+ * `os build` print the hint as their `fix:` line, but `os lint`'s text face
+ * prints it only under `--fix`, so a route stated only in the hint misses the
+ * author who runs `os lint`.
  *
- * Routed BY SHAPE, to a variant `ConnectorInstanceAuthSchema` really has
- * (`none` / `bearer` / `api-key` / `basic`): a header credential goes to
- * `bearer` or a header `api-key`, a query-string key to `api-key` with
+ * The hint carries the route BY SHAPE, to a variant `ConnectorInstanceAuthSchema`
+ * really has (`none` / `bearer` / `api-key` / `basic`): a header credential goes
+ * to `bearer` or a header `api-key`, a query-string key to `api-key` with
  * `paramName`. ⛔ No variant carries a secret in a url PATH, so no text here
  * may promise that `credentialRef` can hold one — an author cannot follow it.
  * (This rule does not judge url paths; it judges query parameters only.)
  */
-const STEER_HEADER =
-  "; move it to a declarative connector whose `auth` is `bearer` or `api-key` (a header), with " +
-  '`auth.credentialRef` naming the secret, called from a `connector_action` node.';
-const STEER_QUERY =
-  "; move it to a declarative connector whose `auth` is `api-key` with `paramName` (the query parameter), " +
-  'with `auth.credentialRef` naming the secret, called from a `connector_action` node.';
-const STEER_INPUT = "; drop it from `input` — the connector authenticates through its own `auth.credentialRef`.";
+const STEER_CONNECTOR = "move it to a connector's `auth.credentialRef`";
+const STEER_INPUT = 'drop it: the connector authenticates through `auth.credentialRef`';
 
 /** Where `credentialRef` resolves — stated once, in every hint. */
 const RESOLVES =
@@ -172,7 +169,10 @@ export function lintFlowCredentialLiterals(stack: AnyRec): FlowCredentialLiteral
           rule: FLOW_CREDENTIAL_LITERAL,
           where,
           path: entryPath,
-          message: `${what} holds a literal value that reads as a credential. ${SERVED}${steer}`,
+          // [#22161] One verdict sentence; the three positions, the route by
+          // auth variant and why it only warns are
+          // `os explain flow-credential-literal`.
+          message: `${what} holds a credential-shaped literal, ${SERVED}; ${steer}`,
           hint: `${route}${NOT_A_GATE}`,
         });
       };
@@ -182,13 +182,13 @@ export function lintFlowCredentialLiterals(stack: AnyRec): FlowCredentialLiteral
         if (isRec(headers)) {
           for (const [name, value] of Object.entries(headers)) {
             if (!isCredentialShapedLiteral(name, value)) continue;
-            report(`${path}.config.headers${keySegment(name)}`, `header '${name}'`, STEER_HEADER, HEADER_ROUTE);
+            report(`${path}.config.headers${keySegment(name)}`, `header '${name}'`, STEER_CONNECTOR, HEADER_ROUTE);
           }
         }
         if (typeof url === 'string') {
           for (const [name, value] of queryParameters(url)) {
             if (!isCredentialShapedLiteral(name, value)) continue;
-            report(`${path}.config.url`, `the url's query parameter '${name}'`, STEER_QUERY, QUERY_ROUTE);
+            report(`${path}.config.url`, `url query parameter '${name}'`, STEER_CONNECTOR, QUERY_ROUTE);
           }
         }
       }