@nightlab-agent/still-true 0.1.1 → 0.3.0

package/README.md

@@ -1,39 +1,80 @@
 # still-true
 
+Checks a handoff note's pull request and issue claims against GitHub.
+
 Your handoff note says "waiting on #12". #12 merged yesterday. The next session plans around it anyway.
 
-    npx @nightlab-agent/still-true STATE.md --repo owner/name --alias Archy=hslee16/Archy
+    npx @nightlab-agent/still-true STATE.md --repo owner/name
+
+Use your own note and repository. Try it first on a note that is out of date:
+
+    dir="$(mktemp -d)" && cd "$dir" && printf '# Now\n\nhslee16/Archy#827 open\n' > note.md
+    npx @nightlab-agent/still-true note.md
+
+Every option and exit code:
+
+    npx @nightlab-agent/still-true --help
 
-`still-true` reads a note, finds the sentences that say a pull request or issue is open, merged, closed or being waited on, and asks GitHub. It prints only what no longer holds:
+`still-true` reads a note, finds the sentences that say a pull request or issue is open, merged, closed or being waited on, and asks GitHub. It also checks references named as queued review work. It prints contradictions and things to look at:
 
-    STATE.md:5  said open, but hslee16/Archy#827 is merged 2026-11-05  https://github.com/hslee16/Archy/pull/827
+    note.md:3  said open, but hslee16/Archy#827 is merged 2026-11-05  https://github.com/hslee16/Archy/pull/827
       "hslee16/Archy#827 open"
-    2 claims checked, 1 contradicted
+    1 claim checked, 1 contradicted
 
-We typed that note to test it. The real miss behind it: an agent's handoff went on counting 5 open pull requests through twelve session ends after one had merged. A bare count names no pull request, so still-true needs the note to name it.
+With one thing to look at, the last line gains `, 1 to look at`.
+
+The real miss behind it: an agent's handoff went on counting 5 open pull requests through six session ends after one had merged. A bare count names no pull request, so still-true needs the note to name it.
 
 ## Use it
 
-Give it one or more Markdown files. For a bare `#12` it uses `--repo owner/name`, or the `origin` remote of the folder you run it in. For a short name like `Archy#827`, give `--alias Archy=owner/name`, or it prints `not checked` for that line.
+Give it one or more Markdown files. For a bare `#12` it uses `--repo owner/name`, or the `origin` remote of the folder you run it in. For a short name like `Archy#827`, give `--alias Archy=owner/name`, or a `--repo` with that repo name; otherwise it prints `not checked` for that line.
 
-Set `GITHUB_TOKEN` for private repositories and a higher rate limit. Without one, GitHub allows 60 requests an hour. Needs Node 20 or newer. Behind a proxy, run with `NODE_USE_ENV_PROXY=1`, tested on Node 22; Node prints an experimental warning.
+Set `GITHUB_TOKEN` for private repositories and a higher rate limit. Without one, GitHub allows 60 requests an hour. Needs Node 20 or newer, tested on 20 and 22. Behind a proxy, run with `NODE_USE_ENV_PROXY=1` on Node 22; Node prints an experimental warning. Node 20 does not read that setting, and the run stops with `fetch failed`.
 
-In a Markdown file with headings, it reads a section only if its heading starts with Now, Handoff, State, Status or Current, and any heading above it does too, or is the file's first level 1 heading. A first level 1 heading starting with History, Archive or Old is not a title. Plans and history stay out. Text before the first heading is read, and a file with no headings is read whole.
+In a Markdown file with headings, it reads a section only if its heading starts with Now, Handoff, State, Status or Current, and any heading above it does too, or is the file's first level 1 heading. A first level 1 heading starting with History, Archive or Old is not a title. Plans and history stay out. Text before the first heading is read, and a file with no headings is read whole. If it finds no claims, it names the sections it skipped.
 
 ## What each line means
 
 - `said open, but ... is merged`: a contradiction. The note and GitHub disagree.
 - `look: waits on ..., which is merged`: the note waits on something finished. It may be waiting for a release or a reply, so read it. This does not fail the run.
+- `look: queued work on ..., which is closed (not_planned)`: the note queues review work for a finished reference. Read whether that work still belongs in the queue. This does not fail the run.
 - `not checked`: it could not place the reference, or GitHub has no such issue, or it is private. Nothing was verified for that line.
 
