open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
ktg-plugin-marketplace/plugins/config-audit/docs/humanizer.md
Kjell Tore Guttormsen f460814fe9 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 <noreply@anthropic.com>
2026-05-18 12:04:02 +02:00

2.6 KiB
Raw Blame History

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 <path> 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.