diff --git a/plugins/ai-psychosis/CLAUDE.md b/plugins/ai-psychosis/CLAUDE.md index a38d35e..13a250e 100644 --- a/plugins/ai-psychosis/CLAUDE.md +++ b/plugins/ai-psychosis/CLAUDE.md @@ -31,11 +31,11 @@ Legacy bash scripts were removed in v1.0 (available in git history). ## Data storage ``` -${CLAUDE_PLUGIN_DATA}/ +$CLAUDE_PLUGIN_DATA/ ├── sessions.jsonl Compact JSONL, one record per session ├── events.jsonl {ts, session_id, tool_name} per tool call └── state/ - └── {session_id}.json Live state during active session + └── .json Live state during active session ``` State files are created at SessionStart and deleted at SessionEnd. @@ -92,20 +92,3 @@ node --test tests/*.test.mjs - Conventional Commits: `type(scope): description` - English for all code, comments, and documentation - Norwegian for project-internal communication - -## 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/plugins/claude-design/CLAUDE.md b/plugins/claude-design/CLAUDE.md index ec7a807..7da304c 100644 --- a/plugins/claude-design/CLAUDE.md +++ b/plugins/claude-design/CLAUDE.md @@ -41,20 +41,3 @@ Pipelinen er sannhet inntil release: 5. Review er release-gate Voyage-policy: Opus på alle sub-agenter og orchestrator-faser. - -## 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/plugins/config-audit/CLAUDE.md b/plugins/config-audit/CLAUDE.md index d072f36..392c292 100644 --- a/plugins/config-audit/CLAUDE.md +++ b/plugins/config-audit/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/plugins/config-audit/docs/humanizer.md b/plugins/config-audit/docs/humanizer.md new file mode 100644 index 0000000..bacb165 --- /dev/null +++ b/plugins/config-audit/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/plugins/config-audit/docs/scanner-internals.md b/plugins/config-audit/docs/scanner-internals.md new file mode 100644 index 0000000..414823f --- /dev/null +++ b/plugins/config-audit/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) | diff --git a/plugins/graceful-handoff/CLAUDE.md b/plugins/graceful-handoff/CLAUDE.md index 2389155..8ee7386 100644 --- a/plugins/graceful-handoff/CLAUDE.md +++ b/plugins/graceful-handoff/CLAUDE.md @@ -63,20 +63,3 @@ node --test plugins/graceful-handoff/tests/ - v1.0.0 (2026-04-19): initial declarative command - v2.0.0 (2026-05-01): skill-arkitektur + JSON-pipeline + 3 hooks + auto-trigger (BREAKING) - v2.1.0 (2026-05-01): modell-bevisst kontekstvindu — 4-stegs resolution-kjede (used_percentage → payload-size → model-map → 1M default). Fikser for-tidlig auto-handoff på Opus 4.7 - -## 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/plugins/human-friendly-style/CLAUDE.md b/plugins/human-friendly-style/CLAUDE.md index f21bfe0..5fe4da3 100644 --- a/plugins/human-friendly-style/CLAUDE.md +++ b/plugins/human-friendly-style/CLAUDE.md @@ -45,20 +45,3 @@ If `keep-coding-instructions` is removed or set to `false`, Claude Code will str - Per-plugin variants (code-focused, deep-technical, etc.) — would belong in a future v1.1 if there's real demand - Forcing the style on other plugins — it remains opt-in. Other plugins may reference it in their READMEs. - Translation of the style file itself into Norwegian — defeats the purpose of language-agnostic instruction - -## 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/plugins/linkedin-thought-leadership/CLAUDE.md b/plugins/linkedin-thought-leadership/CLAUDE.md index e7021be..866c0f4 100644 --- a/plugins/linkedin-thought-leadership/CLAUDE.md +++ b/plugins/linkedin-thought-leadership/CLAUDE.md @@ -98,20 +98,3 @@ All content commands (post, quick, react, pipeline, first-post, video, multiplat 5. Topic must align with user's 5 core expertise areas (360Brew signal) 6. Topic rotation: no back-to-back same pillar, no pillar >50% in 14 days (warn-only) 7. Progressive onboarding: personalization score hidden until 3+ posts; voice guardian suppressed until 5+ voice samples - -## 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/plugins/llm-security/CLAUDE.md b/plugins/llm-security/CLAUDE.md index bb11c41..696909a 100644 --- a/plugins/llm-security/CLAUDE.md +++ b/plugins/llm-security/CLAUDE.md @@ -2,167 +2,7 @@ Security scanning, auditing, and threat modeling for Claude Code projects. 5 frameworks: OWASP LLM Top 10, Agentic AI Top 10 (ASI), Skills Top 10 (AST), MCP Top 10, AI Agent Traps (DeepMind). 1822+ unit, integration, and end-to-end tests (`tests/e2e/` covers the multi-hook attack chain, multi-session state simulation, and the full scan-orchestrator pipeline); mutation-testing coverage not published. -**v7.0.0 — Severity-dominated risk scoring (v2 model, BREAKING).** Three changes target the false-positive cascade on real codebases (hyperframes.com gave `BLOCK / Extreme / 100`, ~70% noise): - -1. **Risk-score v2 formula** (`scanners/lib/severity.mjs`) — severity-dominated, log-scaled within tier. Replaces v1 sum-and-cap that collapsed every non-trivial scan to 100/Extreme. Tiers: critical → 70–95, high only → 40–65, medium only → 15–35, low only → 1–11. Verdict cutoffs realigned to new bands (BLOCK ≥65, WARNING ≥15). `info` findings are observability-only — counted in OWASP aggregates but contribute zero to risk_score, verdict, and riskBand (B3, v7.2.0 — was undocumented pre-7.2.0). See `severity.mjs` JSDoc for full contract. -2. **Rule-based entropy scanner with file-extension skip, 8 line-level suppression rules, and configurable policy** — extensions skipped (`.glsl/.frag/.vert/.shader/.wgsl/.css/.scss/.sass/.less/.svg/.min.*/.map`); line-suppression rules (GLSL keywords, CSS-in-JS, inline SVG, ffmpeg `filter_complex`, User-Agent strings, SQL DDL, `throw new Error(\`...\`)`, markdown image URLs). Configurable via `.llm-security/policy.json` `entropy` section (thresholds, `suppress_extensions`, `suppress_line_patterns`, `suppress_paths`). Envelope `calibration` block reports skip counters + effective thresholds + policy source. -3. **DEP typosquat allowlist expansion** — 22 npm + 5 PyPI entries for short-name tools that tripped Levenshtein detection on every modern codebase (`knip`, `oxlint`, `tsx`, `nx`, `rimraf`, `uv`, `ruff`, etc.). - -See `docs/security-hardening-guide.md` §6 for the calibration story. - -**v7.1.1 — Scan-rapport narrative coherence (patch).** Three coordinated -edits address the whiplash symptom that survived v7.0.0 (numbers fixed, -narrative still walked findings back as "false positive" in prose): -(a) `agents/skill-scanner-agent.md` Step 2.5 mandates context-first -severity assignment — every signal has exactly one disposition (suppressed -OR reported), no per-finding walk-back; (b) `templates/unified-report.md` -gains a `### Narrative Audit` block in Executive Summary surfacing -`summary.narrative_audit.suppressed_findings.{count, by_category}` from -the agent's trailing JSON; (c) both files updated from stale v1 -risk-formula constants to the v2 model that has been authoritative in -`severity.mjs` since v7.0.0. Counter is distinct from the existing -top-level `output.suppressed` (`.llm-security-ignore` rule integer). -Out-of-scope but flagged: `commands/scan.md:113-114` retains the v1 -formula; resolution deferred to Batch B. - -**v7.3.0 — MCP cumulative-drift baseline (in progress, Wave C of Batch C).** -Closes E14 from `docs/critical-review-2026-04-20.md`. The -`mcp-description-cache.mjs` schema gains a sticky `baseline` slot per -tool plus a 10-event rolling `history` array (FIFO). Cumulative drift = -`levenshtein(current, baseline) / max(|current|, |baseline|)`; when the -ratio crosses `mcp.cumulative_drift_threshold` (default 0.25), -`post-mcp-verify.mjs` emits a separate MEDIUM `mcp-cumulative-drift` -advisory. The existing per-update >10% drift signal is unchanged — both -fire independently. Slow-burn rug-pulls that keep each update under the -per-update threshold but cumulatively diverge from baseline are now -caught. Baseline survives the 7-day TTL purge so detection persists -across the full window. New `/security mcp-baseline-reset` slash command -(plus `scanners/mcp-baseline-reset.mjs` CLI: `--list`, `--target `, -or no-args clear-all) lets the user acknowledge a legitimate MCP server -upgrade — clearing the baseline causes the next call to seed a fresh -one from the incoming description; description, firstSeen, lastSeen, and -history are preserved for audit. `LLM_SECURITY_MCP_CACHE_FILE` env var -overrides the cache path for end-to-end testing without polluting the -user's real `~/.cache/llm-security/mcp-descriptions.json`. - -**v7.3.0 — Env-var deprecation warnings (D3 of Batch C, Wave D).** -Closes 8.7 from `.claude/projects/2026-04-29-batch-c-scope-finalize/plan.md`. -`scanners/lib/policy-loader.mjs` exports a new helper -`getPolicyValueWithEnvWarn(section, key, envVarName, defaultValue)` — -env still wins per Preferences (existing behaviour), but when both the -env-var AND the `policy.json` key are explicitly set, the helper emits a -single per-process stderr line: `[llm-security] Deprecation: env-var -${ENVVAR} will be removed in v8.0.0; policy.json key ${section}.${key} -also set — env wins for now. Suppress with LLM_SECURITY_DEPRECATION_QUIET=1.` -Module-scoped `Set` dedupes per env-var name across call-sites. Four -overlapping vars are wired through the helper: -`LLM_SECURITY_INJECTION_MODE` ↔ `injection.mode` (in -`pre-prompt-inject-scan.mjs`), `LLM_SECURITY_TRIFECTA_MODE` ↔ -`trifecta.mode` and `LLM_SECURITY_ESCALATION_WINDOW` ↔ -`trifecta.escalation_window` (in `post-session-guard.mjs`), -`LLM_SECURITY_AUDIT_LOG` ↔ `audit.log_path` (in -`scanners/lib/audit-trail.mjs`). `DEFAULT_POLICY` gains -`trifecta.escalation_window: 5` to close the gap noted in the plan -revisions table (M10). Env-only vars without policy.json equivalents -(`LLM_SECURITY_UPDATE_CHECK`, `LLM_SECURITY_PRECOMPACT_MODE`, -`LLM_SECURITY_PRECOMPACT_MAX_BYTES`, `LLM_SECURITY_IDE_ROOTS`, -`LLM_SECURITY_MCP_CACHE_FILE`) are unchanged — they emit no -deprecation signal because there is nothing to deprecate yet. - -**v7.5.0 — Playground (additive surface, no scanner/hook behavior changes).** -Single-file SPA at `playground/llm-security-playground.html` (~10 200 lines) -for onboarding, demo og workshop-bruk uten Claude Code-installasjon. Parser -+ renderer for alle 18 `produces_report=true`-kommandoer i `CATALOG`. State -i IndexedDB primær (`llm-security-playground-v1`) med localStorage-fallback, -sirkelfri Proxy + EventTarget store, microtask-batchet render. Theme-bootstrap -med FOUC-prevention. 4 overflater: onboarding (5 grupper) → home (3 tracks) -→ catalog (20 kommandoer) ⇄ project (rapporter / oversikt / kontekst / -eksport). Demo-state har tre prosjekter inline; `dft-komplett-demo` har alle -18 rapporter ferdig parsed for klikk-gjennom. Vendor-synket design-system -under `playground/vendor/playground-design-system/` (sjekksum-låst via -`MANIFEST.json`, redigeres aldri direkte). Test-fixtures under -`playground/test-fixtures/` (én markdown-fil per kommando) er kontrakt-anker -for parser-utvikling. Skjermdumper i `playground/screenshots/v7.5.0/`. -Eksponerte vinduer-globaler for testing/automasjon: `__store`, `__navigate`, -`__loadDemoState`, `__scheduleRender`, `__PARSERS`, `__RENDERERS`, `__CATALOG`, -`__inferVerdict`, `__inferKeyStats`, `__renderPageShell`, `__handlePasteImport`. -Inkluderer fix av `normalizeVerdictText` regex-rekkefølge: GO-WITH-CONDITIONS -sjekkes før GO så betinget verdict ikke kollapser til ALLOW. - -**v7.6.0 — Playground Tier 3-referanse-case (additive surface, no -scanner/hook behavior changes).** Playgroundet er nå en visuelt og -strukturelt fullført referanse-implementasjon for -`shared/playground-design-system/` Tier 3-supplementet. 8 nye Tier 3- -komponenter integrert i de 18 rapport-rendererne: `tfa-flow` + `tfa-leg` -+ `tfa-arrow` (lethal trifecta-kjede med `