@assuredloop/cli 0.2.3 → 1.0.0

package/README.md

@@ -10,8 +10,10 @@ AssuredLoop keeps an AI focused on one change. It holds together:
 - the code, the tests and the documents that came with the change.
 
 Its command, `al`, keeps these records, checks them, and says what to do
-next. It refuses only in its own `al conclude`. Every other check is a hint;
-a project that wants blocks turns on `al check --strict` in its CI.
+next. It refuses only in its own `al conclude`. `al check` gives the AI
+review hints, and the review decides. Only a few exact rules are `not ok`
+(see "Hints, and the rules that block"). A project that wants them to block
+turns on `al check --strict` in its CI.
 
 AssuredLoop is not a lifecycle tool. It has no phases, no roles, no task
 states and no approvals beyond the owner's sign-off. How and when you design,
@@ -109,16 +111,16 @@ The user picks the path. The skill has the steps of each path.
 | 0. Fix | no promise changes: it restores what the spec says, or claims a typo in any paragraph | none | no | the PR merges |
 | 1. Small promise amend | one or a few promise paragraphs change | a short request; the PR edits `specs/` directly | yes | the PR merges |
 | 1d. Small design correction | names or wording of design paragraphs only | a short request with a one-line source note; the PR edits `specs/` directly | no | the PR merges |
-| 2. Big change | a real design, one or a few PRs | a request and a change spec | if a promise kind changes | the close rule holds |
+| 2. Big change | a real design, one or a few PRs | a request and a change spec | if a promise kind changes, or the request has an R<n> | the close rule holds |
 | 3. Epic | big, in parts over time | as 2, with optional task references | as 2 | the close rule holds |
 | S. Spike | not yet clear what to build | a request with an organized question; the findings open with the answer | yes, on the question | the answer names the question version |
 
 Every PR states its path and its claim in a commit message, for example
 `Tier: 0 — typo in INV-3` or `Tier: 2 — invoice-payments, part 1`. `al check`
 reads the newest `Tier:` line in the branch's commits, and checks the claim
-against the kinds and the changed paragraphs: "path 0, but a rule paragraph
-is changed with no typo claim" is `not ok`. It checks the labels, not their
-meaning.
+against the kinds and the changed paragraphs. Where they disagree, it gives
+a hint, for example "path 0, but a rule paragraph is changed with no typo
+claim". It checks the labels, not their meaning.
 
 **The close rule.** `al conclude <name>` refuses while a promise change has
 no sign-off, a spike's current question is not signed, or a change paragraph
@@ -140,7 +142,10 @@ with a baseline effect has no valid disposition for its current version.
 - `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 check [--strict]`: the checks of this branch against its base.
+- `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
+  items").
 - `al context [<name> | <ID>]`: where the project, a request or a paragraph
   stands. `--diff <range> --for review` is the review view. `--audit` gives a
   request's whole trace; `--at <commit>` any v4 state.
@@ -173,15 +178,101 @@ results: .assuredloop/results   # where result files are
 outputs:                   # in the central repo: its output repos
   - {name: invoicer-web, path: ../invoicer-web, commit: <sha>}
 central: {path: ../invoicer}    # in an output repo: the central repo
+phrases:                   # text for the review to look at; each match is a hint
+  - the requester          # a phrase: ignoring case, across a line break too
+  - {pattern: "Avery (asked|wants)"}   # a JavaScript regular expression
 ```
 
+`al check` gives the hint `phrase` for each match of `phrases:` in the spec
+docs, the ADRs and the Markdown files of the open requests, but their
+`origin/` folders; with `--issues <folder>`, in the work items too. The list is empty by
+default. A bad entry or an invalid pattern stops `al check` with exit 2.
+
 `.assuredloop/schema.yaml` holds the kinds and the link words, with a version.
 `al spec --add-ids` writes both files when they are absent.
 
 ADRs are `specs/adr/NNNN-<slug>.md`, with `Status: proposed`, `accepted` or
