@rness/cli 0.20.1 → 0.22.0

package/README.md

@@ -29,8 +29,8 @@ Inside a workspace, every `rness` delegates to the copy pinned in
     rness logout
     rness context [--scope <name>] [--json]
     rness status [<tab>] [--json]
-    rness pulse create [<collection>] [-y]
-    rness pulse sync
+    rness board push [-y]
+    rness note [--plan <path>] [--kind approach|deviation|blocker|done] [<text>]
     rness validate
     rness mcp
 
@@ -63,8 +63,8 @@ when dropped, red `?` when missing.
 - `--json`, terminal or not: the tabs and their rows — each row with the
   colour of its status on Agent Pulse (`color`, the board's name for it:
   `yellow` for `In progress`; `red` without a status) and its item there
-  (`link`, the board filtered on its path; null without a pulse) — the
-  board (`pulse`), and what a Claude Code session shows of the workspace,
+  (`link`, the board filtered on its path; null without a board, or before
+  `board push` creates it) — the board (`pulse`), and what a Claude Code session shows of the workspace,
   worded by the CLI — the session-start banner, the footer's label, the
   scope's plans `In progress` and the notes of the safety net (see
   "Hooks"). The plugin's mod reads it (see
@@ -197,7 +197,7 @@ the pinned copy, and computes nothing itself:
   document is read from `.rness/` without its front matter, as the
   board's card shows it; `q` brings the list back, Esc still closes. An
   edit of the document shows at the next refresh. **Agent
-  Pulse is a link** when the workspace declares a pulse: the board from the
+  Pulse is a link** when the workspace has a board: the board from the
   list, the document's item (the board filtered on its path) from the
   document. The terminal opens it as it opens any hyperlink (cmd+click on
   macOS, as a rule), a desktop surface on a click. In `claude -p`, or where
@@ -244,7 +244,9 @@ workspace root's carry four Claude Code hooks, all run by the pinned copy:
   repository or nothing installed there, a `rness.json` rness refuses, a pin
   the installed copy does not match, the problems `rness validate` reports.
   A Claude Code too old for the plugin's mod gets one more line, once (see
-  "The mod"). After a compaction, the context only.
+  "The mod"). When a board keeps a journal and the scope has a plan in
+  progress, the model gets one more line: how and when to post a note (see
+  "Boards"). After a compaction, the context only.
 - **Before an edit** (`PreToolUse` on `Edit|Write`): refused, with the
   reason for the model, when it would change what `sync` generates — a
   line of the block of an `AGENTS.md` or `CLAUDE.md` (the reason names the
@@ -258,10 +260,13 @@ workspace root's carry four Claude Code hooks, all run by the pinned copy:
 - **After an edit** (`PostToolUse` on `Edit|Write`): when the file is under
   `.rness/`, its front-matter problems — or those of `rness.json` — go back
   to the model, which fixes them in the same turn. Any other edit costs one
-  path check. Stale blocks are left to `sync`. With a pulse declared, the
-  edit is then marked on the board, broken or not; see "Pulse".
-- **At session end** (`SessionEnd`): with a pulse declared, clears the marks
-  this session set and syncs the board; see "Pulse". Without one, nothing.
+  path check. Stale blocks are left to `sync`. When a board declares
+  `mark` and holds the document, the edit is then marked on it, broken or
+  not; see "Boards".
+- **At session end** (`SessionEnd`): when a board declares `clear-marks`,
+  clears the marks this session set and syncs; when one declares
+  `journal-summary`, posts the session's summary; see "Boards". Without
+  either, nothing.
 
 Each hook is one fixed `sh` line: it runs
 `<.rness>/node_modules/@rness/cli/dist/bin/rness.js hook <event>` when that
@@ -273,25 +278,97 @@ own hooks stay where they are.
 
 Claude Code runs hooks from a committed settings file without asking each
 developer, including in `claude -p`. These four read `.rness/`, write
-nothing in the workspace and run no install. Only with a pulse declared do
+no file of the workspace and run no install; with a journal, the session
+start records the clone's `HEAD` in its git directory. Only with a board created do
 they reach the network, through a detached `rness` process that uses your
-login; when that process fails, it writes why to `pulse.json` in rness's
+login; when that process fails, it writes why to `board.json` in rness's
 configuration directory (`~/.config/rness/` by default), which the next
-session start reads, says once and deletes. See "Pulse". Review a change to
+session start reads, says once and deletes (0.21 wrote `pulse.json`: read
+once too). See "Boards". Review a change to
 them like code. Verified with Claude Code 2.1.284 on 2026-09-29: in a clone
 and at the root, the model received the context; after an edit that broke a
 status, it received the problem. The `sh` line is not verified on Windows.
 
-### Pulse
-
-    rness pulse create            # once per organization: the board, then a first sync
-    rness pulse create marketing  # a collection's own project (0.17.0)
-    rness pulse sync              # every declared project, as often as wanted
-
-A projection of rness's state on the organization's GitHub Projects: a
-project named **Agent Pulse**, where the team sees — and reads — every
-document of `.rness/`, and sees when an agent is at work on one. rness
-writes the board; if it is not in rness, it does not belong there.
+### Boards
+
+    rness board push    # every board rness.json declares: created if it is not yet, then brought up to date
+    rness note "…"      # the agent's journal on the plan in progress
+
+A board is a view of the rules the agent applies: the documents of
+`.rness/` — decisions, specifications, plans, a team's own collections —
+and where an agent is at work on them. The provider supplies the tool:
+GitHub Projects today. Each board is declared in `rness.json`, under
+`boards`: first **Agent Pulse** (`pulse`), where the team sees — and reads
+— every document of `.rness/`, and sees when an agent is at work on one.
+rness writes the boards; if it is not in rness, it does not belong there.
+
+- **Boards declared in `rness.json`** (0.21.0; `boards` since 0.22.0,
+  `projects` before): `boards` maps a name to a board, written whole — its
+  `number`, `collections`, `colors`, `fields`, `labels`, `views`, and
+  optionally `title`, `description`, `readme` and `updates` (files of
+  `.rness/`) — or to a preset not created yet, by name:
+  `"boards": { "pulse": "agent-pulse", "marketing": "collection" }`
+  (`agent-pulse` for `pulse`, `collection` for a collection's board; see
+  "A board created"). What `rness.json` says is
+  the board; what it does not declare, the board does not have, but the
+  engine's own: one issue of `.rness` per document, found by its `Path`,
+  its `Status`, the label `rness`. Nothing knows Agent Pulse by name: it
+  is a board like any other, made from the preset `agent-pulse`, and the
+  example a team copies for another.
+  - `collections`: `"all"` (ADR, specs and plans with the contract's
+    statuses, then every other directory `rness status` finds, but those
+    another board holds), or directories, each with `statuses` —
+    `"contract"`, `"found"` or a list in order — a `label` and an optional
+    `field`, a select of its statuses alone.
+  - `fields`: each a `type` (`text`, `date`, `select`, `number`) and a
+    `from`: a front-matter key, or what rness knows — `$collection`,
+    `$status`, `$agent` (`working` while a session marks the card),
+    `$session`, `$sessions`, `$id` — or a list, the first present winning.
+    `Path`, `Status` and GitHub's own fields cannot be declared.
+  - `views`: each a `name` and a `layout` (`board`, `table`, `roadmap`),
+    optionally `collection` and `filter`; a board's `columns`, a table's
+    `fields`, a roadmap's `date`.
+  - `colors`: option → `gray`, `blue`, `green`, `yellow`, `orange`, `red`,
+    `pink` or `purple`; an option not named takes its kind's colour (a
+    status its tone, a collection pink). A colour changed is set at the
+    next sync, every card keeping its value.
+  - A board that `rness.json` declares wrongly is refused alone, by its
+    full key (`"boards.marketing.views[2].date" must name a date
+field`); the others sync. `validate` reports it, and also a collection
+    that is no directory of `.rness/`, one on two boards, a `readme` or
+    `updates` not there, a README that still declares (below). `readme`
+    and `updates` are paths within `.rness/`: a path out of it, or a file
+    that is a link leading out, is refused before anything is read.
+  - A view declared and missing is made; one whose filter or fields differ
+    is updated in place, keeping its id, sort and widths (GitHub returns a
+    filter as given and the fields in the project's order, read on
+    2026-10-06); one whose layout or columns differ is made again. A view
+    rness made and no longer declared is deleted; one the team made is
+    left, and said once per clone (`note view Roadmap is not declared:
+delete it on GitHub if unwanted`), as is a field no longer declared and
+    views out of the declared order (GitHub reorders none). A roadmap's
+    date is chosen in its settings: GitHub's API does not set it.
+  - **Presets and their revisions.** `board push` writes a board from a
+    preset, `agent-pulse` or `collection`, recording it (`"preset":
+"agent-pulse/1"`). When a later rness ships a newer revision, `rness
+sync` merges it into the board value by value: a value the team never
+    changed takes the new one, one it changed is kept, and said when the
+    revision changed it too (`kept boards.pulse.colors.Draft: kept orange,
+agent-pulse/2 gives blue`). Removing `preset` takes a board off the
+    merge. An upgrade commits the result, for the team to read before
+    pushing.
+  - **From 0.20 and before.** A board declared by its number
+    (`"pulse": 4`) is read as its preset, and `rness sync` — which `rness
+upgrade` runs — writes it whole; nothing changes on GitHub. A
+    collection's `README.md` that declared `description`, `statuses`,
+    `fields` or `labels` has them moved into its board and out of its front
+    matter (a value declared otherwise in both is refused, naming both).
+    Until then, `board push` skips a board whose README still declares.
+  - **From 0.21 and before.** `projects`, and the older
+    `"pulse": { "project": <number> }`, still read as `boards`; more than
+    one of the three at once is refused. `rness sync` renames the key
+    (`renamed projects to boards in .rness/rness.json`), the boards as they
+    were, and every write of `rness.json` writes `boards`.
 
 - **Items**: one per document of `rness status`, an issue of
   `<org>/.rness` added to the project. GitHub shows it only to people who
