@geonosis/review 1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,106 @@
+# @geonosis/review
+
+The decision-only reviewer contract. A review's sole output is one JSON decision; a deterministic
+step validates it and records it. The step comments nowhere, labels nothing, approves nothing, and
+has no forge client and no network client in it — by construction, and there is a test that reads
+the shipped bundle to keep it that way.
+
+Ported from Medusa's `reviewing-prs` skill, which runs this in production: read-only tools, one
+`review-decision.json`, and the mutation scripts *deliberately unavailable in this job*.
+
+```bash
+npm i -D @geonosis/review zod
+
+geonosis-review apply  decision.json [--to ledger|stdout] [--slug <name>]
+geonosis-review check  decision.json --criteria plans/022-1.0.0-everything.md
+```
+
+| exit | what it means |
+|---|---|
+| `0` | applied |
+| `1` | the review was READ and REFUSED — prose, a bad shape, a contradiction, a criterion never checked |
+| `2` | the command could not run — no file, no verb, an unknown flag, an option with no value, a plan with no criteria |
+
+Only `1` is an answer about a review. Everything the command line itself gets wrong is `2`, on one
+line and with no stack trace, so a caller that branches on the code never reads a typo as a refusal.
+
+## The decision
+
+```json
+{
+  "decision": "request-changes",
+  "summary": "The ops-leakage probe reads its patterns twice and defaults them in one of the two.",
+  "findings": [
+    {
+      "file": "packages/walk/src/probes/ops-leakage.ts",
+      "line": 21,
+      "severity": "blocking",
+      "criterion": "When a probe is enabled without its list, the run shall refuse",
+      "text": "needs() requires patterns but run() falls back to an empty list, so a walk that skipped needs() reports a clean page."
+    }
+  ],
+  "criteriaChecked": [
+    "When a probe is enabled without its list, the run shall refuse"
+  ]
+}
+```
+
+`decision` is `approve`, `request-changes` or `comment` — the three outcomes a review has anywhere.
+Medusa's two closing templates are not here: closing is a forge action, and this applier takes none.
+`severity` is `blocking`, `major` or `minor`. `file` and `text` are required on every finding,
+because "being vague about required changes" is on Medusa's own list of mistakes and a finding that
+names neither is exactly that. `criterion` is the field Medusa has no analogue for: it binds a
+finding to the plan's EARS criterion.
+
+## What is refused
+
+Beyond the schema — which is strict, so an unknown key is refused rather than dropped:
+
+- **a prose review**, in the first clause of the message rather than after a schema dump;
+- **an approval that lists a blocking finding** — Medusa's "Common Mistakes", made mechanical;
+- **a `request-changes` with nothing blocking or major in it** — the same failure from the other
+  side: a decision the author cannot act on, and how a review loop reaches round three having said
+  nothing;
+- **a decision that never looked at a criterion the plan states** (`check`), naming which.
+
+## `check --criteria`
+
+Every EARS criterion under the plan's acceptance heading must appear in `criteriaChecked`, matched
+on the whole criterion with whitespace normalised — a criterion an editor reflowed is the same
+criterion; a criterion half-quoted is not, or `criteriaChecked: ["When"]` would cover a plan.
+
+The heading and the criterion pattern are configuration, because a heading is a repo's vocabulary:
+
+```json
+{
+  "review": {
+    "criteriaHeading": "^#{2,3} +Acceptance criteria\\b",
+    "criteria": "^- When .+ shall .+",
+    "proofs": "proofs",
+    "runner": "peer-session"
+  }
+}
+```
+
+## `runner`
+
+`peer-session` or `agent:<model>` (C13). D-009 said the reviewer runs on a different model; D-016
+said the cross-context check is the peer session that owns the other repo. Both are *not the
+author*, which is the property that matters — so the kit ships the contract and leaves the runner to
+configuration. **Nothing in this package acts on the field**; the agent text reads it, because a
+library that picked a runner would have picked for every consumer.
+
+## Why it does not use `@geonosis/ledger`
+
+`apply --to ledger` writes `<proofs>/<slug>.md` itself, and this package imports nothing of the kit.
+Three measured reasons:
+
+1. the ledger's only proof API is `captureProof`, which **runs a command** and captures its output —
+   a decision that already exists is not a command, and an applier that shells out is not
+   deterministic;
+2. `captureProof` writes `NNN-slug.md`, one past the highest number on disk, so the same decision
+   lands at a different path on a different tree — the opposite of a deterministic apply;
+3. a reviewer that can reach the ledger is one call away from writing the tick it just judged. The
+   scored agent never writes the scoreboard.
+
+Running `apply` twice on the same decision rewrites the same bytes at the same path.

