@saasontools/strauss-kb 0.1.1 → 0.1.3

package/ARCHITECTURE.md

@@ -0,0 +1,85 @@
+# Architecture
+
+The README says what the format is and how to use it. This says why it is
+shaped that way, and which alternatives were tried and dropped — the decisions
+a later reader would otherwise reopen.
+
+## One record per file
+
+The filename is the identity, so two writers never merge; they only choose
+distinct names. Publication uses `link`, which fails when the name is taken, and
+a collision surfaces as a 409 the caller has to answer rather than a silent
+last-write-wins.
+
+Read-modify-write (`setStatus`, `answer`) checks a content digest immediately
+before publishing. That narrows the lost-update window to two adjacent syscalls
+rather than closing it. A lock would close it and add a stale-hold failure worse
+than the residue: a crashed holder blocks every later writer, where a lost
+update costs one retry.
+
+## Read for a question, not for a session
+
+A base loaded at the start of a long conversation is summarised away by the end
+of it, and nothing keeps it alive. So no consumer loads it that way:
+
+| Consumer                        | How it reads                                                                 |
+| ------------------------------- | ---------------------------------------------------------------------------- |
+| Diff annotation                 | `matchToDiff` — deterministic, no context involved                           |
+| "Has this been decided?"        | a fresh short-lived reader, given the base and the question, discarded after |
+| An implementor writing a record | a point query at the moment of writing, not a load an hour earlier           |
+
+Each has clean context by construction. Where a base genuinely must stay
+resident it will drift, and there is no defence — the mitigation is that
+reloading costs about three thousand tokens, so read it again at the point of
+use rather than trying to keep it.
+
+## What happens when a base outgrows a context
+
+Loading stops working somewhere above a few hundred records. What replaces it is
+not a different answer to the same question — it is the same reader, given
+candidates instead of everything:
+
+```
+vector recall  →  top ~20 candidates, with their scores
+                  ↓
+reader judges  →  picks what answers, or says nothing does
+```
+
+The reader stays the judge in both regimes, which is what preserves the two
+structural wins the README reports: it can say no record answers the question,
+and it picks the record that answers rather than the one nearest the topic.
+Neither survives if a ranker's top hit is taken as the answer.
+
+**A score threshold is not the growth path.** The wrong `audit trail` hit scored
+0.318 against the correct `race condition` hit at 0.295; any cut that drops the
+first drops the second. A threshold excludes the absurd — an unrelated query
+scored 0.091 — and nothing else.
+
+**Tags are not the growth path either.** The field exists, is written, and is
+read by nothing but an index line, deliberately. Free-text tags drift the way
+`auth` / `authentication` / `authn` drift, which is the failure this format was
+rewritten to remove; enforcing a vocabulary would make them a closed enum, which
+`type` already is. The labels that matter here are already verifiable —
+`strauss_anchors` names a file and a symbol, which either match the repository
+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.
+
+## Rejected: a format that needs a parser
+
+This was broken twice. A hand-rolled frontmatter reader could not express nested
+maps, so it misread every OKF `generated`, `sources[]`, and `verified[]`. Its
+replacement's first log format was `·`-delimited, with a splitter to read it
+back. Both are gone: the log is JSONL and the schema is emitted from Zod, so
+`strauss-kb schema` is the contract rather than a description of one.
+
+## Rejected for now: a base registry
+
+Cross-base questions are unaskable by construction — supersession, traces, and
+search stop at the directory boundary. That is the price of a base that can be
+copied, deleted, or handed over whole, and it is what keeps the search index
+disposable.
+
+If cross-base ever becomes the common case, the cheap escape is a registry: a
+list of paths a caller may name explicitly, queried one at a time and merged
+only for display. It is deliberately unbuilt. Adding it early would drag back
+the cross-scope machinery this model exists to avoid.

package/README.md

