@assuredloop/cli 0.2.1 → 0.2.3

package/README.md

@@ -66,7 +66,9 @@ Search at level 2 needs the library `@huggingface/transformers` 4.3.1 (see
 
   GitHub does not show the marker. The ID is one flat number per file, and
   it is never used again. `al` computes a display number, for example
-  `INV-41 (2.3:4, in Export links)`, which can change when text moves.
+  `INV-41 (2.3:4, in Export links)`, which can change when text moves. So
+  a heading needs no number of its own: write `## The proxy`, not
+  `## 7. The proxy`.
 - **Kinds.** Promise kinds (purpose, scope, rule, limit, definition): a
   change needs a signed requirement that covers it. Design kinds (component,
   interface, data, flow, choice) and `approach` (how one change is built):
@@ -76,7 +78,15 @@ Search at level 2 needs the library `@huggingface/transformers` 4.3.1 (see
 - **A request** is the folder `requests/<name>/`: `origin/` (the owner's words
   and the sign-offs, as snapshots with SHA-256), `request.md` (the dialog, the
   organized requirement R1…, the decisions D1…) and, from path 2, `spec.md`,
-  the change spec, with IDs SP-1, SP-2…
+  the change spec, with IDs SP-1, SP-2… The order of its paragraphs is
+  free. The recommended order is one section per topic. Each section has
+  the promise paragraph first, then the design that keeps it, with its
+  rationale and examples, then its open points. Cross-cutting design and
+  decisions follow. While the request is open, a paragraph of its change
+  spec may be deleted: its ID is retired and never used again, and
+  `al check` gives a hint. In `specs/`, a removal needs `removes:`. Plan,
+  step and migration paragraphs may live in the tracker issue that a task's
+  `ref` names, instead of in the change spec.
 - **Records** in `.assuredloop/records/`, committed to git: one per request
   (its sources, requirement versions, sign-offs, decisions, tasks, the
   bindings of its links and the dispositions of its paragraphs) and one per
@@ -136,8 +146,11 @@ with a baseline effect has no valid disposition for its current version.
   request's whole trace; `--at <commit>` any v4 state.
 - `al conclude <name>`: the close rule; with `--yes` it writes the Outcome
   and moves the request to `requests/archive/<name>/`.
-- `al export [--at <commit>] [--out <file>]`: one JSONL row per paragraph
-  version, with its role, version, commit and links. It is not committed.
+- `al export [--at <commit>] [--out <file>] [--yes]`: one JSONL row per
+  paragraph version, with its role, version, commit and links. It is not
+  committed. With no `--out`, it writes the rows to standard output. With
+  `--out`, it shows the path, the row count and whether it replaces an
+  existing file; with `--yes`, it writes the file.
 - `al search <words>`: see "Search".
 
 Every command that changes files, except `new` and `index`, shows what it
@@ -147,7 +160,10 @@ tool cannot know).
 
 ## Settings
 
-`.assuredloop/config.yaml`, at the repo's root. Every key is optional.
+`.assuredloop/config.yaml`, at the repo's root. Every key is optional. A
+spec root that is outside the repository, reached through a symlink, or not a
+folder is a `not ok` in `al check`. Only the default root, `specs`, may be
+absent.
 
 ```yaml
 root: specs                # the spec folder; every *.md in it except adr/ is a spec doc
@@ -260,7 +276,7 @@ those commits. To move:
 | The tool checks | The skill asks | The owner decides |
 |---|---|---|
 | `al conclude` refuses on its three conditions (see "The close rule") | write the owner's words and the organized requirement, and ask for the sign-off | what is wanted, by signing the organized requirement |
-| IDs: missing, used twice, lost, used again; kinds and links; links that do not resolve; sign-off coverage of promise changes; path and typo claims; dispositions and exact equality; stale bindings; overlapping changes; ADR text changes; result applicability, as hints | choose the path, and state it in a commit message and the PR | whether a changed requirement is signed again |
+| IDs: missing, used twice, lost, used again; kinds and links; links that do not resolve; sign-off coverage of promise changes; path and typo claims; dispositions and exact equality; stale bindings; overlapping changes; ADR text changes; result applicability; a design paragraph that links to none of its requirement's promise paragraphs in its change spec; a `for:` that names no task, as hints | choose the path, and state it in a commit message and the PR | whether a changed requirement is signed again |
 | `check --strict` exits 1 on a `not ok`, when a project opts in | record each later decision, with its source | decisions whose source is the owner, such as dropping or keeping work |
 
 `al` checks that declarations are well formed and that references resolve.

package/bin/al.js

@@ -29,7 +29,7 @@ const COMMANDS = {
   index: { run: index, positionals: 0, options: { align: { type: 'string' } } },
   spec: { run: spec, positionals: (o) => (o['add-ids'] === undefined ? Infinity : 0), options: { 'add-ids': { type: 'string' }, prefix: { type: 'string' }, yes: { type: 'boolean' } } },
   check: { run: check, positionals: 0, options: { strict: { type: 'boolean' } } },
-  export: { run: exportCommand, positionals: 0, options: { at: { type: 'string' }, out: { type: 'string' } } },
+  export: { run: exportCommand, positionals: 0, options: { at: { type: 'string' }, out: { type: 'string' }, yes: { type: 'boolean' } } },
   search: {
     run: search,
     options: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assuredloop/cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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

@@ -57,8 +57,13 @@ The export link MUST expire 30 minutes after the email is sent.
 ```
 
 - When you edit a marked paragraph, keep its marker line and the blank lines
-  around it. Keep the ID when you move the paragraph. Never renumber or
-  delete an ID: a lost ID is `not ok`.
+  around it. Keep the ID when you move the paragraph. Never renumber an ID,
+  and never use one again.
+- In an open request's change spec, you may delete a paragraph with its
+  marker. Its ID is retired and never used again. `al check` gives a hint
+  that names the deletion; when it is on purpose, nothing more is needed. In
+  `specs/`, a removal needs `removes:<ID>` in a change spec: a lost ID there
+  is `not ok`.
 - For a new paragraph, write the text with no marker. Then run
   `al spec --add-ids <file> --yes`: it gives each unmarked paragraph the next
   free ID. Then write the kind and the links into each new marker.
@@ -131,11 +136,19 @@ The export link MUST expire 30 minutes after the email is sent.
    deliver with the owner's sign-off or after it. A change that touches no
    promise kind needs no sign-off.
 2. Write the design in `requests/<name>/spec.md`, the change spec: the
-   promises this change adds or changes, its design, its plan. Run
+   promises this change adds or changes, its design, its plan. The order
+   of the paragraphs is free. The recommended order is one section per
+   topic. Each section has the promise paragraph first, then the design
+   that keeps it, with its rationale and examples, then its open points.
+   Cross-cutting design and decisions follow. Run
    `al spec --add-ids requests/<name>/spec.md --yes` for the IDs (SP-1,
    SP-2…), then write the kinds and links. A paragraph that relies on a spec
    paragraph says `builds-on:<ID>`. One that replaces it says `changes:<ID>`.
-   One that removes it says `removes:<ID>`. Never copy the old text.
+   One that removes it says `removes:<ID>`. Never copy the old text. A
+   design or approach paragraph that keeps a promise paragraph of this
+   change spec says `builds-on:SP-n`. `al check` gives a hint when it serves
+   a requirement and links to none of that requirement's promise
+   paragraphs here.
 3. Snapshot each later word of the owner that you rely on:
    `al record <name> origin --url <where> --from - --yes`. Record each later
    decision: `al record <name> decision --source <who> --text "<it>" --yes`.
@@ -178,8 +191,9 @@ As path 2, in parts. Each part consolidates the paragraphs it delivers,
 with their dispositions, in its own PR. Tasks are optional: where the
 project uses them, list them in the record as
 `tasks: [{id: T2, ref: "issue #34", delivers: [R3]}]`, and name the task in
-the commit messages of its PRs. Run `al conclude <name> --yes` with the last
-part.
+the commit messages of its PRs. Plan, step and migration paragraphs may live
+in the tracker issue that the task's `ref` names, instead of in the change
+spec. Run `al conclude <name> --yes` with the last part.
 
 ## Path S: a spike
 

package/src/v4/check.js

@@ -4,11 +4,14 @@
 // 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`. --strict raises every marker lint and an invalid
-// disposition to `not ok`; the hints that need judgment stay hints.
+// disposition to `not ok`; the hints that need judgment stay hints. A lost ID
+// of an open request's change spec is a hint, also under --strict (#230).
+import { parse as parseYaml } from 'yaml';
+import { read, recordPath } from './base.js';
 import { loadConfig, loadSchema } from './config.js';
 import { mergeBase } from './git.js';
 import { diffParagraphs, idLints } from './ids.js';
-import { docsInScope, idsEverUsed, isShallow, notRead, parseScopes, rootProblem, SPEC } from './scope.js';
+import { docsInScope, idsEverUsed, isShallow, notRead, parseScopes, rootNotOk, rootProblem, SPEC } from './scope.js';
 import { Fail } from './spec.js';
 import { centralLookup } from './repos.js';
 import { checks } from './checks.js';
@@ -34,7 +37,7 @@ export function check({ top, opts }) {
       lints.push(...idLints(head, head));
       continue;
     }
-    lints.push(...idLints(before, head, { everUsed: used.get(scope) ?? [], removes: scope === SPEC ? removes : [] }));
+    lints.push(...idLints(before, head, { everUsed: used.get(scope) ?? [], removes: scope === SPEC ? removes : [] }).map((l) => deleted(top, l)));
     changes.push(...diffParagraphs(before, head).filter((c) => c.changes.length));
   }
 