-`superseded` on the first line. The heading's marker holds `ADR-<n>` and its
-`decides:`, `source:` and `supersedes:` links. The text of an accepted ADR
-does not change; a new ADR supersedes it.
+`superseded by ADR-<n>` on the first line. 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.
+- 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:`
+  or no `decides:`.
+- A current place that names a superseded ADR also names the ADR that
+  supersedes it, in the same marker or the same paragraph. Current places
+  are the spec docs, the open requests and the proposed and accepted ADRs.
+  The chain itself and dated records are exempt: an ADR that supersedes it,
+  a superseded ADR, an ADR's `## History`, a request's `## Decisions`, the
+  `origin/` files and the archived requests. Else `al check` gives
+  `not ok superseded-cited`.
+- A superseded ADR's status line names the ADR that supersedes it, and that
+  ADR's marker has `supersedes:` for it. Else `al check` gives
+  `not ok superseded-status`.
+
+## Hints from the linked work items
+
+A project may keep its work items in any tracker, or in none. `al` never
+contacts a tracker. The caller saves the items in a folder, and
+`al check --issues <folder>` checks the items that the `tasks:` of the open
+requests name. Without `--issues`, `al check` reads no item. A task's `ref`
+names an item as `#n`, `owner/repo#n`, `<name>#n` for an output repo that
+config names, an issue URL on any host, or the item's own `ref`, for
+example `PROJ-12`. Each finding is a hint:
+
+- `issue-missing`: a task names an item that is not in the folder;
+- `issue-superseded`: the item's text names a superseded ADR without the ADR
+  that supersedes it, by the rule of `superseded-cited`;
+- `issue-bare-ref`: a bare `#n` in an item of another repository, which
+  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>`);
+- `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.
+
+The folder holds `*.json` files. Each file holds one item, or a list of
+items. An item is the JSON that the GitHub CLI prints with
+`--json number,url,body,comments,parent`, so GitHub issues need no
+conversion:
+
+| Field | What it is | Needed |
+|---|---|---|
+| `body` | the item's text | yes |
+| `url` | its address, `https://<host>/owner/repo/issues/n` for GitHub | one of `url`, `number` with `repository`, or `ref` |
+| `number` | its number in its repository | |
+| `comments` | a list, each with `body`, and `isMinimized` true for a hidden comment | no |
+| `parent` | the parent item, with `url` and `number`, or `ref`; `null` for none | no: with no `parent`, the child check is not made |
+| `ref` | the reference that a task names, for another tracker, for example `PROJ-12` | for another tracker |
+| `repository` | `owner/repo`, or a project key | no |
+
+To save GitHub issues, GitHub Enterprise included, save each issue with
+`gh issue view`. `gh issue list` gives at most 100 comments of an issue.
+
+```sh
+mkdir -p /tmp/items
+gh issue view 31 --repo acme/invoicer \
+  --json number,url,body,comments,parent > /tmp/items/invoicer-31.json
+GH_HOST=github.example.com gh issue view 5 --repo acme/web \
+  --json number,url,body,comments,parent > /tmp/items/web-5.json
+al check --issues /tmp/items
+```
+
+An item of another tracker:
+
+```json
+{"ref": "PROJ-12", "repository": "PROJ", "body": "Build the export (ADR-3).",
+ "comments": [{"body": "Done.", "isMinimized": false}], "parent": {"ref": "PROJ-1"}}
+```
 
 ## Search
 
@@ -263,21 +354,63 @@ does not change; `al` hashes each paragraph without its marker.
 
 **From 0.1.0.** v4 (0.2.0) does not read 0.1.0 records. Keep 0.1.0 pinned
 until you move. Older records stay readable as files; run the pinned 0.1.0 at
-those commits. To move:
+those commits.
+
+In a project where `.assuredloop` is a file, as 0.1.0 writes it, each `al`
+command refuses with exit 2 and one line: `al: .assuredloop is a file, so the
+project has 0.1.0 records, which v4 does not read; keep 0.1.0 pinned, or move
+as "From 0.1.0" in the README says`. It reads and writes nothing else, so
+`al check` never passes there. `al --version` and the usage message still
+work. To move:
 
 1. Finish each open 0.1.0 request on its pinned copy, or start it again
    under v4.
 2. Install 0.2.0 (see "Install").
-3. Run `al spec --add-ids`, as in steps 1-5 above. It marks every paragraph
+3. Remove the 0.1.0 file: `git rm .assuredloop`. v4 keeps its settings in
+   the folder `.assuredloop/`. If the file had a `root:` line, write the
+   same line in `.assuredloop/config.yaml` (see "Settings").
+4. Run `al spec --add-ids`, as in steps 1-5 above. It marks every paragraph
    and writes the adoption record.
 