@@ -146,12 +146,21 @@ the name is taken — two writers choosing one concept id is a 409 the caller mu
 answer, by picking a more specific slug or by saying it meant to replace.
 `rename` is used only when the caller passes `overwrite`.
 
+Read-modify-write (`setStatus`, `answer`) checks a content digest immediately
+before publishing, which narrows the lost-update window rather than closing it.
+[ARCHITECTURE.md](./ARCHITECTURE.md) says why a lock was rejected.
+
 `supersede` writes both directions, so a backlink cannot drift in normal use and
 `validate` drops to catching hand-edits.
 
 Records are never deleted. Superseding keeps the earlier reasoning inspectable,
 which is what a later `trace` reads.
 
+`no-decision` records the explicit claim that a piece of work had nothing to
+decide (an idempotent `decision.none` record). It exists for workflow gates:
+"did you write a decision?" rewards writing a junk one, "did you answer?"
+does not — so silence has to be expressible.
+
 ## CLI
 
 ```
@@ -172,6 +181,11 @@ strauss-kb [--bundle PATH] <command> [args]
   validate                                 Cross-record checks. Exits 1 when it reports a problem.
   schema                                   JSON Schema for the format.
   types                                    The twelve types, their sections and initial status.
+  pin [bundle-path] [flags]                Pin a base. --mode, --profiles, --frozen; --local/--user pick the layer.
+  unpin [bundle-path]                      Remove a base from every manifest layer that holds it.
+  pins                                     Every pinned base, with whether it resolves to records.
+  context [--profile NAME] [--budget N]    The pinned-base index block, for injection at context birth.
+  sync-instructions <file>                 Plant the context block between sentinels in an instruction file.
 
   --bundle PATH  defaults to ./.strauss/kb
   STRAUSS_KB_ACTOR names the writer in the log
@@ -202,9 +216,12 @@ 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_load`, `kb_query`, `kb_trace`,
-`kb_list`, `kb_index`, `kb_log`, `kb_validate`, `kb_schema`, `kb_types`. Every
-tool but `kb_schema` and `kb_types` takes a `bundlePath`; those two describe the
-format rather than any one base.
+`kb_list`, `kb_index`, `kb_log`, `kb_validate`, `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
+`kb_pins` and `kb_context` read the workspace pin manifests instead. The one
+CLI verb with no tool is `sync-instructions` — file plumbing for hooks, not an
+agent capability; the capability is `kb_context`.
 
 ```json
 {
@@ -265,12 +282,20 @@ base answered eight; embedding search over the same records answered four. Two
 of those differences are structural rather than matters of degree: a reader can
 say no record answers the question, where vector search returns its nearest
 neighbour whatever the distance; and a reader picks the record that answers the
-question rather than the one nearest the topic.
+question rather than the one nearest the topic. The mechanism is simple:
+retrieval makes similarity the gatekeeper, and a match the ranker misses never
+reaches the model. A full read lets the model do the matching itself —
+synonymy, implication across records, aggregation — which no ranker does.
+
+Read for a question, not for a session: a base loaded at the start of a long
+conversation is summarised away by the end of it, and reloading costs about
+three thousand tokens. Read it again at the point of use.
 
 `load` refuses rather than truncating when a base exceeds its budget (25,000
 tokens by default). A truncated base is indistinguishable from a complete one,
 so a caller would answer "that was never decided" from a slice it did not know
-was a slice. Superseded records come back as name, replacement and date only —
+was a slice. `context` refuses the same way at its own, tighter budget (4,000
+by default). Superseded records come back as name, replacement and date only —
 their bodies no longer hold, and a body read later in a long session outlives
 the qualifier that said so. `trace` still reaches them by id.
 
@@ -294,6 +319,80 @@ 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.
 
+## Living in an agent session
+
+Long sessions lose a knowledge base twice over: attention decays, and
+compaction summarises away both the records loaded early and the instruction
+that said to consult them. The fix is two-tier: a small index is re-injected
+at every context birth, and record bodies are fetched by tool when a question
+actually needs them.
+
+```bash
+strauss-kb pin docs/kb                   # mark a base every session should see
+strauss-kb context                       # emit the pinned index block
+strauss-kb sync-instructions AGENTS.md   # or keep it in an instruction file
+```
+
+Pins live in `.strauss/kb-pins.json`, committed with the repo. Two more
+layers exist: `.strauss/kb-pins.local.json` (personal, gitignore it) and
+`~/.strauss/kb-pins.json` (every workspace). Nearest layer wins per base,
+`--local`/`--user` write the other layers, and `unpin` removes from all
+three. A malformed layer is skipped on read and refused on write.
+
+Per pin:
+
+- `--mode full` — inject the records themselves, not just the index. For
+  small or critical bases (ADRs). Falls back to a labelled index when it
+  cannot fit the block budget.
+- `--mode index` — never inject bodies.
+- `--profiles a,b` — only inject in the named profiles.
+- `--frozen` — the base is concluded; write commands refuse until `--unfreeze`.
+
+Budgets are named profiles — `session-start`, `compact`, `turn` — with
+per-repo overrides in the manifest, so hook commands never carry numbers:
+
+```json
+{
+  "pins": [{ "path": "docs/adr", "mode": "full" }],
+  "context": { "compact": { "budgetTokens": 1500 } }
+}
+```
+
+Flags beat the manifest, the manifest beats the built-ins, and invalid values
+fall back to defaults instead of silencing the index. Past its budget,
+`context` refuses like `load` does — never truncates — and its refusal says
+what to load directly and how to shrink the block.
+
+`sync-instructions <file>` keeps the same block between
+`<!-- strauss-kb:begin/end -->` sentinels in AGENTS.md or CLAUDE.md, touching
+nothing outside them. Re-run it when pins change; it is idempotent. This is
+the mechanism for runtimes without a reliable post-compaction hook, since
+instruction files are re-read where conversation history is not.
+
+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    |
+| Instruction file          | CLAUDE.md          | AGENTS.md                                   | AGENTS.md + rules/         |
+
+One more thing agents add: file tools. A raw read of a record file bypasses
+standing entirely — a superseded record reads exactly like a current one — so
+bases are read through the tools, and a workspace can enforce that with deny
+rules or the plugin's opt-in PreToolUse script:
+
+```json
+{
+  "permissions": {
+    "deny": ["Read(.strauss/kb/**)", "Read(**/.strauss/kb/**)"]
+  }
+}
+```
+
 ## Optional search tier
 
 `@tobilu/qmd` is an **optional peer dependency** providing BM25 (`searchLex`,
@@ -333,7 +432,8 @@ hold is the exception — no invariant, deterministic path.
 the directory boundary. "Was this settled somewhere else?" is answered by a
 person choosing which base to open. That is the price of a base that can be
 copied, deleted, or handed over whole, and it is what keeps the search index
-disposable.
+disposable. [ARCHITECTURE.md](./ARCHITECTURE.md) covers the registry that would
+lift it, and why it is unbuilt.
 
 ## License
 

package/dist/{chunk-WFHYWZX5.js → chunk-FSI4Q2FD.js}

@@ -1,7 +1,7 @@
 import {
   KB_COMMANDS,
   KbStore
-} from "./chunk-ZSYSHJVZ.js";
+} from "./chunk-HYNAEAPM.js";
 
 // src/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -18,6 +18,7 @@ function createKbMcpServer() {
     now: () => (/* @__PURE__ */ new Date()).toISOString()
   };
   for (const command of KB_COMMANDS) {
+    if (!command.tool) continue;
     server.registerTool(
       command.tool,
       { description: command.description, inputSchema: command.input.shape },
@@ -44,4 +45,4 @@ export {
   createKbMcpServer,
   runKbMcpServer
 };
-//# sourceMappingURL=chunk-WFHYWZX5.js.map
+//# sourceMappingURL=chunk-FSI4Q2FD.js.map

package/dist/chunk-FSI4Q2FD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/mcp.ts"],"sourcesContent":["import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { KB_COMMANDS } from \"./commands/index.js\";\nimport { KbStore } from \"./kb-store.js\";\n\n/**\n * A knowledge base's own MCP server, over stdio.\n *\n * Standalone because a base is self-contained: a directory of markdown that\n * needs no database, no HTTP surface, and no running service to read. Folding\n * these tools into a larger server would make every consumer start that server\n * to open files it could open itself.\n *\n * Every tool is a projection of `KB_COMMANDS`, which the CLI also projects, so\n * the two cannot drift.\n */\nexport function createKbMcpServer(): McpServer {\n  const server = new McpServer({ name: \"strauss-kb\", version: \"0.1.0\" });\n  const store = new KbStore({\n    warn: (entry) => process.stderr.write(`${JSON.stringify(entry)}\\n`),\n  });\n  const ctx = {\n    store,\n    actor: process.env.STRAUSS_KB_ACTOR ?? \"mcp\",\n    now: () => new Date().toISOString(),\n  };\n\n  for (const command of KB_COMMANDS) {\n    // CLI-only plumbing (sync-instructions) edits files for hooks and\n    // instruction blocks; the agent capability it serves is kb_context.\n    if (!command.tool) continue;\n    server.registerTool(\n      command.tool,\n      { description: command.description, inputSchema: command.input.shape },\n      async (args: unknown) => {\n        const result = await command.run(ctx, command.input.parse(args));\n        return {\n          content: [\n            {\n              type: \"text\" as const,\n              text:\n                typeof result === \"string\"\n                  ? result\n                  : JSON.stringify(result, null, 2),\n            },\n          ],\n        };\n      },\n    );\n  }\n\n  return server;\n}\n\nexport async function runKbMcpServer(): Promise<void> {\n  await createKbMcpServer().connect(new StdioServerTransport());\n}\n"],"mappings":";;;;;;AAAA,SAAS,iBAAiB;AAC1B,SAAS,4BAA4B;AAe9B,SAAS,oBAA+B;AAC7C,QAAM,SAAS,IAAI,UAAU,EAAE,MAAM,cAAc,SAAS,QAAQ,CAAC;AACrE,QAAM,QAAQ,IAAI,QAAQ;AAAA,IACxB,MAAM,CAAC,UAAU,QAAQ,OAAO,MAAM,GAAG,KAAK,UAAU,KAAK,CAAC;AAAA,CAAI;AAAA,EACpE,CAAC;AACD,QAAM,MAAM;AAAA,IACV;AAAA,IACA,OAAO,QAAQ,IAAI,oBAAoB;AAAA,IACvC,KAAK,OAAM,oBAAI,KAAK,GAAE,YAAY;AAAA,EACpC;AAEA,aAAW,WAAW,aAAa;AAGjC,QAAI,CAAC,QAAQ,KAAM;AACnB,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,EAAE,aAAa,QAAQ,aAAa,aAAa,QAAQ,MAAM,MAAM;AAAA,MACrE,OAAO,SAAkB;AACvB,cAAM,SAAS,MAAM,QAAQ,IAAI,KAAK,QAAQ,MAAM,MAAM,IAAI,CAAC;AAC/D,eAAO;AAAA,UACL,SAAS;AAAA,YACP;AAAA,cACE,MAAM;AAAA,cACN,MACE,OAAO,WAAW,WACd,SACA,KAAK,UAAU,QAAQ,MAAM,CAAC;AAAA,YACtC;AAAA,UACF;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AAEA,eAAsB,iBAAgC;AACpD,QAAM,kBAAkB,EAAE,QAAQ,IAAI,qBAAqB,CAAC;AAC9D;","names":[]}