@assuredloop/cli 0.2.4 → 2.0.0

package/src/v4/commands.js

@@ -107,11 +107,13 @@ function recordOrigin({ top, cwd, args, opts }) {
   return { body: [`Wrote ${dir}/origin/${file} and source ${file} in ${rec.path}`], next: `name it in a requirement's marker: <!-- R<n> from:${file} -->` };
 }
 
-// al record <name> signoff --source <where> [--words <quote>] [--presented <x>] [--transcribed-by <who>] [--yes]
+// al record <name> signoff --source <where> --words <quote> [--presented <x>] [--transcribed-by <who>] [--yes]
 function recordSignoff({ top, args, opts }) {
   const [name] = args;
   oneLine(opts, ['source', 'words', 'presented', 'transcribed-by']);
   if (!opts.source) throw new Fail('--source <where the owner signed> is missing', `al record ${name} signoff --source <where> --words <quote>`);
+  // A sign-off with no words is not valid in al check (DES-89, D10).
+  if (typeof opts.words !== 'string' || !opts.words) throw new Fail('--words <the owner\'s words> is missing', `pass the owner's words: al record ${name} signoff --source <where> --words <quote>`);
   const { dir, rec } = openRequest(top, name);
   const md = read(top, `${dir}/request.md`);
   const text = signedText(md);

package/src/v4/conclude.js

@@ -6,7 +6,7 @@
 // change of the branch, against the merge-base with main, counts as al check
 // counts it (branchOf, #217). With
 // --yes it writes the Outcome, sets the status and archives the request.
-import { mkdirSync, renameSync } from 'node:fs';
+import { mkdirSync, renameSync, statSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { Fail, day, exists, guard, isName, now, write } from './base.js';
 import { branchOf } from './checks.js';
@@ -112,13 +112,17 @@ export function conclude({ top, args, opts }) {
   const block = outcome(state, r, judged, top);
   const target = `requests/archive/${name}`;
   if (exists(top, target)) throw new Fail(`${target} already exists; a request name is never reused`, `al context ${name}`);
+  // The preview refuses for each reason that --yes refuses (#241).
+  const rec = openRecord(top, name);
+  if (!rec) throw new Fail(`${name} has no record .assuredloop/records/requests/${name}.yaml`, 'a v4 request is made with al new');
+  guard(top, [`${r.dir}/request.md`, `${target}/request.md`, rec.path]);
+  if (statSync(join(top, dirname(target)), { throwIfNoEntry: false })?.isDirectory() === false) {
+    throw new Fail(`${dirname(target)} is not a folder; nothing was written`, `make ${dirname(target)} a folder, then al conclude ${name} again`);
+  }
   const what = `Status: concluded, the Outcome in ${target}/request.md, status: concluded in the record, and ${r.dir}/ moved to ${target}/`;
   if (!opts.yes) {
     return { body: [`Would conclude ${name}: ${what}`, ...block.slice(2).map((l) => `  ${l}`)], read, next: 'run the same command with --yes to do it', notKnown };
   }
-  const rec = openRecord(top, name);
-  if (!rec) throw new Fail(`${name} has no record .assuredloop/records/requests/${name}.yaml`, 'a v4 request is made with al new');
-  guard(top, [`${r.dir}/request.md`, `${target}/request.md`, rec.path]);
   const md = withOutcome(withStatus(r.md), block);
   rec.doc.set('status', 'concluded');
   mkdirSync(dirname(join(top, target)), { recursive: true });

package/src/v4/indexer.js

@@ -2,11 +2,10 @@
 // with the agents' hints kept), appends requirement versions, freezes the
 // bindings of new links and fills the hashes of new dispositions. Ordinary
 // indexing never advances a binding; only --align does (design.md 4, 10).
-import { readdirSync } from 'node:fs';
+import { accessSync, constants, lstatSync, readdirSync } from 'node:fs';
 import { join, posix } from 'node:path';
 import { isMap, parse, stringify } from 'yaml';
 import { parseMarkdown } from './markers.js';
-import { diffParagraphs } from './ids.js';
 import { git, mergeBase, fileAt, filesAt } from './git.js';
 import { loadConfig } from './config.js';
 import { SPEC, docsInScope, symlinkOn } from './scope.js';
@@ -110,6 +109,9 @@ export const isCentral = (config) => Array.isArray(config.outputs) && config.out
 // An output in another repo (T12): its repo is named, and is not this one.
 const foreign = (o, config) => Boolean(o.repo) && o.repo !== config.repo && o.repo !== 'central';
 
+// A record's declared outputs; a value that is not a list declares none, so al check still runs (#2).
+const outputsOf = (r) => (Array.isArray(r.data?.outputs) ? r.data.outputs : []);
+
 // Every declared link of a state: { holder, holderSha, link, target, homes }, with
 // `homes` the requests whose record holds it. An output in another repo also
 // has `commit` (<repo>@<sha>), or `unknown` with the reason; `repos` are the
@@ -120,7 +122,7 @@ function linksOf(top, state, config, live, repos = new Map()) {
   const batches = new Map();
   const outputFiles = (repo) => {
     if (!batches.has(repo.name)) {
-      const files = [...state.requests.values()].filter((r) => r.open).flatMap((r) => r.data?.outputs ?? [])
+      const files = [...state.requests.values()].filter((r) => r.open).flatMap(outputsOf)
         .filter((o) => o?.file && o.repo === repo.name).map((o) => String(o.file));
       batches.set(repo.name, filesAt(repo.dir, repo.sha, [...new Set(files)], null));
     }
@@ -140,7 +142,7 @@ function linksOf(top, state, config, live, repos = new Map()) {
       for (const f of q.from) out.push({ holder: `${r.name}/${q.id}`, holderSha: q.sha256, link: 'from', target: `${r.name}/${f}`, t: { req: r.name, id: f }, homes: [r.name] });
     }
     const own = new Set(r.paras.keys());
-    for (const o of r.data?.outputs ?? []) {
+    for (const o of outputsOf(r)) {
       if (!o?.file) continue;
       const other = foreign(o, config);
       const repo = other ? repos.get(o.repo) : null;
@@ -186,6 +188,76 @@ export function targetOf(t, state) {
 const tripleKey = (l) => `${l.holder}\t${l.link}\t${l.target}`;
 const short = (h) => (h ? h.slice(0, 12) : 'unknown');
 
+// Whether a binding's holder declares its link now: the same holder, link
+// word and target (#2). It reads al check's own state (state.js), so each
+// file is read once, by al check's rules.
+export function declaredNow(top, state) {
+  const docs = [
+    { request: null, ids: new Set(), paragraphs: [...state.spec.values()].filter((p) => p.id) },
+    ...[...state.requests.values()].filter((r) => r.open).map((r) => ({ request: r.name, ids: new Set(r.paras.keys()), paragraphs: [...r.paras.values()].filter((p) => p.id) })),
+    ...[...state.adrs.values()].map((a) => ({ request: null, ids: new Set(), paragraphs: a.paragraphs.filter((p) => p.id) })),
+  ];
+  const keys = new Set(linksOf(top, { docs, requests: state.requests }, state.config, false).map(tripleKey));
+  return (b) => keys.has(tripleKey(b));
+}
+
+// Whether al index --align can move a binding to `target` now, by its own
+// target rules, in al check's state (state.js): holder-changed names --align
+// only where it works (#11).
+export function canAlignTo(state) {
+  const adrs = [...state.adrs.values()].flatMap((a) => a.paragraphs.filter((p) => p.id).map((p) => [p.id, p]));
+  const view = { spec: new Map([...state.spec, ...adrs]), requests: state.requests };
+  const central = isCentral(state.config);
+  return (target) => Boolean(targetOf(qualify(String(target), null, new Set(), central), view));
+}
+
+// A state whose archived requests declare their links too: their change
+// specs' markers, their requirements' from: and their records' outputs: (#11).
+function everyDeclaration(state) {
+  const old = [...state.requests.values()].filter((r) => !r.open);
+  return {
+    docs: [...state.docs, ...old.map((r) => ({ request: r.name, ids: new Set(r.paras.keys()), paragraphs: [...r.paras.values()] }))],
+    requests: new Map([...state.requests].map(([n, r]) => [n, { ...r, open: true }])),
+  };
+}
+
+// The files and folders that can declare links but are not read, each with
+// why: reached through a symlink, a file that cannot be read, or a folder that
+// cannot be listed. They are the spec root's, the requests' (open and
+// archived) request.md, spec.md and record, whose outputs: declare links, and
+// the docs that config lists (#11).
+function notRead(top, root, config) {
+  const out = [];
+  const blocked = (p) => {
+    let stat;
+    try { stat = lstatSync(join(top, p)); } catch { return false; }
+    if (stat.isSymbolicLink()) { out.push(`${p}: through a symlink`); return true; }
+    try { accessSync(join(top, p), stat.isDirectory() ? constants.R_OK | constants.X_OK : constants.R_OK); } catch { out.push(`${p}: cannot be read`); return true; }
+    return false;
+  };
+  const tree = (dir) => {
+    if (blocked(dir)) return;
+    for (const e of list(top, dir)) {
+      if (e.isDirectory()) tree(`${dir}/${e.name}`);
+      else blocked(`${dir}/${e.name}`);
+    }
+  };
+  tree(root);
+  const records = !blocked('.assuredloop/records/requests');
+  for (const dir of ['requests', 'requests/archive']) {
+    if (blocked(dir)) continue;
+    for (const e of list(top, dir)) {
+      const d = `${dir}/${e.name}`;
+      if (d === 'requests/archive' || (!e.isDirectory() && !e.isSymbolicLink()) || blocked(d)) continue;
+      blocked(`${d}/request.md`);
+      blocked(`${d}/spec.md`);
+      if (records) blocked(recordPath(e.name));
+    }
+  }
+  for (const d of config.docs) blocked(posix.normalize(String(d.file)));
+  return out;
+}
+
 export function index({ top, opts }) {
   let loaded;
   try { loaded = loadConfig(top); } catch (e) { throw new Fail(e.message, 'fix .assuredloop/config.yaml'); }
@@ -240,13 +312,25 @@ export function index({ top, opts }) {
     if (!froms.has(align)) throw new Fail(`--align ${align}: no paragraph, requirement or output with that ID (a change spec's ID is <request>/<ID>)`, 'al index --align <ID>');
   }
 
+  // The records that already hold each binding: a holder whose marker names
+  // no request any more, such as a superseded ADR that dropped `source:`,
+  // still reaches the bindings it holds (#11).
+  const held = new Map();
+  for (const [n, rec] of recs) {
+    for (const it of rec.doc.get('bindings')?.items ?? []) {
+      if (!it?.get) continue;
+      const k = tripleKey({ holder: it.get('holder'), link: it.get('link'), target: it.get('target') });
+      held.set(k, [...(held.get(k) ?? []), n]);
+    }
+  }
+
   let bound = 0;
   const seen = new Set();
   const once = (line) => { if (!seen.has(line)) { seen.add(line); body.push(line); } };
   for (const l of links) {
     const name = `${l.holder} ${l.link} ${l.target}`;
     if (l.t.cross) { once(`not bound: ${name}: cross-repo`); continue; }
-    const homes = l.homes.filter((h) => recs.has(h));
+    const homes = [...new Set([...l.homes.filter((h) => recs.has(h)), ...(held.get(tripleKey(l)) ?? [])])];
     if (!homes.length) { once(`not bound: ${name}: no request record holds it`); continue; }
     const aligning = align !== undefined && l.holder === align;
     for (const h of homes) {
@@ -277,6 +361,33 @@ export function index({ top, opts }) {
     }
   }
 
+  // Removed links (removed-links/R1, #11): a binding whose link no current
+  // marker, requirement or outputs: entry declares is removed from the records
+  // of the open and the archived requests, and named. An archived change spec
+  // and request.md still declare their links. While a file that can declare
+  // links is not read, nothing is removed: a missing file is not a removed link.
+  const archived = new Map();
+  for (const n of names.archived) {
+    try { const rec = openRecord(top, n); if (rec) archived.set(n, rec); } catch (e) { if (!e.invalid) throw e; notes.push(`not read: ${e.message}`); }
+  }
+  const unread = [...new Set([
+    ...notes.filter((l) => /^not (indexed|read): /.test(l)).map((l) => l.replace(/^not (indexed|read): /, '')),
+    ...notRead(top, root, config),
+  ])];
+  const declared = new Set(linksOf(top, everyDeclaration(now), config, false).map(tripleKey));
+  const undeclared = (it) => it?.get && !declared.has(tripleKey({ holder: it.get('holder'), link: it.get('link'), target: it.get('target') }));
+  const dead = [...recs, ...archived].flatMap(([n, rec]) => (rec.doc.get('bindings')?.items ?? []).filter(undeclared).map((it) => [n, rec, it]));
+  if (unread.length) {
+    body.push(`not removed: no binding is removed in this run, as al index could not read ${unread.join('; ')}`);
+  } else {
+    for (const [n, rec, it] of dead) {
+      const items = rec.doc.get('bindings').items;
+      items.splice(items.indexOf(it), 1);
+      body.push(`removed: ${it.get('holder')} ${it.get('link')} ${it.get('target')} from the record of ${n}: no longer declared`);
+      rec.changed = true;
+    }
+  }
+
   // Dispositions: the hashes of the source version, and of the spec text it
   // produced, frozen when first indexed.
   for (const [n, rec] of recs) {
@@ -310,11 +421,8 @@ export function index({ top, opts }) {
   }
 
   // The per-doc records: regenerable fields, written fresh; hints kept by ID.
-  // A change spec's IDs are its request's own, so they are compared as <request>/<ID>.
-  const qualified = (docs) => docs.flatMap((d) => d.paragraphs.map((p) => (d.request ? { ...p, id: `${d.request}/${p.id}` } : p)));
-  const diffs = main ? diffParagraphs(qualified(loadState(top, main, config, names).docs), qualified(now.docs)) : null;
-  const own = (d, id) => (d.request ? `${d.request}/${id}` : id);
-  const changeOf = new Map((diffs ?? []).filter((x) => x.sha256 !== null).map((x) => [`${x.file}\t${x.id}`, x.changes]));
+  // Nothing in them depends on the branch or its base, so main's index
+  // rebuilds a merged record as it is (#245).
   const outputs = [];
   for (const d of now.docs) {
     const path = docRecordPath(d.file);
@@ -328,16 +436,14 @@ export function index({ top, opts }) {
     }
     const status = d.adr ? d.text.split('\n').find((l) => l.trim())?.match(/^Status:\s*([a-z]+)/i)?.[1].toLowerCase() : undefined;
     const paragraphs = d.paragraphs.map((p) => {
-      const change = changeOf.get(`${d.file}\t${own(d, p.id)}`) ?? [];
       const hint = hints.get(p.id);
       if (hint && stale(hint, p)) body.push(`refresh hint: ${d.file} ${p.id}`);
-      return { id: p.id, ...(p.kind ? { kind: p.kind } : {}), text_sha256: p.sha256, display: p.displayNumber, ...(change.length ? { change } : {}), ...(hint ? { hint } : {}) };
+      return { id: p.id, ...(p.kind ? { kind: p.kind } : {}), text_sha256: p.sha256, display: p.displayNumber, ...(hint ? { hint } : {}) };
     });
-    const removed = (diffs ?? []).filter((x) => x.sha256 === null && x.file === d.file).map((x) => (d.request ? x.id.slice(d.request.length + 1) : x.id));
-    const rec = { schema: SCHEMA, file: d.file, ...(status ? { status } : {}), paragraphs, ...(removed.length ? { removed } : {}) };
+    const rec = { schema: SCHEMA, file: d.file, ...(status ? { status } : {}), paragraphs };
     outputs.push([path, stringify(rec, YAML_OPTIONS)]);
   }
-  for (const [, rec] of recs) if (rec.changed) outputs.push([rec.path, recordText(rec)]);
+  for (const [, rec] of [...recs, ...archived]) if (rec.changed) outputs.push([rec.path, recordText(rec)]);
   guard(top, outputs.map(([path]) => path));
   const written = outputs.filter(([path, text]) => write(top, path, text)).map(([path]) => path);
 

package/src/v4/issues.js

@@ -0,0 +1,297 @@
+// Hints from the linked work items (issue-hints R1, design.md 8). `al` never
+// contacts a tracker (D9): the caller saves the items in a folder, and
+// `al check --issues <folder>` reads them. An item is the JSON that
+// `gh issue view --json number,url,body,comments,parent` prints, or the same
+// shape with `ref` and `repository` for another tracker (D10). Only the
+// items that the `tasks:` of the open requests name are checked (D11). Each
+// finding is a hint (R1, hints-and-blocks R2):
+// - issue-missing: a task names an item that is not in the folder;
+// - issue-superseded: the item's text names a superseded ADR without its
+//   successor, by R5's own code (supersededIn, D7);
+// - issue-bare-ref: a bare `#n` in an item of another repository;
+// - issue-not-sub: not a child of the request's own item, which the file
+//   assuredloop-requests.json of the folder names (own-item R1);
+// - phrase: a phrase of the config matches (R2, phrases.js);
+// - issue-unread: a file of the folder that is not valid JSON, or an entry
+//   that is not an item, or an assuredloop-requests.json that is not valid.
+// An item's text is its body and its comments that are not minimized (D4).
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { recordPath } from './base.js';
+import { citedMessage, supersededIn } from './blocks.js';
+import { git } from './git.js';
+import { phraseHits, phraseMessage } from './phrases.js';
+import { outputRepos } from './repos.js';
+import { Fail } from './spec.js';
+
+const ISSUE_URL = /\bhttps?:\/\/[^\s/]+\/([\w.-]+)\/([\w.-]+)\/issues\/(\d+)\b/g;
+const QUALIFIED = /(?<![\w./-])([\w.-]+)\/([\w.-]+)#(\d+)\b/g;
+const NAMED = /(?<![\w./#-])([a-z0-9][a-z0-9._-]*)#(\d+)\b/g;
+const BARE = /(?<![\w/#&-])#(\d+)\b/g;
+const slug = (s) => String(s).toLowerCase();
+const isMap = (x) => !!x && typeof x === 'object' && !Array.isArray(x);
+const once = (re) => new RegExp(re.source);
+// The file of the folder that names each request's own item (own-item SP-8).
+const OWN_ITEMS = 'assuredloop-requests.json';
+const FORMAT = 'assuredloop-items/1';
+// `text` holds `word` as a whole word: no letter, digit, `_` or `-` beside it.
+const holds = (text, word) => new RegExp(`(?<![\\w-])${word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w-])`).test(text);
+
+// The `owner/repo` of a URL or an `owner/repo#n` (null when it names no item).
+const keyOf = (s) => {
+  const t = String(s ?? '');
+  const m = once(ISSUE_URL).exec(t) ?? once(QUALIFIED).exec(t);
+  return m ? `${m[1]}/${m[2]}#${m[3]}` : null;
+};
+
+// The `owner/repo` that `git remote get-url origin` names in `dir`, any host
+// (D12): { repo } or { unknown }.
+function remoteRepo(dir) {
+  const url = git(dir, ['remote', 'get-url', 'origin'], { allowFail: true });
+  if (!url) return { unknown: 'no remote origin' };
+  const m = /^(?:[\w.+-]+:\/\/(?:[^@/]+@)?[^/]+\/|[^@\s/]+@[^:\s/]+:)(.+?)(?:\.git)?\/?$/.exec(url);
+  // The URL is not shown: it may hold a user name and a password (SP-22).
+  return m && /^[^/]+\/[^/]+$/.test(m[1]) ? { repo: m[1] } : { unknown: 'the remote origin names no owner/repo' };
+}
+
+// An entry of an item file: the item, or null when it is not one (SP-24).
+function itemOf(x, file) {
+  if (!isMap(x) || typeof x.body !== 'string') return null;
+  const at = once(ISSUE_URL).exec(String(x.url ?? ''));
+  const repository = typeof x.repository === 'string' && x.repository ? x.repository
+    : isMap(x.repository) && typeof x.repository.nameWithOwner === 'string' ? x.repository.nameWithOwner
+      : at ? `${at[1]}/${at[2]}` : null;
+  const number = Number.isInteger(x.number) ? x.number : at ? Number(at[3]) : null;
+  const ref = typeof x.ref === 'string' && x.ref ? x.ref : null;
+  const key = repository && number !== null ? `${repository}#${number}` : ref;
+  if (!key) return null;
+  return { key, ref, url: typeof x.url === 'string' ? x.url : null, repository, number, body: x.body, comments: x.comments, parent: x.parent, file };
+}
+
+// The own items that assuredloop-requests.json names (own-item SP-8, SP-9):
+// { requests } (a Map of name to value), { absent: true }, or { why } when
+// the file is not valid and so is ignored as a whole.
+function ownItems(path) {
+  if (!existsSync(path)) return { absent: true };
+  let data;
+  try {
+    data = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (e) {
+    return { why: e instanceof SyntaxError ? 'it is not valid JSON' : `it cannot be read (${e.code ?? e.message})` };
+  }
+  if (!isMap(data)) return { why: 'it is not a JSON object' };
+  const other = Object.keys(data).filter((k) => k !== 'format' && k !== 'requests');
+  if (other.length) return { why: `it has a field other than format and requests: ${other.join(', ')}` };
+  if (data.format !== FORMAT) return { why: `its format is not ${FORMAT}` };
+  if (!isMap(data.requests)) return { why: 'its requests is not an object' };
+  const bad = Object.entries(data.requests).filter(([, v]) => typeof v !== 'string' || !v).map(([k]) => k);
+  if (bad.length) return { why: `the value of ${bad.join(', ')} is not a text that is not empty` };
+  return { requests: new Map(Object.entries(data.requests)) };
+}
+
+// The items of the folder that the caller saved (SP-12): { items, unread,
+// owns }. A folder that is not there is a refusal.
+export function loadItems(cwd, folder) {
+  const dir = resolve(cwd, folder);
+  let isDir = false;
+  try {
+    isDir = statSync(dir).isDirectory();
+  } catch {
+    isDir = false;
+  }
+  if (!isDir) throw new Fail(`--issues ${folder}: no such folder`, 'save the work items in a folder (see the README), then al check --issues <folder>');
+  const items = [];
+  const unread = [];
+  const shown = (name) => `${folder.replace(/\/+$/, '')}/${name}`;
+  const owns = ownItems(join(dir, OWN_ITEMS));
+  if (owns.why) unread.push({ file: shown(OWN_ITEMS), why: owns.why });
+  for (const name of readdirSync(dir).filter((n) => n.endsWith('.json') && n !== OWN_ITEMS).sort()) {
+    const file = shown(name);
+    let data;
+    try {
+      if (!statSync(join(dir, name)).isFile()) continue;
+      data = JSON.parse(readFileSync(join(dir, name), 'utf8'));
+    } catch (e) {
+      unread.push({ file, why: e instanceof SyntaxError ? 'it is not valid JSON' : `it cannot be read (${e.code ?? e.message})` });
+      continue;
+    }
+    (Array.isArray(data) ? data : [data]).forEach((x, i) => {
+      const it = itemOf(x, file);
+      if (it) items.push(it);
+      else unread.push({ file, why: `${Array.isArray(data) ? `its entry ${i + 1}` : 'it'} is not an item: an item needs a body, and a url, a number with a repository, or a ref` });
+    });
+  }
+  return { folder, items, unread, owns };
+}
+
+// The names of the repos that the config names, each with its folder or why it has none.
+function namedRepos(top, config) {
+  const out = new Map();
+  for (const o of outputRepos(top, config)) if (o.name) out.set(o.name, o.dir ? { dir: o.dir } : { unknown: o.unknown });
+  const c = config.central;
+  if (isMap(c) && typeof c.path === 'string' && c.path) {
+    const dir = isAbsolute(c.path) ? c.path : resolve(top, c.path);
+    out.set('central', existsSync(dir) ? { dir } : { unknown: `no clone at ${c.path}` });
+  }
+  return out;
+}
+
+// The references that a task's `ref` writes in the forms of SP-8:
+// [{ written, key } | { written, unknown }].
+function written(ref, names, own, folders) {
+  let rest = String(ref);
+  const out = [];
+  const take = (re, f) => {
+    rest = rest.replace(re, (...m) => {
+      const r = f(m);
+      if (!r) return m[0];
+      out.push({ written: m[0], ...r });
+      return ' '.repeat(m[0].length);
+    });
+  };
+  take(ISSUE_URL, (m) => ({ key: `${m[1]}/${m[2]}#${m[3]}` }));
+  take(QUALIFIED, (m) => ({ key: `${m[1]}/${m[2]}#${m[3]}` }));
+  take(NAMED, (m) => {
+    if (!names.has(m[1])) return null;
+    const r = folders(m[1]);
+    return r.repo ? { key: `${r.repo}#${m[2]}` } : { unknown: `${m[1]}: ${r.unknown}` };
+  });
+  take(BARE, (m) => (own.repo ? { key: `${own.repo}#${m[1]}` } : { unknown: `the request's own repository is not known (${own.unknown})` }));
+  return out;
+}
+
+export function issueHints(top, state, matchers, add, { folder, items, unread, owns }) {
+  const notKnown = [];
+  const names = namedRepos(top, state.config);
+  const cited = supersededIn(state);
+  const own = remoteRepo(top);
+  const remotes = new Map();
+  const folders = (name) => {
+    if (!remotes.has(name)) {
+      const n = names.get(name);
+      remotes.set(name, n.dir ? remoteRepo(n.dir) : { unknown: n.unknown });
+    }
+    return remotes.get(name);
+  };
+  const byKey = new Map();
+  for (const it of items) if (!byKey.has(slug(it.key))) byKey.set(slug(it.key), it);
+  const withRef = items.filter((it) => it.ref);
+
+  for (const u of unread) add('hint', 'issue-unread', u.file, '-', `not read: ${u.why}`);
+  if (unread.length) notKnown.push(`the files in ${folder} that were not read: ${unread.map((u) => u.file).join(', ')}`);
+
+  // The items that each task of each open request names, in order (SP-8, SP-9).
+  const named = []; // [{ r, task, it }]
+  const tasked = []; // the open requests with a task that has a ref
+  for (const r of state.requests.values()) {
+    if (!r.open) continue;
+    for (const t of Array.isArray(r.data?.tasks) ? r.data.tasks : []) {
+      if (!isMap(t) || t.ref == null) continue;
+      if (!tasked.includes(r)) tasked.push(r);
+      const task = String(t.id ?? '-');
+      const id = `${r.name}/${task}`;
+      const found = [];
+      for (const w of written(t.ref, names, own, folders)) {
+        const it = w.key && byKey.get(slug(w.key));
+        if (it) found.push(it);
+        else add('hint', 'issue-missing', w.written, id, w.key ? `${w.written}: no item in ${folder} is ${w.key}` : `${w.written}: ${w.unknown}, so it names no item`);
+      }
+      for (const it of withRef) if (!found.includes(it) && holds(String(t.ref), it.ref)) found.push(it);
+      if (!found.length && !written(t.ref, names, own, folders).length) add('hint', 'issue-missing', recordPath(r.name), id, `its ref names no item in ${folder}: ${JSON.stringify(String(t.ref))}`);
+      for (const it of found) named.push({ r, task, it });
+    }
+  }
+
+  // Each item once, with the ID of the first task that names it.
+  const first = new Map();
+  for (const n of named) if (!first.has(n.it)) first.set(n.it, n);
+  for (const [it, n] of first) {
+    const id = `${n.r.name}/${n.task}`;
+    const texts = [{ where: it.key, text: it.body }];
+    (Array.isArray(it.comments) ? it.comments : []).forEach((c, i) => {
+      if (isMap(c) && c.isMinimized !== true) texts.push({ where: `${it.key}/comment-${i + 1}`, text: c.body });
+    });
+    const other = own.repo && it.repository && slug(it.repository) !== slug(own.repo);
+    for (const { where, text } of texts) {
+      if (typeof text !== 'string' || !text) continue;
+      for (const c of cited(text)) add('hint', 'issue-superseded', `${where}:${c.line}`, id, citedMessage(c));
+      if (other) {
+        text.replace(/\r\n?/g, '\n').split('\n').forEach((l, i) => {
+          const refs = [...l.matchAll(BARE)].map((m) => `#${m[1]}`);
+          if (refs.length) add('hint', 'issue-bare-ref', `${where}:${i + 1}`, id, `${refs.join(', ')} in an item of ${it.repository} points to ${it.repository}, not to ${own.repo}: write ${refs.map((x) => `${own.repo}${x}`).join(', ')} if that is meant`);
+        });
+      }
+      for (const h of phraseHits(text, matchers)) add('hint', 'phrase', `${where}:${h.line}`, id, phraseMessage(h));
+    }
+    if (!own.repo) continue;
+    if (!it.repository) notKnown.push(`the issue-bare-ref check of ${it.key}: its repository is not known`);
+  }
+  if (!own.repo) notKnown.push(`the request's own repository, for #n and the issue-bare-ref check: ${own.unknown}`);
+
+  // Children (SP-10): once for each request and item. The own item is the one
+  // that assuredloop-requests.json names (own-item SP-7); nothing else names it.
+  const ownOf = new Map();
+  const ownItem = (r) => {
+    if (ownOf.has(r.name)) return ownOf.get(r.name);
+    let ids;
+    const value = owns.requests?.get(r.name);
+    if (owns.absent) ids = { unknown: `${folder} has no ${OWN_ITEMS}` };
+    else if (!owns.requests) ids = { unknown: `${folder.replace(/\/+$/, '')}/${OWN_ITEMS} was not read` };
+    else if (value === undefined) ids = { unknown: `${OWN_ITEMS} names no own item for ${r.name}` };
+    else {
+      const w = written(value, names, own, folders);
+      const lost = w.find((x) => x.unknown);
+      if (lost) ids = { unknown: `its own item ${value}: ${lost.unknown}` };
+      else if (w.length) {
+        const keys = new Set(w.map((x) => slug(x.key)));
+        const its = items.filter((x) => keys.has(slug(x.key)));
+        ids = { keys: new Set([...keys, ...its.map((x) => x.ref).filter(Boolean).map(slug)]), urls: new Set([value, ...its.map((x) => x.url).filter(Boolean)]), ref: its.find((x) => x.ref)?.ref ?? null };
+      } else {
+        // Another tracker's key: the item that holds it as its ref, or else the value itself.
+        const it = items.find((x) => x.ref && holds(value, x.ref));
+        ids = it ? { keys: new Set([it.key, it.ref].map(slug)), urls: new Set([value, it.url].filter(Boolean)), ref: it.ref }
+          : { keys: new Set([slug(value)]), urls: new Set([value]), ref: value };
+      }
+    }
+    ownOf.set(r.name, ids);
+    return ids;
+  };
+  const seen = new Set();
+  for (const n of named) {
+    const pair = `${n.r.name} ${slug(n.it.key)}`;
+    if (seen.has(pair)) continue;
+    seen.add(pair);
+    const mine = ownItem(n.r);
+    if (mine.unknown) continue;
+    const it = n.it;
+    if (mine.keys.has(slug(it.key)) || (it.ref && mine.keys.has(slug(it.ref)))) continue;
+    if (it.parent === undefined) {
+      notKnown.push(`whether ${it.key} is a child of the own item of ${n.r.name}: the item has no parent field`);
+      continue;
+    }
+    const p = it.parent;
+    // A parent's number is in the item's repository only when no url names its own.
+    const parent = isMap(p) ? [keyOf(p.url), typeof p.ref === 'string' ? p.ref : null,
+      !keyOf(p.url) && Number.isInteger(p.number) && it.repository ? `${it.repository}#${p.number}` : null].filter(Boolean) : [];
+    // A parent's url names the own item when it is the own item's url or the value, or holds its ref.
+    const url = isMap(p) && typeof p.url === 'string' && p.url ? p.url : null;
+    if (p !== null && !parent.length && !url) {
+      notKnown.push(`whether ${it.key} is a child of the own item of ${n.r.name}: its parent names no item`);
+      continue;
+    }
+    if (url && (mine.urls.has(url) || (mine.ref && holds(url, mine.ref)))) continue;
+    if (parent.some((x) => mine.keys.has(slug(x)))) continue;
+    const named = parent[0] ?? url;
+    add('hint', 'issue-not-sub', it.key, `${n.r.name}/${n.task}`, `is not a child of the request's own item (${[...mine.keys][0]})${named ? `; its parent is ${named}` : ''}`);
+  }
+  // Once for each request with a task that has a ref, whether or not its items are in the folder.
+  for (const r of tasked) {
+    const why = ownItem(r).unknown;
+    if (why) notKnown.push(`whether the items of ${r.name} are children of its own item: ${why}`);
+  }
+
+  const others = items.filter((it) => !first.has(it)).length;
+  if (others) notKnown.push(`${others} item${others === 1 ? '' : 's'} in ${folder} that no task names, not checked`);
+  add('info', 'issues', '-', '-', `checked ${first.size} items for the tasks of the open requests, from ${folder}`);
+  return notKnown;
+}

package/src/v4/markers.js

@@ -163,6 +163,69 @@ export function sameBlocks(text, paragraphs, { file = '', living = new Set(parag
 
 const emptyLinks = () => Object.fromEntries(Object.values(LINK_WORDS).map((k) => [k, []]));
 
+// The tokens of a marker line that are not its ID, one kind or a link (#4): a
+// word that is no kind or a second kind, a word that is no link word, a token
+// that holds `<!--` or `-->`, and a link with an empty item. An HTML renderer
+// can show text that such a token hides.
+export function markerExtras(line, kinds = KINDS) {
+  const m = MARKER.exec(line);
+  if (!m) return [];
+  const known = new Set(Object.values(kinds).flat());
+  const extras = [];
+  let kind = false;
+  for (const token of m[2].trim().split(/[ \t]+/).filter(Boolean)) {
+    const c = token.indexOf(':');
+    if (/<!--|-->/.test(token)) extras.push(token);
+    else if (c < 0) {
+      if (kind || !known.has(token)) extras.push(token);
+      kind = true;
+    } else if (!Object.hasOwn(LINK_WORDS, token.slice(0, c)) || token.slice(c + 1).split(',').includes('')) extras.push(token);
+  }
+  return extras;
+}
+
+// The lines of `text`, outside fenced code, that start like a marker: `<!--`
+// and an ID, spaces allowed. Each is { id, line, extras }: the extras of a
+// well-formed marker, or null for a line that MARKER does not read, whose
+// paragraph is then lost (#4).
+export function markerLines(text, kinds = KINDS) {
+  const out = [];
+  let fence = null;
+  lf(text).split('\n').forEach((l, i) => {
+    const f = FENCE.exec(l);
+    if (fence) {
+      if (f && f[1][0] === fence[0] && f[1].length >= fence.length && l.trim() === f[1]) fence = null;
+      return;
+    }
+    if (f) { fence = f[1]; return; }
+    const m = /^[ \t]*<!--[ \t]*(ADR-[0-9]+-[0-9]+|[A-Z][A-Z0-9]*-[0-9]+)/.exec(l);
+    if (m) out.push({ id: m[1], line: i + 1, extras: MARKER.test(l) ? markerExtras(l, kinds) : null });
+  });
+  return out;
+}
+
+// Whether marker line `now` is marker line `was` with links added and nothing
+// else (schema.md 5, #4): with each link item that `was` does not hold taken
+// out, and each token left with no item, `now` is `was` exactly. A marker
+// with extras never qualifies, so an added item cannot hide text.
+export function onlyLinksAdded(was, now, kinds = KINDS) {
+  const w = MARKER.exec(was);
+  const n = MARKER.exec(now);
+  if (!w || !n || markerExtras(now, kinds).length) return false;
+  const old = new Set((w[2].match(/\S+/g) ?? []).filter((t) => t.includes(':')).flatMap((t) => {
+    const c = t.indexOf(':');
+    return t.slice(c + 1).split(',').map((x) => `${t.slice(0, c)}:${x}`);
+  }));
+  const kept = (n[2].match(/[ \t]+\S+/g) ?? []).map((piece) => {
+    const c = piece.indexOf(':');
+    if (c < 0) return piece;
+    const items = piece.slice(c + 1).split(',').filter((x) => old.has(`${piece.slice(0, c).trim()}:${x}`));
+    return items.length ? `${piece.slice(0, c + 1)}${items.join(',')}` : '';
+  }).join('');
+  const start = now.indexOf(n[1]) + n[1].length;
+  return now.slice(0, start) + kept + now.slice(start + n[2].length) === was;
+}
+
 export function parseMarkdown(text, file, options = {}) {
   const kinds = options.kinds ?? KINDS;
   const known = new Set(Object.values(kinds).flat());