@rness/cli 0.12.0 → 0.14.0

package/README.md

@@ -60,11 +60,15 @@ when dropped, red `?` when missing.
   screen back. Read-only.
 - Off a terminal — a pipe, CI, an agent's tool — Markdown: a table per tab.
 - From Claude Code, `/rness:status [tab]` shows those tables (see "Agent
-  targets"). For the view itself: `Ctrl+Z` suspends Claude Code, run
-  `npx @rness/cli status` (or `rness status` with a global install), `q`,
-  then `fg` resumes it — the skill ends with that line. Nothing started from inside
-  Claude Code gets the terminal, so the view cannot open from there
-  (verified with Claude Code 2.1.284 on 2026-09-29).
+  targets"). Nothing started from inside Claude Code gets the terminal, so
+  the view cannot open from there (verified with Claude Code 2.1.284 on
+  2026-09-29). Two ways to reach it, and the skill ends with both: in the
+  same terminal, `Ctrl+Z` suspends Claude Code, run `npx @rness/cli status`
+  (or `rness status` with a global install), `q`, then `fg` resumes it
+  (Unix only); or in another terminal, from the workspace's `.rness/`, with
+  the manager it installs with — `pnpm rness status`, `npx rness status`,
+  `yarn rness status` or `bunx rness status` — which runs the pinned copy
+  without the network (verified with each manager on 2026-09-30).
 
 ### Agent targets
 
@@ -91,11 +95,30 @@ the files a given agent needs, for the agents the team declares in
   which registers the MCP server; see "MCP server". The same settings file
   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
-  files whole — an edit by hand is reported by `sync --check` and written
-  back by `sync` — and nothing in them depends on the version. Claude Code
-  loads the plugin once the folder is trusted, in a session started there.
+  get a Claude Code plugin, `.claude/skills/rness/`, with five commands:
+  `/rness:status [tab]`, the tables of `rness status`, and the lifecycle
+  skills below. rness owns those files whole — an edit by hand is reported
+  by `sync --check` and written back by `sync`. Nothing in them depends on
+  the version; the last line of the status skill names the workspace's
+  package manager, so changing `packageManager` in `.rness/package.json`
+  leaves it stale until the next `sync`. Claude Code loads the plugin once
+  the folder is trusted, in a session started there.
+- **The lifecycle skills**: `/rness:adr [subject | NNNN]` records a decision
+  as an ADR, `/rness:spec [subject | NNNN]` writes a specification,
+  `/rness:plan <spec>` turns an approved specification into a plan, and
+  `/rness:done [plan]` closes a piece of work — each task checked on
+  evidence, then the plan `Completed`, its specification `Implemented`, and
+  the documents the work made inaccurate corrected. Each is a procedure
+  loaded into the conversation, not a file generator: after a decision has
+  been discussed, `/rness:adr` writes it from the conversation; otherwise
+  it asks, one question at a time. The skill stays in the conversation for
+  the next turns, and the file carries the work to the next session
+  (`/rness:adr 0010` reopens it). The agent may start one itself — an ADR
+  when a choice is expensive to reverse — but writes nothing without a yes.
+  The rules stay in `.rness/CONVENTIONS.md`; the skills only add the steps.
+  A new document takes the collection's first status (`Proposed` for an
+  ADR, `Draft` otherwise) and the next number of the local checkout; two
+  branches can pick the same one. No skill commits.
 - rness owns values, not files: what is missing is added, nothing else is
   touched, and a file it cannot parse is reported, never rewritten.
   `sync --check` and `validate` report a missing value. Removing an agent
@@ -148,12 +171,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 +237,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 +264,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 +301,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 +336,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.14.0 (supported:
 github)`. `add`, `sync` and the local commands never refuse. `null` is not a
   value: an absent key means none.
 
@@ -419,6 +513,69 @@ 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.14.0 — the lifecycle skills; `/rness:status` names a second terminal
+
+- The `rness` plugin of Claude Code gains `/rness:adr`, `/rness:spec`,
+  `/rness:plan` and `/rness:done`: the workspace's lifecycle as procedures
+  the developer or the agent starts, which write nothing without a yes. See
+  "Agent targets".
+- `/rness:status` ends with two ways to the full-screen view: `Ctrl+Z` in
+  the same terminal, or another terminal from `.rness/` —
+  `pnpm rness status`, or the command of the workspace's package manager.
+  See "Status".
+- `rness upgrade` syncs, so it writes the four skills and rewrites
+  `plugin.json` and the status skill; then commit `.claude/skills/rness/` in
+  each repository, as its next steps list. Until then `sync --check` and
+  `validate` report them.
+- Blocks are unchanged.
+
+## 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-AXTFDXN2.js";
 
 // src/bin/rness.ts
 import { pathToFileURL } from "url";