@cejel/cejel 0.1.2 → 0.1.4

package/README.md

@@ -41,14 +41,15 @@ product, and you can falsify it in ten seconds:
 docker run --rm --network=none -v "$PWD:/w" -w /w -v "$PWD/cejel:/cejel:ro" debian:stable-slim /cejel .
 ```
 
-**npm.**
+**npm (scoped package).**
 
 ```bash
-npx @cejel/cejel .
+npx --yes --package @cejel/cejel cejel .
 ```
 
-> **On the name.** npm rejects the unscoped `cejel` package name as too similar to an
-> existing package (`level`). The published package is the scoped `@cejel/cejel`.
+The package is published under the `@cejel` scope while the unscoped name is under npm
+registry review. The installed executable remains `cejel`. For a global install, run
+`npm install --global @cejel/cejel`, then invoke `cejel .`.
 
 **GitHub Action** — score every PR and publish the badge:
 
@@ -70,6 +71,49 @@ Released binaries: `cejel-Darwin-arm64`, `cejel-Linux-x86_64`. A Homebrew tap an
 remaining architectures are in progress; they are not listed here because they do not exist
 yet.
 
+## Leaderboard
+
+This repo ships the [Cejel OSS trust leaderboard](./leaderboard/leaderboard.md): the whole
+corpus scored and published in the open — elite OSS projects, Cejel itself, and the private
+studio monorepo Cejel was built inside — 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 on this board is produced by the same sealed
+public scorer used by `npx cejel .` — check out the source commit printed in the
+report, run the tool, and you will get this number. A required guard does exactly that for
+every corpus row and compares score, verdict, measured coverage, and evidence. No private
+domain collector contributes to any published score, ours included; nobody is exempt.
+
+### Redaction policy
+
+A path is published exactly when the reader can check it. Every public repository on the
+board cites full evidence paths and line numbers, everywhere, in every artifact — a
+certificate whose evidence you cannot open is not evidence. The two private-repository
+entries (this monorepo's own transparency entry, and Cejel's own source sub-package inside
+it) never cite a source path, anywhere, in any field or format — but the finding itself, its
+dimension, status, score, and content hash always survive; only the location is withheld,
+marked uniformly as "path withheld — private repository". Redaction removes a location, never
+a fact: a private repository failing its own check still shows up on its certificate, by
+name. The v3 repository scanner marks B1 and B5 not applicable for every repository,
+including ours; it does not accept structured substrate evidence for them. They remain
+defined for other rubric inputs, while the repository ranking excludes them fail-closed.
+Nobody is scored on evidence the public scanner cannot collect.
+
+### Known false positives (fixed before publishing)
+
+Calibrating a rubric against real, elite repositories surfaces mistakes; the record is part
+of the trust claim, not something to bury. Two dimensions produced a punitive score for the
+*absence* of a ratable surface rather than a real weakness, and both are fixed:
+Django was flagged critical on dependency hygiene for using version ranges instead of exact
+pins — normal, deliberate practice for a library, not an app; the rubric now scores
+dependency hygiene against archetype-appropriate norms. OSSF Scorecard — Google's own
+supply-chain security auditing tool — was flagged critical on audit-trail completeness for
+publishing release notes via GitHub Releases instead of a committed `CHANGELOG.md`; a
+repository with no ratable audit surface now returns "insufficient data" (excluded from the
+composite) instead of a punitive score. The board also publishes a measured-coverage
+indicator per row: a score reflects only its *measured* dimensions, and a row scored on fewer
+than half of its applicable dimensions is shown as unranked rather than ordered against
+better-evidenced rows.
+
 ## Usage
 
 ```bash
@@ -80,11 +124,18 @@ Scores the current directory with sensible defaults: no flags, no signup, fully
 Prints a concise terminal certificate and writes to `.cejel/`:
 
 - `report.json` — the full structured report
+- `attestation.json` — an unsigned in-toto statement binding the report digest, repository
+  revision, rubric, and scored-or-abstained outcome; ready for an external signer
 - `certificate.html` — a self-contained HTML certificate (no external assets)
 - `badge.json` — a [shields.io endpoint](https://shields.io/badges/endpoint-badge) payload
 - `badge.svg` — a static, self-contained trust-score badge
 - `summary.json` — a compact digest (score, verdict, top findings)
 
+The attestation is deliberately explicit about its assurance level: Cejel creates the
+statement, but it does not pretend to be an independent signer. Until a customer, reviewer,
+or provenance system signs it, `assurance.status` is `unsigned` and `issuer` is
+`self-generated`. An abstained scan carries only the refusal reason, never a numeric score.
+
 ### Flags
 
 - `<path>` — repo to score (default: current directory)
@@ -227,7 +278,7 @@ Add it to an MCP client config:
   "mcpServers": {
     "cejel": {
       "command": "npx",
-      "args": ["-y", "--package=@cejel/cejel", "cejel-mcp"]
+      "args": ["-y", "--package=cejel", "cejel-mcp"]
     }
   }
 }
