# Release Evidence State Schema

Release governance uses three states so agent-assisted drafts, verified files, and final human evidence stay visibly separate.

| State | Meaning | Allowed use | Promotion gate |
| --- | --- | --- | --- |
| `draft_advisory` | Agent review, Gemini review, prefill output, simulation, draft label, reviewer note, or provisional working file. | Planning, triage, risk review, candidate wording, and follow-up tracking. | Cannot support final claims. Requires artifact verification or human confirmation before promotion. |
| `verified_artifact` | A concrete file, count, checksum, manifest, figure, table, dataset slice, or export has been checked against an exact ref or named external artifact. | Artifact existence, provenance, counts, checksums, and bounded claims within the verified scope. | Requires a command, checksum, manifest, or manual artifact check recorded in the packet. |
| `human_final` | A human reviewer, adjudicator, coordinator, or author has explicitly confirmed the evidence according to the project gate. | Human-label claims, adjudication conclusions, reviewer decisions, final wording approvals, and release sign-off. | Requires explicit human confirmation fields, reviewer identity or role, review date, and matching denominator or scope. |

## Minimal Packet Schema

Required files:

- `release/release_scope.md`
- `release/canonical_refs.csv`
- `release/local_asset_inventory.csv`
- `release/artifact_anchors.csv`
- `release/evidence_gates.csv`
- `release/claim_ledger.csv`
- `release/verification_report.md`

Required CSV columns:

| File | Columns |
| --- | --- |
| `canonical_refs.csv` | `ref_name`, `sha`, `date`, `status`, `canonical_for`, `caveat` |
| `local_asset_inventory.csv` | `path`, `status`, `file_count`, `size`, `role`, `release_action` |
| `artifact_anchors.csv` | `artifact_id`, `source_ref`, `source_path`, `count_or_checksum`, `evidence_state`, `verified_by`, `claim_supported` |
| `evidence_gates.csv` | `gate_id`, `artifact_id`, `evidence_state`, `human_confirmed`, `reviewer`, `review_date`, `validator`, `status` |
| `claim_ledger.csv` | `claim_id`, `claim_text`, `artifact_ids`, `evidence_state`, `denominator`, `scope_boundary`, `human_gate_required`, `status` |

## Gate Rules

1. `draft_advisory` rows must not be described as final evidence.
2. `verified_artifact` rows need an exact ref, artifact path, manifest, count, checksum, or recorded manual check.
3. `human_final` rows need explicit confirmation, reviewer or coordinator identity, review date, and a denominator or scope boundary.
4. Agent or Gemini review can flag risks, but it cannot promote any row to `human_final`.
5. Repository checks prove repository state only; they do not prove venue, ethics, licensing, or scientific compliance.

# Manuscript Reframing Patterns

Use this reference when a draft reads like an engineering report, module inventory, internal validation packet, or project status report rather than a scientific manuscript.

## Core Reframing Rule

Write around the scientific problem, not the implementation inventory.

Bad center of gravity:

```text
We built module A, module B, module C, reports, figures, and generative-model tests.
```

Better center of gravity:

```text
The field assumes X, but downstream use requires Y. This work defines the missing interface, evaluates the reliability gap, and shows how conservative routing changes what can be safely surfaced.
```

## Problem First, Modules Second

Before rewriting, force the manuscript into one sentence:

```text
This paper solves [specific reliability / evidence / workflow gap] between [upstream technical output] and [downstream scientific or operator-facing use].
```

For action-adjacent or human-facing AI manuscripts, prefer problem statements such as:

- Segmentation outputs are not automatically evidence objects.
- High mask metrics do not guarantee downstream task reliability.
- Uncertain perception should be routed, not silently converted into support.
- Reports and interfaces need explicit claim boundaries.
- Machine-readable records must not imply execution permission unless validated for that role.

## Contribution Shape

Avoid long module lists. Use a small contribution chain that explains why each piece exists.

Recommended structure:

1. Problem formulation: define the reliability or evidence gap.
2. Interface definition: convert raw outputs into structured evidence objects.
3. Bottleneck measurement: quantify where upstream metrics and downstream claims diverge.
4. Conservative routing: expose reliability-coverage trade-offs and review capture.
5. Bounded output: produce traceable reports or records without unsupported claims.

Each contribution should answer: what gap does this close, and what evidence supports it?

## Results Narrative