+## Hints, and the rules that block
+
+`al check` gives the AI review hints, and the review decides. A finding is
+`not ok` only for a rule that meets two tests: breaking it lets an
+unapproved or wrong decision be built, and an exact check of the records,
+hashes and links decides it, with no judgement. These rules are:
+
+- **An unsigned requirement** (`not ok unsigned-requirement`). In each
+  request whose record has `requirements:`, open or archived, the latest
+  version of each requirement has a valid sign-off. A sign-off is valid only
+  when a `covers` entry matches the requirement's id, version and `sha256`
+  exactly; its file is in the request's `origin/` folder, and the hash of
+  its signed text equals the sign-off's `sha256`; and it records when it was
+  signed and the signer's words. A requirement in `request.md` that is not
+  its latest recorded version is not signed. An entry that `al check` cannot
+  read is `not ok` too. A promise paragraph that changes with no signed
+  requirement that covers it stays `not ok signoff-coverage`.
+- **Changed record evidence** (`not ok record-evidence`). Each origin file
+  under `sources:`, and each sign-off file, still has the hash that the
+  record lists. `al check` hashes the snapshot's text after its `---` line,
+  as `al record` did.
+- **A citation of a superseded ADR** (`not ok superseded-cited` and
+  `superseded-status`; see "Settings").
+
+A request record that cannot be read (`record-unreadable`) and a spec root
+that cannot be read (`spec-root`) are `not ok` too. Every other finding is a
+hint in every mode, `--strict` included: the marker and ID lints, the path
+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.
+
 ## What is enforced, and by whom
 
 | 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; 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 |
+| `not ok`: sign-off coverage of promise changes, unsigned requirement versions, changed record evidence, citations of superseded ADRs and their status lines, and records or a spec root that cannot be read | choose the path, and state it in a commit message and the PR | whether a changed requirement is signed again |
+| hints for the review: IDs missing, used twice, lost or used again; kinds and links; links that do not resolve; path and typo claims; dispositions and exact equality; stale bindings; overlapping changes; ADR text changes; a proposed or accepted ADR with no `source:` or no `decides:`; 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; matches of the configured phrases; with `--issues <folder>`, the hints from the linked work items | record each later decision, with its source | decisions whose source is the owner, such as dropping or keeping work |
+| `check --strict` exits 1 on a `not ok`, when a project opts in | | |
 
 `al` checks that declarations are well formed and that references resolve.
 It does not check that a kind is right, that a requirement is fully

package/bin/al.js

@@ -2,7 +2,8 @@
 // al, the v4 command (T17 made it the one in package.json's bin).
 import { parseArgs } from 'node:util';
 import { execFileSync } from 'node:child_process';
-import { readFileSync, realpathSync } from 'node:fs';
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { check } from '../src/v4/check.js';
 import { Fail, spec } from '../src/v4/spec.js';