@@ -327,10 +404,9 @@ status, …`) and its body the document (see **Body**). It carries the
   on `main`, and branches of it are rare). The project is linked to
   `.rness`, so Agent Pulse shows in its Projects tab. Comments are the
   team's: a spec's discussion lives on its issue, and rness never writes
-  or deletes one. `pulse create` and `pulse sync` need Issues on
-  `.rness`. Without them they stop before
-  writing anything: `the pulse needs Issues on <org>/.rness: turn them on
-in its Settings`.
+  or deletes one. `board push` needs Issues on `.rness`. Without them it
+  stops before writing anything: `boards need Issues on <org>/.rness: turn
+them on in its Settings`.
 - **Body**: the document, the same bytes for the same document. It starts
   with a first line: the document's path and a link to the file. Then comes
   the document without its front matter (the status is a field) and
@@ -363,35 +439,46 @@ Session → Working session`). A board per directory, named as
   `rness status` names its tab, filtered on its `Collection`, its columns
   that collection's own steps: each collection has its own status field
   (`ADR status`, `Specs status`, …; a directory without statuses is columned
-  by `Status`, which holds them all for the `All` table). `pulse sync`
+  by `Status`, which holds them all for the `All` table). `board push`
   remakes a board built by an earlier version (its URL changes once); a `Working` table, filtered on `Agent: working`. A first view named `View 1` (GitHub's default) becomes `All` when no `All` exists, on create and on sync, showing Title, Collection, Status and Working session. Options are coloured (statuses by lifecycle: blue proposed, purple approved, yellow in progress, red blocked or rejected, yellow superseded, green done, gray abandoned; collections and `working` too); a sync recolours rness's options and leaves other options' colours alone. rness does
   not set the project's visibility: the project gets GitHub's default for a
   new organization project, which is private (`public: false`). Verified
   with Claude Code 2.1.284 on 2026-09-29.
-- **Login**: the pulse needs the `project` scope. `rness login` asks for it
-  when the workspace declares a pulse, or when `pulse create` needs it (in a
-  terminal it offers to log in; with `-y` or off a terminal it stops with
-  `the pulse needs a GitHub login: run rness login` or
-  `the pulse needs the project scope: run rness login`). A developer who
-  never uses the pulse grants nothing more than `repo read:org`. When GitHub
-  cannot be asked, the pulse says so (`cannot reach GitHub: …`, or GitHub's
-  own answer) instead of asking for a login. A classic `GITHUB_TOKEN` works
-  if it carries the scope; a fine-grained or GitHub App token reports no
-  scope, so the pulse refuses it whatever its permissions. An organization
+- **Login**: boards need the `project` scope. `rness login` asks for it
+  when the workspace declares a board, and `board push` when it creates one
+  (in a terminal it offers to log in; with `-y` or off a terminal it stops
+  with `boards need a GitHub login: run rness login` or
+  `boards need the project scope: run rness login`). A developer who never
+  uses boards grants nothing more than `repo read:org`. When GitHub cannot
+  be asked, rness says so (`cannot reach GitHub: …`, or GitHub's own
+  answer) instead of asking for a login. A classic `GITHUB_TOKEN` works if
+  it carries the scope; a fine-grained or GitHub App token reports no
+  scope, so boards refuse it whatever its permissions. An organization
   that restricts OAuth apps must approve "Rness", as for its private
   repositories.
-- **`pulse create`** needs an `org` in `rness.json` (a blank workspace is
-  refused) and no pulse yet. It creates the project and at once writes
-  `"projects": { "pulse": <number> }` (and the `provider`) into `rness.json`,
-  then adds the fields, options and views, and runs a first sync; its
-  `created` lines say what it added. If a step after the project fails, it
-  exits 1 with the pulse declared, and `rness pulse sync` completes the
-  layout. Commit `rness.json` in `.rness`. The number is that of the
-  project in the organization. A CLI older than 0.12.0 refuses the key, so
-  the pin moves first (`rness upgrade`). A workspace without a `provider`
-  whose repositories look like GitLab is refused before anything is
-  created: write `"provider": "github"` if the organization is on GitHub.
-- **`pulse sync`** works in two passes. First every document gets its
+- **A board created** (0.22.0): a board of `boards` without a `number` —
+  a preset's name, or a declaration that leaves it out — is not on GitHub
+  yet, and `board push` creates it. Its name is `pulse` or a collection of
+  `.rness/`, else it is refused before GitHub is asked anything (`validate`
+  says so too). In a terminal push asks once
+  (`Create Agent Pulse (pulse) on GitHub, in acme?`); `-y` does not ask.
+  Off a terminal without `-y`, or declined, it creates none, pushes the
+  others and exits 1: `not created: pulse — rness board push in a terminal,
+or with --yes, creates it`. Then, in order: the login and its `project`
+  scope, Issues on `.rness`, the project, and at once its `number` in
+  `rness.json` — a preset's name is written whole from that preset, a
+  declaration gets its `number` and nothing else — with the `provider`;
+  then the fields, options and views, and a first push. Its `created` lines
+  say what it added, and the last line what to commit
+  (`git -C .rness commit -am "chore: board pulse"`). If a step after the
+  project fails, it exits 1 with the number written, and the next
+  `board push` completes the layout. A project deleted on GitHub is not
+  made again: push stops on `GitHub has no project 4 in acme`; removing the
+  `number` asks for a new one. A workspace needs an `org` (a blank one is
+  refused); one without a `provider` whose repositories look like GitLab
+  is refused before anything is created: write `"provider": "github"` if
+  the organization is on GitHub.
+- **`board push`** works in two passes. First every document gets its
   issue — created, converted from a 0.12.0 draft, or reopened — with its
   title, label and fields. Then the bodies whose digest differs are
   written, since a body links to other documents' issues by number. It
@@ -411,15 +498,18 @@ unchanged`.
   as the team's item. A workflow someone turns on (`Item closed`, `Item
 added to project`) may change a field of rness's items; the next sync
   writes it back.
-- **A collection's own project** (0.17.0): `rness pulse create <collection>`
-  gives a directory of `.rness/` whose documents carry a status — a tab of
-  `rness status` — a project of its own, named after it, declared as
-  `"projects": { "pulse": 4, "marketing": 5 }`. Agent Pulse keeps every
-  other collection and the `Working` table; the collection's items leave
-  it (`deleteProjectV2Item`, their issues untouched) once its project
-  holds them. `pulse sync` syncs the collections' projects, then Agent
-  Pulse. The project is written from the collection's files, one way:
-  - `<collection>/README.md` is its README; its front matter may give
+- **A collection's own board** (0.17.0): `"marketing": "collection"` in
+  `boards`, then `rness board push`, gives a directory of `.rness/` whose
+  documents carry a status — a tab of `rness status` — a project of its
+  own, named after it, written whole from the preset `collection` into
+  `boards.marketing`. Agent Pulse keeps every other collection and the
+  `Working` table; the collection's items leave it (`deleteProjectV2Item`,
+  their issues untouched) once its board holds them. `board push` pushes
+  the collections' boards, then Agent Pulse. The project is written from the collection's files, one way:
+  - `<collection>/README.md` is its README (`readme` in its board since
+    0.21.0, where `description`, `statuses`, `fields` and `labels` are
+    declared too: what follows is how a README declared them before,
+    which `rness sync` moves); its front matter may give
     `description:` (the short description), `statuses:` (the columns, in
     order, each there even when empty), `fields:` (each a name, a `type` —
     `text`, `date`, `select`, `number` — and `from`, the front-matter key
@@ -438,9 +528,25 @@ added to project`) may change a field of rness's items; the next sync
   none of this reaches Agent Pulse: a workspace that declares no collection
   keeps its board as 0.16 made it.
 