Do not present results as raw artifact counts or CSV-style metrics. Use result paragraphs that explain the transition:

- Perception metric: what the frozen model achieved.
- Direct conversion: what fails when outputs are treated as task evidence.
- Gate effect: how selective support changes agreement and coverage.
- Failure taxonomy: which bottleneck dominates.
- Bounded output audit: whether generated reports or records stayed within evidence.

Keep exact numbers in tables. In prose, translate audit-zero metrics into natural language when clearer:

```text
The audit detected no unsupported statements, contradictions, or prohibited action claims.
```

instead of

```text
unsupported rate 0.000, contradiction rate 0.000, prohibited rate 0.000
```

## Handling Low Values

Low support or coverage is not automatically a failure. Explain whether it means:

- the model missed evidence,
- geometry conversion failed,
- the gate correctly withheld weak evidence,
- a task is intentionally conservative,
- or the dataset lacks enough evaluable cases.

Use wording such as:

```text
Low supported coverage indicates conservative evidence routing under the frozen gate, not a direct measure of segmentation accuracy.
```

## Generative-Model Positioning

Do not let generative-model experiments steal the manuscript thesis unless they are the locked primary experiment.

Safe hierarchy:

- Primary result: deterministic, evidence-grounded, rule-based, or schema-validated workflow.
- Supplementary extension: frozen text-only or image-conditioned formatting tests.
- Future work: live clinical reporting, open-ended reasoning, or deployment validation.

Boundary phrases:

- format structured evidence only
- no new findings
- no geometry recomputation
- no gate override
- no action command
- no clinical or execution decision

Avoid phrases that imply clinical reasoning, autonomous operation, controller updates, or action recommendations unless explicitly negated as non-goals.

## Figure Design

Figures must carry the argument, not decorate the paper.

Useful figure roles:

1. Gap figure: show traditional pipeline versus proposed evidence-routed pipeline.
2. Dataset/evidence standard figure: show source images, annotation states, and evidence products.
3. Boundary figure: show what may pass through the interface and what is blocked.
4. Real-example figure: show actual cases where visual plausibility and task evidence diverge.

Keep small operational details in captions or supplement. Avoid tiny file names, internal IDs, dense JSON fragments, or floating checklist boxes inside figures.

### Figure Evidence Boundaries

Do not let a figure imply stronger evidence than the artifact supports.

- Use `panel`, `evidence construction panel`, `record-grounded replay panel`, or another function-specific label when the figure explains an evidence interface rather than showing raw empirical imagery.
- Avoid `schematic`, `synthetic`, and `proxy` in submission-facing captions when those words make the figure look like a placeholder or weaken confidence in the data source.
- Do not call a panel `raw microscopy`, `real replay`, or `ground truth` unless it is anchored to the actual locked artifact.
- State what the figure reads from: stored evidence fields, gated records, replay overlays, boundary cards, or raw image data.
- If no locked raw image panel exists, say the limitation in status notes or cover materials; do not smuggle it into a caption as if the figure were final empirical evidence.

## Table Design

Main tables should be compact and interpretation-led.

- Bold key locked values if journal style permits.
- Move wide per-case/per-item logs to supplement.
- Avoid raw CSV-style tables in the main manuscript.
- If a denominator is small, say so next to the value.
- If confidence intervals are descriptive only, label them as such.

### Main-Text Table Hardening

Main-text tables should be rewritten for the paper, not copied from reproducibility artifacts.

- Remove local paths, source columns, representative case IDs, filenames, JSON field names, and internal snake_case headers from main-text tables.
- Convert raw artifact tables into compact reader-facing summaries with title-case headers and interpretation columns.
- Keep only fields needed to answer the research question; move traceability fields to source maps, appendices, or reproducibility packages.
- Prefer p-column wrapping and fewer columns over `\resizebox{\linewidth}{!}`. A table that fits by becoming unreadable has not been fixed.
- Replace slash-heavy or unbreakable tokens when they cause layout issues, e.g. use `oocyte and oolemma geometry` rather than `oocyte/oolemma geometry`.
- Treat tables that render as tiny bands, illegible text, or dense horizontal strips as blockers even if LaTeX reports no overfull warning.

### PDF Artifact Hygiene

Before calling a manuscript PDF ready for review, verify the rendered PDF, not only the source files.

