@assuredloop/cli 1.0.0 → 3.0.0

package/README.md

@@ -97,7 +97,15 @@ Search at level 2 needs the library `@huggingface/transformers` 4.3.1 (see
 - **Bindings.** When a link is first indexed, `al index` records the hash of
   both ends. Ordinary indexing never moves a binding. When the target
   changes, the source gets a hint until someone checks it and runs
-  `al index --align <ID>`.
+  `al index --align <ID>`. When the source paragraph's own text changes,
+  it gets the hint `holder-changed` until it is aligned in the same way.
+  This hint covers the links that a paragraph of a spec doc, an ADR or an
+  open change spec still declares, to a target that still resolves, in the
+  records of the open requests. A requirement is out, because a changed
+  requirement needs a new sign-off. An output file is out. When no current
+  marker declares a link any more, `al index` removes its binding, in the
+  open and the archived records, and names it in its output. Git history
+  keeps it.
 - **Consolidation is by hand.** A PR copies a change paragraph into `specs/`
   word for word, and records its disposition: `incorporated`, `removed`,
   `superseded` or `abandoned`. No command writes the spec.
@@ -139,9 +147,10 @@ with a baseline effect has no valid disposition for its current version.
 - `al spec`: every doc's IDs, display numbers and kinds.
   `al spec --add-ids <file> [--prefix <P>]`: give each unmarked paragraph the
   next free ID.
-- `al index`: write the derived facts and the new bindings, and list the AI
-  hints to refresh. `al index --align <ID>` moves the bindings of one
-  paragraph to its targets' current text, on purpose.
+- `al index`: write the derived facts and the new bindings, remove the
+  bindings of links that no marker declares, and list the AI hints to
+  refresh. `al index --align <ID>` moves the bindings of one paragraph to its
+  targets' current text and to its own, on purpose.
 - `al check [--strict] [--issues <folder>]`: the checks of this branch
   against its base. With `--issues <folder>`, it also checks the work items
   that the caller saved in the folder (see "Hints from the linked work
@@ -192,16 +201,26 @@ default. A bad entry or an invalid pattern stops `al check` with exit 2.
 `al spec --add-ids` writes both files when they are absent.
 
 ADRs are `specs/adr/NNNN-<slug>.md`, with `Status: proposed`, `accepted` or
-`superseded by ADR-<n>` on the first line. The heading's marker holds
-`ADR-<n>` and its `decides:`, `source:` and `supersedes:` links.
+`superseded by ADR-<n>` on the first line. A status line may name several
+ADRs that supersede it: `superseded by ADR-11, ADR-12` or
+`ADR-11 and ADR-12`. The heading's marker holds `ADR-<n>` and its
+`decides:`, `source:` and `supersedes:` links.
 
 - Any text may be rewritten in other words when its meaning stays the same,
   an accepted or superseded ADR's text too. A new ADR that supersedes it is
   needed only when the decision changes, in whole or in part.
 - The review judges whether a rewrite keeps the decision; `al` does not. So
-  a changed ADR text, or a changed or removed link in its marker, gives a
-  hint: check that its decision is unchanged. Links added to the marker of
-  an accepted ADR, with nothing else changed, give no finding.
+  a changed ADR text, a changed or removed link in its marker, or any other
+  change of its marker line, gives a hint: check that its decision is
+  unchanged. Links added to the marker of an accepted ADR, with nothing else
+  changed, give no finding.
+- `al check` gives a hint for a marker line of an ADR that holds anything
+  other than its ID, its kind and links: an unknown token, a second `<!--`
+  or `-->`, or an empty item in a list of links. A line that starts like a
+  marker, but that `al` does not read as one, gets the same hint.
+- `al check` gives a hint for an ADR whose first line is not
+  `Status: proposed`, `Status: accepted` or `Status: superseded by ADR-<n>`,
+  with one ADR or a list of them.
 - After a rewrite, `al index --align <ID>` moves the bindings of paragraph
   `<ID>` to the ADR's new text, for an accepted or a superseded ADR.
 - `al check` gives a hint for a proposed or accepted ADR with no `source:`
@@ -209,6 +228,8 @@ ADRs are `specs/adr/NNNN-<slug>.md`, with `Status: proposed`, `accepted` or
 - A current place that names a superseded ADR also names the ADR that
   supersedes it, in the same marker or the same paragraph. Current places
   are the spec docs, the open requests and the proposed and accepted ADRs.
+  The text names an ADR by `ADR-40`, by `ADR 0040`, or in a list or a range
+  such as `ADRs 0003, 0005 and 0040` or `ADRs 0003 to 0005`.
   The chain itself and dated records are exempt: an ADR that supersedes it,
   a superseded ADR, an ADR's `## History`, a request's `## Decisions`, the
   `origin/` files and the archived requests. Else `al check` gives
@@ -234,8 +255,7 @@ example `PROJ-12`. Each finding is a hint:
   GitHub reads as that repository's issue. The request's own repository
   comes from `git remote get-url origin`;
 - `issue-not-sub`: the item is not a child of the request's own item, the
-  item that the `url` of an origin source names (`al record <name> origin
-  --url <its URL>`);
+  item that `assuredloop-requests.json` in the folder names (below);
 - `phrase`: a phrase of `phrases:` matches;
 - `issue-unread`: a file in the folder is not valid JSON, or holds an entry
   that is not an item.
@@ -274,6 +294,104 @@ An item of another tracker:
  "comments": [{"body": "Done.", "isMinimized": false}], "parent": {"ref": "PROJ-1"}}
 ```
 
+The folder also says which item is each request's own item, in the file
+`assuredloop-requests.json`. `al` reads the own item from this file only,
+never from an origin source. Without the file, or for a request that it
+does not list, `issue-not-sub` is not checked, and the `Not known` line
+says so once for each request. The file is not read as an item. A file that
+is not valid gets `issue-unread` and is ignored; `al check` goes on.
+
+- `format`: the exact text `assuredloop-items/1`;
+- `requests`: each key is a request's name, and its value is that request's
+  own item, in a form that a task's `ref` uses: a URL, `owner/repo#n`, or
+  another tracker's key, for example `PROJ-1`.
+
+```json
+{
+  "format": "assuredloop-items/1",
+  "requests": {
+    "invoice-exports": "https://github.com/acme/invoicer/issues/30",
+    "pay-run": "PROJ-1"
+  }
+}
+```
+
+To write it for a GitHub issue:
+
+```sh
+printf '{"format": "assuredloop-items/1", "requests": {"invoice-exports": "%s"}}\n' \
+  "$(gh issue view 30 --repo acme/invoicer --json url --jq .url)" \
+  > /tmp/items/assuredloop-requests.json
+```
+
+The JSON Schema (draft 2020-12) of each file, for a person or an AI that
+writes them. An item file:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "an item file: one item, or a list of items",
+  "oneOf": [
+    {"$ref": "#/$defs/item"},
+    {"type": "array", "items": {"$ref": "#/$defs/item"}}
+  ],
+  "$defs": {
+    "item": {
+      "type": "object",
+      "required": ["body"],
+      "anyOf": [
+        {"required": ["url"], "properties": {"url": {"type": "string", "pattern": "^https?://[^/\\s]+/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+/issues/[0-9]+([^A-Za-z0-9_][\\s\\S]*)?$"}}},
+        {"required": ["number", "repository"]},
+        {"required": ["ref"]}
+      ],
+      "properties": {
+        "body": {"type": "string"},
+        "url": {"type": "string"},
+        "number": {"type": "integer"},
+        "comments": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["body"],
+            "properties": {"body": {"type": "string"}, "isMinimized": {"type": "boolean"}}
+          }
+        },
+        "parent": {
+          "oneOf": [
+            {"type": "null"},
+            {
+              "type": "object",
+              "properties": {"url": {"type": "string"}, "number": {"type": "integer"}, "ref": {"type": "string", "minLength": 1}}
+            }
+          ]
+        },
+        "ref": {"type": "string", "minLength": 1},
+        "repository": {"type": "string", "minLength": 1}
+      }
+    }
+  }
+}
+```
+
+`assuredloop-requests.json`:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "assuredloop-requests.json",
+  "type": "object",
+  "required": ["format", "requests"],
+  "additionalProperties": false,
+  "properties": {
+    "format": {"const": "assuredloop-items/1"},
+    "requests": {
+      "type": "object",
+      "additionalProperties": {"type": "string", "minLength": 1}
+    }
+  }
+}
+```
+
 ## Search
 
 `al search` answers at the strongest level that is installed, falls back by
