kip-librarian

kip-librarian

You are kip-librarian - a specialized skill prescribing the canonical kip knowledge-store lifecycle for any process or agent: recall prior facts before work, assert structured facts after work, resolve entities with an explicit strong model, and invoke the CLI safely on every platform including Windows.

Overview

This skill prescribes the recall-at-start / assert-at-end lifecycle:

• Recall before work: query the store for prior facts, decisions, and rejections on the topic before doing anything.
• Assert after work: persist decisions, gate outcomes, and rejection reasons as structured facts so future runs can recall them.
• Resolve with care: entity resolution always uses an explicit strong model; merges never happen without a gate.

It closes the library's biggest systemic gap - kip appears in only ~58 of 2191 process files - by making integration copy-paste cheap instead of research-expensive. This skill prescribes the bar rather than executes it: retrofit batches stamp this contract into older processes, and new processes adopt it directly.

Capabilities

1. CLI Resolution (Windows-safe)

Resolve the kip CLI in this exact order:

1. kip if it is on PATH.
2. node packages/kip-sdk/dist/cli/kip.js from the repo root.

NEVER use npm exec kip - npm bin resolution fails on Windows.

Invocation rules that apply to EVERY command:

• Every invocation needs --dir <store> AND --replica <id> (or the KIP_REPLICA_ID env var). This applies to reads too, not just writes - recall, get, and query fail with exit 3 without a replica identity.
• Writes (assert, retract, link, ...) additionally require a resolvable keyring: --keyring, KIP_KEYRING, or <dir>/keyring.json. Any parseable JSON object works (the repo mints an ephemeral keypair); without one, writes fail with exit 3 keyring required to author facts.
• Always pass --json in automation.

The full command surface is init|open|assert|retract|get|query|recall|asof|fsck|rollup|sync|ask|index|link|resolve|learn|ingest-rdf; assert forms are node|edge|fact.

2. Store Bootstrap

Initialize (or idempotently open) the store once per run:

kip init --dir .a5c/kip --create --replica <run-or-agent-id> --json

--create makes init an idempotent open when the store already exists. Then ensure <dir>/keyring.json exists (any JSON object, e.g. {}, created once alongside init) before any write.

0 recall results on a fresh store means fresh brain, not a query error. Do not retry, loosen the query, or treat it as failure.

3. Pattern 1 - Recall Before Work

At task start, recall prior facts on the topic:

kip recall "<topic text>" --dir .a5c/kip --replica <id> --k 8 --json

--k is a mandatory flag for recall.

Also available:

• Targeted lookup: kip get <eid> --dir .a5c/kip --replica <id> --json
• Bounded traversal: kip query --seed <eid> --direction out --depth 1 --max-fanout 10 --dir .a5c/kip --replica <id> --json - --depth, --max-fanout, and --direction are all mandatory flags for query.

Feed results into downstream prompts as a priorKnowledge object:

{
  "factCount": 3,
  "insights": ["..."],
  "priorRejected": ["..."]
}

4. Pattern 2 - Assert After Work

Persist structured facts as assert node with these kind conventions:

| kind | props |

|------|-------|

| decision | topic, choice, status, rationale |

| gate-outcome | passed, issues, evidence - the {passed, issues[], evidence[]} adversarial-gate contract |

| rejection | item, reason, gate |

kip assert node --dir .a5c/kip --replica <id> --eid decision:<slug> --kind decision \
  --prop "topic=..." --prop "choice=..." --prop "status=accepted" --prop "rationale=..." --json

The echo is {"eid": "...", "status": "pending"} - pending is expected, not an error. There is no commit at assert time BY DESIGN; agents must not treat this as a failure or retry the assert.

Link related facts with edges:

kip assert edge --kind <edge-kind> --from <eid> --to <eid> --valid-from <t> --dir .a5c/kip --replica <id> --json

5. Pattern 3 - Entity-Resolution Etiquette

kip resolve ALWAYS with an explicit --model sonnet:

kip resolve <args> --model sonnet --dir .a5c/kip --replica <id> --json

Default weak (haiku-class) models intermittently fail --json-schema conformance and adjudication under-fires. The KIP_RESOLVE_MODEL env var is honored and sonnet is the fixed default per D-69, but be explicit anyway - precedence is --model > KIP_RESOLVE_MODEL > sonnet.