- Compile until the final log has no undefined citations, undefined references, or overfull table warnings.
- Render the PDF pages to images and inspect a contact sheet plus any table/figure-heavy pages at full size.
- Extract PDF text and scan for stale version markers, placeholder terms, local paths, `\textbackslash`, raw snake_case fields, and copied table-number prefixes.
- Use explicit required/forbidden marker checks for known review issues, such as required figure captions and forbidden placeholder wording.
- Keep final generated PDFs outside sync-sensitive paths when requested or when sync/permission problems are likely; use a temp or explicit release directory instead.

## Submission Readiness Gate

A draft can be scientifically improved but still not submission-ready. Check separately:

- author list and affiliations
- ethics approval or waiver statement
- funding
- competing interests
- CRediT roles
- data/code availability
- reference verification
- figure source provenance
- no placeholders in the main manuscript

Classify honestly:

- supervisor-review ready
- submission-prep ready
- submission ready

Do not call a paper submission-ready while metadata, ethics, data availability, or references remain unresolved.

# Release Workflow Templates

These templates are intentionally file-driven. They are for manuscripts, datasets, review packets, artifact bundles, claim registers, rebuttal packages, and camera-ready checks.

## Scope

`release/release_scope.md`

```text
# Release Scope

Scope date: 2026-05-31
Paper/artifact: Generic review packet
Deadline/use: collaborator handoff
Included refs: refs/heads/main at abcdef1234567890
Excluded refs: none
Evidence baseline: results/table snapshot or artifact ref at abcdef1234567890
Argument baseline: author-approved intent and manuscript version
Open question: whether an optional asset should stay local-only
```

## Canonical Refs

`release/canonical_refs.csv`

```text
ref_name,sha,date,status,canonical_for,caveat
main,abcdef1234567890,2026-05-31,clean,manuscript,none
```

## Local Asset Inventory

`release/local_asset_inventory.csv`

```text
path,status,file_count,size,role,release_action
figures/source/tracked.png,tracked,1,42K,figure source,keep tracked
data/private-cache,ignored,120,80M,local review cache,exclude and document boundary
```

Allowed status values can be project-specific, but common values are `tracked`, `ignored`, `untracked`, `external-store`, and `generated`.

## Artifact Anchors

`release/artifact_anchors.csv`

```text
artifact_id,source_ref,source_path,count_or_checksum,evidence_state,verified_by,claim_supported
fig1,main,figures/source/tracked.png,sha256:abc,verified_artifact,manual checksum,figure provenance
```

## Evidence Gates

`release/evidence_gates.csv`

```text
gate_id,artifact_id,evidence_state,human_confirmed,reviewer,review_date,validator,status
gate1,fig1,human_final,true,Reviewer One,2026-05-31,manual packet review,passed
```

Use `draft_advisory` for agent or Gemini reviews. Use `verified_artifact` for deterministic artifact checks. Use `human_final` only for explicit human confirmation.

## Claim Ledger

`release/claim_ledger.csv`

```text
claim_id,claim_text,artifact_ids,evidence_state,denominator,scope_boundary,human_gate_required,status
c1,The figure is anchored to a tracked source artifact,fig1,verified_artifact,one figure,provenance only,false,supported
```

Check every row for:

- stale denominators
- subset-to-universe inflation
- "final", "submitted", "merged", or "human" wording unsupported by the gate
- local-only assets used as if they were release artifacts
- advisory reviews used as final evidence

## Verification Report

`release/verification_report.md`

```text
# Verification Report

Canonical refs:
- main at abcdef1234567890 -> manuscript and tracked artifacts

Advisory reviews:
- Gemini scope review -> risks reviewed; no evidence-state promotion

Verification:
- python .claude/skills/release-governance/scripts/check_release_packet.py . -> clean
- git diff --check -> clean

Residual risk:
- Optional external asset still needs owner decision before submission.
```

## Handoff Packet

End release or rebuttal handoff with:

| Item | Location | Ref/SHA | Owner | Next action |
| --- | --- | --- | --- | --- |
| Manuscript | `chapters/` or final export | exact SHA | author | final venue checklist |
| Artifact manifest | `release/artifact_anchors.csv` | exact SHA | maintainer | checksum review |
| Claim ledger | `release/claim_ledger.csv` | exact SHA | reviewer | approve or revise unsupported claims |

#!/usr/bin/env python3
"""Lightweight validation for release-governance packets."""

