@sabaiway/agent-workflow-kit 11.2.0 → 12.1.0

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "11.2.0",
+  "version": "12.1.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "11.2.0",
+  "version": "12.1.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/agents/review-lens.md

@@ -29,6 +29,7 @@ How to review:
   restatement of design intent back to the orchestrator.
 - **Respect what is already decided.** The prompt will name findings already folded and decisions
   already locked. Re-raising them is churn; checking whether the FIX is correct is real work.
+- **When the artifact is a plan, walk around every check.** For every check bullet of each governing spec, name the invariant it proves and one state that walks around it; a named state is a finding with the replacement invariant, never an added case.
 - **Accuracy over volume.** A wrong finding costs the orchestrator more than a missed one — it
   spends a verification cycle and erodes trust in the whole list. If an angle turns up nothing, say
   so in one line and move on. Never pad.

package/references/modes/bridge-settings.md

@@ -8,7 +8,7 @@ The reader + consent-gated **writer** for the **host-level** bridge settings fil
 
 | key | bridge | values | note |
 |---|---|---|---|
-| `CODEX_SERVICE_TIER` | codex | `priority` | **SPEND KNOB** — the "Fast" tier: ~1.5× token speed at a **2.5× credit rate** on gpt-5.6-sol, quality-neutral (same model). Default unset ⇒ standard tier. |
+| `CODEX_SERVICE_TIER` | codex | `priority` | **SPEND KNOB** — the "Fast" tier: "2x speed, **increased usage**" in the codex catalog's own words for gpt-6-astra (cache fetched 2026-09-05); it states no credit-rate figure; quality-neutral (same model). Default unset ⇒ standard tier. |
 | `CODEX_HARD_TIMEOUT` | codex | integer `1..86400` | hard wall-clock cap (seconds) via `timeout(1)`. |
 | `CODEX_REVIEW_MAX_TOTAL_BYTES` | codex | integer `1..100000000` | codex-review payload size above which the diff rides a temp file (never truncated). |
 | `AGY_HARD_TIMEOUT` | agy | duration `5m`/`30m`/`90s` (unit required, nonzero) | hard wall-clock cap via `timeout(1)`. |
@@ -25,7 +25,7 @@ The reader + consent-gated **writer** for the **host-level** bridge settings fil
 
 **Refusals (the guarded contract):** an **unknown key** or an **invalid / out-of-range value** → exit `2` (nothing read of the file, nothing written). A file that already carries **duplicate keys** → exit `1`, named and left **byte-untouched** (fix the duplicates by hand first — the writer never edits blindly around them). A **symlinked / non-regular / unreadable** settings file → exit `1` (refuses to write through it). `--apply` with `--dry-run`, a duplicate op for one key, or a malformed `--set` → usage exit `2`.
 
-**Spend consent (D4):** enabling `CODEX_SERVICE_TIER=priority` costs a **2.5× credit rate** — a per-host, consented act, never a default. The preview shows the caveat (from the manifest `effect`); confirm with the user before `--apply`. The tool also warns when an env var currently shadows the key you are writing (the env value wins for that session until unset).
+**Spend consent (D4):** enabling `CODEX_SERVICE_TIER=priority` costs **increased usage** (the catalog states no credit-rate figure) — a per-host, consented act, never a default. The preview shows the caveat (from the manifest `effect`); confirm with the user before `--apply`. The tool also warns when an env var currently shadows the key you are writing (the env value wins for that session until unset).
 
 Output is **English/structured** — **localize it to the user's conversational language** when you narrate.
 

package/references/modes/now.md