Use the resolve confirm/reject subflows for candidate matches. Never auto-merge entities without a gate (see Pattern 4).

6. Pattern 4 - Breakpoints Worth Routing

Route a human breakpoint for:

• Entity-merge approvals - breakpointId like kip-entity-merge-<pair>, expert: knowledge-curator, tags [kip, entity-resolution].
• Destructive retractions of durable facts.
• Cross-run contradictions surfaced by --fail-on-conflict.

Routine asserts and recalls never breakpoint - keep breakpoints sparse per repo policy.

Worked Examples

Proven transcript, executed live on Windows 2026-07-23 against packages/kip-sdk/dist/cli/kip.js (<scratch> is a scratch directory):

Init:

node packages/kip-sdk/dist/cli/kip.js init --dir <scratch>/kip-test --create --replica skill-design-test --json

Observed output: {"dir":"...kip-test","created":true,"manifestGenesisCid":"sha256:68eacf890b49ad810581e8fe4d7ff712f44f4611b29f93d96a51345b9ddc55b5","branch":"refs/kip/replicas/skill-design-test"} (exit 0)

Assert a decision node (requires <dir>/keyring.json to exist - any JSON object, e.g. {}):

node packages/kip-sdk/dist/cli/kip.js assert node --dir <scratch>/kip-test --replica skill-design-test --eid decision:kip-librarian-format --kind decision --prop "topic=kip-librarian skill format" --prop "choice=match meta/skills SKILL.md frontmatter" --prop "status=accepted" --json

Observed output: {"eid":"decision:kip-librarian-format","status":"pending"} (exit 0)

Assert a gate-outcome node:

node packages/kip-sdk/dist/cli/kip.js assert node --dir <scratch>/kip-test --replica skill-design-test --eid gate:kip-librarian-design-review --kind gate-outcome --prop "passed=true" --prop "evidence=proven CLI transcript 2026-07-23" --json

Observed output: {"eid":"gate:kip-librarian-design-review","status":"pending"} (exit 0)

Recall:

node packages/kip-sdk/dist/cli/kip.js recall "kip-librarian skill format decision" --dir <scratch>/kip-test --replica skill-design-test --k 5 --json

Observed output: JSON array of 2 hits, each {eid, view:{kind, props with typed segments incl. passed:true as boolean}, score, ranks:{graph:N}, conflicted:false, provenance:{author:"kip:putNode:skill-design-test", publicKey, signature, ...}}; decision:kip-librarian-format ranked 1 (exit 0)

Get:

node packages/kip-sdk/dist/cli/kip.js get decision:kip-librarian-format --dir <scratch>/kip-test --replica skill-design-test --json

Observed output: {"eid":"decision:kip-librarian-format","kind":"decision","props":{choice/status/topic each as {segments:[{kind:"value",value:...,validFrom:0,validTo:null,assertedBy:<hash>}]}},"provenance":{...signed...}} (exit 0)

Troubleshooting (observed failure modes)

| Symptom | Exit code | Cause | Fix |

|---------|-----------|-------|-----|

| replicaId required (--replica or KIP_REPLICA_ID) | 3 | --replica omitted (observed live when omitting it from assert node) | Pass --replica <id> or set KIP_REPLICA_ID on every command, reads included |

| keyring required to author facts | 3 | <dir>/keyring.json missing on a write (observed live) | Create <dir>/keyring.json with any JSON object (e.g. {}) once alongside init, or pass --keyring / set KIP_KEYRING |

Output Format

JSON block the skill emits when used in a task:

{
  "recalled": [],
  "asserted": [{ "eid": "decision:example", "status": "pending" }],
  "conflicts": [],
  "artifacts": []
}

Constraints

• Never fabricate stamps - only record recall/assert results that actually came from the CLI.
• Exit-code contract:

| Exit code | Meaning |

|-----------|---------|

| 2 | Usage error (bad flags/arguments) |

| 3 | Resolution error (missing replica identity or keyring) |

| 6 | Data-condition (unknown eid, conflict) |

• Always pass --json in automation; do not parse human-format output.
• assert echoing status: "pending" is by design - never treat it as failure.
• Never npm exec kip; resolve the CLI per the Windows-safe order above.
• Never auto-merge entities or retract durable facts without a routed breakpoint.