package/bin/geonosis-review.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Committed, so `pnpm install` can link the bin on a fresh clone — before `pnpm build` has
+// produced dist/. A bin that only exists after a build is a bin that is missing when you need it.
+import '../dist/review-cli.js'

package/dist/chunk-PJWPFJAP.js

@@ -0,0 +1,168 @@
+// src/config.ts
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+var ReviewError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ReviewError";
+  }
+};
+var REVIEW_DEFAULT = {
+  criteria: "^- When .+ shall .+",
+  criteriaHeading: "^#{2,3} +Acceptance criteria\\b",
+  proofs: "proofs",
+  runner: "peer-session"
+};
+var KNOWN = new Set(Object.keys(REVIEW_DEFAULT));
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var loadReviewConfig = (root) => {
+  const file = resolve(root, "geonosis.json");
+  if (!existsSync(file)) return REVIEW_DEFAULT;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (error) {
+    throw new ReviewError(`geonosis.json is not valid JSON: ${error.message}`);
+  }
+  if (!isRecord(parsed)) throw new ReviewError("geonosis.json must hold an object");
+  const block = parsed.review;
+  if (block === void 0) return REVIEW_DEFAULT;
+  if (!isRecord(block)) throw new ReviewError("review must be an object");
+  const config = { ...REVIEW_DEFAULT };
+  for (const [key, value] of Object.entries(block)) {
+    if (!KNOWN.has(key)) throw new ReviewError(`review.${key} is not a key of the review block`);
+    if (typeof value !== "string") throw new ReviewError(`review.${key} must be a string`);
+    config[key] = value;
+  }
+  for (const key of ["criteria", "criteriaHeading"]) {
+    try {
+      RegExp(config[key]);
+    } catch {
+      throw new ReviewError(`review.${key}: "${config[key]}" is not a regular expression`);
+    }
+  }
+  return config;
+};
+
+// src/criteria.ts
+var HEADING = /^(#{1,6}) +(.*)$/;
+var sectionUnder = (lines, pattern) => {
+  const test = new RegExp(pattern);
+  const headings = [];
+  let fenced = false;
+  for (const [index, line] of lines.entries()) {
+    if (line.startsWith("```") || line.startsWith("~~~")) fenced = !fenced;
+    if (fenced) continue;
+    const match = HEADING.exec(line);
+    if (match?.[1] !== void 0) headings.push({ depth: match[1].length, index });
+  }
+  const at = headings.find((heading) => test.test(lines[heading.index] ?? ""));
+  if (at === void 0) return void 0;
+  const next = headings.find((heading) => heading.index > at.index && heading.depth <= at.depth);
+  return lines.slice(at.index + 1, next?.index ?? lines.length);
+};
+var normalise = (text) => text.trim().replaceAll(/\s+/g, " ");
+var criteriaOf = (plan, config) => {
+  const section = sectionUnder(plan.split("\n"), config.criteriaHeading);
+  if (section === void 0) return [];
+  const test = new RegExp(config.criteria);
+  return section.filter((line) => test.test(line)).map((line) => normalise(line.replace(/^\s*[-*]\s+/, "")));
+};
+var uncovered = (stated, checked) => {
+  const seen = new Set(checked.map(normalise));
+  return stated.filter((one) => !seen.has(normalise(one)));
+};
+
+// src/decision.ts
+import { z } from "zod";
+var DECISIONS = ["approve", "comment", "request-changes"];
+var SEVERITIES = ["blocking", "major", "minor"];
+var finding = z.strictObject({
+  criterion: z.string().min(1).optional(),
+  file: z.string().min(1),
+  line: z.number().int().positive().optional(),
+  severity: z.enum(SEVERITIES),
+  text: z.string().min(1)
+});
+var decisionSchema = z.strictObject({
+  criteriaChecked: z.array(z.string().min(1)),
+  decision: z.enum(DECISIONS),
+  findings: z.array(finding),
+  summary: z.string().min(1)
+});
+var issues = (error) => error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+var contradictions = (decision) => {
+  const blocking = decision.findings.filter((one) => one.severity === "blocking");
+  if (decision.decision === "approve" && blocking.length > 0) {
+    return `an approve cannot carry ${blocking.length} blocking finding(s) \u2014 ${blocking[0]?.file}: ${blocking[0]?.text}`;
+  }
+  if (decision.decision !== "request-changes") return null;
+  const actionable = decision.findings.filter((one) => one.severity !== "minor");
+  return actionable.length > 0 ? null : "a request-changes must carry at least one blocking or major finding saying what to change";
+};
+var readDecision = (source) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(source);
+  } catch (error) {
+    return {
+      ok: false,
+      reason: `the review is not JSON, so no step can apply it: ${error.message}`
+    };
+  }
+  const read = decisionSchema.safeParse(parsed);
+  if (!read.success) return { ok: false, reason: issues(read.error) };
+  const contradiction = contradictions(read.data);
+  return contradiction === null ? { decision: read.data, ok: true } : { ok: false, reason: contradiction };
+};
+
+// src/apply.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { dirname, resolve as resolve2 } from "path";
+var render = (decision) => {
+  const findings = decision.findings.length === 0 ? ["_No findings._"] : decision.findings.map(
+    (one) => `- **${one.severity}** \`${one.file}${one.line === void 0 ? "" : `:${one.line}`}\`${one.criterion === void 0 ? "" : ` \u2014 _${one.criterion}_`}
+  ${one.text}`
+  );
+  const criteria = decision.criteriaChecked.length === 0 ? ["_None stated._"] : decision.criteriaChecked.map((one) => `- ${one}`);
+  return [
+    `# review \u2014 ${decision.decision}`,
+    "",
+    decision.summary,
+    "",
+    "## Findings",
+    "",
+    ...findings,
+    "",
+    "## Criteria checked",
+    "",
+    ...criteria,
+    "",
+    "## The decision, verbatim",
+    "",
+    "```json",
+    JSON.stringify(decision, null, 2),
+    "```",
+    ""
+  ].join("\n");
+};
+var applyDecision = (decision, root, proofs, slug) => {
+  const at = resolve2(root, proofs, `${slug}.md`);
+  mkdirSync(dirname(at), { recursive: true });
+  writeFileSync(at, render(decision));
+  return at;
+};
+
+export {
+  ReviewError,
+  REVIEW_DEFAULT,
+  loadReviewConfig,
+  criteriaOf,
+  uncovered,
+  DECISIONS,
+  SEVERITIES,
+  decisionSchema,
+  readDecision,
+  render,
+  applyDecision
+};

