@joenandez/academy 0.4.0 → 0.5.13

package/templates/skills/user-nightly/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: user-nightly
+layer: craft
+description: Use only in the user-nightly run of the curator agent, to read what happened across all projects and keep user.md and user-work.md true for every agent.
+---
+
+# User Nightly
+
+{{agent_name}} is the curator. This run keeps the user's shared context true:
+`user.md` (who the user is) and `user-work.md` (what the user works on, and
+why). Every agent except a Monitor loads `user.md` at launch. Every agent
+loads its own share of `user-work.md` at launch: the preamble and the sections
+that name the agent. Only you write `user-work.md`, and only you edit `user.md`
+beyond appending `[proposed]` lines.
+
+## Paths
+
+- `user.md`: `{{user_path}}`
+- `user-work.md`: `{{user_work_path}}`
+- Reports: `{{dreams_dir}}/user/YYYY-MM-DD.md` (a subfolder your agent
+  nightly never reads)
+
+## Inputs
+
+1. **Watermark.** The date of your newest report in the reports folder. Read
+   at most 7 days. A missing report leaves the watermark old, so the next run
+   uses the 7-day window. No offsets.
+2. **Feed.** Run
+   `node "$(academy root)/scripts/cli/curator-feed.mjs" --since <watermark> --all --max-tokens 500000 --out {{dreams_dir}}/user-feed/<today>.md`.
+   Read it with Read offset and limit. If the script fails or a source is
+   `error`, sweep that source yourself. Look up with Subspace memory search,
+   then a transcript.
+3. **Beads.** Workstream changes since the watermark:
+   `bd list --type workstream --updated-after <watermark> --json`, and the
+   `ws:proposed` ones: `bd list --type workstream --label ws:proposed --json`.
+4. **Proposed facts.** The `[proposed]` lines at the end of `user.md`.
+5. **Explicit corrections.** Workstream notes that start `User said`, and the
+   user's own statements in the feed.
+
+## Run In The Foreground
+
+A scheduled run is one print-mode turn. When it ends, unfinished work is lost.
+Wait for every foreground subagent. Never use `run_in_background`, a
+background task, or a monitor. Read the feed in full; look up only what it
+cannot answer.
+
+## Steps
+
+1. Map the activity to Workstreams. Link or propose through `work-graph`. Find
+   gaps and duplicates.
+2. Resolve each `[proposed]` line: confirm it into the right section of
+   `user.md`, merge it with a duplicate, or remove it. A line about one agent
+   or one project, not the user, goes back to that agent with
+   `academy notes add <agent> "<line>"`. `<line>` is the text after the
+   `- [proposed] <stamp> <agent>:` prefix. Only when that command succeeds,
+   remove the line from `user.md`.
+3. Revise goals, priorities, and focus. **Explicit statements first.** An
+   explicit decision stands until the user changes it. A busy day is not a new
+   priority.
+4. **Drift is a question.** When attention moves away from a stated priority,
+   name it (aligned, possible drift, intentional shift, or exploration) and put
+   it under Open questions. Do not reorder priorities from activity alone. Do
+   not activate a Workstream on inference alone.
+5. Map each section of `user-work.md` to the agents that need it. Use the
+   mandates and the Beads `owner:` labels. Correct any name that is not in
+   `academy list --json`.
+6. Write `user.md` and `user-work.md`. Run `academy budget {{agent_name}} --json`
+   and read the `user` row. For each agent that `user-work.md` names, run
+   `academy budget <agent> --json` and read its `user-work` row. That row counts
+   the agent's share. Over cap: merge and remove finished or old detail first,
+   never an explicit user decision.
+7. Write the report.
+
+## File Shapes
+
+`user.md`: one fact per line, in these `##` sections, in order: `## Identity`,
+`## Preferences`, `## Feed` (last 7 days; promote or drop each item weekly),
+`## Scoped rules`, `## Projects` (the lead-agent line for each project and a
+pointer to `user-work.md`), `## Proposed`. No per-tier caps.
+Keep `## Proposed` as the last section, because agents append below it. When you first restructure
+a `user.md` that has the older sections, its scoped lines move to
+`## Scoped rules` unchanged.
+
+`user-work.md` is a preamble and sections. The preamble is every line before
+the first `##`. It holds only the `Private:` header line, the title line
+`# Work - <user>`, and an `Updated by the curator, <date time>` line. Every
+agent loads it, so put no work in it. Each `##` section has one `agents:` line
+right after its heading:
+
+```
+## <id> <title> (priority 2 of 4)
+agents: <names>
+```
+
+- `<names>` are agent names from `academy list --json`, comma-separated, or
+  `none`: write `agents: none` when no agent needs the section. Name an agent
+  only when its work needs it.
+- A section without an `agents:` line goes to no agent. An agent that no
+  section names gets only the preamble.
+- The sections, in order: `## Goal: <goal>` (each with a measure or the word
+  qualitative, and `(explicit)` or `(inferred; <why>)`), one
+  `## <id> <title> (priority N of 4)` per ranked Workstream, in priority order
+  and with a reason, `## <id> <title> (not ranked)` for the others, and
+  `## Open questions`.
+- A rule that applies to every agent belongs in `user.md` under Preferences,
+  not in `user-work.md`.
+
+## Report
+
+Write the report in the reports folder: sources read and gaps, changes to each
+file, drift findings, questions asked. Add a `## Feed` line: the script's JSON
+fields and any fallback.
+
+Write the report before you send any email. If the write is refused or fails,
+retry it once (with Bash if Write was refused). If it still cannot be written,
+do not link it.
+
+Do not end your turn until the report is written or its failure is stated.
+End with one line: what changed, or that nothing did, or that the report
+failed.
+
+## Email The User Every Run
+
+Send one email every run, quiet nights included. The user expects it; a
+missing email tells them the run failed. Use tldr messaging:
+`tldr-agents messaging agent send --to user --channel email --subject "<subject>" --reason "<why now>" --body-file <file>`.
+
+- Something material changed: a new or changed priority, a Workstream proposed
+  for confirmation, a drift question, a removed fact, or
+  each new or changed assignment of a section to an agent (kestrel → ac-aiw).
+  Lead with what changed and what you need.
+- A quiet night: say so in the subject. In the body, list what you updated,
+  if anything, in a few short lines, or say that nothing changed.
+
+Link the report only when it was written. If it failed, the email says the
+report failed and why. A reply resumes this agent; treat it as an explicit
+correction.
+
+## Do Not
+
+- Edit another agent's home or `work.md`, except the one `academy notes add`
+  append in step 2.
+- Write a fact from one noisy day, a mood, or a secret.

