@intentius/chant 0.101.0 → 0.104.0

package/src/cli/handlers/scenario.ts

@@ -15,7 +15,7 @@ import { collectEffectReceipts, isEffectReceipt, type EffectReceiptDeclaration }
 import { evaluateScenario, type ScenarioBehaviourFixture, type ScenarioVerdict } from "../../lifecycle/scenario-eval";
 import { validateBehaviourResult } from "../../behaviour-delta";
 import { collectScenarios, type ScenarioDeclaration, type ScenarioGiven } from "../../lifecycle/scenario";
-import { isResourceDeclarable } from "../../declarable";
+import { isObservableDeclarable } from "../../declarable";
 import { loadChantConfig } from "../../config";
 import { unknownEnvError } from "../../env";
 import { collectBuildRootContributors } from "../plugins";
@@ -281,7 +281,7 @@ async function evaluateOneScenario(
     // and observed like any resource (#1832) — it joins the declared axis so
     // its lexicon's fixture data can confirm presence, absence, or a hole,
     // the same as `runLifecyclePlan` (lifecycle.ts:1184).
-    if (!isResourceDeclarable(entity) && !isEffectReceipt(entity)) continue;
+    if (!isObservableDeclarable(entity) && !isEffectReceipt(entity)) continue;
     if (!declaredByLexicon.has(entity.lexicon)) declaredByLexicon.set(entity.lexicon, new Set());
     declaredByLexicon.get(entity.lexicon)!.add(name);
   }

package/src/cli/main.test.ts

@@ -255,6 +255,23 @@ describe("parseArgs", () => {
     expect(result.extraPositional2).toBe(undefined);
   });
 