-- **Hooks**, with `claude` in `agents` and a pulse declared: session start
-  marks the `In progress` plans of the session's scope `Agent: working`, with
-  the session; an edit of a document of `.rness/` marks it — one the agent has just written, with no item yet, gets its issue first
+- **Hooks**, with `claude` in `agents`: what a session does to a board is
+  declared in its `hooks` (spec 0032, 0.21.0), each event — `session-start`,
+  `edit`, `session-end` — listing actions from a fixed catalogue:
+  `mark-in-progress` (the documents of the session's scope in the given
+  `collections` and `statuses`, `plans` and `In progress` by default),
+  `mark` (the document edited, on a board that holds it) and `clear-marks`
+  (the session's marks, then a sync). Marks are written through the
+  board's select from `$agent` and its text from `$session`, whatever their
+  names. A hook never runs a command `rness.json` names: the file is the
+  organization's and the hooks run on every developer's machine. The
+  preset `agent-pulse` declares all three, which is 0.20's behaviour;
+  removing `hooks` from a board turns its marking off, and a board without
+  them is only what `board push` makes of the documents. For each event,
+  one detached `rness board run <event>` does every board's actions, in
+  the order of `boards`; a failure is recorded naming the board and the
+  action (`mark on Marketing failed: …`). A board not created yet runs
+  none. With Agent Pulse's preset:
+  session start marks the `In progress` plans of the session's scope
+  `Agent: working`, with the session; an edit of a document of `.rness/` marks it — one the agent has just written, with no item yet, gets its issue first
   through a sync, and so does one whose status the edit changed, so its
   card moves within seconds rather than at the session's end; an edit that
   leaves the status alone, or of any other file of `.rness/`, costs no sync;
@@ -453,11 +559,45 @@ added to project`) may change a field of rness's items; the next sync
   its file 3 s after `/exit`. It uses your login: with none, without the
   scope, or when GitHub cannot be reached, nothing is sent, and the next
   session start's banner says why, once:
-  `rness: pulse not updated — <reason>`, such as
-  `the pulse needs the project scope: run rness login` or
+  `rness: board not updated — <reason>`, such as
+  `boards need the project scope: run rness login` or
   `cannot reach GitHub: …`. Two sessions marking one plan both write; the
   last wins.
-- **One issue per document**: before making an issue, `pulse sync` reads
+- **Agent journal** (spec 0030, 0.21.0): how a plan was implemented, in
+  the agent's words. A board that holds `plans` declares
+  `{ "action": "journal", "to": "plan" | "repo", "limit": 5 }` at
+  `session-start`, and `journal-summary` at `session-end`. With a plan
+  `In progress` in the session's scope, the session start tells the model
+  to post a note — `rness note`, or `rness_note` — when it chooses an
+  approach, deviates from the plan, is blocked, and when done: decisions
+  and their reasons, not steps. A note is a comment headed
+  `**Approach** · claude · 1a2b3c4d · \`feat/limits\` @ \`9f8e7d6\``
+(`--kind`titles it; the branch and commit are those of the session's
+repository), then the text, from the argument or stdin. With`"plan"`it goes to the plan's issue in`.rness`. With `"repo"`, to the plan's
+implementation issue in the repository the session works in: labelled
+`rness:plan`, found again by the last line of its body, made by the
+first note and made a sub-issue of the plan's. The note prints where it
+went (`acme/api#87`), for the pull request that completes the plan there
+to carry `Closes acme/api#87`and an earlier one`Refs acme/api#87`.
+GitHub closes the issue when a person merges that pull request into the
+default branch; rness closes nothing. A repository with its issues off,
+that refuses this login's write, or not under the organization on GitHub
+sends the note to the plan's issue, its first line saying why, and the
+next session start says so once. A session in `.rness/`or at the root
+writes on the plan's issue. With several plans in progress,`--plan`names one. Each note holds 1 to 4,000 characters; a session posts at most`limit` per plan (`journal full for this session: put the rest in the
+  pull request`); a note that looks like it holds a credential (`ghp_`,
+`gho_`, `github_pat_`, `AKIA…`, a private key, `xox…-`, `sk-…`) is
+refused, never redacted. The counts stay in the `.rness` clone's git
+directory (`rness/journal`), never pushed. At the session's end,
+`journal-summary`posts`**Session summary** · claude · 1a2b3c4d ·
+  47 min`, the branch and its commits since the session started (its
+`HEAD`, recorded in the clone's git directory, `rness/sessions/<id>`)
+and the branch's pull request: to each issue the notes went to, else to
+the one plan in progress when there is a commit; with neither, nothing.
+It counts toward no limit. Not verified against GitHub yet (2026-10-06):
+a sub-issue across repositories, and `Closes` on a pull request merged
+  into the default branch.
+- **One issue per document**: before making an issue, `board push` reads
   the open issues of `.rness` labelled `rness` (one request per 100, and
   only when it has one to make). One whose body starts with the document's
   first line was made by an earlier sync, whose item the board's listing
@@ -474,10 +614,16 @@ added to project`) may change a field of rness's items; the next sync
   documents, 2026-09-30): the migration from 0.12.0 took 169 s with no
   wait; a sync with nothing to change, 4 s; the listing, one page of
   852 KB in about 1 s.
