#794 Guide kb-add note placement with the store's declared taxonomy

[williamthorsen]

What

Improves classification of captured knowledge-base notes by aligning with the domains declared by the KB's taxonomy rather than looking to the directory structure. If a note is filed in a folder not covered by a domain, that folder is now added to the base's taxonomy. A domain added without confirmation is recorded as awaiting review.

Why

Notes drifted into inconsistent folders as a knowledge base grew. With nothing declaring what a base's
shelves were, each capture inferred a folder from whatever a directory listing happened to show, and an
early guess became the precedent the next capture imitated. .kb/taxonomy.yaml gave a base somewhere to
state its structure, but nothing consulted it at the moment a note was placed, so the declared structure
and the structure on disk had no way to converge.

Details

🎉 Features

kb-add helper

• --survey reports the destination's shape: the resolved knowledge base, its .kb/taxonomy.yaml path,
  each declared domain with its description, review state, and note count, and the folders holding notes
  that no domain declares. It writes nothing, opens no note, and returns without consuming stdin, so it is
  safe to run before composing a note. A store the registry marks readonly: true surveys successfully;
  only writes are refused.
• A capture into a folder no domain declares records that folder, plus every undeclared folder above it, so
  the declared structure stays connected and a nested capture mints no taxonomy.orphan warning.
• --domain-description supplies a new domain's one-line description; without it the domain is recorded
  bare. --auto routes the domain to provisional:, as does any capture that supplied no description.
• placement in the result names the domain the note sits in and every domain the capture declared, each
  carrying the block it landed in. A note at the assertions root reports as sitting under no domain.
• A capture whose declaration fails still succeeds, returning the written path plus a warning naming what
  went unrecorded; the folder surfaces as taxonomy.undeclared on the next kb check.
• Adoption is the taxonomy file's presence, so a base whose taxonomy is empty grows its first domain from
  its first capture.
• A malformed .kb/config.yaml or .kb/taxonomy.yaml returns the new invalid-config error code with the
  offending file named, where a survey previously exited non-zero with a bare stderr line.

kb-add skill

• A ## Placement section states the policy: the declared taxonomy is a strong prior with the long tail
  carried by tags, a new domain is warranted by intent rather than note count and is named to match the
  domains already declared, auto mode does not mint a top-level domain, a folder name restating a tag is
  expected, and a reviewed domain beats an unreviewed one where both fit.
• The process runs the survey before classifying, and the proposal names the matched domain, that domain's
  description, and the taxonomy file they came from, so the user can see what the placement was measured
  against.
• The worked invocation example carries a concrete --folder, and the two redundant restatements of the
  assertions/-segment rule are cut so it is stated once, in the argument table. Closes kb-add silently nests a note when --folder restates the content/assertions/ prefix #825.

@williamthorsen/kb

• ./check gains enumerateNotePaths, which returns the note set enumerateNotes selects as
  store-root-relative paths without opening a single note.
• ./taxonomy gains resolveDomain and resolveParent, so a consumer classifying notes against a
  taxonomy derives its answers from the same mapping the drift rules and the back-fill use, and the three
  cannot disagree about which folder a note observes.

♻️ Refactoring

• enumerateNotes and enumerateNotePaths share one walk, scope matcher, and pruning pass via
  collectNoteLocations.
• kb-curate's module-private readonly-tolerant resolver wrapper moves onto a requireWritable option on
  the shared knowledge-base resolver, which the survey path also uses. The wrapper's reconstruction of the
  source label from the explicit-KB input goes away with it.

🧪 Tests

• New unit suites cover the survey and the declaration step: the mixed leaf/ancestor review-state case,
  both reachable declaration-failure causes, a store with no taxonomy and one with an empty taxonomy, and a
  note at the assertions root.
• The survey's read-only contracts are pinned by instrumenting readFile to prove no note is opened, and
  by a stdin stream that never ends, so a regression that consumed stdin hangs rather than passing quietly.
• enumerateNotePaths is tested for set equality against enumerateNotes under the same targets and
  excludes, which is the invariant the export exists to preserve.

Closes #794

[github-actions]

Dependency audit

Production dependency audit passed.