kb-ingest

kb-ingest (ingest / deingest)

The KB lives at ~/.knowledge/. The storage schema (raw/wiki layout, OKF v0.1 conformance, page conventions, status notation, symlink spec) is in ~/.knowledge/CLAUDE.md — read it before starting.

The wiki/ layer is an OKF v0.1 bundle — every page you write or update must satisfy §9.1 (parseable YAML frontmatter + non-empty type).

Ingest

1. Read the schema (~/.knowledge/CLAUDE.md).

2. Collect intermediate-artifact files into ~/.knowledge/raw/: scan ~/works/<project>/docs/{designs,reviews,plans}/ and any other location holding AI-generated middle artifacts (acceptance-test records, retrospectives, conversation logs). Copy each into ~/.knowledge/raw/<project>/<category>/<name>.md if not already mirrored. Tracking state is irrelevant — commit-tracked files are mirrored too. Never delete the source as a shortcut and never skip the copy because "it's already committed in the repo".

3. Read the target at manifest depth only (no full-source reads). Create/update ~/.knowledge/wiki/projects/<name>.md → update wiki/entities/ and wiki/topics/ for cross-cutting elements and add cross-links → register in wiki/index.md → append to wiki/log.md under the matching ## YYYY-MM-DD H2 heading (or add a new heading newest-on-top). Cite the source raw path for every claim (raw/<project>/... for mirrored artifacts; anchor path — works/<path> or ~/.claude/<path> — for source code, manifests, README, CLAUDE.md); mark unverified items as (guess).

4. Write OKF frontmatter at the top of every wiki page (see schema for controlled type vocabulary):

   ---
   type: Project Wiki        # or Entity Wiki / Topic Wiki
   title: <human-readable name>
   description: <one-sentence summary>  # recommended
   tags: [<keyword>, ...]               # recommended
   timestamp: <ISO 8601 UTC>            # this ingest's clock
   source_paths:                        # optional
     - works/<project>/<file or dir>
   source_commit: <git SHA>             # optional but recommended
   ---
   

5. Do not duplicate ground truth. Versions, package manager, presence of CLAUDE.md, etc. come from package.json / lockfile / filesystem at query time. The wiki holds only knowledge that cannot be re-derived from the primary source (purpose, cross-cutting relations, pitfalls, contradictions). Verify package manager from the actual lockfile — do not trust external tables.

6. Large monorepos / framework forks such as angular get a pointer page only.

7. Mandatory post-write sanitize (textlint). After every wiki write/update (project page, entity/topic page, index.md, log.md), run the memory-sanitize skill's check.sh on <changed wiki .md files> and reach 0 violations before moving to step 8. The check surfaces candidates — judge each: if a real violation, restructure the prose; if a false positive (heading-then-list : etc.), leave as-is and note why. Do not pass ~/.knowledge/raw/* or the allowlist *.json files to check.sh — they are not prose. Restrict the argument list to the .md files this ingest touched.

8. Mandatory post-write tech-writing review. After step 7 reaches 0 violations, perform the tech-writing skill review on every wiki .md page this ingest touched. Read the skill's normative sections in full and inspect each touched page for violations the mechanical lint cannot detect — paragraph structure, argumentative rigor, redundancy, performative phrasing, LLM-style filler. Fix violations or, for justified exceptions, leave a one-line reason. If the review modifies prose, re-run step 7's check.sh to confirm textlint still passes.

9. Mandatory post-write OKF check. Run the kb-lintskill'skb-lint.sh`` and confirm the §0 conformance row reports frontmatter 欠落 0 / type 欠落 0 / 予約構造違反 0. Any non-zero count blocks declaring the ingest complete — fix the offending page (add type: or restore the reserved file's required structure) and re-run. Declaring the ingest complete requires steps 7, 8, and 9 to have passed.