@suluk/agents 0.1.0

package/src/resolve.ts

@@ -0,0 +1,110 @@
+/**
+ * Resolution helpers for the agent layer (C027). These walk the document and the agent graph BY NAME (C009/C013)
+ * — they NEVER touch the DOM→ADA request→operation matcher. A route's `operationRef` is a by-name JSON-pointer
+ * into an EXISTING operation; a sub-agent `ref` is a by-name pointer into the same `x-suluk-agents` map.
+ */
+import type { OpenAPIv4Document, Request, SulukAgent } from "@suluk/core";
+
+/** Unescape one JSON-Pointer token (RFC6901): `~1`→`/`, `~0`→`~`. */
+const unescapeToken = (t: string) => t.replace(/~1/g, "/").replace(/~0/g, "~");
+
+/** Parse a `#/a/b~1c/d` fragment pointer into its decoded tokens (or null if not a local fragment pointer). */
+export function parsePointer(ref: string): string[] | null {
+  if (typeof ref !== "string" || !ref.startsWith("#/")) return null;
+  return ref.slice(2).split("/").map(unescapeToken);
+}
+
+export type OperationLocus = "path" | "webhook" | "job";
+export interface ResolvedOperation {
+  locus: OperationLocus;
+  /** the container key (path template / webhook name / job name). */
+  container: string;
+  /** the by-name request handle within a pathItem (paths only). */
+  requestName?: string;
+  request?: Request;
+}
+
+/**
+ * Resolve a route's `operationRef` to an EXISTING operation. Supports the three operation loci:
+ *  - `#/paths/<pathTemplate>/requests/<name>`  (a pathItem request — the common case)
+ *  - `#/webhooks/<name>`                        (an incoming webhook operation)
+ *  - `#/x-suluk-jobs/<name>`                    (a non-HTTP job, C025)
+ * Returns null when the ref dangles (the resolve-lint failure — Conin's MCP-only `run_core_primitive`).
+ */
+export function resolveOperationRef(doc: OpenAPIv4Document, ref: string): ResolvedOperation | null {
+  const toks = parsePointer(ref);
+  if (!toks) return null;
+  if (toks[0] === "paths" && toks.length === 4 && toks[2] === "requests") {
+    const pathItem = doc.paths?.[toks[1]];
+    const request = pathItem?.requests?.[toks[3]] as Request | undefined;
+    return request ? { locus: "path", container: toks[1], requestName: toks[3], request } : null;
+  }
+  if (toks[0] === "webhooks" && toks.length === 2) {
+    const request = doc.webhooks?.[toks[1]];
+    return request ? { locus: "webhook", container: toks[1], request } : null;
+  }
+  if (toks[0] === "x-suluk-jobs" && toks.length === 2) {
+    const job = doc["x-suluk-jobs"]?.[toks[1]];
+    return job ? { locus: "job", container: toks[1] } : null;
+  }
+  return null;
+}
+
+/** The agent map, or an empty record. */
+export const agentMap = (doc: OpenAPIv4Document): Record<string, SulukAgent> => doc["x-suluk-agents"] ?? {};
+
+/** Decode a sub-agent ref `#/x-suluk-agents/<key>` to its key (or null if malformed / not an agent ref). */
+export function subAgentKey(ref: string): string | null {
+  const toks = parsePointer(ref);
+  return toks && toks.length === 2 && toks[0] === "x-suluk-agents" ? toks[1] : null;
+}
+
+/** Direct sub-agent keys of an agent (decoded; may include dangling keys — the caller lint-checks existence). */
+export function childKeys(agent: SulukAgent): { local: string; key: string | null; ref: string }[] {
+  return Object.entries(agent.agents ?? {}).map(([local, r]) => ({ local, key: subAgentKey(r.ref), ref: r.ref }));
+}
+
+/**
+ * Detect a cycle in the agent graph reachable from `root`, following by-name sub-agent refs. Returns the cycle
+ * path (keys) if one exists, else null. JSON-Schema cannot express acyclicity — this is the author/install lint
+ * the C027 gate requires. (Same shape as the shipped builder/compose cycle detection, C021.)
+ */
+export function findCycle(map: Record<string, SulukAgent>, root: string): string[] | null {
+  const onStack: string[] = [];
+  const inStack = new Set<string>();
+  const done = new Set<string>();
+  const dfs = (key: string): string[] | null => {
+    if (inStack.has(key)) return [...onStack.slice(onStack.indexOf(key)), key]; // back-edge → cycle
+    if (done.has(key) || !map[key]) return null;
+    onStack.push(key); inStack.add(key);
+    for (const c of childKeys(map[key])) {
+      if (c.key && map[c.key]) { const hit = dfs(c.key); if (hit) return hit; }
+    }
+    onStack.pop(); inStack.delete(key); done.add(key);
+    return null;
+  };
+  return dfs(root);
+}
+
+/**
+ * Longest sub-agent path depth below `root` (a leaf — no sub-agents — is depth 0). Returns Infinity if a cycle is
+ * reachable. `maxDepth` on an agent must be >= this for its subtree.
+ */
+export function subtreeDepth(map: Record<string, SulukAgent>, root: string, seen = new Set<string>()): number {
+  if (seen.has(root)) return Infinity;
+  const agent = map[root];
+  if (!agent) return 0;
+  const children = childKeys(agent).filter((c) => c.key && map[c.key!]);
+  if (children.length === 0) return 0;
+  seen.add(root);
+  let max = 0;
+  for (const c of children) max = Math.max(max, 1 + subtreeDepth(map, c.key!, new Set(seen)));
+  return max;
+}
+
+/** Every string value reachable in an object (for the request-value-selector D1 scan). */
+export function* deepStrings(v: unknown, path = ""): Generator<{ path: string; value: string }> {
+  if (typeof v === "string") { yield { path, value: v }; return; }
+  if (Array.isArray(v)) { for (let i = 0; i < v.length; i++) yield* deepStrings(v[i], `${path}[${i}]`); return; }
+  if (v && typeof v === "object") for (const [k, val] of Object.entries(v)) yield* deepStrings(val, path ? `${path}.${k}` : k);
+}

