@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/subagents/schema.test.mjs

@@ -0,0 +1,306 @@
+/**
+ * schema.test.mjs — the frontmatter parser/validator (Sub-Agent Registry §2.1).
+ * Run: node --test lib/subagents/schema.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  AUTHORED_KEYS,
+  MODEL_ALIASES,
+  PROVENANCE_KEYS,
+  bodyTokens,
+  checkAgentFile,
+  hashBody,
+  hashFile,
+  normaliseModel,
+  parseAgentMd,
+  parseFrontmatter,
+  splitFrontmatter,
+  stampProvenance,
+  stringifyAgentMd,
+  stringifyFrontmatter,
+  stripProvenance,
+  unsupportedTokens,
+  validateAgentMd,
+} from "./schema.mjs";
+import { listAgentDirs } from "./manifest.mjs";
+
+const MAESTRO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+const GOOD = [
+  "---",
+  "name: alpha",
+  "description: Handles alpha work.",
+  "model: claude-sonnet-4-6",
+  'tools: ["Read", "Write"]',
+  "---",
+  "# alpha",
+  "",
+  "Serve {{agent.firstName}}.",
+  "",
+].join("\n");
+
+// ---------------------------------------------------------------------------
+// splitFrontmatter
+// ---------------------------------------------------------------------------
+
+test("splitFrontmatter: splits fences and keeps the body verbatim", () => {
+  const s = splitFrontmatter(GOOD);
+  assert.equal(s.ok, true);
+  assert.match(s.frontmatterText, /^name: alpha\n/);
+  assert.match(s.body, /^# alpha\n/);
+});
+
+test("splitFrontmatter: a prose-only file is an ERROR, not empty frontmatter", () => {
+  // The bug this closes: an agents/<slug>/ with no real frontmatter used to pass
+  // doctor because doctor only checked that the directory existed.
+  const s = splitFrontmatter("# alpha\n\njust prose\n");
+  assert.equal(s.ok, false);
+  assert.match(s.error, /missing opening/);
+});
+
+test("splitFrontmatter: unterminated frontmatter is an error", () => {
+  const s = splitFrontmatter("---\nname: alpha\n# no closing fence\n");
+  assert.equal(s.ok, false);
+  assert.match(s.error, /unterminated/);
+});
+
+test("splitFrontmatter: tolerates a BOM and CRLF line endings", () => {
+  const crlf = "" + GOOD.replace(/\n/g, "\r\n");
+  const s = splitFrontmatter(crlf);
+  assert.equal(s.ok, true);
+  assert.equal(s.body.includes("\r"), false);
+});
+
+test("splitFrontmatter: empty frontmatter block parses to an empty map", () => {
+  const s = splitFrontmatter("---\n---\nbody\n");
+  assert.equal(s.ok, true);
+  assert.equal(s.frontmatterText, "");
+  assert.equal(s.body, "body\n");
+});
+
+// ---------------------------------------------------------------------------
+// parseFrontmatter
+// ---------------------------------------------------------------------------
+
+test("parseFrontmatter: scalars, flow sequences and block sequences", () => {
+  const r = parseFrontmatter([
+    "name: alpha",
+    'description: "Handles: alpha work"',
+    "model: sonnet   # trailing comment",
+    'tools: [Read, "Write", \'Edit\']',
+    "tokens:",
+    "  - agent.firstName",
+    "  - agent.company",
+  ].join("\n"));
+  assert.equal(r.ok, true, r.errors.join("; "));
+  assert.equal(r.value.name, "alpha");
+  assert.equal(r.value.description, "Handles: alpha work");
+  assert.equal(r.value.model, "sonnet");
+  assert.deepEqual(r.value.tools, ["Read", "Write", "Edit"]);
+  assert.deepEqual(r.value.tokens, ["agent.firstName", "agent.company"]);
+});
+
+test("parseFrontmatter: a `#` inside a quoted scalar is content, not a comment", () => {
+  const r = parseFrontmatter('description: "ships #1 priority"');
+  assert.equal(r.value.description, "ships #1 priority");
+});
+
+test("parseFrontmatter: a comma inside a quoted flow item is not a separator", () => {
+  // The registry round-trips these bytes into a database — "unlikely" is not a
+  // licence to corrupt.
+  const r = parseFrontmatter('tools: ["Read, maybe", Write]');
+  assert.deepEqual(r.value.tools, ["Read, maybe", "Write"]);
+});
+
+test("parseFrontmatter: anything outside the closed grammar is an ERROR, never a silent mis-parse", () => {
+  const r = parseFrontmatter("name: alpha\nnested:\n  key: value\n");
+  assert.equal(r.ok, false);
+  assert.match(r.errors.join(" "), /nested maps are outside the frontmatter grammar/);
+});
+
+test("parseFrontmatter: an orphan list item is an error", () => {
+  const r = parseFrontmatter("name: alpha\n  - stray\n");
+  assert.equal(r.ok, false);
+  assert.match(r.errors.join(" "), /no owning key/);
+});
+
+test("parseFrontmatter: an unterminated flow sequence is an error", () => {
+  const r = parseFrontmatter("tools: [Read, Write\n");
+  assert.equal(r.ok, false);
+  assert.match(r.errors.join(" "), /unterminated flow sequence/);
+});
+
+// ---------------------------------------------------------------------------
+// model normalisation — where the shipped-vs-generated drift dies
+// ---------------------------------------------------------------------------
+
+test("normaliseModel: aliases and full ids both normalise, idempotently", () => {
+  assert.equal(normaliseModel("sonnet"), "claude-sonnet-4-6");
+  assert.equal(normaliseModel("claude-sonnet-4-6"), "claude-sonnet-4-6");
+  assert.equal(normaliseModel(normaliseModel("opus")), "claude-opus-4-8");
+  assert.equal(normaliseModel("HAIKU"), "claude-haiku-4-5");
+  assert.equal(normaliseModel("inherit"), "inherit");
+});
+
+test("normaliseModel: unknown → null (an error for the caller), absent → \"\"", () => {
+  assert.equal(normaliseModel("gpt-4o"), null);
+  assert.equal(normaliseModel(""), "");
+  assert.equal(normaliseModel(undefined), "");
+});
+
+test("MODEL_ALIASES: every alias target is itself a key (normalisation is a fixpoint)", () => {
+  for (const target of Object.values(MODEL_ALIASES)) {
+    assert.equal(MODEL_ALIASES[target], target, `${target} must map to itself`);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// validate
+// ---------------------------------------------------------------------------
+
+function fm(over = {}) {
+  return { name: "alpha", description: "d", model: "sonnet", tools: ["Read"], ...over };
+}
+
+test("validateAgentMd: the happy path normalises the model and derives tokens", () => {
+  const v = validateAgentMd({ frontmatter: fm(), body: "x {{agent.firstName}}", slug: "alpha" });
+  assert.equal(v.ok, true, v.errors.join("; "));
+  assert.equal(v.normalised.frontmatter.model, "claude-sonnet-4-6");
+  assert.deepEqual(v.normalised.frontmatter.tokens, ["agent.firstName"]);
+});
+
+test("validateAgentMd: name must equal the directory name (identity IS the dirname)", () => {
+  const v = validateAgentMd({ frontmatter: fm({ name: "beta" }), body: "x", slug: "alpha" });
+  assert.equal(v.ok, false);
+  assert.match(v.errors.join(" "), /must equal the directory name/);
+});
+
+test("validateAgentMd: description, model, tools and body are all required", () => {
+  const cases = [
+    [fm({ description: "" }), "x", /description is required/],
+    [fm({ model: "gpt-4o" }), "x", /not a known model/],
+    [fm({ model: "" }), "x", /model is required/],
+    [fm({ tools: undefined }), "x", /tools is required/],
+    [fm({ tools: [] }), "x", /tools must be non-empty/],
+    [fm(), "   ", /body is empty/],
+  ];
+  for (const [f, body, re] of cases) {
+    const v = validateAgentMd({ frontmatter: f, body, slug: "alpha" });
+    assert.equal(v.ok, false, `expected failure for ${re}`);
+    assert.match(v.errors.join(" "), re);
+  }
+});
+
+test("validateAgentMd: an ABSENT tokens key is derived, not an error", () => {
+  // Every file that shipped before the registry existed has no `tokens:` key.
+  // Demanding one would fail-closed the whole fleet on the first doctor run.
+  const v = validateAgentMd({ frontmatter: fm(), body: "{{agent.company}}", slug: "alpha" });
+  assert.equal(v.ok, true);
+  assert.deepEqual(v.normalised.frontmatter.tokens, ["agent.company"]);
+});
+
+test("validateAgentMd: a DECLARED tokens list must cover every token the body uses", () => {
+  const v = validateAgentMd({ frontmatter: fm({ tokens: [] }), body: "{{agent.company}}", slug: "alpha" });
+  assert.equal(v.ok, false);
+  assert.match(v.errors.join(" "), /undeclared token/);
+});
+
+test("validateAgentMd: declared-but-unused and renderer-unknown tokens WARN, never fail", () => {
+  const v = validateAgentMd({
+    frontmatter: fm({ tokens: ["agent.firstName", "agent.nope"] }),
+    body: "{{agent.firstName}}",
+    slug: "alpha",
+  });
+  assert.equal(v.ok, true, v.errors.join("; "));
+  assert.match(v.warnings.join(" "), /declared but unused/);
+  assert.match(v.warnings.join(" "), /unknown to this agent's renderer/);
+});
+
+test("unsupportedTokens: honours an injected KNOWN_TOKENS set", () => {
+  assert.deepEqual(unsupportedTokens(["a", "b"], new Set(["a"])), ["b"]);
+  assert.deepEqual(unsupportedTokens(null, new Set()), []);
+});
+
+test("bodyTokens: deduped and sorted", () => {
+  assert.deepEqual(bodyTokens("{{agent.z}} {{agent.a}} {{agent.z}}"), ["agent.a", "agent.z"]);
+});
+
+// ---------------------------------------------------------------------------
+// emit / round-trip — what makes local-edit detection trustworthy
+// ---------------------------------------------------------------------------
+
+test("stringifyFrontmatter: canonical key order (authored, then provenance, then rest)", () => {
+  const text = stringifyFrontmatter({ contentHash: "h", extra: 1, tools: ["Read"], name: "alpha" });
+  assert.deepEqual(text.trim().split("\n"), ['name: alpha', 'tools: ["Read"]', "contentHash: h", "extra: 1"]);
+});
+
+test("round trip: parse(stringify(x)) === x, and a second pass is byte-identical", () => {
+  const f = { name: "alpha", description: "d", model: "claude-sonnet-4-6", tools: ["Read", "Write"], tokens: [] };
+  const once = stringifyAgentMd(f, "# alpha\n\nbody\n");
+  const parsed = parseAgentMd(once);
+  assert.equal(parsed.ok, true, parsed.errors.join("; "));
+  assert.deepEqual(parsed.frontmatter, f);
+  assert.equal(stringifyAgentMd(parsed.frontmatter, parsed.body), once);
+});
+
+test("stampProvenance: is IDEMPOTENT — re-stamping produces identical bytes", () => {
+  // Non-idempotent stamping would change the file hash on every materialisation
+  // and make local-edit detection permanently wrong.
+  const one = stampProvenance({
+    frontmatter: fm(), body: "b\n", layer: "workspace", source: "cohort://o/alpha", version: 7,
+  });
+  const re = parseAgentMd(one);
+  const two = stampProvenance({
+    frontmatter: re.frontmatter, body: re.body, layer: "workspace", source: "cohort://o/alpha", version: 7,
+  });
+  assert.equal(two, one);
+  assert.equal(hashFile(two), hashFile(one));
+});
+
+test("stampProvenance: never renders tokens — {{agent.*}} survives to disk", () => {
+  const text = stampProvenance({ frontmatter: fm(), body: "hi {{agent.firstName}}\n", layer: "sdk" });
+  assert.match(text, /\{\{agent\.firstName\}\}/);
+});
+
+test("stripProvenance: removes exactly the registry-owned keys", () => {
+  const out = stripProvenance({ name: "alpha", layer: "sdk", source: "s", version: "1", contentHash: "h" });
+  assert.deepEqual(Object.keys(out), ["name"]);
+  for (const k of PROVENANCE_KEYS) assert.equal(k in out, false);
+  assert.ok(AUTHORED_KEYS.includes("name"));
+});
+
+test("hashBody and hashFile have different preimages (body vs whole file)", () => {
+  const parsed = parseAgentMd(GOOD);
+  assert.notEqual(hashBody(parsed.body), hashFile(GOOD));
+  assert.equal(hashBody(parsed.body), hashBody(parsed.body));
+  assert.equal(hashBody(null), hashBody(""));
+});
+
+// ---------------------------------------------------------------------------
+// the real corpus — the validator must not reject what already shipped
+// ---------------------------------------------------------------------------
+
+test("every shipped agents/*/agent.md validates (the fleet must not fail-closed)", () => {
+  const { slugs } = listAgentDirs(MAESTRO_ROOT);
+  assert.ok(slugs.length >= 1, "expected the SDK to ship at least one agent");
+  const bad = [];
+  for (const slug of slugs) {
+    const text = readFileSync(join(MAESTRO_ROOT, "agents", slug, "agent.md"), "utf8");
+    const c = checkAgentFile(text, slug);
+    if (!c.ok) bad.push(`${slug}: ${c.errors.join(", ")}`);
+  }
+  assert.deepEqual(bad, []);
+});
+
+test("checkAgentFile: reports the parse error rather than throwing", () => {
+  const c = checkAgentFile("no frontmatter here", "alpha");
+  assert.equal(c.ok, false);
+  assert.match(c.errors.join(" "), /missing opening/);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.3.2",
+  "version": "2.4.0",
   "description": "Cohort Agent SDK \u2014 autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {
@@ -36,6 +36,9 @@
     "./org/approvals": "./lib/org/approvals.mjs",
     "./org/mesh": "./lib/org/mesh.mjs",
     "./org/cohort-client": "./lib/org/cohort-client.mjs",
+    "./org/inbound": "./lib/org/inbound/index.mjs",
+    "./org/inbound/surfaces": "./lib/org/inbound/surfaces.mjs",
+    "./org/inbound/directedness": "./lib/org/inbound/directedness.mjs",
     "./secrets/broker": "./lib/secrets/broker.mjs",
     "./secrets/providers": "./lib/secrets/providers.mjs",
     "./diagnostics/trace": "./lib/diagnostics/trace.mjs",
@@ -118,9 +121,11 @@
   "scripts": {
     "test": "node scripts/ci/run-tests.mjs",
     "test:coverage": "node scripts/ci/run-coverage.mjs",
-    "test:list": "node --test bin/maestro.test.mjs lib/action-executor.test.mjs lib/archetype.test.mjs lib/autonomy.test.mjs lib/backlog.test.mjs lib/budget-guard.test.mjs lib/cadence-bus-schedule.test.mjs lib/cadence-bus.test.mjs lib/cadences.test.mjs lib/capability.test.mjs lib/channels/base-adapter.test.mjs lib/channels/channels.test.mjs lib/channels/contract.test.mjs lib/channels/inbox-item.test.mjs lib/channels/pairing.test.mjs lib/channels/slack-adapter.test.mjs lib/channels/telegram-adapter.test.mjs lib/channels/whatsapp/baileys-typing.test.mjs lib/charter.test.mjs lib/claude-bin.test.mjs lib/collective/capture.test.mjs lib/collective/cards.test.mjs lib/collective/config.test.mjs lib/collective/global-config.test.mjs lib/collective/presence.test.mjs lib/collective/recall.test.mjs lib/comms.test.mjs lib/fs-atomic.test.mjs lib/fs-ownership.test.mjs lib/learning/config.test.mjs lib/learning/counters.test.mjs lib/learning/curator-consolidate.test.mjs lib/learning/curator.test.mjs lib/learning/reflect.test.mjs lib/learning/session-index.test.mjs lib/learning/skill-writer.test.mjs lib/model-router.test.mjs lib/model-router/catalog.test.mjs lib/model-router/economics.test.mjs lib/model-router/failover.test.mjs lib/model-router/health.test.mjs lib/model-router/integration.test.mjs lib/model-router/integration-coverage.test.mjs lib/model-router/ledger.test.mjs lib/model-router/llm-task.test.mjs lib/model-router/org-credentials.test.mjs lib/model-router/reconcile.test.mjs lib/model-router/repair.test.mjs lib/model-router/spawn.test.mjs lib/model-router/taxonomy.test.mjs lib/org/approvals.test.mjs lib/org/board.test.mjs lib/org/client.test.mjs lib/org/cost-sync.test.mjs lib/org/handoff.test.mjs lib/org/keys.test.mjs lib/org/knowledge.test.mjs lib/org/activity.test.mjs lib/org/leases.test.mjs lib/org/mesh.test.mjs lib/org/messaging.test.mjs lib/org/cohort-client.test.mjs lib/org/policy.test.mjs lib/org/registry.test.mjs lib/org/tool-surface.test.mjs lib/org/ui-parity.test.mjs lib/org/doctor.test.mjs lib/org/verify.test.mjs lib/mcp/server.test.mjs lib/channels/orgmail/adapter.test.mjs lib/rag/rag.test.mjs lib/rate-guard.test.mjs lib/render.test.mjs lib/resource-governor.test.mjs lib/security/coerce-args.test.mjs lib/security/dangerous-tools.test.mjs lib/security/external-content.test.mjs lib/security/redact.test.mjs lib/security/secret-equal.test.mjs lib/session-permissions.test.mjs lib/setup/completeness.test.mjs lib/setup/context-pack.test.mjs lib/setup/enrich.test.mjs lib/setup/enroll-from-cohort.test.mjs lib/setup/integration.test.mjs lib/setup/io.test.mjs lib/setup/runner.test.mjs lib/setup/sections/identity.test.mjs lib/setup/sections/learning.test.mjs lib/setup/sections/messaging.test.mjs lib/setup/sections/org.test.mjs lib/setup/sections/orgmail.test.mjs lib/setup/sections/recovery.test.mjs lib/setup/sot.test.mjs lib/setup/state.test.mjs lib/singleton.test.mjs lib/telemetry/alerts.test.mjs lib/telemetry/collect.test.mjs lib/tool-definitions.test.mjs lib/voice/outbound.test.mjs lib/voice/stt.test.mjs lib/voice/voice.test.mjs scripts/cadence/enqueue-cadence-tick.test.mjs scripts/ci/check-no-build-artifacts.test.mjs scripts/ci/check-no-residual-identity.test.mjs scripts/ci/check.test.mjs scripts/collective/hook-runner.test.mjs scripts/cost/fleet-digest.test.mjs scripts/daemon/cadence-consumer-governance.test.mjs scripts/daemon/cadence-consumer.test.mjs scripts/daemon/cadence-handlers.test.mjs scripts/daemon/classify-kind.test.mjs scripts/daemon/dispatcher-cooldown.test.mjs scripts/daemon/dispatcher-governance.test.mjs scripts/daemon/inbox-deferral.test.mjs scripts/daemon/lib/session-router.test.mjs scripts/daemon/prompt-builder.test.mjs scripts/daemon/typing-registry.test.mjs scripts/hooks/pre-send-audit.test.mjs scripts/local-triggers/generate-plists.test.mjs scripts/poller/inbox-scan-poller.test.mjs scripts/poller/lib/cloud-relay-dedup.test.mjs scripts/poller/slack-socket-mode.test.mjs scripts/setup/init-agent.test.mjs services/webhook-relay/server.test.mjs",
-    "test:setup": "node --test lib/setup/io.test.mjs lib/setup/state.test.mjs lib/setup/sot.test.mjs lib/setup/completeness.test.mjs lib/setup/context-pack.test.mjs lib/setup/enrich.test.mjs lib/setup/runner.test.mjs lib/setup/integration.test.mjs",
+    "test:list": "node --test bin/maestro.test.mjs lib/action-executor.test.mjs lib/archetype.test.mjs lib/autonomy.test.mjs lib/backlog.test.mjs lib/budget-guard.test.mjs lib/cadence-bus-schedule.test.mjs lib/cadence-bus.test.mjs lib/cadences.test.mjs lib/capability.test.mjs lib/channels/base-adapter.test.mjs lib/channels/channels.test.mjs lib/channels/contract.test.mjs lib/channels/inbox-item.test.mjs lib/channels/pairing.test.mjs lib/channels/slack-adapter.test.mjs lib/channels/telegram-adapter.test.mjs lib/channels/whatsapp/baileys-typing.test.mjs lib/charter.test.mjs lib/claude-bin.test.mjs lib/collective/capture.test.mjs lib/collective/cards.test.mjs lib/collective/config.test.mjs lib/collective/global-config.test.mjs lib/collective/presence.test.mjs lib/collective/recall.test.mjs lib/comms.test.mjs lib/fs-atomic.test.mjs lib/fs-ownership.test.mjs lib/learning/config.test.mjs lib/learning/counters.test.mjs lib/learning/curator-consolidate.test.mjs lib/learning/curator.test.mjs lib/learning/reflect.test.mjs lib/learning/session-index.test.mjs lib/learning/skill-writer.test.mjs lib/model-router.test.mjs lib/model-router/catalog.test.mjs lib/model-router/economics.test.mjs lib/model-router/failover.test.mjs lib/model-router/health.test.mjs lib/model-router/integration.test.mjs lib/model-router/integration-coverage.test.mjs lib/model-router/ledger.test.mjs lib/model-router/llm-task.test.mjs lib/model-router/org-credentials.test.mjs lib/model-router/reconcile.test.mjs lib/model-router/repair.test.mjs lib/model-router/spawn.test.mjs lib/model-router/taxonomy.test.mjs lib/org/approvals.test.mjs lib/org/board.test.mjs lib/org/client.test.mjs lib/org/cost-sync.test.mjs lib/org/handoff.test.mjs lib/org/keys.test.mjs lib/org/knowledge.test.mjs lib/org/activity.test.mjs lib/org/leases.test.mjs lib/org/mesh.test.mjs lib/org/messaging.test.mjs lib/org/cohort-client.test.mjs lib/org/policy.test.mjs lib/org/registry.test.mjs lib/org/tool-surface.test.mjs lib/org/ui-parity.test.mjs lib/org/doctor.test.mjs lib/org/verify.test.mjs lib/mcp/server.test.mjs lib/channels/orgmail/adapter.test.mjs lib/rag/rag.test.mjs lib/rate-guard.test.mjs lib/render.test.mjs lib/resource-governor.test.mjs lib/security/coerce-args.test.mjs lib/security/dangerous-tools.test.mjs lib/security/external-content.test.mjs lib/security/redact.test.mjs lib/security/secret-equal.test.mjs lib/session-permissions.test.mjs lib/setup/completeness.test.mjs lib/setup/context-pack.test.mjs lib/setup/enrich.test.mjs lib/setup/enroll-from-cohort.test.mjs lib/setup/integration.test.mjs lib/setup/io.test.mjs lib/setup/runner.test.mjs lib/setup/sections/identity.test.mjs lib/setup/sections/learning.test.mjs lib/setup/sections/messaging.test.mjs lib/setup/sections/org.test.mjs lib/setup/sections/orgmail.test.mjs lib/setup/sections/recovery.test.mjs lib/setup/sections/subagents.test.mjs lib/setup/sot.test.mjs lib/setup/state.test.mjs lib/singleton.test.mjs lib/subagents/schema.test.mjs lib/subagents/refs.test.mjs lib/subagents/manifest.test.mjs lib/subagents/lock.test.mjs lib/subagents/resolve.test.mjs lib/subagents/gap.test.mjs lib/subagents/client.test.mjs lib/subagents/cli.test.mjs lib/telemetry/alerts.test.mjs lib/telemetry/collect.test.mjs lib/tool-definitions.test.mjs lib/voice/outbound.test.mjs lib/voice/stt.test.mjs lib/voice/voice.test.mjs scripts/cadence/enqueue-cadence-tick.test.mjs scripts/ci/check-no-build-artifacts.test.mjs scripts/ci/check-no-residual-identity.test.mjs scripts/ci/check.test.mjs scripts/collective/hook-runner.test.mjs scripts/cost/fleet-digest.test.mjs scripts/daemon/cadence-consumer-governance.test.mjs scripts/daemon/cadence-consumer.test.mjs scripts/daemon/cadence-handlers.test.mjs scripts/daemon/classify-kind.test.mjs scripts/daemon/dispatcher-cooldown.test.mjs scripts/daemon/dispatcher-governance.test.mjs scripts/daemon/inbox-deferral.test.mjs scripts/daemon/lib/session-router.test.mjs scripts/daemon/prompt-builder.test.mjs scripts/daemon/typing-registry.test.mjs scripts/hooks/pre-send-audit.test.mjs scripts/local-triggers/generate-plists.test.mjs scripts/poller/inbox-scan-poller.test.mjs scripts/poller/lib/cloud-relay-dedup.test.mjs scripts/poller/slack-socket-mode.test.mjs scripts/setup/gen-subagent-manifest.test.mjs scripts/setup/init-agent.test.mjs services/webhook-relay/server.test.mjs",
+    "test:setup": "node --test lib/setup/io.test.mjs lib/setup/state.test.mjs lib/setup/sot.test.mjs lib/setup/completeness.test.mjs lib/setup/context-pack.test.mjs lib/setup/enrich.test.mjs lib/setup/runner.test.mjs lib/setup/integration.test.mjs lib/setup/sections/subagents.test.mjs",
     "check": "node scripts/ci/check.mjs",
+    "conformance:org": "node scripts/ci/conformance-org-api.mjs",
+    "conformance:org:write": "node scripts/ci/conformance-org-api.mjs --write",
     "test:router": "node --test lib/model-router.test.mjs lib/model-router/catalog.test.mjs lib/model-router/economics.test.mjs lib/model-router/failover.test.mjs lib/model-router/health.test.mjs lib/model-router/integration.test.mjs lib/model-router/integration-coverage.test.mjs lib/model-router/ledger.test.mjs lib/model-router/llm-task.test.mjs lib/model-router/org-credentials.test.mjs lib/model-router/reconcile.test.mjs lib/model-router/repair.test.mjs lib/model-router/spawn.test.mjs lib/model-router/taxonomy.test.mjs scripts/cost/fleet-digest.test.mjs",
     "test:voice": "node --test lib/voice/voice.test.mjs lib/voice/outbound.test.mjs",
     "test:channels": "node --test lib/channels/channels.test.mjs",

package/plugins/maestro-skills/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "maestro-skills",
+  "owner": {
+    "name": "maestro"
+  },
+  "metadata": {
+    "description": "The maestro framework skill pack. Registering this marketplace is what makes the skill files in plugins/maestro-skills/skills/ actually invocable — without it they are inert markdown and rung 1 of the execution ladder (\"a skill exists for this procedure\") is a lie. lib/capability/inventory.mjs probes for this file and reports every skill as reachable:false when it is absent."
+  },
+  "plugins": [
+    {
+      "name": "maestro-skills",
+      "source": "./",
+      "description": "Maestro operational skills — executive briefings, communications, hiring, strategy, org-desk workflows (mail, files, calendar, CRM, books, directory, design) and Cohort call working sessions."
+    }
+  ]
+}

package/policies/ai-disclosure.yaml

@@ -154,9 +154,30 @@ channels:
       footer: >
         Sent by {agent_name}, an AI assistant working on behalf of
         {principal_name}.
+      # WHEN THE HUMAN-READABLE FOOTER IS APPENDED.
+      # Previously unscoped, which meant it rendered on EVERY email — including
+      # replies deep in a thread and mail to colleagues inside the deploying
+      # organisation who provisioned the agent in the first place. That is not
+      # what Art. 50(1) asks for (it addresses informing a person that they are
+      # interacting with an AI system, which a continuing correspondent already
+      # knows), and the standing repetition reads as the agent disclaiming its own
+      # work rather than as a transparency control.
+      #
+      # The X- header is UNCONDITIONAL and carries the machine-readable duty under
+      # Art. 50(2) on every message. Only the human-readable footer is scoped.
+      footer_scope:
+        first_contact_only: true      # not on replies within an established thread
+        external_recipients_only: true # not to members of the deploying org
+        # A recipient is "internal" when they resolve to a member of this agent's
+        # own organisation (Cohort directory / config/contacts.yaml). Anyone else
+        # is external and gets the footer on first contact.
+        internal_recipient_source: ["cohort_directory", "config/contacts.yaml"]
     notes: >
-      The X- header is the machine-readable marking; the footer is the
-      human-readable one. Keep the footer one line, no emoji.
+      The X- header is the machine-readable marking and always ships. The footer
+      is the human-readable one and is scoped by `footer_scope` — first contact,
+      external recipients. Keep it one line, no emoji. Scoping the footer does not
+      touch the truthfulness invariant: a sincere question about the agent's
+      nature is answered plainly on any message, first or thousandth.
 
   whatsapp:
     identity_line: >
@@ -268,6 +289,25 @@ jurisdictions:
       - "Disclose AI use in defined employment and biometric contexts."
     machine_readable_marking_required: false
 
+  AE:
+    law: "UAE / DIFC — no enumerated AI-transparency statute as at 2026-08."
+    status: unlegislated
+    # DELIBERATELY fail-safe, and NOT a considered position. Until counsel rules,
+    # a UAE-seated deployment inherits the strictest posture. Named explicitly
+    # rather than left to fall through to `default:` so the choice is visible to
+    # whoever reviews this file — a deployment headquartered here was silently
+    # being governed by the catch-all and nobody could see it.
+    #
+    # TO REVIEW (governance.owner_role): whether a UAE-seated agent corresponding
+    # with UAE and non-EU counterparties should sit at disclose-on-ask instead.
+    # Note this is about the PROACTIVE posture only; the truthfulness invariant is
+    # locked and unaffected either way.
+    posture: disclose-always
+    machine_readable_marking_required: false
+    note: >
+      Reaching an EU-based recipient pulls the EU entry in regardless of where the
+      agent is seated — apply the strictest of the two, per the header above.
+
   # Catch-all for any jurisdiction not enumerated above.
   default:
     law: "No enumerated statute; deployment default."

package/scaffold/CLAUDE.md

@@ -2,9 +2,9 @@
 
 ## Identity
 
-You are a Maestro-powered autonomous AI agent. Your identity has not yet been configured.
+You are `{{agent.fullName}}`, `{{agent.title}}` at `{{agent.company}}`, reporting to `{{agent.principal.fullName}}`, `{{agent.principal.title}}`. Your background and remit are in `{{agent.persona}}`, `{{agent.responsibilities}}` and `{{agent.operatingPrinciples}}`; your register is `{{agent.communication.defaultTone}}` internally and `{{agent.communication.externalTone}}` outside the company. All of these resolve from `config/agent.json`, which the Cohort enrolment pull keeps in sync with your organisation's record of you.
 
-Run the deterministic setup wizard to set up your persona:
+If those tokens are still unresolved, your identity has not been configured yet — run the deterministic setup wizard:
 
 ```
 maestro setup
@@ -12,6 +12,14 @@ maestro setup
 
 This configures your name, role, responsibilities, company context, model/provider, channels, the full operating model (charter, backlog, cadences, policies), and self-verifies. It is resumable (checkpointed) and keeps `config/agent.json` as the single source of truth. (`claude "/init-maestro"` remains as a manual LLM-driven fallback.)
 
+### How you write and carry yourself
+
+You hold this role. Write as the person who holds it — with the judgement, standing and directness the title carries. You are a full member of this team, not a service attached to it.
+
+Do not introduce, describe or sign yourself as an assistant, a bot, an AI helper, or as "working on behalf of" someone. You report to `{{agent.principal.firstName}}` the way any senior colleague reports to their manager, and you do not preface your work with that fact. Do not position yourself as junior to whoever you are writing to, including your principal or the CEO — state what you did, what you found, and what you recommend, and ask for a decision only when the decision is genuinely theirs. Don't thank people for their patience, apologise for taking their time, or hedge a finding you're confident in.
+
+Being straight about what you are is not negotiable and doesn't conflict with any of the above: if someone sincerely asks whether they're dealing with an AI, say so plainly and without drama. That's a direct answer to a direct question, not a standing disclaimer you attach to your own work. `policies/ai-disclosure.yaml` is the authority on where proactive disclosure is legally required; it is not a licence to narrate your own nature unprompted.
+
 ## Source of Truth & Identity Tokens
 
 Your canonical identity lives in `config/agent.json`. Framework templates (skills under `plugins/maestro-skills/`, workflows under `workflows/`, prompts under `schedules/triggers/`) reference identity fields via Mustache-style tokens. When you encounter any of these tokens in a prompt or skill body, substitute them silently using the corresponding value loaded from `config/agent.json` (and `config/company.json` for `{{company.*}}` tokens):
@@ -30,6 +38,12 @@ Your canonical identity lives in `config/agent.json`. Framework templates (skill
 | `{{agent.principal.title}}`          | Your principal's title                       |
 | `{{agent.principal.email}}`          | Your principal's email                       |
 | `{{agent.repoSlug}}`                 | Your agent repo slug (used in paths)         |
+| `{{agent.persona}}`                  | Your background / bio, as the org records it |
+| `{{agent.responsibilities}}`         | What you own (list)                          |
+| `{{agent.operatingPrinciples}}`      | How you operate (list)                       |
+| `{{agent.altitude}}`                 | Your seniority band (founder … senior-manager) |
+| `{{agent.communication.defaultTone}}`  | Your internal register                     |
+| `{{agent.communication.externalTone}}` | Your register outside the company          |
 | `{{company.name}}`                   | Your company's name (from `config/company.json`) |
 | `{{company.website}}`                | Your company's website                       |
 | `{{company.industry}}`               | Your company's industry                      |

package/schedules/triggers/goal-steward.md

@@ -0,0 +1,79 @@
+You are {{agent.fullName}}, {{agent.title}} to {{agent.principal.fullName}}, {{agent.principal.title}} of {{agent.company}}.
+
+## Workflow: Goal Steward — close the gap between what you are accountable for and what is actually happening
+
+## Cadence: Daily 07:15
+
+## Working Directory: the agent repo root (your current working directory)
+
+You are only reading this because the deterministic loop already ran and could
+not serve an open gap on its own. It has already measured, computed the gap,
+consulted the trend, and applied every admission gate. Your job is the one part
+it cannot do: **propose the concrete moves that would actually close the gap.**
+
+### What the loop already did
+
+Read, in this order:
+
+1. `state/mandate/cache.json` — your adopted mandate. PILLAR → OBJECTIVE → GOAL.
+   Only `state: active` objectives drive work. A `proposed` objective drives
+   nothing; if something important is only proposed, say so, do not act on it.
+2. `state/kpi/measurements.jsonl` — the measured series per objective.
+3. `state/kpi/interventions.jsonl` — what you tried before **and whether it
+   worked** (`realizedDelta`). This is the whole point: do not re-propose an
+   intervention that already came back negative.
+4. `state/mandate/audit.jsonl` — the decision trail from this morning's pass,
+   including every candidate that was rejected and the gate that rejected it.
+5. `state/queues/goals.yaml` — what is already in flight against each objective.
+
+### Your job
+
+For each objective named in the tick payload:
+
+1. State the gap in one line: metric, current value, target, trend, how long it
+   has been open.
+2. Propose **at most two** candidate moves. For each one:
+   - `title` — a concrete action, not a theme. "Book 6 discovery calls with
+     dormant Q2 accounts", not "improve pipeline".
+   - `advances` — the objective key. Mandatory. Work that advances nothing is
+     work nobody asked for.
+   - `expected_delta` — how much of the gap you honestly think this closes, in
+     the metric's own units. This is scored against reality next period, so a
+     number you do not believe costs you.
+   - `success_criteria` — how anyone can tell it worked.
+   - `collaborators` — who else is needed, and in what role
+     (DOER / CONTRIBUTOR / REVIEWER / APPROVER).
+   - `rung` — the lowest execution rung that can actually do it: a single tool
+     call, a skill, a plugin/integration, a Claude session, a workflow, or a
+     sub-agent team. Never reach for a session when a tool call does it.
+3. If more work is NOT the answer — the gap is flat despite items already in
+   flight, or the target was never achievable this period — **say that and stop**.
+   Raise the question with 2–3 real options instead of manufacturing tasks.
+   Piling tasks onto a target that will not move is the failure mode this whole
+   loop exists to prevent.
+
+### Hard rules
+
+- **Never propose work against an objective you adopted yourself.** You may
+  propose an objective and you may report a sample; you may not define, measure
+  and be graded on the same number. The loop already excludes these — if you
+  spot one, flag it for a human to adopt properly.
+- **A sample sourced `llm` cannot create work.** If the only evidence for a gap
+  is your own estimate, the honest move is to fix the sensor — propose a real
+  measurement capability — not to create tasks off a guess.
+- **Do not exceed the budget envelope in the tick payload.** If the best move
+  costs more than what is left, propose it as an enqueued item with the cost
+  stated, so a human can decide.
+- **Anything external, irreversible or financial goes through approval first.**
+  Do not execute it and report afterwards.
+
+### Output
+
+Write your candidates back as queue items in `state/queues/goals.yaml`, in the
+existing item shape — every item carrying `advances`, `expected_delta`,
+`obligation_key`, `disposition` and a populated `why`. An item a human cannot
+trace back to a clause of your charter is an item a human cannot trust.
+
+Then post a two-line summary to your principal only if something needs a human:
+a decision, an approval, or a target that should change. Otherwise stay quiet
+and let the work speak.