2026-06-17 — Knowledge ingestion phase 0: prerequisites (brokered half)

Picked up the knowledge-ingestion epic. Phase 0 = the soul→knowledge promotion lane. Fritz chose prerequisites-first over a minimal manual cascade slice, so this session built the routing/autonomy substrate the promote primitive will sit on, not the cascade itself.

Done

A1 — mark_worlds writable column (broker, Go). The writer set already existed in code (authorizedWorlds / worldAllows(&w.Allow, claims), used by /auth/callback + /me/install) but was never exposed through read-discovery — #189 deliberately made mark_worlds list readable worlds only. Added a 4th writable: yes/no column computed per row from the caller's claims, so a single call yields {readable, writable}. Append-only column → library table parser unaffected. tools/demarkus-broker/internal/broker/mcp_tools_worlds.go (+yesNo), mcp_tools_list.go (tool description), mcp_tools_worlds_test.go. Full broker suite + pre-commit.sh green.

B — world.md per-world descriptor (spec + seed). Example at plugins/claude-code-knowledge/examples/knowledge-system/world.md + README wiring. Structured core: descriptor_version, team, domain, partition_role (hub|team|project|scratch), autonomy_ceiling (human-only|verify-then-auto|auto). Per-world well-known (mark://<world>/.well-known/demarkus/world.md), distinct from root-global policy/template. No-descriptor worlds still work (writable-but-unlabeled, pick-list only, default human-only). Reader is plain mark_fetch.

Key facts learned about the code

Plugins are pure bash/awk hooks + markdown slash-commands + skills — no Go on the promote path. The cascade (triage→distill→dedup→tag→gate→publish→back-stamp) is judgment-heavy model work → belongs in a slash command + skill driving MCP tools, matching the "agent as librarian / intelligence at the edge" invariant. Bash only for detection + back-stamp glue.
Detection is one-way today: knowledge reads ~/.demarkus/plugin-memory.conf (soul_is_configured) to spot a sibling soul; memory does NOT detect knowledge. Mutual detection (plan's bridge) = a memory-side peek at ~/.demarkus/knowledge-systems (the joined-slug registry written by /knowledge-join). Small, not yet built.
Broker authz: worldAllows is the writer predicate (per-world Allow: Emails carve-out, else Domains∧Groups); readableWorlds = every configured world (SSO org gate only). The two are kept deliberately separate so "all logins read, writes allow-listed" is expressible.

Deferred

A2 — plain-remote token-grant introspection (a demarkus-server surface reporting a token's {operations, path-globs}). Live target is brokered, so A1 unblocks routing now; A2 after the brokered path is proven.

Remaining phase-0 prerequisites/work: the promote primitive (the cascade, as /promote command + skill, detection-gated) and the coherence edge (link-not-copy stub / version-stamped back-stamp). A1+B are now in place to route and cap autonomy. Dogfood still stands: promote /plans/knowledge-ingestion.md itself as the first run.

Recorded progress in the plan under "## Build progress".

Session 2 — the promote primitive

Built the promote primitive (phase 0's core) on top of A1+B. Detection-gated bridge, split across both plugins, model-driven.

New files / changes:

plugins/claude-code/scripts/lib.sh — KNOWLEDGE_REGISTRY const + knowledge_endpoints() / knowledge_present() (reverse-peek the knowledge registry; mutual detection; broker-unaware).
plugins/claude-code/scripts/detect-knowledge.sh — detection gate (mirrors detect-soul.sh).
plugins/claude-code/commands/promote.md — /promote <soul-path>: gate → read source → already-promoted check → knowledge cascade → back-stamp (stub | marker-only). One-directional back-stamp; directional reconciliation.
plugins/claude-code-knowledge/skills/knowledge-promote/SKILL.md — execution cascade (triage→distill→dedup→tag→route→gate→publish). First skill in the knowledge plugin (auto-discovered, no manifest entry needed).
plugins/claude-code/tests/detect-knowledge_test.sh — 5 tests, green. Full plugin regression green (memory + knowledge).

Gotchas captured:

Skills + commands auto-discover from their dirs — no plugin.json entry (memory's manifest has no skills key yet soul-memory works).
KNOWLEDGE_REGISTRY is readonly, bound to HOME at source time → can't unit-test the function with a swapped HOME in one shell; test the script in fresh subprocesses with controlled HOME instead (what detect-knowledge_test.sh does).
shellcheck SC1091 (can't follow lib.sh) is info-level and identical on the established detect-soul.sh; no CI shellcheck config in .github. SC2317 in lib.sh:9 is pre-existing.

Next: coherence edge active half (version-stamped invalidation + re-promotion-as-gated-update), then dogfood /promote /plans/knowledge-ingestion.md. Triggers beyond manual (signal/batch) and A2 still open. Plugin version bumps left for Fritz.

Session 3 — coherence edge (folded into the promote branch)

Active downward half of the coherence edge. All plugin work, on branch feat/knowledge-promote-primitive.

Changes:

commands/promote.md — standardized back-stamp marker to a single greppable line promoted: mark://<world>/<path>@v<N> (both stub + marker-only modes); back-stamp now adds the promoted metadata tag. Step-3 already-promoted check updated to the new format + framed as the upward leg.
commands/soul-refresh.md (new) — downward sync. Gate → find promoted docs (tag=promoted) → parse @vN → compare to live knowledge version → directional refresh: stub auto-refreshes down, marker-only surfaces for pull-down vs re-promote-upward. Dangling target surfaced not deleted. Related-but-distinct staleness deferred.
context/session-guidance.md — one line noting /promote + /soul-refresh activate only with a joined knowledge system.

Design notes:

Hooks can't reach the broker, so the staleness check + refresh must be an agent-driven command, not a PostToolUse/recall hook. The plan called this out.
Reconciliation is strictly directional. /soul-refresh never two-way merges; local edits go up via /promote (which owns the gate + the cascade's update path), keeping the v0.5.0 plugin partition + the authority model intact.
No new bash → no new tests needed; full plugin regression still green (memory + knowledge).

Phase-0 prerequisites now all but A2 done. Next candidates: signal/batch triggers, or the dogfood promote of the plan itself. Plugin version bumps (memory + knowledge) still pending Fritz's commit.