feat(kb): maintainer raw-inbox drain (SP-4) — Phase 4c by Cain-Ish · Pull Request #26 · Cain-Ish/claude-code-plugin

Cain-Ish · 2026-06-04T10:05:27Z

SP-4 — Maintainer Raw-Inbox Drain (Phase 4c)

Closes the SP-2 → SP-3 → SP-4 pipeline: the knowledge-maintainer agent now turns unprocessed raw-inbox items (from /second-brain:capture + setup deep-scan) into wiki nodes. Spec: docs/specs/2026-06-04-maintainer-raw-drain-design.md.

What it does

Phase 4c (modeled on Phase 4b): deterministic work-list (raw-capture-cli pending) → author per item → knowledge_validate self-check → shared 50/run cap → explicit-invocation only (auto-dispatched runs skip it).
Conservative + provenance: per item — target_node set → update it; else strong knowledge_search match → update; else create a typed node (8 categories, authored only from the material — never invented). Never auto-discards — low-value items left unprocessed and reported for manual prune. Node gets a ## Sources line; the raw item is marked processed with a target_node back-ref (kept as the audit trail).
Plumbing: new markProcessed (raw-inbox.ts, reuses the SP-2 isSafeId/fmValue guards) + raw-capture-cli pending (TSV) and process <id> --node <slug>.

Deep-review gate (findings fixed before merge)

