@rness/cli 0.11.0 → 0.13.0

package/README.md

@@ -20,7 +20,7 @@ Inside a workspace, every `rness` delegates to the copy pinned in
 
 ## Commands
 
-    rness create [<org>] [--repos a,b] [--agent claude] [--pm npm|pnpm|yarn|bun] [--ssh|--https] [--skip-install] -y
+    rness create [<org>] [--provider github] [--repos a,b] [--agent claude] [--pm npm|pnpm|yarn|bun] [--ssh|--https] [--skip-install] -y
     rness create <name> --blank [--agent claude] [--pm npm|pnpm|yarn|bun] [--skip-install] -y
     rness add <repo> [--scopes apps/web,packages/ui] [--ssh|--https] -y
     rness sync [--all] [--scope <name>] [--check] [--pull] [--agent <name>] -y
@@ -29,6 +29,8 @@ Inside a workspace, every `rness` delegates to the copy pinned in
     rness logout
     rness context [--scope <name>] [--json]
     rness status [<tab>]
+    rness pulse create [-y]
+    rness pulse sync
     rness validate
     rness mcp
 
@@ -87,7 +89,7 @@ the files a given agent needs, for the agents the team declares in
   applies it once the repository has been trusted interactively. Verified
   with Claude Code 2.1.284 on 2026-09-29. Each clone also gets `.mcp.json`,
   which registers the MCP server; see "MCP server". The same settings file
-  carries two hooks, and so does `.claude/settings.json` at the workspace
+  carries three hooks, and so does `.claude/settings.json` at the workspace
   root, which `sync` writes on every machine; see "Hooks". Both places also
   get a Claude Code plugin, `.claude/skills/rness/`, with one command:
   `/rness:status [tab]`, the tables of `rness status`. rness owns those
@@ -104,7 +106,7 @@ the files a given agent needs, for the agents the team declares in
 ### Hooks
 
 With `claude` in `agents`, each clone's `.claude/settings.json` and the
-workspace root's carry two Claude Code hooks, both run by the pinned copy:
+workspace root's carry three Claude Code hooks, all run by the pinned copy:
 
 - **At session start** (`SessionStart`, every source): a line for the
   developer — `rness 0.10.0 · acme · scope web — 3 standards, 2 decisions`
@@ -116,7 +118,10 @@ workspace root's carry two Claude Code hooks, both 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`.
+  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.
 
 Each hook is one fixed `sh` line: it runs
 `<.rness>/node_modules/@rness/cli/dist/bin/rness.js hook <event>` when that
@@ -127,12 +132,190 @@ hand counts as missing, and the next `sync` adds a second one. The team's
 own hooks stay where they are.
 
 Claude Code runs hooks from a committed settings file without asking each