package/src/scope.ts

@@ -0,0 +1,78 @@
+/**
+ * Scope analysis (C027 security red-line) — least-privilege by construction. A child agent's EFFECTIVE scope is the
+ * INTERSECTION of its declared scope and its caller's, NEVER the union: scope cannot ESCALATE across a parent→child
+ * hop. This makes the confused-deputy structurally impossible (a child can't reach a tool its caller-chain doesn't
+ * grant), and the FULL reachable authz surface is computable from the document with zero requests. `null` = an
+ * unconstrained scope (no `scope` declared) — it inherits the caller's; intersection with `null` is the other set.
+ */
+import type { OpenAPIv4Document } from "@suluk/core";
+import { agentMap, childKeys } from "./resolve";
+
+export type Scope = string[] | null;
+
+/** INTERSECTION with null-as-unconstrained: ∩(null, X)=X, ∩(X, null)=X, ∩(X, Y)=X∩Y. */
+export const intersectScope = (a: Scope, b: Scope): Scope =>
+  a === null ? b : b === null ? a : a.filter((x) => b.includes(x));
+
+export interface ScopeEscalation {
+  /** the agent whose declared grant is exceeded by a child. */
+  parent: string;
+  /** the local handle of the offending sub-agent. */
+  childLocal: string;
+  /** the resolved child agent key. */
+  child: string;
+  /** the permissions the child declares that the parent does NOT grant (silently dropped under intersection). */
+  perms: string[];
+}
+
+/**
+ * Walk the agent tree from `root`, computing each reachable node's effective (intersected) scope and every per-edge
+ * escalation. Cycle-guarded (lint rejects cycles independently); on a DAG/tree each node's effective is its first
+ * reaching path's intersection — sufficient for the shallow agent graphs C027 ships.
+ */
+export function analyzeScopes(doc: OpenAPIv4Document, root: string): { effective: Record<string, Scope>; escalations: ScopeEscalation[] } {
+  const map = agentMap(doc);
+  const effective: Record<string, Scope> = {};
+  const escalations: ScopeEscalation[] = [];
+  const seen = new Set<string>();
+
+  const walk = (key: string, callerEff: Scope) => {
+    const agent = map[key];
+    if (!agent || seen.has(key)) return;
+    seen.add(key);
+    const declared: Scope = agent.scope ?? null;
+    const myEff = intersectScope(declared, callerEff);
+    effective[key] = myEff;
+    for (const c of childKeys(agent)) {
+      if (!c.key || !map[c.key]) continue;
+      const childDeclared: Scope = map[c.key].scope ?? null;
+      if (childDeclared !== null && myEff !== null) {
+        const over = childDeclared.filter((p) => !myEff.includes(p));
+        if (over.length) escalations.push({ parent: key, childLocal: c.local, child: c.key, perms: over });
+      }
+      walk(c.key, myEff);
+    }
+  };
+  walk(root, null);
+  return { effective, escalations };
+}
+
+/**
+ * A LOCAL author-time escalation check for one agent's direct children: a child may not DECLARE a permission its
+ * immediate parent does not grant (under intersection it would be silently dropped — flag the author's confusion /
+ * a confused-deputy attempt). Used by the linter; the transitive picture is {@link analyzeScopes}.
+ */
+export function localEscalations(doc: OpenAPIv4Document, agentName: string): ScopeEscalation[] {
+  const map = agentMap(doc);
+  const parent = map[agentName];
+  if (!parent || parent.scope === undefined) return []; // unconstrained parent grants everything → no escalation
+  const grant = parent.scope;
+  const out: ScopeEscalation[] = [];
+  for (const c of childKeys(parent)) {
+    const child = c.key ? map[c.key] : undefined;
+    if (!child || !child.scope) continue;
+    const over = child.scope.filter((p) => !grant.includes(p));
+    if (over.length) out.push({ parent: agentName, childLocal: c.local, child: c.key!, perms: over });
+  }
+  return out;
+}

