fix(code-metrics): ground the principles skill in its primaries and add a skill-quality Next-section check

docs/CATALOG.md

@@ -88,7 +88,7 @@ plugin manifests and kept in sync by CI. Never hand-edit it; the category vocabu
 - [`context-guard`](../plugins/context-guard): Per-session context-window observability plus the first shipped consumer: a statusline wrapper tees each session's context_window fields to a per-session snapshot file, a zone resolver classifies usage into smart/acceptable/dumb bands (percentage bands plus window-class token bands, conservative-min combination, zones.json SSOT with shipped defaults), a reader contract fixes how consuming sessions interpret the snapshots, and zone-crossing hooks report once per transition into a worse zone across two channels: the continuation menu to the operator, who owns that choice, and to the model only the zone determination plus the counter-steer that a zone word is not a decay signal (advisory by default; an optional blocking mode gates new mutating work on a fresh dumb-zone snapshot with handoff-writing exempt), with a PostCompact hook persisting an evidence-degraded marker.
 - [`context-budget`](../plugins/context-budget): Measure a Claude Code session's fixed startup context payload per item, on the consumer's machine at a pinned, version-stamped binary, including per-tool attribution of the built-in tool pools that /context reports only as lump sums, derived live by A/B bare-name-deny differencing with enforced comparability rules (skill-listing signature, one mode, one binary), an SDK-primary exact meter degrading to a version-aware headless /context parser and then to an honest structured error (never a wrong number), and a per-project measure-toggle-remeasure ledger under the plugin data directory recording every lever's real before/after delta. Report-only: prints exact config, applies nothing.
 - [`plugin-quality`](../plugins/plugin-quality): Post-use behavioral audit of Claude Code plugin components: a six-step audit workflow (evidence capture, grounded mapping in a fresh subagent, blindspot pass, interactive contract lock, presence-gated review seams, work-item emit with draft+confirm) over any skill, agent, hook, command, or config you have actually used, zone-informed by context-guard snapshots when present, conservative when not.
-- [`skill-quality`](../plugins/skill-quality): Skill-authoring QA tooling: a static contract checker that runs twenty-six deterministic checks over a Claude Code skill (frontmatter, explicit invocation mode, description/verb-contract polarity, per-skill listing-entry cap, trigger-keyword preservation, line caps, broken internal refs, markdownlint, gotchas surface, evals presence, precompute opportunity, completion-criteria signal, injection shell-declaration, fresh-eyes declaration conformance), a shared skill-listing budget reporter across a set of skills, and a bundled evals.json schema plus a deterministic eval-quality lint (duplicate case identities, missing fixtures, empty or vague grading criteria, set-coverage warnings). Runs against any repo's skills directory via the convention-resolution ladder, with no baked layout.
+- [`skill-quality`](../plugins/skill-quality): Skill-authoring QA tooling: a static contract checker that runs twenty-seven deterministic checks over a Claude Code skill (frontmatter, explicit invocation mode, description/verb-contract polarity, per-skill listing-entry cap, trigger-keyword preservation, line caps, broken internal refs, markdownlint, gotchas surface, evals presence, precompute opportunity, completion-criteria signal, injection shell-declaration, fresh-eyes declaration conformance), a shared skill-listing budget reporter across a set of skills, and a bundled evals.json schema plus a deterministic eval-quality lint (duplicate case identities, missing fixtures, empty or vague grading criteria, set-coverage warnings). Runs against any repo's skills directory via the convention-resolution ladder, with no baked layout.
 - [`computer-use`](../plugins/computer-use): Operating knowledge for Claude Code's built-in computer-use MCP server, the desktop screen-control surface. `/computer-use:diagnose` resolves a symptom to a cause instead of retrying: why every screenshot is downscaled to a fixed pixel budget and why zoom (not a bigger display) is the way back to detail, how to read a capture or input failure, and the per-OS quirks that make a synthesized key or menu behave unlike a human's. `/computer-use:setup` verifies the prerequisites the surface cannot verify for itself and reports the environment settings that end a session mid-run.
 - [`fleet`](../plugins/fleet): Run a Claude Code agent turn on another machine in a personal fleet, over SSH on the tailnet. Every machine signs into its own Claude account, so the built-in peer tools are same-account and never span machines; this carries the SSH path that does, with target resolution from the rendered fleet manifest, one-shot and multi-turn headless recipes, the Windows-side relay that reaches a target's own sessions, and the permission posture that keeps remote agent launches prompting.
 - [`instruction-placement`](../plugins/instruction-placement): Routes agent-instruction content to the surface that loads it at the right moment. The audit skill sweeps a repository's instruction layer and its ordinary markdown for content whose scope is narrower than the surface carrying it, meaning conventions keyed to one file type or one subtree sitting in an always-loaded CLAUDE.md or AGENTS.md, and for normative conventions stranded in documentation Claude never loads at all, then classifies each against a routing rubric and proposes a destination whose `paths:` glob is machine-validated before it is ever offered. Safety-class content (irreversible actions, secrets, data integrity, external publication, compliance, agent authority) is hard-denied from demotion and reported as held back rather than proposed, because demotion trades guaranteed presence for conditional presence and deferred surfaces are invisible inside subagents and absent after compaction until re-triggered. Every accepted move regenerates an always-loaded index of deferred surfaces, which is what keeps a demoted rule reachable from a subagent that never receives its injection. The audit is read-only and emits a diffable findings artifact; realignment is a separate skill gated per item with no blanket-approve path; a deterministic check skill gates that every rule glob still resolves and the index is current; and a setup skill verifies the one thing no other gate can see: that the index target is a file Claude Code will actually read, since it reads CLAUDE.md and not AGENTS.md.