+Queued work needs a reference at the start of a clause, optionally labelled PR, issue or pull request, then an optional commit hash and a counted review obligation such as `argent#1768 81004b3 owes one critic` or `argent#1768, one review owed`. Counts are a, an, one, two, three or a positive integer; the nouns are critic(s) or review(s). `still` may precede the obligation. One comma may separate the reference/hash from it, and a following wait may start with `and` or a comma. An open reference stays quiet. A reference alone, a past-tense obligation, or other unquoted trailing prose in that clause does not qualify. Quoted text and inline code are masked before matching: `argent#1768 owes one critic "not anymore"` and ``argent#1768 owes one critic `done` `` still qualify. A wholly quoted obligation stays out, as do historical and planning scopes. Blockquoted lines contribute no claims, including when the quote follows nested list markers. A quote does not silence the preceding paragraph or an independent list item after it; an immediately following unmarked prose line can still continue the quote.
+
+Look and contradiction lines include GitHub's `state_reason` when supplied, such as `closed (not_planned)` or `closed (completed)`. The reason adds context; it does not change the verdict.
+
 ## Exit status
 
 - `0`: nothing contradicted. Look lines may have printed.
 - `1`: at least one contradiction.
 - `2`: bad usage, or an unreadable file or failed read before any contradiction. The run is not complete.
+- `3`: only with `--strict`. A note had no claim to verify, or a claim could not be checked.
 
 An unreadable file or failed read after a contradiction exits `1` and still says the run is not complete.
 
+Without `--strict`, a note with no claims in the sections it reads exits `0`, and so does a claim GitHub has no record of. Add `--strict` when an agent or a script runs the check for you and a green run has to mean something was verified. A contradiction still exits `1` and a failed read still exits `2`. Each note is judged on its own, so a note with no claims fails the run even when another note checked out. Skipped sections alone do not fail a note that had a claim. With `--json`, a run that fails this way adds `strict_failed: true`.
+
+Queued reads follow the same stop-on-failure rule: a failed queued read stops before later claims, exiting `2` if no contradiction has been found yet. Adding queued claims can therefore change the exit status for the same note. A queued line can also let a neighbouring state claim be read where it was previously suppressed as adjacent nonclaim prose: `argent#1768 owes a review` followed immediately by `#12 open` now checks both, and exits `1` if #12 has merged. A look alone still exits `0`.
+
+## JSON output
+
+Add `--json` for one JSON object on stdout, with no text lines. Exit codes stay the same.
+
+    npx @nightlab-agent/still-true STATE.md more.md --repo owner/name --json
+
+The object has `schema: 1`, `complete`, `reason` (`null` on success), `counts` and `claims`.
+Counts are `checked`, `contradicted`, `looks` and `notChecked`; checked includes contradictions, looks and ok claims.
+Each claim has `file`, a 1-based `line`, `reference` (resolved to `owner/repo#number` when possible), `said`, `actual` (`open`, `merged`, `closed` or `null` when unknown), `kind` (`contradiction`, `look`, `not checked` or `ok`), and `url` when known.
+If no claim was found and a section was skipped, `skipped_sections` lists those sections, each with its file when you gave more than one. `complete` is still `true` and the exit is `0` without `--strict`, so a script that must know a note was really read should use `--strict`.
+`said` can also be `queued`, for the review obligations above. A nonempty GitHub `state_reason` is included as an optional string field; null or absent reasons are omitted.
+
+A failed read or unreadable file sets `complete: false` and gives the reason, keeping earlier results. The run stops there; claims already extracted from the current file that were not reached have kind `not checked`. Later files have no entries. A complete run can still have unchecked claims, such as an unresolved alias or a private issue. No claims gives an empty array and zero counts. `--json --help` returns the help text in a `help` field.
+
+## Remove it
+
+`npx` installs nothing in your project; it keeps a copy under `~/.npm/_npx`, which is safe to delete. If you installed it with `npm install`, use `npm uninstall @nightlab-agent/still-true`. It writes no files of its own.
+
 ## When it is not for you
 
 - Silence does not mean your note is true. It means no contradiction was found in the sentences it understood. It stays quiet when unsure, on purpose.
@@ -43,7 +84,11 @@ An unreadable file or failed read after a contradiction exits `1` and still says
 
 ## How well it reads
 
-An earlier parser scored 0 of 17 on hand-labelled sentences it had not seen. Rewritten against 40 other labelled claims, it found 16 of the same 17, 0 wrong. A sample of 30 claims from six days of logs held 2 wrong, both bare numbers (`#3`, `#4`) that named findings. All of that wording is one agent's, so expect less on yours.
+On 17 hand-labelled sentences kept out of its 40 development claims, it found 16, 0 wrong. A sample of 30 claims from six days of logs held 2 wrong, both bare numbers (`#3`, `#4`) that named findings. All of that wording is one agent's, and those two sets are not in this repository, so expect less on yours.
+
+The queued-review extension finds the reported subject and preserves its dependency. In `test/fixtures`, the development handoff scores 13/13 required claims with 0 extras. The second handoff, held out from development of this extension, retains 28/28 required claims plus 2 permitted optional claims, with 0 extras. It has no counted review obligations: two separately labelled current-work references (a fix ready on a branch and fixes waiting on a date) still go unread, so new-work recall there is 0/2. This supports keeping the rule narrow, not treating every named reference as current work. From a source checkout, `node test/score-queued.mjs` reproduces that supplemental score; checking every uncovered mention instead adds 22 unlabelled references in the first handoff and 12 in the second. These are small samples of the same author's notes, not evidence of recall on other writers.
+
+The rule also misses `needs review`, uncounted obligations, labels before the reference, shared subjects and wrapped obligations. A historical mention without any historical wording or scope can still look current. State wordings it does not read yet: a full GitHub URL, a Markdown link, `**#12**` in bold, a checkbox line, a table row, `Blocked on #12`, `#12 has been merged`. Silence remains an incomplete reading of the note.
 
 ## The contract between the two halves
 
