@cejel/cejel 0.6.0 → 0.6.2

package/README.md

@@ -92,11 +92,12 @@ if (-not $expected -or $actual -ne $expected.ToLowerInvariant()) {
 ```
 
 > **Windows signing status:** `cejel-Windows-x86_64.exe` is intentionally unsigned in
-> 0.6.0 and may trigger Microsoft SmartScreen. The release build removes Node's inherited
+> 0.6.2 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
-> own-platform verification receipt covering `--version`, `--help`, a real scan,
+> GitHub build-provenance attestation. Each binary also has an attached SPDX SBOM (the packages
+> bundled into it, listed from the build, and the Node.js runtime it embeds; from the release after
+> 0.6.0 it is attested to the binary) and an own-platform verification receipt covering `--version`, `--help`, a real scan,
 > source/binary parity, and a network-denied scan. If your policy requires Authenticode,
 > use the npm package or the OCI image until a human-approved signing path is available.
 
@@ -115,7 +116,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.6.0` is the coordinated release version for npm,
+> **Distribution note:** Cejel `0.6.2` is the coordinated release version for npm,
 > standalone binaries, Docker/OCI, GitHub Action, Homebrew, and MCP Registry. A GitLab CI
 > template and Code Quality export live in [`docs/gitlab-ci.md`](./docs/gitlab-ci.md).
 
@@ -148,11 +149,17 @@ The npm package is scoped as `@cejel/cejel`; its executable remains the short co
 **GitHub Action** — score every PR and publish the badge:
 
 ```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0     # full history: A2 and B2 read commit history
 - uses: BargLabs/cejel/action@v1
   with:
     min-score: "2.5"   # optional: fail the build below this
 ```
 
+`actions/checkout` fetches one commit by default. On a shallow clone, A2 and B2 see only that
+commit, and the certificate says so under "History limitations".
+
 For an executed public example that binds a release artifact to the same commit named by its
 Cejel certificate, see [Certified releases with GitHub build provenance](./docs/certified-release-example.md).
 
@@ -166,7 +173,9 @@ node dist/index.js .
 
 Released binaries: `cejel-Darwin-arm64`, `cejel-Darwin-x86_64`, `cejel-Linux-aarch64`,
 `cejel-Linux-x86_64`, and `cejel-Windows-x86_64.exe`. The release also carries
-`SHA256SUMS`, a per-binary SPDX SBOM, and an own-platform verification receipt. Each binary
+`SHA256SUMS`, a per-binary SPDX SBOM, and an own-platform verification receipt. The SBOM lists
+the packages bundled into the binary plus its embedded Node.js runtime. The 0.6.0 SBOMs do not: they
+list only the scanned directory and the binary. See [`docs/release-process.md`](docs/release-process.md). Each binary
 is executed against the source build and with networking denied before attachment. Releases
 from v0.1.6 also carry a Sigstore bundle containing GitHub's signed build-provenance
 attestation for the release set. Verify a downloaded binary with:
@@ -178,20 +187,21 @@ 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.6.0`:
+**Docker / OCI.** The current container release is `0.6.2`:
 
 ```bash
-docker run --rm -i -v "$PWD:/workspace:ro" ghcr.io/barglabs/cejel:0.6.0
+docker run --rm -i -v "$PWD:/workspace:ro" ghcr.io/barglabs/cejel:0.6.2
 ```
 
 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.6.0 .
+docker run --rm -v "$PWD:/workspace:ro" --entrypoint cejel ghcr.io/barglabs/cejel:0.6.2 .
 ```
 
-The OCI image carries an SBOM, maximum-mode build provenance, and a signed registry
-attestation.
+The OCI image carries an SBOM of its base-image packages, maximum-mode build provenance, and a
+signed registry attestation. From the release after 0.6.0 it also carries a second SPDX attestation
+listing the packages Cejel bundles. The 0.6.0 image's SBOM does not list those.
 
 ## Leaderboard
 
@@ -425,11 +435,51 @@ a configurable `min-score` threshold. The scoring step makes no network calls an
 secrets.
 
 ```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0 # full history: A2 and B2 read commit history
 - uses: BargLabs/cejel/action@v1
   with:
     min-score: '2.5' # optional; omit to never fail the check
 ```
 
+Check out with `fetch-depth: 0`: the default depth of 1 truncates the history A2 and B2 read, and
+the certificate then lists a history limitation.
+
+## Use with Claude
+
+Cejel ships as a Claude Code plugin in [`plugins/cejel/`](./plugins/cejel/). The plugin gives
+Claude the `scan` tool below, started through `npx` and pinned to this release, plus a
+`cejel-scan` skill. The skill tells Claude when a scan answers the question and how to read the
+certificate. It also tells Claude to present a score as evidence for your own judgment, never as
+an audit or a guarantee.
+
+Install it from this repository's marketplace, inside Claude Code:
+
+```text
+/plugin marketplace add BargLabs/cejel
+/plugin install cejel@cejel
+```
+
+From a shell, the same two steps are `claude plugin marketplace add BargLabs/cejel` and
+`claude plugin install cejel@cejel`.
+
+Scanning stays offline: the `scan` tool makes no network calls and writes no files. The first
+time the server starts, `npx` fetches the pinned `@cejel/cejel` package from npm. When you name
+a repository that isn't on your machine, Claude asks before cloning it with your `git`. Neither
+fetch is part of the scan.
+
+Example prompts that work on a public repository:
+
+- "Clone https://github.com/BargLabs/cejel into a temporary folder and give me its Cejel trust
+  score."
+- "Scan https://github.com/BargLabs/cejel with Cejel and explain the top findings and the criteria
+  they come from."
+- "Run Cejel on https://github.com/BargLabs/cejel and save its trust badge to ./cejel-badge.svg."
+
+Support: [GitHub issues](https://github.com/BargLabs/cejel/issues). Privacy policy:
+<https://barglabs.ai/privacy>. Terms: <https://barglabs.ai/terms>.
+
 ## MCP server (for agents)
 
 The same package ships a second bin, `cejel-mcp` — a thin MCP (Model Context Protocol)
@@ -517,7 +567,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
-npx -y openclaw@latest mcp set cejel-oci '{"command":"docker","args":["run","--rm","-i","-v","/absolute/path/to/repo:/workspace:ro","ghcr.io/barglabs/cejel:0.6.0"]}'
+npx -y openclaw@latest mcp set cejel-oci '{"command":"docker","args":["run","--rm","-i","-v","/absolute/path/to/repo:/workspace:ro","ghcr.io/barglabs/cejel:0.6.2"]}'
 npx -y openclaw@latest mcp doctor cejel-oci --probe
 ```
 

package/dist/calibration/llm-detector.js

@@ -5,7 +5,7 @@ import {
   deriveProductIdentity,
   runCejelScan,
   serializeWitanReport
-} from "../chunk-2453M7C2.js";
+} from "../chunk-KG62JCJZ.js";
 import {
   listCejelLlmPackFiles
 } from "../chunk-M6YYPJSN.js";
@@ -1597,6 +1597,8 @@ function detectSideEffectingToolWithoutAuthorityBoundary(file) {
 var CEJEL_LLM_ACTION_RULES = [
   {
     id: "LLM-VAL-001",
+    tier: "semantic",
+    tierEvidence: "python-lineage-rules.ts detectPythonInterproceduralModelOutput() emits this id from a 12-pass fixpoint of taint across local call arguments, returns and tainted-branch control dependence; the JS detectUnvalidatedConsequentialAction() tracks aliases",
     title: "Consequential structured action lacks validation",
     detectorConfidence: "high",
     evidenceContract: "A direct local JSON.parse of recognized model output supplies an object field to a named consequential dispatcher without an intervening fail-closed runtime parse or allowlist guard.",
@@ -1610,6 +1612,8 @@ var CEJEL_LLM_ACTION_RULES = [
   },
   {
     id: "LLM-AGY-001",
+    tier: "semantic",
+    tierEvidence: "boundedTaintedIdentifiers() propagates handler-parameter taint through assignments, destructuring and push, and helperCallSideEffects() follows it into one local helper call (bounded data flow; ambiguous with structural, so the higher tier)",
     title: "Side-effecting tool lacks an authority boundary",
     detectorConfidence: "high",
     evidenceContract: "A complete local tool declaration passes a recognized handler parameter or bounded alias to an import-resolved Node filesystem or child-process mutation API, directly or through one unique local helper, without a preceding fail-closed approval or operation-allowlist guard.",
@@ -2273,6 +2277,8 @@ function detectPythonSensitivePromptData(file) {
 var CEJEL_LLM_PYTHON_RULES = [
   {
     id: "LLM-IOH-001",
+    tier: "semantic",
+    tierEvidence: "python-lineage-rules.ts detectPythonInterproceduralModelOutput() emits this id from a 12-pass fixpoint of taint across local call arguments, returns and tainted-branch control dependence",
     title: "Python model output passed to a consequential sink",
     detectorConfidence: "high",
     evidenceContract: "An official OpenAI or Anthropic Python integration, a supported response-output shape or still-live direct alias in the visible function or class scope, and a direct eval, exec, os.system, or subprocess sink are observable in one non-test source file.",
@@ -2286,6 +2292,8 @@ var CEJEL_LLM_PYTHON_RULES = [
   },
   {
     id: "LLM-AGY-002",
+    tier: "structural",
+    tierEvidence: "detectPythonUnboundedAgentLoop() finds a while True loop, takes its indentation-delimited body and tests for guard presence; no data or control flow",
     title: "Unbounded Python agent loop",
     detectorConfidence: "medium",
     evidenceContract: "A literal while True loop has a complete local indentation-delimited body containing an official SDK call or an abstract model-base response call and no observable mandatory finite counter, deadline, cancellation, or budget exit guard; alternatively, one model-facing agent class declares both tools and an explicitly unset per-run tool-call limit.",
@@ -2298,6 +2306,8 @@ var CEJEL_LLM_PYTHON_RULES = [
   },
   {
     id: "LLM-DAT-001",
+    tier: "structural",
+    tierEvidence: "detectPythonSensitivePromptData() paren-matches the full argument extent of an import-resolved SDK model call across lines, then pattern-tests it for secret-named env reads; no flow",
     title: "Sensitive Python environment data passed to a model request",
     detectorConfidence: "high",
     evidenceContract: "A narrowly named os.environ or os.getenv secret-like value occurs inside the executable, syntactically matched arguments of an official SDK model call after comments and strings are excluded from call extraction.",
@@ -3936,6 +3946,8 @@ function hasModelJudgeSurface(files) {
 var CEJEL_LLM_EVALUATION_RULES = [
   {
     id: "LLM-PRV-001",
+    tier: "semantic",
+    tierEvidence: "latestAssignmentsForReferences() and hasLocalOrResolvedHelperInvocationBefore() resolve the latest in-scope assignment and the calling helper that owns the model invocation, following an aggregate to its emitter (data and call-graph flow within a file)",
     title: "Declared evaluation lacks reproducible system provenance",
     detectorConfidence: "high",
     evidenceContract: "A recognized direct or locally called-helper model invocation precedes a complete local evaluation result that is emitted or returned while lacking model or prompt/policy evaluation-configuration lineage. Recognized invocations include import-resolved SDK calls, a complete authenticated OpenAI-compatible REST request, and a complete local Flowise evaluation request. Supported results are aggregate-to-emitter paths, identifier-bound discrete results with model/case/outcome fields, and incrementally built per-case collections with an evaluation identity and resolved return.",
@@ -3951,6 +3963,8 @@ var CEJEL_LLM_EVALUATION_RULES = [
   },
   {
     id: "LLM-EVL-001",
+    tier: "semantic",
+    tierEvidence: "detectMissingDenominator() follows aggregate assignments and denominator aliases (denominatorAliasAssignments, latestAssignmentsForReferences) to the object that is emitted, within function scopes",
     title: "Evaluation result omits its eligible denominator or exclusions",
     detectorConfidence: "high",
     evidenceContract: "A complete local case-iteration, aggregate-calculation, and direct result-emission path is visible, while the emitted object lacks a denominator or raw case results.",
@@ -3964,6 +3978,8 @@ var CEJEL_LLM_EVALUATION_RULES = [
   },
   {
     id: "LLM-EVL-002",
+    tier: "structural",
+    tierEvidence: "detectSoleSelfJudge() counts producer and judge invocations in one file and resolves a model identifier to its literal binding (literalBindings); detectPythonConfiguredSelfJudge() reads class blocks and self.attribute aliasing; no flow beyond one file",
     title: "Evaluated system is its own sole judge",
     detectorConfidence: "high",
     evidenceContract: "Exactly one local producer and one explicit model-assisted judge resolve to the same literal model identity, a result is locally emitted, and no observable independent review signal participates in evaluation acceptance or gating.",
@@ -4751,6 +4767,8 @@ function hasUnsafeSinkSurface(file) {
 var CEJEL_LLM_V1_RULES = [
   {
     id: "LLM-IOH-001",
+    tier: "semantic",
+    tierEvidence: "detectUnsafeSink() keeps a brace-scope stack and propagates model-output taint through assignments, and javaScriptExecutableHelperParameterSinks() runs a taint fixpoint; the Python path (python-rules.ts) is an interprocedural fixpoint",
     title: "Model output passed to a consequential sink",
     detectorConfidence: "high",
     evidenceContract: "A supported model-output expression, or an identifier whose latest assignment in the visible lexical scope is directly from one, appears on the same line as a supported sink; process sinks additionally require a recognized local import or require binding. A local helper is also supported when one of its parameters is observably interpolated into an executable template or passed to dynamic evaluation. Imported model-facing member-tool handlers are supported when their input parameter or bounded alias reaches an import-resolved execution sink directly, through one unique helper, or by writing an executed local artifact.",
@@ -4768,6 +4786,8 @@ var CEJEL_LLM_V1_RULES = [
   },
   {
     id: "LLM-AGY-002",
+    tier: "structural",
+    tierEvidence: "detectUnboundedLoop() finds a literal while(true) or for(;;), brace-matches its whole body and tests for guard presence and a supported model call inside; no data or control flow",
     title: "Unbounded agent loop",
     detectorConfidence: "medium",
     evidenceContract: "A literal while(true) or for(;;) loop has a complete local brace-delimited body containing a recognized model call and no observable conditional counter, deadline, cancellation, budget, return, throw, or break guard.",
@@ -4781,6 +4801,8 @@ var CEJEL_LLM_V1_RULES = [
   },
   {
     id: "LLM-DAT-001",
+    tier: "structural",
+    tierEvidence: "detectSensitivePromptData() paren-matches the full argument extent of an import-resolved SDK model call across lines, then pattern-tests it for secret-named process.env reads; no flow",
     title: "Sensitive data passed to a model request",
     detectorConfidence: "high",
     evidenceContract: "A narrowly named secret-like process.env value occurs inside the executable, syntactically matched arguments of a recognized model call; comments and string-literal lookalikes are masked before call extraction.",

package/dist/{chunk-2453M7C2.js → chunk-KG62JCJZ.js}

@@ -345,6 +345,10 @@ var WitanReportCommonSchema = external_exports.object({
   consumedSignals: external_exports.array(WitanConsumedSignalSummarySchema).optional(),
   archetype: WitanRepoArchetypeSchema.optional(),
   scanLimitations: external_exports.array(external_exports.string().min(1).max(1e3)).max(16).optional(),
+  // Additive-optional (report format 1.5, issue #428): disclosures about the commit history the
+  // scan read, such as a shallow clone. Declared, never scored: unlike scanLimitations it gates
+  // nothing (no score, abstention, badge or --min-score effect). Absent when history is complete.
+  historyLimitations: external_exports.array(external_exports.string().min(1).max(1e3)).max(4).optional(),
   contentReadSummary: WitanContentReadSummarySchema.optional(),
   // Additive-optional (report format 1.3): absent means a report produced before this field
   // existed, never "nothing withheld" — createWitanReport always sets it (possibly to []) on any
@@ -397,7 +401,7 @@ var WitanReportSchema = external_exports.preprocess((value) => {
 }, StrictWitanReportSchema);
 var WITAN_ATTESTATION_STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
 var WITAN_ATTESTATION_PREDICATE_TYPE = "https://cejel.dev/attestations/scan/v1";
-var WITAN_REPORT_FORMAT_VERSION = "1.4";
+var WITAN_REPORT_FORMAT_VERSION = "1.5";
 var WitanAttestationOutcomeSchema = external_exports.discriminatedUnion("status", [
   external_exports.object({
     status: external_exports.literal("scored"),
@@ -502,9 +506,6 @@ function shortCategoryLabel(category) {
 function categoryLabel(category) {
   return category.replaceAll("_", " ");
 }
-function formatCoverageCounts(coverage) {
-  return coverage.byCategory.map((entry) => `${shortCategoryLabel(entry.category)} ${entry.measured}/${entry.total}`).join(" \xB7 ");
-}
 function formatCoverageSummary(coverage) {
   const parts = coverage.byCategory.map(
     (entry) => `${categoryLabel(entry.category)} ${entry.measured}/${entry.total}`
@@ -1368,7 +1369,7 @@ function roundScore(score) {
 }
 
 // src/witan/certificate-presentation.ts
-var CALLER_CONTEXT_PRODUCT_IDENTITY_NOTICE = "Product name and slug are caller context and are excluded from certificate byte-comparison claims.";
+var CALLER_CONTEXT_PRODUCT_IDENTITY_NOTICE = "The product name and its short ID were given by whoever ran the scan, or taken from package.json or the folder name. They are not evidence from the repository, and they are not covered when Cejel says two scans of the same revision give identical results.";
 var CERTIFICATE_SCOPE_NOTICE = "This certificate is a statement about the repository tree at the revision pinned above, not about the system that tree is part of. Evidence outside that tree \u2014 for example, a test suite kept in a separate repository, or CI configuration that changes into a different working directory before running its checks \u2014 is neither seen by this scan nor claimed to be absent.";
 var CERTIFICATE_METRIC_REGISTRY = {
   test_to_source_ratio: { displayLabel: "Test-to-source file ratio" },
@@ -1430,7 +1431,7 @@ var CERTIFICATE_GLOSSARY = [
   {
     key: "static-coverage",
     term: "Static coverage percentage",
-    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.",
+    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. When no percentage above 0 is published, the rubric scores this metric as 0 of 100.",
     metricNames: ["coverage_percent"]
   },
   {
@@ -1670,6 +1671,9 @@ function isCoverageNotMeasured(criterion, metric2) {
     ...criterion.findings.map((finding) => finding.evidence)
   ].some((evidence) => evidence.kind === "coverage");
 }
+function isCoveragePercentageUnpublished(criterion, metric2) {
+  return metric2.name === "coverage_percent" && metric2.value === 0 && !isCoverageNotMeasured(criterion, metric2);
+}
 function labelAlreadyStatesUnit(label, unit) {
   if (!unit) return false;
   const escapedUnit = unit.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -1733,7 +1737,10 @@ function formatEnumerableMetric(metric2) {
 }
 function formatCertificateMetricValue(criterion, metric2) {
   if (isCoverageNotMeasured(criterion, metric2)) {
-    return "no coverage report found \u2014 not measured";
+    return "no coverage report or threshold found, so there is no percentage to read (Cejel does not run tests); the rubric scores this as 0 of 100";
+  }
+  if (isCoveragePercentageUnpublished(criterion, metric2)) {
+    return "coverage configuration found, but no published coverage percentage above 0 (Cejel reads published reports and thresholds and does not run tests); the rubric scores this as 0 of 100";
   }
   if (metric2.name === "test_to_source_ratio" && metric2.max !== void 0) {
     const tests = formatMetricNumber(metric2.value);
@@ -1803,7 +1810,12 @@ function buildNextSteps(report, unmeasured, notApplicable, a1, coverageMetric) {
   }
   if (a1 && coverageMetric && isCoverageNotMeasured(a1, coverageMetric)) {
     steps.push(
-      "Obtain a coverage report or configured threshold for A1's static coverage metric; none was found, so it was not measured."
+      "Obtain a coverage report or configured threshold for A1's static coverage metric; none was found, so no percentage was measured."
+    );
+  }
+  if (a1 && coverageMetric && isCoveragePercentageUnpublished(a1, coverageMetric)) {
+    steps.push(
+      "Publish a coverage report or threshold for A1's static coverage metric; coverage configuration was found, but no published percentage above 0."
     );
   }
   if (!report.repo.headSha && report.criteria.some(
@@ -1825,10 +1837,10 @@ function buildNextSteps(report, unmeasured, notApplicable, a1, coverageMetric) {
       `Resolve the ${scanLimitationCount} scan limitation${scanLimitationCount === 1 ? "" : "s"} qualifying the readable evidence, then reproduce the scan.`
     );
   }
-  const skippedCount = report.contentReadSummary?.skipped ?? 0;
-  if (skippedCount > 0) {
+  const actionableSkips = actionableSkipReasons(report.contentReadSummary);
+  if (actionableSkips.count > 0) {
     steps.push(
-      `Make the ${skippedCount} skipped content entr${skippedCount === 1 ? "y" : "ies"} readable (see the itemized reasons in the certificate), then reproduce the scan.`
+      `Resolve the ${actionableSkips.count} content entr${actionableSkips.count === 1 ? "y" : "ies"} skipped as ${joinWithOr(actionableSkips.reasons)} (see the itemized reasons in the certificate), then reproduce the scan.`
     );
   }
   if (steps.length === 0) {
@@ -1838,6 +1850,76 @@ function buildNextSteps(report, unmeasured, notApplicable, a1, coverageMetric) {
   }
   return steps;
 }
+function joinWithConjunction(items, conjunction) {
+  if (items.length <= 1) return items.join("");
+  return `${items.slice(0, -1).join(", ")} ${conjunction} ${items[items.length - 1]}`;
+}
+function joinWithOr(items) {
+  return joinWithConjunction(items, "or");
+}
+function joinWithAnd(items) {
+  return joinWithConjunction(items, "and");
+}
+var ACTIONABLE_SKIP_REASONS = [
+  { key: "unreadable", label: "unreadable" },
+  { key: "tooLarge", label: "too large" },
+  { key: "deniedPath", label: "a denied path" },
+  { key: "nonRegularFile", label: "not a regular file" }
+];
+function actionableSkipReasons(summary) {
+  if (!summary) return { count: 0, reasons: [] };
+  const present = ACTIONABLE_SKIP_REASONS.filter(({ key }) => summary.byReason[key] > 0);
+  return {
+    count: present.reduce((sum, { key }) => sum + summary.byReason[key], 0),
+    reasons: present.map(({ label }) => label)
+  };
+}
+function contentEntries(count, singular, plural) {
+  return `${count} content entr${count === 1 ? `y ${singular}` : `ies ${plural}`}`;
+}
+function formatMeasuredDimensionCounts(coverage) {
+  return coverage.byCategory.map((entry) => `${shortCategoryLabel(entry.category)} ${entry.measured} of ${entry.total}`).join(", ");
+}
+function notApplicableCount(report) {
+  return report.criteria.filter((criterion) => criterion.status === "not_applicable").length;
+}
+function formatDimensionsMeasuredSentence(report) {
+  const notApplicable = notApplicableCount(report);
+  const counts = `Dimensions measured: ${formatMeasuredDimensionCounts(computeMeasuredCoverage(report))}.`;
+  return notApplicable > 0 ? `${counts} ${notApplicable} do not apply to this repository.` : counts;
+}
+function formatLowConfidenceSentence(report) {
+  const coverage = computeMeasuredCoverage(report);
+  if (!coverage.lowConfidence) return void 0;
+  const isLow = (counts) => counts.total > 0 && counts.measured / counts.total < LOW_CONFIDENCE_COVERAGE_THRESHOLD;
+  const parts = [
+    ...coverage.byCategory.filter(isLow).map((entry) => `${shortCategoryLabel(entry.category)} (${entry.measured} of ${entry.total})`),
+    ...isLow(coverage.overall) ? [`overall (${coverage.overall.measured} of ${coverage.overall.total})`] : []
+  ];
+  const sentence = `Low confidence: fewer than half of the ${joinWithAnd(parts)} dimensions were measured.`;
+  return notApplicableCount(report) > 0 ? `${sentence} Dimensions that do not apply count as not measured here.` : sentence;
+}
+var SCORED_VERDICT_BANDS = {
+  conditional: { label: "Conditional", band: "2.5 up to 3.5" },
+  at_risk: { label: "At risk", band: "1.5 up to 2.5" },
+  unverified: { label: "Unverified", band: "below 1.5" }
+};
+var MAX_LOWEST_DIMENSIONS = 3;
+function buildVerdictExplanation(report) {
+  if (report.verdict === "insufficient_source" || report.verdict === "verified") return void 0;
+  if (report.overallScore === null) return void 0;
+  const hasCriticalOrWarning = report.criteria.some(
+    (criterion) => criterion.findings.some((finding) => finding.severity === "critical" || finding.severity === "warning")
+  );
+  if (hasCriticalOrWarning) return void 0;
+  const { label, band } = SCORED_VERDICT_BANDS[report.verdict];
+  const lowest = report.criteria.map((criterion, index) => ({ criterion, index })).filter(
+    ({ criterion }) => isMeasuredCriterionStatus(criterion.status) && witanVerdictForScore(criterion.score) !== "verified"
+  ).sort((a, b) => a.criterion.score - b.criterion.score || a.index - b.index).slice(0, MAX_LOWEST_DIMENSIONS).map(({ criterion }) => `${criterion.id} (${criterion.score.toFixed(1)})`);
+  const verdictSentence = `The ${label} verdict comes from the overall score of ${report.overallScore.toFixed(1)} out of 4.0, which is in the ${label} band (${band}). No finding set it.`;
+  if (lowest.length === 0) return verdictSentence;
+  return lowest.length === 1 ? `${verdictSentence} The measured dimension scoring lowest is ${lowest[0]}.` : `${verdictSentence} The measured dimensions scoring lowest are ${joinWithAnd(lowest)}.`;
+}
 var WITHHELD_PATH_READ_FAILURE_REASONS = /* @__PURE__ */ new Set([
   "unreadable",
   "denied_path"
@@ -1876,6 +1958,13 @@ function buildWithheldPathsGapSentence(report) {
   const reportsOnWhatItRead = signals.length === 1 ? "that signal reports on what it read" : "these signals report on what they read";
   return `${count} ${entryWord} withheld (${reasonLabel}); ${signalList} would have read ${pronoun}. Under this rubric ${reportsOnWhatItRead}; the prospective v23 rubric abstains instead.`;
 }
+function describeEstablishedDimensions(report, measured, applicable) {
+  const total = report.criteria.length;
+  const counts = formatMeasuredDimensionCounts(computeMeasuredCoverage(report));
+  const measuredSentence = `The report measured ${measured} of the ${total} rubric dimensions (${counts}).`;
+  const notApplicable = total - applicable;
+  return notApplicable > 0 ? `${measuredSentence} ${notApplicable} do not apply to this repository; ${measured} of the ${applicable} that apply were measured.` : `${measuredSentence} All ${total} apply to this repository.`;
+}
 function buildRelyingPartySummary(report) {
   const applicable = report.criteria.filter((criterion) => criterion.status !== "not_applicable");
   const measured = applicable.filter((criterion) => criterion.status !== "insufficient_data");
@@ -1886,7 +1975,12 @@ function buildRelyingPartySummary(report) {
   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."
+      "No coverage report or configured threshold was found, so no static coverage percentage was measured and the rubric scored it as 0 of 100; Cejel does not run the subject's tests."
+    );
+  }
+  if (a1 && coverageMetric && isCoveragePercentageUnpublished(a1, coverageMetric)) {
+    gaps.push(
+      "Coverage configuration was found, but no coverage report or threshold in this tree publishes a percentage above 0, so the rubric scored static coverage as 0 of 100; Cejel does not run the subject's tests."
     );
   }
   if (!report.repo.headSha && report.criteria.some(
@@ -1910,10 +2004,16 @@ function buildRelyingPartySummary(report) {
     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;
+  const actionableSkips = actionableSkipReasons(report.contentReadSummary).count;
+  if (actionableSkips > 0) {
     gaps.push(
-      `${skipped} content entr${skipped === 1 ? "y was" : "ies were"} skipped for the reasons itemized in the certificate.`
+      `${contentEntries(actionableSkips, "was", "were")} skipped for the reasons itemized in the certificate.`
+    );
+  }
+  const excludedByExtension = report.contentReadSummary?.byReason.excludedByExtension ?? 0;
+  if (excludedByExtension > 0) {
+    gaps.push(
+      `${contentEntries(excludedByExtension, "was", "were")} not read because ${excludedByExtension === 1 ? "its file type is" : "their file types are"} outside what Cejel reads. This is a fixed limit of the tool, not something the repository needs to fix.`
     );
   }
   const withheldPathsSentence = buildWithheldPathsGapSentence(report);
@@ -1926,7 +2026,7 @@ function buildRelyingPartySummary(report) {
   return {
     scope: CERTIFICATE_SCOPE_NOTICE,
     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"}.`,
+    established: `${describeEstablishedDimensions(report, measured.length, applicable.length)} It recorded ${findings} evidence-backed finding${findings === 1 ? "" : "s"}.`,
     notEstablished: gaps.join(" "),
     next: buildNextSteps(report, unmeasured, notApplicable, a1, coverageMetric).join(" ")
   };
@@ -2022,6 +2122,7 @@ function renderWitanHtmlReport(report, options = {}) {
   const coverage = computeMeasuredCoverage(report);
   const gitHistoryUnavailable = !report.repo.headSha;
   const relyingPartySummary = buildRelyingPartySummary(report);
+  const lowConfidenceSentence = formatLowConfidenceSentence(report);
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -2043,7 +2144,6 @@ function renderWitanHtmlReport(report, options = {}) {
           <p class="eyebrow">Trust Certificate</p>
           <h1>${escapeHtml(report.productDisplayName)}</h1>
           <dl class="meta">
-            <div><dt>Product identity</dt><dd>${escapeHtml(CALLER_CONTEXT_PRODUCT_IDENTITY_NOTICE)}</dd></div>
             ${options.generatedAt ? `<div><dt>Date</dt><dd>${escapeHtml(formatDate(options.generatedAt))}</dd></div>` : ""}
             <div><dt>Run</dt><dd>${escapeHtml(renderRepo(report))}</dd></div>
             <div><dt>CLI</dt><dd>${escapeHtml(options.cliVersion ? `Cejel ${options.cliVersion}` : "Not recorded")}</dd></div>
@@ -2052,6 +2152,7 @@ function renderWitanHtmlReport(report, options = {}) {
             ${// Gated on the rubric actually being prospective — a calibrated (v17) certificate's
   // HTML stays byte-identical to before --rubric-pin existed.
   isProspectiveRubricVersion(report.rubricVersion) ? `<div><dt>Calibration</dt><dd class="prospective-rubric-notice">${escapeHtml(PROSPECTIVE_RUBRIC_NOTICE)}</dd></div>` : ""}
+            <div><dt>About the name</dt><dd>${escapeHtml(CALLER_CONTEXT_PRODUCT_IDENTITY_NOTICE)}</dd></div>
             ${contributingSources.length > 0 ? `<div><dt>Sources</dt><dd>Incorporates findings from: ${escapeHtml(contributingSources.join(", "))}<ul class="source-counts">${externalSourceSummaries.map((s) => `<li>${escapeHtml(formatSourceProvenanceLine(s))}</li>`).join("")}</ul></dd></div>` : ""}
           </dl>
         </section>
@@ -2065,7 +2166,8 @@ function renderWitanHtmlReport(report, options = {}) {
             <span>Code ${renderCategoryScore(report.codeTrustScore, coverage, "code_trust")}</span>
             <span>Process ${renderCategoryScore(report.processTrustScore, coverage, "process_trust")}</span>
           </div>
-          <div class="coverage-note">${escapeHtml(formatCoverageCounts(coverage))} measured${coverage.lowConfidence ? " \xB7 low confidence" : ""}</div>`}
+          <div class="coverage-note">${escapeHtml(formatDimensionsMeasuredSentence(report))}</div>${lowConfidenceSentence ? `
+          <div class="coverage-note">${escapeHtml(lowConfidenceSentence)}</div>` : ""}`}
         </aside>
       </div>
     </header>
@@ -2081,6 +2183,13 @@ function renderWitanHtmlReport(report, options = {}) {
   ).join("")}</ul>
     </section>` : ""}
 
+    ${(report.historyLimitations?.length ?? 0) > 0 ? `<section class="scan-limitations-section evidence-section" aria-label="History limitations">
+      <h2>History limitations</h2>
+      <ul>${(report.historyLimitations ?? []).map(
+    (limitation) => `<li class="scan-warning"><strong>History limitation</strong><span>${escapeHtml(limitation)}</span></li>`
+  ).join("")}</ul>
+    </section>` : ""}
+
     ${renderContentReadSummary(report)}
 
     <section class="trust-grid" aria-label="Rubric criteria">
@@ -2128,9 +2237,12 @@ function collectFindingsFirstEntries(report) {
 function renderFindingsFirstSummary(report) {
   const entries = collectFindingsFirstEntries(report);
   const body = entries.length > 0 ? `<ul>${entries.map(({ criterion, finding }) => `<li>${renderFindingEvidence(criterion, finding)}</li>`).join("")}</ul>` : '<p class="findings-first-empty">No critical or warning findings were identified across any criterion in this scan.</p>';
+  const verdictExplanation = buildVerdictExplanation(report);
+  const explanation = verdictExplanation ? `
+      <p class="verdict-explanation">${escapeHtml(verdictExplanation)}</p>` : "";
   return `<section class="findings-first-summary" aria-labelledby="findings-first-heading">
       <h2 id="findings-first-heading">Critical and warning findings</h2>
-      ${body}
+      ${body}${explanation}
     </section>`;
 }
 function renderRelyingPartySummary(summary) {
@@ -2457,6 +2569,7 @@ dd { margin: 0; color: var(--muted); overflow-wrap: anywhere; }
 .findings-first-summary { margin-top: 20px; border: 1px solid var(--line-strong); border-radius: 8px; background: var(--surface); padding: 22px; }
 .findings-first-summary ul { margin: 0; padding-left: 18px; display: grid; gap: 10px; }
 .findings-first-empty { margin: 0; color: var(--muted); }
+.verdict-explanation { margin: 10px 0 0; 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; }
@@ -9116,6 +9229,15 @@ function hasEnvPathInGitHistory(repoPath, scanLimitations) {
 // src/witan/public-scan.ts
 init_esm_shims();
 
+// src/witan/history-depth.ts
+init_esm_shims();
+var SHALLOW_HISTORY_LIMITATION = "This repository is a shallow clone (git rev-parse --is-shallow-repository reports true), so its commit history is truncated. A2 (credentials and .env files in earlier commits) and B2 (pull-request merge ratio over recent commits) read history and saw only the commits present; on a full clone their results may differ. Scores are computed exactly as for any other scan. Re-scan a full clone (for actions/checkout, set fetch-depth: 0).";
+function detectHistoryLimitations(repoPath) {
+  const result = execGit(["rev-parse", "--is-shallow-repository"], { cwd: repoPath });
+  if (!result.ok || result.stdout.trim() !== "true") return void 0;
+  return [SHALLOW_HISTORY_LIMITATION];
+}
+
 // src/witan/ingest.ts
 init_esm_shims();
 import { lstatSync as lstatSync3, opendirSync, readFileSync as readFileSync4, realpathSync as realpathSync3 } from "fs";
@@ -9653,12 +9775,14 @@ function scoreRepoWithPublicCejel(options) {
     ...options.rubricVersion ? { rubricVersion: options.rubricVersion } : {}
   });
   const inputSignals = resolvePublicIngestSignals(options);
-  const report = createWitanReport(
+  const scored = createWitanReport(
     input,
     inputSignals.length > 0 ? inputSignals : void 0,
     void 0,
     options.toolVersion
   );
+  const historyLimitations = detectHistoryLimitations(options.repoPath);
+  const report = historyLimitations ? { ...scored, historyLimitations } : scored;
   if (report.verdict !== "insufficient_source" || !isWitanNoMeasurementAbstention(report)) {
     return report;
   }
@@ -9880,6 +10004,7 @@ function buildWitanCliSummary(report) {
     externalFindingCount: allExternalFindings.length,
     topExternalFindings: allExternalFindings.slice(0, EXTERNAL_FINDINGS_DISPLAY_LIMIT),
     scanLimitations: [...report.scanLimitations ?? []],
+    ...report.historyLimitations?.length ? { historyLimitations: [...report.historyLimitations] } : {},
     ...report.contentReadSummary ? { contentReadSummary: report.contentReadSummary } : {}
   };
   if (report.verdict === "insufficient_source") {
@@ -9937,6 +10062,9 @@ export {
   formatCertificateMetricLabel,
   formatCertificateMetricAppliedWeightPercent,
   formatCertificateMetricValue,
+  formatDimensionsMeasuredSentence,
+  formatLowConfidenceSentence,
+  buildVerdictExplanation,
   buildRelyingPartySummary,
   renderWitanHtmlReport,
   renderWitanBadgeEndpoint,