# 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](/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.