aval-adr 1.0.0 → 1.2.0

package/README.md

@@ -101,6 +101,28 @@ load, or a name it does not carry.
 Nothing on that surface writes. Resolving answers a question; deciding is not
 something to do on an agent's behalf.
 
+**From the parent of all your projects**, where there is no corpus above and
+several below, the same server is a **workspace**: every tool takes `repo` to name one.
+`resolve` and `history` answer for all of them when it is omitted — a map
+keyed by name, which is the cross-repository question in a single call —
+while `keys`, `heads` and `show` ask for a name, because every repository's
+heads at once is a lot of context to fetch by forgetting an argument.
+`aval repos` says what was found, and `--all-repos` renders the same map from
+the shell:
+
+```console
+$ aval resolve stack.sql-layer --scope effect-stack --all-repos
+== decisions ==
+active   ADR-0002   @effect/sql
+
+== homelab ==
+unknown   no such key `stack.sql-layer`
+…
+```
+
+A linked worktree is detected and left out when its parent is also there, so
+one corpus never answers twice; it stays addressable by name.
+
 Codes `1`, `2` and `3` mean the tool failed, was misused, or could not read the
 corpus. They never overlap a verdict, so "I could not look" is never mistaken
 for "I looked and found nothing".
@@ -128,11 +150,53 @@ different edges:
 | `aval heads [--write\|--check]` | the projection |
 | `aval show ADR-0015` | derived status, including partial supersession |
 | `aval history <key>` | the chain, labelled as history |
+| `aval rules [--level L] [--all]` | the rules the decisions have adopted, one line each |
+| `aval rule <id>` | one rule, with its translation and why |
 | `aval hook install [--check]` | put the heads in front of an agent at session start |
 | `aval pack [--write\|--check]` | publish this corpus's declarations for others to read |
 | `aval add <source>… [--dry-run]` | vendor another repository's declarations |
 | `aval add --check` | are the vendored packs still what their revisions name |
 
+## Rules: what a decision does not settle
+
+A decision settles *what* is used. How the code that uses it is written gets
+answered the way the first question used to be — a paragraph restated in six
+`CLAUDE.md` files, one already wrong, and whatever a model remembers of a book.
+So a **rule** is written once, in a markdown file whose headings are the
+declarations, and it is **adopted by a record**:
+
+```markdown
+---
+adopts: ADR-0011
+source: Clean Code (Robert C. Martin, 2008)
+---
+
+## names.reveal-intent [constraint]
+
+Names reveal intention: an identifier says what it holds, in the vocabulary
+of the domain, and a reader never decodes an abbreviation.
+
+The body is the translation — what this means here, and what it does not cover.
+```
+
+A rule has no authority of its own: it is active exactly while the record that
+adopts it still holds, so superseding that record retires its rules with it.
+There are no per-rule supersession edges, because the graph already tracks the
+record — a rule whose meaning changes gets a new id.
+
+```console
+$ aval rules
+constraint names.reveal-intent   Names reveal intention: an identifier says what it holds …
+heuristic  functions.few-arguments   A function takes no more inputs than it uses …
+```
+
+A `constraint` is followed and a review blocks on it; the session hook prints
+every active one. A `heuristic` is followed unless a reviewer argues why not,
+in that place, and is fetched on demand. Precedence, which the hook also
+prints: the decision at the scope asked, then the default-scope decision, then
+these rules, then the book a rule cites — as explanation only. Remembered
+advice from that book does not outrank a rule here.
+
 ## Sharing one decision across repositories
 
 A decision made once should be readable everywhere it applies. `aval pack`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aval-adr",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Ask what the current architecture decision is, and get a typed answer",
   "keywords": [
     "adr",
@@ -32,11 +32,11 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@aval-adr/darwin-arm64": "1.0.0",
-    "@aval-adr/darwin-x64": "1.0.0",
-    "@aval-adr/linux-arm64-gnu": "1.0.0",
-    "@aval-adr/linux-x64-gnu": "1.0.0",
-    "@aval-adr/linux-x64-musl": "1.0.0",
-    "@aval-adr/win32-x64": "1.0.0"
+    "@aval-adr/darwin-arm64": "1.2.0",
+    "@aval-adr/darwin-x64": "1.2.0",
+    "@aval-adr/linux-arm64-gnu": "1.2.0",
+    "@aval-adr/linux-x64-gnu": "1.2.0",
+    "@aval-adr/linux-x64-musl": "1.2.0",
+    "@aval-adr/win32-x64": "1.2.0"
   }
 }