package/templates/skills/work-graph/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: work-graph
+layer: craft
+description: Use when work you see or do may belong to a Workstream - before you start a sustained effort, when the user decides a priority or pause, or when you must find, link, propose, or update a Workstream in Beads.
+---
+
+# Work Graph
+
+A Workstream is a durable body of purposeful work. It outlives sessions, epics,
+and handoffs. It lives in Beads, in the one user database that `BEADS_DIR`
+points to, next to the tasks that advance it. Call `bd` with `--json`.
+
+A Workstream is not an epic (one bounded implementation) and not a Topic (a
+conversation). Goals and priorities are not Beads items; they live in `work.md`
+and `user-work.md`, which name Workstreams by Beads id.
+
+## Procedure
+
+1. **Identify.** Does this effort survive a session and serve a purpose? If it
+   is bounded execution work, it is a task, not a Workstream.
+2. **Match first.** List the Workstream titles with
+   `bd list --type workstream --json`. Open the full `user-work.md` only when
+   you need more. Then run `bd search "<two or three key words>" --json` and try a synonym. Run
+   `bd find-duplicates --json` when the area looks crowded. Search closed items
+   too: a `rejected` Workstream blocks a new proposal from the same evidence.
+3. **Link when one matches.** Connect the task or epic to the Workstream. This
+   link does not block: `bd dep add <workstream-id> <task-id> --type tracks --json`.
+4. **Propose when none matches.**
+   - `bd create "<title>" --type workstream --description "<purpose, intended outcome, evidence>" --labels owner:<who is accountable> --json`
+   - `bd set-state <id> ws=proposed --reason "<evidence>" --json`
+
+   Use `owner:{{agent_id}}` when you will drive it, else `owner:user`.
+5. **Update.** Add evidence with `bd update <id> --append-notes "<what changed, source>" --json`.
+   Change state with `bd set-state <id> ws=<state> --reason "<why>" --json`.
+   Label a task you create for a Workstream `owner:{{agent_id}}`.
+
+## State Rules
+
+States: `proposed`, `active`, `paused`, `done`, `rejected`. Close a `done` or
+`rejected` Workstream with `bd close <id> --reason "<evidence>" --json`.
+
+- Any agent may propose a Workstream, add notes, and add links.
+- A Workstream becomes `active` only when the user confirms it, or when the
+  user's own action shows it ("I'm implementing X this week"). Quote those
+  words in the reason.
+- Never activate on inference alone: not on activity, not on mentions, not on
+  your own judgment. Ask the user instead.
+- An Owner may make a Workstream `active` inside its mandate. It reports each
+  new one in its daily message.
+- Pause or finish a Workstream on the user's word. An Owner may do it inside
+  its mandate.
+- A `rejected` Workstream keeps a note with the reason. Do not propose it
+  again from the same evidence.
+- A user correction ("not a priority", "pause it", "wrong Workstream") goes at
+  once on the Workstream as a note that starts `User said (<date>):`. Act on
+  it if it is a state change. The nightly gives it precedence.
+
+## Duplicates
+
+Related Workstreams with different outcomes or owners are not duplicates. Close
+a real duplicate and keep the history: `bd duplicate <id> --of <canonical-id> --json`
+or `bd supersede <id> --with <new-id> --json`.
+
+## Keep Workstreams Out Of The Ready Queue
+
+The ready query lists open Workstreams as if they were tasks. Every ready query
+adds `--exclude-type workstream`, for example
+`bd ready --json --exclude-type workstream`. Never claim or work a Workstream
+as a task.
+
+## Do Not
+
+- Edit `user-work.md`. Only the curator's user-nightly writes it.
+- Rewrite `work.md` mid-session unless the user asks. Your nightly consolidates it.
+- Open a Workstream for a one-off task.

