@rness/cli 0.12.0 → 0.13.0

package/README.md

@@ -148,12 +148,63 @@ status, it received the problem. The `sh` line is not verified on Windows.
     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 every document of
-`.rness/` and when an agent is at work on one. rness writes the board and
-never reads it back; if it is not in rness, it does not belong there.
-
-- **Layout**: one item per document (a draft issue: its title, its path and a
-  link to it in `<org>/.rness`), and the fields `Status` (the union of the
+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
@@ -163,7 +214,7 @@ never reads it back; if it is not in rness, it does not belong there.
   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, green done, gray dropped; collections and `working` too); a sync recolours rness's options and leaves other options' colours alone. rness does
+  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.
@@ -190,17 +241,32 @@ never reads it back; if it is not in rness, it does not belong there.
   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`**: creates the items that are missing, updates those whose
-  title, status or collection changed, archives those whose document is
-  gone, and adds the option or the board a new status or directory needs. It
-  says `synced 49 items: 2 updated, 47 unchanged`. An item converted to an
-  issue by hand is the team's: left alone, and its document gets a new
-  draft.
-- **One way**: the board is only read to find rness's items. What someone
-  changes there by hand is overwritten at the next sync.
+- **`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; session end clears
+  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.
@@ -212,11 +278,16 @@ never reads it back; if it is not in rness, it does not belong there.
   `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 its requests one after another, without pausing. A
-  first sync makes a draft and sets up to three fields per document — about
-  200 requests for fifty documents; whether that stays under GitHub's
-  limits for creating content is to be confirmed on GitHub. Later syncs
-  touch only what changed.
+- **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
@@ -242,7 +313,7 @@ repository, the board).
   `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.12.0 (supported:
+  `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.
 
@@ -419,6 +490,53 @@ 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

package/dist/bin/rness.js

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