@rness/cli 0.18.0 → 0.19.0

package/README.md

@@ -28,7 +28,7 @@ Inside a workspace, every `rness` delegates to the copy pinned in
     rness login [--setup-git|--no-setup-git]
     rness logout
     rness context [--scope <name>] [--json]
-    rness status [<tab>]
+    rness status [<tab>] [--json]
     rness pulse create [<collection>] [-y]
     rness pulse sync
     rness validate
@@ -48,6 +48,7 @@ writes nothing and exits 1 when a block is out of date — use it in CI.
 
     rness status            # every decision, specification and plan, a tab per directory
     rness status specs      # open on one tab (off a terminal: print only that one)
+    rness status --json     # one JSON object: what the Claude Code plugin draws
 
 A tab for `ADR`, `Specs` and `Plans`, always, then one for each other
 directory of `.rness/` whose Markdown files carry a `status` in their front
@@ -59,8 +60,15 @@ when dropped, red `?` when missing.
   `PgUp`/`PgDn`, `Home`/`End` scroll, `q` or `Esc` closes and gives the
   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"). Nothing started from inside Claude Code gets the terminal, so
+- `--json`, terminal or not: the tabs and their rows, with what a Claude
+  Code session shows of the workspace, worded by the CLI — the session-start
+  banner, the status line entry, the scope's plans `In progress` and the
+  notes of the safety net (see "Hooks"). The plugin's mod reads it (see
+  "The mod").
+- From Claude Code, `/rness:status [tab]` opens a pane beside the
+  conversation when the plugin's mod is loaded (see "The mod"), and shows
+  those tables otherwise (see "Agent 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`
@@ -93,11 +101,12 @@ 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 three hooks, and so does `.claude/settings.json` at the workspace
+  carries four 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 five commands:
+  get a Claude Code plugin, `.claude/skills/rness/`, with four 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
+  skills below; and a mod, its hooks module (see "The mod"). rness owns
+  those files whole — an edit by hand is reported
   by `sync --check` and written back by `sync`. The plugin's manifest,
   `.claude-plugin/plugin.json`, also carries the agent-plugins.org
   `$schema`, the author, homepage, repository, licence and keywords, so a
@@ -133,7 +142,8 @@ the files a given agent needs, for the agents the team declares in
   by `rness doc new <collection>` — the second pre-approved line of each
   skill, so that every runtime and a bare terminal get the same number;
   `rness validate` refuses two documents with one number, the case a merge
-  of two branches can still produce. Each skill records its session: it adds
+  of two branches can still produce, and a document named without one
+  (`NNNN-<slug>.md`, never a date). Each skill records its session: it adds
   `{ id: <session id>, agent: <model> }` to `sessions:` in the front matter
   of what it writes or closes. The agent is the model it runs as, as Claude
   Code names it (`Claude Opus 5.5`): no variable gives it to a skill. An
@@ -151,10 +161,60 @@ the files a given agent needs, for the agents the team declares in
 - Other agents (Codex, Cursor, GitHub Copilot) read the `AGENTS.md` block;
   `sync` refuses an agent it has no target for.
 
+### The mod
+
+Since 0.19.0 the plugin carries a hooks module — what Claude Code calls a
+mod — in `hooks/hooks.json`, `hooks/register.tsx` and `types/index.d.ts`.
+It draws the workspace in the session, from `rness status --json` run by
+the pinned copy, and computes nothing itself:
+
+- **A band above the prompt**, whenever a note needs action (a pin the
+  installed copy does not match, problems `validate` would report): those
+  notes. The banner is not repeated there; the session-start line says it
+  once, in the transcript.
+- **The status line**: `<scope> · <n> in progress`, with `⚠ <n>` when
+  there are notes. Claude Code draws it after the plugin's name:
+  `⚠ rness: web · 1 in progress` (2.1.289).
+- **`/rness:status [tab]` as a pane** beside the conversation, a tab per
+  collection, a row per document; no model turn. The pane takes the
+  keyboard as it opens: a tab's digit (written before its name), or Tab
+  then Enter, shows that tab; ↑/↓, `PgUp`/`PgDn`, `Home`/`End` scroll, as
+  in the full-screen `rness status`; Esc and `q` close it, and so does Esc
+  at an empty prompt once the prompt has the keys back. A pane has no
+  ←/→ in Claude Code 2.1.289. In `claude -p`, or where no pane can be
+  placed, the skill's tables answer instead.
+
+It reads the snapshot again at session start, after an `Edit` or `Write`
+of a file under `.rness/`, and at the end of each turn, off the turn's
+path. The module runs the pinned copy at the one path `sync` writes into it
+for its place (`.rness` at the root, `../../.rness` in a clone), as the
+settings hooks do: never a copy a clone's own tree could hold. It loads
+where the plugin loads — a trusted folder, `claude -p` included — on a
+Claude Code that has mods: run by 2.1.280 and later, ignored without an
+error by 2.1.240 and 2.1.199, where the skills work as before (verified on
+2026-10-04). An older Claude Code is told so once per version and machine,
+in the session-start line: `rness: Claude Code 2.1.240 shows no rness band,
+status line or pane; 2.1.280 or later does — claude update`. The version
+comes from `AI_AGENT`, which Claude Code sets (2.1.240 does); one that does
+not set it, or not in that form, is told nothing. The versions told are kept
+in `claude-code.json` beside the login (`~/.config/rness/` by default). Not in
+`claude -p` or another SDK session, where nobody would read it; not after a
+compaction. Versions between 2.1.240 and 2.1.280 were not tried: one of
+them that loads mods is told to update for nothing. Mods are early access
+in Claude Code: a release that changes their API may stop the band or the
+pane until the next rness release; the skills and the settings hooks do not
+depend on it.
+
+To work on it, from `org/rness`: `pnpm check:mod` runs
+`claude plugin validate` and `claude plugin test` on `packages/cli/mod`
+(Claude Code needed, so not in CI); `tsc -p packages/cli/mod` type-checks it
+once a `claude --plugin-dir packages/cli/mod` session has laid Claude
+Code's types there.
+
 ### Hooks
 
 With `claude` in `agents`, each clone's `.claude/settings.json` and the
-workspace root's carry three Claude Code hooks, all run by the pinned copy:
+workspace root's carry four 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`
@@ -162,7 +222,18 @@ workspace root's carry three Claude Code hooks, all run by the pinned copy:
   them. When the context may be wrong, both say why: no `.rness` next to the
   repository or nothing installed there, a `rness.json` rness refuses, a pin
   the installed copy does not match, the problems `rness validate` reports.
-  After a compaction, the context only.
+  A Claude Code too old for the plugin's mod gets one more line, once (see
+  "The mod"). 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
+  standard that line comes from, to edit instead), or a file of
+  `.claude/skills/rness/` — or add a problem to a document of `.rness/` or
+  to `rness.json`. Only the problems the edit adds: a document already
+  broken stays editable. The `old_string` is found as Claude Code's `Edit`
+  finds it, straight quotes matching curly ones. Writes through Bash are
+  not seen: the guard is best effort. About 0.07 s per edit, 0.11 s for a
+  document of `.rness/` (measured 2026-10-04).
 - **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