package/dist/index.d.ts

@@ -0,0 +1,131 @@
+import { z } from 'zod';
+
+/**
+ * Where the reviewer's runner comes from (C13).
+ *
+ * D-009 said "a different model"; D-016 said the cross-context check is the PEER SESSION that owns
+ * the other repo. Both are "not the author", which is the property that matters, so the kit ships
+ * the CONTRACT and leaves the runner to configuration. The agent text reads this field; nothing in
+ * this package acts on it, because a library that chose a model would have chosen for both.
+ */
+type ReviewConfig = {
+    criteria: string;
+    criteriaHeading: string;
+    proofs: string;
+    runner: string;
+};
+declare class ReviewError extends Error {
+    constructor(message: string);
+}
+/** The same two patterns the ledger's plan contract uses, and for the same reason: a heading is a repo's vocabulary. */
+declare const REVIEW_DEFAULT: ReviewConfig;
+/** The `review` block of `geonosis.json`, every key optional, every default a contract. */
+declare const loadReviewConfig: (root: string) => ReviewConfig;
+
+/** Every EARS criterion the plan states, in order, with the list marker taken off. */
+declare const criteriaOf: (plan: string, config: ReviewConfig) => string[];
+/**
+ * The criteria the decision never looked at.
+ *
+ * Equality of the whole normalised criterion, never a prefix: a review that quoted the first six
+ * words of a criterion has not stated that it checked it, and accepting a prefix would let
+ * `criteriaChecked: ["When"]` cover a whole plan.
+ */
+declare const uncovered: (stated: string[], checked: string[]) => string[];
+
+/**
+ * The three outcomes a review has anywhere.
+ *
+ * Medusa's contract has five `review_template` values, two of which close the pull request. Closing
+ * is a forge action, and this applier takes none — so `close-spam` and `close-malicious` are a
+ * decision to describe in the summary, not an outcome the kit can carry out.
+ */
+declare const DECISIONS: readonly ["approve", "comment", "request-changes"];
+declare const SEVERITIES: readonly ["blocking", "major", "minor"];
+/**
+ * `file` is required and `text` is required, because Medusa's own list of mistakes has "being vague
+ * about required changes — always state exactly what needs to change and where", and a finding that
+ * names neither is exactly that. `criterion` is the field Medusa has no analogue for: it binds a
+ * finding to the plan's EARS criterion, so `check` can say which criterion is unmet rather than
+ * only which file.
+ */
+declare const finding: z.ZodObject<{
+    criterion: z.ZodOptional<z.ZodString>;
+    file: z.ZodString;
+    line: z.ZodOptional<z.ZodNumber>;
+    severity: z.ZodEnum<{
+        blocking: "blocking";
+        major: "major";
+        minor: "minor";
+    }>;
+    text: z.ZodString;
+}, z.core.$strict>;
+/**
+ * `strictObject`, not `object`: an unknown key is refused rather than dropped.
+ *
+ * Medusa's schema note is that a value outside the allowlist makes the downstream apply job FAIL,
+ * surfacing in the logs. A KEY outside it is the same mistake one step earlier — silently ignoring
+ * `labels_to_add` would apply a decision the reviewer did not make and tell nobody.
+ */
+declare const decisionSchema: z.ZodObject<{
+    criteriaChecked: z.ZodArray<z.ZodString>;
+    decision: z.ZodEnum<{
+        approve: "approve";
+        comment: "comment";
+        "request-changes": "request-changes";
+    }>;
+    findings: z.ZodArray<z.ZodObject<{
+        criterion: z.ZodOptional<z.ZodString>;
+        file: z.ZodString;
+        line: z.ZodOptional<z.ZodNumber>;
+        severity: z.ZodEnum<{
+            blocking: "blocking";
+            major: "major";
+            minor: "minor";
+        }>;
+        text: z.ZodString;
+    }, z.core.$strict>>;
+    summary: z.ZodString;
+}, z.core.$strict>;
+type ReviewDecision = z.infer<typeof decisionSchema>;
+type ReviewFinding = z.infer<typeof finding>;
+type ReadDecision = {
+    decision: ReviewDecision;
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The whole gate, in one function: a review is either this object or it is refused.
+ *
+ * A reviewer that wrote three paragraphs has produced something no deterministic step can apply,
+ * and the refusal says so in the first clause rather than after a schema dump — "not JSON" is the
+ * sentence that tells the author what went wrong.
+ */
+declare const readDecision: (source: string) => ReadDecision;
+
+/**
+ * The decision, rendered.
+ *
+ * Deterministic to the byte: no timestamp, no git HEAD, no directory scan. Running the applier
+ * twice on the same decision rewrites the same file, which is what "applies deterministically"
+ * means and is why this is not `@geonosis/ledger`'s `captureProof` — that numbers a proof one past
+ * the highest on disk, so the same input lands somewhere else on a different tree.
+ *
+ * The decision is embedded verbatim as well as rendered, so nothing a reader needs is lost to the
+ * rendering and a later tool can read the record back.
+ */
+declare const render: (decision: ReviewDecision) => string;
+/**
+ * Writes the record, and NOTHING else.
+ *
+ * There is no comment to post, no label to set, no approval to give and no forge to reach — by
+ * construction, not by policy: this package has no network client and no forge client in it, and a
+ * test reads the shipped bundle to keep it that way. 2ndm1nd's rail is that the scored agent never
+ * writes the scoreboard; an applier that held a token would be a reviewer that could approve
+ * itself.
+ */
+declare const applyDecision: (decision: ReviewDecision, root: string, proofs: string, slug: string) => string;
+
+export { DECISIONS, REVIEW_DEFAULT, type ReadDecision, type ReviewConfig, type ReviewDecision, ReviewError, type ReviewFinding, SEVERITIES, applyDecision, criteriaOf, decisionSchema, loadReviewConfig, readDecision, render, uncovered };

package/dist/index.js

@@ -0,0 +1,26 @@
+import {
+  DECISIONS,
+  REVIEW_DEFAULT,
+  ReviewError,
+  SEVERITIES,
+  applyDecision,
+  criteriaOf,
+  decisionSchema,
+  loadReviewConfig,
+  readDecision,
+  render,
+  uncovered
+} from "./chunk-PJWPFJAP.js";
+export {
+  DECISIONS,
+  REVIEW_DEFAULT,
+  ReviewError,
+  SEVERITIES,
+  applyDecision,
+  criteriaOf,
+  decisionSchema,
+  loadReviewConfig,
+  readDecision,
+  render,
+  uncovered
+};

package/dist/review-cli.js

@@ -0,0 +1,94 @@
+import {
+  ReviewError,
+  applyDecision,
+  criteriaOf,
+  loadReviewConfig,
+  readDecision,
+  render,
+  uncovered
+} from "./chunk-PJWPFJAP.js";
+
+// src/review-cli.ts
+import { existsSync, readFileSync } from "fs";
+import { basename, resolve } from "path";
+var parse = (argv) => {
+  const out = {};
+  for (let at = 0; at < argv.length; at += 1) {
+    const arg = argv[at];
+    if (arg === void 0) continue;
+    const takes = (name) => {
+      const value = argv[at + 1];
+      if (value === void 0) throw new ReviewError(`${name} needs a value`);
+      at += 1;
+      return value;
+    };
+    if (arg === "--to") out.to = takes("--to");
+    else if (arg === "--slug") out.slug = takes("--slug");
+    else if (arg === "--criteria") out.criteria = takes("--criteria");
+    else if (arg.startsWith("-")) throw new ReviewError(`unknown option ${arg}`);
+    else if (out.verb === void 0) out.verb = arg;
+    else if (out.file === void 0) out.file = arg;
+    else throw new ReviewError(`unexpected argument ${arg}`);
+  }
+  return out;
+};
+var readFile = (root, relative, what) => {
+  if (relative === void 0) throw new ReviewError(`geonosis-review needs ${what}`);
+  const at = resolve(root, relative);
+  if (!existsSync(at)) throw new ReviewError(`${relative}: no such file`);
+  return readFileSync(at, "utf8");
+};
+var Refused = class extends Error {
+};
+var apply = (argv, root) => {
+  const config = loadReviewConfig(root);
+  const source = readFile(root, argv.file, "a decision file to apply");
+  const read = readDecision(source);
+  if (!read.ok) throw new Refused(read.reason);
+  if (argv.to === void 0 || argv.to === "stdout") {
+    process.stdout.write(render(read.decision));
+    return;
+  }
+  if (argv.to !== "ledger")
+    throw new ReviewError(`--to takes "ledger" or "stdout", not "${argv.to}"`);
+  const slug = argv.slug ?? basename(argv.file ?? "review").replace(/\.[^.]+$/, "");
+  process.stdout.write(`${applyDecision(read.decision, root, config.proofs, slug)}
+`);
+};
+var check = (argv, root) => {
+  const config = loadReviewConfig(root);
+  const read = readDecision(readFile(root, argv.file, "a decision file to check"));
+  if (!read.ok) throw new Refused(read.reason);
+  const plan = readFile(root, argv.criteria, "--criteria <plan.md>");
+  const stated = criteriaOf(plan, config);
+  if (stated.length === 0) {
+    throw new ReviewError(
+      `${argv.criteria ?? ""} states no acceptance criteria \u2014 there is nothing to review it against`
+    );
+  }
+  const missed = uncovered(stated, read.decision.criteriaChecked);
+  if (missed.length > 0) {
+    throw new Refused(
+      [`the review did not check ${missed.length} of ${stated.length} criteria:`, ...missed].join(
+        "\n  "
+      )
+    );
+  }
+  process.stdout.write(`all ${stated.length} criteria checked
+`);
+};
+var main = () => {
+  const root = process.cwd();
+  try {
+    const argv = parse(process.argv.slice(2));
+    if (argv.verb === "apply") apply(argv, root);
+    else if (argv.verb === "check") check(argv, root);
+    else throw new ReviewError(`geonosis-review takes "apply" or "check", not "${argv.verb ?? ""}"`);
+  } catch (error) {
+    process.stderr.write(`${error.message}
+`);
+    return error instanceof Refused ? 1 : 2;
+  }
+  return 0;
+};
+process.exitCode = main();

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@geonosis/review",
+  "version": "1.0.0",
+  "description": "The decision-only reviewer contract: a review's sole output is one JSON decision, validated and applied by a step that comments nowhere, approves nothing and cannot reach a forge.",
+  "keywords": [
+    "code-review",
+    "pull-request",
+    "agent",
+    "zod",
+    "gate",
+    "ci",
+    "ears"
+  ],
+  "homepage": "https://github.com/microcompanies/geonosis/tree/main/packages/review",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microcompanies/geonosis.git",
+    "directory": "packages/review"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "geonosis-review": "bin/geonosis-review.mjs"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "zod": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}