@cohortapp/agent-sdk 2.3.0

package/lib/setup/sections/enrich.mjs

@@ -0,0 +1,138 @@
+/**
+ * sections/enrich.mjs — LLM enrichment of company-specific prose slots.  (order 70)
+ *
+ * Iterates the enumerated enrichable units that still need filling and calls
+ * lib/setup/enrich.enrichField (one `claude --print` per unit). Honors
+ * `--no-enrich` (skips entirely, leaving deterministic skeletons) and is
+ * fail-open: any unit that fails is marked `pending` and the section continues.
+ *
+ * The spawn is injectable via `ctx.enrichSpawn` so the wizard's integration
+ * tests stay hermetic.
+ *
+ * @module lib/setup/sections/enrich
+ */
+
+"use strict";
+
+import { join } from "node:path";
+import { existsSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { enrichField, ENRICHABLE } from "../enrich.mjs";
+import { readAgentJson } from "../sot.mjs";
+import { loadProgress } from "../state.mjs";
+import * as io from "../io.mjs";
+
+/**
+ * Substitute enriched company-slot values into the deterministic charter body,
+ * clearing the placeholder markers (mandate stub, KPI "TBD" targets, stakeholder
+ * "_TBD_") so the completeness gate's findCharterPlaceholders sees none.
+ * @param {string} agentRoot
+ * @param {{mandate?:string, kpiTarget?:string, stakeholderContact?:string}} value
+ */
+function applyCharterEnrichment(agentRoot, value) {
+  const p = join(agentRoot, "config", "operating-charter.md");
+  if (!existsSync(p)) return;
+  let body = readFileSync(p, "utf-8");
+  const mandate = (value.mandate || "").trim();
+  const kpi = (value.kpiTarget || "set against the company baseline this quarter").trim();
+  const contact = (value.stakeholderContact || "named at onboarding").trim();
+
+  if (mandate) {
+    body = body.replace(
+      /_Mandate \(enrich at init\):[^_]*_/,
+      mandate.replace(/\$/g, "$$$$")
+    );
+  }
+  // KPI targets: "_target: TBD at init_" → concrete phrasing.
+  body = body.replace(/_target: TBD at init_/g, `target: ${kpi}`);
+  // Stakeholder named contacts: "| _TBD_ |" → concrete phrasing.
+  body = body.replace(/_TBD_/g, contact);
+  // Any remaining bare "TBD" (defensive) — replace with the KPI phrasing.
+  body = body.replace(/\bTBD\b/g, kpi);
+
+  const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, body, "utf-8");
+  renameSync(tmp, p);
+}
+
+function emptyArr(v) { return !Array.isArray(v) || v.length === 0; }
+function emptyStr(v) { return v === undefined || v === null || String(v).trim() === ""; }
+
+function companyDescriptionEmpty(agentRoot) {
+  const p = join(agentRoot, "config", "company.json");
+  try { const c = existsSync(p) ? JSON.parse(readFileSync(p, "utf-8")) : {}; return emptyStr(c.description); }
+  catch { return true; }
+}
+
+async function charterHasPlaceholders(agentRoot, maestroRoot) {
+  const p = join(agentRoot, "config", "operating-charter.md");
+  if (!existsSync(p)) return false;
+  try {
+    const { findCharterPlaceholders } = await import(pathToFileURL(join(maestroRoot, "lib", "charter.mjs")).href);
+    return findCharterPlaceholders(readFileSync(p, "utf-8")).length > 0;
+  } catch { return false; }
+}
+
+/** Which enrichable units still need work, given current on-disk state. */
+export async function pendingUnits(agentRoot, maestroRoot) {
+  const id = readAgentJson(agentRoot) || {};
+  const units = [];
+  if (emptyStr(id.persona)) units.push("agent.persona");
+  if (emptyArr(id.responsibilities)) units.push("agent.responsibilities");
+  if (emptyArr(id.operatingPrinciples)) units.push("agent.operatingPrinciples");
+  if (companyDescriptionEmpty(agentRoot)) units.push("company.description");
+  if (await charterHasPlaceholders(agentRoot, maestroRoot)) units.push("charter.companySlots");
+  return units.filter((u) => u in ENRICHABLE);
+}
+
+export default {
+  id: "enrich",
+  label: "LLM enrichment (company-specific prose)",
+  order: 70,
+
+  async detect(ctx) {
+    if (ctx.flags && ctx.flags.noEnrich) return { status: "complete", summary: "skipped (--no-enrich)" };
+    const pending = await pendingUnits(ctx.agentRoot, ctx.maestroRoot);
+    if (pending.length === 0) return { status: "complete", summary: "all prose slots filled" };
+    return { status: "partial", missing: pending };
+  },
+
+  async prompt() { /* non-interactive */ },
+
+  async apply(ctx) {
+    if (ctx.flags && ctx.flags.noEnrich) {
+      io.note("Enrichment skipped (--no-enrich) — deterministic skeletons left in place.", { dim: true });
+      return;
+    }
+    const units = await pendingUnits(ctx.agentRoot, ctx.maestroRoot);
+    if (units.length === 0) return;
+    const spawn = ctx.enrichSpawn; // undefined → real claude spawn inside enrichField
+    let enriched = 0, pending = 0;
+    for (const unit of units) {
+      const opts = spawn ? { spawn } : {};
+      const res = await enrichField(ctx.agentRoot, unit, opts);
+      if (res.status === "enriched") {
+        enriched++;
+        // charter company-slots: substitute the enriched values into the
+        // deterministic charter body (clears the TBD / mandate placeholders).
+        if (unit === "charter.companySlots" && res.value) {
+          try { applyCharterEnrichment(ctx.agentRoot, res.value); } catch { /* fail-open */ }
+        }
+      } else {
+        pending++;
+      }
+    }
+    if (ctx.flags && ctx.flags.verbose) io.note(`enrichment: ${enriched} filled, ${pending} left as skeleton`, { dim: true });
+  },
+
+  async verify(ctx) {
+    // Enrichment is best-effort — a pending unit is NOT a hard failure (the
+    // deterministic skeleton is still a real artifact). Report as informational.
+    const ledger = loadProgress(ctx.agentRoot).enrich || {};
+    const pendingCount = Object.values(ledger).filter((e) => e && e.status === "pending").length;
+    return {
+      ok: true,
+      checks: [{ name: `enrichment (${pendingCount} unit(s) left as skeleton)`, ok: true, remedy: pendingCount ? "re-run `maestro setup --only enrich` to retry" : undefined }],
+    };
+  },
+};