plugins/code-metrics/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "code-metrics",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Read-only code measures for a change, with cited references and no verdict: lines per file (audit-size), cyclomatic, cognitive, and Halstead complexity (audit-complexity), duplication with sanctioned-replication exclusions (audit-duplication), coverage per function with CRAP from existing lcov, Cobertura, coverage.py, or Go artifacts (audit-coverage), type debt for TypeScript and Python (audit-type-debt), the literacy router for what each number can and cannot say (principles), and a setup skill for the consumer's .claude/code-metrics.yaml. Runs external collectors only when they already resolve, never installs, never runs tests, never emits a finding.",
   "author": {
     "name": "Melodic Software",

plugins/code-metrics/CHANGELOG.md

@@ -3,6 +3,59 @@
 All notable changes to the `code-metrics` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.2.2]
+
+### Fixed
+
+- **`principles`: the Halstead split-file answer overstated what the formula supports.** The
+  quick guide said difficulty "should not have" moved when a file was split, and eval 1 expected
+  the same. Difficulty `(n1/2) * (N2/n2)` carries no explicit length term, but both factors change
+  per half on a split, and a radon run on two functions measured together and apart gave 1.667 for
+  the whole against 1.000 and 1.800 for the halves. The entry and the eval now say per-file
+  difficulty legitimately moves on a split, in either direction.
+- **`principles`: the §8.2.115 reading is labelled as the plugin's.** thresholds.md, measures.md,
+  and the configuration reference presented "a function's non-empty lines as a percentage of the
+  file's" as the clause's words. The clause states `MaxNumberOfNonEmptyLinesOfCode` with a default
+  of "5%" and names no base; the percentage-of-file base is this plugin's reading, and thresholds.md
+  now carries the four-part verification record for it (OMG ASCQM v1.1 and the ISO edition, as of
+  2026-09-11, recheck on a new revision). The same files now name ISO/IEC 5055:2021 as the ISO
+  publication of ASCQM v1.0, with v1.1 identical for the cited clauses, and note that the
+  document's informative CWE summary rows carry different defaults (1000 lines per file, 10%) from
+  its detection patterns (5%, 90%).
+- **`principles`: McCabe's framing and Campbell's switch rule are quoted as written.** McCabe 1976
+  frames cyclomatic complexity for modules that are "testable and maintainable", not testability
+  alone; Campbell v1.7 states "a switch and all its cases combined incurs a single structural
+  increment". measures.md and literature.md carry both verbatim.
+
+### Changed
+
+- **`principles`: the quick guide answers "which measure should I look at" with an intent-keyed
+  tree**, each branch grounded in its primary: testing burden to cyclomatic (McCabe; NIST SP 500-235
+  sets the test count equal to it), readability to cognitive (Campbell), diff size and copying to
+  lines per file and duplication (ISO/IEC 5055 CWE-1080 and CWE-1041), and whether a suite would
+  catch a fault to the mutation-testing presence gate, because coverage records execution and the
+  primary literature disagrees on how well it predicts fault detection (Inozemtseva and Holmes
+  2014 against Gopinath, Jensen and Groce 2014 and Kochhar, Thung and Lo 2015). A duplication entry
+  states that no reference ships and that the percentage moves with `duplication.min_tokens`, and
+  the routing table names the plugin's report-schema reference for the report vocabulary.
+- **`principles`: the no-verdict rule is stated once**, at the top of the skill body, and the
+  reference files no longer cite the marketplace's ADR by number, which a consumer of the installed
+  plugin cannot read.
+- **`principles`: the reference files state present-tense facts and carry no research narrative.**
+  The thresholds file's account of how ten candidate values were commissioned from a social post,
+  scrutinized at an interview, and full-text searched is replaced by a table of popular numbers with
+  no found source, naming what was checked and what was not; literature.md states each source's
+  confidence and its basis without narrating the pass that established it. For the record, that
+  candidate list was 22 (cyclomatic), 22 (cognitive), 80 (Halstead difficulty), 500 (lines per
+  file), 100 (coverage), 25 (CRAP), and four zeros for count-based concerns; 20 and 1000 survived
+  as shipped defaults because a citation exists for them, and the rest traced to no source.
+- **`principles`: a `## Next` section** names the audit skill for the measure in question and
+  `/code-metrics:setup` for setting the reader's own reference values, in the mention-only shape
+  the sibling skills use.
+- **`principles`: literature.md gains a coverage-and-test-effectiveness section** citing the five
+  primaries above with their DOIs, and a duplication row in the thresholds table records that no
+  duplication reference ships and why.
+
 ## [0.2.1]
 
 ### Changed

