@saasontools/strauss-kb 0.1.14 → 0.1.16

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).
 
@@ -398,8 +408,8 @@ Worked flows:
 
 **Placement is cache economics.** `load`'s output belongs in the stable
 prefix — system prompt or first turn; `query` and `pack` results belong at
-the tail. `digest` is the base's content stamp: a change-notification hook
-and `kb_stamp` (SAA-719) compare it to detect change, not the model. A
+the tail. `digest` is the base's content stamp: `kb_stamp` and the opt-in
+reload hook compare it to detect change, not the model. A
 prompt cache matches a byte-for-byte prefix, so one volatile result ahead of
 a stable load prices the base at full rate thereafter. Mechanism and digest
 caveats: <https://saasontools.github.io/strauss-agent-tools/mcp-reference>.
@@ -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).
@@ -441,6 +451,11 @@ carry no numbers:
 }
 ```
 
+A pinned base can also change mid-session — a `git pull`, a sub-agent's write.
+`strauss-kb stamp` reports each pinned base's content digest. Comparing it for
+you is opt-in, see the
+[plugin README](../../plugins/strauss-kb/README.md#opt-in-workspace-hooks).
+
 `sync-instructions <file>` keeps that block between
 `<!-- strauss-kb:begin/end -->` sentinels in AGENTS.md or CLAUDE.md; it is
 idempotent, and covers runtimes without a reliable post-compaction hook.
@@ -448,15 +463,16 @@ idempotent, and covers runtimes without a reliable post-compaction hook.
 What each runtime gets (configs in the
 [plugin's adapters](../../plugins/strauss-kb/adapters/)):
 
-| Layer                     | Claude Code        | Codex CLI                                   | Antigravity CLI            |
-| ------------------------- | ------------------ | ------------------------------------------- | -------------------------- |
-| MCP tool descriptions     | ✓                  | ✓                                           | ✓                          |
-| Session-start injection   | SessionStart hook  | SessionStart hook                           | PreInvocation, per turn    |
-| Post-compact re-injection | ✓ `compact` source | ✓ client-side; instruction-only when hosted | moot — injected every turn |
-| File-read blocking        | opt-in PreToolUse  | ✗ (shell is the side door)                  | opt-in PreToolUse, JSON    |
-| Manual-edit validation    | opt-in PostToolUse | ✗                                           | ✗                          |
-| Generated-file edit guard | opt-in PreToolUse  | ✗                                           | ✗                          |
-| Instruction file          | CLAUDE.md          | AGENTS.md                                   | AGENTS.md + rules/         |
+| Layer                     | Claude Code                      | Codex CLI                                   | Antigravity CLI            |
+| ------------------------- | -------------------------------- | ------------------------------------------- | -------------------------- |
+| MCP tool descriptions     | ✓                                | ✓                                           | ✓                          |
+| Session-start injection   | SessionStart hook                | SessionStart hook                           | PreInvocation, per turn    |
+| Post-compact re-injection | ✓ `compact` source               | ✓ client-side; instruction-only when hosted | moot — injected every turn |
+| Reload after a pull       | opt-in PostToolUse, SubagentStop | opt-in PostToolUse on `shell`               | moot — injected every turn |
+| File-read blocking        | opt-in PreToolUse                | ✗ (shell is the side door)                  | opt-in PreToolUse, JSON    |
+| Manual-edit validation    | opt-in PostToolUse               | ✗                                           | ✗                          |
+| Generated-file edit guard | opt-in PreToolUse                | ✗                                           | ✗                          |
+| Instruction file          | CLAUDE.md                        | AGENTS.md                                   | AGENTS.md + rules/         |
 
 Never read record files directly — read through the tools; a raw read bypasses
 standing, and a superseded record reads exactly like a current one. Enforce it