package/lib/setup/sections/identity.mjs

@@ -0,0 +1,182 @@
+/**
+ * sections/identity.mjs — collect the agent's identity, write the SoT, ensure
+ * the agent.ts wrapper, and generate config/agent.env.  (order 10)
+ *
+ * SetupSection contract (design §3.3):
+ *   { id, label, order, detect, prompt, apply, verify }
+ *
+ * @module lib/setup/sections/identity
+ */
+
+"use strict";
+
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import * as io from "../io.mjs";
+import { readAgentJson, mergeAgentJson, ensureSotWrapper } from "../sot.mjs";
+import { isPlaceholder } from "../completeness.mjs";
+import { runGenerator } from "../run-generator.mjs";
+import { cohortPullEnv, pullAndPlan } from "../enroll-from-cohort.mjs";
+import { fetchSelfProfile } from "../../org/client.mjs";
+
+const FUNCTIONS = [
+  { value: "executive-operator", label: "Executive operator (chief of staff / COO-style)" },
+  { value: "technical-leader", label: "Technical leader (eng / platform / CTO-style)" },
+  { value: "commercial-leader", label: "Commercial leader (sales / GTM / revenue)" },
+  { value: "people-leader", label: "People leader (HR / talent / org)" },
+  { value: "finance-leader", label: "Finance leader (finance / corp dev / capital)" },
+  { value: "compliance-leader", label: "Compliance leader (legal / risk / regulatory)" },
+];
+const ALTITUDES = [
+  { value: "c-suite", label: "C-suite" },
+  { value: "svp", label: "SVP" },
+  { value: "vp", label: "VP" },
+  { value: "senior-manager", label: "Senior manager" },
+];
+
+/**
+ * When the Cohort pull env (COHORT_API_KEY + COHORT_ORG_ID, optional
+ * COHORT_AGENT_ID) is present, PULL this agent's record and merge it into
+ * config/agent.json BEFORE we prompt — so the prompts default to (and thus
+ * CONFIRM) the org-authoritative values rather than starting from scratch. A
+ * locally-customised value is never clobbered (mergeProfilePatch drops it unless
+ * --force). Fail-open + non-blocking: a missing var / unreachable server is a
+ * no-op and the manual prompts stand. Returns the pull plan (or null).
+ * @param {string} agentRoot
+ * @returns {Promise<object|null>}
+ */
+async function maybePullProfile(agentRoot) {
+  if (!cohortPullEnv().enabled) return null;
+  try {
+    const plan = await pullAndPlan({ agentRoot, fetchSelfProfileImpl: fetchSelfProfile });
+    if (plan && plan.pulled && plan.patch && Object.keys(plan.patch).length) {
+      mergeAgentJson(agentRoot, plan.patch);
+    }
+    return plan;
+  } catch {
+    return null;
+  }
+}
+
+async function archetypeResolves(agentRoot, maestroRoot) {
+  try {
+    const arch = await import(pathToFileURL(join(maestroRoot, "lib", "archetype.mjs")).href);
+    const id = readAgentJson(agentRoot) || {};
+    const sel = id.function && id.altitude
+      ? { function: id.function, altitude: id.altitude }
+      : arch.migrateLegacyArchetype(id.archetype);
+    if (!sel) return { ok: false, label: null };
+    const p = await arch.resolveArchetype(sel);
+    return { ok: true, label: p.label };
+  } catch (e) {
+    return { ok: false, label: null, error: e && e.message ? e.message : String(e) };
+  }
+}
+
+export default {
+  id: "identity",
+  label: "Agent identity",
+  order: 10,
+
+  async detect(ctx) {
+    const id = readAgentJson(ctx.agentRoot);
+    if (!id) return { status: "unconfigured", missing: ["config/agent.json"] };
+    const fields = ["firstName", "lastName", "title", "email"];
+    const missing = fields.filter((f) => isPlaceholder(id[f]));
+    const arch = await archetypeResolves(ctx.agentRoot, ctx.maestroRoot);
+    if (!arch.ok) missing.push("archetype");
+    if (missing.length === 0) {
+      return { status: "complete", summary: `${id.fullName || id.firstName} — ${id.title} (${arch.label})` };
+    }
+    return { status: missing.length === fields.length + 1 ? "unconfigured" : "partial", missing };
+  },
+
+  async prompt(ctx) {
+    // Cohort-driven setup: pull the org record first so the prompts CONFIRM the
+    // pulled values (they become the defaults below) instead of starting blank.
+    const plan = await maybePullProfile(ctx.agentRoot);
+    if (plan && plan.pulled) {
+      const n = plan.changes ? plan.changes.length : 0;
+      io.note(`Pulled this agent's profile from Cohort (${n} field${n === 1 ? "" : "s"}). Confirm or edit below.`, { dim: true });
+    }
+    const cur = readAgentJson(ctx.agentRoot) || {};
+    const firstName = await io.text(ctx, { message: "Agent first name", key: "firstName", default: placeholderless(cur.firstName) });
+    const lastName = await io.text(ctx, { message: "Agent last name", key: "lastName", default: placeholderless(cur.lastName) });
+    const title = await io.text(ctx, { message: "Agent title / role", key: "title", default: placeholderless(cur.title) });
+    const email = await io.text(ctx, { message: "Agent work email", key: "email", default: placeholderless(cur.email) });
+    const fn = await io.select(ctx, { message: "Function (what the agent owns)", key: "function", choices: FUNCTIONS, default: cur.function || "executive-operator" });
+    const altitude = await io.select(ctx, { message: "Altitude (seniority)", key: "altitude", choices: ALTITUDES, default: cur.altitude || "c-suite" });
+    const principalName = await io.text(ctx, { message: "Principal full name (who the agent reports to)", key: "principalName", default: (cur.principal && cur.principal.fullName) || "" });
+    const principalTitle = await io.text(ctx, { message: "Principal title", key: "principalTitle", default: (cur.principal && cur.principal.title) || "" });
+    const principalEmail = await io.text(ctx, { message: "Principal email", key: "principalEmail", default: (cur.principal && cur.principal.email) || "" });
+
+    ctx.answers.identity = { firstName, lastName, title, email, function: fn, altitude, principalName, principalTitle, principalEmail };
+  },
+
+  async apply(ctx) {
+    // Idempotent safety net: ensure the Cohort pull has landed even on an
+    // apply-only path (e.g. headless re-run where prompt() was a no-op). Pulled
+    // values are merged into config/agent.json; they never clobber local edits.
+    await maybePullProfile(ctx.agentRoot);
+    const a = (ctx.answers && ctx.answers.identity) || pullFromAnswers(ctx);
+    if (!a) {
+      // No prompt answers (headless with no --answers) but a pull may have just
+      // populated config/agent.json — still run the downstream generators so the
+      // archetype + wrapper + env reflect the pulled identity.
+      if (cohortPullEnv().enabled) {
+        runGenerator("init-archetype.mjs", ctx.agentRoot, { maestroRoot: ctx.maestroRoot });
+        ensureSotWrapper(ctx.agentRoot);
+        runGenerator("generate-agent-env.mjs", ctx.agentRoot, { maestroRoot: ctx.maestroRoot });
+      }
+      return;
+    }
+    const fullName = [a.firstName, a.lastName].filter(Boolean).join(" ").trim();
+    const [pf, ...pr] = String(a.principalName || "").trim().split(/\s+/);
+    const principalLast = pr.join(" ");
+    const patch = {
+      firstName: a.firstName, lastName: a.lastName, fullName, title: a.title, email: a.email,
+      function: a.function, altitude: a.altitude,
+      principal: {
+        firstName: pf || "", lastName: principalLast || "",
+        fullName: String(a.principalName || "").trim(),
+        title: a.principalTitle || "", email: a.principalEmail || "",
+      },
+    };
+    mergeAgentJson(ctx.agentRoot, patch);
+    // Normalise archetype (function/altitude → archetype) via init-archetype.
+    runGenerator("init-archetype.mjs", ctx.agentRoot, { maestroRoot: ctx.maestroRoot });
+    // Born-unified: ensure config/agent.ts is the thin wrapper.
+    ensureSotWrapper(ctx.agentRoot);
+    // Regenerate the shell env file.
+    runGenerator("generate-agent-env.mjs", ctx.agentRoot, { maestroRoot: ctx.maestroRoot });
+  },
+
+  async verify(ctx) {
+    const checks = [];
+    const id = readAgentJson(ctx.agentRoot);
+    const idOk = !!id && ["firstName", "lastName", "title", "email"].every((f) => !isPlaceholder(id[f]));
+    checks.push({ name: "identity populated", ok: idOk, remedy: idOk ? undefined : "run `maestro setup --only identity`" });
+    const arch = await archetypeResolves(ctx.agentRoot, ctx.maestroRoot);
+    checks.push({ name: "archetype resolves", ok: arch.ok, remedy: arch.ok ? undefined : "set a valid function × altitude" });
+    const tsPath = join(ctx.agentRoot, "config", "agent.ts");
+    const wrapperOk = existsSync(tsPath) && /agent\.json/.test(readFileSync(tsPath, "utf-8"));
+    checks.push({ name: "agent.ts is SoT wrapper", ok: wrapperOk, remedy: wrapperOk ? undefined : "ensureSotWrapper failed" });
+    return { ok: checks.every((c) => c.ok), checks };
+  },
+};
+
+function placeholderless(v) { return isPlaceholder(v) ? "" : v; }
+
+/** Allow `--answers` files to supply flat keys (no nested identity object). */
+function pullFromAnswers(ctx) {
+  const ans = ctx.answers || {};
+  if (ans.identity) return ans.identity;
+  const flat = ["firstName", "lastName", "title", "email", "function", "altitude", "principalName", "principalTitle", "principalEmail"];
+  if (flat.some((k) => k in ans)) {
+    const out = {};
+    for (const k of flat) out[k] = ans[k];
+    return out;
+  }
+  return null;
+}

