Fixes#152. Phase 3d step 3 instructed the LLM to "merge with existing
fingerprints (keep unchanged files as-is)" but the prose was vague
enough that the LLM-written script frequently wrote only the freshly
re-analyzed batch entries to fingerprints.json, discarding every other
file's fingerprint. The next auto-update saw N-batch_size files with
no stored fingerprint → classified as STRUCTURAL → exceeded the 30-file
threshold → FULL_UPDATE permanently, burning hundreds of thousands of
tokens on every subsequent commit.
Replace the four-bullet description with an explicit LOAD-PATCH-SAVE
script template:
1. LOAD ALL existing entries from fingerprints.json (never skip).
2. PATCH or REMOVE each path in filesToReanalyze (inline deletion
handling so the spec doesn't need a separate deletedFiles list).
3. GUARD: if the file existed and was non-empty but loaded as {},
abort the write — silent load failure would otherwise clobber
every fingerprint.
4. SAVE the full dict back.
The reporter's dry-run showed this restores 81/97 files to COSMETIC
classification on their project (zero LLM tokens) instead of all 97
incorrectly forced into STRUCTURAL.
Note: a related ordering bug exists in skills/understand/SKILL.md
Phase 7 (meta.json written before fingerprints.json — silent failure
in step 2.5 leaves stale fingerprints). That's a separate fix in a
different file and is intentionally not bundled here.
Fixes#153. Phase 0 step 7 filters changed files to source extensions
only and never reads `.understandignore`, so files in user-excluded
paths (migrations, vendored code, tests) count as structural changes
and can spuriously escalate the action to FULL_UPDATE. The reporter
saw 50 → 38 structural files after applying their ignore patterns
(below the 30-file FULL_UPDATE threshold, ARCHITECTURE_UPDATE would
have sufficed).
Add step 9 that delegates to `createIgnoreFilter` from
`@understand-anything/core` via $CLAUDE_PLUGIN_ROOT. Same code path
as /understand's project-scanner Step 2.5, so the auto-update honors
the exact same patterns (hardcoded defaults + user .understandignore
files at both standard locations + `!` negation semantics).
If $CLAUDE_PLUGIN_ROOT can't be resolved, fail loud rather than
silently skipping — a silent skip reproduces the original bug.
Hook echo commands referenced \${PLUGIN_DIR}, which Claude Code does not
inject into hook commands. The documented variable is \${CLAUDE_PLUGIN_ROOT}
(used elsewhere in skills/understand/SKILL.md and friends). Also switched
the surrounding single quotes to double quotes so the variable actually
expands at runtime instead of being passed literally.
Without this fix, the auto-update hook silently sent Claude a non-existent
file path, so the knowledge graph never incrementally updated even when
autoUpdate: true was configured.
Builds on the direction identified in #96; closes#96.
Co-Authored-By: xiaolai <lixiaolai@gmail.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
echo interprets escape sequences and flags (e.g. -e, -n) in some
shells, which can corrupt or truncate the hook event JSON before it
reaches grep. printf '%s' passes the value as a plain string with
no interpretation, eliminating any risk of mishandled special chars.
Co-Authored-By: Claude Code <noreply@anthropic.com>
Delete the 5 prompt template files from skills/understand/ now that
they live in agents/. Update auto-update-prompt.md hook to reference
agent definitions instead of deleted prompt files.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The PostToolUse hook used `<<<` (bash herestring) which fails when
Claude Code runs hooks under `/bin/sh`. Replace with `echo | grep`
for POSIX compatibility.
- C1: use [...array].sort() to avoid mutating fingerprint inputs
- C2: replace echo piping with here-string to prevent shell injection in hooks
- M1/M2: add allKnownFiles param to classifyUpdate for correct directory baseline
- M3: add try-catch to loadFingerprints for corrupted JSON resilience
- M5: add hasStructuralAnalysis flag for conservative no-tree-sitter classification
- m3: replace fragile sed with node JSON.parse in SessionStart hook
- Add 7 new tests covering all fixes
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Introduced hooks in `hooks.json` for PostToolUse and SessionStart events to prompt users about knowledge graph updates based on commit and session changes.
- Implemented `change-classifier.ts` to classify updates based on structural changes, including SKIP, PARTIAL_UPDATE, ARCHITECTURE_UPDATE, and FULL_UPDATE actions.
- Added comprehensive tests for change classification in `change-classifier.test.ts` to ensure correct behavior across various scenarios.
- Created `fingerprint.ts` to manage file fingerprints, including content hashing, structural analysis, and comparison of fingerprints to detect changes.
- Developed tests for fingerprint extraction and comparison in `fingerprint.test.ts` to validate functionality and ensure accurate change detection.
Lum1104
claude[bot]andClaude Code
Pablo Speciale
Aditya