@@ -43,14 +46,17 @@ export function check({ top, opts }) {
   const shown = lints.filter((l) => !(l.code === 'no-link' && t10.adopted.has(l.id) && !l.file.startsWith('requests/')));
   lints.length = 0;
   lints.push(...shown);
-  const severity = (l) => (opts.strict ? 'not ok' : l.severity);
+  const severity = (l) => (opts.strict && !l.staysHint ? 'not ok' : l.severity);
   const body = notRead(top, config);
+  // A root that config sets but that is not read is a not ok, as in al index (#218).
+  const rootLine = rootNotOk(top, config);
+  if (rootLine) body.push(rootLine);
   body.push(...lints.map((l) => `${severity(l)} ${l.code} ${l.file}:${l.line} ${l.id ?? '-'} ${l.message}`));
   if (base) body.push(...changes.map((c) => `${c.file} ${c.id} ${c.changes.join('+')}`));
   if (!lints.length) body.push('ok: no marker lint');
   body.push(...t10.findings.map((f) => `${f.severity} ${f.code} ${f.where} ${f.id} ${f.message}`));
   // Under --strict every marker lint is a not ok.
-  const notOk = lints.length > 0 || t10.findings.some((f) => f.severity === 'not ok');
+  const notOk = Boolean(rootLine) || lints.some((l) => severity(l) === 'not ok') || t10.findings.some((f) => f.severity === 'not ok');
   // In an output repo: the central IDs that the branch's changed files cite (T12).
   const central = centralLookup(top);
   body.push(...central.body);
@@ -61,13 +67,38 @@ export function check({ top, opts }) {
   return {
     body,
     read: base ? `working tree · base ${base.slice(0, 7)} (merge-base with main)` : 'working tree · no base',
-    next: nextStep([...lints.map(severity), ...t10.findings.map((f) => f.severity),
+    next: nextStep([...(rootLine ? ['not ok'] : []), ...lints.map(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')),
     notKnown,
     exit: opts.strict && notOk ? 1 : 0,
   };
 }
 
+// A lost ID of an open request's change spec (its file at the base is
+// requests/<name>/spec.md): deleting a paragraph there is ordinary editing,
+// so it is a hint that names the deletion and each disposition or wording
+// decision of the request's record that names the ID (#230, D1-D4).
+const OPEN_SPEC = /^requests\/(?!archive\/)([^/]+)\/spec\.md$/;
+function deleted(top, l) {
+  const name = l.code === 'lost-id' && OPEN_SPEC.exec(l.file)?.[1];
+  if (!name) return l;
+  const source = `${name}/${l.id}`;
+  let rec;
+  try {
+    rec = parseYaml(read(top, recordPath(name)) ?? 'null');
+  } catch {
+    rec = null;
+  }
+  const list = (x) => (Array.isArray(x) ? x : []);
+  const says = { incorporated: (d) => `incorporated as ${d.spec}`, removed: (d) => `removed ${d.spec}`, superseded: (d) => `superseded by ${d.by}` };
+  const facts = [
+    ...list(rec?.dispositions).filter((d) => d?.source === source && says[d.disposition]).map((d) => `its disposition says ${says[d.disposition](d)}`),
+    ...list(rec?.decisions).filter((d) => d?.wording?.source === source).map((d) => `decision ${d.id} names its wording`),
+  ];
+  const message = `${source} is deleted${facts.map((f) => `; ${f}`).join('')}. If that is on purpose, nothing more is needed: the ID is retired and never used again.`;
+  return { ...l, severity: 'hint', staysHint: true, message };
+}
+
 // The Next line names what to do for what printed: a not ok, a hint, both, or
 // neither (#198).
 function nextStep(severities, noId) {

package/src/v4/checks.js

@@ -6,7 +6,7 @@
 import { createHash } from 'node:crypto';
 import { parse as parseYaml } from 'yaml';
 import { read } from './base.js';
-import { judgeRequest } from './dispositions.js';
+import { droppedUnsigned, judgeRequest } from './dispositions.js';
 import { commitsOf, git } from './git.js';
 import { diffParagraphs } from './ids.js';
 import { crossResults } from './repos.js';
@@ -16,6 +16,7 @@ import {
 } 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';
 
 const DESIGN = ['component', 'interface', 'data', 'flow', 'choice'];
 const TIER = /^[ \t]*Tier:[ \t]*(0|1d|1|2|3|S)\b[ \t]*(?:—|–|--?)?[ \t]*(.*)$/m;
@@ -62,13 +63,12 @@ function changesOf(now, was) {
 
 const changeWord = (c) => (c.changes.includes('New') ? 'new' : c.changes.includes('Removed') ? 'removed' : c.changed ? 'changed' : 'given another kind');
 
-export function checks(top, { base, strict = false }) {
-  const now = loadState(top);
-  const was = base ? loadState(top, base) : null;
-  const findings = [];
-  const notKnown = [];
-  const at = (p) => (p ? `${p.file}:${p.line}` : '-');
-  const add = (severity, code, p, id, message) => findings.push({ severity, code, where: typeof p === 'string' ? p : at(p), id, message });
+// The branch against its base, in states `now` and `was` (null with no
+// base): each paragraph's change, adoption aside, the path claim, and the
+// promise changes with no signed requirement that covers them (design.md 6).
+// A change paragraph that is validly abandoned with no kept effect needs none.
+// al check reports each of those, and al conclude refuses on them (DES-37).
+export function branchOf(top, now, was, base) {
   const promise = (k) => isPromise(now, k);
   const open = [...now.requests.values()].filter((r) => r.open);
   // Adoption on the branch (D16, D21): a spec paragraph that is new at the
@@ -102,9 +102,12 @@ export function checks(top, { base, strict = false }) {
   const isPromiseChange = (c) => (c.changed && (promise(c.head?.kind) || promise(c.base?.kind)))
     || (c.kindChange && (promise(c.head.kind) || promise(c.base.kind)));
 
-  // Sign-off coverage (design.md 6): a promise change with no signed requirement that covers it.
+  // Sign-off coverage: a promise change with no signed requirement that covers it.
+  const uncovered = [];
   for (const c of changes.filter(isPromiseChange)) {
     if (typo.has(c.name)) continue;
+    const r = c.request && c.head ? now.requests.get(c.request) : null;
+    if (r && !r.spike && droppedUnsigned(now, r, c.head, { typo, baseSpec: was?.spec ?? null })) continue;
     let covered;
     if (!c.head) {
       if (c.request) continue; // a change spec paragraph taken out is no promise change
@@ -113,9 +116,26 @@ export function checks(top, { base, strict = false }) {
     } else {
       covered = servesSigned(now, c.head, c.request);
     }
-    if (!covered) add('not ok', 'signoff-coverage', c.head ?? c.base, c.name, `a ${(c.head ?? c.base).kind} paragraph is ${changeWord(c)} with no signed requirement that covers it`);
+    if (!covered) uncovered.push(c);
   }
 
+  return { changes, captured, notAdopted, claim, commits, typo, isPromiseChange, uncovered };
+}
+
+export function checks(top, { base, strict = false }) {
+  const now = loadState(top);
+  const was = base ? loadState(top, base) : null;
+  const findings = [];
+  const notKnown = [];
+  const at = (p) => (p ? `${p.file}:${p.line}` : '-');
+  const add = (severity, code, p, id, message) => findings.push({ severity, code, where: typeof p === 'string' ? p : at(p), id, message });
+  const promise = (k) => isPromise(now, k);
+  const open = [...now.requests.values()].filter((r) => r.open);
+  const { changes, captured, notAdopted, claim, commits, typo, isPromiseChange, uncovered } = branchOf(top, now, was, base);
+
+  // Sign-off coverage (design.md 6): a promise change with no signed requirement that covers it.
+  for (const c of uncovered) add('not ok', 'signoff-coverage', c.head ?? c.base, c.name, `a ${(c.head ?? c.base).kind} paragraph is ${changeWord(c)} with no signed requirement that covers it`);
+
   // The path claim (design.md 7), and the typo claim's words (design.md 6).
   if (!base) notKnown.push('no base, so the path claim was not read');
   else if (!claim) {
@@ -237,6 +257,50 @@ export function checks(top, { base, strict = false }) {
     }
   }
 
+  // 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);
+  for (const r of open) {
+    const own = new Set(r.paras.keys());
+    const key = (ref) => qualify(self(ref), r.name, own).key;
+    const promises = new Map();
+    for (const p of r.paras.values()) {
+      if (!promise(p.kind)) continue;
+      for (const k of new Set(p.links.serves.map(key))) {
+        if (!promises.has(k)) promises.set(k, []);
+        promises.get(k).push(p.id);
+      }
+    }
+    if (!promises.size) continue;
+    for (const p of r.paras.values()) {
+      if (groupOf(p.kind, now.kinds) !== 'design') continue;
+      const linked = new Set([...p.links.buildsOn, ...p.links.changes].map(key));
+      for (const k of new Set(p.links.serves.map(key))) {
+        const ids = promises.get(k);
+        if (!ids || ids.some((id) => linked.has(`${r.name}/${id}`))) continue;
+        add('hint', 'design-link', p, `${r.name}/${p.id}`, `serves ${k}, but links to none of its promise paragraphs in this change spec (${ids.join(', ')}): which promise does it keep?`);
+      }
+    }
+  }
+
+  // Task references (design.md 8): where the project uses tasks, a `for:`
+  // that names no task in the record. A bare task is the paragraph's own
+  // request's. The records are read only when an open change spec has a `for:`.
+  const tasksOf = (r) => (Array.isArray(r?.data?.tasks) ? r.data.tasks : []);
+  const fors = open.flatMap((r) => [...r.paras.values()].flatMap((p) => p.links.for.map((ref) => ({ r, p, ref }))));
+  if (fors.length && [...now.requests.values()].some((r) => tasksOf(r).length)) {
+    for (const { r, p, ref } of fors) {
+      const t = self(ref);
+      if (t.includes(':')) continue;
+      const slash = t.indexOf('/');
+      const [name, id] = slash > 0 ? [t.slice(0, slash), t.slice(slash + 1)] : [r.name, t];
+      if (tasksOf(now.requests.get(name)).some((x) => String(x?.id) === id)) continue;
+      add('hint', 'unknown-task', p, `${r.name}/${p.id}`, `for:${ref}: no task ${id} in the record of ${name}`);
+    }
+  }
+
   // Bindings whose target changed since they were bound (design.md 4, 6).
   for (const r of open) {
     for (const b of Array.isArray(r.data?.bindings) ? r.data.bindings : []) {

package/src/v4/conclude.js

@@ -2,13 +2,16 @@
 // only command that refuses. It reads the working tree, the closing PR's
 // 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. With
+// 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
+// counts it (branchOf, #217). With
 // --yes it writes the Outcome, sets the status and archives the request.
 import { mkdirSync, renameSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { Fail, day, exists, guard, isName, now, write } from './base.js';
+import { branchOf } from './checks.js';
 import { judgeRequest } from './dispositions.js';
-import { git } from './git.js';
+import { git, mergeBase } from './git.js';
 import { openRecord, recordText } from './records.js';
 import { isPromise, loadState, qualify, servesSigned } from './state.js';
 import { signState } from './views.js';
@@ -17,9 +20,11 @@ const NOT_KNOWN = ['whether the code, tests and documents do what the paragraphs
   'whether the work has ended: the tool does not take a merged task or a reconciled spec as evidence of that'];
 
 // The reasons the close rule refuses, each naming its IDs; [] when it holds.
-function reasons(state, r) {
+// `branch` holds the branch's promise changes that no signed requirement covers.
+function reasons(state, r, branch) {
   const out = [];
   if (r.spike) {
+    if (branch.length) out.push(`a promise change with no signed requirement that covers it: ${branch.map((c) => c.name).join(', ')}`);
     if (!r.reqs.length) out.push(`the spike has no organized question to sign in ${r.dir}/request.md`);
     const unsigned = r.reqs.filter((q) => !signState(state, r, q).startsWith('signed'));
     if (unsigned.length) out.push(`the spike's current question is not signed: ${unsigned.map((q) => `${r.name}/${q.id} (${signState(state, r, q)})`).join(', ')}`);
@@ -33,8 +38,9 @@ function reasons(state, r) {
     ...[...r.paras.values()].filter((p) => isPromise(state, p.kind) && !dropped.has(p.id) && !servesSigned(state, p, r.name)).map((p) => `${r.name}/${p.id}`),
     ...[...state.spec.values()].filter((p) => isPromise(state, p.kind) && p.links.serves.some((s) => qualify(s, null).req === r.name)
       && !servesSigned(state, p, null)).map((p) => p.id),
+    ...branch.map((c) => c.name),
   ];
-  if (unsigned.length) out.push(`a promise change with no signed requirement that covers it: ${unsigned.join(', ')}`);
+  if (unsigned.length) out.push(`a promise change with no signed requirement that covers it: ${[...new Set(unsigned)].join(', ')}`);
   const open = judged.filter((j) => j.status === 'pending' || !j.valid);
   if (open.length) {
     out.push(`no valid disposition for the current version of ${open.map((j) => `${j.id} (${j.status === 'pending' ? 'none' : `${j.status}, not valid: ${j.reason}`})`).join(', ')}`);
@@ -89,13 +95,17 @@ 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 { out, judged } = reasons(state, r);
+  const base = mergeBase(top);
+  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 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) {
     return {
       body: out.map((x) => `refused: ${x}`),
-      read: 'working tree',
+      read,
       next: `al context ${name}; sign, record the dispositions, or align what is named, then al index`,
-      notKnown: NOT_KNOWN,
+      notKnown,
       exit: 1,
     };
   }
@@ -104,7 +114,7 @@ export function conclude({ top, args, opts }) {
   if (exists(top, target)) throw new Fail(`${target} already exists; a request name is never reused`, `al context ${name}`);
   const what = `Status: concluded, the Outcome in ${target}/request.md, status: concluded in the record, and ${r.dir}/ moved to ${target}/`;
   if (!opts.yes) {
-    return { body: [`Would conclude ${name}: ${what}`, ...block.slice(2).map((l) => `  ${l}`)], read: 'working tree', next: 'run the same command with --yes to do it', notKnown: NOT_KNOWN };
+    return { body: [`Would conclude ${name}: ${what}`, ...block.slice(2).map((l) => `  ${l}`)], read, next: 'run the same command with --yes to do it', notKnown };
   }
   const rec = openRecord(top, name);
   if (!rec) throw new Fail(`${name} has no record .assuredloop/records/requests/${name}.yaml`, 'a v4 request is made with al new');
@@ -115,5 +125,5 @@ export function conclude({ top, args, opts }) {
   renameSync(join(top, r.dir), join(top, target));
   write(top, `${target}/request.md`, md);
   write(top, rec.path, recordText(rec));
-  return { body: [`Concluded ${name}: ${what}`], read: 'working tree', next: 'commit the archive move with the closing PR', notKnown: NOT_KNOWN };
+  return { body: [`Concluded ${name}: ${what}`], read, next: 'commit the archive move with the closing PR', notKnown };
 }

package/src/v4/config.js

@@ -25,7 +25,8 @@ function read(top, name) {
 export function loadConfig(top) {
   const c = read(top, 'config.yaml') ?? {};
   if (typeof c !== 'object' || Array.isArray(c)) throw new Error(`${DIR}/config.yaml: give a mapping of settings`);
-  return { ...c, root: c.root ?? 'specs', docs: Array.isArray(c.docs) ? c.docs : [] };
+  // rootSet: config names the root itself, so al check may hold it to that (#218).
+  return { ...c, root: c.root ?? 'specs', rootSet: c.root != null, docs: Array.isArray(c.docs) ? c.docs : [] };
 }
 
 export function loadSchema(top) {

package/src/v4/dispositions.js

@@ -166,6 +166,17 @@ const nearNotes = (state, p) => {
   return near ? [`near-match ${near.id}: applied in another form?`] : [];
 };
 
+// Whether change paragraph `p` of request `r` is validly abandoned at its
+// current version with no kept effect, so that it needs no sign-off (design.md
+// 6). An archived request is judged here too: on the branch that archives it,
+// al check reads the paragraph as al conclude read it (#226).
+export function droppedUnsigned(state, r, p, opts = {}) {
+  const d = dispositionOf(r.data, `${r.name}/${p.id}`, p.sha256);
+  if (d?.disposition !== 'abandoned') return false;
+  const v = judge(state, r, p, d, opts);
+  return v.valid && v.kept === false;
+}
+
 // Every change paragraph of request `r` with a baseline effect, with the
 // disposition of its current version and its validity. A spike has none.
 export function judgeRequest(state, r, opts = {}) {

package/src/v4/export.js

@@ -11,7 +11,7 @@ import { requirements } from './request-md.js';
 import { git, readObjects } from './git.js';
 import { findCites, namedIds, outputRepos, repoConfigAt } from './repos.js';
 import { SPEC, scopeOf } from './scope.js';
-import { Fail, guard, write } from './base.js';
+import { Fail, exists, guard, write } from './base.js';
 
 const OUTPUT_LINKS = ['implements', 'verifies', 'documents'];
 const sha256 = (text) => createHash('sha256').update(text).digest('hex');
@@ -449,13 +449,18 @@ export function sectionAt(top, commit, file, id) {
 // A row as the export writes it: the design's fields, in a fixed order.
 export const exported = ({ title, ...row }) => row;
 
-// al export [--at <commit>] [--out <file>]
+// al export [--at <commit>] [--out <file>] [--yes]: --out shows what it
+// would write, and writes only with --yes (#219).
 export function exportCommand({ top, opts }) {
   const commit = resolveCommit(top, opts.at);
   const { rows, repos } = exportRows(top, commit);
   const text = rows.map((r) => JSON.stringify(exported(r))).join('\n') + (rows.length ? '\n' : '');
   if (opts.out === undefined) return { raw: text };
   guard(top, [opts.out]);
+  if (!opts.yes) {
+    const replaces = exists(top, opts.out) ? 'replacing the existing file' : 'a new file';
+    return { body: [`Would write ${rows.length} rows to ${opts.out}, ${replaces}, at ${commit.slice(0, 12)}`], next: 'run the same command with --yes to write it' };
+  }
   write(top, opts.out, text);
   const roles = {};
   for (const r of rows) roles[r.role] = (roles[r.role] ?? 0) + 1;

package/src/v4/request-md.js

@@ -32,6 +32,18 @@ export function signedText(md) {
   return `${kept.join('\n')}\n`;
 }
 
+// The signed text `text` (as signedText gives it) with no requirement in it:
+// its heading, the intro and the Out: and Assumed: text. Each requirement of
+// the section is signed with it, so a change to it unsigns them all (#216).
+export function frameOf(text) {
+  let inReq = false;
+  return text.split('\n').filter((l) => {
+    if (/^###\s+[RQ]\d+\b/.test(l)) inReq = true;
+    else if (/^#{1,6}\s/.test(l) || /^(Out|Assumed|Signed off):/.test(l)) inReq = false;
+    return !inReq;
+  }).join('\n');
+}
+
 // Each `### R<n> <title>` (or `### Q<n>`): { id, title, text, sha256, from }.
 // Its text runs from the heading to the next heading, or an Out:, Assumed:
 // or Signed off: line, with no marker line and no blank line at either end.

package/src/v4/scope.js

@@ -49,6 +49,28 @@ export const rootProblem = (config) => (!outside(config.root) && ['.', ''].inclu
   ? `.assuredloop/config.yaml: root: ${JSON.stringify(String(config.root))} is the repository top; give the spec folder, for example specs`
   : null);
 
+// The not ok line of al check for a root that cannot be read: outside the
+// repository, through a symlink, or no folder; else null. The default root
+// may be absent, with nothing at its path (#218).
+export function rootNotOk(top, config) {
+  const at = join(top, clean(config.root));
+  if (!config.rootSet && !lexists(at)) return null;
+  const why = outside(config.root) ? 'outside the repository'
+    : symlinkOn(top, clean(config.root)) ? 'through a symlink'
+      : !existsSync(at) || !lstatSync(at).isDirectory() ? 'no such folder' : null;
+  return why && `not ok spec-root .assuredloop/config.yaml - ${String(config.root).replace(/\/+$/, '')}/: ${why}`;
+}
+
+// Whether anything is at `at`, a dangling symlink included.
+function lexists(at) {
+  try {
+    lstatSync(at);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // One line for each root or docs entry that is not read, and why.
 export const notRead = (top, config) => [
   ...outsideDocs(config).map((f) => `not read: ${f}: outside the repository`),

package/src/v4/state.js

@@ -4,11 +4,12 @@
 import { readdirSync } from 'node:fs';
 import { join, posix } from 'node:path';
 import { parse } from 'yaml';
-import { read, recordPath } from './base.js';
+import { 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 { requirements } from './request-md.js';
+import { frameOf, requirements, signedText } from './request-md.js';
+import { SIGNED } from './snapshot.js';
 import { SPEC, docsInScope, parseScopes, symlinkOn } from './scope.js';
 
 const ADR_FILE = /^(\d{4})-[^/]*\.md$/;
@@ -92,6 +93,29 @@ export function loadState(top, rev = null) {
     const specFile = `${dir}/spec.md`;
     const paras = (scopes.get(`request:${name}`) ?? []).filter((p) => p.file === specFile);
     const tierOf = () => String(dataOf()?.tier ?? /^Tier:\s*(\S+)/m.exec(md)?.[1] ?? '');
+    // Whether sign-off `s` signed the intro, Out: and Assumed: text that the
+    // section has now (#216): its signed text is the section's, or its
+    // snapshot in origin/, checked against its hash, has the same frame.
+    const current = signedText(md);
+    const framed = new Map();
+    const framedBy = (s) => {
+      if (current === null) return false;
+      if (s.sha256 === sha256(current)) return true;
+      const file = typeof s.file === 'string' ? `${dir}/origin/${s.file.replace(/^origin\//, '')}` : null;
+      if (!file) return false;
+      if (!framed.has(file)) {
+        let snap = null;
+        try {
+          snap = get(file);
+        } catch {
+          snap = null;
+        }
+        const at = typeof snap === 'string' ? snap.indexOf(`\n${SIGNED}\n`) : -1;
+        const signed = at < 0 ? null : snap.slice(at + SIGNED.length + 2);
+        framed.set(file, signed !== null && sha256(signed) === s.sha256 ? frameOf(signed) : null);
+      }
+      return framed.get(file) === frameOf(current);
+    };
     requests.set(name, {
       name, open, dir, md, specFile,
       get data() { return dataOf(); },
@@ -103,7 +127,7 @@ export function loadState(top, rev = null) {
       // double-quoted string, so a record with a backslash always counts.
       mentions: (x) => typeof text === 'string' && (text.includes(x) || text.includes('\\')),
       mayAdopt: typeof text === 'string' && (text.includes('adoption') || text.includes('\\')),
-      reqs: requirements(md), paras: new Map(paras.map((p) => [p.id, p])),
+      reqs: requirements(md), paras: new Map(paras.map((p) => [p.id, p])), framedBy,
     });
   };
   for (const n of openNames) add(n, true);
@@ -183,16 +207,22 @@ export function adrParagraph(state, id) {
 export const latestVersion = (data, id) => (Array.isArray(data?.requirements) ? data.requirements : []).filter((v) => v?.id === id)
   .reduce((a, v) => (Number(v.version) > Number(a?.version ?? 0) ? v : a), null);
 
-// Whether requirement (or question) `id` of request `name` is signed at its
-// current text: a sign-off covers that id with the current text's hash.
-export function signed(state, name, id) {
+// The latest sign-off that signs requirement (or question) `id` of request
+// `name` at its current text: it covers that id with the current text's hash,
+// and it signed the section's current intro, Out: and Assumed: text. Null
+// when there is none.
+export function signedBy(state, name, id) {
   const r = state.requests.get(name);
   const q = r?.reqs.find((x) => x.id === id);
-  if (!q) return false;
+  if (!q) return null;
   return (Array.isArray(r.data?.signoff) ? r.data.signoff : [])
-    .some((s) => (Array.isArray(s?.covers) ? s.covers : []).some((c) => c?.id === id && c.sha256 === q.sha256));
+    .filter((s) => (Array.isArray(s?.covers) ? s.covers : []).some((c) => c?.id === id && c.sha256 === q.sha256) && r.framedBy(s))
+    .at(-1) ?? null;
 }
 
+// Whether requirement (or question) `id` of request `name` is signed at its current text.
+export const signed = (state, name, id) => !!signedBy(state, name, id);
+
 // Whether paragraph `p` (of request `request`, or of specs/ when null) serves a
 // requirement that is signed at its current text.
 export function servesSigned(state, p, request) {

package/src/v4/views.js

@@ -8,7 +8,8 @@ import { git, mergeBase, mergesOf } from './git.js';
 import { crossRepo, findCites } from './repos.js';
 import { diffParagraphs } from './ids.js';
 import { loadResults } from './results.js';
-import { latestVersion, loadState, named, qualify, requestOf, resolve, signed } from './state.js';
+import { latestVersion, loadState, named, qualify, requestOf, resolve, signedBy } from './state.js';
+import { isCentral } from './indexer.js';
 
 export const line = (label, text) => `${label.length < 10 ? label.padEnd(10) : `${label} `}${text}`;
 const list = (x) => (Array.isArray(x) ? x : []);
@@ -21,10 +22,8 @@ export const NOT_CHECKED = 'whether each kind is right; whether a requirement is
 // The sign-off state of one requirement or question: "signed in S1",
 // "changed since S1" or "not signed".
 export function signState(state, r, q) {
-  if (signed(state, r.name, q.id)) {
-    const s = list(r.data?.signoff).filter((x) => list(x?.covers).some((c) => c?.id === q.id && c.sha256 === q.sha256)).at(-1);
-    return `signed in ${s.id}`;
-  }
+  const s = signedBy(state, r.name, q.id);
+  if (s) return `signed in ${s.id}`;
   const before = list(r.data?.signoff).filter((x) => list(x?.covers).some((c) => c?.id === q.id)).at(-1);
   return before ? `changed since ${before.id}` : 'not signed';
 }
@@ -341,6 +340,25 @@ function checkLines(state, id, local) {
   return out;
 }
 
+// The paragraphs of specs/ and of the open change specs that build on,
+// explain or illustrate the paragraph named `who`. In the central repo,
+// `central:X` is its own X (design.md 12).
+function linkedTo(state, who) {
+  const self = (ref) => (isCentral(state.config) && ref.startsWith('central:') ? ref.slice('central:'.length) : ref);
+  const holders = [
+    ...[...state.spec.values()].map((p) => ({ p, r: null })),
+    ...[...state.requests.values()].filter((r) => r.open).flatMap((r) => [...r.paras.values()].map((p) => ({ p, r }))),
+  ];
+  const out = [];
+  for (const { p, r } of holders) {
+    const own = r ? new Set(r.paras.keys()) : new Set();
+    for (const [key, verb] of [['buildsOn', 'builds on it'], ['explains', 'explains it'], ['illustrates', 'illustrates it']]) {
+      if (p.links[key].some((ref) => qualify(self(ref), r?.name ?? null, own).key === who)) out.push(`${named(r?.name ?? null, p.id)} ${verb}`);
+    }
+  }
+  return out.length ? out.join(' · ') : 'no paragraph builds on, explains or illustrates it';
+}
+
 function idView(state, id) {
   const t = qualify(id, null);
   const r = t.req ? state.requests.get(t.req) : null;
@@ -358,6 +376,7 @@ function idView(state, id) {
     if (word === 'serves' || !refs.length) continue;
     body.push(line('Links', `${word} ${refs.join(', ')}`));
   }
+  body.push(line('Linked', linkedTo(state, who)));
   if (!t.req) {
     const govern = [...state.adrs.values()].filter((a) => (a.head?.links.decides ?? []).includes(p.id) || p.links.governedBy.includes(a.id));
     body.push(line('Governed', govern.length ? `by ${govern.map((a) => `${a.id} (${a.status ?? 'no status'}${a.status === 'superseded' ? ': history' : ''})`).join(' · ')}` : 'by no ADR'));