@@ -238,9 +289,9 @@ The server exposes one tool and two resources:
 - `scan` — input `{ path, format? }`; scores the repository at `path` and returns the trust
   cert as JSON (`format: "summary"`, the default, is the compact digest; `format: "json"` is
   the full report, identical to the CLI's `report.json`).
-- `cejel-cejel://last-scan/certificate.html` and `cejel-cejel://last-scan/badge.svg` — the
+- `cejel://last-scan/certificate.html` and `cejel://last-scan/badge.svg` — the
   HTML certificate and SVG badge for the most recent scan (the URI scheme derives from the
-  npm package name, `@cejel/cejel` → `cejel-cejel`).
+  npm package name).
 
 Like the CLI, scoring over MCP is fully offline: no network calls, no telemetry, no signup,
 and the server writes no files.
@@ -248,10 +299,24 @@ and the server writes no files.
 ## What "offline" means here
 
 Scoring a repo — `cejel .` itself, and the Action's scoring step — makes zero network
-calls: no telemetry, no signup, no model call. Fetching the `@cejel/cejel` package the
+calls: no telemetry, no signup, no model call. Fetching the `cejel` package the
 first time (like any npm-distributed CLI, including this Action's own dependency install)
 does need network; that's a one-time install cost, not part of the scoring guarantee.
 
+## Help validate Cejel
+
+Cejel does not collect telemetry. External validation is therefore opt-in and inspectable:
+
+- [Report a calibration result](https://github.com/BargLabs/cejel/issues/new?template=calibration.yml)
+  when a score, finding, evidence pointer, or refusal is wrong. The form asks permission before
+  a correction is added to the public error ledger.
+- [Join a pack design-partner pilot](https://github.com/BargLabs/cejel/issues/new?template=pack-interest.yml)
+  for the Quant or Healthcare Pack. Both remain pilot surfaces until their domain-specific
+  calibration gates pass.
+
+Submit only public or redacted evidence. Never put credentials, proprietary strategy code,
+patient data, or protected health information in a GitHub issue.
+
 ## The public leaderboard: what we redact, what we exclude, and where we were wrong
 
 We publish a trust board scoring a corpus of well-known open-source repositories alongside
@@ -278,9 +343,11 @@ separately produced structured report. We neither score you on evidence the publ
 cannot collect nor award ourselves points for evidence you cannot contest.
 
 **Where we were wrong.** Calibrating this rubric against real repositories — and running the
-board itself like a stranger would — surfaced seven errors in our own tool, all found before
-(or, in one case, on) publication day, and all fixed. We list them because a scoring tool
-that has never been wrong is a scoring tool that has not been checked:
+board itself like a stranger would — surfaced the errors below in our own tool, every one found
+by us and every one fixed. The list is its own count; we do not keep a tally in this sentence,
+because a number typed by hand beside a list that grows is exactly the kind of unchecked claim
+this tool exists to catch. We publish them because a scoring tool that has never been wrong is a
+scoring tool that has not been checked:
 
 - **Django, scored a false critical on dependency hygiene.** We applied application-shaped
   expectations to a library. Archetype now gates the dimension.
@@ -315,6 +382,23 @@ that has never been wrong is a scoring tool that has not been checked:
 - **Version 0.1.1 rejected `--help` and `--version` as unknown flags, and read `-h` as a
   directory path.** Version 0.1.2 handles both aliases before positional-path parsing and
   derives its printed version from the package manifest.
+- **We reported a timing side-channel in our own test fixtures.** Pointed at its own
+  repository, Cejel's secret-handling dimension flagged a "non-constant-time secret
+  comparison" — in string literals inside a test file, the deliberately-insecure example code
+  that exists to prove the detector fires. It read a *file*, not a comparison, and reported a
+  vulnerability in the test written to catch that vulnerability. Two sub-rules of the same
+  dimension held two different private notions of what "production code" meant, and the one
+  that had none was the louder. Version 0.1.3 gives every rule one shared, derived answer to
+  that question, and reports the real line of a real match or nothing at all.
+- **We fixed the COBOL false-verdict, shipped it, and it was still broken.** An earlier release
+  corrected a repository written in a language we cannot read being scored anyway. The fixture
+  that proved the fix contained COBOL and nothing else. The first real COBOL repository we
+  pointed it at — AWS's mainframe credit-card demo — carried nine incidental shell scripts
+  among 329 files, and those nine were enough to short-circuit the abstention path entirely:
+  a 99%-COBOL codebase was scored on its deploy scripts and drew a confident `0.0`,
+  "Unverified". Every real legacy repository has a deploy script, so the fix that passed every
+  test was unreachable for essentially all of them. Recognised source must now be *dominant*,
+  not merely present. **A fixture cleaner than reality proves nothing.**
 
 Every one was a trust failure produced by *us* — false alarms about other people's code,
 silent omissions, inconsistent presentation, or a home-only scoring path — and we would