@saasontools/strauss-kb 0.1.14 → 0.1.15

package/ARCHITECTURE.md

@@ -93,8 +93,26 @@ interface admits a tree-sitter replacement.
 Repository identity is normalised and compared, not parsed: an invented format
 would reject correct values from unseen hosts.
 
-Not one anchored file found under a default root is a wrong root, so its
-findings are dropped.
+## Remote over local checkout
+
+An anchor naming another repository resolves against that repository's remote,
+through a bare cache under `~/.strauss/repo-cache`. A checkout is one person's
+view — stale, dirty, or absent — so a hash from it is evidence about that
+machine, not the code.
+
+The rejected design was multi-root: `--repo-root name=path` per repository,
+root discovery, a `.strauss/kb-roots.json` map, a `repo-not-mapped` finding. It
+makes the answer depend on the reader's disk — one machine verifies, another
+reports drift — and needs configuring before a base can check itself. Git
+already knows how to reach a remote.
+
+A pinned `ref` is checked at that commit and the default branch compared on top
+of it: was the record ever true, and does it still hold.
+
+`repo` and `ref` come out of a `.md` file the reader did not write, so both are
+validated against a shape before any `git` runs: an argv array stops the shell
+but not git's own option parsing, where `--upload-pack=<cmd>` as a rev and
+`ext::sh -c <cmd>` as a URL are each an execution primitive.
 
 ## Cross-worktree log safety
 

package/README.md

@@ -208,13 +208,13 @@ An anchor names where a record attaches in the code: a `file`, optionally a
 `symbol` — symbolic, because a line number written mid-change is wrong by the
 end of it. Five optional fields extend it:
 
-| Field         | Meaning                                                                                                          |
-| ------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `hash`        | `sha256:<hex>` over the anchored text, algorithm-prefixed.                                                       |
-| `lines`       | Line count the hash covered.                                                                                     |
-| `resolved_at` | When the anchor last resolved.                                                                                   |
-| `repo`        | Which repository — remote URL or short name. Absent means this base's own repository.                            |
-| `ref`         | Git rev the evidence was taken at. Recorded but unused until [SAA-709](https://linear.app/saason/issue/SAA-709). |
+| Field         | Meaning                                                                               |
+| ------------- | ------------------------------------------------------------------------------------- |
+| `hash`        | `sha256:<hex>` over the anchored text, algorithm-prefixed.                            |
+| `lines`       | Line count the hash covered.                                                          |
+| `resolved_at` | When the anchor last resolved.                                                        |
+| `repo`        | Which repository — remote URL or short name. Absent means this base's own repository. |
+| `ref`         | Git rev the evidence was taken at.                                                    |
 
 `hash`, `lines`, and `resolved_at` are **measured** — a resolution pass stamps
 them; `repo` and `ref` are **author-owned identity** and a resolution pass
@@ -229,25 +229,35 @@ counterpart: it checks the anchored code against the working tree
 - **drifted** — hash changed. Baseline kept unless `--rebaseline`.
 - **unresolved** — not comparable, with a reason. A finding, not an error.
 
-An anchor naming another `repo` is skipped: never read, stamped, or counted.
+An anchor naming another `repo` is read from that repository's **remote**,
+through a bare cache under `~/.strauss/repo-cache` — a local checkout is one
+person's possibly stale view of the same file. With a `ref` it has three
+states: `matches-ref`, `drifted-from-ref`, and `drifted-on-default`.
+`--offline` reads the cache and never fetches. Only `https`, `ssh`, and `git`
+remotes are fetched, and a `repo` or `ref` git could read as an option is a
+finding, not a command.
 
 An anchor must not read outside the repository it describes, checked lexically
 and again on the real path after symlinks.
 
 Exit code is non-zero on **drifted**, or on **unresolved** for an anchor that
-carries a hash; unstamped and foreign anchors never fail.
+carries a hash; unstamped anchors and unreachable remotes never fail.
 
-A fully clean run — every checkable anchor `match`, none stamped this run —
+A fully clean run — every anchor checked and `match`, none stamped this run —
 appends a `verified[]` event.
 
 Symbol resolution is a v1 heuristic; ties and unclosed blocks return
 `unresolved`.
 
 Drift also surfaces on read: `kb_load` and `kb_query` attach a
-`{ kind: "drifted" }` warning, and `kb_doctor` lists every drifted anchor
-base-wide — all three take `--repo-root`. With no `--repo-root` given, a run
-that finds not one anchored file drops the finding as a wrong root; an explicit
-`--repo-root` is taken at its word.
+`{ kind: "drifted" }` warning — or `{ kind: "unchecked" }` for a foreign anchor
+they could not read from the cache, because they never fetch — and `kb_doctor`
+lists both base-wide, per repository. All three take `--repo-root`. With no
+`--repo-root` given, a run that finds not one anchored file drops the finding as
+a wrong root; an explicit `--repo-root` is taken at its word.
+
+Remote resolution in full:
+[specification](https://saasontools.github.io/strauss-agent-tools/specification#anchors-in-another-repository).
 
 Details: [specification](https://saasontools.github.io/strauss-agent-tools/specification).
 
@@ -407,9 +417,9 @@ caveats: <https://saasontools.github.io/strauss-agent-tools/mcp-reference>.
 ## Health
 
 `doctor` sweeps a base read-only for `expired`, `expiring`, `unverified`,
-`aging`, `orphaned`, `broken-supersession`, `superseded-but-cited`, and
-`drifted`. All eight groups are reported even when empty; `--strict` gates on
-expiry alone, not on drift. Pass `--repo-root PATH` when the base does not sit
+`aging`, `orphaned`, `broken-supersession`, `superseded-but-cited`, `drifted`,
+and `unchecked`. All nine groups are reported even when empty; `--strict` gates
+on expiry alone, not on drift. Pass `--repo-root PATH` when the base does not sit
 inside the tree it describes.
 Windows and judgments:
 [cli-reference](https://saasontools.github.io/strauss-agent-tools/cli-reference).