@saasontools/strauss-kb 0.1.11 → 0.1.13

package/ARCHITECTURE.md

@@ -64,6 +64,21 @@ rewritten to remove; enforcing a vocabulary would make them a closed enum, which
 or do not, where a tag can be wrong forever. If narrowing ever matters, measure
 tag narrowing against vector recall on a real base rather than adding both.
 
+## Typed links
+
+Supersession is not a rel. It is a lifecycle, and
+`strauss_supersedes`/`strauss_superseded_by` already carry it in both
+directions; a rel would be a second spelling free to disagree with them.
+
+The rel vocabulary is closed, but the read schema tolerates an unknown one.
+Frontmatter strict enough to reject it would make the file fail to parse, and a
+file that fails to parse is skipped by `list()` rather than reported — the
+bundle would drop the record instead of naming it. Tolerant read, strict write:
+`kb_write` refuses an unknown rel, `kb_validate` reports one as an error.
+
+`kb_impact` reports a superseded or rejected record and stops there. A withdrawn
+record's declared dependencies are not obligations anyone still owes.
+
 ## Rejected: a format that needs a parser
 
 This was broken twice. A hand-rolled frontmatter reader could not express nested

package/README.md

@@ -155,6 +155,7 @@ OKF version defining the same name cannot collide:
 | `strauss_status`                                               | `draft`, `proposed`, `accepted`, `open`, `resolved`, `rejected`, `superseded`. Parses with a default of `draft`.                                                                              |
 | `strauss_supersedes` / `strauss_superseded_by`                 | Both directions of a supersession, written together.                                                                                                                                          |
 | `strauss_anchors`                                              | `{ file, symbol?, hash?, lines?, resolved_at? }` — where the record attaches in the code, and optionally what that code looked like when it did. See [Anchors and drift](#anchors-and-drift). |
+| `strauss_links`                                                | `{ target, rel }` — a typed causal edge, source → target. See [Links](#links).                                                                                                                |
 | `strauss_assumption`                                           | The claim has no source, said as a field rather than as a fake entry in `sources`.                                                                                                            |
 | `strauss_answered`                                             | Who resolved an open question, and when.                                                                                                                                                      |
 | `strauss_verify`                                               | Checks that would confirm the record still holds.                                                                                                                                             |
@@ -162,7 +163,8 @@ OKF version defining the same name cannot collide:
 
 Edges are markdown links in the body, as OKF specifies — untyped, with the kind
 conveyed by the surrounding prose. Broken links are legal: records are routinely
-written before the ones they point at exist.
+written before the ones they point at exist. `strauss_links` adds a typed layer
+over that, described below.
 
 Twelve record types differ only in what their body answers and where they start
 in the lifecycle — `fact`, `requirement`, `constraint`, `decision`,
@@ -197,6 +199,35 @@ A lock file. It closes the window and adds a stale-hold failure mode that is
 worse than the residue.
 ```
 
+## Links
+
+`strauss_links` is a typed causal edge, `[{ target, rel }]` on the source
+record, read source → target: `A depends_on B` means A needs B. The vocabulary
+is closed: eight rels. The **dependant** — the end that breaks when the other
+changes — is per-rel.
+
+| `rel`         | `A <rel> B` means            | Dependant |
+| ------------- | ---------------------------- | --------- |
+| `depends_on`  | A needs B to hold            | A         |
+| `verified_by` | B confirms A                 | A         |
+| `satisfies`   | A discharges B's requirement | A         |
+| `constrains`  | A bounds what B may do       | B         |
+| `informs`     | A shaped B, not binding      | B         |
+| `blocks`      | B waits on A                 | B         |
+| `invalidates` | A makes B no longer hold     | B         |
+| `related_to`  | no dependence                | —         |
+
+`kb_impact` (`strauss-kb impact <id>`): the transitive set of dependants, each
+rel followed in its own direction, never `related_to`.
+
+`kb_backlinks` (`strauss-kb backlinks <id>`): every inbound edge, one hop, any rel.
+
+`kb_validate`: unknown rel or malformed target is an `error`, absent target a
+`warning`. Only errors fail the exit code.
+
+The [specification](https://saasontools.github.io/strauss-agent-tools/specification)
+has the rest.
+
 ## Writes
 
 Records are staged to a sibling file and published atomically, so a concurrent
@@ -314,6 +345,9 @@ strauss-kb [--bundle PATH] <command> [args]
                                            The bounded neighbourhood around one record, every cut named.
   query <text...> [--repo-root PATH]       Search; every match arrives flagged with its standing.
   trace <concept-id> [edges...]            How a position was arrived at, as a timeline.
+  impact <concept-id> [--depth N] [--rels a,b]
+                                           What breaks if this changes: its dependants, transitively.
+  backlinks <concept-id>                   Who points at this record — one hop, every rel.
   list [type]                              Every record, optionally narrowed to one type.
   index                                    The index, rebuilt if it disagrees with the records.
   log                                      What touched what, and when.
@@ -342,7 +376,9 @@ worked; `--` ends flag parsing, for the verbs that end in free prose. Errors
 go to stderr and exit 1. `validate`, `anchor-resolve`, and `doctor --strict`
 are the commands whose exit code is not just "did it run": a check that
 reports a problem succeeded as a command and failed as a check, so each exits
-1 with its findings on stdout.
+1 with its findings on stdout. Only `validate` findings with `severity: "error"`
+do that — a base mid-write is full of links to records not written yet, so
+warnings alone exit 0.
 
 A flag accepts either spelling — `--budget 4000` or `--budget=4000` — and a
 flag given no value is an error rather than a silent fallback to the default,
@@ -360,7 +396,7 @@ strauss-kb --bundle .strauss/kb write fact <<'JSON'
 JSON
 
 strauss-kb query cache key region
-strauss-kb validate || echo "problems above"
+strauss-kb validate || echo "errors above"   # warnings alone still exit 0
 ```
 
 ## MCP server
@@ -368,7 +404,8 @@ strauss-kb validate || echo "problems above"
 `strauss-kb-mcp` speaks stdio and takes no API key and no required environment.
 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_pack`, `kb_query`, `kb_trace`, `kb_list`,
+`kb_load`, `kb_catalog`, `kb_pack`, `kb_query`, `kb_trace`, `kb_impact`,
+`kb_backlinks`, `kb_list`,
 `kb_index`, `kb_log`, `kb_validate`, `kb_doctor`, `kb_schema`, `kb_types`,
 `kb_pin`, `kb_unpin`, `kb_pins`, `kb_context`. Most tools take a `bundlePath`;
 `kb_schema` and `kb_types` describe the format rather than any one base, and
@@ -534,6 +571,14 @@ fact; a missing replacement is `broken-chain` with no head — the case that nee
 the most care, because returning the stale record unmarked looks exactly like
 success.
 
+**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
+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>.
+
 ## Health
 
 `doctor` sweeps a whole base and reports what has decayed. It is read-only —

package/dist/{chunk-CWWXMD35.js → chunk-WZODZNR6.js}

@@ -2,7 +2,7 @@ import {
   KB_COMMANDS,
   KbStore,
   VERSION
-} from "./chunk-OVRQCQ6P.js";
+} from "./chunk-XALWG3EZ.js";
 
 // src/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -46,4 +46,4 @@ export {
   createKbMcpServer,
   runKbMcpServer
 };
-//# sourceMappingURL=chunk-CWWXMD35.js.map
+//# sourceMappingURL=chunk-WZODZNR6.js.map