@@ -28,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' } } },
+  check: { run: check, positionals: 0, options: { strict: { type: 'boolean' }, issues: { type: 'string' } } },
   export: { run: exportCommand, positionals: 0, options: { at: { type: 'string' }, out: { type: 'string' }, yes: { type: 'boolean' } } },
   search: {
     run: search,
@@ -102,6 +103,11 @@ async function main(argv) {
       throw new Fail(`extra argument ${JSON.stringify(extra)}: ${used} takes ${n === 0 ? 'no' : n} positional argument${n === 1 ? '' : 's'}`,
         'quote an option value that holds spaces, and leave out the extra argument');
     }
+    // 0.1.0 kept its settings in a file .assuredloop; v4 keeps a folder (#241).
+    if (statSync(join(top, '.assuredloop'), { throwIfNoEntry: false })?.isFile()) {
+      throw new Fail('.assuredloop is a file, so the project has 0.1.0 records, which v4 does not read; keep 0.1.0 pinned, or move as "From 0.1.0" in the README says',
+        'npm install --global @assuredloop/cli@0.1.0, or move as "From 0.1.0" in the README says');
+    }
     let out;
     try {
       out = await command.run({ top, cwd, args: parsed.positionals, opts: parsed.values });

package/package.json

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

@@ -10,8 +10,9 @@ description: >-
 # AssuredLoop v4
 
 `al` keeps the records of what was asked, decided, changed and delivered,
-and gives hints. It refuses only in `al conclude`. How and when you design,
-test and review is your project's way of working; this skill does not set it.
+and gives the review hints. The review decides. It refuses only in
+`al conclude`. How and when you design, test and review is your project's
+way of working; this skill does not set it.
 
 ## Start here, on every path
 
@@ -31,16 +32,19 @@ test and review is your project's way of working; this skill does not set it.
 | 0 | No promise changes: a fix that restores what the spec says, or a typo in any paragraph. | none | no |
 | 1 | One or a few promise paragraphs change. | a short request; no change spec | yes |
 | 1d | Only names or wording of design paragraphs change. | a short request; no change spec | no |
-| 2 | A real design, in one or a few PRs. | a request and a change spec | if a promise changes |
+| 2 | A real design, in one or a few PRs. | a request and a change spec | if a promise changes, or the request has an R<n> |
 | 3 | A big change, delivered in parts over time. | as path 2, part by part | as path 2 |
 | S | It is not clear yet what to build. | a request with a question | yes, on the question |
 
 The promise kinds are purpose, scope, rule, limit and definition. Work that
 grows changes its path: a small change that needs a design becomes path 2.
 
-4. Before you ask for review, run `al index`, then `al check`. Fix each
-   `not ok`, or say in the PR why it stays. A hint is an observation, not a
-   verdict.
+4. Before you ask for review, run `al index`, then `al check`. A `not ok` is
+   one of the few exact rules: a promise change or a requirement version
+   with no valid sign-off, changed record evidence, a citation of a
+   superseded ADR, or a record that cannot be read. Fix each one. A hint is
+   for the review, not a verdict: deal with it, or say in the PR why it
+   stays. A finding has the same severity with or without `--strict`.
 5. Put the claim in a commit message and in the PR, for example
    `Tier: 1 — amends INV-10`. `al check` reads the newest `Tier:` line of the
    branch.
@@ -63,7 +67,7 @@ The export link MUST expire 30 minutes after the email is sent.
   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`.
+  gets a hint that asks for it.
 - 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.
@@ -77,6 +81,20 @@ The export link MUST expire 30 minutes after the email is sent.
   `governed-by:<ADR>`; `for:<task>`. A promise, design or approach paragraph
   needs at least one link. In `specs/`, the ID of a change spec paragraph
   names its request: `invoice-exports/SP-12`.
+- An ADR in `specs/adr/` has one marker on its heading: `ADR-<n>`, its kind,
+  and its `decides:`, `source:` and `supersedes:` links. `al check` gives a
+  hint for each proposed or accepted ADR with no `source:` or no
+  `decides:`.
+- Any text may be rewritten in other words when its meaning stays the same,
+  an accepted or superseded ADR's text too. Write a new ADR that supersedes
+  it only when the decision changes, in whole or in part. `al check` gives a
+  hint on a changed ADR: check that its decision is unchanged. After the
+  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`.
 - `al` writes every hash and every derived field. Do not write them by hand.
 
 ## Path 0: a fix
@@ -122,9 +140,9 @@ The export link MUST expire 30 minutes after the email is sent.
 1. `al new <name> --tier 1d --from -`, with a one-line note of where the
    correction comes from.
 2. Change only names or wording of design paragraphs in `specs/`. Add or
-   remove no paragraph. Do not change an accepted ADR's text: a new ADR
-   supersedes it.
-3. Claim `Tier: 1d — <what changes>`. `al check` gives `not ok` when the PR
+   remove no paragraph. You may reword an ADR when its decision stays; a
+   changed decision is a new ADR that supersedes it.
+3. Claim `Tier: 1d — <what changes>`. `al check` gives a hint when the PR
    touches a promise paragraph, or adds or removes a design paragraph. No
    sign-off is needed.
 4. Run `al conclude <name> --yes` with the PR.
@@ -133,8 +151,11 @@ The export link MUST expire 30 minutes after the email is sent.
 
 1. `al new <name> --tier 2 --from -`. Write the organized requirement as in
    path 1, with `Out:` and `Assumed:` lines where they help. Draft freely;
-   deliver with the owner's sign-off or after it. A change that touches no
-   promise kind needs no sign-off.
+   deliver with the owner's sign-off or after it. Each R<n> needs the
+   owner's sign-off, also when the change touches no promise kind: until it
+   is signed, `al check` gives `not ok unsigned-requirement`. For a
+   design-only change, which needs no sign-off, write the organized section
+   with no `### R<n>`: a short note of what the design changes and why.
 2. Write the design in `requests/<name>/spec.md`, the change spec: the
    promises this change adds or changes, its design, its plan. The order
    of the paragraphs is free. The recommended order is one section per
@@ -193,7 +214,12 @@ 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. 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.
+spec. `al` never contacts a tracker: save the items in a folder (the README
+has the format and the `gh` commands), and `al check --issues <folder>`
+gives hints on them: an item missing from the folder, a superseded ADR
+named without its successor, a bare `#n` in another repository's item, an
+item that is not a child of the request's own item, and the phrases of
+`phrases:` in `.assuredloop/config.yaml`. Run `al conclude <name> --yes` with the last part.
 
 ## Path S: a spike