feat(kb): surface cleanup + 3-OS verification (SP-5)#27
Merged
Conversation
Four audit-fixes: create /second-brain:maintain skill (dispatches the maintainer agent), fix doc-sources.filterIgnored Windows path-sep, add agent allowed-tools guard, fix stale doubt example. Cross-OS sweep of SP-1..SP-4 came back clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…5 A) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…Windows) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…SP-5 C) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…s.md (SP-5 D) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The plugin convention is second-brain:<agent> (per doubt/code-review-deep); the bare 'knowledge-maintainer' risked a dispatch-resolution failure. Test now asserts the namespaced form. Also documented the agent-guard's known blind spots. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR completes SP-5 “surface cleanup” by adding an explicit user entry point for the knowledge maintainer, improving Windows path-separator handling in doc-sources junk filtering, and adding preventive test guards + documentation updates. It also bumps the plugin version to 0.24.14 and records the migration note.
Changes:
- Add a new user-invocable
/second-brain:maintainskill that dispatches the namespacedsecond-brain:knowledge-maintaineragent for an explicit full run (incl. Phase 4b/4c). - Fix
doc-sources.filterIgnoredto split path segments on both/and\, plus add a Vitest regression test (and rebuild dist artifacts). - Add a new guard test to ensure agents declare
tools:grants matchingnode/ plugin-bashinvocations; update a stale/second-brain:doubtruntime example.
Reviewed changes
Copilot reviewed 11 out of 19 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| tests/test-maintain-skill.sh | New guard ensuring the maintain skill exists, is user-invocable, and dispatches the namespaced maintainer agent. |
| tests/test-agent-allowed-tools.sh | New guard ensuring agents that invoke node / plugin bash scripts declare the matching tools: grants. |
| skills/upgrade/SKILL.md | Adds the 0.24.14 migration row describing SP-5 changes. |
| skills/maintain/SKILL.md | New /second-brain:maintain skill dispatching second-brain:knowledge-maintainer for explicit full maintenance (4b/4c included). |
| skills/doubt/SKILL.md | Updates a runtime-state example to reference a current on-disk file (persona-signals.jsonl). |
| mcp/src/tools/doc-sources.ts | Fixes junk-dir filtering to split relative paths on both OS separators. |
| mcp/src/tools/doc-sources.test.ts | Adds Vitest coverage for filterIgnored junk-dir handling and the cross-OS split regex. |
| mcp/dist/tools/raw-scan-cli.bundle.js | Rebuilt dist bundle reflecting the updated filterIgnored behavior. |
| mcp/dist/tools/doc-sources.js | Rebuilt dist output reflecting the updated filterIgnored behavior. |
| mcp/dist/tools/doc-sources-cli.bundle.js | Rebuilt dist bundle reflecting the updated filterIgnored behavior. |
| mcp/dist/tools/doc-sources.test.js | Built dist test output for the new doc-sources test. |
| mcp/dist/tools/doc-sources.test.js.map | Source map for the built dist test output. |
| mcp/dist/tools/doc-sources.test.d.ts | Built dist typings output for the new doc-sources test. |
| mcp/dist/tools/doc-sources.test.d.ts.map | Source map for the built dist typings output. |
| mcp/dist/tools/doc-sources.js.map | Updated source map for the rebuilt doc-sources output. |
| docs/specs/2026-06-04-surface-cleanup-design.md | New SP-5 design/spec document. |
| docs/plans/2026-06-04-surface-cleanup.md | New SP-5 implementation plan document. |
| .claude-plugin/plugin.json | Bumps plugin version to 0.24.14. |
| .claude-plugin/marketplace.json | Bumps marketplace version to 0.24.14. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| [ -f "$S" ] || fail "skills/maintain/SKILL.md missing" | ||
| grep -q '^name: maintain$' "$S" || fail "name is not 'maintain'" | ||
| grep -q '^user-invocable: true$' "$S" || fail "not user-invocable" | ||
| grep -qE '^allowed-tools:.*\bAgent\b' "$S" || fail "allowed-tools must include Agent (to dispatch the agent)" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
SP-5 — Surface Cleanup + 3-OS Verification (final sub-project)
Four audit-fixes surfaced by a discovery sweep. The cross-OS portability of the SP-1..SP-4 scripts came back clean (the conventions held:
awk -v,stat -c||-f, nomapfile/grep -P). Spec:docs/specs/2026-06-04-surface-cleanup-design.md.Fixes
/second-brain:maintainskill. The maintainer had no user-facing entry point —/second-brain:maintainis referenced throughout (upgrade migrations, the agent's Phase 4b/4c boundary) butskills/maintain/didn't exist. The new thin skill dispatches theknowledge-maintaineragent (namespacedsecond-brain:knowledge-maintainer) for an explicit full run (incl. the bulk-authoring 4b/4c that auto-runs skip). Realizes the vision's second main skill.doc-sources.filterIgnoredWindows path-sep.relative().split('/')→.split(/[\\/]+/)so junk-dir filtering works whenpath.relativeemits backslashes (affected doc-sources + the SP-3 setup-scan on Windows). Same class SP-3'sisHighSignalfixed.test-agent-allowed-tools.sh. Agents had no allowed-tools guard (unlike skills), which is why the maintainer's missingBash(node *)shipped undetected. Preventive — passes now, fails if a future agent forgets a grant.doubtexample points at a real file (persona-signals.jsonl, not the removed legacylearnings.md).Deep-review gate (finding fixed before merge)
subagent_type: "knowledge-maintainer", but the plugin convention is namespaced (second-brain:<agent>) — a bare name risks a dispatch-resolution failure (the skill wouldn't work). Fixed tosecond-brain:knowledge-maintainer; the test now asserts the namespaced form. Unit + history passes otherwise clean.Notes
Plugin 0.24.13 → 0.24.14 + migration row.
🤖 Generated with Claude Code