@rness/cli 0.17.3 → 0.18.1

package/dist/{chunk-MMPMXYZU.js → chunk-JHU2G7K7.js}

@@ -508,7 +508,7 @@ function parseRepoSpec(spec, org, host) {
 }
 
 // src/version.ts
-var VERSION = "0.17.3";
+var VERSION = "0.18.1";
 
 // src/core/pm.ts
 import { execFile as execFile2 } from "child_process";
@@ -741,6 +741,25 @@ async function assembleContext({
 
 // src/core/contract.ts
 import { join as join5 } from "path";
+
+// src/core/documents.ts
+import { posix as posix2 } from "path";
+function documentDate(rel) {
+  return /^((?:19|20)\d{2}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01]))-/.exec(
+    posix2.basename(rel)
+  )?.[1] ?? null;
+}
+function documentNumber(rel) {
+  if (documentDate(rel) !== null) return null;
+  return /^(\d{4})-/.exec(posix2.basename(rel))?.[1] ?? null;
+}
+function documentTitle(heading, number) {
+  if (number === null) return heading;
+  const rest = new RegExp(`^${number}\\s*[\u2014\u2013:-]\\s*(.+)$`).exec(heading)?.[1];
+  return rest ?? heading;
+}
+
+// src/core/contract.ts
 var STATUSES = {
   adr: ["Proposed", "Accepted", "Rejected", "Superseded"],
   specs: [
@@ -760,9 +779,31 @@ async function checkContract(rnessDir) {
   for (const name of COLLECTIONS) {
     const allowed = STATUSES[name];
     const items = await collectMarkdown(join5(rnessDir, name));
+    const byNumber = /* @__PURE__ */ new Map();
     for (const item of items) {
       const where = `${name}/${item.rel}`;
       if (SKIP.has(where)) continue;
+      const number = allowed === void 0 ? null : documentNumber(item.rel);
+      if (number !== null)
+        byNumber.set(number, [...byNumber.get(number) ?? [], where]);
+    }
+    for (const [number, files] of byNumber) {
+      if (files.length < 2) continue;
+      for (const where of files)
+        problems.push(
+          `${where}: the number ${number} is also that of ${files.filter((f) => f !== where).join(", ")}`
+        );
+    }
+    const next = String(
+      Math.max(0, ...[...byNumber.keys()].map(Number)) + 1
+    ).padStart(4, "0");
+    for (const item of items) {
+      const where = `${name}/${item.rel}`;
+      if (SKIP.has(where)) continue;
+      if (allowed !== void 0 && documentNumber(item.rel) === null)
+        problems.push(
+          `${where}: not numbered; name it ${next}-<slug>.md, the next number of ${name}`
+        );
       if (item.fieldsError !== null) {
         problems.push(`${where}: invalid front matter (${item.fieldsError})`);
         continue;
@@ -808,6 +849,9 @@ var PULSE_SCOPE = "project";
 function clientId() {
   return process.env["RNESS_GITHUB_CLIENT_ID"] ?? GITHUB_CLIENT_ID;
 }
+function approvalUrl() {
+  return `https://github.com/settings/connections/applications/${clientId()}`;
+}
 function webBase() {
   return (process.env["RNESS_GITHUB_WEB"] ?? GITHUB_WEB).replace(/\/+$/, "");
 }
@@ -1063,19 +1107,6 @@ async function resolveToken(deps = {}) {
 // src/core/status.ts
 import { readdir } from "fs/promises";
 import { join as join7, posix as posix3 } from "path";
-
-// src/core/documents.ts
-import { posix as posix2 } from "path";
-function documentNumber(rel) {
-  return /^(\d{4})-/.exec(posix2.basename(rel))?.[1] ?? null;
-}
-function documentTitle(heading, number) {
-  if (number === null) return heading;
-  const rest = new RegExp(`^${number}\\s*[\u2014\u2013:-]\\s*(.+)$`).exec(heading)?.[1];
-  return rest ?? heading;
-}
-
-// src/core/status.ts
 var FIXED = [
   ["adr", "ADR"],
   ["specs", "Specs"],
@@ -1109,8 +1140,8 @@ function sessionsOf(item) {
 }
 function rowOf(dir, item) {
   const base = posix3.basename(item.rel, ".md");
-  const date = /^(\d{4}-\d{2}-\d{2})-/.exec(base)?.[1] ?? null;
-  const number = date === null ? documentNumber(item.rel) : null;
+  const date = documentDate(item.rel);
+  const number = documentNumber(item.rel);
   const sessions = sessionsOf(item);
   return {
     id: date ?? number ?? base,
@@ -2052,16 +2083,26 @@ async function getUser(options) {
     throw new Error(`GitHub API answered ${status2} for /user`);
   return { login };
 }
-async function listUserOrganizations(options) {
+async function listUserMemberships(options) {
   const { status: status2, body } = await getJson(
-    `/user/orgs?per_page=${PER_PAGE}`,
+    `/user/memberships/orgs?state=active&per_page=${PER_PAGE}`,
     options
   );
   if (status2 !== 200 || !Array.isArray(body))
-    throw new Error(`GitHub API answered ${status2} for /user/orgs`);
-  return body.map(
-    (o) => o !== null && typeof o === "object" ? o["login"] : void 0
-  ).filter((l) => typeof l === "string");
+    throw new Error(`GitHub API answered ${status2} for /user/memberships/orgs`);
+  const memberships = [];
+  for (const m of body) {
+    if (m === null || typeof m !== "object") continue;
+    const entry = m;
+    const org = entry["organization"];
+    const login = org !== null && typeof org === "object" ? org["login"] : void 0;
+    if (typeof login !== "string" || entry["state"] !== "active") continue;
+    memberships.push({
+      login,
+      role: typeof entry["role"] === "string" ? entry["role"] : ""
+    });
+  }
+  return memberships;
 }
 async function getOrgMembership(org, options) {
   const { status: status2, body } = await getJson(
@@ -3663,8 +3704,15 @@ var GitHubOAuthProvider = class {
   }
   async listOrganizations() {
     if (this.#token === null) return [];
-    const logins = await listUserOrganizations(this.#api(this.#token.token));
-    return logins.map((login) => ({ login }));
+    const memberships = await listUserMemberships(this.#api(this.#token.token));
+    return memberships.map((m) => ({
+      login: m.login,
+      approved: true,
+      canGrant: m.role === "admin"
+    }));
+  }
+  approvalUrl() {
+    return this.#token?.source === "login" ? approvalUrl() : null;
   }
   async organizationAccess(org) {
     if (this.#token === null) return "unknown";
@@ -3913,6 +3961,9 @@ function inverse(text, stream = process.stdout) {
   const painted = styleText("inverse", text, { stream, validateStream: true });
   return painted === text ? plain : painted;
 }
+function count(n, [one, many]) {
+  return `${n} ${n === 1 ? one : many}`;
+}
 function grey(text, stream = process.stdout) {
   if (noColor()) return text;
   return styleText("gray", text, { stream, validateStream: true });
@@ -4059,6 +4110,12 @@ function agentHintLines(platform = process.platform) {
     `  ~/.ssh/config: AddKeysToAgent yes${mac ? ", UseKeychain yes" : ""}`
   ];
 }
+function passphraseHint(platform = process.platform) {
+  return [
+    "ssh asked for your passphrase, and asks again for every repository unless an agent holds the key:",
+    ...agentHintLines(platform).slice(1)
+  ].join("\n");
+}
 function sshWorkspaceLines(reason3) {
   return [
     `this workspace clones over SSH (rness.json) but ssh to github.com fails: ${reason3}`,
@@ -4308,7 +4365,7 @@ async function ensureClaudeMd(dir) {
 import { join as join15 } from "path";
 
 // src/core/agent-targets.ts
-import { mkdir as mkdir2 } from "fs/promises";
+import { mkdir as mkdir2, rm as rm4, rmdir } from "fs/promises";
 import { dirname as dirname4, join as join14 } from "path";
 
 // src/core/claude-skills.ts
@@ -4317,7 +4374,7 @@ var PLUGIN_JSON = `${JSON.stringify(
   {
     $schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
     name: "rness",
-    description: "The rness workspace in Claude Code: /rness:status, /rness:adr, /rness:spec, /rness:plan, /rness:done.",
+    description: "The rness workspace in Claude Code: /rness:status, /rness:adr, /rness:spec, /rness:plan.",
     author: { name: "rness-dev", url: "https://rness.dev" },
     homepage: "https://rness.dev",
     repository: "https://github.com/rness-dev/rness",
@@ -4360,53 +4417,68 @@ terminal, from the workspace's \`.rness/\`: \`${localRunner(pm)} rness status\`.
 }
 var STATUS_RULE = `Move a status yourself when the work calls for it, and whenever the
 developer says so: a plan \`In progress\` as you start its tasks,
-\`Completed\` once they pass; a specification \`Implemented\` with its last
-plan; a document \`Superseded\` by the one that replaces it. Accepting a
-decision \u2014 an ADR \`Accepted\`, a specification \`Approved\` \u2014 is the
-developer's, unless they asked you to go ahead with the work.`;
+\`Completed\` once its proofs pass under \`check\`; a specification
+\`Implemented\` with its last plan; a document \`Superseded\` by the one that
+replaces it. Accepting an ADR is the developer's; a specification is
+\`Approved\` by \`/rness:plan from NNNN\`, which is their word for it.`;
 var COMMIT_RULE = `Commit each file you changed, in its own repository, and only the files
 you alone changed: add them by name, never \`git add -A\` nor \`commit -a\`.
 A file that had uncommitted changes before your first edit (\`git status\`
 tells you), or that someone else changed since, stays uncommitted: say
 which. Never push.`;
+var SESSION_LINE = `\`{ id: \${CLAUDE_SESSION_ID}, agent: <model> }\` at the end of
+  \`sessions:\` in the front matter, unless that id is already there;
+  \`<model>\` is the model you run as, as Claude Code names it, after
+  \`Claude\`: for example \`Claude Opus 5.5\``;
+var allocateStep = (allocate, collection) => `Allocate the file: run \`${allocate}\` from the project directory, where
+   Claude Code was opened (pre-approved above as typed; \`CLAUDE_PROJECT_DIR\`
+   is not set in your shell, so the path is relative). It writes
+   \`${collection}/NNNN-untitled.md\` with the next number, the front matter
+   and the opening sections, and prints the path. Rename it to
+   \`NNNN-<slug>.md\`, the slug a few lowercase words of the title joined by
+   hyphens, and write the title as \`# NNNN \u2014 <title>\`. Never choose the
+   number yourself.`;
+var HOOK_LINE = (rness) => `The rness hook checks every edit under \`${rness}/\`: fix what it reports.`;
 var LIFECYCLE2 = [
   {
     name: "adr",
-    description: "Record a decision of the rness workspace as an ADR in .rness/adr/ \u2014 a choice expensive to reverse or that creates a lasting constraint. Use when the developer asks for an ADR, or when the conversation reaches such a decision.",
-    hint: "[subject | NNNN]",
+    description: "Record a decision of the rness workspace as an ADR in .rness/adr/ \u2014 a choice expensive to reverse or that creates a lasting constraint \u2014 or reopen one. Use when the developer asks for an ADR, or when the conversation reaches such a decision.",
+    hint: "[create <subject> | open NNNN]",
     tab: "adr",
-    body: (rness) => `You record a decision of this workspace as an ADR in \`${rness}/adr/\`. The table
-above lists the existing ADRs, newest first. Arguments: \`$ARGUMENTS\`.
+    body: (rness, allocate) => `You keep the decisions of this workspace: the ADRs in \`${rness}/adr/\`. The table
+above lists the existing ones, newest first. Arguments: \`$ARGUMENTS\`.
 
-Before writing:
+The first word is the verb, when a reference (\`0010\`, or a path) follows
+it; a bare reference is \`open\`; any other words are the subject of a
+\`create\` (\`open source licensing\` is a subject):
+
+- \`create [subject]\`, or nothing: a new ADR, numbered by rness.
+- \`open NNNN\`: reopen ADR NNNN. An \`Accepted\` ADR is never edited: offer a
+  new one that supersedes it. \`Rejected\` and \`Superseded\` are history too.
+
+Creating:
 
 1. If the developer did not ask for an ADR in so many words, propose one in
    a single line \u2014 its title, and why the choice is hard to reverse \u2014 and
    wait for a yes.
 2. Read \`${rness}/CONVENTIONS.md\` and \`${rness}/adr/0000-template.md\`: they hold the
    rules and the sections; this skill is only the procedure.
-3. Arguments naming an ADR (\`NNNN\`): reopen that file. An \`Accepted\` ADR is
-   never edited: offer a new ADR that supersedes it.
-4. Otherwise the subject is the arguments, else the decision just
-   discussed. Context, alternatives or consequences missing from the
-   conversation: ask for them, one question at a time. Never invent them.
-
-Writing:
-
-- \`${rness}/adr/NNNN-<slug>.md\`, NNNN the highest number above plus one.
-- The template's front matter and sections, filled in, its guidance lines
-  removed: \`date\` today, \`status: Proposed\`, \`repo\` the repositories under
-  \`org/\` it affects.
-- An ADR it replaces is named in Context. That one becomes \`Superseded\`,
-  with \`superseded_by:\`, only once the new ADR is \`Accepted\`.
-- Add \`{ id: \${CLAUDE_SESSION_ID}, agent: <model> }\` at the end of
-  \`sessions:\` in the front matter, unless that id is already there.
-  \`<model>\` is the model you run as, as Claude Code names it, after
-  \`Claude\`: for example \`Claude Opus 5.5\`.
-- The rness hook checks every edit under \`${rness}/\`: fix what it reports.
+3. The subject is the arguments, else the decision just discussed. Context,
+   alternatives or consequences missing from the conversation: ask for
+   them, one question at a time. Never invent them.
+4. ${allocateStep(allocate, "adr")}
+5. Fill it: \`repo\` the repositories under \`org/\` it affects; the template's
+   sections, their guidance lines removed; an ADR it replaces named in
+   Context \u2014 that one becomes \`Superseded\`, with \`superseded_by:\`, only once
+   the new ADR is \`Accepted\`. Add ${SESSION_LINE}.
+6. ${HOOK_LINE(rness)}
 
-After writing: give the path and the Decision section. The ADR stays
-\`Proposed\` until it is accepted.
+Opening: read the ADR and amend what the developer asks, in place while it
+is \`Proposed\`; add the session line above. Nothing of the file's history is
+rewritten: a decision that changed is a new ADR.
+
+After writing: give the path and the Decision section. A new ADR stays
+\`Proposed\` until the developer accepts it.
 
 ${STATUS_RULE}
 
@@ -4415,43 +4487,47 @@ ${COMMIT_RULE}
   },
   {
     name: "spec",
-    description: "Write a specification of the rness workspace in .rness/specs/ \u2014 the outcome wanted and its scope, before any plan. Use when the developer asks for a spec, or when agreed work is too large to start without one.",
-    hint: "[subject | NNNN]",
+    description: "Write a specification of the rness workspace in .rness/specs/ \u2014 the outcome wanted and its scope, before any plan \u2014 or reopen one. Use when the developer asks for a spec, or when agreed work is too large to start without one.",
+    hint: "[create <subject> | open NNNN]",
     tab: "specs",
-    body: (rness) => `You write a specification of this workspace in \`${rness}/specs/\`. The table above
-lists the existing ones, newest first. Arguments: \`$ARGUMENTS\`.
+    body: (rness, allocate) => `You keep the specifications of this workspace, in \`${rness}/specs/\`. The table
+above lists the existing ones, newest first. Arguments: \`$ARGUMENTS\`.
+
+The first word is the verb, when a reference (\`0028\`, or a path) follows
+it; a bare reference is \`open\`; any other words are the subject of a
+\`create\`:
+
+- \`create [subject]\`, or nothing: a new specification, numbered by rness.
+- \`open NNNN\`: reopen specification NNNN. One that is \`Implemented\`,
+  \`Superseded\` or \`Rejected\` is not edited: offer a new one.
 
-Before writing:
+Creating:
 
 1. If the developer did not ask for a specification in so many words,
    propose one in a single line and wait for a yes.
 2. Read \`${rness}/CONVENTIONS.md\`, then the most recent specification above: match
    its front matter, sections and tone.
-3. Arguments naming a specification (\`NNNN\`): reopen it. One that is
-   \`Implemented\`, \`Superseded\` or \`Rejected\` is not edited: offer a new one.
-4. Otherwise the subject is the arguments, else the work just discussed.
-   The problem, what is in and out of scope, the ADRs it rests on: ask what
-   the conversation does not say, one question at a time.
-
-Writing:
-
-- \`${rness}/specs/NNNN-<slug>.md\`, NNNN the highest number above plus one.
-- \`date\` and \`updated\` today, \`status: Draft\`, \`repo\`, and \`adr:\` linking
-  the decisions it rests on \u2014 or the rationale in the body when none does.
-- No specification yet to follow: Summary, Scope, Out of scope,
-  Alternatives considered, To verify, Tests.
-- What was checked in this session (a document read, a command run) is
-  written as verified, with the date; everything else as a proposal or an
-  open question.
-- Add \`{ id: \${CLAUDE_SESSION_ID}, agent: <model> }\` at the end of
-  \`sessions:\` in the front matter, unless that id is already there.
-  \`<model>\` is the model you run as, as Claude Code names it, after
-  \`Claude\`: for example \`Claude Opus 5.5\`.
-- The rness hook checks every edit under \`${rness}/\`: fix what it reports.
+3. The subject is the arguments, else the work just discussed. The problem,
+   what is in and out of scope, the ADRs it rests on: ask what the
+   conversation does not say, one question at a time.
+4. ${allocateStep(allocate, "specs")}
+5. Fill it: \`repo\`, and \`adr:\` linking the decisions it rests on \u2014 or the
+   rationale in the body when none does; the sections it opened with
+   (Summary, Scope, Out of scope, Alternatives considered, To verify,
+   Tests), or the most recent specification's when the team's differ. What
+   was checked in this session (a document read, a command run) is written
+   as verified, with the date; everything else as a proposal or an open
+   question. Add ${SESSION_LINE}.
+6. ${HOOK_LINE(rness)}
+
+Opening: read the specification and amend what the developer asks \u2014 a
+section, a scope, an open question answered \u2014 \`updated\` today, the session
+line added. A status moves only as the developer says, or by
+\`/rness:plan from\`.
 
-After writing: give the path and the summary. It starts \`Draft\`:
-\`Proposed\` for review, \`Approved\` to plan it. No plan here:
-\`/rness:plan NNNN\` once approved.
+After writing: give the path and the summary. A new specification starts
+\`Draft\`: \`Proposed\` for review; \`/rness:plan from NNNN\` approves it and
+plans it.
 
 ${STATUS_RULE}
 
@@ -4460,105 +4536,104 @@ ${COMMIT_RULE}
   },
   {
     name: "plan",
-    description: "Turn an approved specification of the rness workspace into a plan in .rness/plans/ \u2014 ordered tasks, each with the command that proves it done. Use when the developer asks for a plan, or when a specification has just been approved.",
-    hint: "<spec NNNN>",
+    description: "The plans of the rness workspace in .rness/plans/ \u2014 a plan from a specification (from, which approves it), from the conversation (create), reopened (open), or closed on evidence (check). Use when the developer asks for a plan, to approve a specification, or to check the work of a plan.",
+    hint: "[create <subject> | from <spec> | open NNNN | check NNNN]",
     tab: "plans",
-    body: (rness) => `You turn a specification into a plan in \`${rness}/plans/\`. The table above lists
-the existing plans, newest first. Arguments, the specification:
-\`$ARGUMENTS\`.
-
-Before writing:
-
-1. If the developer did not ask for a plan in so many words, propose one in
-   a single line and wait for a yes.
-2. No specification named: ask which. Read it, \`${rness}/CONVENTIONS.md\`, and the
-   most recent plan above: match its front matter and sections.
-3. A specification that is not \`Approved\`: say so, and plan it only if the
-   developer confirms. A plan of it that is neither \`Completed\` nor
-   \`Abandoned\`: reopen it rather than write a second.
-4. Read the code and the repositories the specification touches: every
-   task names real files and real commands.
+    body: (rness, allocate) => `You keep the plans of this workspace, in \`${rness}/plans/\`. The table above
+lists the existing ones, newest first. Arguments: \`$ARGUMENTS\`.
 
-Writing:
-
-- \`${rness}/plans/NNNN-<slug>.md\`, NNNN the highest plan number above plus one \u2014
-  not the specification's.
-- \`date\` and \`updated\` today, \`status: Draft\`, \`repo\`, \`spec:\` linking the
-  specification.
-- Tasks in order, as checkboxes. Each gives the files, what changes, and
-  the command that proves it (a test, a build, a run). The last tasks:
-  the documentation the work makes inaccurate, then the release when the
-  repository has one.
-- Where the plan decides something the specification leaves open, a
-  section says so.
-- Add \`{ id: \${CLAUDE_SESSION_ID}, agent: <model> }\` at the end of
-  \`sessions:\` in the front matter, unless that id is already there.
-  \`<model>\` is the model you run as, as Claude Code names it, after
-  \`Claude\`: for example \`Claude Opus 5.5\`.
-- The rness hook checks every edit under \`${rness}/\`: fix what it reports.
+The first word is the verb, when a reference (\`0037\`, or a path) follows
+it \u2014 \`check\` alone means the plan \`In progress\`; a bare reference is
+\`open\`; any other words are the subject of a \`create\`:
 
-After writing: give the path and the list of tasks. It starts \`Draft\`, and
-becomes \`Ready\` once the developer agrees with it or asks you to carry it
-out.
+- \`from NNNN\`: a plan from specification NNNN, which this approves.
+- \`create [subject]\`, or nothing: a plan from the conversation, for work
+  too small for a specification; \`spec:\` is left empty.
+- \`open NNNN\`: reopen plan NNNN.
+- \`check NNNN\`: run the proofs of plan NNNN; close it when they all pass.
 
-${STATUS_RULE}
+\`from\`:
 
-${COMMIT_RULE}
-`
-  },
-  {
-    name: "done",
-    description: "Close a piece of work of the rness workspace \u2014 check each task of its plan on evidence, then move the plan and its specification to their final status and correct the documents the work made inaccurate. Use when the developer says the work is done, or when the last task of a plan passes.",
-    hint: "[plan NNNN]",
-    tab: "plans",
-    body: (rness) => `You close a piece of work: its plan in \`${rness}/plans/\`, its specification, and
-what they made inaccurate. The table above lists the plans, newest first.
-Arguments: \`$ARGUMENTS\`.
+1. Read the specification, \`${rness}/CONVENTIONS.md\`, and the most recent plan
+   above: match its front matter and sections. A specification that is
+   \`Implemented\`, \`Superseded\` or \`Rejected\` is refused: say its status,
+   write nothing. A plan of it that is neither \`Completed\` nor \`Abandoned\`:
+   reopen it rather than write a second.
+2. The developer typed this command: that is their approval, and the
+   specification moves from \`Draft\` or \`Proposed\` to \`Approved\`, \`updated\`
+   today, in the same commit as the plan \u2014 no confirmation question. If
+   you are proposing it yourself, propose it in a single line and wait for
+   a yes first: the approval is theirs, never yours.
+3. Read the code and the repositories the specification touches: every
+   task names real files and real commands.
+4. ${allocateStep(allocate, "plans")}
+5. Fill it: \`spec:\` linking the specification; tasks in order, as
+   checkboxes, each with the files, what changes, and the command that
+   proves it (a test, a build, a run) \u2014 the last tasks the documentation
+   the work makes inaccurate, then the release when the repository has
+   one; where the plan decides something the specification leaves open, the
+   section it opened with says so. Add ${SESSION_LINE}.
+6. ${HOOK_LINE(rness)}
+
+\`create\`: as \`from\`, without a specification. If the developer did not ask
+for a plan in so many words, propose one in a single line and wait for a
+yes. The body says what the work is and why it needs no specification.
+
+\`open\`: read the plan and its specification; amend what the developer
+asks \u2014 a task added, split or reworded, a blocker recorded \u2014 \`updated\`
+today, the session line added; move \`Draft\` to \`Ready\` or \`Blocked\` as they
+say. A \`Completed\` or \`Abandoned\` plan is not reopened: offer a new plan of
+the same specification.
+
+\`check\`:
 
 1. The plan: the one named, else the one \`In progress\`. Several or none:
    ask.
-2. The developer asked to close it, or its last task has just passed in
-   this session: close it. Otherwise propose it in a single line and wait
-   for a yes.
+2. The developer asked for the check, or the plan's last task has just
+   passed in this session: run it. Otherwise propose it in a single line
+   and wait for a yes.
 3. Read the plan, its specification and \`${rness}/CONVENTIONS.md\`.
-4. Evidence first. For each task, what shows it done: a test, a build, a
-   command's output in this session. A task without evidence: run its
-   check now, or report it. Never mark a task done on belief.
-5. All tasks proven:
+4. Evidence first. For each task, what proves it: its command run now, or
+   its result read in this session. Never mark a task done on belief. A
+   check has no cache: run twice, it proves twice.
+5. Every task proven:
    - the plan: \`status: Completed\`, \`updated\` today, the checkboxes of the
      proven tasks ticked, and a section \`Verification (YYYY-MM-DD)\` \u2014 what
      ran, what it showed, what could not run and why;
    - the specification: \`Implemented\` once every plan of it is
      \`Completed\`; \`updated\` today;
-   - the plan and the specification: add
-     \`{ id: \${CLAUDE_SESSION_ID}, agent: <model> }\` at the end of
-     \`sessions:\` in their front matter, unless that id is already there;
-     \`<model>\` is the model you run as, as Claude Code names it, after
-     \`Claude\`: for example \`Claude Opus 5.5\`;
+   - the plan and the specification: add ${SESSION_LINE};
    - the smallest set of documents the work makes inaccurate: \`${rness}/docs/\`,
      the READMEs of the repositories it changed.
-6. A task not proven: the plan stays \`In progress\` \u2014 or \`Blocked\`, the
-   blocker written in it. Say what remains.
-7. The rness hook checks every edit under \`${rness}/\`: fix what it reports.
+6. A task not proven: nothing moves, the plan stays \`In progress\`. Say,
+   task by task, what passed and what remains. A blocker the developer
+   names is a move of its own: \`Blocked\`, the blocker written in the plan.
+7. ${HOOK_LINE(rness)}
+
+After writing: give the path and the list of tasks, or the statuses moved.
+A new plan starts \`Draft\`, and becomes \`Ready\` once the developer agrees
+with it or asks you to carry it out.
 
-After: list the files changed and the statuses moved.
+${STATUS_RULE}
 
 ${COMMIT_RULE}
 `
   }
 ];
+var RETIRED_SKILLS = ["done"];
 function lifecycleSkill(rness, s) {
   const command = `node "\${CLAUDE_PROJECT_DIR}/${rness}/${PINNED_BIN}" status ${s.tab} --cwd "\${CLAUDE_PROJECT_DIR}"`;
+  const allocate = `node "${rness}/${PINNED_BIN}" doc new ${s.tab}`;
   return `---
 name: ${s.name}
 description: ${s.description}
 argument-hint: '${s.hint}'
-allowed-tools: Bash(${command})
+allowed-tools: Bash(${command}), Bash(${allocate})
 ---
 
 !\`${command}\`
 
-${s.body(rness)}`;
+${s.body(rness, allocate)}`;
 }
 function pluginFiles(rness, at, ctx) {
   return [
@@ -4572,6 +4647,11 @@ function pluginFiles(rness, at, ctx) {
       file: `${PLUGIN}/skills/${s.name}/SKILL.md`,
       at,
       content: lifecycleSkill(rness, s)
+    })),
+    ...RETIRED_SKILLS.map((name) => ({
+      file: `${PLUGIN}/skills/${name}/SKILL.md`,
+      at,
+      retired: true
     }))
   ];
 }
@@ -5097,6 +5177,21 @@ async function agentTargets(root, manifest, opts) {
   for (const owned of await filesOf(root, manifest, declared(manifest))) {
     const { file, label } = owned;
     const existing = await readOrNull(file);
+    if ("retired" in owned) {
+      if (existing === null) continue;
+      if (opts.check) {
+        outcomes.push({
+          label,
+          status: "stale",
+          detail: "no longer written by rness; remove it"
+        });
+        continue;
+      }
+      await rm4(file);
+      await rmdir(dirname4(file)).catch(() => void 0);
+      outcomes.push({ label, status: "removed", detail: null });
+      continue;
+    }
     if ("content" in owned) {
       const diff = wholeDiff(existing, owned.content);
       if (diff === null)
@@ -5147,6 +5242,7 @@ async function leftoverTargets(root, manifest) {
   );
   const leftovers = [];
   for (const owned of await filesOf(root, manifest, undeclared)) {
+    if ("retired" in owned) continue;
     const existing = await readOrNull(owned.file);
     if (existing === null) continue;
     if ("content" in owned) {
@@ -5435,7 +5531,7 @@ async function askWhatToSync(input) {
         {
           value: SELECT_ALL,
           label: "Select all",
-          hint: `${input.missing.length} repositories from rness.json`
+          hint: `${count(input.missing.length, ["repository", "repositories"])} from rness.json`
         },
         ...input.missing.map((name) => ({ value: name, label: name }))
       ],
@@ -5542,6 +5638,7 @@ async function syncCommand(opts, deps = {}) {
         () => ui.line(...CHECKING)
       );
       if (unattended) ui.gitIsSilent = true;
+      else if (access2.ok) ui.hint(passphraseHint(), "stderr");
       if (!access2.ok) {
         process.stderr.write(
           `${[...sshWorkspaceLines(access2.reason), ...INSTEAD_OF_LINES].join("\n")}
@@ -5779,6 +5876,7 @@ async function addCommand(spec, opts, deps = {}) {
         () => ui.line(...CHECKING)
       );
       if (unattended || !access2.ok) ui.gitIsSilent = true;
+      else ui.hint(passphraseHint(), "stderr");
       const overSsh = Object.values(manifest.repos).some(
         (r) => isSshUrl(r.url, transport.hosts)
       );
@@ -6000,9 +6098,23 @@ async function copyScaffold(dest, tokens) {
 }
 
 // src/commands/login.ts
-import { spawn as spawn3 } from "child_process";
 import { realpath } from "fs/promises";
 
+// src/core/browser.ts
+import { spawn as spawn3 } from "child_process";
+function openInBrowser(url) {
+  const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+  try {
+    const child = spawn3(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => void 0);
+    child.unref();
+  } catch {
+  }
+}
+function canOpenBrowser() {
+  return process.env["SSH_CONNECTION"] === void 0;
+}
+
 // src/core/setup-git.ts
 import { execFile as execFile4 } from "child_process";
 import { promisify as promisify4 } from "util";
@@ -6047,15 +6159,6 @@ async function removeGitSetup() {
 }
 
 // src/commands/login.ts
-function openInBrowser(url) {
-  const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
-  try {
-    const child = spawn3(command, args, { stdio: "ignore", detached: true });
-    child.on("error", () => void 0);
-    child.unref();
-  } catch {
-  }
-}
 async function offerSetupGit(opts, terminal, bin, ui) {
   if (opts.setupGit === false) return;
   if (!isStableInstall(bin)) {
@@ -6132,7 +6235,7 @@ async function loginCommand(opts, deps = {}) {
       ui.line("open", code.verificationUri);
       ui.line("code", code.userCode);
     }
-    if (terminal.isTty() && process.env["SSH_CONNECTION"] === void 0)
+    if (terminal.isTty() && canOpenBrowser())
       (deps.open ?? openInBrowser)(code.verificationUri);
     if (!ui.session)
       ui.line("waiting", "for you to approve rness on github.com\u2026");
@@ -6165,35 +6268,134 @@ async function loginCommand(opts, deps = {}) {
     return reportError(e);
   }
 }
-function revokeUrl() {
-  return `https://github.com/settings/connections/applications/${clientId()}`;
-}
 
 // src/commands/create.ts
-import { mkdir as mkdir6, mkdtemp as mkdtemp2, rename as rename2, rm as rm6 } from "fs/promises";
+import { mkdir as mkdir6, mkdtemp as mkdtemp2, rename as rename2, rm as rm7 } from "fs/promises";
 import { tmpdir as tmpdir2 } from "os";
 import { join as join22, relative as relative4, resolve as resolve5 } from "path";
 
+// src/core/approval.ts
+var APPROVAL_INTERVAL_MS = 5e3;
+var APPROVAL_WAIT_MS = 10 * 6e4;
+function approvalQuestion(org) {
+  return `Open github.com to approve rness for ${org} now?`;
+}
+async function checkAccess(input) {
+  const { org, provider, ui } = input;
+  if (!provider.authenticated) return "unknown";
+  const login = (await provider.identity())?.login;
+  const as = login === void 0 ? "" : ` (as ${login})`;
+  const member = () => ui.line("member", `${org}${as}`, `You are a member of ${org}${as}`);
+  const access2 = await provider.organizationAccess(org);
+  if (access2 === "member") {
+    member();
+    return access2;
+  }
+  if (access2 !== "restricted") return access2;
+  const url = provider.approvalUrl();
+  ui.warn(
+    `${org} has not approved rness, so its private repositories are hidden`
+  );
+  if (!input.interactive || url === null) {
+    ui.hint(
+      url === null ? `an owner of ${org} has to approve the app your token belongs to` : `an owner approves it at ${url}`,
+      "stderr"
+    );
+    return "restricted";
+  }
+  const p = await input.prompts();
+  const ok = await p.confirm({
+    message: approvalQuestion(org),
+    initialValue: true
+  });
+  if (p.isCancel(ok)) return "cancelled";
+  if (ok !== true) {
+    ui.hint(`approve it later: ${url}`, "stderr");
+    return "restricted";
+  }
+  ui.line("open", url, `Open ${url} and approve rness for ${org}`);
+  if (canOpenBrowser()) (input.deps?.open ?? openInBrowser)(url);
+  const sleep = input.deps?.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const now = input.deps?.now ?? Date.now;
+  const who = input.canGrant === true ? org : `an owner of ${org}`;
+  const waiting = `for ${who} to approve rness on github.com`;
+  if (!ui.session) ui.line("waiting", `${waiting}\u2026`);
+  let interrupted = false;
+  let wake = () => void 0;
+  const interrupt = () => {
+    interrupted = true;
+    wake();
+  };
+  if (!ui.session) process.once("SIGINT", interrupt);
+  let outcome;
+  try {
+    outcome = await ui.step(
+      {
+        doing: `waiting  ${waiting}`,
+        sentence: `Waiting ${waiting}`,
+        quiet: true
+      },
+      async () => {
+        const deadline = now() + APPROVAL_WAIT_MS;
+        for (; ; ) {
+          await Promise.race([
+            sleep(APPROVAL_INTERVAL_MS),
+            new Promise((resolve8) => {
+              wake = resolve8;
+            })
+          ]);
+          if (interrupted) return "cancelled";
+          const again = await provider.organizationAccess(org);
+          if (again === "member" || again === "not-member") return again;
+          if (now() >= deadline) return "timeout";
+        }
+      },
+      (r) => r === "member" ? ["member", `${org}${as}`] : null
+    );
+  } finally {
+    process.off("SIGINT", interrupt);
+  }
+  if (outcome === "cancelled") return outcome;
+  if (outcome === "member") {
+    if (!ui.session) member();
+    return outcome;
+  }
+  if (outcome === "not-member") return outcome;
+  ui.warn(
+    `${org} still has not approved rness; its private repositories stay hidden this time`
+  );
+  ui.hint(
+    `once an owner approves it, add its private repositories with ${rnessCommand()} add <repo>`,
+    "stderr"
+  );
+  return "restricted";
+}
+
 // src/core/ask-provider.ts
 var PROVIDER_QUESTION = "Where does your organization live?";
+var BLANK = "blank";
+var BLANK_LABEL = "No organization yet: a blank local workspace";
 async function askProvider(p) {
   return p.select({
     message: PROVIDER_QUESTION,
-    options: Object.values(PROVIDERS).map((entry) => ({
-      value: entry.name,
-      label: entry.available ? entry.label : `${entry.label} (coming later)`,
-      disabled: !entry.available
-    }))
+    options: [
+      ...Object.values(PROVIDERS).map((entry) => ({
+        value: entry.name,
+        label: entry.available ? entry.label : `${entry.label} (coming later)`,
+        disabled: !entry.available
+      })),
+      { value: BLANK, label: BLANK_LABEL, disabled: false }
+    ]
   });
 }
 
 // src/core/new-workspace.ts
-import { mkdir as mkdir4, readdir as readdir4, rm as rm5, stat as stat3 } from "fs/promises";
+import { mkdir as mkdir4, readdir as readdir4, rm as rm6, stat as stat3 } from "fs/promises";
 import { dirname as dirname8, join as join20, relative as relative2 } from "path";
 
 // src/core/scaffold-git.ts
 import { execFile as execFile5 } from "child_process";
-import { mkdtemp, realpath as realpath2, rm as rm4, writeFile as writeFile3 } from "fs/promises";
+import { mkdtemp, realpath as realpath2, rm as rm5, writeFile as writeFile3 } from "fs/promises";
 import { tmpdir } from "os";
 import { dirname as dirname7, join as join19, resolve as resolve3 } from "path";
 import { promisify as promisify5 } from "util";
@@ -6321,7 +6523,7 @@ async function buildScaffoldCommit(rnessDir, base, files, version) {
       scaffoldMessage(`chore: rness scaffold ${version}`, version)
     ]);
   } finally {
-    await rm4(scratch, { recursive: true, force: true });
+    await rm5(scratch, { recursive: true, force: true });
   }
 }
 async function blobAt(rnessDir, rev, path) {
@@ -6445,9 +6647,9 @@ async function buildContext(input) {
     return true;
   } catch (e) {
     reportError(e);
-    await rm5(rnessDir, { recursive: true, force: true }).catch(() => void 0);
+    await rm6(rnessDir, { recursive: true, force: true }).catch(() => void 0);
     if (await isEmptyDir(root).catch(() => false))
-      await rm5(root, { recursive: true, force: true }).catch(() => void 0);
+      await rm6(root, { recursive: true, force: true }).catch(() => void 0);
     process.stderr.write(
       `removed ${shown}/.rness after the failure; fix it and retry
 `
@@ -6630,22 +6832,6 @@ function cancelled(ui) {
 }
 async function pickRepositories(input) {
   const { org, prompts, provider, ui } = input;
-  if (provider.authenticated) {
-    const access2 = await provider.organizationAccess(org);
-    const login = (await provider.identity())?.login;
-    if (access2 === "member")
-      ui.line(
-        "member",
-        `${org}${login === void 0 ? "" : ` (as ${login})`}`,
-        `You are a member of ${org}${login === void 0 ? "" : ` (as ${login})`}`
-      );
-    else if (access2 === "restricted") {
-      ui.warn(
-        `${org} restricts OAuth apps, so its private repositories are hidden from rness`
-      );
-      ui.hint(`ask an owner to approve it: ${revokeUrl()}`, "stderr");
-    }
-  }
   let listed = [];
   let failed = false;
   if (!ui.session) ui.line("listing", `${org} repositories\u2026`);
@@ -6661,7 +6847,7 @@ async function pickRepositories(input) {
       // list below it must agree (spec 0009).
       (l) => [
         "listed",
-        `${l.repositories.filter(isMemberRepo).length} repositories of ${org}`
+        `${count(l.repositories.filter(isMemberRepo).length, ["repository", "repositories"])} of ${org}`
       ]
     );
     listed = listing.repositories;
@@ -6795,17 +6981,6 @@ function blankConflict(opts) {
   if (opts.provider !== void 0) return "--provider";
   return null;
 }
-async function chooseStart(prompts) {
-  const answer = await prompts.select({
-    message: "How do you want to start?",
-    options: [
-      { value: "github", label: "From a GitHub organization" },
-      { value: "blank", label: "Blank local workspace" }
-    ]
-  });
-  if (prompts.isCancel(answer)) return null;
-  return answer === "blank" ? "blank" : "github";
-}
 function providerFlagError(value) {
   if (!isProviderName(value))
     return `unknown provider "${value}" (${Object.keys(PROVIDERS).join(", ")})`;
@@ -6814,27 +6989,37 @@ function providerFlagError(value) {
   return `provider "${value}" is not available yet (available: ${available.join(", ")})`;
 }
 var OTHER = /* @__PURE__ */ Symbol("another organization");
+var OTHER_LABEL = "an organization not listed here\u2026";
+var OTHER_HINT = "not a member, or it has not approved rness yet";
+var NOT_APPROVED = "rness not approved";
 async function chooseOrganization(provider, prompts) {
   if (!provider.authenticated) return OTHER;
-  let names;
+  let organizations;
+  let self;
   try {
-    const self = (await provider.identity())?.login;
-    names = (await provider.listOrganizations()).map((o) => o.login);
-    if (self !== void 0) names.push(self);
+    self = (await provider.identity())?.login;
+    organizations = await provider.listOrganizations();
   } catch {
     return OTHER;
   }
-  if (names.length === 0) return OTHER;
+  if (organizations.length === 0 && self === void 0) return OTHER;
+  const padlock = unicode();
+  const options = organizations.map((o) => ({
+    value: o.login,
+    label: !o.approved && padlock ? `${o.login} ${PRIVATE_MARK}` : o.login,
+    ...o.approved ? {} : { hint: NOT_APPROVED }
+  }));
+  if (self !== void 0)
+    options.push({ value: self, label: self, hint: "your account" });
+  options.push({ value: "", label: OTHER_LABEL, hint: OTHER_HINT });
   const answer = await prompts.select({
     message: "Which GitHub organization?",
-    options: [
-      ...names.map((name) => ({ value: name, label: name })),
-      { value: "", label: "another one\u2026" }
-    ]
+    options
   });
   if (prompts.isCancel(answer)) return null;
   if (typeof answer !== "string" || answer === "") return OTHER;
-  return answer;
+  const picked = organizations.find((o) => o.login === answer);
+  return { org: answer, canGrant: picked?.canGrant ?? null };
 }
 async function publishContext(input) {
   const { ui, prompts, provider, org } = input;
@@ -6873,6 +7058,11 @@ async function publishContext(input) {
 async function createCommand(opts, deps = {}) {
   const terminal = deps.terminal ?? defaultTerminal;
   const transport = deps.transport ?? defaultTransport;
+  const clock = {
+    ...deps.open === void 0 ? {} : { open: deps.open },
+    ...deps.sleep === void 0 ? {} : { sleep: deps.sleep },
+    ...deps.now === void 0 ? {} : { now: deps.now }
+  };
   let provider = deps.provider;
   const getProvider = async () => provider ??= await githubProvider(opts.githubApi);
   const cwd = opts.cwd ?? process.cwd();
@@ -6938,6 +7128,7 @@ async function createCommand(opts, deps = {}) {
         () => ui.line(...CHECKING)
       );
       if (sshTest.unattended) ui.gitIsSilent = true;
+      else if (sshTest.access.ok) ui.hint(passphraseHint(), "stderr");
     }
     return sshTest.access;
   };
@@ -6967,10 +7158,14 @@ async function createCommand(opts, deps = {}) {
       return 1;
     }
     let blank = opts.blank === true;
-    if (!blank && interactive && opts.org === void 0 && opts.repos === void 0) {
-      const start = await chooseStart(await prompts());
-      if (start === null) return cancelled(ui);
-      blank = start === "blank";
+    let chosenProvider = "github";
+    if (opts.provider !== void 0 && isProviderName(opts.provider))
+      chosenProvider = opts.provider;
+    else if (!blank && interactive && opts.org === void 0 && opts.repos === void 0) {
+      const answer = await askProvider(await prompts());
+      if (typeof answer !== "string") return cancelled(ui);
+      if (answer === BLANK) blank = true;
+      else chosenProvider = answer;
     }
     if (blank)
       return await createBlank({
@@ -6984,14 +7179,6 @@ async function createCommand(opts, deps = {}) {
         ui,
         prompts
       });
-    let chosenProvider = "github";
-    if (opts.provider !== void 0 && isProviderName(opts.provider))
-      chosenProvider = opts.provider;
-    else if (interactive) {
-      const answer = await askProvider(await prompts());
-      if (typeof answer !== "string") return cancelled(ui);
-      chosenProvider = answer;
-    }
     let prompted = false;
     let org = opts.org;
     if (org === void 0 && !interactive) {
@@ -7001,19 +7188,20 @@ async function createCommand(opts, deps = {}) {
     if (interactive && opts.repos === void 0 && !(await getProvider()).authenticated) {
       const p = await prompts();
       const login = await p.confirm({
-        message: "Log in to GitHub to list private repositories?",
+        message: "Log in to GitHub to list your organizations and private repositories?",
         initialValue: true
       });
       if (p.isCancel(login)) return cancelled(ui);
       if (login === true) {
         const code2 = await loginCommand(
           opts.githubApi === void 0 ? {} : { githubApi: opts.githubApi },
-          { terminal, ui }
+          { terminal, ui, ...clock }
         );
         if (code2 !== 0) return code2;
         provider = await githubProvider(opts.githubApi);
       }
     }
+    let canGrant = null;
     if (org === void 0) {
       const chosen = await chooseOrganization(
         await getProvider(),
@@ -7021,7 +7209,8 @@ async function createCommand(opts, deps = {}) {
       );
       if (chosen === null) return cancelled(ui);
       if (chosen !== OTHER) {
-        org = chosen;
+        org = chosen.org;
+        canGrant = chosen.canGrant;
         prompted = true;
       }
     }
@@ -7053,6 +7242,16 @@ async function createCommand(opts, deps = {}) {
       );
       return 2;
     }
+    const outcome = await checkAccess({
+      org,
+      provider: await getProvider(),
+      ui,
+      interactive,
+      prompts,
+      canGrant,
+      deps: clock
+    });
+    if (outcome === "cancelled") return cancelled(ui);
     const host = await chooseHost();
     const contextUrl = repoUrl(host, org, ".rness");
     let gitProvider = await getProvider();
@@ -7292,7 +7491,7 @@ ${next2.map((l) => `  ${l}`).join("\n")}
     return reportError(e);
   } finally {
     if (staging !== void 0)
-      await rm6(staging, { recursive: true, force: true }).catch(() => void 0);
+      await rm7(staging, { recursive: true, force: true }).catch(() => void 0);
   }
 }
 
@@ -7397,7 +7596,7 @@ async function logoutCommand() {
         `${status("updated", "git: rness no longer answers for https://github.com")}
 `
       );
-    process.stdout.write(`revoke rness on GitHub: ${revokeUrl()}
+    process.stdout.write(`revoke rness on GitHub: ${approvalUrl()}
 `);
     return 0;
   } catch (e) {
@@ -7407,7 +7606,7 @@ async function logoutCommand() {
 
 // src/commands/upgrade.ts
 import { execFile as execFile6 } from "child_process";
-import { mkdtemp as mkdtemp3, readFile as readFile10, rm as rm7 } from "fs/promises";
+import { mkdtemp as mkdtemp3, readFile as readFile10, rm as rm8 } from "fs/promises";
 import { tmpdir as tmpdir3 } from "os";
 import { basename as basename5, join as join24, relative as relative5 } from "path";
 import { promisify as promisify6 } from "util";
@@ -7433,7 +7632,7 @@ async function scaffoldFor(version, rnessDir) {
   if (installed?.version === version && inside2 !== null && await exists(join24(inside2, "package.json")))
     return { dir: inside2 };
   const scratch = await mkdtemp3(join24(tmpdir3(), "rness-pack-"));
-  const cleanup = () => rm7(scratch, { recursive: true, force: true });
+  const cleanup = () => rm8(scratch, { recursive: true, force: true });
   try {
     const { stdout } = await execFileP6(
       "npm",
@@ -7852,6 +8051,102 @@ async function validateCommand(opts, deps = {}) {
 // src/cli.ts
 import { Command, CommanderError, Option } from "commander";
 
+// src/commands/doc.ts
+import { mkdir as mkdir7, readFile as readFile11, writeFile as writeFile4 } from "fs/promises";
+import { join as join25 } from "path";
+var NUMBERED = Object.keys(STATUSES);
+var SECTIONS = {
+  specs: [
+    "Summary",
+    "Scope",
+    "Out of scope",
+    "Alternatives considered",
+    "To verify",
+    "Tests"
+  ],
+  plans: ["Decided here, where the specification leaves it open", "Tasks"]
+};
+function slugOf(title) {
+  const slug = title.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60).replace(/-+$/g, "");
+  return slug === "" ? "untitled" : slug;
+}
+function today() {
+  return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+}
+function headingsOf(template) {
+  return [...template.matchAll(/^## (.+)$/gm)].map((m) => (m[1] ?? "").trim());
+}
+async function adrSections(rnessDir) {
+  const own = join25(rnessDir, "adr", "0000-template.md");
+  const shipped = join25(scaffoldDir(), "adr", "0000-template.md");
+  for (const file of [own, shipped]) {
+    try {
+      const sections = headingsOf(await readFile11(file, "utf8"));
+      if (sections.length > 0) return sections;
+    } catch {
+    }
+  }
+  return ["Context", "Decision", "Alternatives Considered", "Consequences"];
+}
+async function writeDocument(file, text) {
+  try {
+    await writeFile4(file, text, { flag: "wx" });
+  } catch (e) {
+    if (e.code !== "EEXIST") throw e;
+    process.stderr.write(`${file} exists; nothing written
+`);
+    return 1;
+  }
+  process.stdout.write(`${file}
+`);
+  return 0;
+}
+async function docNewCommand(collection, opts) {
+  if (!NUMBERED.includes(collection)) {
+    process.stderr.write(
+      `${collection} is not a numbered collection of this workspace (${NUMBERED.join(", ")})
+`
+    );
+    return 2;
+  }
+  const name = collection;
+  try {
+    const ws = await findWorkspace(opts.cwd ?? process.cwd());
+    const dir = join25(ws.rnessDir, name);
+    await mkdir7(dir, { recursive: true });
+    let highest = 0;
+    for (const item of await collectMarkdown(dir)) {
+      const number2 = documentNumber(item.rel);
+      if (number2 !== null) highest = Math.max(highest, Number(number2));
+    }
+    const number = String(highest + 1).padStart(4, "0");
+    const title = opts.title?.trim() || "Untitled";
+    const file = join25(dir, `${number}-${slugOf(title)}.md`);
+    const status2 = STATUSES[name]?.[0] ?? "Draft";
+    const date = today();
+    const front = [
+      "---",
+      `date: ${date}`,
+      `status: ${status2}`,
+      "repo: ''",
+      // An ADR is never updated once accepted: no `updated` (CONVENTIONS.md).
+      ...name === "adr" ? [] : [`updated: ${date}`],
+      "---"
+    ];
+    const sections = name === "adr" ? await adrSections(ws.rnessDir) : SECTIONS[name] ?? [];
+    const body = [
+      `# ${number} \u2014 ${title}`,
+      // The rule under the title, as the ADR and specification templates draw it.
+      ...name === "plans" ? [] : ["", "---"],
+      ...sections.flatMap((s) => ["", `## ${s}`])
+    ];
+    return await writeDocument(file, `${[...front, "", ...body].join("\n")}
+`);
+  } catch (e) {
+    return reportError(e);
+  }
+}
+
 // src/commands/git-credential.ts
 async function readStdin() {
   const chunks = [];
@@ -7880,8 +8175,8 @@ import { realpath as realpath4 } from "fs/promises";
 import { isAbsolute as isAbsolute2, posix as posix8, relative as relative7, resolve as resolve7, sep as sep5 } from "path";
 
 // src/mcp/tools.ts
-import { readFile as readFile11, realpath as realpath3, stat as stat4 } from "fs/promises";
-import { isAbsolute, join as join25, posix as posix7, relative as relative6, resolve as resolve6, sep as sep4 } from "path";
+import { readFile as readFile12, realpath as realpath3, stat as stat4 } from "fs/promises";
+import { isAbsolute, join as join26, posix as posix7, relative as relative6, resolve as resolve6, sep as sep4 } from "path";
 var LABELS = {
   standards: "Standards",
   adr: "Decisions",
@@ -7910,7 +8205,7 @@ async function documents(rnessDir, only) {
   const docs = [];
   for (const collection of COLLECTIONS) {
     if (only !== void 0 && collection !== only) continue;
-    for (const item of await collectMarkdown(join25(rnessDir, collection))) {
+    for (const item of await collectMarkdown(join26(rnessDir, collection))) {
       const path = `${collection}/${item.rel}`;
       if (path === TEMPLATE2) continue;
       const status2 = item.fields?.["status"];
@@ -8032,7 +8327,7 @@ async function read(cwd, args) {
     return refuse(
       `${path}: ${info.size} bytes, over the 256 KiB rness_read returns`
     );
-  return { text: await readFile11(real, "utf8") };
+  return { text: await readFile12(real, "utf8") };
 }
 async function search(cwd, args) {
   const { ws } = await workspaceAt(cwd);
@@ -8140,8 +8435,8 @@ function mcpTools(cwd) {
 
 // src/pulse/detached.ts
 import { spawn as nodeSpawn } from "child_process";
-import { mkdir as mkdir7, open as open2, readFile as readFile12, rm as rm8, stat as stat5, writeFile as writeFile4 } from "fs/promises";
-import { join as join26 } from "path";
+import { mkdir as mkdir8, open as open2, readFile as readFile13, rm as rm9, stat as stat5, writeFile as writeFile5 } from "fs/promises";
+import { join as join27 } from "path";
 import { setTimeout as delay2 } from "timers/promises";
 var detached = (args, cwd) => {
   const bin = process.argv[1];
@@ -8155,11 +8450,11 @@ var detached = (args, cwd) => {
   child.on("error", () => void 0);
   child.unref();
 };
-var failureFile = () => join26(configDir(), "pulse.json");
+var failureFile = () => join27(configDir(), "pulse.json");
 async function recordFailure(reason3) {
   try {
-    await mkdir7(configDir(), { recursive: true, mode: 448 });
-    await writeFile4(
+    await mkdir8(configDir(), { recursive: true, mode: 448 });
+    await writeFile5(
       failureFile(),
       `${JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), reason: reason3 })}
 `
@@ -8169,8 +8464,8 @@ async function recordFailure(reason3) {
 }
 async function takeFailure() {
   try {
-    const data = JSON.parse(await readFile12(failureFile(), "utf8"));
-    await rm8(failureFile(), { force: true });
+    const data = JSON.parse(await readFile13(failureFile(), "utf8"));
+    await rm9(failureFile(), { force: true });
     const reason3 = data !== null && typeof data === "object" ? data["reason"] : void 0;
     return typeof reason3 === "string" && reason3 !== "" ? reason3 : null;
   } catch {
@@ -8179,8 +8474,8 @@ async function takeFailure() {
 }
 var PULSE_LOCK_STALE_MS = 15 * 6e4;
 async function oneSyncAtATime(key, work, options = {}) {
-  await mkdir7(configDir(), { recursive: true, mode: 448 });
-  const file = join26(configDir(), `pulse-${key}.lock`);
+  await mkdir8(configDir(), { recursive: true, mode: 448 });
+  const file = join27(configDir(), `pulse-${key}.lock`);
   for (; ; ) {
     try {
       const handle = await open2(file, "wx");
@@ -8192,7 +8487,7 @@ async function oneSyncAtATime(key, work, options = {}) {
         (s) => Date.now() - s.mtimeMs,
         () => 0
       );
-      if (age > PULSE_LOCK_STALE_MS) await rm8(file, { force: true });
+      if (age > PULSE_LOCK_STALE_MS) await rm9(file, { force: true });
       else if (options.wait !== true) return false;
       else await (options.sleep ?? ((ms) => delay2(ms)))(1e3);
     }
@@ -8201,7 +8496,7 @@ async function oneSyncAtATime(key, work, options = {}) {
     await work();
     return true;
   } finally {
-    await rm8(file, { force: true });
+    await rm9(file, { force: true });
   }
 }
 
@@ -8232,9 +8527,6 @@ function cwdOf(input, env) {
   return env["CLAUDE_PROJECT_DIR"] ?? process.cwd();
 }
 var toPosix2 = (p) => p.split(sep5).join(posix8.sep);
-function count(n, [one, many]) {
-  return `${n} ${n === 1 ? one : many}`;
-}
 async function safetyNet(ws, manifest) {
   const notes = [];
   const drift = await pinDrift(ws.rnessDir);
@@ -8576,12 +8868,12 @@ async function mcpCommand(opts, io = {
 }
 
 // src/commands/pulse.ts
-import { readFile as readFile14, readdir as readdir5 } from "fs/promises";
-import { join as join27 } from "path";
+import { readFile as readFile15, readdir as readdir5 } from "fs/promises";
+import { join as join28 } from "path";
 import { setTimeout as delay3 } from "timers/promises";
 
 // src/pulse/opened.ts
-import { mkdir as mkdir8, readFile as readFile13, rename as rename3, rm as rm9, writeFile as writeFile5 } from "fs/promises";
+import { mkdir as mkdir9, readFile as readFile14, rename as rename3, rm as rm10, writeFile as writeFile6 } from "fs/promises";
 import { dirname as dirname9 } from "path";
 var NAME2 = "rness/opened";
 function openedFile(rnessDir) {
@@ -8593,7 +8885,7 @@ async function readOpened(file) {
   if (file === null) return opened;
   let data;
   try {
-    data = JSON.parse(await readFile13(file, "utf8"));
+    data = JSON.parse(await readFile14(file, "utf8"));
   } catch {
     return opened;
   }
@@ -8608,13 +8900,13 @@ async function writeOpened(file, opened) {
   if (file === null) return;
   try {
     if (opened.size === 0) {
-      await rm9(file, { force: true });
+      await rm10(file, { force: true });
       return;
     }
     const entries = [...opened].sort(([a], [b]) => a - b);
-    await mkdir8(dirname9(file), { recursive: true });
+    await mkdir9(dirname9(file), { recursive: true });
     const temporary = `${file}.${process.pid}`;
-    await writeFile5(
+    await writeFile6(
       temporary,
       `${JSON.stringify(Object.fromEntries(entries), null, 2)}
 `
@@ -8708,7 +9000,7 @@ async function scopeOf(c, name, tabs, owners) {
     label: labelOf(name),
     rows: []
   };
-  const dir = join27(c.rnessDir, name);
+  const dir = join28(c.rnessDir, name);
   const shape = await readShape(c.rnessDir, name);
   const fronts = new Map(
     (await collectMarkdown(dir)).map((item) => [
@@ -8754,7 +9046,7 @@ async function working(ui, doing, count3, work) {
 async function filesOf2(rnessDir) {
   const files = /* @__PURE__ */ new Set();
   const walk = async (rel) => {
-    const dir = rel === "" ? rnessDir : join27(rnessDir, ...rel.split("/"));
+    const dir = rel === "" ? rnessDir : join28(rnessDir, ...rel.split("/"));
     for (const e of await readdir5(dir, { withFileTypes: true })) {
       const path = rel === "" ? e.name : `${rel}/${e.name}`;
       if (e.isDirectory()) {
@@ -8866,7 +9158,7 @@ async function syncBoard(c, board, ui, sayLayout, scope) {
         w.path,
         issueBody({
           path: w.path,
-          text: await readFile14(join27(c.rnessDir, ...w.path.split("/")), "utf8"),
+          text: await readFile15(join28(c.rnessDir, ...w.path.split("/")), "utf8"),
           org: c.org,
           numbers,
           files
@@ -9358,6 +9650,14 @@ function buildProgram(state) {
   ).argument("[tab]", "open on this tab: adr, specs, plans, \u2026").addOption(new Option("--cwd <dir>").hideHelp()).action(async (tab, opts) => {
     state.code = await statusCommand(tab, opts);
   });
+  const doc = program.command("doc").description("Documents of the workspace: doc new <collection>");
+  doc.command("new").description(
+    "Write the next numbered document of a collection (adr, specs, plans) and print its path"
+  ).argument("<collection>", "adr, specs or plans").option("--title <text>", "the title; the file name takes its slug").addOption(new Option("--cwd <dir>").hideHelp()).action(
+    async (collection, opts) => {
+      state.code = await docNewCommand(collection, opts);
+    }
+  );
   program.command("validate").description(
     "Check the .rness/ tree against the contract and every generated block"
   ).addOption(new Option("--cwd <dir>").hideHelp()).action(async (opts) => {
@@ -9618,4 +9918,4 @@ export {
   OWN_COMMANDS,
   catchUp
 };
-//# sourceMappingURL=chunk-MMPMXYZU.js.map
+//# sourceMappingURL=chunk-JHU2G7K7.js.map