@@ -53,14 +98,14 @@ An earlier parser scored 0 of 17 on hand-labelled sentences it had not seen. Rew
 
 - `line`: 1-based line number in the note.
 - `ref`: `{ owner, repo, number }`, or `{ repo, number }` for the short form `Archy#827`, or `{ number }` for `#12`.
-- `said`: `"open"`, `"merged"`, `"closed"` or `"waiting"`: what the sentence claims is true now.
+- `said`: `"open"`, `"merged"`, `"closed"` or `"waiting"` for a present-state claim, or `"queued"` for a counted review obligation.
 - `quote`: the sentence, trimmed to 160 characters.
 
-A sentence that does not claim a present state gives no claim.
+A sentence needs a present-state claim or the narrow queued-review form above to give a claim.
 
-`src/github.mjs` (network) turns a ref into `{ state: "open" | "merged" | "closed", kind, at, url }`.
+`src/github.mjs` (network) turns a ref into `{ state: "open" | "merged" | "closed", kind, at, url }`, with an optional nonempty `state_reason` string from GitHub.
 
-`src/compare.mjs` decides: `said` against `state`. "closed" said of a merged PR is not a contradiction.
+`src/compare.mjs` decides: `said` against `state`. "closed" said of a merged PR is not a contradiction. Waiting and queued review work on a closed or merged reference are advisory looks.
 
 ## Credit
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nightlab-agent/still-true",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Check a handoff note against GitHub: finds what it says about PRs and issues and prints the claims that are no longer true. Exits 1 on a contradiction.",
   "type": "module",
   "bin": { "still-true": "bin/still-true.js" },

package/src/cli.mjs

@@ -3,7 +3,10 @@ import { spawnSync } from 'node:child_process';
 import { compare } from './compare.mjs';
 import { readState, resolveRef } from './github.mjs';
 
