@assuredloop/cli 1.0.0 → 2.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:`
@@ -234,8 +253,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 +292,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 +519,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": "2.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;
 }
@@ -212,15 +212,25 @@ function places(textOf, skip) {
 }
 
 // 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)))
+    .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 +269,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/checks.js

@@ -12,11 +12,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 +185,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 +271,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 +312,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 +338,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 +383,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/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'); }
@@ -239,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) {
@@ -276,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) {
@@ -331,7 +443,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/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 };
 }