From 2f52fcc751fa76d70b465aad3d3650d449e842b2 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Mon, 18 May 2026 12:04:02 +0200 Subject: [PATCH] chore: WIP marketplace doc adjustments across plugins Pre-trekexecute snapshot of in-progress CLAUDE.md/SKILL.md edits and extracted docs/ files. Captured as one commit so /trekexecute claude-design can run against a clean working tree. Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 144 +++----------------------------------- docs/humanizer.md | 52 ++++++++++++++ docs/scanner-internals.md | 76 ++++++++++++++++++++ 3 files changed, 137 insertions(+), 135 deletions(-) create mode 100644 docs/humanizer.md create mode 100644 docs/scanner-internals.md diff --git a/CLAUDE.md b/CLAUDE.md index d072f36..392c292 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -50,79 +50,6 @@ Analyzes and optimizes Claude Code configuration across three pillars: | verifier-agent | Verify results | sonnet | purple | Read, Glob, Grep | | feature-gap-agent | Context-aware feature recommendations | opus | green | Read, Glob, Grep, Write | -## Deterministic Scanners - -Node.js scanners (zero external dependencies), run via `node scanners/scan-orchestrator.mjs `. -Posture CLI: `node scanners/posture.mjs [--json] [--global] [--full-machine] [--output-file path]`. -Scanner CLI: `node scanners/scan-orchestrator.mjs [--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, trust levels, 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 (Opus 4.7 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 | - -### 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 13 scanner prefixes (CML/SET/HKV/RUL/MCP/IMP/CNF/COL/TOK/CPS/DIS/GAP/PLH). 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 [--apply] [--json] [--global]` | -| `drift-cli.mjs` | CLI: `node drift-cli.mjs [--save] [--baseline name] [--json]` | -| `whats-active.mjs` | CLI: `node whats-active.mjs [--json] [--verbose] [--suggest-disables]` — read-only active-config inventory | -| `token-hotspots-cli.mjs` | CLI: `node token-hotspots-cli.mjs [--json] [--global] [--output-file path] [--accurate-tokens] [--with-telemetry-recipe]` — Opus-4.7 token hotspots ranking with optional API calibration | -| `manifest.mjs` | CLI: `node manifest.mjs [--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: Opus 4.7 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 | -| `opus-4.7-patterns.md` | Token-cost dynamics for Opus 4.7 era — patterns powering the TOK scanner | -| `cache-telemetry-recipe.md` | Manual `jq` recipe for verifying prompt-cache hit rate from session transcripts (v5 M7) | - ## Hooks | Event | Script | Purpose | @@ -132,56 +59,20 @@ Scanner CLI: `node scanners/scan-orchestrator.mjs [--global] [--full-mach | SessionStart | `session-start.mjs` | Checks for active (unfinished) sessions | | Stop | `stop-session-reminder.mjs` | Reminds about current session phase | -## Plain-Language Output (v5.1.0) +## Reference docs (read on demand) -Default output of all 18 commands routes through `humanizeEnvelope` from `lib/humanizer.mjs`. Findings are decorated with three additive fields and may have title/description/recommendation replaced when a translation exists. +- **Scanner inventory, lib modules, action engines, knowledge base:** `docs/scanner-internals.md` +- **Plain-language output (v5.1.0), humanizer vocabularies, output modes:** `docs/humanizer.md` -### Output modes +## Plain-Language Output (v5.1.0) — summary -| Flag | Behavior | -|------|----------| -| (default, no flag) | Plain-language: humanizer applied, findings group by user-impact, titles lead with prose. Self-audit terminal render also humanized. | -| `--raw` | Byte-stable v5.0.0 verbatim — humanizer bypassed, technical IDs and severity-only labels. For tooling that scrapes stderr from v5.0.0. | -| `--json` | Unchanged from v5.0.0 — humanizer bypassed, byte-stable JSON envelope. Always preferred for programmatic consumption over `--raw`. | -| `--output-file ` | Writes raw v5.0.0-shape JSON (humanizer bypassed). Posture-specific. | +Default output of all 18 commands routes through `humanizeEnvelope` from `lib/humanizer.mjs`. Findings get three decorated fields: -`--raw` is threaded through every CLI: `posture.mjs`, `scan-orchestrator.mjs`, `token-hotspots-cli.mjs`, `manifest.mjs`, `whats-active.mjs`, `fix-cli.mjs`, `drift-cli.mjs`, `self-audit.mjs`. +- `userImpactCategory` — Configuration mistake / Conflict / Wasted tokens / Dead config / Missed opportunity +- `userActionLanguage` — Fix this now / Fix soon / Fix when convenient / Optional cleanup / FYI (derived from severity) +- `relevanceContext` — `affects-everyone` (default) / `affects-this-machine-only` (`*.local.*` files) / `test-fixture-no-impact` -### Vocabularies - -User-impact category (added to each finding as `userImpactCategory`, derived from scanner prefix): - -| Label | Scanners | -|-------|----------| -| Configuration mistake | CML, SET, HKV, RUL, MCP, IMP, PLH | -| Conflict | CNF, COL | -| Wasted tokens | TOK, CPS | -| Dead config | DIS | -| Missed opportunity | GAP | - -Action language (added to each finding as `userActionLanguage`, derived from severity): - -| Severity | Phrase | -|----------|--------| -| critical | Fix this now | -| high | Fix soon | -| medium | Fix when convenient | -| low | Optional cleanup | -| info | FYI | - -Relevance context (added to each finding as `relevanceContext`, computed from finding's file path): - -| Value | When | -|-------|------| -| `test-fixture-no-impact` | Path contains `/tests/fixtures/` or `/test/fixtures/` | -| `affects-this-machine-only` | Basename matches `*.local.*` (e.g., `settings.local.json`) | -| `affects-everyone` | Default — assumed shared/committed config | - -### Wave 5 lessons - -- Posture's stderr scorecard is rendered prose-side and is not part of the JSON envelope; `humanized.areas[].titleHumanized` referenced by command templates lives only in the prose render. -- Posture's `--output-file` writes raw v5.0.0-shape JSON because `posture.mjs` does not call `humanizeEnvelope`. If session-files should later be humanized, posture needs its own humanize pass — out of v5.1.0 scope. -- The default-output snapshot at `tests/snapshots/default-output/posture.json` is frozen — change requires `UPDATE_SNAPSHOT=1` plus intent confirmation. +`--raw` bypasses the humanizer for byte-stable v5.0.0 output. `--json` is also byte-stable. Full detail and Wave 5 lessons: `docs/humanizer.md`. ## Suppressions @@ -225,20 +116,3 @@ node --test 'tests/**/*.test.mjs' - Session directories accumulate — use `/config-audit cleanup` to manage - Scanners run on Node.js >= 18 (uses node:test, node:fs/promises) - Plugin CLAUDE.md files in node_modules should be excluded via scope - -## Communication patterns - -### Linking to local files - -When pointing to local files in responses, always use markdown link syntax with a descriptive name: - -- Use `[Human-friendly name](file:///absolute/path)` — never bare `file:///...` URLs or autolinks ``. -- Always use absolute paths. Never `~/` or relative paths. -- For multiple files, render as a bullet list of named markdown links. - -Why: bare `file://` URLs only render the first as clickable across multiple lines. Named markdown links make each entry independently clickable and look cleaner. - -Example: - -- [Brief](file:///Users/ktg/.../brief.html) -- [Research summary](file:///Users/ktg/.../research/summary.md) diff --git a/docs/humanizer.md b/docs/humanizer.md new file mode 100644 index 0000000..bacb165 --- /dev/null +++ b/docs/humanizer.md @@ -0,0 +1,52 @@ +# Config-Audit — Plain-language output (v5.1.0) + +Imported from `CLAUDE.md` via pointer. + +Default output of all 18 commands routes through `humanizeEnvelope` from `lib/humanizer.mjs`. Findings are decorated with three additive fields and may have title/description/recommendation replaced when a translation exists. + +## Output modes + +| Flag | Behavior | +|------|----------| +| (default, no flag) | Plain-language: humanizer applied, findings group by user-impact, titles lead with prose. Self-audit terminal render also humanized. | +| `--raw` | Byte-stable v5.0.0 verbatim — humanizer bypassed, technical IDs and severity-only labels. For tooling that scrapes stderr from v5.0.0. | +| `--json` | Unchanged from v5.0.0 — humanizer bypassed, byte-stable JSON envelope. Always preferred for programmatic consumption over `--raw`. | +| `--output-file ` | Writes raw v5.0.0-shape JSON (humanizer bypassed). Posture-specific. | + +`--raw` is threaded through every CLI: `posture.mjs`, `scan-orchestrator.mjs`, `token-hotspots-cli.mjs`, `manifest.mjs`, `whats-active.mjs`, `fix-cli.mjs`, `drift-cli.mjs`, `self-audit.mjs`. + +## Vocabularies + +User-impact category (added to each finding as `userImpactCategory`, derived from scanner prefix): + +| Label | Scanners | +|-------|----------| +| Configuration mistake | CML, SET, HKV, RUL, MCP, IMP, PLH | +| Conflict | CNF, COL | +| Wasted tokens | TOK, CPS | +| Dead config | DIS | +| Missed opportunity | GAP | + +Action language (added to each finding as `userActionLanguage`, derived from severity): + +| Severity | Phrase | +|----------|--------| +| critical | Fix this now | +| high | Fix soon | +| medium | Fix when convenient | +| low | Optional cleanup | +| info | FYI | + +Relevance context (added to each finding as `relevanceContext`, computed from finding's file path): + +| Value | When | +|-------|------| +| `test-fixture-no-impact` | Path contains `/tests/fixtures/` or `/test/fixtures/` | +| `affects-this-machine-only` | Basename matches `*.local.*` (e.g., `settings.local.json`) | +| `affects-everyone` | Default — assumed shared/committed config | + +## Wave 5 lessons + +- Posture's stderr scorecard is rendered prose-side and is not part of the JSON envelope; `humanized.areas[].titleHumanized` referenced by command templates lives only in the prose render. +- Posture's `--output-file` writes raw v5.0.0-shape JSON because `posture.mjs` does not call `humanizeEnvelope`. If session-files should later be humanized, posture needs its own humanize pass — out of v5.1.0 scope. +- The default-output snapshot at `tests/snapshots/default-output/posture.json` is frozen — change requires `UPDATE_SNAPSHOT=1` plus intent confirmation. diff --git a/docs/scanner-internals.md b/docs/scanner-internals.md new file mode 100644 index 0000000..414823f --- /dev/null +++ b/docs/scanner-internals.md @@ -0,0 +1,76 @@ +# 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 `. +Posture CLI: `node scanners/posture.mjs [--json] [--global] [--full-machine] [--output-file path]`. +Scanner CLI: `node scanners/scan-orchestrator.mjs [--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, trust levels, 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 (Opus 4.7 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 | + +## 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 13 scanner prefixes (CML/SET/HKV/RUL/MCP/IMP/CNF/COL/TOK/CPS/DIS/GAP/PLH). 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 [--apply] [--json] [--global]` | +| `drift-cli.mjs` | CLI: `node drift-cli.mjs [--save] [--baseline name] [--json]` | +| `whats-active.mjs` | CLI: `node whats-active.mjs [--json] [--verbose] [--suggest-disables]` — read-only active-config inventory | +| `token-hotspots-cli.mjs` | CLI: `node token-hotspots-cli.mjs [--json] [--global] [--output-file path] [--accurate-tokens] [--with-telemetry-recipe]` — Opus-4.7 token hotspots ranking with optional API calibration | +| `manifest.mjs` | CLI: `node manifest.mjs [--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: Opus 4.7 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 | +| `opus-4.7-patterns.md` | Token-cost dynamics for Opus 4.7 era — patterns powering the TOK scanner | +| `cache-telemetry-recipe.md` | Manual `jq` recipe for verifying prompt-cache hit rate from session transcripts (v5 M7) |