@joenandez/academy 0.4.0-rc.1 → 0.5.12

package/.claude-plugin/marketplace.json

@@ -9,6 +9,11 @@
       "name": "academy",
       "source": ".",
       "description": "Academy v3 — portable AI agents."
+    },
+    {
+      "name": "roque",
+      "source": "./hooks/roque",
+      "description": "Roque: keeps long sessions on track across compaction."
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "academy",
   "description": "Academy v3 — portable AI agents.",
-  "version": "0.4.0-rc.1",
+  "version": "0.5.12",
   "hooks": "./hooks/hooks.json"
 }

package/CHANGELOG.md

@@ -3,6 +3,420 @@
 This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 The heading at the top of this file is the version in `package.json`.
 
+<!--
+The release skill folds the block below into the `## <target>` section when it
+cuts the next release. It is not a `## ` heading, so the version check in
+`scripts/release-check.mjs` still reads the released version at the top.
+-->
+
+## 0.5.12 — 2026-10-19
+
+### Added
+
+- **Backstory memory for agents.** The Stop-hook sweep also copies Backstory
+  observations (`BACKSTORY_HOME`, default `~/.backstory`) for the agent's
+  recorded sessions into its archive, so an agent that runs on Backstory instead
+  of Subspace memory still feeds its nightly. Nightly sessions are now marked in
+  `memory/sessions.jsonl`, and their own observations are never swept.
+
+## 0.5.11 — 2026-10-19
+
+### Changed
+
+- **Context compression: agents just note, and the nightly routes.** Agents
+  add notes with `academy notes add` and no longer pick a file. Each nightly
+  files a note into knowledge, work, a new `references/` file, or Beads (system
+  notes become `academy-system` tasks). The curator hands agent-specific
+  `[proposed]` user lines back to that agent.
+- **The nightly runs only when there is something to do.** A note or new
+  session arms it; a night with no new input skips in code, without a model
+  run. A night with an empty archive still curates notes and trims.
+- **`references/` holds conditional facts.** Each file is reached by a
+  `useWhen` line in an always-on file, and `academy skills check` measures it.
+  Owner hires write their environment and context to `references/mandate.md`;
+  curation never edits that file.
+- **Budgets.** The mandate cap is 600 tokens, enforced and reported, but it
+  never blocks a nightly. Staged `## Proposed` lines in `user.md` do not count.
+  `user.md` is organized in tiers, with `## Proposed` last.
+
+### Fixed
+
+- **A note added during a nightly is never lost.** Every writer saves its input
+  and arms the nightly marker in one locked step, and a marker the last run did
+  not use always launches the next one. A lock left by a dead process clears
+  after 60 seconds.
+
+## 0.5.10 — 2026-10-18
+
+### Changed
+
+- **The curator emails the user after every nightly run, quiet nights
+  included.** Before, it wrote only when something material changed, so a
+  quiet night looked the same as a failed run. A material change still leads
+  with what changed and what the curator needs. A quiet night says so in the
+  subject, and the body lists what was updated or says that nothing changed.
+- **Internal: the curator feed code is split into smaller modules** so the
+  pre-push quality gate passes again. The feed's output is unchanged.
+
+## 0.5.9 — 2026-10-17
+
+### Fixed
+
+- **Scheduled agent runs in a memory topic now keep their memory.** When a run
+  inherits a topic (its project and workspace) without the memory-enabled flag,
+  as a scheduled job does, `academy run` now sets the flag. Before, the
+  client skipped every turn of such a run, and the session record kept no
+  topic, so the agent's nightly found nothing to consolidate. An explicit flag
+  value, such as `0`, is kept.
+
+## 0.5.8 — 2026-10-17
+
+### Added
+
+- **Every Principal sends a morning brief.** A new job,
+  `<name>-principal-brief`, runs each day at 07:00 in the agent's timezone and
+  starts the new `principal-brief` skill. The agent emails the user a short
+  agenda: what they did together the day before, and what to pair on today.
+  It suggests an idea only from something the user said, with its date. The
+  brief only reads, writes, and sends; it starts no work. The agent picks the
+  sections and the length, and keeps a quiet day short. A local rule can change
+  the brief or turn it off. `create` registers the job for a new Principal,
+  `stop`, `archive`, and `delete` remove it, and `start` registers it again. An
+  existing Principal gets the job with `academy start <name>`. A rename keeps
+  the job. Under a named `AGENTS_ROOT`, the brief gets the same
+  `jobs.agents_root` warning as the nightly.
+- **Every agent can read the user feed.** The feed script now serves any
+  agent, and the operating model lists it in every agent's Tools table. By
+  default it holds only the entries attributed to the calling agent. `--all`
+  holds every entry, and `--project`, `--topic`, and `--branch` narrow it; a
+  header line counts the entries each filter leaves out. `--max-tokens` caps
+  the file (default 25,000). When the cap cuts, the oldest entries go first and
+  a header line says how many went and how to narrow the window. A cap smaller
+  than the header is refused.
+
+### Changed
+
+- **The curator still reads every entry.** The `user-nightly` skill runs the
+  feed with `--all --max-tokens 500000`, so the curator's file is the same as
+  in 0.5.7.
+
+### Fixed
+
+- **The agent-written brief mark names no person.** Spectre plan-review briefs
+  in the feed are now marked
+  `[likely agent-written brief, not the user's words]`.
+
+## 0.5.7 — 2026-10-17
+
+### Added
+
+- **The curator reads a daily feed.** A new script,
+  `scripts/cli/curator-feed.mjs`, writes one file per night to the curator's
+  `dreams/user-feed/` folder. It holds every prompt the user typed in Claude
+  Code and Codex chat, every email the user sent to an agent through tldr, and
+  the last memory observation of each turn, each with its time, project,
+  branch, session, and agent. Automation turns are left out only by an entry
+  flag, an exact generated string, or a complete generated envelope; a typed
+  prompt is never dropped for its opening words. Spectre plan-review briefs
+  stay in, marked as likely agent-written. Prompts are cut at 2,000 characters
+  with a `[cut: N chars]` marker. When one source fails, the file still holds
+  the others. The script prints one JSON line with the counts, the source
+  states, and the token totals of the curator's previous run.
+- **Sessions record their injected context size.** Each `sessions.jsonl` row
+  now carries a `context` measurement (total, overhead, per-surface tokens,
+  skill listing) and the transcript path, so context growth can be tracked per
+  agent.
+
+### Changed
+
+- **The `user-nightly` skill reads the feed first.** The curator runs the
+  feed script, reads the whole file, and searches memory or transcripts only
+  to settle a question the feed cannot answer. When a source fails, it falls
+  back to its old search for that source. Its report gets a `## Feed` section
+  with the feed size and the previous run's tokens. On a test day the run
+  took 9 minutes instead of 46 and used 34 model calls instead of 53.
+- **Roque sync.** Roque `f62066c` (0.1.1): `3c61e59` retires the standalone
+  Roque release, and `f62066c` documents that Roque ships inside Academy. No
+  hook behavior changed.
+
+## 0.5.6 — 2026-10-15
+
+### Added
+
+- **Roque ships with Academy.** Every agent session now loads Roque, which
+  keeps long sessions on track across compaction. Near the compaction point
+  (75% and 90%) it asks the agent to keep a state file at
+  `.roque/state/<session>.md`. After a compaction it gives that state back to
+  the agent. Claude Code sessions also save each compaction summary. Claude
+  Code loads the Roque copy in Academy with `--plugin-dir`, so an installed
+  `roque` plugin does not run a second time. Codex sessions get two Roque
+  hooks next to the Academy hooks; approve them once in Codex `/hooks`.
+  `.roque/off` in a project turns Roque off there. First Roque sync: Roque
+  `bf4c36b` (0.1.1).
+- **Normal sessions can install Roque from Academy.** The Academy marketplace
+  now lists `roque`: `claude plugin install roque@academy-local`.
+
+### Changed
+
+- **Agent sessions compact at a 430,000-token window.** `academy run` sets
+  `CLAUDE_CODE_AUTO_COMPACT_WINDOW=430000` for each Claude Code session it
+  starts. A value already set in the environment wins. Other sessions do not
+  change.
+
+## 0.5.5 — 2026-10-15
+
+### Added
+
+- **The Owner loop.** An Owner now keeps a strategy, runs a weekly
+  owner-review with the user, drives initiatives, and schedules its own
+  follow-up sessions. A new Owner gets a seeded `craft.md` and identity, and
+  says hello with a first update on its first daily open.
+- **Owner onboarding.** `academy create` makes an Owner as a draft. A draft
+  Owner has only the nightly job and does not run. `academy start <agent>`
+  checks the Owner's mandate and terms, registers its jobs, and requests one
+  first daily run. A failed start restores the earlier state.
+- **`academy stop <agent>`.** Stop marks the agent stopped, deletes every job
+  of the agent, and keeps its files. A stopped agent does not run until
+  `academy start`.
+- **Default names.** `academy create` without a name picks the first free
+  default name.
+- **Rename keeps the agent.** Each agent has a fixed id. `academy rename`
+  changes only the name: the folder, jobs, run routes, and Beads labels keep
+  the fixed id. Commands accept the fixed id or the current name.
+- **A Principal can hire an Owner** through the Owner hire steps.
+
+### Changed
+
+- `academy doctor` lists `start` and `stop` in its command list and usage.
+- A terminal Owner create prints how to start the draft.
+- Every tldr call has a 60 s limit, so a hung call cannot hold the lifecycle
+  lock.
+
+### Fixed
+
+- An agent loads the `user-work.md` sections that name its fixed id or its
+  current name.
+- `academy list`, `clean`, and `run` use the current name after a rename.
+- `academy hire` counts a draft Owner as a taken name and never reuses an
+  existing agent.
+- An Owner backs off only after an empty session.
+- Archive and rename delete an Owner's self-scheduled sessions.
+
+## 0.5.4 — 2026-10-13
+
+### Changed
+
+- **Scheduled runs bypass permission prompts by default.** A nightly run
+  without a permission flag on its job now launches Claude Code with
+  `--permission-mode bypassPermissions` (was `auto`) and Codex with
+  `--dangerously-bypass-approvals-and-sandbox` (was `--ask-for-approval never
+  --sandbox workspace-write`). New Owner daily and heartbeat jobs store
+  `bypassPermissions` for Claude and `danger-full-access` for Codex. A mode
+  already stored on a job is never changed.
+
+### Fixed
+
+- **Nightly runs can write their memory files again.** Auto mode refused every
+  file write in an unattended run, so the nightly kept no work, notes,
+  knowledge, or dreams report.
+
+## 0.5.3 — 2026-10-12
+
+### Added
+
+- **A new Principal opens with a short first-session intro.** `create --kind
+  principal` now writes `intro-pending.md` in the agent's home. The first
+  `academy run` of that Principal from a terminal, with nothing after `--`,
+  starts the session with one plain sentence that points at the
+  `principal-intro` skill. A scheduled run, a headless run, a resume, and any
+  run with a passthrough never starts the intro. `run` writes one
+  `run.intro_seed` line to stderr when it does.
+- **`create --kind principal` in a terminal asks for a missing name and starts
+  the first session.** `--no-start` creates the agent and prints
+  `academy run <name>` instead. `--json`, a pipe, and every other kind take the
+  same path as before: a missing name is still `invalid_name`, and the
+  `create` envelope has no new field. `contract_version` stays `1`.
+
+### Changed
+
+- **The Principal mandate names the work, not projects.** A new Principal's
+  `mandate.md` has a `## Working on` section. The first session adds one
+  `- <ws-id> <title>` line for the work the user names, and the curator uses
+  it to map that Workstream to the Principal. The template has no
+  `## Projects` or `## Environment` section, and the Principal operating
+  model points at the work in the mandate.
+
+## 0.5.2 — 2026-10-12
+
+### Changed
+
+- **Each agent loads only its own part of `user-work.md`.** The shared file is
+  now a short preamble and `##` sections, one for each goal and each
+  Workstream. Each section has an `agents:` line with agent names or `none`.
+  When `academy run` compiles an agent's prompt, it keeps the preamble and
+  only the sections that name the agent, and it removes the `agents:` lines.
+  A section without an `agents:` line goes to no agent, and an agent that no
+  section names gets the preamble only. Claude and Codex get the same view.
+  `academy run` writes one `run.user_work_view` line to stderr with the
+  section and kept counts.
+- **`academy tokens` and `academy budget` count each agent's share** of
+  `user-work.md`, not the whole file. The JSON shape is unchanged, and
+  `contract_version` stays `1`.
+- **The curator's `user-nightly` skill writes the sectioned format.** It maps
+  sections to agents from mandates and Beads `owner:` labels, checks each
+  mapped agent's budget, and lists each new or changed assignment in its
+  email. Rules that apply to every agent go to `user.md` Standing rules.
+- **Agent skills read the full `user-work.md` only on demand.** The operating
+  model and the work skills say the agent's share is in its prompt.
+  `work-graph` lists Workstream titles with `bd list --type workstream --json`
+  before it proposes a new Workstream.
+
+## 0.5.1 — 2026-10-09
+
+### Changed
+
+- **A user can create any number of Principals.** `create --kind principal`
+  no longer refuses a second Principal, live or archived. The `agent_exists`
+  reason `principal_exists` is retired and no longer raised. `contract_version`
+  stays `1`: no field was added or removed. A create now writes each missing
+  shared seed with an exclusive-create flag, so concurrent creates and
+  `academy notes add --user` never overwrite `user.md` or `user-work.md`.
+- **The Principal pack mandate has a Projects section.** A new Principal's
+  `mandate.md` starts with `- Not yet named.` under `## Projects` and tells the
+  Principal to ask the user in its first session which projects it covers. The
+  pack text no longer says "all projects".
+
+### Fixed
+
+- **A create that loses a same-name race no longer deletes the winner.** When
+  two `academy create` requests for one name run at once, the one that loses
+  the directory creation now refuses with `agent_exists` and removes nothing.
+  Before, its rollback could delete the agent the other request had just made.
+- **Concurrent first creates no longer fail on the agents folder.** Creating
+  the `AGENTS_ROOT` folder is now safe when several creates start together.
+
+## 0.5.0 — 2026-10-09
+
+### Added
+
+- **`academy notes add --user "<text>"`** appends a
+  `- [proposed] YYYY-MM-DD HH:MM <agent>: <text>` line to the shared `user.md`.
+- **Skills `work-graph` and `check-in` for every kind, and `user-nightly` for
+  the curator.** `work-graph` covers Workstreams in Beads. `user-nightly`
+  maintains `user.md` and `user-work.md` each night.
+- **Agent kinds.** `academy create --kind specialist|owner|principal` makes
+  an agent of that kind, and agent records report `kind`. Each kind renders its
+  own skill list from a package-skill manifest, and every kind gets the
+  `skill-method` and `local-rules` skills and a `local-rules.md` surface.
+- **The Owner pack.** An Owner gets the `owner`, `owner-work`,
+  `owner-heartbeat`, `owner-nightly`, and `owner-feedback` skills, `owner_*`
+  settings in `agent.yaml`, and three scheduled jobs: a daily run, a heartbeat
+  inside `owner_hours`, and a nightly. `academy delete` and `archive`
+  unschedule every Academy job of the agent.
+- **The Principal pack.** One Principal per user, with its pack skills and
+  write access to the shared root for Codex runs.
+- **Scheduler skip line.** A scheduled run that decides on purpose not to start
+  a session prints one `helm.skip` line and exits 0, so the scheduler records a
+  skip and starts no fallback session.
+- **Nightly receipts.** The nightly verifies its consolidation and writes
+  `memory/nightly-last.json`; `academy doctor` reports each agent's last
+  nightly receipt and checks `bd`.
+- **Skill size check.** `academy skills check` measures unpublished skills
+  against the 2,000-token ceiling.
+
+### Changed
+
+- **Breaking: a new boot-surface file set for every agent.** Every kind now
+  boots the same nine surfaces, in this order: `identity.md`, `craft.md`,
+  `mandate.md`, `work.md`, `knowledge.md`, `notes.md`, `local-rules.md`, and the
+  shared `user.md` and `user-work.md` in `ACADEMY_HOME`. These files are
+  retired: `role.md`, `goals.md`, `priorities.md`, `threads.md`, `dailys.md`,
+  and the shared `projects.md`. `inspect` reports the new names, so a client
+  that reads or writes a retired file must move to the new names. An existing
+  agent needs a one-time, reviewed migration: split `identity.md` and `role.md`
+  into identity, craft, and mandate; fold `goals.md` into `mandate.md`; fold
+  `priorities.md` and `threads.md` into `work.md`. The migration moves the old
+  files to `<agent>/retired/` and deletes nothing. `contract_version` stays
+  `1`: Academy's own tools were the only consumers of these filenames.
+  `docs/integration-guide.md` §10 lists the new file set and the shared paths.
+- **One user Beads database.** Every kind works in the database at
+  `ACADEMY_HOME/.beads`, with `BEADS_ACTOR=<agent>@<pid>`. Workstreams are a
+  custom Beads type in it, and each Owner item carries the label
+  `owner:<agent>`. An Owner's own `.beads` directory moves into it once.
+- **The harness prompt is kept.** Academy now appends its prompt to the
+  runtime's own system prompt (inline `--append-system-prompt <text>` for Claude,
+  and `developer_instructions` for Codex). It no longer replaces that prompt.
+  Claude gets the inline form so that a host's own
+  `--append-system-prompt-file` (the Subspace terminal wrapper) combines with
+  Academy's prompt instead of being replaced by it.
+- **A shared writable home.** Every kind gets `ACADEMY_HOME` as a writable
+  directory, so any agent can append to the shared user files.
+- **The memory bridge is always on.** There is no opt-in flag. Runs go
+  through the memory wrapper when the memory environment is absent, each
+  session records its memory project and workspace, and a sweep collects
+  delayed observations.
+- **Every compiled prompt opens with the operating model** for the agent's
+  kind.
+- **Scheduling goes through `tldr-agents tasks`**, and nightly jobs register
+  with `schedule --merge`, so a re-register keeps operator edits.
+
+### Fixed
+
+- **A scheduled run for a missing agent skips instead of failing.** Under a
+  scheduler job id, `academy run` and `academy nightly` print one `helm.skip`
+  line (`agent_not_found`), log `run.agent_missing`, and exit 0, so the
+  scheduler records a skip and launches no fallback session. A run without a
+  job id still exits 1 with the not-found message.
+- **Owner status emails name the agent and the run.** The `owner-work` skill
+  starts each subject with the agent's name and says in its first body line
+  which run sent the message, in plain words.
+- **Dependency security.** `smol-toml` moves past GHSA-r4xh-jqrq-34v2.
+- **Nightly robustness.** A failed, busy, or swept nightly keeps its input; a
+  Codex nightly runs outside a git repository; a report Academy judged failed
+  never seeds a checkpoint; and the verdict and seed read the report with one
+  parser.
+- **Owner schedules.** Scheduled run flags come from the job id, an overnight
+  weekday window is read by the day it opened, and `owner_hours` is read once
+  for both the daily cron and the heartbeat guard.
+- **Prompt rendering.** The shared system prompt is written atomically, and a
+  failed write removes its temp file.
+- **`create` errors.** `create` reports the scheduler's error envelope instead
+  of its log line.
+- **Curator nightly.** It works in the foreground, writes its report before
+  any email, and states a failed report.
+
+### Removed
+
+- **`principal-memory` and `self-update` skills.** Routing moves into the
+  operating model, and graduation rules move into the nightly skills.
+- **Internal files in the package.** The packed tarball no longer carries the
+  conformance suite or the integration guide, and the release check refuses
+  internal paths.
+
+## 0.4.0 — 2026-09-02
+
+First stable release.
+
+### Changed
+
+- **Stable registry channel.** `npm install -g @joenandez/academy` installs
+  the finished 0.4.0 release. Release checks can validate an explicit new
+  target while the previous candidate tag remains.
+- **Published guidance.** The README documents stable registry installation
+  and the enforced `threads.md` budget.
+
+### Fixed
+
+- **Memory bridge opt-in.** The observation bridge copies client observations
+  only when `ACADEMY_MEMORY_BRIDGE=1`. Session tracking and pending
+  consolidation remain active when the bridge is off.
+- **Bare-run scheduler stability.** A bare run leaves the saved runtime and
+  the existing nightly registration unchanged. An explicit runtime flag is
+  the only run action that changes them.
+- **Lifecycle recovery guidance.** The integration guide explains that an
+  archive or delete change can complete before an event-log failure. It tells
+  clients to recover with `list --json`.
+
 ## 0.4.0-rc.1 — 2026-08-31
 
 First release candidate, and the first Academy artifact that can be installed