package/conformance/README.md

@@ -1,60 +0,0 @@
-# Academy client conformance suite
-
-This suite checks that an Academy build implements the client contract. It is
-written for authors of clients that drive Academy, not for Academy's own
-developers: it never imports Academy source and asserts only what a client can
-observe — the response envelope, the exit status, and the published error codes.
-
-## Run it
-
-```sh
-# against the build in this package
-node --test conformance/*.test.mjs
-
-# against any other build
-ACADEMY_BIN=/usr/local/bin/academy node --test conformance/*.test.mjs
-```
-
-`ACADEMY_BIN` is the path of the Academy launcher to test. Unset, the suite
-drives the `bin/academy` beside this directory. Point it at a global install, an
-unpacked tarball, or a source checkout — the assertions are the same.
-
-Requirements: Node 18 or later, a POSIX shell, and nothing else. No packages are
-installed and no test framework is used.
-
-## What it asserts
-
-| File | Asserts |
-| --- | --- |
-| `discovery.test.mjs` | `doctor --json` — the published command list, the payload keys, the version rule, and the one state answered `ok:false` |
-| `identity.test.mjs` | Every agent-addressed command refuses an out-of-root agents root and an out-of-root agent directory, and writes nothing outside the root |
-| `error-codes.test.mjs` | An invocation for each of the fifteen published error codes |
-| `envelope.test.mjs` | The envelope and the exit rule across every published command, on success and on failure |
-
-## Safety
-
-Every test builds its own throwaway install: a fresh temporary `HOME`, a fresh
-temporary `AGENTS_ROOT`, and a `PATH` built from nothing. Values already
-exported into your shell are **not** inherited by the build under test. The
-suite drives the full lifecycle, including `delete`, `archive`, `rename` and
-`migrate`, and can reach no agent outside its own temporary directories.
-
-## Stubs
-
-Two executables Academy uses are stubbed, because neither is part of the
-response contract and a client author must not need either installed:
-
-- `helm-tasks` — the scheduler Academy registers each agent's nightly job with.
-  Academy resolves it from `PATH`, or from `ACADEMY_HELM_TASKS_BIN`. Without it,
-  `create`, `delete`, `rename` and `archive` answer `runtime_unavailable`.
-- `claude` — the runtime `hire --spec` drives. Academy resolves it from `PATH`,
-  or from `ACADEMY_CLAUDE_BIN`.
-
-The scheduler stub is also the only way to reach `unschedule_failed` and
-`unschedule_failed_restore_blocked` from outside the binary.
-
-## Reading a failure
-
-Each assertion prints the exit status and both streams of the invocation that
-produced it, so a failure names the command, the envelope it returned, and the
-field that disagreed.