package/lib/setup/sections/identity.test.mjs

@@ -0,0 +1,140 @@
+/**
+ * identity.test.mjs — Cohort-driven setup pull in the identity section.
+ *
+ * Focuses on the pull seam added for Cohort-driven setup: when COHORT_API_KEY +
+ * COHORT_ORG_ID are present, prompt()/apply() PULL the agent's record and merge
+ * it into config/agent.json so the prompts CONFIRM (rather than start blank); a
+ * locally-customised value is protected unless --force; absent vars leave the
+ * manual path unchanged. The real client.fetchSelfProfile is exercised via an
+ * injected global fetch (no network).
+ *
+ * Run: node --test lib/setup/sections/identity.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import identity from "./identity.mjs";
+import { readAgentJson } from "../sot.mjs";
+import * as io from "../io.mjs";
+
+const MAESTRO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+
+function tmpRoot() {
+  const root = mkdtempSync(join(tmpdir(), "maestro-identity-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  return root;
+}
+function ctxFor(root, answers = {}) {
+  return { agentRoot: root, maestroRoot: MAESTRO_ROOT, flags: { headless: true }, answers, io };
+}
+function writeAgent(root, obj) {
+  writeFileSync(join(root, "config", "agent.json"), JSON.stringify(obj, null, 2) + "\n");
+}
+
+const PROFILE = {
+  slug: "robin", kind: "agent", displayName: "Robin Vega", firstName: "Robin", lastName: "Vega",
+  title: "VP Eng", team: "Platform", role: "engineering-lead", agentEmail: "robin@example.com",
+  supervisor: { displayName: "Layla Al-Masri", title: "CTO", email: "layla@example.com" },
+};
+
+function withCohortEnv(vars, fn) {
+  const keys = ["COHORT_API_KEY", "COHORT_ORG_ID", "COHORT_AGENT_ID", "COHORT_BASE"];
+  const saved = Object.fromEntries(keys.map((k) => [k, process.env[k]]));
+  for (const k of keys) delete process.env[k];
+  Object.assign(process.env, vars);
+  return Promise.resolve().then(fn).finally(() => {
+    for (const k of keys) { if (saved[k] === undefined) delete process.env[k]; else process.env[k] = saved[k]; }
+  });
+}
+
+function withFetch(impl, fn) {
+  const saved = globalThis.fetch;
+  globalThis.fetch = impl;
+  return Promise.resolve().then(fn).finally(() => { globalThis.fetch = saved; });
+}
+
+const okFetch = (sink) => async (url) => {
+  if (sink) sink.push(String(url));
+  return { ok: true, status: 200, headers: { get: () => undefined }, json: async () => PROFILE };
+};
+
+test("section shape: id/order=10/hooks", () => {
+  assert.equal(identity.id, "identity");
+  assert.equal(identity.order, 10);
+  for (const h of ["detect", "prompt", "apply", "verify"]) assert.equal(typeof identity[h], "function");
+});
+
+test("prompt: with COHORT_* env, pulls the profile into config/agent.json", async () => {
+  const root = tmpRoot();
+  writeAgent(root, { firstName: "UNCONFIGURED" });
+  const urls = [];
+  await withCohortEnv(
+    { COHORT_API_KEY: "k", COHORT_ORG_ID: "acme", COHORT_AGENT_ID: "robin", COHORT_BASE: "https://cohort.example" },
+    () => withFetch(okFetch(urls), async () => {
+      const ctx = ctxFor(root);
+      await identity.prompt(ctx);
+      // Headless prompt resolves the answers from the (now pulled) config defaults.
+      assert.equal(ctx.answers.identity.firstName, "Robin");
+      assert.equal(ctx.answers.identity.email, "robin@example.com");
+    })
+  );
+  assert.ok(urls.some((u) => u.includes("/api/v1/org/members/robin")), "members endpoint hit");
+  const id = readAgentJson(root);
+  assert.equal(id.firstName, "Robin", "placeholder overwritten by pull");
+  assert.equal(id.function, "technical-leader");
+});
+
+test("COHORT_AGENT_ID selects /org/members/<id>; absent selects whoami", async () => {
+  const root = tmpRoot();
+  const urls = [];
+  await withCohortEnv(
+    { COHORT_API_KEY: "k", COHORT_ORG_ID: "acme", COHORT_BASE: "https://cohort.example" },
+    () => withFetch(okFetch(urls), async () => {
+      await identity.prompt(ctxFor(root));
+    })
+  );
+  assert.ok(urls.some((u) => u.includes("/api/v1/org/whoami?orgId=acme")), "whoami endpoint hit when no agent id (org sent as the tenant pin, not a member slug)");
+});
+
+test("a local override is NOT clobbered by the pull (without --force)", async () => {
+  const root = tmpRoot();
+  writeAgent(root, { title: "My Custom Title", firstName: "" });
+  await withCohortEnv(
+    { COHORT_API_KEY: "k", COHORT_ORG_ID: "acme", COHORT_AGENT_ID: "robin", COHORT_BASE: "https://cohort.example" },
+    () => withFetch(okFetch(), async () => {
+      await identity.prompt(ctxFor(root));
+    })
+  );
+  const id = readAgentJson(root);
+  assert.equal(id.title, "My Custom Title", "operator title preserved");
+  assert.equal(id.firstName, "Robin", "empty field still filled from org");
+});
+
+test("absent COHORT_* env → no pull (manual path unchanged)", async () => {
+  const root = tmpRoot();
+  writeAgent(root, { firstName: "UNCONFIGURED" });
+  let fetched = false;
+  await withCohortEnv({}, () => withFetch(async () => { fetched = true; return { ok: true, status: 200, headers: { get: () => undefined }, json: async () => PROFILE }; }, async () => {
+    await identity.prompt(ctxFor(root));
+  }));
+  assert.equal(fetched, false, "no network call without the pull env");
+  assert.equal(readAgentJson(root).firstName, "UNCONFIGURED", "config unchanged");
+});
+
+test("pull is fail-open: a fetch error leaves config untouched", async () => {
+  const root = tmpRoot();
+  writeAgent(root, { firstName: "UNCONFIGURED" });
+  await withCohortEnv(
+    { COHORT_API_KEY: "k", COHORT_ORG_ID: "acme", COHORT_AGENT_ID: "robin", COHORT_BASE: "https://cohort.example" },
+    () => withFetch(async () => { throw new Error("network down"); }, async () => {
+      await identity.prompt(ctxFor(root)); // must not throw
+    })
+  );
+  assert.equal(readAgentJson(root).firstName, "UNCONFIGURED");
+});

package/lib/setup/sections/learning.mjs

@@ -0,0 +1,153 @@
+/**
+ * sections/learning.mjs — the self-learning loop (WS3, order 80).
+ *
+ * Cross-workstream seam (design §3.2): registered by dropping this file into
+ * sections/ (no core edit). It turns the autonomous skill-authoring loop on,
+ * seeds its runtime state (counters + the transcript search DB), and verifies
+ * the global Stop-hook the loop piggybacks on is wired.
+ *
+ * Order 80 (after enrich/tools, before verify) per design §3.2 / §4.
+ *
+ * Every hook is non-blocking under --headless: detect/apply/verify never read
+ * the TTY; prompt honours `io` headless resolution. Idempotent.
+ *
+ * @module lib/setup/sections/learning
+ */
+
+"use strict";
+
+import { join } from "node:path";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from "node:fs";
+import { homedir } from "node:os";
+import * as io from "../io.mjs";
+import { countersPath, emptyCounters } from "../../learning/counters.mjs";
+
+const CONFIG_REL = join("config", "learning.yaml");
+
+/** Is the loop enabled per the on-disk config? (absent file → default-enabled) */
+function configEnabled(agentRoot) {
+  const p = join(agentRoot, CONFIG_REL);
+  if (!existsSync(p)) return null; // unconfigured
+  try {
+    const body = readFileSync(p, "utf-8");
+    // Cheap scan to avoid a yaml dep in the wizard: an explicit `enabled: false`.
+    if (/^\s*enabled\s*:\s*false\b/m.test(body)) return false;
+    return true;
+  } catch {
+    return null;
+  }
+}
+
+/** Is the global maestro hook-runner wired into ~/.claude/settings.json? */
+export function hookWired() {
+  try {
+    const p = join(homedir(), ".claude", "settings.json");
+    if (!existsSync(p)) return false;
+    const body = readFileSync(p, "utf-8");
+    // The collective + learning loop share the one hook entry point.
+    return /collective\/hook-runner\.mjs/.test(body);
+  } catch {
+    return false;
+  }
+}
+
+/** Write config/learning.yaml from the scaffold (or a minimal enabled stub). */
+function ensureConfig(ctx, enabled) {
+  const dst = join(ctx.agentRoot, CONFIG_REL);
+  if (existsSync(dst)) {
+    // Respect an explicit operator choice to disable, but don't rewrite an
+    // existing file the operator may have customised.
+    if (enabled === false) flipEnabled(dst, false);
+    return;
+  }
+  mkdirSync(join(ctx.agentRoot, "config"), { recursive: true });
+  const scaffold = join(ctx.maestroRoot, "scaffold", "config", "learning.yaml");
+  if (existsSync(scaffold)) {
+    try { copyFileSync(scaffold, dst); } catch { writeStub(dst, enabled); }
+  } else {
+    writeStub(dst, enabled);
+  }
+  if (enabled === false) flipEnabled(dst, false);
+}
+
+function writeStub(dst, enabled) {
+  writeFileSync(dst, `# config/learning.yaml — Self-Learning Loop (WS3)\nenabled: ${enabled === false ? "false" : "true"}\nminTurns: 4\nreviewModel: sonnet\n`);
+}
+
+function flipEnabled(dst, value) {
+  try {
+    let body = readFileSync(dst, "utf-8");
+    if (/^\s*enabled\s*:/m.test(body)) body = body.replace(/^\s*enabled\s*:.*$/m, `enabled: ${value}`);
+    else body = `enabled: ${value}\n` + body;
+    writeFileSync(dst, body);
+  } catch { /* fail-open */ }
+}
+
+/** Seed state/learning/counters.json if absent. */
+function seedCounters(agentRoot) {
+  const p = countersPath(agentRoot);
+  if (existsSync(p)) return;
+  try {
+    mkdirSync(join(agentRoot, "state", "learning"), { recursive: true });
+    writeFileSync(p, JSON.stringify(emptyCounters(), null, 2) + "\n");
+  } catch { /* fail-open */ }
+}
+
+export default {
+  id: "learning",
+  label: "Self-learning loop",
+  order: 80,
+
+  async detect(ctx) {
+    const enabled = configEnabled(ctx.agentRoot);
+    if (enabled === null) return { status: "unconfigured", missing: ["config/learning.yaml"] };
+    if (enabled === false) return { status: "complete", summary: "self-learning disabled (config)" };
+    const missing = [];
+    if (!existsSync(countersPath(ctx.agentRoot))) missing.push("state/learning/counters.json");
+    if (!hookWired()) missing.push("global hook (run `maestro global-setup`)");
+    if (missing.length === 0) return { status: "complete", summary: "self-learning enabled + wired" };
+    return { status: "partial", summary: "self-learning enabled", missing };
+  },
+
+  async prompt(ctx) {
+    const cur = configEnabled(ctx.agentRoot);
+    const on = await io.confirm(ctx, {
+      message: "Enable the self-learning loop (the agent autonomously authors & prunes its own skills)?",
+      key: "learningEnabled",
+      default: cur !== false,
+    });
+    ctx.answers.learningEnabled = on;
+  },
+
+  async apply(ctx) {
+    const enabled = ctx.answers && typeof ctx.answers.learningEnabled === "boolean"
+      ? ctx.answers.learningEnabled
+      : (configEnabled(ctx.agentRoot) !== false);
+    ensureConfig(ctx, enabled);
+    if (enabled === false) return;
+    seedCounters(ctx.agentRoot);
+    // Seed the transcript search DB from any existing session logs (best-effort;
+    // the Stop-hook worker + daily catch-up keep it warm thereafter).
+    try {
+      const sidx = await import("../../learning/session-index.mjs");
+      await sidx.ingestAll({ agentRoot: ctx.agentRoot });
+    } catch { /* DB is on-demand; a failed seed is non-fatal */ }
+  },
+
+  async verify(ctx) {
+    const checks = [];
+    const enabled = configEnabled(ctx.agentRoot);
+    checks.push({ name: "config/learning.yaml present", ok: enabled !== null, remedy: enabled !== null ? undefined : "run `maestro setup --only learning`" });
+    if (enabled === false) {
+      checks.push({ name: "self-learning disabled (by config)", ok: true });
+      return { ok: true, checks };
+    }
+    const countersOk = existsSync(countersPath(ctx.agentRoot));
+    checks.push({ name: "counters seeded", ok: countersOk, remedy: countersOk ? undefined : "seed state/learning/counters.json" });
+    // The hook is a SOFT check: on a fresh repo / CI / non-agent machine it
+    // isn't wired yet, which is expected — surface a remedy but don't hard-fail.
+    const wired = hookWired();
+    checks.push({ name: "global Stop-hook wired", ok: true, remedy: wired ? undefined : "run `maestro global-setup` to enable on this machine" });
+    return { ok: checks.every((c) => c.ok), checks };
+  },
+};