-- **Not yet**: GitLab and Atlassian. `create` lists them, disabled; a
-  workspace whose `rness.json` names one is refused by `pulse`. `Waiting`
-  and `Review` statuses, several agents on one board and hooks for agents
-  other than Claude Code are not built.
+- **Not yet**: GitLab and Atlassian, and their own boards. `create` lists
+  them, disabled; a workspace whose `rness.json` names one is refused by
+  `board push`. `Waiting` and `Review` statuses, several agents on one
+  board and hooks for agents other than Claude Code are not built.
+- **`rness pulse`**, the name of all this until 0.21: hidden, each of its
+  commands still runs as its new one and says so once on stderr
+  (`rness pulse sync is now rness board push`); `rness pulse create
+[<collection>]` adds the preset's name to `boards` when it is not there,
+  then pushes without asking. `rness pulse mark`, which 0.20's hooks
+  started, exits 0 and does nothing. The alias goes in a later minor.
 
 ### Provider
 
@@ -496,13 +642,16 @@ repository, the board).
   names.
 - A workspace without the key is read from its first repository URL: a
   GitLab host reads as `gitlab`, any other host — or no repository — as
-  `github`. Nothing to change: `pulse create` writes it, and refuses a
-  detected provider this version cannot talk to. The order of keys is
-  `contract`, `provider`, `org`, `agents`, `projects`, `repos`, `scopes`.
-  The former `"pulse": { "project": <number> }` still reads, as
-  `"projects": { "pulse": <number> }`; both at once are refused.
+  `github`. Nothing to change: `board push` writes it when it creates a
+  board, and refuses a detected provider this version cannot talk to. The
+  order of keys is `contract`, `provider`, `org`, `agents`, `boards`,
+  `repos`, `scopes`. The former `projects` and
+  `"pulse": { "project": <number> }` still read, as `boards`; more than one
+  of them at once is refused. A board in `boards` is written whole, on
+  several lines, once created; a number still reads, as its preset, until
+  `rness sync` writes it whole.
 - A provider _written_ in `rness.json` that this version cannot talk to