@@ -180,7 +251,7 @@ 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 three read `.rness/`, write
+developer, including in `claude -p`. These four 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
@@ -603,6 +674,45 @@ 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.19.0 — the plugin's mod; edits of generated files refused before they land
+
+- The Claude Code plugin gains a mod (see "The mod"): the notes to act on
+  above the prompt, a status line entry, and `/rness:status` as a pane
+  beside the conversation, with no model turn, driven by the keyboard. `sync` writes three more files into `.claude/skills/rness/`,
+  at the root and in each clone; an upgrade lists the clone's for commit.
+  Claude Code without mods ignores them; older than 2.1.280, it is told once
+  per version, in the session-start line, to run `claude update` (when it
+  sets `AI_AGENT`, as 2.1.240 does).
+- A fourth hook, `PreToolUse` on `Edit|Write`: an edit of the block of an
+  `AGENTS.md` or `CLAUDE.md`, or of the plugin's files, is refused before
+  it is written, naming the file to edit instead; so is an edit that would
+  add a problem to a document of `.rness/` or to `rness.json`. Until the
+  upgrade has run on a machine, a session there runs the old pinned copy,
+  which says `unknown hook event "pre-tool-use"` and lets the edit through.
+- `rness status --json` prints the tabs and what the mod draws.
+
+## 0.18.1 — a document without a number is caught; small fixes
+
+- `rness validate` and the edit hook name a document of `adr/`, `specs/` or
+  `plans/` whose file name has no number, with the next one:
+  `plans/2026-10-02-x.md: not numbered; name it 0002-<slug>.md, the next
+number of plans`. A plan another agent's skill wrote with a dated name
+  is the usual case; rename it, or let the agent do it when the hook
+  tells it. A workspace with such a file fails `validate` (and its CI)
+  after the upgrade until it is renamed. The scaffold's `CONVENTIONS.md`
+  states the rule, and `upgrade` merges it in.
+- A dated file name is no longer read as a number: `rness doc new` after
+  `2026-10-02-x.md` gave `2027`, and two dated plans of one year were
+  reported as one number twice.
+- `rness doc new` racing another one at the same number says `<file>
+exists; nothing written` (exit 1) instead of a raw `EEXIST`.
+- `1 repository`, not `1 repositories`, in `create` and `sync`.
+- When the SSH test passes only by asking for the key's passphrase,
+  `create`, `add` and `sync` say once how to load it into an agent
+  (`ssh-add`), since every clone would ask again.
+- Ctrl+C while `create` waits for an organization's approval is a cancel
+  in the plain look too: `cancelled`, nothing written, exit 0 (it was 130).
+
 ## 0.18.0 — the wizard asks where first and waits for the approval; the skills on one grammar; Node 22.17
 
 - The published CLI runs on **Node 22.17 or later** (ADR 0010); the guard

package/dist/bin/rness.js

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