bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/skf-test-skill/references/scoring-rules.md

@@ -56,7 +56,7 @@ When `docs_only_mode: true` is set by step 3 (indicating a skill where all SKILL
 
 This is functionally identical to Quick tier weight redistribution but with a different coverage denominator (self-consistency instead of source comparison).
 
-**External-validator requirement for docs-only:** docs-only mode removes two categories (Signature Accuracy, Type Coverage) from scoring. If External Validation is ALSO unavailable, the evidence base collapses to Coverage alone (naive) or Coverage + Coherence (contextual) — which in the naive/Quick case trips the minimum-evidence floor (INCONCLUSIVE). To keep docs-only skills gradable when external validators are present but still deterministic when they are missing: **when `docsOnly: true` AND `externalValidation is null`, step 5 MUST cap `totalScore` at `threshold - 1` (forcing FAIL) before the INCONCLUSIVE floor is evaluated.** This prevents a docs-only skill from PASSing with only one or two redistributed categories carrying all the weight. Implement in step 5 §4 as a pre-compare cap, recorded in the report as `scoring_notes: docs-only without external validators — capped below threshold`.
+**External-validator requirement for docs-only:** docs-only mode removes two categories (Signature Accuracy, Type Coverage) from scoring. If External Validation is also unavailable, the evidence base collapses to Coverage alone (naive) or Coverage + Coherence (contextual) — which in the naive/Quick case trips the minimum-evidence floor (INCONCLUSIVE). To keep docs-only skills gradable when external validators are present but still deterministic when they are missing: **when `docsOnly: true` AND `externalValidation is null`, step 5 must cap `totalScore` at `threshold - 1` (forcing FAIL) before the INCONCLUSIVE floor is evaluated.** This prevents a docs-only skill from PASSing with only one or two redistributed categories carrying all the weight. Implement in step 5 §4 as a pre-compare cap, recorded in the report as `scoring_notes: docs-only without external validators — capped below threshold`.
 
 ### Stack Skills (Any Tier)
 
@@ -68,8 +68,6 @@ When `metadata.json.skill_type == "stack"` (set `stackSkill: true` in the scorin
 - **Applies regardless of detected tier** (Quick, Forge, Forge+, Deep) and is independent of `docsOnly` and `state2`. A stack skill can also be docs-only or State 2; the skip reasons combine additively (e.g. `"stack skill (external type surface) + State 2 (provenance-map)"`).
 - **Detection:** step 5 reads `metadata.json.skill_type` from the skill package. If the value is `"stack"`, set `stackSkill: true` in the scoring input JSON.
 
-Equivalence-class note: stack skills with `docsOnly:false` / `state2:false` map to the same equivalence class as State 2 contextual rows (class B) or State 2 naive rows (class D) — the redistribution math is identical; only the `skipReasons` string changes.
-
 ### Reference-App Skills (Any Tier)
 
 When `metadata.json.scope_type == "reference-app"` (set `referenceApp: true` in the scoring input):
@@ -80,8 +78,6 @@ When `metadata.json.scope_type == "reference-app"` (set `referenceApp: true` in
 - **Applies regardless of detected tier** (Quick, Forge, Forge+, Deep) and is independent of `docsOnly` and `state2`; skip reasons combine additively. `referenceApp` and `stackSkill` are distinct scope/type signals and should not both be set for the same skill.
 - **Detection:** step 5 reads `metadata.json.scope_type` from the skill package. If the value is `"reference-app"`, set `referenceApp: true` in the scoring input JSON. The skip reason recorded is `"reference-app (no library export signatures)"`.
 
-Equivalence-class note: reference-app skills map to the same redistribution equivalence class as stack skills — the math is identical; only the `skipReasons` string changes.
-
 ### State 2 Source Access (Any Tier, Provenance-Map Only)
 
 When source is not locally available and analysis resolves to State 2 (provenance-map baseline per source-access-protocol.md):
@@ -94,7 +90,7 @@ When source is not locally available and analysis resolves to State 2 (provenanc
 
 Note: When provenance-map entries are predominantly T1 (AST-verified at compilation time), the coverage and name-matching data is already at highest confidence. The N/A categories reflect the inability to re-verify at test time, not low-quality extraction data.
 
-**State 2 undercount risk acknowledgement:** provenance-map is a cached extraction snapshot — if the source has evolved since extraction, public API adds/removes will NOT surface in Export Coverage (denominator is frozen to the provenance-map union). When `state2: true` AND step 3 records any provenance vs metadata divergence (e.g. union > either source by >5%), apply a flat **10% deduction** to `exportCoverage` before calling the scoring script, AND set `analysis_confidence: provenance-map` (already set) with a report note: `scoring_notes: State 2 undercount risk acknowledged — 10% deduction applied to Export Coverage`. Rationale: the skill cannot be reliably scored on a frozen denominator when the cache is known to disagree with its own metadata; prefer understating over overstating.
+**State 2 undercount risk acknowledgement:** provenance-map is a cached extraction snapshot — if the source has evolved since extraction, public API adds/removes will not surface in Export Coverage (denominator is frozen to the provenance-map union). When `state2: true` AND step 3 records any provenance vs metadata divergence (e.g. union > either source by >5%), apply a flat **10% deduction** to `exportCoverage` before calling the scoring script, AND set `analysis_confidence: provenance-map` (already set) with a report note: `scoring_notes: State 2 undercount risk acknowledged — 10% deduction applied to Export Coverage`. Rationale: the skill cannot be reliably scored on a frozen denominator when the cache is known to disagree with its own metadata; prefer understating over overstating.
 
 ### Forge Tier (ast-grep)
 - Export Coverage: AST-backed export comparison
@@ -114,60 +110,6 @@ Note: When provenance-map entries are predominantly T1 (AST-verified at compilat
 - Full scoring formula with maximum depth
 - **Migration & Deprecation Warnings section:** If T2-future annotations exist in the enrichment data, verify that Section 4b is present in SKILL.md Tier 1 and that each warning traces to a T2 provenance citation. If no T2-future annotations exist, Section 4b should normally be absent (not empty). Presence/absence mismatch is a Medium severity gap — with one Info-severity exception for historical-migration content (completed package renames, consolidated import paths, shipped API cutovers that remain load-bearing for training-data drift remediation). See `references/coherence-check.md` §2b/§5b for the three-case rule.
 
-## Redistribution Combinations Matrix (M3 — terminology + determinism)
-
-The table below enumerates every `(mode × tier × docsOnly × state2)` cell and
-the redistribution outcome. Two cells map to the same **equivalence class**
-whenever their skip set and base-weight table are identical — the scoring
-script then emits the same `weights` / `activeCategories` / `skippedCategories`
-output regardless of which specific cell produced it. The rightmost column
-cites the representative fixture in
-`test/fixtures/compute-score-contract.json` used to pin the class's math.
-
-| # | mode       | tier     | docsOnly | state2 | Base table     | Skipped (sig/type)    | Skipped (ext if null) | Equiv. class | Representative fixture        |
-|---|------------|----------|----------|--------|----------------|-----------------------|-----------------------|--------------|-------------------------------|
-| 1 | contextual | Deep     | F        | F      | contextual     | —                     | if null               | **A**        | `suite_a_all_active`          |
-| 2 | contextual | Forge+   | F        | F      | contextual     | —                     | if null               | A            | `suite_k_forge_plus`          |
-| 3 | contextual | Forge    | F        | F      | contextual     | —                     | if null               | A            | `suite_p_contextual_forge`    |
-| 4 | contextual | Quick    | F        | F      | contextual     | Quick tier            | if null               | **B**        | `suite_c_quick_tier`          |
-| 5 | contextual | Deep     | T        | F      | contextual     | docs-only             | if null               | B            | `suite_r_contextual_deep_docsonly` |
-| 6 | contextual | Forge+   | T        | F      | contextual     | docs-only             | if null               | B            | (equiv. — see `suite_r_*`)    |
-| 7 | contextual | Forge    | T        | F      | contextual     | docs-only             | if null               | B            | (equiv.)                      |
-| 8 | contextual | Quick    | T        | F      | contextual     | Quick tier + docs-only| if null               | B            | `suite_f_docs_only`           |
-| 9 | contextual | Deep     | F        | T      | contextual     | State 2               | if null               | B            | `suite_g_state2`              |
-| 10| contextual | Forge+   | F        | T      | contextual     | State 2               | if null               | B            | (equiv.)                      |
-| 11| contextual | Forge    | F        | T      | contextual     | State 2               | if null               | B            | (equiv.)                      |
-| 12| contextual | Quick    | F        | T      | contextual     | Quick + State 2       | if null               | B            | (equiv. — Quick+state2)       |
-| 13| contextual | *        | T        | T      | contextual     | docs-only + State 2   | if null               | B            | (equiv.)                      |
-| 14| naive      | Deep     | F        | F      | naive          | —                     | if null               | **C**        | `suite_q_naive_deep`          |
-| 15| naive      | Forge+   | F        | F      | naive          | —                     | if null               | C            | (equiv.)                      |
-| 16| naive      | Forge    | F        | F      | naive          | —                     | if null               | C            | `suite_b_naive`               |
-| 17| naive      | Quick    | F        | F      | naive          | Quick tier            | if null               | **D**        | `suite_e_triple_skip`         |
-| 18| naive      | Deep     | T        | F      | naive          | docs-only             | if null               | D            | `suite_s_naive_deep_docsonly` |
-| 19| naive      | Forge+   | T        | F      | naive          | docs-only             | if null               | D            | (equiv.)                      |
-| 20| naive      | Forge    | T        | F      | naive          | docs-only             | if null               | D            | (equiv.)                      |
-| 21| naive      | Quick    | T        | F      | naive          | Quick + docs-only     | if null               | D            | `suite_o_input_echo`          |
-| 22| naive      | Deep     | F        | T      | naive          | State 2               | if null               | D            | `suite_t_naive_state2`        |
-| 23| naive      | Forge+   | F        | T      | naive          | State 2               | if null               | D            | (equiv.)                      |
-| 24| naive      | Forge    | F        | T      | naive          | State 2               | if null               | D            | (equiv.)                      |
-| 25| naive      | Quick    | F        | T      | naive          | Quick + State 2       | if null               | D            | (equiv.)                      |
-| 26| naive      | *        | T        | T      | naive          | docs-only + State 2   | if null               | D            | (equiv.)                      |
-
-**How to read the matrix.** The four equivalence classes A/B/C/D are
-exhaustive: the scoring script's weight-redistribution output depends ONLY on
-(base table, sig/type skip, ext skip), so every row mapping to class X emits
-the same final weights for identical input scores. "(equiv.)" rows are *not*
-missing coverage — they reduce algebraically to a listed representative. The
-M3 fixture set ships at least one representative per equivalence class and one
-representative per unique skip-reason combination so the `skipReasons` string
-is also pinned (e.g. "Quick tier", "docs-only mode", "State 2
-(provenance-map)", "Quick tier + docs-only mode").
-
-**Quick-tier INCONCLUSIVE interaction.** Rows 4, 8, 12, 17, 21, 25 all force
-the minimum-evidence floor to evaluate "Quick tier + Export Coverage alone"
-cases separately — see `Result Determination` below. The matrix above is the
-pre-floor redistribution only; INCONCLUSIVE verdict determination runs after.
-
 ## Score Calculation
 
 ```
@@ -185,11 +127,13 @@ combined_coherence = (reference_validity * 0.6) + (integration_completeness * 0.
 
 If no integration patterns exist, combined coherence equals reference validity.
 
+This is the documented contract. The tally + weighted mean is computed by `scripts/aggregate-coherence.py` (invoked from coherence-check.md §5c), not by hand; the per-reference validity judgment (§4) and pattern-completeness judgment (§5) stay in the prompt, only the arithmetic is scripted.
+
 ## Result Determination
 
-Three-state gate — **PASS / FAIL / INCONCLUSIVE**. `INCONCLUSIVE` is not PASS and not FAIL; it signals insufficient evidence to grade the skill. Downstream workflows MUST treat `INCONCLUSIVE` as a hard gate — do not export, do not auto-retry, surface to the human.
+Three-state gate — **PASS / FAIL / INCONCLUSIVE**. `INCONCLUSIVE` is not PASS and not FAIL; it signals insufficient evidence to grade the skill. Downstream workflows must treat `INCONCLUSIVE` as a hard gate — do not export, do not auto-retry, surface to the human.
 
-- **Minimum-Evidence Floor (MANDATORY — applies before PASS/FAIL comparison):**
+- **Minimum-Evidence Floor (applies before PASS/FAIL comparison):**
   - `active_categories` = count of categories with a non-zero final weight *after* all redistribution (Quick tier, docs-only, State 2, external-validator-unavailable). Categories with a redistributed weight of 0 do not count as active, even if they received a score.
   - **If `active_categories < 2`** → force `result: INCONCLUSIVE` with rationale `"insufficient evidence: only {N} active category"`. A single active category cannot cross-validate itself and a PASS would be a false signal.
   - **If `tier == "Quick"` AND the sole active contributor is Export Coverage** → force `result: INCONCLUSIVE` with rationale `"Quick tier: Export Coverage alone is insufficient evidence — add a second active category by upgrading tier or enabling external validators"`. This catches the degenerate case where every signature/type/coherence/external category gets redistributed to 0 and Export Coverage is doing all the work.

package/src/skf-test-skill/references/source-access-protocol.md

@@ -41,14 +41,14 @@
 
   Leave `analysis_confidence` unchanged (still `full` or `provenance-map` per the waterfall) — stratified scope does not degrade confidence, only the denominator. Annotate the coverage report with: `Stratified scope — denominator: {effective_denominator | tier_a_include union | scope.include union} ({N} files matched, {M} exports union)`.
 
-  **When this clause does NOT apply:** `scope.type: "full-library"` skills, single-package repositories, or stratified briefs where the full monorepo is intentionally in scope. For those, use the standard barrel-based denominator — **unless** the single-package repo is a pattern-reference app (see next bullet).
+  **When this clause does not apply:** `scope.type: "full-library"` skills, single-package repositories, or stratified briefs where the full monorepo is intentionally in scope. For those, use the standard barrel-based denominator — **unless** the single-package repo is a pattern-reference app (see next bullet) or publishes a multi-subpath `exports` map (use the multi-entry clause below).
 
 - **Pattern-reference apps (non-library source):** If the source is a single-package repo whose purpose is demonstrating an integration pattern rather than distributing a library API — typical markers are `scope.type: "full-library"` **without** a barrel file at any recognized entry-point path (`__init__.py`, `index.ts`/`index.js`, `lib.rs`, `mod.rs`) AND without a monorepo layout — the skill's value lives in wiring patterns, not exports. None of the preceding three clauses fits: there is no barrel to count from, no empty-barrel `scope.include` to consult, and no monorepo stratification to re-derive.
 
   **Trigger (either fires):**
 
   1. `scope.notes` in `forge-data/{skill_name}/skill-brief.yaml` flags pattern-reference intent (phrases such as "Reference app, not a library", "pattern-reference", "embedded-pattern skill", or "skill value is the … pattern"). The `scope.notes` field is authoritative when the author wrote it.
-  2. Source tree lacks a barrel file at every recognized entry-point path AND the repo is not a monorepo (no `packages/`, `workspaces`, `lerna.json`, `rush.json`, `nx.json`, or Cargo `[workspace]`). Detected at test time by filesystem inspection of `{source_path}`.
+  2. Source tree lacks a barrel file at every recognized entry-point path AND the repo is not a monorepo (no `packages/`, `workspaces`, `lerna.json`, `rush.json`, `nx.json`, or Cargo `[workspace]`) AND the package does not declare a multi-subpath `exports` map (those route to the multi-entry clause below). Detected at test time by filesystem inspection of `{source_path}`.
 
   **Denominator:** canonicalized provenance-map entry count (same canonicalization as the "Provenance-map canonicalization" section below). `skf-create-skill`'s extraction pass has already curated the provenance-map to the authored pattern surface; treat it as the authoritative enumeration of the skill's documented reach.
 
@@ -56,7 +56,7 @@
 
   **Confidence:** leave `analysis_confidence` unchanged (still `full` or `provenance-map` per the waterfall). Pattern-reference does not degrade confidence — the surface is smaller than a library barrel, not lower quality. Annotate the coverage report with: `Pattern-reference — denominator: {tier_a_include union | canonicalized provenance-map count} ({N} pattern surfaces)`.
 
-  **When this clause does NOT apply:** any repo with a non-empty barrel file, any monorepo (use the stratified-scope clause), or any single-package repo whose `scope.type` is explicitly `public-api` / `specific-modules` / `component-library` / `docs-only` (those scope types have their own denominator semantics). Also does NOT apply when `scope.type: "reference-app"` — that scope type carries its own pattern-surface denominator semantics (the brief speaks for itself), so this clause's filesystem trigger is moot.
+  **When this clause does not apply:** any repo with a non-empty barrel file, any monorepo (use the stratified-scope clause), or any single-package repo whose `scope.type` is explicitly `specific-modules` (use the specific-modules clause), `public-api` with a multi-subpath `exports` map (use the multi-entry clause below — a `public-api` package WITHOUT such a map keeps the standard root-barrel rule), `component-library`, or `docs-only`. Also does not apply when `scope.type: "reference-app"` — that scope type carries its own pattern-surface denominator semantics (the brief speaks for itself), so this clause's filesystem trigger is moot.
 
 - **Single-crate curated subset (`scope.type: "specific-modules"`):** If the source is a single-package (non-monorepo) repo whose skill brief sets `scope.type: "specific-modules"` and uses `scope.include`/`scope.exclude` to carve a subset of the crate's public surface, the coverage denominator is the **in-scope reachable barrel** — not the full barrel.
 
@@ -70,7 +70,17 @@
 
   **When `effective_denominator` is present:** prefer `metadata.json.stats.effective_denominator` (same priority-1 rule as the stratified-scope clause), subject to the same deflation guard.
 
-  **When this clause does NOT apply:** monorepo packages (use the stratified-scope clause), `scope.type: "full-library"` (use the standard barrel), or empty-barrel packages (use the empty-barrel clause). This clause is specifically for single-crate repos where the brief intentionally documents a curated subset rather than the full public surface.
+  **When this clause does not apply:** monorepo packages (use the stratified-scope clause), `scope.type: "full-library"` (use the standard barrel), or empty-barrel packages (use the empty-barrel clause). This clause is specifically for single-crate repos where the brief intentionally documents a curated subset rather than the full public surface.
+
+- **Multi-entry (exports-map) packages (single-package libraries publishing via a `package.json` `exports` map):** If the in-scope `package.json` declares an `exports` map with **multiple non-root subpath entries** (more than just `"."`) and the repo carries **no** monorepo markers (`packages/` layout, `workspaces` field, `lerna.json`, `rush.json`, `nx.json`, Cargo `[workspace]`), the package's public surface spans every published subpath, not just the root barrel. The standard "named exports from `index.ts`" rule undercounts: it measures only the `"."` barrel while installers reach the full subpath set. This clause covers both `scope.type: "full-library"` AND `scope.type: "public-api"` for such packages.
+
+  **Denominator:** the **union of named exports across the files each NON-WILDCARD `exports` subpath resolves to**. Resolve each subpath to its target file (or its committed `.d.ts` / `.d.mts` declaration), then apply the same multi-line brace-accumulation and `export *` star-resolution rules documented for barrel re-derivation earlier in this file ("TypeScript / JavaScript barrel re-derivation"). **Explicitly exclude wildcard subpaths** (`"./*"` forms — they map to an open-ended file set whose surface is unbounded and uncountable). If the `exports` map has only a root `"."` entry, or only wildcard subpaths, fall back to the standard root-barrel rule.
+
+  **Curation/priority (same ladder the specific-modules clause uses):** prefer `metadata.json.stats.effective_denominator` first (subject to the existing deflation guard), then `scope.tier_a_include` globs (filtered by `scope.exclude`, the umbrella-barrel note applies) when the brief supplies it, else the full subpath union.
+
+  **Audit:** the root-barrel named-export count must be reported as a **secondary candidate** in the Denominator Candidates audit block (coverage-check.md §4) so the root-barrel-vs-subpath-union choice is auditable. Annotate the coverage report with: `Multi-entry (exports-map) — denominator: {effective_denominator | tier_a_include union | subpath union} ({N} subpaths resolved, {M} exports union; root barrel: {R})`.
+
+  **When this clause does not apply:** monorepo packages (use the stratified-scope clause), empty-barrel packages (use the empty-barrel clause), pattern-reference apps (use the pattern-reference clause), `scope.type: "specific-modules"` (use the specific-modules clause), or single-entry / wildcard-only `exports` maps (use the standard root-barrel rule).
 
 Internal module symbols are **excluded** from the coverage denominator unless they are explicitly documented in SKILL.md (in which case they count as documented extras, not missing coverage).
 
@@ -136,6 +146,6 @@ Set `analysis_confidence` in context for use in Section 2 analysis depth, step 5
 
 **Degradation notice rules:** When `analysis_confidence` is `provenance-map`, check the `confidence` field of provenance-map entries before emitting a degradation recommendation:
 
-- **All/most entries T1 (AST-verified):** The provenance-map data is already at highest confidence. Do NOT recommend re-running with a local clone — it would produce identical results. Use: "Resolved via: provenance-map (T1 AST-verified at compilation time). Local clone not required — provenance data is already at highest confidence."
+- **All/most entries T1 (AST-verified):** The provenance-map data is already at highest confidence. Do not recommend re-running with a local clone — it would produce identical results. Use: "Resolved via: provenance-map (T1 AST-verified at compilation time). Local clone not required — provenance data is already at highest confidence."
 - **Mixed T1/T1-low entries:** Report the breakdown. Recommend local clone only for the T1-low entries: "Resolved via: provenance-map ({n} T1, {m} T1-low). Re-run with local clone to upgrade T1-low entries to full AST verification."
 - **All/most entries T1-low or lower:** Keep the standard recommendation: "Re-run with local clone for full AST-backed verification."

package/src/skf-test-skill/references/step-hard-gate.md

@@ -66,8 +66,6 @@ The hard gate passes. Medium, low, and info findings are documented in the gap r
 Update `{outputFile}` frontmatter:
 - Append `'hard-gate'` to `stepsCompleted`
 
-Report:
-
-"**Hard gate passed** — {N} medium/low/info finding(s) noted, proceeding to scoring."
+Report that the hard gate passed, noting the count of non-blocking medium/low/info finding(s), then proceed to scoring.
 
 Update stepsCompleted, then load and execute `{nextStepFile}`.

package/src/skf-test-skill/scripts/aggregate-coherence.py

@@ -0,0 +1,276 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""Deterministic contextual-coherence aggregator.
+
+Pure-function tally + weighted mean for the SKF test-skill workflow
+(step-04, coherence-check.md §5c). The prompt keeps the judgment — deciding
+which cross-references are valid (§4) and which integration patterns are
+complete (§5). This script does ONLY the arithmetic those judgments feed:
+the reference-validity ratio, the integration-completeness ratio, and their
+fixed 0.6 / 0.4 weighted mean. That way the 18%-weight `coherence` input to
+compute-score.py is computed once, deterministically, instead of by hand on
+every run (this skill grades other skills — a false PASS is catastrophic, so
+every scoring input is scripted for run-to-run reproducibility).
+
+Formula (mirrors scoring-rules.md "Coherence Score Aggregation (Contextual
+Mode)" — the prose there remains the documented contract):
+
+    reference_validity       = (valid_references / total_references) * 100
+    integration_completeness = (complete_patterns / total_patterns) * 100
+    combined_coherence       = reference_validity * 0.6 + integration_completeness * 0.4
+
+Field-name mapping: the step-04 §5 integration JSON calls the pattern counts
+`patterns_documented` (= total_patterns) and `patterns_complete`
+(= complete_patterns); this script's input uses those step-04 names directly
+so §5c passes them through unrenamed.
+
+Edge cases (both documented in scoring-rules.md — absence is never penalized):
+  * patterns_documented == 0 -> no integration patterns to weigh, so
+    combined_coherence == reference_validity and integrationCompleteness is
+    null. (Do not divide by zero.)
+  * total_references == 0 -> no references means no broken references, so
+    reference_validity == 100.0 (vacuously coherent). Unreachable on the normal
+    contextual path — §3 always extracts at least one reference — but handled so
+    the arithmetic never divides by zero.
+
+Input schema (one JSON object):
+  {
+    "valid_references":    <int >= 0, <= total_references>,
+    "total_references":    <int >= 0>,
+    "patterns_documented": <int >= 0>,
+    "patterns_complete":   <int >= 0, <= patterns_documented>
+  }
+
+Output (JSON):
+  {
+    "input": { ...echo... },
+    "referenceValidity":       <0-100>,
+    "integrationCompleteness": <0-100 | null when patterns_documented == 0>,
+    "combinedCoherence":       <0-100>,
+    "patternsScored":          <bool>
+  }
+  or {"error": ..., "code": "INVALID_INPUT"} on a schema violation.
+
+Percentages use the same JavaScript-compatible 2-decimal rounding as
+compute-score.py so the two scoring scripts agree to the last digit.
+
+CLI usage (mirrors compute-score.py):
+  uv run aggregate-coherence.py '<JSON>'                  # positional arg
+  uv run aggregate-coherence.py --json-input '<JSON>'     # explicit flag form
+  cat input.json | uv run aggregate-coherence.py --stdin  # piped input
+
+Exit codes:
+  0  — input was parsed; either a result object or a schema-validation error
+       object ({"error": ..., "code": "INVALID_INPUT"}) was emitted as JSON
+  1  — input could not be parsed at all (no input provided, or malformed JSON)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import sys
+
+# Weights for the combined-coherence mean (from scoring-rules.md). Kept as
+# named constants so the 0.6 / 0.4 split lives in exactly one place.
+REFERENCE_VALIDITY_WEIGHT = 0.6
+INTEGRATION_COMPLETENESS_WEIGHT = 0.4
+
+COUNT_FIELDS = (
+    "valid_references",
+    "total_references",
+    "patterns_documented",
+    "patterns_complete",
+)
+
+
+def round2(value):
+    """Round to 2 decimals with JavaScript-compatible half-up rounding.
+
+    Matches compute-score.py.round2 so both scoring scripts produce identical
+    numbers. JS Math.round rounds .5 away from zero for positives; Python's
+    built-in round uses banker's rounding. We replicate JS: floor(x*100+0.5)/100.
+    """
+    return math.floor(value * 100 + 0.5) / 100
+
+
+def make_error(message):
+    return {"error": message, "code": "INVALID_INPUT"}
+
+
+def validate_input(inp):
+    if inp is None or not isinstance(inp, dict):
+        return "Input must be a JSON object"
+
+    for field in COUNT_FIELDS:
+        if field not in inp or inp[field] is None:
+            return f"Missing required field: {field} (non-negative integer)"
+        value = inp[field]
+        # bool is a subclass of int; reject it so true/false can't pose as 1/0.
+        if isinstance(value, bool) or not isinstance(value, int):
+            return (
+                f"Field `{field}` must be a non-negative integer, "
+                f"got {type(value).__name__}: {value!r}"
+            )
+        if value < 0:
+            return f"Field `{field}` must be >= 0, got {value}"
+
+    if inp["valid_references"] > inp["total_references"]:
+        return (
+            "valid_references cannot exceed total_references "
+            f"({inp['valid_references']} > {inp['total_references']})"
+        )
+
+    if inp["patterns_complete"] > inp["patterns_documented"]:
+        return (
+            "patterns_complete cannot exceed patterns_documented "
+            f"({inp['patterns_complete']} > {inp['patterns_documented']})"
+        )
+
+    return None
+
+
+def aggregate_coherence(inp):
+    """Compute reference validity, integration completeness, and combined coherence.
+
+    Weighted mean of the two ratios (0.6 / 0.4), JS-compatible 2-decimal rounding:
+    >>> out = aggregate_coherence({"valid_references": 6, "total_references": 7,
+    ...                            "patterns_documented": 5, "patterns_complete": 4})
+    >>> out["referenceValidity"], out["integrationCompleteness"], out["combinedCoherence"]
+    (85.71, 80.0, 83.43)
+    >>> out["patternsScored"]
+    True
+
+    Zero integration patterns -> combined equals reference validity, no divide-by-zero:
+    >>> out = aggregate_coherence({"valid_references": 9, "total_references": 10,
+    ...                            "patterns_documented": 0, "patterns_complete": 0})
+    >>> out["integrationCompleteness"] is None
+    True
+    >>> out["patternsScored"]
+    False
+    >>> out["referenceValidity"], out["combinedCoherence"]
+    (90.0, 90.0)
+
+    Zero references -> vacuously perfect reference validity, never a ZeroDivision:
+    >>> aggregate_coherence({"valid_references": 0, "total_references": 0,
+    ...                      "patterns_documented": 2, "patterns_complete": 1})["referenceValidity"]
+    100.0
+
+    A schema violation returns an error object, not an exception:
+    >>> aggregate_coherence({"valid_references": 5, "total_references": 3,
+    ...                      "patterns_documented": 0, "patterns_complete": 0})["code"]
+    'INVALID_INPUT'
+    """
+    validation_error = validate_input(inp)
+    if validation_error:
+        return make_error(validation_error)
+
+    valid_references = inp["valid_references"]
+    total_references = inp["total_references"]
+    patterns_documented = inp["patterns_documented"]
+    patterns_complete = inp["patterns_complete"]
+
+    # Reference validity — vacuously 100 when there are no references at all.
+    if total_references == 0:
+        reference_validity = 100.0
+    else:
+        reference_validity = round2((valid_references / total_references) * 100)
+
+    # Integration completeness — absent when no patterns are documented.
+    patterns_scored = patterns_documented > 0
+    if patterns_scored:
+        integration_completeness = round2(
+            (patterns_complete / patterns_documented) * 100
+        )
+        combined_coherence = round2(
+            reference_validity * REFERENCE_VALIDITY_WEIGHT
+            + integration_completeness * INTEGRATION_COMPLETENESS_WEIGHT
+        )
+    else:
+        integration_completeness = None
+        combined_coherence = reference_validity
+
+    return {
+        "input": {field: inp[field] for field in COUNT_FIELDS},
+        "referenceValidity": reference_validity,
+        "integrationCompleteness": integration_completeness,
+        "combinedCoherence": combined_coherence,
+        "patternsScored": patterns_scored,
+    }
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="aggregate-coherence",
+        description=(
+            "Deterministic contextual-coherence aggregator. Input is a single "
+            "JSON object of reference + integration-pattern counts; output is the "
+            "reference-validity, integration-completeness, and combined-coherence "
+            "percentages that feed the `coherence` scoring input."
+        ),
+        epilog=(
+            "Example:\n"
+            "  uv run aggregate-coherence.py "
+            "'{\"valid_references\":6,\"total_references\":7,"
+            "\"patterns_documented\":5,\"patterns_complete\":4}'"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    src = parser.add_mutually_exclusive_group()
+    src.add_argument(
+        "json_input",
+        nargs="?",
+        help="JSON object as a positional argument (single-quote it on the shell).",
+    )
+    src.add_argument(
+        "--json-input",
+        dest="json_input_flag",
+        help="JSON object passed via flag (overrides positional).",
+    )
+    src.add_argument(
+        "--stdin",
+        action="store_true",
+        help="Read the JSON object from stdin.",
+    )
+    return parser
+
+
+def _resolve_input(args: argparse.Namespace) -> str:
+    if args.stdin:
+        return sys.stdin.read()
+    if args.json_input_flag is not None:
+        return args.json_input_flag
+    if args.json_input is not None:
+        return args.json_input
+    return ""
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    raw = _resolve_input(args)
+    if not raw.strip():
+        parser.print_usage(file=sys.stderr)
+        print(
+            "error: no input provided (positional arg, --json-input, or --stdin)",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        print(json.dumps(make_error(f"Invalid JSON: {exc.msg}"), indent=2))
+        return 1
+
+    result = aggregate_coherence(data)
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())