High: granted the agent Bash(node *) — Phase 4c and pre-existing Phase 4b shell out to node CLIs; without the grant the process call would prompt/deny → items stay unprocessed → re-drained duplicate nodes. Fixes a latent 4b gap too.
Medium: pending now tab-sanitizes target_node (fmValue strips CR/LF, not tabs) so a tab can't shift the TSV columns.
Medium: tightened a hollow test guard (the ## Sources grep matched the pre-existing ### Sources ENRICH heading). Added tests for markProcessed's update-branch (no duplicate target_node) + the TSV tab-safety.
History + architectural passes: no blockers (the raw→node back-ref always survives in the raw frontmatter, so provenance is never lost; phase ordering means 4c only uses leftover budget).

Notes

No MCP server tool change, no kb-schema change (processed already valid; the 8 categories already exist; server stays 2.6.4).
Additive: Phase 4c only fires on an explicit maintain with a non-empty inbox. Full suite 82 pass / 0 fail / 1 known skip.

Plugin 0.24.12 → 0.24.13 + migration row.

🤖 Generated with Claude Code

Conservative create/update/never-auto-discard drain of the raw inbox into wiki nodes, modeled on Phase 4b (explicit-only, 50/run cap, no invented content). Bidirectional provenance (node ## Sources line + raw target_node back-ref). SP-2 CLI gains pending + process; new markProcessed in raw-inbox.ts. No server/schema change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…k-ref (SP-4 Task 1) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- High: grant Bash(node *) to the maintainer agent — Phase 4c (and pre-existing Phase 4b) shell out to node CLIs; without the grant the process call would prompt/deny, leaving items unprocessed → re-drained → duplicate nodes. - pending now tab-sanitizes target_node (fmValue strips CR/LF, not tabs) so a tab can't shift the TSV columns and corrupt the work-list. - Strengthen the agent guard: tightened the '## Sources' grep (was satisfied by the pre-existing '### Sources' ENRICH heading), pinned 'process <id> --node <slug>', and assert the Bash(node *) grant. New tests for markProcessed's update-branch (no duplicate target_node) and the TSV tab-safety. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…n row Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Adds SP-4 Phase 4c “raw-inbox drain” support to close the SP-2 → SP-3 → SP-4 pipeline: the knowledge-maintainer agent can now turn unprocessed raw-inbox captures into wiki nodes via a deterministic CLI work-list + a processed/back-ref transition, with explicit-only execution and provenance.

Changes:

Introduces raw-capture-cli pending (TSV work-list) and raw-capture-cli process (mark item processed + optional target_node back-ref).
Adds markProcessed() plumbing to raw-inbox (atomic rewrite) with new vitest + bash e2e coverage.
Wires Phase 4c into knowledge-maintainer prompt, bumps plugin version to 0.24.13, and adds an upgrade/migration row + design/plan docs.

Reviewed changes

Copilot reviewed 11 out of 20 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/test-raw-capture.sh	Adds e2e coverage for `pending` TSV output, `process` transition, and tab-sanitization.
tests/test-maintainer-raw-drain.sh	Adds a structural guard ensuring the maintainer prompt includes Phase 4c behavior and tool grants.
skills/upgrade/SKILL.md	Adds `0.24.13` migration row documenting the Phase 4c feature and operational notes.
mcp/src/tools/raw-inbox.ts	Adds `markProcessed()` to flip status → processed and optionally update/insert `target_node`.
mcp/src/tools/raw-inbox.test.ts	Adds vitest coverage for `markProcessed()` (status flip, back-ref, unsafe id, no-duplicate target_node).
mcp/src/tools/raw-capture-cli.ts	Adds `pending` and `process` CLI actions; sanitizes TSV cells to keep output machine-safe.
mcp/dist/tools/raw-inbox.test.js.map	Updates built artifact map for new `markProcessed` tests.
mcp/dist/tools/raw-inbox.test.js	Updates built artifact for new `markProcessed` tests.
mcp/dist/tools/raw-inbox.js.map	Updates built artifact map for `markProcessed` implementation.
mcp/dist/tools/raw-inbox.js	Updates built artifact for `markProcessed` implementation.
mcp/dist/tools/raw-inbox.d.ts.map	Updates built type map for new `markProcessed` export.
mcp/dist/tools/raw-inbox.d.ts	Updates built types to include `markProcessed` signature.
mcp/dist/tools/raw-capture-cli.js.map	Updates built artifact map for new CLI actions.
mcp/dist/tools/raw-capture-cli.js	Updates built artifact for new CLI actions.
mcp/dist/tools/raw-capture-cli.bundle.js	Updates bundled CLI used by skills/agents to include `pending`/`process` and `markProcessed`.
docs/specs/2026-06-04-maintainer-raw-drain-design.md	Adds the Phase 4c design spec (goals, contract, boundary, provenance).
docs/plans/2026-06-04-maintainer-raw-drain.md	Adds implementation plan and TDD steps for SP-4 Phase 4c.
agents/knowledge-maintainer.md	Grants `Bash(node *)`, adds Phase 4c instructions, and updates the auto-dispatch exception to skip 4b/4c.
.claude-plugin/plugin.json	Bumps plugin version `0.24.12` → `0.24.13`.
.claude-plugin/marketplace.json	Bumps marketplace version `0.24.12` → `0.24.13`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+  let next = /^status:[ \t]*.*$/m.test(content)
+    ? content.replace(/^status:[ \t]*.*$/m, 'status: processed')
+    : content.replace(/^---\r?\n/, '---\nstatus: processed\n');


+run process "$PID" --node my-node | grep -q "Processed $PID" || fail "process did not report"
+grep -q '^status: processed$' "$RAW/$PID.md" || fail "status not flipped to processed"
+grep -q '^target_node: my-node$' "$RAW/$PID.md" || fail "target_node back-ref not set"
+[ -z "$(run pending | grep "$PID" || true)" ] || fail "processed item still appears in pending"


+   - **Decide the target node:**
+     - `target_node` non-empty → **update** that wiki page (`Read` it in full first).
+     - else `knowledge_search` the gist / key terms → a top hit that is a *strong, same-topic* match →


Cain-Ish and others added 7 commits June 4, 2026 11:30

docs(plan): SP-4 maintainer raw-inbox drain implementation plan

5d05de9

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(kb): raw-inbox markProcessed — drain transition + provenance bac…

a1d89e5

…k-ref (SP-4 Task 1) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(kb): raw-capture-cli pending + process actions (SP-4 Task 2)

82566ae

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(kb): maintainer Phase 4c — raw-inbox drain (SP-4 Task 3)

b2c289a

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

chore(release): maintainer raw drain (SP-4) — bump 0.24.13 + migratio…

dcf48e9

…n row Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings June 4, 2026 10:05

Cain-Ish merged commit 7e0c820 into main Jun 4, 2026
1 check passed

Cain-Ish deleted the feat/sp4-maintainer-raw-drain branch June 4, 2026 10:05

Copilot started reviewing on behalf of Cain-Ish June 4, 2026 10:05 View session

Copilot AI reviewed Jun 4, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(kb): maintainer raw-inbox drain (SP-4) — Phase 4c#26

feat(kb): maintainer raw-inbox drain (SP-4) — Phase 4c#26
Cain-Ish merged 7 commits into
mainfrom
feat/sp4-maintainer-raw-drain

Cain-Ish commented Jun 4, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Cain-Ish commented Jun 4, 2026

SP-4 — Maintainer Raw-Inbox Drain (Phase 4c)

What it does

Deep-review gate (findings fixed before merge)

Notes

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants