@awebai/oats 0.22.0

package/capabilities/oats-linear/test/oats-linear.test.mjs

@@ -0,0 +1,168 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const DIR = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const CLI = join(DIR, "bin", "oats-linear.mjs");
+const HOOK = join(DIR, "bin", "oats-linear-hook.mjs");
+
+function run(script, args = [], env = {}) {
+  return new Promise((done) => {
+    const child = spawn(process.execPath, [script, ...args], {
+      env: { ...process.env, ...env },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stderr.on("data", (chunk) => { stderr += chunk; });
+    child.on("close", (code) => done({ code, stdout, stderr }));
+  });
+}
+
+async function mockApi(responder, fn) {
+  const requests = [];
+  const server = createServer(async (request, response) => {
+    let body = "";
+    for await (const chunk of request) body += chunk;
+    const parsed = JSON.parse(body);
+    requests.push({ headers: request.headers, ...parsed });
+    const payload = await responder(parsed, requests);
+    response.writeHead(payload.status || 200, { "content-type": "application/json" });
+    response.end(JSON.stringify(payload.body || payload));
+  });
+  await new Promise((ready) => server.listen(0, "127.0.0.1", ready));
+  const url = `http://127.0.0.1:${server.address().port}/graphql`;
+  try { await fn({ url, requests }); }
+  finally { await new Promise((closed) => server.close(closed)); }
+}
+
+const team = { id: "team-1", key: "ENG", name: "Engineering" };
+const issue = {
+  id: "issue-1", identifier: "ENG-1", title: "Test issue", description: "body",
+  url: "https://linear.app/issue/ENG-1", priority: 0, priorityLabel: "No priority",
+  team, state: { id: "started-1", name: "In Progress", type: "started" },
+  project: null, parent: null, assignee: { id: "human-1", name: "Human", email: "human@example.com" },
+  labels: { nodes: [] },
+};
+
+function operation(query) { return query.match(/(?:query|mutation)\s+(\w+)/)?.[1]; }
+
+test("missing API key fails once with setup guidance", async () => {
+  const result = await run(CLI, ["auth"], { LINEAR_API_KEY: "" });
+  assert.equal(result.code, 1);
+  assert.match(result.stderr, /LINEAR_API_KEY is not set/);
+  assert.match(result.stderr, /Security & access/);
+});
+
+test("auth uses the personal-key Authorization header", async () => {
+  await mockApi(() => ({ data: {
+    viewer: { id: "user-1", name: "Human", email: "human@example.com" },
+    organization: { id: "org-1", name: "Acme", urlKey: "acme" },
+  } }), async ({ url, requests }) => {
+    const result = await run(CLI, ["auth"], { LINEAR_API_KEY: "secret-key", LINEAR_API_URL: url });
+    assert.equal(result.code, 0, result.stderr);
+    assert.equal(JSON.parse(result.stdout).authenticated, true);
+    assert.equal(requests[0].headers.authorization, "secret-key");
+    assert.equal(operation(requests[0].query), "OatsLinearAuth");
+  });
+});
+
+test("issue list builds an open agent/project filter", async () => {
+  await mockApi(({ query }) => {
+    if (operation(query) === "OatsLinearTeam") return { data: { teams: { nodes: [team] } } };
+    if (operation(query) === "OatsLinearProjects") return { data: { projects: { nodes: [
+      { id: "project-1", name: "Agent Platform", slugId: "agent-platform", status: { id: "ps-1", name: "Started", type: "started" }, teams: { nodes: [team] } },
+    ] } } };
+    if (operation(query) === "OatsLinearIssues") return { data: { issues: { nodes: [issue], pageInfo: { hasNextPage: false, endCursor: null } } } };
+    throw new Error(`unexpected operation ${operation(query)}`);
+  }, async ({ url, requests }) => {
+    const result = await run(CLI, ["issue", "list", "--team", "ENG", "--agent", "worker-1", "--project", "Agent Platform"], {
+      LINEAR_API_KEY: "key", LINEAR_API_URL: url,
+    });
+    assert.equal(result.code, 0, result.stderr);
+    const listRequest = requests.find((request) => operation(request.query) === "OatsLinearIssues");
+    assert.deepEqual(listRequest.variables.filter, {
+      team: { id: { eq: "team-1" } },
+      state: { type: { nin: ["completed", "canceled", "duplicate"] } },
+      labels: { some: { name: { eqIgnoreCase: "agent-worker-1" } } },
+      project: { id: { eq: "project-1" } },
+    });
+  });
+});
+
+test("issue create provisions the agent label and records identity", async () => {
+  await mockApi(({ query, variables }) => {
+    const op = operation(query);
+    if (op === "OatsLinearTeam") return { data: { teams: { nodes: [team] } } };
+    if (op === "OatsLinearLabels") return { data: { issueLabels: { nodes: [] } } };
+    if (op === "OatsLinearCreateLabel") return { data: { issueLabelCreate: {
+      success: true, issueLabel: { id: "label-1", name: variables.input.name, color: "#5E6AD2", team },
+    } } };
+    if (op === "OatsLinearIssueCreate") return { data: { issueCreate: { success: true, issue } } };
+    throw new Error(`unexpected operation ${op}`);
+  }, async ({ url, requests }) => {
+    const result = await run(CLI, ["issue", "create", "--team", "ENG", "--title", "Bounded work", "--description", "Acceptance", "--agent", "worker-1"], {
+      LINEAR_API_KEY: "key", LINEAR_API_URL: url,
+    });
+    assert.equal(result.code, 0, result.stderr);
+    const create = requests.find((request) => operation(request.query) === "OatsLinearIssueCreate");
+    assert.equal(create.variables.input.teamId, "team-1");
+    assert.deepEqual(create.variables.input.labelIds, ["label-1"]);
+    assert.match(create.variables.input.description, /Acceptance\n\n---\nAgent: worker-1/);
+  });
+});
+
+test("terminal transitions require explicit authorization", async () => {
+  await mockApi(({ query }) => {
+    const op = operation(query);
+    if (op === "OatsLinearIssue") return { data: { issue } };
+    if (op === "OatsLinearStates") return { data: { team: { states: { nodes: [
+      { id: "done-1", name: "Done", type: "completed", position: 1 },
+    ] } } } };
+    throw new Error(`unexpected operation ${op}`);
+  }, async ({ url, requests }) => {
+    const result = await run(CLI, ["issue", "update", "ENG-1", "--state", "Done"], {
+      LINEAR_API_KEY: "key", LINEAR_API_URL: url,
+    });
+    assert.equal(result.code, 1);
+    assert.match(result.stderr, /refusing terminal state/);
+    assert.equal(requests.some((request) => operation(request.query) === "OatsLinearIssueUpdate"), false);
+  });
+});
+
+test("comment accepts multiline markdown from a file", async () => {
+  const temp = mkdtempSync(join(tmpdir(), "oats-linear-test-"));
+  const bodyFile = join(temp, "comment.md");
+  writeFileSync(bodyFile, "[worker-1] handoff: details\n\n- tests pass\n");
+  try {
+    await mockApi(({ query }) => {
+      assert.equal(operation(query), "OatsLinearComment");
+      return { data: { commentCreate: { success: true, comment: { id: "comment-1", body: "ok", createdAt: "2026-07-10", url: "https://linear.app/c/1", user: { id: "user-1", name: "Human" } } } } };
+    }, async ({ url, requests }) => {
+      const result = await run(CLI, ["issue", "comment", "ENG-1", "--body-file", bodyFile], {
+        LINEAR_API_KEY: "key", LINEAR_API_URL: url,
+      });
+      assert.equal(result.code, 0, result.stderr);
+      assert.equal(requests[0].variables.input.body, "[worker-1] handoff: details\n\n- tests pass");
+    });
+  } finally { rmSync(temp, { recursive: true, force: true }); }
+});
+
+test("spawn hook briefs settings and warns without auth", async () => {
+  const result = await run(HOOK, ["spawn"], {
+    OATS_EVENT: "spawn", OATS_INSTANCE: "worker-1",
+    OATS_SETTINGS: JSON.stringify({ team: "ENG", project: "Agent Platform" }),
+    LINEAR_API_KEY: "",
+  });
+  assert.equal(result.code, 0, result.stderr);
+  const payload = JSON.parse(result.stdout);
+  assert.deepEqual(payload.meta, { label: "agent-worker-1", team: "ENG", project: "Agent Platform" });
+  assert.match(payload.brief, /team ENG, default project Agent Platform/);
+  assert.match(payload.warning, /LINEAR_API_KEY/);
+});

package/capabilities/oats-okf/agents/memory-harvest.md

@@ -0,0 +1,25 @@
+# memory-harvest — soul promotion from live instances
+
+You are a memory-harvest instance. You were spawned because a live agent
+instance committed work while holding pending notes.
+
+**Your briefing (TASK.md) is the authority on your situation**: the source
+notes dir, the soul to update, the work tree you were given, and how your
+promotion is delivered. That last part depends on the source soul's custody —
+a commit on the shared tree, a commit plus a PR from your own worktree, or a
+direct edit with nothing to commit at all. Read it before you plan anything.
+
+**You are ephemeral.** Skip all episodic-state upkeep of your own: do not
+maintain STATE.md/log.md, do not write notes/, and never harvest yourself.
+Any memory instructions injected below do not apply to you.
+
+Follow the **memory-harvest** skill — **load it before touching any
+note**; it is your entire protocol: judge each
+note (promote / merge / drop), route knowledge vs skills, keep index and log
+discipline, validate, delete processed notes, deliver the way your briefing
+says, then `oats retire <your-instance> --self`.
+
+Boundaries: only the soul dirs named in your briefing and the source notes
+files, and nothing else. When your briefing attached you to another instance's
+work tree, that tree belongs to an agent still working in it — one focused
+commit, no other changes, never switch branches.

package/capabilities/oats-okf/bin/oats-okf.mjs

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+/**
+ * oats-okf — OATS knowledge-integration hooks for OKF (Open Knowledge Format).
+ *
+ * THE KNOWLEDGE INTEGRATION OWNS ALL MEMORY CONVENTIONS. The kernel knows
+ * nothing about STATE.md, log.md, notes/, knowledge bundles, or harvest —
+ * agents without a knowledge integration simply have none of this.
+ *
+ * Events (hook contract):
+ *   soul-scaffold  scaffold the soul's OKF knowledge bundle (idempotent)
+ *   spawn          scaffold instance memory (STATE.md, log.md, notes/) + brief
+ *   retire         no-op (promotion is continuous — see harvest)
+ *   harvest        AGENT-INITIATED (not a kernel hook): run from an instance
+ *                  home (`node <pkg>/capabilities/oats-okf/bin/oats-okf.mjs harvest`)
+ *                  after committing with pending notes — spawns the memory-harvest
+ *                  agent attached to this instance's work tree.
+ *
+ * Env: OATS_EVENT, OATS_INSTANCE, OATS_HOME, OATS_AGENT, OATS_SOUL (soul dir),
+ *      OATS_CONTEXT, OATS_WORKSPACE, OATS_SETTINGS ({ "sections-file"? }),
+ *      OATS_TASK (spawn), OATS_REPO/OATS_BRANCH/OATS_WORK (spawn), OATS_META (retire).
+ * Output: JSON { meta, brief, warning } on stdout. Failures warn, never block.
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, copyFileSync, realpathSync } from "node:fs";
+import { join, isAbsolute, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { execSync } from "node:child_process";
+
+/** The kernel install root. When this package runs from inside the kernel
+ * (marketplace source tree), ../../.. works; when it runs as a copied
+ * marketplace install (.agents/capabilities/installed/oats-okf), resolve the
+ * kernel through `oats root` — the same mechanism adapters use. */
+const FRAMEWORK_ROOT = (() => {
+  const rel = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+  if (existsSync(join(rel, "lib", "core.mjs"))) return rel;
+  try {
+    const root = execSync("oats root", { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 15000 }).trim();
+    if (root && existsSync(join(root, "lib", "core.mjs"))) return root;
+  } catch { /* fall through */ }
+  return rel; // callers report the missing module with a clear path
+})();
+
+const out = (o) => { process.stdout.write(JSON.stringify(o) + "\n"); process.exit(0); };
+const warn = (m) => out({ warning: `oats-okf: ${String(m).slice(0, 300)}` });
+
+// Desktop CLI API v1: `oats okf harvest --json` emits EXACTLY ONE envelope
+// object on stdout — {schemaVersion:1,ok,result|error} — and a nonzero exit
+// on failure. Ordinary (non---json) output keeps the hook JSON shape above.
+const JSON_MODE = process.argv.includes("--json");
+const jsonOk = (result) => { process.stdout.write(JSON.stringify({ schemaVersion: 1, ok: true, result }) + "\n"); process.exit(0); };
+const jsonFail = (code, message) => { process.stdout.write(JSON.stringify({ schemaVersion: 1, ok: false, error: { code, message: String(message).slice(0, 300) } }) + "\n"); process.exit(1); };
+
+const event = process.env.OATS_EVENT || process.argv[2];
+const instance = process.env.OATS_INSTANCE;
+const home = process.env.OATS_HOME || process.cwd();
+const soulDir = process.env.OATS_SOUL;
+const agentName = process.env.OATS_AGENT || "agent";
+// Fallible init stays inside an error boundary: malformed inherited env must
+// never produce a bare stack trace — in --json mode Desktop expects one
+// envelope object on stdout even for init failures.
+let settings = {};
+try { settings = JSON.parse(process.env.OATS_SETTINGS || "{}"); }
+catch (e) {
+  if (JSON_MODE) jsonFail("E_HARVEST_FAILED", `malformed OATS_SETTINGS: ${e.message || e}`);
+  process.stderr.write(`oats-okf: malformed OATS_SETTINGS (ignoring): ${e.message || e}\n`);
+}
+/** Model for the memory-harvest agent — promotion judgment is cheap-but-good
+ *  work; default gpt-5.5, overridable via okf settings { "harvest-model": ... }. */
+const DEFAULT_HARVEST_MODEL = "github-copilot/gpt-5.5";
+
+/** Append a one-line entry to an OKF log.md (newest-first, date-grouped per spec §7). */
+function appendLogEntry(logPath, entry, title) {
+  const today = new Date().toISOString().slice(0, 10);
+  let text = existsSync(logPath) ? readFileSync(logPath, "utf8") : `# ${title}\n\n`;
+  const heading = `## ${today}`;
+  if (text.includes(heading)) text = text.replace(`${heading}\n`, `${heading}\n* ${entry}\n`);
+  else text = text.replace(/^(# [^\n]*\n\n?)/, `$1${heading}\n* ${entry}\n\n`);
+  writeFileSync(logPath, text);
+}
+
+/** Scaffold the soul's OKF knowledge bundle (idempotent). */
+function scaffoldSoul() {
+  if (!soulDir) return false;
+  const kb = join(soulDir, "knowledge");
+  mkdirSync(kb, { recursive: true });
+  const index = join(kb, "index.md");
+  if (!existsSync(index)) {
+    let seeded = "";
+    const sf = settings["sections-file"];
+    if (sf) {
+      const abs = isAbsolute(sf) ? sf : join(process.env.OATS_CONTEXT || home, sf);
+      if (existsSync(abs)) seeded = readFileSync(abs, "utf8").trim() + "\n";
+    }
+    writeFileSync(index, `---
+okf_version: "0.1"
+---
+
+# ${agentName} knowledge base
+
+Curated long-term knowledge for the ${agentName} agent (OKF bundle). Follow links
+selectively — read what the current task needs, not everything.
+
+# Sections
+
+* [lessons/](lessons/) - durable lessons learned (type: Lesson).
+* [decisions/](decisions/) - decisions and their rationale (type: Decision).
+* [playbooks/](playbooks/) - step-by-step procedures kept as knowledge (type: Playbook).
+* [references/](references/) - internal/external reference material (type: Reference).
+${seeded}
+Grow role-specific sections beyond these as the agent's role demands (e.g.
+architecture/, codebase/) — list them here and log the growth in log.md.
+`);
+  }
+  const log = join(kb, "log.md");
+  if (!existsSync(log)) appendLogEntry(log, "**Initialization**: knowledge bundle scaffolded by oats-okf.", "Knowledge Log");
+  return true;
+}
+
+if (event === "soul-scaffold") {
+  try { out({ meta: { scaffolded: scaffoldSoul() } }); } catch (e) { warn(e.message || e); }
+} else if (event === "spawn") {
+  // Ephemeral CAPABILITY agents (reviewer, memory-harvest) carry no episodic
+  // state of their own — no STATE.md/log.md/notes scaffolding, and no
+  // session-protocol brief. LOCAL souls are full souls: they get everything.
+  // ("tmp" is the legacy spelling of local — treat it as local, with memory.)
+  if ((process.env.OATS_KIND || "") === "capability") {
+    out({ meta: { memory: "none" }, brief: "Memory: none — you are ephemeral; no STATE.md/log.md/notes upkeep, no harvest." });
+  }
+  try {
+    const task = (process.env.OATS_TASK || "").trim();
+    writeFileSync(join(home, "STATE.md"), `---
+type: Instance State
+title: ${instance} working state
+description: Live working state for instance ${instance} — rewritten as work progresses.
+timestamp: ${new Date().toISOString()}
+---
+
+# Task
+
+${task || "_No task assigned yet — await instructions._"}
+
+# Plan
+
+_(numbered steps once you have a plan)_
+
+# Progress
+
+_(what is done — commits, files touched, verified results)_
+
+# Next
+
+_(the single next action — keep this current; a fresh session on any model resumes from here)_
+
+# Context
+
+- repo: ${process.env.OATS_REPO || "?"} (branch ${process.env.OATS_BRANCH || "?"}, mode ${process.env.OATS_WORK || "?"})
+- key files/paths: _(fill in as you learn them)_
+`);
+    appendLogEntry(join(home, "log.md"),
+      `**Creation**: instance ${instance} spawned from soul ${agentName}${task ? ` — task: ${task.split("\n")[0].slice(0, 120)}` : ""}.`,
+      "Instance Log");
+    mkdirSync(join(home, "notes"), { recursive: true });
+    out({
+      meta: { memory: "okf" },
+      brief: "Memory: your STATE.md/log.md/notes/ are scaffolded — your AGENTS.md's 'Knowledge: OKF' section has the session protocol.",
+    });
+  } catch (e) { warn(`instance memory scaffold failed: ${e.message || e}`); }
+} else if (event === "harvest") {
+  // AGENT-INITIATED HARVEST. An instance that committed with pending notes
+  // runs `harvest` from its home: spawn the
+  // memory-harvest agent ATTACHED to the same work tree — sibling home, shared
+  // tree — to promote notes into the soul, commit, and retire itself.
+  // Long-lived sessions thus feed the soul continuously, on the agent's call.
+  try {
+    // Derive context from the instance home (cwd) when hook env is absent.
+    const metaFile = join(home, "instance.json");
+    const meta = existsSync(metaFile) ? JSON.parse(readFileSync(metaFile, "utf8")) : {};
+    const inst = instance || meta.instance;
+    const agName = process.env.OATS_AGENT || meta.agent || "agent";
+    const sDir = soulDir || join(home, "soul");
+    const context = process.env.OATS_CONTEXT || meta.repo;
+    let root = process.env.OATS_ROOT;
+    if (!root) { // walk up from home to the agents/ dir
+      let d = home;
+      while (d !== dirname(d)) { if (d.endsWith("/instances")) { root = join(d, "..", ".."); break; } d = dirname(d); }
+      root = root ? realpathSync(join(root)) : undefined;
+      // instances live at <root>/<agent>/instances/<inst>, at the legacy nested
+      // <root>/{local,tmp}-agents/<agent>/instances/<inst>, or at the sibling
+      // <scope>/local-agents/<agent>/instances/<inst> — canonical root is <scope>/agents.
+      if (root && ["local-agents", "tmp-agents"].includes(root.split("/").pop())) {
+        const parent = dirname(root);
+        root = parent.split("/").pop() === "agents" ? parent : join(parent, "agents");
+      }
+    }
+    const notesDir = join(home, "notes");
+    const skip = (why) => (JSON_MODE ? jsonOk({ harvest: "skipped", reason: why }) : out({ meta: { harvestSpawn: "skipped", why } }));
+    if (String(agName).startsWith("memory-harvest")) skip("self (loop guard)");
+    const notes = existsSync(notesDir) ? readdirSync(notesDir).filter((f) => f.endsWith(".md")) : [];
+    if (notes.length === 0) skip("no pending notes");
+    if (!root || (!existsSync(root) && !existsSync(join(dirname(root), "local-agents")))) skip("no agents root found above this home");
+    if (!inst) skip("no instance identity (run from an instance home)");
+    const core = await import(pathToFileURL(join(FRAMEWORK_ROOT, "lib", "core.mjs")).href);
+    const slug = String(inst).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 30);
+    // Debounce: one harvester per source instance at a time (canonical sibling
+    // local-agents/ plus legacy nested locations).
+    const harvesterHomes = [
+      join(dirname(root), "local-agents", "memory-harvest", "instances", `memory-harvest-${slug}`),
+      join(root, "local-agents", "memory-harvest", "instances", `memory-harvest-${slug}`),
+      join(root, "tmp-agents", "memory-harvest", "instances", `memory-harvest-${slug}`),
+    ];
+    if (harvesterHomes.some((h) => existsSync(h))) skip("harvester already running for this instance");
+    let agentDef = core.findAgent(root, "memory-harvest");
+    if (!agentDef) {
+      const upsert = core.upsertLocalAgent || core.upsertTmpAgent; // kernel ≥0.18 / older
+      upsert(root, { name: "memory-harvest", instructions: readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "agents", "memory-harvest.md"), "utf8") });
+      agentDef = core.findAgent(root, "memory-harvest");
+    }
+    // The harvester is service infrastructure: ALWAYS ephemeral, regardless of
+    // its on-disk kind (it homes as a local soul so it is uncommitted).
+    agentDef = { ...agentDef, kind: "capability" };
+    // Harvest model: explicit okf settings win (hook env, or resolved from config
+    // when agent-initiated); else the integration's default.
+    let harvestModel = settings["harvest-model"];
+    if (!harvestModel && context) {
+      try { harvestModel = core.resolveOatsConfig(context).layers?.knowledge?.settings?.["harvest-model"]; } catch { /* config unreadable: use default */ }
+    }
+    harvestModel = harvestModel || DEFAULT_HARVEST_MODEL;
+    const workDir = realpathSync(join(home, "work"));
+    const realSoul = realpathSync(sDir);
+    const harvName = `memory-harvest-${slug}`;
+    const gitRootOf = (start) => { let d = start; while (d !== dirname(d)) { if (existsSync(join(d, ".git"))) return d; d = dirname(d); } return undefined; };
+    let r;
+    const srcKind = process.env.OATS_KIND || meta.kind || "";
+    if (["local", "tmp"].includes(srcKind)) {
+      // LOCAL soul: uncommitted by contract (local-agents/, gitignored). The
+      // harvester judges notes exactly as usual, but the deliverable is DIRECT
+      // edits to the canonical soul — no commit, no PR: there is nothing to
+      // version. It must not touch the owner's work tree.
+      r = core.spawnInstance(root, agentDef, {
+        instance: harvName, parent: inst,
+        repo: context, work: "attached", workDir, model: harvestModel,
+        task: `Harvest the pending notes of live LOCAL-SOUL instance "${inst}" (agent "${agName}") into its soul — by direct edits, no commit.\n\n- Source notes: ${notesDir} (${notes.join(", ")})\n- Soul knowledge bundle to update: ${join(realSoul, "knowledge")}\n- Soul skills dir (for procedure-shaped notes): ${join(realSoul, "skills")}\n- This soul is LOCAL (uncommitted, gitignored): edit those soul files IN PLACE. Do NOT run git commit — not for the soul, and not in ./work (the shared tree belongs to the working instance; leave it untouched).\n- Follow your memory-harvest skill for everything else: promote/merge/drop each note, knowledge vs skill routing, index + log discipline, validate the bundle, DELETE processed notes from the source notes/ dir.\n- Then run \`oats retire ${harvName} --self\`.`,
+      });
+    } else if ((process.env.OATS_WORK || meta.work) === "workspace") {
+      // WORKSPACE-MODE instance: ./work is the whole workspace, not a git repo —
+      // the harvester may NOT commit there. The soul lives in its own home repo
+      // (committed to the workspace): harvest in a WORKTREE of that repo and
+      // deliver the promotion as a PR, never a direct push to its main branch.
+      const soulRepo = gitRootOf(realSoul);
+      if (!soulRepo) skip("workspace-mode soul is not inside a git repo — nowhere to deliver a PR");
+      const relSoul = realSoul.slice(soulRepo.length + 1);
+      r = core.spawnInstance(root, agentDef, {
+        instance: harvName, parent: inst,
+        repo: soulRepo, work: "worktree", branch: `memory-harvest/${slug}`, model: harvestModel,
+        task: `Harvest the pending notes of live WORKSPACE-MODE instance "${inst}" (agent "${agName}") into its soul — delivered as a PR.\n\n- Source notes: ${notesDir} (${notes.join(", ")})\n- Your ./work is a dedicated worktree of the soul's home repo (${soulRepo}), branch memory-harvest/${slug}.\n- Soul knowledge bundle to update: ./work/${join(relSoul, "knowledge")}\n- Soul skills dir (for procedure-shaped notes): ./work/${join(relSoul, "skills")}\n- Follow your memory-harvest skill: promote/merge/drop each note, knowledge vs skill routing, index + log discipline, validate the bundle, DELETE processed notes from the source notes/ dir, commit once (prefixed "memory-harvest:").\n- Then push the branch and open a PR (\`git push -u origin memory-harvest/${slug}\` then \`gh pr create --fill\`). Do NOT merge it; the humans/owners of ${soulRepo} review soul changes. If gh is unavailable, push the branch and report the compare URL.\n- Finally run \`oats retire ${harvName} --self\` (keep the branch: --self only).`,
+      });
+    } else {
+      // Repo-resident souls: write to the soul AS SEEN FROM THE WORK TREE, so the
+      // promotion commits onto the instance's own branch. Otherwise the canonical soul.
+      const realRepo = realpathSync(context || workDir);
+      const soulTarget = realSoul.startsWith(realRepo + "/")
+        ? join(workDir, realSoul.slice(realRepo.length + 1))
+        : realSoul;
+      r = core.spawnInstance(root, agentDef, {
+        instance: harvName, parent: inst,
+        repo: context, work: "attached", workDir, model: harvestModel,
+        task: `Harvest the pending notes of live instance "${inst}" (agent "${agName}") into its soul.\n\n- Source notes: ${notesDir} (${notes.join(", ")})\n- Soul knowledge bundle to update: ${join(soulTarget, "knowledge")}\n- Soul skills dir (for procedure-shaped notes): ${join(soulTarget, "skills")}\n- You are ATTACHED to the instance's work tree (./work) — commit your promotions there as a single commit, prefixed "memory-harvest:".\n- Follow your memory-harvest skill: promote/merge/drop each note, knowledge vs skill routing, index + log discipline, validate the bundle, DELETE processed notes from the source notes/ dir (so they are not re-harvested), commit, then run \`oats retire ${harvName} --self\`.`,
+      });
+    }
+    if (JSON_MODE) jsonOk({ harvest: "spawned", instance: r.instance, window: r.tmux?.window || null });
+    out({ meta: { harvestSpawn: r.instance, window: r.tmux?.window } });
+  } catch (e) {
+    if (JSON_MODE) jsonFail("E_HARVEST_FAILED", `harvest spawn failed (notes are safe on disk): ${e.message || e}`);
+    warn(`harvest spawn failed (notes are safe on disk): ${e.message || e}`);
+  }
+} else if (event === "retire") {
+  // Retirement is intentionally a no-op for knowledge (for now): promotion happens
+  // continuously via agent-initiated harvest. Uncommitted notes die with the home —
+  // the injection tells instances to bring memory up to date, commit, and harvest
+  // before finishing.
+  out({ meta: {} });
+} else {
+  warn(`unknown event "${event}" (expected soul-scaffold|spawn|retire)`);
+}

package/capabilities/oats-okf/injects/okf.md

@@ -0,0 +1,62 @@
+## Knowledge: OKF
+
+Your knowledge layer is **OKF** (Open Knowledge Format). Long-term knowledge
+lives in your soul's OKF bundle (`./soul/knowledge/`, index-first); episodic
+state lives in `STATE.md`/`log.md`/`notes/`.
+
+**Before working — every session, no exceptions:**
+
+1. **Load the okf skill.** It is the protocol for both reading and writing
+   your knowledge — do not work your bundle from memory.
+2. Read `./STATE.md` and recent `./log.md` — if STATE.md has a plan/progress
+   you are resuming, continue from its `# Next`.
+3. **Check your knowledge for the task at hand**: open
+   `./soul/knowledge/index.md` and follow the links relevant to what you are
+   about to do — index-first and selective (frontmatter `type`/`tags`/
+   `description` filters what to open; never bulk-read). Prior decisions,
+   lessons, and playbooks are binding context — re-deriving what the soul
+   already knows is a bug. Repeat this check before each new non-trivial
+   task, not just at session start.
+
+Keep STATE.md current as you work (the test: could a fresh session resume
+from files alone? its `# Next` names the single next action). Append dated
+milestones to `./log.md` (newest first).
+
+**Write down what you learn.** Anything you figured out that was not obvious
+— a gotcha, a decision and its why, a procedure that worked — goes in
+`./notes/`, one OKF concept per insight, as you go. Do not judge whether it
+is "important enough"; that is someone else's job. Just capture it
+faithfully.
+
+**Before every commit, bring memory up to date**: STATE.md current, log.md
+milestone appended, fresh insights in `./notes/`.
+
+**After committing with pending notes, launch the harvester yourself**: run
+
+```bash
+oats okf harvest
+```
+
+from your instance home. It spawns the memory-harvest agent attached to your
+work tree to promote your notes into the soul (it skips cleanly when there
+are no notes or a harvester is already running — calling it "too often" is
+safe; not calling it means your insights never reach the soul, and unwritten
+or unharvested notes are lost when your home is retired).
+
+**Workspace-mode instances**: your soul lives in its own home repo, and your
+`./work` (the workspace) is not where it commits. `oats okf harvest` handles
+this — it promotes your notes in a worktree of the soul's home repo and
+delivers the update **as a PR to that repo**, never a direct push and never
+a commit into member repos. Your job is unchanged: write notes, commit
+nothing yourself, call the harvester.
+
+**Local-soul instances**: your soul is uncommitted by design (it lives in
+`local-agents/`, gitignored). The harvester edits your soul directly — no
+commit, no PR. Your job is still unchanged: write notes, commit your WORK
+normally, call the harvester.
+
+The okf skill you loaded at session start also governs writing: notes,
+concepts, index.md, and log.md follow its format craft (concepts,
+frontmatter, index/log discipline, validation). Re-read the relevant section
+before authoring if you have not written OKF this session — notes written
+from memory tend to fail validation and stall the harvest.

package/capabilities/oats-okf/oats.json

@@ -0,0 +1,20 @@
+{
+  "capability": "oats.okf",
+  "command": "okf",
+  "version": "1.4.1",
+  "compatibility": { "oats": ">=0.6.2" },
+  "layer": "knowledge",
+  "description": "Knowledge layer via OKF: soul bundles, instance memory (STATE.md/log.md/notes/), continuous post-commit harvest into the soul (commit, PR, or direct-edit for local souls), craft + memory skills, validator.",
+  "requires": [],
+  "skills": [
+    "skills"
+  ],
+  "commands": {
+    "harvest": "bin/oats-okf.mjs harvest"
+  },
+  "inject": "injects/okf.md",
+  "hooks": {
+    "soul-scaffold": "bin/oats-okf.mjs soul-scaffold",
+    "spawn": "bin/oats-okf.mjs spawn"
+  }
+}

package/capabilities/oats-okf/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@awebai/oats-okf",
+  "version": "0.1.0",
+  "description": "OATS knowledge provider: Open Knowledge Format (OKF) craft skill, bundle validator, and agents-md injection",
+  "keywords": [
+    "pi-package",
+    "oats",
+    "okf"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/awebai/oats",
+    "directory": "capabilities/oats-okf"
+  },
+  "license": "MIT",
+  "type": "module",
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  }
+}