package/conformance/discovery.test.mjs

@@ -1,140 +0,0 @@
-// Discovery — what a client learns before it renders anything.
-//
-// `doctor --json` is the one call a client may make against an Academy it knows
-// nothing about. Everything else in this suite is driven from what it answers.
-
-import assert from 'node:assert/strict';
-import { existsSync, rmSync, symlinkSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
-import { join } from 'node:path';
-import test from 'node:test';
-import { academy, assertFailure, assertSuccess, createHost, hireAgent } from './harness.mjs';
-
-// The frozen answer at contract_version 1, in order. A client may key on the
-// order, so this is asserted by equality rather than by membership.
-const PUBLISHED_COMMANDS = [
-  'doctor',
-  'list',
-  'inspect',
-  'tokens',
-  'budget',
-  'sessions',
-  'events',
-  'create',
-  'hire',
-  'rename',
-  'archive',
-  'unarchive',
-  'delete',
-  'migrate',
-];
-
-// Commands an Academy build may implement but must not publish. A client that
-// found one here would build on a surface with no contract behind it.
-const UNPUBLISHED_COMMANDS = ['notes', 'nightly', 'clean', 'root', 'run', 'destroy'];
-
-// The payload keys, in order, after the three envelope keys.
-const DOCTOR_PAYLOAD_KEYS = [
-  'contracts',
-  'version',
-  'packageRoot',
-  'agentsRoot',
-  'eventLog',
-  'commands',
-  'runtimes',
-  'errors',
-];
-
-// `errors[]` is a health channel, not the error channel: it names a degraded
-// part of an install and how much of it there is. None of the fifteen failure
-// codes may appear here.
-const HEALTH_CODES = ['unowned_agents', 'invalid_runtime_agents', 'unattributable_sessions'];
-
-test('doctor publishes the whole command set, in order', () => {
-  const host = createHost();
-
-  const payload = assertSuccess(academy(host, ['doctor', '--json']), 'doctor');
-
-  assert.deepEqual(payload.commands, PUBLISHED_COMMANDS);
-  for (const command of UNPUBLISHED_COMMANDS) {
-    assert.equal(payload.commands.includes(command), false, `${command} must not be published`);
-  }
-});
-
-test('doctor answers with exactly the published payload keys', () => {
-  const host = createHost();
-
-  const payload = assertSuccess(academy(host, ['doctor', '--json']), 'doctor');
-
-  assert.deepEqual(Object.keys(payload), [
-    'contract_version',
-    'ok',
-    'command',
-    ...DOCTOR_PAYLOAD_KEYS,
-  ]);
-  assert.deepEqual(payload.contracts, [1]);
-  assert.equal(typeof payload.packageRoot, 'string');
-  assert.equal(typeof payload.agentsRoot, 'string');
-  assert.equal(typeof payload.eventLog, 'string');
-  assert.deepEqual(Object.keys(payload.runtimes).sort(), ['claude_code', 'codex']);
-  for (const runtime of Object.values(payload.runtimes)) {
-    assert.equal(typeof runtime.available, 'boolean');
-  }
-});
-
-// Two builds with different capabilities must never report the same version. A
-// checkout names its own commit as semver build metadata; an install has no
-// checkout to name and reports the published version bare.
-test('doctor reports build metadata only for a checkout', () => {
-  const host = createHost();
-
-  const payload = assertSuccess(academy(host, ['doctor', '--json']), 'doctor');
-
-  assert.equal(typeof payload.version, 'string');
-  assert.notEqual(payload.version, '');
-  if (describesItsOwnCheckout(host, payload.packageRoot)) {
-    assert.match(payload.version, /^[^+]+\+[0-9A-Za-z-]+$/);
-  } else {
-    assert.equal(payload.version.includes('+'), false);
-  }
-});
-
-function describesItsOwnCheckout(host, packageRoot) {
-  if (!existsSync(join(packageRoot, '.git'))) return false;
-  return spawnSync('git', ['--version'], { env: host.env, encoding: 'utf8' }).status === 0;
-}
-
-// A degraded component is not a failure. A client calls doctor before it renders
-// anything, so an install with repairable faults must still be usable.
-test('a degraded install stays ok:true and exits 0', () => {
-  const host = createHost();
-  hireAgent(host, 'kai');
-  rmSync(join(host.agentsRoot, 'kai', '.academy-agent.json'));
-
-  const result = academy(host, ['doctor', '--json']);
-
-  const payload = assertSuccess(result, 'doctor');
-  assert.equal(result.status, 0);
-  assert.deepEqual(payload.errors, [{ code: 'unowned_agents', count: 1 }]);
-  for (const entry of payload.errors) assert.equal(HEALTH_CODES.includes(entry.code), true);
-});
-
-// The one state doctor answers with ok:false: every agent-addressed command
-// would fail on this root, so a client told ok:true would render an interface
-// whose first call fails. The payload still ships, beside the error.
-test('doctor is ok:false only when the agents root fails its audit', () => {
-  const host = createHost();
-  symlinkSync(host.outside, host.agentsRoot);
-
-  const result = academy(host, ['doctor', '--json']);
-
-  const envelope = assertFailure(result, 'doctor', 'unsafe_agent_path');
-  assert.deepEqual(Object.keys(envelope), [
-    'contract_version',
-    'ok',
-    'command',
-    ...DOCTOR_PAYLOAD_KEYS,
-    'error',
-  ]);
-  assert.deepEqual(envelope.commands, PUBLISHED_COMMANDS);
-});

package/conformance/envelope.test.mjs

@@ -1,185 +0,0 @@
-// The envelope, swept across every published command.
-//
-//   success   stdout, exit 0   { contract_version, ok: true,  command, ...payload }
-//   failure   stderr, exit 1   { contract_version, ok: false, command, error }
-//
-// Exit status is 0 if and only if `ok` is true. The table is checked against
-// the command list `doctor` publishes, so a build that publishes a command this
-// suite has no case for fails here rather than going unchecked.
-
-import assert from 'node:assert/strict';
-import { symlinkSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import test from 'node:test';
-import {
-  academy,
-  assertFailure,
-  assertSuccess,
-  createHost,
-  hireAgent,
-  publishedCommands,
-} from './harness.mjs';
-
-function agentHost() {
-  const host = createHost();
-  hireAgent(host, 'kai');
-  return host;
-}
-
-function archivedHost() {
-  const host = agentHost();
-  assertSuccess(academy(host, ['archive', 'kai', '--json']), 'archive');
-  return host;
-}
-
-// An agents root that resolves outside itself — the one state that fails every
-// command reading the root, and so the failure case for the two that address no
-// agent and reject no option.
-function escapedHost() {
-  const host = createHost();
-  symlinkSync(host.outside, host.agentsRoot);
-  return host;
-}
-
-function specHost() {
-  const host = createHost();
-  const body = { name: 'kai', role: 'conformance subject', objective: 'exist' };
-  writeFileSync(join(host.root, 'spec.json'), JSON.stringify(body));
-  return host;
-}
-
-// `hire` without --spec execs into an interactive session with inherited stdio
-// and can never print an envelope, so the headless form is the one under test.
-const SPEC = (host) => join(host.root, 'spec.json');
-
-const CASES = {
-  doctor: [createHost, () => ['doctor'], escapedHost, () => ['doctor'], 'unsafe_agent_path'],
-  list: [createHost, () => ['list'], escapedHost, () => ['list'], 'unsafe_agent_path'],
-  inspect: [
-    agentHost,
-    () => ['inspect', 'kai'],
-    createHost,
-    () => ['inspect', 'ghost'],
-    'agent_not_found',
-  ],
-  tokens: [
-    agentHost,
-    () => ['tokens', 'kai'],
-    createHost,
-    () => ['tokens', 'ghost'],
-    'agent_not_found',
-  ],
-  budget: [
-    agentHost,
-    () => ['budget', 'kai'],
-    createHost,
-    () => ['budget', 'ghost'],
-    'agent_not_found',
-  ],
-  sessions: [
-    createHost,
-    () => ['sessions'],
-    createHost,
-    () => ['sessions', '--nope'],
-    'invalid_spec',
-  ],
-  events: [
-    createHost,
-    () => ['events', '--since', '0'],
-    createHost,
-    () => ['events', '--since', '99999'],
-    'replay_unavailable',
-  ],
-  create: [createHost, () => ['create', 'kai'], agentHost, () => ['create', 'kai'], 'agent_exists'],
-  hire: [
-    specHost,
-    (h) => ['hire', '--spec', SPEC(h)],
-    createHost,
-    (h) => ['hire', '--spec', SPEC(h)],
-    'invalid_spec',
-  ],
-  rename: [
-    agentHost,
-    () => ['rename', 'kai', 'nova'],
-    createHost,
-    () => ['rename', 'ghost', 'nova'],
-    'agent_not_found',
-  ],
-  archive: [
-    agentHost,
-    () => ['archive', 'kai'],
-    createHost,
-    () => ['archive', 'ghost'],
-    'agent_not_found',
-  ],
-  unarchive: [
-    archivedHost,
-    () => ['unarchive', 'kai'],
-    createHost,
-    () => ['unarchive', 'ghost'],
-    'agent_not_found',
-  ],
-  delete: [
-    agentHost,
-    () => ['delete', 'kai'],
-    createHost,
-    () => ['delete', 'ghost'],
-    'agent_not_found',
-  ],
-  migrate: [createHost, () => ['migrate'], createHost, () => ['migrate', '--nope'], 'invalid_spec'],
-};
-
-test('every published command has a success case and a failure case', () => {
-  const published = publishedCommands(createHost());
-
-  assert.deepEqual([...published].sort(), Object.keys(CASES).sort());
-});
-
-for (const [command, [okHost, okArgs, failHost, failArgs, code]] of Object.entries(CASES)) {
-  test(`${command} answers success in the envelope with exit 0`, () => {
-    const host = okHost();
-
-    const result = academy(host, [...okArgs(host), '--json']);
-
-    assertSuccess(result, command);
-    assert.equal(result.status, 0);
-    assert.equal(result.stderr, '');
-  });
-
-  test(`${command} answers failure in the envelope with a non-zero exit`, () => {
-    const host = failHost();
-
-    const result = academy(host, [...failArgs(host), '--json']);
-
-    assertFailure(result, command, code);
-    assert.notEqual(result.status, 0);
-    assert.equal(result.stdout, '');
-  });
-}
-
-// The one success that carries a false flag in its payload. The exit rule
-// follows `ok`, never the payload, so a client must not read a budget breach as
-// a failed command.
-test('a payload reporting a breach is still ok:true and exit 0', () => {
-  const host = agentHost();
-  writeFileSync(join(host.agentsRoot, 'kai', 'knowledge.md'), 'over the cap. '.repeat(4000));
-
-  const result = academy(host, ['budget', 'kai', '--json']);
-
-  const payload = assertSuccess(result, 'budget');
-  assert.equal(result.status, 0);
-  assert.equal(payload.withinBudget, false);
-});
-
-// The health channel is not the error channel: a degraded component is reported
-// beside an ok:true answer, and the exit rule still follows `ok`.
-test('doctor reporting health errors is still ok:true and exit 0', () => {
-  const host = agentHost();
-  writeFileSync(join(host.agentsRoot, 'kai', 'agent.yaml'), 'name: kai\nruntime: mainframe\n');
-
-  const result = academy(host, ['doctor', '--json']);
-
-  const payload = assertSuccess(result, 'doctor');
-  assert.equal(result.status, 0);
-  assert.deepEqual(payload.errors, [{ code: 'invalid_runtime_agents', count: 1 }]);
-});