@joenandez/academy 0.4.0 → 0.5.13

package/hooks/sync_memory.mjs

@@ -2,7 +2,7 @@
 import { mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { isMainModule, readPayload, runtimeEnvFor } from './hook_runtime.mjs';
-import { syncBridgeObservations } from './memory_bridge.mjs';
+import { sweepBridgeObservations } from './memory_bridge.mjs';
 import { markPendingConsolidation, recordSession } from './memory_store.mjs';
 
 export function syncAcademyMemory(payload, env = process.env) {
@@ -12,15 +12,19 @@ export function syncAcademyMemory(payload, env = process.env) {
   if (!agentDir || !sessionId) return { synced: 0 };
 
   const memoryDir = join(resolve(agentDir), 'memory');
-  const observationsDir = join(memoryDir, 'observations');
-  mkdirSync(observationsDir, { recursive: true });
+  mkdirSync(join(memoryDir, 'observations'), { recursive: true });
   recordSession(memoryDir, payload, env);
+  // Observations land after Stop, so this copies what earlier stops of every
+  // recorded session could not yet see (the store is one turn behind).
   // Eligibility tracks Academy session activity, not the bridge copy, so an
-  // agent still consolidates when the memory bridge is unavailable.
-  if (env.ACADEMY_NIGHTLY_RUN !== '1') markPendingConsolidation(memoryDir);
+  // agent still consolidates when the memory bridge is unavailable. A
+  // nightly's own Stop marks only when it swept in earlier sessions' input.
+  let synced = 0;
+  markPendingConsolidation(memoryDir, () => {
+    synced = sweepBridgeObservations(resolve(agentDir), { env });
+    return env.ACADEMY_NIGHTLY_RUN !== '1' || synced > 0;
+  });
 
-  const synced =
-    env.ACADEMY_MEMORY_BRIDGE === '1' ? syncBridgeObservations(env, observationsDir, sessionId) : 0;
   return { synced };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joenandez/academy",
-  "version": "0.4.0",
+  "version": "0.5.13",
   "description": "Academy v3 — portable AI agents with 8 boot surfaces and a skills primitive.",
   "type": "module",
   "bin": {
@@ -21,12 +21,12 @@
     "templates/",
     "hooks/",
     ".claude-plugin/",
-    "conformance/",
-    "docs/integration-guide.md",
     "CHANGELOG.md"
   ],
   "scripts": {
     "test": "node --test tests/*.test.mjs",
+    "sync:roque": "node scripts/sync-roque.mjs",
+    "sync:backstory": "node scripts/sync-backstory.mjs",
     "quality:setup": "node quality/run.mjs setup",
     "quality:commit": "node quality/run.mjs commit",
     "quality:push": "node quality/run.mjs push",
@@ -35,7 +35,14 @@
   "keywords": ["academy", "ai-agent", "claude-code", "portable-agent"],
   "author": "Joe Fernandez",
   "license": "MIT",
+  "engines": {
+    "node": ">=24.20.0"
+  },
   "devDependencies": {
+    "js-yaml": "4.3.2",
     "knip": "5.70.2"
+  },
+  "dependencies": {
+    "@joenandez/tldr": "0.2.0"
   }
 }

package/scripts/cli/agent-gate.mjs

@@ -0,0 +1,70 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { currentAgentName } from './agent-id.mjs';
+import { CLI_NAME, kindOf } from './core.mjs';
+import { printHelmSkip } from './helm-skip.mjs';
+import { schedulerJobId } from './tldr.mjs';
+import { readAgentYaml } from './yaml.mjs';
+
+// Decision D1: nothing runs until the user signs the mandate, and a stopped
+// agent runs nothing. Job registration and every run entry ask these two.
+
+// The hire placeholder the Owner mandate template carries until a person
+// writes the mandate. Matched as a substring, so the template may change around it.
+const MANDATE_PLACEHOLDER = 'Hire flow will populate this';
+
+export const isStopped = (dir) => readAgentYaml(dir).stopped === 'true';
+
+export function readMandate(dir) {
+  try {
+    return readFileSync(join(dir, 'mandate.md'), 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/** Mandate text that is blank or still holds the hire placeholder. */
+export const isDraftMandate = (text) => text.trim() === '' || text.includes(MANDATE_PLACEHOLDER);
+
+/** An Owner whose mandate.md is missing, blank, or still holds the hire placeholder. */
+export function isDraftOwner(dir) {
+  return kindOf(dir) === 'owner' && isDraftMandate(readMandate(dir));
+}
+
+// Of a kind's job ids, nightly first, the ones registered while the agent is
+// in this state: none when stopped, only the nightly for a draft Owner.
+export function liveJobIds(dir, ids) {
+  if (isStopped(dir)) return [];
+  return isDraftOwner(dir) ? ids.slice(0, 1) : ids;
+}
+
+function notStartedReason(dir) {
+  if (isStopped(dir)) return 'agent_stopped';
+  if (isDraftOwner(dir)) return 'owner_draft';
+  return null;
+}
+
+// The run entry gate, before any model. A scheduled run, a stale job left by a
+// failed delete included, ends as a skip the scheduler records; a person is
+// told to start the agent.
+export function refuseNotStarted(dir, id) {
+  const reason = notStartedReason(dir);
+  if (!reason) return;
+  const jobId = schedulerJobId();
+  console.error(
+    JSON.stringify({
+      event: 'run.not_started',
+      status: 'warn',
+      params: { agent: id, jobId },
+      result: { skip: reason },
+    }),
+  );
+  if (jobId) {
+    printHelmSkip(reason, id);
+    process.exit(0);
+  }
+  const name = currentAgentName(dir);
+  const state = reason === 'agent_stopped' ? 'is stopped' : 'has no signed mandate';
+  console.error(`Agent "${name}" ${state}. Run \`${CLI_NAME} start ${name}\` to start it.`);
+  process.exit(1);
+}

package/scripts/cli/agent-id.mjs

@@ -0,0 +1,37 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { AGENTS_ROOT, NAME_RE } from './core.mjs';
+import { holdingAreaOrNull, isArchivedAgent } from './archived.mjs';
+import { readAgentYaml } from './yaml.mjs';
+
+// An agent's folder name is its fixed id; agent.yaml `name:` is its current
+// name. `agentDir` in core.mjs resolves either through here.
+
+/** The id an id or current name resolves to, live or archived, or null. Never exits. */
+export function agentIdOrNull(nameOrId) {
+  if (typeof nameOrId !== 'string' || !NAME_RE.test(nameOrId)) return null;
+  if (existsSync(join(AGENTS_ROOT, nameOrId)) || isArchivedAgent(nameOrId)) return nameOrId;
+  // Read only on a folder miss, so a lookup by id never opens a YAML file.
+  const holding = holdingAreaOrNull();
+  for (const home of holding === null ? [AGENTS_ROOT] : [AGENTS_ROOT, holding]) {
+    const id = listIds(home).find((entry) => readAgentYaml(join(home, entry)).name === nameOrId);
+    if (id) return id;
+  }
+  return null;
+}
+
+/** The current name: agent.yaml `name:`, or the id when it names none. */
+export function currentAgentName(dir) {
+  return readAgentYaml(dir).name || basename(dir);
+}
+
+/** The fixed id an id or current name addresses; an unknown or invalid input as given. */
+export const agentIdOf = (nameOrId) => agentIdOrNull(nameOrId) ?? nameOrId;
+
+function listIds(home) {
+  try {
+    return readdirSync(home).filter((entry) => NAME_RE.test(entry));
+  } catch {
+    return [];
+  }
+}

package/scripts/cli/archive.mjs

@@ -11,17 +11,21 @@ import {
   withFileLock,
 } from './core.mjs';
 import { ARCHIVED_DIR, archivedAgentDir, holdingAreaOrNull } from './archived.mjs';
-import { registerNightlyConsolidationTask } from './create.mjs';
+import { jobLabel, registerAcademyJobs, scheduledJobFields } from './create.mjs';
+import { agentIdOf, currentAgentName } from './agent-id.mjs';
 import { appendLifecycleEvent } from './eventlog.mjs';
 import {
   DeleteAgentError,
   SLOT,
+  academyJobIds,
   assertOwnedAgentForDelete,
-  deleteNightlyConsolidation,
+  deleteAcademyJobs,
   preflightOwnedAgent,
   reportLifecycleFailure,
+  unscheduleError,
   validateOwnedAgentDir,
 } from './lifecycle.mjs';
+import { reportRegisteredJobs } from './rename.mjs';
 
 // `archive` / `unarchive`. Archived agents live at AGENTS_ROOT/.archived/<name>,
 // which is not the canonical slot, so they are validated against the holding
@@ -29,16 +33,19 @@ import {
 // Neither command destroys anything, so neither quarantines: the move itself is
 // the whole operation and it is reversible by the other command.
 
+// Both commands act on the fixed id: its folder, slot, marker and lock. The
+// current name is what they report.
 export function archiveAgent(name, json) {
-  preflightOwnedAgent(name, json);
-  runLocked(name, json, 'archive', () => archiveAgentLocked(name, json));
+  const { id } = preflightOwnedAgent(name, json);
+  runLocked(id, json, 'archive', () => archiveAgentLocked(id, json));
 }
 
 export function unarchiveAgent(name, json) {
   validateName(name);
   validateAgentsRoot();
-  validateOwnedAgentDir(name, archivedAgentDir(name), json, SLOT.archived);
-  runLocked(name, json, 'unarchive', () => unarchiveAgentLocked(name, json));
+  const id = agentIdOf(name);
+  validateOwnedAgentDir(id, archivedAgentDir(id), json, SLOT.archived);
+  runLocked(id, json, 'unarchive', () => unarchiveAgentLocked(id, json));
 }
 
 // Both commands take the canonical lifecycle lock, the same one `delete` and
@@ -94,26 +101,20 @@ function refuseOccupiedTarget(name, target) {
   );
 }
 
-function archiveAgentLocked(name, json) {
-  const { dirReal } = assertOwnedAgentForDelete(name, agentDir(name));
-  const previousDir = resolve(agentDir(name));
+function archiveAgentLocked(id, json) {
+  const { dirReal } = assertOwnedAgentForDelete(id, agentDir(id));
+  const name = currentAgentName(dirReal);
+  const previousDir = resolve(agentDir(id));
   ensureHoldingArea();
-  assertContainedHoldingArea(name);
-  const target = archivedAgentDir(name);
-  assertContainedSlot(name, target);
-  refuseOccupiedTarget(name, target);
-
-  // Unscheduled before the move, for the same reason `rename` unschedules
-  // first: the job's --cwd names a directory that is about to move, and an
-  // archived agent must not keep firing nightly.
-  const unscheduled = deleteNightlyConsolidation(name, dirReal);
-  if (!unscheduled.ok) {
-    throw new DeleteAgentError(
-      unscheduled.code ?? 'unschedule_failed',
-      `Refusing to archive "${name}" because nightly unschedule failed: ${unscheduled.reason}`,
-      { name },
-    );
-  }
+  assertContainedHoldingArea(id);
+  const target = archivedAgentDir(id);
+  assertContainedSlot(id, target);
+  refuseOccupiedTarget(id, target);
+
+  // Unscheduled before the move: the job's --cwd names a directory that is
+  // about to move, and an archived agent must not keep firing any of its jobs.
+  const unscheduled = deleteAcademyJobs(dirReal, academyJobIds(id, dirReal));
+  if (!unscheduled.ok) throw unscheduleError('archive', name, unscheduled);
 
   renameSync(dirReal, target);
   appendLifecycleEvent('agent_archived', name, resolve(target), { previousDir });
@@ -125,37 +126,37 @@ function archiveAgentLocked(name, json) {
       dir: resolve(target),
       previousDir,
       unscheduledJobId: unscheduled.id,
+      unscheduledJobIds: unscheduled.ids,
     });
     return;
   }
   console.log(`Archived agent "${name}" (${previousDir} → ${resolve(target)}).`);
-  console.log(`Unregistered nightly consolidation job "${unscheduled.id}".`);
+  for (const id of unscheduled.ids) console.log(`Unregistered ${jobLabel(id)} "${id}".`);
 }
 
-function unarchiveAgentLocked(name, json) {
-  assertContainedHoldingArea(name);
-  const { dirReal } = assertOwnedAgentForDelete(name, archivedAgentDir(name), SLOT.archived);
-  const previousDir = resolve(archivedAgentDir(name));
-  const target = agentDir(name);
-  assertContainedSlot(name, target);
-  refuseOccupiedTarget(name, target);
+function unarchiveAgentLocked(id, json) {
+  assertContainedHoldingArea(id);
+  const { dirReal } = assertOwnedAgentForDelete(id, archivedAgentDir(id), SLOT.archived);
+  const name = currentAgentName(dirReal);
+  const previousDir = resolve(archivedAgentDir(id));
+  const target = agentDir(id);
+  assertContainedSlot(id, target);
+  refuseOccupiedTarget(id, target);
 
   renameSync(dirReal, target);
-  const nightly = registerNightlyConsolidationTask(target, name);
+  const jobs = registerAcademyJobs(target, id);
   appendLifecycleEvent('agent_unarchived', name, resolve(target), { previousDir });
 
-  const scheduledJobId = nightly.registered ? nightly.id : null;
   if (json) {
     contractOk('unarchive', {
       unarchived: true,
       name,
       dir: resolve(target),
       previousDir,
-      scheduledJobId,
+      ...scheduledJobFields(jobs),
     });
     return;
   }
   console.log(`Unarchived agent "${name}" (${previousDir} → ${resolve(target)}).`);
-  if (scheduledJobId) console.log(`Registered nightly consolidation job "${scheduledJobId}".`);
-  else console.log(`Nightly consolidation job not registered: ${nightly.reason}`);
+  reportRegisteredJobs(jobs);
 }

package/scripts/cli/archived.mjs

@@ -1,6 +1,7 @@
 import { lstatSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { AGENTS_ROOT, NAME_RE, activeCommandName, contractError, jsonMode } from './core.mjs';
+import { agentIdOf } from './agent-id.mjs';
 
 // The holding area, as one module. Archived agents live in a dot-directory
 // beside their canonical slots, so the roster's NAME_RE filter already keeps
@@ -73,8 +74,9 @@ function isRealDirectory(path) {
 // replacement for somebody who is still there. `unarchive` is the one command
 // allowed to address one, so it is the one command that does not ask.
 export function assertNotArchived(name, json = jsonMode()) {
-  if (!isArchivedAgent(name)) return;
-  const dir = resolve(archivedAgentDir(name));
+  const id = agentIdOf(name);
+  if (!isArchivedAgent(id)) return;
+  const dir = resolve(archivedAgentDir(id));
   const message = `Agent "${name}" is archived at ${dir}. Unarchive it first.`;
   if (json) contractError(activeCommandName(), 'agent_archived', message, { name, dir });
   console.error(`Error: ${message}`);

package/scripts/cli/args-kinds.mjs

@@ -0,0 +1,33 @@
+// `create <name> [--kind <kind>] [--no-start] [--json]`. Like `rename`, an option Academy
+// does not know stays on the command so the handler answers it inside the
+// envelope the caller asked for. The kind stays a raw string: only `create` can
+// answer an unsupported one in the envelope.
+export function parseCreateArgs(command, rest) {
+  const json = rest.includes('--json');
+  let name;
+  let kind;
+  let noStart = false;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === '--json') continue;
+    else if (arg === '--no-start') noStart = true;
+    else if (arg === '--kind') kind = rest[++i] ?? '';
+    else if (arg.startsWith('--kind=')) kind = arg.slice('--kind='.length);
+    else if (arg.startsWith('--')) return { command, json, name, invalidOption: arg };
+    else name ??= arg;
+  }
+  return { command, json, name, kind, noStart };
+}
+
+// `skills check <agent> [--json]`. Like `create`, an option Academy does not
+// know stays on the command so the handler answers it in the envelope.
+export function parseSkillsArgs(command, rest) {
+  const json = rest.includes('--json');
+  const positional = [];
+  for (const arg of rest) {
+    if (arg === '--json') continue;
+    else if (arg.startsWith('--')) return { command, json, invalidOption: arg };
+    else positional.push(arg);
+  }
+  return { command, json, action: positional[0], name: positional[1] };
+}

package/scripts/cli/args-notes.mjs

@@ -0,0 +1,42 @@
+import { NAME_RE } from './core.mjs';
+
+// `notes add [<agent>] [--user] "text"` and `notes list [<agent>] [--last N]`. The first
+// positional token is treated as an agent only when it looks like an agent name
+// (NAME_RE) AND there is more to follow — so quoted single-arg text stays text.
+export function parseNotesArgs(rest) {
+  const action = rest[0];
+  if (action !== 'add' && action !== 'list') {
+    console.error(`Unknown notes action: ${action ?? '(none)'}. Use 'add' or 'list'.`);
+    return { command: 'help', exitCode: 1 };
+  }
+  const args = rest.slice(1);
+
+  if (action === 'add') {
+    // `--user` proposes a fact about the user rather than noting for the agent.
+    const user = args.includes('--user');
+    const words = args.filter((arg) => arg !== '--user');
+    let name;
+    let textParts = words;
+    if (words.length >= 2 && NAME_RE.test(words[0])) {
+      name = words[0];
+      textParts = words.slice(1);
+    }
+    return { command: 'notes', action, name, text: textParts.join(' '), user };
+  }
+
+  // list — pull out --last N (or --last=N), the rest is an optional agent name.
+  let last = 12;
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--last') {
+      last = Number.parseInt(args[++i], 10);
+    } else if (args[i].startsWith('--last=')) {
+      last = Number.parseInt(args[i].slice('--last='.length), 10);
+    } else {
+      positional.push(args[i]);
+    }
+  }
+  if (!Number.isInteger(last) || last <= 0) last = 12;
+  const name = positional[0] && NAME_RE.test(positional[0]) ? positional[0] : undefined;
+  return { command: 'notes', action, name, last };
+}

package/scripts/cli/args-owner.mjs

@@ -0,0 +1,37 @@
+// `rename <old> <new> [--json]`. Like `events`, `migrate` and `sessions`, an
+// option Academy does not know stays on the command so the handler answers it
+// inside the envelope the caller asked for.
+export function parseRenameArgs(command, rest) {
+  const json = rest.includes('--json');
+  const positional = [];
+  for (const arg of rest) {
+    if (arg === '--json') continue;
+    else if (arg.startsWith('--')) return { command, json, invalidOption: arg };
+    else positional.push(arg);
+  }
+  return { command, json, name: positional[0], newName: positional[1] };
+}
+
+const START_OPTIONS = {
+  '--mandate': 'mandate',
+  '--hours': 'hours',
+  '--contact': 'contact',
+  '--trust': 'trust',
+};
+
+// `start <name> [--mandate <file>] [--hours <h>] [--contact <c>] [--trust 1-4]
+// [--json]`. Like `rename`, an option Academy does not know stays on the
+// command so the handler answers it inside the envelope.
+export function parseStartArgs(command, rest) {
+  const parsed = { command, json: rest.includes('--json') };
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    const [flag, inline] = arg.split(/=(.*)/s);
+    if (arg === '--json') continue;
+    else if (Object.hasOwn(START_OPTIONS, flag))
+      parsed[START_OPTIONS[flag]] = inline ?? rest[++i] ?? '';
+    else if (arg.startsWith('--') || parsed.name !== undefined) parsed.invalidOption ??= arg;
+    else parsed.name = arg;
+  }
+  return parsed;
+}

package/scripts/cli/args-run.mjs

@@ -0,0 +1,38 @@
+import { RUNTIMES } from './core.mjs';
+
+export function parseRunArgs(rest) {
+  const name = rest[0];
+  const afterName = rest.slice(1);
+  const dashIdx = afterName.indexOf('--');
+  const optionArgs = dashIdx >= 0 ? afterName.slice(0, dashIdx) : afterName;
+  const passthrough = dashIdx >= 0 ? afterName.slice(dashIdx + 1) : [];
+  // No default here. The agent is not resolved yet, and defaulting before it is
+  // what re-registered a codex agent's nightly job as claude-code for ten
+  // nights. A null runtime means "not explicit"; `run` reads the persisted
+  // scalar instead.
+  let runtime = null;
+
+  for (let i = 0; i < optionArgs.length; i++) {
+    const arg = optionArgs[i];
+    if (arg === '--agent') {
+      const value = optionArgs[++i];
+      if (!RUNTIMES.has(value))
+        return invalidRunOption(`Invalid --agent value: ${value ?? '(none)'}`);
+      runtime = value;
+    } else if (arg?.startsWith('--agent=')) {
+      const value = arg.slice('--agent='.length);
+      if (!RUNTIMES.has(value))
+        return invalidRunOption(`Invalid --agent value: ${value || '(none)'}`);
+      runtime = value;
+    } else if (arg) {
+      return invalidRunOption(`Unknown run option: ${arg}`);
+    }
+  }
+
+  return { command: 'run', name, runtime, passthrough };
+}
+
+function invalidRunOption(message) {
+  console.error(`${message}. Use --agent claude-code or --agent codex before --.`);
+  return { command: 'help', exitCode: 1 };
+}