-  (`gitlab`) is refused by `validate`, `create`, `login` and `pulse`:
+  (`gitlab`) is refused by `validate`, `create`, `login` and `board`:
   `provider "gitlab" is not supported by @rness/cli 0.17.1 (supported:
 github)`. `add`, `sync` and the local commands never refuse. `null` is not a
   value: an absent key means none.
@@ -511,22 +660,26 @@ github)`. `add`, `sync` and the local commands never refuse. `null` is not a
 
     rness mcp      # started by the agent over stdio, not by hand
 
-A local, read-only MCP server over the workspace's `.rness/`, for an agent to
-find what applies to the repository it works in and where a subject was
-decided:
+A local MCP server over the workspace's `.rness/`, for an agent to find what
+applies to the repository it works in and where a subject was decided. It
+is read-only but for `rness_note`, listed only when a board keeps a journal
+as the server starts (Claude Code starts it with the session):
 
-| Tool                                   | Returns                                                                                                                                             |
-| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `rness_context({ scope? })`            | the scope of the working directory (or the one named) and what applies to it: standards, decisions, specifications, plans — id, status, title, path |
-| `rness_list({ collection, status? })`  | every document of a collection, across scopes, optionally of one status                                                                             |
-| `rness_read({ path })`                 | one file of `.rness/`, 256 KiB at most; nothing outside it                                                                                          |
-| `rness_search({ query, collection? })` | the documents that match, most matching first, with the matching lines                                                                              |
+| Tool                                          | Returns                                                                                                                                             |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rness_context({ scope? })`                   | the scope of the working directory (or the one named) and what applies to it: standards, decisions, specifications, plans — id, status, title, path |
+| `rness_list({ collection, status? })`         | every document of a collection, across scopes, optionally of one status                                                                             |
+| `rness_read({ path })`                        | one file of `.rness/`, 256 KiB at most; nothing outside it                                                                                          |
+| `rness_search({ query, collection? })`        | the documents that match, most matching first, with the matching lines                                                                              |
+| `rness_note({ text, session, kind?, plan? })` | a note of the agent's journal posted to GitHub, as `rness note` posts it; the issue it went to (see "Boards")                                       |
 
 - MCP over stdio, one message per line: the `2026-07-28` revision and the
   earlier ones that open with `initialize` (`2025-11-25` back to
   `2024-11-05`). No MCP SDK, no added dependency.
 - `.rness/` is read again on each call, so an edit shows at once. Nothing is
-  written.
+  written, but by `rness_note`, which posts with your login. It takes the
+  session as an argument (`claude · 1a2b3c4d`, as the session start spells
+  it): the server's environment names none.
 - With `claude` in `agents`, `sync` registers it in each clone:
   `.mcp.json` gets `mcpServers.rness`, which runs the pinned copy
   (`node ../../.rness/node_modules/@rness/cli/dist/bin/rness.js mcp`). A
@@ -558,7 +711,7 @@ anonymously.
   it — CI needs no login.
 - rness asks for `repo` and `read:org`: GitHub has no read-only scope for
   private repositories. It only lists and clones. Where the workspace
-  declares a pulse it asks for `project` too; see "Pulse".
+  declares a board it asks for `project` too; see "Boards".
 - A new workspace has to reach GitHub before teammates can join it. Logged
   in, the `create` wizard offers to do it: it creates the private repository
   `<org>/.rness` and pushes the context with `git`. Declined, refused by
@@ -695,6 +848,75 @@ per repository, the files to commit there.
 Exit codes: 0 success, 1 failure, 2 usage — or a refusal without a TTY.
 `RNESS_DEBUG=1` adds stack traces; `RNESS_NO_DELEGATE=1` skips the delegation.
 
