@saasontools/strauss-kb 0.1.16 → 0.1.18

package/ARCHITECTURE.md

@@ -84,11 +84,54 @@ from Zod, and `strauss-kb schema` is the contract.
 A fresh stamp is a baseline nobody has checked, so only a run where every
 checkable anchor already matched appends `verified[]`.
 
-The v1 resolver is regex-based, biased so a wrong answer loses to no answer: a
-span short of the code it claims hashes as stable while that code moves. It
-ranks by shape, scopes a dotted symbol to its parent, captures by brace depth or
-Python indentation, and returns `null` otherwise. A pure `AnchorResolver`
-interface admits a tree-sitter replacement.
+Symbols resolve through tree-sitter first: a WASM parser per language, each
+grammar's own upstream `queries/tags.scm` over definition sites, and the
+definition node's range as the span. A dotted symbol matches the definition whose enclosing chain
+matches; a bare name matching two is `symbol-ambiguous`. Only declarations are
+captured: a symbol appearing solely in a call is no match.
+
+The chain is tree-sitter, then regex, then a whole-file hash. A resolver that
+parsed the file answers for it unless it defines no such symbol at all — tags
+queries capture functions and types, not constants, aliases or fields — so
+`symbol-not-found` continues down the chain and the anchor records whichever
+resolver answered. `symbol-ambiguous` and `resolver-unavailable` stop it:
+picking one of two definitions by text search, or swapping a precise span for a
+heuristic one when a grammar will not load, is how a wrong span comes to hash
+as `match`. A grammar that will not load is a finding, never a throw.
+
+Grammars download on first use, sha256-pinned by `grammars/manifest.json` and
+cached under `~/.strauss/grammars`; the reasoning is in the
+[specification](https://saasontools.github.io/strauss-agent-tools/specification#symbol-resolution).
+
+Each anchor records the resolver that stamped it. A hash only the previous
+resolver reproduces is `drifted`, reason `resolver-changed`. Trees are cached
+per content hash, grammars load once per process.
+
+A tree-sitter stamp hashes the span's token stream rather than its text
+(`hash_kind: "ast"`), so a reformat is not drift; a raw hash keeps comparing
+raw until it is rebaselined.
+
+### Drift classification
+
+Once the bytes differ, the question is what a machine can settle and what it
+must hand on.
+
+| Class      | Test                                        | Who settles it |
+| ---------- | ------------------------------------------- | -------------- |
+| `moved`    | the stored hash resolves at another address | `kb_reassess`  |
+| `cosmetic` | both spans are one token stream             | classification |
+| `gone`     | the file or symbol no longer exists         | a reader       |
+| `changed`  | everything else                             | a reader       |
+
+`moved` and `cosmetic` cost a repository search and a git read, so `load` and
+`query` report only the two a hash comparison already answers and
+`classifyDrift` refines the rest on demand.
+
+Classification stops there because the next question — does the record's claim
+still hold — is a reading, and every mechanical proxy for it (similarity
+scores, "small" diffs) answers a different question confidently. So the packet
+carries the evidence a reader needs and names a type-based default, and no
+drift path writes `verified[]` or moves standing.
 
 Repository identity is normalised and compared, not parsed: an invented format
 would reject correct values from unseen hosts.

package/README.md

@@ -206,17 +206,19 @@ Why a lock was rejected: [ARCHITECTURE.md](./ARCHITECTURE.md).
 
 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:
+end of it. Six optional fields extend it:
 
 | Field         | Meaning                                                                               |
 | ------------- | ------------------------------------------------------------------------------------- |
 | `hash`        | `sha256:<hex>` over the anchored text, algorithm-prefixed.                            |
+| `hash_kind`   | What `hash` covered: `raw` text, or the `ast` token stream. Absent means `raw`.       |
 | `lines`       | Line count the hash covered.                                                          |
 | `resolved_at` | When the anchor last resolved.                                                        |
+| `resolver`    | Which resolver produced the hash: `tree-sitter` or `regex`.                           |
 | `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
+`hash`, `hash_kind`, `lines`, `resolved_at`, and `resolver` are **measured** — a resolution pass stamps
 them; `repo` and `ref` are **author-owned identity** and a resolution pass
 never writes them.
 
@@ -246,8 +248,40 @@ carries a hash; unstamped anchors and unreachable remotes never fail.
 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`.
+Symbols resolve tree-sitter first — the 20 language packs that have both a
+grammar and a definitions query, pinned together by `pnpm grammars pin` from
+`grammars/packs.json` and proved at pin time — then the regex heuristic for
+other extensions and for symbols the tags query does not define (constants,
+type aliases, class fields), then a
+whole-file hash when the anchor names no symbol; an ambiguous match or an
+unloadable grammar returns `unresolved` rather than falling through to a guess. Neither half of a pack is published with the
+package: grammar and query both download on first use, sha256-pinned against
+`grammars/manifest.json`, and are cached under `~/.strauss/grammars`. A hash the old resolver still reproduces and
+the new one does not is `drifted` with reason `resolver-changed` — accept it
+with `--rebaseline`.
+
+A tree-sitter stamp hashes the span's normalised token stream
+(`hash_kind: "ast"`), so reformatting the anchored code is not drift. An anchor
+stamped before that keeps comparing raw text until `--rebaseline` restamps it.
+
+### Drift classes
+
+Once the bytes differ, drift is classified — two classes a machine can close,
+two it hands on:
+
+- **moved** — the stored hash turned up elsewhere: same code, new address.
+  `kb_reassess` moves the anchor and asks nothing of a reader.
+- **cosmetic** — the old and new spans are one token stream; only formatting
+  changed. Needs a grammar, so the regex resolver never reports it.
+- **gone** — the file or the symbol no longer exists. The strongest signal:
+  the described code cannot be re-read.
+- **changed** — everything else, and the only class a reader has to judge.
+
+`kb_reassess <concept-id>` (`kb_doctor --drifted` base-wide) turns what is left
+into a packet: the record's claim, each anchor's class, the old-vs-new span diff
+(`--with-diff`, recovered from `ref` or from history), and the record's `impact`
+set. Neither verb verifies, supersedes, or changes standing — see the skill's
+protocol.
 
 Drift also surfaces on read: `kb_load` and `kb_query` attach a
 `{ kind: "drifted" }` warning — or `{ kind: "unchecked" }` for a foreign anchor
@@ -275,6 +309,8 @@ strauss-kb [--bundle PATH] <command> [args]
   verify <concept-id> --note <text>        Append a verified[] event — who checked, when, and what the check found.
   anchor-resolve <concept-id> [--repo-root <path>] [--rebaseline] [--restamp]
                                            Resolve anchors against the working tree: stamp, or report drift.
+  reassess <concept-id> [--repo-root <path>] [--with-diff]
+                                           One drifted record as something to judge: claim, classes, diff, impact.
   load [type] [--budget N | --all] [--repo-root PATH]
                                            Hand over the whole base, each record with its standing.
   catalog [type]                           Every record in one line — id, type, title, standing, stale flag.
@@ -344,9 +380,11 @@ strauss-kb validate || echo "errors above"   # warnings alone still exit 0
 ```
 
 Every CLI verb is a tool: `kb_write`, `kb_write_decision`, `kb_no_decision`,
-`kb_status`, `kb_supersede`, `kb_answer`, `kb_verify`, `kb_anchor_resolve`, `kb_load`, `kb_catalog`,
+`kb_status`, `kb_supersede`, `kb_answer`, `kb_verify`, `kb_anchor_resolve`, `kb_reassess`,
+`kb_load`, `kb_catalog`,
 `kb_pack`,
-`kb_query`, `kb_trace`, `kb_impact`, `kb_backlinks`, `kb_list`, `kb_index`, `kb_log`, `kb_validate`,
+`kb_query`, `kb_trace`, `kb_impact`, `kb_backlinks`, `kb_list`, `kb_index`, `kb_log`, `kb_stamp`,
+`kb_validate`,
 `kb_doctor`, `kb_schema`, `kb_types`, `kb_pin`, `kb_unpin`, `kb_pins`,
 `kb_context`. Most take a `bundlePath`. The one CLI verb with no tool is
 `sync-instructions`; the agent capability is `kb_context`.