Guide kb-add note placement with a per-KB taxonomy.yaml

[williamthorsen]

Problem

kb-add improvises a folder for each note from whatever already exists on disk. With nothing
to anchor to, early notes drift into inconsistent domains and the structure never converges.
#1196 gives a knowledge base a declared taxonomy; nothing yet consults it when a note is
placed.

Context

Depends on #1196 for the .kb/taxonomy.yaml format, its loader, and its comment-preserving
writer.

Absorbs #825, which edits the same kb-add SKILL.md surfaces this ticket touches, in the
opposite direction.

Requiring a taxonomy of stores marked shared is #1193, which needs the visibility
primitive from #1190 and is out of scope here.

Nothing currently reads the provisional flag: kb taxonomy init writes it, the loader
carries it, and no lint, command, or report consumes it. This change adds a second producer
without a queue that surfaces entries awaiting review. Promotion stays a manual edit.

Proposed solution

The taxonomy records placement decisions rather than gating them. kb-add never refuses a
placement; it writes where told and declares the folder when no domain does, so the file
accumulates what actually happened. The declared taxonomy is the primary placement signal and
the on-disk folder survey corroborates it, rather than the reverse.

Folders serve human browsing and tags serve machine retrieval, so a folder name restating a
tag is expected rather than redundant. The bar for a new domain is intent, not note count: a
domain is warranted when someone means to keep that shelf, however few notes sit on it.

A new KB starts with an empty taxonomy and grows one domain per capture.

Barring auto mode from creating a top-level domain is guidance, not an acceptance criterion.
The caller chooses which flags to pass, so any flag-keyed restriction binds only a caller that
opts into it.

Acceptance criteria

Must have

kb-add

• The taxonomy is the primary placement signal, the existing folder and note survey
  corroborates it, and a disagreement between them surfaces as a drift signal.
• Classification treats the taxonomy as a strong prior rather than a hard constraint: the
  long tail is absorbed by tags rather than forced into an ill-fitting folder.
• When no declared domain fits, kb-add proposes a new one named to match existing
  conventions. In default mode the proposal carries the new domain and its description for
  confirmation.
• The proposal step names the matched domain and the taxonomy it came from.
• The worked invocation example carries a concrete --folder value, and the redundant
  --folder restatements are cut so the rule is stated once (kb-add silently nests a note when --folder restates the content/assertions/ prefix #825).

The helper

• A read-only mode reports the resolved knowledge base, its declared domains with their
  descriptions and review state, and the folders holding notes. It resolves the knowledge
  base exactly as the write path does, and reads no note body.
• In a single invocation the helper writes the note and idempotently declares the note's
  folder, plus any undeclared ancestors, when no domain declares the folder.
• A flag supplies a new domain's description; without it the domain is declared bare.
• A domain lands in domains: only when the capture was confirmed and carries a
  description. Every other append is provisional, so it can be reviewed later.
• The result reports any domain the write declared, and reports a note written to the
  assertions root as sitting under no domain.
• A declaration failure after a successful note write does not fail the capture: the
  result stays ok, reports the written path, and carries a warning naming what could not
  be declared.
• With no taxonomy present, the helper behaves as it does today.

Gates

• New and modified behavior in this change is covered by tests.
• Documentation covers the new mode and the new flag.

[williamthorsen]

Design notes from a live cold start, where a brand-new knowledge base needed placement guidance and this mechanism did not exist yet.

Unmatched-note behavior needs an explicit decision. When a note fits no declared domain, the options are refuse, place at root, or propose a new domain and require confirmation. Propose-and-confirm looks right: a taxonomy that cannot grow gets bypassed, and silent root placement is how triage folders accumulate. coding-kb already carries a content/_triage/ tree, which is the evidence.

Surface the matched domain in kb-add's proposal step. Placement is the judgment most worth a human glance and currently the least visible one. Echoing the matched domain, and the taxonomy it came from, costs one line and catches a misfiling before the write rather than after.

Make the taxonomy the source of truth and the folder tree derived. Folders are created lazily as notes arrive, so the declared taxonomy is the only complete picture of intended structure. That also unlocks drift detection in kb check: folders present but undeclared, and declared domains holding zero notes.

Interaction with #1190. For a store marked shared, the taxonomy's domain descriptions stop being a personal hint and become a filing contract for other contributors. A shared store arguably should require a taxonomy rather than treating it as optional.