fix(kb): whole-product audit fixes (0.24.16)#29
Merged
Conversation
- Persona: USER.md (priority-1 human rules) now bypasses the SessionStart byte budget via a force arg — a degraded multi-banner state can no longer silently drop the human's Never/Always rules. (+ functional test) - Maintainer Phase 4c: handle binary/blob items (the .md body is a placeholder; bytes are in the sibling blob) — author a sources node pointing at the original, never fabricate; + reserve drain budget so a large 4b backfill can't starve the inbox. - Maintainer doc drift: 6-phase → 8-phase, drop the non-existent 'Phase 6', add ai-block/raw-drain lines to the report template. - README: document /second-brain:capture + /second-brain:maintain (were missing); correct the SB_MAINTAINER_* docs (suggestion banner, not auto-dispatch); add the capture→inbox→drain loop to the memory-flow. The SessionStart maintenance banner now points at /second-brain:maintain (live) + /second-brain:dream (staged). - Dead code: removed migrate-to-1.0.0.sh + migrate-to-1.3.0.sh (zero live refs). Kept migrate-to-1.2.0.sh (verify.sh hint) + migrate-to-2.8.0.sh (live test) — the audit's 'all 4 dead' was wrong for those two. New guards: test-session-load-usermd-budget.sh, test-readme-skills.sh; +binary/phase assertions in test-maintainer-raw-drain.sh. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Cap the forced USER.md at 6000B (deep-review low finding: an uncapped forced USER.md could breach the ~10K hook-output ceiling). Lockstep version bump + migration registry row. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Hardening/documentation pass for the second-brain knowledge-base workflows (release 0.24.16), focused on keeping user-facing session context reliable (USER.md inclusion), aligning maintainer docs/tests with the current 8-phase model (incl. raw-inbox binary handling guidance), and removing dead migration scripts while keeping version metadata in sync.
Changes:
- Ensure USER.md is appended with a
forcebypass (but capped) so global Never/Always rules are not dropped under byte-budget pressure. - Update maintainer agent documentation and add/extend shell guards to prevent drift (README skills table, Phase 4c binary/blob handling, phase count).
- Remove unreferenced legacy migration scripts and bump plugin/marketplace versions to 0.24.16.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| tests/test-session-load-usermd-budget.sh | New guard verifying USER.md append is forced and capped; functional check of sb_append force behavior. |
| tests/test-readme-skills.sh | New guard ensuring /second-brain:capture and /second-brain:maintain remain documented in README. |
| tests/test-maintainer-raw-drain.sh | Adds assertions for binary/blob handling guidance and removes stale “Phase 6” references. |
| skills/upgrade/SKILL.md | Adds 0.24.16 migration-row documentation summarizing the audit fixes and removals. |
| scripts/session-load.sh | Implements sb_append(..., force) support and updates maintainer suggestion banner + USER.md capping. |
| scripts/migrate-to-1.3.0.sh | Removes dead migration script. |
| scripts/migrate-to-1.0.0.sh | Removes dead migration script. |
| README.md | Documents capture/maintain skills, corrects maintainer env var semantics, and clarifies capture→inbox→drain flow. |
| agents/knowledge-maintainer.md | Updates to 8-phase model; adds explicit binary/blob-item handling guidance and reporting lines. |
| .claude-plugin/plugin.json | Version bump to 0.24.16. |
| .claude-plugin/marketplace.json | Version bump to 0.24.16. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| TMP=$(mktemp); awk '/^sb_append\(\) \{/{f=1} f{print} f&&/^\}$/{exit}' "$SL" > "$TMP" | ||
| sb_log_error(){ :; } # no-op stub for the extracted function | ||
| OUT=$(mktemp); OUTPUT_FILE="$OUT"; BYTE_BUDGET=100; USED=95 | ||
| BIG="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # 49 chars → 95+49 > 100 |
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.
Hardening pass surfaced by a 5-dimension whole-product validation of the shipped SP-0..SP-5 consolidation vision (focus, functional completeness, dead code, backward-compat, maintainer coverage, persona). No new feature — all changes are prompt/doc/bash; additive (behaviour unchanged with no new on-disk state).
Fixes
session-load.sh):sb_appendgains aforcearg so the human's priority-1 global Never/Always rules always land even after conditional banners spend the byte budget; capped at 6000B so a huge USER.md can't breach Claude Code's ~10K hook-output ceiling.knowledge-maintainer.md): a captured PDF/image has only a placeholder.mdbody (bytes live in the sibling blob) — the drain now authors asourcesnode pointing at the original instead of fabricating content; + a reserve-a-slice note so a large Phase 4b backfill can't starve the inbox./second-brain:maintain(live) and/second-brain:dream(staged) — previously only/dream, despite SP-5 shipping the real maintainer skill./second-brain:capture+/second-brain:maintain(were missing); corrects theSB_MAINTAINER_*docs (a suggestion banner, not auto-dispatch — neutered in 0.21.0); adds the capture→inbox→drain memory-flow.migrate-to-1.0.0.sh+migrate-to-1.3.0.sh(zero live refs). Kept1.2.0(verify.sh hint) +2.8.0(live test) — the audit's "all 4 dead" was wrong for those two (caught by verify-before-delete).Verification
--base main): Unit-A had one low finding (uncapped forced USER.md) — fixed with the 6000B cap; Unit-B + history pass clean, no regressions.test-session-load-usermd-budget.sh,test-readme-skills.sh, + binary/phase assertions intest-maintainer-raw-drain.sh.🤖 Generated with Claude Code