@hraness/kb 0.18.0 → 0.19.0

package/skills/kb/references/customize.md

@@ -0,0 +1,123 @@
+# Customize a KB setup
+
+Design the smallest KB arrangement that answers the user's recurring memory
+questions. Begin with an interview and read-only inspection. Do not install a
+runtime, initialize a vault, build an index, access an account, or write a file
+before the proposal has the user's approval.
+
+## Establish the boundary
+
+Identify the repositories, vaults, people, agents, and time horizons in scope.
+Ask what the KB must help a future agent recover, which information must remain
+outside it, and which existing instructions govern the target paths. Treat the
+user's explicit request as authorization for the named work. Do not extend it
+to another path, repository, account, application, or integration.
+
+For a new vault, ask for or propose an exact location. Do not require an
+existing `index.md`. For an existing vault, resolve its front door and read the
+applicable `AGENTS.md` files before proposing changes.
+
+## Inspect without mutation
+
+Inspect only the surfaces needed to understand the current setup. Typical
+evidence includes directory structure, existing Markdown conventions, scoped
+agent guides, active plans, source records, repository paths, and available
+local commands. Keep filesystem, application, account, network, and
+integration access within the user's stated scope and the host's actual
+permissions.
+
+Do not run `kb doctor`, `kb init`, `kb index`, QMD, hybrid or semantic search,
+an installer, or a command that may create a cache during this phase. Do not
+create a hidden profile such as `.context/me.md` or infer personal context from
+an ambient account.
+
+## Interview in small batches
+
+Ask only questions whose answers change the proposed structure. Prefer a small
+batch about one decision at a time:
+
+- Which recurring questions should the KB answer?
+- Which sources, maintained explanations, plans, and repository rules already
+  exist?
+- Which writes should happen automatically, require review, or never happen?
+- Which recurring action is common enough to justify a companion skill?
+
+Summarize each resolved decision before moving to the next uncertain one. A
+short interview may conclude that the standard profile or no change is best.
+
+## Propose the smallest useful change
+
+Describe the exact files and surfaces before editing. Use this table:
+
+| Surface | Exact target | Read | Write | Purpose | Approval |
+| --- | --- | --- | --- | --- | --- |
+| Vault | `<path>` | `<bounded inputs>` | `<files or none>` | `<memory question>` | `<approved or pending>` |
+
+Propose zero to three companion skills. Each proposed skill must own a distinct
+recurring request that the main `kb` router cannot express clearly enough. Do
+not add a skill only to restate repository policy or wrap one command.
+
+State the verification, idempotence, retry, and failure behavior for every
+write. Keep Markdown and Git authoritative. Treat indexes, embeddings,
+catalogs, graph reports, and caches as replaceable views.
+
+## Obtain approval
+
+Present the proposal and wait when its writes are not already authorized by
+the user's explicit request. Approval applies to the exact targets and
+operations shown. A changed path, expanded repository, additional skill,
+account surface, network action, or broader write requires renewed approval.
+
+Silence, a denial, or an ambiguous response is not approval. Inspection does
+not grant write authority. Discovery of a command, application, account, or
+integration does not authorize its use.
+
+## Scaffold within the approved boundary
+
+Create only approved paths. For a companion skill, read [Companion skill
+contracts](companion-skills.md) and copy
+[`companion-skill.template.md`](../templates/companion-skill.template.md) to
+`<explicit-skill-root>/<name>/SKILL.md`. Never edit the template inside an
+installed package or `node_modules`.
+
+If approved execution needs the KB CLI, prepare the runtime now using the main
+skill's pinned installation instructions. Installation does not authorize
+`kb init`, indexing, semantic search, or vault writes. Run only the approved
+commands and exact allowlisted writes.
+
+The scaffold executor writes filesystem targets only. It never performs an
+application, account, network, or integration write. A companion skill may
+describe one of those later actions, but its execution is a separate runtime
+request with its own exact proposal, approval, tool boundary, and result.
+
+On a repeated request, compare the desired bytes with the approved targets.
+Treat an exact match as a no-op. Stop on divergent existing content, a symlink,
+a path that escapes the approved root, an unapproved external surface, or a
+partial write. Report the retained state instead of overwriting, silently
+retrying, or widening the boundary.
+
+## Start with real material
+
+Use a small amount of material that exercises the agreed structure: one saved
+source, one maintained explanation, one plan, or one repository-context
+mapping. Do not manufacture empty directories, placeholder notes, a complete
+ontology, or speculative metadata merely to make the vault look populated.
+
+## Verify and hand off
+
+Verify every approved file and record the exact paths changed. Run the
+narrowest applicable KB checks only when they were approved and the runtime is
+available. State what remains unconfigured, which views are rebuildable, and
+which action would require separate authority.
+
+Keep durable output free of credentials, session material, account exports,
+and hidden ambient context. Record source provenance and the boundary of any
+incomplete acquisition.
+
+## Evolve an existing setup
+
+Re-run the boundary, inspection, interview, proposal, and approval steps when
+the vault's recurring questions change. Prefer a focused convention or skill
+revision to a migration. Preserve authored Markdown and Git history, and do not
+mass-rewrite metadata to fit a new taxonomy unless a measured retrieval or
+maintenance problem justifies that work.

