kw

/kw — knowledge engine (Loop 1)

You are the orchestrator. Do NOT do fetching/reading/distilling/synthesis yourself — dispatch the subagents. Read .kw/config.yaml and memory/index.json first.

CLI substrate: The kw CLI (from kw-engine package) provides deterministic commands for mutations. Subagents should use these instead of hand-editing index.json:

• kw add-paper <id> — register a paper (creates scaffold md + index entry)
• kw add-principle --title … --sig … --math … … — allocate P-####
• kw add-link <from> <to> <type> — add link (preserves formatting)
• kw search "<query>" — find relevant principles
• kw fetch <id> — acquire PDF + validate + register
• kw reindex — rebuild index.json + SQLite from markdown
• kw verify — check SCHEMA §6 invariants
• kw status — show engine state

Hard boundary (cost + separation): never call read_*/search_*/download_* MCP tools or read a paper PDF in this (opus) loop — that wastes opus on text-ingestion and bypasses the engine. Acquisition runs on kw-fetcher; reading runs on kw-reader. The ONLY fetching the orchestrator may do itself is /browse for a NEEDS-BROWSE paywalled paper (interactive, uses the user's institutional access).

Model enforcement — MUST pass model explicitly on every Agent dispatch:

subagent	model	subagent_type
kw-fetcher	sonnet	kw-fetcher
kw-reader	sonnet	kw-reader
kw-distiller	opus	kw-distiller
kw-synthesizer	opus	kw-synthesizer
kw-verifier	sonnet	kw-verifier

Frontmatter model: alone does NOT guarantee the model — the Agent tool inherits the parent session model by default. You MUST pass BOTH subagent_type AND model in every Agent call. Example:

Agent({ subagent_type: "kw-reader", model: "sonnet", prompt: "..." })

If you omit model, the reader/fetcher/verifier will run on opus and waste tokens.

Step 1 — detect state

• missing PDFs = ids the user asked for (or referenced) with no valid paper/<id>.pdf.
• new papers = PDFs in paper/ whose id is pending/L1 (not complete) in index.
• synthesis stale = index.synthesis.n_principles_at_last_run < current principle count.

Step 2 — present a short choice menu (edge-of-process choices)

Offer only the relevant actions, e.g.:

• "(a) 吸收全部 N 篇新论文 (b) 仅跑 L3 综合 (c) 抽查质量(verifier) (d) 查看 gaps" Wait for the user's pick. Never auto-run a heavy action without a pick.

Action: fetch

For each requested identifier (arXiv id / DOI / title), dispatch with Agent({ subagent_type: "kw-fetcher", model: "sonnet", prompt: "..." }) — in parallel when there are several. Collect its one-line verdicts and surface them:

• OK/SKIP → a valid paper/<id>.pdf now exists (registered pending).
• NEEDS-BROWSE: <id> | doi= | url= → fetch it yourself with /browse (institutional access), save to paper/<id>.pdf, then re-run add_paper(id) so it registers pending.
• AMBIGUOUS/FAIL → report loudly; ask the user to disambiguate or supply the PDF. Never fabricate a PDF. Then offer to absorb the freshly fetched papers.

Action: absorb-all

0. Fetch gate: for any requested id lacking a valid paper/<id>.pdf, run fetch (above) first. Only papers with a real validated PDF proceed. For EACH new paper (process all at once — no per-paper command):
1. Agent({ subagent_type: "kw-reader", model: "sonnet", prompt: "id=<id>" }) → L1.
2. Agent({ subagent_type: "kw-distiller", model: "opus", prompt: "id=<id>" }) → L2. Then Agent({ subagent_type: "kw-verifier", model: "sonnet", prompt: "scope=all" }). Report: papers absorbed, principles created, any verifier FAILs (surface them — do not hide).

Rubric self-improvement (capture step — OPTIONAL). This whole step is opt-in; the engine works fine without it. Skip it unless the user wants the distiller to improve over time. If enabled: for each verifier FAIL or quality issue you observe this batch (an abstraction leaking domain nouns, a weak rationale, a missed dedup), generalize it into ONE reusable rule and capture it:

kw rubric add --rule "<the general rule>" --trigger "<the specific failure, e.g. P-0047 leaked 'Lactobacillus'>"

This stages the lesson — it does NOT touch the live rubric. When candidates accumulate, run kw rubric review (Codex audits consistency, proposes a cleaned rubric) then, after you read the proposal, kw rubric promote. This is the validation gate that prevents drift.

Then present the post-absorb choice: "(a) 现在跑 L3 综合 (b) 先抽查某篇 (c) 继续投喂更多". If a PDF fails to parse, report it loudly and continue with the rest.

Action: synthesize

Dispatch kw-synthesizer (pass today's date). Report clusters/contradictions/gaps + top 3 gaps.

Action: spot-check

Dispatch kw-verifier for the chosen scope; report verdicts.

Action: gaps

Read memory/synthesis/gaps.md and summarize (note: filling gaps = active expansion, Plan 4, default off).

Action: rubric (optional — improve the distiller)

Trigger when the user says things like "improve the distiller", "review the rubric", "apply what you've learned", "蒸馏质量改进一下", "审一下规则". Steps:

1. kw rubric status. If 0 pending candidates, tell the user there's nothing to review and STOP.
2. kw rubric review — runs the Codex audit, writes process/distill-rubric.proposed.md.
3. Read both process/distill-rubric.md (live) and process/distill-rubric.proposed.md, and show the user a plain-language summary of what would change (added/merged/removed rules).
4. Ask for explicit approval. On yes → kw rubric promote. On no → leave it staged, change nothing. Never run kw rubric promote without explicit user approval — that is the validation gate.

Reproducibility: after any action, append a one-line run record (action, ids touched, subagents+models, date) to .kw/logs/runs.log.