@@ -0,0 +1,30 @@
+### Mode: now
+
+<!-- opt-in-capability: none — an inspection surface that configures nothing -->
+
+Read-only. The single answer to where the work stands. It writes no file, cache, receipt, lock or git state; it never commits and never runs a subscription CLI.
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/now-cli.mjs --dir <project> --json`. For a direct terminal render, use `--format=plain|ansi|json`; `--json` is strict sugar for `--format=json`.
+
+Render the returned envelope compactly in the user's conversational language. Never paste the JSON and never expose an internal field name. Preserve every fact, evidence label, annotation and withheld cause while translating only the prose around source-language commands, paths and identifiers.
+
+The four blocks keep this order:
+
+1. **NOW** — every plan in flight, its derived phase, current and next step, then the tree fingerprint, clean state, review verdict lines, final run and red-proof currency. No plan and several plans are rendered states; never pick one silently.
+2. **STEPS** — every ledger row with one of `landed`, `in progress`, `pending` or `unjudged`. The rows are the steps; invent no numbering.
+3. **QUEUE** — every work-carrying row (live, parked, ambiguous) under the full line-numbered heading path it carries, with per-class counts covering every row of the bucket, terminal and record included, and names rather than ids. Only a path through `## Pending / backlog` calls its position priority; every other bucket is archive and calls it position.
+4. **CAMPAIGN** — source-size config state (`absent`, `authored`, `incomplete`, `minted`), caps, roots, recorded over-cap files and aggregate lines. An absent opt-in config is a rendered state.
+
+Evidence alone sets a ledger status: the row's path and verb, then the path fact, changed set and exclusion fact. The plan's prose never sets a status. A checked box or terminal marker is only a claim; when evidence contradicts it, print the claim beside the evidence-derived status. Keep anomaly and current red-proof annotations beside the same status too. Every status line names its evidence source.
+
+A block that cannot be derived is `WITHHELD` and prints its cause on one line. NOW has two halves, plans and tree, each independently a value or `WITHHELD`; NOW itself is `WITHHELD` only when both are. Render every other block normally.
+
+Exit codes:
+
+| Code | Meaning |
+|------|---------|
+| 0 | Anything rendered, including default states, contradictions and a WITHHELD block. |
+| 1 | Nothing rendered: every block withheld, each cause printed on stderr; the usual cause is a `--dir` that is not a git work tree. |
+| 2 | Usage: an unknown flag, an invalid or missing value, conflicting `--json` / `--format`, or `--help` combined with anything. |
+
+**Invariants:** read-only · the plan's prose never sets status · evidence is shown beside every status · compact user-language render with no JSON or internal field names · `process.exitCode`, never `process.exit()`.

package/references/scripts/spec-schema.mjs

@@ -1,13 +1,5 @@
 #!/usr/bin/env node