+## 0.22.0 — `board`, not `pulse`: `rness board push`, `rness note`, `boards` in rness.json
+
+- One word for the view, whatever the provider (spec 0033, see "Boards"):
+  `rness board push` replaces `rness pulse sync`, `rness note` replaces
+  `rness pulse note`, and the hooks start `rness board run`. `rness.json`
+  names its boards `boards`; `projects` and the older `pulse` still read,
+  and `rness sync` (which `rness upgrade` runs) renames the key. `pulse`
+  stays the name of the board rness ships, Agent Pulse.
+- A board comes to exist by its declaration and a push: there is no
+  `create`. A board of `boards` without a `number`, or a preset by name
+  (`"pulse": "agent-pulse"`, `"marketing": "collection"`), is created by
+  `rness board push` once asked (`-y` off a terminal), its number then
+  written into `rness.json`.
+- `rness pulse …` still runs, hidden, as its new command, and says so on
+  stderr; it goes in a later minor. `rness pulse mark`, kept through
+  0.21.x for 0.20's hooks, now exits 0 and does nothing. Spec 0031's
+  `eject` is not built and will not be: every board is written whole.
+- The session-start notice is `rness: board not updated — …`, its record
+  `board.json` (one 0.21 left in `pulse.json` is said once), and messages
+  name boards: `boards need a GitHub login: run rness login`.
+- Upgrade with `npx @rness/cli@latest upgrade`, which runs the new copy
+  throughout: a 0.21 copy cannot read `boards` (`unknown key "boards"`).
+- For the package's API: `Manifest.projects` is `Manifest.boards`
+  (`Boards`, a record of `BoardEntry`: a number, a preset's name, or a
+  `BoardDeclaration`, whose `number` is null until the board is created).
+
+## 0.21.0 — boards declared in rness.json; what a session does to a board, declared; the agent's journal
+
+- The agent journal (spec 0030, see "Pulse"): a board declares `journal`
+  at `session-start` and `journal-summary` at `session-end`. The agent
+  posts notes on the plan it implements — `rness pulse note`, or
+  `rness_note` of `rness mcp` — to the plan's issue in `.rness`, or to an
+  implementation issue in the repository it works in, a sub-issue of the
+  plan's, which the pull request closes. The session's end posts a summary:
+  its commits, its pull request, its duration. The preset `agent-pulse`
+  declares neither: nothing changes until a board does.
+- Boards are declared in `rness.json` (spec 0031, see "Pulse"): each one's
+  collections, statuses, colours, fields, labels and views, written whole.
+  Agent Pulse is the preset `agent-pulse`, no longer a special case of the
+  code. `pulse create` writes the board it makes; `rness sync` (which
+  `rness upgrade` runs) writes a board declared by its number whole, moves
+  a collection's README declarations into its board, and merges a newer
+  revision of a preset value by value. Views are updated in place where
+  GitHub allows; a view rness made and no longer declared is deleted, the
+  team's are said once. Nothing changes on GitHub for a board 0.20 made.
+  For the package's API: `Projects` is `Record<string, number |
+BoardDeclaration>`; `BoardDeclaration` and `parseBoard` are exported.
+- A board's `readme` and `updates` stay within `.rness/`: a path out of
+  it, or a link leading out, is refused before anything is read.
+- What a session does to a board is declared in its `hooks` (spec 0032):
+  `mark-in-progress`, `mark` and `clear-marks`, from a fixed catalogue; a
+  hook never runs a command `rness.json` names. The preset `agent-pulse`
+  declares today's three, so nothing changes on GitHub. The hooks start
+  `rness pulse run <event>`; `rness pulse mark` stays, hidden, through
+  0.21.x, for sessions started before an upgrade.
+- `upgrade` run by a workspace's pinned copy installed with pnpm no longer
+  ends on `mod directory not found next to the @rness/cli package`. After
+  its commit it lists the files to commit in the clones, and that list read
+  the plugin's mod from the folder of the copy running it, which the install
+  had just removed. The list now takes the paths alone. The upgrade itself
+  was complete: 0.20.0 to 0.20.1 printed the error after its commit.
+- An upgrade to 0.21.0 run by a 0.20 copy (`pnpm rness upgrade` from
+  `.rness/`) ends, after its commit, on `rness.json: "projects" must map
+names to distinct project numbers`: the old copy, finishing, cannot read
+  the boards the new version has just written. The upgrade is complete, and
+  `rness validate` passes. `npx @rness/cli@latest upgrade` runs the new
+  copy throughout; `pnpm dlx @rness/cli` takes the previous version for a
+  day after a release, pnpm refusing a version younger than 24 hours.
+
 ## 0.20.1 — the workspace's line in the prompt footer, without a warning sign; the mod never installs the pin
 
 - The workspace's line in Claude Code moves from the pinned status line to

package/dist/bin/rness.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 import {
   OWN_COMMANDS,
-  VERSION,
   catchUp,
   findDelegate,
-  reportError,
   run
-} from "../chunk-2AFAQO5B.js";
+} from "../chunk-S4NARIQP.js";
+import {
+  VERSION,
+  reportError
+} from "../chunk-XCO5ZT2H.js";
 
 // src/bin/rness.ts
 import { pathToFileURL } from "url";

package/dist/bin/rness.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/bin/rness.ts","../../src/core/node-version.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { pathToFileURL } from 'node:url'\n\nimport { run } from '../cli.ts'\nimport { OWN_COMMANDS, catchUp } from '../core/catch-up.ts'\nimport { findDelegate } from '../core/delegate.ts'\nimport { MIN_NODE_LABEL, isSupportedNode } from '../core/node-version.ts'\nimport { reportError } from '../report.ts'\nimport { VERSION } from '../version.ts'\n\n// `rness context | head`: once the reader has its lines it closes the pipe and\n// every further write emits EPIPE on stdout. Nothing is left to deliver, so end\n// quietly with success. This is the one process.exit() in the code base — it\n// runs only when there is no output left to drain (see main() below).\nprocess.stdout.on('error', (e: NodeJS.ErrnoException) => {\n  if (e.code === 'EPIPE') process.exit(0)\n  throw e\n})\n\n// Set process.exitCode rather than calling process.exit(): process.exit()\n// terminates before Node drains an async stdout pipe, truncating piped output\n// at the ~64 KiB pipe buffer (breaks `rness context --json | jq`, `$(...)`).\nasync function main(): Promise<number> {\n  if (!isSupportedNode(process.versions.node)) {\n    process.stderr.write(\n      `rness needs Node ${MIN_NODE_LABEL} or newer (running ${process.version})\\n`\n    )\n    return 1\n  }\n  const argv = process.argv.slice(2)\n  const skipDelegation =\n    OWN_COMMANDS.includes(argv[0] ?? '') ||\n    process.env['RNESS_NO_DELEGATE'] === '1'\n  // A pin that moved is installed first, and the fresh copy runs the command\n  // as its own process (spec 0008 §4).\n  const handedOff = await catchUp(argv)\n  if (handedOff !== null) return handedOff\n  const delegate = skipDelegation\n    ? null\n    : await findDelegate(process.cwd(), VERSION)\n  if (delegate !== null) {\n    const broken = (reason: string): Error =>\n      new Error(\n        `@rness/cli ${delegate.version} pinned in ${delegate.root}/.rness is not installed correctly (${reason}); reinstall in .rness/`\n      )\n    if (process.env['RNESS_DEBUG'] === '1') {\n      process.stderr.write(\n        `rness: delegating to @rness/cli ${delegate.version} (${delegate.entry})\\n`\n      )\n    }\n    let mod: Record<string, unknown>\n    try {\n      mod = (await import(pathToFileURL(delegate.entry).href)) as Record<\n        string,\n        unknown\n      >\n    } catch (e) {\n      throw broken(e instanceof Error ? e.message : String(e))\n    }\n    if (typeof mod['run'] !== 'function')\n      throw broken('dist/index.js does not export run')\n    const delegateRun = mod['run'] as (argv: string[]) => Promise<unknown>\n    const code = await delegateRun(argv)\n    return typeof code === 'number' ? code : 1\n  }\n  return run(argv)\n}\n\nmain()\n  .then((code) => {\n    process.exitCode = code\n  })\n  .catch((e: unknown) => {\n    process.exitCode = reportError(e)\n  })\n","/** The runtime floor of the published CLI (ADR 0010): Node 22.17, the line where `fs.glob` is stable. */\nexport const MIN_NODE = { major: 22, minor: 17 } as const\nexport const MIN_NODE_LABEL = `${MIN_NODE.major}.${MIN_NODE.minor}`\n\nfunction component(version: string, index: number): number {\n  const n = Number.parseInt(version.split('.')[index] ?? '', 10)\n  return Number.isNaN(n) ? -1 : n\n}\n\nexport function nodeMajor(version: string): number {\n  return Math.max(component(version, 0), 0)\n}\n\n/** True from `MIN_NODE` on: a newer major, or the same major from its minor. */\nexport function isSupportedNode(version: string): boolean {\n  const major = component(version, 0)\n  const minor = component(version, 1)\n  if (major < 0 || minor < 0) return false\n  if (major !== MIN_NODE.major) return major > MIN_NODE.major\n  return minor >= MIN_NODE.minor\n}\n"],"mappings":";;;;;;;;;;;AACA,SAAS,qBAAqB;;;ACAvB,IAAM,WAAW,EAAE,OAAO,IAAI,OAAO,GAAG;AACxC,IAAM,iBAAiB,GAAG,SAAS,KAAK,IAAI,SAAS,KAAK;AAEjE,SAAS,UAAU,SAAiB,OAAuB;AACzD,QAAM,IAAI,OAAO,SAAS,QAAQ,MAAM,GAAG,EAAE,KAAK,KAAK,IAAI,EAAE;AAC7D,SAAO,OAAO,MAAM,CAAC,IAAI,KAAK;AAChC;AAOO,SAAS,gBAAgB,SAA0B;AACxD,QAAM,QAAQ,UAAU,SAAS,CAAC;AAClC,QAAM,QAAQ,UAAU,SAAS,CAAC;AAClC,MAAI,QAAQ,KAAK,QAAQ,EAAG,QAAO;AACnC,MAAI,UAAU,SAAS,MAAO,QAAO,QAAQ,SAAS;AACtD,SAAO,SAAS,SAAS;AAC3B;;;ADNA,QAAQ,OAAO,GAAG,SAAS,CAAC,MAA6B;AACvD,MAAI,EAAE,SAAS,QAAS,SAAQ,KAAK,CAAC;AACtC,QAAM;AACR,CAAC;AAKD,eAAe,OAAwB;AACrC,MAAI,CAAC,gBAAgB,QAAQ,SAAS,IAAI,GAAG;AAC3C,YAAQ,OAAO;AAAA,MACb,oBAAoB,cAAc,sBAAsB,QAAQ,OAAO;AAAA;AAAA,IACzE;AACA,WAAO;AAAA,EACT;AACA,QAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;AACjC,QAAM,iBACJ,aAAa,SAAS,KAAK,CAAC,KAAK,EAAE,KACnC,QAAQ,IAAI,mBAAmB,MAAM;AAGvC,QAAM,YAAY,MAAM,QAAQ,IAAI;AACpC,MAAI,cAAc,KAAM,QAAO;AAC/B,QAAM,WAAW,iBACb,OACA,MAAM,aAAa,QAAQ,IAAI,GAAG,OAAO;AAC7C,MAAI,aAAa,MAAM;AACrB,UAAM,SAAS,CAAC,WACd,IAAI;AAAA,MACF,cAAc,SAAS,OAAO,cAAc,SAAS,IAAI,uCAAuC,MAAM;AAAA,IACxG;AACF,QAAI,QAAQ,IAAI,aAAa,MAAM,KAAK;AACtC,cAAQ,OAAO;AAAA,QACb,mCAAmC,SAAS,OAAO,KAAK,SAAS,KAAK;AAAA;AAAA,MACxE;AAAA,IACF;AACA,QAAI;AACJ,QAAI;AACF,YAAO,MAAM,OAAO,cAAc,SAAS,KAAK,EAAE;AAAA,IAIpD,SAAS,GAAG;AACV,YAAM,OAAO,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC,CAAC;AAAA,IACzD;AACA,QAAI,OAAO,IAAI,KAAK,MAAM;AACxB,YAAM,OAAO,mCAAmC;AAClD,UAAM,cAAc,IAAI,KAAK;AAC7B,UAAM,OAAO,MAAM,YAAY,IAAI;AACnC,WAAO,OAAO,SAAS,WAAW,OAAO;AAAA,EAC3C;AACA,SAAO,IAAI,IAAI;AACjB;AAEA,KAAK,EACF,KAAK,CAAC,SAAS;AACd,UAAQ,WAAW;AACrB,CAAC,EACA,MAAM,CAAC,MAAe;AACrB,UAAQ,WAAW,YAAY,CAAC;AAClC,CAAC;","names":[]}
+{"version":3,"sources":["../../src/bin/rness.ts","../../src/core/node-version.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { pathToFileURL } from 'node:url'\n\nimport { run } from '../cli.ts'\nimport { OWN_COMMANDS, catchUp } from '../core/catch-up.ts'\nimport { findDelegate } from '../core/delegate.ts'\nimport { MIN_NODE_LABEL, isSupportedNode } from '../core/node-version.ts'\nimport { reportError } from '../report.ts'\nimport { VERSION } from '../version.ts'\n\n// `rness context | head`: once the reader has its lines it closes the pipe and\n// every further write emits EPIPE on stdout. Nothing is left to deliver, so end\n// quietly with success. This is the one process.exit() in the code base — it\n// runs only when there is no output left to drain (see main() below).\nprocess.stdout.on('error', (e: NodeJS.ErrnoException) => {\n  if (e.code === 'EPIPE') process.exit(0)\n  throw e\n})\n\n// Set process.exitCode rather than calling process.exit(): process.exit()\n// terminates before Node drains an async stdout pipe, truncating piped output\n// at the ~64 KiB pipe buffer (breaks `rness context --json | jq`, `$(...)`).\nasync function main(): Promise<number> {\n  if (!isSupportedNode(process.versions.node)) {\n    process.stderr.write(\n      `rness needs Node ${MIN_NODE_LABEL} or newer (running ${process.version})\\n`\n    )\n    return 1\n  }\n  const argv = process.argv.slice(2)\n  const skipDelegation =\n    OWN_COMMANDS.includes(argv[0] ?? '') ||\n    process.env['RNESS_NO_DELEGATE'] === '1'\n  // A pin that moved is installed first, and the fresh copy runs the command\n  // as its own process (spec 0008 §4).\n  const handedOff = await catchUp(argv)\n  if (handedOff !== null) return handedOff\n  const delegate = skipDelegation\n    ? null\n    : await findDelegate(process.cwd(), VERSION)\n  if (delegate !== null) {\n    const broken = (reason: string): Error =>\n      new Error(\n        `@rness/cli ${delegate.version} pinned in ${delegate.root}/.rness is not installed correctly (${reason}); reinstall in .rness/`\n      )\n    if (process.env['RNESS_DEBUG'] === '1') {\n      process.stderr.write(\n        `rness: delegating to @rness/cli ${delegate.version} (${delegate.entry})\\n`\n      )\n    }\n    let mod: Record<string, unknown>\n    try {\n      mod = (await import(pathToFileURL(delegate.entry).href)) as Record<\n        string,\n        unknown\n      >\n    } catch (e) {\n      throw broken(e instanceof Error ? e.message : String(e))\n    }\n    if (typeof mod['run'] !== 'function')\n      throw broken('dist/index.js does not export run')\n    const delegateRun = mod['run'] as (argv: string[]) => Promise<unknown>\n    const code = await delegateRun(argv)\n    return typeof code === 'number' ? code : 1\n  }\n  return run(argv)\n}\n\nmain()\n  .then((code) => {\n    process.exitCode = code\n  })\n  .catch((e: unknown) => {\n    process.exitCode = reportError(e)\n  })\n","/** The runtime floor of the published CLI (ADR 0010): Node 22.17, the line where `fs.glob` is stable. */\nexport const MIN_NODE = { major: 22, minor: 17 } as const\nexport const MIN_NODE_LABEL = `${MIN_NODE.major}.${MIN_NODE.minor}`\n\nfunction component(version: string, index: number): number {\n  const n = Number.parseInt(version.split('.')[index] ?? '', 10)\n  return Number.isNaN(n) ? -1 : n\n}\n\nexport function nodeMajor(version: string): number {\n  return Math.max(component(version, 0), 0)\n}\n\n/** True from `MIN_NODE` on: a newer major, or the same major from its minor. */\nexport function isSupportedNode(version: string): boolean {\n  const major = component(version, 0)\n  const minor = component(version, 1)\n  if (major < 0 || minor < 0) return false\n  if (major !== MIN_NODE.major) return major > MIN_NODE.major\n  return minor >= MIN_NODE.minor\n}\n"],"mappings":";;;;;;;;;;;;;AACA,SAAS,qBAAqB;;;ACAvB,IAAM,WAAW,EAAE,OAAO,IAAI,OAAO,GAAG;AACxC,IAAM,iBAAiB,GAAG,SAAS,KAAK,IAAI,SAAS,KAAK;AAEjE,SAAS,UAAU,SAAiB,OAAuB;AACzD,QAAM,IAAI,OAAO,SAAS,QAAQ,MAAM,GAAG,EAAE,KAAK,KAAK,IAAI,EAAE;AAC7D,SAAO,OAAO,MAAM,CAAC,IAAI,KAAK;AAChC;AAOO,SAAS,gBAAgB,SAA0B;AACxD,QAAM,QAAQ,UAAU,SAAS,CAAC;AAClC,QAAM,QAAQ,UAAU,SAAS,CAAC;AAClC,MAAI,QAAQ,KAAK,QAAQ,EAAG,QAAO;AACnC,MAAI,UAAU,SAAS,MAAO,QAAO,QAAQ,SAAS;AACtD,SAAO,SAAS,SAAS;AAC3B;;;ADNA,QAAQ,OAAO,GAAG,SAAS,CAAC,MAA6B;AACvD,MAAI,EAAE,SAAS,QAAS,SAAQ,KAAK,CAAC;AACtC,QAAM;AACR,CAAC;AAKD,eAAe,OAAwB;AACrC,MAAI,CAAC,gBAAgB,QAAQ,SAAS,IAAI,GAAG;AAC3C,YAAQ,OAAO;AAAA,MACb,oBAAoB,cAAc,sBAAsB,QAAQ,OAAO;AAAA;AAAA,IACzE;AACA,WAAO;AAAA,EACT;AACA,QAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;AACjC,QAAM,iBACJ,aAAa,SAAS,KAAK,CAAC,KAAK,EAAE,KACnC,QAAQ,IAAI,mBAAmB,MAAM;AAGvC,QAAM,YAAY,MAAM,QAAQ,IAAI;AACpC,MAAI,cAAc,KAAM,QAAO;AAC/B,QAAM,WAAW,iBACb,OACA,MAAM,aAAa,QAAQ,IAAI,GAAG,OAAO;AAC7C,MAAI,aAAa,MAAM;AACrB,UAAM,SAAS,CAAC,WACd,IAAI;AAAA,MACF,cAAc,SAAS,OAAO,cAAc,SAAS,IAAI,uCAAuC,MAAM;AAAA,IACxG;AACF,QAAI,QAAQ,IAAI,aAAa,MAAM,KAAK;AACtC,cAAQ,OAAO;AAAA,QACb,mCAAmC,SAAS,OAAO,KAAK,SAAS,KAAK;AAAA;AAAA,MACxE;AAAA,IACF;AACA,QAAI;AACJ,QAAI;AACF,YAAO,MAAM,OAAO,cAAc,SAAS,KAAK,EAAE;AAAA,IAIpD,SAAS,GAAG;AACV,YAAM,OAAO,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC,CAAC;AAAA,IACzD;AACA,QAAI,OAAO,IAAI,KAAK,MAAM;AACxB,YAAM,OAAO,mCAAmC;AAClD,UAAM,cAAc,IAAI,KAAK;AAC7B,UAAM,OAAO,MAAM,YAAY,IAAI;AACnC,WAAO,OAAO,SAAS,WAAW,OAAO;AAAA,EAC3C;AACA,SAAO,IAAI,IAAI;AACjB;AAEA,KAAK,EACF,KAAK,CAAC,SAAS;AACd,UAAQ,WAAW;AACrB,CAAC,EACA,MAAM,CAAC,MAAe;AACrB,UAAQ,WAAW,YAAY,CAAC;AAClC,CAAC;","names":[]}