plugins/code-metrics/reference/config.md

@@ -63,9 +63,9 @@ The third column is written by hand and is not derived from anything. A row whos
 | `complexity.cyclomatic.reference` | `20` | ISO/IEC 5055:2021 §8.2.117 (normative). Cited alternatives: 10 (McCabe 1976, "reasonable, but not magical") and 15 (NIST SP 500-235, with its six practices) |
 | `complexity.cognitive.reference` | `null` | Campbell, SonarSource; no standard sets a threshold |
 | `complexity.halstead.difficulty` | `null` | Halstead 1977; no standard sets a threshold |
-| `size.mode` | `file-lines` | `file-lines` compares each file's non-blank lines to `size.file_lines`; `iso-8.2.115` adds each function's non-empty lines as a percentage of the file's, from a collector that reports function ranges |
-| `size.file_lines` | `1000` | The plugin's own number. It coincides with an informative figure in ISO/IEC 5055:2021 §6.3 Table 1, which is not normative; 500, the operator-list figure, is selectable |
-| `size.function_lines_pct` | `5` | ISO/IEC 5055:2021 §8.2.115 (normative), used in `iso-8.2.115` mode |
+| `size.mode` | `file-lines` | `file-lines` compares each file's non-blank lines to `size.file_lines`; `iso-8.2.115` adds each function's non-empty lines as a percentage of the file's (the plugin's reading of the clause, which states 5% with no base), from a collector that reports function ranges |
+| `size.file_lines` | `1000` | The plugin's own number. It coincides with an informative figure in ISO/IEC 5055:2021 §6.3 Table 1, which is not normative; 500 is selectable |
+| `size.function_lines_pct` | `5` | ISO/IEC 5055:2021 §8.2.115 (normative) states the 5%; the percentage-of-file base is the plugin's reading; used in `iso-8.2.115` mode |
 | `duplication.min_tokens` | `50` | Passed to the clone collector |
 | `duplication.min_lines` | `5` | Passed to the clone collector |
 | `duplication.ignore` | `[]` | Collector ignore globs |

plugins/code-metrics/scripts/config-defaults.json

@@ -65,14 +65,14 @@
       "config_key": "size.file_lines",
       "value_key": "lines_non_blank",
       "direction": "at_or_above",
-      "provenance": "the plugin's own number, not ISO-backed: it coincides with the informative figure in ISO/IEC 5055:2021 §6.3 Table 1, which is not normative, while the normative form (§8.2.115) is a function-level percentage; 500 is the operator-list figure, selectable; size.mode iso-8.2.115 selects the normative function-percentage alternative"
+      "provenance": "the plugin's own number, not ISO-backed: it coincides with the informative figure in ISO/IEC 5055:2021 §6.3 Table 1, which is not normative, while the normative form (§8.2.115) is a function-level percentage; 500 is selectable; size.mode iso-8.2.115 selects the normative function-percentage alternative"
     },
     {
       "measure": "function_lines_pct",
       "config_key": "size.function_lines_pct",
       "value_key": "function_lines_pct",
       "direction": "at_or_above",
-      "provenance": "ISO/IEC 5055:2021 §8.2.115 (normative): a function whose non-empty lines exceed this percentage of the file's; used when size.mode is iso-8.2.115"
+      "provenance": "ISO/IEC 5055:2021 §8.2.115 (normative) states the 5% with no base; the percentage-of-file reading is the plugin's; used when size.mode is iso-8.2.115"
     },
     {
       "measure": "coverage",

plugins/code-metrics/skills/audit-size/SKILL.md

@@ -59,9 +59,8 @@ side as INCONCLUSIVE); otherwise keep the JSON beside your notes and compare by
 - The reference compares against `lines_non_blank`. The bundled default is 1000, and its
   provenance is the one sentence the report prints beside it: the plugin's own number, not
   ISO-backed: it coincides with the informative figure in ISO/IEC 5055:2021 §6.3 Table 1, which is
-  not normative, while the normative form (§8.2.115) is a function-level percentage; 500 is the
-  operator-list figure, selectable; size.mode iso-8.2.115 selects the normative
-  function-percentage alternative.
+  not normative, while the normative form (§8.2.115) is a function-level percentage; 500 is
+  selectable; size.mode iso-8.2.115 selects the normative function-percentage alternative.
 - A `null` value means the collector did not produce it (the bundled counter has no comment
   count); it is never zero.
 - `status` is `complete` when every lane in scope was measured, `partial` when one was not, and