Plan: Plugin Knowledge-Quality Enforcement

Status: active (opened 2026-06-01). Raises the demarkus-memory Claude Code plugin from "advisory knowledge system" to "enforced knowledge system," and aligns the per-project template to the proven demarkus-soul structure.

Owner: Fritz. Driver: agent.

Release strategy (Fritz 2026-06-01): stack ALL plugin work onto one branch (feat/plugin-publish-tag-gate, PR #171) and ship a single 0.4.0 release rather than churning many plugin versions. Review the code at each step, but no per-item version bump.

Problem

The plugin splits into two layers at very different maturity:

• Infra layer (binary install, server spawn, token mint, version pins, health checks): solid, deterministic, harness-executed.
• Knowledge-quality layer (context/session-guidance.md, the soul-memory skill, routing + tagging rules): 100% advisory prose executed by the model on best effort. Nothing verifies any of it happened.

Every load-bearing quality assumption — tag every publish, recall before answering, route content to the right file, journal significant sessions — is hope, not enforcement. The server "infers nothing." So quality degrades silently and invisibly: a tagless publish is accepted happily and becomes permanently invisible to mark_lookup. That is the single most damaging hole, because the entire recall half of the system depends on tags the agent must remember to set by hand while focused on content.

Strategy

Move enforcement off advisory prose and onto hooks, which the harness executes deterministically. Pure composition of existing surface — no core changes (consistent with the core-vs-overlay layering rule: the server stays permissive; the agent-driven client gets the guardrail).

Severity is configurable but the check always runs — this is a strictness level, not an opt-in capability (no "validation off" deployment exists):

• warn (default) — PostToolUse injects a system-reminder after a tagless publish, nudging a re-publish with tags. Non-blocking.
• block — PreToolUse denies a tagless publish until tags are added.
• ask — PreToolUse escalates to the user.

Hook mechanics (verified against code.claude.com/docs/en/hooks)

• PreToolUse: hookSpecificOutput.permissionDecision in allow|deny|ask|defer + permissionDecisionReason. Carries block/ask.
• PostToolUse: hookSpecificOutput.additionalContext injects a system-reminder the model sees next turn. Carries warn. (Plain stdout is debug-only, not model-visible.)
• Stop: only top-level {"decision":"block","reason":...} surfaces anything (no confirmed additionalContext). So a Stop nudge necessarily blocks one extra turn. Input carries session_id, transcript_path, stop_hook_active; loop-guard on stop_hook_active plus a per-session sentinel.
• Matchers are JS regex against the full mcp__server__tool name. The publish gate uses a broad mcp__.*__mark_publish matcher and scopes precisely in-script (local soul + registered knowledge systems only). Stop takes no matcher.
• One dispatcher script handles both publish events; branches on hook_event_name, reads STRICTNESS. Zero runtime dependencies — payloads parsed by pure-awk character-level JSON scanners (no jq, no python; awk is already the engine behind json_escape). A naive grep would false-match the arbitrary body value, so the scanner tracks string boundaries + the object-key path and reads only the exact fields it needs. Fails open — any parse hiccup defers, never blocks.

Work items

1. Publish tag/importance gate — DONE 2026-06-01 (PR #171)

hooks/publish-gate.sh (one dispatcher on both PreToolUse + PostToolUse) + matcher wiring in plugin.json. Tagless publish (tool_input.metadata.tags absent/empty/whitespace, or a non-string tags value) or importance outside [0,1] → warn/block/ask per strictness. Strictness read by configured_strictness in lib.sh: DEMARKUS_MEMORY_STRICTNESS env override → ~/.demarkus/plugin-memory.strictness file → warn default (kept in its own file, orthogonal to plugin-memory.conf, so setup.sh rewrites never clobber it). Parser is the pure-awk publish_metadata_check in lib.sh. Pins bumped SERVER 0.17.13→0.17.14 (client/tools already latest). Plugin version 0.3.0→0.4.0.

CodeRabbit review surfaced four real correctness holes in the awk parser, all fixed + regression-tested:

• escaped-whitespace bypass — {"tags":"\n"} was stored raw (backslash+n) and passed; added a pure-awk json_unescape (decodes \n \t \r \b \f \/ \" \\ and \uXXXX; whitespace codepoints → space, others → non-space marker) applied before trim/range checks.
• non-string tags bypass — {"tags":false|null|0} and array/object values passed; recordValue now tracks whether the value came from a JSON string (tagsStr) and tags_ok requires it.
• exponent importance — 1e-1 was wrongly rejected; regex now allows ([eE][+-]?[0-9]+)?.
• escaped-whitespace + array/object test coverage added. Publish suite now 22 cases, green.

Follow-up noted: the plugin's shell tests (tests/*.sh) are not run by any CI workflow today — knowledge-join_test.sh is manual too. Wiring them into CI is a separate, small task (touches .github/workflows/, mind the YAML ${{ }}-in-comments rule).

2. Relocate decaying guidance to the moment of action — DONE 2026-06-01 (PR #171)

session-guidance.md tagging block tightened: the gate now carries the tagging rule at write time, so the startup prose states it tersely, points at the gate, and makes the enforced-vs-advisory split explicit. (Reconciled in item 3 to note journaling now has a soft session-end backstop; in item 6 to point routing at the canonical template.)

3. Session-end journal nudge (Stop hook, guarded) — DONE 2026-06-01 (PR #171)

hooks/session-journal-nudge.sh (Stop hook, no matcher). Nudges once, at session end, when the session changed files (Edit/Write/NotebookEdit tool_use in the transcript — a low-false-positive "real work" signal) but recorded nothing to any demarkus memory store (no mark_publish/mark_append via MCP attribution or tool name). Since a Stop hook can only surface a message by blocking, it emits {"decision":"block","reason":...} once with an explicit "if it's routine, just stop" out. Two loop guards: stop_hook_active==true (also tolerates a quoted "true") early-exits, and a per-session sentinel fires at most once per session. New parser stop_hook_fields in lib.sh (pure awk). Tests: tests/session-journal-nudge_test.sh, 11 cases.

Open question for review: the blocking Stop nudge forces one extra turn per qualifying session. Acceptable + bounded (once per session, easy out), but if it proves annoying, add a disable knob (e.g. DEMARKUS_MEMORY_JOURNAL_NUDGE=off / strictness file) — deferred until there's signal it's needed.

4. Recall-before-answering (deferred until 1-3 land)

Hardest, most false-positive-prone. Good capture is the precondition for good recall — fix tags first. Cheap version: UserPromptSubmit pattern-match ("did we / what did / last time / decide") → one-line "check the soul" nudge.

5. Catalog hygiene tooling (/soul-doctor)

Surfaces existing rot: orphan docs (no inbound links, not in any index), broken [[links]], duplicate content, stale index entries, ADR numbering collisions. Built on mark_backlinks / mark_graph. Tooling, not enforcement.

6. Align local per-project template to the proven demarkus-soul structure — DONE 2026-06-01 (PR #171)