@rness/cli 0.20.1 → 0.21.0

package/README.md

@@ -31,6 +31,7 @@ Inside a workspace, every `rness` delegates to the copy pinned in
     rness status [<tab>] [--json]
     rness pulse create [<collection>] [-y]
     rness pulse sync
+    rness pulse note [--plan <path>] [--kind approach|deviation|blocker|done] [<text>]
     rness validate
     rness mcp
 
@@ -244,7 +245,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
+  "Pulse"). 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 +261,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 "Pulse".
+- **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 "Pulse". 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,7 +279,8 @@ 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 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
@@ -288,10 +295,70 @@ status, it received the problem. The `sh` line is not verified on Windows.
     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.
+A projection of rness's state on the organization's GitHub Projects,
+each declared in `rness.json`: first **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 boards; if it is not in rness, it does not belong
+there.
+
+- **Boards declared in `rness.json`** (0.21.0): `projects` 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/`). 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 (`"projects.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.** `pulse create` 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 projects.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, `pulse sync` skips a board whose README still declares.
 
 - **Items**: one per document of `rness status`, an issue of
   `<org>/.rness` added to the project. GitHub shows it only to people who
@@ -381,8 +448,9 @@ Session → Working session`). A board per directory, named as
   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`,
+  refused) and no pulse yet. It creates the project and at once writes the
+  board whole, from the preset `agent-pulse`, into `projects.pulse` (and
+  the `provider`) in `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
@@ -413,13 +481,17 @@ 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
+  `rness status` — a project of its own, named after it, written whole
+  from the preset `collection` into `projects.<collection>` (0.21.0;
+  before, `"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
+  - `<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 +510,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 `pulse sync` makes of the documents. For each event,
+  one detached `rness pulse run <event>` does every board's actions, in
+  the order of `projects`; a failure is recorded naming the board and the
+  action (`mark on Marketing failed: …`). `rness pulse mark`, which 0.20's
+  hooks started, stays, hidden, through 0.21.x. 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;
@@ -457,6 +545,40 @@ added to project`) may change a field of rness's items; the next sync
   `the pulse needs the project scope: run rness login` or
   `cannot reach GitHub: …`. Two sessions marking one plan both write; the
   last wins.
+- **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 pulse 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, `pulse sync` 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
@@ -500,7 +622,9 @@ repository, the board).
   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.