from __future__ import annotations

import argparse
import csv
import json
import re
import sys
from pathlib import Path
from typing import Dict, Iterable, List, Optional, Sequence, Tuple


ALLOWED_EVIDENCE_STATES = {"draft_advisory", "verified_artifact", "human_final"}

REQUIRED_FILES: Dict[str, Sequence[str]] = {
    "release/release_scope.md": (),
    "release/canonical_refs.csv": ("ref_name", "sha", "date", "status", "canonical_for", "caveat"),
    "release/local_asset_inventory.csv": ("path", "status", "file_count", "size", "role", "release_action"),
    "release/artifact_anchors.csv": (
        "artifact_id",
        "source_ref",
        "source_path",
        "count_or_checksum",
        "evidence_state",
        "verified_by",
        "claim_supported",
    ),
    "release/evidence_gates.csv": (
        "gate_id",
        "artifact_id",
        "evidence_state",
        "human_confirmed",
        "reviewer",
        "review_date",
        "validator",
        "status",
    ),
    "release/claim_ledger.csv": (
        "claim_id",
        "claim_text",
        "artifact_ids",
        "evidence_state",
        "denominator",
        "scope_boundary",
        "human_gate_required",
        "status",
    ),
    "release/verification_report.md": (),
}

TEXT_EXTENSIONS = {".csv", ".json", ".md", ".txt", ".yaml", ".yml"}
STRUCTURED_EXTENSIONS = {".csv", ".json", ".yaml", ".yml"}

UNRESOLVED_CJK_MARKERS = "|".join((chr(0x5F85) + chr(0x8865), chr(0x5F85) + chr(0x5B9A)))
MARKER_RE = re.compile(
    r"\b(to\s*do|tbd|fix\s*me|xxx|replace me|fill in|pending update|placeholder|path/to|sample only)\b|"
    + UNRESOLVED_CJK_MARKERS,
    re.IGNORECASE,
)
LOCAL_PATH_RE = re.compile(
    r"(^|[\s'\"(,;:])((/[Uu]sers|/[Hh]ome|/[Pp]rivate|/[Tt]mp|/[Vv]ar/[Ff]olders)(/|\b)|[A-Za-z]:\\)"
)


def issue(kind: str, path: str, detail: str, line: Optional[int] = None) -> Dict[str, object]:
    item: Dict[str, object] = {"kind": kind, "path": path, "detail": detail}
    if line is not None:
        item["line"] = line
    return item


def iter_packet_files(root: Path) -> Iterable[Path]:
    release_dir = root / "release"
    if not release_dir.is_dir():
        return []
    return (path for path in sorted(release_dir.rglob("*")) if path.is_file())


def read_text(path: Path) -> str:
    return path.read_text(encoding="utf-8-sig")


def check_text(path: Path, rel: str) -> List[Dict[str, object]]:
    issues: List[Dict[str, object]] = []
    if path.suffix.lower() not in TEXT_EXTENSIONS:
        return issues
    try:
        text = read_text(path)
    except UnicodeDecodeError as exc:
        return [issue("decode-error", rel, str(exc))]
    for line_no, line in enumerate(text.splitlines(), start=1):
        if MARKER_RE.search(line):
            issues.append(issue("placeholder-text", rel, "remove unresolved template marker or working note", line_no))
        if LOCAL_PATH_RE.search(line):
            issues.append(issue("local-absolute-path", rel, "replace local absolute path with a relative path or external artifact identifier", line_no))
    return issues


def read_csv(path: Path) -> Tuple[List[str], List[Dict[str, str]]]:
    with path.open("r", encoding="utf-8-sig", newline="") as handle:
        reader = csv.DictReader(handle)
        rows = list(reader)
    if reader.fieldnames is None:
        raise ValueError("no header row")
    return list(reader.fieldnames), rows


def parse_yaml_fallback(text: str) -> None:
    stack = []
    for raw_line in text.splitlines():
        line = raw_line.strip()
        if not line or line.startswith("#"):
            continue
        if line.startswith("- "):
            stack.append(line)
            continue
        if ":" not in line:
            raise ValueError("line is not a simple yaml mapping or list item")


def parse_structured(path: Path) -> None:
    suffix = path.suffix.lower()
    if suffix == ".csv":
        read_csv(path)
    elif suffix == ".json":
        json.loads(read_text(path))
    elif suffix in {".yaml", ".yml"}:
        text = read_text(path)
        try:
            import yaml  # type: ignore
        except Exception:
            parse_yaml_fallback(text)
        else:
            yaml.safe_load(text)


