@cejel/cejel 0.4.1 → 0.4.3

package/README.md

@@ -68,7 +68,7 @@ if (-not $expected -or $actual -ne $expected.ToLowerInvariant()) {
 ```
 
 > **Windows signing status:** `cejel-Windows-x86_64.exe` is intentionally unsigned in
-> 0.4.1 and may trigger Microsoft SmartScreen. The release build removes Node's inherited
+> 0.4.3 and may trigger Microsoft SmartScreen. The release build removes Node's inherited
 > signature before SEA injection and fails unless Windows reports the result as `NotSigned`;
 > it does not ship an invalid signature. Before running it, verify `SHA256SUMS` and the
 > GitHub build-provenance attestation. Each binary also has an attached SPDX SBOM and an
@@ -91,7 +91,7 @@ docker run --rm --network=none -v "$PWD:/w" -w /w -v "$PWD/cejel:/cejel:ro" debi
 npx @cejel/cejel@latest .
 ```
 
-> **Distribution note:** Cejel `0.4.1` is the coordinated release version for npm,
+> **Distribution note:** Cejel `0.4.3` is the coordinated release version for npm,
 > standalone binaries, Docker/OCI, GitHub Action, Homebrew, and MCP Registry.
 
 `npx` can reuse a stale cached package. Force the current npm release with the `@latest`
@@ -105,7 +105,7 @@ If a root `package.json` still carries a template name, override only the certif
 name while keeping the repository-derived stable slug:
 
 ```bash
-npx @cejel/cejel . --name "Customer Portal"
+npx @cejel/cejel@latest . --name "Customer Portal"
 ```
 
 The npm package is scoped as `@cejel/cejel`; its executable remains the short command `cejel`.
@@ -140,16 +140,16 @@ gh attestation verify ./cejel-Windows-x86_64.exe -R BargLabs/cejel
 This is cryptographically signed provenance. It is distinct from Apple Developer ID or
 Microsoft Authenticode code-signing.
 
-**Docker / OCI.** The current container release is `0.4.1`:
+**Docker / OCI.** The current container release is `0.4.3`:
 
 ```bash
-docker run --rm -i -v "$PWD:/workspace:ro" ghcr.io/barglabs/cejel:0.4.1
+docker run --rm -i -v "$PWD:/workspace:ro" ghcr.io/barglabs/cejel:0.4.3
 ```
 
 The image defaults to `cejel-mcp` over stdio. To use the CLI instead:
 
 ```bash
-docker run --rm -v "$PWD:/workspace:ro" --entrypoint cejel ghcr.io/barglabs/cejel:0.4.1 .
+docker run --rm -v "$PWD:/workspace:ro" --entrypoint cejel ghcr.io/barglabs/cejel:0.4.3 .
 ```
 
 The OCI image carries an SBOM, maximum-mode build provenance, and a signed registry
@@ -162,7 +162,7 @@ projects, the public Cejel repository itself, and one explicitly labeled transpa
 snapshot from the private studio monorepo where Cejel was built, with a per-repository
 evidence report for every row under [`leaderboard/reports/`](./leaderboard/reports/). The
 board is also hosted at [cejel.dev](https://cejel.dev). Every score is produced by the same
-sealed public scorer used by `npx @cejel/cejel .`; no private domain collector contributes.
+sealed public scorer used by `npx @cejel/cejel@latest .`; no private domain collector contributes.
 For each public-repository row, check out the immutable source commit printed in its report
 and run the public scorer to reproduce the score, verdict, measured coverage, and evidence.
 The private Alfred snapshot discloses its limitation instead: its source commit and withheld
@@ -426,7 +426,7 @@ The OCI image is an alternative when Docker is the preferred execution boundary.
 the host path with the repository OpenClaw should allow Cejel to read:
 
 ```bash
-openclaw mcp set cejel-oci '{"command":"docker","args":["run","--rm","-i","-v","/absolute/path/to/repo:/workspace:ro","ghcr.io/barglabs/cejel:0.4.1"]}'
+openclaw mcp set cejel-oci '{"command":"docker","args":["run","--rm","-i","-v","/absolute/path/to/repo:/workspace:ro","ghcr.io/barglabs/cejel:0.4.3"]}'
 openclaw mcp doctor cejel-oci --probe
 ```
 

package/dist/{chunk-HG5NAFH5.js → chunk-ITHPLYKX.js}

@@ -4531,6 +4531,317 @@ function collectExternalFindings(consumedSignals) {
 
 // src/witan/finding-presentation.ts
 init_esm_shims();
+
+// src/witan/certificate-presentation.ts
+init_esm_shims();
+var CERTIFICATE_GLOSSARY = [
+  {
+    key: "labels",
+    term: "labels / why the labels differ",
+    definition: "Three labels can appear on one line because they answer three different questions. Finding severity describes how serious one issue is. The dimension band summarizes the criterion evidence. The numeric band comes from the weighted score.",
+    metricNames: []
+  },
+  {
+    key: "capped",
+    term: "capped",
+    definition: "Credit stops increasing after the maximum defined by the scoring rubric, even when the raw count is higher. Caps are fixed per rubric version because they are part of what was calibrated. Extra volume therefore cannot outweigh the rest of the rubric.",
+    metricNames: []
+  },
+  {
+    key: "test-to-source-file-ratio",
+    term: "test-to-source file ratio",
+    definition: "The number of detected test files compared with detected source files. A larger implementation surface needs a correspondingly visible test surface.",
+    metricNames: ["test_to_source_ratio"]
+  },
+  {
+    key: "static-coverage",
+    term: "static coverage",
+    definition: "A percentage read from a coverage report or threshold that the repository itself publishes. Cejel does not run the repository's tests. The scoring rubric defines how much credit the published percentage receives.",
+    metricNames: ["coverage_percent"]
+  },
+  {
+    key: "verification-script",
+    term: "verification script",
+    definition: "the checks that run automatically: tests, linting, type-checking, build",
+    metricNames: ["verification_script_ratio"]
+  },
+  {
+    key: "non-hollow",
+    term: "non-hollow",
+    definition: "test files that actually assert something rather than being empty or skipped",
+    metricNames: ["non_hollow_test_share"]
+  },
+  {
+    key: "secrets",
+    term: "secrets",
+    definition: "credentials like API keys and tokens",
+    metricNames: ["secret_cleanliness"]
+  },
+  {
+    key: "environment-handling-depth",
+    term: "environment handling depth",
+    definition: "The visible controls for keeping environment-specific configuration and credentials out of source. Unsafe configuration handling can expose production access.",
+    metricNames: ["env_handling_depth"]
+  },
+  {
+    key: "rls-policy-count",
+    term: "RLS policy count",
+    definition: "The number of detected database row-level security policies. Those policies can enforce which rows each tenant or user may reach.",
+    metricNames: ["rls_policy_count"]
+  },
+  {
+    key: "tenant-scoped-schema-ratio",
+    term: "tenant-scoped schema ratio",
+    definition: "The share of relevant database tables with a visible tenant boundary. Missing tenant scope can allow one customer's data to mix with another's.",
+    metricNames: ["tenant_scope_ratio"]
+  },
+  {
+    key: "crypto-comparison-hygiene",
+    term: "crypto comparison hygiene",
+    definition: "Comparisons of secret values that take the same time whether or not the values match. Attackers therefore cannot recover secrets by measuring response times.",
+    metricNames: ["crypto_comparison_hygiene"]
+  },
+  {
+    key: "basic-checks",
+    term: "basic checks",
+    definition: "In code trust, production-readiness basic checks cover build or type-check commands, automated pipelines, deployment configuration, environment templates, health checks, and error boundaries. In process trust, PR trace basic checks cover automated pipelines, pull-request templates, and review-gate records. Missing checks leave part of the acceptance path unsupported.",
+    metricNames: ["prod_readiness_primitives", "pr_trace_primitives"]
+  },
+  {
+    key: "workflow-depth",
+    term: "workflow depth",
+    definition: "Workflows here are automated build, test, or release pipelines, such as GitHub Actions, not team policy. This measures how many relevant pipeline stages Cejel can see rather than how many workflow files exist. A deeper pipeline checks more of the path to a release.",
+    metricNames: ["prod_workflow_depth"]
+  },
+  {
+    key: "observability-depth",
+    term: "observability depth",
+    definition: "The visible health, logging, and error-reporting controls. Operators need evidence that failures can be detected and investigated.",
+    metricNames: ["observability_depth"]
+  },
+  {
+    key: "rollback-and-migration-safety-depth",
+    term: "rollback and migration-safety depth",
+    definition: "The visible procedures and checks for reversing a release or changing stored data safely. Recovery and data changes are high-risk parts of accepting software.",
+    metricNames: ["rollback_safety_depth"]
+  },
+  {
+    key: "dependency-automation-ratio",
+    term: "dependency automation ratio",
+    definition: "The share of expected automated dependency-update and audit controls that are present. Stale or vulnerable packages otherwise depend on manual discovery.",
+    metricNames: ["dependency_automation_ratio"]
+  },
+  {
+    key: "pinned-dependency-ratio",
+    term: "pinned dependency ratio",
+    definition: "The share of application dependencies fixed to exact versions. Exact inputs make deployed builds more reproducible.",
+    metricNames: ["pinned_dependency_ratio"]
+  },
+  {
+    key: "lockfile-coverage",
+    term: "lockfile coverage",
+    definition: "Whether the package manifests are backed by committed lockfiles. Lockfiles record the exact dependency versions selected for a build.",
+    metricNames: ["lockfile_coverage"]
+  },
+  {
+    key: "declared-version-range-ratio",
+    term: "declared version range ratio",
+    definition: "The share of library dependencies with an explicit compatible version range. Unconstrained dependencies can change without a deliberate source change.",
+    metricNames: ["declared_version_range_ratio"]
+  },
+  {
+    key: "dependency-count-sanity",
+    term: "dependency count sanity",
+    definition: "A bounded check for an unusually long list of direct dependencies for a library. Every direct dependency adds maintenance and supply-chain exposure.",
+    metricNames: ["dependency_count_sanity"]
+  },
+  {
+    key: "claim-match-rate",
+    term: "claim match rate",
+    definition: "The share of documented product claims that match visible repository evidence. An acceptance claim should be checkable against the delivered revision.",
+    metricNames: ["claim_match_rate"]
+  },
+  {
+    key: "claim-source-depth",
+    term: "claim source depth",
+    definition: "How much concrete, checkable claim material is present. Vague or missing claims give a relying party nothing specific to verify.",
+    metricNames: ["claim_source_depth"]
+  },
+  {
+    key: "reconciliation-artifact-depth",
+    term: "reconciliation artifact depth",
+    definition: "The visible records connecting stated claims to evidence. A relying party needs to trace what was promised to what was inspected.",
+    metricNames: ["reconciliation_artifact_depth"]
+  },
+  {
+    key: "recent-pr-merge-ratio",
+    term: "recent PR merge ratio",
+    definition: "The share of recent visible commits associated with merged pull requests. Review history helps a relying party inspect how changes reached the revision.",
+    metricNames: ["pr_merge_ratio"]
+  },
+  {
+    key: "ci-verification-depth",
+    term: "CI verification depth",
+    definition: "The number of test, lint, type-check, and build categories Cejel sees running in continuous integration. Automated gates make checks repeatable for each change.",
+    metricNames: ["ci_script_depth"]
+  },
+  {
+    key: "pr-gate-ci-workflow-count",
+    term: "PR-gate CI workflow count",
+    definition: "Workflows here are automated build and test pipelines, such as GitHub Actions, not team policy. This counts pipelines that visibly run on pull requests or the default branch. Checks that never gate changes cannot support the acceptance decision.",
+    metricNames: ["default_branch_ci_depth"]
+  },
+  {
+    key: "audit-artifact-depth",
+    term: "audit artifact depth",
+    definition: "How many durable audit records such as changelogs, incident notes, or security records are present. Past operational decisions should remain inspectable.",
+    metricNames: ["audit_artifact_depth"]
+  },
+  {
+    key: "audit-freshness-depth",
+    term: "audit freshness depth",
+    definition: "How recently the visible audit records were maintained. Stale records may not describe the revision being accepted.",
+    metricNames: ["audit_freshness_depth"]
+  },
+  {
+    key: "un-overridable-kill-switch",
+    term: "un-overridable kill-switch",
+    definition: "A stop control that ordinary automation cannot bypass. Operators need a dependable way to halt privileged behavior.",
+    metricNames: ["kill_switch_fail_safe_present"]
+  },
+  {
+    key: "human-gate-documented",
+    term: "human gate documented",
+    definition: "A written requirement for a person to approve sensitive operations. High-impact actions should not rely only on unattended automation.",
+    metricNames: ["human_gate_documented"]
+  },
+  {
+    key: "fail-closed-privilege-check",
+    term: "fail-closed privilege check",
+    definition: "A permission check that refuses the operation when it cannot reach a confident allow decision. Errors must not silently grant elevated access.",
+    metricNames: ["fail_closed_privilege_check"]
+  },
+  {
+    key: "privilege-escalation-cleanliness",
+    term: "privilege-escalation cleanliness",
+    definition: "The absence of detected patterns that unsafely widen permissions. Unnecessary elevation increases the impact of a mistake or compromise.",
+    metricNames: ["privilege_escalation_cleanliness"]
+  },
+  {
+    key: "protected-path-review-gate",
+    term: "protected-path review gate",
+    definition: "A rule requiring review before sensitive files or directories can change. Critical controls deserve an explicit second check.",
+    metricNames: ["protected_path_review_gate"]
+  }
+];
+var GLOSSARY_BY_METRIC = new Map(
+  CERTIFICATE_GLOSSARY.flatMap(
+    (entry) => entry.metricNames.map((metricName) => [metricName, entry])
+  )
+);
+function glossaryEntryForMetric(metric2) {
+  return GLOSSARY_BY_METRIC.get(metric2.name) ?? {
+    key: `metric-${metric2.name.replace(/[^a-z0-9-]+/gi, "-").toLowerCase()}`,
+    term: formatCertificateMetricLabel(metric2),
+    definition: metric2.description ? `${metric2.description} This measurement contributes to the criterion score.` : "A measured input to this criterion. This measurement contributes to the criterion score.",
+    metricNames: [metric2.name]
+  };
+}
+var CERTIFICATE_METRIC_LABELS = {
+  prod_readiness_primitives: "Production-readiness basic checks",
+  pr_trace_primitives: "PR trace basic checks",
+  prod_workflow_depth: "Production workflow depth (automated build/test/release pipeline)",
+  default_branch_ci_depth: "PR-gate CI workflow count (automated build/test pipeline)"
+};
+function formatCertificateMetricLabel(metric2) {
+  return CERTIFICATE_METRIC_LABELS[metric2.name] ?? metric2.label;
+}
+function glossaryEntriesForReport(report) {
+  const entries = new Map(CERTIFICATE_GLOSSARY.map((entry) => [entry.key, entry]));
+  for (const metric2 of report.criteria.flatMap((criterion) => criterion.metrics)) {
+    const entry = glossaryEntryForMetric(metric2);
+    entries.set(entry.key, entry);
+  }
+  return [...entries.values()];
+}
+function isCoverageNotMeasured(criterion, metric2) {
+  if (metric2.name !== "coverage_percent" || metric2.value !== 0) return false;
+  return ![
+    ...criterion.evidence,
+    ...criterion.findings.map((finding) => finding.evidence)
+  ].some((evidence) => evidence.kind === "coverage");
+}
+function labelAlreadyStatesUnit(label, unit) {
+  if (!unit) return false;
+  const escapedUnit = unit.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(?:^|[\\s-])${escapedUnit}$`, "i").test(label.trim());
+}
+function formatCertificateMetricValue(criterion, metric2) {
+  if (isCoverageNotMeasured(criterion, metric2)) {
+    return "no coverage report found \u2014 not measured";
+  }
+  if (metric2.name === "test_to_source_ratio" && metric2.max !== void 0) {
+    const tests = formatMetricNumber(metric2.value);
+    const sources = formatMetricNumber(metric2.max);
+    const comparison = `${tests} test file${metric2.value === 1 ? "" : "s"} / ${sources} source file${metric2.max === 1 ? "" : "s"}`;
+    return metric2.value > metric2.max ? `${comparison} (credit capped at parity)` : comparison;
+  }
+  const displayUnit = metric2.name === "prod_readiness_primitives" || metric2.name === "pr_trace_primitives" ? "checks" : labelAlreadyStatesUnit(formatCertificateMetricLabel(metric2), metric2.unit) ? void 0 : metric2.unit;
+  const unit = displayUnit ? ` ${displayUnit}` : "";
+  if (metric2.max === void 0) return `${formatMetricNumber(metric2.value)}${unit}`;
+  if (metric2.kind === "saturating_count" && metric2.value > metric2.max) {
+    return `${formatMetricNumber(metric2.max)}${unit} (capped; ${formatMetricNumber(metric2.value)} raw)`;
+  }
+  return `${formatMetricNumber(metric2.value)}/${formatMetricNumber(metric2.max)}${unit}`;
+}
+function buildRelyingPartySummary(report) {
+  const applicable = report.criteria.filter((criterion) => criterion.status !== "not_applicable");
+  const measured = applicable.filter((criterion) => criterion.status !== "insufficient_data");
+  const findings = report.criteria.reduce((sum, criterion) => sum + criterion.findings.length, 0);
+  const revision = report.repo.headSha ? ` at revision ${report.repo.headSha}` : " from the repository snapshot named in this report; no Git revision was available";
+  const a1 = report.criteria.find((criterion) => criterion.id === "A1");
+  const coverageMetric = a1?.metrics.find((metric2) => metric2.name === "coverage_percent");
+  const gaps = [];
+  if (a1 && coverageMetric && isCoverageNotMeasured(a1, coverageMetric)) {
+    gaps.push(
+      "No coverage report or configured threshold was found, so static coverage was not measured; Cejel does not run the subject's tests."
+    );
+  }
+  const unmeasured = applicable.filter((criterion) => criterion.status === "insufficient_data");
+  if (unmeasured.length > 0) {
+    gaps.push(`The report did not measure ${unmeasured.map((criterion) => criterion.id).join(", ")}.`);
+  }
+  const notApplicable = report.criteria.filter((criterion) => criterion.status === "not_applicable");
+  if (notApplicable.length > 0) {
+    gaps.push(
+      `${notApplicable.map((criterion) => criterion.id).join(", ")} ${notApplicable.length === 1 ? "was" : "were"} marked not applicable and therefore not examined.`
+    );
+  }
+  if ((report.scanLimitations?.length ?? 0) > 0) {
+    const count = report.scanLimitations?.length ?? 0;
+    gaps.push(`${count} scan limitation${count === 1 ? "" : "s"} qualifies the readable evidence.`);
+  }
+  if ((report.contentReadSummary?.skipped ?? 0) > 0) {
+    const skipped = report.contentReadSummary?.skipped ?? 0;
+    gaps.push(
+      `${skipped} content entr${skipped === 1 ? "y was" : "ies were"} skipped for the reasons itemized in the certificate.`
+    );
+  }
+  gaps.push(
+    "Anything absent from the measured evidence was not established: no measurement and no finding are not clearance."
+  );
+  return {
+    examined: `Cejel examined the repository evidence recorded for ${report.productDisplayName}${revision} under ${report.rubricVersion}.`,
+    established: `The report established measured results for ${measured.length} of ${applicable.length} applicable rubric dimensions and recorded ${findings} evidence-backed finding${findings === 1 ? "" : "s"}.`,
+    notEstablished: gaps.join(" "),
+    next: "Review the cited evidence and open or unverified items, reproduce the scan at the reported revision when one is available, and obtain missing measurements or resolve limitations before deciding whether to accept the code."
+  };
+}
+function formatMetricNumber(value) {
+  return Number.isInteger(value) ? String(value) : value.toFixed(2).replace(/0+$/, "").replace(/\.$/, "");
+}
+
+// src/witan/finding-presentation.ts
 var METRIC_DERIVED_FINDING_PATTERN = /^[A-Z]\d+ metric-derived score is (\d+\.\d)\/4\.0, in the (critical|warning) band — no single finding drove this; it reflects the combined metric weighting below\.$/;
 var REMEDIATION_BY_METRIC = {
   test_to_source_ratio: "add concrete regression tests for the implementation surface",
@@ -4575,18 +4886,18 @@ function renderFindingSummary(criterion, finding) {
   if (drivers.length === 0) {
     return `${criterion.id} dimension band is ${band} at ${score}/4.0. To improve this dimension, add stronger measurable evidence for ${criterion.title.toLowerCase()}.`;
   }
-  const measurements = drivers.map(formatMetricMember).join("; ");
+  const measurements = drivers.map((metric2) => formatMetricMember(criterion, metric2)).join("; ");
   const actions = Array.from(
     new Set(
       drivers.map(
-        (metric2) => REMEDIATION_BY_METRIC[metric2.name] ?? `raise the measured ${metric2.label.toLowerCase()}`
+        (metric2) => REMEDIATION_BY_METRIC[metric2.name] ?? `raise the measured ${formatCertificateMetricLabel(metric2).toLowerCase()}`
       )
     )
   ).join("; ");
   return `${criterion.id} dimension band is ${band} at ${score}/4.0. Lowest contributing measurements: ${measurements}. To improve: ${actions}.`;
 }
 function selectLowestDrivers(metrics) {
-  return [...metrics].filter((metric2) => metric2.max !== void 0).sort((left, right) => {
+  return [...metrics].filter((metric2) => metric2.max !== void 0 && normalizedMetricValue(metric2) < 1).sort((left, right) => {
     const leftRatio = normalizedMetricValue(left);
     const rightRatio = normalizedMetricValue(right);
     if (leftRatio !== rightRatio) return leftRatio - rightRatio;
@@ -4598,17 +4909,8 @@ function normalizedMetricValue(metric2) {
   if (metric2.max === void 0) return 1;
   return Math.min(metric2.value / metric2.max, 1);
 }
-function formatMetricMember(metric2) {
-  const unit = metric2.unit ? ` ${metric2.unit}` : "";
-  const maximum = metric2.max;
-  if (maximum === void 0) return `${metric2.label} ${formatMetricValue(metric2.value)}${unit}`;
-  if (metric2.kind === "saturating_count" && metric2.value > maximum) {
-    return `${metric2.label} ${formatMetricValue(maximum)}${unit} capped (${formatMetricValue(metric2.value)} raw)`;
-  }
-  return `${metric2.label} ${formatMetricValue(metric2.value)}/${formatMetricValue(maximum)}${unit}`;
-}
-function formatMetricValue(value) {
-  return Number.isInteger(value) ? String(value) : value.toFixed(2).replace(/0+$/, "").replace(/\.$/, "");
+function formatMetricMember(criterion, metric2) {
+  return `${formatCertificateMetricLabel(metric2)} ${formatCertificateMetricValue(criterion, metric2)}`;
 }
 
 // src/witan/html.ts
@@ -4624,6 +4926,7 @@ function renderWitanHtmlReport(report, options = {}) {
   const externalFindings = collectExternalFindings(report.consumedSignals ?? []);
   const coverage = computeMeasuredCoverage(report);
   const gitHistoryUnavailable = !report.repo.headSha;
+  const relyingPartySummary = buildRelyingPartySummary(report);
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -4666,6 +4969,8 @@ function renderWitanHtmlReport(report, options = {}) {
       </div>
     </header>
 
+    ${renderRelyingPartySummary(relyingPartySummary)}
+
     ${(report.scanLimitations?.length ?? 0) > 0 ? `<section class="scan-limitations-section evidence-section" aria-label="Scan limitations">
       <h2>Scan limitations</h2>
       <ul>${(report.scanLimitations ?? []).map(
@@ -4698,11 +5003,32 @@ function renderWitanHtmlReport(report, options = {}) {
         <ul>${renderExternalFindingItems(externalFindings).join("")}</ul>
       </article>
     </section>` : ""}
+
+    ${renderGlossary(glossaryEntriesForReport(report))}
   </main>
 </body>
 </html>
 `;
 }
+function renderRelyingPartySummary(summary) {
+  return `<section class="relying-party-summary" aria-labelledby="relying-party-heading">
+      <h2 id="relying-party-heading">How to read this certificate</h2>
+      <dl>
+        <div><dt>What was examined</dt><dd>${escapeHtml(summary.examined)}</dd></div>
+        <div><dt>What was established</dt><dd>${escapeHtml(summary.established)}</dd></div>
+        <div><dt>What was not established</dt><dd>${escapeHtml(summary.notEstablished)}</dd></div>
+        <div><dt>What to do next</dt><dd>${escapeHtml(summary.next)}</dd></div>
+      </dl>
+    </section>`;
+}
+function renderGlossary(entries) {
+  return `<section class="glossary" aria-labelledby="glossary-heading">
+      <h2 id="glossary-heading">Plain-language glossary</h2>
+      <dl>${entries.map(
+    (entry) => `<div><dt id="glossary-${escapeAttribute(entry.key)}">${escapeHtml(entry.term)}</dt><dd>${escapeHtml(entry.definition)}</dd></div>`
+  ).join("")}</dl>
+    </section>`;
+}
 function renderContentReadSummary(report) {
   const summary = report.contentReadSummary;
   if (!summary || summary.skipped === 0) return "";
@@ -4791,7 +5117,7 @@ function renderCriterionCard(criterion, gitHistoryUnavailable) {
     ...criterion.evidence.map(renderEvidencePointer),
     ...criterion.findings.map((finding) => renderFindingEvidence(criterion, finding))
   ];
-  const metrics = criterion.metrics.map(renderMetric);
+  const metrics = criterion.metrics.map((metric2) => renderMetric(criterion, metric2));
   const statusReconciliation = renderStatusReconciliation(criterion);
   const historyWarning = gitHistoryUnavailable && criterion.metrics.some((metric2) => metric2.name === "pr_merge_ratio") ? `<p class="scan-warning"><strong>Scan limitation:</strong> Git history was unavailable (for example, this may be a source tarball), so the recent PR merge ratio is not a measured repository outcome and its displayed zero may undercount ${escapeHtml(criterion.id)}. Re-scan a full Git clone for this signal.</p>` : "";
   return `<article class="criterion">
@@ -4800,7 +5126,7 @@ function renderCriterionCard(criterion, gitHistoryUnavailable) {
                 <div class="criterion-id">${escapeHtml(criterion.id)}</div>
                 <h3>${escapeHtml(criterion.title)}</h3>
               </div>
-              ${renderStatusChip(criterion.status)}
+              ${renderStatusChip(criterion.id, criterion.status)}
             </div>
             <div class="criterion-score">${criterion.status === "not_applicable" ? "N/A" : criterion.status === "insufficient_data" ? "No data" : formatScore(criterion.score)}</div>
             ${statusReconciliation}
@@ -4819,7 +5145,9 @@ function renderStatusReconciliation(criterion) {
   }
   const numericBand = scoreBandForPresentation(criterion.score);
   if (numericBand === criterion.status) return "";
-  return `<p class="status-explanation"><strong>Why the labels differ:</strong> the ${escapeHtml(criterion.status)} dimension band is calibrated from criterion evidence thresholds and findings, independently of the ${formatScore(criterion.score)}/4.0 weighted score (which falls in the ${numericBand} numeric band).</p>`;
+  const entry = CERTIFICATE_GLOSSARY.find((candidate) => candidate.key === "labels");
+  const help = entry ? `<span class="term-help" tabindex="0" aria-describedby="tooltip-${criterion.id}-labels"><strong>Why the labels differ:</strong><span class="term-tooltip" id="tooltip-${criterion.id}-labels" role="tooltip">${escapeHtml(entry.definition)}</span></span>` : "<strong>Why the labels differ:</strong>";
+  return `<p class="status-explanation">${help} the ${escapeHtml(criterion.status)} dimension band is calibrated from criterion evidence thresholds and findings, independently of the ${formatScore(criterion.score)}/4.0 weighted score (which falls in the ${numericBand} numeric band).</p>`;
 }
 function scoreBandForPresentation(score) {
   if (score >= 3.5) return "verified";
@@ -4827,20 +5155,24 @@ function scoreBandForPresentation(score) {
   if (score >= 1.5) return "warning";
   return "critical";
 }
-function renderMetric(metric2) {
-  const unit = metric2.unit ? ` ${escapeHtml(metric2.unit)}` : "";
-  if (metric2.kind === "saturating_count" && metric2.max !== void 0 && metric2.value > metric2.max) {
-    return `<strong>${escapeHtml(metric2.label)}</strong><span>${formatMetricValue2(metric2.max)}${unit} (capped; ${formatMetricValue2(metric2.value)} raw)</span>`;
-  }
-  const max = metric2.max ? `/${formatMetricValue2(metric2.max)}` : "";
-  return `<strong>${escapeHtml(metric2.label)}</strong><span>${formatMetricValue2(metric2.value)}${max}${unit}</span>`;
+function renderMetric(criterion, metric2) {
+  const entry = glossaryEntryForMetric(metric2);
+  const tooltipId = `tooltip-${criterion.id}-${entry.key}`;
+  const formatted = formatCertificateMetricValue(criterion, metric2);
+  const cappedEntry = formatted.includes("capped") ? CERTIFICATE_GLOSSARY.find((candidate) => candidate.key === "capped") : void 0;
+  const label = `<span class="term-help" tabindex="0" aria-describedby="${escapeAttribute(tooltipId)}"><strong>${escapeHtml(formatCertificateMetricLabel(metric2))}</strong><span class="term-tooltip" id="${escapeAttribute(tooltipId)}" role="tooltip">${escapeHtml(entry.definition)}</span></span>`;
+  if (!cappedEntry) return `${label}<span>${escapeHtml(formatted)}</span>`;
+  const cappedTooltipId = `${tooltipId}-capped`;
+  return `${label}<span class="term-help metric-value" tabindex="0" aria-describedby="${escapeAttribute(cappedTooltipId)}">${escapeHtml(formatted)}<span class="term-tooltip" id="${escapeAttribute(cappedTooltipId)}" role="tooltip">${escapeHtml(cappedEntry.definition)}</span></span>`;
 }
 function renderCategoryScore(score, coverage, category) {
   const categoryCoverage = coverage.byCategory.find((entry) => entry.category === category);
   return categoryCoverage !== void 0 && categoryCoverage.measured === 0 || score === null ? "not measured" : formatScore(score);
 }
-function renderStatusChip(status) {
-  return `<span class="status" data-status="${status}">dimension band: ${status}</span>`;
+function renderStatusChip(criterionId, status) {
+  const entry = CERTIFICATE_GLOSSARY.find((candidate) => candidate.key === "labels");
+  const tooltipId = `tooltip-${criterionId}-status-labels`;
+  return `<span class="status term-help" data-status="${status}" tabindex="0" aria-describedby="${tooltipId}">dimension band: ${status}${entry ? `<span class="term-tooltip" id="${tooltipId}" role="tooltip">${escapeHtml(entry.definition)}</span>` : ""}</span>`;
 }
 function renderEvidenceListItem(criterion, evidence) {
   return `<li><strong>${escapeHtml(criterion.id)} - ${escapeHtml(criterion.title)}</strong><span>${renderEvidencePointer(evidence)}</span></li>`;
@@ -4904,9 +5236,6 @@ function renderMachineVerdict(verdict) {
 function formatScore(score) {
   return score.toFixed(1);
 }
-function formatMetricValue2(value) {
-  return Number.isInteger(value) ? value.toString() : value.toFixed(2);
-}
 function formatDate(value) {
   return value.slice(0, 10);
 }
@@ -4982,6 +5311,13 @@ dd { margin: 0; color: var(--muted); overflow-wrap: anywhere; }
 .subscores { display: flex; gap: 12px; flex-wrap: wrap; margin-top: 18px; color: var(--muted); font-family: var(--mono); font-size: 12px; }
 .coverage-note { margin-top: 8px; color: var(--faint); font-family: var(--mono); font-size: 11px; }
 .source-counts { margin: 8px 0 0; padding-left: 18px; font-family: var(--mono); font-size: 12px; color: var(--muted); }
+.relying-party-summary, .glossary { margin-top: 28px; border: 1px solid var(--line-strong); border-radius: 8px; background: var(--surface); padding: 22px; }
+.relying-party-summary dl { display: grid; gap: 14px; margin: 0; }
+.relying-party-summary dl div { display: grid; grid-template-columns: 190px minmax(0, 1fr); gap: 18px; }
+.relying-party-summary dt, .glossary dt { color: var(--text); }
+.glossary dl { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 12px 22px; margin: 0; }
+.glossary dl div { border-top: 1px solid var(--line); padding-top: 10px; }
+.glossary dd { margin-top: 4px; font-size: 13px; }
 .trust-grid, .evidence-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 18px; margin-top: 28px; }
 .scan-limitations-section { margin-top: 28px; border-color: rgba(231, 191, 114, .44); }
 .scan-limitations-section .scan-warning { list-style: none; margin-left: -18px; }
@@ -5011,6 +5347,19 @@ h3 { font-size: 15px; line-height: 1.35; font-weight: 600; margin-bottom: 0; }
 .criterion-metrics li { display: flex; justify-content: space-between; gap: 12px; border-bottom: 1px solid rgba(238, 244, 247, .08); padding-bottom: 6px; }
 .criterion-metrics strong { color: var(--text); font-weight: 650; }
 .criterion-metrics span { white-space: nowrap; color: var(--muted); }
+.term-help { position: relative; cursor: help; outline: none; }
+.term-help:focus-visible { box-shadow: 0 0 0 2px var(--periwinkle); border-radius: 3px; }
+.term-tooltip {
+  position: absolute; z-index: 100; left: 0; bottom: calc(100% + 8px); width: min(320px, 75vw);
+  visibility: hidden; opacity: 0; pointer-events: none; white-space: normal;
+  border: 1px solid var(--line-strong); border-radius: 6px; padding: 9px 11px;
+  background: #101b2a; color: var(--text); font-family: var(--sans); font-size: 12px;
+  font-weight: 400; line-height: 1.45; text-transform: none; letter-spacing: normal;
+  box-shadow: 0 10px 28px rgba(0, 0, 0, .55);
+  transition: opacity .12s ease;
+}
+.term-help:hover > .term-tooltip, .term-help:focus-within > .term-tooltip { visibility: visible; opacity: 1; }
+.metric-value .term-tooltip { left: auto; right: 0; }
 .status { flex: none; border-radius: 999px; padding: 4px 9px; font-family: var(--mono); font-size: 11px; border: 1px solid var(--line-strong); }
 .status[data-status="verified"] { color: var(--teal); background: var(--teal-weak); border-color: rgba(47, 200, 166, .42); }
 .status[data-status="info"] { color: var(--periwinkle); background: var(--periwinkle-weak); border-color: rgba(147, 166, 218, .4); }
@@ -5029,6 +5378,7 @@ a:hover { text-decoration: underline; text-underline-offset: 2px; }
 @media (max-width: 840px) {
   .certificate { padding: 28px 18px 48px; }
   .hero-grid, .trust-grid, .evidence-grid { grid-template-columns: 1fr; }
+  .relying-party-summary dl div, .glossary dl { grid-template-columns: 1fr; }
   h1 { font-size: 46px; }
 }
 `;
@@ -6784,7 +7134,7 @@ function collectA3ProdReadinessEvidence(repoPath, repoFiles, useV27Detectors) {
     metrics: [
       metric(
         "prod_readiness_primitives",
-        "Production-readiness primitive coverage",
+        "Production-readiness basic checks",
         [
           packageJson && (scripts.has("build") || scripts.has("typecheck")),
           workflows.length > 0,
@@ -6795,8 +7145,8 @@ function collectA3ProdReadinessEvidence(repoPath, repoFiles, useV27Detectors) {
         ].filter(Boolean).length,
         6,
         0.55,
-        "primitives",
-        "Counts distinct static production-readiness primitives instead of treating presence as enough."
+        "checks",
+        "Counts distinct static production-readiness checks instead of treating presence as enough."
       ),
       metric(
         "prod_workflow_depth",
@@ -7137,7 +7487,7 @@ function collectB2PrTraceEvidence(repoPath, repoFiles) {
       // sat well under half credit here even with a healthy PR-trace posture.
       metric(
         "pr_trace_primitives",
-        "PR trace primitive coverage",
+        "PR trace basic checks",
         workflows.length + (prTemplate ? 1 : 0) + (branchProtectionDoc ? 1 : 0),
         2,
         0.8,
@@ -10982,18 +11332,18 @@ function renderFindingSummary2(criterion, finding) {
   if (drivers.length === 0) {
     return `${criterion.id} dimension band is ${band} at ${score}/4.0. To improve this dimension, add stronger measurable evidence for ${criterion.title.toLowerCase()}.`;
   }
-  const measurements = drivers.map(formatMetricMember2).join("; ");
+  const measurements = drivers.map((metric2) => formatMetricMember2(criterion, metric2)).join("; ");
   const actions = Array.from(
     new Set(
       drivers.map(
-        (metric2) => REMEDIATION_BY_METRIC2[metric2.name] ?? `raise the measured ${metric2.label.toLowerCase()}`
+        (metric2) => REMEDIATION_BY_METRIC2[metric2.name] ?? `raise the measured ${formatCertificateMetricLabel(metric2).toLowerCase()}`
       )
     )
   ).join("; ");
   return `${criterion.id} dimension band is ${band} at ${score}/4.0. Lowest contributing measurements: ${measurements}. To improve: ${actions}.`;
 }
 function selectLowestDrivers2(metrics) {
-  return [...metrics].filter((metric2) => metric2.max !== void 0).sort((left, right) => {
+  return [...metrics].filter((metric2) => metric2.max !== void 0 && normalizedMetricValue2(metric2) < 1).sort((left, right) => {
     const leftRatio = normalizedMetricValue2(left);
     const rightRatio = normalizedMetricValue2(right);
     if (leftRatio !== rightRatio) return leftRatio - rightRatio;
@@ -11005,17 +11355,8 @@ function normalizedMetricValue2(metric2) {
   if (metric2.max === void 0) return 1;
   return Math.min(metric2.value / metric2.max, 1);
 }
-function formatMetricMember2(metric2) {
-  const unit = metric2.unit ? ` ${metric2.unit}` : "";
-  const maximum = metric2.max;
-  if (maximum === void 0) return `${metric2.label} ${formatMetricValue3(metric2.value)}${unit}`;
-  if (metric2.kind === "saturating_count" && metric2.value > maximum) {
-    return `${metric2.label} ${formatMetricValue3(maximum)}${unit} capped (${formatMetricValue3(metric2.value)} raw)`;
-  }
-  return `${metric2.label} ${formatMetricValue3(metric2.value)}/${formatMetricValue3(maximum)}${unit}`;
-}
-function formatMetricValue3(value) {
-  return Number.isInteger(value) ? String(value) : value.toFixed(2).replace(/0+$/, "").replace(/\.$/, "");
+function formatMetricMember2(criterion, metric2) {
+  return `${formatCertificateMetricLabel(metric2)} ${formatCertificateMetricValue(criterion, metric2)}`;
 }
 
 // src/summary.ts
@@ -11104,6 +11445,10 @@ export {
   external_exports,
   WitanReportSchema,
   formatExternalSourceLine,
+  CERTIFICATE_GLOSSARY,
+  formatCertificateMetricLabel,
+  formatCertificateMetricValue,
+  buildRelyingPartySummary,
   renderWitanHtmlReport,
   renderWitanBadgeEndpoint,
   renderWitanBadgeSvg,

package/dist/index.js

@@ -2,8 +2,12 @@
 import { createRequire as __cejelCreateRequire } from 'node:module';
 const require = __cejelCreateRequire(import.meta.url);
 import {
+  CERTIFICATE_GLOSSARY,
   WitanReportSchema,
+  buildRelyingPartySummary,
   createWitanAttestation,
+  formatCertificateMetricLabel,
+  formatCertificateMetricValue,
   formatExternalSourceLine,
   renderWitanBadgeEndpoint,
   renderWitanBadgeSvg,
@@ -11,7 +15,7 @@ import {
   runCejelScan,
   serializeWitanReport,
   verifyWitanAttestationBinding
-} from "./chunk-HG5NAFH5.js";
+} from "./chunk-ITHPLYKX.js";
 import {
   init_esm_shims
 } from "./chunk-LZVKQV3R.js";
@@ -39,7 +43,7 @@ function renderMinScoreLimitationFailure(summary, minScore) {
   return `Cejel: cannot evaluate the required minimum ${minScore.toFixed(1)}/4.0 because the scan has limited evidence (${summary.scanLimitations.length} limitation${summary.scanLimitations.length === 1 ? "" : "s"}). Resolve the reported limitations and re-scan.
 `;
 }
-function renderTerminalCertificate(summary) {
+function renderTerminalCertificate(summary, report) {
   const abstained = summary.verdict === "Insufficient source" || summary.verdict === "Insufficient evidence";
   if (!abstained && (summary.overallScore === null || summary.codeTrustScore === null || summary.processTrustScore === null)) {
     throw new Error("A scored Cejel summary must carry numeric headline scores.");
@@ -58,6 +62,18 @@ function renderTerminalCertificate(summary) {
     `  Process trust: ${formatScore(summary.processTrustScore)}/4.0`,
     ""
   ];
+  if (report) {
+    const relyingPartySummary = buildRelyingPartySummary(report);
+    lines.splice(
+      2,
+      0,
+      `What was examined: ${relyingPartySummary.examined}`,
+      `What was established: ${relyingPartySummary.established}`,
+      `What was not established: ${relyingPartySummary.notEstablished}`,
+      `What to do next: ${relyingPartySummary.next}`,
+      ""
+    );
+  }
   if (summary.scanLimitations.length > 0) {
     lines.push(
       "LIMITED EVIDENCE \u2014 the score and verdict are qualified by scan limitations:",
@@ -85,6 +101,20 @@ function renderTerminalCertificate(summary) {
     }
     lines.push("");
   }
+  const measurements = report?.criteria.flatMap(
+    (criterion) => criterion.metrics.map((metric) => ({
+      criterionId: criterion.id,
+      label: formatCertificateMetricLabel(metric),
+      value: formatCertificateMetricValue(criterion, metric)
+    }))
+  );
+  if (!abstained && (measurements?.length ?? 0) > 0) {
+    lines.push("Measurements:");
+    for (const measurement of measurements ?? []) {
+      lines.push(`  ${measurement.criterionId} \u2014 ${measurement.label}: ${measurement.value}`);
+    }
+    lines.push("");
+  }
   if (abstained) {
     lines.push("See report.json / certificate.html for the full per-criterion detail.");
   } else if (summary.topFindings.length === 0) {
@@ -118,6 +148,10 @@ function renderTerminalCertificate(summary) {
       lines.push(`  ...and ${remaining} more \u2014 see report.json for the full list.`);
     }
   }
+  lines.push("", "Plain-language glossary:");
+  for (const entry of CERTIFICATE_GLOSSARY) {
+    lines.push(`  ${entry.term} \u2014 ${entry.definition}`);
+  }
   return `${lines.join("\n")}
 `;
 }
@@ -271,7 +305,7 @@ async function runWitanFreeCli(args) {
   writeFileSync(join(options.outDir, "badge.svg"), renderWitanBadgeSvg(report), "utf8");
   writeFileSync(join(options.outDir, "summary.json"), JSON.stringify(summary, null, 2), "utf8");
   if (!options.quiet) {
-    process.stdout.write(renderTerminalCertificate(summary));
+    process.stdout.write(renderTerminalCertificate(summary, report));
     process.stdout.write(
       `
 Wrote:

package/dist/mcp/index.js

@@ -9,7 +9,7 @@ import {
   renderWitanBadgeSvg,
   renderWitanHtmlReport,
   runCejelScan
-} from "../chunk-HG5NAFH5.js";
+} from "../chunk-ITHPLYKX.js";
 import {
   __commonJS,
   __export,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cejel/cejel",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "mcpName": "io.github.BargLabs/cejel",
   "private": false,
   "publishConfig": {