+  `"projects": { "pulse": <number> }`; both at once are refused. Since
+  0.21.0 a board in `projects` is written whole, on several lines; 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`:
   `provider "gitlab" is not supported by @rness/cli 0.17.1 (supported:
@@ -511,22 +635,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 pulse note` posts it; the issue it went to (see "Pulse")                                  |
 
 - 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
@@ -695,6 +823,44 @@ 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.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 from 0.20.1 still prints it, since the copy that runs it is the
+  old one; `pnpm dlx @rness/cli upgrade` runs the new one.
+
 ## 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-T5PINUCP.js";
+import {
+  VERSION,
+  reportError
+} from "../chunk-D3D2WCGW.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":[]}

package/dist/chunk-4BM4FUWO.js

@@ -0,0 +1,263 @@
+import {
+  JournalRefused,
+  blobUrl,
+  branchOf,
+  cloneHolding,
+  context,
+  declaredBoards,
+  fromGithub,
+  headOf,
+  issueUrl,
+  notePosted,
+  notesPosted,
+  parseFrontMatter,
+  plansInProgress,
+  recordNotice,
+  resolveScope,
+  statusTabs
+} from "./chunk-D3D2WCGW.js";
+
+// src/pulse/note.ts
+import { relative, resolve, sep } from "path";
+var KINDS = ["approach", "deviation", "blocker", "done"];
+var TITLE = {
+  approach: "Approach",
+  deviation: "Deviation",
+  blocker: "Blocker",
+  done: "Done"
+};
+var MAX = 4e3;
+var SECRETS = [
+  /ghp_/,
+  /gho_/,
+  /github_pat_/,
+  /AKIA[0-9A-Z]{16}/,
+  /-----BEGIN [A-Z ]*PRIVATE KEY/,
+  /xox[abpr]-/,
+  /sk-[A-Za-z0-9]{20,}/
+];
+var NoteRefused = class extends Error {
+};
+function sessionFrom(given, env) {
+  const raw = given ?? env["CLAUDE_CODE_SESSION_ID"] ?? "";
+  if (raw.trim() === "") return null;
+  return raw.includes(" \xB7 ") ? raw : `claude \xB7 ${raw.slice(0, 8)}`;
+}
+function checked(input) {
+  const length = input.text.trim().length;
+  if (length < 1 || length > MAX)
+    throw new NoteRefused(
+      `a note holds 1 to ${MAX.toLocaleString("en")} characters (this one ${length})`
+    );
+  if (SECRETS.some((s) => s.test(input.text)))
+    throw new NoteRefused("the note looks like it holds a credential");
+  const kind = KINDS.find((k) => k === (input.kind ?? "approach"));
+  if (kind === void 0)
+    throw new NoteRefused(
+      `--kind is one of ${KINDS.slice(0, -1).join(", ")} or ${KINDS.at(-1)}`
+    );
+  const session = sessionFrom(input.session, input.env ?? process.env);
+  if (session === null)
+    throw new NoteRefused(
+      "no session: write it from a Claude Code session, or pass --session"
+    );
+  return { kind, session };
+}
+function journalOf(declared) {
+  for (const d of declared)
+    for (const a of d.declaration.hooks["session-start"] ?? [])
+      if (a.action === "journal") return { board: d, journal: a };
+  return null;
+}
+function githubRepo(url) {
+  const m = /^(?:git@github\.com:|ssh:\/\/git@github\.com\/|https:\/\/github\.com\/)([^/]+)\/(.+?)(?:\.git)?\/?$/.exec(
+    url.trim()
+  );
+  return m === null || m[1] === void 0 || m[2] === void 0 ? null : { owner: m[1], name: m[2] };
+}
+async function planOf(c, cwd, given) {
+  const tabs = await statusTabs(c.rnessDir);
+  const plans = tabs.find((t) => t.name === "plans")?.rows ?? [];
+  if (given !== void 0) {
+    const path = given.replace(/^\.rness\//, "");
+    if (!plans.some((r) => r.path === path))
+      throw new NoteRefused(`${given} is no plan of .rness`);
+    return path;
+  }
+  const scope = resolveScope(
+    c.manifest,
+    relative(c.root, resolve(cwd)).split(sep).join("/")
+  );
+  const candidates = await plansInProgress(
+    { root: c.root, rnessDir: c.rnessDir },
+    c.manifest,
+    scope
+  );
+  if (candidates.length === 0)
+    throw new NoteRefused(
+      `no plan in progress in scope ${scope ?? "global"}: set one In progress first`
+    );
+  if (candidates.length > 1)
+    throw new NoteRefused(
+      `several plans in progress: pass --plan, one of ${candidates.join(", ")}`
+    );
+  return candidates[0] ?? "";
+}
+async function planIssue(c, board, plan) {
+  const items = await fromGithub(
+    c.provider.items(board.board, { bodies: false })
+  );
+  const number = items.find((i) => i.path === plan)?.issue?.number;
+  const found = number === void 0 ? null : await fromGithub(c.provider.issueOf(c.org, ".rness", number));
+  if (found === null)
+    throw new NoteRefused(`${plan} has no issue yet: rness pulse sync`);
+  return {
+    id: found.id,
+    number: found.number,
+    repository: `${c.org}/.rness`
+  };
+}
+var refusedWrite = (e) => e instanceof Error && /not accessible|forbidden|permission|must have push access/i.test(e.message);
+async function implementationBody(c, plan, planNumber) {
+  const lines = [
+    `Plan [\`${plan}\`](${blobUrl(c.org, plan)}) \xB7 [plan issue](${issueUrl(c.org, planNumber)})`
+  ];
+  try {
+    const { readFile } = await import("fs/promises");
+    const front = parseFrontMatter(
+      await readFile(resolve(c.rnessDir, ...plan.split("/")), "utf8")
+    ) ?? {};
+    const spec = /\(\.\.\/(specs\/[^)\s]+\.md)\)/.exec(
+      String(front["spec"] ?? "")
+    );
+    if (spec?.[1] !== void 0)
+      lines.push(`Specification [\`${spec[1]}\`](${blobUrl(c.org, spec[1])})`);
+  } catch {
+  }
+  return `${lines.join("\n")}
+
+The agent's notes on this implementation follow as comments. The pull request that completes it carries \`Closes\` with this issue's reference.`;
+}
+async function postNote(input) {
+  const { kind, session } = checked(input);
+  const c = await context({
+    cwd: input.cwd,
+    ...input.githubApi === void 0 ? {} : { githubApi: input.githubApi }
+  });
+  const declared = await declaredBoards(c);
+  const kept = journalOf(declared);
+  if (kept === null)
+    throw new NoteRefused(
+      'no board keeps a journal: add { "action": "journal", "to": "plan" } to its session-start hooks'
+    );
+  const plan = await planOf(c, input.cwd, input.plan);
+  if (await notesPosted(c.rnessDir, session, plan) >= kept.journal.limit)
+    throw new NoteRefused(
+      "journal full for this session: put the rest in the pull request"
+    );
+  const parent = await planIssue(c, kept.board, plan);
+  const clone = cloneHolding(c.root, c.manifest.repos, input.cwd);
+  let target = parent;
+  let why = null;
+  if (kept.journal.to === "repo" && clone !== null) {
+    const repo = githubRepo(clone.url);
+    if (repo === null || repo.owner.toLowerCase() !== c.org.toLowerCase())
+      why = `${clone.name} is not on the workspace's provider`;
+    else
+      try {
+        const there = await fromGithub(
+          c.provider.journalIssue(repo.owner, repo.name, plan)
+        );
+        if (there !== null) target = there;
+        else {
+          const row = (await statusTabs(c.rnessDir)).find((t) => t.name === "plans")?.rows.find((r) => r.path === plan);
+          target = await fromGithub(
+            c.provider.createJournalIssue(repo.owner, repo.name, plan, {
+              title: `Implement ${row === void 0 ? plan : `${row.id} \u2014 ${row.title}`}`,
+              body: await implementationBody(c, plan, parent.number)
+            })
+          );
+          try {
+            await fromGithub(c.provider.addSubIssue(parent.id, target.id));
+          } catch {
+            await fromGithub(
+              c.provider.comment(
+                parent.id,
+                `Implementation: ${target.repository}#${target.number}`
+              )
+            );
+          }
+        }
+      } catch (e) {
+        if (e instanceof JournalRefused)
+          why = e.why === "issues" ? `${repo.owner}/${repo.name} takes no issues` : `${repo.owner}/${repo.name} is not on GitHub, or this login cannot see it`;
+        else if (refusedWrite(e))
+          why = `${repo.owner}/${repo.name} refuses this login's write`;
+        else throw e;
+      }
+  }
+  if (why !== null)
+    await recordNotice(`journal \u2014 ${why}, notes go to the plan's issue`);
+  const where = clone?.dir ?? input.cwd;
+  const [branch, head] = await Promise.all([branchOf(where), headOf(where)]);
+  const id = session.split(" \xB7 ").pop() ?? session;
+  const header = [
+    `**${TITLE[kind]}**`,
+    session,
+    ...branch === null || head === null ? [] : [`\`${branch}\` @ \`${head.slice(0, 7)}\``]
+  ].join(" \xB7 ");
+  const body = [
+    ...why === null ? [] : [`_${why}: this note goes to the plan's issue._`, ""],
+    header,
+    "",
+    input.text.trim(),
+    "",
+    `<!-- rness note ${id} -->`
+  ].join("\n");
+  await fromGithub(c.provider.comment(target.id, body));
+  const reference = `${target.repository}#${target.number}`;
+  await notePosted(c.rnessDir, session, plan, { id: target.id, reference });
+  return {
+    reference,
+    to: target === parent ? "plan" : "repo"
+  };
+}
+async function pulseNoteCommand(opts) {
+  try {
+    const text = opts.text === void 0 || opts.text === "-" ? await (opts.stdin ?? readStdin)() : opts.text;
+    const posted = await postNote({
+      cwd: opts.cwd ?? process.cwd(),
+      text,
+      ...opts.kind === void 0 ? {} : { kind: opts.kind },
+      ...opts.plan === void 0 ? {} : { plan: opts.plan },
+      ...opts.session === void 0 ? {} : { session: opts.session },
+      ...opts.githubApi === void 0 ? {} : { githubApi: opts.githubApi }
+    });
+    process.stdout.write(`${posted.reference}
+`);
+    return 0;
+  } catch (e) {
+    process.stderr.write(
+      `rness: ${e instanceof Error ? e.message : String(e)}
+`
+    );
+    return 1;
+  }
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+export {
+  KINDS,
+  NoteRefused,
+  sessionFrom,
+  journalOf,
+  githubRepo,
+  planIssue,
+  postNote,
+  pulseNoteCommand
+};
+//# sourceMappingURL=chunk-4BM4FUWO.js.map