demarkus-soul journal — 2026-06-01

Plugin knowledge-quality enforcement — opened plan, shipped item 1

Hashed out how the demarkus-memory Claude Code plugin can enforce a high-quality knowledge system rather than merely advise one. Core diagnosis: the infra layer is solid and deterministic, but the entire knowledge-quality layer (session-guidance, the soul-memory skill, tagging/routing rules) is advisory prose the model executes on best effort — nothing verifies it. The single most damaging hole: a tagless mark_publish is accepted silently by the server and becomes permanently invisible to mark_lookup, so the whole recall half rots invisibly.

Wrote the plan to /plans/plugin-knowledge-quality.md (7 items) and indexed it under Active Plans.

Item 1 implemented (pending Fritz commit): a publish tag-gate.

• hooks/publish-gate.sh — one dispatcher wired on both PreToolUse and PostToolUse for the plugin's own mark_publish (matcher mcp__.*demarkus-memory__mark_publish). Tagless publish (or importance outside [0,1]) → warn (default, PostToolUse additionalContext nudge) / block (PreToolUse deny) / ask (PreToolUse ask).
• Strictness via configured_strictness in lib.sh: env DEMARKUS_MEMORY_STRICTNESS → ~/.demarkus/plugin-memory.strictness file → warn. Kept in its own file so setup.sh conf rewrites never clobber it. Always-on check, severity-only knob (not an opt-in capability).
• tests/publish-gate_test.sh, 14 cases, all green; knowledge-join_test.sh still 11/11.
• Pins SERVER 0.17.13→0.17.14; plugin 0.3.0→0.4.0; session-guidance notes the gate.

Two correctness lessons worth keeping:

1. The python3 fallback I first wrote used python3 - <<EOF, which makes Python read the program from stdin and consume the payload — sys.stdin is then empty and the gate always fails open. Caught it because the isolated parser test returned the fail-open tuple for every case. (Then dropped python entirely — see #2.)
2. Fritz: no python, no jq, no external deps that may not be installed. Rewrote the parser as a pure-awk character-level JSON scanner (awk is already the engine behind json_escape). It tracks string boundaries (honoring \ escapes) and the object-key path, so an arbitrary body value containing literal "tags":"DECOY" and stray braces is correctly skipped — verified on stock BSD /usr/bin/awk and pinned by a decoy-body regression test.

Design decisions for later items also locked: per-project template aligns to the proven demarkus-soul structure (add debugging.md, guidelines.md, maintained per-project index.md, plans/ lifecycle); knowledge systems get a guaranteed root hub world holding the global template + policy at mark://root/.well-known/demarkus/, with the agent acting as courier to mirror declared strictness into local config the credential-less hook can read.

Pre-existing gap noted: the plugin's shell tests aren't run by any CI workflow.

Plugin knowledge-quality enforcement — MERGED to main (v0.4.0)

PR #171 merged. The demarkus-memory Claude Code plugin moves from advisory to enforced, all seven planned items shipped in one stacked PR / single 0.4.0 release:

1. Publish tag/importance gate (warn/block/ask) — PreToolUse + PostToolUse
2. Guidance relocated to moment-of-action
3. Session-end journal nudge — Stop hook
4. Recall nudge — UserPromptSubmit hook
5. /soul-doctor read-only hygiene audit
6. Canonical per-project template seeded as /project-template.md
7. Knowledge-system gating + per-system strictness & require_tags (literal axis match), with the live root policy/template on knowledge.demarkus.io

Hook surface: SessionStart, PreToolUse, PostToolUse, Stop, UserPromptSubmit. Tests: 68 cases across 6 suites, pure awk/bash, zero runtime deps.

CodeRabbit review was substantial and caught several real holes the local tests hadn't: the escaped-whitespace + non-string + array/object tag bypasses, exponent importance, the regex-injection and glob-expansion in axis matching, and seed_doc aborting set -e callers. All fixed + regression-tested. Lesson reinforced: an adversarial reviewer on pure-shell JSON/΄token handling earns its keep — the bypasses were exactly the "unquoted/raw" class of shell bug.

Also slimmed the demarkus CLAUDE.md (~⅓ size): dropped the generic memory mechanics the plugin now owns, kept the project preflight, working-style rules, test workflow, and the corrected flat demarkus-soul layout.

Tail (not blocking, not started): wire the plugin tests/*.sh into CI (they're still manual); optional disable knobs for the journal + recall nudges if they prove noisy.