package/skills/kb/references/percolate.md

@@ -42,6 +42,16 @@ minimum of two therefore requires two shared signals, not merely both endpoints
 of one tag match. Other candidate kinds count their natural unit: supporting
 notes, mention occurrences, or authored hygiene evidence.
 
+Percolation Result V2 reports a missing relationship as an unordered pair of
+endpoints with `predicate: { "kind": "required" }`. The output does not choose
+which note owns the assertion, its direction, or its predicate. In particular,
+it never inserts `related-to` as a fallback. Read both notes and their evidence,
+then choose a source, target, and predicate only when the prose establishes that
+claim. Historical unversioned V1 results may contain a suggested predicate;
+parse them through the explicit V1 compatibility surface and do not treat that
+suggestion as an authored fact or silently upgrade it to V2. V1 remains
+available through the 0.19 release line and is not removed before 0.20.0.
+
 For a missing concept, use `suggestedId`. When `collidesWith` is non-null, the
 natural ID is already an ordinary note, so KB chooses an unoccupied
 `*-concept` ID. Read the occupied note before deciding whether to create the
@@ -88,11 +98,26 @@ kb relation add notes/write-path supports notes/durable-agent-memory \
   --root "$KB_ROOT"
 ```
 
-Use a specific lower-kebab-case predicate. A local target is an exact
-vault-root note ID without `.md`. A reviewed cross-vault target is its stable
-qualified identity, such as `kb://hraness/kb/document-id`; never use a checkout
-path as cross-vault identity. Ground the assertion in nearby prose or evidence;
-the frontmatter is an indexable statement, not a substitute for explanation.
+Use a specific lower-kebab-case predicate. Recommended predicates for common
+KB evidence and maintenance claims are:
+
+- `synthesizes` when the source combines and maintains conclusions from the
+  target material;
+- `evidenced-by` when the target directly supports a claim in the source;
+- `informed-by` when the target influenced the source without serving as its
+  direct evidence;
+- `supersedes` when the source deliberately replaces the target as the current
+  account;
+- `contradicts` when the source records a supported incompatible claim.
+
+This vocabulary is advisory. A vault may use any canonical custom predicate
+whose meaning its prose establishes. Do not assign a recommended predicate by
+directory, note type, shared tags, chronology, or similarity alone. A local
+target is an exact vault-root note ID without `.md`. A reviewed cross-vault
+target is its stable qualified identity, such as
+`kb://hraness/kb/document-id`; never use a checkout path as cross-vault
+identity. Ground the assertion in nearby prose or evidence; the frontmatter is
+an indexable statement, not a substitute for explanation.
 
 List or remove relationships without editing reciprocal notes:
 