package/src/skill.ts

@@ -0,0 +1,39 @@
+/**
+ * SKILL.md generation + the STALENESS STAMP — the single highest-value, lowest-risk feature the council flagged as
+ * genuinely missing today (conin's build-skill.ts has no hash). The skill's instruction TEXT is never the source of
+ * truth: a served endpoint is, and SKILL.md is GENERATED from a `contentHash`-pinned snapshot of it. The stamp
+ * binds the artifact to that snapshot so drift (the served preprompt changing after a signature/mint) is
+ * tool-detectable. Pure: the instructions snapshot is an INPUT — no fetch at generate time.
+ */
+import { createHash } from "node:crypto";
+
+/** A short, stable content hash of an instructions snapshot. */
+export function contentHash(instructions: string): string {
+  return "sha256-" + createHash("sha256").update(instructions, "utf8").digest("hex").slice(0, 16);
+}
+
+export interface SkillRenderInput {
+  name: string;
+  description: string;
+  /** the instruction snapshot (the served /v1/instructions content, pinned at generate time). */
+  instructions: string;
+  /** the URL the snapshot was taken from (recorded in the stamp; not fetched here). */
+  source?: string;
+  version?: string;
+}
+
+/**
+ * Render a Claude SKILL.md: YAML frontmatter (name + description) + a GENERATED stamp carrying source, the
+ * computed contentHash, and version — then the instructions body verbatim. Deterministic in its inputs.
+ */
+export function renderSkillMd(input: SkillRenderInput): string {
+  const hash = contentHash(input.instructions);
+  const stamp = [
+    "<!-- GENERATED by @suluk/agents — DO NOT EDIT BY HAND. Re-run on release.",
+    `     source: ${input.source ?? "(inline)"}`,
+    `     contentHash: ${hash}`,
+    `     version: ${input.version ?? "(unversioned)"} -->`,
+  ].join("\n");
+  const desc = input.description.replace(/"/g, '\\"');
+  return `---\nname: ${input.name}\ndescription: "${desc}"\n---\n\n${stamp}\n\n${input.instructions}\n`;
+}

package/test/conformance.test.ts

@@ -0,0 +1,34 @@
+import { test, expect, describe } from "bun:test";
+import { reachableSurface, assertServedSubset, verifySkillFreshness, contentHash } from "../src/index";
+import { coninDoc, coninInstructions } from "./fixtures/conin";
+
+describe("C027 conformance — static reachable surface + over-serve auditor", () => {
+  test("the full reachable tool surface is statically enumerable (zero requests)", () => {
+    const s = reachableSurface(coninDoc, "conin");
+    expect(s.tools).toEqual(["find_comparables", "generate_deliverable", "run_core_primitive", "search_library"]);
+    expect(s.agents).toEqual(["coninRetrieval"]);
+  });
+
+  test("a served set equal to the surface is conformant", () => {
+    expect(assertServedSubset(coninDoc, "conin", ["generate_deliverable", "run_core_primitive", "search_library", "find_comparables"])).toEqual([]);
+  });
+
+  test("NAMED failure: a server that WIDENS the surface (Conin's full-catalog over-serve) is flagged", () => {
+    const findings = assertServedSubset(coninDoc, "conin", ["generate_deliverable", "list_everything", "audit_boq_raw"]);
+    expect(findings.map((f) => f.code)).toEqual(["over-serve", "over-serve"]);
+    expect(findings[0].detail).toContain("list_everything");
+  });
+});
+
+describe("C027 conformance — skill freshness (drift detection)", () => {
+  const snap = coninInstructions.operate;
+  test("a matching declared hash is fresh", () => {
+    expect(verifySkillFreshness(contentHash(snap), snap)).toEqual([]);
+  });
+  test("a drifted served snapshot is caught as stale", () => {
+    expect(verifySkillFreshness("sha256-0000000000000000", snap).map((f) => f.code)).toEqual(["stale-skill"]);
+  });
+  test("an unpinned skill (no declared hash) is flagged — drift would be invisible", () => {
+    expect(verifySkillFreshness(undefined, snap).map((f) => f.code)).toEqual(["unpinned-skill"]);
+  });
+});

package/test/context.test.ts

@@ -0,0 +1,167 @@
+import { test, expect, describe } from "bun:test";
+import type { OpenAPIv4Document } from "@suluk/core";
+import { contextReport, suggestUnflatten, SEED_CATALOG } from "../src/index";
+
+/** An agent with one resident route (with a schema), one cold-tail route, and a resident skill. */
+function doc1(opts: { budget?: number } = {}): OpenAPIv4Document {
+  return {
+    openapi: "4.0.0-candidate",
+    info: { title: "x", version: "0" },
+    paths: {
+      "v1/a": { requests: { opA: { method: "post", responses: { ok: { status: 200 } }, contentSchema: { type: "object", properties: { foo: { type: "string" }, bar: { type: "number" } } } } } },
+      "v1/b": { requests: { opB: { method: "get", responses: { ok: { status: 200 } } } } },
+    },
+    "x-suluk-agents": {
+      one: {
+        description: "agent one",
+        ...(opts.budget !== undefined ? { contextBudget: { tokens: opts.budget, basis: "estimate" } } : {}),
+        skills: { guide: { model: ["anthropic/claude-opus-4"] } }, // resident skill (no tier)
+        routes: {
+          tool_a: { operationRef: "#/paths/v1~1a/requests/opA" },                    // resident
+          tool_b: { operationRef: "#/paths/v1~1b/requests/opB", tier: "cold-tail" }, // cold-tail
+        },
+      },
+    },
+  } as OpenAPIv4Document;
+}
+
+describe("C027 context-budget analyzer", () => {
+  test("cold-tail tools are NOT counted in the default load (the tiering's whole point)", () => {
+    const load = contextReport(doc1()).loads[0];
+    expect(load.tools.find((t) => t.name === "tool_b")!.tier).toBe("cold-tail");
+    expect(load.tools.filter((t) => t.tier === "resident").map((t) => t.name)).toEqual(["tool_a"]);
+    expect(load.coldTailTokens).toBeGreaterThan(0);
+    expect(load.totalTokens).toBe(load.instructionsTokens + load.residentToolTokens + load.overheadTokens);
+    // tool_b's cost is in coldTailTokens, not the resident surface
+    expect(load.residentToolTokens).toBeLessThan(load.residentToolTokens + load.coldTailTokens);
+  });
+
+  test("instruction sizing: unmeasured without a snapshot, measured with one", () => {
+    expect(contextReport(doc1()).findings.some((f) => f.code === "unmeasured-instructions")).toBe(true);
+    const measured = contextReport(doc1(), { instructions: { "one/guide": "x".repeat(400) } });
+    expect(measured.loads[0].instructionsTokens).toBe(100); // 400 chars / 4
+    expect(measured.loads[0].instructionsMeasured).toBe(true);
+    expect(measured.findings.some((f) => f.code === "unmeasured-instructions")).toBe(false);
+  });
+
+  test("over-window: a tiny model window flags no-fitting-model + an unflatten suggestion", () => {
+    const r = contextReport(doc1(), { modelWindows: { "anthropic/claude-opus-4": 200 } });
+    expect(r.loads[0].modelWindow).toBe(200);
+    expect(r.findings.some((f) => f.code === "no-fitting-model")).toBe(true); // overhead alone > 200
+    const sug = r.suggestions.find((s) => s.agent === "one")!;
+    expect(sug).toBeDefined();
+    expect(sug.moveToColdTail).toContain("tool_a");
+  });
+
+  test("over-budget + flat-agent-overloaded when the resident surface dwarfs a small budget", () => {
+    const r = contextReport(doc1({ budget: 100 }));
+    expect(r.findings.some((f) => f.code === "context-over-budget")).toBe(true);
+    expect(r.findings.some((f) => f.code === "flat-agent-overloaded")).toBe(true);
+  });
+
+  test("comfortably under budget ⇒ no over-findings, no suggestion", () => {
+    const r = contextReport(doc1({ budget: 100_000 }));
+    expect(r.findings.some((f) => ["context-over-window", "context-over-budget", "flat-agent-overloaded"].includes(f.code))).toBe(false);
+    expect(r.suggestions).toEqual([]);
+  });
+
+  test("empty layer (no skills, no routes) is flagged to fill — the 'layers first' flow", () => {
+    const d = { openapi: "4.0.0-candidate", info: { title: "x", version: "0" }, paths: {}, "x-suluk-agents": { hollow: { description: "reserved layer" } } } as OpenAPIv4Document;
+    expect(contextReport(d).findings.some((f) => f.code === "empty-layer")).toBe(true);
+  });
+
+  test("suggestUnflatten moves the biggest resident tools first and reports the saving", () => {
+    const load = contextReport(doc1({ budget: 100 })).loads[0];
+    const s = suggestUnflatten(load)!;
+    expect(s.moveToColdTail.length).toBeGreaterThan(0);
+    expect(s.wouldSaveTokens).toBeGreaterThan(0);
+    expect(suggestUnflatten(load, 1_000_000)).toBeNull(); // not over a generous target
+  });
+});
+
+/** A parent with no own work delegating to one small leaf — the flatten cases. */
+function layered(): OpenAPIv4Document {
+  return {
+    openapi: "4.0.0-candidate",
+    info: { title: "x", version: "0" },
+    paths: { "v1/s": { requests: { search: { method: "get", responses: { ok: { status: 200 } } } } } },
+    "x-suluk-agents": {
+      top: { description: "orchestrator with no own tools", maxDepth: 1, agents: { leaf: { ref: "#/x-suluk-agents/worker" } } },
+      worker: { description: "a thin leaf", maxDepth: 0, skills: { go: { model: ["google/gemini-2.5-flash"] } }, routes: { search: { operationRef: "#/paths/v1~1s/requests/search" } }, agents: {} },
+    },
+  } as OpenAPIv4Document;
+}
+
+describe("C027 flatten (the dual of unflatten) — collapse a thin/redundant layer up", () => {
+  test("a passthrough agent (no own work, one child) is flagged", () => {
+    const r = contextReport(layered());
+    expect(r.findings.some((f) => f.code === "passthrough-agent" && f.agent === "top")).toBe(true);
+  });
+
+  test("a thin leaf reached by one parent, merging within budget, is a flatten candidate", () => {
+    const r = contextReport(layered());
+    const flat = r.flatten.find((f) => f.parent === "top" && f.child === "worker");
+    expect(flat).toBeDefined();
+    expect(flat!.fitsTarget).toBe(true);
+    expect(flat!.savedHopOverhead).toBeGreaterThan(0);
+    expect(r.findings.some((f) => f.code === "flattenable-layer")).toBe(true);
+  });
+
+  test("NOT flattenable when merging would blow the parent's target (the layer earns its keep)", () => {
+    const d = layered();
+    // give the worker a big resident tool so inlining it would exceed a tight parent budget
+    d.paths["v1/big"] = { requests: { bigOp: { method: "post", responses: { ok: { status: 200 } }, contentSchema: { type: "object", properties: Object.fromEntries(Array.from({ length: 25 }, (_, i) => [`p${i}`, { type: "string", description: "a descriptive field" }])) } } } };
+    d["x-suluk-agents"]!.worker.routes!.big = { operationRef: "#/paths/v1~1big/requests/bigOp" };
+    d["x-suluk-agents"]!.top.contextBudget = { tokens: 500, basis: "estimate" }; // top (460) fits; merged (>600) does not
+    const r = contextReport(d);
+    expect(r.flatten.some((f) => f.parent === "top")).toBe(false);
+  });
+});
+
+describe("C029 thinking — round-accretion folds into the load the analyzer checks", () => {
+  test("a multi-round PEAK can exceed a window the single-shot base fits (the fixed blindspot)", () => {
+    const d = doc1();
+    d["x-suluk-agents"]!.one.thinking = { maxRounds: 6 };
+    const r = contextReport(d, { modelWindows: { "anthropic/claude-opus-4": 600 } });
+    const load = r.loads[0];
+    expect(load.maxRounds).toBe(6);
+    expect(load.peakTokens).toBeGreaterThan(load.totalTokens);
+    expect(load.totalTokens).toBeLessThan(600);    // single-shot fits
+    expect(load.peakTokens).toBeGreaterThan(600);  // the 6-round peak does not
+    expect(load.minWindowRequired).toBe(load.peakTokens);
+    expect(r.findings.some((f) => f.code === "no-fitting-model")).toBe(true);
+    expect(r.findings.some((f) => f.code === "thinking-context-growth")).toBe(true);
+  });
+
+  test("an explicit thinking budget is used as the accretion", () => {
+    const d = doc1();
+    d["x-suluk-agents"]!.one.thinking = { maxRounds: 3, budget: { tokens: 5000, basis: "estimate" } };
+    const load = contextReport(d).loads[0];
+    expect(load.thinkingBudget).toBe(5000);
+    expect(load.peakTokens).toBe(load.totalTokens + 5000);
+  });
+
+  test("no thinking ⇒ peak equals single-shot (backward-compatible)", () => {
+    const load = contextReport(doc1()).loads[0];
+    expect(load.peakTokens).toBe(load.totalTokens);
+    expect(load.maxRounds).toBeUndefined();
+  });
+});
+
+describe("C027 model fit — which declared models are expected to work", () => {
+  test("each candidate model is checked for window fit; minWindowRequired is the load", () => {
+    // windows now come from the catalog (DEFAULT_WINDOWS deleted) — opus is 200k in the seed
+    const load = contextReport(doc1(), { catalog: SEED_CATALOG }).loads[0];
+    expect(load.minWindowRequired).toBe(load.totalTokens);
+    const fit = load.modelFit.find((f) => f.model === "anthropic/claude-opus-4")!;
+    expect(fit.window).toBe(200_000);
+    expect(fit.fits).toBe(true);
+    expect(fit.headroom).toBe(200_000 - load.totalTokens);
+  });
+
+  test("model-too-small names a declared model that cannot hold the agent", () => {
+    const r = contextReport(doc1(), { modelWindows: { "anthropic/claude-opus-4": 100 } });
+    expect(r.findings.some((f) => f.code === "no-fitting-model" && f.agent === "one")).toBe(true);
+    expect(r.loads[0].modelFit[0].fits).toBe(false);
+  });
+});

package/test/core-boundary.test.ts

@@ -0,0 +1,38 @@
+import { test, expect, describe } from "bun:test";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * The C027 MODULE-BOUNDARY INVARIANT — D1 enforced by build, not discipline. @suluk/core's matcher must never be
+ * able to consult an agent field, and the structural guarantee of that is: @suluk/core NEVER imports @suluk/agents.
+ * This is a maintained tripwire — if anyone ever wires the agent layer into core, this fails loud.
+ */
+function walk(dir: string): string[] {
+  return readdirSync(dir).flatMap((e) => {
+    const p = join(dir, e);
+    return statSync(p).isDirectory() ? walk(p) : p.endsWith(".ts") ? [p] : [];
+  });
+}
+
+describe("C027 module boundary (D1 by build)", () => {
+  const coreSrc = join(import.meta.dir, "..", "..", "core", "src");
+
+  test("@suluk/core imports nothing from @suluk/agents (the dependency is one-way)", () => {
+    const offenders: string[] = [];
+    for (const f of walk(coreSrc)) {
+      const text = readFileSync(f, "utf8");
+      if (/from\s+["']@suluk\/agents["']|require\(\s*["']@suluk\/agents["']\s*\)|from\s+["'][./]+agents["']/.test(text)) {
+        offenders.push(f);
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  test("@suluk/core's matcher source (ada.ts) never references x-suluk-agents or x-suluk-policy", () => {
+    const ada = readFileSync(join(coreSrc, "ada.ts"), "utf8");
+    expect(ada.includes("x-suluk-agents")).toBe(false);
+    expect(ada.includes("x-suluk-policy")).toBe(false);
+    expect(ada.includes("agents")).toBe(false);
+    expect(ada.includes("policy")).toBe(false);
+  });
+});

package/test/fixtures/conin.ts

@@ -0,0 +1,112 @@
+/**
+ * Conin as an `x-suluk-agents` fixture (C027) — the live, un-standardized cowpath, serialized. A FLAT two-tier
+ * agent: an orchestrator (`conin`) with a model-bearing skill + two deterministic routes + one sub-agent (the
+ * untrusted retrieval tier `coninRetrieval`). Plus the NAMED conformance-failure variants the council requires
+ * tracked (not laundered): Conin's MCP-only primitive (a dangling operationRef), a cycle, a missing depth bound,
+ * and a forbidden request-value selector.
+ */
+import type { OpenAPIv4Document, Request, HttpMethod } from "@suluk/core";
+
+const req = (method: HttpMethod): Request => ({ method, responses: { ok: { status: 200 } } });
+
+/** The valid, installable Conin agent (all four routes resolve to real operations). */
+export const coninDoc: OpenAPIv4Document = {
+  openapi: "4.0.0-candidate",
+  info: { title: "Conin — Construction Intelligence", version: "1.0.0" },
+  paths: {
+    "v1/deliverables": { requests: { generateDeliverable: req("post") } },
+    "v1/primitives": { requests: { runCorePrimitive: req("post") } },
+    "v1/library/search": { requests: { searchLibrary: req("get") } },
+    "v1/comparables": { requests: { findComparables: req("get") } },
+  },
+  "x-suluk-agents": {
+    conin: {
+      description: "Construction-intelligence orchestrator: messy project docs → provenance-graded deliverables. Use to cost/value/certify/reconcile a MENA capital project.",
+      // the orchestrator must GRANT what its sub-tree uses (incl. the retrieval child's library:read) — a child's
+      // effective scope is INTERSECTION(child, caller), so a permission absent here would be silently dropped.
+      scope: ["project:read", "deliverable:write", "library:read"],
+      maxDepth: 1,
+      skills: {
+        operate: {
+          model: ["anthropic/claude-opus-4", "google/gemini-2.5-flash"],
+          tier: "cold-tail",
+          whenToUse: "Always loaded first; governs deterministic-first + SOURCED/ASSUMED grading; routes to a deliverable kind.",
+          trust: "author-declared",
+          scope: ["project:read"],
+          provenance: { source: "https://construction-intelligence.saastemly.com/v1/instructions", contentHash: "sha256-9f2c0000deadbeef", version: "2026-06-11" },
+        },
+      },
+      routes: {
+        generate_deliverable: { operationRef: "#/paths/v1~1deliverables/requests/generateDeliverable", guarantee: "same-in-same-out", scope: ["deliverable:write"] },
+        run_core_primitive: { operationRef: "#/paths/v1~1primitives/requests/runCorePrimitive", guarantee: "same-in-same-out", scope: ["project:read"] },
+      },
+      agents: { retrieval: { ref: "#/x-suluk-agents/coninRetrieval" } },
+    },
+    coninRetrieval: {
+      description: "Untrusted retrieval tier: search_library / find_comparables. Returns ASSUMED-grade material only; never emits a graded figure.",
+      scope: ["library:read"],
+      maxDepth: 0,
+      trustBoundary: "untrusted",
+      skills: {
+        search: {
+          model: ["google/gemini-2.5-flash"],
+          tier: "resident",
+          whenToUse: "Find comparables/evidence; returns ASSUMED-grade material only.",
+          provenance: { source: "https://construction-intelligence.saastemly.com/v1/instructions#retrieval", contentHash: "sha256-1a7d0000feedface", version: "2026-06-11" },
+        },
+      },
+      routes: {
+        search_library: { operationRef: "#/paths/v1~1library~1search/requests/searchLibrary", guarantee: "idempotent", scope: ["library:read"] },
+        find_comparables: { operationRef: "#/paths/v1~1comparables/requests/findComparables", guarantee: "idempotent", scope: ["library:read"] },
+      },
+      agents: {},
+    },
+  },
+};
+
+/** The instruction snapshots a projector is fed (pinned; never fetched at generate time). */
+export const coninInstructions: Record<string, string> = {
+  operate: "You are Conin. Deterministic-first: every NUMBER comes from a deterministic tool; the LLM only routes. Grade every figure SOURCED or ASSUMED.",
+  search: "Retrieval tier. Find comparables and evidence. You return ASSUMED-grade material only — never a graded figure.",
+};
+
+/** FAILURE FIXTURE — Conin's REAL day-one gap: run_core_primitive is dispatched MCP-only, with no REST operation. */
+export function coninDayOne(): OpenAPIv4Document {
+  const d = structuredClone(coninDoc);
+  delete (d.paths as Record<string, unknown>)["v1/primitives"]; // the operationRef now dangles
+  return d;
+}
+
+/** FAILURE FIXTURE — a recursion cycle (a ↔ b), each with a (useless) declared maxDepth. */
+export function cyclicDoc(): OpenAPIv4Document {
+  return {
+    openapi: "4.0.0-candidate",
+    info: { title: "cyclic", version: "0" },
+    paths: {},
+    "x-suluk-agents": {
+      a: { description: "agent a", maxDepth: 1, agents: { toB: { ref: "#/x-suluk-agents/b" } } },
+      b: { description: "agent b", maxDepth: 1, agents: { toA: { ref: "#/x-suluk-agents/a" } } },
+    },
+  };
+}
+
+/** FAILURE FIXTURE — sub-agents present but no maxDepth declared (must not install). */
+export function missingMaxDepthDoc(): OpenAPIv4Document {
+  const d = structuredClone(coninDoc);
+  delete d["x-suluk-agents"]!.conin.maxDepth;
+  return d;
+}
+
+/** FAILURE FIXTURE — a forbidden request-value selector smuggled in via a vendor field (the #20 tripwire, D1). */
+export function selectorDoc(): OpenAPIv4Document {
+  const d = structuredClone(coninDoc);
+  d["x-suluk-agents"]!.conin["x-suluk-route-when"] = "{$request.body#/kind}";
+  return d;
+}
+
+/** FAILURE FIXTURE — scope escalation: the retrieval child needs library:read but the orchestrator no longer grants it. */
+export function escalationDoc(): OpenAPIv4Document {
+  const d = structuredClone(coninDoc);
+  d["x-suluk-agents"]!.conin.scope = ["project:read", "deliverable:write"]; // drops library:read → child escalates
+  return d;
+}

package/test/lint.test.ts

@@ -0,0 +1,62 @@
+import { test, expect, describe } from "bun:test";
+import { lintAgents, lintOk } from "../src/index";
+import { coninDoc, coninDayOne, cyclicDoc, missingMaxDepthDoc, selectorDoc } from "./fixtures/conin";
+
+const codes = (doc: Parameters<typeof lintAgents>[0]) => lintAgents(doc).filter((f) => f.severity === "error").map((f) => f.code);
+
+describe("C027 agent lint", () => {
+  test("the valid Conin agent installs (no errors)", () => {
+    const findings = lintAgents(coninDoc);
+    expect(findings.filter((f) => f.severity === "error")).toEqual([]);
+    expect(lintOk(findings)).toBe(true);
+  });
+
+  test("NAMED failure: Conin's MCP-only run_core_primitive is a dangling operationRef", () => {
+    const errs = lintAgents(coninDayOne()).filter((f) => f.severity === "error");
+    expect(errs.some((e) => e.code === "dangling-operation-ref" && e.at?.includes("run_core_primitive"))).toBe(true);
+    expect(lintOk(errs)).toBe(false);
+  });
+
+  test("a recursion cycle is rejected", () => {
+    expect(codes(cyclicDoc())).toContain("agent-cycle");
+  });
+
+  test("sub-agents without a declared maxDepth do not install", () => {
+    expect(codes(missingMaxDepthDoc())).toContain("missing-max-depth");
+  });
+
+  test("D1: a request-value selector smuggled via a vendor field is forbidden", () => {
+    const errs = lintAgents(selectorDoc()).filter((f) => f.severity === "error");
+    expect(errs.some((e) => e.code === "request-value-selector")).toBe(true);
+  });
+
+  test("a route carrying a model is an error (a route is deterministic)", () => {
+    const d = structuredClone(coninDoc);
+    (d["x-suluk-agents"]!.conin.routes!.generate_deliverable as unknown as Record<string, unknown>).model = ["x"];
+    expect(codes(d)).toContain("route-has-model");
+  });
+
+  test("C029: thinking present without maxRounds is rejected", () => {
+    const d = structuredClone(coninDoc);
+    d["x-suluk-agents"]!.conin.thinking = {} as { maxRounds: number };
+    expect(codes(d)).toContain("missing-max-rounds");
+  });
+
+  test("C029: maxRounds < 1 is rejected", () => {
+    const d = structuredClone(coninDoc);
+    d["x-suluk-agents"]!.conin.thinking = { maxRounds: 0 };
+    expect(codes(d)).toContain("invalid-max-rounds");
+  });
+
+  test("C029: a stopCondition-shaped member is forbidden (declare the bound, not the process)", () => {
+    const d = structuredClone(coninDoc);
+    d["x-suluk-agents"]!.conin.thinking = { maxRounds: 3, stopCondition: "final-answer" } as unknown as { maxRounds: number };
+    expect(codes(d)).toContain("thinking-process-declared");
+  });
+
+  test("C029: a valid thinking bound lints clean", () => {
+    const d = structuredClone(coninDoc);
+    d["x-suluk-agents"]!.conin.thinking = { maxRounds: 6, budget: { tokens: 40000, basis: "estimate" } };
+    expect(lintAgents(d).filter((f) => f.severity === "error")).toEqual([]);
+  });
+});