@assuredloop/cli 0.2.0 → 0.2.2

package/README.md

@@ -28,13 +28,13 @@ It needs Node 24 or newer and git 2.31 or newer. Install the npm package
 
     npm install --global @assuredloop/cli
 
-The recommended install adds the optional package `@assuredloop/search`
-beside it, for search at level 2 (see "Search"):
+The recommended install adds the embedding model's library beside it, for
+search at level 2 (see "Search"). `al` names the library as an optional
+dependency, so npm installs it only when you ask:
 
-    npm install --global @assuredloop/cli @assuredloop/search
+    npm install --global @assuredloop/cli @huggingface/transformers@4.3.1
 
 To pin a version, name it: `npm install --global @assuredloop/cli@<version>`.
-Give both packages the same version.
 
 The package carries the skill, at
 `$(npm root -g)/@assuredloop/cli/skills/assuredloop/SKILL.md`. Add one line to
@@ -49,7 +49,7 @@ the skill at the pinned version into the project, for example as
 `.claude/skills/assuredloop/SKILL.md`. Name that path in the AGENTS.md line,
 and say in the commit which version it came from.
 
-Search at level 2 needs the optional package `@assuredloop/search` (see
+Search at level 2 needs the library `@huggingface/transformers` 4.3.1 (see
 "Search"). Install it in the project, or beside `al`.
 
 ## The model in one page
@@ -136,8 +136,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 +150,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
@@ -176,7 +182,7 @@ itself (2, then 1, then 0), and says which level answered and why.
 |---|---|---|
 | 0 | a scan of the export | nothing |
 | 1 | a local full-text index (SQLite FTS5, BM25), with the ID in its own exact column | Node 24 or newer (`node:sqlite`) |
-| 2 | level 1, plus a small local embedding model; word and vector results are fused | the package `@assuredloop/search` |
+| 2 | level 1, plus a small local embedding model; word and vector results are fused | the library `@huggingface/transformers` 4.3.1, in the project or beside `al` |
 
 - The default query is the current system: the spec text at the selected
   commit. `--change <name>` adds that request's open change spec, its
@@ -199,7 +205,9 @@ itself (2, then 1, then 0), and says which level answered and why.
   brings it up to date before it answers; `--rebuild` builds it again.
 - Level 2 runs a small local model (bge-small-en-v1.5, pinned by its
   revision). The model download is the only data that leaves the machine.
-  `al` itself makes no network call.
+  `al` itself makes no network call. Without the library, `al search`
+  answers at level 1, and a `Not known` line says how to add level 2. Only
+  `al search` loads the library.
 
 ## One central repo, and output repos
 
@@ -299,15 +307,13 @@ in this repository.
 
 ## Releasing
 
-1. Bump `version` in `package.json` and in `packages/search/package.json` to
-   the same version in a PR, and merge it.
+1. Bump `version` in `package.json` in a PR, and merge it.
 2. Publish a GitHub Release tagged `v<version>` on that commit. Mark it a
    pre-release to publish under npm's `next` tag.
 
 `.github/workflows/publish.yml` does the rest: it runs the tests and
-`al check --strict`, checks that the tag matches both `package.json` files,
-and publishes @assuredloop/cli, then @assuredloop/search, to npm. It skips a
-package whose version is already on npm, so a failed run can run again. It
-stores no npm token: npm trusts the workflow by name, and adds a provenance
-statement saying which commit built the package. npm must trust the workflow
-for each package before its first publish.
+`al check --strict`, checks that the tag matches `package.json`, and
+publishes @assuredloop/cli to npm. It skips a version that is already on npm,
+so a failed run can run again. It stores no npm token: npm trusts the
+workflow by name, and adds a provenance statement saying which commit built
+the package.

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.0",
+  "version": "0.2.2",
   "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": {
@@ -33,5 +33,13 @@
   },
   "dependencies": {
     "yaml": "2.9.1"
+  },
+  "peerDependencies": {
+    "@huggingface/transformers": "4.3.1"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/transformers": {
+      "optional": true
+    }
   }
 }

package/src/v4/check.js

@@ -8,7 +8,7 @@
 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';
