Kjell Tore Guttormsen
7bb254780a
Fase 4 Items 2+3 (CC 2.1.114→181 gap-review). New orchestrated scanner `skill-listing-scanner.mjs` (prefix SKL) flags every active skill whose description exceeds the verified 1,536-char listing cap (CC 2.1.105, changelog L1502). Past the cap, Claude Code silently truncates the description the model reads to route skill invocation — dropping the trigger phrases at the tail. HOME-scoped over all user + plugin skills via enumerateSkills (COL is the model). - CA-SKL-001 (medium): description > 1,536 chars. Remediation folds in Item 2(b) — recommends disableBundledSkills + skillOverrides + trimming (designvalg A: no standalone GAP-check, which would fire for nearly everyone). - Designvalg B: v1 ships the verified cap ONLY. The aggregate 2%-of-context listing budget is deferred — it needs a context-window assumption that would turn a verified fact into a guess (would carry a CALIBRATION_NOTE if added). - Choice C: recognize the skillOverrides settings key (CC 2.1.129) in KNOWN_KEYS. Left OUT of TYPE_CHECKS — the value is a per-skill object (off/user-invocable-only/name-only), not a string; a 'string' check (as the plan sketched) would create a NEW false positive. Verify-first deviation. Registration: scan-orchestrator (13th scanner), humanizer (SKL → 'Wasted tokens' + static/_default translations), scoring SCANNER_AREA_MAP (→ Token Efficiency; no 11th area), README badge 12→13, CLAUDE.md (finding-id + test-count), docs/scanner-internals.md, gap-matrix + plan status notes. Snapshots reseeded hermetically (SEED_SNAPSHOT/UPDATE_SNAPSHOT): SKL entry with 0 findings in empty HOME, scanners_ok 11→12, claudeMdEstimatedTokens bump from the CLAUDE.md edits flowing through the cascade. Contamination grep clean. Suite 868/868 (856 baseline + 11 SKL + 1 skillOverrides). RED→GREEN logged per cycle. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ter3E2JSi1Khgmuf2kady8
6.4 KiB
6.4 KiB
Config-Audit — Scanner internals
Detailed scanner inventory, lib modules, action engines, knowledge base. Imported from CLAUDE.md via pointer.
Deterministic Scanners
Node.js scanners (zero external dependencies), run via node scanners/scan-orchestrator.mjs <path>.
Posture CLI: node scanners/posture.mjs <path> [--json] [--global] [--full-machine] [--output-file path].
Scanner CLI: node scanners/scan-orchestrator.mjs <path> [--global] [--full-machine] [--no-suppress].
| Scanner | Prefix | Detects |
|---|---|---|
claude-md-linter.mjs |
CML | Structure, length, sections, @imports, duplicates, TODOs |
settings-validator.mjs |
SET | Schema, unknown/deprecated keys, type mismatches, permissions |
hook-validator.mjs |
HKV | Format, script existence, event validity, timeouts |
rules-validator.mjs |
RUL | Glob matching, orphan rules, deprecated fields, unscoped rules |
mcp-config-validator.mjs |
MCP | Server types, env vars, unknown fields |
import-resolver.mjs |
IMP | Broken @imports, circular refs, deep chains, tilde paths |
conflict-detector.mjs |
CNF | Settings conflicts, permission contradictions, hook duplicates |
feature-gap-scanner.mjs |
GAP | 25 feature checks across 4 tiers — shown as opportunities, not grades |
token-hotspots.mjs |
TOK | Cache-breaking volatile content, redundant tool permissions, deep import chains, oversized cascade, bloated SKILL.md descriptions, MCP tool-schema budget (prompt-cache patterns) |
cache-prefix-scanner.mjs |
CPS | Volatile content in lines 31–150 of CLAUDE.md cascade (beyond Pattern A's top-30 window) |
disabled-in-schema-scanner.mjs |
DIS | Tools listed in BOTH permissions.deny AND permissions.allow — deny wins, allow entries are dead config |
collision-scanner.mjs |
COL | Cross-plugin skill name collisions (low); user-vs-plugin overlaps (medium); details.namespaces payload |
skill-listing-scanner.mjs |
SKL | Active skill descriptions over the verified 1,536-char listing cap (CC 2.1.105) → silently truncated in the model's skill listing (medium). HOME-scoped (all user + plugin skills). Remediation surfaces disableBundledSkills / skillOverrides. Distinct lens from TOK pattern F (project-local 500-char bloat heuristic) |
Scanner Lib (scanners/lib/)
| Module | Purpose |
|---|---|
severity.mjs |
Severity constants, risk scoring, verdict logic, WEIGHTS named export (v5 F3) |
output.mjs |
Finding objects (CA-XXX-NNN format), scanner results, envelope, optional details payload (v5 N6) |
file-discovery.mjs |
Config file discovery: single-path, multi-path (discoverConfigFilesMulti), full-machine (discoverFullMachinePaths) |
yaml-parser.mjs |
Frontmatter parsing, JSON parsing, @import/section extraction |
string-utils.mjs |
Line counting, truncation, similarity, key extraction |
scoring.mjs |
Severity-weighted scoreByArea (v5 F3), health scorecard, dedup-by-area (v5 N3), scoringVersion: 'v5' |
backup.mjs |
Backup creation, manifest parsing, checksum verification |
diff-engine.mjs |
Drift diffing: diffEnvelopes(), formatDiffReport() |
baseline.mjs |
Baseline save/load/list/delete for drift detection |
report-generator.mjs |
Unified markdown reports: posture, drift, plugin health |
suppression.mjs |
.config-audit-ignore parsing, finding suppression, audit trail |
active-config-reader.mjs |
Read-only inventory: readActiveConfig(), detectGitRoot(), walkClaudeMdCascade(), readClaudeJsonProjectSlice() (longest-prefix match), enumeratePlugins(), enumerateSkills(), readActiveHooks(), readActiveMcpServers() (with cache → package.json tool-count fallback), estimateTokens() (v5: 'mcp' kind = 500 + toolCount × 200) |
tokenizer-api.mjs |
Anthropic count_tokens wrapper for --accurate-tokens (v5 N5); 5s AbortController timeout, exponential 429 backoff, key masking |
humanizer.mjs |
Plain-language output translator (v5.1.0): humanizeFinding, humanizeFindings, humanizeEnvelope, computeRelevanceContext. Pure functions; never mutate inputs. Adds userImpactCategory, userActionLanguage, relevanceContext fields and replaces title/description/recommendation when a translation exists. Bypassed by --raw and --json paths. |
humanizer-data.mjs |
TRANSLATIONS table for 14 scanner prefixes (CML/SET/HKV/RUL/MCP/IMP/CNF/COL/TOK/CPS/DIS/GAP/PLH/SKL). Three-step lookup: exact title → regex pattern → _default → fall through to original |
Action Engines (scanners/)
| Module | Purpose |
|---|---|
fix-engine.mjs |
planFixes(), applyFixes(), verifyFixes() — 9 fix types |
rollback-engine.mjs |
listBackups(), restoreBackup(), deleteBackup() |
fix-cli.mjs |
CLI: node fix-cli.mjs <path> [--apply] [--json] [--global] |
drift-cli.mjs |
CLI: node drift-cli.mjs <path> [--save] [--baseline name] [--json] |
whats-active.mjs |
CLI: node whats-active.mjs <path> [--json] [--verbose] [--suggest-disables] — read-only active-config inventory |
token-hotspots-cli.mjs |
CLI: node token-hotspots-cli.mjs <path> [--json] [--global] [--output-file path] [--accurate-tokens] [--with-telemetry-recipe] — prompt-cache token hotspots ranking with optional API calibration |
manifest.mjs |
CLI: node manifest.mjs <path> [--json] — ranked system-prompt token-source table (v5 N2) |
Standalone Scanner
| Module | Prefix | Purpose |
|---|---|---|
plugin-health-scanner.mjs |
PLH | Plugin structure, frontmatter, cross-plugin conflicts (runs independently) |
self-audit.mjs |
— | Runs all scanners + plugin health on this plugin itself |
Knowledge Base (knowledge/)
| File | Content |
|---|---|
claude-code-capabilities.md |
Feature register: 18 config surfaces, Anthropic guidance, relevance table |
configuration-best-practices.md |
Per-layer best practices (v5: cache-stability guidance replaces Sonnet-era 200-line rule) |
anti-patterns.md |
Common mistakes mapped to scanner IDs |
hook-events-reference.md |
All 26 hook events with details |
feature-evolution.md |
Feature timeline for staleness detection |
gap-closure-templates.md |
Config-specific templates for closing gaps |
prompt-cache-patterns.md |
Token-cost dynamics (prompt-cache patterns) — patterns powering the TOK scanner |
cache-telemetry-recipe.md |
Manual jq recipe for verifying prompt-cache hit rate from session transcripts (v5 M7) |