@@ -103,8 +128,15 @@ kb relation remove notes/write-path supports notes/durable-agent-memory \
 ```
 
 Never write inverse edges, generated backlinks, inferred transitive
-relationships, or semantic-search scores into Markdown. Those are derived
-views.
+relationships, reciprocal edges, similarity-derived relationships, or
+semantic-search scores into Markdown. External or unclassified material is
+outside this vocabulary evaluation and remains unresolved. Those are derived
+views or review work.
+
+The interview-first setup and relationship-review pattern builds on Frank
+Chen's public notes about [designing a personal knowledge base with an
+agent](https://gist.github.com/fxchen/773397095d7a6bffda621e4237da0da9)
+and [extending it with skills](https://gist.github.com/fxchen/09cb410b22c9c5256d80243ee925b57e).
 
 ## Query before concluding
 

package/skills/kb/references/query.md

@@ -14,6 +14,27 @@ authority; search scores, metadata rows, and graph results are derived views.
 - Pass the resolved path to every `--root`; do not scan a repository root merely
   because that is where the agent session started.
 
+## Recover a stopped session
+
+When the user asks to resume earlier work, begin with the path being changed.
+Keep each retrieval signal separate so the agent can inspect why a record was
+returned:
+
+```sh
+kb context packages/parser/src/index.ts --root "$KB_ROOT" --repo "$KB_REPO"
+kb search "why parser retries stop" --root "$KB_ROOT" --mode exact \
+  --history --repo "$KB_REPO" --json
+kb backlinks notes/parser-contract --root "$KB_ROOT" --json
+kb history notes/parser-contract --root "$KB_ROOT" \
+  --repo "$KB_REPO" --json
+```
+
+Replace the example path, query, and note ID with values from the current task.
+Read the inherited guides and authoritative Markdown returned by these views.
+Use the backlink to inspect related plans and use Git history as provenance,
+not as proof that the note remains correct. This workflow recovers only context
+that was persisted in files or Git; it does not reconstruct private chat.
+
 ## Choose the retrieval lane
 
 - Repository file or directory: run `kb context` first. Read its inherited

package/skills/kb/templates/companion-skill.template.md

@@ -0,0 +1,57 @@
+---
+name: replace-with-skill-name
+description: Replace with the recurring KB request that should select this skill.
+---
+
+# Replace with the skill title
+
+## Use when
+
+State the exact recurring KB request that this skill owns.
+
+## Do not use when
+
+Route generic query, capture, plan, percolation, refresh, and validation work
+to the public `kb` skill. State any additional exclusions that prevent an
+unsafe or ambiguous match.
+
+## Inputs and preconditions
+
+List required inputs, existing state, commands, and authorization. Do not
+install, probe an account, create a cache, or mutate state while resolving
+these preconditions.
+
+## Surfaces and authority
+
+List every filesystem, repository, application, account, network, and
+integration surface this workflow may read or write. Discovery and an existing
+session grant no authority. The setup scaffold writes filesystem targets only;
+describe any later external action as a separate runtime request with its own
+proposal, approval, capable tool, and result.
+
+## Approval
+
+Name the exact write targets and effects. State when existing user
+authorization applies and which proposal changes require renewed approval.
+
+## Workflow
+
+Describe the smallest deterministic sequence that produces the approved
+result. Keep every effect inside the approved boundary.
+
+## Idempotence, retries, and failure
+
+Treat matching output as a no-op. Stop on divergent existing content, path
+escape, symbolic links, partial writes, or an unapproved surface. Do not
+silently retry or overwrite.
+
+## Durable outputs and provenance
+
+Name the files or records that persist, the evidence they retain, and their
+authority. Exclude credentials, tokens, cookies, session data, and unrelated
+ambient context.
+
+## Verification
+
+Name the narrow checks that demonstrate the approved result and the KB
+maintenance required after durable edits.

package/src/authoring.ts

@@ -35,7 +35,10 @@ import {
   type NoteLock,
   type NoteLockOptions,
 } from "./note-lock.js";
-import { isCanonicalNoteId } from "./graph.js";
+import {
+  isCanonicalNoteId,
+  isCanonicalRelationPredicate,
+} from "./graph.js";
 import {
   parseDocumentId,
   parseQualifiedDocumentUri,
@@ -43,7 +46,6 @@ import {
 
 const MAX_NOTE_BYTES = 16 * 1024 * 1024;
 const NOTE_REVISION_PATTERN = /^sha256:[0-9a-f]{64}$/u;
-const PREDICATE_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
 const MAX_PARENT_DIRECTORY_ENTRIES = 100_000;
 const MAX_RECOVERY_LOCATIONS_PER_NOTE = 8;
 
@@ -259,7 +261,7 @@ export function normalizeRelationPredicate(value: string): string {
     .replaceAll("_", "-")
     .replace(/\s+/gu, "-")
     .replace(/-{2,}/gu, "-");
-  if (!PREDICATE_PATTERN.test(normalized)) {
+  if (!isCanonicalRelationPredicate(normalized)) {
     throw new TypeError(`not a valid relation predicate: ${JSON.stringify(value)}`);
   }
   return normalized;

package/src/cli.ts

@@ -81,6 +81,7 @@ import {
   MAX_PERCOLATION_NOTES,
   MAX_SCOPED_PERCOLATION_MENTION_PAIRS,
   percolateVault,
+  type PercolationCliOutputV2,
   type PercolationResult,
 } from "./percolate.js";
 import {
@@ -2693,7 +2694,7 @@ function renderPercolation(result: PercolationResult, note: string | undefined):
       );
     } else if (candidate.kind === "missing-relation") {
       lines.push(
-        `  relation  ${safe(candidate.source)} ${safe(candidate.suggestedPredicate)} ${safe(candidate.target)}  (${candidate.support} shared signals)`,
+        `  relation pair  {${safe(candidate.source)}, ${safe(candidate.target)}}  (predicate required; ${candidate.support} shared signals)`,
       );
     } else if (candidate.kind === "unlinked-mention") {
       lines.push(
@@ -2754,13 +2755,17 @@ async function runPercolate(
       limit: command.limit,
     },
   );
+  const jsonOutput: PercolationCliOutputV2 = {
+    root: snapshot.root,
+    note: command.note ?? null,
+    minSupport: command.minSupport,
+    limit: command.limit,
+    schemaVersion: result.schemaVersion,
+    candidates: result.candidates,
+    truncated: result.truncated,
+  };
   output.stdout(command.json
-    ? terminalSafeJson({
-        root: snapshot.root,
-        note: command.note ?? null,
-        minSupport: command.minSupport,
-        ...result,
-      })
+    ? terminalSafeJson(jsonOutput)
     : sanitizeTerminalText(renderPercolation(result, command.note)));
   return 0;
 }

package/src/graph.ts

@@ -327,6 +327,13 @@ type ParsedMetadata = {
 const relationPredicatePattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
 const maxNoteIdLength = 2_048;
 
+/** Whether a value is the exact lower-kebab predicate accepted by the graph. */
+export function isCanonicalRelationPredicate(value: string): boolean {
+  return value !== ""
+    && value === value.normalize("NFC")
+    && relationPredicatePattern.test(value);
+}
+
 /**
  * Whether a value is the exact, extensionless vault-root ID used on disk.
  *
@@ -476,7 +483,7 @@ function parsedRelations(
     }
 
     const predicate = pair.key.value.normalize("NFC");
-    if (!relationPredicatePattern.test(predicate)) {
+    if (!isCanonicalRelationPredicate(predicate)) {
       relationIssues.push(malformedRelation(
         source,
         predicateLine,