@@ -45,12 +45,15 @@ export function check({ top, opts }) {
   lints.push(...shown);
   const severity = (l) => (opts.strict ? '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.length > 0 || 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,7 +64,7 @@ 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,

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';
@@ -62,13 +62,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 +101,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 +115,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) {

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/level2.js

@@ -0,0 +1,154 @@
+// Level 2 of `al search` (design.md 11): the embedding model and the vectors.
+// `al search` gives it the rows to embed and a query, and it answers with the
+// row keys ranked by similarity; search.js fuses that list with its full-text
+// list.
+//
+// The vectors live beside al's index, in <dir>/vectors.sqlite. Only new or
+// changed rows are embedded; a change of model embeds everything again.
+// The model's library, @huggingface/transformers, is an optional peer
+// dependency: it is found by normal Node resolution (the project first, then
+// beside al) and imported only at the first embed, so no other command and no
+// search without words loads it.
+import { mkdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const BATCH = 32;
+
+// node:sqlite is imported here, not at load, so a Node without it still
+// loads this file and falls back by search.js's own check.
+async function open(dir) {
+  const { DatabaseSync } = await import('node:sqlite');
+  mkdirSync(dir, { recursive: true });
+  const db = new DatabaseSync(join(dir, 'vectors.sqlite'));
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS meta (k TEXT PRIMARY KEY, v TEXT);
+    CREATE TABLE IF NOT EXISTS vectors (key TEXT PRIMARY KEY, sha256 TEXT NOT NULL, vec BLOB NOT NULL);
+  `);
+  return db;
+}
+
+// A vector as unit length, so a dot product is the cosine.
+function unit(v) {
+  const a = Float32Array.from(v);
+  let n = 0;
+  for (const x of a) n += x * x;
+  n = Math.sqrt(n) || 1;
+  for (let i = 0; i < a.length; i++) a[i] /= n;
+  return a;
+}
+const blob = (a) => Buffer.from(a.buffer, a.byteOffset, a.byteLength);
+const vector = (b) => new Float32Array(b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength));
+
+async function embedAll(embed, texts) {
+  const out = [];
+  for (let i = 0; i < texts.length; i += BATCH) {
+    const part = texts.slice(i, i + BATCH);
+    const vs = await embed(part);
+    if (!Array.isArray(vs) || vs.length !== part.length) throw new Error(`the model gave ${vs?.length ?? 'no'} vectors for ${part.length} texts`);
+    out.push(...vs.map(unit));
+  }
+  if (out.some((v) => v.length !== out[0].length)) throw new Error('the model gave vectors of different lengths');
+  return out;
+}
+
+// A level-2 object: `model` names it in al's output; `embed(texts)` gives one
+// vector per text. `queryPrefix` is put before a query only.
+function createLevel2({ model, embed, queryPrefix = '' }) {
+  if (typeof model !== 'string' || !model) throw new Error('createLevel2 needs a model name');
+  if (typeof embed !== 'function') throw new Error('createLevel2 needs an embed function');
+  return {
+    model,
+
+    // Makes the stored vectors match `rows` ([{ key, sha256, text }]):
+    // embeds the new and changed rows and removes the others.
+    async refresh({ dir, rows }) {
+      const db = await open(dir);
+      try {
+        if (db.prepare("SELECT v FROM meta WHERE k = 'model'").get()?.v !== model) {
+          db.exec('DELETE FROM vectors');
+          db.prepare("INSERT OR REPLACE INTO meta (k, v) VALUES ('model', ?)").run(model);
+        }
+        const have = new Map(db.prepare('SELECT key, sha256 FROM vectors').all().map((x) => [x.key, x.sha256]));
+        const want = new Map(rows.map((r) => [r.key, r]));
+        const todo = rows.filter((r) => have.get(r.key) !== r.sha256);
+        const vs = await embedAll(embed, todo.map((r) => r.text));
+        db.exec('BEGIN');
+        const del = db.prepare('DELETE FROM vectors WHERE key = ?');
+        let removed = 0;
+        for (const k of have.keys()) if (!want.has(k)) { del.run(k); removed += 1; }
+        const put = db.prepare('INSERT OR REPLACE INTO vectors (key, sha256, vec) VALUES (?, ?, ?)');
+        todo.forEach((r, i) => put.run(r.key, r.sha256, blob(vs[i])));
+        db.exec('COMMIT');
+        return { embedded: todo.length, removed };
+      } finally {
+        db.close();
+      }
+    },
+
+    // The `keys` ranked by similarity to `query`, best first, at most `k`.
+    // A plain scan of the stored vectors: no vector database is needed at
+    // this size (design.md 11).
+    async rank({ dir, query, keys, k }) {
+      const [q] = await embedAll(embed, [`${queryPrefix}${query}`]);
+      const db = await open(dir);
+      try {
+        const wanted = new Set(keys);
+        const scored = [];
+        for (const { key, vec } of db.prepare('SELECT key, vec FROM vectors').all()) {
+          if (!wanted.has(key)) continue;
+          const v = vector(vec);
+          if (v.length !== q.length) throw new Error('the stored vectors and the query differ in length');
+          let s = 0;
+          for (let i = 0; i < v.length; i++) s += v[i] * q[i];
+          scored.push([key, s]);
+        }
+        scored.sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+        return scored.slice(0, k).map(([key]) => key);
+      } finally {
+        db.close();
+      }
+    },
+  };
+}
+
+export const LIBRARY = '@huggingface/transformers';
+const VERSION = '4.3.1';
+export const INSTALL = `npm install --global @assuredloop/cli ${LIBRARY}@${VERSION}`;
+
+// The library's path by normal Node resolution: from the project, then
+// beside al. Null when neither has it.
+export function findLibrary(top) {
+  for (const from of [join(top, 'package.json'), import.meta.url]) {
+    try { return createRequire(from).resolve(LIBRARY); } catch { /* not here */ }
+  }
+  return null;
+}
+
+// The real model: bge-small-en-v1.5 (MIT), the ONNX port, pinned by revision.
+const MODEL = 'Xenova/bge-small-en-v1.5';
+const REVISION = 'ea104dacec62c0de699686887e3f920caeb4f3e3';
+
+// Level 2 with the library at `path`, which is imported at the first embed.
+export function level2(path) {
+  let extractor = null;
+  async function embed(texts) {
+    if (!extractor) {
+      // The path is the library's require entry; its exports may come as a default.
+      const mod = await import(pathToFileURL(path).href);
+      const pipeline = mod.pipeline ?? mod.default?.pipeline;
+      if (typeof pipeline !== 'function') throw new Error(`${path} has no pipeline function`);
+      extractor = await pipeline('feature-extraction', MODEL, { revision: REVISION, dtype: 'q8' });
+    }
+    // bge takes the first token's vector (CLS pooling).
+    const out = await extractor(texts, { pooling: 'cls', normalize: true });
+    return out.tolist();
+  }
+  return createLevel2({
+    model: `${MODEL}@${REVISION.slice(0, 12)}`,
+    embed,
+    // bge's instruction for a short query that looks for passages.
+    queryPrefix: 'Represent this sentence for searching relevant passages: ',
+  });
+}

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/search.js

@@ -1,13 +1,10 @@
 // al search (design.md 11): the current system, a change's context and the
 // history, at the strongest level installed. Level 0 scans the export; level
 // 1 is a SQLite FTS5 index of it (BM25) with the ID in its own exact column;
-// level 2 fuses level 1 with the ranking of the optional package
-// @assuredloop/search (reciprocal rank fusion). `al` holds no model and no
-// vectors: the package does, and returns a ranked list.
+// level 2 fuses level 1 with the ranking of level2.js (reciprocal rank
+// fusion), which needs the optional peer dependency @huggingface/transformers.
 import { mkdirSync, rmSync } from 'node:fs';
-import { createRequire } from 'node:module';
 import { isAbsolute, join } from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { parse } from 'yaml';
 import { Fail, isName } from './base.js';
 import { git } from './git.js';
@@ -39,22 +36,13 @@ async function sqlite() {
   }
 }
 
-// The optional package by normal Node resolution: from the project, then
-// beside al. Null with the reason when neither has it.
+// Level 2 when its library is installed, or null with the reason. level2.js
+// is loaded only here, and the library only at its first embed.
 async function level2(top) {
-  for (const from of [join(top, 'package.json'), import.meta.url]) {
-    let path;
-    try { path = createRequire(from).resolve('@assuredloop/search'); } catch { continue; }
-    try {
-      const mod = await import(pathToFileURL(path).href);
-      const l2 = mod.default;
-      if (!l2 || typeof l2.refresh !== 'function' || typeof l2.rank !== 'function') return { reason: `${path} is not a level 2 package (no refresh and rank)` };
-      return { l2 };
-    } catch (e) {
-      return { reason: `@assuredloop/search did not load: ${e.message.split('\n')[0]}` };
-    }
-  }
-  return { reason: 'level 2 is not installed: no @assuredloop/search in the project or beside al' };
+  const { findLibrary, level2: create, LIBRARY, INSTALL } = await import('./level2.js');
+  const path = findLibrary(top);
+  if (!path) return { reason: `level 2 is not installed: no ${LIBRARY} in the project or beside al`, install: `level 2: ${LIBRARY} is not installed; to add level 2, run ${INSTALL}` };
+  return { l2: create(path) };
 }
 
 // The folder of the index: <git dir>/assuredloop, never in the working tree.
@@ -352,7 +340,7 @@ export async function search({ top, args, opts }) {
   let lite = null;
   if (level === 2) {
     found2 = await level2(top);
-    if (!found2.l2) { falls.push(found2.reason); level = 1; }
+    if (!found2.l2) { falls.push(found2.reason); notKnown.push(found2.install); level = 1; }
   }
   if (level >= 1) {
     lite = await sqlite();

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,7 @@ 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';
 
 export const line = (label, text) => `${label.length < 10 ? label.padEnd(10) : `${label} `}${text}`;
 const list = (x) => (Array.isArray(x) ? x : []);
@@ -21,10 +21,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';
 }