@tiangong-lca/pcr 0.1.2 → 0.2.0

package/README.md

@@ -1,7 +1,8 @@
 # @tiangong-lca/pcr
 
-Read TianGong LCA product category rules (PCRs), inspect methodology guidance,
-and validate foreground data drafts from a local content library. This package
+Use TianGong LCA product category rules (PCRs) to guide LCA data creation,
+optionally author TIDAS processes, and support Agent-led review of existing
+TIDAS processes/models using a local content library. This package
 contains the CLI, schemas, bundled runtime dependencies, and a consumer Agent
 Skill. Install the content separately with
 [`@tiangong-lca/pcr-library`](https://www.npmjs.com/package/@tiangong-lca/pcr-library).
@@ -39,6 +40,10 @@ combined with `--library`.
 ./node_modules/.bin/tiangong-pcr coverage summary --classification cpc:3.0 --format json
 ./node_modules/.bin/tiangong-pcr resolve --classification cpc:3.0:01111 --format json
 ./node_modules/.bin/tiangong-pcr guidance --pcr <pcr-id> --format json
+./node_modules/.bin/tiangong-pcr guidance --pcr <pcr-id> --topic boundary --format json
+./node_modules/.bin/tiangong-pcr inspect --input process.json --related ./datasets --section exchanges --format json
+./node_modules/.bin/tiangong-pcr review prepare --pcr <pcr-id> --input process.json --related ./datasets --output review.json --format json
+./node_modules/.bin/tiangong-pcr review check --pcr <pcr-id> --input process.json --related ./datasets --report review.json --format json
 ./node_modules/.bin/tiangong-pcr --help
 ```
 
@@ -48,12 +53,26 @@ compatibility records. Guidance reports readiness and validation coverage:
 candidate content still requires review, and installing a package does not
 approve a methodology. The content package provides English documents only.
 
+Selected guidance returns verified source hashes, applicability and JSON Pointers;
+follow pagination or read complete values with `--pointer`. `inspect` reads native
+TIDAS JSON and explicitly supplied local references without fetching URIs or
+asserting schema validity. `calculate` performs normalization, conversion or
+balance arithmetic with explicit quantities, bases and evidence; see its help.
+
+The Agent fills the draft review after investigating the data. Findings distinguish
+confirmed issues, suspected anomalies and evidence gaps, with input/PCR evidence
+and unreviewed scope. `review check` validates the envelope and references;
+`methodology_approval` remains false. A valid report does not certify its reasoning.
+Use the separately provisioned TIDAS toolkit/SDK for format validation. A foreground
+package is optional; legacy `validate-model` only checks qualifier text and
+`validate-dataset` only checks collection protocol IDs.
+
 ## Fully offline installation
 
 On a connected machine, download both packages:
 
 ```sh
-npm pack @tiangong-lca/pcr@0.1.2
+npm pack @tiangong-lca/pcr@0.2.0
 npm pack @tiangong-lca/pcr-library@0.1.2
 ```
 
@@ -61,7 +80,7 @@ Transfer the two tarballs and a suitable Node.js runtime to the offline machine.
 In the destination directory:
 
 ```sh
-npm install --offline --ignore-scripts --no-audit --no-fund ./tiangong-lca-pcr-0.1.2.tgz ./tiangong-lca-pcr-library-0.1.2.tgz
+npm install --offline --ignore-scripts --no-audit --no-fund ./tiangong-lca-pcr-0.2.0.tgz ./tiangong-lca-pcr-library-0.1.2.tgz
 ./node_modules/.bin/tiangong-pcr library verify --format json
 ```
 
@@ -69,6 +88,8 @@ Runtime dependencies are bundled. No install scripts, runtime downloads, or
 network connection are required. Tool and content versions are independent;
 record both versions and the snapshot hash for reproducible work. Use
 `--library-sha256 sha256:<digest>` to require a specific trusted snapshot hash.
+The CLI does not include an LLM. Fully offline semantic review requires an
+offline-capable Agent/model supplied by the caller.
 
 ## Agent Skill
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiangong-lca/pcr",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "description": "Offline PCR consumer CLI and agent Skill",
   "license": "MIT",
@@ -27,7 +27,7 @@
     "type": "git",
     "url": "git+https://github.com/tiangong-lca/pcr.git"
   },
-  "gitHead": "02f5b58ca242035dcbce41845c4ea92dc8c63d25",
+  "gitHead": "f70d735639de9d21a24ff8959f0330880f969631",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"

package/packages/pcr-core/schemas/agent-review.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiangong-lca.org/schemas/pcr/v1/agent-review.schema.json",
+  "title": "PCR Agent review evidence envelope; never a methodology approval",
+  "type": "object",
+  "required": ["schema_version", "report_kind", "status", "pcr", "inputs", "scope", "coverage", "findings"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "report_kind": { "const": "tiangong-pcr-agent-review" },
+    "status": { "enum": ["draft", "reviewed"] },
+    "pcr": { "$ref": "#/$defs/pcrBinding" },
+    "inputs": { "type": "array", "minItems": 1, "items": {
+      "type": "object", "required": ["file", "sha256", "kind", "uuid", "version"],
+      "properties": {
+        "file": { "$ref": "#/$defs/text" }, "sha256": { "$ref": "#/$defs/hash" },
+        "kind": { "$ref": "#/$defs/text" }, "uuid": { "type": ["string", "null"] }, "version": { "type": ["string", "null"] }
+      }, "additionalProperties": false
+    } },
+    "scope": {
+      "type": "object", "required": ["description", "applicability", "limitations"],
+      "properties": {
+        "description": { "$ref": "#/$defs/text" }, "applicability": { "$ref": "#/$defs/text" },
+        "limitations": { "$ref": "#/$defs/texts" }
+      }, "additionalProperties": true
+    },
+    "coverage": { "type": "array", "minItems": 1, "items": {
+      "type": "object", "required": ["topic", "status", "rationale"],
+      "properties": {
+        "topic": { "$ref": "#/$defs/text" }, "status": { "enum": ["reviewed", "not_applicable", "not_reviewed"] },
+        "rationale": { "$ref": "#/$defs/text" }
+      }, "additionalProperties": true
+    } },
+    "findings": { "type": "array", "items": {
+      "type": "object", "required": ["id", "kind", "severity", "observation", "rationale", "input_refs", "pcr_refs", "suggested_action", "questions"],
+      "properties": {
+        "id": { "$ref": "#/$defs/text" },
+        "kind": { "enum": ["confirmed_issue", "suspected_anomaly", "evidence_gap"] },
+        "severity": { "enum": ["error", "warning", "info"] },
+        "observation": { "$ref": "#/$defs/text" }, "rationale": { "$ref": "#/$defs/text" },
+        "input_refs": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/inputRef" } },
+        "pcr_refs": { "type": "array", "items": { "allOf": [
+          { "$ref": "#/$defs/pcrBinding" },
+          { "type": "object", "required": ["pointer"], "properties": { "pointer": { "type": "string" } } }
+        ] } },
+        "suggested_action": { "$ref": "#/$defs/text" }, "questions": { "$ref": "#/$defs/texts" },
+        "alternative_explanations": { "$ref": "#/$defs/texts" }
+      }, "additionalProperties": true
+    } }
+  },
+  "additionalProperties": true,
+  "$defs": {
+    "text": { "type": "string", "minLength": 1, "pattern": "\\S" },
+    "texts": { "type": "array", "items": { "$ref": "#/$defs/text" } },
+    "hash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "inputRef": {
+      "type": "object", "required": ["file", "sha256", "pointer"],
+      "properties": { "file": { "$ref": "#/$defs/text" }, "sha256": { "$ref": "#/$defs/hash" }, "pointer": { "type": "string" } },
+      "additionalProperties": false
+    },
+    "pcrBinding": {
+      "type": "object", "required": ["pcr_id", "version", "projection_sha256", "markdown_sha256", "methodology_status"],
+      "properties": {
+        "pcr_id": { "$ref": "#/$defs/text" }, "version": { "type": ["string", "null"] },
+        "projection_sha256": { "$ref": "#/$defs/hash" }, "markdown_sha256": { "$ref": "#/$defs/hash" },
+        "methodology_status": { "$ref": "#/$defs/text" }
+      }, "additionalProperties": true
+    }
+  }
+}

package/packages/pcr-core/src/consumption-calculation.mjs

@@ -0,0 +1,53 @@
+import { ConsumptionError, object, strictNumber } from "./consumption-data.mjs";
+
+function text(value, name) {
+  if (typeof value !== "string" || !value.trim()) throw new ConsumptionError("PCR_CALCULATION_INPUT", `${name} must state the unit, basis or evidence explicitly.`, { field: name });
+  return value;
+}
+
+// Arithmetic only: the Agent owns physical equivalence, applicability and evidence.
+export function calculate(request) {
+  if (!object(request)) throw new ConsumptionError("PCR_CALCULATION_INPUT", "Use a JSON object with operation normalize, convert or balance. See calculate --help.");
+  const evidence = text(request.evidence, "evidence");
+  const basis = text(request.basis, "basis");
+  let result;
+  let formula;
+  if (request.operation === "normalize") {
+    const amount = strictNumber(request.amount, "amount");
+    const sourceReference = strictNumber(request.source_reference, "source_reference", { positive: true });
+    const targetReference = strictNumber(request.target_reference, "target_reference", { positive: true });
+    const unit = text(request.unit, "unit");
+    text(request.reference_unit, "reference_unit");
+    result = { amount: amount * targetReference / sourceReference, unit, factor: targetReference / sourceReference };
+    formula = "amount * target_reference / source_reference; both reference quantities share reference_unit and the stated physical basis";
+  } else if (request.operation === "convert") {
+    const amount = strictNumber(request.amount, "amount");
+    const factor = strictNumber(request.factor, "factor", { positive: true });
+    text(request.from_unit, "from_unit");
+    const unit = text(request.to_unit, "to_unit");
+    result = { amount: amount * factor, unit, factor };
+    formula = "amount * factor; factor is explicitly supplied in to_unit / from_unit";
+  } else if (request.operation === "balance") {
+    const unit = text(request.unit, "unit");
+    const sums = {};
+    for (const name of ["inputs", "outputs"]) {
+      if (!Array.isArray(request[name]) || !request[name].length) throw new ConsumptionError("PCR_CALCULATION_INPUT", `${name} must be a non-empty array of {amount, label} in the declared common unit and basis.`);
+      sums[name] = request[name].reduce((sum, item, index) => {
+        if (!object(item)) throw new ConsumptionError("PCR_CALCULATION_INPUT", `${name}[${index}] must be an amount/label object.`);
+        text(item.label, `${name}[${index}].label`);
+        return sum + strictNumber(item.amount, `${name}[${index}].amount`);
+      }, 0);
+    }
+    const accumulation = strictNumber(request.accumulation, "accumulation");
+    result = { input_total: sums.inputs, output_total: sums.outputs, accumulation, residual: sums.inputs - sums.outputs - accumulation, unit };
+    formula = "sum(inputs) - sum(outputs) - accumulation; positive residual is unaccounted net input";
+  } else {
+    throw new ConsumptionError("PCR_CALCULATION_OPERATION", "Use operation normalize, convert or balance. No formulas, factors or units are inferred.");
+  }
+  if (Object.values(result).some((value) => typeof value === "number" && !Number.isFinite(value))) throw new ConsumptionError("PCR_CALCULATION_OVERFLOW", "Calculation produced a non-finite number; rescale or correct the input quantities.");
+  return {
+    schema_version: 1, calculation_kind: "tiangong-pcr-arithmetic", operation: request.operation,
+    request, formula, result, basis, evidence,
+    interpretation: "Arithmetic only, using supplied values and JavaScript floating-point precision. Physical applicability, evidence quality, tolerance and anomaly judgment are not evaluated.",
+  };
+}

package/packages/pcr-core/src/consumption-data.mjs

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+
+export class ConsumptionError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "ConsumptionError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export const sha256 = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+export const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+export const pointerToken = (value) => String(value).replaceAll("~", "~0").replaceAll("/", "~1");
+
+export function atPointer(value, pointer) {
+  if (typeof pointer !== "string" || (pointer !== "" && !pointer.startsWith("/")) || /~(?:[^01]|$)/u.test(pointer)) {
+    throw new ConsumptionError("PCR_POINTER_INVALID", "Use an RFC 6901 JSON Pointer, such as /processDataSet/exchanges/exchange/0.");
+  }
+  if (pointer === "") return value;
+  let current = value;
+  for (const encoded of pointer.slice(1).split("/")) {
+    const key = encoded.replaceAll("~1", "/").replaceAll("~0", "~");
+    if (current === null || typeof current !== "object" || !Object.hasOwn(current, key)
+      || (Array.isArray(current) && !/^(0|[1-9]\d*)$/u.test(key))) {
+      throw new ConsumptionError("PCR_POINTER_NOT_FOUND", `No value exists at ${pointer}. Inspect the summary or a paged section first.`, { pointer });
+    }
+    current = current[key];
+  }
+  return current;
+}
+
+export function readJsonDocument(filename, maxBytes = 16 * 1024 * 1024) {
+  const file = path.resolve(filename);
+  let bytes;
+  try {
+    const stat = statSync(file);
+    if (!stat.isFile() || stat.size > maxBytes) {
+      throw new ConsumptionError("PCR_INPUT_SIZE", `Expected a JSON file no larger than ${maxBytes} bytes: ${file}`);
+    }
+    bytes = readFileSync(file);
+    if (bytes.length > maxBytes) throw new ConsumptionError("PCR_INPUT_SIZE", `Input grew beyond ${maxBytes} bytes: ${file}`);
+  } catch (error) {
+    if (error instanceof ConsumptionError) throw error;
+    throw new ConsumptionError("PCR_INPUT_READ", `Cannot read local JSON file ${file}: ${error.message}`, { file });
+  }
+  try {
+    return { file, sha256: sha256(bytes), bytes: bytes.length, value: JSON.parse(bytes.toString("utf8").replace(/^\uFEFF/u, "")) };
+  } catch (error) {
+    throw new ConsumptionError("PCR_INPUT_JSON", `Malformed JSON in ${file}: ${error.message}`, { file });
+  }
+}
+
+export function entriesAt(value, pointer) {
+  if (value === undefined || value === null) return [];
+  return Array.isArray(value)
+    ? value.map((item, index) => ({ pointer: `${pointer}/${index}`, value: item }))
+    : [{ pointer, value }];
+}
+
+export function paginate(items, page = 1, pageSize = 10) {
+  if (!Number.isSafeInteger(page) || page < 1 || !Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 100) {
+    throw new ConsumptionError("PCR_PAGE_INVALID", "Use --page >= 1 and --page-size from 1 to 100.");
+  }
+  const pages = Math.max(1, Math.ceil(items.length / pageSize));
+  if (page > pages) throw new ConsumptionError("PCR_PAGE_RANGE", `Page ${page} exceeds ${pages}; use --page ${pages}.`);
+  return {
+    items: items.slice((page - 1) * pageSize, page * pageSize),
+    pagination: { page, page_size: pageSize, total: items.length, total_pages: pages, has_more: page < pages },
+  };
+}
+
+export function preview(value, maxChars = 2400) {
+  const json = JSON.stringify(value);
+  return json.length <= maxChars ? { value, truncated: false }
+    : { excerpt: json.slice(0, maxChars), truncated: true, total_characters: json.length };
+}
+
+export function strictNumber(value, name, { positive = false } = {}) {
+  if ((typeof value !== "number" && typeof value !== "string")
+    || (typeof value === "string" && !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/u.test(value))
+    || !Number.isFinite(Number(value)) || (positive && Number(value) <= 0)) {
+    throw new ConsumptionError("PCR_NUMBER_INVALID", `${name} must be a finite${positive ? " positive" : ""} decimal number. Missing values are not zero.`, { field: name });
+  }
+  return Number(value);
+}

package/packages/pcr-core/src/consumption-guidance.mjs

@@ -0,0 +1,62 @@
+import { getVerifiedPcrProjection } from "./index.mjs";
+import { ConsumptionError, atPointer, entriesAt, paginate, preview } from "./consumption-data.mjs";
+
+const TOPICS = {
+  overview: ["product_category_identity", "functional_unit", "boundary_abstraction"],
+  "reference-flow": ["functional_unit", "reference_flow_definition"],
+  boundary: ["system_boundary/rules", "boundary_abstraction"],
+  measurement: ["measurement_rules"],
+  inventory: ["process_map", "process_inventory"],
+  collection: ["dataset_production/collection_protocols"],
+  calculation: ["dataset_production/calculation_rules"],
+  allocation: ["allocation_rules"],
+  quality: ["data_quality_rules", "dataset_production/data_quality_requirements", "published_dataset_profile"],
+  validation: ["validation_rules"],
+  sources: ["data_sources"],
+};
+export const GUIDANCE_TOPICS = Object.keys(TOPICS);
+
+export function projectionBinding(snapshot) {
+  return {
+    pcr_id: snapshot.pcr.id,
+    version: snapshot.pcr.version,
+    projection_sha256: snapshot.structured.projection_metadata.generated_content_sha256,
+    markdown_sha256: snapshot.structured.projection_metadata.canonical_markdown.sha256,
+    methodology_status: snapshot.readiness.methodology_status,
+  };
+}
+
+export function pcrEvidence(snapshot, pointer) {
+  return { ...projectionBinding(snapshot), pointer };
+}
+
+export function selectGuidance({ root, pcrId, topic = "overview", pointer, page = 1, pageSize = 10 }) {
+  const snapshot = getVerifiedPcrProjection({ root, pcrId });
+  const base = {
+    schema_version: 1, guidance_kind: "tiangong-pcr-guidance-selection",
+    pcr: projectionBinding(snapshot), readiness: snapshot.readiness,
+    source_structured: snapshot.source_structured,
+    source_markdown: snapshot.source_structured.replace(/structured\.yaml$/u, "pcr.en-US.md"),
+    topics: GUIDANCE_TOPICS,
+    citation_note: "Pointers address this verified structured projection. Preserve its hashes; applicability remains an Agent judgment. Explicit rule IDs may persist across revisions; array pointers are snapshot-bound.",
+  };
+  if (pointer !== undefined) {
+    return { ...base, source: pcrEvidence(snapshot, pointer), value: atPointer(snapshot.structured, pointer) };
+  }
+  if (!Object.hasOwn(TOPICS, topic)) throw new ConsumptionError("PCR_GUIDANCE_TOPIC", `Use --topic ${GUIDANCE_TOPICS.join("|")}.`);
+  const entries = [];
+  for (const name of TOPICS[topic]) {
+    const pointer = `/${name}`;
+    let value;
+    try { value = atPointer(snapshot.structured, pointer); }
+    catch (error) { if (error.code !== "PCR_POINTER_NOT_FOUND") throw error; }
+    for (const entry of entriesAt(value, pointer)) {
+      entries.push({
+        source: pcrEvidence(snapshot, entry.pointer),
+        rule_id: entry.value?.rule_id ?? entry.value?.protocol_id ?? entry.value?.row_id ?? entry.value?.id ?? null,
+        ...preview(entry.value),
+      });
+    }
+  }
+  return { ...base, topic, ...paginate(entries, page, pageSize) };
+}

package/packages/pcr-core/src/consumption-review.mjs

@@ -0,0 +1,83 @@
+import { atPointer } from "./consumption-data.mjs";
+import { getVerifiedPcrProjection } from "./index.mjs";
+import { projectionBinding } from "./consumption-guidance.mjs";
+import { documentIdentity, extractReferences, loadTidasContext } from "./tidas-inspection.mjs";
+import { validateCoreContract } from "./contracts.mjs";
+
+const TOPICS = ["scope_and_applicability", "reference_basis", "inventory_and_boundary", "allocation", "data_quality"];
+
+export function prepareReview({ root, pcrId, input, related }) {
+  const snapshot = getVerifiedPcrProjection({ root, pcrId });
+  const context = loadTidasContext({ input, related });
+  const unresolved = extractReferences(context).filter((reference) => reference.status !== "resolved");
+  return {
+    schema_version: 1, report_kind: "tiangong-pcr-agent-review", status: "draft",
+    pcr: projectionBinding(snapshot), inputs: context.documents.map(documentIdentity),
+    scope: {
+      description: `Review of supplied ${context.primary.kind}; the Agent must establish its declared scope and reference basis.`,
+      applicability: "Not assessed. Explain product, technology, gate and PCR applicability before drawing conclusions.",
+      limitations: [
+        "No semantic review or TIDAS schema validation has been performed by this command.",
+        `${unresolved.length} reference(s) could not be uniquely resolved in the supplied local inputs; inspect references before claiming omissions.`,
+        `${context.ignoredFiles.length} JSON file(s) with no native TIDAS dataset root were ignored by input inspection.`,
+        `PCR methodology status: ${snapshot.readiness.methodology_status}; library availability does not promote candidate methodology.`,
+      ],
+    },
+    coverage: TOPICS.map((topic) => ({ topic, status: "not_reviewed", rationale: "Awaiting Agent investigation of applicability and evidence." })),
+    findings: [],
+  };
+}
+
+export function checkReview({ root, pcrId, input, related, report }) {
+  const shape = validateCoreContract("agent-review.schema.json", report);
+  const issues = [];
+  const add = (code, location, message) => issues.push({ code, location, message });
+  if (!shape.valid) {
+    for (const error of shape.issues ?? shape.errors) add("report_shape", error.instance_path ?? error.instancePath ?? "", error.message);
+  } else {
+    const snapshot = getVerifiedPcrProjection({ root, pcrId });
+    const binding = projectionBinding(snapshot);
+    const context = loadTidasContext({ input, related });
+    const actual = context.documents.map(documentIdentity);
+    const files = new Map(context.documents.map((doc) => [doc.file, doc]));
+    const sameBinding = (candidate) => Object.keys(binding).every((key) => candidate[key] === binding[key]);
+    if (!sameBinding(report.pcr)) add("pcr_changed", "/pcr", "PCR identity, content hashes or methodology status differ from the selected verified projection.");
+    if (report.inputs.length !== actual.length || report.inputs.some((item, index) => Object.keys(actual[index] ?? {}).some((key) => item[key] !== actual[index][key]))) {
+      add("inputs_changed", "/inputs", "Input files, identities, order or exact-byte hashes differ. Regenerate the draft bindings and review the changed evidence.");
+    }
+    if (report.status === "reviewed" && !report.coverage.some((item) => item.status === "reviewed")) add("review_empty", "/coverage", "A reviewed report must name at least one actually reviewed topic; otherwise retain draft status.");
+    const ids = new Set();
+    for (const [index, finding] of report.findings.entries()) {
+      const prefix = `/findings/${index}`;
+      if (ids.has(finding.id)) add("duplicate_finding", `${prefix}/id`, "Finding IDs must be unique within this report.");
+      ids.add(finding.id);
+      for (const [refIndex, reference] of finding.input_refs.entries()) {
+        const location = `${prefix}/input_refs/${refIndex}`;
+        const doc = files.get(reference.file);
+        if (!doc || reference.sha256 !== doc.sha256) add("input_reference_changed", location, "Reference must identify an explicitly supplied input and its current exact-byte hash.");
+        else {
+          try { atPointer(doc.value, reference.pointer); }
+          catch (error) { add("input_pointer", location, error.message); }
+        }
+      }
+      for (const [refIndex, reference] of finding.pcr_refs.entries()) {
+        const location = `${prefix}/pcr_refs/${refIndex}`;
+        if (!sameBinding(reference)) add("pcr_reference_changed", location, "PCR reference does not match the selected verified projection.");
+        else {
+          try { atPointer(snapshot.structured, reference.pointer); }
+          catch (error) { add("pcr_pointer", location, error.message); }
+        }
+      }
+    }
+  }
+  return {
+    schema_version: 1, check_kind: "tiangong-pcr-review-envelope-check",
+    envelope_valid: issues.length === 0, methodology_approval: false,
+    report_status: shape.valid ? report.status : null,
+    checked: ["report_shape", ...(shape.valid ? ["input_and_pcr_bindings", "finding_reference_locations", "review_status_consistency"] : [])],
+    not_checked: ["PCR applicability", "truth of observations or conclusions", "sufficiency of evidence", "coverage completeness", "TIDAS schema validity"],
+    issues,
+    next_step: issues.length ? "Correct the report or re-review changed evidence, then run review check again."
+      : "Have the Agent/user assess the reasoning and remaining scope. Envelope validity does not approve the dataset.",
+  };
+}

package/packages/pcr-core/src/contracts.mjs

@@ -8,6 +8,7 @@ import {
 
 const CORE_SCHEMA_DEPENDENCY_FILES = ["controlled-vocabulary.schema.json"];
 const CORE_SCHEMA_FILES = [
+  "agent-review.schema.json",
   "classification-coverage.schema.json",
   "dataset-validation-input.schema.json",
   "feedback-draft-output.schema.json",
@@ -29,6 +30,7 @@ const schemaDependencies = CORE_SCHEMA_DEPENDENCY_FILES.map((fileName) =>
 );
 const contractIds = new Map(schemaEntries.map(({ fileName, schema }) => [fileName, schema.$id]));
 const entityKindsByFile = {
+  "agent-review.schema.json": "agent_review",
   "classification-coverage.schema.json": "classification_coverage",
   "dataset-validation-input.schema.json": "dataset_validation_input",
   "feedback-draft-output.schema.json": "feedback_draft_output",

package/packages/pcr-core/src/index.mjs

@@ -738,9 +738,9 @@ function buildGuidanceForOperation({ root, pcrId, operation, context = null }) {
     validation_rules: structured.validation_rules ?? [],
     data_sources: structured.data_sources ?? [],
     validation_notes: [
-      "Use this guidance as the source of Tiangong foreground data collection package requirements.",
-      "Preserve Tiangong UUIDs exactly and keep PCR-derived UUID references version-free.",
-      "Run tiangong-pcr validate-dataset after constructing a foreground data package and draft feedback if PCR guidance is missing or ambiguous.",
+      "Use this guidance for LCA data authoring, optional TIDAS process authoring, or Agent-led review of existing process/model data. Select requirements for the declared scope.",
+      "Preserve PCR-derived UUID identities exactly. They are version-free suggestions; preserve and verify explicit versions on supplied TIDAS dataset references.",
+      "validate-model checks qualifier text presence; validate-dataset checks collection protocol ID presence. Neither performs TIDAS schema validation or semantic review. Use inspect and review prepare/check to support Agent-led review; a foreground package is optional.",
     ],
   };
   assertCoreContract("guidance-output.schema.json", guidance, {