# Evidence Status Schema

| Status | Meaning | Allowed use |
| --- | --- | --- |
| `verified_full_text_supported` | Full text or structured full-text notes have been reviewed locally. | Can support claims within verified scope. |
| `published_anchor_supported` | Published direct anchor for the central review domain. | Can support central claims with stated cautions. |
| `direct_domain_full_text_supported` | Full-text evidence directly studies the target domain. | Domain-specific claims. |
| `background_supported` | Full-text evidence from an adjacent background domain. | Context only. |
| `methodological_support_only` | Evidence supports method rationale. | Method framing, not target-domain validation. |
| `workflow_support_only` | Evidence supports workflow or decision-support framing. | Design logic, not direct validation. |
| `governance_support_only` | Evidence supports reporting, audit, traceability, or lifecycle governance. | Governance design, not clinical or empirical correctness. |
| `boundary_supported` | Scope or limitation boundary derived from evidence-control logic. | Prevents overclaiming. |
| `metadata_only` | Bibliographic metadata only. | Candidate tracking only. |
| `abstract_only` | Abstract but no verified full text. | Background scouting only unless explicitly allowed. |
| `candidate_placeholder_only` | Candidate record without verified evidence. | Do not use as evidence. |
| `unpublished_work_context_only` | Unpublished thesis, pre-submission, or under-review work. | Context only, not published literature. |
| `in_progress_work_context_only` | In-progress system or experiment. | Context only, not validated evidence. |
| `insufficient_evidence` | Claim lacks adequate support. | Revise, remove, or mark as gap. |

## Rules

1. Direct evidence must match the target domain, task, data type, and claim level.
2. Adjacent-domain evidence cannot validate target-domain performance.
3. Method evidence supports rationale, not completed validation.
4. Outcome claims require outcome evidence.
5. A visible feature is not automatically a diagnosis.
6. Auditability, provenance, or structured reporting is not clinical validation.
7. If sample size or metadata conflicts, preserve the caution.

# Reading Notes Template

```markdown
# Reading Notes: {Author} - {Title} ({Year})

**Citation key**: {CitationKey or provisional ID}
**Source**: {single-line citation or metadata record}
**Source URL or provenance**: {URL, database, DOI, PMID, local path, or user-provided source}
**Date read**: {YYYY-MM-DD}
**Evidence status**: {verified_full_text_supported / metadata_only / abstract_only / candidate_placeholder_only / other status}
**Relevance**: {review section, chapter, or gap area}
**Manual check needed**: yes/no

---

## Key Arguments

- {main argument}

## Detailed Notes

### p.{N}-{M} or section marker: {Topic}

{Paraphrased note. Keep quotes short and page-specific if used.}

## Key Terms

| Term | Meaning in context | Review relevance |
| --- | --- | --- |
| {term} | {meaning} | {connection} |

## Review Connections

| Note point | Section | Connection type | Evidence role |
| --- | --- | --- | --- |
| {point} | {section_id} | supports / challenges / extends / boundary | direct / background / method / workflow / governance |

## Claim Candidates

| Candidate claim | Citation key | Evidence status | Boundary language needed | Use or defer |
| --- | --- | --- | --- | --- |
| {claim} | {key} | {status} | {yes/no and wording} | use / defer / gap |

## Limitations And Boundary Cautions

- {limitation}
- {claim not supported by this source}

## Questions And Follow-ups

- {question}

---

*Last updated: {YYYY-MM-DD}*
```

# Review Workflow Templates

## Evidence Matrix

`evidence/evidence_matrix.csv`

```text
citation_key,title,year,authors,source_type,evidence_status,scope_role,domain,task,key_findings,limits,source_path,provenance,manual_check_needed
```

## Claim Register

`evidence/claim_register.csv`

```text
section_id,claim_id,claim_text,evidence_status,citation_keys,source_paths,evidence_strength,overclaim_risk,boundary_language,manual_check_needed
```

## Citation Plan

`evidence/citation_plan.csv`

```text
section_id,citation_key,citation_role,evidence_type,source_path,use_case,priority,caution_note
```

Citation roles:

- direct_domain_anchor
- clinical_or_domain_problem_framing
- background_context
- methodological_support
- workflow_support
- governance_support
- boundary_support
- unpublished_context
- in_progress_context
- candidate_only_do_not_use

## Remaining Gap Notes

`evidence/remaining_gap_notes.csv`

```text
gap_id,section_id,gap_description,evidence_needed,current_evidence_status,why_gap_matters,next_action
```

## Claim Traceability

`evidence/<section>_claim_traceability.csv`

```text
section_id,subsection_id,paragraph_id,main_claim,citation_keys_used,evidence_status,source_summary_paths,overclaim_risk,boundary_language_used,manual_check_needed
```

## Citation Usage Audit

`evidence/<section>_citation_usage_audit.csv`

```text
citation_key,subsections_used,citation_role,evidence_type,used_correctly,overused,underused,caution_note
```

## Overclaim Audit

For each risk:

```text
- risk:
- status: absent / present / needs_revision
- affected subsection:
- recommended safer wording:
```

#!/usr/bin/env python3
"""Lightweight checks for an evidence-controlled review project."""

from __future__ import annotations

import argparse
import csv
from pathlib import Path


COMMON_FILES = [
    "evidence/evidence_matrix.csv",
    "evidence/claim_register.csv",
    "evidence/citation_plan.csv",
    "evidence/overclaim_risk_register.csv",
]

COMMON_DIRS = ["docs", "evidence", "reports", "summaries"]
OPTIONAL_DIRS = ["literature", "literature/reading_notes", "chapters", "outputs", "final_output"]


def read_csv(path: Path) -> tuple[bool, str]:
    try:
        with path.open("r", encoding="utf-8-sig", newline="") as handle:
            reader = csv.DictReader(handle)
            rows = list(reader)
        if reader.fieldnames is None:
            return False, "no header row"
        return True, f"{len(rows)} rows"
    except Exception as exc:
        return False, str(exc)


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("root", nargs="?", default=".", help="review project root")
    parser.add_argument("--strict", action="store_true", help="exit 1 if expected files are missing")
    args = parser.parse_args()

    root = Path(args.root).resolve()
    missing: list[str] = []

    print(f"Review project root: {root}")
    print("\nDirectory check:")
    for rel in COMMON_DIRS:
        path = root / rel
        status = "ok" if path.is_dir() else "missing"
        print(f"- {rel}: {status}")
        if status == "missing":
            missing.append(rel)

    print("\nOptional academic-writing workflow directories:")
    for rel in OPTIONAL_DIRS:
        status = "ok" if (root / rel).is_dir() else "not present"
        print(f"- {rel}: {status}")

    print("\nCommon file check:")
    for rel in COMMON_FILES:
        path = root / rel
        if not path.exists():
            print(f"- {rel}: missing")
            missing.append(rel)
            continue
        ok, detail = read_csv(path)
        status = "ok" if ok else "csv_error"
        print(f"- {rel}: {status} ({detail})")
        if not ok:
            missing.append(rel)

    print("\nSummary:")
    if missing:
        print(f"- warnings: {len(missing)} issue(s)")
        for item in missing:
            print(f"  - {item}")
        return 1 if args.strict else 0

    print("- no common package issues detected")
    return 0


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