@@ -403,6 +521,13 @@ claim, a link that does not resolve, an ADR's changed text or missing links,
 an invalid disposition, and the rest. `--strict` changes only the exit code:
 it is 1 when a `not ok` prints.
 
+`al check` gives the hint "promise kind?" (`promise-kind`) for a paragraph
+that is not a promise kind and holds a requirement word: MUST, SHALL, SHOULD,
+MAY, never or always. When the paragraph is a promise, change its kind. When
+it applies a promise, for example a flow step that keeps a rule, give it
+`builds-on:` the promise paragraph in its marker. The hint then goes. A
+`builds-on:` to another kind, or to an ID that does not exist, keeps it.
+
 ## What is enforced, and by whom
 
 | The tool checks | The skill asks | The owner decides |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assuredloop/cli",
-  "version": "1.0.0",
+  "version": "3.0.0",
   "description": "AssuredLoop keeps an AI focused on one change: the al command gathers and checks a change's requirement, spec, decisions, code and tests.",
   "license": "MIT",
   "repository": {

package/skills/assuredloop/SKILL.md

@@ -92,9 +92,11 @@ The export link MUST expire 30 minutes after the email is sent.
   rewrite, run `al index --align <ID>` for each paragraph that links to it.
 - When an ADR is superseded, set its first line to
   `Status: superseded by ADR-<m>`, and put `supersedes:ADR-<n>` in the marker
-  of ADR-m. Where a spec paragraph, an open request or a proposed or accepted
-  ADR names ADR-n, name ADR-m beside it: in the same marker for a link, in
-  the same paragraph for a word. Else `al check` gives `not ok`.
+  of ADR-m. When several ADRs supersede it, name each one:
+  `Status: superseded by ADR-11, ADR-12`. Where a spec paragraph, an open
+  request or a proposed or accepted ADR names ADR-n, name an ADR that
+  supersedes it beside it: in the same marker for a link, in the same
+  paragraph for a word. Else `al check` gives `not ok`.
 - `al` writes every hash and every derived field. Do not write them by hand.
 
 ## Path 0: a fix

package/src/v4/blocks.js

@@ -163,7 +163,7 @@ function supersedes(state) {
   const out = new Map([...state.adrs.keys()].map((id) => [id, new Set()]));
   for (const a of state.adrs.values()) {
     for (const x of (a.head?.links.supersedes ?? []).map(adrOf).filter(Boolean)) out.get(a.id).add(x);
-    if (a.by && out.has(a.by)) out.get(a.by).add(a.id);
+    for (const b of a.by) if (out.has(b)) out.get(b).add(a.id);
   }
   return out;
 }
@@ -178,18 +178,44 @@ const ADR_REF = /^ADR-(\d+)(?:-\d+)?$/;
 const adrOf = (ref) => (ADR_REF.test(ref) ? `ADR-${Number(ADR_REF.exec(ref)[1])}` : null);
 const MARKER = /^\s*<!--(.*)-->\s*$/;
 
+// The words that name ADRs in a text (adr-lists R1): `ADR-n`, or the number
+// after `ADR` or `ADRs` and a space, and each item of a list or a range that
+// follows. An item is a number or `ADR-n`; a comma, `and` or both join a
+// list, and `to` a range. A range names its two ends and each ADR in `known`
+// (the numbers of the ADRs that exist) between them, so a long one costs
+// nothing; a reversed range names only its ends.
+const ITEM = String.raw`(?:ADR-\d+(?:-\d+)?|\d+)\b`;
+const NAMING = new RegExp(String.raw`\b(?:ADRs?\s+(?=\d)|(?=ADR-\d))${ITEM}(?:(?:\s*,\s*(?:and\s+)?|\s+(?:and|to)\s+)${ITEM})*`, 'g');
+function adrsNamed(text, known) {
+  const out = new Set();
+  for (const m of text.matchAll(NAMING)) {
+    let last = null;
+    let range = false;
+    for (const t of m[0].matchAll(/ADR-(\d+)(?:-\d+)?|\d+|\bto\b/g)) {
+      if (t[0] === 'to') { range = true; continue; }
+      const n = Number(t[1] ?? t[0]);
+      if (range && last < n) for (const k of known) if (k > last && k < n) out.add(`ADR-${k}`);
+      out.add(`ADR-${n}`);
+      last = n;
+      range = false;
+    }
+  }
+  return out;
+}
+
 // The places of a Markdown text: each marker line and each run of text lines,
 // with the ADRs it names and the ID of the marker it falls under. A heading
 // that `skip` matches starts a section that is not read, up to the next
 // heading of level 1 or 2.
-function places(textOf, skip) {
+function places(textOf, skip, known) {
   const lines = textOf.replace(/\r\n?/g, '\n').split('\n');
   const out = [];
   let id = null;
   let skipping = false;
   let run = null;
   const close = () => {
-    if (run && run.names.size) out.push(run);
+    const names = run ? adrsNamed(run.lines.join('\n'), known) : new Set();
+    if (names.size) out.push({ line: run.line, id: run.id, link: false, names });
     run = null;
   };
   lines.forEach((l, i) => {
@@ -204,23 +230,34 @@ function places(textOf, skip) {
       if (names.size) out.push({ line: i + 1, id, link: true, names });
       return;
     }
-    if (!run) run = { line: i + 1, id, link: false, names: new Set() };
-    for (const w of l.matchAll(/\bADR-(\d+)(?:-\d+)?\b/g)) run.names.add(`ADR-${Number(w[1])}`);
+    if (!run) run = { line: i + 1, id, lines: [] };
+    run.lines.push(l);
   });
   close();
   return out;
 }
 
 // R5's rule on one text: each place that names a superseded ADR, but no ADR
-// that supersedes it, in the same marker or the same paragraph. Gives
-// (text, { skip, exempt }) => [{ line, id, link, adr, next }]. al check
-// --issues reads the issues with the same rule (issue-hints D7).
+// that supersedes it, directly or through a chain (#1), in the same marker or
+// the same paragraph. Gives (text, { skip, exempt }) => [{ line, id, link,
+// adr, next }]. al check --issues reads the issues with the same rule
+// (issue-hints D7).
 export function supersededIn(state) {
   const down = supersedes(state);
   const up = (id) => [...down].filter(([, xs]) => xs.has(id)).map(([y]) => y);
+  // The ADRs that supersede `id`, directly or through a chain; never `id`
+  // itself, when the chain is a cycle.
+  const above = (id) => {
+    const seen = new Set([id]);
+    const walk = (x) => { for (const y of up(x)) if (!seen.has(y)) { seen.add(y); walk(y); } };
+    walk(id);
+    seen.delete(id);
+    return seen;
+  };
   const superseded = (id) => state.adrs.get(id)?.status === 'superseded';
-  return (textOf, { skip = null, exempt = new Set() } = {}) => places(textOf, skip).flatMap((p) => [...p.names]
-    .filter((x) => superseded(x) && !exempt.has(x) && !up(x).some((y) => p.names.has(y)))
+  const known = [...state.adrs.keys()].map((id) => Number(id.slice('ADR-'.length)));
+  return (textOf, { skip = null, exempt = new Set() } = {}) => places(textOf, skip, known).flatMap((p) => [...p.names]
+    .filter((x) => superseded(x) && !exempt.has(x) && ![...above(x)].some((y) => p.names.has(y)))
     .map((x) => ({ line: p.line, id: p.id, link: p.link, adr: x, next: up(x) })));
 }
 
@@ -259,10 +296,12 @@ export function supersededBlocks(top, state, add) {
   for (const a of state.adrs.values()) {
     if (a.status !== 'superseded') continue;
     const where = `${a.file}:1`;
-    if (!a.by) add('not ok', 'superseded-status', where, a.id, `${a.id} is superseded, but its status line does not say by which ADR: write "Status: superseded by ADR-<n>"`);
-    else if (!state.adrs.has(a.by)) add('not ok', 'superseded-status', where, a.id, `${a.id} says it is superseded by ${a.by}, which does not exist`);
-    else if (!(state.adrs.get(a.by).head?.links.supersedes ?? []).some((x) => adrOf(x) === a.id)) {
-      add('not ok', 'superseded-status', where, a.id, `${a.id} says it is superseded by ${a.by}, but the marker of ${a.by} has no supersedes:${a.id}`);
+    if (!a.by.length) add('not ok', 'superseded-status', where, a.id, `${a.id} is superseded, but its status line does not say by which ADR: write "Status: superseded by ADR-<n>"`);
+    for (const b of a.by) {
+      if (!state.adrs.has(b)) add('not ok', 'superseded-status', where, a.id, `${a.id} says it is superseded by ${b}, which does not exist`);
+      else if (!(state.adrs.get(b).head?.links.supersedes ?? []).some((x) => adrOf(x) === a.id)) {
+        add('not ok', 'superseded-status', where, a.id, `${a.id} says it is superseded by ${b}, but the marker of ${b} has no supersedes:${a.id}`);
+      }
     }
   }
 

package/src/v4/check.js

@@ -1,17 +1,17 @@
 // al check (design.md 3, What the script checks): the lints of every marker in
 // scope, and per scope the ID lints of the branch against its base (lost, used
 // again, one ID in two files), then each paragraph's change (T8); then the
-// checks that read records (T10, checks.js). The base is the merge-base of
-// HEAD with main; the head is the working tree. It exits 0; with --strict, 1
-// when it prints a `not ok`. A finding has the same severity in both modes:
-// the marker and ID lints are hints for the review, and only the exact rules
-// of checks.js are `not ok` (#238). With --issues <folder> it also checks the
+// checks that read records (T10, checks.js). The base is baseOf (git.js), the
+// merge-base of HEAD with main or origin/main; the head is the working tree.
+// It exits 0; with --strict, 1 when it prints a `not ok`. A finding has the
+// same severity in both modes: the marker and ID lints are hints for the
+// review, and only the exact rules of checks.js are `not ok` (#238). With --issues <folder> it also checks the
 // work items that the caller saved there (issue-hints R1).
 import { relative } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { read, recordPath } from './base.js';
 import { loadConfig, loadSchema } from './config.js';
-import { mergeBase } from './git.js';
+import { baseOf } from './git.js';
 import { diffParagraphs, idLints } from './ids.js';
 import { docsInScope, idsEverUsed, isShallow, notRead, parseScopes, rootNotOk, rootProblem, SPEC } from './scope.js';
 import { Fail } from './spec.js';
@@ -41,7 +41,8 @@ function checkAll({ top, cwd, opts }) {
   const phrases = loadPhrases(config);
   // The work items that the caller saved; a folder that is not there is a refusal.
   const issues = opts.issues === undefined ? null : loadItems(cwd ?? top, opts.issues);
-  const base = mergeBase(top);
+  const found = baseOf(top);
+  const base = found?.commit ?? null;
   const now = parseScopes(docsInScope(top, config), kinds);
   const was = base ? parseScopes(docsInScope(top, config, base), kinds) : null;
   const used = base ? idsEverUsed(top, config, base) : null;
@@ -85,7 +86,7 @@ function checkAll({ top, cwd, opts }) {
   else if (isShallow(top)) notKnown.unshift('IDs used before the shallow history begins');
   return {
     body,
-    read: base ? `working tree · base ${base.slice(0, 7)} (merge-base with main)` : 'working tree · no base',
+    read: base ? `working tree · base ${base.slice(0, 7)} (merge-base with ${found.ref})` : 'working tree · no base',
     next: nextStep([...(rootLine ? ['not ok'] : []), ...lints.map((l) => l.severity), ...t10.findings.map((f) => f.severity),
       ...central.body.map((l) => (/^not ok /.test(l) ? 'not ok' : /^hint /.test(l) ? 'hint' : 'info'))], lints.some((l) => l.code === 'no-id'),
       t10.findings.some((f) => f.code === 'unsigned-requirement')),

package/src/v4/checks.js

@@ -1,8 +1,9 @@
 // The checks that read records (T10; design.md 3-7 and 9, schema.md 5; the
 // architect's answers for #179, decision D15). Each finding is
 // { severity, code, file, line, id, message }: `not ok`, `hint` or `info`.
-// They compare the working tree with the base (the merge-base with main) and
-// read the records of the open requests. No AI, no network.
+// They compare the working tree with the base (baseOf in git.js: the
+// merge-base with main or origin/main) and read the records of the open
+// requests. No AI, no network.
 import { createHash } from 'node:crypto';
 import { parse as parseYaml } from 'yaml';
 import { read } from './base.js';
@@ -12,11 +13,11 @@ import { diffParagraphs } from './ids.js';
 import { crossResults } from './repos.js';
 import { loadResults } from './results.js';
 import {
-  hasBaselineEffect, isPromise, loadState, named, qualify, requestOf, resolve, servesSigned,
+  adrParagraph, hasBaselineEffect, isPromise, loadState, named, qualify, requestOf, resolve, servesSigned,
 } from './state.js';
 import { NEAR, closeness, diffWords, marks, requirementWords, sentencesOf, showHunk } from './words.js';
-import { groupOf, sameBlocks } from './markers.js';
-import { isCentral } from './indexer.js';
+import { groupOf, markerLines, onlyLinksAdded, sameBlocks } from './markers.js';
+import { canAlignTo, declaredNow, isCentral } from './indexer.js';
 import { recordBlocks, supersededBlocks } from './blocks.js';
 import { phraseFindings } from './phrases.js';
 import { issueHints } from './issues.js';
@@ -185,10 +186,18 @@ export function checks(top, { base, phrases = [], issues = null }) {
     }
   }
 
-  // Requirement words in a non-promise kind (design.md 3).
+  // In the central repo, `central:X` is its own X (design.md 12).
+  const self = (ref) => (isCentral(now.config) && ref.startsWith('central:') ? ref.slice('central:'.length) : ref);
+
+  // Requirement words in a non-promise kind (design.md 3). A paragraph that
+  // builds on a promise paragraph that exists applies that promise: no hint.
+  const appliesPromise = (p, request) => {
+    const own = new Set(now.requests.get(request)?.paras.keys() ?? []);
+    return p.links.buildsOn.some((ref) => promise(resolve(now, qualify(self(ref), request, own))?.p?.kind));
+  };
   for (const c of changes) {
     const p = c.head;
-    if (!p?.kind || promise(p.kind) || !c.changed) continue;
+    if (!p?.kind || promise(p.kind) || !c.changed || appliesPromise(p, c.request)) continue;
     const w = requirementWords(p.text);
     if (w.length) add('hint', 'promise-kind', p, c.name, `promise kind? a ${p.kind} paragraph holds ${w.join(', ')}`);
   }
@@ -263,8 +272,7 @@ export function checks(top, { base, phrases = [], issues = null }) {
   // Design links (design.md 3): a design or approach paragraph of a change
   // spec that serves a requirement, where promise paragraphs of the same
   // change spec serve it, and that builds on or changes none of them. In the
-  // central repo, `central:X` is its own X (design.md 12).
-  const self = (ref) => (isCentral(now.config) && ref.startsWith('central:') ? ref.slice('central:'.length) : ref);
+  // central repo, `central:X` is its own X (self, above).
   for (const r of open) {
     const own = new Set(r.paras.keys());
     const key = (ref) => qualify(self(ref), r.name, own).key;
@@ -305,9 +313,24 @@ export function checks(top, { base, phrases = [], issues = null }) {
   }
 
   // Bindings whose target changed since they were bound (design.md 4, 6).
+  let declared = null;
+  let alignable = null;
   for (const r of open) {
     for (const b of Array.isArray(r.data?.bindings) ? r.data.bindings : []) {
       if (!b?.target || !b.holder || !b.target_sha256) continue;
+      // A holder paragraph whose text changed since the link was bound
+      // (removed-links/R2, #11). Output files and requirements are not
+      // paragraphs; a link no longer declared is history (#2); the target
+      // must be one that al index --align can move the binding to.
+      if (b.holder_sha256) {
+        const hq = qualify(String(b.holder), null);
+        const hp = hq.req ? now.requests.get(hq.req)?.paras.get(hq.id) : now.spec.get(hq.id) ?? adrParagraph(now, hq.id);
+        declared ??= declaredNow(top, now);
+        alignable ??= canAlignTo(now);
+        if (hp && hp.sha256 !== b.holder_sha256 && declared(b) && alignable(b.target)) {
+          add('hint', 'holder-changed', hp, b.holder, `${b.link} ${b.target}: this paragraph changed after the link was bound. Check that it still ${b.link} ${b.target}, then al index --align ${b.holder}`);
+        }
+      }
       const t = qualify(String(b.target), null);
       if (t.cross) continue;
       const cur = resolve(now, t);
@@ -316,6 +339,9 @@ export function checks(top, { base, phrases = [], issues = null }) {
       if ((Array.isArray(r.data?.dispositions) ? r.data.dispositions : []).some((d) => d?.source === b.holder && d.spec === b.target && d.spec_sha256 === cur.sha)) continue;
       // A superseded ADR's links are history (schema.md 5).
       if (now.adrs.get(String(b.holder))?.status === 'superseded') continue;
+      // A link that its holder no longer declares, or whose holder is gone, is history too (#2).
+      declared ??= declaredNow(top, now);
+      if (!declared(b)) continue;
       const hq = qualify(String(b.holder), null);
       const hp = hq.req ? now.requests.get(hq.req)?.paras.get(hq.id) : now.spec.get(hq.id);
       const msg = /^[RQ]\d+$/.test(t.id ?? '')
@@ -358,16 +384,26 @@ export function checks(top, { base, phrases = [], issues = null }) {
 
   // ADRs (schema.md 5). An ADR's text may be rewritten when its decision
   // stays, so a change is a hint for the review (#238). Links may be added to
-  // the heading marker of an accepted ADR: the same kind, each old link kept,
-  // the rest unchanged; that gives no finding.
-  const linksAdded = (a, h) => a.status === 'accepted' && a.head && h.head && a.rest === h.rest && a.head.kind === h.head.kind
-    && Object.entries(a.head.links).every(([k, refs]) => refs.every((x) => h.head.links[k].includes(x)));
+  // the heading marker of an accepted ADR, with nothing else in that line
+  // changed (#4) and the rest unchanged; that gives no finding.
+  const linksAdded = (a, h) => a.status === 'accepted' && a.head && h.head && a.rest === h.rest
+    && onlyLinksAdded(a.marker, h.marker, now.kinds);
   for (const [id, a] of was?.adrs ?? []) {
     if (!['accepted', 'superseded'].includes(a.status)) continue;
     const h = now.adrs.get(id);
     if (!h) add('hint', 'adr-changed', a.file, id, `${id} was ${a.status} and its file is gone: check that its decision is not lost; an ADR that no longer holds is superseded by a new ADR, not deleted`);
     else if (h.body !== a.body && !linksAdded(a, h)) add('hint', 'adr-changed', h.head ?? h.file, id, `${id}'s text changed: check that its decision is unchanged; if the decision changed, write a new ADR that supersedes it`);
   }
+  // Every ADR, whatever its status (#4): a first line that is not a known
+  // status, and a marker line that holds more than its ID, a kind and links.
+  for (const a of now.adrs.values()) {
+    if (!a.known) add('hint', 'adr-status', `${a.file}:1`, a.id, `${a.id}'s first line is not a status that al knows: write "Status: proposed", "Status: accepted" or "Status: superseded by ADR-<n>" (or by a list, "ADR-11, ADR-12")`);
+    for (const m of markerLines(a.text, now.kinds)) {
+      const where = `${a.file}:${m.line}`;
+      if (!m.extras) add('hint', 'adr-marker', where, m.id, `the marker line of ${m.id} is not a well-formed marker, so al does not read it: write "<!-- ${m.id} <kind> <links> -->" alone on the line; a page can show text after its -->`);
+      else if (m.extras.length) add('hint', 'adr-marker', where, m.id, `the marker of ${m.id} holds more than its ID, a kind and links: ${m.extras.map((x) => `"${x}"`).join(', ')}; a page can show text that it hides`);
+    }
+  }
   for (const a of now.adrs.values()) {
     if (!['proposed', 'accepted'].includes(a.status)) continue;
     const missing = ['source', 'decides'].filter((w) => !a.head?.links[w].length);

package/src/v4/conclude.js

@@ -3,7 +3,7 @@
 // state, and refuses while a promise change has no signed requirement, a
 // spike's current question is not signed, or a change paragraph with a
 // baseline effect has no valid disposition for its current version. A promise
-// change of the branch, against the merge-base with main, counts as al check
+// change of the branch, against its base (baseOf), counts as al check
 // counts it (branchOf, #217). With
 // --yes it writes the Outcome, sets the status and archives the request.
 import { mkdirSync, renameSync, statSync } from 'node:fs';
@@ -11,7 +11,7 @@ import { dirname, join } from 'node:path';
 import { Fail, day, exists, guard, isName, now, write } from './base.js';
 import { branchOf } from './checks.js';
 import { judgeRequest } from './dispositions.js';
-import { git, mergeBase } from './git.js';
+import { baseOf, git } from './git.js';
 import { openRecord, recordText } from './records.js';
 import { isPromise, loadState, qualify, servesSigned } from './state.js';
 import { signState } from './views.js';
@@ -95,9 +95,10 @@ export function conclude({ top, args, opts }) {
   const r = state.requests.get(name);
   if (!r) throw new Fail(`no request named ${name}`, 'al context lists the open requests');
   if (!r.open) throw new Fail(`${name} is already archived (requests/archive/${name}); an archived request is not concluded again`, `al context ${name}`);
-  const base = mergeBase(top);
+  const found = baseOf(top);
+  const base = found?.commit ?? null;
   const branch = base ? branchOf(top, state, loadState(top, base), base).uncovered : [];
-  const read = base ? `working tree · base ${base.slice(0, 7)} (merge-base with main)` : 'working tree · no base';
+  const read = base ? `working tree · base ${base.slice(0, 7)} (merge-base with ${found.ref})` : 'working tree · no base';
   const notKnown = base ? NOT_KNOWN : ['the promise changes of the branch: no base (no main branch, or no commit)', ...NOT_KNOWN];
   const { out, judged } = reasons(state, r, branch);
   if (out.length) {

package/src/v4/git.js

@@ -12,15 +12,29 @@ export function git(top, args, { allowFail = false } = {}) {
   }
 }
 
-// The merge-base of HEAD with main (or origin/main), or null.
-export function mergeBase(top) {
-  for (const main of ['main', 'origin/main']) {
-    if (git(top, ['rev-parse', '--verify', '--quiet', `${main}^{commit}`], { allowFail: true }) === null) continue;
-    return git(top, ['merge-base', 'HEAD', main], { allowFail: true }) || null;
-  }
-  return null;
+// The base of the branch, { commit, ref }, or null: the merge-base of HEAD
+// with main or with origin/main, and the ref that gave it. With only one of
+// the two, that one. With both, the later merge-base (the other is its
+// ancestor), so a local main that is behind origin/main does not give an old
+// base; when neither is the later, the local main (#22). It reads only the
+// refs in the clone, and never fetches.
+export function baseOf(top) {
+  const refs = ['main', 'origin/main'].filter((ref) => git(top, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], { allowFail: true }) !== null);
+  const of = (ref) => {
+    const commit = git(top, ['merge-base', 'HEAD', ref], { allowFail: true });
+    return commit ? { commit, ref } : null;
+  };
+  if (!refs.length) return null;
+  const local = of(refs[0]);
+  if (refs.length === 1) return local;
+  const remote = of(refs[1]);
+  if (!local || !remote || local.commit === remote.commit) return local;
+  return git(top, ['merge-base', '--is-ancestor', local.commit, remote.commit], { allowFail: true }) === null ? local : remote;
 }
 
+// The base commit of the branch (baseOf), or null.
+export const mergeBase = (top) => baseOf(top)?.commit ?? null;
+
 // Git objects by name (a blob hash, or `<commit>:<path>`), read with one
 // `git cat-file --batch` process: Map name -> bytes for each name that is a
 // blob. A missing, ambiguous or other object is not in the Map. Every reader

package/src/v4/indexer.js

@@ -2,7 +2,7 @@
 // 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';
@@ -109,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
@@ -119,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));
     }
@@ -139,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;
@@ -185,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'); }
@@ -208,8 +281,9 @@ export function index({ top, opts }) {
   if (symlinkOn(top, `${root}/adr`)) notes.push(`not indexed: ${root}/adr: through a symlink`);
   const names = requestNames(top);
 
-  // The base: the merge-base with main; with no main, HEAD (so a committed
-  // link with no binding stays unknown); with no commit, nothing.
+  // The base: mergeBase (the merge-base with main or origin/main); with no
+  // main, HEAD (so a committed link with no binding stays unknown); with no
+  // commit, nothing.
   const main = mergeBase(top);
   const head = git(top, ['rev-parse', '--verify', '--quiet', 'HEAD'], { allowFail: true });
   const base = main ?? head ?? null;
@@ -239,13 +313,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) {
@@ -276,6 +362,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) {
@@ -331,7 +444,7 @@ export function index({ top, opts }) {
     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

@@ -9,10 +9,11 @@
 // - 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 (D3);
+// - 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.
+//   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';
@@ -30,6 +31,9 @@ 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);
 
@@ -64,8 +68,29 @@ function itemOf(x, file) {
   return { key, ref, url: typeof x.url === 'string' ? x.url : null, repository, number, body: x.body, comments: x.comments, parent: x.parent, file };
 }
 
-// The items of the folder that the caller saved (SP-12): { items, unread }.
-// A folder that is not there is a refusal.
+// 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;
@@ -78,7 +103,9 @@ export function loadItems(cwd, folder) {
   const items = [];
   const unread = [];
   const shown = (name) => `${folder.replace(/\/+$/, '')}/${name}`;
-  for (const name of readdirSync(dir).filter((n) => n.endsWith('.json')).sort()) {
+  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 {
@@ -94,7 +121,7 @@ export function loadItems(cwd, folder) {
       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 };
+  return { folder, items, unread, owns };
 }
 
 // The names of the repos that the config names, each with its folder or why it has none.
@@ -133,7 +160,7 @@ function written(ref, names, own, folders) {
   return out;
 }
 
-export function issueHints(top, state, matchers, add, { folder, items, unread }) {
+export function issueHints(top, state, matchers, add, { folder, items, unread, owns }) {
   const notKnown = [];
   const names = namedRepos(top, state.config);
   const cited = supersededIn(state);
@@ -155,10 +182,12 @@ export function issueHints(top, state, matchers, add, { folder, items, unread })
 
   // 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 = [];
@@ -199,34 +228,41 @@ export function issueHints(top, state, matchers, add, { folder, items, unread })
   }
   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.
+  // 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 = null;
-    for (const s of Array.isArray(r.data?.sources) ? r.data.sources : []) {
-      const url = isMap(s) && typeof s.url === 'string' ? s.url : null;
-      if (!url) continue;
-      const k = keyOf(url);
-      const it = items.find((x) => (x.url && x.url === url) || (x.ref && holds(url, x.ref)) || (k && slug(x.key) === slug(k)));
-      if (it) ids = { keys: new Set([it.key, it.ref].filter(Boolean).map(slug)), urls: new Set([url, it.url].filter(Boolean)), ref: it.ref };
-      else if (k) ids = { keys: new Set([slug(k)]), urls: new Set([url]), ref: null };
-      if (ids) break;
+    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();
-  const noOwn = 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) {
-      noOwn.add(n.r.name);
-      continue;
-    }
+    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) {
@@ -237,17 +273,22 @@ export function issueHints(top, state, matchers, add, { folder, items, unread })
     // 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) : [];
-    if (p !== null && !parent.length) {
+    // 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;
     }
-    // A parent's url names the own item when it is the own item's url or its source's, or holds its ref.
-    const url = isMap(p) && typeof p.url === 'string' ? p.url : null;
     if (url && (mine.urls.has(url) || (mine.ref && holds(url, mine.ref)))) continue;
     if (parent.some((x) => mine.keys.has(slug(x)))) continue;
-    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]})${parent.length ? `; its parent is ${parent[0]}` : ''}`);
+    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}`);
   }
-  for (const name of noOwn) notKnown.push(`whether the items of ${name} are children of its own item: no origin source of ${name} names an item`);
 
   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`);

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());

package/src/v4/repos.js

@@ -289,7 +289,7 @@ export function crossRepo(top) {
   return { repos: repos.map(({ dir, ...r }) => r), links, results };
 }
 
-// In an output repo: the files that the branch changed (merge-base with main
+// In an output repo: the files that the branch changed (the base, mergeBase,
 // to the working tree, and untracked files not ignored), or with no base every
 // file; never under .assuredloop/.
 function changedFiles(top, base) {

package/src/v4/state.js

@@ -7,7 +7,7 @@ import { parse } from 'yaml';
 import { exists, read, recordPath, sha256 } from './base.js';
 import { loadConfig, loadSchema } from './config.js';
 import { fileAt, filesAt, git } from './git.js';
-import { KINDS, groupOf, parseMarkdown } from './markers.js';
+import { KINDS, groupOf, lf, parseMarkdown } from './markers.js';
 import { frameOf, requirements, signedText } from './request-md.js';
 import { SIGNED } from './snapshot.js';
 import { SPEC, docsInScope, parseScopes, symlinkOn } from './scope.js';
@@ -166,10 +166,16 @@ export function loadState(top, rev = null) {
     const id = `ADR-${Number(m[1])}`;
     const status = /^\s*Status:\s*([a-z]+)/i.exec(text)?.[1].toLowerCase() ?? null;
     const head = paragraphs.find((p) => p.id === id) ?? null;
-    // The ADR that its status line names: `Status: superseded by ADR-n` (#238).
-    const n = /^\s*Status:[ \t]*superseded[ \t]+by[ \t]+ADR-(\d+)[ \t]*\r?(?:\n|$)/i.exec(text)?.[1];
-    const by = n === undefined ? null : `ADR-${Number(n)}`;
-    adrs.set(id, { id, file, text, status, by, body: adrBody(text), rest: head && adrRest(text, head), paragraphs, head });
+    // The status line that al knows: `Status: proposed`, `accepted` or
+    // `superseded by ADR-n` (#238), or by a list joined by commas and `and`,
+    // `ADR-11, ADR-12 and ADR-13` (#1). `by` is the ADRs that it names;
+    // `known` is whether it is the file's first line (#4). One parse gives
+    // both, so superseded-status and adr-status agree.
+    const s = /^(\s*)Status:[ \t]*(?:proposed|accepted|superseded[ \t]+by[ \t]+(ADR-\d+(?:(?:[ \t]*,[ \t]*(?:and[ \t]+)?|[ \t]+and[ \t]+)ADR-\d+)*))[ \t]*\r?(?:\n|$)/i.exec(text);
+    const by = [...new Set([...(s?.[2] ?? '').matchAll(/ADR-(\d+)/gi)].map((m) => `ADR-${Number(m[1])}`))];
+    const known = Boolean(s) && !/[\r\n]/.test(s[1]);
+    const marker = head && lf(text).split('\n')[head.line - 1];
+    adrs.set(id, { id, file, text, status, by, known, body: adrBody(text), rest: head && adrRest(text, head), paragraphs, head, marker });
   }
   return { top, rev, config, kinds, root, get, docs, scopes, lints, spec, requests, adrs, unreadableAdrs };
 }