# GEOmend stable review contract

GEOmend accepts GSE accessions, family-SOFT files, CSV, TSV, and a versioned
YAML manifest. Planning is offline and identifies ambiguous entity scope,
layout, identifiers, duplicate headers, missing files, and changed hashes.
Running creates a pending-review SQLite workspace plus immutable evidence.

All reviewers use the same identity, packet, evidence, and decision contract.
Permissions are granted through explicit scopes, independently of reviewer metadata.

Always call `geomend capabilities --json`, then `geomend reconcile plan`.
Resolve blockers in the generated manifest before `geomend reconcile run`.
Inspect with `geomend review show`. Create portable assignments with `geomend
review assign`. Import returned opinions only through `geomend review import`.
Use `nomatch` when no selectable target applies, or `defer` when more evidence
is needed. `geomend export data` exports reviewed mappings by default
and leaves source files intact.

For a portable reviewer assignment, run `geomend review show PACKET --json`.
`PACKET` should be a `.geomend-review.zip` or `.geomend-response.zip` file.
The result includes progress, the next unanswered evidence
card, ranked complete variants, and argv-style next actions. Use `geomend review
show PACKET --source-id SOURCE_ID --json` only when additional fixed evidence
is needed. Record the current preference with `geomend review decide PACKET
--accept A1 --rationale RATIONALE --json`. Use `--nomatch` when no
selectable target applies, or `--defer` when evidence is insufficient. When only some sources directly represent the target,
repeat `--merge-source SOURCE_ID`; every unselected source remains unresolved.
The issued packet remains unchanged; the command
writes an atomic `.geomend-response.zip` and returns the next case. No SQLite database,
server, token, Ollama runtime, or manual JSON editing is required for packet
review.

When `ready_to_return` is true, return the `.geomend-response.zip` file. A
coordinator imports it with `geomend review import STATE RESPONSE --json`.

`geomend review derive STATE POLICY.yaml OUTPUT_DIR --json` creates an immutable,
view of attributed opinions using the supplied policy. The workspace's current
mappings remain unchanged. Select it explicitly with `geomend export
STATE OUTPUT_DIR --derived-view VIEW_ID --json`.

For reviewed value or shape transformations, use a native LinkML-Map
`TransformationSpecification`. Validate and hash-bind it with `geomend
workspace transformation validate SPEC --source-schema SOURCE --target-schema
TARGET --linkml-map-version VERSION --output ENVELOPE`. The LinkML-Map object defines the transformation. GEOmend stores review metadata
separately, and generates R, Python, or SQL from that specification.

JSON errors contain `code`, `message`, `remediation`, and `details`. Exit codes:
2 invocation, 3 incomplete input, 4 environment, 5 acquisition, 6 validation,
7 internal failure.