+  test("positionals keeps every positional after the command, for workspace box listing set <member> (#3308)", () => {
+    const result = parseArgs(["workspace", "box", "listing", "set", "app", "--from", "-", "--cover", "c.png", "--cover-path", "app/c.png"]);
+    expect(result.positionals).toEqual(["box", "listing", "set", "app"]);
+    expect(result).toMatchObject({ path: "box", extraPositional: "listing", migrateFrom: "-", cover: "c.png", coverPath: "app/c.png" });
+    expect(() => parseArgs(["workspace", "box", "listing", "set", "app", "--cover"])).toThrow(/--cover needs/);
+  });
+
+  test("workspace wip takes --label and --branch, with its verb and snapshot as positionals (#3172)", () => {
+    const save = parseArgs(["workspace", "wip", "save", "--label", "turn:3", "--by", "github:alex", "--json"]);
+    expect(save).toMatchObject({ positionals: ["wip", "save"], label: "turn:3", by: "github:alex", json: true });
+    expect(resolveCommand(save, commandRegistry)?.def.name).toBe("workspace wip");
+    expect(parseArgs(["workspace", "wip", "restore", "abc123"]).positionals).toEqual(["wip", "restore", "abc123"]);
+    expect(parseArgs(["workspace", "wip", "--branch", "chant/work/W-1", "--json"])).toMatchObject({ branch: "chant/work/W-1", json: true });
+    expect(() => parseArgs(["workspace", "wip", "save", "--label"])).toThrow(/--label needs/);
+    expect(() => parseArgs(["workspace", "wip", "--branch"])).toThrow(/--branch needs/);
+  });
+
   // ── components release/status flags (#568) ──────────────────────────────
 
   test("parses --component, --digest, --git-sha, --run-id, --actor for components release", () => {
@@ -751,6 +768,7 @@ describe("workspace init and ls (#2534)", () => {
       "workspace adopt-lineage",
       "workspace agent",
       "workspace audit",
+      "workspace box",
       "workspace build",
       "workspace check",
       "workspace evidence",
@@ -761,17 +779,20 @@ describe("workspace init and ls (#2534)", () => {
       "workspace init",
       "workspace lineage",
       "workspace lint",
+      "workspace lock",
       "workspace ls",
       "workspace member-run",
       "workspace patch",
       "workspace pin",
       "workspace points",
       "workspace records",
+      "workspace runs",
       "workspace signers",
       "workspace status",
       "workspace upgrade",
       "workspace verify",
       "workspace versions",
+      "workspace wip",
       "workspace work",
     ]);
   });

package/src/cli/main.ts

@@ -102,6 +102,7 @@ const BOOLEAN_FLAGS = new Set([
   "--durable-requests",
   "--skip-mcp",
   "--current",
+  "--uncommitted",
   "--allow-code",
   "--root-only",
   "--generated",
@@ -227,6 +228,12 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant import --kustomize <dir>` (#1548): render the overlay, import
       // the output through the k8s template parser.
       result.kustomize = args[++i];
+    } else if (arg === "--parser-option") {
+      // `chant import --parser-option key[=value]` (#2994), repeatable: checked
+      // against the lexicon's parserOptions() by the import command.
+      const v = args[++i];
+      if (!v || v.startsWith("-")) throw new Error("--parser-option needs key or key=value: --parser-option acceptLossyV1");
+      (result.parserOption ??= []).push(v);
     } else if (arg === "--type") {
       result.selectType = args[++i];
     } else if (arg === "--name") {
@@ -340,6 +347,30 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.fromAffected = args[++i];
     } else if (arg === "--gate") {
       result.gate = args[++i];
+    } else if (arg === "--wave-gate") {
+      result.waveGate = args[++i];
+      if (!result.waveGate || result.waveGate.startsWith("-")) throw new Error("--wave-gate needs a gate name: --wave-gate <name>");
+    } else if (arg === "--wave") {
+      const raw = args[++i];
+      const wave = Number(raw);
+      if (!Number.isInteger(wave) || wave < 1) throw new Error(`--wave needs a wave number from 1: got "${raw ?? ""}"`);
+      result.wave = wave;
+    } else if (arg === "--canary") {
+      const raw = args[++i];
+      if (!raw || raw.startsWith("-")) throw new Error("--canary needs a component name: --canary <name>[,<name>...]");
+      (result.canary ??= []).push(...raw.split(",").map((n) => n.trim()).filter(Boolean));
+    } else if (arg === "--pr") {
+      const raw = args[++i];
+      const pr = Number(raw);
+      if (!Number.isInteger(pr) || pr < 1) throw new Error(`--pr needs a pull or merge request number: got "${raw ?? ""}"`);
+      result.pr = pr;
+    } else if (arg === "--forge") {
+      result.forge = args[++i];
+      if (!result.forge || result.forge.startsWith("-")) throw new Error("--forge needs a forge: --forge github|gitlab|forgejo");
+    } else if (arg === "--require-review") {
+      result.requireReview = true;
+    } else if (arg === "--pr-loop") {
+      result.prLoop = true;
     } else if (arg === "--resume") {
       result.resume = args[++i];
     } else if (arg === "--local") {
@@ -377,11 +408,14 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant workspace graph --composites` (#2662)
       result.composites = true;
     } else if (arg === "--intent") {
-      // `chant workspace graph --intent <path[:start-end]>` (#2651), or `--intent --record <id>` with no region.
+      // `chant workspace graph --intent <path[:start-end]|path#symbol>` (#2651), or `--intent --record <id>` with no region.
       const value = args[i + 1];
       if (value !== undefined && !value.startsWith("-")) result.intent = args[++i];
       else if (args.includes("--record")) result.intent = "";
-      else throw new Error("--intent needs a region: --intent <path[:start-end]>, or --intent --record <id>");
+      else throw new Error("--intent needs a region: --intent <path[:start-end]|path#symbol>, or --intent --record <id>");
+    } else if (arg === "--follow-squash") {
+      // `chant workspace graph --intent ... --follow-squash` and `chant workspace runs --follow-squash` (#3035)
+      result.followSquash = true;
     } else if (arg === "--record") {
       // `chant workspace graph --intent --record <id>`
       result.record = args[++i];
@@ -409,10 +443,36 @@ export function parseArgs(args: string[]): ParsedArgs {
       if (!result.severity || result.severity.startsWith("-")) throw new Error("--severity needs off, warn or fail");
     } else if (arg === "--current") {
       result.current = true;
+    } else if (arg === "--uncommitted") {
+      // `chant workspace records --uncommitted` (#3160)
+      result.uncommitted = true;
     } else if (arg === "--set") {
       // `chant workspace records amend <id> --set <file|->` (#2670)
       result.set = args[++i];
       if (!result.set || (result.set.startsWith("-") && result.set !== "-")) throw new Error("--set needs a JSON file, or - for standard input: --set <file|->");
+    } else if (arg === "--cover") {
+      // `chant workspace box listing set <member> --cover <image>` (#3308)
+      result.cover = args[++i];
+      if (!result.cover || result.cover.startsWith("-")) throw new Error("--cover needs a PNG, JPEG or WebP file: --cover <image>");
+    } else if (arg === "--cover-path") {
+      // `chant workspace box listing set <member> --cover <image> --cover-path <path>` (#3308)
+      result.coverPath = args[++i];
+      if (!result.coverPath || result.coverPath.startsWith("-")) throw new Error("--cover-path needs a path from the workspace root: --cover-path <path>");
+    } else if (arg === "--records") {
+      // `chant workspace box publish <member> --records` (#3165): the records kept uncommitted, not a work item.
+      result.records = true;
+    } else if (arg === "--expect") {
+      // `chant workspace records amend|review|close <id> --expect <digest>` (#3173): the record's digest the caller last read.
+      result.expect = args[++i];
+      if (!result.expect || result.expect.startsWith("-")) throw new Error("--expect needs the record's digest, as records --json prints it: --expect <digest>");
+    } else if (arg === "--label") {
+      // `chant workspace wip save --label <text>` (#3172)
+      result.label = args[++i];
+      if (!result.label || result.label.startsWith("-")) throw new Error("--label needs the snapshot's name, such as a turn id: --label <text>");
+    } else if (arg === "--branch") {
+      // `chant workspace wip --branch <branch>` (#3172)
+      result.branch = args[++i];
+      if (!result.branch || result.branch.startsWith("-")) throw new Error("--branch needs a branch name: --branch <branch>");
     } else if (arg === "--verdict") {
       // `chant workspace records review <id> --verdict agree|dissent|abstain` (#2670)
       result.verdict = args[++i];
@@ -427,9 +487,13 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant workspace points --open` (#2739): only the questions still open.
       result.open = true;
     } else if (arg === "--inputs") {
-      // `chant workspace points ask <point> --inputs <file|->` (#2739)
+      // `chant workspace points ask <point> --inputs <file|-|json>` (#2739; JSON itself, #3403)
       result.inputs = args[++i];
-      if (!result.inputs || (result.inputs.startsWith("-") && result.inputs !== "-")) throw new Error("--inputs needs a JSON file, or - for standard input: --inputs <file|->");
+      if (!result.inputs || (result.inputs.startsWith("-") && result.inputs !== "-")) throw new Error("--inputs needs a JSON file, - for standard input, or the JSON itself: --inputs <file|-|json>");
+    } else if (arg === "--candidates") {
+      // `chant workspace points ask <point> --candidates <file|-|json>` (#3403): an ad-hoc point's question and candidates.
+      result.candidates = args[++i];
+      if (!result.candidates || (result.candidates.startsWith("-") && result.candidates !== "-")) throw new Error("--candidates needs a JSON file, - for standard input, or the JSON itself: --candidates <file|-|json>");
     } else if (arg === "--response") {
       // `chant workspace points ask <point> --response <file>` (#2739): a POST /v1/systemone response the caller got.
       result.response = args[++i];
@@ -445,6 +509,7 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--sign") {
       // `chant workspace records review <id> --sign [<key file>]` (#2687): seal the verdict.
       // `records new` and `records amend` take it too, to seal the record's author (#2688).
+      // `chant approve <op> <gate> --sign [<key file>]` seals a gate approval (#3163).
       // With no key file, git's user.signingkey, as `git commit -S` reads it.
       const next = args[i + 1];
       result.sign = next !== undefined && !next.startsWith("-") ? args[++i] : true;
@@ -497,6 +562,11 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.actor = args[++i];
     } else if (arg === "--approver") {
       result.approver = args[++i];
+    } else if (arg === "--relayed-by") {
+      // `chant approve <op> <gate> --relayed-by <principal>` and `workspace points answer <id> --relayed-by <principal>` (#3402):
+      // who carried the approval or answer to chant for the person it names.
+      result.relayedBy = args[++i];
+      if (!result.relayedBy || result.relayedBy.startsWith("-")) throw new Error("--relayed-by needs the principal that relayed it: --relayed-by <principal>");
     } else if (arg === "--on") {
       // `chant run ... --on <lexicon>` (#2121) — which runtime hosts the run.
       result.on = args[++i];
@@ -566,6 +636,16 @@ export function parseArgs(args: string[]): ParsedArgs {
       const value = args[++i];
       if (!value || value.startsWith("-")) throw new Error(`${arg} needs a value: ${arg} <${arg.slice(2)}>`);
       result[arg.slice(2) as "holder" | "ttl" | "token" | "outcome"] = value;
+    } else if (arg === "--signer") {
+      // `chant workspace runs statement <id> --signer <principal>` (#3192): the runner principal that will sign.
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error("--signer needs a principal: --signer <principal>");
+      result.signer = value;
+    } else if (arg === "--unit" || arg === "--decision") {
+      // `chant workspace runs --unit <id> | --decision <id>` (#3033): the runs on one work item, or for one decision.
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error(`${arg} needs an id: ${arg} <id>`);
+      result[arg.slice(2) as "unit" | "decision"] = value;
     } else if (arg === "--note") {
       result.note = args[++i];
     } else if (arg === "--expire") {
@@ -643,6 +723,7 @@ export function parseArgs(args: string[]): ParsedArgs {
       // flags" isn't something this loop can name in isolation.
       throw new Error(`Unknown flag: ${arg}\nRun "chant --help" to see supported flags.`);
     } else if (!arg.startsWith("-")) {
+      if (result.command) (result.positionals ??= []).push(arg);
       if (!result.command) {
         result.command = arg;
       } else if (result.path === ".") {
@@ -761,6 +842,14 @@ Commands:
                         (--json)          its target, stage (planned/emitted/bridged/
                                           applied) and path. Read-only.
 
+Change sets:
+  change-set summary <file>  The grouped plan summary of a change-set
+                        [--format text|json|markdown]  document: members taking
+                        [--limit <chars>]  the same change grouped, every destroy,
+                                          replacement, failure and hole named.
+                                          markdown fits an MR/PR note of --limit
+                                          characters (default 65536). Read-only.
+
 Ops:
   run <name>            Run an Op on the resolved runtime (--on; local by default)
                         [--work <id>] [--holder <name>]: the work item an Op
@@ -818,7 +907,13 @@ Ops:
                         and defaults to the PR/MR of the surrounding CI job.
                         The next "chant run <op>" walks through the gate.
                         --expire clears a pending fact without approving it,
-                        so the gate is re-decided from scratch next run
+                        so the gate is re-decided from scratch next run.
+                        --sign [<key file>] seals the approval with an ssh
+                        key; a gate the workspace's identity.gates names
+                        counts only an approval sealed by a key the signers
+                        file at base lists for --actor. --relayed-by
+                        <principal> records who carried the approval to chant
+                        for --actor (a follower, a bot); --sign covers it
 
   graph                 Show Op dependency graph (--stacks for cross-stack order,
                         --format ir|mermaid|dot|layout for the lint-gated graph IR,
@@ -858,7 +953,7 @@ Workspace (level 1, #2524):
                         beside it and marks the members whose digests differ.
                         Read only; never fetches. --json prints the
                         read-contract document
-  workspace records [--kind <kind file>] [--current] [--at <rev>] [--base <rev>] [--require attested] [--json]
+  workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--json]
                         Without --kind, every record kind the declaration
                         names. Read the records a record kind locates, validated
                         against its schema, with reason codes for invalid
@@ -868,7 +963,10 @@ Workspace (level 1, #2524):
                         the signers at --base (default: the target branch);
                         --require attested exits 2 if any record is not
                         attested. A pinned file that changed is a warning,
-                        asset-drift or asset-missing
+                        asset-drift or asset-missing. In the working tree,
+                        each record says whether it is committed, modified
+                        or new against HEAD, with the branch and base;
+                        --uncommitted lists only the modified and new ones
   workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json]
                         What changed in the records between <rev> and --at
                         (default: the working tree): new and removed records,
@@ -886,7 +984,7 @@ Workspace (level 1, #2524):
                         the fields hold none. --sign seals the record's author
                         (decided_by for decisions) with an ssh key. Prints
                         {path, id} as JSON and never commits
-  workspace records amend <id> [--kind <kind file>] --set <file|-> [--sign [<key file>]] [--dry-run]
+  workspace records amend <id> [--kind <kind file>] --set <file|-> [--expect <digest>] [--sign [<key file>]] [--dry-run]
                         Set top-level fields of one record. A closed record
                         never changes, and an approved one changes only its
                         state (upward), pins and reviews; anything else is
@@ -895,22 +993,31 @@ Workspace (level 1, #2524):
                         decisions) is refused with ratify-quorum-not-met
                         until its quorum is met. --sign seals the author
                         again; without it an amendment removes the author
-                        seal and says so. Prints {path, id, changed}
-  workspace records review <id> [--kind <kind file>] --verdict agree|dissent|abstain --by <principal> [--note <text>] [--session <id>] [--sign [<key file>]] [--dry-run]
+                        seal and says so. --expect refuses the write with
+                        record-conflict when the record's digest has moved
+                        on. Prints {path, id, changed, digest}
+  workspace records review <id> [--kind <kind file>] --verdict agree|dissent|abstain --by <principal> [--note <text>] [--session <id>] [--expect <digest>] [--sign [<key file>]] [--dry-run]
                         Append a review to one record, dated and bound to
                         the digest of the record text. A dissent needs
                         --note. --sign seals it with an ssh key (git's
                         user.signingkey without a file); under a signers
                         file at base only a sealed verdict counts. With
                         --session, the session must be open, and the verdict
-                        is appended to its verdicts too. Prints
-                        {path, id, review}
-  workspace records close <session id> [--kind <session kind file>] [--dry-run]
+                        is appended to its verdicts too. --expect refuses a
+                        verdict on a record that moved on. Prints
+                        {path, id, review, digest}
+  workspace records close <session id> [--kind <session kind file>] [--expect <digest>] [--dry-run]
                         Close an open review session: its state, close time,
                         closing commit and seal, in one write. Without
                         --kind, the one session kind the declaration names.
                         Prints {path, id, changed, seal, closedRev}
-  workspace work claim|renew|release <id> --holder <name> [--kind <kind file>] [--ttl <seconds|duration>] [--token <token>] [--outcome <text>] [--note <text>] [--json]
+                        Every working-tree write holds the working tree's
+                        write lock (CHANT_WRITE_LOCK_WAIT_MS, default 15s)
+  workspace lock [acquire --holder <name> [--ttl <duration>] | release --token <token>] [--json]
+                        Who holds the working tree's write lock; take it for
+                        a batch of writes across chant calls, each run with
+                        CHANT_WRITE_LOCK=<token>, and give it back
+  workspace work claim|renew|release <id> --holder <name> [--kind <kind file>] [--ttl <seconds|duration>] [--token <token>] [--outcome <outcome>] [--note <text>] [--json]
                         Take, heartbeat or give back the lease on a work item:
                         refs/chant/lease/work/<id>, a compare-and-set ref with a
                         fencing token and an expiry, pushed to the remote so
@@ -921,18 +1028,89 @@ Workspace (level 1, #2524):
                         A work item's lease history: each claim with its token
                         and holder, and how it ended, released with an outcome
                         or never released (expired or lost). Read-only
+  workspace work evidence <id> --holder <name> --token <token> --from <file|-> [--kind <kind file>]
+                        Attach evidence for one acceptance criterion under the
+                        lease you hold: the entry (criterion, result, title,
+                        a url or a path pinned by hash) is appended to the
+                        item's pins through records amend. Prints the
+                        work-evidence document and never commits
+  workspace runs [--unit <id>] [--decision <id>] [--by <principal>] [--since <rev>] [--follow-squash] [--json]
+                        The agent runs in the run ledger on chant/lifecycle, each
+                        with its model, tokens, cost and the commits it made,
+                        and totals per work item, decision and principal; a run
+                        that reports no cost is listed as unpriced, never zero.
+                        Read-only, never fetches; --follow-squash joins each
+                        squash merge to its pull request's runs, fetching a
+                        missing refs/pull/<n>/head from origin
+  workspace runs start --from <file|->
+                        Record that an agent run started: who it worked for,
+                        its harness, model, work item and lease. Prints the run
+                        and its Chant-Run trailer. chant never starts a run
+  workspace runs end <run id> [--from <file|->]
+                        Record how a started run ended: its outcome, tokens,
+                        cost and price source, the transcript pinned by hash,
+                        and the commits it made
+  workspace runs record --from <file|->
+                        Record a finished run, its start and end in one write
+  workspace runs sign <run id> (--key <runner.pem> | --envelope <file|->) [--base <rev>]
+                        Store a DSSE statement over an ended run (its record's
+                        hash, work item, harness, model and commits), signed
+                        with a runner or steward key .chant/trust.json lists
+                        at base, or signed elsewhere and checked here
+  workspace runs statement <run id> --signer <principal>
+                        Print the statement for a signer whose key is
+                        elsewhere, such as a lobby, with the payload to sign
+  workspace runs verify [<run id>] [--require signed] [--base <rev>] [--json]
+                        Judge each run's stored statements against the runner
+                        keys at base. Reports only, unless --require signed
+  workspace box listing set <member> [--from <file|->] [--cover <image> [--cover-path <path>]] [--by <principal>] [--dry-run]
+                        Change a box's listing (published, title, line, cover)
+                        in the declaration, in place, keeping its formatting
+                        and comments; --cover copies a PNG, JPEG or WebP into
+                        the repository. Judged by the write scope at base.
+                        Prints the box-listing-write document; never commits
+  workspace box publish <member> (<item> | --records) [--by <principal>] [--head <owner/name>] [--dry-run]
+                        Publish a built work item, or the records kept
+                        uncommitted, through the publisher the box block names:
+                        run with a JSON request on stdin, its answer checked
+                        and its commit held to the apply record (ws-088).
+                        Prints the box-publish document; chant itself never
+                        commits, pushes or calls a forge
+  workspace wip [--branch <branch>] [--json]
+                        List the work-in-progress snapshots under
+                        refs/chant/wip/<branch>, newest first, and how far each
+                        ref the box's replicate policy names is from its remote.
+                        Reads locally; never fetches (#3172)
+  workspace wip save [--label <text>] [--by <principal>]
+                        Snapshot the whole working tree, uncommitted records
+                        included, onto refs/chant/wip/<branch> without touching
+                        the index or the branch; pushes when the policy says so
+  workspace wip restore [<snapshot>] [--by <principal>]
+                        Put the working tree back as the snapshot (the branch's
+                        latest by default) holds it, after a snapshot of how it
+                        is now; HEAD never moves
+  workspace wip push    Push the refs the box's replicate policy names to its
+                        remote, never forced, for the host's schedule
+  workspace wip fetch   On a replacement box, bring back what was replicated:
+                        create or fast-forward the local refs, then wip restore
   workspace points [--open] [--kind <kind file>] [--at <rev>] [--json]
                         List the decision points the declared answer kinds'
                         points files declare, and the questions asked of them;
                         --open keeps the escalated and proposed ones (ws-058)
-  workspace points ask <point> --inputs <file|-> [--response <file>] [--subject <id>] [--kind <kind file>] [--dry-run]
+  workspace points ask <point> --inputs <file|-|json> [--candidates <file|-|json>] [--response <file>] [--subject <id>] [--kind <kind file>] [--dry-run]
                         Ask a point's table, model and quorum deciders and
                         record the answer: proposed from a model, escalated to
                         people below its threshold. --response is a POST
-                        /v1/systemone response the caller got; chant calls no model
-  workspace points answer <id> --answer <value> --by <name>... [--kind <kind file>] [--dry-run]
+                        /v1/systemone response the caller got; chant calls no model.
+                        --candidates gives an ad-hoc point's question and
+                        candidates, { question, criteria }
+  workspace points answer <id> --answer <value> --by <name>... [--note <text>] [--relayed-by <principal>] [--kind <kind file>] [--dry-run]
                         Record people's answer to an open question, or confirm
-                        a model's proposal, once the point's quorum is met
+                        a model's proposal, once the point's quorum is met,
+                        with their note and who relayed it
+  workspace points retract <id> --by <name>... [--note <text>] [--kind <kind file>] [--dry-run]
+                        Take an answer back: the question is open for people
+                        again, and the answer stays in its retractions
   workspace pin <path> [--json]
                         Print the integrity value that pins the plugin at
                         <path>, to put in a path pin of chant.workspace.json.
@@ -942,13 +1120,14 @@ Workspace (level 1, #2524):
                         member it is bound to, the record kinds and verbs its
                         write scope allows, and the spec records --current
                         prints. Without a name, the session CHANT_AGENT names
-  workspace verify [--base <rev>] [--head <rev>] [--require attested]
+  workspace verify [--base <rev>] [--head <rev>] [--require attested | attested-runs]
                         Check the commits in base..head against the signers
                         and roles read from base. A change to the signers file
                         or .chant/trust.json needs a signature by a signer
                         trusted at base, and a new signer set needs a
-                        threshold of the old one. Does nothing without a
-                        signers file
+                        threshold of the old one. A commit an agent run made
+                        is attested by the run's signed statement; with
+                        attested-runs, only those commits must be
   workspace signers [--json] [rotate [--threshold <n>] | sign --key <file>]
                         Show the signer history at base, or propose the next
                         signer set and sign it with a current signer's key
@@ -1056,12 +1235,14 @@ Workspace (level 1, #2524):
                         Each composite instance the members declare, with the
                         components whose contract can deploy it; an instance
                         with none lists an empty set
-  workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]
+  workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]
                         The intent graph over one region: the commits that
                         touched it, the decisions whose constrains cover it,
                         the artifacts they pin, and findings with closed codes.
-                        Without --kind, every record kind the declaration names
-  workspace graph --intent --record <id> [--at <rev>] [--kind <kind file>...] [--json]
+                        Without --kind, every record kind the declaration names.
+                        --follow-squash follows a squash merge to its pull
+                        request's commits, fetching a missing ref from origin
+  workspace graph --intent --record <id> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]
                         One decision's intent walk over every path: and member:
                         entry it constrains: the commits in its window, each
                         own, worked, within-other or unexplained, with counts
@@ -1111,8 +1292,23 @@ Component release ledger + status:
                             (--base <ref> [--head <ref>] [--include-dependents],
                              or --from-affected <file>; --dry-run prints the
                              derivation and dispatches nothing; --gate <name>
-                             puts one approval over the whole set; --resume
-                             <file> finishes an attempt that stopped)
+                             puts one approval over the whole set;
+                             --wave-gate <name> puts one on each wave, planned
+                             when the wave is reached, with --canary <name>
+                             for wave 1 and --wave <n> for one wave per CI
+                             job; --resume <file> finishes an attempt that
+                             stopped)
+  components pr-plan       Plan the components a pull request reaches and
+                            the ones that depend on them, and write the
+                            report and note (--base <ref> --pr <n>
+                            [--forge github|gitlab|forgejo] posts them);
+                            applies nothing
+  components pr-apply      On merge: plan the same members again and apply
+                            them only if an approval stands for that digest
+                            (chant approve pr-<n> pr-apply --plan <digest>);
+                            a moved plan refuses with exit 3
+                            (--require-review: the approver must have
+                            approved the pull request on the forge)
   components release <env> Append one immutable release record
                             (--component <name> --digest <sha256:...>
                              [--git-sha <sha>] [--run-id <id>] [--actor <name>]);
@@ -1150,8 +1346,13 @@ Lexicon development:
                             --check: fail if the committed baseline drifted (never writes);
                             --run-examples: also run example build harness;
                             --pinned-digest <file>: verify spec digest before regen)
-  dev pinned-upgrade <dir> Report if a pinned lexicon (k8s|gcp|docker|gitlab) has a newer
-                           upstream release; dry-run bump + regen + surface-diff, then revert
+  dev pinned-upgrade <dir> [pin]
+                           Report if a lexicon that declares upstreamPin (k8s, k3s, gcp, docker,
+                           gitlab, cedar, sql) has a newer upstream release; dry-run bump + regen +
+                           surface-diff, then revert. A pin that moves with other constants (sql's
+                           image digest) is reported with how to move it, not edited. A lexicon
+                           with several pins (sql: clickhouse, postgres-14 .. postgres-18) gets one
+                           report per pin; name a pin to check only that one
                            (reports only; --force bypasses the spec cache, -f json for JSON)
   dev rolling-upgrade <dir>  Report rolling-spec drift (aws, azure, github): regen from
                            latest, diff surface vs committed baseline, print delta + PR
@@ -1194,8 +1395,9 @@ Options:
   -h, --help            Show this help message
   -V, --version         Print the installed chant's version
   --on <lexicon>        Which runtime hosts the run: a configured lexicon with
-                        an opRuntime, or the built-in local runtime when
-                        omitted (every run subcommand; #2121)
+                        an opRuntime, or local. Omitted, run.on in
+                        chant.config.ts decides, then the built-in local
+                        runtime (every run subcommand; #2121, #2523)
   --local               Run an Op with the local in-process executor (default)
   -p, --profile <name>  Named connection profile the hosting runtime targets
                         (fountain.profiles in chant.config.ts); each runtime's
@@ -1287,6 +1489,7 @@ Examples:
   chant components export prod --component search-service -o ./dist/search-service
   chant import template.json --output ./infra/
   chant import manifest.yaml --lexicon k8s --output ./infra/
+  chant import dash.json --lexicon grafana --parser-option acceptLossyV1
   chant import --from prod --name my-bucket --output src/
   chant lint ./infra/
   chant lint ./infra/ --format sarif
@@ -1512,6 +1715,8 @@ export const commandRegistry: CommandDef[] = [
   // Status read over a tree of carve manifests (#2038): the contract a
   // renderer replaces its own walk-and-guess discovery with. Read-only.
   { name: "carve status", handler: runCarveStatus },
+  // #3188 — the grouped plan summary of a change-set document. Reads one file; imported on first use.
+  { name: "change-set summary", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/change-set")).runChangeSetSummary(ctx) },
   { name: "init", handler: runInit, runsNoConfig: true },
   { name: "init lexicon", handler: runInitLexicon },
 { name: "update", handler: runUpdate },
@@ -1552,6 +1757,8 @@ export const commandRegistry: CommandDef[] = [
   { name: "workspace ls", handler: async (ctx) => (await import("../workspace/ls")).runWorkspaceLs(ctx) },
   // #2732 — the work lease: claim, renew and release a work item.
   { name: "workspace work", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/work-cli")).runWorkspaceWork(ctx) },
+  // #3033 — the agent run record: what each run cost and which commits it made. chant records runs and never starts one.
+  { name: "workspace runs", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/runs-cli")).runWorkspaceRuns(ctx) },
   { name: "workspace status", handler: async (ctx) => (await import("../workspace/status")).runWorkspaceStatus(ctx) },
   { name: "workspace lineage", handler: async (ctx) => (await import("../workspace/lineage-cli")).runWorkspaceLineage(ctx) },
   { name: "workspace upgrade", handler: async (ctx) => (await import("../workspace/lineage-upgrade-cli")).runWorkspaceUpgrade(ctx) },
@@ -1576,6 +1783,12 @@ export const commandRegistry: CommandDef[] = [
   { name: "workspace graph", handler: async (ctx) => (await import("../workspace/member-commands")).runWorkspaceMembers(ctx, "graph") },
   // Each unit decides for itself whether its config is loaded (runCommandInProcess).
   { name: "workspace member-run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/member-run")).runWorkspaceMemberRun(ctx, runCommandInProcess) },
+  // #3308 — a box's listing, written through chant so a tool never edits the declaration itself (ws-074).
+  { name: "workspace box", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/box-cli")).runWorkspaceBox(ctx) },
+  // #3173 — the working tree's write lock, held across chant calls for a batch of writes (ws-089).
+  { name: "workspace lock", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/write-lock-cli")).runWorkspaceLock(ctx) },
+  // #3172 — work in progress under refs/chant/wip/<branch>, replicated under the box's policy (ws-085).
+  { name: "workspace wip", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/wip-cli")).runWorkspaceWip(ctx) },
   { name: "workspace pin", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/pin-cli")).runWorkspacePin(ctx) },
   // #2548 — an agent session's member, write scope and spec, for a session that resumes.
   { name: "workspace agent", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/agent-cli")).runWorkspaceAgent(ctx) },
@@ -1601,6 +1814,9 @@ export const commandRegistry: CommandDef[] = [
 
   // Component release ledger + status surface (#568, epic #551)
   { name: "components fan-out", requiresPlugins: true, handler: runComponentsFanOut },
+  // #3183 — the pull-request loop the generated CI runs. Imported on first use.
+  { name: "components pr-plan", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrPlan(ctx) },
+  { name: "components pr-apply", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrApply(ctx) },
   { name: "components status", requiresPlugins: true, handler: runComponentsStatus },
   { name: "components release", handler: runComponentsReleaseRecord },
   { name: "components export", handler: runComponentsExport },