-developer, including in `claude -p`. These two read `.rness/` and nothing
-else: they write no file, run no install and reach no network. 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.
+developer, including in `claude -p`. These three read `.rness/`, write
+nothing in the workspace and run no install. Only with a pulse declared 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
+configuration directory (`~/.config/rness/` by default), which the next
+session start reads, says once and deletes. See "Pulse". 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 sync        # 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.
+
+- **Items**: one per document of `rness status`, an issue of
+  `<org>/.rness` added to the project. GitHub shows it only to people who
+  can read `.rness`. Its title is the document's (`0016 — CLI: rness
+status, …`) and its body the document (see **Body**). It carries the
+  label `rness`, made if missing; `-label:rness` leaves these issues out of
+  `.rness`'s Issues tab. An issue is open while its document exists. When
+  the document is gone, the issue is closed as not planned and its item
+  archived. Gone means gone for this clone's git: the path is in its
+  history and no longer in its working tree. A path it has never seen is
+  judged only on an issue this clone's sync opened — a document its agent
+  wrote, then renamed or deleted before any commit. The clone records the
+  issues it opens in its own git directory (`rness/opened`, per worktree,
+  never pushed), and forgets one as soon as its git has seen the path. Any
+  other — a teammate's new document, or yours from another clone, not
+  pulled yet — is left alone. An issue closed while its document exists —
+  by hand, or by a `fixes #12` in a `.rness` commit — is reopened at the
+  next sync. The document's status is its field, not the issue's state.
+  rness's items are those with a `Path`
+  whose content is an issue of `.rness`. A draft with a `Path` is rness's
+  from 0.12.0, and is converted into an issue of `.rness`. An issue of
+  `.rness` on the board, labelled `rness`, without `Path`, whose body's
+  first line is a document's first line, is one a stopped sync left: it
+  gets its `Path` and is brought up to date, and no second issue is made.
+  Anything else — an item without `Path`, an issue of another repository,
+  any other issue of `.rness` without `Path` — is the team's: never
+  edited, closed or archived. Two known limits. A clone behind the others
+  writes what its working tree holds — an older title, status or body —
+  until it pulls; the next up-to-date sync writes them back. A document
+  that lives only on a branch of `.rness` has its issue closed by a sync
+  from a branch without it, if git has seen the path or this clone opened
+  the issue; back on its branch, it gets a new issue (`.rness` is worked
+  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`.
+- **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
+  without its first heading (the title). Links outside code are rewritten.
+  A link to another document becomes the URL of its issue, which opens in
+  the board's side panel. A link to any other file of `.rness` points to
+  it on GitHub at `main` (an image, raw). An absolute link, a link out of
+  `.rness`, or a link to no file stays as written. Outside code spans and
+  fenced blocks, `@name` is written `\@name`, and a bare `#12` gets a
+  zero-width space after `#`: a body notifies no one and points at no
+  wrong issue. A body holds at most 65,536 characters. A longer document
+  is cut at the last blank line that fits and ends with
+  `The rest: <link>`. A last line, invisible on GitHub,
+  `<!-- rness <digest> -->`, is how sync tells a body that changed.
+- **Layout**: the fields `Status` (the union of the
+  collection fields' options: every contract status plus the ones found in
+  `.rness/`, in lifecycle order, at most 50), `Collection` (one option per tab of
+  `rness status`; not `Type`, which is GitHub's own issue-type field and
+  filter), `Agent` (`working`), `Session` (`claude · 1a2b3c4d`, plus the
+  agent type for a subagent) and `Path`. 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`
+  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 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
+  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
+  `"pulse": { "project": <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
+  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
+  also adds the option or the board that a new status or directory needs.
+  It says what it did to the issues, then to the items: `created 1 issue`,
+  `reopened 1 issue`, `synced 52 items: 1 created, 2 updated, 49
+unchanged`.
+- **One way**: rness reads the board and the issues only to find its items
+  and to tell a changed body. Anything changed by hand — a card moved, a
+  field, a title, a body, an issue closed — is written back at the next
+  sync, and never reaches `.rness/`. The board is not made read-only:
+  whoever runs an agent writes it with their own login, so they need Write
+  on the project. Read-only access for anyone else is set by hand, in the
+  project's "Manage access". The project's workflows are left alone.
+  GitHub turns on "Auto-add sub-issues to project" for a new project, so a
+  sub-issue added under a document's issue joins the board without `Path`,
+  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.
+- **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
+  through a sync, and an edit of any other file of `.rness/` costs no sync;
+  the hooks' syncs run one at a time, an edit's skipped while another runs,
+  the session end's waiting its turn; session end clears
+  the marks of that session (its subagents' included) and syncs. Each one
+  starts a detached `rness` process and answers at once, so a slow network
+  never holds Claude Code; the session-end sync outlives Claude Code's exit.
+  Verified with Claude Code 2.1.284 on 2026-09-29: the detached process wrote
+  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
+  `cannot reach GitHub: …`. Two sessions marking one plan both write; the
+  last wins.
+- **Rate**: rness sends one request at a time. A new document costs an
+  issue, its addition to the board, up to four fields, then its body. An
+  unchanged document costs nothing but its share of the listing, which
+  reads every item's body. On one of GitHub's rate limits rness waits as
+  long as GitHub says (`waiting  60 s — GitHub's rate limit`), 10 minutes
+  at most in all. Past that it stops, saying how many changes it did not
+  make, and the next sync makes them. Measured on `rness-dev` (54
+  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.
+
+### Provider
+
+`rness.json` records where the organization lives:
+`"provider": "github"`, between `contract` and `org`. Every command talks to
+it through one adapter; `git` still does what git does (clone, pull, push,
+credentials), and the provider's API the rest (organizations, creating a
+repository, the board).
+
+- `rness create` asks `Where does your organization live?`: GitHub, and
+  GitLab and Atlassian (Bitbucket + Jira) shown disabled, coming later.
+  `--provider github` answers it off a terminal. A blank workspace asks
+  nothing. Joining an organization asks first as well, then takes the
+  provider its `rness.json` 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`, `pulse`, `repos`, `scopes`.
+- A provider _written_ in `rness.json` that this version cannot talk to
+  (`gitlab`) is refused by `validate`, `create`, `login` and `pulse`:
+  `provider "gitlab" is not supported by @rness/cli 0.13.0 (supported:
+github)`. `add`, `sync` and the local commands never refuse. `null` is not a
+  value: an absent key means none.
 
 ### MCP server
 
@@ -184,7 +367,8 @@ anonymously.
   hours and is renewed on its own. `GITHUB_TOKEN`, then `GH_TOKEN`, win over
   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.
+  private repositories. It only lists and clones. Where the workspace
+  declares a pulse it asks for `project` too; see "Pulse".
 - 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
@@ -306,6 +490,76 @@ 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.13.0 — Agent Pulse: each document an issue of `.rness`, its content on the card
+
+- Each item of Agent Pulse is an issue of `<org>/.rness`, labelled
+  `rness`, whose body is the document. A link to another document opens
+  its issue in the board's side panel. GitHub shows the items only to
+  people who can read `.rness`. See "Pulse".
+- **Needs Issues on `.rness`**: without them `pulse create` and
+  `pulse sync` refuse, before writing anything.
+- **Upgrading**: the first `pulse sync` with 0.13.0 — run by hand, or at
+  the end of a Claude Code session — does the migration. It converts every
+  draft that carries a `Path` into an issue of `.rness`: its id and fields
+  stay, so the boards do not change. It labels each issue, writes its
+  body, and links the project to `.rness`. GitHub notifies the people who
+  watch `.rness` of each new issue, once. Nothing is asked. Until every
+  developer's `.rness` is on 0.13.0, a session that ends on 0.12.0 syncs
+  as 0.12.0 did: it sees the issues as the team's and adds a draft per
+  document. The next 0.13.0 sync archives those drafts.
+- The board is not made read-only, and its workflows are left alone. A
+  change made on the board is written back at the next sync. See "Pulse".
+- When it did, `pulse sync` says `created 1 issue`,
+  `converted 52 drafts into issues of <org>/.rness` or `reopened 1 issue`.
+  It waits on GitHub's rate limits, 10 minutes at most in all.
+- An edit of a document that has no item yet — a spec or a plan the agent
+  has just written — now gives it its issue, then marks it `working`.
+  Before, it was marked only once a sync had added it.
+- A clone that has not pulled a teammate's new document — or the same
+  developer's, from another clone — leaves its item alone. 0.12.0 archived
+  it, and the next up-to-date sync made a second one. A document renamed
+  or deleted before any commit has its issue closed by the clone that
+  opened it, which records it in its git directory (`rness/opened`).
+- The package's `Provider` interface changes:
+  - `checkIssues(org)` is new;
+  - `apply` returns the item and issue number of a create or a convert:
+    `Placed | null`;
+  - `BoardItem` gains a required `issue`: the item's issue of `.rness`
+    (number, state, label, body), or null;
+  - `Step` gains the kinds `convert`, `close` and `body`, and `update`
+    gains `reopen`;
+  - `items(board, { bodies: false })` lists the items without their
+    issues' bodies (`body: null`).
+
+  An implementation outside this package must adapt to each.
+
+- Blocks are unchanged.
+- Status colours: `Rejected` is red and `Superseded` yellow, in every
+  collection's field and in `Status`; a sync recolours them.
+
+## 0.12.0 — `rness pulse`; the provider
+
+- `rness pulse create` and `rness pulse sync`: the Agent Pulse board on the
+  organization's GitHub Projects, a projection of `.rness/`. See "Pulse".
+  `rness login` asks for the `project` scope where the workspace declares a
+  pulse.
+- `rness.json` gains two optional keys of contract 1: `provider` (`github`;
+  `gitlab` and `atlassian` are listed as not available) and
+  `pulse: { "project": <number> }`. A CLI older than 0.12.0 refuses them:
+  move the pin (`rness upgrade`) before either is written. `create` asks
+  `Where does your organization live?`, or takes `--provider github`. See
+  "Provider".
+- With `claude` in `agents`, `sync` adds a third hook, `SessionEnd`
+  (`rness hook session-end`), to each clone's `.claude/settings.json` and to
+  the workspace root's. `rness upgrade` syncs, so it adds it; then commit
+  `.claude/settings.json` in each repository, as its next steps list. Until
+  then `sync --check` and `validate` report the hook missing. The two
+  existing hook lines do not change.
+- With a pulse declared, the hooks mark and clear the plans an agent works
+  on, through a detached process. See "Hooks".
+- One status field per collection (`ADR status`, `Specs status`, `Plans status`, …); each board's columns are that collection's steps and only them. `rness pulse sync` remakes a board built by an earlier version (its URL changes once) and renames a first view named `View 1` to `All` when no `All` exists.
+- Blocks are unchanged.
+
 ## 0.11.0 — `rness status`; `/rness:status` in Claude Code
 
 - `rness status [tab]`: every decision, specification and plan — and any

package/dist/bin/rness.js

@@ -6,7 +6,7 @@ import {
   findDelegate,
   reportError,
   run
-} from "../chunk-LW4S5OLI.js";
+} from "../chunk-4VTYSPZW.js";
 
 // src/bin/rness.ts
 import { pathToFileURL } from "url";