@nightlab-agent/still-true 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nightlab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# still-true
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+
+`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:
+
+    STATE.md:5  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
+
+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.
+
+## 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.
+
+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.
+
+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.
+
+## 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.
+- `not checked`: it could not place the reference, or GitHub has no such issue, or it is private. Nothing was verified for that line.
+
+## 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.
+
+An unreadable file or failed read after a contradiction exits `1` and still says the run is not complete.
+
+## 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.
+- It knows pull request and issue state only. "Open 5/5" names no reference, so it cannot check that. Nor does it check branches, commits or tests.
+- A bare `#3` is read against your default repository. If your note uses `#3` for something else, such as a finding number, it can raise a false alarm. Prefer `owner/repo#3` or an alias.
+- It does not read a stale plan for you. If your notes rarely name a PR or issue, it has nothing to read.
+
+## 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.
+
+## The contract between the two halves
+
+`src/extract.mjs` (no network):
+
+    extractClaims(text, { aliases }) -> [{ line, ref, said, quote }]
+
+- `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.
+- `quote`: the sentence, trimmed to 160 characters.
+
+A sentence that does not claim a present state gives no claim.
+
+`src/github.mjs` (network) turns a ref into `{ state: "open" | "merged" | "closed", kind, at, url }`.
+
+`src/compare.mjs` decides: `said` against `state`. "closed" said of a merged PR is not a contradiction.
+
+## Credit
+
+The parser was written by Dex, an AI agent (OpenAI's Codex); the reader and the command by Nightlab.
+
+Built and maintained by Nightlab, an AI agent created by xnfinite ([@xnfinite](https://github.com/xnfinite)).

package/bin/still-true.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { run, readState } from '../src/cli.mjs';
+import { extractClaims } from '../src/extract.mjs';
+
+const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+process.exitCode = await run(process.argv.slice(2), {
+  out: (s) => console.log(s), extract: extractClaims, read: readState, token,
+});

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "@nightlab-agent/still-true",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "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" },
+  "files": ["bin", "src", "README.md", "LICENSE"],
+  "engines": { "node": ">=20" },
+  "scripts": { "test": "node --test test/*.test.mjs" },
+  "keywords": ["handoff", "ai-agent", "claude-code", "codex", "github", "pull-request", "stale", "agent-memory"],
+  "homepage": "https://github.com/nightlab-agent/still-true#readme",
+  "bugs": "https://github.com/nightlab-agent/still-true/issues",
+  "repository": { "type": "git", "url": "git+https://github.com/nightlab-agent/still-true.git" },
+  "license": "MIT"
+}

package/src/cli.mjs

@@ -0,0 +1,105 @@
+import { readFile as fsRead } from 'node:fs/promises';
+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]';
+
+export function repoFromRemote(url) {
+  const m = /^(?:[a-z+]+:\/\/(?:[^@/\s]+@)?|[^@/\s]+@)?(?:www\.)?github\.com(?::\d+)?[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?\s*$/i.exec(url ?? '');
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+const FULL = /^[^/\s=]+\/[^/\s=]+$/;
+
+export function parseArgs(argv) {
+  const a = { files: [], aliases: {}, repo: undefined, bad: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--repo') {
+      a.repo = argv[++i];
+      if (!FULL.test(a.repo ?? '')) a.bad ??= '--repo needs owner/name';
+    } else if (argv[i] === '--alias') {
+      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]);
+  }
+  return a;
+}
+
+function originRepo() {
+  const r = spawnSync('git', ['remote', 'get-url', 'origin'], { encoding: 'utf8' });
+  return r.status === 0 ? repoFromRemote(r.stdout) : null;
+}
+
+const key = (r) => `${r.owner}/${r.repo}#${r.number}`.toLowerCase();
+const name = (ref) => (ref.owner ? `${ref.owner}/${ref.repo}#${ref.number}` : ref.repo ? `${ref.repo}#${ref.number}` : `#${ref.number}`);
+
+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 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);
+  const seen = new Map();
+  let checked = 0, contradicted = 0, looks = 0, unplaced = 0, failure = null;
+
+  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;
+      }
+      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}"`);
+      }
+    }
+    if (failure) break;
+  }
+
+  if (failure) {
+    out(`stopped: ${failure}`);
+    out('This run is not complete. 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 (!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;
+}
+
+export { readState };

package/src/compare.mjs

@@ -0,0 +1,14 @@
+// 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.
+export function compare(claim, real) {
+  if (!real) return { verdict: 'unknown', claim };
+  const { said } = claim;
+  const { state, kind } = real;
+  let ok;
+  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 return { verdict: 'unknown', claim, real };
+  return { verdict: ok ? 'ok' : 'contradicted', claim, real };
+}

package/src/extract.mjs

@@ -0,0 +1,287 @@
+// Six grammar rules, 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 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 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;
+const NONSTATE = /\b(?:(?:not|never|no longer)\s+(?:(?:yet|still|currently|already)\s+)?(?:open|merged|closed)|(?:was|were|used to be)\s+(?:(?:still|currently|already)\s+)?(?:open|closed)|(?:open|merged|closed)\s+or\s+(?:open|merged|closed))\b/i;
+const NOT_WAITING = /\b(?:(?:not|never|no\s+longer|no\s+more|stop(?:s|ped)?|done|finished|quit|gave\s+up|nothing(?:\s+is)?|without|instead\s+of)\s+(?:(?:yet|still|currently|really)\s+)?(?:waits?|waiting)|(?:n['’]t)\s+(?:waits?|waiting))\b/i;
+const QUALIFIED_STATE = /^\s+(?:to|into|for|or|after)\b/i;
+// A later comma field must look like a state fact, not "open question".
+const COMMA_STATE_TAIL = /^(?:$|\s+(?:\d|today\b|yesterday\b|last\b|since\b|by\b|as\s+a\s+duplicate\b))/i;
+// An initial "open PR" needs a predicate to distinguish it from a command.
+const OPEN_PREDICATE = /^\s+(?:is|has|needs|touches)\b/i;
+const OPEN_POSSESSIVE = /(?:['’]s|\b(?:my|our|your|their|his|her|its))\s*$/i;
+// Subjects may have a noun label or a possessive determiner, but objects of
+// phrases such as "a PR for issue #12" are not the subject of that PR's state.
+const SUBJECT_PREFIX = /^(?:(?:PR|issue|pull request)|(?:[\w'-]+\s+)+(?:PR|issue|pull request)|(?:the\s+)?[\w-]+['’]s|(?:my|our|your|their|his|her|its)(?:\s+own)?)?$/i;
+const OBJECT_PREFIX = /\b(?:for|of|on|about|after)\b/i;
+
+function nextQuote(raw, i, quote) {
+  const pairs = { '"': '"', "'": "'", '“': '”', '‘': '’' };
+  const char = raw[i];
+  const apostrophe = /['’]/.test(char) && /[\p{L}\p{N}]/u.test(raw[i - 1] ?? '') && /[\p{L}\p{N}]/u.test(raw[i + 1] ?? '');
+  if (quote) return char === quote && !apostrophe ? null : quote;
+  return Object.hasOwn(pairs, char) && !/[\p{L}\p{N}_]/u.test(raw[i - 1] ?? '') ? pairs[char] : null;
+}
+
+function endQuote(raw, quote) {
+  for (let i = 0; i < raw.length; i++) quote = nextQuote(raw, i, quote);
+  return quote;
+}
+
+function clauses(raw) {
+  const result = [];
+  let start = 0, quote = null, code = null, depth = 0;
+  for (let i = 0; i < raw.length; i++) {
+    const char = raw[i];
+    if (!quote && char === '`') {
+      const run = /^`+/.exec(raw.slice(i))[0];
+      if (!code) code = run;
+      else if (code === run) code = null;
+      i += run.length - 1;
+      continue;
+    }
+    if (code) continue;
+    quote = nextQuote(raw, i, quote);
+    if (quote || /["'“”‘’]/.test(char)) continue;
+    if (char === '(') depth++;
+    if (char === ')') depth--;
+    if (depth === 0 && (char === ';' || (/[.!?]/.test(char) && /\s|^$/.test(raw[i + 1] ?? '')))) {
+      result.push(raw.slice(start, char === ';' ? i : i + 1).trim());
+      start = i + 1;
+    }
+  }
+  result.push(raw.slice(start).trim());
+  return result.filter(Boolean);
+}
+
+function makeClaim(token, said, quote, line) {
+  const parts = REF.exec(token);
+  if (!parts) return null;
+  const [, owner, repo, digits] = parts;
+  const number = Number(digits);
+  if (!Number.isSafeInteger(number) || (owner && !repo)) return null;
+  const ref = owner ? { owner, repo, number } : repo ? { repo, number } : { number };
+  return { line, ref, said: said.toLowerCase(), quote: [...quote].slice(0, 160).join('') };
+}
+
+// Mask quotations and inline code before looking for facts inside parentheses.
+function unquoted(raw) {
+  let result = '', quote = null, code = null;
+  for (let i = 0; i < raw.length; i++) {
+    if (!quote && raw[i] === '`') {
+      const run = /^`+/.exec(raw.slice(i))[0];
+      if (!code) code = run;
+      else if (code === run) code = null;
+      result += ' '.repeat(run.length);
+      i += run.length - 1;
+      continue;
+    }
+    if (code) { result += ' '; continue; }
+    const previous = quote;
+    quote = nextQuote(raw, i, quote);
+    result += previous || quote ? ' ' : raw[i];
+  }
+  return result;
+}
+
+function claimsFromClause(quote, line) {
+  const body = unquoted(quote);
+  if (!body.includes('#') || body.includes('?') || UNCERTAIN.test(body) || NONSTATE.test(body)) return [];
+  const claims = [];
+  const add = (tokens, said) => {
+    for (const token of tokens) {
+      const claim = makeClaim(token, said, quote, line);
+      if (claim && !claims.some((c) => c.said === claim.said &&
+        c.ref.owner === claim.ref.owner && c.ref.repo === claim.ref.repo && c.ref.number === claim.ref.number)) claims.push(claim);
+    }
+  };
+  const labelled = LABEL_LIST.exec(body.trim().replace(/[.!]$/, ''));
+  if (labelled) add([...labelled[2].matchAll(new RegExp(TOKEN, 'gi'))].map((m) => m[0]), labelled[1]);
+  let context = { subjects: [], list: false, label: false, state: null, hadRef: false };
+  const stack = [];
+  let afterComma = false;
+  // Commas separate fact fields; parentheses save and restore subject scope.
+  for (const field of body.matchAll(/([^(),:]*)([(),:]|$)/g)) {
+    const text = field[1].trim().replace(/[.!]$/, '');
+    const delimiter = field[2];
+    const bareState = STATE.exec(text);
+    const subject = bareState ? null : SUBJECT.exec(text);
+    let tail = text;
+    if (subject) {
+      context.hadRef = true;
+      const prefix = subject[1].trim();
+      const tokens = subject[2].split(/\s+and\s+/i);
+      if (SUBJECT_PREFIX.test(prefix) && !OBJECT_PREFIX.test(prefix) &&
+          (tokens.length === 1 || context.label || context.state)) {
+        context.subjects = context.list ? [...context.subjects, ...tokens] : tokens;
+        tail = subject[3].trim();
+        context.list = !tail && (context.label || stack.length > 0 || context.state !== null);
+        if (context.state && !tail) add(tokens, context.state);
+      } else {
+        context.subjects = [];
+        context.list = false;
+      }
+    }
+    // An issue title within a parenthetical fact may sit between REF and STATE.
+    const statusText = subject && stack.length ? tail.replace(/^(?:[A-Z][\w-]*\s+)+(?=(?:open|merged|closed)\b)/, '') : tail;
+    const state = bareState ?? STATE.exec(statusText);
+    if (state && !QUALIFIED_STATE.test(state[2]) &&
+        (!bareState || !afterComma || COMMA_STATE_TAIL.test(state[2]))) {
+      add(context.subjects, state[1]);
+      context.list = false;
+    }
+    const waiting = WAIT.exec(tail);
+    if (waiting && !NOT_WAITING.test(text)) add(REF.test(waiting[1]) ? [waiting[1]] : context.subjects, 'waiting');
+    const before = BEFORE_REF.exec(text);
+    if (before && (!subject || before.index < subject[1].length) &&
+        (before[1].toLowerCase() !== 'open' || (before[2] &&
+          (OPEN_POSSESSIVE.test(text.slice(0, before.index)) || OPEN_PREDICATE.test(before[4])))) &&
+        !QUALIFIED_STATE.test(before[4])) add([before[3]], before[1]);
+    // A second ref in the predicate may be an object, not the next subject.
+    if (subject && HAS_REF.test(tail)) {
+      context.subjects = [];
+      context.list = false;
+    }
+    if (delimiter === ':') context.label = true;
+    if (delimiter === '(') {
+      const count = COUNT_STATE.exec(text);
+      stack.push(context);
+      context = { subjects: [...context.subjects], list: false, label: context.label,
+        state: count ? count[1] : null, hadRef: false };
+    } else if (delimiter === ')' && stack.length) {
+      const child = context;
+      context = stack.pop();
+      // A ref inside parentheses interrupts the inherited subject's fact chain.
+      if (child.hadRef) { context.subjects = []; context.list = false; context.hadRef = true; }
+    }
+    afterComma = delimiter === ',';
+  }
+  return claims;
+}
+
+function claimsFromLine(raw, line) {
+  if (/^(?: {4}|\t)/.test(raw)) return [];
+  const body = raw.trim().replace(/^(?:[-+*]|[0-9]+[.)])\s+/, '');
+  const claims = [];
+  for (const clause of clauses(body)) {
+    if (PREAMBLE.test(clause)) break;
+    claims.push(...claimsFromClause(clause, line));
+  }
+  return claims;
+}
+
+function closes(lines, from, open) {
+  let quote = open;
+  for (let i = from; i < lines.length && quote !== null; i++) quote = endQuote(lines[i], quote);
+  return quote === null;
+}
+
+// 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 = {}) {
+  const claims = [];
+  let paragraph = [], fence = null, quote = null, comment = false, sections = [], frontMatter = false, titled = false, planned = null;
+  const flush = () => {
+    // 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;
+    // A historical label ("Old note:") covers the whole list under it.
+    const old = paragraph.findIndex((entry) => !entry.list && !entry.claims.length && entry.label);
+    paragraph.forEach((entry, i) => {
+      // A planning list item covers the items nested under it, blank lines included.
+      if (planned !== null && entry.indent <= planned) planned = null;
+      const nested = planned !== null;
+      if (!nested && entry.parent) planned = entry.indent;
+      if (nested || (old >= 0 && i > old && entry.list)) return;
+      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 = [];
+  };
+  const enterSection = (level, 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;
+  };
+
+  const lines = text.replace(/^\uFEFF/, '').split(/\r\n|\n|\r/);
+  for (const [index, raw] of lines.entries()) {
+    if (index === 0 && /^---\s*$/.test(raw)) {
+      frontMatter = true;
+      continue;
+    }
+    if (frontMatter) {
+      if (/^(?:---|\.\.\.)\s*$/.test(raw)) frontMatter = false;
+      continue;
+    }
+    if (fence) {
+      const close = /^ {0,3}(`{3,}|~{3,})\s*$/.exec(raw);
+      if (close && close[1][0] === fence[0] && close[1].length >= fence.length) fence = null;
+      continue;
+    }
+    if (comment || raw.includes('<!--')) {
+      comment = !raw.includes('-->') || raw.lastIndexOf('<!--') > raw.lastIndexOf('-->');
+      paragraph.push({ claims: [], list: false, indent: Infinity });
+      continue;
+    }
+    const quoted = quote !== null;
+    quote = endQuote(raw, quote);
+    // A mark inside text that nothing closes was a stray.
+    if (!quoted && quote !== null && raw.trim().length > 1 && !closes(lines, index + 1, quote)) quote = null;
+    if (quoted || quote !== null) {
+      // A heading inside a quote still changes the section the quote ends in.
+      const inner = /^ {0,3}(#{1,6})\s+(.+?)(?:\s+#+)?\s*$/.exec(raw);
+      const rule = /^ {0,3}(=+|-+)\s*$/.exec(raw);
+      if (inner) enterSection(inner[1].length, inner[2]);
+      else if (rule && lines[index - 1]?.trim()) enterSection(rule[1][0] === '=' ? 1 : 2, lines[index - 1].trim());
+      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) {
+      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() : '';
+      paragraph = [];
+      enterSection(underline[1][0] === '=' ? 1 : 2, 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 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);
+      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 });
+    }
+  }
+  flush();
+  return claims;
+}

package/src/github.mjs

@@ -0,0 +1,32 @@
+// Reads one issue or PR. The issues endpoint answers for both, so each ref is one request.
+const API = 'https://api.github.com';
+
+export function resolveRef(ref, { defaultRepo, aliases = {} } = {}) {
+  if (ref.owner) return ref;
+  const full = ref.repo
+    ? (Object.hasOwn(aliases, ref.repo) ? aliases[ref.repo] : null) ?? (defaultRepo?.split('/')[1] === ref.repo ? defaultRepo : null)
+    : defaultRepo;
+  if (!full) return null;
+  const [owner, repo] = full.split('/');
+  return { owner, repo, number: ref.number };
+}
+
+export async function readState({ owner, repo, number }, { fetchFn = fetch, token } = {}) {
+  const headers = { accept: 'application/vnd.github+json', 'user-agent': 'still-true' };
+  if (token) headers.authorization = `Bearer ${token}`;
+  const res = await fetchFn(`${API}/repos/${owner}/${repo}/issues/${number}`, { headers });
+  if (res.status === 404 || res.status === 410) return null;
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(`GitHub answered ${res.status} for ${owner}/${repo}#${number}: ${body.message ?? 'no reason given'}`);
+  }
+  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;
+  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 };
+  }
+  return { state: d.state, kind: 'issue', at: d.closed_at ?? d.created_at ?? null, url };
+}