-// spec-schema.mjs — the ONE reader that DEFINES a well-formed spec document under docs/ai/specs/.
-//
-// Pure text in, verdict out: readSpecDocument(text, rel) never touches the filesystem and imports
-// nothing, so it seeds layout-free into any deployment. The navigator's collapse (check-docs-size.mjs)
-// and the future spec-check read through THIS module — "malformed" has one definition, never two.
-// `rel` is the path INSIDE docs/ai/specs/ (the store root navigator is `index.md`).
-//
-// SPEC_SCHEMA carries the frozen values; the engine canon (references/specs.md) is pinned against it.
-// A refusal names exactly one rule id per defect, so a fixture corpus can be read rule by rule.
+// Canon: the methodology engine's references/specs.md (frozen schema, refusals table).
 
 export const SPEC_SCHEMA = Object.freeze({
   storePrefix: 'docs/ai/specs/',
@@ -34,17 +26,25 @@ export const SPEC_SCHEMA = Object.freeze({
   rootOwnedKeys: Object.freeze(['status', 'revision']),
   rootOwnedSections: Object.freeze(['## Scenarios', '## Out of scope', '## Module', '## Parts']),
   scenarioGrammar: '- S<N> <name> :: <repo-relative test path> :: spec:<slug>/S<N>  |  - S<N> <name> :: unbound',
+  openList: Object.freeze({
+    checkVerbs: Object.freeze(['refuse', 'refusal', 'REFUSE', 'REFUSAL']),
+    enumerationForms: Object.freeze([Object.freeze([',', ' or ']), Object.freeze([' · '])]),
+    closureTokens: Object.freeze([
+      'only if', 'only when', 'the only', 'everything else', 'anything else', 'nothing else',
+      'every other', 'any other', 'otherwise', 'exactly', 'one of', 'closed',
+    ]),
+    emphaticToken: 'ONLY',
+  }),
   rules: Object.freeze([
     'frontmatter', 'frontmatter-key', 'substrate-key', 'type', 'kind', 'maxlines', 'status', 'revision',
     'root-owns', 'slug', 'kind-path', 'root-uplink', 'title', 'section-missing', 'section-order',
-    'section-forbidden', 'fence', 'children-link', 'children-duplicate', 'fan-out', 'scenario-line',
+    'section-forbidden', 'fence', 'open-list', 'children-link', 'children-duplicate', 'fan-out', 'scenario-line',
     'scenario-number', 'scenario-marker', 'scenario-path', 'scenarios-empty', 'out-of-scope', 'module-line', 'module-empty',
     'module-traversal', 'module-absolute', 'module-backslash', 'module-glob', 'module-mix', 'parts',
   ]),
 });
 
-// The descriptor check-docs-size.mjs joins to its ADR group: rows under `prefix` whose reader verdict
-// is clean collapse into ONE navigator row linking `navPath`; a row with reader errors stays visible.
+// Consumer contract: scripts/check-docs-size.mjs.
 export const SPECS_COLLAPSE = Object.freeze({
   prefix: SPEC_SCHEMA.storePrefix,
   navPath: `${SPEC_SCHEMA.storePrefix}${SPEC_SCHEMA.navigatorFile}`,
@@ -72,8 +72,6 @@ const FORBIDDEN_SECTIONS = Object.freeze({
 
 const KNOWN_KEYS = Object.freeze([...SPEC_SCHEMA.substrateKeys, 'kind', ...SPEC_SCHEMA.rootOwnedKeys]);
 
-// The frontmatter is a closed key set: an unknown key, a repeated key or a line that is not
-// `key: value` is a defect (`frontmatter-key`), never silently dropped or last-one-wins.
 const parseFrontmatter = (text) => {
   const match = text.match(FRONTMATTER_RE);
   if (!match) return null;
@@ -91,10 +89,6 @@ const parseFrontmatter = (text) => {
 
 const FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
 
-// The body as { title, sections: [{ heading, lines }], preamble, fenced } — the title is the FIRST
-// `# ` line, every `## ` line opens a section, the lines before the first section are the preamble.
-// The reader parses NO markdown code: a fence line is recorded (the `fence` refusal) rather than
-// modelled, so a spec carries no code sample and no line is ever ambiguous between code and structure.
 const parseBody = (body) => {
   const sections = [];
   const preamble = [];
@@ -116,8 +110,6 @@ const parseBody = (body) => {
   return { title: state.title, sections, preamble, fenced, sectionBeforeTitle: state.sectionBeforeTitle };
 };
 
-// Lexical classification of a repo-relative path field — the same vocabulary for module roots and
-// scenario bindings. Realpath/symlink containment needs the filesystem and is the checker's duty.
 export const classifyPath = (path) => {
   if (path.trim() === '') return 'empty';
   if (path.includes('\\')) return 'backslash';
@@ -139,8 +131,47 @@ const MODULE_PATH_RULES = Object.freeze({
 const isBullet = (line) => line === '-' || line.startsWith('- ');
 const bulletsOf = (lines) => lines.filter(isBullet).map((line) => line.slice(2));
 const contentOf = (lines) => lines.filter((line) => line.trim() !== '');
+const isAtxHeading = (line) => /^ {0,3}#{1,6}(?:[ \t]|$)/.test(line);
+const topLevelBulletsOf = (lines) => lines.reduce((state, raw) => {
+  const line = raw.replace(/\s+$/, '');
+  if (isBullet(line)) {
+    state.current = [line === '-' ? '' : line.slice(2)];
+    state.bullets.push(state.current);
+  } else if (line.trim() === '' || isAtxHeading(line)) state.current = null;
+  else if (state.current !== null) state.current.push(line.trim());
+  return state;
+}, { bullets: [], current: null }).bullets.map((parts) => parts.join(' ').replace(/\s+/g, ' ').trim());
+
+const CLAUSE_BREAK = String.fromCharCode(0);
+const MASKED_DOT = String.fromCharCode(1);
+const MASKED_SEMICOLON = String.fromCharCode(2);
+const maskClauseSpans = (text) => [...text].reduce((state, character) => {
+  if (character === '`') state.inSpan = !state.inSpan;
+  state.output.push(state.inSpan && character === '.' ? MASKED_DOT : state.inSpan && character === ';' ? MASKED_SEMICOLON : character);
+  return state;
+}, { inSpan: false, output: [] }).output.join('');
+const clausesOf = (bullet) => maskClauseSpans(bullet).replace(/([.;][*`\)\]]*) /g, `$1${CLAUSE_BREAK}`).split(CLAUSE_BREAK)
+  .map((clause) => clause.split(MASKED_DOT).join('.').split(MASKED_SEMICOLON).join(';').trim()).filter(Boolean);
+const containsInOrder = (text, tokens) => tokens.reduce((position, token) => {
+  const found = position === -1 ? -1 : text.indexOf(token, position);
+  return found === -1 ? -1 : found + token.length;
+}, 0) !== -1;
+const hasBoundedToken = (clause, token, flags) => new RegExp(`(^|[^A-Za-z0-9_-])${token}([^A-Za-z0-9_-]|$)`, flags).test(clause);
+const checkOpenLists = (parsed, kind, errors) => {
+  const groups = kind === 'spec' ? parsed.sections.filter((section) => section.heading === '## Contract').map((section) => section.lines)
+    : kind === 'part' ? [parsed.preamble, ...parsed.sections.map((section) => section.lines)] : [];
+  for (const clause of groups.flatMap(topLevelBulletsOf).flatMap(clausesOf)) {
+    const hasVerb = SPEC_SCHEMA.openList.checkVerbs.some((verb) => clause.includes(verb));
+    const hasEnumeration = SPEC_SCHEMA.openList.enumerationForms.some((form) => containsInOrder(clause, form));
+    const hasClosure = SPEC_SCHEMA.openList.closureTokens.some((token) => hasBoundedToken(clause, token, 'i'))
+      || hasBoundedToken(clause, SPEC_SCHEMA.openList.emphaticToken, '');
+    if (hasVerb && hasEnumeration && !hasClosure) {
+      const prefix = clause.split(/\s+/).slice(0, 6).join(' ');
+      errors.push({ rule: 'open-list', message: `the clause "${prefix}…" is an open list — add a closing form to it such as "only if …; everything else …"` });
+    }
+  }
+};
 
-// The slug a document owns: the file stem for a flat file, the folder name for an index.md.
 const describeRel = (rel) => {
   const segments = rel.split('/');
   const file = segments[segments.length - 1];
@@ -314,11 +345,7 @@ const checkParts = (parsed, at, errors) => {
   if (duplicate !== undefined) errors.push({ rule: 'parts', message: `part "${duplicate}" is listed twice` });
 };
 
-// The structure verdict (additive, slice 2a): the DETERMINISTIC extraction of what parsed, per
-// section, targets VERBATIM as written (`./x.md` and `./x/index.md` stay distinct strings). The
-// grammar is per line for scenarios/children/parts — a malformed line is simply absent — while the
-// module is a conjunction (ONE `dir/` root or an all-file list): prose, a refused path, a mix or
-// `*(empty)*` extracts null. `## Links` is free prose and is never extracted.
+// Structure verdict: the same canon, "The frozen schema".
 const scenarioEntry = (line) => {
   const scenario = parseScenario(line);
   if (scenario === null) return null;
@@ -345,10 +372,6 @@ const extractStructure = (parsed) => ({
   module: extractModule(parsed),
 });
 
-// The verdict: { kind, status, revision, structure, errors: [{ rule, message }], warnings: [{ rule,
-// message }] }. Errors are collected past the first defect wherever later checks stay meaningful; a
-// missing or defective frontmatter and an unknown kind each end the read (structure stays null),
-// because no shape can be judged without them.
 export const readSpecDocument = (text, rel) => {
   const errors = [];
   const warnings = [];
@@ -372,6 +395,7 @@ export const readSpecDocument = (text, rel) => {
   const at = checkPath(rel, kind, errors);
   const parsed = parseBody(body);
   if (parsed.fenced.length > 0) errors.push({ rule: 'fence', message: `"${parsed.fenced[0]}" — a spec document carries no code fence` });
+  checkOpenLists(parsed, kind, errors);
   checkSections(parsed, kind, errors);
   if (kind === 'index') {
     checkChildren(parsed, errors);

package/references/scripts/spec-schema.test.mjs

@@ -32,6 +32,8 @@ const refuses = (text, rel, rule) => {
   const verdict = readSpecDocument(text, rel);
   expect(rulesOf(verdict)).toEqual([rule]);
 };
+const withContract = (contract) => specDoc().replace('Accepts a credential pair.', contract);
+const openListErrors = (contract, rel = 'login.md') => readSpecDocument(withContract(contract), rel).errors;
 
 describe('readSpecDocument — accept', () => {
   it('a flat draft spec reads clean with kind/status/revision', () => {
@@ -269,6 +271,69 @@ describe('readSpecDocument — the structure verdict (additive, slice 2a)', () =
   });
 });
 
+describe('readSpecDocument — open-list clauses', () => {
+  const refusal = 'the clause "an anchor path reported modified, untracked…" is an open list — add a closing form to it such as "only if …; everything else …"';
+  const open = '- an anchor path reported modified, untracked or ignored is the named refusal `anchor-dirty`';
+  const closed = '- an anchor path is accepted only if `ls-files -v` lists it with tag `H` and `status` is silent — everything else, a path reported modified, untracked or ignored, is the named refusal `anchor-dirty`';
+
+  it('refuses the measured clause with the exact message; verb alone, form alone and an in-clause closure pass', () => {
+    expect(openListErrors(open)).toEqual([{ rule: 'open-list', message: refusal }]);
+    for (const text of [closed, '- refuse one case', '- alpha, beta or gamma']) expect(openListErrors(text)).toEqual([]);
+  });
+
+  it('joins continuation lines, collapses whitespace and keeps an indented bullet in its top-level bullet', () => {
+    for (const text of ['- refuse alpha,\n   beta   or ignored', '- refuse alpha,\n  - beta or ignored']) expect(rulesOf(readSpecDocument(withContract(text), 'login.md'))).toEqual(['open-list']);
+  });
+
+  it('ends a bullet at a blank, the next top-level bullet or every ATX heading; Contract prose is ignored', () => {
+    for (const tail of ['\n\nEverything else closes', '\n- Everything else closes', ...Array.from({ length: 6 }, (_, i) => `\n${'#'.repeat(i + 1)} Everything else closes`)]) {
+      expect(rulesOf(readSpecDocument(withContract('- refuse alpha, beta or gamma' + tail), 'login.md'))).toEqual(['open-list']);
+    }
+    expect(openListErrors('refuse alpha, beta or gamma')).toEqual([]);
+  });
+
+  it('ends a bullet at indented and tab-separated ATX headings', () => {
+    for (const tail of ['\n   ## Everything else closes', '\n#\tEverything else closes']) expect(rulesOf(readSpecDocument(withContract('- refuse alpha, beta or gamma' + tail), 'login.md'))).toEqual(['open-list']);
+  });
+
+  it('starts a new empty top-level bullet before following prose', () => {
+    for (const tail of ['\n- \nEverything else closes', '\n-\nonly if closes']) expect(rulesOf(readSpecDocument(withContract('- refuse alpha, beta or gamma' + tail), 'login.md'))).toEqual(['open-list']);
+  });
+
+  it('judges an open list in every Contract section', () => {
+    const duplicate = specDoc().replace('## Scenarios', '## Contract\n\n- refuse alpha, beta or gamma\n\n## Scenarios');
+    expect(rulesOf(readSpecDocument(duplicate, 'login.md')).includes('open-list')).toBe(true);
+  });
+
+  it('splits clauses at punctuation plus markdown tails, but not inside backtick spans', () => {
+    for (const tail of ['.** ', '.` ', '.) ', '.] ', '; ']) expect(rulesOf(readSpecDocument(withContract(`- refuse alpha, beta or gamma${tail}Everything else closes`), 'login.md'))).toEqual(['open-list']);
+    for (const text of ['- refuse `alpha. beta`, gamma or delta', '- refuse `alpha; beta`, gamma or delta', '- refuse `alpha. beta, gamma or delta']) expect(rulesOf(readSpecDocument(withContract(text), 'login.md'))).toEqual(['open-list']);
+    expect(openListErrors('- refuse alpha``. beta, gamma or delta')).toEqual([]);
+  });
+
+  it('keeps span content in judgement, and a closure in a neighbouring clause cannot lift a refusal', () => {
+    expect(rulesOf(readSpecDocument(withContract('- `refuse` alpha, beta or gamma'), 'login.md'))).toEqual(['open-list']);
+    expect(openListErrors('- refuse alpha, beta or gamma with `everything else`')).toEqual([]);
+    expect(rulesOf(readSpecDocument(withContract('- refuse alpha, beta or gamma. Everything else closes'), 'login.md'))).toEqual(['open-list']);
+  });
+
+  it('matches verbs, forms and closure tokens with the frozen case and boundary rules', () => {
+    for (const verb of ['refuse', 'refuses', 'refused', 'refusal', 'refusals', 'REFUSE', 'REFUSAL']) expect(rulesOf(readSpecDocument(withContract(`- ${verb} alpha, beta or gamma`), 'login.md'))).toEqual(['open-list']);
+    for (const text of ['- Refuse alpha, beta or gamma', '- refuse alpha, beta and gamma']) expect(openListErrors(text)).toEqual([]);
+    expect(rulesOf(readSpecDocument(withContract('- refuse alpha · beta'), 'login.md'))).toEqual(['open-list']);
+    for (const token of SPEC_SCHEMA.openList.closureTokens) expect(openListErrors(`- ${token.toUpperCase()}: refuse alpha, beta or gamma`)).toEqual([]);
+    for (const text of ['- refuse alpha, beta or gamma — none of these', '- refuse alpha, beta or gamma — closed-key', '- refuse alpha, beta or gamma — READ-ONLY', '- refuse alpha, beta or gamma — if only this', '- refuse alpha, beta or gamma — not only this']) expect(rulesOf(readSpecDocument(withContract(text), 'login.md'))).toEqual(['open-list']);
+    expect(openListErrors('- refuse alpha, beta or gamma — ONLY this')).toEqual([]);
+  });
+
+  it('judges every part bullet, never an index, and freezes every schema list and inner pair', () => {
+    expect(rulesOf(readSpecDocument(partDoc({ extra: `\n${open}\n` }), 'auth/login/sessions.md'))).toEqual(['open-list']);
+    expect(readSpecDocument(indexDoc({ children: [], preamble: `\n${open}\n` }), 'auth/index.md').errors).toEqual([]);
+    expect(SPEC_SCHEMA.openList).toEqual({ checkVerbs: ['refuse', 'refusal', 'REFUSE', 'REFUSAL'], enumerationForms: [[',', ' or '], [' · ']], closureTokens: ['only if', 'only when', 'the only', 'everything else', 'anything else', 'nothing else', 'every other', 'any other', 'otherwise', 'exactly', 'one of', 'closed'], emphaticToken: 'ONLY' });
+    expect([SPEC_SCHEMA.openList, SPEC_SCHEMA.openList.checkVerbs, SPEC_SCHEMA.openList.enumerationForms, ...SPEC_SCHEMA.openList.enumerationForms, SPEC_SCHEMA.openList.closureTokens].every(Object.isFrozen)).toBe(true);
+  });
+});
+
 describe('classifyPath + the frozen constants', () => {
   it('classifies the lexical path forms', () => {
     expect(['src/', 'src/a.mjs', '../x', '/x', 'C:/x', 'a\\b', 'src/*.mjs'].map(classifyPath)).toEqual([

package/tools/bridge-settings.mjs

@@ -273,7 +273,7 @@ export const main = (argv = [], ctx = {}) => {
     const body = joinLines(newLines);
 
     // The machine surface carries the SAME spend/credit-rate caveats the human preview prints (D4) — a
-    // --json consumer must not miss the 2.5x-credit consent warning the human render shows.
+    // --json consumer must not miss the spend consent warning the human render shows.
     const jsonBody = (wrote) => ({ path, wrote, noop, changes: changes.map((c) => ({ key: c.key, kind: c.kind, before: c.before, after: c.after })), envShadows, caveats });
 
     if (!apply || noop) {

package/tools/commands.mjs

@@ -84,6 +84,13 @@ const CATALOG = [
     kind: READ_ONLY,
     oneLine: 'Show what is installed and at what version, your settings and backends, and what is deployed in this project.',
   },
+  {
+    key: 'now',
+    invocation: invocationOf('now'),
+    group: 'Inspect',
+    kind: READ_ONLY,
+    oneLine: 'Show where work stands: NOW answers the plan and tree, STEPS the evidence-derived ledger state, QUEUE its named positions, and CAMPAIGN its size-practice figures; the plan’s own text never sets a status.',
+  },
   {
     key: 'backends',
     invocation: invocationOf('backends'),

package/tools/feedback-record.mjs

@@ -18,7 +18,11 @@ const NOTES_HEADING = '## Notes';
 const TABLE_HEADER = '| # | Claim | Evidence | Verdict | Disposition |';
 const OBJECT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/iu;
 const ANCHOR = /^`([^`,\s]+):([1-9][0-9]*)(?:-([1-9][0-9]*))?`$/u;
-const ROW_ID = '[A-Z0-9][A-Z0-9-]*';
+// The row id a checked record hands over, and the ONE home of that grammar: the queue's name
+// judge reads it back for the EXPLICITLY marked form (`— id <ID>`), so every id this writer may
+// legally emit round-trips through the judge — including `FOO`, `TASK-123` and `1-TASK`, which
+// the judge's own heuristic deliberately does not read unmarked.
+export const ROW_ID = '[A-Z0-9][A-Z0-9-]*';
 const QUEUE = new RegExp(`^queue (${ROW_ID})$`, 'u');
 const ALREADY_QUEUED = new RegExp(`^already-queued (${ROW_ID})$`, 'u');
 const REASONED_DISPOSITION = /^(?:declined|folded): (.+)$/u;
@@ -227,7 +231,7 @@ export const renderRows = (record, { date, recordPath }) => {
   return ids.map((id) => {
     const claims = record.claims.filter((claim) => QUEUE.exec(claim.disposition)?.[1] === id);
     return [
-      `- [ ] ${id}: ${claims[0].claim} (${date})`,
+      `- [ ] ${claims[0].claim} — id ${id} (${date})`,
       ...claims.map((claim) => `  - ${claim.claim}; verdict ${claim.verdict}; evidence ${claim.anchors.map(rendersAnchor).join(', ')}`),
       `  - record: ${recordPath}`,
       `  - head: ${record.head}`,

package/tools/now-cli.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// The CLI half of `now`: argv, the io seam and the pipeline. The rules live in now-status.mjs, the
+// facts in now-facts.mjs, the phrases in now-render.mjs.
+
+import { resolve } from 'node:path';
+import { fail } from '../references/scripts/markdown-blocks.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { FORMATS, detectSurface } from './surface.mjs';
+import { gatherNowFacts } from './now-facts.mjs';
+import { isWithheld } from './now-status.mjs';
+import { renderNow, toNowViewModel } from './now-render.mjs';
+
+const BLOCKS = Object.freeze(['now', 'steps', 'queue', 'campaign']);
+const SCHEMA = 1;
+const FORMAT_FLAG = '--format=';
+const HELP = `now — read-only: where the work stands, in four blocks.
+
+Usage:
+  node now-cli.mjs [--dir <project>] [--format=<${FORMATS.join('|')}>] [--json]
+
+--dir     the project to read (default: the current directory).
+--format  the output surface; --json is strict sugar for --format=json, and naming both with
+          different values is usage.
+--help    answered only when it is the whole invocation.
+
+Blocks: NOW (the plans in flight, the phase, the current and the next step, the tree), STEPS (the
+ledger rows, one status each), QUEUE (the backlog folded under each row's heading path), CAMPAIGN
+(the size practice). A block that cannot be derived is WITHHELD with its cause on one line.
+
+A status is a function of the row's (path, verb) pair and the evidence at that path; the row's prose
+is printed as a claim beside a status it never moves.
+
+Exit codes: 0 anything rendered, a withheld block included; 1 nothing rendered at all (a --dir that
+is not a git work tree); 2 usage.
+
+Reads only: no store, no receipt, no cache, no lock.`;
+
+const valueAt = (argv, index, flag) => {
+  const value = argv[index + 1];
+  if (value === undefined || value === '' || value.startsWith('-')) throw fail(2, `${flag} takes a value`);
+  return value;
+};
+
+export const parseArgv = (argv) => {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    if (argv.length !== 1) throw fail(2, '--help is answered only when it is the whole invocation');
+    return { help: true, dir: null, formats: [] };
+  }
+  const parsed = argv.reduce((state, arg, index) => {
+    if (state.skip) return { ...state, skip: false };
+    if (arg === '--dir') return { ...state, dir: valueAt(argv, index, arg), skip: true };
+    if (arg === '--format') return { ...state, formats: [...state.formats, valueAt(argv, index, arg)], skip: true };
+    if (arg.startsWith(FORMAT_FLAG)) return { ...state, formats: [...state.formats, arg.slice(FORMAT_FLAG.length)] };
+    if (arg === '--json') return { ...state, formats: [...state.formats, 'json'], json: true };
+    throw fail(2, `unknown argument "${arg}" — run with --help`);
+  }, { help: false, dir: null, formats: [], json: false, skip: false });
+  if (parsed.json && parsed.formats.some((format) => format !== 'json')) {
+    throw fail(2, '--json is strict sugar for --format=json — naming both with different values is usage');
+  }
+  return parsed;
+};
+
+const resolveSurface = (formats, env, io) => detectSurface({
+  argv: formats.map((format) => `${FORMAT_FLAG}${format}`),
+  env,
+  isTTY: io.isTTY ?? Boolean(process.stdout.isTTY),
+  columns: io.columns ?? process.stdout.columns,
+  platform: io.platform ?? process.platform,
+});
+
+const toEnvelope = (dir, vm) => ({ schema: SCHEMA, command: 'now', dir, ...vm });
+
+export const main = (argv, io = {}) => {
+  const log = io.log ?? console.log;
+  const error = io.error ?? console.error;
+  const env = io.env ?? process.env;
+  const start = (() => {
+    try {
+      const options = parseArgv(argv);
+      return options.help ? { help: true } : { options, surface: resolveSurface(options.formats, env, io) };
+    } catch (err) {
+      error(err?.message ?? String(err));
+      return { code: err?.exitCode ?? 2 };
+    }
+  })();
+  if (start.code !== undefined) return start.code;
+  if (start.help) {
+    log(HELP);
+    return 0;
+  }
+  const cwd = resolve(io.cwd ?? process.cwd(), start.options.dir ?? '.');
+  // The composed readers spawn git under process.env alone, so the flag must reach them there too.
+  process.env.GIT_OPTIONAL_LOCKS = '0';
+  const vm = toNowViewModel(gatherNowFacts({ cwd, env: { ...env, GIT_OPTIONAL_LOCKS: '0' } }));
+  const blocks = BLOCKS.map((name) => vm[name]);
+  if (blocks.every(isWithheld)) {
+    for (const cause of new Set(blocks.map(({ withheld }) => withheld))) error(cause);
+    return 1;
+  }
+  log(start.surface.mode === 'json' ? JSON.stringify(toEnvelope(cwd, vm), null, 2) : renderNow(vm, start.surface));
+  return 0;
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/tools/now-facts.mjs

@@ -0,0 +1,67 @@
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { buildSummaryState, isTreeClean } from './core-evidence.mjs';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { resolveGitLocation } from './git-env.mjs';
+import { auditQueue } from './queue-audit.mjs';
+import { loadSourceSizeConfig, practiceFacts } from './source-size-config.mjs';
+import { gatherPlanFacts, readSummaryFacts } from './now-plan-facts.mjs';
+import { isWithheld } from './now-status.mjs';
+
+const QUEUE_REL = 'docs/plans/queue.md';
+const BLOCKS = Object.freeze(['plans', 'tree', 'queue', 'campaign']);
+
+const attempt = (label, read) => {
+  try {
+    return read();
+  } catch (error) {
+    return { withheld: `${label}: ${error?.message ?? error}` };
+  }
+};
+
+const readQueueFacts = (cwd, deps) => {
+  const read = readRegularFileNoFollow(join(cwd, QUEUE_REL), deps.io ?? {});
+  if (read.outcome !== 'ok') throw new Error(`${QUEUE_REL} is not a readable regular file (${read.className ?? read.code ?? read.outcome})`);
+  const { rows, counts, total } = auditQueue(read.content, { label: QUEUE_REL });
+  return { path: QUEUE_REL, rows, counts, total };
+};
+
+// The practice is opt-in: an absent declaration is a rendered STATE, only an unreadable one is withheld.
+const readCampaignFacts = (cwd, deps) => {
+  const loaded = loadSourceSizeConfig(cwd, deps);
+  return loaded.state === 'absent' ? { state: loaded.state } : { state: loaded.state, ...practiceFacts(loaded.config) };
+};
+
+// A store the summary cannot trust never attests: the tree is withheld with the store's own cause.
+const describeUntrustedStore = (summary) => {
+  if (summary.evidenceUnavailable) return `the core-evidence store is malformed or unreadable (${summary.storeReadError ?? `${summary.storeMalformed} malformed line(s)`})`;
+  if (summary.receiptsUnavailable) return `the review receipts store is malformed or unreadable (${summary.receiptsReadError ?? `${summary.receiptsMalformed} malformed line(s)`})`;
+  return null;
+};
+
+const toTreeFacts = (summary, clean) => {
+  const untrusted = describeUntrustedStore(summary);
+  if (untrusted) return { withheld: untrusted };
+  const { redProofs, receipts } = readSummaryFacts(summary);
+  return { fingerprint: summary.fingerprint, clean, verdicts: receipts.verdicts, finalRun: receipts.finalRun, redProofs };
+};
+
+export const gatherNowFacts = ({ cwd, env: given = process.env, deps = {} }) => {
+  // Every reader honouring an env argument spawns under this one: a plain `git diff` rewrites .git/index without the flag.
+  const env = { ...given, GIT_OPTIONAL_LOCKS: '0' };
+  const location = resolveGitLocation(cwd, { spawn: deps.spawn ?? spawnSync, env });
+  if (location.state !== 'work-tree') {
+    const withheld = `${cwd} is not a git work tree (${location.state}: ${location.cause})`;
+    return Object.fromEntries(BLOCKS.map((block) => [block, { withheld }]));
+  }
+  const root = location.top;
+  const summary = attempt('the evidence summary', () => deps.summary ?? buildSummaryState({ cwd: root, env }));
+  return {
+    plans: attempt('the plans in flight', () => ({
+      entries: gatherPlanFacts({ cwd: root, env, deps }).plans,
+    })),
+    tree: isWithheld(summary) ? summary : attempt('the tree state', () => toTreeFacts(summary, isTreeClean(root, { env }))),
+    queue: attempt('the queue', () => readQueueFacts(root, deps)),
+    campaign: attempt('the practice', () => readCampaignFacts(root, deps)),
+  };
+};