def check_required_file(root: Path, rel: str, columns: Sequence[str]) -> List[Dict[str, object]]:
    path = root / rel
    if not path.exists():
        return [issue("missing-file", rel, "required release packet file is missing")]
    if not path.is_file():
        return [issue("not-file", rel, "required path is not a file")]
    if path.suffix.lower() != ".csv":
        return []
    try:
        fieldnames, rows = read_csv(path)
    except Exception as exc:
        return [issue("csv-parse-error", rel, str(exc))]
    missing = [column for column in columns if column not in fieldnames]
    issues: List[Dict[str, object]] = []
    if missing:
        issues.append(issue("missing-columns", rel, ", ".join(missing)))
    issues.extend(check_evidence_states(rel, rows))
    issues.extend(check_human_final_gate(rel, rows))
    return issues


def check_evidence_states(rel: str, rows: List[Dict[str, str]]) -> List[Dict[str, object]]:
    issues: List[Dict[str, object]] = []
    for index, row in enumerate(rows, start=2):
        value = (row.get("evidence_state") or "").strip()
        if value and value not in ALLOWED_EVIDENCE_STATES:
            issues.append(issue("invalid-evidence-state", rel, value, index))
    return issues


def truthy(value: str) -> bool:
    return value.strip().lower() in {"true", "yes", "y", "1", "confirmed", "passed"}


def check_human_final_gate(rel: str, rows: List[Dict[str, str]]) -> List[Dict[str, object]]:
    issues: List[Dict[str, object]] = []
    for index, row in enumerate(rows, start=2):
        if (row.get("evidence_state") or "").strip() != "human_final":
            continue
        if "human_confirmed" in row and not truthy(row.get("human_confirmed", "")):
            issues.append(issue("human-final-gate-missing", rel, "human_final row needs human_confirmed=true", index))
        if "reviewer" in row and not row.get("reviewer", "").strip():
            issues.append(issue("human-final-gate-missing", rel, "human_final row needs reviewer", index))
        if "review_date" in row and not row.get("review_date", "").strip():
            issues.append(issue("human-final-gate-missing", rel, "human_final row needs review_date", index))
    return issues


def validate(root: Path) -> List[Dict[str, object]]:
    issues: List[Dict[str, object]] = []
    release_dir = root / "release"
    if not release_dir.is_dir():
        issues.append(issue("missing-directory", "release", "release packet directory is missing"))

    for rel, columns in REQUIRED_FILES.items():
        issues.extend(check_required_file(root, rel, columns))

    for path in iter_packet_files(root):
        rel = path.relative_to(root).as_posix()
        issues.extend(check_text(path, rel))
        if path.suffix.lower() in STRUCTURED_EXTENSIONS:
            try:
                parse_structured(path)
            except Exception as exc:
                issues.append(issue("parse-error", rel, str(exc)))
    return issues


def emit_text(root: Path, issues: List[Dict[str, object]]) -> None:
    print("Release packet root: {}".format(root))
    if not issues:
        print("- no release packet issues detected")
        return
    print("- issues: {}".format(len(issues)))
    for item in issues:
        location = item["path"]
        if "line" in item:
            location = "{}:{}".format(location, item["line"])
        print("- {kind}: {location}: {detail}".format(location=location, **item))


def main() -> int:
    parser = argparse.ArgumentParser(description="Validate a release-governance packet.")
    parser.add_argument("root", nargs="?", default=".", help="project root containing release/")
    parser.add_argument("--json", action="store_true", dest="emit_json", help="emit machine-readable output")
    args = parser.parse_args()

    root = Path(args.root).resolve()
    if not root.is_dir():
        sys.stderr.write("error: root is not a directory\n")
        return 2

    issues = validate(root)
    payload = {
        "schema_version": 1,
        "root": str(root),
        "issues": issues,
        "issue_count": len(issues),
        "allowed_evidence_states": sorted(ALLOWED_EVIDENCE_STATES),
    }
    if args.emit_json:
        print(json.dumps(payload, indent=2, sort_keys=True))
    else:
        emit_text(root, issues)
    return 1 if issues else 0


if __name__ == "__main__":
    raise SystemExit(main())