-const USAGE = 'usage: still-true NOTE.md [more.md] [--repo owner/name] [--alias Name=owner/name]';
+const USAGE = 'usage: still-true NOTE.md [more.md] [--repo owner/name] [--alias Name=owner/name] [--json] [--strict]';
+const JSON_HELP = '--json: print one JSON object (schema 1) with completeness, counts and every extracted claim.';
+const STRICT_HELP = '--strict: exit 3 if any note had no claim to verify, or if any claim could not be checked. Use it when a green run has to mean the note was really read.';
+const EXIT_HELP = 'exit 0: nothing contradicted, look lines may have printed\nexit 1: at least one contradiction\nexit 2: bad usage, or an unreadable file or failed read before any contradiction; the run is not complete\nexit 3: with --strict only, nothing was verified or a claim was not checked';
 
 export function repoFromRemote(url) {
   const m = /^(?:[a-z+]+:\/\/(?:[^@/\s]+@)?|[^@/\s]+@)?(?:www\.)?github\.com(?::\d+)?[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?\s*$/i.exec(url ?? '');
@@ -13,7 +16,7 @@ export function repoFromRemote(url) {
 const FULL = /^[^/\s=]+\/[^/\s=]+$/;
 
 export function parseArgs(argv) {
-  const a = { files: [], aliases: {}, repo: undefined, bad: null };
+  const a = { files: [], aliases: {}, repo: undefined, bad: null, json: argv.includes('--json'), strict: false };
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--repo') {
       a.repo = argv[++i];
@@ -22,7 +25,8 @@ export function parseArgs(argv) {
       const [name, full, more] = (argv[++i] ?? '').split('=');
       if (name && FULL.test(full ?? '') && more === undefined) a.aliases[name] = full;
       else a.bad ??= '--alias needs Name=owner/name';
-    } else a.files.push(argv[i]);
+    } else if (argv[i] === '--strict') a.strict = true;
+    else if (argv[i] !== '--json') a.files.push(argv[i]);
   }
   return a;
 }
@@ -38,68 +42,120 @@ const name = (ref) => (ref.owner ? `${ref.owner}/${ref.repo}#${ref.number}` : re
 export async function run(argv, deps) {
   const { out, extract, readFile = fsRead, read, token, defaultRepo = originRepo, env = process.env } = deps;
   const args = parseArgs(argv);
-  if (argv.includes('--help')) { out(USAGE); return 0; }
+  const print = (line) => { if (!args.json) out(line); };
+  const entries = [];
+  let checked = 0, contradicted = 0, looks = 0, unplaced = 0, failure = null;
+  const finish = (code, reason = null, extra = {}) => {
+    if (args.json) out(JSON.stringify({
+      schema: 1, complete: reason === null, reason,
+      counts: { checked, contradicted, looks, notChecked: entries.length - checked },
+      claims: entries, ...extra,
+    }));
+    return code;
+  };
+  if (argv.includes('--help')) {
+    print(USAGE); print(JSON_HELP); print(STRICT_HELP); print(EXIT_HELP);
+    return finish(0, null, { help: `${USAGE}\n${JSON_HELP}\n${STRICT_HELP}\n${EXIT_HELP}` });
+  }
   const odd = args.files.find((f) => f.startsWith('--'));
-  if (odd) { out(`unknown option ${odd}`); out(USAGE); return 2; }
-  if (args.bad) { out(args.bad); out(USAGE); return 2; }
-  if (!args.files.length) { out(USAGE); return 2; }
-  const repo = args.repo ?? (typeof defaultRepo === 'function' ? defaultRepo() : defaultRepo);
+  if (odd) { print(`unknown option ${odd}`); print(USAGE); return finish(2, `unknown option ${odd}`); }
+  if (args.bad) { print(args.bad); print(USAGE); return finish(2, args.bad); }
+  if (!args.files.length) { print(USAGE); return finish(2, USAGE); }
   const seen = new Map();
-  let checked = 0, contradicted = 0, looks = 0, unplaced = 0, failure = null;
+  const skipped = [];
+  const unread = [];
 
-  for (const file of args.files) {
-    let text;
-    try { text = await readFile(file, 'utf8'); }
-    catch (e) {
-      out(`${file}: cannot read: ${e.message}`);
-      out('This run is not complete.');
-      return contradicted ? 1 : 2;
-    }
-    for (const claim of extract(text, { aliases: args.aliases })) {
-      const ref = resolveRef(claim.ref, { defaultRepo: repo, aliases: args.aliases });
-      if (!ref) {
-        unplaced++;
-        const hint = claim.ref.repo ? `--alias ${claim.ref.repo}=owner/name` : '--repo owner/name';
-        out(`${file}:${claim.line}  not checked: ${name(claim.ref)} (use ${hint})`);
-        continue;
+  try {
+    const repo = args.repo ?? (typeof defaultRepo === 'function' ? defaultRepo() : defaultRepo);
+    for (const file of args.files) {
+      let text;
+      try { text = await readFile(file, 'utf8'); }
+      catch (e) {
+        const reason = `${file}: cannot read: ${e instanceof Error ? e.message : String(e)}`;
+        print(reason);
+        print('This run is not complete.');
+        return finish(contradicted ? 1 : 2, reason);
       }
-      let real;
-      try {
-        if (!seen.has(key(ref))) seen.set(key(ref), await read(ref, { token }));
-        real = seen.get(key(ref));
-      } catch (e) { failure = e.message; break; }
-      const r = compare(claim, real);
-      if (r.verdict === 'unknown') {
-        unplaced++;
-        out(`${file}:${claim.line}  not checked: ${name(ref)} (GitHub has no such issue, or it is private)`);
-        continue;
-      }
-      checked++;
-      const when = real.at ? ` ${real.at.slice(0, 10)}` : '';
-      if (r.verdict === 'look') {
-        looks++;
-        out(`${file}:${claim.line}  look: waits on ${name(ref)}, which is ${real.state}${when}  ${real.url}`);
-        out(`  "${claim.quote}"`);
-      } else if (r.verdict === 'contradicted') {
-        contradicted++;
-        out(`${file}:${claim.line}  said ${claim.said}, but ${name(ref)} is ${real.state}${when}  ${real.url}`);
-        out(`  "${claim.quote}"`);
+      // Record all claims in this file before reading GitHub, including those a failure may leave unchecked.
+      const here = [];
+      const claims = extract(text, { aliases: args.aliases, skipped: here }).map((claim) => {
+        const ref = resolveRef(claim.ref, { defaultRepo: repo, aliases: args.aliases });
+        const entry = args.json ? {
+          file, line: claim.line, reference: name(ref ?? claim.ref), said: claim.said,
+          actual: null, kind: 'not checked',
+        } : null;
+        if (entry) entries.push(entry);
+        return { claim, ref, entry };
+      });
+      if (!claims.length) unread.push(file);
+      skipped.push(...here.map((section) => (args.files.length > 1 ? `${file}: ${section}` : section)));
+      for (const { claim, ref, entry } of claims) {
+        if (!ref) {
+          unplaced++;
+          const hint = claim.ref.repo ? `--alias ${claim.ref.repo}=owner/name` : '--repo owner/name';
+          print(`${file}:${claim.line}  not checked: ${name(claim.ref)} (use ${hint})`);
+          continue;
+        }
+        let real;
+        try {
+          if (!seen.has(key(ref))) seen.set(key(ref), await read(ref, { token }));
+          real = seen.get(key(ref));
+        } catch (e) { failure = e instanceof Error ? e.message : String(e); break; }
+        const r = compare(claim, real);
+        if (entry) {
+          entry.actual = real?.state ?? null;
+          entry.kind = r.verdict === 'contradicted' ? 'contradiction' : r.verdict === 'unknown' ? 'not checked' : r.verdict;
+          if (real?.url) entry.url = real.url;
+          if (real?.state_reason) entry.state_reason = real.state_reason;
+        }
+        if (r.verdict === 'unknown') {
+          unplaced++;
+          print(`${file}:${claim.line}  not checked: ${name(ref)} (GitHub has no such issue, or it is private)`);
+          continue;
+        }
+        checked++;
+        const when = real.at ? ` ${real.at.slice(0, 10)}` : '';
+        const reason = real.state_reason ? ` (${real.state_reason})` : '';
+        if (r.verdict === 'look') {
+          looks++;
+          const action = claim.said === 'queued' ? 'queued work on' : 'waits on';
+          print(`${file}:${claim.line}  look: ${action} ${name(ref)}, which is ${real.state}${reason}${when}  ${real.url}`);
+          print(`  "${claim.quote}"`);
+        } else if (r.verdict === 'contradicted') {
+          contradicted++;
+          print(`${file}:${claim.line}  said ${claim.said}, but ${name(ref)} is ${real.state}${reason}${when}  ${real.url}`);
+          print(`  "${claim.quote}"`);
+        }
       }
+      if (failure !== null) break;
     }
-    if (failure) break;
-  }
+  } catch (e) { failure = e instanceof Error ? e.message : String(e); }
 
-  if (failure) {
-    out(`stopped: ${failure}`);
-    out('This run is not complete. Set GITHUB_TOKEN for a higher rate limit, or try again later.');
+  if (failure !== null) {
+    print(`stopped: ${failure}`);
+    print('This run is not complete.');
+    if (/rate limit/i.test(failure)) print('Set GITHUB_TOKEN for a higher rate limit, or try again later.');
     // Node's fetch ignores proxy settings unless told otherwise.
-    if ((env.HTTPS_PROXY ?? env.https_proxy) && !env.NODE_USE_ENV_PROXY) out('You have a proxy set: run again with NODE_USE_ENV_PROXY=1.');
-    return contradicted ? 1 : 2;
+    if ((env.HTTPS_PROXY ?? env.https_proxy) && !env.NODE_USE_ENV_PROXY) print('You have a proxy set: run again with NODE_USE_ENV_PROXY=1.');
+    return finish(contradicted ? 1 : 2, failure);
+  }
+  const strictFail = (extra = {}) => {
+    const why = [];
+    if (unplaced) why.push(`${unplaced} claim${unplaced === 1 ? '' : 's'} not checked`);
+    if (unread.length) why.push(`nothing was verified in ${unread.join(', ')}`);
+    print(`--strict: ${why.join(', ')}`);
+    return finish(3, null, { ...extra, strict_failed: true });
+  };
+  if (!checked && !unplaced) {
+    print('no claims about PR or issue state found');
+    if (!skipped.length) return args.strict ? strictFail() : finish(0);
+    print(`skipped ${skipped.length} section${skipped.length === 1 ? '' : 's'}: ${skipped.join(', ')}. A section is read only if its heading, and every heading above it, apart from the file's title, starts with Now, Handoff, State, Status or Current.`);
+    return args.strict ? strictFail({ skipped_sections: skipped }) : finish(0, null, { skipped_sections: skipped });
   }
-  if (!checked && !unplaced) { out('no claims about PR or issue state found'); return 0; }
   const note = (looks ? `, ${looks} to look at` : '') + (unplaced ? `, ${unplaced} not checked` : '');
-  out(`${checked} claim${checked === 1 ? '' : 's'} checked, ${contradicted} contradicted${note}`);
-  return contradicted ? 1 : 0;
+  print(`${checked} claim${checked === 1 ? '' : 's'} checked, ${contradicted} contradicted${note}`);
+  if (contradicted) return finish(1);
+  return args.strict && (unplaced || unread.length) ? strictFail() : finish(0);
 }
 
 export { readState };

package/src/compare.mjs

@@ -1,5 +1,5 @@
 // Decides one claim against what GitHub says. Only a real disagreement is "contradicted".
-// A wait on something finished is a "look": it may be waiting for a release or a reply.
+// A wait or queued review on something finished is a "look": work may remain after closure.
 export function compare(claim, real) {
   if (!real) return { verdict: 'unknown', claim };
   const { said } = claim;
@@ -8,7 +8,7 @@ export function compare(claim, real) {
   if (said === 'open') ok = state === 'open';
   else if (said === 'closed') ok = state === 'closed' || state === 'merged';
   else if (said === 'merged') ok = state === 'merged' || (kind === 'issue' && state === 'closed');
-  else if (said === 'waiting') return { verdict: state === 'open' ? 'ok' : 'look', claim, real };
+  else if (said === 'waiting' || said === 'queued') return { verdict: state === 'open' ? 'ok' : 'look', claim, real };
   else return { verdict: 'unknown', claim, real };
   return { verdict: ok ? 'ok' : 'contradicted', claim, real };
 }

package/src/extract.mjs

@@ -1,15 +1,19 @@
-// Six grammar rules, shared by bare statements, labelled lists and fact fields.
+// State and wait grammar, shared by bare statements, labelled lists and fact fields.
 const TOKEN = '[a-z0-9_./-]*#[a-z0-9_.-]+';
 const HAS_REF = new RegExp(TOKEN, 'i');
 const SUBJECT = new RegExp(`^((?:[^#]*\\s)?)(${TOKEN}(?:\\s+and\\s+${TOKEN})*)(.*)$`, 'i');
 const STATE = /^(?:(?:is(?:\s+(?:still|currently|now))?|remains|still|currently|already|was(?=\s+merged\b)|(?:PR|issue)(?:\s+is)?)\s+)?(open|merged|closed)\b(?!-)(.*)$/i;
 const BEFORE_REF = new RegExp(`(?<![\\w-])\\b(open|merged|closed)\\s+((?:PR|issue|pull request)\\s+)?(${TOKEN})(.*)$`, 'i');
 const COUNT_STATE = /^\d+\s+(open|merged|closed)$/i;
-const WAIT = new RegExp(`(?:^|\\s)(?:waits?|waiting)\\s+(?:on|for)\\s+(${TOKEN}|(?:its|the) maintainer)(?:\\s+(?:to merge|for a response))?$`, 'i');
+const WAIT = new RegExp(`(?:^|\\s)(?:waits?|waiting)\\s+(?:on|for)\\s+(${TOKEN}|(?:its|the) maintainer)(?:\\s+(?:to merge|for a response|and\\s+(?:a|an|the|its)\\s+(?!.*\\b(?:is|are|was|were)\\b)[\\w -]+))?$`, 'i');
+// A counted review obligation names queued work, without asserting it is open.
+// Only the obligation and an optional wait qualify; other trailing prose stays quiet.
+const REVIEW_COUNT = '(?:a|an|one|two|three|[1-9][0-9]*)';
+const QUEUED = new RegExp(`^(?:(?:PR|issue|pull request)\\s+)?(${TOKEN})(?:\\s+[a-f0-9]{6,40})?(?:\\s+|,\\s*)(?:still\\s+)?(?:owes\\s+${REVIEW_COUNT}\\s+(?:critic|review)s?|${REVIEW_COUNT}\\s+(?:critic|review)s?\\s+owed)(.*)$`, 'i');
 const LABEL_LIST = new RegExp(`(?:^|:\\s*)(open|merged|closed)(?:\\s+(?:PRs|issues|pull requests))?:\\s*(${TOKEN}(?:\\s*(?:,|and)\\s*${TOKEN})*)$`, 'i');
 
 const REF = /^(?:([a-z0-9-]+)\/)?([a-z0-9_.-]+)?#([1-9][0-9]*)$/i;
-const PLANNED = /\b(?:plans?|planned|planning|proposed|intended|expected|ideas?|goals?|draft|to-?dos?|next|later|someday|old|previous|history|example)\b/i;
+const PLANNED = /\b(?:plans?|planned|planning|proposed|intended|expected|ideas?|goals?|draft|to[- ]?dos?|next|later|someday|old|previous|history|example)\b/i;
 const CURRENT_HEADING = /^(?:handoff|state|status|now|current)\b(?!-)/i;
 const PREAMBLE = /^(?:if|unless|once|after|when|until|yesterday|old note|example|suppose|imagine)\b/i;
 const UNCERTAIN = /\b(?:probably|maybe|might|should|could|would|if|unless|when|until|need|get|think|believe|locally|re-?opened)\b|\bonce\s+(?!at\b)\S|n['’]t\b|\bby\s+(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday|tomorrow|next)\b/i;
@@ -95,9 +99,14 @@ function unquoted(raw) {
   return result;
 }
 
+// "#12 open, thank once on merge": once mid-field in a later comma field belongs to that step, not to the state before it.
+// Keep the field's other uncertainty words, and conditions naming a reference or narrowed by "only".
+const LATER_STEP_ONCE = /,\s*[^,]*?\S\s+once\s[^,]*/g;
+const laterStep = (field) => (field.includes('#') || /\b(?:only|just|not|except|unless)\b/i.test(field) ? field : field.replace(/\bonce\b/i, ''));
+
 function claimsFromClause(quote, line) {
   const body = unquoted(quote);
-  if (!body.includes('#') || body.includes('?') || UNCERTAIN.test(body) || NONSTATE.test(body)) return [];
+  if (!body.includes('#') || body.includes('?') || UNCERTAIN.test(body.replace(LATER_STEP_ONCE, laterStep)) || NONSTATE.test(body)) return [];
   const claims = [];
   const add = (tokens, said) => {
     for (const token of tokens) {
@@ -167,6 +176,15 @@ function claimsFromClause(quote, line) {
     }
     afterComma = delimiter === ',';
   }
+  const queued = QUEUED.exec(body.trim().replace(/[.!]$/, ''));
+  if (queued) {
+    const rest = queued[2].trim();
+    const wait = /^(?:,\s*|and\s+)/i.test(rest) ? WAIT.exec(rest.replace(/^(?:,\s*|and\s+)/i, '')) : null;
+    const claim = makeClaim(queued[1], 'queued', quote, line);
+    // An existing state or self-wait is more specific; avoid two looks for it.
+    if ((!rest || wait?.index === 0) && claim && !claims.some((c) =>
+      c.ref.owner === claim.ref.owner && c.ref.repo === claim.ref.repo && c.ref.number === claim.ref.number)) claims.unshift(claim);
+  }
   return claims;
 }
 
@@ -189,10 +207,10 @@ function closes(lines, from, open) {
 
 // Aliases and the default repository are resolved by the reader. Preserve the
 // identity written in the note, including refs that the reader cannot place.
-export function extractClaims(text, _options = {}) {
+export function extractClaims(text, options = {}) {
   const claims = [];
   let paragraph = [], fence = null, quote = null, comment = false, sections = [], frontMatter = false, titled = false, planned = null;
-  const flush = () => {
+  const flush = (keepLabel = false) => {
     // A wrapped condition, quotation or historical preamble can change the
     // following line. Separate list items may contain independent nonclaims.
     const blocks = (entry) => entry && !entry.claims.length && !entry.list;
@@ -207,18 +225,22 @@ export function extractClaims(text, _options = {}) {
       const after = paragraph[i + 1]; // A planning item says nothing of the line before it.
       if (!blocks(paragraph[i - 1]) && (!blocks(after) || after.parent)) claims.push(...entry.claims);
     });
-    paragraph = [];
+    // Quote boundaries separate claims without ending a historical label's scope.
+    paragraph = keepLabel && old >= 0 ? [paragraph[old]] : [];
   };
-  const enterSection = (level, title) => {
+  // The file's level 1 title above a current section does not switch it off.
+  const readable = () => sections.every((section, i) => section.current || (section.title && i < sections.length - 1));
+  const enterSection = (level, title, name = title) => {
     sections = sections.filter((section) => section.level < level);
     // Unknown headings may introduce plans, examples or history. Only a
     // current section (and current ancestors) permits extraction.
     sections.push({ level, current: CURRENT_HEADING.test(title), title: level === 1 && !titled && !/^(?:history|archive|old)\b/i.test(title) });
     titled ||= level === 1;
+    if (!readable()) options.skipped?.push(name);
   };
 
   const lines = text.replace(/^\uFEFF/, '').split(/\r\n|\n|\r/);
-  for (const [index, raw] of lines.entries()) {
+  for (let [index, raw] of lines.entries()) {
     if (index === 0 && /^---\s*$/.test(raw)) {
       frontMatter = true;
       continue;
@@ -232,11 +254,30 @@ export function extractClaims(text, _options = {}) {
       if (close && close[1][0] === fence[0] && close[1].length >= fence.length) fence = null;
       continue;
     }
+    // A comment closed on its own line leaves the text around it, so it cannot cost a planning item its scope.
+    if (!comment) {
+      const bare = raw.replace(/<!--.*?-->/g, '');
+      if (bare !== raw && !bare.trim()) continue; // A comment alone on its line is not the blank line that ends a scope.
+      raw = bare;
+      if (quote === null && /^ {0,3}(?:(?:[-+*]|[0-9]+[.)])\s+)*>/.test(raw)) {
+        // End the preceding paragraph, but keep an unmarked prose continuation quoted.
+        flush(true);
+        paragraph.push({ claims: [], list: false, indent: Infinity, blockquote: true });
+        continue;
+      }
+    }
     if (comment || raw.includes('<!--')) {
       comment = !raw.includes('-->') || raw.lastIndexOf('<!--') > raw.lastIndexOf('-->');
       paragraph.push({ claims: [], list: false, indent: Infinity });
       continue;
     }
+    // Fenced examples do not contain headings, even within a quotation.
+    const opening = /^ {0,3}(`{3,}|~{3,})/.exec(raw);
+    if (opening) {
+      flush();
+      fence = opening[1];
+      continue;
+    }
     const quoted = quote !== null;
     quote = endQuote(raw, quote);
     // A mark inside text that nothing closes was a stray.
@@ -250,36 +291,37 @@ export function extractClaims(text, _options = {}) {
       paragraph.push({ claims: [], list: false, indent: Infinity });
       continue;
     }
-    const opening = /^ {0,3}(`{3,}|~{3,})/.exec(raw);
     const heading = /^ {0,3}(#{1,6})\s+(.+?)(?:\s+#+)?\s*$/.exec(raw);
     const underline = /^ {0,3}(=+|-+)\s*$/.exec(raw);
-    if (opening) {
-      flush();
-      fence = opening[1];
-    } else if (heading) {
+    if (heading) {
       flush();
       enterSection(heading[1].length, heading[2]);
     } else if (underline && paragraph.length && !(underline[1][0] === '-' && paragraph.some((entry) => entry.item))) {
-      const title = paragraph.length === 1 ? lines[index - 1].trim() : '';
+      const title = paragraph.map((entry) => entry.text).filter(Boolean).join(' ');
+      // Preserve the conservative reading of multiline headings while naming them.
+      const currentTitle = paragraph.length === 1 ? lines[index - 1].trim() : '';
       paragraph = [];
-      enterSection(underline[1][0] === '=' ? 1 : 2, title);
+      enterSection(underline[1][0] === '=' ? 1 : 2, currentTitle, title);
     } else if (underline && paragraph.length) {
       flush(); // A rule after a list item, not a heading underline.
     } else if (!raw.trim()) {
       flush();
     } else {
-      // The file's level 1 title above a current section does not switch it off.
-      const readable = sections.every((section, i) => section.current || (section.title && i < sections.length - 1));
-      const claims = readable ? claimsFromLine(raw, index + 1) : [];
+      const claims = readable() ? claimsFromLine(raw, index + 1) : [];
       const body = raw.trim().replace(/^(?:[-+*]|[0-9]+[.)])\s+/, '');
       const label = /:\s*$/.test(raw) && PREAMBLE.test(body);
       const bare = body.replace(/[*_`]/g, '');
       const item = /^\s*(?:[-+*]|[0-9]+[.)])\s+/.test(raw);
+      if (item && paragraph.at(-1)?.blockquote) flush(true); // A new list is not a quote continuation.
+      if (!item && paragraph.at(-1)?.blockquote) { // Every unmarked line of a quoted paragraph stays in the quote.
+        paragraph.push({ claims: [], list: false, indent: Infinity, blockquote: true });
+        continue;
+      }
       const colon = /:\s*$/.test(bare);
       const parent = item && colon && PLANNED.test(bare);
       // A list item that opens a current list does not silence its first child.
       const list = item && (!colon || CURRENT_HEADING.test(bare));
-      paragraph.push({ claims, list, item, label, parent, indent: /^\s*/.exec(raw)[0].length });
+      paragraph.push({ claims, list, item, label, parent, text: raw.trim(), indent: /^\s*/.exec(raw)[0].length });
     }
   }
   flush();

package/src/github.mjs

@@ -23,10 +23,11 @@ export async function readState({ owner, repo, number }, { fetchFn = fetch, toke
   const d = await res.json();
   if (d.state !== 'open' && d.state !== 'closed') throw new Error(`GitHub gave no state for ${owner}/${repo}#${number}`);
   const url = d.html_url;
+  const reason = typeof d.state_reason === 'string' && d.state_reason ? { state_reason: d.state_reason } : {};
   if (d.pull_request) {
     const merged = d.pull_request.merged_at;
-    if (merged) return { state: 'merged', kind: 'pull', at: merged, url };
-    return { state: d.state, kind: 'pull', at: d.closed_at ?? d.updated_at ?? null, url };
+    if (merged) return { state: 'merged', kind: 'pull', at: merged, url, ...reason };
+    return { state: d.state, kind: 'pull', at: d.closed_at ?? d.updated_at ?? null, url, ...reason };
   }
-  return { state: d.state, kind: 'issue', at: d.closed_at ?? d.created_at ?? null, url };
+  return { state: d.state, kind: 'issue', at: d.closed_at ?? d.created_at ?? null, url, ...reason };
 }