# Panel Review Template (Phase 2.6)

Reusable scaffolding for the multi-agent panel: a reviewer output schema, a
generic reviewer prompt skeleton with per-domain focus checklists, and an
editor synthesis prompt skeleton. This is a template, not a runtime program —
it carries no manuscript-specific content. Fill the `{...}` placeholders from
the manuscript under review and from the reviewer-set mapping in Phase 2.6.

The per-domain focus checklists below name *categories of concern*; the precise
probes (and their output templates) live in the vendored domain-probe modules
(`references/domain-probes/*.md`), which each reviewer should load.

---

## Reviewer output schema

Each reviewer returns one object with these fields:

```json
{
  "reviewer_id": "R1",
  "expertise_area": "Biostatistics & Study Design",
  "overall_assessment": "3-5 sentences. State explicitly whether a fatal flaw exists and name the single biggest threat to the conclusions.",
  "strengths": ["...", "..."],
  "major": [
    {
      "number": 1,
      "heading": "Short title of the issue",
      "comment": "Detailed critique. Quote the manuscript where relevant. Explain why it threatens validity.",
      "location": "section / table / figure / specific claim",
      "severity": "Fatal | Fixable",
      "suggested_fix": "What the authors should do to address it"
    }
  ],
  "minor": [
    { "number": 1, "comment": "...", "location": "..." }
  ]
}
```

`severity` uses this skill's own scale: **Fatal** for a conclusion-threatening /
design-level finding, **Fixable** for a reporting-level finding.

---

## Reviewer prompt skeleton

> You are an expert peer reviewer for a competitive journal in {field}, performing a
> blinded pre-submission review of the author's own manuscript. Read the full
> manuscript (and any supplement) first.
>
> TONE: rigorous and skeptical, but fair and constructive. Hunt for the issues that
> threaten the manuscript's conclusions. Keep strengths to 2–3 genuine items. Every
> major comment must threaten an actual conclusion or a reporting requirement; quote
> the manuscript when you criticize a specific claim, and cite the location.
>
> Stay strictly within YOUR assigned area of expertise: {expertise_area}. Do not
> stray into the other reviewers' domains. Load and apply the probes in
> {domain_probe_module} where it applies. Report **only genuine threats** to the
> conclusions — quality, not quantity. A strong manuscript may warrant few or even
> **zero** major comments; do not manufacture majors to hit a count, and do not
> inflate severity. List as many minor or optional refinements as are genuinely
> useful. Return them in the reviewer output schema above. Set `reviewer_id`
> to "{reviewer_id}" and `expertise_area` to "{expertise_area}".
>
> YOUR FOCUS:
> {focus_checklist}

### Per-domain focus checklists (generic)

**Biostatistics & Study Design**
- Model specification: is the primary model pre-specified, or chosen post hoc in a results-favorable direction? Over-adjustment / conditioning on mediators on the causal pathway?
- Assumption checks appropriate to the model (e.g., proportional hazards for Cox), and adequacy of any corrections.
- Missing data: extent, plausibility of the missingness mechanism, whether the headline estimate survives a principled imputation, and whether imputation is primary or relegated to sensitivity.
- Competing risks / informative censoring where multiple event types exist.
- Sparse events: events-per-variable, penalization adequacy, CI stability.
- Multiplicity across multiple outcomes, subgroups, and exploratory analyses.
- Sensitivity / bias analyses (e.g., E-value) computed and interpreted correctly.
- Time-zero / immortal-time / left-truncation; power for any null finding.

**Clinical (domain)**
- Clinical actionability: do the stated recommendations follow from the actual (possibly attenuated) results, or do they overreach?
- Residual confounding by the dominant clinical driver of the outcome; can the exposure be disentangled from it?
- Screening vs symptomatic population framing; external validity to the target readership.
- Plausibility of the pattern of findings (e.g., a selective association without an expected concomitant one) — biology vs confounding vs chance.
- Whether the findings would change management for a real patient.
- Missing clinical variables and their interpretive cost.

**Imaging / Radiology**
- Exposure / measurement validity: how the imaging variable was defined and measured; visual/binary vs quantitative; threshold dependence.
- Interobserver reliability measured in THIS cohort vs cited from the literature; defensibility of any non-differential-misclassification "bias toward the null" claim.
- Protocol heterogeneity over time (scanner generation, slice thickness, reconstruction, dose) and its effect on the measurement.
- Unavailable / non-retrievable images and selection implications.
- Subtype/severity collapsed into a binary; loss of dose-response.
- Reliability of routine clinical reports used as a research-grade variable.

**Methodology (SR/MA)**
- Search comprehensiveness and reproducibility; screening reviewer count.
- Extraction fidelity vs source; comparator existence and consistent definition.
- Non-independence (overlapping cohorts / shared public benchmarks).
- Risk-of-bias instrument and per-study application; supplementary completeness.
- Registration (PROSPERO) format and amendment discipline.

**ML / Statistics (radiomics, AI)**
- Design-grid circularity: is an outcome predicted from the very axes used to construct the dataset?
- Construct validity: reliability ≠ predictiveness; orthogonality of proxy and target.
- Transportability: cross-domain failure framed as success; negative R² read as a weak metric.
- Multiplicity across model × threshold / cohort grids; small-cohort bootstrap intervals.
- Leakage (patient-level vs image-level splits); calibration beyond discrimination.
- Prior-art / dual-publication (salami): does the contribution duplicate a findable prior paper (same dataset size / architecture / metric values, delta-only)? An undisclosed near-duplicate is a contribution killer — check prior art, do not assume novelty.

**Clinical translation / reference standard**
- Reference-standard validity and verification bias.
- Whether reported performance reflects the intended-use population and decision point.
- Incremental value over the comparator already in routine use.

**Methodology / SANRA (narrative review)**
- Novelty / value-add against recent reviews; scope and aims clarity.
- Evidence-gathering transparency (suggestion-level; not PRISMA).
- Taxonomy / synthesis coherence; balance, currency, citation accuracy.
- Load-bearing figures/tables; proportionate gap-filling ("consider adding", never "must cite").

**Technical accuracy (narrative review)**
- Engineering and domain correctness of specific claims; itemize errors with location.
- Verify-your-own-criticism: cross-check each asserted inaccuracy against a current authoritative source before raising it.

**Adversarial reject-hunter (narrative review)**
- RV9 curated-base circularity: is any field-level / bibliometric asymmetry ("the field invested in X, neglected Y") actually a property of the authors' non-systematic selection? Could an opposing reviewer re-curate the citations and reach the reverse thesis? If the gradient is the central contribution, this is a Fatal candidate — demand down-scope-everywhere ("within the surveyed literature", zero field-level residue at every claim site) or a documented search with per-axis counts.
- RV6 single-anchor overload: does a load-bearing clinical claim rest on essentially one (often abstract-only/unreplicated) study while the Abstract calls it "landmark" and the body concedes the base "is thin"? Flag the Abstract↔body register mismatch.
- RV8 self-citation architecture: do the weakest/most-deferred axes coincide with the authors' own forthcoming/companion work without a body-level disclosure, and does each load-bearing axis carry ≥1 independent (other-group) source?

**Handling editor — desk-impression / champion-or-bounce (cross-type, the ceiling lens)**

This persona is the counterweight to the rigor reviewers above. It is **not** a domain expert and
loads **no** domain-probe module; it reads the manuscript exactly as a handling editor skimming
for the desk decision, and its only question is whether the manuscript reads as a **confident
narrative** an editor would champion or a **defensive audit** an editor would bounce. It raises no
Major and no Fatal — every finding is a Minor with a SUBTRACTION action (REMOVE / MOVE / TIGHTEN),
mirroring category L / Phase 2.5g. Append it to any reviewer set on a `--panel` run; it does
**not** count toward the lens-diversity axes (its findings fall to the `other` family and the gate
never penalizes an extra lens). Add the optional `action` field (`"REMOVE" | "MOVE" | "TIGHTEN"`)
to each of its `minor[]` items.

- Does the manuscript open by stating the problem, the design, and the headline result, or does it
  bury the result behind qualifiers? Is the Abstract carrying several caveat clauses before a
  reader reaches the finding? (TIGHTEN)
- Is the strongest robustness / sensitivity result up front in Results, or hidden in Limitations or
  the supplement where it reads as a caveat rather than as evidence? (MOVE → Results)
- Does the narrative (Introduction / Results / Discussion) carry audit minutiae — hashes, commit
  ids, unit-test mentions, post-lock timelines, manifests — that belong in a Methods statement or a
  supplement? (MOVE)
- Is the same caveat repeated at multiple claim sites? Does the Limitations section read as a
  consolidated honest disclosure or as a long rebuttal-letter enumeration? Say each caveat once,
  firmly. (TIGHTEN / REMOVE)
- Overall: is the manuscript longer and more defended than its evidence requires? Name the single
  change that would most raise an editor's confidence on a skim — and it should be a subtraction.

Run `scripts/check_editorial_impression.py` first and use its verdicts as the deterministic spine
for this persona's findings, then add anything the gate cannot see (tone, narrative order, a
result that is technically present but framed apologetically).

---

## Editor synthesis prompt skeleton

> You are the handling editor. {N} expert reviewers (areas: {areas}) have returned
> independent blinded reviews of this pre-submission manuscript. Here are their
> structured reviews as JSON:
>
> {reviews_json}
>
> Read enough of the manuscript to adjudicate conflicts and weigh severity yourself.
> Then:
> 1. Reach an internal readiness decision and state the rationale honestly. (This sets
>    the Phase 3c verdict / score; it is not a journal recommendation to print.) Run BOTH
>    lenses before settling the tier: the measurement/design lens AND a contribution/priority
>    lens (is the value and the novelty actually there?). A measurement-only read is the
>    classic cause of a too-lenient verdict. When an **unfixable-in-current-form** defect is
>    present — invalid poolability/construct validity, irrecoverable leakage/circularity, an
>    undisclosed near-identical prior publication, or (for a review/primer) weak novelty /
>    no distinct contribution since the contribution IS the product — let it dominate the
>    tier over fixable reporting defects rather than letting the fixable framing soften it.
>    Then run a THIRD, opposite-direction lens — **defensiveness / narrative** — symmetric to
>    the contribution lens but guarding the other failure: is the manuscript *over-defended*?
>    Does it read as a confident narrative or as a rebuttal letter (over-hedged, audit-trail in
>    the body, Abstract buried under caveats, the strongest sensitivity result hidden in
>    Limitations, too long)? Treat a defensive over-disclosure as a **cut / move**, not a virtue,
>    while keeping any integrity-critical disclosure (stated once, crisply). The contribution lens
>    guards against a too-lenient verdict; this lens guards against blessing an over-hardened
>    manuscript an editor would bounce on impression.
> 2. De-duplicate and consolidate the major comments by theme. For each consolidated
>    point, flag CONSENSUS (raised by ≥2 reviewers) or single-reviewer, and attribute
>    (R1/R2/R3).
> 3. List the top priority pre-submission actions, ranked and concrete.
> 4. Give an honest readiness verdict: ready for the target tier now, fix specific
>    items first, or consider a different tier.
> 5. Rate each reviewer's contribution as high-signal / mixed / low-signal with one
>    reason (which of their findings survived consolidation; their signal-to-noise; any
>    whole-axis they uniquely covered). This makes the per-lens contribution explicit
>    rather than implicit in the attribution.
>
> Map every finding onto the self-review framing (Fatal / Fixable, category letters
> A–L) and emit it through the Phase 3 report, Phase 3b R0 numbering, and Phase 3c
> JSON, adding the optional `consensus` field where ≥2 reviewers agreed. Route the
> handling-editor desk-impression findings to the separate Editorial-Impression Risks
> block (category L, each with a REMOVE / MOVE / TIGHTEN `action`); do not fold them into
> the Anticipated Major / Minor (ADD / FIX) comments, so the author sees both forces.
> Follow the manuscript-style rules: no "§" symbols, minimal em-dashes, full prose, cite
> specific locations.

---

## Lens-diversity gate (Step 3.5)

Before finalizing, the editor runs `scripts/check_panel_diversity.py` on the collected
reviewer JSON. The gate classifies each major finding into a concern family and checks
that the panel spans the axes its research type is expected to probe — the deterministic
backstop against a panel converging on one easy theme while a high-risk axis goes unprobed.

**Expected high-risk axes per research type** (each should yield ≥1 major; mirrors the
Phase 2.6 reviewer-set table). Optional axes — for example imaging when the exposure is
non-imaging — are not required:

| Research type | Expected axes (families) |
|---|---|
| Survival / prognostic | statistics, clinical |
| Systematic review / meta-analysis | search_screening, clinical, statistics |
| Radiomics | imaging, statistics, clinical |
| Diagnostic-accuracy / AI model | design_leakage, statistics, clinical |
| Observational (STROBE) | confounding, clinical, statistics |
| Narrative / review article | clinical, reporting |

Concern families the classifier recognizes: `search_screening`, `design_leakage`,
`confounding`, `imaging`, `reporting`, `reproducibility`, `statistics`, `clinical`
(everything else falls to `other` and does not count toward coverage). When the research
type is unknown, the axis-coverage check is skipped (the monoculture and lens-collapse
checks still run). The gate never penalizes genuine consensus — only full reviewer
redundancy (`LENS_COLLAPSE`) or panel-level concentration (`FAMILY_MONOCULTURE`).

### What a same-substrate panel cannot check: claims about other papers

`SUBSTRATE_MONOCULTURE` says the panel is not independent. It does not say **where** the
dependence bites, and that turns out to be specific rather than diffuse.

Findings grounded in the manuscript's **own numbers** are checkable by any lens — the table is
right there, and a reviewer sharing the drafter's substrate can still add the column up.
Findings about **what another paper says** are not. There the reviewer inherits the drafter's
reading of a source it never reopens, and every lens inherits the same one.

A four-reviewer panel plus an editor lens, all sharing the drafter's substrate, cleared **two
false characterisations of cited papers**. Its own roster had `SUBSTRATE_MONOCULTURE` recorded as
an open finding, so the *risk* was known; what was not known is that the failures concentrate
exactly there. A different-substrate pass caught one in a single run by opening the sources'
enrolment criteria, and a senior co-author caught the other by reading the anchor paper's stated
conclusion.

**Roster rule.** Route these claim types by construction to a **non-drafter substrate or a
human**:

- Introduction premises about the state of the literature
- Descriptions of comparator or prior studies — design, population, what they concluded
- "No prior study has…" / "this is the first…" statements
- Any sentence whose truth depends on a document the panel did not open

**When the whole panel shares the drafter's substrate, the editor synthesis reports this class as
`UNCHECKED`, not as reviewed.** That is the entire change, and it is deliberately cheap: it adds
no reviewer and finds no new defect. It stops the panel claiming coverage it did not have — which
is what let two false characterisations through with a clean panel report attached to them.

#!/usr/bin/env python3
"""check_analysis_definitions.py — every analysis reported in Results must be
defined in Methods. A model with no outcome variable is not complex; it is
incomplete.

Twenty-four detectors in this skill ask whether a number is *correct*. None asks
whether the analysis that produced it was ever *defined*. This one does.

The failure it catches is not "the statistics are too advanced". It is a Cox model
whose dependent variable is never stated, and a calibration analysis whose
reference standard is, in a reviewer's words, "not defined anywhere". Both were
asked for twice in the rejection that motivated this gate, alongside "this section
is largely incomprehensible in its current form".

Load is the *cause*, not the crime. The same reviewer wrote: "too many analyses
have been performed and reported, resulting in a manuscript with multiple tables
and a lengthy Results section. This appears to have contributed to omissions of
critical information in the Materials and Methods section." A second reviewer, on
the same manuscript, listed the sensitivity analyses as a *strength*. So the count
is reported here as context (`ANALYSIS_LOAD`, informational) and never as a
verdict: a detector that punished the strength and missed the defect would be
worse than none.

Fires on:
  MODEL_NOT_IN_METHODS        a model reported in Results that Methods never
                              describes at all.
  MODEL_OUTCOME_UNDEFINED     a model described in Methods with no outcome /
                              dependent variable (and, for time-to-event, no time
                              variable) named anywhere near it.
  REFERENCE_STANDARD_UNDEFINED
                              discrimination (C-index / AUC) or calibration is
                              reported, but Methods names no reference standard or
                              observed outcome to score against.
  TIER_LABEL_UNDEFINED        a tier/group label (T1–T4, Group A, Class 2) carries
                              results but Methods never states its defining
                              criterion.
  ANALYSIS_LOAD               informational: distinct analyses + tables. Context
                              for the above, never a verdict on its own.

Stdlib-only. Reads the manuscript, never writes it.

Usage:
  python3 check_analysis_definitions.py --manuscript paper.md [--strict] [--quiet] [--json]
Exit: 0 clean; with --strict, 1 on any MAJOR finding; 2 on input/usage error.
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from dataclasses import dataclass, field, asdict

# Journals name this section differently and a gate that cannot find it is a gate
# that silently passes. CHEST requires "Study Design and Methods"; others use
# "Subjects and Methods", "Design and Methods", "Methods and Materials".
METHODS_RE = re.compile(
    r"^#{1,4}\s*\**\s*(?:\d+\.?\s*)?"
    r"(?:(?:study\s+design|design|subjects?|patients?|participants?|materials?|"
    r"methods?)\s+and\s+)?"
    r"(?:methods?|materials?)\b", re.I | re.M)
RESULTS_RE = re.compile(r"^#{1,4}\s*\**\s*(?:\d+\.?\s*)?results?\b", re.I | re.M)
DISCUSSION_RE = re.compile(r"^#{1,4}\s*\**\s*(?:\d+\.?\s*)?discussion\b", re.I | re.M)

# Model families a reader must be told the outcome of.
MODELS = {
    "Cox proportional-hazards": r"\bCox\b(?:[^.]{0,40}?\b(?:model|regression|hazard))?",
    "Fine–Gray subdistribution": r"\bFine[-–—\s]?Gray\b|\bsubdistribution\s+hazard\b",
    "logistic regression": r"\blogistic\s+regression\b",
    "Poisson / negative-binomial": r"\b(?:Poisson|negative[-\s]binomial)\s+(?:model|regression)\b",
    "linear / mixed model": r"\b(?:linear\s+mixed|mixed[-\s]effects)\s+model\b",
}

# Methods must say what the model predicts.
OUTCOME_DECL_RE = re.compile(
    r"\b(?:"
    r"outcome\s+(?:was|were|is|variable|of\s+interest)|"
    r"dependent\s+variable|"
    r"event\s+of\s+interest|"
    r"(?:primary|secondary)\s+(?:endpoint|outcome)\s+(?:was|were|is)|"
    r"time[-\s]to[-\s]\w+|"
    r"time\s+(?:variable|scale|origin)|"
    r"modell?ed\s+(?:the\s+)?(?:time\s+to|risk\s+of|hazard\s+of|odds\s+of)|"
    r"the\s+outcome\s+for\s+(?:the|this)|"
    r"failure\s+time|"
    r"censor\w+\s+at"
    r")\b", re.I)

# Discrimination / calibration need something to be scored against.
PERF_RE = re.compile(
    r"\b(?:C[-\s]?index|c[-\s]?statistic|Harrell'?s?\s+C|Uno'?s?\s+C|"
    r"AUROC|AUC\b|discrimination|calibration|Brier\s+score|"
    r"calibration\s+(?:slope|plot|curve))\b", re.I)
REFSTD_DECL_RE = re.compile(
    r"\b(?:"
    r"reference\s+standard|ground\s+truth|gold\s+standard|"
    r"observed\s+(?:outcome|event|risk|proportion)s?|"
    r"predicted\s+(?:versus|vs\.?|against)\s+observed|"
    r"against\s+the\s+observed|"
    r"compared\s+with\s+(?:the\s+)?observed"
    r")\b", re.I)

TIER_LABEL_RE = re.compile(r"\b([TC][1-9]|Group\s+[A-D]|Class\s+[1-4]|Tier\s+[1-4])\b")
# A tier is defined when its label sits next to a criterion: "T1 (≥15 mm)", "T1 = ...",
# "T1 was defined as", "T1 (6–9 mm)".
TIER_DEF_TMPL = (r"{lab}\s*(?:\(|,|:|=|\bwas\s+defined\b|\bwere\s+defined\b|\bdenote|\brefer)"
                 r"[^.\n]{{0,60}}?(?:[<>≥≤]|\d|\bmm\b|\bcm\b|defined)")

SENS_RE = re.compile(
    r"\b(?:sensitivity\s+analys[ie]s|subgroup\s+analys[ie]s|landmark\s+analys[ie]s|"
    r"competing[-\s]risk\w*|robustness\s+(?:check|analys[ie]s)|"
    r"meta[-\s]regression|leave[-\s]one[-\s]out|E[-\s]value)\b", re.I)
TABLE_RE = re.compile(r"^\s*\**\s*Table\s+\d+\b", re.I | re.M)


@dataclass
class Finding:
    kind: str
    severity: str
    line: int
    detail: str


@dataclass
class Report:
    source: str
    load: dict = field(default_factory=dict)
    findings: list[Finding] = field(default_factory=list)

    @property
    def n_major(self) -> int:
        return sum(1 for f in self.findings if f.severity == "MAJOR")

    @property
    def verdict(self) -> str:
        return "UNDEFINED ANALYSES" if self.n_major else "OK"


def _sections(text: str) -> tuple[str, str]:
    """Return (methods, results). Empty strings when a heading is absent."""
    m = METHODS_RE.search(text)
    r = RESULTS_RE.search(text)
    d = DISCUSSION_RE.search(text)
    methods = text[m.end(): r.start()] if m and r and r.start() > m.start() else (
        text[m.end():] if m else "")
    if r:
        results = text[r.end(): d.start()] if d and d.start() > r.start() else text[r.end():]
    else:
        results = ""
    return methods, results


def _line_of(text: str, idx: int) -> int:
    return text.count("\n", 0, idx) + 1


def audit(text: str, source: str) -> Report:
    rep = Report(source=source)
    methods, results = _sections(text)
    if not methods or not results:
        rep.findings.append(Finding(
            "SECTIONS_NOT_FOUND", "MINOR", 1,
            "could not locate both a Methods and a Results heading; "
            "the definition cross-check needs both"))
        return rep

    m_off = text.index(methods) if methods else 0
    outcome_declared = bool(OUTCOME_DECL_RE.search(methods))

    # --- models -----------------------------------------------------------
    for label, pat in MODELS.items():
        rx = re.compile(pat, re.I)
        in_results = rx.search(results)
        m_hits = list(rx.finditer(methods))
        if in_results and not m_hits:
            rep.findings.append(Finding(
                "MODEL_NOT_IN_METHODS", "MAJOR",
                _line_of(text, text.index(results) + in_results.start()),
                f"a {label} model carries results but Methods never describes it"))
            continue
        if not m_hits:
            continue
        # Search the WHOLE Methods section, not a window around the model. A
        # manuscript that declares its outcome once under "Outcomes" and then
        # specifies models under "Statistical Analysis" is doing it *correctly*;
        # a windowed search punishes the recommended structure.
        if not outcome_declared:
            rep.findings.append(Finding(
                "MODEL_OUTCOME_UNDEFINED", "MAJOR",
                _line_of(text, m_off + m_hits[0].start()),
                f"a {label} model is specified with no outcome / dependent variable "
                f"named near it — state the event and, for time-to-event, the time "
                f"variable and the censoring rule"))

    # --- discrimination / calibration -------------------------------------
    # "Reference standard" is diagnostic-accuracy vocabulary. A prognostic model
    # scores its predictions against the outcome it already declared, so a declared
    # outcome satisfies this too. Fire only when neither exists.
    perf_hit = PERF_RE.search(results) or PERF_RE.search(methods)
    if perf_hit and not REFSTD_DECL_RE.search(methods) and not outcome_declared:
        where = results if PERF_RE.search(results) else methods
        base = text.index(where)
        rep.findings.append(Finding(
            "REFERENCE_STANDARD_UNDEFINED", "MAJOR",
            _line_of(text, base + PERF_RE.search(where).start()),
            "discrimination and/or calibration are reported, but Methods names no "
            "reference standard or observed outcome to score the predictions against"))

    # --- tier labels -------------------------------------------------------
    used = {m.group(1) for m in TIER_LABEL_RE.finditer(results)}
    for lab in sorted(used):
        rx = re.compile(TIER_DEF_TMPL.format(lab=re.escape(lab)), re.I)
        if not rx.search(methods):
            first = TIER_LABEL_RE.search(results)
            rep.findings.append(Finding(
                "TIER_LABEL_UNDEFINED", "MINOR",
                _line_of(text, text.index(results) + (first.start() if first else 0)),
                f"'{lab}' carries results but Methods never states its defining "
                f"criterion — give the range or rule, and prefer the criterion itself "
                f"over an invented label"))

    # --- load (context only, never a verdict) ------------------------------
    n_models = sum(1 for pat in MODELS.values()
                   if re.search(pat, methods + results, re.I))
    n_sens = len({m.group(0).lower() for m in SENS_RE.finditer(methods + results)})
    n_tables = len(TABLE_RE.findall(text))
    rep.load = {"model_families": n_models, "auxiliary_analyses": n_sens, "tables": n_tables}
    rep.findings.append(Finding(
        "ANALYSIS_LOAD", "INFO", 0,
        f"{n_models} model famil{'y' if n_models == 1 else 'ies'}, {n_sens} auxiliary "
        f"analys{'is' if n_sens == 1 else 'es'}, {n_tables} table{'' if n_tables == 1 else 's'}. "
        f"Load is context, not a verdict — but it is what crowds the Methods until "
        f"definitions fall out. If the checks above fired, look here first."))
    return rep


def format_report(rep: Report, color: bool) -> str:
    tag = {"OK": "\033[92m", "UNDEFINED ANALYSES": "\033[91m"}.get(rep.verdict, "") if color else ""
    end = "\033[0m" if color else ""
    out = [f"{tag}== {rep.verdict} =={end}  {rep.source}"]
    if rep.load:
        out.append(f"load: models={rep.load['model_families']} "
                   f"auxiliary={rep.load['auxiliary_analyses']} tables={rep.load['tables']}")
    majors = [f for f in rep.findings if f.severity != "INFO"]
    if not majors:
        out.append("every reported analysis names its outcome and its reference standard.")
    for f in sorted(rep.findings, key=lambda x: (x.severity == "INFO", x.line, x.kind)):
        out.append(f"[{f.severity}] {f.kind} L{f.line}  {f.detail}")
    return "\n".join(out)


def main(argv: list[str] | None = None) -> int:
    ap = argparse.ArgumentParser(description=__doc__,
                                 formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--strict", action="store_true", help="exit 1 on any MAJOR finding")
    ap.add_argument("--quiet", action="store_true", help="suppress the report; exit code only")
    ap.add_argument("--json", action="store_true", help="emit JSON instead of a text report")
    args = ap.parse_args(argv)
    try:
        text = open(args.manuscript, encoding="utf-8").read()
    except OSError as e:
        print(f"error: cannot read manuscript: {e}", file=sys.stderr)
        return 2
    rep = audit(text, args.manuscript)
    if not args.quiet:
        if args.json:
            print(json.dumps({"detector": "check_analysis_definitions",
                              "source": rep.source, "verdict": rep.verdict,
                              "load": rep.load,
                              "findings": [asdict(f) for f in rep.findings]},
                             ensure_ascii=False, indent=2))
        else:
            print(format_report(rep, color=sys.stdout.isatty()))
    return 1 if (args.strict and rep.n_major) else 0


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

#!/usr/bin/env python3
"""Aphorism-density gate — a prose-rhythm AI tell (self-review §J / humanize P26).

LLM-drafted argumentative prose writes in epigrams. Every sentence lands; almost none
merely explains. Two things co-occur and are individually measurable:

  * the **negative definition** — "Authority is not cognition." "Involvement is not
    independence." A short sentence whose whole content is `X is not Y`.
  * a high share of **very short declaratives** used as punchlines ("It did not."
    "It is not one." "It cost more than it paid.").

Human academic prose has both, sparingly, for emphasis. What marks the machine draft is
density: the reader gets a closing line every few sentences and never a sentence that
simply carries information forward. The fix is not to delete the epigrams — two or three
are what a reader remembers — but to restore the explanatory sentences between them.

Verdict:
  APHORISM_DENSITY (Minor)  BOTH the negative-definition rate AND the short-declarative
                            share exceed thresholds calibrated on published prose.

Scope, deliberately conservative on a widely-used skill:
  * Requires BOTH signals. Either alone is ordinary style; together they are the tell.
  * The negative-definition pattern only counts inside a SHORT sentence, so ordinary
    negation in a long explanatory sentence ("the bound is not derived from multiplicity,
    because ...") never counts.
  * Headings, tables, block quotes, code fences and citation markers are stripped first.
  * Reports the offending sentences so the author can absorb them rather than hunt.

Thresholds are calibrated against a corpus of published Perspectives (see --calibrate),
not chosen a priori. Across eight published npj Digital Medicine Perspectives, cleaned to
body prose and measured with this same code, the negative-definition rate ran 0.00-0.45%
of sentences (seven of eight were 0.00%) and the short-declarative share 0.94-10.47%.
The defaults sit above both observed maxima, so prose inside the published range does not
fire. Regenerate with --calibrate if you have your own corpus; the numbers above are from
argumentative Perspectives and a different genre may sit elsewhere.

Exit codes: 0 clean/report-only, 1 with --strict when any Major (none — Minor only),
2 usage. Stdlib-only.

Usage:
    python3 check_aphorism_density.py --manuscript manuscript.md \
        [--out qc/aphorism_density.json] [--neg-def-pct 0.9] [--short-pct 13.0] \
        [--min-sentences 40] [--strict] [--quiet]
    python3 check_aphorism_density.py --calibrate corpus/*.txt
"""
from __future__ import annotations

import argparse
import glob
import json
import re
import statistics
import sys
from pathlib import Path

from _prose import body_text

SENT_SPLIT_RE = re.compile(r"(?<=[.!?])\s+(?=[A-Z\"“])")

# `X is not Y` where the complement is a bare noun phrase, not a clause or a
# prepositional phrase. "Authority is not cognition." counts; "the bound is not
# derived from multiplicity" does not (participle), nor does "is not in the frame" (PP).
NEG_DEF_RE = re.compile(
    r"\b\w[\w'-]*\s+(?:is|are|was|were)\s+not\s+"
    r"(?:a|an|the\s+)?[\w'-]+(?:\s+[\w'-]+){0,2}\s*[.,;]",
    re.I,
)
_PARTICIPLE_OR_PP = re.compile(
    r"\b(?:is|are|was|were)\s+not\s+"
    r"(?:\w+(?:ed|ing)\b|in|on|at|by|for|from|to|with|about|under|over|within|between)\b",
    re.I,
)

SHORT_MAX_WORDS = 9          # "very short declarative"
NEG_DEF_MAX_WORDS = 14       # a negative definition only counts inside a short sentence
MIN_SENTENCES = 40           # below this a rate is noise



def sentences(txt: str) -> list[str]:
    return [s.strip() for s in SENT_SPLIT_RE.split(txt) if len(s.split()) >= 2]


def analyse(md: str) -> dict:
    sents = sentences(body_text(md))
    n = len(sents)
    if not n:
        return {"sentences": 0, "neg_def": [], "short": [], "neg_def_pct": 0.0, "short_pct": 0.0}
    neg, short = [], []
    for s in sents:
        w = len(s.split())
        if w <= SHORT_MAX_WORDS:
            short.append(s)
        if w <= NEG_DEF_MAX_WORDS and NEG_DEF_RE.search(s) and not _PARTICIPLE_OR_PP.search(s):
            neg.append(s)
    return {
        "sentences": n,
        "neg_def": neg,
        "short": short,
        "neg_def_pct": round(100.0 * len(neg) / n, 2),
        "short_pct": round(100.0 * len(short) / n, 2),
        "mean_sentence_words": round(statistics.mean(len(s.split()) for s in sents), 1),
    }


def main() -> int:
    ap = argparse.ArgumentParser()
    ap.add_argument("--manuscript")
    ap.add_argument("--calibrate", nargs="+", help="plain-text corpus files; print rates and exit")
    ap.add_argument("--out")
    ap.add_argument("--neg-def-pct", type=float, default=0.9)
    ap.add_argument("--short-pct", type=float, default=13.0)
    ap.add_argument("--min-sentences", type=int, default=MIN_SENTENCES,
                    help="floor below which a rate is treated as noise (tests lower it)")
    ap.add_argument("--strict", action="store_true")
    ap.add_argument("--quiet", action="store_true")
    a = ap.parse_args()

    if a.calibrate:
        paths = [p for pat in a.calibrate for p in sorted(glob.glob(pat))]
        rows = []
        for p in paths:
            r = analyse(Path(p).read_text(encoding="utf-8", errors="ignore"))
            if r["sentences"] < MIN_SENTENCES:
                continue
            rows.append((Path(p).name, r))
            print(f"{Path(p).name[:40]:<42}{r['sentences']:>5}"
                  f"{r['neg_def_pct']:>8.2f}%{r['short_pct']:>8.2f}%{r['mean_sentence_words']:>8.1f}")
        if rows:
            nd = [r["neg_def_pct"] for _, r in rows]
            sh = [r["short_pct"] for _, r in rows]
            print(f"{'median':<42}{'':>5}{statistics.median(nd):>8.2f}%{statistics.median(sh):>8.2f}%")
            print(f"{'max':<42}{'':>5}{max(nd):>8.2f}%{max(sh):>8.2f}%")
        return 0

    if not a.manuscript:
        sys.stderr.write("error: --manuscript or --calibrate is required\n")
        return 2
    src = Path(a.manuscript)
    if not src.exists():
        sys.stderr.write(f"error: no such file: {src}\n")
        return 2

    r = analyse(src.read_text(encoding="utf-8", errors="ignore"))
    fired = (
        r["sentences"] >= a.min_sentences
        and r["neg_def_pct"] > a.neg_def_pct
        and r["short_pct"] > a.short_pct
    )
    findings = []
    if fired:
        findings.append({
            "check": "APHORISM_DENSITY",
            "severity": "Minor",
            "detail": (
                f"prose reads as a run of epigrams: {len(r['neg_def'])} negative definitions "
                f"({r['neg_def_pct']}% of sentences, threshold {a.neg_def_pct}%) and "
                f"{len(r['short'])} very short declaratives ({r['short_pct']}%, threshold "
                f"{a.short_pct}%); mean sentence {r['mean_sentence_words']} words. "
                "Absorb most of them into the neighbouring sentence and restore the "
                "explanatory prose between; keep two or three for emphasis."
            ),
            "negative_definitions": r["neg_def"][:12],
            "short_declaratives": r["short"][:12],
        })

    if not a.quiet:
        print("=" * 42)
        print(" Aphorism density (§J / P26)")
        print("=" * 42)
        print("| Check | Severity | Detail |")
        print("|---|---|---|")
        if findings:
            for f in findings:
                print(f"| {f['check']} | {f['severity']} | {f['detail']} |")
            print("\nnegative definitions:")
            for s in r["neg_def"][:12]:
                print(f"  • {s}")
            print("\nvery short declaratives:")
            for s in r["short"][:12]:
                print(f"  • {s}")
        else:
            print("| (none) | — | sentence rhythm within the published range |")
            print("\nOK: sentence rhythm within the published range.")

    if a.out:
        out = Path(a.out)
        out.parent.mkdir(parents=True, exist_ok=True)
        out.write_text(json.dumps({"detector": "check_aphorism_density", "manuscript": str(src), "metrics": {
            k: r[k] for k in ("sentences", "neg_def_pct", "short_pct", "mean_sentence_words")
        }, "findings": findings}, indent=2) + "\n")
        if not a.quiet:
            print(f"\nwrote {out}")

    return 0


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

#!/usr/bin/env python3
"""Methods <-> Results <-> disk artifact coverage gate (self-review Phase 2.5f).

Two directional failures survive a single prose pass because the manuscript is
internally consistent:

  FORWARD  PROMISED_ABSENT   an analysis named in the Methods / Statistical
                            Analysis subsection (a sensitivity analysis, multiple
                            imputation, an interaction test, a subgroup, mediation,
                            a competing-risk or landmark model, an E-value) never
                            reaches Results. Methods promised it; the paper never
                            delivered it.
  REVERSE  DISK_UNREPORTED   an analysis output that exists on disk (an
                            added-value DeLong CSV, a calibration table) is never
                            mentioned in the manuscript. The work was done and run
                            but its result — which may contradict the headline —
                            is silently absent.
  FORWARD2 PROMISED_STAT_NO_VALUE  a named statistic framed as a bound/ceiling/
                            de-confounded value (e.g. "the de-confounded reader AUC
                            is reported in Table S16", "the classifier ceiling AUC")
                            is promised with a reporting verb but never given a
                            numeric value anywhere in the manuscript or supplement.
                            This is the "described but never quantified" reviewer
                            catch — the bound that makes the primary estimand
                            interpretable, marked Addressed in a checklist yet
                            absent from every table. Conservative: fires only on a
                            bound/ceiling/de-confounded framing whose statistic has
                            zero associated numeric values in the whole corpus.

The reverse direction is the false-positive-prone one, so it is calibrated: when
an `_analysis_outputs.md` manifest exists (written by /analyze-stats) it is the
source of truth; otherwise the analysis directory is globbed and a finding is only
a Major when the file stem carries an analysis-bearing token (delong, nested,
added-value, interaction, sensitivity, subgroup, mediation, imputation, landmark,
calibration, dca, nri, idi). A cryptic stem with no such token is a Minor flag.

INPUTS
  --manuscript    manuscript markdown/text (required).
  --analysis-dir  directory of analysis outputs. If omitted, the first existing of
                  output/analysis/, analysis/, results/ is used. An
                  `_analysis_outputs.md` manifest in that dir (or alongside the
                  manuscript) takes precedence as the output source of truth.

OUTPUT
  A reconciliation table (stdout) and, with --out, a JSON artifact:
    {manuscript, analysis_dir, manifest, claims[{verdict, severity, detail, where}], summary}
  PROMISED_ABSENT is always Major; DISK_UNREPORTED is Major or Minor per the rule
  above. Exit 1 (with --strict) when any Major-severity claim exists.

Stdlib-only (json / re / argparse / pathlib). Exit codes: 0 clean (or report-only),
1 Major claim(s) found (with --strict), 2 input/usage error.
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

# Promised analyses: key -> (detect-in-Methods regex, appears-in-Results regex).
# The Results regex is intentionally looser (the concept can be phrased differently
# downstream) but still anchored to the analysis name.
PROMISED = {
    "multiple imputation": (r"multiple imputation|\bm\s*=\s*\d+\s*imput|imputed using",
                            r"imput-|imputation|imputed"),
    "sensitivity analysis": (r"sensitivity analys[ie]s", r"sensitivity analys[ie]s"),
    "leave-one-out": (r"leave[-\s]one[-\s]out", r"leave[-\s]one[-\s]out"),
    "interaction": (r"interaction (?:term|test|analys|effect)|tested? for interaction|"
                    r"p[-\s]?(?:for[-\s])?interaction",
                    r"interaction|p[-\s]?(?:for[-\s])?interaction|effect modif"),
    "subgroup": (r"subgroup analys", r"subgroup"),
    "mediation": (r"mediation (?:analys|model)", r"mediation|mediat"),
    "competing risk": (r"competing[-\s]risk|fine[-\s]?gray|subdistribution",
                       r"competing[-\s]risk|fine[-\s]?gray|subdistribution|cumulative incidence"),
    "landmark": (r"landmark analys", r"landmark"),
    "E-value": (r"e[-\s]?value", r"e[-\s]?value"),
}

ANALYSIS_TOKENS = (
    "delong", "nested", "added", "addedvalue", "incremental", "interaction",
    "sensitivity", "subgroup", "mediation", "imputation", "imputed", "landmark",
    "calibration", "dca", "netbenefit", "nri", "idi", "competing", "finegray",
    "tipping", "leaveone", "bootstrap",
)
OUTPUT_EXT = (".csv", ".tsv", ".r", ".py", ".rds")
MANIFEST_NAME = "_analysis_outputs.md"


def _norm(s: str) -> str:
    return re.sub(r"[^a-z0-9]+", "", s.lower())


def split_sections(text: str) -> list[tuple[str, str]]:
    """Return (heading, body) for each markdown heading region."""
    sections, heading, buf = [], "(preamble)", []
    for line in text.splitlines():
        m = re.match(r"^#{1,4}\s+(.*)", line)
        if m:
            sections.append((heading, "\n".join(buf)))
            heading = re.sub(r"[*_`]", "", m.group(1)).strip()
            buf = []
        else:
            buf.append(line)
    sections.append((heading, "\n".join(buf)))
    return sections


def section_text(sections: list[tuple[str, str]], names: tuple[str, ...]) -> str:
    out = []
    for heading, body in sections:
        h = heading.lower()
        if any(n in h for n in names):
            out.append(body)
    return "\n".join(out)


# --- FORWARD: promised-but-absent ------------------------------------------

def check_forward(text: str) -> list[dict]:
    sections = split_sections(text)
    methods = section_text(sections, ("method", "statistical analys", "analysis plan"))
    results = section_text(sections, ("result", "finding"))
    if not methods.strip():
        return []  # no Methods section to read promises from
    # If there is no separate Results section, compare against the whole document
    # minus the Methods text (conservative: avoids matching a promise to itself).
    haystack = results if results.strip() else text
    claims = []
    for key, (mre, rre) in PROMISED.items():
        if re.search(mre, methods, re.I):
            if not re.search(rre, haystack, re.I):
                claims.append({
                    "verdict": "PROMISED_ABSENT",
                    "severity": "Major",
                    "detail": (f"Methods promises a '{key}' analysis, but it does not "
                               f"appear in Results"),
                    "where": "Methods → Results",
                })
    return claims


# --- FORWARD2: promised statistic that is never given a number --------------

# Statistic nouns whose *value* is the deliverable. "sensitivity" excludes the
# "sensitivity analysis" sense.
STAT_NOUN = re.compile(
    r"\bAUROC\b|\bAUC\b|\bc[-\s]?statistic\b|\bc[-\s]?index\b"
    r"|\bsensitivity\b(?!\s+analys)|\bspecificity\b|\bnet benefit\b|\bcalibration slope\b",
    re.IGNORECASE)
# A bound/ceiling/de-confounded framing — the cases where a promised-but-unquantified
# statistic is the load-bearing bound, not an ordinary reported metric.
PROMISE_FRAME = re.compile(
    r"\bceiling\b|\bde[-\s]?confounded\b|\bupper[-\s]bound\b|\blower[-\s]bound\b|\bbound(?:s|ed|ing)?\b"
    r"|\bchance[-\s]level\b|\bdiscriminat\w*\s+ceiling\b",
    re.IGNORECASE)
REPORT_VERB = re.compile(
    r"\b(?:is|are|was|were)\s+(?:reported|read|given|shown|presented|computed|provided|derived)\b"
    r"|reported in (?:Table|Supplement|Supplementary)|\bwe report\b|\bsee (?:Table|Supplement)",
    re.IGNORECASE)
# A numeric value a statistic can take: a 0.xx discrimination value or an N% rate.
STAT_VALUE = re.compile(r"\b0\.\d{2,3}\b|\b\d{1,3}(?:\.\d+)?\s?%")


def _sentences(text: str) -> list[str]:
    flat = re.sub(r"\s*\n\s*", " ", text)
    return [s for s in re.split(r"(?<=[.;])\s+", flat) if s.strip()]


def check_promised_stat(methods_supp: str, corpus: str) -> list[dict]:
    """Fire when a bound/ceiling/de-confounded statistic is promised with a
    reporting verb but no numeric value for that statistic exists in the corpus."""
    claims = []
    # statistic tokens that DO have an associated value somewhere in the corpus
    valued: set[str] = set()
    for sent in _sentences(corpus):
        if STAT_VALUE.search(sent):
            for sm in STAT_NOUN.finditer(sent):
                valued.add(sm.group(0).lower().replace(" ", "").replace("-", ""))
    seen: set[str] = set()
    for sent in _sentences(methods_supp):
        if STAT_VALUE.search(sent):
            continue  # the value is right here — not a promise
        if not (STAT_NOUN.search(sent) and PROMISE_FRAME.search(sent) and REPORT_VERB.search(sent)):
            continue
        for sm in STAT_NOUN.finditer(sent):
            tok = sm.group(0)
            key = tok.lower().replace(" ", "").replace("-", "")
            if key in valued or key in seen:
                continue
            seen.add(key)
            claims.append({
                "verdict": "PROMISED_STAT_NO_VALUE",
                "severity": "Major",
                "detail": (f"a bound/ceiling/de-confounded '{tok}' is promised with a "
                           f"reporting verb but no numeric value for it appears in the "
                           f"manuscript or supplement"),
                "where": sent.strip()[:160],
            })
    return claims


# --- REVERSE: disk-present-but-unreported -----------------------------------

def find_analysis_dir(manuscript: Path, override: str | None) -> Path | None:
    if override:
        p = Path(override)
        return p if p.is_dir() else None
    base = manuscript.resolve().parent
    for cand in ("output/analysis", "analysis", "results", "output"):
        for root in (base, base.parent):
            p = root / cand
            if p.is_dir():
                return p
    return None


def parse_manifest(path: Path) -> list[str]:
    """Return declared output basenames from an _analysis_outputs.md manifest.
    Lines like '- `table1.csv` -- desc' or '* roc_curve.pdf'."""
    items = []
    for line in path.read_text(encoding="utf-8").splitlines():
        for m in re.finditer(r"`([^`]+\.[A-Za-z0-9]{1,5})`", line):
            items.append(m.group(1))
        if not re.search(r"`", line):
            m = re.search(r"[-*]\s+([\w./-]+\.[A-Za-z0-9]{1,5})", line)
            if m:
                items.append(m.group(1))
    return items


def stem_tokens(name: str) -> list[str]:
    stem = Path(name).stem
    toks = re.split(r"[_\-.\s]+", stem)
    return [t for t in toks if len(t) >= 4 and re.search(r"[a-z]", t.lower())]


def mentioned(name: str, body_norm: str) -> bool:
    toks = stem_tokens(name)
    if not toks:
        return True  # nothing distinctive to look for -> do not flag
    return any(_norm(t) in body_norm for t in toks)


def check_reverse(text: str, manuscript: Path, analysis_dir: str | None) -> tuple[list[dict], dict]:
    body_norm = _norm(text)
    meta = {"analysis_dir": None, "manifest": None}
    # 1) manifest precedence
    manifest_files: list[str] = []
    for cand in (manuscript.resolve().parent / MANIFEST_NAME,):
        if cand.is_file():
            manifest_files = parse_manifest(cand)
            meta["manifest"] = str(cand)
            break
    adir = find_analysis_dir(manuscript, analysis_dir)
    if adir is not None:
        meta["analysis_dir"] = str(adir)
        mpath = adir / MANIFEST_NAME
        if not manifest_files and mpath.is_file():
            manifest_files = parse_manifest(mpath)
            meta["manifest"] = str(mpath)

    claims = []
    if manifest_files:
        for name in sorted(set(manifest_files)):
            if Path(name).suffix.lower() not in OUTPUT_EXT:
                continue  # figures (.pdf/.png) are checked by /make-figures legends
            if not mentioned(name, body_norm):
                claims.append({
                    "verdict": "DISK_UNREPORTED",
                    "severity": "Major",
                    "detail": (f"manifest output '{name}' is not mentioned anywhere in "
                               f"the manuscript"),
                    "where": meta["manifest"],
                })
        return claims, meta

    # 2) glob fallback (calibrated severity)
    if adir is None:
        return claims, meta
    for f in sorted(adir.rglob("*")):
        if not f.is_file() or f.suffix.lower() not in OUTPUT_EXT:
            continue
        if mentioned(f.name, body_norm):
            continue
        analysis_bearing = any(_norm(t) in ANALYSIS_TOKENS for t in stem_tokens(f.name))
        claims.append({
            "verdict": "DISK_UNREPORTED",
            "severity": "Major" if analysis_bearing else "Minor",
            "detail": (f"analysis output '{f.name}' exists on disk but is not mentioned "
                       f"in the manuscript" + (" (analysis-bearing name)" if analysis_bearing else "")),
            "where": str(f.relative_to(adir.parent) if adir.parent in f.parents else f),
        })
    return claims, meta


# --- driver ----------------------------------------------------------------

def analyze(manuscript: str, analysis_dir: str | None, supplements: list[str] | None = None) -> dict:
    p = Path(manuscript)
    if not p.is_file():
        sys.stderr.write(f"ERROR: manuscript not found: {manuscript}\n")
        sys.exit(2)
    text = p.read_text(encoding="utf-8")

    supp_texts = []
    for s in supplements or []:
        sp = Path(s)
        if not sp.is_file():
            sys.stderr.write(f"ERROR: supplement not found: {s}\n")
            sys.exit(2)
        supp_texts.append(sp.read_text(encoding="utf-8", errors="replace"))

    claims = check_forward(text)
    rev, meta = check_reverse(text, p, analysis_dir)
    claims += rev

    # FORWARD2: promised-but-unquantified bound/ceiling statistic. The promise may
    # live in the Methods or in the supplement; the value may live anywhere.
    sections = split_sections(text)
    methods = section_text(sections, ("method", "statistical analys", "analysis plan"))
    methods_supp = "\n".join([methods] + supp_texts)
    corpus = "\n".join([text] + supp_texts)
    claims += check_promised_stat(methods_supp, corpus)

    n_major = sum(1 for c in claims if c["severity"] == "Major")
    return {
        "manuscript": str(p),
        "analysis_dir": meta["analysis_dir"],
        "manifest": meta["manifest"],
        "claims": claims,
        "summary": {
            "n_claims": len(claims),
            "n_major": n_major,
            "n_flag": len(claims) - n_major,
            "verdict": "MAJOR_CANDIDATE" if n_major else "OK",
        },
    }


def render(result: dict) -> str:
    lines = ["| Direction | Severity | Detail |", "|---|---|---|"]
    for c in result["claims"]:
        lines.append(f"| {c['verdict']} | {c['severity']} | {c['detail']} |")
    if len(lines) == 2:
        lines.append("| (none) | — | Methods↔Results↔disk all reconciled |")
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(description="Methods<->Results<->disk coverage gate (Phase 2.5f).")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--analysis-dir", help="analysis-output dir (default: output/analysis, analysis, results)")
    ap.add_argument("--supplement", action="append", default=[], metavar="PATH",
                    help="supplement file(s) to include in the promised-statistic corpus (repeatable)")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true", help="exit 1 if any Major claim exists")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    args = ap.parse_args()

    result = analyze(args.manuscript, args.analysis_dir, args.supplement)

    if not args.quiet:
        print("=" * 41)
        print(" Artifact Coverage (Phase 2.5f)")
        print("=" * 41)
        if result["manifest"]:
            print(f"manifest: {result['manifest']}")
        elif result["analysis_dir"]:
            print(f"analysis dir (globbed): {result['analysis_dir']}")
        print(render(result))
        print()
        s = result["summary"]
        if s["n_major"]:
            print(f"MAJOR candidate: {s['n_major']} coverage gap(s).")
        else:
            print("OK: Methods/Results/disk reconciled.")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_artifact_coverage", **result}, indent=2), encoding="utf-8")
        if not args.quiet:
            print(f"\nwrote {args.out}")

    return 1 if (args.strict and result["summary"]["n_major"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Baseline-drift gate (self-review) -- anchor the refine loop to the human-approved version.

Self-review is run in a loop (review -> revise -> review). The danger is not any single
pass but the *anchor*: each pass takes the previous **AI output** as its baseline, so a
small framing bias introduced in one pass becomes the starting point for the next and
compounds -- claims strengthen, scope inflates, caveats accrete -- while every individual
pass looks locally reasonable. Nothing measures how far the manuscript has drifted from
the last version a human actually approved.

This gate compares the current manuscript against a **baseline** -- the last
human-approved / circulated version (the frozen v_N of manuscript-versioning), NOT the
last AI output -- and reports lexical framing drift. It is advisory: framing is a
judgment call the author owns, so every finding is Minor and the gate never blocks
(--strict is accepted for CLI parity but exits 0). Comparing to the AI's own previous
draft would defeat the purpose; the baseline must be a human anchor.

  STRENGTH_INFLATION            certainty/assertion markers rose while hedges fell vs the
                               baseline -- the same result stated more strongly than a
                               human signed off on.
  SIGNIFICANCE_INFLATION_DRIFT significance-inflation tokens (novel / pivotal /
                               unprecedented / paradigm-shifting ...) rose vs the baseline.
  SCOPE_INFLATION_DRIFT        generalization phrases the baseline did not contain ("in
                               clinical practice", "broadly applicable", "can be used to")
                               appeared -- the estimand's reach widened without new data.
  HEDGE_ACCRETION              hedge / caveat density rose vs the baseline -- the additive,
                               over-hardening side of drift (the cumulative form of what
                               the ceiling pass catches within one pass).

Conservative by construction: a probe fires only when a density delta exceeds an explicit
threshold, so ordinary revision does not trip it. With no --baseline (the crossfire path
passes only --manuscript) there is nothing to anchor against and the gate emits zero
findings.

INPUTS
  --manuscript  current manuscript markdown/text (required).
  --baseline    the last human-approved version (optional; without it the gate is a no-op).
  thresholds    --strength-delta (2.0), --sig-delta (2), --scope-delta (1),
                --hedge-delta (8.0). Densities are per 1,000 words; --sig/--scope are
                absolute counts (those tokens are rare). A probe fires when the delta
                exceeds its threshold.

OUTPUT
  A drift table (stdout) and, with --out, a JSON artifact:
    {detector, manuscript, baseline, claims[{verdict, severity, detail, where}], summary}
  Every claim is severity "Minor". Exit code is always 0 for the findings themselves
  (advisory); --strict is accepted for CLI parity but never blocks. Exit 2 on a missing
  manuscript.

Stdlib-only (json / re / argparse / pathlib). Exit codes: 0 clean or advisory findings,
2 input/usage error.
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

DETECTOR = "check_baseline_drift"

# --------------------------------------------------------------------------- #
# Lexicons -- fixed, word-boundary matched. Kept small and unambiguous to hold the
# false-positive rate down on a widely-used skill.
# --------------------------------------------------------------------------- #
ASSERTION = [
    "demonstrates", "demonstrate", "proves", "prove", "proven", "establishes",
    "establish", "confirms", "confirm", "definitively", "conclusively",
    "unequivocally", "undoubtedly", "clearly shows", "guarantees", "ensures",
    "highly accurate", "highly effective",
]
HEDGE = [
    "may", "might", "could", "suggests", "suggest", "appears", "appear", "seems",
    "seem", "potentially", "possibly", "perhaps", "tends to", "is likely",
    "are likely", "we speculate", "cannot exclude",
]
SIGNIFICANCE = [
    "novel", "pivotal", "unprecedented", "paradigm", "paradigm-shifting",
    "groundbreaking", "revolutionary", "cutting-edge", "state-of-the-art",
    "remarkable", "landmark", "first-ever", "first to demonstrate",
]
SCOPE = [
    "in clinical practice", "in routine practice", "in the general population",
    "broadly applicable", "widely applicable", "can be used to", "should be used",
    "generalizable to", "translate directly", "ready for deployment",
    "ready for clinical use", "in real-world",
]


def _count(text: str, terms: list[str]) -> int:
    n = 0
    for t in terms:
        pat = r"(?<![A-Za-z0-9-])" + re.escape(t) + r"(?![A-Za-z0-9-])"
        n += len(re.findall(pat, text))
    return n


def _present(text: str, terms: list[str]) -> set[str]:
    found = set()
    for t in terms:
        pat = r"(?<![A-Za-z0-9-])" + re.escape(t) + r"(?![A-Za-z0-9-])"
        if re.search(pat, text):
            found.add(t)
    return found


def _words(text: str) -> int:
    return max(1, len(re.findall(r"[A-Za-z0-9']+", text)))


def _profile(text: str) -> dict:
    low = text.lower()
    w = _words(text)
    return {
        "words": w,
        "assertion": _count(low, ASSERTION),
        "hedge": _count(low, HEDGE),
        "sig": _count(low, SIGNIFICANCE),
        "scope_terms": _present(low, SCOPE),
        "sig_terms": _present(low, SIGNIFICANCE),
    }


def _per1k(n: int, words: int) -> float:
    return round(n * 1000.0 / words, 2)


def analyze(current: str, baseline: str | None, thr: dict) -> dict:
    claims: list[dict] = []
    if baseline is None:
        return {"claims": claims, "summary": {"n_claims": 0, "verdict": "OK"}}

    cur = _profile(current)
    base = _profile(baseline)

    # STRENGTH_INFLATION: assertions up AND hedges down (per 1k)
    d_assert = _per1k(cur["assertion"], cur["words"]) - _per1k(base["assertion"], base["words"])
    d_hedge = _per1k(cur["hedge"], cur["words"]) - _per1k(base["hedge"], base["words"])
    if d_assert >= thr["strength"] and d_hedge < 0:
        claims.append({
            "verdict": "STRENGTH_INFLATION",
            "severity": "Minor",
            "detail": (
                f"certainty markers {_per1k(base['assertion'], base['words'])}->"
                f"{_per1k(cur['assertion'], cur['words'])}/1k while hedges "
                f"{_per1k(base['hedge'], base['words'])}->{_per1k(cur['hedge'], cur['words'])}/1k "
                "vs baseline -- the result is stated more strongly than the approved version"
            ),
            "where": "whole document",
        })

    # SIGNIFICANCE_INFLATION_DRIFT: absolute significance-token count up
    d_sig = cur["sig"] - base["sig"]
    if d_sig >= thr["sig"]:
        added = sorted(cur["sig_terms"] - base["sig_terms"])
        detail = f"significance-inflation tokens {base['sig']}->{cur['sig']} vs baseline"
        if added:
            detail += " (added: " + ", ".join(added) + ")"
        claims.append({"verdict": "SIGNIFICANCE_INFLATION_DRIFT", "severity": "Minor", "detail": detail, "where": "whole document"})

    # SCOPE_INFLATION_DRIFT: new generalization phrases absent from baseline
    added_scope = sorted(cur["scope_terms"] - base["scope_terms"])
    if len(added_scope) >= thr["scope"]:
        claims.append({
            "verdict": "SCOPE_INFLATION_DRIFT",
            "severity": "Minor",
            "detail": "generalization phrase(s) not in baseline: " + ", ".join(f'"{p}"' for p in added_scope),
            "where": "whole document",
        })

    # HEDGE_ACCRETION: hedge density up (the additive/over-hardening drift)
    if d_hedge >= thr["hedge"]:
        claims.append({
            "verdict": "HEDGE_ACCRETION",
            "severity": "Minor",
            "detail": (
                f"hedge/caveat density {_per1k(base['hedge'], base['words'])}->"
                f"{_per1k(cur['hedge'], cur['words'])}/1k vs baseline -- cumulative over-hardening"
            ),
            "where": "whole document",
        })

    verdict = "DRIFT_FLAGS" if claims else "OK"
    return {"claims": claims, "summary": {"n_claims": len(claims), "verdict": verdict}}


def render(result: dict, manuscript: str, baseline: str | None) -> str:
    lines = ["Baseline-drift scan"]
    lines.append(f"  manuscript: {manuscript}")
    lines.append(f"  baseline:   {baseline if baseline else '(none -- no-op)'}")
    claims = result["claims"]
    if not claims:
        lines.append("  OK: no framing drift beyond threshold." if baseline else "  OK: no baseline supplied; nothing to anchor against.")
        return "\n".join(lines)
    lines.append(f"  DRIFT FOUND: {len(claims)} finding(s) (advisory / Minor)")
    for c in claims:
        lines.append(f"    [{c['verdict']}] {c['detail']}")
    return "\n".join(lines)


def main(argv=None) -> int:
    ap = argparse.ArgumentParser(description="Report lexical framing drift of a manuscript vs its last human-approved baseline.")
    ap.add_argument("--manuscript", required=True, help="current manuscript markdown/text")
    ap.add_argument("--baseline", help="last human-approved version (optional; no-op without it)")
    ap.add_argument("--out", help="optional JSON artifact path")
    ap.add_argument("--quiet", action="store_true", help="suppress the stdout summary")
    ap.add_argument("--strict", action="store_true", help="accepted for CLI parity; never blocks (advisory)")
    ap.add_argument("--strength-delta", type=float, default=2.0, help="min assertion-density rise per 1k (default 2.0)")
    ap.add_argument("--sig-delta", type=int, default=2, help="min significance-token count rise (default 2)")
    ap.add_argument("--scope-delta", type=int, default=1, help="min new scope phrases (default 1)")
    ap.add_argument("--hedge-delta", type=float, default=8.0, help="min hedge-density rise per 1k (default 8.0)")
    args = ap.parse_args(argv)

    mpath = Path(args.manuscript)
    if not mpath.is_file():
        print(f"error: manuscript not found: {args.manuscript}", file=sys.stderr)
        return 2
    current = mpath.read_text(encoding="utf-8", errors="replace")

    baseline_text = None
    if args.baseline:
        bpath = Path(args.baseline)
        if not bpath.is_file():
            print(f"error: baseline not found: {args.baseline}", file=sys.stderr)
            return 2
        baseline_text = bpath.read_text(encoding="utf-8", errors="replace")

    thr = {
        "strength": args.strength_delta,
        "sig": args.sig_delta,
        "scope": args.scope_delta,
        "hedge": args.hedge_delta,
    }
    result = analyze(current, baseline_text, thr)
    out = {
        "detector": DETECTOR,
        "manuscript": str(args.manuscript),
        "baseline": str(args.baseline) if args.baseline else None,
        **result,
    }
    if args.out:
        Path(args.out).write_text(json.dumps(out, indent=2) + "\n", encoding="utf-8")
    if not args.quiet:
        print(render(result, str(args.manuscript), str(args.baseline) if args.baseline else None))
    return 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Cross-script categorical / cut-point and composite-definition consistency gate (self-review Phase 2.5b).

A derived categorical variable (age band, BMI category, eGFR/CKD stage, FIB-4
strata, risk tier) is often re-derived in more than one analysis script — the
primary table in one file, a sensitivity or secondary analysis in another. When
those re-derivations disagree on the cut-points or the interval closure, the SAME
cohort is split differently in each file: per-stratum Ns drift between tables even
though the grand total still matches, and a stratum can spuriously appear to cross
a threshold. A grand-total / row-sum check does not catch it because every total
still reconciles; a reviewer who compares the primary table's stratum Ns against
the sensitivity table's stratum Ns does.

This detector parses analysis SOURCE (R / Python), not the manuscript. It extracts
every binning assignment of the form

    R:       <var> <- cut(<src>, breaks = c(...), right = TRUE/FALSE, labels = ...)
    R:       <var> <- case_when( <numeric boundary literals> )
    Python:  <var> = pd.cut(<src>, bins=[...], right=True/False, labels=...)

groups them by the assigned variable name, and fires BINNING_DRIFT when one
variable is defined with two or more distinct (breaks, right-closure) signatures
across the scanned files. It is deterministic and conservative: it fires only when
it can extract a complete `breaks`/`bins` operand and the signatures genuinely
differ. The interval-closure flag is compared using each language's documented
default (R `cut` right=TRUE, pandas `pd.cut` right=True), so an explicit
`right=FALSE` in one file and an omitted default in another is a real difference.

It ALSO extracts composite boolean-indicator definitions — the sibling failure
mode where a derived 0/1 component (e.g. a metabolic-syndrome criterion) is built
from a disjunction of comparison clauses and a second script omits or adds a
clause:

    R:       <var> <- as.integer(a >= x | b == 1 | c == 1)
    R:       <var> <- as.numeric(<bool expr>)   / ifelse(<bool expr>, 1, 0)
    Python:  <var> = np.where(<bool expr>, 1, 0)

The boolean expression is split into comparison ATOMS on the top-level `|` (OR);
clause order, whitespace, and outer parentheses do not matter (atoms are compared
as a SET), so only a genuinely missing or added clause counts. It fires
DERIVED_DEF_DRIFT when one variable is defined with two or more distinct atom sets.
Motivation: `mets_bp <- as.integer(bl_he_sbp>=130 | bl_he_dbp>=85 |
bl_tx_hypertension_med==1 | bl_hypertension==1)` in the canonical script vs the
same name without the final `| bl_hypertension==1` in a re-analysis script. The two
definitions classify different participants, so the metabolic-syndrome C-index computed
from each disagreed in the fourth decimal — enough to put two different values for one
quantity into a main table and its supplement, and small enough that nobody reading
either artifact alone would notice.

Motivation: a screening cohort binned age with
`cut(bl_age, breaks=c(-Inf,45,50,60,Inf), right=FALSE)` in the primary script and
`cut(bl_age, breaks=c(-Inf,44,49,59,Inf), right=TRUE)` in the threshold sensitivity
script. Fractional ages (e.g. 44.5 y) fell into different bands, shifting ~353
participants and producing a spurious "reached" stratum in the sensitivity table
that vanished once the binning was harmonized. See
~/.claude/rules/cross-script-categorical-consistency.md.

INPUTS
  --root PATH        directory to scan recursively for *.R/*.r/*.py (repeatable;
                     default: ./analysis and ./scripts if present, else .)
  --glob PATTERN     extra filename glob to include (repeatable)
  --out PATH         write JSON artifact
  --strict           exit 1 if any Major (BINNING_DRIFT) finding
  --quiet            suppress stdout table

OUTPUT  reconciliation table (stdout) + optional JSON:
  {scanned[], definitions[], claims[{verdict, severity, detail, where}], summary}

Stdlib-only (re / json / argparse / pathlib). Exit codes: 0 clean/report-only,
1 Major with --strict, 2 input/usage error.
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

# Variable-name hints that mark a derived categorical (the assigned LHS or the
# binned source). Used only to keep the reconciliation table focused; a drift on
# any repeatedly-binned variable still fires.
CATEGORICAL_HINTS = (
    "band", "cat", "category", "group", "grp", "strat", "stage", "tier",
    "quartile", "tertile", "quintile", "decile", "level", "class",
    "age", "bmi", "egfr", "gfr", "fib4", "fib_4", "cmb", "mets", "ckd",
)

# Name hints for composite 0/1 indicator components (the DERIVED_DEF_DRIFT path).
INDICATOR_HINTS = (
    "mets", "indicator", "flag", "criteria", "criterion", "_pos", "_neg",
    "_yes", "_bin", "_ind", "comp", "positive", "present",
)

SCRIPT_SUFFIXES = (".r", ".py")


def _is_categorical_name(name: str) -> bool:
    n = name.lower()
    return any(h in n for h in CATEGORICAL_HINTS)


def _is_indicator_name(name: str) -> bool:
    n = name.lower()
    return any(h in n for h in INDICATOR_HINTS)


def _norm_breaks(raw: str) -> str:
    """Normalize a breaks/bins operand to a comparable token string.

    Keeps the numeric/-Inf/Inf sequence in order; drops whitespace and the
    c(...) / [...] wrapper. '-Inf,45,50,60,Inf' style."""
    body = raw.strip()
    body = re.sub(r"^(c|seq)\s*\(", "", body, flags=re.I)
    body = body.strip().lstrip("[(").rstrip("])")
    toks = []
    for t in body.split(","):
        t = t.strip()
        if not t:
            continue
        t = t.replace("Inf", "Inf").replace("inf", "Inf")
        t = re.sub(r"^np\.|^math\.|^float\(['\"]?|['\"]?\)$", "", t)
        t = t.replace("-Inf", "-Inf")
        toks.append(t)
    return ",".join(toks)


def _right_default(lang: str) -> str:
    # R cut() default right=TRUE; pandas pd.cut default right=True.
    return "TRUE"


def _norm_right(raw, lang: str) -> str:
    if raw is None:
        return _right_default(lang)
    v = raw.strip().upper()
    if v in ("T", "TRUE"):
        return "TRUE"
    if v in ("F", "FALSE"):
        return "FALSE"
    return v


def _find_matching_paren(text: str, open_idx: int) -> int:
    """Index of the ')' matching the '(' at open_idx, or -1."""
    depth = 0
    for i in range(open_idx, len(text)):
        c = text[i]
        if c == "(":
            depth += 1
        elif c == ")":
            depth -= 1
            if depth == 0:
                return i
    return -1


# `lhs <- cut(...)`, `lhs = cut(...)`, `lhs = pd.cut(...)`. Captures lhs + call start.
_ASSIGN_CUT_RE = re.compile(
    r"(?P<lhs>[A-Za-z_][\w.$\[\]\"']*?)\s*(?:<<-|<-|=)\s*"
    r"(?P<fn>(?:pd\.)?cut)\s*\(",
)
_BREAKS_RE = re.compile(r"\b(?:breaks|bins)\s*=\s*", re.I)
_RIGHT_RE = re.compile(r"\bright\s*=\s*(TRUE|FALSE|True|False|T|F)\b")
_LABELS_RE = re.compile(r"\blabels\s*=\s*(c\([^)]*\)|\[[^\]]*\])", re.I)


def _operand_after(text: str, start: int) -> str:
    """Return the operand string starting at `start`, balanced over () and []."""
    # skip leading spaces
    i = start
    while i < len(text) and text[i] in " \t":
        i += 1
    if i >= len(text):
        return ""
    if text[i] in "c([":
        # c(...) or [...]
        if text[i] == "c":
            paren = text.find("(", i)
            end = _find_matching_paren(text, paren)
            return text[i:end + 1] if end != -1 else text[i:i + 80]
        opener = text[i]
        closer = ")" if opener == "(" else "]"
        depth = 0
        for j in range(i, len(text)):
            if text[j] == opener:
                depth += 1
            elif text[j] == closer:
                depth -= 1
                if depth == 0:
                    return text[i:j + 1]
        return text[i:i + 80]
    # bare token up to comma
    m = re.match(r"[^,)\n]+", text[i:])
    return m.group(0) if m else ""


def extract_cut_defs(path: Path):
    """Yield dicts for each cut/pd.cut assignment in a file."""
    text = path.read_text(encoding="utf-8", errors="replace")
    lang = "py" if path.suffix.lower() == ".py" else "r"
    out = []
    for m in _ASSIGN_CUT_RE.finditer(text):
        open_idx = m.end() - 1
        close_idx = _find_matching_paren(text, open_idx)
        if close_idx == -1:
            continue
        call = text[open_idx + 1:close_idx]
        bm = _BREAKS_RE.search(call)
        if not bm:
            continue
        breaks_raw = _operand_after(call, bm.end())
        breaks = _norm_breaks(breaks_raw)
        if not breaks or not re.search(r"\d", breaks):
            continue
        rm = _RIGHT_RE.search(call)
        right = _norm_right(rm.group(1) if rm else None, lang)
        lm = _LABELS_RE.search(call)
        labels = re.sub(r"\s+", "", lm.group(1)) if lm else ""
        lhs = m.group("lhs").strip()
        line_no = text[:m.start()].count("\n") + 1
        out.append({
            "var": lhs,
            "kind": "cut",
            "breaks": breaks,
            "right": right,
            "labels": labels,
            "file": str(path),
            "line": line_no,
        })
    return out


# Composite boolean-indicator assignment: `lhs <- as.integer(...)`, `as.numeric`,
# `ifelse(...)`, Python `(...).astype(int)` / `np.where(...)`.
_ASSIGN_DERIVED_RE = re.compile(
    r"(?P<lhs>[A-Za-z_][\w.$\[\]\"']*?)\s*(?:<<-|<-|=)\s*"
    r"(?P<fn>as\.integer|as\.numeric|np\.where|ifelse)\s*\(",
)
_COMPARISON_RE = re.compile(r"==|!=|>=|<=|%in%|>|<")


def _first_arg(call_body: str) -> str:
    """The first top-level (depth-0) comma-delimited argument of a call body."""
    depth = 0
    for i, c in enumerate(call_body):
        if c in "([":
            depth += 1
        elif c in ")]":
            depth -= 1
        elif c == "," and depth == 0:
            return call_body[:i]
    return call_body


def _split_top_level(expr: str, op: str):
    """Split on a top-level (depth-0) boolean operator char `op` ('|' or '&').
    Parenthesized/`&`-or-`|` sub-groups stay intact; the doubled form (`||`/`&&`)
    is treated identically as a single separator."""
    parts, depth, cur, i = [], 0, [], 0
    while i < len(expr):
        c = expr[i]
        if c in "([":
            depth += 1
            cur.append(c)
        elif c in ")]":
            depth -= 1
            cur.append(c)
        elif c == op and depth == 0:
            if i + 1 < len(expr) and expr[i + 1] == op:  # collapse `||` / `&&`
                i += 1
            parts.append("".join(cur))
            cur = []
        else:
            cur.append(c)
        i += 1
    if cur:
        parts.append("".join(cur))
    return parts


def _strip_wrap_parens(a: str) -> str:
    """Remove fully-wrapping outer parens, e.g. `(a | b)` -> `a | b`. A leading
    paren that does NOT close at the end (e.g. `(a & b) | c`) is left intact."""
    a = a.strip()
    while len(a) >= 2 and a[0] == "(" and _find_matching_paren(a, 0) == len(a) - 1:
        a = a[1:-1].strip()
    return a


def _norm_atom(a: str) -> str:
    """Whitespace-free canonical form of one OR-clause. Dataframe-receiver
    qualifiers are dropped so the SAME derivation rule expressed against different
    dataframe objects compares equal — a base-R `df$col`, a bare `mutate()`
    reference, and a Python `df['col']` / `df["col"]` subscript all reduce to the
    column `col`. This matters for a legitimately-parallel sensitivity cohort:
    `v0['end_date'] >= x` in the primary script and `lenient_cohort['end_date'] >= x`
    in the sensitivity script are the SAME rule on two df objects and must not read
    as DERIVED_DEF_DRIFT. A top-level `&`-group is sorted so operand order inside an
    AND does not matter (`x==1 & y>=2` == `y>=2 & x==1`)."""
    a = re.sub(r"\s+", "", _strip_wrap_parens(a))
    a = re.sub(r"[A-Za-z_]\w*\$", "", a)  # base-R df$col / sub$col -> col
    # Python df['col'] / df["col"] receiver subscript -> col (receiver alias dropped)
    a = re.sub(r"[A-Za-z_]\w*\[\s*(['\"])([^'\"]+)\1\s*\]", r"\2", a)
    if "&" in a:
        andparts = _split_top_level(a, "&")
        if len(andparts) > 1:
            a = "&".join(sorted(_strip_wrap_parens(p) for p in andparts))
    return a


def extract_derived_defs(path: Path):
    """Yield dicts for each composite boolean-indicator assignment in a file.

    Only definitions whose expression contains at least one comparison operator
    are kept (a plain `as.integer(count)` cast is not an indicator and is skipped).
    The atom set is order- and whitespace-insensitive."""
    text = path.read_text(encoding="utf-8", errors="replace")
    out = []
    for m in _ASSIGN_DERIVED_RE.finditer(text):
        open_idx = m.end() - 1
        close_idx = _find_matching_paren(text, open_idx)
        if close_idx == -1:
            continue
        inner = text[open_idx + 1:close_idx]
        # np.where(expr, 1, 0) / ifelse(expr, 1, 0): the boolean test is arg 1.
        if m.group("fn") in ("np.where", "ifelse"):
            inner = _first_arg(inner)
        inner = _strip_wrap_parens(inner)
        if not _COMPARISON_RE.search(inner):
            continue
        atoms = sorted({_norm_atom(a) for a in _split_top_level(inner, "|") if _norm_atom(a)})
        if not atoms:
            continue
        lhs = m.group("lhs").strip()
        line_no = text[:m.start()].count("\n") + 1
        out.append({
            "var": lhs,
            "kind": "derived",
            "atoms": atoms,
            "file": str(path),
            "line": line_no,
        })
    return out


def analyze(roots, extra_globs):
    files = []
    seen = set()
    for root in roots:
        rp = Path(root)
        if rp.is_file():
            cands = [rp]
        else:
            cands = [p for p in rp.rglob("*") if p.suffix.lower() in SCRIPT_SUFFIXES]
            for g in extra_globs:
                cands += list(rp.rglob(g))
        for p in cands:
            if p.is_file() and str(p) not in seen:
                seen.add(str(p))
                files.append(p)

    defs = []
    for p in sorted(files):
        try:
            defs.extend(extract_cut_defs(p))
        except OSError:
            continue

    # Group by assigned variable name (normalized to leaf identifier).
    # `df$col` (R) / `df['col']` (py) / `df.col` (py) / bare `col` all reduce to
    # the COLUMN name `col` — the table handle is not the variable of interest.
    def _leaf(v):
        v = v.strip().strip("\"'")
        m = re.search(r"\[\s*[\"']([^\"']+)[\"']\s*\]", v)   # py df['col'] / df["col"]
        if m:
            return m.group(1)
        v = re.sub(r"\[[^\]]*\]", "", v)                      # drop other [..] indexers
        return v.split("$")[-1].split(".")[-1].strip()        # R df$col / py df.col / bare

    groups: dict[str, list[dict]] = {}
    for d in defs:
        groups.setdefault(_leaf(d["var"]), []).append(d)

    claims = []
    for var, ds in sorted(groups.items()):
        sigs = {(d["breaks"], d["right"]) for d in ds}
        # Only meaningful for repeatedly-derived categoricals across >=2 sites.
        if len(ds) < 2 or len(sigs) < 2:
            continue
        # Conservative focus: name looks categorical OR appears in >=2 files.
        n_files = len({d["file"] for d in ds})
        if not (_is_categorical_name(var) or n_files >= 2):
            continue
        detail_parts = []
        for d in ds:
            fn = Path(d["file"]).name
            detail_parts.append(f"{fn}:{d['line']} breaks=[{d['breaks']}] right={d['right']}")
        claims.append({
            "verdict": "BINNING_DRIFT",
            "severity": "Major",
            "var": var,
            "detail": f"`{var}` derived with {len(sigs)} different cut signatures across "
                      f"{n_files} file(s): " + " | ".join(detail_parts),
            "where": "; ".join(f"{Path(d['file']).name}:{d['line']}" for d in ds),
        })

    # --- Composite boolean-indicator definition drift (DERIVED_DEF_DRIFT) -----
    derived_defs = []
    for p in sorted(files):
        try:
            derived_defs.extend(extract_derived_defs(p))
        except OSError:
            continue

    dgroups: dict[str, list[dict]] = {}
    for d in derived_defs:
        dgroups.setdefault(_leaf(d["var"]), []).append(d)

    for var, ds in sorted(dgroups.items()):
        sigs = {tuple(d["atoms"]) for d in ds}
        if len(ds) < 2 or len(sigs) < 2:
            continue
        n_files = len({d["file"] for d in ds})
        # Conservative focus: indicator/categorical-looking name OR re-derived in >=2 files.
        if not (_is_indicator_name(var) or _is_categorical_name(var) or n_files >= 2):
            continue
        siglist = [set(s) for s in sigs]
        diff = sorted(set().union(*siglist) - set.intersection(*siglist))
        detail_parts = [f"{Path(d['file']).name}:{d['line']} {{{', '.join(d['atoms'])}}}" for d in ds]
        claims.append({
            "verdict": "DERIVED_DEF_DRIFT",
            "severity": "Major",
            "var": var,
            "detail": f"`{var}` defined with {len(sigs)} different clause sets across "
                      f"{n_files} file(s); differing clause(s): {{{', '.join(diff)}}}. "
                      + " | ".join(detail_parts),
            "where": "; ".join(f"{Path(d['file']).name}:{d['line']}" for d in ds),
        })

    n_major = sum(1 for c in claims if c["severity"] == "Major")
    return {
        "scanned": [str(p) for p in sorted(files)],
        "definitions": defs + derived_defs,
        "claims": claims,
        "summary": {
            "n_files": len(files),
            "n_definitions": len(defs) + len(derived_defs),
            "n_cut_definitions": len(defs),
            "n_derived_definitions": len(derived_defs),
            "n_claims": len(claims),
            "n_major": n_major,
            "verdict": "MAJOR_CANDIDATE" if n_major else "OK",
        },
    }


def render(result: dict) -> str:
    lines = ["| Check | Severity | Detail |", "|---|---|---|"]
    for c in result["claims"]:
        lines.append(f"| {c['verdict']} | {c['severity']} | {c['detail']} |")
    if len(lines) == 2:
        lines.append("| (none) | — | no cross-script binning or definition drift detected |")
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(
        description="Cross-script categorical / cut-point consistency gate (Phase 2.5b).")
    ap.add_argument("--root", action="append", default=[],
                    help="directory or file to scan (repeatable; "
                         "default: ./analysis and ./scripts if present, else .)")
    ap.add_argument("--glob", action="append", default=[],
                    help="extra filename glob to include under each --root (repeatable)")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true", help="exit 1 if any Major finding")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    args = ap.parse_args()

    roots = args.root
    if not roots:
        roots = [d for d in ("analysis", "scripts") if Path(d).is_dir()] or ["."]

    result = analyze(roots, args.glob)

    if not args.quiet:
        print("=" * 46)
        print(" Cross-script Categorical / Definition Consistency (Phase 2.5c)")
        print("=" * 46)
        print(render(result))
        print()
        s = result["summary"]
        defs_desc = (f"{s['n_cut_definitions']} cut + {s['n_derived_definitions']} "
                     f"composite definitions in {s['n_files']} files")
        if s["n_major"]:
            print(f"MAJOR candidate: {s['n_major']} variable(s) derived inconsistently "
                  f"across scripts ({defs_desc}).")
        else:
            print(f"OK: no cross-script binning or definition drift ({defs_desc}).")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_binning_consistency", **result}, indent=2), encoding="utf-8")
        if not args.quiet:
            print(f"\nwrote {args.out}")

    return 1 if (args.strict and result["summary"]["n_major"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Citation-ORDER gate — numbered floats and the in-text reference series (journal technical-check pass).

Journals (KJR, Radiology, AJR, and most others) require that numbered floats be
**cited in ascending order of first appearance** in the narrative text, evaluated
per series independently:

    main Tables   (Table 1, 2, 3, …)
    main Figures  (Figure 1, 2, 3, …)
    Suppl. Tables (Table S1, S2, … / Supplementary Table S1, …)
    Suppl. Figures(Supplementary Figure S1, … / Figure S1, …)

The same Vancouver discipline governs a FIFTH series the float scan never saw: the
**in-text reference numbers** ("[12]", "[4–11]"). They too must ascend by first
appearance, be contiguous from 1, and reach the reference-list length. A citeproc
manuscript renumbers "[@key]" at render and so has no numbers to check here; but a
HAND-TYPED "[N]" manuscript (the Word/Zotero placeholder path) has no gate at all,
and an out-of-order or gapped reference series is a desk-check reject just like an
out-of-order table.

This is a deterministic, pre-peer-review desk/technical-check item: editorial
offices "unsubmit" manuscripts for it before a reviewer ever sees them. Existing
self-review gates lint xref *resolution* (does the callout resolve to a section)
but never *order*.

What it does: scans the NARRATIVE body (everything before the first float-definition
/ back-matter section header — Figure Legends, Tables, Supplementary, References —
so a legends block that lists figures in order does not mask an out-of-order body),
extracts the first-citation position of every numbered float per series AND of every
bracketed reference number, EXPANDS ranges ("4–11" → 4..11 — so a number inside a
rendered range is never read as a false gap), and flags any series whose first-
appearance sequence is not ascending (or, for references, is gapped or overruns the list).

Verdicts:
  CITATION_ORDER (Major)  a float series is cited out of numerical order (e.g., Table 3
                          first-cited before Table 1, or Suppl. Tables cited
                          S3, S1, S2, …). Technical-check-fatal.
  CITATION_GAP  (Minor)   a float series' cited numbers are not contiguous from 1
                          (a possible missing / mis-numbered float). Report-only.
  REFERENCE_ORDER (Major) in-text reference numbers are cited out of order (e.g. [12]
                          before [5]) — the Vancouver list is mis-numbered. Ranges are
                          expanded first, so a re-citation inside "[4–11]" is not a fault.
  REFERENCE_GAP (Minor)   cited reference numbers are not contiguous from 1 (a number
                          never cited) — a missing or mis-numbered citation. Report-only.
  REFERENCE_COUNT_MISMATCH  the highest cited reference overruns the reference-list length
        (Major/Minor)     ([N] resolves to nothing → Major dangling), or the list has
                          trailing entries never cited (→ Minor). Needs a numbered list.
  UNCITED_FLOAT (Minor)   a float that HAS a legend/caption in the back matter is never
                          cited anywhere in the narrative body — a display item the reader
                          is never pointed to (uncited supplements/tables/figures are a
                          recurrent reviewer/technical-check rejection). Report-only.
  DANGLING_SECTION_XREF   an in-text "Section N" / "Section N.M" reference has no
        (Major)           matching numbered heading — the common case being a
                          journal that typesets UNNUMBERED headings, where every
                          such reference dangles at production. Name the heading
                          instead of a number. ("Supplementary/Appendix Section N"
                          is exempt — it points at the supplement.)

Fix: renumber the series by first-citation order (and reorder the float/supplement
document + remap ALL cross-references, expanding ranges like "S12–S15" by hand and
leaving non-float "S1–S6" sensitivity-spec labels untouched), or rephrase to remove
the early out-of-order citation. See ~/.claude/rules/journal-technical-check-gate.md.

INPUT
  --manuscript  manuscript markdown/text (required).
  --include-back-matter  also scan back-matter sections (legends/refs) — off by default.

OUTPUT
  stdout table and, with --out, a JSON artifact {manuscript, claims[], summary}.

Stdlib-only (re / json / argparse / pathlib). Exit codes: 0 clean (or report-only),
1 Major claim(s) found (with --strict), 2 input/usage error.
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

from _frontmatter import strip_frontmatter

# A back-matter / float-definition section header. Everything from the first such
# header onward is excluded from the body citation-order scan (legends list floats
# in order by construction; references are not citations).
BACK_MATTER_RE = re.compile(
    r"(?im)^#{1,6}\s*\**\s*"
    r"(figure\s+legends?|figure\s+captions?|table\s+legends?|table\s+captions?|"
    r"tables?|supplementary|supplement|references|bibliography)\b")

# A "Table(s)/Figure(s) <numlist>" mention. numlist = S?<digits> tokens joined by
# comma / ampersand / en-dash / hyphen / "and". Captures the kind word + the list.
MENTION_RE = re.compile(
    r"\b(Tables?|Figures?)\s+"
    r"(S?\d+(?:\s*(?:,|&|–|-|and)\s*S?\d+)*)", re.IGNORECASE)

# One citation token inside a numlist: optional S-prefix, a number, and an optional
# "A–B" range tail. Ranges MUST be expanded before ordering/gap analysis — an
# endpoint-only read of "4–11" as {4, 11} both hides the interior (5..10) and reports
# every interior number as a false gap. Shared by the float scan and the reference scan.
TOKEN_RANGE_RE = re.compile(r"(S?)(\d+)(?:\s*[–—-]\s*(S?)(\d+))?", re.IGNORECASE)


def _expand_numlist(numlist: str):
    """Yield (supp_bool, number, offset) for every number in a citation numlist,
    expanding an "A–B" range to A..B. offset is the token's start within numlist so a
    caller can recover first-appearance position; a range's members share the range
    token's offset. The S-prefix of a range is taken from its start token. An inverted
    or absurdly wide (> 500) range degrades to its two endpoints rather than expanding."""
    for m in TOKEN_RANGE_RE.finditer(numlist):
        supp = bool(m.group(1))
        a = int(m.group(2))
        if m.group(4) is not None:
            b = int(m.group(4))
            if a <= b <= a + 500:
                for k in range(a, b + 1):
                    yield supp, k, m.start()
            else:
                yield supp, a, m.start()
                yield bool(m.group(3)) or supp, b, m.start(4)
        else:
            yield supp, a, m.start()


# An in-text numbered reference citation: a bracketed numlist ("[12]", "[4,5]",
# "[4–11]"). Guards against the other square-bracket syntaxes: a wikilink "[[1]]"
# (leading "["), an image "![alt]" (leading "!"), a markdown link "[1](url)" or link-
# definition "[1]:" (trailing "(" / ":"), and a footnote "[^1]" (the "^" is not a digit,
# so it never matches). Only the bracketed Vancouver form is scanned — parenthetical
# "(1)" is left alone: it is indistinguishable from equation, panel, group-size and
# CI-bound numbers.
REF_CITE_RE = re.compile(r"(?<![\[!])\[(\d[\d\s,;&–—-]*)\](?!\s*[:(\[])")
# A numbered entry in the reference list ("1. …", "[1] …", "1) …").
REF_LIST_ITEM_RE = re.compile(r"(?m)^\s{0,3}(?:\[(\d+)\]|(\d+)[.)])\s+\S")
# Below this many distinct in-text reference numbers there is too little signal to tell
# a Vancouver citation apart from a stray "[1]", so the reference-series check stays silent.
REF_MIN_DISTINCT = 3

SERIES_LABEL = {
    ("table", False): "Table",
    ("figure", False): "Figure",
    ("table", True): "Supplementary Table",
    ("figure", True): "Supplementary Figure",
}

# A float DEFINITION (legend / caption line) in the back matter — line-start, optional
# bold, the kind word, the number, then a caption delimiter (`.`/`:`/`|`). This is a
# definition, not a citation: "Table 3. Baseline characteristics" (legend) vs "Table 3
# shows…" (citation). Series is keyed by the number's S-prefix, exactly as the body-
# citation scan keys it, so a defined float and its in-text citation land in the same
# series and never produce a spurious mismatch.
FLOAT_DEF_RE = re.compile(
    r"(?im)^\s{0,3}\**\s*(?:Supplementary\s+|Suppl\.?\s+|Online\s+|e-?)?"
    r"(Table|Figure)\s+(S?\d+)\s*[.:|]")
# The references/bibliography list is back matter too but is not a source of float
# definitions; truncate the definition scan there so a "Fig. 3" inside a citation string
# cannot be read as a legend.
REF_HEADER_RE = re.compile(r"(?im)^#{1,6}\s*\**\s*(references|bibliography)\b")

# In-text reference to a numbered section ("as reported in Section 3.4"). Many
# medical journals typeset UNNUMBERED headings (house style), so a "Section N"
# cross-reference written during drafting dangles at production — a deterministic
# desk/galley flag the float-order check does not cover.
SECTION_REF_RE = re.compile(r"\bSection\s+(\d+(?:\.\d+)?)\b")
# A heading that carries a leading number: "## 3 Results", "### 3.4 Foo".
NUMBERED_HEADING_RE = re.compile(r"^#{1,6}\s+\*{0,2}\s*(\d+(?:\.\d+)*)\b", re.MULTILINE)


def _check_section_xref(body: str) -> list[dict]:
    """A `Section N` / `Section N.M` reference must resolve to a numbered heading.
    If the manuscript has no numbered headings at all (the common unnumbered-house-
    style case), every such reference dangles at typeset."""
    refs: list[str] = []
    for m in SECTION_REF_RE.finditer(body):
        pre = body[max(0, m.start() - 18):m.start()].lower()
        if "supplement" in pre or "appendix" in pre:
            continue  # "Supplementary Section 3" points at the supplement, not a body section
        refs.append(m.group(1))
    if not refs:
        return []
    heading_nums = set(NUMBERED_HEADING_RE.findall(body))
    dangling = [r for r in dict.fromkeys(refs)
                if not any(h == r or h.startswith(r + ".") for h in heading_nums)]
    if not dangling:
        return []
    refs_str = ", ".join(f"Section {d}" for d in dangling)
    if not heading_nums:
        detail = (f"in-text cross-reference(s) to numbered sections ({refs_str}) but the manuscript "
                  f"has no numbered headings — every 'Section N' reference dangles at typeset "
                  f"(unnumbered-heading house style); name the heading (e.g. 'the Sensitivity analyses "
                  f"section') instead of a number")
    else:
        detail = (f"{refs_str} has no matching numbered heading "
                  f"(numbered headings present: {', '.join(sorted(heading_nums))}); "
                  f"name the heading or correct the number")
    return [{
        "verdict": "DANGLING_SECTION_XREF",
        "severity": "Major",
        "detail": detail,
        "where": refs_str[:160],
    }]


def _body(text: str, include_back_matter: bool) -> str:
    if include_back_matter:
        return text
    m = BACK_MATTER_RE.search(text)
    return text[: m.start()] if m else text


def _first_appearance(text: str):
    """Return {series_label: [numbers in order of first appearance]} for the body."""
    seen: dict[str, dict[int, int]] = {}  # label -> {number: first_position}
    for m in MENTION_RE.finditer(text):
        kind = "table" if m.group(1).lower().startswith("table") else "figure"
        for supp, num, off in _expand_numlist(m.group(2)):
            label = SERIES_LABEL[(kind, supp)]
            seen.setdefault(label, {})
            # keep the EARLIEST position for each number
            pos = m.start() + off
            if num not in seen[label] or pos < seen[label][num]:
                seen[label][num] = pos
    order = {}
    for label, num_pos in seen.items():
        # tie-break by number so a range's members read ascending at their shared position
        order[label] = [n for n, _ in sorted(num_pos.items(), key=lambda kv: (kv[1], kv[0]))]
    return order


def _defined_floats(text: str) -> set[tuple[str, int]]:
    """{(series_label, number)} for every float DEFINED by a legend/caption line in the
    back matter (references excluded). Keyed the same way as a body citation."""
    m = REF_HEADER_RE.search(text)
    legends = text[: m.start()] if m else text
    out: set[tuple[str, int]] = set()
    for dm in FLOAT_DEF_RE.finditer(legends):
        kind = "table" if dm.group(1).lower() == "table" else "figure"
        supp = dm.group(2)[0].lower() == "s"
        num = int(dm.group(2).lstrip("Ss"))
        out.add((SERIES_LABEL[(kind, supp)], num))
    return out


def _cited_floats(body: str) -> set[tuple[str, int]]:
    """{(series_label, number)} cited at least once in the narrative body."""
    return {(label, n) for label, nums in _first_appearance(body).items() for n in nums}


def _check_uncited_floats(clean: str) -> list[dict]:
    """A float DEFINED by a legend/caption but never cited in the narrative body is a
    display item the reader is never pointed to — editorial offices and reviewers reject
    uncited tables/figures/supplements (DIR-4084: three supplements shipped uncited)."""
    m = BACK_MATTER_RE.search(clean)
    if not m:
        return []  # no legends/back matter -> nothing is "defined" to check against
    body_only = clean[: m.start()]
    defined = _defined_floats(clean[m.start():])
    if not defined:
        return []
    cited = _cited_floats(body_only)
    claims = []
    for label, num in sorted(defined - cited):
        prefix = "S" if label.startswith("Supplementary") else ""
        claims.append({
            "verdict": "UNCITED_FLOAT",
            "severity": "Minor",
            "detail": (f"{label} {prefix}{num} has a legend/caption but is never cited in the "
                       f"main text — cite it at least once or remove it (editorial offices and "
                       f"reviewers flag display items the narrative never points to)"),
            "where": f"{label} {prefix}{num}",
        })
    return claims


def _reference_list_length(text: str) -> "int | None":
    """Highest number in the numbered reference/bibliography list, or None if there is no
    such list (e.g. a citeproc manuscript whose bibliography is generated at render)."""
    m = REF_HEADER_RE.search(text)
    if not m:
        return None
    nums = [int(im.group(1) or im.group(2)) for im in REF_LIST_ITEM_RE.finditer(text[m.end():])]
    return max(nums) if nums else None


def _reference_series(body: str, full_text: str) -> list[dict]:
    """Bracketed in-text reference citations ("[12]", "[4–11]") must be cited in ascending
    order of first appearance, be contiguous from 1, and reach the reference-list length —
    the Vancouver numbering discipline a hand-typed "[N]" manuscript has no other gate for.
    Ranges are expanded first, so a number inside "[4–11]" is never a false gap; citeproc
    "[@key]" manuscripts match nothing here and stay silent."""
    first: dict[int, int] = {}  # reference number -> earliest position
    for m in REF_CITE_RE.finditer(body):
        for _supp, num, off in _expand_numlist(m.group(1)):
            pos = m.start() + off
            if num not in first or pos < first[num]:
                first[num] = pos
    if len(first) < REF_MIN_DISTINCT:
        return []  # too little signal to distinguish citations from stray brackets
    seq = [n for n, _ in sorted(first.items(), key=lambda kv: (kv[1], kv[0]))]
    pretty = ", ".join(str(n) for n in seq)
    claims: list[dict] = []
    if seq != sorted(seq):
        inv = next((seq[i] for i in range(1, len(seq)) if seq[i] < seq[i - 1]), seq[-1])
        claims.append({
            "verdict": "REFERENCE_ORDER",
            "severity": "Major",
            "detail": (f"in-text references are cited out of numerical order — first-citation "
                       f"sequence is [{pretty}]; Vancouver numbering must ascend by first "
                       f"appearance (renumber the reference list and remap every [N], or correct "
                       f"the marker; first inversion at [{inv}])"),
            "where": "reference series",
        })
        return claims  # order is wrong; gap/count numbers are not yet meaningful
    cited = set(first)
    hi = max(cited)
    length = _reference_list_length(full_text)
    if length is not None and hi > length:
        # A citation points past the end of the list — the dominant fault. The apparent
        # gap up to [hi] is an artifact of the dangling number, so report only this.
        claims.append({
            "verdict": "REFERENCE_COUNT_MISMATCH",
            "severity": "Major",
            "detail": (f"the highest in-text reference cited is [{hi}] but the reference list has "
                       f"only {length} entries — [{hi}] resolves to nothing (dangling citation)"),
            "where": "reference series",
        })
        return claims
    missing = [n for n in range(1, hi + 1) if n not in cited]
    if missing:
        claims.append({
            "verdict": "REFERENCE_GAP",
            "severity": "Minor",
            "detail": (f"in-text references cited [{pretty}] are not contiguous from 1 (never "
                       f"cited: {', '.join(str(n) for n in missing)}) — a missing or mis-numbered "
                       f"citation (ranges like [4–11] are expanded before this check)"),
            "where": "reference series",
        })
    if length is not None and hi < length:
        claims.append({
            "verdict": "REFERENCE_COUNT_MISMATCH",
            "severity": "Minor",
            "detail": (f"in-text references reach [{hi}] but the reference list has {length} "
                       f"entries — {length - hi} trailing reference(s) are never cited (or the "
                       f"list is mis-numbered)"),
            "where": "reference series",
        })
    return claims


def check(text: str, include_back_matter: bool) -> list[dict]:
    claims = []
    # Strip any leading YAML front matter first: a `status:`/changelog block that narrates a
    # display-item renumber ("old Table 1 -> Supplementary Table S2") is not a body citation.
    clean = strip_frontmatter(text)
    body = _body(clean, include_back_matter)
    claims += _check_section_xref(body)
    claims += _check_uncited_floats(clean)
    claims += _reference_series(body, clean)
    order = _first_appearance(body)
    for label in ("Table", "Figure", "Supplementary Table", "Supplementary Figure"):
        seq = order.get(label)
        if not seq or len(seq) < 2:
            continue
        prefix = "S" if label.startswith("Supplementary") else ""
        pretty = ", ".join(f"{prefix}{n}" for n in seq)
        # ORDER: first-appearance sequence must be ascending.
        if seq != sorted(seq):
            # locate the first inversion for a precise message
            inv = next((seq[i] for i in range(1, len(seq)) if seq[i] < seq[i - 1]), seq[-1])
            claims.append({
                "verdict": "CITATION_ORDER",
                "severity": "Major",
                "detail": (f"{label}s are cited out of numerical order — first-citation "
                           f"sequence is {pretty}; renumber by first-citation order or "
                           f"rephrase (first inversion at {prefix}{inv})"),
                "where": f"{label} series",
            })
        else:
            # GAP (Minor) only when order is otherwise fine, to avoid double-flagging.
            expected = list(range(1, max(seq) + 1))
            if seq != expected:
                missing = [f"{prefix}{n}" for n in expected if n not in seq]
                claims.append({
                    "verdict": "CITATION_GAP",
                    "severity": "Minor",
                    "detail": (f"{label}s cited {pretty} are not contiguous from 1 "
                               f"(not cited in body: {', '.join(missing)}) — check for a "
                               f"missing or mis-numbered float"),
                    "where": f"{label} series",
                })
    return claims


def analyze(manuscript: str, include_back_matter: bool) -> dict:
    p = Path(manuscript)
    if not p.is_file():
        sys.stderr.write(f"ERROR: manuscript not found: {manuscript}\n")
        sys.exit(2)
    claims = check(p.read_text(encoding="utf-8"), include_back_matter)
    n_major = sum(1 for c in claims if c["severity"] == "Major")
    n_minor = sum(1 for c in claims if c["severity"] == "Minor")
    return {
        "manuscript": str(p),
        "claims": claims,
        "summary": {
            "n_claims": len(claims),
            "n_major": n_major,
            "n_minor": n_minor,
            "verdict": "MAJOR_CANDIDATE" if n_major else "OK",
        },
    }


def render(result: dict) -> str:
    lines = ["| Check | Severity | Detail |", "|---|---|---|"]
    for c in result["claims"]:
        lines.append(f"| {c['verdict']} | {c['severity']} | {c['detail']} |")
    if len(lines) == 2:
        lines.append("| (none) | — | all float series cited in ascending order |")
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(description="Float citation-order gate (technical-check pass).")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--include-back-matter", action="store_true",
                    help="also scan legends/references back-matter (off by default)")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true", help="exit 1 if any Major claim exists")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    args = ap.parse_args()

    result = analyze(args.manuscript, args.include_back_matter)
    if not args.quiet:
        print("=" * 41)
        print(" Float Citation Order")
        print("=" * 41)
        print(render(result))
        print()
        s = result["summary"]
        print(f"MAJOR candidate: {s['n_major']} out-of-order series." if s["n_major"]
              else "OK: every float series is cited in ascending order.")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_citation_order", **result}, indent=2), encoding="utf-8")
        if not args.quiet:
            print(f"\nwrote {args.out}")

    return 1 if (args.strict and result["summary"]["n_major"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Claim-vs-artifact cross-check for self-review Phase 2.5f (narrowed 1st scope).

The errors that survive a single-pass review are the ones where the manuscript
text is internally consistent but disagrees with an external artifact — the
pre-registration, the analysis code, the qc outputs. This gate checks the two
highest-value, deterministic instances:

  1. ESTIMAND PROVENANCE — does the manuscript's stated primary contrast match
     the pre-registered / protocol primary, and is there language admitting the
     primary was re-designated after results were known (outcome-dependent
     primary selection)?
  2. E-VALUE — is a reported E-value arithmetically consistent with its adjacent
     effect estimate, and is it attached to the *primary* estimate rather than a
     secondary/exploratory one quoted as if it bounded the headline claim?
  3. REGISTRATION CHRONOLOGY — a "prospectively registered" claim is falsifiable
     against the manuscript's own dates: if the registration date postdates search
     completion, the review was registered retrospectively. Manuscript-internal
     (needs no external prereg artifact); include supplement text in --manuscript
     to catch an overclaim that survives only in the supplement.

Figure/flow-count reconciliation, Methods-promised-analysis completeness, and
imputation-input integrity are separate subchecks (see /make-figures and
/write-paper); the JSON schema below reserves their `type` values so they can be
added without a breaking change.

INPUTS
  --manuscript  manuscript markdown/text.
  --prereg      pre-registration / protocol / project.yaml text (for estimand
                provenance). Optional; without it only the post-hoc-reassignment
                language scan and the E-value check run.

OUTPUT  (--out path)
  {"claims": [{claim_id, type, prose_value, artifact_source, verdict, detail}],
   "summary": {...}}
  Major verdicts: PRIMARY_REASSIGNED (explicit post-hoc re-designation),
                  EVALUE_ARITHMETIC.
  Advisory flags (review, not strict-fail): ESTIMAND_DRIFT (fuzzy prereg↔manuscript
                  primary token overlap — confirm against the registration first),
                  PRIMARY_DISCLOSURE_NOTE (honest manuscript-stage disclosure),
                  EVALUE_NON_PRIMARY, EVALUE_UNVERIFIABLE, FLAG_NO_PREREG_PRIMARY.

Stdlib-only (re / json / math / argparse). Exit codes: 0 clean (or report-only),
1 a Major verdict exists (with --strict), 2 input/usage error.
"""

from __future__ import annotations

import argparse
import json
import math
import re
import sys
from pathlib import Path

from _frontmatter import strip_frontmatter

EVALUE_TOL = 0.15  # relative tolerance for E-value recompute

PRIMARY_RE = re.compile(
    r"[^.]*\bprimary\b[^.]*\b(outcome|endpoint|analysis|objective|contrast|comparison|model|estimand)[^.]*\.",
    re.I,
)
# Explicit post-hoc re-designation of the primary (Major): the estimand was
# changed / switched / re-designated, chosen post-hoc, or selected after results
# were known. This is a genuine integrity issue.
REASSIGN_RE = re.compile(
    r"\bprimary\b[^.]*\b(re-?designat|re-?assign|re-?defin|switch|chang)\w*|"
    r"\b(re-?designat|re-?assign)\w*[^.]*\bprimary\b|"
    r"\bpost[- ]?hoc\b[^.]*\bprimary\b|"
    r"\bprimary\b[^.]*\bafter\b[^.]*\bresult",
    re.I,
)
# Honest disclosure of a manuscript-stage analytical decision (ADVISORY, not Major):
# estimand-provenance guidance *recommends writing* exactly this. Flag only to confirm
# it is disclosed coequally with the pre-specified analysis, not to allege a violation.
# Only emitted when the explicit-reassignment pattern above does NOT also match.
DISCLOSURE_RE = re.compile(
    r"\bmanuscript[- ]stage\b[^.]*\b(decision|primary|analy)|"
    r"\b(decision|analys[ie]s)\b[^.]*\bmanuscript[- ]stage\b",
    re.I,
)
EFFECT_RE = re.compile(r"\b(s?HR|a?HR|a?OR|RR|hazard ratio|odds ratio|risk ratio)\b\D{0,8}(\d+\.\d+)", re.I)
# The E-value figure follows a connective (was / of / = / :), so the non-greedy
# scan does not grab the effect estimate's number from an adjacent "(HR 1.34)".
EVALUE_RE = re.compile(
    r"E[- ]?value\b[^\n]{0,90}?\b(?:was|were|of|is|=|:|reached|equals?(?:\s+to)?)\s*\(?(\d+\.\d+)",
    re.I,
)
NONPRIMARY_KW = ("secondary", "exploratory", "subgroup", "sensitivity", "supporting",
                 "cause-specific", "cancer-specific", "post-hoc", "post hoc", "non-primary")

# The manuscript asserts exactly ONE primary model/analysis (so a script annotating a
# model as "co-primary" is a third-SSOT drift).
SINGLE_PRIMARY = re.compile(
    r"\bsingle\s+primary\b|\ba\s+single\s+primary\b|\bone\s+primary\s+(?:model|analysis|endpoint|outcome)\b"
    r"|\bthe\s+primary\s+(?:model|analysis|endpoint|outcome)\b[^.]{0,70}?"
    r"(?:consistent\s+with\s+the\s+(?:registered|pre-?specified)|registered\s+analysis\s+plan)",
    re.I)
# A model annotated "co-primary" in analysis code (a comment, string, or variable).
CO_PRIMARY_CODE = re.compile(r"\bco[-\s]?primary\b", re.I)

STOP = set("the a an of for in on to and or with by is was were are be been being this that "
           "between association associated estimated using model analysis primary outcome "
           "endpoint study patients group as at from".split())


def _tokens(s: str) -> set[str]:
    return {w for w in re.findall(r"[a-z0-9]+", s.lower()) if w not in STOP and len(w) > 2}


def _jaccard(a: set[str], b: set[str]) -> float:
    if not a or not b:
        return 0.0
    return len(a & b) / len(a | b)


# Structured pre-registration fields — the authoritative anchor when the prereg is
# a project.yaml / registration form with explicit keys. Comparing the manuscript
# primary sentence against these VALUES (which carry the actual variable names)
# beats comparing it against a free-text "Strategy for data synthesis" paragraph or
# a `# PRIMARY — locked` YAML comment, which are lexically dissimilar even when
# semantically identical.
_STRUCT_PRIMARY_RE = re.compile(
    r"^\s*(primary_(?:exposure|outcome|estimand|endpoint|contrast|model|comparison|analysis))\s*:\s*(.+?)\s*$",
    re.I | re.M,
)


def _structured_primary(prereg: str) -> list[str]:
    """Values of explicit primary_* keys in a structured prereg (YAML/form)."""
    out = []
    for m in _STRUCT_PRIMARY_RE.finditer(prereg):
        v = m.group(2).strip().strip("\"'").strip()
        if v and not v.startswith("#"):
            out.append(v)
    return out


def _strip_yaml_comments(text: str) -> str:
    """Drop whole-line YAML/# comments so PRIMARY_RE does not anchor on a
    `# PRIMARY — locked` annotation rather than a real primary-outcome statement."""
    return "\n".join(ln for ln in text.splitlines() if not ln.lstrip().startswith("#"))


def evalue_point(rr: float) -> float:
    """VanderWeele-Ding E-value for a point estimate (risk-ratio scale)."""
    g = rr if rr >= 1 else 1.0 / rr
    return g + math.sqrt(g * (g - 1.0))


def _flatten(t: str) -> str:
    return re.sub(r"\s*\n\s*", " ", t)


def check_estimand(manuscript: str, prereg: str | None, prereg_raw: str | None = None) -> list[dict]:
    claims = []
    man_primary = [m.group(0).strip() for m in PRIMARY_RE.finditer(manuscript)]

    # 1. Explicit post-hoc reassignment language (highest-confidence Major catch).
    m = REASSIGN_RE.search(manuscript)
    if m:
        claims.append({
            "claim_id": "EST-reassign",
            "type": "estimand",
            "prose_value": re.sub(r"\s+", " ", manuscript[max(0, m.start() - 40):m.end() + 40]).strip(),
            "artifact_source": "manuscript (self-admission)",
            "verdict": "PRIMARY_REASSIGNED",
            "detail": "Language indicates the primary was re-designated after results were known; "
                      "report the pre-specified and revised models coequally and disclose the change.",
        })
    else:
        # 1b. Honest manuscript-stage disclosure → advisory note, NOT a Major. The
        # estimand-provenance guidance recommends writing this; do not penalise it.
        d = DISCLOSURE_RE.search(manuscript)
        if d:
            claims.append({
                "claim_id": "EST-disclosure",
                "type": "estimand",
                "prose_value": re.sub(r"\s+", " ", manuscript[max(0, d.start() - 40):d.end() + 40]).strip(),
                "artifact_source": "manuscript (disclosed analytical decision)",
                "verdict": "PRIMARY_DISCLOSURE_NOTE",
                "detail": "Discloses a manuscript-stage analytical decision — the honest disclosure "
                          "estimand-provenance guidance recommends, not a violation. Confirm the "
                          "pre-specified and revised analyses are reported coequally. Advisory, not Major.",
            })

    # 2. Manuscript primary vs prereg primary (token overlap).
    if prereg:
        # Prefer explicit structured primary_* fields (authoritative). Structured
        # extraction needs the RAW (line-based) prereg — the flattened form has no
        # line boundaries. Otherwise fall back to free-text primary sentences, with
        # YAML comment lines stripped so the anchor is a real statement, not a
        # `# PRIMARY — locked` annotation.
        raw = prereg_raw if prereg_raw is not None else prereg
        struct = _structured_primary(raw)
        pre_primary = struct or [m.group(0).strip()
                                 for m in PRIMARY_RE.finditer(_flatten(_strip_yaml_comments(raw)))]
        anchor = "structured prereg field" if struct else "prereg primary sentence"
        if man_primary and pre_primary:
            # tokens of every manuscript primary sentence vs the union of prereg
            # anchors — a structured field's variable names need only appear somewhere
            # in the manuscript's primary description to count as consistent.
            man_tok = set().union(*[_tokens(a) for a in man_primary])
            pre_tok = set().union(*[_tokens(b) for b in pre_primary])
            score = _jaccard(man_tok, pre_tok)
            best_a = max(man_primary, key=lambda a: _jaccard(_tokens(a), pre_tok))
            # Structured-field match is more reliable, so a moderate overlap is a
            # soft "confirm", not a drift allegation. Free-text stays at the old 0.30.
            drift_cut, confirm_cut = (0.20, 0.40) if struct else (0.30, 0.30)
            verdict = ("ESTIMAND_DRIFT" if score < drift_cut
                       else "ESTIMAND_CONFIRM" if score < confirm_cut else "OK")
            claims.append({
                "claim_id": "EST-primary",
                "type": "estimand",
                "prose_value": re.sub(r"\s+", " ", best_a)[:160],
                "artifact_source": (re.sub(r"\s+", " ", " | ".join(pre_primary))[:160]),
                "verdict": verdict,
                "detail": f"manuscript↔{anchor} token overlap = {score:.2f} "
                          f"(<{drift_cut:.2f} → drift candidate; {drift_cut:.2f}–{confirm_cut:.2f} → "
                          f"confirm). ADVISORY: fuzzy token overlap is noisy; confirm against the "
                          f"actual registration before treating as drift.",
            })
        elif man_primary and not pre_primary:
            claims.append({
                "claim_id": "EST-primary",
                "type": "estimand",
                "prose_value": re.sub(r"\s+", " ", man_primary[0])[:160],
                "artifact_source": "prereg (no primary statement found)",
                "verdict": "FLAG_NO_PREREG_PRIMARY",
                "detail": "No primary-outcome statement located in the prereg/protocol; confirm one exists.",
            })
    return claims


def check_evalue(manuscript: str) -> list[dict]:
    claims = []
    for i, m in enumerate(EVALUE_RE.finditer(manuscript), 1):
        stated = float(m.group(1))
        # sentence window around the E-value
        start = manuscript.rfind(".", 0, m.start()) + 1
        end = manuscript.find(".", m.end())
        sent = manuscript[start:(end if end != -1 else len(manuscript))]
        eff = EFFECT_RE.search(sent)
        nonprimary = any(kw in sent.lower() for kw in NONPRIMARY_KW)

        if not eff:
            claims.append({
                "claim_id": f"EVAL-{i}",
                "type": "evalue",
                "prose_value": f"E-value {stated}",
                "artifact_source": "no adjacent effect estimate",
                "verdict": "EVALUE_UNVERIFIABLE",
                "detail": "No HR/OR/RR found in the same sentence; confirm the E-value is computed "
                          "for the declared primary estimate.",
            })
            continue

        rr = float(eff.group(2))
        recomputed = evalue_point(rr)
        rel = abs(stated - recomputed) / recomputed if recomputed else 1.0
        if rel > EVALUE_TOL:
            verdict = "EVALUE_ARITHMETIC"
            detail = (f"stated E-value {stated} but {eff.group(1)} {rr} recomputes to "
                      f"{recomputed:.2f} (rel. diff {rel:.0%} > {EVALUE_TOL:.0%}); the stated value "
                      "likely belongs to a different (e.g. non-primary) estimate.")
        elif nonprimary:
            verdict = "EVALUE_NON_PRIMARY"
            detail = (f"E-value {stated} matches {eff.group(1)} {rr} (recompute {recomputed:.2f}), "
                      "but the sentence references a secondary/exploratory estimate; confirm the "
                      "headline E-value bounds the PRIMARY contrast, not this one.")
        else:
            verdict = "OK"
            detail = f"E-value {stated} consistent with {eff.group(1)} {rr} (recompute {recomputed:.2f})."
        claims.append({
            "claim_id": f"EVAL-{i}",
            "type": "evalue",
            "prose_value": f"E-value {stated} ({eff.group(1)} {rr})",
            "artifact_source": "recomputed (VanderWeele-Ding)",
            "verdict": verdict,
            "detail": detail,
        })
    return claims


# ESTIMAND_DRIFT (fuzzy prereg↔manuscript token overlap) and PRIMARY_DISCLOSURE_NOTE
# (honest manuscript-stage disclosure) are ADVISORY, not Major: the docs require
# manual confirmation against the registration before either is acted on, and a P0
# that needs hand-confirmation is not a P0. Only explicit re-designation and a
# non-recomputing E-value are Major.
def check_code_labels(manuscript: str, scripts_dir: str | None) -> list[dict]:
    """Reconcile the manuscript's declared primary against analysis-script labels.

    Fires only the specific conflict: the manuscript asserts a SINGLE primary while an
    analysis script annotates a model as 'co-primary' — the code label is a third SSOT
    that drifts across revisions. Advisory (code comments can lag)."""
    claims: list[dict] = []
    if not scripts_dir:
        return claims
    d = Path(scripts_dir)
    if not d.exists() or not SINGLE_PRIMARY.search(manuscript):
        return claims
    for p in sorted(d.rglob("*")):
        if p.suffix.lower() not in (".r", ".py"):
            continue
        try:
            txt = p.read_text(encoding="utf-8", errors="replace")
        except OSError:
            continue
        m = CO_PRIMARY_CODE.search(txt)
        if not m:
            continue
        ln = txt[:m.start()].count("\n") + 1
        snippet = txt.splitlines()[ln - 1].strip()[:80] if ln - 1 < len(txt.splitlines()) else ""
        claims.append({
            "claim_id": "EST-code-label",
            "type": "estimand",
            "prose_value": "manuscript asserts a single primary model/analysis",
            "artifact_source": f"{p.name}:{ln} labels a model 'co-primary'",
            "verdict": "PRIMARY_LABEL_CODE_DRIFT",
            "detail": (f"the manuscript declares a SINGLE primary while an analysis script "
                       f"annotates a model as co-primary ({p.name}:{ln}: '{snippet}'); reconcile "
                       f"the code's primary/co-primary label with the declared estimand — code "
                       f"labels are a third SSOT that can drift across revisions. ADVISORY."),
        })
        break  # one is enough to prompt a reconcile
    return claims


# --- Check: REGISTRATION_CHRONOLOGY ----------------------------------------
# A "prospectively registered" claim is falsifiable against the manuscript's own
# dates: if the registration date postdates search completion, the review was
# registered *retrospectively*, and a reviewer flags the overclaim on sight. This
# is manuscript-internal (no external prereg artifact needed) -- both dates and the
# claim live in the text (body or supplement). Fires only when a prospective claim
# co-occurs with a registry AND both dates parse AND registration > search-end.
_MONTHS = ("January|February|March|April|May|June|July|August|September|October|"
           "November|December")
_MONTH_NUM = {m.lower(): i + 1 for i, m in enumerate(_MONTHS.split("|"))}
_DATE = (rf"\d{{4}}-\d{{2}}-\d{{2}}|\d{{1,2}}\s+(?:{_MONTHS})\s+\d{{4}}|"
         rf"(?:{_MONTHS})\s+\d{{1,2}},?\s+\d{{4}}")
_PROSPECTIVE_RE = re.compile(r"\bprospectiv\w*\b", re.I)
_REGISTRY_RE = re.compile(r"\b(?:PROSPERO|CRD42\d{9}|OSF|ClinicalTrials|NCT\d{6,})\b", re.I)
_REG_DATE_RE = re.compile(
    rf"(?:registered|registration|PROSPERO|CRD42\d{{9}}|OSF)[^.]*?\bon\b\s+({_DATE})"
    rf"|(?:registered|registration)[^.]{{0,60}}?({_DATE})", re.I)
_SEARCH_END_RE = re.compile(
    rf"search\w*[^.]*?\b(?:to|through|up to|until|inception to)\b\s+({_DATE})"
    rf"|search\w*[^.]{{0,80}}?({_DATE})", re.I)


def _parse_date(s: str) -> tuple[int, int, int] | None:
    s = s.strip()
    m = re.fullmatch(r"(\d{4})-(\d{2})-(\d{2})", s)
    if m:
        return (int(m.group(1)), int(m.group(2)), int(m.group(3)))
    m = re.fullmatch(rf"(\d{{1,2}})\s+({_MONTHS})\s+(\d{{4}})", s, re.I)
    if m:
        return (int(m.group(3)), _MONTH_NUM[m.group(2).lower()], int(m.group(1)))
    m = re.fullmatch(rf"({_MONTHS})\s+(\d{{1,2}}),?\s+(\d{{4}})", s, re.I)
    if m:
        return (int(m.group(3)), _MONTH_NUM[m.group(1).lower()], int(m.group(2)))
    return None


def _first_group(m) -> str | None:
    return next((g for g in m.groups() if g), None) if m else None


def check_registration_chronology(manuscript: str) -> list[dict]:
    claims: list[dict] = []
    if not (_PROSPECTIVE_RE.search(manuscript) and _REGISTRY_RE.search(manuscript)):
        return claims
    reg_s = _first_group(_REG_DATE_RE.search(manuscript))
    srch_s = _first_group(_SEARCH_END_RE.search(manuscript))
    if not reg_s or not srch_s:
        return claims
    reg, srch = _parse_date(reg_s), _parse_date(srch_s)
    if not reg or not srch or reg <= srch:
        return claims
    claims.append({
        "claim_id": "registration-chronology",
        "type": "registration",
        "prose_value": f"registered {reg_s.strip()}",
        "artifact_source": f"search completed {srch_s.strip()} (manuscript)",
        "verdict": "REGISTRATION_CHRONOLOGY",
        "detail": (f"a prospective-registration claim, but registration ({reg_s.strip()}) postdates "
                   f"search completion ({srch_s.strip()}) — the review was registered "
                   f"retrospectively; reframe as \"registered with\" or correct the chronology"),
    })
    return claims


MAJOR = {"PRIMARY_REASSIGNED", "EVALUE_ARITHMETIC", "REGISTRATION_CHRONOLOGY"}


def main() -> int:
    ap = argparse.ArgumentParser(description="Claim-vs-artifact cross-check (estimand + E-value).")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--prereg", help="pre-registration / protocol / project.yaml text")
    ap.add_argument("--scripts", help="analysis-scripts directory (reconcile code primary/co-primary labels)")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true", help="exit 1 if any Major verdict")
    args = ap.parse_args()

    mp = Path(args.manuscript)
    if not mp.is_file():
        sys.stderr.write(f"ERROR: manuscript not found: {args.manuscript}\n")
        return 2
    # Collapse hard-wrap newlines to spaces so a sentence-level claim is not split
    # across lines (the decimal points inside HR/E-value figures must survive).
    def _unwrap(t: str) -> str:
        return re.sub(r"\s*\n\s*", " ", t)

    # Strip the YAML front matter before any estimand pattern runs. A project that
    # honestly logs "the primary endpoint was changed ..." in a `changelog:` block was
    # read as a body self-admission and given PRIMARY_REASSIGNED — a Major that fires
    # harder the more openly a project records its own history, which is exactly the
    # Major most likely to get waved through.
    manuscript = _unwrap(strip_frontmatter(mp.read_text(encoding="utf-8")))
    prereg = None
    prereg_raw = None
    if args.prereg:
        pp = Path(args.prereg)
        if pp.is_file():
            prereg_raw = pp.read_text(encoding="utf-8")
            prereg = _unwrap(prereg_raw)
        else:
            sys.stderr.write(f"WARN: prereg not found: {args.prereg} (estimand provenance limited)\n")

    claims = (check_estimand(manuscript, prereg, prereg_raw) + check_evalue(manuscript)
              + check_code_labels(manuscript, args.scripts)
              + check_registration_chronology(manuscript))
    n_major = sum(1 for c in claims if c["verdict"] in MAJOR)
    n_flag = sum(1 for c in claims if c["verdict"] not in MAJOR and c["verdict"] != "OK")

    result = {
        "manuscript": str(mp),
        "prereg": args.prereg,
        "claims": claims,
        "summary": {"n_claims": len(claims), "n_major": n_major, "n_flag": n_flag,
                    "verdict": "MAJOR_CANDIDATE" if n_major else ("REVIEW" if n_flag else "OK")},
    }

    print("=" * 41)
    print(" Claim-vs-Artifact Cross-Check (Phase 2.5f)")
    print("=" * 41)
    for c in claims:
        mark = "✗" if c["verdict"] in MAJOR else ("△" if c["verdict"] != "OK" else "✓")
        print(f"{mark} [{c['claim_id']}] {c['verdict']}")
        print(f"    {c['detail']}")
    print(f"\n{n_major} Major candidate(s), {n_flag} flag(s).")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_claim_artifact", **result}, indent=2), encoding="utf-8")
        print(f"wrote {args.out}")

    return 1 if (args.strict and n_major) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Classical-style body lint (self-review §J / write-paper Phase 7.1).

A senior meta-analysis reviewer reads several surface signals as "AI wrote this"
or as a policy violation. They are all deterministic greps, so they belong in a
gate rather than a prose checklist (manuscript-style-classical.md §5/§6/§7/§8):

  SECTION_SYMBOL        (Major) the § symbol anywhere in the body — the canonical
                        AI tell; also catches "see Methods §2" self-references.
  INBODY_AI_DISCLOSURE  an AI/LLM-use disclosure paragraph in the body. WHERE IT
                        BELONGS IS A JOURNAL FACT, and the journals disagree: npj
                        Digital Medicine says "document use in Methods", Investigative
                        Radiology says cover letter + Acknowledgments, Diabetes &
                        Metabolism Journal says title page. So the placement is read
                        from the target's profile (--profile) or given inline
                        (--disclosure-placement):
                          body-legitimate target (methods / acknowledgements) -> silent
                          title-page / cover-letter-only target -> Major
                          NO target recorded -> Minor, naming the ambiguity rather
                          than asserting a placement it cannot know.
  ELIGIBILITY_PROSE     (Minor) eligibility/inclusion criteria written as a prose
                        sentence rather than a numbered list.
  DECIMAL_INCONSISTENCY (Minor) OR/HR/RR reported with mixed decimal places (some
                        2 dp, some 3 dp) in the same manuscript.
  PERCENT_DECIMALS      (Minor) percentage(s) reported to >1 decimal place ("35.14%").
                        Several journals (e.g. KJR) require one-decimal percentages at
                        technical check; journal-dependent, so report-only.
  EM_DASH_OVERUSE       (Minor) more than 25 *prose* em-dashes — a generation tell.
                        Structural dashes (markdown table cells incl. "—" N/A
                        placeholders and panel-label captions, ORCID separators,
                        author/affiliation lines) are excluded and reported
                        separately, so a cohort manuscript with large baseline
                        tables is not pushed into destructive edits on correct
                        table dashes.

INPUTS
  --manuscript   manuscript markdown/text (required).
  --em-dash-max  em-dash threshold (default 25).

OUTPUT
  A reconciliation table (stdout) and, with --out, a JSON artifact:
    {manuscript, claims[{verdict, severity, detail, where}], summary}
  Exit 1 (with --strict) when any Major-severity claim exists (§ symbol or in-body
  AI disclosure).

Stdlib-only (json / re / argparse / pathlib). Exit codes: 0 clean (or report-only),
1 Major claim(s) found (with --strict), 2 input/usage error.
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

# The § AI-tell is a SECTION CROSS-REFERENCE ("Methods §2", "(see §3.1)", "§L4"),
# not the dagger-family footnote markers (†, ‡, §, ¶) that legitimately mark
# author/affiliation footnotes and co-senior-author lines (e.g. "§ Dr. Hong and
# Dr. Kim are co-senior authors", a superscript "^§"). Count only § that is part
# of a section reference: § followed by a section id (digit, or up to 3 letters
# then a digit — §3, §L4, §S1, §2.1), or a section noun immediately before §.
SECTION_XREF = re.compile(
    r"§\s*[A-Za-z]{0,3}\d"
    r"|(?:see|in|per|section|sections|methods?|results?|discussion|introduction|"
    r"appendix|appendices|supplement(?:ary|al)?|table|figure)\s+§",
    re.IGNORECASE)

INBODY_AI_DISCLOSURE = re.compile(
    r"generative ai was not used|artificial intelligence disclosure|"
    r"during the preparation of (?:this|the) (?:manuscript|work|study)[^.]{0,120}?"
    r"(?:used|use[d]?|employed)[^.]{0,60}?(?:ai|gpt|chatgpt|claude|copilot|gemini|language model)",
    re.IGNORECASE)

# A paper whose SUBJECT is AI-use disclosure (a reporting-methods / QC paper about
# disclosure statements) contains such phrasing as an object of study, not as its
# own disclosure. When the match sits next to disclosure-as-subject framing, do not
# fire INBODY_AI_DISCLOSURE. Kept tight so a genuine in-body disclosure still fires.
AI_DISCLOSURE_SUBJECT = re.compile(
    r"ai[-\s]?disclosure|disclosure (?:statement|practice|policy|policies|requirement|item)|"
    r"reporting of ai (?:use|tools|assistance)|MI[-\s]?CLEAR|"
    r"(?:this|the present) (?:paper|study|work|review|analysis)\b[^.]{0,60}?"
    r"(?:disclosure|ai use|ai tools|ai assistance|reporting)",
    re.IGNORECASE)

ELIGIBILITY_LEAD = re.compile(
    r"(?:studies|articles|records|participants|patients|trials)\s+were\s+eligible\s+if|"
    r"eligibility criteria were|inclusion criteria (?:were|included)|"
    r"(?:studies|articles) were included if",
    re.IGNORECASE)
NUMBERED_MARKER = re.compile(r"\(\s*1\s*\)|\(\s*i\s*\)|(?:^|\s)1\.\s")

EFFECT_DECIMAL = re.compile(
    r"(?:\b(?:a?OR|a?HR|RR|sHR)\b|\bodds ratio\b|\bhazard ratio\b|\brisk ratio\b)"
    r"\s*(?:of|was|were|=|:|,)?\s*(\d+\.(\d+))", re.IGNORECASE)

# A percentage reported to >1 decimal place ("35.14%"). Several journals (e.g. KJR)
# require one-decimal percentages at technical check ("35.1%"). Journal-dependent.
PERCENT_DECIMAL = re.compile(r"\b\d{1,3}\.\d{2,}\s*%")


# Where an AI-use disclosure belongs is set by the target journal, not by house style. A
# profile states it in prose already ("document use in Methods section", "declared on title
# page", "disclosed in cover letter and Acknowledgments"); this reads that line if the profile
# carries the explicit machine-readable form, and otherwise falls back to the prose.
DISCLOSURE_PLACEMENT_LINE = re.compile(
    r"^\s*[-*]?\s*\*{0,2}AI[-\s]use disclosure placement\*{0,2}\s*:\s*(.+)$", re.M | re.I)
# Tokens meaning "the body is where it goes" — if any appears, an in-body paragraph is correct.
# CONVENTION for whoever adds a placement line to a profile: if the journal puts the disclosure
# in the body but names a section none of these words cover — JACC: Advances asks for a
# "Declaration of generative AI …" section immediately above the References — write "(body)"
# in the placement string. Without it the location reads as non-body and the author is told to
# move a paragraph the journal put exactly where it is, which is the failure this whole gate
# exists to stop.
# "acknowledg" is a STEM — a trailing \b breaks on "Acknowledgments"/"Acknowledgements",
# which is exactly how the placement is written in the profiles that use it.
BODY_PLACEMENT = re.compile(r"\b(?:methods?|acknowledg\w*|body|main text)\b", re.I)


def disclosure_placement(profile_text: str | None, inline: str | None) -> str | None:
    """The declared placement string, or None when nothing was recorded."""
    if inline:
        return inline
    if not profile_text:
        return None
    m = DISCLOSURE_PLACEMENT_LINE.search(profile_text)
    return m.group(1).strip() if m else None


def check(text: str, em_dash_max: int, placement: str | None = None) -> list[dict]:
    claims = []

    # SECTION_SYMBOL (Major) — only § used as a section cross-reference, not the
    # dagger-family author/affiliation footnote markers.
    xrefs = list(SECTION_XREF.finditer(text))
    if xrefs:
        n = len(xrefs)
        first = xrefs[0].start()
        claims.append({
            "verdict": "SECTION_SYMBOL",
            "severity": "Major",
            "detail": f"a § section cross-reference appears {n} time(s) — a senior-reviewer "
                      f"AI tell; replace with the section name (manuscript-style-classical §6)",
            "where": text[max(0, first - 30):first + 20].replace("\n", " ").strip()[:120],
        })

    # INBODY_AI_DISCLOSURE (Major) — unless the paper's SUBJECT is AI disclosure
    # (a reporting-methods paper naming the pattern, not committing it).
    m = INBODY_AI_DISCLOSURE.search(text)
    if m and AI_DISCLOSURE_SUBJECT.search(text[max(0, m.start() - 200):m.end() + 200]):
        m = None
    if m:
        # The target decides. Firing "this belongs on the title page" at a journal that
        # requires it in Methods tells the author to move a paragraph the journal wants
        # exactly where it is — and this verdict fired that way across five real projects,
        # none of which could be scored real or spurious without knowing the target.
        if placement and BODY_PLACEMENT.search(placement):
            pass  # the body IS where this journal puts it
        elif placement:
            claims.append({
                "verdict": "INBODY_AI_DISCLOSURE",
                "severity": "Major",
                "detail": (f"an AI/LLM-use disclosure paragraph is in the body, but the target "
                           f"places it in: {placement} (manuscript-style-classical §7)"),
                "where": m.group(0)[:120],
            })
        else:
            claims.append({
                "verdict": "INBODY_AI_DISCLOSURE",
                "severity": "Minor",
                "detail": ("an AI/LLM-use disclosure paragraph is in the body and no target "
                           "journal is recorded — journals disagree (npj Digital Medicine asks "
                           "for Methods, Diabetes & Metabolism Journal for the title page, "
                           "Investigative Radiology for the cover letter and Acknowledgments), "
                           "so pass --profile or --disclosure-placement to settle it"),
                "where": m.group(0)[:120],
            })

    # ELIGIBILITY_PROSE (Minor)
    em = ELIGIBILITY_LEAD.search(text)
    if em and not NUMBERED_MARKER.search(text[em.start():em.start() + 320]):
        claims.append({
            "verdict": "ELIGIBILITY_PROSE",
            "severity": "Minor",
            "detail": "eligibility/inclusion criteria are written as prose; senior reviewers "
                      "expect a numbered list (1)…(2)…(3) (manuscript-style-classical §5)",
            "where": em.group(0)[:120],
        })

    # DECIMAL_INCONSISTENCY (Minor)
    dps = {len(mm.group(2)) for mm in EFFECT_DECIMAL.finditer(text)}
    if len(dps) > 1:
        claims.append({
            "verdict": "DECIMAL_INCONSISTENCY",
            "severity": "Minor",
            "detail": f"OR/HR/RR reported with mixed decimal places ({sorted(dps)}); "
                      f"standardize (OR/HR to 2 dp)",
            "where": "effect-size decimals",
        })

    # PERCENT_DECIMALS (Minor) — percentages to >1 decimal place. Several journals
    # (e.g. KJR) require one-decimal percentages at technical check ("35.1%" not
    # "35.14%"); journal-dependent, so report-only (Minor, does not fail --strict).
    pcts = [mm.group(0).strip() for mm in PERCENT_DECIMAL.finditer(text)]
    if pcts:
        ex = ", ".join(dict.fromkeys(pcts))  # dedup, keep order
        claims.append({
            "verdict": "PERCENT_DECIMALS",
            "severity": "Minor",
            "detail": f"{len(pcts)} percentage(s) reported to >1 decimal place "
                      f"(e.g. {ex[:80]}); several journals require one decimal at "
                      f"technical check (35.1% not 35.14%)",
            "where": "percentage decimals",
        })

    # EM_DASH_OVERUSE (Minor) — count PROSE em-dashes only. Structural dashes are
    # legitimate, not a generation tell: markdown table cells (incl. "—" = N/A
    # placeholders and "(A) — label" panel captions), ORCID separators, and
    # author/affiliation lines ("Name, MD — Department of …"). Counting them forces
    # destructive edits on correct table dashes in cohort manuscripts with large
    # Table 1 / Table 3.
    prose_dash, structural_dash = _count_em_dashes(text)
    if prose_dash > em_dash_max:
        claims.append({
            "verdict": "EM_DASH_OVERUSE",
            "severity": "Minor",
            "detail": f"{prose_dash} prose em-dashes (> {em_dash_max}); a generation tell — "
                      f"replace some with commas/colons or split sentences "
                      f"({structural_dash} structural em-dashes in tables/ORCID/affiliation "
                      f"lines were excluded)",
            "where": f"{prose_dash} prose em-dashes ({structural_dash} structural excluded)",
        })

    return claims


_ORCID_RE = re.compile(r"\d{4}-\d{4}-\d{4}-\d{3}[\dXx]")
# A credential token immediately before the dash, or an affiliation noun right
# after it — the "Name, MD — Department of …" author/affiliation signature.
_AFFIL_DASH_RE = re.compile(
    r"\b(?:MD|PhD|MSc|MPH|MBBS|DO|DrPH|RN)\b[^—|]{0,20}—"
    r"|—[^—|]{0,20}\b(?:Department|Division|Institute|Faculty|College|University|Hospital|Center|Centre)\b",
    re.IGNORECASE)
# Figure/table/panel caption lines ("(A) — obesity stratum", "Figure 1. …",
# "*(A) S1 — …*") — structural, not prose.
_CAPTION_RE = re.compile(
    r"^\s*\*{0,2}(?:\(?[A-Za-z]\)|(?:Figure|Fig\.?|Table|Panel|Supplementary)\b)", re.IGNORECASE)


def _count_em_dashes(text: str) -> tuple[int, int]:
    """Return (prose, structural) em-dash counts. Structural = table rows, ORCID /
    affiliation / author lines, and standalone-cell dashes; prose = everything else
    (the genuine generation-tell surface)."""
    prose = structural = 0
    for line in text.splitlines():
        n = line.count("—")
        if not n:
            continue
        s = line.strip()
        is_table = "|" in line
        is_orcid = "orcid" in line.lower() or bool(_ORCID_RE.search(line))
        is_standalone = bool(re.fullmatch(r"[-–—\s]*", s))
        is_affil = bool(_AFFIL_DASH_RE.search(line))
        is_caption = bool(_CAPTION_RE.match(line))
        if is_table or is_orcid or is_standalone or is_affil or is_caption:
            structural += n
        else:
            prose += n
    return prose, structural


def analyze(manuscript: str, em_dash_max: int, placement: str | None = None) -> dict:
    p = Path(manuscript)
    if not p.is_file():
        sys.stderr.write(f"ERROR: manuscript not found: {manuscript}\n")
        sys.exit(2)
    claims = check(p.read_text(encoding="utf-8"), em_dash_max, placement)
    n_major = sum(1 for c in claims if c["severity"] == "Major")
    return {
        "manuscript": str(p),
        "disclosure_placement": placement,
        "claims": claims,
        "summary": {
            "n_claims": len(claims),
            "n_major": n_major,
            "n_flag": len(claims) - n_major,
            "verdict": "MAJOR_CANDIDATE" if n_major else ("FLAG" if claims else "OK"),
        },
    }


def render(result: dict) -> str:
    lines = ["| Check | Severity | Detail |", "|---|---|---|"]
    for c in result["claims"]:
        lines.append(f"| {c['verdict']} | {c['severity']} | {c['detail']} |")
    if len(lines) == 2:
        lines.append("| (none) | — | classical-style body conventions satisfied |")
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(description="Classical-style body lint (§J).")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--em-dash-max", type=int, default=25, help="em-dash threshold (default 25)")
    ap.add_argument("--profile", help="target journal profile .md (for AI-disclosure placement)")
    ap.add_argument("--disclosure-placement",
                    help="where the target puts an AI-use disclosure, e.g. 'Methods' or "
                         "'title page' — overrides --profile")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true", help="exit 1 if any Major claim exists")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    args = ap.parse_args()

    profile_text = None
    if args.profile:
        pp = Path(args.profile)
        if not pp.is_file():
            sys.stderr.write(f"ERROR: profile not found: {args.profile}\n")
            return 2
        profile_text = pp.read_text(encoding="utf-8", errors="replace")
    placement = disclosure_placement(profile_text, args.disclosure_placement)
    result = analyze(args.manuscript, args.em_dash_max, placement)

    if not args.quiet:
        print("=" * 41)
        print(" Classical-Style Body Lint (§J)")
        print("=" * 41)
        print(render(result))
        print()
        s = result["summary"]
        if s["n_major"]:
            print(f"MAJOR candidate: {s['n_major']} policy/AI-tell violation(s).")
        elif s["n_flag"]:
            print(f"FLAG: {s['n_flag']} style inconsistency(ies).")
        else:
            print("OK: classical-style body conventions satisfied.")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_classical_style", **result}, indent=2), encoding="utf-8")
        if not args.quiet:
            print(f"\nwrote {args.out}")

    return 1 if (args.strict and result["summary"]["n_major"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Cohort arithmetic gate for observational studies (self-review Phase 2.5 / 2.5b).

Phase 2.5 covers n/N percentage arithmetic and Phase 2.5b reconciles SR/MA
study counts from ID sets. Neither covers the cohort-specific arithmetic that a
reviewer recomputes by hand and that survives a single prose pass because every
section echoes the same wrong number:

  1. RATE_BACKCALC     a reported incidence rate must invert to its own
                       numerator/denominator: rate ~= events / person-years * scale.
                       An impossible rate (more implied events than person-time, or
                       a rate that does not recompute from the stated events and PY)
                       is the failure mode where "X per 1,000 person-years" was
                       transcribed or computed wrong.
  2. CASCADE_SUM       a STROBE exclusion cascade must balance: start - sum(excluded)
                       == final analytic N; and a complete-case statement must
                       balance: total - missing == complete. A footnote that says
                       3,667 where 4,252 - 583 = 3,669 is this finding.
  3. PARTITION_OVERLAP an ordinal tier/stratum partition that is presented as
                       mutually exclusive must satisfy sum(stratum N) == unique
                       total and sum(stratum events) == total events. A tier split
                       whose denominators sum above the unique cohort double-counts
                       subjects; a table where every stratum n equals the grand
                       total is a stratum-total mis-entry. This also fires on an
                       in-text PROSE enumeration presented as an exhaustive split
                       of a stated total (>=3 "count (pct%)" categories with
                       partition-cue language, e.g. "of the 289 cases, 37 (12.8%)
                       ... 185 (64.0%) ... 103 (35.6%) ...") when the counts do not
                       sum to the total or the percentages do not sum to ~100% --
                       the sign that a non-exclusive component was mixed among the
                       mutually exclusive categories. The partition-cue gate keeps
                       it off legitimate overlapping-attribute prose (comorbidity
                       prevalence).
  4. ANALYSIS_UNIT_   when --data carries a subject ID and records > unique
     UNDISCLOSED       subjects (health-screening / EMR / registry repeat
                       attendees), observations are non-independent -> anti-
                       conservative CIs. Fires only when the manuscript discloses
                       neither the analysis unit nor a one-record-per-subject
                       sensitivity. Pass --id-col, or it auto-detects a common ID
                       column name (with a cardinality guard).

The script is deterministic but conservative: it fires only when it can extract a
complete equation (all operands present in one window, or a Total row in a parsed
table, or recomputable columns in --data). Read the reconciliation table; a missed
case is safer than a false Major on a widely-used gate.

INPUTS
  --manuscript  manuscript markdown/text (required). Prose equations + GFM tables
                are parsed from it.
  --data        optional CSV for exact recompute. Auto-detected columns:
                  events / event / n_events / cases
                  person_years / py / person-years / personyears
                  rate / ir / incidence_rate          (RATE_BACKCALC)
                  stratum / tier / group + n / count + (events)  (PARTITION_OVERLAP)
                A row whose label normalizes to total/overall is the marginal.

OUTPUT
  A reconciliation table (stdout) and, with --out, a JSON artifact:
    {manuscript, data, claims[{verdict, severity, detail, where}], summary}
  verdicts RATE_BACKCALC / CASCADE_SUM / PARTITION_OVERLAP are Major candidates;
  FOLLOWUP_VS_CRITERION, SUBGROUP_DUPLICATE_CI (the same subgroup rendered twice in one
  table with divergent confidence intervals) and NESTED_MODEL_NO_BASELINE (nested
  discrimination models sharing a covariate set with no base-model row / ΔC) are Minor.
  Exit 1 (with --strict) when any Major-severity claim exists.

Stdlib-only (csv / json / re / argparse). Exit codes: 0 clean (or report-only),
1 Major claim(s) found (with --strict), 2 input/usage error.
"""

from __future__ import annotations

import argparse
import csv
import json
import re
import sys
from pathlib import Path

# Relative tolerance for a rate to "recompute" from events/PY (covers rounding of
# the displayed rate and of the inputs). 5% is generous; a real impossible rate
# misses it by far more.
RATE_REL_TOL = 0.05
SCALE_WORDS = {"100": 100, "1,000": 1000, "1000": 1000, "10,000": 10000, "10000": 10000,
               "100,000": 100000, "100000": 100000}

TOTAL_LABELS = ("total", "overall", "all", "whole cohort", "entire cohort", "full cohort",
                "all participants", "all subjects", "all patients")


# --- number / column helpers ----------------------------------------------

def _num(s: str):
    """Parse '1,234' / '1234' / '3.5' -> float, else None."""
    if s is None:
        return None
    m = re.search(r"-?\d[\d,]*\.?\d*", s.strip())
    if not m:
        return None
    try:
        return float(m.group(0).replace(",", ""))
    except ValueError:
        return None


def _ints_in(text: str) -> list[int]:
    """All comma-grouped integers in a span, as ints (drops decimals/percent)."""
    out = []
    for m in re.finditer(r"\d[\d,]*(?!\.\d)", text):
        try:
            out.append(int(m.group(0).replace(",", "")))
        except ValueError:
            pass
    return out


def _norm(s: str) -> str:
    s = s.lower()
    s = re.sub(r"\(.*?\)", " ", s)
    s = re.sub(r"[^a-z0-9 ]+", " ", s)
    return re.sub(r"\s+", " ", s).strip()


def _is_total_label(label: str) -> bool:
    n = _norm(label)
    return any(n == t or n.startswith(t + " ") or n == t.replace(" ", "") for t in TOTAL_LABELS)


# A hint shorter than this is matched only exactly — never as a substring.
MIN_SUBSTRING_HINT = 3


def _pick(header: list[str], hints: tuple[str, ...]):
    norm = [_norm(h) for h in header]
    for hint in hints:
        h = _norm(hint)
        for i, col in enumerate(norm):
            if col == h and h:
                return i
    # Substring fallback, with the guard the exact pass does not need. A hint of one or two
    # characters has no business matching a longer word: the hint "n" found "Normal" in the
    # header of an exposure-stratified Table 1, so every characteristic row's Normal-column
    # value was summed as if it were a stratum size (8,299 "strata" against a "total" of 194).
    # The same one-character-substring bug was fixed once in check_confounding_completeness
    # and never here. Longer hints still match, but only on a word boundary.
    for hint in hints:
        h = _norm(hint)
        if len(h) < MIN_SUBSTRING_HINT:
            continue
        for i, col in enumerate(norm):
            if col and re.search(rf"(?<![a-z0-9]){re.escape(h)}(?![a-z0-9])", col):
                return i
    return None


# --- Check 1: RATE_BACKCALC ------------------------------------------------

RATE_LINE_RE = re.compile(
    r"([0-9][0-9,]*\.?[0-9]*)\s*(?:per|/)\s*([0-9][0-9,]*)\s*person[-\s]?years?", re.I)
# The numerator must be a count glued to a count noun (events/cases), optionally
# "N incident cases/events". Two guards against grabbing the wrong integer:
#   (a) lookbehind (?<![A-Za-z0-9.]) so a tier label's digit ("T1") or a decimal's
#       fractional part ("0.97") is never captured as the numerator;
#   (b) drop the bare "incident" alternative, which matched the word in "incident
#       rate" and bound the nearest stray small integer (the false-positive source).
#   (c) a HYPHEN or slash before the digit means it belongs to a label, not to the count:
#       "882 KSAR S4-1 events occurred" bound the 1 of "S4-1" and reported the rate as
#       irreconcilable with 1 event. When the count cannot be bound the check must say
#       nothing — an unbindable numerator is not evidence of an arithmetic error.
EVENTS_NEAR_RE = re.compile(
    r"(?<![A-Za-z0-9.\-\u2013\u2014/])([0-9][0-9,]*)\s*(?:incident\s+)?(?:events?|cases?)\b", re.I)
# Person-time is frequently reported to one decimal ("35,581.3 person-years"). Without the
# decimal branch the integer part failed to reach the noun and the FRACTIONAL DIGIT matched
# instead — a cohort of "3 person-years" — so the same lookbehind applies here.
PY_NEAR_RE = re.compile(
    r"(?<![A-Za-z0-9.\-\u2013\u2014/])([0-9][0-9,]*(?:\.[0-9]+)?)\s*(?:person[-\s]?years?|py\b)", re.I)


def _sentences(text: str) -> list[str]:
    """Split into sentences after flattening intra-paragraph line wraps, so a
    sentence that the source wrapped across lines is still one unit. Markdown
    table rows (pipe-delimited) are kept as their own units."""
    units = []
    for para in re.split(r"\n[ \t]*\n", text):
        if para.lstrip().startswith("|"):
            units.extend(para.splitlines())
            continue
        flat = re.sub(r"\s*\n\s*", " ", para).strip()
        units.extend(re.split(r"(?<=[.;])\s+", flat))
    return [u for u in units if u.strip()]


def check_rate_text(text: str) -> list[dict]:
    """Fire when a single sentence carries a rate, an event count, and a
    person-time, and the rate does not recompute from them."""
    claims = []
    for line in _sentences(text):
        rm = RATE_LINE_RE.search(line)
        if not rm:
            continue
        rate = _num(rm.group(1))
        scale = _num(rm.group(2))
        if rate is None or not scale:
            continue
        em = EVENTS_NEAR_RE.search(line)
        # the PY in "rate per <scale> person-years" is the scale, not the cohort PY;
        # the cohort PY is a *different*, larger person-time figure in the same span.
        py_candidates = [float(g.replace(",", "")) for g in PY_NEAR_RE.findall(line)]
        py_candidates = [p for p in py_candidates if abs(p - scale) > 1e-9]
        if not em or not py_candidates:
            continue
        events = _num(em.group(1))
        py = max(py_candidates)  # cohort person-time is the larger figure
        if events is None or py <= 0:
            continue
        expected = events / py * scale
        if expected <= 0:
            continue
        if abs(rate - expected) / max(expected, 1e-9) > RATE_REL_TOL:
            claims.append({
                "verdict": "RATE_BACKCALC",
                "severity": "Major",
                "detail": (f"reported rate {rate:g} per {int(scale):,} PY does not recompute "
                           f"from {int(events):,} events / {py:,.6g} PY "
                           f"(= {expected:.4g} per {int(scale):,})"),
                "where": line.strip()[:160],
            })
    return claims


def check_rate_csv(rows: list[dict]) -> list[dict]:
    claims = []
    if not rows:
        return claims
    header = list(rows[0].keys())
    ei = _pick(header, ("events", "event", "n_events", "cases", "n_cases"))
    pi = _pick(header, ("person_years", "person-years", "personyears", "py", "person years"))
    ri = _pick(header, ("rate", "ir", "incidence_rate", "incidence rate"))
    si = _pick(header, ("scale", "per", "rate_per"))
    if ei is None or pi is None or ri is None:
        return claims
    cols = list(header)
    for idx, row in enumerate(rows):
        events = _num(row[cols[ei]])
        py = _num(row[cols[pi]])
        rate = _num(row[cols[ri]])
        scale = _num(row[cols[si]]) if si is not None else 1000.0
        if None in (events, py, rate) or not scale or py <= 0:
            continue
        expected = events / py * scale
        if expected <= 0:
            continue
        if abs(rate - expected) / max(expected, 1e-9) > RATE_REL_TOL:
            claims.append({
                "verdict": "RATE_BACKCALC",
                "severity": "Major",
                "detail": (f"row {idx + 1}: rate {rate:g} per {int(scale):,} PY != "
                           f"{events:g}/{py:g}*{int(scale):,} = {expected:.4g}"),
                "where": f"--data row {idx + 1}",
            })
    return claims


# --- Check 2: CASCADE_SUM --------------------------------------------------

COMPLETE_CASE_RE = re.compile(
    r"\b(?:of|among|from)\s+([0-9][0-9,]{2,})\b.{0,80}?"
    r"\b([0-9][0-9,]{1,})\s*(?:had|were|with)?\s*"
    r"(?:missing|incomplete|excluded|without)\b.{0,80}?"
    r"\b(?:leaving|remaining|resulting in|yielded?|left|final(?:ly)?|analyti\w+|included)\D{0,20}"
    r"([0-9][0-9,]{2,})\b",
    re.I | re.S)

START_RE = re.compile(
    r"\b([0-9][0-9,]{2,})\b\s*(?:participants?|subjects?|patients?|individuals?|records?)?\s*"
    r"(?:were\s+)?(?:initially\s+)?(?:screened|assessed|identified|enrolled|eligible|"
    r"recruited|included for screening)", re.I)
EXCLUDED_RE = re.compile(
    r"(?:excluded|removed)\D{0,20}?([0-9][0-9,]{1,})\b"
    r"|\b([0-9][0-9,]{1,})\s*(?:were\s+)?(?:excluded|removed)", re.I)
FINAL_RE = re.compile(
    r"\b(?:final|analytic|included|remaining)\D{0,30}?([0-9][0-9,]{2,})\b"
    r"|\b([0-9][0-9,]{2,})\b\D{0,20}(?:were included|comprised the (?:final|analytic)|"
    r"in the (?:final|analytic))", re.I)


def check_cascade_text(text: str) -> list[dict]:
    claims = []
    # (a) complete-case: total - missing == complete
    for m in COMPLETE_CASE_RE.finditer(text):
        total, missing, complete = (_num(m.group(1)), _num(m.group(2)), _num(m.group(3)))
        if None in (total, missing, complete):
            continue
        if abs((total - missing) - complete) >= 1:  # off by >= 1 (not rounding)
            claims.append({
                "verdict": "CASCADE_SUM",
                "severity": "Major",
                "detail": (f"complete-case arithmetic: {int(total):,} - {int(missing):,} = "
                           f"{int(total - missing):,}, but text states {int(complete):,}"),
                "where": m.group(0).strip()[:160],
            })
    # (b) exclusion cascade: start - sum(excluded) == final (within a flow window)
    sm = START_RE.search(text)
    fm = FINAL_RE.search(text)
    if sm and fm and fm.start() > sm.start():
        window = text[sm.start():fm.end()]
        start = _num(sm.group(1))
        final = next((_num(g) for g in fm.groups() if g), None)
        excluded = []
        for em in EXCLUDED_RE.finditer(window):
            v = next((g for g in em.groups() if g), None)
            if v:
                excluded.append(int(v.replace(",", "")))
        if start is not None and final is not None and excluded:
            if abs((start - sum(excluded)) - final) >= 1:
                claims.append({
                    "verdict": "CASCADE_SUM",
                    "severity": "Major",
                    "detail": (f"exclusion cascade: {int(start):,} - "
                               f"({' + '.join(f'{e:,}' for e in excluded)}) = "
                               f"{int(start - sum(excluded)):,}, but final stated {int(final):,}"),
                    "where": "study-population flow",
                })
    return claims


# --- Check 3: PARTITION_OVERLAP --------------------------------------------

def _parse_md_tables(text: str) -> list[list[list[str]]]:
    """Return GFM tables as lists of cell-rows (header + body, separator dropped)."""
    tables, cur = [], []
    for line in text.splitlines():
        if line.lstrip().startswith("|") and line.count("|") >= 2:
            cells = [c.strip() for c in line.strip().strip("|").split("|")]
            if all(re.fullmatch(r":?-{2,}:?", c) or c == "" for c in cells) and cur:
                continue  # separator row
            cur.append(cells)
        else:
            if len(cur) >= 2:
                tables.append(cur)
            cur = []
    if len(cur) >= 2:
        tables.append(cur)
    return tables


def _partition_from_rows(label_of, n_of, ev_of, rows, source: str) -> list[dict]:
    claims = []
    body, total_row = [], None
    for r in rows:
        if _is_total_label(label_of(r)):
            total_row = r
        else:
            body.append(r)
    ns = [n_of(r) for r in body]
    ns = [x for x in ns if x is not None]
    if len(ns) < 2:
        return claims
    # all-equal-to-total mis-entry
    if total_row is not None:
        tot_n = n_of(total_row)
        if tot_n is not None and all(abs(x - tot_n) < 1 for x in ns):
            claims.append({
                "verdict": "PARTITION_OVERLAP",
                "severity": "Major",
                "detail": (f"every stratum n equals the grand total ({int(tot_n):,}) — "
                           f"stratum-total mis-entry, not a partition"),
                "where": source,
            })
            return claims
        if tot_n is not None and abs(sum(ns) - tot_n) >= 1:
            claims.append({
                "verdict": "PARTITION_OVERLAP",
                "severity": "Major",
                "detail": (f"stratum N sum to {int(sum(ns)):,} but the stated total is "
                           f"{int(tot_n):,} (difference {int(sum(ns) - tot_n):+,}) — "
                           f"non-disjoint strata or a missing/extra row"),
                "where": source,
            })
        # events partition
        evs = [ev_of(r) for r in body]
        evs = [x for x in evs if x is not None]
        tot_ev = ev_of(total_row)
        if len(evs) >= 2 and tot_ev is not None and abs(sum(evs) - tot_ev) >= 1:
            claims.append({
                "verdict": "PARTITION_OVERLAP",
                "severity": "Major",
                "detail": (f"stratum events sum to {int(sum(evs)):,} but total events "
                           f"stated {int(tot_ev):,}"),
                "where": source,
            })
    return claims


def check_partition_md(text: str) -> list[dict]:
    claims = []
    for tbl in _parse_md_tables(text):
        header = tbl[0]
        ni = _pick(header, ("n", "count", "number", "no", "denominator", "subjects", "patients"))
        ei = _pick(header, ("events", "event", "cases", "outcomes", "incident"))
        if ni is None:
            continue
        li = 0  # first column is the stratum label by convention
        if ni == li:
            li = 1 if len(header) > 1 else 0

        def label_of(r, li=li):
            return r[li] if li < len(r) else ""

        def n_of(r, ni=ni):
            return _num(r[ni]) if ni < len(r) else None

        def ev_of(r, ei=ei):
            return _num(r[ei]) if (ei is not None and ei < len(r)) else None

        claims += _partition_from_rows(label_of, n_of, ev_of, tbl[1:],
                                       source=f"table[{' | '.join(header)[:60]}]")
    return claims


def check_partition_csv(rows: list[dict]) -> list[dict]:
    if not rows:
        return []
    header = list(rows[0].keys())
    li = _pick(header, ("stratum", "tier", "group", "category", "level", "label"))
    ni = _pick(header, ("n", "count", "number", "denominator", "subjects", "patients"))
    ei = _pick(header, ("events", "event", "cases", "outcomes"))
    if li is None or ni is None:
        return []
    cols = list(header)

    def label_of(r):
        return r[cols[li]]

    def n_of(r):
        return _num(r[cols[ni]])

    def ev_of(r):
        return _num(r[cols[ei]]) if ei is not None else None

    return _partition_from_rows(label_of, n_of, ev_of, rows, source="--data partition")


# Prose partition: an in-text enumeration presented as an exhaustive split of a
# stated total. A sentence that decomposes N into >=3 "count (pct%)" categories
# with partition-cue language, but whose counts do not sum to N (or whose
# percentages do not sum to ~100), has mixed a non-exclusive component in among
# mutually exclusive categories -- a "these don't add to N" reviewer flag. The
# partition-cue gate is what keeps this off legitimate overlapping-attribute prose
# ("210 (72.7%) had hypertension, 140 (48.4%) had diabetes, ..."): comorbidity
# prevalence is not a partition, and its counts legitimately sum above N.
_PART_CUE_RE = re.compile(
    r"\b(?:decomposed|broke\s+down|broken\s+down|breakdown|comprised|"
    r"consist(?:ed|ing)\s+of|partitioned|categori[sz]ed|classified|of\s+which|"
    r"identified\s+(?:by|as|through)|attributable\s+to|ascertained\s+(?:by|through|via)|"
    r"accounted\s+for|respectively)\b", re.I)
_PART_TOTAL_RE = re.compile(
    r"\b(?:among|of|the|these|totall?ing)\s+(?:the\s+)?([0-9][0-9,]{2,})\s+"
    r"(?:incident\s+|total\s+|remaining\s+|eligible\s+|included\s+)?"
    r"(?:cases|patients|subjects|participants|individuals|events|records|women|men|"
    r"children|deaths|lesions|nodules|tumou?rs|samples|episodes|visits)\b", re.I)
_PART_CAT_RE = re.compile(r"\b([0-9][0-9,]{0,})\s*\(\s*([0-9]+(?:\.[0-9]+)?)\s*%\s*\)")
_SENT_SPLIT_RE = re.compile(r"(?<=[.!?])\s+(?=[A-Z(\"'])")
# Bound the scan to a paragraph so an enumeration cannot accrue counts across a
# blank line or a markdown header (a partition claim lives in one sentence).
_BLOCK_SPLIT_RE = re.compile(r"\n\s*\n|\n#{1,6}\s")


def _iter_partition_sentences(text: str):
    for block in _BLOCK_SPLIT_RE.split(text):
        for sent in _SENT_SPLIT_RE.split(block):
            yield sent


def check_partition_text(text: str) -> list[dict]:
    claims = []
    for sent in _iter_partition_sentences(text):
        tm = _PART_TOTAL_RE.search(sent)
        if not tm:
            continue
        cats = _PART_CAT_RE.findall(sent)
        if len(cats) < 3:
            continue
        if not _PART_CUE_RE.search(sent):
            continue  # cue gate: only an exhaustive-split claim, never overlapping attributes
        total = _num(tm.group(1))
        counts = [_num(c) for c, _ in cats]
        if total is None or any(c is None for c in counts):
            continue
        sum_c = sum(counts)
        sum_p = sum(float(p) for _, p in cats)
        if abs(sum_c - total) >= 1:
            claims.append({
                "verdict": "PARTITION_OVERLAP",
                "severity": "Major",
                "detail": (f"enumerated counts sum to {int(sum_c):,} but the stated total is "
                           f"{int(total):,} (difference {int(sum_c - total):+,}); a non-exclusive "
                           f"component may be mixed among the mutually exclusive categories"),
                "where": sent.strip()[:160],
            })
        elif not (99.0 <= sum_p <= 101.0):
            claims.append({
                "verdict": "PARTITION_OVERLAP",
                "severity": "Major",
                "detail": (f"category percentages sum to {sum_p:.1f}% (expected ~100%) for an "
                           f"exhaustive split of {int(total):,}; a non-exclusive component may be "
                           f"mixed among the mutually exclusive categories"),
                "where": sent.strip()[:160],
            })
    return claims


# --- Check: FOLLOWUP_VS_CRITERION ------------------------------------------
# A reported "median follow-up was 102 days" against a reference standard that
# requires "size stability for >=24 months" reads, to a reviewer, as if the
# benign classification had 102 days to work with. Usually the 102 days is the
# index-visit interval and the total observation window (median 442 days) is
# simply never stated. Pure arithmetic: if the shortest reported follow-up is
# below the longest duration threshold the outcome/reference standard requires,
# and no total-observation window is labelled, ask which quantity is reported.
_DUR_UNIT_DAYS = {"day": 1.0, "week": 7.0, "month": 30.44, "year": 365.25}
_FOLLOWUP_RE = re.compile(
    r"(?:median|mean)\s+follow[-\s]?up[^.]{0,40}?(\d[\d,]*(?:\.\d+)?)\s*(day|week|month|year)s?", re.I)
_CRITERION_CUE = re.compile(
    r"stabilit|stable|reference standard|benign if|confirmed by|criterion|classified as|"
    r"resolution over|no growth for|unchanged for|followed for", re.I)
_CRITERION_DUR_RE = re.compile(
    r"(?:>=|≥|at least|minimum of|for|over)\s*(\d+)\s*(day|week|month|year)s?", re.I)
_TOTAL_WINDOW_RE = re.compile(
    r"total observation|observation period|overall follow[-\s]?up|maximum follow[-\s]?up|"
    r"observed for a (?:median|maximum) of|total follow[-\s]?up", re.I)


def check_followup_criterion(text: str) -> list[dict]:
    fu = [(_num(v) or 0) * _DUR_UNIT_DAYS[u.lower()]
          for v, u in _FOLLOWUP_RE.findall(text)]
    fu = [d for d in fu if d > 0]
    if not fu:
        return []
    # criterion thresholds: a duration inside a reference-standard/outcome cue window
    crit = []
    for m in _CRITERION_DUR_RE.finditer(text):
        win = text[max(0, m.start() - 120):m.end() + 40]
        if _CRITERION_CUE.search(win):
            crit.append(int(m.group(1)) * _DUR_UNIT_DAYS[m.group(2).lower()])
    if not crit:
        return []
    min_fu, max_crit = min(fu), max(crit)
    if min_fu >= max_crit:
        return []
    if _TOTAL_WINDOW_RE.search(text):
        return []  # a distinctly-labelled total-observation window is already reported
    return [{
        "verdict": "FOLLOWUP_VS_CRITERION",
        "severity": "Minor",
        "detail": (f"the shortest reported follow-up ({min_fu / 30.44:.1f} months / {min_fu:.0f} days) "
                   f"is below a {max_crit / 30.44:.0f}-month duration criterion in the outcome/reference "
                   f"standard, and no total-observation window is reported — state whether the reported "
                   f"follow-up is the index-visit interval or the total observation, and give the latter"),
        "where": (_FOLLOWUP_RE.search(text).group(0)[:120] if _FOLLOWUP_RE.search(text) else "follow-up"),
    }]


# --- Check 4: ANALYSIS_UNIT_UNDISCLOSED ------------------------------------
# Health-screening / EMR / registry cohorts routinely have repeat attendees, so a
# record count is not a subject count. When the data carry a subject ID and
# records > subjects, non-independent observations give anti-conservative CIs. The
# finding is the *undisclosed* gap: fire only when the manuscript neither states
# the analysis unit nor reports a one-record-per-subject sensitivity.

# Safelist of normalized ID column names for auto-detection (tight, to avoid
# mistaking a low-cardinality flag like "valid" for an identifier). Explicit
# --id-col bypasses both the safelist and the cardinality guard.
ID_NAME_SAFELIST = {
    "id", "mockid", "mock id", "subjectid", "subject id", "patientid", "patient id",
    "personid", "person id", "recordid", "record id", "studyid", "study id",
    "pid", "eid", "uid", "mrn",
}

UNIT_STATED_RE = re.compile(
    r"one record per subject|per[-\s]subject|per subject|analysis unit|analytic unit|"
    r"screening encounter|one observation per (?:subject|participant|person)|"
    r"one row per (?:subject|participant|person)|first (?:qualifying )?(?:visit|encounter)",
    re.IGNORECASE)
SENSITIVITY_STATED_RE = re.compile(
    r"first[-\s](?:visit|encounter)|one[-\s]record[-\s]per[-\s]subject|de[-\s]?duplicat|"
    r"unique (?:subject|participant|individual)s?|repeat (?:attendee|visit|screen)|"
    r"sensitivity analysis[^.]{0,80}(?:subject|visit|first|repeat)",
    re.IGNORECASE)


def _detect_id_col(header: list[str], rows: list[dict], explicit: str | None) -> str | None:
    if explicit:
        for h in header:
            if _norm(h) == _norm(explicit) or h == explicit:
                return h
        sys.stderr.write(f"WARN: --id-col '{explicit}' not found in {header}\n")
        return None
    n = len(rows)
    for h in header:
        if _norm(h) in ID_NAME_SAFELIST:
            distinct = len({(r.get(h) or "").strip() for r in rows})
            if n and distinct >= 0.5 * n:   # subject-level, not a low-cardinality flag
                return h
    return None


def check_analysis_unit(rows: list[dict], text: str, id_col: str | None) -> list[dict]:
    if not rows:
        return []
    header = list(rows[0].keys())
    col = _detect_id_col(header, rows, id_col)
    if not col:
        return []
    ids = [(r.get(col) or "").strip() for r in rows]
    ids = [i for i in ids if i]
    nrow = len(ids)
    counts: dict[str, int] = {}
    for i in ids:
        counts[i] = counts.get(i, 0) + 1
    subjects = len(counts)
    if nrow <= subjects:
        return []                                   # already one record per subject
    if UNIT_STATED_RE.search(text) or SENSITIVITY_STATED_RE.search(text):
        return []                                   # disclosed -> not a finding
    repeats = sum(1 for c in counts.values() if c > 1)
    max_visits = max(counts.values())
    return [{
        "verdict": "ANALYSIS_UNIT_UNDISCLOSED",
        "severity": "Major",
        "detail": (f"records={nrow:,}, unique_subjects={subjects:,}, "
                   f"repeat_subjects={repeats:,}, max_visits={max_visits} "
                   f"(id column '{col}'); the manuscript states neither the analysis "
                   f"unit nor a one-record-per-subject sensitivity, so non-independent "
                   f"observations give anti-conservative CIs"),
        "where": f"--data id column '{col}'",
    }]


# --- driver ----------------------------------------------------------------

def load_csv(path: str) -> list[dict]:
    p = Path(path)
    if not p.is_file():
        sys.stderr.write(f"ERROR: --data not found: {path}\n")
        sys.exit(2)
    with p.open(encoding="utf-8-sig", newline="") as f:
        return [r for r in csv.DictReader(f)]


# Effect estimate with a bracketed CI: "4.95 (4.32-5.94)" / "4.95 [4.32 to 5.94]".
_EFFECT_CI_RE = re.compile(
    r"(?P<pt>\d+(?:\.\d+)?)\s*[\(\[]\s*"
    r"(?P<lo>\d+(?:\.\d+)?)\s*(?:[-–—]|to|,)\s*(?P<hi>\d+(?:\.\d+)?)\s*[\)\]]"
)


def check_duplicate_subgroup_ci(text: str) -> list[dict]:
    """Within one GFM table, two rows that share the SAME effect estimate AND the same
    identity counts (n / events) but print DIFFERENT confidence intervals are the same
    subgroup rendered twice (relabeled) with independently-resampled uncertainty — a
    reviewer asks why one group has two intervals. High precision by construction: it
    requires the non-effect integer cells (n, events) to be IDENTICAL between the rows,
    so two genuinely distinct subgroups with a coincidentally-equal point estimate do
    not fire; a table with no count columns is left alone."""
    claims: list[dict] = []
    for tbl in _parse_md_tables(text):
        if len(tbl) < 3:            # header + at least two body rows
            continue
        groups: dict = {}
        for row in tbl[1:]:
            eff = eff_idx = None
            for ci, cell in enumerate(row):
                m = _EFFECT_CI_RE.search(cell)
                if m:
                    eff, eff_idx = m, ci
                    break
            if eff is None:
                continue
            # Identity = the count columns (n / events), NOT the label (col 0, which is
            # exactly what differs between the two relabeled rows) and NOT the effect+CI
            # cell. _ints_in already drops decimals, so CI bounds / p-values / percents
            # do not enter the identity.
            ids: list[int] = []
            for ci, cell in enumerate(row):
                if ci not in (0, eff_idx):
                    ids += _ints_in(cell)
            if not ids:             # need n/events to confirm it is the same subgroup
                continue
            key = (eff.group("pt"), tuple(sorted(ids)))
            label = (row[0] if row else "").strip()
            groups.setdefault(key, []).append(((eff.group("lo"), eff.group("hi")), label))
        for (pt, ids), members in groups.items():
            cis = {ci for ci, _ in members}
            if len(members) >= 2 and len(cis) >= 2:
                labels = [lab for _, lab in members if lab]
                intervals = "; ".join(f"{lo}–{hi}" for lo, hi in sorted(cis))
                claims.append({
                    "verdict": "SUBGROUP_DUPLICATE_CI",
                    "severity": "Minor",
                    "detail": (f"rows sharing estimate {pt} and identity counts {list(ids)} print "
                               f"different confidence intervals ({intervals}); the same subgroup appears "
                               f"rendered twice with divergent uncertainty — harmonize to one interval, "
                               f"or footnote why the two differ"
                               + (f" (rows: {', '.join(labels)})" if labels else "")),
                    "where": (" / ".join(labels))[:120] or f"estimate {pt}",
                })
    return claims


_CINDEX_HDR = ("c-index", "c index", "cindex", "c-statistic", "c statistic", "concordance",
               "auc", "auroc", "harrell", "discrimination", "c (95")
_MODEL_HDR = ("model", "covariate", "predictor", "variables", "adjustment")
# tokens that appear in a model label but are NOT covariates
_COVAR_STOP = {"model", "models", "only", "vs", "versus", "plus", "the", "and", "reference",
               "baseline", "base", "full", "final", "adjusted", "unadjusted", "alone",
               "with", "index"}
_CI_VAL_RE = re.compile(r"\b0\.[5-9]\d")


def _covar_set(label: str) -> frozenset:
    """'CMB + age + sex' -> {'cmb','age','sex'} (additive split on '+', notes and
    non-covariate words dropped)."""
    label = re.sub(r"\(.*?\)", " ", label)
    out = set()
    for tok in re.split(r"\s*\+\s*", label):
        t = re.sub(r"[^a-z0-9]", "", tok.lower())
        if t and len(t) >= 2 and t not in _COVAR_STOP:
            out.add(t)
    return frozenset(out)


def check_nested_model_baseline(text: str) -> list[dict]:
    """A table of nested prediction models reports a discrimination statistic (C-index /
    AUC) for two or more models that all embed a common covariate set (e.g. every model
    is 'X + age + sex'), but there is no BASE-model row (the common covariates alone) and
    no incremental deltaC — so the shared covariates could account for the discrimination,
    and 'model A comparable to model B' is uninterpretable. Deterministic and header-gated:
    only tables with a discrimination column and additive ('X + Y') model labels are
    considered, so an ordinary results table does not fire."""
    claims: list[dict] = []
    for tbl in _parse_md_tables(text):
        if len(tbl) < 3:
            continue
        header = tbl[0]
        ci_idx = _pick(header, _CINDEX_HDR)
        if ci_idx is None:
            continue
        model_idx = _pick(header, _MODEL_HDR)
        if model_idx is None:
            model_idx = 0
        additive: list[tuple[str, frozenset]] = []
        ci_row_sets: set = set()
        for row in tbl[1:]:
            if ci_idx >= len(row) or not _CI_VAL_RE.search(row[ci_idx]):
                continue
            label = row[model_idx] if model_idx < len(row) else (row[0] if row else "")
            cset = _covar_set(label)
            ci_row_sets.add(cset)
            if "+" in label:
                additive.append((label, cset))
        if len(additive) < 2:
            continue
        common = frozenset.intersection(*(s for _, s in additive))
        if not common or common in ci_row_sets:
            continue
        if re.search(r"(?:Δ|delta[-\s]?)\s?(?:c\b|auc)|incremental (?:c[-\s]?index|auc|discrimination)",
                     text, re.IGNORECASE):
            continue
        claims.append({
            "verdict": "NESTED_MODEL_NO_BASELINE",
            "severity": "Minor",
            "detail": (f"{len(additive)} nested models report a discrimination statistic and all embed "
                       f"the covariates {sorted(common)}, but no base-model row (those covariates alone) "
                       f"and no incremental ΔC is reported; the shared covariates could account for the "
                       f"discrimination — add the base-model C-index and the ΔC so the incremental value "
                       f"is interpretable"),
            "where": ("; ".join(lab for lab, _ in additive[:3]))[:120],
        })
    return claims


def analyze(manuscript: str, data: str | None, id_col: str | None = None) -> dict:
    p = Path(manuscript)
    if not p.is_file():
        sys.stderr.write(f"ERROR: manuscript not found: {manuscript}\n")
        sys.exit(2)
    text = p.read_text(encoding="utf-8")

    claims = []
    claims += check_rate_text(text)
    claims += check_cascade_text(text)
    claims += check_partition_md(text)
    claims += check_partition_text(text)
    claims += check_followup_criterion(text)
    claims += check_duplicate_subgroup_ci(text)
    claims += check_nested_model_baseline(text)

    if data:
        rows = load_csv(data)
        claims += check_rate_csv(rows)
        claims += check_partition_csv(rows)
        claims += check_analysis_unit(rows, text, id_col)

    n_major = sum(1 for c in claims if c["severity"] == "Major")
    return {
        "manuscript": str(p),
        "data": data,
        "claims": claims,
        "summary": {
            "n_claims": len(claims),
            "n_major": n_major,
            "n_flag": len(claims) - n_major,
            "verdict": "MAJOR_CANDIDATE" if n_major else "OK",
        },
    }


def render(result: dict) -> str:
    lines = ["| Check | Severity | Detail |", "|---|---|---|"]
    for c in result["claims"]:
        lines.append(f"| {c['verdict']} | {c['severity']} | {c['detail']} |")
    if len(lines) == 2:
        lines.append("| (none) | — | no cohort-arithmetic discrepancy detected |")
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(description="Cohort arithmetic gate (Phase 2.5 / 2.5b).")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--data", help="optional CSV for exact recompute (rate / partition / analysis-unit)")
    ap.add_argument("--id-col", help="subject-ID column in --data for the records-vs-subjects "
                                     "analysis-unit check (auto-detected from common ID names if omitted)")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true", help="exit 1 if any Major claim exists")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    args = ap.parse_args()

    result = analyze(args.manuscript, args.data, args.id_col)

    if not args.quiet:
        print("=" * 41)
        print(" Cohort Arithmetic (Phase 2.5 / 2.5b)")
        print("=" * 41)
        print(render(result))
        print()
        s = result["summary"]
        if s["n_major"]:
            print(f"MAJOR candidate: {s['n_major']} cohort-arithmetic discrepancy(ies).")
        else:
            print("OK: no cohort-arithmetic discrepancy detected.")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_cohort_arithmetic", **result}, indent=2), encoding="utf-8")
        if not args.quiet:
            print(f"\nwrote {args.out}")

    return 1 if (args.strict and result["summary"]["n_major"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Confounding-completeness gate for observational studies (self-review Phase 2.5e).

The highest-yield observational reviewer finding is also the most mechanical: a
covariate that was *measured*, is *imbalanced across exposure groups* in the
baseline table, and is *absent from the adjustment set* is residual confounding
by a measured variable. A single-pass prose review misses it because the
manuscript text is internally consistent; only a join of the exposure-stratified
Table 1 against the Methods adjustment set exposes it. This script is that join
(probe O1 of observational_confounding.md), backported from the panel so the
deterministic finding lands without a multi-agent pass.

INPUTS
  --table1   exposure-stratified baseline table, CSV. One row per covariate.
             Needs a covariate-name column and a p-value (or SMD) column. Column
             names are auto-detected (case-insensitive); override with
             --name-col / --p-col / --smd-col. A file named like
             `table1_by_<exposure>.csv` is the convention.
  --adjusted adjustment-set variables. Either a path to a file (one variable per
             line, or a Methods paragraph the script greps after "adjusted for")
             or a comma-separated list passed inline with --adjusted-list.
  --exposure-defining[-list]
             covariates that are components of the exposure's own diagnostic
             criteria (e.g. BMI / glycaemia / lipids for a metabolic-syndrome or
             MASLD exposure). These are EXEMPT from the residual-confounding flag —
             adjusting for them is over-adjustment (probe O7), not a fix. The
             remedy for residual confounding is an extended-adjustment model with
             NON-defining prognostic covariates only.
  --group-cols A,B
             when the Table 1 has no p-value / SMD column but two exposure-stratum
             columns of "mean ± SD" (or "mean +/- SD") cells, name them here (or
             let the script auto-detect) and the SMD is computed per row. The
             "mean (SD)" paren form is intentionally NOT auto-parsed (it collides
             with "n (%)"); use the ± form or pass an explicit SMD column.

OUTPUT
  A reconciliation table (stdout) and, with --out, a JSON artifact:
    {covariate, imbalance_p / smd, in_adjustment_set, verdict}
  verdict UNADJUSTED_IMBALANCED is the Major candidate. Exit 1 (with --strict)
  when any UNADJUSTED_IMBALANCED row exists.

Matching the adjustment set to Table-1 covariate labels is fuzzy (a table row
"Smoking, pack-years" vs an adjustment token "smoking"), so the match is a
normalized-substring test in both directions; review the reconciliation table
rather than trusting the count blindly.

Stdlib-only (csv / json / re / argparse). Exit codes: 0 clean (or report-only),
1 unadjusted-imbalanced rows found (with --strict), 2 input/usage error.
"""

from __future__ import annotations

import argparse
import csv
import json
import re
import sys
from pathlib import Path

# --- column auto-detection -------------------------------------------------

NAME_HINTS = ("covariate", "variable", "characteristic", "feature", "name", "")
P_HINTS = ("p_value", "pvalue", "p-value", "p val", "p", "pr")
SMD_HINTS = ("smd", "std_diff", "standardized", "std. mean", "std mean")

P_THRESHOLD = 0.05
SMD_THRESHOLD = 0.10

# Header / summary rows that are not covariates (sample-size lines, group totals,
# trend-p rows). Matched on the whole normalized label, not a substring, so a real
# covariate like "Total cholesterol" is not swallowed by "total".
def _is_skip_row(cov: str) -> bool:
    c = _norm(cov)
    if c in ("", "total", "overall", "n", "no", "number"):
        return True
    if re.match(r"^n\s*[=:]", cov.strip().lower()):     # "N = ...", "n: ..."
        return True
    if "p for trend" in c or "p trend" in c or "for trend" in c:
        return True
    return False


def _norm(s: str) -> str:
    """Lowercase, drop punctuation/units, collapse whitespace for fuzzy match."""
    s = s.lower()
    s = re.sub(r"\(.*?\)", " ", s)            # drop "(mg/dL)", "(%)"
    s = re.sub(r"[^a-z0-9 ]+", " ", s)        # punctuation -> space
    s = re.sub(r"\s+", " ", s).strip()
    return s


# --- DB-code / prose synonym aliases ---------------------------------------
# A reviewer writes the adjustment set in prose ("systolic blood pressure") while
# a DB-exported Table 1 carries the column code ("he_sbp"); a normalized-substring
# match then fails and a covariate that *was* adjusted is false-flagged as
# imbalanced-and-unadjusted. Each row maps one canonical concept to the surface
# forms (DB code + prose synonyms) that denote it; two labels match when they
# resolve to a shared concept. This only ever *adds* matches (turns a false ✗ into
# ✓): a true unadjusted covariate shares no concept with any adjustment token, so
# no false ✓ is introduced. Extend as new DB dictionaries appear — one concept per
# row, lowercase, unit-free; multi-letter codes belong to the controlled
# `he_*` / `b_*` namespace so a bare token clash with a prose label is implausible.
ALIAS_GROUPS = {
    "sbp": ("he_sbp", "sbp", "systolic blood pressure", "systolic bp"),
    "dbp": ("he_dbp", "dbp", "diastolic blood pressure", "diastolic bp"),
    "uric_acid": ("b_uric", "uric acid", "serum uric acid", "urate"),
    "hdl": ("b_chol_hdl", "hdl", "hdl cholesterol", "high density lipoprotein"),
    "total_cholesterol": ("b_chol_t", "total cholesterol", "cholesterol total"),
    "triglycerides": ("b_tg", "tg", "triglyceride", "triglycerides"),
    "hba1c": ("b_hba1c", "hba1c", "glycated haemoglobin", "glycated hemoglobin",
              "glycohemoglobin"),
    "bmi": ("he_bmi", "bmi", "body mass index"),
    "waist": ("he_wc", "wc", "waist", "waist circumference"),
    "smoking": ("smk", "smk_packyrs", "smoking", "smoking status", "pack years",
                "pack-years", "smoker", "cigarette"),
    "fasting_glucose": ("he_glu", "b_glu", "fasting glucose", "fasting plasma glucose",
                        "fpg", "glucose"),
    "hemoglobin": ("he_hb", "b_hb", "hemoglobin", "haemoglobin"),
    "alcohol": ("alc", "alcohol", "alcohol intake", "drinking", "ethanol"),
    "egfr": ("egfr", "e_gfr", "estimated gfr", "estimated glomerular filtration rate"),
    "diabetes": ("dm", "diabetes", "diabetes mellitus"),
    "hypertension": ("htn", "hypertension", "high blood pressure"),
}

# concept -> set of normalized surface forms
_ALIAS_NORM = {c: {_norm(f) for f in forms if _norm(f)} for c, forms in ALIAS_GROUPS.items()}


def _concepts(label: str) -> set[str]:
    """Canonical concept keys a (normalized) covariate / adjustment label denotes.

    Single-token surface ("sbp", "wc"): whole-token match. Multi-word surface
    ("waist circumference"): contiguous phrase or all tokens present (so a Table-1
    row "Smoking, pack-years" -> 'smoking pack years' still resolves to smoking).
    """
    s = _norm(label)
    if not s:
        return set()
    tokens = set(s.split())
    out = set()
    for concept, surfaces in _ALIAS_NORM.items():
        for f in surfaces:
            ft = f.split()
            if len(ft) == 1:
                if ft[0] in tokens:
                    out.add(concept)
                    break
            elif f in s or all(t in tokens for t in ft):
                out.add(concept)
                break
    return out


def _pick_col(header: list[str], hints: tuple[str, ...], override: str | None) -> int | None:
    if override:
        for i, h in enumerate(header):
            if _norm(h) == _norm(override):
                return i
        sys.stderr.write(f"ERROR: column '{override}' not found in header {header}\n")
        return None
    norm = [_norm(h) for h in header]
    # exact-ish first
    for hint in hints:
        h = _norm(hint)
        for i, col in enumerate(norm):
            if col == h and h:
                return i
    # then substring — but only for hints >= 3 chars, so a 1-2 char hint like
    # "p" / "pr" does not match an unrelated column ("p" in "exposed").
    for hint in hints:
        h = _norm(hint)
        for i, col in enumerate(norm):
            if h and len(h) >= 3 and h in col:
                return i
    return None


def _parse_p(raw: str) -> float | None:
    """Parse a p-value cell: '0.001', '<0.001', 'p<0.01', '0.03*', 'NS'."""
    if raw is None:
        return None
    s = raw.strip().lower()
    if not s or s in ("ns", "na", "n/a", "-", "."):
        return 1.0 if s == "ns" else None
    m = re.search(r"<\s*(0?\.[0-9]+|[0-9]+\.?[0-9]*)", s)   # "<0.001", "p<.01"
    if m:
        try:                                   # report just under the stated bound
            return max(float(m.group(1)) - 1e-6, 0.0)
        except ValueError:
            return None
    m = re.search(r"0?\.[0-9]+|[0-9]+\.?[0-9]*", s)
    if m:
        try:
            return float(m.group(0))
        except ValueError:
            return None
    return None


def _parse_float(raw: str) -> float | None:
    if raw is None:
        return None
    m = re.search(r"-?[0-9]*\.?[0-9]+", raw.strip())
    return float(m.group(0)) if m else None


# --- adjustment set --------------------------------------------------------

def load_adjustment_set(path: str | None, inline: str | None) -> list[str]:
    if inline:
        return [t.strip() for t in inline.split(",") if t.strip()]
    if not path:
        return []
    p = Path(path)
    if not p.is_file():
        sys.stderr.write(f"ERROR: adjustment file not found: {path}\n")
        sys.exit(2)
    text = p.read_text(encoding="utf-8")
    # If the file is a Methods paragraph, grep the "adjusted for ..." clause.
    m = re.search(r"adjust(?:ed|ing)?\s+for\s+(.+?)(?:\.|;|\n\n|$)", text, re.I | re.S)
    if m:
        clause = m.group(1)
        parts = re.split(r",| and | as well as ", clause)
        return [p2.strip() for p2 in parts if p2.strip()]
    # Otherwise treat as one variable per line.
    return [ln.strip() for ln in text.splitlines() if ln.strip() and not ln.startswith("#")]


def in_adjustment_set(cov: str, adj_norm: list[str], adj_concepts: set[str] | None = None) -> bool:
    c = _norm(cov)
    if not c:
        return False
    # concept-level match across the DB-code / prose alias map (he_sbp ~ "systolic
    # blood pressure"); resolves the false ✗ when Table 1 carries DB column codes
    # and the adjustment set is written in prose.
    if adj_concepts and (_concepts(cov) & adj_concepts):
        return True
    for a in adj_norm:
        if not a:
            continue
        if a in c or c in a:
            return True
        # token overlap on the leading word (smoking ~ "smoking, pack-years")
        if c.split(" ")[0] == a.split(" ")[0] and len(c.split(" ")[0]) >= 3:
            return True
    return False


# --- A3: SMD computed from per-stratum mean ± SD ---------------------------
# The common wide Table 1 from /analyze-stats carries stratified "mean ± SD"
# (or "mean +/- SD") cells but no p / SMD column, so the gate could not run. When
# no p/SMD column is present, compute SMD from two group columns whose cells use
# the UNAMBIGUOUS mean±SD form (not "n (%)" / "mean (SD)", which collide), so a
# categorical "53 (52)" is never mistaken for a continuous mean(sd).
MEANSD_RE = re.compile(r"^\s*(-?\d[\d,]*\.?\d*)\s*(?:\+/-|±)\s*(\d[\d,]*\.?\d*)\s*$")


def _meansd(cell: str):
    if cell is None:
        return None
    m = MEANSD_RE.match(cell)
    if not m:
        return None
    try:
        return float(m.group(1).replace(",", "")), float(m.group(2).replace(",", ""))
    except ValueError:
        return None


def _smd_meansd(m1: float, s1: float, m2: float, s2: float):
    denom = ((s1 ** 2 + s2 ** 2) / 2.0) ** 0.5
    if denom <= 0:
        return None
    return (m1 - m2) / denom


def _detect_group_cols(header, body_rows, name_idx, override):
    """Return (i, j) column indices of the two exposure-stratum value columns to
    compute SMD from, or None. With --group-cols, resolve the two named columns;
    otherwise pick the first two non-name columns whose cells are mostly mean±SD."""
    if override:
        idxs = []
        for want in override:
            found = next((k for k, h in enumerate(header) if _norm(h) == _norm(want)), None)
            if found is None:
                sys.stderr.write(f"ERROR: --group-cols column '{want}' not found in {header}\n")
                sys.exit(2)
            idxs.append(found)
        return (idxs[0], idxs[1]) if len(idxs) >= 2 else None
    cand = []
    for k in range(len(header)):
        if k == name_idx:
            continue
        hits = sum(1 for r in body_rows if k < len(r) and _meansd(r[k]) is not None)
        if hits >= 2:
            cand.append(k)
    return (cand[0], cand[1]) if len(cand) >= 2 else None


def is_exposure_defining(cov: str, defining_norm: list[str], defining_concepts: set[str]) -> bool:
    """A4: a covariate that is a component of the exposure's diagnostic criteria
    (e.g. BMI/glycaemia/lipids for a metabolic-syndrome / MASLD exposure). Same
    fuzzy match as in_adjustment_set."""
    if not defining_norm and not defining_concepts:
        return False
    return in_adjustment_set(cov, defining_norm, defining_concepts)


# --- core ------------------------------------------------------------------

def analyze(table1: str, adj: list[str], name_col, p_col, smd_col,
            defining: list[str] | None = None, group_cols: list[str] | None = None) -> dict:
    p = Path(table1)
    if not p.is_file():
        sys.stderr.write(f"ERROR: table1 not found: {table1}\n")
        sys.exit(2)
    with p.open(encoding="utf-8-sig", newline="") as f:
        reader = csv.reader(f)
        rows = [r for r in reader if any(c.strip() for c in r)]
    if len(rows) < 2:
        sys.stderr.write("ERROR: table1 has no data rows\n")
        sys.exit(2)
    header = rows[0]
    ni = _pick_col(header, NAME_HINTS, name_col)
    pi = _pick_col(header, P_HINTS, p_col)
    si = _pick_col(header, SMD_HINTS, smd_col)
    if ni is None:
        ni = 0
    gi = None
    if pi is None and si is None:
        # A3: no p / SMD column — fall back to computing SMD from two mean±SD cols.
        gi = _detect_group_cols(header, rows[1:], ni, group_cols)
        if gi is None:
            sys.stderr.write(
                "ERROR: no p-value or SMD column found, and no two mean±SD group "
                "columns to compute SMD from; pass --p-col/--smd-col or --group-cols.\n")
            sys.exit(2)

    adj_norm = [_norm(a) for a in adj]
    adj_concepts = set().union(*(_concepts(a) for a in adj)) if adj else set()
    defining = defining or []
    def_norm = [_norm(d) for d in defining]
    def_concepts = set().union(*(_concepts(d) for d in defining)) if defining else set()
    smd_source = "reported" if (pi is not None or si is not None) else "computed_from_mean_sd"
    covariates = []
    for r in rows[1:]:
        if ni >= len(r):
            continue
        cov = r[ni].strip()
        if _is_skip_row(cov):
            continue
        pval = _parse_p(r[pi]) if (pi is not None and pi < len(r)) else None
        smd = _parse_float(r[si]) if (si is not None and si < len(r)) else None
        if smd is None and gi is not None:                       # A3: compute SMD
            g1 = _meansd(r[gi[0]]) if gi[0] < len(r) else None
            g2 = _meansd(r[gi[1]]) if gi[1] < len(r) else None
            if g1 and g2:
                smd = _smd_meansd(g1[0], g1[1], g2[0], g2[1])
        imbalanced = (pval is not None and pval < P_THRESHOLD) or \
                     (smd is not None and abs(smd) >= SMD_THRESHOLD)
        if not imbalanced:
            continue
        # A4: a component of the exposure's own diagnostic criteria is over-
        # adjustment, not residual confounding — exempt it from the Major flag.
        if is_exposure_defining(cov, def_norm, def_concepts):
            verdict = "EXPOSURE_DEFINING_EXEMPT"
            adjusted = in_adjustment_set(cov, adj_norm, adj_concepts)
        else:
            adjusted = in_adjustment_set(cov, adj_norm, adj_concepts)
            verdict = "ADJUSTED" if adjusted else "UNADJUSTED_IMBALANCED"
        covariates.append({
            "covariate": cov,
            "imbalance_p": pval,
            "smd": round(smd, 4) if smd is not None else None,
            "in_adjustment_set": adjusted,
            "verdict": verdict,
        })

    unadjusted = [f for f in covariates if f["verdict"] == "UNADJUSTED_IMBALANCED"]
    exempt = [f for f in covariates if f["verdict"] == "EXPOSURE_DEFINING_EXEMPT"]
    # `findings` is the DEFECT list and nothing else. It used to be the whole per-covariate
    # audit table, two of whose three verdicts mean "this is fine": ADJUSTED says the
    # covariate WAS handled and EXPOSURE_DEFINING_EXEMPT records a deliberate exemption.
    # Every consumer that aggregates qc/ counted those as fires — in one real project that
    # was ~45 pseudo-findings from three runs, enough to make this the loudest detector in
    # the suite and to corrupt the precision ledger built on top of it. The full table is
    # still emitted, as `covariates`, which is what the human-readable render walks.
    findings = [dict(f, severity="major", message=(
        f"{f['covariate']} is imbalanced by exposure "
        + (f"(p={f['imbalance_p']:.4g})" if f["imbalance_p"] is not None else
           f"(SMD={f['smd']:.3g})" if f["smd"] is not None else "")
        + " and is not in the adjustment set; report an extended-adjustment sensitivity model."
    )) for f in unadjusted]
    return {
        "table1": str(p),
        "adjustment_set": adj,
        "exposure_defining": defining,
        "thresholds": {"p": P_THRESHOLD, "smd": SMD_THRESHOLD},
        "smd_source": smd_source,
        "n_imbalanced": len(covariates),
        "n_unadjusted_imbalanced": len(unadjusted),
        "n_exposure_defining_exempt": len(exempt),
        "covariates": covariates,
        "findings": findings,
        "verdict": "MAJOR_CANDIDATE" if unadjusted else "OK",
        "suggested_fix": (
            "Report an extended-adjustment sensitivity model adding the unadjusted "
            "imbalanced covariates that are NON-defining prognostic factors (not the "
            "exposure's own diagnostic criteria); keep the original model primary "
            "only if the extended model agrees."
        ) if unadjusted else None,
    }


def render_table(result: dict) -> str:
    lines = [
        "| Covariate | Imbalance p | SMD | In adjustment set? | Verdict |",
        "|---|---|---|---|---|",
    ]
    marks = {
        "UNADJUSTED_IMBALANCED": "✗ Major",
        "ADJUSTED": "✓",
        "EXPOSURE_DEFINING_EXEMPT": "⊘ exposure-defining (exempt; adjusting = over-adjustment)",
    }
    for f in result["covariates"]:
        p = "—" if f["imbalance_p"] is None else f"{f['imbalance_p']:.4g}"
        s = "—" if f["smd"] is None else f"{f['smd']:.3g}"
        mark = marks.get(f["verdict"], f["verdict"])
        lines.append(
            f"| {f['covariate']} | {p} | {s} | "
            f"{'yes' if f['in_adjustment_set'] else 'NO'} | {mark} |"
        )
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(description="Observational confounding-completeness gate (O1).")
    ap.add_argument("--table1", required=True, help="exposure-stratified Table 1 CSV")
    ap.add_argument("--adjusted", help="adjustment-set file (var-per-line or Methods paragraph)")
    ap.add_argument("--adjusted-list", help="comma-separated adjustment variables (inline)")
    ap.add_argument("--name-col", help="override covariate-name column header")
    ap.add_argument("--p-col", help="override p-value column header")
    ap.add_argument("--smd-col", help="override SMD column header")
    ap.add_argument("--group-cols",
                    help="two stratum value-column headers (comma-separated) to compute SMD from "
                         "mean±SD cells when no p/SMD column exists (e.g. 'exposed,unexposed')")
    ap.add_argument("--exposure-defining",
                    help="file of exposure-defining covariates (components of the exposure's "
                         "diagnostic criteria); these are exempt from the residual-confounding flag")
    ap.add_argument("--exposure-defining-list",
                    help="comma-separated exposure-defining covariates (inline)")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true", help="exit 1 if unadjusted-imbalanced rows exist")
    args = ap.parse_args()

    adj = load_adjustment_set(args.adjusted, args.adjusted_list)
    if not adj:
        sys.stderr.write("WARN: empty adjustment set — every imbalanced covariate will flag.\n")
    defining = load_adjustment_set(args.exposure_defining, args.exposure_defining_list)
    group_cols = [c.strip() for c in args.group_cols.split(",")] if args.group_cols else None

    result = analyze(args.table1, adj, args.name_col, args.p_col, args.smd_col,
                     defining, group_cols)

    print("=" * 41)
    print(" Confounding Completeness (Phase 2.5e / O1)")
    print("=" * 41)
    print(f"adjustment set: {', '.join(adj) if adj else '(none)'}")
    if defining:
        print(f"exposure-defining (exempt): {', '.join(defining)}")
    if result["smd_source"] == "computed_from_mean_sd":
        print("SMD source: computed from mean±SD group columns (no p/SMD column present)")
    print(render_table(result))
    print()
    if result["n_exposure_defining_exempt"]:
        print(f"Note: {result['n_exposure_defining_exempt']} imbalanced covariate(s) exempt as "
              f"exposure-defining (adjusting for them would be over-adjustment — see probe O7).")
    if result["n_unadjusted_imbalanced"]:
        print(f"MAJOR candidate: {result['n_unadjusted_imbalanced']} imbalanced covariate(s) "
              f"absent from the adjustment set.")
        print(f"Fix: {result['suggested_fix']}")
    else:
        print("OK: no measured-but-unadjusted imbalanced covariate.")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_confounding_completeness", **result}, indent=2), encoding="utf-8")
        print(f"\nwrote {args.out}")

    return 1 if (args.strict and result["n_unadjusted_imbalanced"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Feature-selection-outside-CV leakage gate (self-review Phase 2.5 / data-prep).

For a classifier / NLP / tabular manuscript, if feature selection, vocabulary
construction, log-odds / univariate filtering, or a threshold is chosen on the WHOLE
dataset and only THEN cross-validation is run, the CV performance is optimistically
inflated: the selection has already seen the held-out folds. The fix is to nest the
selection inside each training fold (nested CV). This is a class a statistical
reviewer catches deterministically, and it is distinct from patient-vs-image split
leakage (`model-validation/check_split_leakage.py`).

Verdict:
  CV_SELECTION_LEAKAGE (Major)  a feature-selection / vocabulary / threshold step
                                co-occurs with a cross-validation description AND no
                                fold-nesting disclosure ("within each fold", "nested
                                CV", "inside the training fold") is present. The
                                headline CV metric is likely optimistic.

Conservative by construction: fires only when BOTH a selection token AND a CV token
appear AND no nesting-disclosure token is anywhere in the document. A single
"within each training fold" / "nested cross-validation" sentence suppresses it.

Exit codes: 0 clean/report-only, 1 with --strict when any Major, 2 usage. Stdlib-only.

Usage:
    python3 check_cv_leakage.py --manuscript manuscript.md \
        [--out qc/cv_leakage.json] [--strict] [--quiet]
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

# A data-driven selection / construction step that must be nested inside CV.
SELECTION = re.compile(
    r"\bfeature\s+selection\b|\bselected\s+(?:the\s+)?(?:top\s+)?\d+\s+(?:features|variables|predictors)"
    r"|\blog[-\s]?odds\b|\bvocabulary\s+(?:construction|was\s+built|building)\b|\bbuilt\s+(?:a\s+)?vocabulary"
    r"|\bfeature\s+ranking\b|\bunivariate\s+(?:filter|screening|selection)\b|\btop[-\s]?k\s+features"
    r"|\bmutual[-\s]information\s+(?:selection|ranking)\b|\bchi[-\s]?square(?:d)?\s+selection"
    r"|\b(?:selected|chose|retained|kept)\s+(?:the\s+)?(?:most\s+)?(?:informative|discriminative|predictive)\s+features"
    r"|\bthreshold(?:ed|ing)?\b[^.\n]{0,40}\b(?:on|over|across|using)\s+the\s+(?:entire|full|whole|complete)\s+(?:data|dataset|cohort|corpus)"
    r"|\b(?:LASSO|elastic[-\s]net|recursive\s+feature\s+elimination|RFE|Boruta)\b",
    re.IGNORECASE)

# A cross-validation evaluation.
CV = re.compile(
    r"\bcross[-\s]?validat(?:ion|ed)\b|\b\d+[-\s]?fold\b|\bk[-\s]?fold\b"
    r"|\bleave[-\s]one[-\s]out\b|\bLOOCV\b|\bstratified\s+(?:\d+[-\s]?)?fold",
    re.IGNORECASE)

# Disclosure that the selection is correctly nested inside the CV training folds.
NESTING = re.compile(
    r"\bnested\s+(?:cross[-\s]?validat|CV)\b"
    r"|\bwithin\s+each\s+(?:training\s+)?fold\b|\binside\s+(?:the\s+)?training\s+(?:fold|partition|split)"
    r"|\bper[-\s]?fold\b|\bfold[-\s]specific\b|\bfor\s+each\s+(?:training\s+)?fold\b"
    r"|\bon\s+the\s+training\s+(?:fold|partition|split|set)\s+only\b"
    r"|\brefit(?:ted)?\s+within\b|\brepeated\s+(?:in|within|inside)\s+each\s+fold"
    r"|\bselection\s+was\s+(?:performed|done|repeated)\s+(?:in|within|inside)\s+each\b",
    re.IGNORECASE)


def check(text: str) -> list[dict]:
    sel = SELECTION.search(text)
    cv = CV.search(text)
    if not (sel and cv):
        return []
    if NESTING.search(text):
        return []  # nesting is disclosed
    return [{
        "verdict": "CV_SELECTION_LEAKAGE",
        "severity": "Major",
        "detail": (f"a data-driven selection step ('{sel.group(0).strip()}') co-occurs with "
                   f"cross-validation ('{cv.group(0).strip()}') but no fold-nesting is disclosed "
                   f"(no 'within each fold' / 'nested CV'); if the selection was fit on the full "
                   f"dataset the CV metric is optimistically inflated — nest it in each training fold"),
        "where": text[max(0, sel.start() - 30):sel.end() + 50].replace("\n", " ").strip()[:170],
    }]


def analyze(manuscript: str) -> dict:
    p = Path(manuscript)
    if not p.is_file():
        sys.stderr.write(f"ERROR: manuscript not found: {manuscript}\n")
        sys.exit(2)
    claims = check(p.read_text(encoding="utf-8"))
    n_major = sum(1 for c in claims if c["severity"] == "Major")
    return {
        "manuscript": str(p),
        "claims": claims,
        "summary": {"n_claims": len(claims), "n_major": n_major, "n_flag": len(claims) - n_major,
                    "verdict": "MAJOR_CANDIDATE" if n_major else "OK"},
    }


def render(result: dict) -> str:
    lines = ["| Check | Severity | Detail |", "|---|---|---|"]
    for c in result["claims"]:
        lines.append(f"| {c['verdict']} | {c['severity']} | {c['detail']} |")
    if len(lines) == 2:
        lines.append("| (none) | — | no feature-selection-outside-CV leakage detected |")
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(
        description="Feature-selection-outside-CV leakage gate (Phase 2.5 / data-prep).")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true", help="exit 1 if any Major claim exists")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    args = ap.parse_args()

    result = analyze(args.manuscript)

    if not args.quiet:
        print("=" * 44)
        print(" CV selection-leakage (§2.5 / data-prep)")
        print("=" * 44)
        print(render(result))
        print()
        if result["summary"]["n_major"]:
            print("MAJOR candidate: a selection step co-occurs with CV and no fold-nesting is disclosed.")
        else:
            print("OK: no feature-selection-outside-CV leakage detected.")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_cv_leakage", **result}, indent=2), encoding="utf-8")
        if not args.quiet:
            print(f"\nwrote {args.out}")

    return 1 if (args.strict and result["summary"]["n_major"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""check_dta_denominators.py — cross-check diagnostic-accuracy sensitivity /
specificity denominators against the reference-standard category counts in the
characteristics table.

Sensitivity is a/(a+c) over the disease-positive patients; specificity is d/(b+d)
over the disease-negative patients. Those denominators must equal the reference-
standard positive / negative counts printed in the characteristics table. When
they disagree while the grand total still matches (e.g. table 14/19, Results
15/18, both summing to 33), a totals check passes and the split-level error — which
sits under an Abstract headline — survives multiple review rounds. This detector
recovers both category counts and both denominators and asserts equality per
category, refusing to accept grand-total agreement as passing.

Also `STAGE_ROWSUM`: a staging-confusion breakdown must satisfy
correctly-staged + over-staged + under-staged == n.

Runs on FIRST submissions, not only revisions — the source incident had both
numbers on the page from submission one.

Stdlib-only. Reads the manuscript, never writes it.

Usage:
  python3 check_dta_denominators.py --manuscript paper.md [--strict] [--quiet] [--json]
Exit: 0 clean; with --strict, 1 on any mismatch; 2 on input/usage error.
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from dataclasses import dataclass, field, asdict

SEP_RE = re.compile(r"^\s*\|?[\s:|-]*-[\s:|-]*\|?\s*$")
NEG_LABEL_RE = re.compile(r"\b(p?N\s*0|node[- ]negative|disease[- ](?:free|negative)|absent|benign|non-?malignant)\b", re.I)
POS_LABEL_RE = re.compile(r"\b(p?N\s*[1-9]|node[- ]positive|disease[- ]positive|present|malignant|metasta\w+)\b", re.I)
# "sensitivity ... 13/18" or "13 of 18"; bounded gap so it does not cross a
# sentence boundary but tolerates a decimal percentage (e.g. "72.2% (13/18)").
SENS_RE = re.compile(r"sensitivit\w*[^\n]{0,40}?\b(\d+)\s*(?:/|of)\s*(\d+)", re.I)
SPEC_RE = re.compile(r"specificit\w*[^\n]{0,40}?\b(\d+)\s*(?:/|of)\s*(\d+)", re.I)
CORRECT_RE = re.compile(r"correctl\w*[^.\n]*?\b(\d+)", re.I)
OVER_RE = re.compile(r"over[- ]?stag\w*[^.\n]*?\b(\d+)", re.I)
UNDER_RE = re.compile(r"under[- ]?stag\w*[^.\n]*?\b(\d+)", re.I)
STAGE_N_RE = re.compile(r"\b(?:in|of|among)\s+(\d+)\s+(?:patients|exams|cases|lesions)\b", re.I)


@dataclass
class Finding:
    kind: str
    severity: str
    detail: str


@dataclass
class Report:
    source: str
    findings: list[Finding] = field(default_factory=list)

    @property
    def n_flag(self) -> int:
        return sum(1 for f in self.findings if f.severity == "MAJOR")

    @property
    def verdict(self) -> str:
        return "DENOMINATOR MISMATCH" if self.n_flag else "OK"


def _split_row(line: str) -> list[str]:
    s = line.strip()
    if s.startswith("|"):
        s = s[1:]
    if s.endswith("|"):
        s = s[:-1]
    return [c.strip() for c in s.split("|")]


def _reference_counts(text: str):
    """Return (neg_total, pos_total) summed over reference-standard rows, or None."""
    neg = pos = 0
    seen = False
    lines = text.splitlines()
    i, n = 0, len(lines)
    while i < n:
        if "|" in lines[i] and i + 1 < n and SEP_RE.match(lines[i + 1]) and "-" in lines[i + 1]:
            j = i + 2
            while j < n and "|" in lines[j] and lines[j].strip():
                cells = _split_row(lines[j])
                if cells:
                    label = cells[0]
                    cm = re.search(r"\b(\d[\d,]*)\b", " ".join(cells[1:]))
                    if cm:
                        cnt = int(cm.group(1).replace(",", ""))
                        if NEG_LABEL_RE.search(label):
                            neg += cnt; seen = True
                        elif POS_LABEL_RE.search(label):
                            pos += cnt; seen = True
                j += 1
            i = j
        else:
            i += 1
    return (neg, pos) if seen else None


def audit(text: str, source: str) -> Report:
    rep = Report(source=source)
    ref = _reference_counts(text)
    sens = SENS_RE.search(text)
    spec = SPEC_RE.search(text)

    if ref and (sens or spec):
        neg_ct, pos_ct = ref
        sens_denom = int(sens.group(2)) if sens else None
        spec_denom = int(spec.group(2)) if spec else None
        if sens_denom is not None and pos_ct and sens_denom != pos_ct:
            rep.findings.append(Finding(
                "DTA_DENOMINATOR_MISMATCH", "MAJOR",
                f"sensitivity denominator {sens_denom} (disease-positive) ≠ reference-standard "
                f"positive count {pos_ct} from the characteristics table"))
        if spec_denom is not None and neg_ct and spec_denom != neg_ct:
            rep.findings.append(Finding(
                "DTA_DENOMINATOR_MISMATCH", "MAJOR",
                f"specificity denominator {spec_denom} (disease-negative) ≠ reference-standard "
                f"negative count {neg_ct} from the characteristics table"))
        # note when the grand totals still agree — that is what hides it
        if rep.n_flag and sens_denom and spec_denom and neg_ct + pos_ct == sens_denom + spec_denom:
            rep.findings.append(Finding(
                "GRAND_TOTAL_AGREES", "INFO",
                f"grand totals agree ({neg_ct}+{pos_ct} = {sens_denom}+{spec_denom} = "
                f"{neg_ct + pos_ct}), so a totals-only check passes — the split-level "
                f"mismatch is the defect"))

    c, o, u = CORRECT_RE.search(text), OVER_RE.search(text), UNDER_RE.search(text)
    sn = STAGE_N_RE.search(text)
    if c and o and u and sn:
        s = int(c.group(1)) + int(o.group(1)) + int(u.group(1))
        tot = int(sn.group(1))
        if s != tot:
            rep.findings.append(Finding(
                "STAGE_ROWSUM", "MAJOR",
                f"correctly {c.group(1)} + over {o.group(1)} + under {u.group(1)} = {s} ≠ n={tot}"))
    return rep


def format_report(rep: Report, color: bool) -> str:
    tag = {"OK": "\033[92m", "DENOMINATOR MISMATCH": "\033[91m"}.get(rep.verdict, "") if color else ""
    end = "\033[0m" if color else ""
    out = [f"{tag}== {rep.verdict} =={end}  {rep.source}", f"mismatches={rep.n_flag}"]
    if not rep.findings:
        out.append("sens/spec denominators reconcile with the reference-standard category counts.")
        return "\n".join(out)
    for f in sorted(rep.findings, key=lambda x: (x.severity != "MAJOR", x.kind, x.detail)):
        out.append(f"[{f.severity:<5}] {f.kind}  {f.detail}")
    return "\n".join(out)


def main(argv: list[str] | None = None) -> int:
    ap = argparse.ArgumentParser(description=__doc__,
                                 formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--strict", action="store_true", help="exit 1 on any mismatch")
    ap.add_argument("--quiet", action="store_true", help="suppress the report; exit code only")
    ap.add_argument("--json", action="store_true", help="emit JSON instead of a text report")
    args = ap.parse_args(argv)
    try:
        text = open(args.manuscript, encoding="utf-8").read()
    except OSError as e:
        print(f"error: cannot read manuscript: {e}", file=sys.stderr)
        return 2
    rep = audit(text, args.manuscript)
    if not args.quiet:
        if args.json:
            print(json.dumps({"detector": "check_dta_denominators", "source": rep.source, "verdict": rep.verdict,
                              "findings": [asdict(f) for f in rep.findings]},
                             ensure_ascii=False, indent=2))
        else:
            print(format_report(rep, color=sys.stdout.isatty()))
    return 1 if (args.strict and rep.n_flag) else 0


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

#!/usr/bin/env python3
"""Editorial-impression / defensiveness gate (self-review §L) — the counterweight pass.

The rest of the MedSci-Audit stack minimizes *rejection-for-cause* (the floor):
fabricated citations, drifting numbers, overclaims, missing checklist items. Several
of those gates raise the floor by *adding* material — a hedge, a caveat, a disclosure,
a checklist row — and nothing in the stack pushes back. Iterated, a manuscript
monotonically over-hardens: a confident narrative turns into a defensive audit that an
editor reads as a risk signal even when every individual gate finding was correct.

This gate is the missing opposite force. It does not relax any integrity gate; it scans
the *manuscript as a whole* for editorial-impression risks and recommends SUBTRACTION —
REMOVE, MOVE, or TIGHTEN — so the accurate content the gates secured is also read
confidently. Every finding is advisory (Minor / impression) and NON-BLOCKING: this gate
never returns a submission blocker. It raises the ceiling; it does not gate the floor.

  HEDGE_DENSITY         defensive-caveat tokens per 1,000 body-narrative words exceed a
                        threshold — the prose hedges faster than it asserts. TIGHTEN.
  HEDGE_REPEAT          one caveat motif ("no deployable claim", "not generalizable",
                        "none evaluated here") repeats >=N times across body + abstract.
                        Say it once, firmly. TIGHTEN.
  AUDIT_IN_BODY         provenance/audit minutiae (SHA / git commit / unit-test /
                        post-lock timeline / manifest / seed=N / audit trail) appear in
                        the Introduction / Results / Discussion narrative rather than a
                        Methods reproducibility statement or a supplement. MOVE.
  LIMITATIONS_VOLUME    the Limitations passage enumerates more than N discrete items;
                        a wall of limitations reads as a rebuttal letter. TIGHTEN.
  ABSTRACT_CAVEAT_LOAD  the Abstract carries >=N caveat clauses; the headline result is
                        buried under qualifiers before a reader reaches it. TIGHTEN.
  BURIED_DEFENSE        a strong numeric robustness / sensitivity result sits only in the
                        Limitations / supplement, with no robustness mention in Results.
                        This is the inverse of the scope-coherence gate: scope-coherence
                        pushes a *weak* analysis out of Results; BURIED_DEFENSE pulls a
                        *strong* confound rebuttal back into Results. MOVE (promote).

Conservative by construction: each probe fires only on an explicit, locatable signal, to
keep false positives low on a widely-used skill. The gate needs IMRAD-style headings to
locate sections; with none it degrades to a whole-document density read.

INPUTS
  --manuscript  manuscript markdown/text (required).
  thresholds    --hedge-per-1k (10.0), --repeat-threshold (3), --limitations-max (6),
                --abstract-caveat-max (2). A probe fires when its count exceeds the max.

OUTPUT
  A reconciliation table (stdout) and, with --out, a JSON artifact:
    {manuscript, claims[{verdict, severity, action, detail, where}], summary}
  Every claim is severity "Minor" with an action of REMOVE / MOVE / TIGHTEN. Exit code is
  always 0 for the findings themselves (advisory); --strict is accepted for CLI parity
  with the other gates but never blocks, since this gate emits no Major.

Stdlib-only (json / re / argparse / pathlib). Exit codes: 0 clean or advisory findings,
2 input/usage error.
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

# --------------------------------------------------------------------------- #
# Section segmentation
# --------------------------------------------------------------------------- #

HEADING_RE = re.compile(r"^(#{1,6})\s*\*{0,2}(.+?)\*{0,2}\s*$", re.MULTILINE)

# Narrative regions where defensive prose and out-of-place audit minutiae read worst.
# Methods is deliberately excluded (a reproducibility statement belongs there), as is
# any supplement / availability / declarations region.
BODY_NARRATIVE = {"introduction", "results", "discussion", "conclusion", "limitations"}


def classify_heading(h: str) -> str:
    t = h.lower().strip()
    if "abstract" in t or t == "summary":
        return "abstract"
    if any(k in t for k in (
        "data availability", "code availability", "availability", "supplement",
        "appendix", "acknowledg", "funding", "declaration", "competing interest",
        "conflict of interest", "reproducibility", "references", "author contribution",
    )):
        return "supplement"
    if "limitation" in t:
        return "limitations"
    if "introduction" in t or "background" in t:
        return "introduction"
    if any(k in t for k in (
        "method", "material", "statistical analys", "study design",
        "patients and", "data collection", "study population",
    )):
        return "methods"
    if "result" in t or "finding" in t:
        return "results"
    if "discussion" in t:
        return "discussion"
    if "conclusion" in t:
        return "conclusion"
    return "other"


def segment(text: str) -> list[tuple[str, str]]:
    """Return an ordered list of (region, body_text) pairs. Text before the first
    heading is a 'preamble' region. Region names follow classify_heading()."""
    matches = list(HEADING_RE.finditer(text))
    regions: list[tuple[str, str]] = []
    if not matches:
        return [("preamble", text)]
    if matches[0].start() > 0:
        pre = text[: matches[0].start()].strip()
        if pre:
            regions.append(("preamble", pre))
    for i, m in enumerate(matches):
        start = m.end()
        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
        body = text[start:end].strip()
        regions.append((classify_heading(m.group(2)), body))
    return regions


def region_text(regions: list[tuple[str, str]], names: set[str]) -> str:
    return "\n".join(b for r, b in regions if r in names)


def abstract_text(regions: list[tuple[str, str]], full: str) -> str:
    """The Abstract region; fall back to the text before the first Introduction/Methods
    heading (a structured abstract without its own heading), capped to ~350 words."""
    abs_regions = [b for r, b in regions if r == "abstract"]
    if abs_regions:
        return "\n".join(abs_regions)
    # Fallback: preamble + everything up to the first intro/methods region.
    out: list[str] = []
    for r, b in regions:
        if r in ("introduction", "methods", "results", "discussion"):
            break
        if r in ("preamble", "other"):
            out.append(b)
    joined = "\n".join(out)
    words = joined.split()
    return " ".join(words[:350]) if len(words) > 350 else joined


def word_count(text: str) -> int:
    return sum(1 for w in text.split() if any(c.isalpha() for c in w))


def sentences(text: str) -> list[str]:
    # Lightweight sentence split on ., !, ? followed by whitespace.
    parts = re.split(r"(?<=[.!?])\s+", text.strip())
    return [s.strip() for s in parts if s.strip()]


# --------------------------------------------------------------------------- #
# Lexicons
# --------------------------------------------------------------------------- #

# Defensive caveats — explicitly hedging phrases, not ordinary modal verbs. Stacking
# these is the defensiveness tell HEDGE_DENSITY measures.
CAVEAT = re.compile(
    r"\bcaveats?\b|should be interpreted with caution|with caution\b|"
    r"must be interpreted|interpreted? with care|"
    r"cannot be (?:inferred|established|excluded|determined|generaliz\w+|ruled out|drawn|assumed)|"
    r"no (?:causal|deployable|clinical|definitive) (?:claim|inference|conclusion|relationship)|"
    r"not (?:be )?(?:generaliz\w+|definitive|conclusive|deployable|warranted)|"
    r"\bpreliminary\b|\bexploratory\b|hypothesis[-\s]generating|"
    r"warrants? (?:caution|further (?:study|validation|research|investigation))|"
    r"remains? (?:unclear|uncertain|to be (?:established|determined|confirmed))|"
    r"\blimited (?:by|generaliz\w+|sample|to|in scope)|"
    r"single[-\s](?:cent(?:er|re)|institution|site)|retrospective (?:design|nature)|"
    r"should not be (?:used|interpreted|construed)|"
    r"do(?:es)? not (?:establish|imply|permit|support|prove)|"
    r"not (?:yet )?(?:ready|validated|intended) for (?:clinical|deployment|practice)|"
    r"\bunderpowered\b|\bmodest\b|no (?:firm|strong) (?:conclusion|inference)",
    re.IGNORECASE)

# Repeated caveat motifs (HEDGE_REPEAT): family key -> regex. A family repeating across
# body + abstract above the threshold should be stated once, firmly.
MOTIFS: dict[str, re.Pattern] = {
    "no_deployable_claim": re.compile(
        r"no (?:deployable|deployment|clinical|practice|diagnostic) (?:claim|use|recommendation)|"
        r"not (?:ready|intended|validated) for (?:clinical|deployment|practice)",
        re.IGNORECASE),
    "not_generalizable": re.compile(r"not (?:be )?generaliz\w+|limited generaliz\w+", re.IGNORECASE),
    "none_evaluated_here": re.compile(
        r"(?:none|not|no \w+) (?:were |was |are |is )?evaluated (?:here|in this (?:study|work|analysis))|"
        r"not (?:assessed|examined|tested) (?:here|in this (?:study|work))", re.IGNORECASE),
    "no_causal": re.compile(r"no causal (?:claim|inference|relationship|conclusion|interpretation)", re.IGNORECASE),
    "hypothesis_generating": re.compile(r"hypothesis[-\s]generating", re.IGNORECASE),
    "interpret_with_caution": re.compile(
        r"interpret\w* with caution|should be interpreted with caution|with caution", re.IGNORECASE),
    "single_center": re.compile(r"single[-\s](?:cent(?:er|re)|institution|site)", re.IGNORECASE),
    "retrospective_design": re.compile(r"retrospective (?:design|nature|study|cohort)", re.IGNORECASE),
    "preliminary": re.compile(r"\bpreliminary\b", re.IGNORECASE),
}

# Motifs that are factual study-design descriptors rather than defensive caveats. A
# single-centre / retrospective study must state its design in Methods, and naming it
# again in the Abstract and Limitations is normal, not over-hedging. Count these only
# in the non-Methods narrative so an honestly-written single-centre retrospective study
# (the most common observational design) is not flagged for stating a true fact.
FACTUAL_DESCRIPTOR_MOTIFS = {"single_center", "retrospective_design"}

# Provenance / audit minutiae that belong in Methods or a supplement, not the narrative.
AUDIT = re.compile(
    r"\bsha-?256\b|\bmd5\b|\bchecksum\b|(?:git\s+)?(?:commit|hash|sha)\s*[:=]?\s*[0-9a-f]{7,40}\b|"
    r"\bcommit\s+[0-9a-f]{7,40}\b|\bunit[-\s]?test(?:s|ing|ed)?\b|\bpost[-\s]?lock\b|"
    r"seed\s*=\s*\d+|\brandom seed\s+\d+\b|\baudit trail\b|"
    r"reproducibility (?:manifest|hash|record)|data lock(?:ed)? on|\bcontent[-\s]hash\b",
    re.IGNORECASE)

# Robustness / sensitivity vocabulary (for BURIED_DEFENSE).
ROBUST = re.compile(
    r"sensitivity analys\w+|robustness|leave[-\s]one[-\s]out|leave[-\s]pair[-\s]out|"
    r"\bE[-\s]?value\b|remained (?:significant|robust|consistent|unchanged|stable)|"
    r"did not (?:materially |substantially |meaningfully )?(?:change|alter|differ)|"
    r"results were (?:similar|consistent|robust|unchanged)|consistent across|"
    r"after (?:excluding|adjusting for|accounting for)|tipping[-\s]point", re.IGNORECASE)

# A strong numeric token next to a robustness statement makes it Results-worthy.
NUMERIC = re.compile(
    r"\b\d+\.\d+\b|\b\d{1,3}%|95%\s*ci|(?:OR|HR|RR|AUC|aHR|aOR)\s*[=:]?\s*\d|"
    r"p\s*[<=>]\s*0?\.\d+", re.IGNORECASE)

ORDINALS = ["first", "second", "third", "fourth", "fifth", "sixth", "seventh",
            "eighth", "ninth", "tenth"]


# --------------------------------------------------------------------------- #
# Probes
# --------------------------------------------------------------------------- #

def probe_hedge_density(regions, body, threshold) -> list[dict]:
    words = word_count(body)
    if words < 80:  # too little narrative to judge density reliably
        return []
    n = len(CAVEAT.findall(body))
    density = n / words * 1000
    if density > threshold:
        return [{
            "verdict": "HEDGE_DENSITY", "severity": "Minor", "action": "TIGHTEN",
            "detail": (f"defensive-caveat density is {density:.1f} per 1,000 body words "
                       f"({n} caveat tokens / {words} words; threshold {threshold:.0f}); the "
                       f"prose hedges faster than it asserts — keep the load-bearing caveats, "
                       f"cut the reflexive ones"),
            "where": f"body narrative ({words} words)",
        }]
    return []


def probe_hedge_repeat(regions, full, threshold) -> list[dict]:
    non_methods = "\n".join(b for r, b in regions if r != "methods")
    claims = []
    for key, rx in MOTIFS.items():
        # Factual design descriptors are not over-hedging when stated in Methods;
        # count them only in the non-Methods narrative.
        hay = non_methods if key in FACTUAL_DESCRIPTOR_MOTIFS else full
        n = len(rx.findall(hay))
        if n >= threshold:
            m = rx.search(hay)
            phrase = m.group(0).strip() if m else key
            claims.append({
                "verdict": "HEDGE_REPEAT", "severity": "Minor", "action": "TIGHTEN",
                "detail": (f"the caveat '{phrase}' (motif: {key}) appears {n} times across "
                           f"the narrative; state it once, firmly, and remove the repeats"),
                "where": phrase[:120],
            })
    return claims


def probe_audit_in_body(regions) -> list[dict]:
    body = region_text(regions, BODY_NARRATIVE)
    claims = []
    seen = set()
    for m in AUDIT.finditer(body):
        tok = m.group(0).strip().lower()
        norm = re.sub(r"[0-9a-f]{7,40}", "<hash>", tok)
        if norm in seen:
            continue
        seen.add(norm)
        claims.append({
            "verdict": "AUDIT_IN_BODY", "severity": "Minor", "action": "MOVE",
            "detail": (f"provenance/audit token '{m.group(0).strip()}' appears in the "
                       f"Introduction/Results/Discussion narrative; move reproducibility "
                       f"detail to a Methods statement or a supplement"),
            "where": body[max(0, m.start() - 40):m.end() + 40].strip()[:160],
        })
    return claims


def probe_limitations_volume(regions, full, max_items) -> list[dict]:
    lim = region_text(regions, {"limitations"})
    if not lim:
        # Inline limitations paragraph inside Discussion.
        disc = region_text(regions, {"discussion", "conclusion"})
        m = re.search(r"(?:our |this )?stud(?:y|ies) (?:has|have)[^.]{0,40}limitations?|"
                      r"several (?:important )?limitations|limitations? (?:of this|warrant)",
                      disc, re.IGNORECASE)
        if not m:
            return []
        lim = disc[m.start():]
    # Count discrete items: max of ordinal markers, (N) enumerators, bullet lines.
    low = lim.lower()
    n_ord = sum(1 for o in ORDINALS if re.search(rf"(?:^|[\s(,;])\b{o}\b\s*,", low))
    n_enum = len(set(re.findall(r"\((\d{1,2})\)", lim)))
    n_bullet = len(re.findall(r"^\s*[-*]\s+\S", lim, re.MULTILINE))
    n = max(n_ord, n_enum, n_bullet)
    if n > max_items:
        return [{
            "verdict": "LIMITATIONS_VOLUME", "severity": "Minor", "action": "TIGHTEN",
            "detail": (f"the Limitations passage enumerates {n} discrete items "
                       f"(threshold {max_items}); consolidate related items so the section "
                       f"reads as honest disclosure, not a rebuttal letter"),
            "where": f"Limitations ({n} items)",
        }]
    return []


def probe_abstract_caveat_load(regions, full, max_caveats) -> list[dict]:
    abs_t = abstract_text(regions, full)
    if word_count(abs_t) < 40:
        return []
    caveat_sents = [s for s in sentences(abs_t) if CAVEAT.search(s)]
    n = len(caveat_sents)
    if n > max_caveats:
        return [{
            "verdict": "ABSTRACT_CAVEAT_LOAD", "severity": "Minor", "action": "TIGHTEN",
            "detail": (f"the Abstract carries {n} caveat-bearing clauses (threshold "
                       f"{max_caveats}); lead with the result and keep at most one or two "
                       f"essential qualifiers so the headline is not buried"),
            "where": (caveat_sents[0][:140] if caveat_sents else "Abstract"),
        }]
    return []


def probe_buried_defense(regions) -> list[dict]:
    results = region_text(regions, {"results"})
    buried_src = region_text(regions, {"limitations", "supplement"})
    if not buried_src:
        return []
    # If Results already discusses robustness, nothing is buried.
    if ROBUST.search(results):
        return []
    claims = []
    for s in sentences(buried_src):
        if ROBUST.search(s) and NUMERIC.search(s):
            claims.append({
                "verdict": "BURIED_DEFENSE", "severity": "Minor", "action": "MOVE",
                "detail": ("a numeric robustness/sensitivity result sits in the "
                           "Limitations/supplement with no robustness mention in Results; "
                           "promote it into Results — it is evidence for the finding, not a "
                           "caveat against it"),
                "where": s[:160],
            })
            break  # one promotion recommendation is enough
    return claims


# --------------------------------------------------------------------------- #
# Driver
# --------------------------------------------------------------------------- #

def check(text: str, *, hedge_per_1k: float, repeat_threshold: int,
          limitations_max: int, abstract_caveat_max: int) -> list[dict]:
    regions = segment(text)
    body = region_text(regions, BODY_NARRATIVE)
    if not body:  # no IMRAD headings — degrade to a whole-document read (minus supplement)
        body = region_text(regions, {"preamble", "other"}) or text
    claims: list[dict] = []
    claims += probe_hedge_density(regions, body, hedge_per_1k)
    claims += probe_hedge_repeat(regions, text, repeat_threshold)
    claims += probe_audit_in_body(regions)
    claims += probe_limitations_volume(regions, text, limitations_max)
    claims += probe_abstract_caveat_load(regions, text, abstract_caveat_max)
    claims += probe_buried_defense(regions)
    return claims


def analyze(manuscript: str, **kw) -> dict:
    p = Path(manuscript)
    if not p.is_file():
        sys.stderr.write(f"ERROR: manuscript not found: {manuscript}\n")
        sys.exit(2)
    claims = check(p.read_text(encoding="utf-8"), **kw)
    by_action = {"REMOVE": 0, "MOVE": 0, "TIGHTEN": 0}
    for c in claims:
        by_action[c["action"]] = by_action.get(c["action"], 0) + 1
    return {
        "manuscript": str(p),
        "claims": claims,
        "summary": {
            "n_claims": len(claims),
            "by_action": by_action,
            "verdict": "IMPRESSION_FLAGS" if claims else "OK",
        },
    }


def render(result: dict) -> str:
    lines = ["| Check | Action | Detail |", "|---|---|---|"]
    for c in result["claims"]:
        lines.append(f"| {c['verdict']} | {c['action']} | {c['detail']} |")
    if len(lines) == 2:
        lines.append("| (none) | — | narrative reads confidently; no subtraction needed |")
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(
        description="Editorial-impression / defensiveness gate (§L) — advisory, non-blocking.")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true",
                    help="accepted for CLI parity; this gate emits no Major, so it never blocks")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    ap.add_argument("--hedge-per-1k", type=float, default=10.0,
                    help="HEDGE_DENSITY: caveat tokens per 1,000 body words before firing (default 10)")
    ap.add_argument("--repeat-threshold", type=int, default=3,
                    help="HEDGE_REPEAT: motif occurrences across body+abstract before firing (default 3)")
    ap.add_argument("--limitations-max", type=int, default=6,
                    help="LIMITATIONS_VOLUME: discrete Limitations items allowed (default 6)")
    ap.add_argument("--abstract-caveat-max", type=int, default=2,
                    help="ABSTRACT_CAVEAT_LOAD: caveat clauses allowed in the Abstract (default 2)")
    args = ap.parse_args()

    result = analyze(
        args.manuscript,
        hedge_per_1k=args.hedge_per_1k,
        repeat_threshold=args.repeat_threshold,
        limitations_max=args.limitations_max,
        abstract_caveat_max=args.abstract_caveat_max,
    )

    if not args.quiet:
        print("=" * 41)
        print(" Editorial Impression / Defensiveness (§L)")
        print("=" * 41)
        print(render(result))
        print()
        s = result["summary"]
        if s["n_claims"]:
            ba = s["by_action"]
            print(f"IMPRESSION flags: {s['n_claims']} advisory finding(s) "
                  f"(REMOVE {ba['REMOVE']} / MOVE {ba['MOVE']} / TIGHTEN {ba['TIGHTEN']}). "
                  f"Non-blocking — these raise the ceiling, they do not gate submission.")
        else:
            print("OK: narrative reads confidently; no subtraction recommended.")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_editorial_impression", **result}, indent=2), encoding="utf-8")
        if not args.quiet:
            print(f"\nwrote {args.out}")

    # Advisory: never blocks. --strict is accepted for parity but this gate has no Major.
    return 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Effect-stability gate — a wide interval is a direction, not a magnitude
(self-review Phase 2.5).

The errors here are pure arithmetic on the printed cells, and two independent
reviewers hit the same number when they occur:

  1. UNSTABLE_EFFECT_ESTIMATE  an OR / HR / RR / IRR reported in the Abstract or
                               Conclusions whose 95% CI upper/lower ratio exceeds
                               ~10 (default --ratio-threshold 10). "OR 24.0; 95%
                               CI 3.0-240.0" is a 80-fold interval: the data
                               support a direction, not the point estimate. Fires
                               only when the estimate is presented as a magnitude
                               with NO co-located caveat (exploratory /
                               hypothesis-generating / underpowered / imprecise /
                               unstable / wide CI / interpret with caution) — the
                               same suppression discipline as check_null_calibration.
  2. EPV_LOW                   events / covariates < 10 (events per variable). A
                               model estimated on too few events per covariate
                               produces exactly the unstable estimates above;
                               fires only when both an event count and a covariate
                               count are printed in proximity.

Both are computable from the manuscript's own numbers. Deterministic and
conservative: it reads only the headline regions for the ratio (so a wide CI on
a clearly-labelled exploratory subgroup deep in the Results does not fire), and
it requires the caveat to be absent from the estimate's own neighbourhood.

INPUT
  --manuscript          manuscript markdown/text (required).
  --ratio-threshold N   CI upper/lower ratio above which an estimate is unstable
                        (default 10; a 10-fold interval already spans an order of
                        magnitude).

OUTPUT  (--out path)
  {"detector": "check_effect_stability", "manuscript", "claims":
     [{verdict, severity, detail, where}], "summary": {...}}
  UNSTABLE_EFFECT_ESTIMATE and EPV_LOW are Major candidates.

Stdlib-only (re / json / argparse / pathlib). Exit codes: 0 clean (or report-only),
1 a Major claim exists (with --strict), 2 input/usage error.
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

DEFAULT_RATIO_THRESHOLD = 10.0

# An effect estimate with a 95% CI: (a)OR / (a)HR / RR / IRR, point, low-high.
# Longer kinds (aOR/aHR) precede OR/HR so they match first. The gap between the
# point estimate and the CI is bounded and allowed to contain "95%" (which has
# digits), so `.` rather than `\D` is used there.
EFFECT_RE = re.compile(
    r"\b(?:adjusted\s+)?(?P<kind>aOR|aHR|OR|HR|RR|IRR)\s*[=:]?\s*"
    r"(?P<pt>[0-9]+(?:\.[0-9]+)?)"
    r".{0,22}?(?:95\s*%\s*)?(?:CI|confidence\s+interval)[^0-9]{0,5}"
    r"(?P<lo>[0-9]+(?:\.[0-9]+)?)\s*(?:[–—\-]|to)\s*(?P<hi>[0-9]+(?:\.[0-9]+)?)",
    re.IGNORECASE,
)

# A co-located caveat that acknowledges the instability: if present, the author is
# already reporting the estimate as a direction, so the gate stays silent.
INSTABILITY_CAVEAT = re.compile(
    r"exploratory|hypothesis[-\s]?generating|underpowered|imprecise|unstable|"
    r"wide\s+(?:confidence\s+interval|CI)|(?:confidence\s+interval|CI)\s+(?:is\s+)?wide|"
    r"interpret(?:ed)?\s+with\s+caution|should\s+be\s+interpreted\s+as\s+(?:a\s+)?direction|"
    r"not\s+(?:a\s+)?precise|direction(?:al)?\s+(?:rather\s+than|not)|caution",
    re.IGNORECASE,
)

# EPV operands.
EVENTS_RE = re.compile(r"\b([0-9]+)\s+events?\b", re.IGNORECASE)
COVAR_RE = re.compile(
    r"\b([0-9]+)\s+(?:covariates?|predictors?|(?:independent\s+)?variables?|"
    r"degrees?\s+of\s+freedom|parameters?)\b",
    re.IGNORECASE,
)

REGION_HEADINGS = re.compile(
    r"^#{1,4}\s*\*{0,2}(?:ABSTRACT|Abstract|CONCLUSIONS?|Conclusions?|DISCUSSION|Discussion|"
    r"Interpretation|Clinical Implications?|Summary)\*{0,2}\s*$",
    re.IGNORECASE | re.MULTILINE,
)

_COLOCATE_WINDOW = 160   # chars each side of an estimate searched for a caveat
_EPV_WINDOW = 130        # chars between an event count and a covariate count


def headline_region(text: str) -> str:
    """Title + Abstract + Conclusion/Discussion regions + inline 'Conclusion:'
    clauses. Fallback: whole text. (Mirrors check_null_calibration.)"""
    spans: list[str] = []
    mt = re.search(r"^#{1,6}\s+(.+)$", text, re.MULTILINE)
    if mt:
        spans.append(mt.group(1))
    else:
        for line in text.splitlines():
            if line.strip():
                spans.append(line.strip())
                break
    all_headings = [m.start() for m in re.finditer(r"^#{1,4}\s", text, re.MULTILINE)]
    for m in REGION_HEADINGS.finditer(text):
        s = m.end()
        nxt = next((h for h in all_headings if h > s), len(text))
        spans.append(text[s:nxt])
    for m in re.finditer(r"(?:^|\n)\s*\*{0,2}(?:Conclusions?|Interpretation)\*{0,2}\s*[:.]\s*(.+?)(?:\n\n|$)",
                         text, re.IGNORECASE | re.DOTALL):
        spans.append(m.group(1))
    if not spans:
        spans.append(text)
    return "\n".join(spans)


def check(text: str, ratio_threshold: float = DEFAULT_RATIO_THRESHOLD) -> list[dict]:
    claims: list[dict] = []

    # 1. UNSTABLE_EFFECT_ESTIMATE — headline regions only.
    region = headline_region(text)
    seen: set[str] = set()
    for m in EFFECT_RE.finditer(region):
        lo, hi = float(m.group("lo")), float(m.group("hi"))
        if lo <= 0 or hi <= lo:
            continue
        ratio = hi / lo
        if ratio <= ratio_threshold:
            continue
        window = region[max(0, m.start() - _COLOCATE_WINDOW):m.end() + _COLOCATE_WINDOW]
        if INSTABILITY_CAVEAT.search(window):
            continue  # the author already flags this estimate as unstable
        key = m.group(0).lower()
        if key in seen:
            continue
        seen.add(key)
        claims.append({
            "verdict": "UNSTABLE_EFFECT_ESTIMATE",
            "severity": "Major",
            "detail": (f"{m.group('kind').upper()} {m.group('pt')} has a 95% CI "
                       f"{m.group('lo')}-{m.group('hi')} spanning {ratio:.0f}-fold "
                       f"(> {ratio_threshold:g}x) in the Abstract/Conclusions with no co-located "
                       f"caveat; a {ratio:.0f}-fold interval supports a direction, not the point "
                       f"estimate — report it as such or add an imprecision/exploratory caveat"),
            "where": m.group(0).replace("\n", " ").strip()[:160],
        })

    # 2. EPV_LOW — an event count and a covariate count printed in proximity.
    for em in EVENTS_RE.finditer(text):
        events = int(em.group(1))
        win = text[em.start():em.end() + _EPV_WINDOW]
        cm = COVAR_RE.search(win)
        if not cm:
            # also look just before the event count
            win2 = text[max(0, em.start() - _EPV_WINDOW):em.start()]
            cm = COVAR_RE.search(win2)
        if not cm:
            continue
        covar = int(cm.group(1))
        if covar <= 0:
            continue
        epv = events / covar
        if epv >= 10:
            continue
        claims.append({
            "verdict": "EPV_LOW",
            "severity": "Major",
            "detail": (f"{events} events for {covar} covariates is {epv:.1f} events per variable "
                       f"(< 10); the model is underpowered for stable coefficient estimation — "
                       f"reduce covariates, use penalisation, or report the estimates as exploratory"),
            "where": text[em.start():em.start() + 120].replace("\n", " ").strip()[:160],
        })
        break  # one EPV finding is enough; the first printed pair is representative

    return claims


def analyze(manuscript: str, ratio_threshold: float = DEFAULT_RATIO_THRESHOLD) -> dict:
    p = Path(manuscript)
    if not p.is_file():
        sys.stderr.write(f"ERROR: manuscript not found: {manuscript}\n")
        sys.exit(2)
    claims = check(p.read_text(encoding="utf-8"), ratio_threshold=ratio_threshold)
    n_major = sum(1 for c in claims if c["severity"] == "Major")
    return {
        "manuscript": str(p),
        "claims": claims,
        "summary": {
            "n_claims": len(claims),
            "n_major": n_major,
            "n_flag": len(claims) - n_major,
            "verdict": "MAJOR_CANDIDATE" if n_major else "OK",
        },
    }


def render(result: dict) -> str:
    lines = ["| Check | Severity | Detail |", "|---|---|---|"]
    for c in result["claims"]:
        lines.append(f"| {c['verdict']} | {c['severity']} | {c['detail']} |")
    if len(lines) == 2:
        lines.append("| (none) | — | no headline estimate has an order-of-magnitude interval |")
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(description="Effect-stability gate (Phase 2.5).")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--ratio-threshold", type=float, default=DEFAULT_RATIO_THRESHOLD,
                    help="CI upper/lower ratio above which an estimate is unstable (default %(default)s)")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true", help="exit 1 if any Major claim exists")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    args = ap.parse_args()

    result = analyze(args.manuscript, ratio_threshold=args.ratio_threshold)

    if not args.quiet:
        print("=" * 41)
        print(" Effect Stability (Phase 2.5)")
        print("=" * 41)
        print(render(result))
        print()
        s = result["summary"]
        if s["n_major"]:
            print(f"MAJOR candidate: {s['n_major']} unstable effect estimate / low-EPV finding(s).")
        else:
            print("OK: no headline estimate spans an order of magnitude without a caveat.")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_effect_stability", **result}, indent=2),
                                  encoding="utf-8")
        if not args.quiet:
            print(f"\nwrote {args.out}")

    return 1 if (args.strict and result["summary"]["n_major"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Inline-emphasis over-use gate — a typographic AI tell (self-review §J / humanize P25).

LLM-drafted prose over-uses inline italic emphasis: single-word italics
(*into*, *passive*, *same*), whole-clause italics (*a redesign of the relationship
itself*), and mid-paragraph signposting. A human copy-editor strips almost all of it.
This gate counts NON-allowlisted italic emphasis spans per 1,000 body words and flags
an over-dense manuscript.

Verdict:
  EMPHASIS_OVERUSE (Minor)  italic-emphasis density exceeds the threshold after an
                            allowlist of legitimate italics (statistical symbols,
                            Latin phrases, journal/species terms) is removed.
                            Escalation note added when a span is a whole clause
                            (a long italic phrase, the strongest tell).

Scope, by construction, to keep false positives low on a widely-used skill:
  * Only ITALIC (`*...*`) spans count. Bold (`**...**`) is NOT counted — a bold
    run-in lead-in ("**Study design.**") is a legitimate Nature/npj subheading style
    (manuscript-style-classical §1.2), so counting it would fight another rule.
  * Fenced code blocks and allowlisted italics are excluded.
  * Fires only when both the density AND the raw count clear a floor, so a short
    note with one stray italic never trips it.

Exit codes: 0 clean/report-only, 1 with --strict when any Major (none — Minor only),
2 usage. Stdlib-only.

Usage:
    python3 check_emphasis_density.py --manuscript manuscript.md \
        [--out qc/emphasis_density.json] [--per-1000 5.0] [--strict] [--quiet]
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

# An italic span: single * ... * that is not part of a ** ... ** bold span.
ITALIC_RE = re.compile(r"(?<!\*)\*(?!\*)([^*\n]{1,120}?)\*(?!\*)")
FENCE_RE = re.compile(r"```.*?```", re.S)
WORD_RE = re.compile(r"[A-Za-z0-9']+")

# Legitimate italics that must NOT count toward the tell.
LATIN = {
    "in vivo", "in vitro", "ex vivo", "in situ", "in silico", "de novo", "post hoc",
    "a priori", "a posteriori", "et al", "et al.", "vs", "vs.", "versus", "i.e.",
    "e.g.", "per se", "et cetera", "ad hoc", "in utero", "in toto", "c-index",
}
# Single statistical symbols routinely italicised (P, t, r, n, F, z, d, k, R, b).
STAT_SYMBOL = re.compile(r"^[A-Za-z](?:[\s=<>²]|$)|^[A-Za-z]\s*[<>=]")
# A stat clause: an italic that is just a symbol + operator + number (e.g. "P = .03").
STAT_CLAUSE = re.compile(r"^[A-Za-z]\s*[=<>]\s*[.\d]")


def _is_allowlisted(span: str) -> bool:
    s = span.strip()
    low = s.strip(".,;:").lower()
    if low in LATIN:
        return True
    if len(s) <= 2:                       # single letter / symbol (P, t, n, β)
        return True
    if STAT_SYMBOL.match(s) or STAT_CLAUSE.match(s):
        return True
    # a species / gene-like token: single capitalised italic word with no space
    if " " not in s and re.fullmatch(r"[A-Za-z][A-Za-z0-9\-]+", s) and s[:1].isupper():
        # allow only if it looks like a proper noun/gene, not a plain emphasised word
        return bool(re.search(r"[A-Z].*[a-z].*[A-Z]|[0-9]", s))  # e.g. BRCA1, TP53
    return False


def check(text: str, per_1000: float) -> list[dict]:
    body = FENCE_RE.sub(" ", text)
    n_words = len(WORD_RE.findall(body))
    if n_words == 0:
        return []
    spans = [m.group(1) for m in ITALIC_RE.finditer(body)]
    flagged = [s for s in spans if not _is_allowlisted(s)]
    n = len(flagged)
    density = n * 1000.0 / n_words
    if n < 5 or density <= per_1000:
        return []
    whole_clause = [s for s in flagged if len(WORD_RE.findall(s)) >= 6]
    detail = (f"{n} non-allowlisted italic emphasis spans in {n_words} body words "
              f"({density:.1f}/1000 > {per_1000:.1f} threshold) — an LLM typographic "
              f"tell; a human editor removes almost all inline emphasis")
    if whole_clause:
        detail += (f". {len(whole_clause)} are whole-clause italics (e.g. "
                   f"\"*{whole_clause[0][:48]}*\") — the strongest tell; rewrite without italics")
    return [{
        "verdict": "EMPHASIS_OVERUSE",
        "severity": "Minor",
        "detail": detail,
        "where": ", ".join(f"*{s[:24]}*" for s in flagged[:6]),
    }]


def analyze(manuscript: str, per_1000: float) -> dict:
    p = Path(manuscript)
    if not p.is_file():
        sys.stderr.write(f"ERROR: manuscript not found: {manuscript}\n")
        sys.exit(2)
    claims = check(p.read_text(encoding="utf-8"), per_1000)
    return {
        "manuscript": str(p),
        "claims": claims,
        "summary": {"n_claims": len(claims), "n_major": 0, "n_flag": len(claims),
                    "verdict": "REVIEW" if claims else "OK"},
    }


def render(result: dict) -> str:
    lines = ["| Check | Severity | Detail |", "|---|---|---|"]
    for c in result["claims"]:
        lines.append(f"| {c['verdict']} | {c['severity']} | {c['detail']} |")
    if len(lines) == 2:
        lines.append("| (none) | — | inline-emphasis density within human range |")
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(
        description="Inline-emphasis over-use gate — a typographic AI tell (§J / humanize P25).")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--per-1000", type=float, default=5.0,
                    help="italic-emphasis spans per 1000 words that trips the flag (default 5)")
    ap.add_argument("--strict", action="store_true",
                    help="exit 1 if any Major (none — this gate is Minor-only)")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    args = ap.parse_args()

    result = analyze(args.manuscript, args.per_1000)

    if not args.quiet:
        print("=" * 42)
        print(" Inline-emphasis over-use (§J / P25)")
        print("=" * 42)
        print(render(result))
        print()
        n = result["summary"]["n_flag"]
        print("REVIEW: emphasis over-use." if n else "OK: inline-emphasis density within human range.")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_emphasis_density", **result}, indent=2), encoding="utf-8")
        if not args.quiet:
            print(f"\nwrote {args.out}")

    return 1 if (args.strict and result["summary"]["n_major"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Orphan figure / table gate — every numbered float must be cited in the body
(self-review Phase 2.5d cross-reference).

A figure or table that has a legend/caption but is never cited in the running text
is an "orphan": a reviewer or production editor flags it, and a journal may refuse
the float. This gate cross-checks each declared "Figure N." / "Table N." caption
against at least one in-text "Figure N" / "Table N" citation elsewhere in the body.

Verdict:
  FIGURE_ORPHAN (Minor)  a figure with a caption "Figure N." has no in-text
                         "Figure N" / "Fig. N" citation anywhere outside its caption.
  TABLE_ORPHAN  (Minor)  the same for a "Table N." caption.
  FIGURE_NOT_EMBEDDED    the manuscript has figure captions but NO markdown image link
        (Minor;          (`![...](...)`) anywhere, so every figure is captioned yet
   Major w/ --require-   absent from the rendered output — the "complete" submission that
   embedded)             ships with the legends and none of the pictures. Advisory by
                         default (a drafting manuscript may keep figures as separate
                         files); --require-embedded (the submission preflight) makes it
                         Major. Conservative: fires only when ZERO images are embedded,
                         never a per-figure guess, so it stays silent once any figure is
                         embedded.

Deterministic and caption-anchored: a line beginning "Figure N." / "Table N." (with
optional **bold**) DECLARES float N; any "Figure N" / "Table N" mention on a
DIFFERENT line CITES it. A float declared but never cited elsewhere is the orphan.
This needs no section-boundary heuristic — the caption line itself is the anchor, so
a caption that happens to reference another float still counts as citing that other
float.

Exit codes: 0 clean/report-only, 1 with --strict when any Major, 2 usage. Major is reachable two
ways: FIGURE_ATTR_STALE is Major unconditionally, and FIGURE_NOT_EMBEDDED escalates to Major under
--require-embedded. (This line used to read "none — Minor only", which was stale in the direction
that matters: it described a submission-adjacent gate as unable to block.) Stdlib-only.

Usage:
    python3 check_figure_citation.py --manuscript manuscript.md \
        [--out qc/figure_citation.json] [--strict] [--quiet]
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

# A caption/legend line: (optional **) Figure|Table N (.|:) ...
CAPTION_RE = re.compile(r"^\s*\*{0,2}\s*(?P<kind>Figure|Fig\.?|Table)\s+(?P<num>\d+)\s*[.:]", re.I)
# Any in-text mention: Figure N / Fig N / Fig. N / Table N (+ "Figures 1 and 2" heads),
# with an OPTIONAL single-letter panel suffix so "Figure 3a" / "(Figure 3b)" registers
# as citing Figure 3 (multi-panel figures are cited only by panel, and without this the
# num-then-\b never matched "3a"). Panels never appear in CAPTION_RE ("Figure 3." names
# the whole float), so caption<->citation correspondence is preserved; the trailing \b
# after the optional letter keeps "Figure 3rd" / "3mg" from matching (no boundary
# between the letter and a following word char).
MENTION_RE = re.compile(r"\b(?P<kind>Figures?|Figs?\.?|Tables?)\s+(?P<num>\d+)(?P<panel>[a-zA-Z])?\b", re.I)
# A markdown image embed: ![alt](path). Its presence is how a figure reaches the
# rendered output; a manuscript with figure captions but zero image links ships
# with every legend and no picture.
IMG_LINK_RE = re.compile(r"!\[[^\]]*\]\([^)]+\)")
# The author-contributions / CRediT heading.
CREDIT_HEADING_RE = re.compile(
    r"^#{1,6}\s*\*{0,2}\s*(?:Authors?[’'\s]*\s*[Cc]ontributions?|CRediT[^\n]*)\*{0,2}\s*:?\s*$",
    re.MULTILINE)


def _kind(raw: str) -> str:
    return "Table" if raw.lower().startswith("tab") else "Figure"


def check(text: str, require_embedded: bool = False) -> list[dict]:
    lines = text.splitlines()
    declared: dict[tuple[str, int], int] = {}   # (kind, num) -> caption line index
    for i, line in enumerate(lines):
        m = CAPTION_RE.match(line)
        if m:
            declared.setdefault((_kind(m.group("kind")), int(m.group("num"))), i)

    cited: set[tuple[str, int]] = set()
    for i, line in enumerate(lines):
        for m in MENTION_RE.finditer(line):
            key = (_kind(m.group("kind")), int(m.group("num")))
            # a mention on any line other than this float's own caption line = a citation
            if declared.get(key) != i:
                cited.add(key)

    claims = []
    for (kind, num), cap_line in sorted(declared.items(), key=lambda kv: (kv[0][0], kv[0][1])):
        if (kind, num) in cited:
            continue
        claims.append({
            "verdict": "TABLE_ORPHAN" if kind == "Table" else "FIGURE_ORPHAN",
            "severity": "Minor",
            "detail": (f"{kind} {num} has a caption (line {cap_line + 1}) but is never cited "
                       f"in the body; add an in-text '{kind} {num}' citation or remove the float"),
            "where": lines[cap_line].strip()[:120],
        })

    # FIGURE_NOT_EMBEDDED: captioned figures but no image link anywhere in the file.
    # Conservative on purpose (only the zero-embed case, never a per-figure guess) so
    # it stays silent whenever any figure is embedded. Tables are inline markdown, not
    # embedded images, so they are exempt.
    figures = sorted((n, ln) for (k, n), ln in declared.items() if k == "Figure")
    if figures and not IMG_LINK_RE.search(text):
        # Advisory by default: a markdown manuscript with figures kept as separate
        # attachment files legitimately embeds no image. --require-embedded (the
        # submission preflight) escalates to Major, where captions-with-no-picture
        # is the "complete package that ships with the legends and none of the
        # figures" failure.
        sev = "Major" if require_embedded else "Minor"
        # ONE claim, because the condition above is document-level: `not IMG_LINK_RE.search(text)`
        # is true or false for the whole manuscript, never per figure. Emitting it once per caption
        # repeated a single fact N times — on the repo's own demo manuscripts, 8 claims for 3
        # documents — which inflates every count downstream that treats a claim as a finding.
        nums = ", ".join(f"Figure {n}" for n, _ in figures)
        claims.append({
            "verdict": "FIGURE_NOT_EMBEDDED",
            "severity": sev,
            "detail": (f"no image is embedded anywhere in the manuscript, while {len(figures)} "
                       f"figure(s) are captioned ({nums}); confirm they are embedded or attached "
                       f"as separate files before submission"),
            "where": lines[figures[0][1]].strip()[:120],
        })

    # Author-contributions / CRediT figure-number attribution. A "prepared Figure 4"
    # attribution silently breaks when figures are renumbered or merged; the canonical
    # CRediT "Visualization" role carries no numbers and is drift-proof. Scanned ONLY
    # inside the author-contributions/CRediT section (never Results/Discussion, where
    # "Figure N" is a normal citation).
    cm = CREDIT_HEADING_RE.search(text)
    if cm:
        start = cm.end()
        nxt = re.search(r"^#{1,6}\s", text[start:], re.MULTILINE)
        region = text[start: start + nxt.start()] if nxt else text[start:]
        declared_fignums = {n for (k, n) in declared if k == "Figure"}
        fig_tokens = [int(m.group("num")) for m in MENTION_RE.finditer(region)
                      if _kind(m.group("kind")) == "Figure"]
        if fig_tokens:
            claims.append({
                "verdict": "AUTHOR_CONTRIB_FIGURE_REF",
                "severity": "Minor",
                "detail": ("the author-contributions/CRediT section attributes work by figure number "
                           "(e.g. 'prepared Figure N'); this attribution breaks on any figure renumber or "
                           "merge — use the CRediT 'Visualization' role, which carries no figure numbers"),
                "where": "author contributions",
            })
            for num in sorted(set(fig_tokens)):
                if num not in declared_fignums:
                    claims.append({
                        "verdict": "FIGURE_ATTR_STALE",
                        "severity": "Major",
                        "detail": (f"the author-contributions/CRediT section attributes Figure {num}, but no "
                                   f"Figure {num} is declared in the manuscript — a stale attribution left by a "
                                   f"figure renumber/merge (declared figures: "
                                   f"{', '.join(str(n) for n in sorted(declared_fignums)) or 'none'})"),
                        "where": "author contributions",
                    })
    return claims


def analyze(manuscript: str, require_embedded: bool = False) -> dict:
    p = Path(manuscript)
    if not p.is_file():
        sys.stderr.write(f"ERROR: manuscript not found: {manuscript}\n")
        sys.exit(2)
    claims = check(p.read_text(encoding="utf-8"), require_embedded=require_embedded)
    n_major = sum(1 for c in claims if c["severity"] == "Major")
    # Counted BY VERDICT, because the summary line names a kind of defect and `n_major`/`n_flag`
    # name a severity. This detector emits five verdicts, only two of which are orphans, so
    # "n_flag orphan float(s)" described the wrong thing whenever a non-orphan was the finding —
    # on the repo's own demo manuscripts it printed "3 orphan float(s)" with zero orphans present.
    n_orphan = sum(1 for c in claims if c["verdict"] in ("FIGURE_ORPHAN", "TABLE_ORPHAN"))
    n_not_embedded = sum(1 for c in claims if c["verdict"] == "FIGURE_NOT_EMBEDDED")
    return {
        "manuscript": str(p),
        "claims": claims,
        "summary": {
            "n_claims": len(claims),
            "n_major": n_major,
            "n_flag": len(claims) - n_major,
            "n_orphan": n_orphan,
            "n_not_embedded": n_not_embedded,
            "verdict": "MAJOR_CANDIDATE" if n_major else ("REVIEW" if claims else "OK"),
        },
    }


def render(result: dict) -> str:
    lines = ["| Check | Severity | Detail |", "|---|---|---|"]
    for c in result["claims"]:
        lines.append(f"| {c['verdict']} | {c['severity']} | {c['detail']} |")
    if len(lines) == 2:
        lines.append("| (none) | — | every captioned figure/table is cited in the body |")
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(
        description="Orphan figure/table gate — captioned floats must be cited (Phase 2.5d).")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true",
                    help="exit 1 if any Major (a captioned figure with no embedded image under --require-embedded)")
    ap.add_argument("--require-embedded", action="store_true",
                    help="submission context: escalate FIGURE_NOT_EMBEDDED to Major (figures must be "
                         "embedded in the manuscript, not kept as separate files)")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    args = ap.parse_args()

    result = analyze(args.manuscript, require_embedded=args.require_embedded)

    if not args.quiet:
        print("=" * 44)
        print(" Orphan figure / table citation (§2.5d)")
        print("=" * 44)
        print(render(result))
        print()
        s = result["summary"]
        # Say what was found, by name. Each part appears only when it happened, so the line can no
        # longer report a count of a thing that is not there.
        parts = []
        if s["n_orphan"]:
            parts.append(f"{s['n_orphan']} orphan float(s)")
        if s["n_not_embedded"]:
            parts.append("no image embedded for the captioned figure(s)")
        other = s["n_claims"] - s["n_orphan"] - s["n_not_embedded"]
        if other:
            parts.append(f"{other} other finding(s)")
        if parts:
            level = "MAJOR" if s["n_major"] else "REVIEW"
            print(f"{level}: " + "; ".join(parts) + ".")
        else:
            print("OK: every captioned float is cited and embedded.")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_figure_citation", **result}, indent=2), encoding="utf-8")
        if not args.quiet:
            print(f"\nwrote {args.out}")

    return 1 if (args.strict and result["summary"]["n_major"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Incorporation-bias gate — the reference standard and a reported predictor are
the same construct (self-review Phase 2.5, category B. Reference Standard).

A reference standard defined by lesion trajectory can overlap with a trajectory
predictor. If absence of growth defines a benign outcome, an association between
growth and malignancy can be partly definitional rather than independent
predictive evidence.

This is textbook incorporation bias, and its commonest form — a size/trajectory
reference standard with a size/trajectory predictor — is deterministic from the
Methods and Results text alone:

  INCORPORATION_BIAS (Major)  the reference-standard / outcome DEFINITION is stated
                              in trajectory terms (resolution, regression, decrease,
                              stability, no growth, progression, growth), AND a
                              variable reported as *associated with* the outcome
                              (carrying an OR/HR/RR or "associated with / predictor
                              of") is itself a trajectory variable (growth, interval
                              change, increase/decrease in size). The predictor is
                              not independent of the reference standard.

Deterministic and conservative. It reads trajectory tokens ONLY from the
reference-standard/outcome-defining sentences (not an incidental "we measured
growth rate" in Methods), requires the reported association to name the outcome
in the same sentence, and stays silent when the manuscript already discloses the
overlap ("incorporation bias", "partly definitional", "not independent of the
reference standard"). It deliberately covers only the trajectory sub-class; the
broader "framework-under-validation supplied the endpoint" instances are left to
the prose review probes, which are not deterministic from text alone.

INPUT   --manuscript  manuscript markdown/text (required).
OUTPUT  (--out path) {"detector": "check_incorporation_bias", "manuscript",
          "claims":[{verdict, severity, detail, where}], "summary":{...}}

Stdlib-only (re / json / argparse / pathlib). Exit codes: 0 clean (or report-only),
1 a Major claim exists (with --strict), 2 input/usage error.
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

# A reference-standard / outcome DEFINING heading.
REF_HEADING_RE = re.compile(
    r"^#{1,4}\s*\*{0,2}\s*(?:Reference standard|Outcome(?: definition| assessment| measure)?|"
    r"Ground truth|Gold standard|Definition of (?:benign|malignan\w+|the outcome))\*{0,2}\s*:?\s*$",
    re.IGNORECASE | re.MULTILINE)

# A sentence that DEFINES the benign/malignant outcome or the reference standard.
REF_CUE_SENTENCE_RE = re.compile(
    r"[^.\n]*\b(?:classified (?:as )?(?:benign|malignan\w+)"
    r"|(?:benign|malignan\w+)\s+(?:was|were|is|are)?\s*(?:defined|classified|confirmed|considered)"
    r"|reference standard (?:was|were|comprised|consisted|included|is|are)"
    r"|benign if|malignan\w+ if)\b[^.\n]*\.",
    re.IGNORECASE)

# Trajectory / size-change vocabulary — the family that a size reference standard
# and a size predictor share.
TRAJECTORY_RE = re.compile(
    r"\b(?:complete\s+)?resolution\b|\bregress\w+|\bdecreas\w+|\bshrink\w+|\bshrank\b|\bstabilit\w+"
    r"|\bstable\b|\bno growth\b|\bnot? grow\w*|\bunchanged\b|\bgrowth\b|\bgrew\b|\bgrow\w+"
    r"|\bprogress\w+|\benlarg\w+|increas\w+\s+in\s+(?:size|diameter)|interval change|size change"
    r"|\btrajector\w+", re.IGNORECASE)

# An association marker: a reported effect measure or "associated with / predictor of".
ASSOC_MARKER_RE = re.compile(
    r"\b(?:a?OR|a?HR|RR|odds ratio|hazard ratio|risk ratio)\b"
    r"|associated with|predictor of|risk factor for|predict\w*\s+(?:malignan|the outcome)",
    re.IGNORECASE)

# A trajectory-named PREDICTOR variable.
PREDICTOR_TRAJ_RE = re.compile(
    r"\bgrowth\b|\bgrew\b|interval change|size change|change in (?:size|diameter)"
    r"|increas\w+\s+in\s+(?:size|diameter)|\bdecreas\w+|\bresolution\b|\btrajector\w+|\benlarg\w+",
    re.IGNORECASE)

# The outcome named in the association sentence.
OUTCOME_RE = re.compile(r"malignan\w+|\bbenign\b|\bcancer\b|carcinoma|the outcome", re.IGNORECASE)

# The manuscript already names the overlap — do not fire.
DISCLOSURE_RE = re.compile(
    r"incorporation bias|partly definitional|not independent of the reference standard"
    r"|circular by construction|definitional(?:ly)?\s+(?:linked|related|confounded)|"
    r"by construction (?:linked|related|not independent)",
    re.IGNORECASE)

_SENT_SPLIT = re.compile(r"(?<=[.!?])\s+(?=[A-Z(\"'])")


def _ref_standard_text(text: str) -> str:
    spans = []
    all_h = [m.start() for m in re.finditer(r"^#{1,4}\s", text, re.MULTILINE)]
    for m in REF_HEADING_RE.finditer(text):
        s = m.end()
        nxt = next((h for h in all_h if h > s), len(text))
        spans.append(text[s:nxt])
    for m in REF_CUE_SENTENCE_RE.finditer(text):
        spans.append(m.group(0))
    return "\n".join(spans)


def check(text: str) -> list[dict]:
    if DISCLOSURE_RE.search(text):
        return []  # the overlap is disclosed; not a hidden incorporation bias
    ref_text = _ref_standard_text(text)
    if not ref_text or not TRAJECTORY_RE.search(ref_text):
        return []  # the reference standard is not trajectory-defined
    for block in re.split(r"\n\s*\n|\n#{1,6}\s", text):
        for sent in _SENT_SPLIT.split(block):
            if (ASSOC_MARKER_RE.search(sent) and PREDICTOR_TRAJ_RE.search(sent)
                    and OUTCOME_RE.search(sent)):
                pm = PREDICTOR_TRAJ_RE.search(sent)
                return [{
                    "verdict": "INCORPORATION_BIAS",
                    "severity": "Major",
                    "detail": (f"the reference standard defines the outcome by size trajectory "
                               f"(resolution / decrease / stability / growth), and '{pm.group(0)}' — a "
                               f"trajectory variable — is reported as associated with the outcome: the "
                               f"predictor is built into the reference standard, so the association is "
                               f"partly definitional. Use a predictor independent of the reference "
                               f"standard, or disclose the overlap explicitly"),
                    "where": sent.strip().replace("\n", " ")[:160],
                }]
    return []


def analyze(manuscript: str) -> dict:
    p = Path(manuscript)
    if not p.is_file():
        sys.stderr.write(f"ERROR: manuscript not found: {manuscript}\n")
        sys.exit(2)
    claims = check(p.read_text(encoding="utf-8"))
    n_major = sum(1 for c in claims if c["severity"] == "Major")
    return {
        "manuscript": str(p),
        "claims": claims,
        "summary": {"n_claims": len(claims), "n_major": n_major,
                    "n_flag": len(claims) - n_major,
                    "verdict": "MAJOR_CANDIDATE" if n_major else "OK"},
    }


def render(result: dict) -> str:
    lines = ["| Check | Severity | Detail |", "|---|---|---|"]
    for c in result["claims"]:
        lines.append(f"| {c['verdict']} | {c['severity']} | {c['detail']} |")
    if len(lines) == 2:
        lines.append("| (none) | — | reference standard and reported predictors are independent |")
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(description="Incorporation-bias gate (Phase 2.5, reference standard).")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true", help="exit 1 if any Major claim exists")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    args = ap.parse_args()

    result = analyze(args.manuscript)
    if not args.quiet:
        print("=" * 41)
        print(" Incorporation Bias (Phase 2.5)")
        print("=" * 41)
        print(render(result))
        print()
        s = result["summary"]
        print(f"MAJOR candidate: {s['n_major']} incorporation-bias finding(s)." if s["n_major"]
              else "OK: reference standard and reported predictors are independent.")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_incorporation_bias", **result}, indent=2),
                                  encoding="utf-8")
        if not args.quiet:
            print(f"\nwrote {args.out}")

    return 1 if (args.strict and result["summary"]["n_major"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""check_nested_group_comparison.py — flag a baseline/characteristics table that
reports a P value comparing an analysed subset against the parent cohort that
contains it.

When authors answer a selection-bias comment with a "representativeness" table,
they routinely compare the analysed subset (n=33) with the "full cohort" (n=132)
that *includes* those 33 patients, and print P values from it. The two groups are
nested, so the two-group test is not merely uninformative — it is invalid. The
informative contrast is subset vs remainder (n=99). This is deterministic: the
column headers announce the two n's and their labels verbatim.

Fires when a table has (a) two column headers each carrying an ``n = N``, (b) one
header labelled subset/sub-cohort/correlated/analysed/surgical/pathology and the
other labelled full/total/overall/entire/whole cohort, and (c) a P-value column.
Also on prose of the form "compared … between the … subset and the … cohort".

Stdlib-only. Reads the manuscript, never writes it.

Usage:
  python3 check_nested_group_comparison.py --manuscript paper.md [--strict] [--quiet] [--json]
Exit: 0 clean; with --strict, 1 on any NESTED_GROUP_TEST; 2 on input/usage error.
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from dataclasses import dataclass, field, asdict

HEADER_N_RE = re.compile(r"\bn\s*=\s*([0-9][0-9,]*)", re.I)
SUBSET_RE = re.compile(r"\b(subset|sub-?cohort|correlated|analy[sz]ed|surgical|patholog\w*|resected|with .*patholog)", re.I)
FULL_RE = re.compile(r"\b(full|total|overall|entire|whole)\b", re.I)
REMAINDER_RE = re.compile(r"\b(remainder|remaining|rest of|excluded|non-)", re.I)
PVAL_HEADER_RE = re.compile(r"^\s*\*?\s*[Pp]\s*(?:[- ]?value)?\s*\*?\s*$")
PVAL_HEADER_CONTAINS = re.compile(r"\bp[- ]?value\b", re.I)
SEP_RE = re.compile(r"^\s*\|?[\s:|-]*-[\s:|-]*\|?\s*$")
PROSE_RE = re.compile(
    r"compar\w+\b[^.]*\bbetween\b[^.]*\b(subset|sub-?cohort|analy[sz]ed[^.]*?)\b[^.]*\b(full|entire|total|whole)\s+cohort",
    re.I)


@dataclass
class Finding:
    kind: str
    severity: str
    line: int
    detail: str


@dataclass
class Report:
    source: str
    findings: list[Finding] = field(default_factory=list)

    @property
    def n_flag(self) -> int:
        return sum(1 for f in self.findings if f.kind == "NESTED_GROUP_TEST")

    @property
    def verdict(self) -> str:
        return "NESTED COMPARISON FOUND" if self.n_flag else "OK"


def _split_row(line: str) -> list[str]:
    s = line.strip()
    if s.startswith("|"):
        s = s[1:]
    if s.endswith("|"):
        s = s[:-1]
    return [c.strip() for c in s.split("|")]


def _tables(text: str):
    lines = text.splitlines()
    i, n = 0, len(lines)
    while i < n:
        if "|" in lines[i] and i + 1 < n and SEP_RE.match(lines[i + 1]) and "-" in lines[i + 1]:
            yield _split_row(lines[i]), i + 1
            i += 2
        else:
            i += 1


def audit(text: str, source: str) -> Report:
    rep = Report(source=source)
    for header, lineno in _tables(text):
        n_cols = [(j, h, int(m.group(1).replace(",", "")))
                  for j, h in enumerate(header) if (m := HEADER_N_RE.search(h))]
        if len(n_cols) < 2:
            continue
        has_p = any(PVAL_HEADER_RE.match(h) or PVAL_HEADER_CONTAINS.search(h) for h in header)
        if not has_p:
            continue
        subset_cols = [(j, h, nv) for j, h, nv in n_cols if SUBSET_RE.search(h)]
        full_cols = [(j, h, nv) for j, h, nv in n_cols
                     if FULL_RE.search(h) and not REMAINDER_RE.search(h)]
        if subset_cols and full_cols:
            s = min(subset_cols, key=lambda c: c[2])
            f = max(full_cols, key=lambda c: c[2])
            if s[2] < f[2]:  # subset smaller than the cohort that names it
                rep.findings.append(Finding(
                    "NESTED_GROUP_TEST", "MAJOR", lineno,
                    f"P-value table compares subset '{s[1]}' (n={s[2]}) against "
                    f"'{f[1]}' (n={f[2]}) that contains it — nested groups; the valid "
                    f"contrast is subset vs remainder (n={f[2] - s[2]})"))
    for m in PROSE_RE.finditer(text):
        line = text.count("\n", 0, m.start()) + 1
        rep.findings.append(Finding(
            "NESTED_GROUP_TEST", "MAJOR", line,
            f"prose compares a subset against the full cohort that contains it: "
            f"\"{m.group(0)[:90]}…\""))
    return rep


def format_report(rep: Report, color: bool) -> str:
    tag = {"OK": "\033[92m", "NESTED COMPARISON FOUND": "\033[91m"}.get(rep.verdict, "") if color else ""
    end = "\033[0m" if color else ""
    out = [f"{tag}== {rep.verdict} =={end}  {rep.source}", f"nested_comparisons={rep.n_flag}"]
    if not rep.findings:
        out.append("no subset-vs-parent-cohort P-value comparison detected.")
        return "\n".join(out)
    for f in sorted(rep.findings, key=lambda x: (x.line, x.detail)):
        out.append(f"[{f.severity}] {f.kind} L{f.line}  {f.detail}")
    return "\n".join(out)


def main(argv: list[str] | None = None) -> int:
    ap = argparse.ArgumentParser(description=__doc__,
                                 formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--strict", action="store_true", help="exit 1 on any NESTED_GROUP_TEST")
    ap.add_argument("--quiet", action="store_true", help="suppress the report; exit code only")
    ap.add_argument("--json", action="store_true", help="emit JSON instead of a text report")
    args = ap.parse_args(argv)
    try:
        text = open(args.manuscript, encoding="utf-8").read()
    except OSError as e:
        print(f"error: cannot read manuscript: {e}", file=sys.stderr)
        return 2
    rep = audit(text, args.manuscript)
    if not args.quiet:
        if args.json:
            print(json.dumps({"detector": "check_nested_group_comparison", "source": rep.source, "verdict": rep.verdict,
                              "findings": [asdict(f) for f in rep.findings]},
                             ensure_ascii=False, indent=2))
        else:
            print(format_report(rep, color=sys.stdout.isatty()))
    return 1 if (args.strict and rep.n_flag) else 0


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

#!/usr/bin/env python3
"""Power-aware null-interpretation gate (self-review §C estimand contracts).

A headline negative claim ("no synergy", "no association", "not associated",
"showed no difference") is only interpretable next to a *precision* statement —
a minimum-detectable-effect, a power calculation, an equivalence margin / TOST,
or a confidence-interval-compatibility sentence. A primary NULL that asserts
"the null was not underpowered or fragile" while the interval (e.g. interaction
OR 1.04, 95% CI 0.75–1.44) does not exclude a modest effect, with no MDE/
equivalence reported, is a Major a prose pass misses but a panel/co-reviewer
catches.

Verdict:
  CONFIRM_NULL_NO_MDE (Major)  a negative/equivalence claim sits in the Title /
                               Abstract / Conclusion with no minimum-detectable-
                               effect, power, equivalence-margin/TOST, or CI-
                               compatibility token anywhere in those regions.

Conservative by construction: it fires only when a headline negative claim is
present AND no precision token is CO-LOCATED with that claim (a MDE / power /
equivalence / CI-compatibility statement within the claim's own sentence
neighbourhood suppresses it). The check is per-claim-SITE, not per-region: a
power-aware caveat next to the Abstract-Results null does NOT license a bare
"equivalence within +/-0.10" in the Conclusions. Each unqualified claim site is
flagged on its own; a caveat in one region no longer masks an uncaveated
equivalence claim in another.

Exit codes: 0 clean (or report-only), 1 with --strict when any Major exists, 2 usage.
Stdlib-only (json / re / argparse / pathlib).

Usage:
    python3 check_null_calibration.py --manuscript manuscript.md \
        [--out qc/null_calibration.json] [--strict] [--quiet]
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

# Headline negative / equivalence claims. Anchored to a NULL conclusion, not a
# mere mention of the word "no".
NEGATIVE_CLAIM = re.compile(
    r"\bno\s+(?:significant\s+)?(?:synerg|associat|interaction|difference|effect|relationship|correlation|impact)"
    r"|\bnot\s+(?:significantly\s+)?associat(?:ed)?"
    r"|\b(?:was|were|is|are)\s+not\s+associated"
    r"|\bshowed\s+no\b|\bfound\s+no\b|\bdid\s+not\s+(?:differ|increase|decrease|affect|predict|improve)"
    r"|\bno\s+evidence\s+(?:of|for|that)\b"
    r"|\bhad\s+no\s+(?:significant\s+)?(?:effect|association|impact)"
    r"|\bnull\b(?:\s+(?:finding|result|association|hypothesis))"
    r"|\b(?:were|was)\s+(?:statistically\s+)?equivalent\b|\bno\s+meaningful\b",
    re.IGNORECASE)

# Precision / MDE / equivalence / CI-compatibility tokens that make a null
# interpretable.
PRECISION_TOKEN = re.compile(
    r"minimum\s+detectable\s+effect|\bMDE\b|detectable\s+(?:effect|difference)"
    r"|power(?:ed)?\s+to\s+detect|statistical(?:ly)?\s+power|post[-\s]?hoc\s+power|a\s+priori\s+power"
    r"|equivalence\s+(?:margin|bound|test|range)|\bTOST\b|two\s+one[-\s]sided"
    r"|non[-\s]?inferiority\s+margin|smallest\s+effect\s+size\s+of\s+interest|\bSESOI\b"
    r"|(?:confidence\s+interval|CI)\s+(?:excludes?|is\s+compatible|includes?\s+values|rules?\s+out|cannot\s+exclude)"
    r"|compatible\s+with\s+(?:effects?|a\s+(?:clinically\s+)?(?:meaningful|modest|important))"
    r"|cannot\s+(?:exclude|rule\s+out)\s+a\b|may\s+be\s+underpowered|was\s+underpowered"
    r"|wide\s+confidence\s+interval|interval\s+(?:does\s+not\s+exclude|spans)|equivalence\s+was\s+(?:not\s+)?established",
    re.IGNORECASE)

REGION_HEADINGS = re.compile(
    r"^#{1,4}\s*\*{0,2}(?:ABSTRACT|Abstract|CONCLUSIONS?|Conclusions?|DISCUSSION|Discussion|"
    r"Interpretation|Clinical Implications?|Summary)\*{0,2}\s*$",
    re.IGNORECASE | re.MULTILINE)


def headline_region(text: str) -> str:
    """Title (first heading / first non-empty line) + Abstract + Conclusion/
    Discussion regions + any inline 'Conclusion:' clause. Fallback: whole text."""
    spans: list[str] = []
    # title = first markdown heading, else first non-empty line
    mt = re.search(r"^#{1,6}\s+(.+)$", text, re.MULTILINE)
    if mt:
        spans.append(mt.group(1))
    else:
        for line in text.splitlines():
            if line.strip():
                spans.append(line.strip())
                break
    all_headings = [m.start() for m in re.finditer(r"^#{1,4}\s", text, re.MULTILINE)]
    for m in REGION_HEADINGS.finditer(text):
        s = m.end()
        nxt = next((h for h in all_headings if h > s), len(text))
        spans.append(text[s:nxt])
    for m in re.finditer(r"(?:^|\n)\s*\*{0,2}(?:Conclusions?|Interpretation)\*{0,2}\s*[:.]\s*(.+?)(?:\n\n|$)",
                         text, re.IGNORECASE | re.DOTALL):
        spans.append(m.group(1))
    if not spans:
        spans.append(text)
    return "\n".join(spans)


# Neighbourhood (chars each side of a claim) searched for a co-located precision
# statement. Wide enough to cover the same sentence / adjacent clause, narrow
# enough that a caveat in a different paragraph/region does not mask this claim.
_COLOCATE_WINDOW = 160


def check(text: str) -> list[dict]:
    region = headline_region(text)
    claims: list[dict] = []
    seen: set[str] = set()
    for nm in NEGATIVE_CLAIM.finditer(region):
        window = region[max(0, nm.start() - _COLOCATE_WINDOW):nm.end() + _COLOCATE_WINDOW]
        if PRECISION_TOKEN.search(window):
            continue  # a precision statement is co-located with THIS claim site
        key = re.sub(r"\s+", " ", nm.group(0).strip().lower())
        if key in seen:
            continue
        seen.add(key)
        claims.append({
            "verdict": "CONFIRM_NULL_NO_MDE",
            "severity": "Major",
            "detail": (f"a headline negative/equivalence claim ('{nm.group(0).strip()}') in the "
                       f"Title/Abstract/Conclusion has no co-located minimum-detectable-"
                       f"effect, power, equivalence-margin/TOST, or CI-compatibility statement; a "
                       f"non-significant result is not evidence of no effect without one "
                       f"(a caveat elsewhere in the manuscript does not cover this claim site)"),
            "where": region[max(0, nm.start() - 40):nm.end() + 60].replace("\n", " ").strip()[:160],
        })
    return claims


def analyze(manuscript: str) -> dict:
    p = Path(manuscript)
    if not p.is_file():
        sys.stderr.write(f"ERROR: manuscript not found: {manuscript}\n")
        sys.exit(2)
    claims = check(p.read_text(encoding="utf-8"))
    n_major = sum(1 for c in claims if c["severity"] == "Major")
    return {
        "manuscript": str(p),
        "claims": claims,
        "summary": {
            "n_claims": len(claims),
            "n_major": n_major,
            "n_flag": len(claims) - n_major,
            "verdict": "MAJOR_CANDIDATE" if n_major else "OK",
        },
    }


def render(result: dict) -> str:
    lines = ["| Check | Severity | Detail |", "|---|---|---|"]
    for c in result["claims"]:
        lines.append(f"| {c['verdict']} | {c['severity']} | {c['detail']} |")
    if len(lines) == 2:
        lines.append("| (none) | — | no headline null lacks a precision/MDE statement |")
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(description="Power-aware null-interpretation gate (§C).")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true", help="exit 1 if any Major claim exists")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    args = ap.parse_args()

    result = analyze(args.manuscript)

    if not args.quiet:
        print("=" * 41)
        print(" Null Calibration (§C)")
        print("=" * 41)
        print(render(result))
        print()
        s = result["summary"]
        if s["n_major"]:
            print(f"MAJOR candidate: {s['n_major']} headline null without a precision/MDE statement.")
        else:
            print("OK: no headline null lacks a precision/MDE statement.")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_null_calibration", **result}, indent=2), encoding="utf-8")
        if not args.quiet:
            print(f"\nwrote {args.out}")

    return 1 if (args.strict and result["summary"]["n_major"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""check_paired_difference_estimator.py — sanity-check a reported "median paired
difference" against the achievable value set, its interval, and its named estimator.

Reader/Likert studies routinely bolt an effect size onto a revision to answer an
uncertainty comment, and the estimator is left undefined. The tells are
deterministic: the median of an odd number of integer paired differences is one of
the integer differences, so a reported non-integer median (e.g. 0.5) is impossible
and signals a Hodges–Lehmann pseudomedian mislabelled as a median; a "95% CI" whose
bounds are equal (0.5–0.5) is degenerate; and an effect size + CI with no estimator
or interval method named cannot be reproduced.

Checks:
  MEDIAN_PARITY    n odd ∧ integer scale ∧ reported median difference non-integer
                   (if scores are means of R raters, the step is 1/R — still flag a
                   value that is not a multiple of 1/R). Suppressed when the value is
                   labelled a Hodges–Lehmann pseudomedian.
  DEGENERATE_CI    a reported interval whose lower bound equals its upper bound.
  ESTIMATOR_UNNAMED a median-difference effect size + CI while no estimator / interval
                   method (Hodges–Lehmann, pseudomedian, bootstrap, Wilcoxon, exact,
                   sign test) is named anywhere in the manuscript.

Stdlib-only. Reads the manuscript, never writes it.

Usage:
  python3 check_paired_difference_estimator.py --manuscript paper.md [--strict] [--quiet] [--json]
Exit: 0 clean; with --strict, 1 on any MAJOR finding; 2 on input/usage error.
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from dataclasses import dataclass, field, asdict

MEDIAN_DIFF_RE = re.compile(
    r"(?<!pseudo)\b(?:paired\s+)?median\s+(?:paired\s+)?difference\b[^.\n]{0,40}?\b(\d+(?:\.\d+)?)", re.I)
N_RE = re.compile(r"\b(\d+)\s+paired\b|\bn\s*=\s*(\d+)\b", re.I)
SCALE_RE = re.compile(r"\b(\d+)-point\b|\bLikert\b", re.I)
RATERS_RE = re.compile(r"\b(?:mean|average[d]?)\b[^.\n]{0,30}?\b(\d+)\s+raters?\b", re.I)
CI_RE = re.compile(r"95\s*%\s*CI[:\s]*\(?\s*(-?\d+(?:\.\d+)?)\s*(?:[–\-−]|to)\s*(-?\d+(?:\.\d+)?)", re.I)
ESTIMATOR_RE = re.compile(r"\b(hodges[-–\s]?lehmann|pseudomedian|bootstrap|wilcoxon|exact\s+(?:test|confidence)|sign\s+test)\b", re.I)


@dataclass
class Finding:
    kind: str
    severity: str
    detail: str


@dataclass
class Report:
    source: str
    findings: list[Finding] = field(default_factory=list)

    @property
    def n_flag(self) -> int:
        return sum(1 for f in self.findings if f.severity == "MAJOR")

    @property
    def verdict(self) -> str:
        return "ESTIMATOR PROBLEM" if self.n_flag else "OK"


def _is_multiple(value: float, step: float) -> bool:
    q = value / step
    return abs(q - round(q)) < 1e-9


def audit(text: str, source: str) -> Report:
    rep = Report(source=source)
    estimator_named = bool(ESTIMATOR_RE.search(text))

    n_m = N_RE.search(text)
    n_val = int(next(g for g in (n_m.groups() if n_m else ()) if g)) if n_m else None
    scale_m = SCALE_RE.search(text)
    integer_scale = bool(scale_m)
    raters_m = RATERS_RE.search(text)
    step = 1.0 / int(raters_m.group(1)) if raters_m else 1.0

    for m in MEDIAN_DIFF_RE.finditer(text):
        # is this occurrence a mislabel guarded by a nearby pseudomedian/HL tag?
        window = text[max(0, m.start() - 20):m.end()]
        if re.search(r"pseudomedian|hodges", window, re.I):
            continue
        value = float(m.group(1))
        if n_val is not None and n_val % 2 == 1 and integer_scale and not _is_multiple(value, step):
            rep.findings.append(Finding(
                "MEDIAN_PARITY", "MAJOR",
                f"reported median paired difference {value:g} is not achievable: the median of "
                f"n={n_val} (odd) integer differences must be an integer"
                + (f" (or a multiple of 1/{int(raters_m.group(1))})" if raters_m else "")
                + " — likely a Hodges–Lehmann pseudomedian mislabelled as a median"))

    for m in CI_RE.finditer(text):
        lo, hi = float(m.group(1)), float(m.group(2))
        if lo == hi:
            rep.findings.append(Finding(
                "DEGENERATE_CI", "MAJOR",
                f"reported 95% CI has equal bounds ({m.group(1)}–{m.group(2)}) — zero width"))

    if MEDIAN_DIFF_RE.search(text) and CI_RE.search(text) and not estimator_named:
        rep.findings.append(Finding(
            "ESTIMATOR_UNNAMED", "MAJOR",
            "a median-difference effect size with a CI is reported but no estimator / interval "
            "method (Hodges–Lehmann, pseudomedian, bootstrap, Wilcoxon, exact, sign test) is named"))
    return rep


def format_report(rep: Report, color: bool) -> str:
    tag = {"OK": "\033[92m", "ESTIMATOR PROBLEM": "\033[91m"}.get(rep.verdict, "") if color else ""
    end = "\033[0m" if color else ""
    out = [f"{tag}== {rep.verdict} =={end}  {rep.source}", f"problems={rep.n_flag}"]
    if not rep.findings:
        out.append("median-difference estimator, interval, and value set are consistent.")
        return "\n".join(out)
    for f in sorted(rep.findings, key=lambda x: (x.kind, x.detail)):
        out.append(f"[{f.severity}] {f.kind}  {f.detail}")
    return "\n".join(out)


def main(argv: list[str] | None = None) -> int:
    ap = argparse.ArgumentParser(description=__doc__,
                                 formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--strict", action="store_true", help="exit 1 on any MAJOR finding")
    ap.add_argument("--quiet", action="store_true", help="suppress the report; exit code only")
    ap.add_argument("--json", action="store_true", help="emit JSON instead of a text report")
    args = ap.parse_args(argv)
    try:
        text = open(args.manuscript, encoding="utf-8").read()
    except OSError as e:
        print(f"error: cannot read manuscript: {e}", file=sys.stderr)
        return 2
    rep = audit(text, args.manuscript)
    if not args.quiet:
        if args.json:
            print(json.dumps({"detector": "check_paired_difference_estimator", "source": rep.source, "verdict": rep.verdict,
                              "findings": [asdict(f) for f in rep.findings]},
                             ensure_ascii=False, indent=2))
        else:
            print(format_report(rep, color=sys.stdout.isatty()))
    return 1 if (args.strict and rep.n_flag) else 0


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

#!/usr/bin/env python3
"""Panel lens-diversity gate (self-review Phase 2.6, --panel).

A multi-agent panel is only worth its cost if its reviewers cover *distinct*
concern axes. Left unchecked, independent reviewers converge on the same easy
themes (everyone flags "missing calibration") while whole high-risk axes go
unprobed — the panel collapses to fewer effective lenses than reviewers, and
the editor synthesis cannot tell monoculture from genuine consensus. This gate
post-processes the reviewers' structured output (the panel_review_template
schema the editor already collects) and reports these diversity and panel-independence failures:

  UNCOVERED_AXIS     an expected high-risk axis for this research type produced
                     ZERO major findings across the whole panel. Mirrors the
                     "completeness critic" pattern: name what nobody probed so
                     the editor can re-probe it before finalizing. (Major)
  FAMILY_MONOCULTURE the panel's major findings concentrate in ONE concern
                     family beyond a threshold (one family holds the majority),
                     a signal the lenses converged rather than spanned the
                     manuscript. (Major)
  LENS_COLLAPSE      one reviewer contributed only families that another
                     reviewer already covered — a fully-redundant lens that
                     added no independent signal. Distinct from healthy
                     CONSENSUS (a reviewer agreeing on SOME themes but also
                     raising at least one family nobody else did). Exempt when
                     the roster declares that reviewer on a DIFFERENT substrate
                     from the generator: agreement reached from another substrate
                     is corroboration, not a redundant assignment, and it is the
                     very lens SUBSTRATE_MONOCULTURE requires. Exempted ids are
                     reported in summary.lens_collapse_substrate_exempt. (Flag)
  SUBSTRATE_MONOCULTURE  every reviewer the roster declares shares the *generator's*
                     model substrate — a same-model panel inherits the blind spots that
                     produced the draft and is not an independent check. Fires only when
                     the roster declares the generator's and the reviewers' substrates and
                     none differs; absent substrate info => skipped. (Major)

Healthy consensus is preserved: a finding family raised by ≥2 reviewers is a
strength, not a defect. The gate only fires LENS_COLLAPSE when a reviewer's
ENTIRE contribution is redundant, and UNCOVERED_AXIS/MONOCULTURE on
panel-level coverage, never on agreement per se.

INPUTS
  --panel  JSON file. Either a list of reviewer objects, or an object with a
           "reviewers" list (and optional "research_type"). Each reviewer
           object needs reviewer_id, expertise_area, and major[] (with heading
           and/or comment text); minor[] is ignored for axis coverage.
  --research-type  one of: survival, sr_ma, radiomics, dta, observational,
           narrative (synonyms accepted). Overrides any value in the JSON.
           When unknown/absent, UNCOVERED_AXIS is skipped (cannot know the
           expected axes) and noted in the summary.
  --roster  roster manifest of SPAWNED reviewers. A list of ids, or
           {reviewers|roster: [{reviewer_id, substrate}]} with an optional top-level
           "generator_substrate". Enables PANEL_UNDERRETURN (spawned vs returned) and
           SUBSTRATE_MONOCULTURE (independence). substrate is a coarse lane label
           ("claude" | "codex" | "gpt" | "human"), not a model version.

OUTPUT
  A diversity table (stdout) and, with --out, a JSON artifact:
    {panel, research_type, claims[{verdict, severity, detail, where}], summary}
  summary carries the family histogram, concentration index, and the
  expected/covered/uncovered axes. Exit 1 (with --strict) when any Major claim
  exists; exit 2 on input error.

Stdlib-only (json / re / argparse / pathlib). Exit codes: 0 clean (or
report-only), 1 Major claim(s) found (with --strict), 2 input/usage error.
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

# Concern families, aligned to the panel's per-domain focus checklists and the
# self-review A–J category system. Each finding is assigned to the FIRST family
# whose lexicon matches its text; order is most-specific to most-generic so a
# leakage finding is not swallowed by the generic "statistics" family.
FAMILY_LEXICON: list[tuple[str, re.Pattern]] = [
    ("search_screening", re.compile(
        r"search strateg|screening|eligibilit|inclusion criteri|exclusion criteri|"
        r"database\b|grey literature|gray literature|duplicate (?:removal|record)|"
        r"prisma flow|records identified|study selection", re.IGNORECASE)),
    ("design_leakage", re.compile(
        r"leakage|data (?:split|leak)|train(?:ing|/test| test)|test set|"
        r"contaminat|allocation|randomi[sz]|immortal time|time[-\s]?zero|"
        r"selection bias|spectrum bias|case[-\s]?control selection|"
        r"reference standard|verification bias", re.IGNORECASE)),
    ("confounding", re.compile(
        r"confound|residual confounding|covariate|adjust(?:ment|ed)|mediator|"
        r"collider|confounding by indication|propensity", re.IGNORECASE)),
    ("imaging", re.compile(
        r"acquisition|scanner|sequence|segmentation|voxel|kernel|reconstruction|"
        r"combat|harmoni[sz]|slice thickness|field strength|radiomic feature|"
        r"window(?:ing| level)|protocol heterogeneity", re.IGNORECASE)),
    ("reporting", re.compile(
        r"strobe|tripod|prisma\b|consort|claim\b|stard|reporting (?:guideline|standard|"
        r"completeness)|checklist|flow diagram|disclosure|registration|protocol "
        r"deviation|abstract (?:inconsisten|mismatch)", re.IGNORECASE)),
    ("reproducibility", re.compile(
        r"reproducib|code availab|data availab|random seed|\bseed\b|script\b|"
        r"open (?:data|code)|version pin", re.IGNORECASE)),
    ("statistics", re.compile(
        r"calibrat|discriminat|\bauc\b|c[-\s]?statistic|delong|confidence interval|"
        r"\bci\b|heterogeneit|\bi2\b|i\^?2|pooling|pooled|random[-\s]?effects|"
        r"multiplicit|multiple compar|\bp[-\s]?value|\bpower\b|sample size|"
        r"model specif|proportional hazard|missing data|imputation|competing risk|"
        r"events per variable|overfitting|effect size|subdistribution|"
        # Type-agnostic statistical vocabulary a reader / agreement study raises but the
        # meta-analysis-flavoured list above missed — effect measures, resampling,
        # inter-rater agreement, multiplicity siblings, common tests, Bayesian. Without
        # these a statistics-dedicated reviewer's majors classified as "other" and the
        # statistics axis looked uncovered (false UNCOVERED_AXIS Major).
        r"odds ratio|hazard ratio|risk ratio|relative risk|rate ratio|"
        r"bootstrap|permutation|jackknife|monte[-\s]?carlo|"
        r"\bkappa\b|κ|inter[-\s]?rater|intraclass|\bicc\b|\bac1\b|concordance|"
        r"bonferroni|false discovery|\bfdr\b|\bholm\b|family[-\s]?wise|"
        r"wilcoxon|mann[-\s]?whitney|mcnemar|log[-\s]?rank|chi[-\s]?squared?|fisher'?s? exact|"
        r"bayesian|credible interval|posterior distribution|standard deviation|standard error",
        re.IGNORECASE)),
    ("clinical", re.compile(
        r"clinical|actionab|guideline|management|generali[sz]ab|applicab|"
        r"external validit|patient[-\s]?care|over(?:reach|claim)|"
        r"clinical (?:relevance|utility|significance)", re.IGNORECASE)),
]

# Expected high-risk axes per research type (each SHOULD yield ≥1 major). Mirrors
# the Phase 2.6 reviewer-set table; optional axes (e.g. imaging when the exposure
# is non-imaging) are not required and so are omitted here.
EXPECTED_AXES: dict[str, list[str]] = {
    "survival": ["statistics", "clinical"],
    "sr_ma": ["search_screening", "clinical", "statistics"],
    "radiomics": ["imaging", "statistics", "clinical"],
    "dta": ["design_leakage", "statistics", "clinical"],
    "observational": ["confounding", "clinical", "statistics"],
    "narrative": ["clinical", "reporting"],
}

RESEARCH_TYPE_SYNONYMS: dict[str, str] = {
    "survival": "survival", "prognostic": "survival", "cohort": "survival",
    "sr": "sr_ma", "ma": "sr_ma", "sr_ma": "sr_ma", "sr/ma": "sr_ma",
    "systematic review": "sr_ma", "meta-analysis": "sr_ma", "meta analysis": "sr_ma",
    "radiomics": "radiomics", "feature": "radiomics",
    "dta": "dta", "diagnostic": "dta", "diagnostic-accuracy": "dta", "ai model": "dta",
    "observational": "observational", "strobe": "observational",
    "narrative": "narrative", "review article": "narrative", "sanra": "narrative",
}

MONOCULTURE_MIN_MAJORS = 4   # too few majors to call concentration meaningful
MONOCULTURE_SHARE = 0.60     # one family holding > this share = monoculture


def normalize_research_type(raw: str | None) -> str | None:
    if not raw:
        return None
    key = raw.strip().lower()
    if key in RESEARCH_TYPE_SYNONYMS:
        return RESEARCH_TYPE_SYNONYMS[key]
    for syn, canon in RESEARCH_TYPE_SYNONYMS.items():
        if syn in key:
            return canon
    return None


def classify(text: str) -> str:
    for family, pat in FAMILY_LEXICON:
        if pat.search(text):
            return family
    return "other"


def finding_text(major: dict) -> str:
    parts = [str(major.get(k, "")) for k in ("heading", "comment", "location")]
    return " ".join(p for p in parts if p)


def load_reviewers(obj) -> tuple[list[dict], str | None]:
    if isinstance(obj, list):
        return obj, None
    if isinstance(obj, dict):
        revs = obj.get("reviewers")
        if isinstance(revs, list):
            return revs, obj.get("research_type")
    raise ValueError("panel JSON must be a list of reviewers or an object with a 'reviewers' list")


def load_roster_ids(path: str | None) -> set[str] | None:
    """The reviewer_ids that were SPAWNED (a roster manifest written before spawning).
    Accepts a list of ids, a list of {reviewer_id: ...}, or {reviewers|roster: [...]}.
    Returns None when no roster is given (roster checks then stay silent)."""
    if not path:
        return None
    obj = json.loads(Path(path).read_text(encoding="utf-8"))
    if isinstance(obj, list):
        ids: set[str] = set()
        for x in obj:
            if isinstance(x, str):
                ids.add(x)
            elif isinstance(x, dict) and x.get("reviewer_id"):
                ids.add(str(x["reviewer_id"]))
        return ids
    if isinstance(obj, dict):
        revs = obj.get("reviewers") or obj.get("roster") or []
        return {str(r["reviewer_id"]) for r in revs
                if isinstance(r, dict) and r.get("reviewer_id")}
    return set()


def load_roster_substrates(path: str | None) -> tuple[str | None, dict[str, str]]:
    """The generator's substrate and each spawned reviewer's substrate, from the roster
    manifest. Returns (generator_substrate, {reviewer_id: substrate}); either may be empty
    when the roster is a bare id list or omits substrate fields (SUBSTRATE_MONOCULTURE then
    stays silent). Substrate is a coarse lane label ("claude" | "codex" | "gpt" | "human")."""
    if not path:
        return None, {}
    obj = json.loads(Path(path).read_text(encoding="utf-8"))
    if isinstance(obj, dict):
        gen = obj.get("generator_substrate")
        revs = obj.get("reviewers") or obj.get("roster") or []
    elif isinstance(obj, list):
        gen, revs = None, obj
    else:
        return None, {}
    subs: dict[str, str] = {}
    for r in revs:
        if isinstance(r, dict) and r.get("reviewer_id") and r.get("substrate"):
            subs[str(r["reviewer_id"])] = str(r["substrate"])
    return (str(gen) if gen else None), subs


def check(reviewers: list[dict], research_type: str | None,
          roster_ids: set[str] | None = None,
          generator_substrate: str | None = None,
          reviewer_substrates: dict[str, str] | None = None) -> tuple[list[dict], dict]:
    claims: list[dict] = []

    returned_ids = {str(rev.get("reviewer_id") or f"R{i + 1}")
                    for i, rev in enumerate(reviewers)}

    # 0) PANEL_UNDERRETURN — spawned (roster) vs returned (panel). The failure this
    # exists for: a --panel run spawns N reviewers and some/all return nothing, so the
    # panel JSON is thin or empty and NOTHING errors — the run reads as "completed".
    # Set arithmetic over the two id lists turns a silent absence into a Major. Silent
    # (no roster given): the caller did not record who was spawned, so nothing to compare.
    if roster_ids is not None:
        missing = sorted(roster_ids - returned_ids)
        n_returned = len(reviewers)
        if n_returned < 2 or missing:
            if n_returned < 2:
                detail = (f"only {n_returned} of {len(roster_ids)} rostered reviewer(s) returned "
                          f"a parseable review; a panel with fewer than 2 returned reviews is a "
                          f"FAILED run, not a thin one — do not synthesize it or report it as a "
                          f"review. Non-returning: {', '.join(missing) or '(all)'}. Re-spawn on a "
                          f"different substrate (or route to a human co-author) before treating "
                          f"this as a panel.")
            else:
                detail = (f"{n_returned} of {len(roster_ids)} rostered reviewers returned; "
                          f"{len(missing)} did not: {', '.join(missing)}. A missing reviewer is a "
                          f"gap, not an absence — re-spawn the missing lens(es), or state "
                          f"explicitly that synthesis used only the returned subset.")
            claims.append({
                "verdict": "PANEL_UNDERRETURN",
                "severity": "Major",
                "detail": detail,
                "where": f"roster: {len(roster_ids)} spawned, {n_returned} returned",
            })

    # 0b) SUBSTRATE_MONOCULTURE — a generator/critic/verifier sharing a model substrate have
    # correlated blind spots; a same-model-only panel is not an independent check. Fires only
    # when the roster declares the generator's substrate AND >=1 reviewer's substrate, and none
    # of the declared reviewer substrates differs from the generator's. Absent substrate info =>
    # skip (older rosters / no --roster), so this never false-positives on an unlabelled panel.
    if generator_substrate and reviewer_substrates:
        declared = {rid: s for rid, s in reviewer_substrates.items() if s}
        if declared:
            gen = generator_substrate.strip().lower()
            independent = sorted(rid for rid, s in declared.items() if s.strip().lower() != gen)
            if not independent:
                claims.append({
                    "verdict": "SUBSTRATE_MONOCULTURE",
                    "severity": "Major",
                    "detail": (f"all {len(declared)} declared reviewer(s) share the generator's "
                               f"substrate ('{generator_substrate}'); a same-model panel inherits the "
                               f"generator's blind spots and is not an independent check. Route at "
                               f"least one lens to a different substrate (the Codex adversarial path) "
                               f"or a human co-author before treating this as an independent panel."),
                    "where": f"substrate: generator={generator_substrate}, "
                             f"reviewers={sorted(set(declared.values()))}",
                })

    # Per-reviewer families (set of distinct families this reviewer raised as majors)
    rev_families: dict[str, set[str]] = {}
    family_hist: dict[str, int] = {}
    n_majors = 0
    for i, rev in enumerate(reviewers):
        rid = str(rev.get("reviewer_id") or f"R{i + 1}")
        fams: set[str] = set()
        for maj in rev.get("major", []) or []:
            fam = classify(finding_text(maj))
            fams.add(fam)
            family_hist[fam] = family_hist.get(fam, 0) + 1
            n_majors += 1
        rev_families[rid] = fams

    covered = set(family_hist)
    covered.discard("other")

    # 1) UNCOVERED_AXIS — only when we know the expected axes
    expected: list[str] = []
    uncovered: list[str] = []
    if research_type and research_type in EXPECTED_AXES:
        expected = EXPECTED_AXES[research_type]
        uncovered = [ax for ax in expected if family_hist.get(ax, 0) == 0]
        for ax in uncovered:
            claims.append({
                "verdict": "UNCOVERED_AXIS",
                "severity": "Major",
                "detail": (f"no major finding addresses the '{ax}' axis, which a "
                           f"{research_type} panel is expected to probe; the editor "
                           f"should re-probe it before finalizing"),
                "where": f"expected axes for {research_type}: {', '.join(expected)}",
            })

    # 2) FAMILY_MONOCULTURE — concentration of majors in one family
    hhi = 0.0
    top_family = None
    top_share = 0.0
    if n_majors:
        shares = {f: c / n_majors for f, c in family_hist.items() if f != "other"}
        hhi = sum(s * s for s in shares.values())
        if shares:
            top_family, top_share = max(shares.items(), key=lambda kv: kv[1])
        if n_majors >= MONOCULTURE_MIN_MAJORS and top_share > MONOCULTURE_SHARE:
            claims.append({
                "verdict": "FAMILY_MONOCULTURE",
                "severity": "Major",
                "detail": (f"{top_share:.0%} of major findings fall in the '{top_family}' "
                           f"family ({family_hist.get(top_family, 0)}/{n_majors}); the panel "
                           f"converged on one axis rather than spanning the manuscript"),
                "where": "family histogram: " + ", ".join(
                    f"{f}={c}" for f, c in sorted(family_hist.items(), key=lambda kv: -kv[1])),
            })

    # 3) LENS_COLLAPSE — a reviewer whose every family is also covered by another.
    #
    # Exempt: a reviewer whose declared substrate DIFFERS from the generator's. For a
    # same-substrate lens, raising only families others already raised is evidence of a
    # redundant assignment. For a cross-substrate lens it is close to the opposite —
    # independent corroboration is the strongest signal a panel can produce, and that lens is
    # exactly what SUBSTRATE_MONOCULTURE (0b, above) requires the panel to contain. Firing
    # here told the editor to reconsider the one reviewer keeping the panel independent.
    # Gated on both substrates being declared, so an unlabelled roster is unaffected.
    gen_sub = (generator_substrate or "").strip().lower()
    declared_subs = {rid: str(s).strip().lower()
                     for rid, s in (reviewer_substrates or {}).items() if s}
    cross_substrate_exempt: list[str] = []
    for rid, fams in rev_families.items():
        own = {f for f in fams if f != "other"}
        if not own:
            continue
        others = set()
        for other_rid, other_fams in rev_families.items():
            if other_rid != rid:
                others |= {f for f in other_fams if f != "other"}
        if own and own <= others and gen_sub and declared_subs.get(rid, gen_sub) != gen_sub:
            # Recorded, never silent: a skipped check that prints nothing is
            # indistinguishable from a check that passed.
            cross_substrate_exempt.append(rid)
            continue
        if own and own <= others:  # fully subsumed by other reviewers
            claims.append({
                "verdict": "LENS_COLLAPSE",
                "severity": "Flag",
                "detail": (f"reviewer {rid} raised only families also covered by other "
                           f"reviewers ({', '.join(sorted(own))}); this lens added no "
                           f"independent axis — confirm it is a genuine consensus, not a "
                           f"redundant reviewer assignment"),
                "where": f"reviewer {rid}",
            })

    # 4) THIN_PANEL
    if len(reviewers) < 2:
        claims.append({
            "verdict": "THIN_PANEL",
            "severity": "Flag",
            "detail": (f"only {len(reviewers)} reviewer(s); a panel needs ≥2 independent "
                       f"lenses for diversity to be meaningful"),
            "where": "panel composition",
        })

    summary = {
        "n_reviewers": len(reviewers),
        "n_majors": n_majors,
        "family_histogram": family_hist,
        "concentration_hhi": round(hhi, 3),
        "top_family": top_family,
        "top_family_share": round(top_share, 3),
        "expected_axes": expected,
        "covered_axes": sorted(covered),
        "uncovered_axes": uncovered,
        "research_type_known": bool(research_type and research_type in EXPECTED_AXES),
        "lens_collapse_substrate_exempt": sorted(cross_substrate_exempt),
    }
    return claims, summary


def analyze(panel: str, research_type_arg: str | None, roster_arg: str | None = None) -> dict:
    p = Path(panel)
    if not p.is_file():
        sys.stderr.write(f"ERROR: panel JSON not found: {panel}\n")
        sys.exit(2)
    try:
        obj = json.loads(p.read_text(encoding="utf-8"))
        reviewers, rt_in_json = load_reviewers(obj)
    except (ValueError, json.JSONDecodeError) as exc:
        sys.stderr.write(f"ERROR: {exc}\n")
        sys.exit(2)
    try:
        roster_ids = load_roster_ids(roster_arg)
        generator_substrate, reviewer_substrates = load_roster_substrates(roster_arg)
    except (OSError, ValueError, json.JSONDecodeError) as exc:
        sys.stderr.write(f"ERROR: roster: {exc}\n")
        sys.exit(2)

    research_type = normalize_research_type(research_type_arg) or normalize_research_type(rt_in_json)
    claims, summary = check(reviewers, research_type, roster_ids,
                            generator_substrate, reviewer_substrates)
    if generator_substrate:
        summary["generator_substrate"] = generator_substrate
        summary["reviewer_substrates"] = reviewer_substrates
    if roster_ids is not None:
        returned = {str(rev.get("reviewer_id") or f"R{i + 1}") for i, rev in enumerate(reviewers)}
        summary["rostered"] = len(roster_ids)
        summary["returned"] = len(reviewers)
        summary["not_returned"] = sorted(roster_ids - returned)
    n_major = sum(1 for c in claims if c["severity"] == "Major")
    summary["n_claims"] = len(claims)
    summary["n_major"] = n_major
    summary["n_flag"] = len(claims) - n_major
    summary["verdict"] = "MAJOR_CANDIDATE" if n_major else "OK"
    return {
        "panel": str(p),
        "research_type": research_type,
        "claims": claims,
        "summary": summary,
    }


def render(result: dict) -> str:
    lines = ["| Check | Severity | Detail |", "|---|---|---|"]
    for c in result["claims"]:
        lines.append(f"| {c['verdict']} | {c['severity']} | {c['detail']} |")
    if len(lines) == 2:
        lines.append("| (none) | — | panel lenses span distinct axes; no monoculture |")
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(description="Panel lens-diversity gate (Phase 2.6, --panel).")
    ap.add_argument("--panel", required=True, help="reviewers JSON (list or {reviewers:[...]})")
    ap.add_argument("--roster", help="roster manifest of SPAWNED reviewer_ids written before "
                                     "spawning (list of ids, or {reviewers|roster:[{reviewer_id}]}); "
                                     "enables PANEL_UNDERRETURN when the returned panel is missing "
                                     "rostered reviewers or has <2 returned")
    ap.add_argument("--research-type", help="survival|sr_ma|radiomics|dta|observational|narrative")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true", help="exit 1 if any Major claim exists")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    args = ap.parse_args()

    result = analyze(args.panel, args.research_type, args.roster)

    if not args.quiet:
        print("=" * 41)
        print(" Panel Lens-Diversity (Phase 2.6)")
        print("=" * 41)
        print(render(result))
        print()
        s = result["summary"]
        if not s["research_type_known"]:
            print("NOTE: research type unknown — UNCOVERED_AXIS skipped "
                  "(pass --research-type to enable axis-coverage checks).")
        if s.get("lens_collapse_substrate_exempt"):
            print("NOTE: LENS_COLLAPSE exempt for "
                  f"{', '.join(s['lens_collapse_substrate_exempt'])} — declared on a different "
                  f"substrate from the generator, so full agreement reads as cross-substrate "
                  f"corroboration, not a redundant lens.")
        if s["n_major"]:
            print(f"MAJOR candidate: {s['n_major']} diversity failure(s); "
                  f"covered axes: {', '.join(s['covered_axes']) or '(none)'}.")
        else:
            print(f"OK: {s['n_reviewers']} reviewers spanning "
                  f"{len(s['covered_axes'])} distinct axes "
                  f"(HHI={s['concentration_hhi']}).")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_panel_diversity", **result}, indent=2), encoding="utf-8")
        if not args.quiet:
            print(f"\nwrote {args.out}")

    return 1 if (args.strict and result["summary"]["n_major"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Parenthesis-span corruption gate (post em-dash-reduction safety scan).

Reducing em-dashes to satisfy a classical-style gate (`" — X — "` appositive →
`(X)`) is a common edit. When a bulk regex pairs two *unrelated* single em-dashes
across a sentence boundary, it wraps a whole sentence inside one parenthesis:

    "... E-value 3.10 — Sixth, the lean-MASLD subgroup was small — and ..."
  → "... E-value 3.10 (Sixth, the lean-MASLD subgroup was small) and ..."

The result is grammatically broken but **paren-balanced**, so a balance check
misses it; only a human re-read (or this scan) catches it. This gate flags any
outer `(...)` span whose content (after stripping nested parens) contains:

  PAREN_SPAN_ORDINAL  (Major) an ordinal limitation marker ("First," … "Tenth,") —
                      the exact corruption above; an ordinal sentence-opener does
                      not belong inside a parenthesis.
  PAREN_SPAN_SENTENCE (Major) a sentence boundary ("word. Capital") inside a LONG
                      span (> --min-sentence-span chars, default 120) — a wrapped
                      sentence. The length guard avoids false positives on short
                      legitimate parentheticals ("(Dr. Smith)", "(Fig. 2; cf. A)").

Run it after `--fix` / `/humanize` em-dash work (and standalone on any draft).

INPUT
  --manuscript  manuscript markdown/text (required).

OUTPUT
  stdout table and, with --out, a JSON artifact {manuscript, claims[], summary}.
  Both verdicts are Major. Exit 1 (with --strict) when any Major claim exists.

Stdlib-only (re / json / argparse / pathlib). Exit codes: 0 clean (or report-only),
1 Major claim(s) found (with --strict), 2 input/usage error.
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

ORDINAL_RE = re.compile(
    r"\b(First|Second|Third|Fourth|Fifth|Sixth|Seventh|Eighth|Ninth|Tenth)\s*,", re.IGNORECASE)
# A sentence boundary: a lowercase word, a period, whitespace, then a capitalized
# word. (Requiring lowercase-before-period skips most abbreviations like "Fig.".)
SENTENCE_BOUNDARY_RE = re.compile(r"[a-z]{2,}\.\s+[A-Z][a-z]")


def _strip_nested(s: str) -> str:
    """Remove inner (...) groups so only the outer span's own text is tested."""
    prev = None
    while prev != s:
        prev = s
        s = re.sub(r"\([^()]*\)", " ", s)
    return s


def _outer_spans(text: str):
    """Yield (content, start) for every top-level balanced (...) span."""
    depth = 0
    start = -1
    for i, ch in enumerate(text):
        if ch == "(":
            if depth == 0:
                start = i
            depth += 1
        elif ch == ")" and depth > 0:
            depth -= 1
            if depth == 0 and start >= 0:
                yield text[start + 1:i], start


def check(text: str, min_sentence_span: int) -> list[dict]:
    claims = []
    for content, pos in _outer_spans(text):
        inner = _strip_nested(content)
        om = ORDINAL_RE.search(inner)
        if om:
            claims.append({
                "verdict": "PAREN_SPAN_ORDINAL",
                "severity": "Major",
                "detail": (f"a parenthesis wraps an ordinal sentence-opener "
                           f"('{om.group(0).strip()}') — likely an em-dash→paren "
                           f"conversion that paired unrelated dashes across a sentence"),
                "where": content.strip()[:160],
            })
            continue
        if len(inner) > min_sentence_span and SENTENCE_BOUNDARY_RE.search(inner):
            sm = SENTENCE_BOUNDARY_RE.search(inner)
            claims.append({
                "verdict": "PAREN_SPAN_SENTENCE",
                "severity": "Major",
                "detail": (f"a long parenthesis ({len(inner)} chars) contains a sentence "
                           f"boundary ('{sm.group(0).strip()}') — a whole sentence appears "
                           f"wrapped in parentheses"),
                "where": content.strip()[:160],
            })
    return claims


def analyze(manuscript: str, min_sentence_span: int) -> dict:
    p = Path(manuscript)
    if not p.is_file():
        sys.stderr.write(f"ERROR: manuscript not found: {manuscript}\n")
        sys.exit(2)
    claims = check(p.read_text(encoding="utf-8"), min_sentence_span)
    n_major = sum(1 for c in claims if c["severity"] == "Major")
    return {
        "manuscript": str(p),
        "claims": claims,
        "summary": {
            "n_claims": len(claims),
            "n_major": n_major,
            "verdict": "MAJOR_CANDIDATE" if n_major else "OK",
        },
    }


def render(result: dict) -> str:
    lines = ["| Check | Severity | Detail |", "|---|---|---|"]
    for c in result["claims"]:
        lines.append(f"| {c['verdict']} | {c['severity']} | {c['detail']} |")
    if len(lines) == 2:
        lines.append("| (none) | — | no parenthesis-span corruption detected |")
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(description="Parenthesis-span corruption gate (post em-dash reduction).")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--min-sentence-span", type=int, default=120,
                    help="min span length (chars) for the sentence-boundary check (default 120)")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true", help="exit 1 if any Major claim exists")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    args = ap.parse_args()

    result = analyze(args.manuscript, args.min_sentence_span)
    if not args.quiet:
        print("=" * 41)
        print(" Parenthesis-Span Corruption")
        print("=" * 41)
        print(render(result))
        print()
        s = result["summary"]
        print(f"MAJOR candidate: {s['n_major']} wrapped-sentence span(s)." if s["n_major"]
              else "OK: no parenthesis-span corruption detected.")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_paren_spans", **result}, indent=2), encoding="utf-8")
        if not args.quiet:
            print(f"\nwrote {args.out}")

    return 1 if (args.strict and result["summary"]["n_major"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Perspective structural gate — two article-genre tells that mark a Perspective / opinion
essay drafted like an original article (self-review §J / §D). Genre-gated: fires only when the
manuscript is a Perspective (front-matter ``article_type:`` or ``--type``).

A Perspective's contribution lives in its prose, not in data, so two habits carried over from
IMRAD writing read as "this was drafted as a study, not argued":

  * **IMRAD section headings.** Published Perspectives name sections as argument-moves
    ("The model reads your account, not your patient"), never "Introduction / Methods / Results /
    Discussion". A generic IMRAD heading in a Perspective is the tell.
  * **A thesis abstract with no authorial move.** Eight of nine sampled npj Digital Medicine
    Perspectives open the abstract with an explicit "we argue" / "we propose" / "here we ...".
    A purely declarative abstract reads as a report, not a position.

Both are Minor (advisory). The gate never judges the argument — only these two surface forms.
Conclusion / Summary headings are allowed; an absent abstract is allowed (many Perspectives carry
the summary only in metadata / the submission portal, not the body).

Parser is deliberately careful (hardened against a Codex design review):
  * Only the leading ``---``-fenced front matter is read for the genre; a body ``**Article type**``
    line is ignored. Self-review passes its known type through ``--type``; on disagreement the gate
    warns and uses ``--type`` rather than guessing.
  * HTML comment blocks are blanked (newline-preserving) before any scan, so a commented-out
    ``## Methods`` is not flagged and a "we argue" inside a comment does not suppress the abstract
    verdict.
  * Only level-2 ``##`` headings are sections (``### Box 1`` is not); leading section numbers
    ("1.", "2.3") and markdown decoration are stripped before the IMRAD-token test.
  * Structural / front / back-matter headings (Title page, Abstract, Display items, Submission
    notes, References, ...) are skipped, never flagged.
  * The FIRST body Abstract is evaluated; a duplicate raises a parser warning.

v1 auto-activates on an exact "perspective" label only. Viewpoint / Comment are deferred until
they carry their own fixtures — a Lancet "Comment" and an RSNA "Perspective" are different genres.

Verdicts (both Minor; either can fire independently):
  PERSPECTIVE_HEADING_NOT_ASSERTION       a content-section heading is an IMRAD label.
  PERSPECTIVE_ABSTRACT_NO_AUTHORIAL_MOVE   a body abstract states its thesis with no authorial move.

Exit codes: 0 clean/report-only (Minor-only, so ``--strict`` never returns 1), 2 usage. Stdlib-only.

Usage:
    python3 check_perspective_structure.py --manuscript manuscript.md \
        [--type perspective] [--out qc/perspective_structure.json] [--min-words 120] \
        [--strict] [--quiet]
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

from _frontmatter import strip_frontmatter

DETECTOR = "check_perspective_structure"

# v1: exact "perspective" only. Viewpoint / Comment auto-activation deferred (different genres).
PERSPECTIVE_TYPES = {"perspective"}

HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.S)
H2_RE = re.compile(r"^##(?!#)\s+(.*\S)\s*$")
FENCE_RE = re.compile(r"```.*?```", re.S)
INLINE_RE = re.compile(r"[*_`]")
CITE_RE = re.compile(r"\[@[^\]]+\]|\[\d+(?:[,–-]\d+)*\]")
WORD_RE = re.compile(r"[A-Za-z0-9']+")
NUM_PREFIX_RE = re.compile(r"^\d+(?:\.\d+)*\.?\s+")
ARTICLE_TYPE_RE = re.compile(r"(?i)^\s*article[_-]?type\s*:\s*(.+?)\s*$")

IMRAD_TOKENS = {"introduction", "methods", "materials and methods", "results", "discussion"}

# Structural / front / back-matter headings — never a content argument-section, never flagged.
STRUCTURAL_SKIP = {
    "title page", "abstract", "keywords", "key points", "key messages", "essentials",
    "summary statement", "display items", "submission notes", "references", "reference",
    "data availability", "code availability", "acknowledgements", "acknowledgments",
    "author contributions", "competing interests", "conflicts of interest", "declarations",
    "funding", "supplementary information", "additional information", "figure legends",
    "figures", "tables", "abbreviations",
}

AUTHORIAL_MOVE_RE = re.compile(
    r"\b(?:we\s+(?:argue|propose|show|contend|claim|call|advocate|introduce|present|"
    r"demonstrate|find|maintain|hold|report|suggest)|here\s+we)\b",
    re.I,
)


def blank_comments(text: str) -> str:
    """Replace ``<!-- ... -->`` blocks with equal-count newlines (line structure preserved)."""
    return HTML_COMMENT_RE.sub(lambda m: "\n" * m.group(0).count("\n"), text)


def article_type_from_frontmatter(text: str) -> str | None:
    """Single ``article_type`` value from the leading ``---``-fenced front matter (casefolded)."""
    lines = text.splitlines()
    if not lines or lines[0].strip() != "---":
        return None
    for line in lines[1:]:
        if line.strip() == "---":
            break
        m = ARTICLE_TYPE_RE.match(line)
        if m:
            val = HTML_COMMENT_RE.sub("", m.group(1)).strip()
            if len(val) >= 2 and val[0] in "\"'" and val[-1] == val[0]:
                val = val[1:-1].strip()
            return val.casefold()
    return None


def normalize_heading(h: str) -> str:
    h = INLINE_RE.sub("", h).strip()
    h = NUM_PREFIX_RE.sub("", h)
    return h.strip().rstrip(".").strip().casefold()


def parse(md: str) -> dict:
    """Structural facts about the (front-matter-stripped, comment-blanked) manuscript."""
    body = blank_comments(strip_frontmatter(md))
    lines = body.splitlines()

    heads = []  # (line_index, raw, normalized)
    for i, line in enumerate(lines):
        m = H2_RE.match(line)
        if m:
            heads.append((i, m.group(1).strip(), normalize_heading(m.group(1))))

    imrad = [raw for (_, raw, norm) in heads
             if norm not in STRUCTURAL_SKIP and norm in IMRAD_TOKENS]

    abstract_idxs = [k for k, (_, _, norm) in enumerate(heads) if norm == "abstract"]
    abstract_text = None
    if abstract_idxs:
        k = abstract_idxs[0]
        start = heads[k][0] + 1
        end = heads[k + 1][0] if k + 1 < len(heads) else len(lines)
        chunk = "\n".join(lines[start:end])
        chunk = FENCE_RE.sub(" ", chunk)
        chunk = CITE_RE.sub("", chunk)
        chunk = INLINE_RE.sub("", chunk)
        abstract_text = re.sub(r"\s+", " ", chunk).strip()

    prose = []
    for line in lines:
        s = line.strip()
        if not s or s.startswith(("#", "|", ">", "!", "---")):
            continue
        if re.match(r"^\s*(?:[-*+]|\d+\.)\s", line):
            continue
        prose.append(s)
    n_words = len(WORD_RE.findall(" ".join(prose)))

    return {
        "n_words": n_words,
        "n_headings": len(heads),
        "imrad_headings": imrad,
        "abstract_section_count": len(abstract_idxs),
        "abstract_text": abstract_text,
    }


def check(md: str, front_type: str | None, cli_type: str | None, min_words: int) -> dict:
    warnings = []
    ft = front_type or None
    ct = cli_type.casefold() if cli_type else None
    if ct and ft and ct != ft:
        warnings.append(f"article_type mismatch: front-matter '{ft}' vs --type '{ct}'; using --type")
    active_type = ct or ft
    active = bool(active_type) and active_type in PERSPECTIVE_TYPES

    r = parse(md)
    findings = []
    if active and r["n_words"] >= min_words:
        if r["imrad_headings"]:
            findings.append({
                "verdict": "PERSPECTIVE_HEADING_NOT_ASSERTION",
                "severity": "Minor",
                "detail": (
                    f"{len(r['imrad_headings'])} IMRAD section heading(s) in a Perspective "
                    f"({', '.join(r['imrad_headings'])}) — published Perspectives name sections as "
                    "argument-moves, not \"Introduction / Methods / Results / Discussion\". Rename "
                    "each heading to the claim it makes; Conclusion / Summary are fine."
                ),
                "where": "; ".join(r["imrad_headings"]),
            })
        if r["abstract_text"] is not None and not AUTHORIAL_MOVE_RE.search(r["abstract_text"]):
            findings.append({
                "verdict": "PERSPECTIVE_ABSTRACT_NO_AUTHORIAL_MOVE",
                "severity": "Minor",
                "detail": (
                    "the abstract states its thesis declaratively, with no explicit authorial move "
                    "(\"we argue\" / \"we propose\" / \"here we ...\"). Eight of nine sampled npj "
                    "Digital Medicine Perspectives open the abstract with one; a report-style "
                    "abstract reads as a study, not a position. Lead the thesis with the move."
                ),
                "where": (r["abstract_text"][:70] + "...") if r["abstract_text"] else "",
            })
    if r["abstract_section_count"] > 1:
        warnings.append(f"{r['abstract_section_count']} '## Abstract' sections; evaluated the first")

    return {
        "metrics": {
            "active": active,
            "article_type": active_type,
            "body_words": r["n_words"],
            "imrad_heading_count": len(r["imrad_headings"]),
            "abstract_present": r["abstract_text"] is not None,
            "abstract_section_count": r["abstract_section_count"],
        },
        "warnings": warnings,
        "findings": findings,
    }


def main() -> int:
    ap = argparse.ArgumentParser(
        description="Perspective structural gate — IMRAD headings + abstract authorial move (§J/§D).")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--type", help="known article type (overrides front matter on disagreement)")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--min-words", type=int, default=120,
                    help="stay silent below this many body words (default 120)")
    ap.add_argument("--strict", action="store_true",
                    help="exit 1 if any Major (none — this gate is Minor-only)")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    a = ap.parse_args()

    src = Path(a.manuscript)
    if not src.is_file():
        sys.stderr.write(f"error: no such file: {src}\n")
        return 2

    raw = src.read_text(encoding="utf-8", errors="ignore")
    result = check(raw, article_type_from_frontmatter(raw), a.type, a.min_words)
    findings = result["findings"]
    m = result["metrics"]

    for w in result["warnings"]:
        sys.stderr.write(f"warning: {w}\n")

    if not a.quiet:
        print("=" * 42)
        print(" Perspective structure (§J / §D)")
        print("=" * 42)
        print("| Verdict | Severity | Detail |")
        print("|---|---|---|")
        if findings:
            for f in findings:
                print(f"| {f['verdict']} | {f['severity']} | {f['detail']} |")
            for f in findings:
                print(f"\n{f['verdict']} - {f['where']}")
        elif not m["active"]:
            print("| (none) | - | not gated as a Perspective |")
            print(f"\nOK: article_type={m['article_type']!r} is not a Perspective; no findings.")
        else:
            print("| (none) | - | Perspective structure within convention |")
            print("\nOK: argument-move headings and an abstract that carries an authorial move.")

    if a.out:
        out = Path(a.out)
        out.parent.mkdir(parents=True, exist_ok=True)
        out.write_text(json.dumps({
            "detector": DETECTOR,
            "manuscript": str(src),
            "metrics": m,
            "warnings": result["warnings"],
            "findings": findings,
        }, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
        if not a.quiet:
            print(f"\nwrote {out}")

    return 1 if (a.strict and any(f["severity"] == "Major" for f in findings)) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Reference adequacy gate for self-review Phase 2.5c-2 / write-paper Step 7.3c.

Reference INTEGRITY (are the cited references real and metadata-valid?) is the
job of verify-refs. This is the complementary REFERENCE ADEQUACY check: are
there enough relevant references, in the right sections, and does every named
statistical method or reporting guideline carry a citation? The highest-value,
most-deterministic instance is Methods named-method citation coverage -- an
autonomous draft can name a competing-risk model, multiple imputation, the
E-value, and an eGFR equation in its Statistical Analysis subsection with zero
citations and still read as internally consistent.

This gate NEVER proposes reference text. It diagnoses gaps (fixable_by_ai=false);
fix-forward belongs to /search-lit -> /lit-sync -> /verify-refs.

INPUTS
  --manuscript    manuscript markdown/qmd (required).
  --bib           optional refs.bib; reports the bib entry count for cross-check.
  --article-type  repo paper-type name or target bucket (see ALIASES); default
                  original_article.
  --journal-cap   optional journal reference cap (int).

OUTPUT  (--out path)
  {article_type, article_bucket, journal_cap, cited_reference_count,
   bib_entry_count, effective_target, section_distribution,
   named_methods_found, uncited_named_methods, methods_zero_citations,
   reference_count_verdict, adequacy_safe,
   findings[{issue_type, subtype, severity, location, description,
             fixable_by_ai, suggested_fix}], summary{major, minor, notes}}

Stdlib-only (re / json / argparse / pathlib). Exit codes: 0 clean (or
report-only), 1 a Major adequacy finding exists (with --strict), 2 input/usage
error.
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

# --------------------------------------------------------------------------- #
# Article-type targets and aliases (single SSOT for the named-method registry  #
# and the reference-count ranges; write-paper Step 7.3c calls this script      #
# directly rather than mirroring these constants).                             #
# --------------------------------------------------------------------------- #

# bucket -> (min, max) recommended reference count
TARGETS = {
    "original_research": (25, 45),
    "ai_validation": (25, 45),
    "meta_analysis": (40, 80),   # also systematic_review
    "review": (50, 100),         # narrative / review
    "technical_note": (10, 20),
    "case_report": (10, 20),
    "editorial": (5, 15),
    "letter": (0, 10),
    "perspective": (0, 90),      # opinion essay; count spans NEJM AI (<=5) to npj DM (40+)
}

# repo paper-type filename (skills/write-paper/references/paper_types/) -> bucket
ALIASES = {
    "original_article": "original_research",
    "original_research": "original_research",
    "nhis_cohort": "original_research",
    "cross_national": "original_research",
    "animal_study": "original_research",
    "ai_validation": "ai_validation",
    "meta_analysis": "meta_analysis",
    "systematic_review": "meta_analysis",
    "review": "review",
    "narrative": "review",
    "narrative_review": "review",
    "technical_note": "technical_note",
    "brief": "technical_note",
    "case_report": "case_report",
    "editorial": "editorial",
    "commentary": "editorial",
    "letter": "letter",
    "perspective": "perspective",
    "viewpoint": "perspective",
}

# Buckets where a Methods/Statistical-Analysis section is expected to carry
# citations; methods_zero_citations escalates to Major only for these.
METHODS_SECTION_EXPECTED = {"original_research", "ai_validation", "meta_analysis"}

# Named methods whose mention without a citation is a Major adequacy gap.
STATISTICAL = [
    "Cox proportional hazards", "Cox",
    "Fine-Gray", "competing risk", "subdistribution hazard",
    "multiple imputation", "MICE", "White-Royston",
    "E-value", "Benjamini-Hochberg", "FDR", "bootstrap", "Schoenfeld",
    "CKD-EPI", "Harrell C-index", "DeLong", "calibration", "Brier",
    "decision curve", "net benefit", "propensity score",
    "inverse probability weighting",
]
# Reporting/diagnostic standards whose mention without a citation is Minor.
GUIDELINE_REPORTING = [
    "GOLD", "FEV1/FVC", "STROBE", "TRIPOD", "CONSORT", "PRISMA", "STARD",
]

# --------------------------------------------------------------------------- #
# Citation-marker detection (union of pandoc, numbered, author-year,           #
# superscript). Paragraph-level clustering keeps the check conservative.       #
# --------------------------------------------------------------------------- #

_SUP = {"⁰": "0", "¹": "1", "²": "2", "³": "3", "⁴": "4",
        "⁵": "5", "⁶": "6", "⁷": "7", "⁸": "8", "⁹": "9"}
_SUP_CLASS = r"[⁰¹²³⁴-⁹]+"
# A name token allows internal apostrophes/hyphens (O'Brien, Smith-Jones).
_NAME = r"[A-Z][A-Za-z'’\-]+"

CITE_RE = re.compile(
    r"\[@[^\]]+\]"                                                  # pandoc [@key] / [@a; @b]
    r"|\[\d+(?:[–—-]\d+)?(?:,\s*\d+(?:[–—-]\d+)?)*\]"  # [12] [1-3] [1,2,5]
    r"|\((?:" + _NAME + r")(?:\s+(?:et al\.?|and|&)\s+" + _NAME + r")?,?\s*(?:19|20)\d{2}[a-z]?\)"  # (Author, 2020)
    r"|" + _SUP_CLASS,                                              # superscript ¹²
    re.UNICODE,
)


def normalize(text: str) -> str:
    """Fold non-breaking/figure hyphens to ASCII so 'E-value' matches."""
    return text.replace("‑", "-").replace("‐", "-")


def distinct_refs(body: str) -> set[str]:
    """Distinct reference identifiers cited in `body` (keys/numbers/author-year)."""
    keys: set[str] = set()
    for m in re.finditer(r"\[@([^\]]+)\]", body):
        for k in re.split(r"[;,]\s*@?", m.group(1)):
            k = k.strip().lstrip("@")
            if k:
                keys.add("@" + k)
    for m in re.finditer(r"\[(\d+(?:[–—-]\d+)?(?:,\s*\d+(?:[–—-]\d+)?)*)\]", body):
        for part in m.group(1).split(","):
            part = part.strip()
            rng = re.match(r"(\d+)[–—-](\d+)$", part)
            if rng:
                a, b = int(rng.group(1)), int(rng.group(2))
                if 0 < b - a < 500:
                    keys.update("#" + str(n) for n in range(a, b + 1))
            elif part.isdigit():
                keys.add("#" + part)
    for m in re.finditer(r"\((" + _NAME + r")(?:\s+(?:et al\.?|and|&)\s+" + _NAME +
                         r")?,?\s*((?:19|20)\d{2}[a-z]?)\)", body):
        keys.add("AY:" + m.group(1) + m.group(2))
    for m in re.finditer(_SUP_CLASS, body):
        num = "".join(_SUP.get(c, "") for c in m.group(0))
        if num:
            keys.add("^" + num)
    return keys


# --------------------------------------------------------------------------- #
# Section parsing                                                              #
# --------------------------------------------------------------------------- #

SEC_PATTERNS = {
    "introduction": re.compile(r"^(introduction|background)\b", re.I),
    "methods": re.compile(r"^(materials and methods|methods and materials|methods|"
                          r"statistical analysis|statistical methods)\b", re.I),
    "results": re.compile(r"^(results|findings)\b", re.I),
    "discussion": re.compile(r"^(discussion|comment)\b", re.I),
}


def top_sections(md: str) -> list[tuple[str, int, str]]:
    """Return (clean_title, level, body) for every header (any level)."""
    lines = md.split("\n")
    heads = []
    for i, line in enumerate(lines):
        m = re.match(r"(#{1,6})\s+(.*)$", line)
        if m:
            title = re.sub(r"[*_`]", "", m.group(2)).strip()
            heads.append((i, len(m.group(1)), title))
    out = []
    for idx, (li, lvl, title) in enumerate(heads):
        end = len(lines)
        for lj, lvl2, _ in heads[idx + 1:]:
            if lvl2 <= lvl:
                end = lj
                break
        out.append((title, lvl, "\n".join(lines[li + 1:end])))
    return out


def section_text(sections, key: str) -> str:
    """Concatenate top-level (h1/h2) section bodies matching a canonical key."""
    pat = SEC_PATTERNS[key]
    return "\n\n".join(body for title, lvl, body in sections
                       if lvl <= 2 and pat.match(title))


# --------------------------------------------------------------------------- #
# Named-method coverage                                                        #
# --------------------------------------------------------------------------- #

def scan_named_methods(methods_body: str) -> dict[str, dict]:
    """term -> {cited: bool, tier: 'stat'|'guide'} for every registry term found.

    A term is 'cited' if any paragraph containing it also carries a citation
    marker. Longest term first so 'Cox proportional hazards' claims its span
    before the bare 'Cox' can double-count it.
    """
    terms = [(t, "stat") for t in STATISTICAL] + [(t, "guide") for t in GUIDELINE_REPORTING]
    terms.sort(key=lambda x: -len(x[0]))
    compiled = [(t, tier, re.compile(r"(?<![A-Za-z0-9])" + re.escape(t) + r"(?![A-Za-z0-9])", re.I))
                for t, tier in terms]
    found: dict[str, dict] = {}
    for para in re.split(r"\n\s*\n", methods_body):
        has_cite = bool(CITE_RE.search(para))
        covered: list[tuple[int, int]] = []
        for term, tier, pat in compiled:
            for m in pat.finditer(para):
                span = (m.start(), m.end())
                if any(span[0] >= c[0] and span[1] <= c[1] for c in covered):
                    continue
                covered.append(span)
                rec = found.setdefault(term, {"cited": False, "tier": tier})
                rec["cited"] = rec["cited"] or has_cite
                break
    return found


# --------------------------------------------------------------------------- #
# Main                                                                         #
# --------------------------------------------------------------------------- #

def _finding(subtype, severity, location, description, fix):
    return {"issue_type": "reference_adequacy", "subtype": subtype,
            "severity": severity, "location": location, "description": description,
            "fixable_by_ai": False, "suggested_fix": fix}


def assess(manuscript: str, article_type: str, journal_cap, bib_entry_count) -> dict:
    notes = []
    key = article_type.strip().lower().replace(" ", "_").replace("-", "_")
    bucket = ALIASES.get(key)
    if bucket is None:
        bucket = "original_research"
        notes.append(f"unknown article-type '{article_type}'; defaulted to original_research")

    sections = top_sections(manuscript)
    methods_body = section_text(sections, "methods")
    distribution = {k: len(distinct_refs(section_text(sections, k))) for k in SEC_PATTERNS}
    cited_count = len(distinct_refs(manuscript))

    found = scan_named_methods(methods_body)
    methods_has_citation = bool(CITE_RE.search(methods_body))
    methods_zero_citations = bool(methods_body.strip()) and not methods_has_citation

    named_methods_found = sorted(found)
    uncited = sorted(t for t, r in found.items() if not r["cited"])

    amin, amax = TARGETS[bucket]
    if journal_cap is not None and journal_cap < amin:
        eff_min, eff_max = journal_cap, journal_cap
        notes.append(f"journal cap {journal_cap} below article-type floor {amin}; "
                     f"effective target lowered to the cap")
    else:
        eff_min, eff_max = amin, amax

    findings = []

    if methods_zero_citations and bucket in METHODS_SECTION_EXPECTED:
        listed = ", ".join(named_methods_found) if named_methods_found else "named methods/scores"
        findings.append(_finding(
            "methods_zero_citations", "major", "Methods - Statistical Analysis",
            f"The Methods/Statistical Analysis section contains no citations; every named "
            f"method, score, guideline, and diagnostic criterion needs a canonical source "
            f"(found uncited: {listed}).",
            "Run /search-lit (paper mode) for canonical methodology sources, sync via "
            "/lit-sync, then rerun /verify-refs --strict."))
    else:
        for term in uncited:
            if found[term]["tier"] == "stat":
                findings.append(_finding(
                    "methods_named_method_uncited", "major", "Methods - Statistical Analysis",
                    f"{term} is named in the Statistical Analysis subsection without a citation "
                    f"in its paragraph.",
                    f"Run /search-lit (paper mode) for the canonical {term} source, sync via "
                    f"/lit-sync, then rerun /verify-refs --strict."))
            else:
                findings.append(_finding(
                    "reporting_guideline_uncited", "minor", "Methods",
                    f"The {term} standard is named without a citation in its paragraph.",
                    f"Run /search-lit for the {term} reference, sync via /lit-sync, then rerun "
                    f"/verify-refs --strict."))

    verdict = "ADEQUATE" if cited_count >= eff_min else "BELOW_TARGET"
    if verdict == "BELOW_TARGET":
        sev = "major" if cited_count < 0.5 * eff_min else "minor"
        findings.append(_finding(
            "below_article_type_target", sev, "Whole manuscript",
            f"Cited references ({cited_count}) are below the {bucket} target "
            f"({eff_min}-{eff_max}).",
            "Run /search-lit (paper mode) to retrieve verified candidates across the six "
            "categories, sync via /lit-sync, then rerun /verify-refs --strict."))

    n_major = sum(1 for f in findings if f["severity"] == "major")
    n_minor = sum(1 for f in findings if f["severity"] == "minor")

    return {
        "article_type": article_type,
        "article_bucket": bucket,
        "journal_cap": journal_cap,
        "cited_reference_count": cited_count,
        "bib_entry_count": bib_entry_count,
        "effective_target": [eff_min, eff_max],
        "section_distribution": distribution,
        "named_methods_found": named_methods_found,
        "uncited_named_methods": uncited,
        "methods_zero_citations": methods_zero_citations,
        "reference_count_verdict": verdict,
        "adequacy_safe": n_major == 0,
        "findings": findings,
        "summary": {"major": n_major, "minor": n_minor, "notes": notes},
    }


def count_bib_entries(bib_path: Path) -> int:
    try:
        text = bib_path.read_text(encoding="utf-8", errors="replace")
    except OSError:
        return -1
    return len(re.findall(r"^\s*@\w+\s*\{", text, re.M))


def main() -> int:
    ap = argparse.ArgumentParser(description="Reference adequacy gate (count + section + named-method coverage).")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/qmd")
    ap.add_argument("--bib", help="optional refs.bib (reports entry count)")
    ap.add_argument("--article-type", default="original_article",
                    help="repo paper-type name or target bucket (see ALIASES)")
    ap.add_argument("--journal-cap", type=int, help="optional journal reference cap")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true", help="exit 1 if any Major adequacy finding")
    ap.add_argument("--quiet", action="store_true", help="suppress the stdout table")
    args = ap.parse_args()

    mp = Path(args.manuscript)
    if not mp.is_file():
        sys.stderr.write(f"ERROR: manuscript not found: {args.manuscript}\n")
        return 2
    manuscript = normalize(mp.read_text(encoding="utf-8"))

    bib_entry_count = None
    if args.bib:
        bp = Path(args.bib)
        if bp.is_file():
            bib_entry_count = count_bib_entries(bp)
        else:
            sys.stderr.write(f"WARN: bib not found: {args.bib} (bib entry count skipped)\n")

    result = assess(manuscript, args.article_type, args.journal_cap, bib_entry_count)

    if not args.quiet:
        s = result
        print("=" * 46)
        print(" Reference Adequacy Gate (count + named methods)")
        print("=" * 46)
        print(f" Article type   : {s['article_type']} -> {s['article_bucket']}")
        print(f" Cited refs     : {s['cited_reference_count']}  "
              f"(target {s['effective_target'][0]}-{s['effective_target'][1]}"
              f"{', cap ' + str(s['journal_cap']) if s['journal_cap'] is not None else ''})")
        d = s["section_distribution"]
        print(f" Distribution   : Intro {d['introduction']} / Methods {d['methods']} / "
              f"Results {d['results']} / Discussion {d['discussion']}")
        print(f" Methods 0-cite : {s['methods_zero_citations']}")
        if s["uncited_named_methods"]:
            print(f" Uncited methods: {', '.join(s['uncited_named_methods'])}")
        for f in s["findings"]:
            mark = "✗" if f["severity"] == "major" else "△"
            print(f" {mark} [{f['severity']}] {f['subtype']}: {f['description']}")
        print(f"\n Verdict: {s['reference_count_verdict']}  |  "
              f"{s['summary']['major']} major, {s['summary']['minor']} minor  |  "
              f"adequacy_safe={s['adequacy_safe']}")
        for note in s["summary"]["notes"]:
            print(f"   note: {note}")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_reference_adequacy", **result}, indent=2), encoding="utf-8")
        if not args.quiet:
            print(f" wrote {args.out}")

    return 1 if (args.strict and result["summary"]["major"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""check_reported_p_from_counts.py — recompute each 2x2 table row's P value from its
own integer counts and flag a reported P that reproduces under no standard test.

A baseline table comparing two groups prints a count per group and a P value per
row. That P is fully determined by the four cell counts, yet a wrong one (e.g. a
reported ``p<0.001`` whose true value is ~0.06) routinely survives review because
no one recomputes it. This detector rebuilds the 2x2 table for every count row,
recomputes Fisher's exact test and Pearson's chi-square (with and without Yates'
correction) in pure stdlib, *calibrates* which family the manuscript used on the
rows that reproduce, and flags any row whose reported P differs by more than one
order of magnitude under **every** family.

Guards: continuous rows (mean ± SD, median [IQR]) are skipped; at least two count
rows are required so the family can be calibrated; a single-row table never fires.

Stdlib-only (math.comb / math.erfc). Reads the manuscript, never writes it.

Usage:
  python3 check_reported_p_from_counts.py --manuscript paper.md [--strict] [--quiet] [--json]
Exit: 0 clean; with --strict, 1 on any P_NOT_REPRODUCIBLE; 2 on input/usage error.
"""
from __future__ import annotations

import argparse
import json
import math
import re
import sys
from dataclasses import dataclass, field, asdict

SEP_RE = re.compile(r"^\s*\|?[\s:|-]*-[\s:|-]*\|?\s*$")
HEADER_N_RE = re.compile(r"\bn\s*=\s*([0-9][0-9,]*)", re.I)
PVAL_HEADER_RE = re.compile(r"^\s*\*?\s*[Pp]\s*(?:[- ]?value)?\s*\*?\s*$")
PVAL_HEADER_CONTAINS = re.compile(r"\bp[- ]?value\b", re.I)
COUNT_CELL_RE = re.compile(r"^\s*(\d[\d,]*)\s*(?:\(|$)")          # integer count, optionally "count (pct)"
PVAL_CELL_RE = re.compile(r"^\s*([<=]?)\s*(0?\.\d+|\d+(?:\.\d+)?)\s*$")
FAMILIES = ("Fisher exact", "Pearson chi-square (Yates)", "Pearson chi-square (uncorrected)")


@dataclass
class Finding:
    kind: str
    severity: str
    line: int
    detail: str


@dataclass
class Report:
    source: str
    findings: list[Finding] = field(default_factory=list)

    @property
    def n_flag(self) -> int:
        return sum(1 for f in self.findings if f.kind == "P_NOT_REPRODUCIBLE")

    @property
    def verdict(self) -> str:
        return "NON-REPRODUCIBLE P" if self.n_flag else "OK"


def _split_row(line: str) -> list[str]:
    s = line.strip()
    if s.startswith("|"):
        s = s[1:]
    if s.endswith("|"):
        s = s[:-1]
    return [c.strip() for c in s.split("|")]


def _fisher(a: int, b: int, c: int, d: int) -> float:
    r1, r2, c1, n = a + b, c + d, a + c, a + b + c + d
    if 0 in (r1, r2, c1, b + d):
        return 1.0
    denom = math.comb(n, c1)
    lo, hi = max(0, c1 - r2), min(r1, c1)
    p_obs = math.comb(r1, a) * math.comb(r2, c1 - a) / denom
    tol = p_obs * (1 + 1e-7)
    total = sum(math.comb(r1, k) * math.comb(r2, c1 - k) / denom
                for k in range(lo, hi + 1)
                if math.comb(r1, k) * math.comb(r2, c1 - k) / denom <= tol)
    return min(1.0, total)


def _chi2(a: int, b: int, c: int, d: int, yates: bool) -> float:
    n = a + b + c + d
    r1, r2, c1, c2 = a + b, c + d, a + c, b + d
    if 0 in (r1, r2, c1, c2):
        return 1.0
    num = abs(a * d - b * c)
    if yates:
        num = max(0.0, num - n / 2)
    chi2 = n * num * num / (r1 * r2 * c1 * c2)
    return math.erfc(math.sqrt(chi2 / 2))  # 1 df


def _pvals(a: int, b: int, c: int, d: int) -> tuple[float, float, float]:
    return _fisher(a, b, c, d), _chi2(a, b, c, d, True), _chi2(a, b, c, d, False)


def _order_gap(rep_op: str, rep_val: float, comp: float) -> float:
    """log10 gap between reported and computed; for '<' bounds, only a computed
    value ABOVE the bound counts (a computed below the claimed upper bound is fine)."""
    if comp <= 0 or rep_val <= 0:
        return 0.0
    if rep_op == "<":
        return max(0.0, math.log10(comp) - math.log10(rep_val))
    return abs(math.log10(comp) - math.log10(rep_val))


def audit(text: str, source: str) -> Report:
    rep = Report(source=source)
    lines = text.splitlines()
    i, n = 0, len(lines)
    while i < n:
        if not ("|" in lines[i] and i + 1 < n and SEP_RE.match(lines[i + 1]) and "-" in lines[i + 1]):
            i += 1
            continue
        header = _split_row(lines[i])
        lineno0 = i + 1
        group_cols = [j for j, h in enumerate(header) if HEADER_N_RE.search(h)]
        p_col = next((j for j, h in enumerate(header)
                      if PVAL_HEADER_RE.match(h) or PVAL_HEADER_CONTAINS.search(h)), None)
        # gather rows
        rows = []
        j = i + 2
        while j < n and "|" in lines[j] and lines[j].strip():
            rows.append((_split_row(lines[j]), j + 1))
            j += 1
        i = j
        if len(group_cols) < 2 or p_col is None:
            continue
        g1, g2 = group_cols[0], group_cols[1]
        n1 = int(HEADER_N_RE.search(header[g1]).group(1).replace(",", ""))
        n2 = int(HEADER_N_RE.search(header[g2]).group(1).replace(",", ""))

        parsed = []
        for cells, ln in rows:
            if max(g1, g2, p_col) >= len(cells):
                continue
            m1, m2 = COUNT_CELL_RE.match(cells[g1]), COUNT_CELL_RE.match(cells[g2])
            pm = PVAL_CELL_RE.match(cells[p_col])
            if not (m1 and m2 and pm):
                continue  # continuous row (mean±SD / IQR) or no P
            a, c = int(m1.group(1).replace(",", "")), int(m2.group(1).replace(",", ""))
            if a > n1 or c > n2:
                continue
            b, d = n1 - a, n2 - c
            parsed.append((cells[0], ln, a, b, c, d, pm.group(1) or "=", float(pm.group(2))))

        if len(parsed) < 2:
            continue  # cannot calibrate the family on a single row

        # calibrate: which family reproduces the most rows to <= 1e-3 (op '=')?
        computed = [(_pvals(a, b, c, d)) for _, _, a, b, c, d, _, _ in parsed]
        repro = [0, 0, 0]
        for (lbl, ln, a, b, c, d, op, val), pv in zip(parsed, computed):
            if op == "=":
                for k in range(3):
                    if abs(pv[k] - val) <= 1e-3:
                        repro[k] += 1
        fam_idx = max(range(3), key=lambda k: repro[k]) if any(repro) else 2

        for (lbl, ln, a, b, c, d, op, val), pv in zip(parsed, computed):
            gaps = [_order_gap(op, val, pv[k]) for k in range(3)]
            if min(gaps) > 1.0:  # differs by >1 order under EVERY family
                closest = min(range(3), key=lambda k: gaps[k])
                rep.findings.append(Finding(
                    "P_NOT_REPRODUCIBLE", "MAJOR", ln,
                    f"row '{lbl}' ({a}/{a+b} vs {c}/{c+d}) reports P{op}{val:g}, but recomputes to "
                    f"Fisher {pv[0]:.3g} / Yates {pv[1]:.3g} / uncorrected {pv[2]:.3g} "
                    f"(closest {FAMILIES[closest]}; table family ≈ {FAMILIES[fam_idx]})"))
    return rep


def format_report(rep: Report, color: bool) -> str:
    tag = {"OK": "\033[92m", "NON-REPRODUCIBLE P": "\033[91m"}.get(rep.verdict, "") if color else ""
    end = "\033[0m" if color else ""
    out = [f"{tag}== {rep.verdict} =={end}  {rep.source}", f"non_reproducible={rep.n_flag}"]
    if not rep.findings:
        out.append("every reported P reproduces from its counts under a standard test.")
        return "\n".join(out)
    for f in sorted(rep.findings, key=lambda x: (x.line, x.detail)):
        out.append(f"[{f.severity}] {f.kind} L{f.line}  {f.detail}")
    return "\n".join(out)


def main(argv: list[str] | None = None) -> int:
    ap = argparse.ArgumentParser(description=__doc__,
                                 formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--strict", action="store_true", help="exit 1 on any P_NOT_REPRODUCIBLE")
    ap.add_argument("--quiet", action="store_true", help="suppress the report; exit code only")
    ap.add_argument("--json", action="store_true", help="emit JSON instead of a text report")
    args = ap.parse_args(argv)
    try:
        text = open(args.manuscript, encoding="utf-8").read()
    except OSError as e:
        print(f"error: cannot read manuscript: {e}", file=sys.stderr)
        return 2
    rep = audit(text, args.manuscript)
    if not args.quiet:
        if args.json:
            print(json.dumps({"detector": "check_reported_p_from_counts", "source": rep.source, "verdict": rep.verdict,
                              "findings": [asdict(f) for f in rep.findings]},
                             ensure_ascii=False, indent=2))
        else:
            print(format_report(rep, color=sys.stdout.isatty()))
    return 1 if (args.strict and rep.n_flag) else 0


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

#!/usr/bin/env python3
"""
check_reviewer_team_consistency.py — fabrication-grade self-review check.

Detects manuscripts that simultaneously claim dual independent reviewers
(in Methods + PROSPERO) and confess to single-reviewer execution (in
Discussion §Limitations). Either claim alone is fine; the conjunction is
a fabrication-grade red flag.

Why this check exists
=====================
Cross-project precedent (anonymized): a reporting-quality SR-of-AI-tools
manuscript had:
- Methods: "Two reviewers independently screened titles and abstracts ..."
- PROSPERO record: "Two independent reviewers will perform full-text
  screening and data extraction."
- Discussion §Limitations: "Single primary reviewer; a 20% sample by an
  additional reviewer is deferred to before submission."

The conjunction admits in Limitations what Methods denies in narrative
form. Reviewers and editors who notice this read it as fabrication-grade
(the manuscript misrepresents what was actually done) and reject.

Detection strategy
==================
Section-aware grep for two regex families:
- DUAL claim: "(independently|dual|two reviewers|both reviewers|two
  independent)" within Methods OR a PROSPERO record file.
- SINGLE confession: "(single primary reviewer|one additional reviewer|
  20% sample|sample of records|deferred to before submission|due to
  resource constraints|by the first reviewer alone)" within Limitations
  OR Discussion.

Both present → MAJOR self-review red flag.

Two further fabrication-grade axes (the prose↔JSON↔confession 3-way):
- LLM-AS-REVIEWER (fatal): a per-study extraction JSON whose reviewer /
  screener / extractor / rater field is an LLM ("Claude", "GPT-4", "LLM",
  "Gemini"). An LLM is a tool, not an independent reviewer; listing it as
  one misrepresents the screening team regardless of the prose. Pass the
  extraction JSON (file or directory) via --extraction-json.
- DEFERRED-MITIGATION (MAJOR): a future-tense mitigation promise — "a 20%
  sample will be completed before submission" — that is unmet at the time
  the manuscript circulates. The promise is evidence the work is not done.

Usage
=====

    python check_reviewer_team_consistency.py \\
        --manuscript manuscript.md \\
        --prospero prospero/record.md \\
        --out _audit_self/reviewer_team_consistency.md

Output
======
Markdown report at `--out` summarizing matches. Also a JSON sidecar at
`--out` + ".json".

Exit codes
==========
  0  no conflict
  1  MAJOR red flag detected (both DUAL and SINGLE patterns present)
  2  invocation error
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from dataclasses import dataclass, field
from pathlib import Path


DUAL_PATTERNS = [
    (
        re.compile(r"\btwo\s+(?:independent\s+)?reviewers?\b", re.IGNORECASE),
        "two reviewers",
    ),
    (re.compile(r"\bdual\s+(?:independent\s+)?(?:reviewers?|extractors?)\b", re.IGNORECASE),
     "dual reviewers"),
    (re.compile(r"\bindependent(?:ly)?\s+screened\b", re.IGNORECASE), "independently screened"),
    (
        re.compile(r"\bboth\s+reviewers?\s+(?:independently|extracted|screened)\b", re.IGNORECASE),
        "both reviewers",
    ),
    (
        re.compile(r"\bindependent(?:ly)?\s+(?:extracted|coded|assessed)\b", re.IGNORECASE),
        "independent extraction",
    ),
    (
        re.compile(r"\bindependent\s+reviewers?\b", re.IGNORECASE),
        "independent reviewers",
    ),
]

SINGLE_PATTERNS = [
    (re.compile(r"\bsingle\s+primary\s+reviewer\b", re.IGNORECASE), "single primary reviewer"),
    (
        re.compile(r"\bone\s+additional\s+reviewer\b", re.IGNORECASE),
        "one additional reviewer",
    ),
    (
        re.compile(r"\b20\s*%?\s+sample\b", re.IGNORECASE),
        "20% sample",
    ),
    (
        re.compile(r"\bsample\s+of\s+records\b", re.IGNORECASE),
        "sample of records",
    ),
    (
        re.compile(r"\bdeferred\s+to\s+before\s+submission\b", re.IGNORECASE),
        "deferred to before submission",
    ),
    (
        re.compile(r"\bdue\s+to\s+resource\s+constraints\b", re.IGNORECASE),
        "due to resource constraints",
    ),
    (
        re.compile(r"\b(?:by|with)\s+(?:the\s+)?first\s+reviewer\s+(?:alone|only)\b", re.IGNORECASE),
        "first reviewer alone",
    ),
]


# An LLM named where an independent reviewer should be (fatal). Bare "ai" is too
# broad (matches names), so it is excluded; explicit model families + "LLM" only.
LLM_NAME_RE = re.compile(
    r"\b(?:claude|chatgpt|gpt-?\d|gpt|llm|large language model|gemini|copilot|bard|"
    r"ai model|an ai\b)\b", re.IGNORECASE)
REVIEWER_KEY_RE = re.compile(
    r"reviewer|screener|extractor|rater|annotator|adjudicator|coder", re.IGNORECASE)

# A future-tense mitigation promised but not yet executed at circulation.
DEFERRED_MITIGATION_RE = re.compile(
    r"(?:will be|to be|is to be|are to be)\s+"
    r"(?:completed|performed|conducted|done|undertaken|carried out|finalized|finalised)\b"
    r"[^.]{0,80}?(?:before|prior to|ahead of)\s+(?:final\s+)?submission",
    re.IGNORECASE)


SECTION_HEADERS = {
    "Methods": re.compile(
        r"^#{1,3}\s*\*{0,2}(?:METHODS?|Method[s]?|Materials and Methods)\*{0,2}\s*$",
        re.IGNORECASE | re.MULTILINE,
    ),
    "Discussion": re.compile(
        r"^#{1,3}\s*\*{0,2}(?:DISCUSSION|Discussion)\*{0,2}\s*$",
        re.IGNORECASE | re.MULTILINE,
    ),
    "Limitations": re.compile(
        r"^#{1,3}\s*\*{0,2}(?:LIMITATIONS?|Limitations?|Study Limitations)\*{0,2}\s*$",
        re.IGNORECASE | re.MULTILINE,
    ),
}


@dataclass
class Hit:
    pattern_label: str
    line: int
    context: str


@dataclass
class Report:
    submission_safe: bool
    dual_hits: list[dict] = field(default_factory=list)
    single_hits: list[dict] = field(default_factory=list)
    llm_reviewer_hits: list[dict] = field(default_factory=list)
    deferred_mitigation_hits: list[dict] = field(default_factory=list)


def split_sections(text: str) -> dict[str, str]:
    out: dict[str, str] = {name: "" for name in SECTION_HEADERS}
    headers: list[tuple[str, int, int]] = []
    for name, pat in SECTION_HEADERS.items():
        for m in pat.finditer(text):
            headers.append((name, m.start(), m.end()))
    headers.sort(key=lambda t: t[1])
    for i, (name, _, hdr_end) in enumerate(headers):
        end = headers[i + 1][1] if i + 1 < len(headers) else len(text)
        out[name] = (out[name] + "\n" + text[hdr_end:end]).strip()
    return out


def scan_text(text: str, patterns: list[tuple[re.Pattern[str], str]]) -> list[Hit]:
    hits: list[Hit] = []
    lines = text.splitlines()
    for lineno, line in enumerate(lines, start=1):
        for pat, label in patterns:
            if pat.search(line):
                ctx = line.strip()
                if len(ctx) > 200:
                    ctx = ctx[:200] + "..."
                hits.append(Hit(pattern_label=label, line=lineno, context=ctx))
    return hits


def hit_to_dict(h: Hit, source: str) -> dict:
    return {
        "source": source,
        "pattern": h.pattern_label,
        "line": h.line,
        "context": h.context,
    }


def _iter_extraction_files(path: Path):
    if path.is_dir():
        yield from sorted(path.rglob("*.json"))
    elif path.is_file():
        yield path


def _walk_reviewer_fields(obj, source: str, hits: list[dict], keypath: str = "") -> None:
    """Recursively find reviewer-role fields whose value names an LLM."""
    if isinstance(obj, dict):
        for k, v in obj.items():
            kp = f"{keypath}.{k}" if keypath else str(k)
            if isinstance(v, str) and REVIEWER_KEY_RE.search(str(k)) and LLM_NAME_RE.search(v):
                hits.append({"source": source, "field": kp, "value": v[:120]})
            _walk_reviewer_fields(v, source, hits, kp)
    elif isinstance(obj, list):
        for i, v in enumerate(obj):
            _walk_reviewer_fields(v, source, hits, f"{keypath}[{i}]")


def scan_llm_reviewers(extraction: Path | None) -> list[dict]:
    hits: list[dict] = []
    if extraction is None:
        return hits
    for f in _iter_extraction_files(extraction):
        try:
            data = json.loads(f.read_text(encoding="utf-8"))
        except (json.JSONDecodeError, OSError):
            continue
        _walk_reviewer_fields(data, f.name, hits)
    return hits


def scan_deferred_mitigation(manuscript: str) -> list[dict]:
    hits: list[dict] = []
    for lineno, line in enumerate(manuscript.splitlines(), start=1):
        m = DEFERRED_MITIGATION_RE.search(line)
        if m:
            hits.append({"source": "manuscript", "line": lineno, "context": m.group(0).strip()[:160]})
    return hits


def build_report(manuscript: str, prospero: str | None,
                 extraction: Path | None = None) -> Report:
    sections = split_sections(manuscript)

    dual_hits: list[dict] = []
    single_hits: list[dict] = []

    # Methods → DUAL evidence.
    for h in scan_text(sections.get("Methods", ""), DUAL_PATTERNS):
        dual_hits.append(hit_to_dict(h, "manuscript:Methods"))

    # PROSPERO → DUAL evidence.
    if prospero is not None:
        for h in scan_text(prospero, DUAL_PATTERNS):
            dual_hits.append(hit_to_dict(h, "prospero"))

    # Discussion & Limitations → SINGLE evidence.
    for region in ("Limitations", "Discussion"):
        for h in scan_text(sections.get(region, ""), SINGLE_PATTERNS):
            single_hits.append(hit_to_dict(h, f"manuscript:{region}"))

    llm_reviewer_hits = scan_llm_reviewers(extraction)
    deferred_hits = scan_deferred_mitigation(manuscript)

    submission_safe = not (
        (dual_hits and single_hits) or llm_reviewer_hits or deferred_hits
    )
    return Report(
        submission_safe=submission_safe,
        dual_hits=dual_hits,
        single_hits=single_hits,
        llm_reviewer_hits=llm_reviewer_hits,
        deferred_mitigation_hits=deferred_hits,
    )


def _render_extra(lines: list[str], report: Report) -> None:
    if report.llm_reviewer_hits:
        lines.append("")
        lines.append("## LLM-AS-REVIEWER (fatal)")
        lines.append("An LLM is named where an independent reviewer is required:")
        for h in report.llm_reviewer_hits:
            lines.append(f"- `{h['source']}` field `{h['field']}` = {h['value']}")
        lines.append("Fix: list a human reviewer; an LLM is a tool, not a member of the review team.")
    if report.deferred_mitigation_hits:
        lines.append("")
        lines.append("## DEFERRED-MITIGATION (MAJOR)")
        lines.append("A mitigation is promised in the future tense but not yet executed:")
        for h in report.deferred_mitigation_hits:
            lines.append(f"- line {h['line']}: {h['context']}")
        lines.append("Fix: execute and report the mitigation before circulation, or remove the claim.")


def render_markdown(report: Report) -> str:
    lines = ["# Reviewer-team consistency audit", ""]
    if report.submission_safe:
        lines.append(
            "Status: **PASS** — no conjunction of DUAL claim + SINGLE confession."
        )
        lines.append("")
        if report.dual_hits:
            lines.append(f"DUAL claims found ({len(report.dual_hits)}, OK alone):")
            for h in report.dual_hits:
                lines.append(f"- `{h['source']}` line {h['line']}: `{h['pattern']}` — {h['context']}")
        if report.single_hits:
            lines.append("")
            lines.append(f"SINGLE confessions found ({len(report.single_hits)}, OK alone):")
            for h in report.single_hits:
                lines.append(f"- `{h['source']}` line {h['line']}: `{h['pattern']}` — {h['context']}")
    else:
        triggers = []
        if report.dual_hits and report.single_hits:
            triggers.append("DUAL claim + SINGLE confession")
        if report.llm_reviewer_hits:
            triggers.append("LLM-as-reviewer")
        if report.deferred_mitigation_hits:
            triggers.append("deferred mitigation")
        lines.append(f"Status: **MAJOR red flag** — {', '.join(triggers)}.")
        lines.append("")
        lines.append("Reviewers will read this as fabrication-grade.")
        if report.dual_hits and report.single_hits:
            lines.append("")
            lines.append("## DUAL claims (Methods / PROSPERO)")
            for h in report.dual_hits:
                lines.append(f"- `{h['source']}` line {h['line']}: `{h['pattern']}`")
                lines.append(f"  > {h['context']}")
            lines.append("")
            lines.append("## SINGLE confessions (Discussion / Limitations)")
            for h in report.single_hits:
                lines.append(f"- `{h['source']}` line {h['line']}: `{h['pattern']}`")
                lines.append(f"  > {h['context']}")
        _render_extra(lines, report)
    return "\n".join(lines) + "\n"


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        description="Reviewer-team consistency check (fabrication-grade self-review)."
    )
    parser.add_argument("--manuscript", type=Path, required=True)
    parser.add_argument("--prospero", type=Path, default=None)
    parser.add_argument(
        "--extraction-json", type=Path, default=None,
        help="per-study extraction JSON file or directory (reviewer-field LLM scan)",
    )
    parser.add_argument(
        "--out",
        type=Path,
        default=Path("_audit_self/reviewer_team_consistency.md"),
    )
    parser.add_argument("--quiet", action="store_true")
    args = parser.parse_args(argv)

    if not args.manuscript.is_file():
        print(f"ERROR: manuscript not found: {args.manuscript}", file=sys.stderr)
        return 2
    prospero_text: str | None = None
    if args.prospero is not None:
        if not args.prospero.is_file():
            print(f"ERROR: prospero not found: {args.prospero}", file=sys.stderr)
            return 2
        prospero_text = args.prospero.read_text(encoding="utf-8")
    if args.extraction_json is not None and not args.extraction_json.exists():
        print(f"ERROR: extraction-json not found: {args.extraction_json}", file=sys.stderr)
        return 2

    text = args.manuscript.read_text(encoding="utf-8")
    report = build_report(text, prospero_text, args.extraction_json)

    args.out.parent.mkdir(parents=True, exist_ok=True)
    args.out.write_text(render_markdown(report), encoding="utf-8")
    json_out = args.out.with_suffix(args.out.suffix + ".json")
    json_out.write_text(
        json.dumps({"detector": "check_reviewer_team_consistency", "submission_safe": report.submission_safe,
                "dual_hits": report.dual_hits,
                "single_hits": report.single_hits,
                "llm_reviewer_hits": report.llm_reviewer_hits,
                "deferred_mitigation_hits": report.deferred_mitigation_hits,
            },
            indent=2,
        ),
        encoding="utf-8",
    )

    if not args.quiet:
        counts = (f"DUAL={len(report.dual_hits)} SINGLE={len(report.single_hits)} "
                  f"LLM={len(report.llm_reviewer_hits)} "
                  f"DEFERRED={len(report.deferred_mitigation_hits)}")
        if report.submission_safe:
            print(f"PASS: no fabrication-grade conflict. {counts}")
        else:
            print(f"FAIL: MAJOR red flag. {counts}")
            print(f"See {args.out}")

    return 0 if report.submission_safe else 1


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Rhetorical-construction density gate — antithesis parallelism and cleft, two
sentence-structure AI tells (self-review §J / humanize P27).

LLM-drafted argumentative prose over-builds two marked constructions that a per-instance
rule cannot flag, because each single occurrence is grammatical and often functional:

  * **antithesis parallelism** — "authority rather than cognition", "not a check but a
    second road", "involvement, not independence". One is a legitimate contrast; a run of
    them is an epigram machine. This was the dominant tell (28 "rather than" in one draft)
    an external reader found in prose that had already cleared the em-dash / passive / word
    sweeps.
  * **cleft / pseudo-cleft** — sentence-initial "What matters is …", "It is X that …". A
    fronting construction the model reaches for to sound weighty.

Neither is wrong once. What marks the machine draft is DENSITY: the reader meets a "rather
than" or a fronted clause every few sentences. So this gate never judges a single instance
— it counts them per 1,000 body words and fires only when the rate AND a raw floor both
clear a threshold set above the rate seen in this project's own published-quality demos
(where "rather than" runs 1.4-3.7 / 1,000 and sentence-initial clefts are absent). A lone
functional "rather than", an "instead of", or one pseudo-cleft therefore never trips it.

Verdicts (both Minor; either can fire independently):
  ANTITHESIS_DENSITY  antithesis markers (rather-than / not-X-but-Y / X-not-Y) per 1,000
                      words exceed the threshold, with the raw count above a floor.
  CLEFT_DENSITY       sentence-initial cleft / pseudo-cleft constructions per 1,000 words
                      exceed the threshold, with the raw count above a floor.

Scope, deliberately conservative on a widely-used skill:
  * Front matter, headings, tables, block quotes, code fences, list items, citation
    markers and inline markup are stripped before measuring (shared _frontmatter helper).
  * "instead of" is NOT counted — it is the functional, non-decorative sibling of "rather
    than" and its presence is not a tell.
  * "not only X but also Y" is excluded from the not-X-but-Y marker (that correlative is
    humanize Pattern 9, a separate check), and conjunctive-adverb / partial-negation forms
    ("however, not all …", "not yet") are excluded from the X-not-Y marker.
  * Silent below --min-words (default 200): a short note has too few words for a rate to
    mean anything.

The rewrite heuristic to apply once flagged (M2, adapted from the SNL-UCSB paper-writing
skill's gate_mechanical.md, MIT): delete the negative half and rewrite the clause in the
positive. If a fact disappears the contrast was functional — keep it; if nothing
disappears it was decoration — cut it. Judge by the manuscript's overall rate, not
instance by instance; keep two or three for emphasis rather than flattening every one.

Exit codes: 0 clean/report-only, 1 with --strict when any Major (none — Minor only),
2 usage. Stdlib-only.

Usage:
    python3 check_rhetorical_density.py --manuscript manuscript.md \
        [--out qc/rhetorical_density.json] [--antithesis-per-1000 6.0] \
        [--cleft-per-1000 2.5] [--min-words 200] [--strict] [--quiet]
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

from _prose import body_text

DETECTOR = "check_rhetorical_density"

WORD_RE = re.compile(r"[A-Za-z0-9']+")
SENT_SPLIT_RE = re.compile(r"(?<=[.!?])\s+(?=[\"“(]?[A-Z0-9])")

# --- antithesis markers ------------------------------------------------------------------
RATHER_THAN_RE = re.compile(r"\brather than\b", re.I)
# "not X but Y" (X up to three words); "not only … but" is Pattern 9, excluded.
NOT_BUT_RE = re.compile(r"\bnot\s+(?!only\b)[\w'-]+(?:\s+[\w'-]+){0,2}\s+but\b", re.I)
# "X, not Y" contrastive apposition, Y a bare 1-3 word phrase closing the clause.
X_NOT_Y_RE = re.compile(
    r"([\w'-]+),\s+not\s+([\w'-]+)(?:\s+[\w'-]+){0,2}\s*[.;:,]", re.I
)
# Pre-comma words that make "X, not …" a sentence adverb + negation, not an antithesis.
_CONJ_ADVERBS = {
    "however", "therefore", "moreover", "furthermore", "thus", "hence", "nonetheless",
    "nevertheless", "indeed", "finally", "first", "second", "third", "meanwhile",
    "otherwise", "consequently", "accordingly", "similarly", "conversely", "also", "again",
}
# Y-heads that make "not Y" a partial/quantifier negation, not a contrastive noun.
_PARTIAL_NEG = {
    "all", "every", "always", "necessarily", "yet", "just", "merely", "simply", "only",
    "quite", "entirely", "wholly", "fully",
}

# --- cleft markers (applied per sentence) ------------------------------------------------
# pseudo-cleft: "What <>=1 word> is/are/was/were …" (a statement, not a "What is X?" question)
PSEUDO_CLEFT_RE = re.compile(r"^What\s+[\w'-]+(?:\s+[\w'-]+)*?\s+(?:is|are|was|were)\b", re.I)
# it-cleft: "It is/was <focus> that/which/who …"
IT_CLEFT_RE = re.compile(
    r"^It\s+(?:is|was|has\s+been)\s+[\w'-].*?\b(?:that|which|who)\b", re.I
)



def sentences(txt: str) -> list:
    return [s.strip() for s in SENT_SPLIT_RE.split(txt) if s.strip()]


def _x_not_y_hits(txt: str) -> list:
    hits = []
    for m in X_NOT_Y_RE.finditer(txt):
        if m.group(1).lower() in _CONJ_ADVERBS:
            continue
        if m.group(2).lower() in _PARTIAL_NEG:
            continue
        hits.append(m.group(0).strip())
    return hits


def analyse(md: str) -> dict:
    body = body_text(md)
    n_words = len(WORD_RE.findall(body))

    anti = (
        [m.group(0) for m in RATHER_THAN_RE.finditer(body)]
        + [m.group(0).strip() for m in NOT_BUT_RE.finditer(body)]
        + _x_not_y_hits(body)
    )
    cleft = []
    for s in sentences(body):
        if s.endswith("?"):
            continue
        if PSEUDO_CLEFT_RE.match(s) or IT_CLEFT_RE.match(s):
            cleft.append(s[:70])

    def rate(n: int) -> float:
        return round(n * 1000.0 / n_words, 2) if n_words else 0.0

    return {
        "words": n_words,
        "antithesis": anti,
        "cleft": cleft,
        "antithesis_per_1000": rate(len(anti)),
        "cleft_per_1000": rate(len(cleft)),
    }


ANTITHESIS_MIN_COUNT = 5
CLEFT_MIN_COUNT = 3


def check(md: str, antithesis_per_1000: float, cleft_per_1000: float, min_words: int) -> dict:
    r = analyse(md)
    findings = []
    if r["words"] >= min_words:
        na, nc = len(r["antithesis"]), len(r["cleft"])
        if na >= ANTITHESIS_MIN_COUNT and r["antithesis_per_1000"] > antithesis_per_1000:
            findings.append({
                "verdict": "ANTITHESIS_DENSITY",
                "severity": "Minor",
                "detail": (
                    f"{na} antithesis constructions in {r['words']} body words "
                    f"({r['antithesis_per_1000']}/1000 > {antithesis_per_1000:.1f} threshold) — "
                    "a run of 'rather than' / 'not X but Y' / 'X, not Y' epigrams; each is "
                    "grammatical but the density is an LLM tell. Delete the negative half and "
                    "rewrite in the positive; if a fact disappears the contrast was functional "
                    "(keep it), if nothing disappears it was decoration (cut it). Keep two or three."
                ),
                "where": "; ".join(m[:40] for m in r["antithesis"][:8]),
            })
        if nc >= CLEFT_MIN_COUNT and r["cleft_per_1000"] > cleft_per_1000:
            findings.append({
                "verdict": "CLEFT_DENSITY",
                "severity": "Minor",
                "detail": (
                    f"{nc} cleft / pseudo-cleft constructions in {r['words']} body words "
                    f"({r['cleft_per_1000']}/1000 > {cleft_per_1000:.1f} threshold) — "
                    "sentence-initial 'What … is …' / 'It is … that …' fronting used for "
                    "weight. Rewrite in plain subject-verb order ('What matters is X' -> 'X "
                    "matters'); keep at most one for genuine emphasis."
                ),
                "where": "; ".join(s[:48] for s in r["cleft"][:8]),
            })
    return {"metrics": {k: r[k] for k in
            ("words", "antithesis_per_1000", "cleft_per_1000")}, "findings": findings,
            "detail": r}


def main() -> int:
    ap = argparse.ArgumentParser(
        description="Rhetorical-construction density gate — antithesis + cleft (§J / P27).")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--antithesis-per-1000", type=float, default=6.0,
                    help="antithesis markers per 1000 words that trips the flag (default 6.0)")
    ap.add_argument("--cleft-per-1000", type=float, default=2.5,
                    help="cleft constructions per 1000 words that trips the flag (default 2.5)")
    ap.add_argument("--min-words", type=int, default=200,
                    help="stay silent below this many body words (default 200)")
    ap.add_argument("--strict", action="store_true",
                    help="exit 1 if any Major (none — this gate is Minor-only)")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    a = ap.parse_args()

    src = Path(a.manuscript)
    if not src.is_file():
        sys.stderr.write(f"error: no such file: {src}\n")
        return 2

    result = check(src.read_text(encoding="utf-8", errors="ignore"),
                   a.antithesis_per_1000, a.cleft_per_1000, a.min_words)
    findings = result["findings"]

    if not a.quiet:
        print("=" * 42)
        print(" Rhetorical-construction density (§J / P27)")
        print("=" * 42)
        print("| Verdict | Severity | Detail |")
        print("|---|---|---|")
        if findings:
            for f in findings:
                print(f"| {f['verdict']} | {f['severity']} | {f['detail']} |")
            for f in findings:
                print(f"\n{f['verdict']} — {f['where']}")
        else:
            print("| (none) | — | antithesis / cleft density within the published range |")
            m = result["metrics"]
            print(f"\nOK: antithesis {m['antithesis_per_1000']}/1000, "
                  f"cleft {m['cleft_per_1000']}/1000 — within range.")

    if a.out:
        out = Path(a.out)
        out.parent.mkdir(parents=True, exist_ok=True)
        out.write_text(json.dumps({
            "detector": DETECTOR,
            "manuscript": str(src),
            "metrics": result["metrics"],
            "findings": findings,
        }, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
        if not a.quiet:
            print(f"\nwrote {out}")

    return 1 if (a.strict and any(f["severity"] == "Major" for f in findings)) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Rounded-component vs stated-difference arithmetic gate (self-review Phase 2.5a).

When a manuscript displays two metric values at a given precision and also states
their difference, the stated difference must equal the subtraction of the DISPLAYED
components at that same precision. A paper that reports "AUC 0.70 vs 0.73" (a shown
gap of 0.03) while stating the between-arm difference as "0.02" is self-consistent
only at full unrounded precision — at the displayed two decimals it reads as a
contradiction, and a reviewer flags it. (The usual cause: the delta is computed on
unrounded values, e.g. 0.726 − 0.703 = 0.023 → 0.02, while the components are shown
rounded to 0.70 / 0.73.)

Verdict:
  ROUNDED_DELTA_MISMATCH (Minor)  a stated difference does not equal the subtraction
                                  of its two displayed component values AT THE SAME
                                  precision. Fix: either report both components and
                                  the delta at a consistent precision, or add a
                                  footnote that the delta is computed on unrounded
                                  values.

Conservative by construction: fires only when (a) two component values joined by a
comparator (vs / versus / and / to / , ) appear in the same sentence as (b) an
explicitly LABELLED difference (Δ / difference / delta), and (c) all three are at the
SAME decimal precision. A higher-precision component pair (0.703 vs 0.726) with a
2-dp delta is the legitimate unrounded-delta case and is NOT flagged.

Exit codes: 0 clean/report-only, 1 with --strict when any Major (none here — Minor
only, so --strict never fails on this gate alone), 2 usage. Stdlib-only.

Usage:
    python3 check_rounded_delta.py --manuscript manuscript.md \
        [--out qc/rounded_delta.json] [--strict] [--quiet]
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from decimal import Decimal
from pathlib import Path

# Two component values joined by a comparator (the "0.70 vs 0.73" construction).
COMP_PAIR = re.compile(
    r"(?P<a>\d?\.\d+|\d+\.\d+)\s*(?:vs\.?|versus|and|to|,|–|—|-)\s*(?P<b>\d?\.\d+|\d+\.\d+)",
    re.I)
# An explicitly labelled difference value.
DELTA = re.compile(
    r"(?:Δ\s*(?:AUC|AUROC|C[-\s]?index|accuracy)?|"
    r"(?:absolute\s+|between[-\s]\w+\s+|net\s+)?difference|delta|"
    r"differ(?:ed|s)?\s+by)"
    r"\s*(?:of|was|were|is|=|:|,|by)?\s*(?:only\s+|about\s+|approximately\s+)?"
    r"\(?(?P<d>\d?\.\d+|\d+\.\d+)",
    re.I)


def _prec(tok: str) -> int:
    return len(tok.split(".", 1)[1]) if "." in tok else 0


# How far back from a labelled difference to look for its two component values.
# Wide enough to bridge a "0.70 and 0.73; the difference was 0.02" clause boundary,
# narrow enough not to grab an unrelated pair from a previous sentence.
_LOOKBACK = 170


def check(text: str) -> list[dict]:
    claims: list[dict] = []
    seen: set[str] = set()
    for dm in DELTA.finditer(text):
        d_tok = dm.group("d")
        p = _prec(d_tok)
        if p == 0:
            continue
        window = text[max(0, dm.start() - _LOOKBACK):dm.start()]
        # bind the component pair to the delta's OWN sentence: drop anything up to the
        # last sentence terminator so a pair from a previous clause is not matched.
        cut = max(window.rfind(". "), window.rfind(".\n"), window.rfind("\n\n"))
        if cut != -1:
            window = window[cut + 1:]
        for cm in COMP_PAIR.finditer(window):
            a_tok, b_tok = cm.group("a"), cm.group("b")
            # the delta value itself is not a component of the pair
            if d_tok in (a_tok, b_tok):
                continue
            # all three must share the displayed precision (else it is the
            # legitimate unrounded-delta case, not a display contradiction)
            if _prec(a_tok) != p or _prec(b_tok) != p:
                continue
            a, b, d = Decimal(a_tok), Decimal(b_tok), Decimal(d_tok)
            shown = abs(a - b)
            q = Decimal(1).scaleb(-p)  # 10**-p
            if shown.quantize(q) == d.quantize(q):
                continue
            key = f"{a_tok}|{b_tok}|{d_tok}"
            if key in seen:
                continue
            seen.add(key)
            claims.append({
                "verdict": "ROUNDED_DELTA_MISMATCH",
                "severity": "Minor",
                "detail": (f"displayed components {a_tok} and {b_tok} differ by "
                           f"{shown.quantize(q)} at the shown precision, but the stated "
                           f"difference is {d_tok}; report components and delta at one "
                           f"precision or footnote that the delta is on unrounded values"),
                "where": text[max(0, dm.start() - _LOOKBACK):dm.end() + 4].replace("\n", " ").strip()[:170],
            })
    return claims


def analyze(manuscript: str) -> dict:
    p = Path(manuscript)
    if not p.is_file():
        sys.stderr.write(f"ERROR: manuscript not found: {manuscript}\n")
        sys.exit(2)
    claims = check(p.read_text(encoding="utf-8"))
    return {
        "manuscript": str(p),
        "claims": claims,
        "summary": {
            "n_claims": len(claims),
            "n_major": 0,
            "n_flag": len(claims),
            "verdict": "REVIEW" if claims else "OK",
        },
    }


def render(result: dict) -> str:
    lines = ["| Check | Severity | Detail |", "|---|---|---|"]
    for c in result["claims"]:
        lines.append(f"| {c['verdict']} | {c['severity']} | {c['detail']} |")
    if len(lines) == 2:
        lines.append("| (none) | — | stated differences match displayed components |")
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(
        description="Rounded-component vs stated-difference arithmetic gate (Phase 2.5a).")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true",
                    help="exit 1 if any Major (none — this gate is Minor-only)")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    args = ap.parse_args()

    result = analyze(args.manuscript)

    if not args.quiet:
        print("=" * 44)
        print(" Rounded-component vs stated difference (§2.5a)")
        print("=" * 44)
        print(render(result))
        print()
        n = result["summary"]["n_flag"]
        print(f"{'REVIEW: ' + str(n) + ' rounded-delta mismatch(es).' if n else 'OK: stated differences match displayed components.'}")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_rounded_delta", **result}, indent=2), encoding="utf-8")
        if not args.quiet:
            print(f"\nwrote {args.out}")

    return 1 if (args.strict and result["summary"]["n_major"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Endpoint↔conclusion scope-coherence gate (self-review §D).

Two overclaim patterns where the conclusion's action exceeds what the design or
endpoint can support. Both are deterministic when a design/endpoint signal and a
conclusion action verb co-occur, and both are documented anti-patterns
(scope-coherence-gate.md):

  CROSS_SECTIONAL_PROGNOSTIC  the design is cross-sectional / single-visit /
                              prevalence, yet the conclusion makes a prognostic or
                              surveillance claim (rescreen interval, surveillance,
                              disease progression, predicting future risk). A single
                              time point cannot license a longitudinal conclusion.
  SURROGATE_CARE_DIRECTIVE    a binary surrogate endpoint (present/absent, >0,
                              dichotomized) drives a patient-care directive (defer,
                              withhold, initiate/discontinue therapy, statin). A
                              risk-stratification marker is not a management trigger.
  UNIVERSAL_NEGATIVE_UNSCOPED  a 'nobody / first to / has not been' novelty claim
                          in a claim region with no named discipline-scope qualifier
                          (Minor): a single-database search cannot support a universal
                          negative. Narrow the claim or widen the search.
  CROSS_SECTIONAL_YIELD_LANGUAGE  a cross-sectional / prevalence design uses
                              incidence/prospective-flavored vocabulary — "yield",
                              "detection rate", "number-needed-to-screen/image",
                              "rescreen interval", "screen-detected". On a
                              prevalence design these read as longitudinal screening
                              performance. Minor unless "yield" is defined once as
                              cross-sectional report-positive prevalence.
  GRADIENT_WITHOUT_INTERACTION  a cross-strata directional claim ("shortest in the
                              high-risk tertile", "monotonically across the age strata")
                              stated as a finding, with a stratification context nearby,
                              but NO interaction test (interaction term / LRT / p-
                              interaction / effect modification) reported anywhere. A
                              difference in significance across strata is not a tested
                              interaction. Minor. Precision-guarded: a physical "pressure
                              gradient" or "gradient echo" and an interaction-tested claim
                              do not fire.

The gate is conservative: it fires only when both a signal and a conclusion-region
verb are present, to keep false positives low on a widely-used skill.

INPUTS
  --manuscript  manuscript markdown/text (required).

OUTPUT
  A reconciliation table (stdout) and, with --out, a JSON artifact:
    {manuscript, claims[{verdict, severity, detail, where}], summary}
  CROSS_SECTIONAL_PROGNOSTIC and SURROGATE_CARE_DIRECTIVE are Major; UNIVERSAL_NEGATIVE_
  UNSCOPED, CROSS_SECTIONAL_YIELD_LANGUAGE and GRADIENT_WITHOUT_INTERACTION are Minor.
  Exit 1 (with --strict) on any Major.

Stdlib-only (json / re / argparse / pathlib). Exit codes: 0 clean (or report-only),
1 Major claim(s) found (with --strict), 2 input/usage error.
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

DESIGN_CROSS_SECTIONAL = re.compile(
    r"cross[-\s]?sectional|single[-\s](?:time[-\s]?point|visit|examination|measurement)|"
    r"at (?:a |one )?(?:single |one )?time[-\s]?point|point[-\s]prevalence|"
    r"prevalence (?:study|survey|design)", re.IGNORECASE)

PROGNOSTIC_VERB = re.compile(
    r"surveillance|re[-\s]?screen|screening interval|rescreening|"
    r"monitor(?:ed|ing)?\s+over\s+time|disease progression|progress(?:es|ion)\s+to|"
    r"prognost|predict(?:s|ing|ed)?\s+(?:incident|future|long[-\s]?term|the risk of developing)|"
    r"longitudinal (?:follow|risk|trajector)", re.IGNORECASE)

# A prognostic/surveillance token sitting inside a negation/deferral frame is a
# correct hedge, not an overclaim ("describes concurrent burden RATHER THAN
# surveillance intervals, which WOULD REQUIRE PROSPECTIVE data"). You cannot
# disavow surveillance without naming it; do not fire CROSS_SECTIONAL_PROGNOSTIC
# when the match is disclaimed in its immediate vicinity.
PROGNOSTIC_DISCLAIMER = re.compile(
    r"rather than|instead of|not\s+(?:a\s+|the\s+)?(?:surveillance|prognostic|longitudinal)|"
    r"does not (?:establish|imply|support|provide|address|determine|permit)|"
    r"cannot (?:establish|determine|inform|assess|address)|"
    r"would require|requires?\s+prospective|warrants?\s+prospective|"
    r"defer(?:s|red|ring)?\b[^.]{0,40}\bprospective|"
    r"beyond the scope|no (?:prognostic|surveillance|longitudinal) (?:claim|inference|conclusion)",
    re.IGNORECASE)

# A methods / QC / detector paper — or a review — whose SUBJECT is this very
# anti-pattern NAMES the pattern rather than committing it ("this paper detects
# manuscripts that make a prognostic claim in a cross-sectional setting"). When the
# match sits inside such a meta-framing, it is a description, not an overclaim; do
# not fire. Kept tight (requires the meta-framing structure, not a bare "detect")
# so a real prognostic overclaim is never suppressed.
META_DOC_FRAME = re.compile(
    r"anti[-\s]?pattern|such (?:patterns|claims|conclusions|overclaims)\b|"
    r"(?:papers?|manuscripts?|studies|authors) (?:that|which|who) "
    r"(?:commit|make|assert|report|conflate|claim|treat|use)\b|"
    r"we (?:report|show|find|note|observe) that (?:papers|manuscripts|studies|authors|some|many)|"
    r"(?:this|the present) (?:paper|study|work|review|tool|detector|gate|framework|probe)\b"
    r"[^.]{0,40}?(?:discuss|describ|detect|flag|identif|examin|review|illustrat|catalog)|"
    r"(?:as|is) an? (?:example|illustration|instance|case) of",
    re.IGNORECASE)

# A sentence that LABELS a prognostic/surveillance claim as a defect — "an
# unsupported prognostic claim in a cross-sectional study", "prognostic
# overreach", "an unwarranted surveillance recommendation" — is naming the
# anti-pattern, not committing it. This catches the enumerated-defect framing
# (a defect listed as an appositive in a list of things a tool flags) that
# META_DOC_FRAME misses because the framing verb ("flags"/"detects") sits far
# from the match. Stays high-precision: a manuscript making a real prognostic
# claim never precedes it with "unsupported"/"unwarranted", nor calls it an
# "overreach"/"overclaim" — so no genuine overclaim is suppressed.
ANTIPATTERN_LABEL = re.compile(
    r"(?:unsupported|unwarranted|unjustified|inappropriate|spurious|invalid|"
    r"overreaching|erroneous|illegitimate)\s+(?:\w+\s+){0,2}?"
    r"(?:prognostic|surveillance|longitudinal)|"
    r"(?:prognostic|surveillance|longitudinal)\s+(?:overclaim|overreach|fallacy|error)",
    re.IGNORECASE)

DIRECTIVE_VERB = re.compile(
    r"\bdefer(?:ral|red|ring)?\b|\bwithhold\b|\bforgo\b|\binitiat(?:e|ed|ion)\b|"
    r"\bdiscontinu(?:e|ed|ation)\b|start(?:ing)?\s+(?:statin|therapy|treatment|pharmacotherapy)|"
    r"(?:statin|treatment|therapy|pharmacotherapy)\s+(?:can|should|may)\s+be\s+(?:deferred|withheld|started|initiated)|"
    r"recommend(?:ed)?\s+(?:statin|treatment|therapy|initiation|against treatment)|"
    r"guide\s+(?:treatment|management|therapy)", re.IGNORECASE)

YIELD_LANGUAGE = re.compile(
    r"\byield\b|detection rate|number[-\s]needed[-\s]to[-\s](?:screen|image)|"
    r"\bnn[si]\b|rescreen(?:ing)?\s+interval|screen[-\s]detected", re.IGNORECASE)

# "yield" pinned once to a cross-sectional prevalence reading suppresses the flag.
YIELD_DEFINED = re.compile(
    r"yield (?:is|was|here|,)?\s*(?:defined|refers|denotes|i\.e\.)|"
    r"defined as the (?:cross[-\s]sectional )?(?:report[-\s]positive )?prevalence|"
    r"cross[-\s]sectional (?:report[-\s]positive )?prevalence", re.IGNORECASE)

SURROGATE_SIGNAL = re.compile(
    r"binary (?:surrogate|endpoint|outcome|marker)|dichotom(?:ous|ised|ized)|surrogate (?:endpoint|marker|outcome)|"
    r"presence (?:or absence )?of|present (?:vs\.?|versus|or) absent|positive (?:vs\.?|versus|or) negative|"
    r"categor(?:ised|ized) as (?:positive|present|absent)|>\s?0\b", re.IGNORECASE)

CONCLUSION_HEADINGS = re.compile(
    r"^#{1,4}\s*\*{0,2}(?:CONCLUSIONS?|Conclusions?|DISCUSSION|Discussion|"
    r"Clinical Implications?|Interpretation)\*{0,2}\s*$", re.IGNORECASE | re.MULTILINE)


def conclusion_region(text: str) -> str:
    """Text under Conclusion/Discussion/Implications headings, plus any inline
    'Conclusion:' clause (abstract). Fallback: the last 25% of the document."""
    spans = []
    starts = [m.end() for m in CONCLUSION_HEADINGS.finditer(text)]
    # heading-delimited regions: from each heading to the next top-level heading
    all_headings = [m.start() for m in re.finditer(r"^#{1,4}\s", text, re.MULTILINE)]
    for s in starts:
        nxt = next((h for h in all_headings if h > s), len(text))
        spans.append(text[s:nxt])
    for m in re.finditer(r"(?:^|\n)\s*\*{0,2}Conclusions?\*{0,2}\s*[:.]\s*(.+?)(?:\n\n|$)",
                         text, re.IGNORECASE | re.DOTALL):
        spans.append(m.group(1))
    if not spans:
        spans.append(text[int(len(text) * 0.75):])
    return "\n".join(spans)


# Claim regions where a novelty/neglect claim lives: Abstract, Introduction/
# Background, Discussion, Conclusion.
NOVELTY_REGION_HEADINGS = re.compile(
    r"^#{1,4}\s*\*{0,2}(?:ABSTRACT|Abstract|INTRODUCTION|Introduction|BACKGROUND|Background|"
    r"DISCUSSION|Discussion|CONCLUSIONS?|Conclusions?)\*{0,2}\s*:?\s*$",
    re.IGNORECASE | re.MULTILINE)

# A universal-negative / first-to novelty construction.
UNIVERSAL_NEGATIVE_RE = re.compile(
    r"\bno(?:body|-one| one)\b"
    r"|\bnone of (?:the |these )?(?:\w+\s+){0,2}(?:studies|systems|works|methods|papers|reports)\b"
    r"|\bno (?:\w+\s+){0,3}(?:published |existing |prior )?"
    r"(?:system|study|work|method|approach|dataset|benchmark|paper|report|research)\b"
    r"[^.\n]{0,50}?\b(?:measure|report|quantif|examine|assess|address|exist|investigate|describe|ask)"
    r"|\bnever been (?:measured|examined|studied|reported|asked|quantified|assessed|investigated|addressed|explored)\b"
    r"|\bhas not (?:yet )?been (?:measured|examined|studied|asked|quantified|assessed|investigated|addressed|explored)\b"
    r"|\bfirst (?:study|work|report|paper)\b[^.\n]{0,50}?\b(?:to )?(?:measure|report|examine|quantif|assess|investigate|describe|characteri[sz]e)"
    r"|\bwe are the first\b|\bthe first to (?:measure|report|examine|quantif|assess|investigate|describe|characteri[sz]e)"
    r"|\bremains? (?:largely )?(?:unmeasured|unexamined|unexplored|unaddressed)\b|\bunexamined\b|\bunexplored\b",
    re.IGNORECASE)

# A named discipline/literature FRAME that legitimately scopes the negative. A bare
# epistemic hedge ("to our knowledge") is NOT a frame and does not suppress.
SCOPE_QUALIFIER_RE = re.compile(
    r"\bclinical(?:ly)? (?:published|literature)\b"
    r"|\bin (?:the )?(?:clinical|medical|radiolog\w+|surgical|nursing|imaging|oncolog\w+) (?:literature|domain|setting|field)\b"
    r"|\bin radiology\b|\bin medicine\b|\bpeer-reviewed clinical\b"
    r"|\b(?:within|among|across) (?:the )?(?:published )?\w+ (?:literature|studies)\b"
    r"|\bto date in the \w+ literature\b",
    re.IGNORECASE)


# A cross-strata DIRECTIONAL claim: the estimate trends / differs across the levels of a
# subgroup. Anchored to distinctive phrases so a physical "pressure gradient across the
# stenosis" or an MRI "gradient echo" does not match (bare "gradient" is never enough).
GRADIENT_CLAIM_RE = re.compile(
    r"more pronounced (?:in|among|for)\b"
    r"|(?:short|long|high|low|great|small|strong|weak)(?:est|er) (?:in|among|for)\b"
    r"|monotonic(?:ally)?\b"
    r"|step[-\s]?wise (?:increase|decrease|rise|decline|shorten|across|with)"
    r"|gradient (?:across|among|by|over|with (?:higher|increasing|worsening))"
    r"|dose[-\s]?response (?:relationship|gradient|pattern)?\s*(?:across|with|by)"
    r"|(?:increas|decreas|shorten|worsen)(?:ed|ing) (?:monotonically|step[-\s]?wise|progressively)",
    re.IGNORECASE)

# A stratification CONTEXT (the LEVELS of a subgroup) — required in the same window so
# the directional language is about subgroup strata, not a physical or temporal trend.
STRATA_CONTEXT_RE = re.compile(
    r"tertile|quartile|quintile|decile|stratum|strata|stratified|subgroup"
    r"|categor(?:y|ies)|\bband\b|joint(?:ly)?[-\s]?(?:strat|classif)|cross[-\s]?classif"
    r"|(?:age|risk|score|bmi|dose)[-\s]?(?:group|categor|band|tier)",
    re.IGNORECASE)

# Evidence an interaction WAS actually tested (any hit anywhere -> suppress the flag).
INTERACTION_TEST_RE = re.compile(
    r"interaction (?:term|test|p[-\s]?value|effect|coefficient)"
    r"|p[-_\s]?interaction|p[-_\s]?int\b|effect modification"
    r"|test(?:ed|ing)? for interaction|multiplicative interaction|product term"
    r"|likelihood[-\s]?ratio test|\bLRT\b|(?:OR|HR|RR|beta|β)[-_]?int\b",
    re.IGNORECASE)

# Claim regions where a cross-strata directional statement is a substantive claim
# (not the Methods description of a stratified analysis).
CLAIM_REGION_HEADINGS = re.compile(
    r"^#{1,4}\s*\*{0,2}\s*(?:abstract|results?|discussion|interpretation|conclusions?"
    r"|key results?|principal findings?)\b",
    re.IGNORECASE | re.MULTILINE)


def _region(text: str, heading_re) -> str:
    spans = []
    all_headings = [m.start() for m in re.finditer(r"^#{1,4}\s", text, re.MULTILINE)]
    for m in heading_re.finditer(text):
        s = m.end()
        nxt = next((h for h in all_headings if h > s), len(text))
        spans.append(text[s:nxt])
    mt = re.search(r"^#{1,6}\s+(.+)$", text, re.MULTILINE)  # title
    if mt:
        spans.append(mt.group(1))
    return "\n".join(spans) if spans else text


def check(text: str) -> list[dict]:
    claims = []
    concl = conclusion_region(text)

    # UNIVERSAL_NEGATIVE_UNSCOPED — a "nobody / first to / has not been" claim in a
    # claim region with no named discipline-scope qualifier nearby. Minor: the fix is
    # usually a one-word scope narrowing (or a wider, cross-discipline search).
    region = _region(text, NOVELTY_REGION_HEADINGS)
    seen: set[str] = set()
    for m in UNIVERSAL_NEGATIVE_RE.finditer(region):
        window = region[max(0, m.start() - 200):m.end() + 200]
        if SCOPE_QUALIFIER_RE.search(window):
            continue
        key = re.sub(r"\s+", " ", m.group(0).lower())[:60]
        if key in seen:
            continue
        seen.add(key)
        claims.append({
            "verdict": "UNIVERSAL_NEGATIVE_UNSCOPED",
            "severity": "Minor",
            "detail": (f"a universal-negative / first-to claim ('{m.group(0).strip()}') with no named "
                       f"discipline-scope qualifier; a single-database search supports 'no *clinical* "
                       f"paper does X', never 'nobody does X' — narrow the claim ('...in the clinical "
                       f"literature') or widen the search to the venues where the subject lives"),
            "where": region[max(0, m.start() - 30):m.end() + 40].replace("\n", " ").strip()[:160],
        })

    if DESIGN_CROSS_SECTIONAL.search(text):
        # Fire only on a prognostic/surveillance token that is NOT inside a
        # negation/deferral frame; iterate all matches so a real claim later in the
        # conclusion still fires even if an earlier mention was a disclaimer.
        for pm in PROGNOSTIC_VERB.finditer(concl):
            window = concl[max(0, pm.start() - 120):pm.end() + 120]
            if (PROGNOSTIC_DISCLAIMER.search(window) or META_DOC_FRAME.search(window)
                    or ANTIPATTERN_LABEL.search(window)):
                continue
            claims.append({
                "verdict": "CROSS_SECTIONAL_PROGNOSTIC",
                "severity": "Major",
                "detail": (f"cross-sectional/single-visit design, but the conclusion makes a "
                           f"prognostic/surveillance claim ('{pm.group(0).strip()}')"),
                "where": concl[max(0, pm.start() - 40):pm.end() + 40].strip()[:160],
            })
            break

    dm = DIRECTIVE_VERB.search(concl)
    sm = SURROGATE_SIGNAL.search(concl)
    if dm and sm:
        claims.append({
            "verdict": "SURROGATE_CARE_DIRECTIVE",
            "severity": "Major",
            "detail": (f"a binary surrogate endpoint ('{sm.group(0).strip()}') drives a "
                       f"patient-care directive ('{dm.group(0).strip()}') in the conclusion"),
            "where": concl[max(0, dm.start() - 40):dm.end() + 40].strip()[:160],
        })

    if DESIGN_CROSS_SECTIONAL.search(text):
        ym = YIELD_LANGUAGE.search(text)
        if ym and not YIELD_DEFINED.search(text):
            claims.append({
                "verdict": "CROSS_SECTIONAL_YIELD_LANGUAGE",
                "severity": "Minor",
                "detail": (f"cross-sectional/prevalence design uses incidence-flavored "
                           f"screening vocabulary ('{ym.group(0).strip()}') without defining "
                           f"'yield' as cross-sectional report-positive prevalence; on a "
                           f"single-timepoint design this reads as longitudinal screening "
                           f"performance"),
                "where": text[max(0, ym.start() - 40):ym.end() + 40].strip()[:160],
            })

    # GRADIENT_WITHOUT_INTERACTION — a cross-strata directional claim ("shortest in the
    # high-risk tertile", "monotonically across the age strata") stated as a finding, with
    # a stratification context nearby, but NO interaction test reported anywhere. A
    # difference in significance across strata is not a tested interaction; the
    # joint-stratification framing escapes the synergy/interaction token trigger.
    if not INTERACTION_TEST_RE.search(text):
        claim_region = _region(text, CLAIM_REGION_HEADINGS)
        for gm in GRADIENT_CLAIM_RE.finditer(claim_region):
            window = claim_region[max(0, gm.start() - 160):gm.end() + 160]
            if not STRATA_CONTEXT_RE.search(window):
                continue
            claims.append({
                "verdict": "GRADIENT_WITHOUT_INTERACTION",
                "severity": "Minor",
                "detail": (f"a cross-strata directional claim ('{gm.group(0).strip()}') is made across "
                           f"subgroup levels, but no interaction test (interaction term / LRT / "
                           f"p-interaction / effect modification) is reported anywhere; a difference in "
                           f"significance across strata is not a tested interaction — report the "
                           f"interaction test, or reframe as descriptive stratified estimates"),
                "where": window.replace("\n", " ").strip()[:160],
            })
            break

    return claims


def analyze(manuscript: str) -> dict:
    p = Path(manuscript)
    if not p.is_file():
        sys.stderr.write(f"ERROR: manuscript not found: {manuscript}\n")
        sys.exit(2)
    claims = check(p.read_text(encoding="utf-8"))
    n_major = sum(1 for c in claims if c["severity"] == "Major")
    return {
        "manuscript": str(p),
        "claims": claims,
        "summary": {
            "n_claims": len(claims),
            "n_major": n_major,
            "n_flag": len(claims) - n_major,
            "verdict": "MAJOR_CANDIDATE" if n_major else "OK",
        },
    }


def render(result: dict) -> str:
    lines = ["| Check | Severity | Detail |", "|---|---|---|"]
    for c in result["claims"]:
        lines.append(f"| {c['verdict']} | {c['severity']} | {c['detail']} |")
    if len(lines) == 2:
        lines.append("| (none) | — | conclusion scope matches the design/endpoint |")
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(description="Endpoint↔conclusion scope-coherence gate (§D).")
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true", help="exit 1 if any Major claim exists")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    args = ap.parse_args()

    result = analyze(args.manuscript)

    if not args.quiet:
        print("=" * 41)
        print(" Scope Coherence (§D)")
        print("=" * 41)
        print(render(result))
        print()
        s = result["summary"]
        if s["n_major"]:
            print(f"MAJOR candidate: {s['n_major']} endpoint↔conclusion scope mismatch(es).")
        elif s["n_flag"]:
            print(f"MINOR flag: {s['n_flag']} scope-language issue(s) (see table).")
        else:
            print("OK: conclusion scope matches the design/endpoint.")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_scope_coherence", **result}, indent=2), encoding="utf-8")
        if not args.quiet:
            print(f"\nwrote {args.out}")

    return 1 if (args.strict and result["summary"]["n_major"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Reader-facing supplement / tables / caption hygiene gate (self-review §J supplement pass).

Existing classical-style and scope gates lint `manuscript.md` ONLY; the rendered
supplement, a separately-built tables file, and figure-caption files are never
linted — yet those are the artifacts where technical-check-fatal residue hides
(internal SAP labels, unfilled placeholders, build markers, response-letter
framing, and body↔supplement cross-reference numbers that do not resolve). This
detector lints a LIST of rendered submission artifacts for that residue and, when
given the manuscript body, checks that every "Supplementary X N" callout resolves
to a supplement section.

Verdicts (all Major — each reaches a reviewer/editor as a non-anonymous slip):
  SUPP_INTERNAL_LABEL    a § / §L internal section or SAP label (§L0, §L10b, "see
                         Methods §3") in a reader-facing file — internal scaffolding.
  SUPP_PLACEHOLDER       an unfilled placeholder: "Supplementary Table SX", "Table
                         S?", "Figure S-N", a literal "S-N"/"TABLE N", "[Authors]",
                         a figure-path brace-glob (figS_*.{png,pdf}), or an internal
                         build-dir path (1_Search/, 4_Analysis/, 5_Figures/).
  SUPP_BUILD_MARKER      a build/QA marker that should never ship: "[VERIFY…]",
                         "TODO", "FIXME", "XXXX", "Remove this line if…".
  SUPP_RESPONSE_FRAMING  response-to-reviewers framing in a reader-facing supplement:
                         "Per Section Editor #2", "Per Reviewer 2 #3", "Response to
                         Reviewer", "Reviewer 2 Comment 4".
  SUPP_PLANNING_RESIDUE  pre-execution planning residue: "Designed by:", "Expected
                         PRISMA Numbers", "Deduplication Plan", "to be executed/run".
  SUPP_PARTICIPANT_PII_TIE a reader/participant identity (pseudonym R+hex, or a named
                         participant) tied to an INDIVIDUAL response on one line — a
                         re-identifiable datum in a reader-facing/public supplement. A
                         byline/roster without individual responses does not fire.
  SUPP_XREF_UNRESOLVED   (needs --manuscript) a body "Supplementary Table/Figure/
                         Material N" callout with no matching supplement section.

Exit codes: 0 clean (or report-only), 1 with --strict when any Major exists, 2 usage.
Stdlib-only (json / re / argparse / pathlib).

Usage:
    python3 check_supplement_hygiene.py --supplement supplement.md [--supplement tables.md ...] \
        [--manuscript manuscript.md] [--out qc/supplement_hygiene.json] [--strict] [--quiet]
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

# --- residue patterns (per reader-facing file) -----------------------------

# § anywhere, or a §-less "§L" SAP label, or a "see Methods §3" cross-ref. In a
# reader-facing supplement any of these is internal scaffolding (manuscript-style
# bans § outright); we report per file with a count.
INTERNAL_LABEL = re.compile(r"§")

# Unfilled placeholders. Literal letter N/X (not a digit) after a table/figure
# label, "S?"/"SX"/"S-N" tokens, an author placeholder, a figure-path brace-glob,
# and internal build-dir paths.
PLACEHOLDER = re.compile(
    r"\b(?:Supplementary\s+)?(?:Table|Figure|Fig\.?|Appendix)\s+S?[NX]\b"  # Table SX / Figure N
    r"|\bS-?[NX]\b"                                                         # S-N / SN (letter)
    r"|\bS\?\b"                                                             # S?
    r"|\bTABLE\s+[NX]\b|\bFIGURE\s+[NX]\b"                                  # TABLE N
    r"|\[\s*Authors?\s*\]|\[\s*Author names?\s*\]"                          # [Authors]
    r"|[\w/]*\bfig\w*_\*\.\{[^}]*\}"                                        # figS_*.{png,pdf}
    r"|\*\.\{(?:png|pdf|jpe?g|tiff?|svg)[^}]*\}"                            # *.{png,pdf}
    r"|(?<![\w/])(?:0_|1_|2_|3_|4_|5_|6_)[A-Za-z][\w]*/",                   # 1_Search/ 5_Figures/
    re.IGNORECASE)

BUILD_MARKER = re.compile(
    r"\[\s*VERIFY[^\]]*\]|\bTODO\b|\bFIXME\b|\bXXXX+\b|\bTBD\b"
    r"|Remove this line if|placeholder text|<!--\s*(?:TODO|note|draft)",
    re.IGNORECASE)

RESPONSE_FRAMING = re.compile(
    r"\bPer\s+(?:Section\s+Editor|Reviewer|Editor)\s*#?\s*\d"
    r"|\bResponse\s+to\s+(?:the\s+)?Reviewers?\b"
    r"|\bReviewer\s+\d+\s*(?:Comment|#|,\s*(?:comment|point))"
    r"|\bin\s+response\s+to\s+(?:Reviewer|the\s+Editor|comment)\b",
    re.IGNORECASE)

PLANNING_RESIDUE = re.compile(
    r"\bDesigned\s+by\s*:|\bExpected\s+[\w\s]{0,30}\bNumbers\b"
    r"|\bDeduplication\s+Plan\b|\bSearch\s+Plan\b|\bAnalysis\s+Plan\s*:"
    r"|\bto\s+be\s+(?:executed|run|determined|finalized|completed)\b"
    r"|\bawaiting\s+(?:data|results|execution)\b",
    re.IGNORECASE)

# Participant-privacy tie: a reader/participant IDENTITY on the same line as an
# INDIVIDUAL-RESPONSE datum re-identifies that person's answers in a reader-facing /
# public supplement. Identity = a reader pseudonym token (R + hex) OR a proper "First
# Last" name accompanied by a participant word on the line. Response datum = an
# explicit per-trial answer. A byline / roster line (a name with NO individual
# response) is legitimate and must NOT fire.
READER_PSEUDONYM = re.compile(r"\bR[0-9a-f]{5,}\b")
PROPER_NAME = re.compile(r"\b[A-Z][a-z]+(?:\s+[A-Z]\.?)?\s+[A-Z][a-z]+\b")
PARTICIPANT_WORD = re.compile(r"\b(?:reader|participant|rater|observer|respondent|subject)\b", re.I)
RESPONSE_DATUM = re.compile(
    r"\bresponse\s*[=:]|\bconfidence\s*[=:]|\bcue\s*[=:]|\btrial\s+\d+\b"
    r"|\brated\s+(?:it|this|the\s+\w+)\b|\banswered\s+(?:real|fake|ai|synthetic)\b"
    r"|\bresponse\s+(?:was\s+)?(?:real|fake|ai|synthetic|authentic)\b",
    re.IGNORECASE)


def lint_pii_tie(path: Path) -> list[dict]:
    """Flag a line that ties a reader identity to an individual response (de-anon)."""
    claims: list[dict] = []
    text = path.read_text(encoding="utf-8", errors="replace")
    for i, line in enumerate(text.splitlines(), 1):
        if not RESPONSE_DATUM.search(line):
            continue
        has_pseudonym = READER_PSEUDONYM.search(line)
        has_named = PROPER_NAME.search(line) and PARTICIPANT_WORD.search(line)
        if not (has_pseudonym or has_named):
            continue
        who = "a reader pseudonym" if has_pseudonym else "a named participant"
        claims.append({
            "verdict": "SUPP_PARTICIPANT_PII_TIE",
            "severity": "Major",
            "detail": (f"{who} is tied to an individual response on one line in {path.name} — "
                       f"a re-identifiable participant-level datum in a reader-facing supplement; "
                       f"de-identify (a byline/roster without individual responses is fine)"),
            "where": f"{path.name}:{i}: …{line.strip()[:110]}…",
        })
        break  # one per file
    return claims


PER_FILE_CHECKS = [
    ("SUPP_INTERNAL_LABEL", INTERNAL_LABEL,
     "a § / §L internal section or SAP label leaked into a reader-facing file"),
    ("SUPP_PLACEHOLDER", PLACEHOLDER,
     "an unfilled placeholder (S?/SX/S-N, [Authors], figure-path glob, or build-dir path)"),
    ("SUPP_BUILD_MARKER", BUILD_MARKER,
     "a build/QA marker that should not ship ([VERIFY]/TODO/FIXME/XXXX/'Remove this line if')"),
    ("SUPP_RESPONSE_FRAMING", RESPONSE_FRAMING,
     "response-to-reviewers framing in a reader-facing supplement"),
    ("SUPP_PLANNING_RESIDUE", PLANNING_RESIDUE,
     "pre-execution planning residue (Designed by:/Expected … Numbers/to be executed)"),
]


def _line_of(text: str, pos: int) -> int:
    return text[:pos].count("\n") + 1


def lint_file(path: Path) -> list[dict]:
    claims: list[dict] = []
    text = path.read_text(encoding="utf-8", errors="replace")
    for verdict, rx, detail in PER_FILE_CHECKS:
        m = rx.search(text)
        if not m:
            continue
        n = len(rx.findall(text))
        ln = _line_of(text, m.start())
        snippet = text[max(0, m.start() - 25):m.end() + 35].replace("\n", " ").strip()
        claims.append({
            "verdict": verdict,
            "severity": "Major",
            "detail": f"{detail} — {n} occurrence(s) in {path.name}",
            "where": f"{path.name}:{ln}: …{snippet[:120]}…",
        })
    claims.extend(lint_pii_tie(path))
    return claims


# --- body ↔ supplement cross-reference resolution --------------------------

# A body callout like "Supplementary Table 3", "Supplementary Figure 2",
# "Supplementary Material 5", "Supplementary Methods 1", "Supplementary Appendix 4".
BODY_CALLOUT = re.compile(
    r"Supplementary\s+(Table|Figure|Fig\.?|Material|Methods?|Appendix|Data|Note)\s+(\d{1,3})\b",
    re.IGNORECASE)

# A supplement section identity: a heading that ends in / contains a number, or an
# explicit "Supplementary Table/Material N" / "Table SN" title line.
SUPP_SECTION = re.compile(
    r"^#{1,4}\s.*?\b(?:Supplementary\s+)?(?:Table|Figure|Material|Methods?|Appendix|Section|Data|Note)\s+S?(\d{1,3})\b"
    r"|^#{1,4}\s.*?\bS(\d{1,3})\b",
    re.IGNORECASE | re.MULTILINE)


def supplement_section_numbers(texts: list[str]) -> set[int]:
    nums: set[int] = set()
    for t in texts:
        for m in SUPP_SECTION.finditer(t):
            g = m.group(1) or m.group(2)
            if g:
                nums.add(int(g))
    return nums


def check_xref(manuscript_text: str, supplement_texts: list[str]) -> list[dict]:
    claims: list[dict] = []
    present = supplement_section_numbers(supplement_texts)
    seen: set[tuple[str, int]] = set()
    for m in BODY_CALLOUT.finditer(manuscript_text):
        kind = m.group(1).rstrip(".").title()
        num = int(m.group(2))
        key = (kind, num)
        if key in seen:
            continue
        seen.add(key)
        if num not in present:
            ln = _line_of(manuscript_text, m.start())
            claims.append({
                "verdict": "SUPP_XREF_UNRESOLVED",
                "severity": "Major",
                "detail": (f"body cites 'Supplementary {kind} {num}' but no supplement "
                           f"section numbered {num} was found (renumber drift or a "
                           f"silently-skipped/unrendered section)"),
                "where": f"manuscript:{ln}",
            })
    return claims


def analyze(supplements: list[str], manuscript: str | None) -> dict:
    supp_paths = []
    supp_texts = []
    claims: list[dict] = []
    for s in supplements:
        p = Path(s)
        if not p.is_file():
            sys.stderr.write(f"ERROR: supplement not found: {s}\n")
            sys.exit(2)
        supp_paths.append(p)
        supp_texts.append(p.read_text(encoding="utf-8", errors="replace"))
        claims.extend(lint_file(p))

    if manuscript:
        mp = Path(manuscript)
        if not mp.is_file():
            sys.stderr.write(f"ERROR: manuscript not found: {manuscript}\n")
            sys.exit(2)
        claims.extend(check_xref(mp.read_text(encoding="utf-8", errors="replace"), supp_texts))

    n_major = sum(1 for c in claims if c["severity"] == "Major")
    return {
        "supplements": [str(p) for p in supp_paths],
        "manuscript": manuscript,
        "claims": claims,
        "summary": {
            "n_claims": len(claims),
            "n_major": n_major,
            "n_flag": len(claims) - n_major,
            "verdict": "MAJOR_CANDIDATE" if n_major else "OK",
        },
    }


def render(result: dict) -> str:
    lines = ["| Check | Severity | Detail |", "|---|---|---|"]
    for c in result["claims"]:
        lines.append(f"| {c['verdict']} | {c['severity']} | {c['detail']} |")
    if len(lines) == 2:
        lines.append("| (none) | — | supplement / tables / caption files are reader-clean |")
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(
        description="Reader-facing supplement / tables / caption hygiene gate.")
    ap.add_argument("--supplement", action="append", default=[], metavar="PATH",
                    help="a rendered reader-facing file to lint (repeatable: supplement, tables, captions)")
    ap.add_argument("--manuscript", help="manuscript body (for Supplementary-X-N cross-ref resolution)")
    ap.add_argument("--out", help="write JSON artifact to this path")
    ap.add_argument("--strict", action="store_true", help="exit 1 if any Major claim exists")
    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
    args = ap.parse_args()

    if not args.supplement:
        sys.stderr.write("ERROR: at least one --supplement file is required\n")
        return 2

    result = analyze(args.supplement, args.manuscript)

    if not args.quiet:
        print("=" * 41)
        print(" Supplement Hygiene (§J supplement pass)")
        print("=" * 41)
        print(render(result))
        print()
        s = result["summary"]
        if s["n_major"]:
            print(f"MAJOR candidate: {s['n_major']} reader-facing supplement residue issue(s).")
        else:
            print("OK: supplement / tables / caption files are reader-clean.")

    if args.out:
        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
        Path(args.out).write_text(json.dumps({"detector": "check_supplement_hygiene", **result}, indent=2), encoding="utf-8")
        if not args.quiet:
            print(f"\nwrote {args.out}")

    return 1 if (args.strict and result["summary"]["n_major"]) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""check_table_percentages.py — recompute every ``n (p%)`` table cell against its
own column denominator and flag a printed percentage that does not match the count.

The cheapest, highest-precision arithmetic check a reviewer can run: a
characteristics table printing ``79 (63%)`` and ``53 (37%)`` under a denominator of
132 is simply wrong (59.8% / 40.2%), needs no judgement or domain knowledge, and
routinely survives multiple review rounds because it was on the page from the
first submission. This detector parses GFM pipe tables from a manuscript, recovers
each column's denominator, and recomputes ``100·n/denominator`` for every count/
percentage cell.

Percentage-column detection (so ``mean (SD)`` cells never fire): a column is
treated as percentages only when a cell carries an explicit ``%`` OR its
parenthetical values (each ≤ 100) sum to ~100 — a percentage partition. Standard
deviations do not sum to 100 and carry no ``%``, so they are skipped.

Denominator recovery, in order: a ``n = N`` in the column header; a Total/Overall
row's count; or the column's own counts summing (a partition). A column with no
recoverable denominator emits ``PERCENT_DENOM_UNKNOWN`` (informational only).

Stdlib-only. Reads the manuscript, never writes it.

Usage:
  python3 check_table_percentages.py --manuscript paper.md
  python3 check_table_percentages.py --manuscript paper.md --strict --quiet
  python3 check_table_percentages.py --manuscript paper.md --tol 0.5 --json
Exit: 0 clean; with --strict, 1 on any PERCENT_MISMATCH; 2 on input/usage error.
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from dataclasses import dataclass, field, asdict

DEFAULT_TOL = 0.5  # percentage points

CELL_RE = re.compile(r"^\s*([0-9][0-9,]*)\s*\(\s*([0-9]+(?:\.[0-9]+)?)\s*(%?)\s*\)\s*$")
HEADER_N_RE = re.compile(r"\bn\s*=\s*([0-9][0-9,]*)", re.I)
TOTAL_LABEL_RE = re.compile(r"^\s*(total|overall|all|entire cohort|full cohort|whole cohort)\b", re.I)
SEP_RE = re.compile(r"^\s*\|?[\s:|-]*-[\s:|-]*\|?\s*$")


@dataclass
class Finding:
    kind: str            # PERCENT_MISMATCH / PERCENT_DENOM_UNKNOWN
    severity: str        # MAJOR / INFO
    table_line: int      # 1-indexed line of the table header
    cell: str
    detail: str


@dataclass
class Report:
    source: str
    findings: list[Finding] = field(default_factory=list)

    @property
    def n_mismatch(self) -> int:
        return sum(1 for f in self.findings if f.kind == "PERCENT_MISMATCH")

    @property
    def verdict(self) -> str:
        return "MISMATCH FOUND" if self.n_mismatch else "OK"


def _split_row(line: str) -> list[str]:
    s = line.strip()
    if s.startswith("|"):
        s = s[1:]
    if s.endswith("|"):
        s = s[:-1]
    return [c.strip() for c in s.split("|")]


def _parse_tables(text: str):
    """Yield (header_cells, data_rows, header_line_no) for each GFM pipe table."""
    lines = text.splitlines()
    i, n = 0, len(lines)
    while i < n:
        if "|" in lines[i] and i + 1 < n and SEP_RE.match(lines[i + 1]) and "-" in lines[i + 1]:
            header = _split_row(lines[i])
            rows, j = [], i + 2
            while j < n and "|" in lines[j] and lines[j].strip():
                rows.append(_split_row(lines[j]))
                j += 1
            yield header, rows, i + 1
            i = j
        else:
            i += 1


def _cell_count_pct(cell: str):
    m = CELL_RE.match(cell)
    if not m:
        return None
    count = int(m.group(1).replace(",", ""))
    pct = float(m.group(2))
    has_pct = m.group(3) == "%"
    return count, pct, has_pct


def audit(text: str, source: str, tol: float = DEFAULT_TOL) -> Report:
    rep = Report(source=source)
    for header, rows, lineno in _parse_tables(text):
        ncols = len(header)
        data_rows = [r for r in rows if r and not TOTAL_LABEL_RE.match(r[0])]
        total_rows = [r for r in rows if r and TOTAL_LABEL_RE.match(r[0])]

        for col in range(1, ncols):  # col 0 is the row label
            # gather count/pct cells in this column
            parsed = []
            for r in data_rows:
                if col < len(r):
                    cp = _cell_count_pct(r[col])
                    if cp:
                        parsed.append((r[0], r[col], *cp))  # label, raw, count, pct, has_pct
            if not parsed:
                continue

            # is this a percentage column?
            has_pct = any(p[4] for p in parsed)
            le100 = [p[3] for p in parsed if p[3] <= 100]
            is_partition = len(le100) >= 2 and 98.0 <= sum(le100) <= 102.0
            if not (has_pct or is_partition):
                continue  # e.g. mean (SD): no %, SDs don't sum to 100

            # recover denominator
            denom = None
            src = ""
            if col < len(header):
                hm = HEADER_N_RE.search(header[col])
                if hm:
                    denom, src = int(hm.group(1).replace(",", "")), "header n="
            if denom is None:
                for tr in total_rows:
                    if col < len(tr):
                        tc = CELL_RE.match(tr[col]) or re.match(r"^\s*([0-9][0-9,]*)\s*$", tr[col])
                        if tc:
                            denom, src = int(tc.group(1).replace(",", "")), "Total row"
                            break
            # Summing a column's counts is a denominator only for a partition — mutually exclusive
            # categories accounting for everyone. For the most common table in clinical research, a
            # Table 1 of independent binary characteristics with N declared in the CAPTION, the sum
            # is a meaningless number larger than N, and using it accused every correct cell of bad
            # arithmetic while printing a specific wrong replacement percentage.
            #
            # Gating on `is_partition` is NOT the fix: that flag is computed from the printed
            # percentages summing to ~100, so a partition with a wrong percentage stops looking like
            # a partition — the check would go silent on exactly the error it exists to catch.
            #
            # The denominator is INFERRED here, unlike a header `n =` or a Total row, which the
            # author declared. So it must earn its use: keep it only if it explains at least one
            # cell. A denominator that reconciles nothing is not evidence that every cell is wrong,
            # it is evidence that it is the wrong denominator. Verified below, after recomputation.
            inferred = False
            if denom is None:
                denom, src, inferred = sum(p[2] for p in parsed), "column count-sum", True

            if not denom:
                rep.findings.append(Finding("PERCENT_DENOM_UNKNOWN", "INFO", lineno,
                                            f"column {col}", "percentage column with no recoverable denominator"))
                continue

            column_findings: list[Finding] = []
            reconciled = 0
            for label, raw, count, pct, _hp in parsed:
                if count > denom:
                    continue  # not a proportion of this denominator
                recomputed = 100.0 * count / denom
                if abs(recomputed - pct) > tol:
                    column_findings.append(Finding(
                        "PERCENT_MISMATCH", "MAJOR", lineno, f"{label}: {raw}",
                        f"printed {pct:g}% but {count}/{denom} ({src}) = {recomputed:.1f}% "
                        f"(Δ{abs(recomputed - pct):.1f}pp)"))
                else:
                    reconciled += 1

            # An inferred denominator that reconciles NOTHING is the wrong denominator, not proof
            # that every cell is wrong. Report the gap rather than the accusation. A declared
            # denominator (header `n =`, Total row) is never second-guessed this way: if the author
            # states N and the arithmetic disagrees, that is the finding.
            if inferred and column_findings and reconciled == 0:
                rep.findings.append(Finding(
                    "PERCENT_DENOM_UNKNOWN", "INFO", lineno, f"column {col}",
                    f"percentage column with no declared denominator; the column count-sum "
                    f"({denom}) reconciles none of {len(column_findings)} cell(s), so it is not the "
                    f"denominator — declare N in the column header (n = N) or a Total row to check"))
            else:
                rep.findings.extend(column_findings)
    return rep


def format_report(rep: Report, color: bool) -> str:
    tag = {"OK": "\033[92m", "MISMATCH FOUND": "\033[91m"}.get(rep.verdict, "") if color else ""
    end = "\033[0m" if color else ""
    lines = [f"{tag}== {rep.verdict} =={end}  {rep.source}",
             f"mismatches={rep.n_mismatch} findings={len(rep.findings)}"]
    if not rep.findings:
        lines.append("all n (%) cells reconcile with their column denominators.")
        return "\n".join(lines)
    for f in sorted(rep.findings, key=lambda x: (x.kind != "PERCENT_MISMATCH", x.table_line, x.cell)):
        lines.append(f"[{f.severity:<5}] {f.kind:<22} L{f.table_line}  {f.detail}")
        lines.append(f"        cell> {f.cell}")
    return "\n".join(lines)


def main(argv: list[str] | None = None) -> int:
    ap = argparse.ArgumentParser(description=__doc__,
                                 formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text with GFM tables")
    ap.add_argument("--tol", type=float, default=DEFAULT_TOL,
                    help=f"flag threshold in percentage points (default {DEFAULT_TOL})")
    ap.add_argument("--strict", action="store_true", help="exit 1 if any PERCENT_MISMATCH")
    ap.add_argument("--quiet", action="store_true", help="suppress the report; exit code only")
    ap.add_argument("--json", action="store_true", help="emit JSON instead of a text report")
    ap.add_argument("--out", help="write the JSON artifact to this path")
    args = ap.parse_args(argv)

    try:
        text = open(args.manuscript, encoding="utf-8").read()
    except OSError as e:
        print(f"error: cannot read manuscript: {e}", file=sys.stderr)
        return 2

    rep = audit(text, source=args.manuscript, tol=args.tol)
    payload = {"source": rep.source, "verdict": rep.verdict,
               "n_mismatch": rep.n_mismatch, "findings": [asdict(f) for f in rep.findings]}
    if args.out:
        with open(args.out, "w", encoding="utf-8") as fh:
            json.dump({"detector": "check_table_percentages", **payload}, fh, ensure_ascii=False, indent=2)

    if not args.quiet:
        print(json.dumps({"detector": "check_table_percentages", **payload}, ensure_ascii=False, indent=2) if args.json
              else format_report(rep, color=sys.stdout.isatty()))

    return 1 if (args.strict and rep.n_mismatch) else 0


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

#!/usr/bin/env python3
"""Refinement regression axis -- did this revision fix without breaking?

self-review is stateless: each run reports the manuscript's current findings, but nothing
compares one run to the last. So when the author revises to fix finding X, the gate
pass-rate goes up ("X resolved") and no one measures whether the fix *introduced* a new
finding Y. The loop looks like it is improving -- fewer of the old problems -- while
quietly accumulating new ones. Worse, a finding that was fixed can reappear a round later
(the "Mirror Loop"): the loop is churning, re-deriving, not converging.

This is NOT a detector -- it finds no defect in the manuscript. It reads a small
run-history **ledger** (one line per self-review run, each line the fingerprints of that
run's findings) plus the current run's `qc/*.json`, and reports the regression axis
*alongside* the pass-rate axis:

  resolved   findings present last run, gone now            (what the revision FIXED)
  carried    findings present both runs                     (still open)
  new        findings present now, absent last run          (what the revision BROKE)
  churn      new findings that were present in an EARLIER    (Mirror Loop: a fixed finding
             run and had been resolved                        resurfaced -> stop churning)

  Verdict:
    CONVERGED      nothing new and nothing carried -- the loop is done
    CHURNING       a resolved finding reappeared -- ungrounded re-derivation, stop the loop
    REGRESSION     the revision introduced new finding(s)
    PROGRESSING    findings resolved, none newly introduced
    INDETERMINATE  first run -- no prior entry to compare against

A finding's fingerprint is `verdict@where` (deterministic; no semantic matching). The gate
is advisory and NEVER blocks -- it is a signal, not a barrier: `--strict` is accepted for
CLI parity but every non-error path exits 0. By default it only classifies (read-only); with
`--append` it also records the current run as the next ledger entry.

INPUTS
  --qc-dir   directory holding the current run's qc/*.json artifacts (required).
  --ledger   the run-history ledger, one JSON object per line (required; created on
             first --append).
  --append   after classifying, append the current run's fingerprints as a new entry.
  --out      optional JSON artifact path.
  --quiet    suppress the stdout summary.
  --strict   accepted for CLI parity; never blocks.

OUTPUT
  A regression summary (stdout) and, with --out, a JSON artifact:
    {tool, qc_dir, ledger, verdict, resolved[], carried[], new[], churn[], recommendation}

Stdlib-only (json / argparse / pathlib / sys). Exit codes: 0 always for a judged or
indeterminate state (advisory), 2 input/usage error.
"""

from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path

import _qc_findings  # same-dir helper: read the heterogeneous detector JSON schemas uniformly

TOOL = "refinement_regression"

STOP_HINT = {
    "CONVERGED": "Nothing new and nothing carried -- the loop is done. Stop.",
    "CHURNING": (
        "A previously-resolved finding reappeared ({churn}) -- the loop is re-deriving, not "
        "converging (the Mirror Loop). Stop revising and re-anchor; more passes will not help."
    ),
    "REGRESSION": (
        "The last revision resolved {n_resolved} finding(s) but INTRODUCED {n_new} new one(s) "
        "({new}). Fixing raised the pass-rate while breaking something else -- review the new "
        "findings before continuing."
    ),
    "PROGRESSING": (
        "{n_resolved} finding(s) resolved and none newly introduced -- the revision improved "
        "the manuscript without breaking anything. Continue."
    ),
    "INDETERMINATE": (
        "No prior ledger entry -- this is the first run. Re-run after a revision (with "
        "--append recording each run) to measure regression."
    ),
}


def _current_keys(qc_dir: Path) -> tuple[list[str], list[str]]:
    """Return (sorted finding fingerprints, sorted unparsed gate names) for the current run.
    Reads both the `claims` and `findings` detector schemas via _qc_findings; a detector-keyed
    file whose schema is unrecognised is surfaced (unparsed), not silently dropped — a dropped
    gate would understate what the run found and corrupt the cross-run comparison."""
    keys: set[str] = set()
    unparsed: set[str] = set()
    for path in sorted(qc_dir.glob("*.json")):
        try:
            obj = json.loads(path.read_text(encoding="utf-8"))
        except (OSError, ValueError):
            continue
        g = _qc_findings.parse_gate(obj)
        if g is None:
            continue
        if not g["parsed"]:
            unparsed.add(g["name"])
            continue
        keys.update(g["keys"])
    return sorted(keys), sorted(unparsed)


def _read_ledger(path: Path) -> list[dict]:
    if not path.is_file():
        return []
    entries = []
    for line in path.read_text(encoding="utf-8").splitlines():
        line = line.strip()
        if not line:
            continue
        try:
            obj = json.loads(line)
        except ValueError:
            continue
        if isinstance(obj, dict) and isinstance(obj.get("keys"), list):
            entries.append(obj)
    return entries


def classify(current: list[str], entries: list[dict]) -> dict:
    cur = set(current)
    if not entries:
        verdict = "INDETERMINATE"
        resolved = carried = new = churn = []
    else:
        prev = set(entries[-1]["keys"])
        prior_all: set[str] = set()
        for e in entries[:-1]:
            prior_all |= set(e["keys"])
        resolved = sorted(prev - cur)
        carried = sorted(prev & cur)
        new = sorted(cur - prev)
        churn = sorted(set(new) & prior_all)
        if not new and not carried:
            verdict = "CONVERGED"
        elif churn:
            verdict = "CHURNING"
        elif new:
            verdict = "REGRESSION"
        else:
            verdict = "PROGRESSING"

    rec = STOP_HINT[verdict].format(
        n_resolved=len(resolved),
        n_new=len(new),
        new=", ".join(new) if new else "-",
        churn=", ".join(churn) if churn else "-",
    )
    return {
        "tool": TOOL,
        "verdict": verdict,
        "resolved": resolved,
        "carried": carried,
        "new": new,
        "churn": churn,
        "recommendation": rec,
    }


def render(result: dict, qc_dir: str, ledger: str) -> str:
    lines = [
        f"Refinement regression: {result['verdict']}",
        f"  fixed (resolved): {len(result['resolved'])}   still open (carried): {len(result['carried'])}",
        f"  broke (new):      {len(result['new'])}   resurfaced (churn):  {len(result['churn'])}",
    ]
    if result.get("gates_unparsed"):
        lines.append(f"  unparsed gates:   {', '.join(result['gates_unparsed'])}  (unrecognised schema — NOT counted)")
    lines.append(f"  qc dir: {qc_dir}   ledger: {ledger}")
    lines.append(f"  -> {result['recommendation']}")
    return "\n".join(lines)


def main(argv=None) -> int:
    ap = argparse.ArgumentParser(description="Classify a self-review run against the prior run (regression axis) from a run-history ledger.")
    ap.add_argument("--qc-dir", required=True, help="directory holding the current run's qc/*.json artifacts")
    ap.add_argument("--ledger", required=True, help="run-history ledger (one JSON object per line)")
    ap.add_argument("--append", action="store_true", help="append the current run's fingerprints as a new ledger entry")
    ap.add_argument("--out", help="optional JSON artifact path")
    ap.add_argument("--quiet", action="store_true", help="suppress the stdout summary")
    ap.add_argument("--strict", action="store_true", help="accepted for CLI parity; never blocks (advisory)")
    args = ap.parse_args(argv)

    qc_dir = Path(args.qc_dir)
    if not qc_dir.is_dir():
        print(f"error: qc dir not found: {args.qc_dir}", file=sys.stderr)
        return 2
    current, unparsed = _current_keys(qc_dir)
    ledger_path = Path(args.ledger)
    entries = _read_ledger(ledger_path)

    result = classify(current, entries)
    result["gates_unparsed"] = unparsed
    if unparsed:
        result["recommendation"] += (
            f" (WARNING: {len(unparsed)} gate artifact(s) had an unrecognised schema and were not "
            f"counted, so this comparison may miss findings: {', '.join(unparsed)})")

    if args.append:
        run_no = len(entries) + 1
        with ledger_path.open("a", encoding="utf-8") as fh:
            fh.write(json.dumps({"run": run_no, "keys": current}) + "\n")

    out = {"qc_dir": str(args.qc_dir), "ledger": str(args.ledger), **result}
    if args.out:
        Path(args.out).write_text(json.dumps(out, indent=2) + "\n", encoding="utf-8")
    if not args.quiet:
        print(render(result, str(args.qc_dir), str(args.ledger)))
    return 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""Refinement terminal-state classifier -- the loop controller for self-review.

self-review runs a stack of *floor* gates (Phases 2.5-2.5f: numerical, citation,
cross-reference, leakage) that minimize rejection-for-cause, and one *ceiling* pass
(Phase 2.5g, check_editorial_impression) that recommends SUBTRACTION so an accurate
manuscript also reads confidently. Run in a loop -- self-review, revise, self-review --
the floor gates converge to a fixed point (0 Major) but nothing tells the author the
loop is *done*. Because every additive gate can always surface one more caveat, an
ungrounded refinement loop drifts: the manuscript over-hardens, the same findings get
re-raised in new words (the "Mirror Loop"), and "no edit needed" is never declared a
valid outcome.

This is NOT a detector -- it finds no defect in the manuscript, so it carries no
`check_`/`detect_`/`derive_` prefix and is not counted in the detector catalog. It reads
the JSON artifacts the other gates already wrote (qc/*.json) and classifies the
*terminal state* of the refinement loop, so the harness has a reproducible stop signal
it cannot rationalize away:

  CONTINUE             a floor gate still reports a Major (rejection-for-cause). Real
                       work remains.
  STOP_OVERHARDENING   floor at its fixed point (0 Major), but the ceiling pass flags
                       accumulation (over-hedging / buried defense). Stop ADDING; the
                       only remaining action is optional SUBTRACTION.
  STOP_MINOR_OPTIONAL  floor at fixed point; only optional Minor polish remains, ceiling
                       clean. Stop the required-work loop; present the Minor items as a
                       menu, do not loop for them.
  STOP_ZERO_EDIT       floor at fixed point (0 Major, 0 Minor), ceiling clean. The
                       manuscript is submission-ready as-is. A zero-edit result is a
                       valid PASS -- do not manufacture changes.
  INDETERMINATE        no gate artifacts found; the floor/ceiling gates have not run.

A floor gate's JSON is recognised by a `summary.n_major`; the ceiling pass by a
`summary.by_action`. The classifier is advisory and NEVER blocks -- it must not
double-gate the floor detectors, which already exit non-zero under --strict on their own
Majors. --strict is accepted for CLI parity but every non-error path exits 0. This is the
counterweight to the additive bias of the whole stack: the one step that can say "stop,
this is done".

INPUTS
  --qc-dir   directory holding the gates' qc/*.json artifacts (required).
  --out      optional JSON artifact path.
  --quiet    suppress the stdout summary.
  --strict   accepted for parity; never blocks.

OUTPUT
  A terminal-state summary (stdout) and, with --out, a JSON artifact:
    {tool, qc_dir, verdict, stop, floor_major, floor_minor, ceiling_findings,
     gates_read[], recommendation}

Stdlib-only (json / argparse / pathlib / sys). Exit codes: 0 always for a judged or
indeterminate state (advisory), 2 input/usage error (--qc-dir missing as an argument).
"""

from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path

import _qc_findings  # same-dir helper: read the heterogeneous detector JSON schemas uniformly

TOOL = "refinement_stop"

RECOMMENDATIONS = {
    "CONTINUE": (
        "Floor gates report {floor_major} Major finding(s) (rejection-for-cause). "
        "Genuine work remains -- resolve these before treating the loop as done."
    ),
    "STOP_OVERHARDENING": (
        "Floor is at its fixed point (0 Major). The ceiling pass flags {ceiling_findings} "
        "accumulation signal(s) -- the draft has begun to over-harden. STOP additive "
        "refinement: do NOT run another add-a-caveat/defense pass. The only remaining "
        "action is SUBTRACTION (REMOVE / MOVE / TIGHTEN) and it is optional, not required "
        "for submission."
    ),
    "STOP_MINOR_OPTIONAL": (
        "Floor is at its fixed point (0 Major); {floor_minor} optional Minor item(s) "
        "remain and the ceiling is clean. No required edits -- present the Minor items as "
        "an optional menu; do not treat them as blocking and do not loop for them."
    ),
    "STOP_ZERO_EDIT": (
        "Floor is at its fixed point (0 Major, 0 Minor) and the ceiling is clean. The "
        "manuscript is submission-ready as-is. NO EDITS REQUIRED -- a zero-edit result is "
        "a valid PASS. Do not manufacture changes."
    ),
    "INDETERMINATE": (
        "No gate artifacts found in the qc directory. Run the floor gates "
        "(Phases 2.5-2.5f) and the ceiling pass (Phase 2.5g) first; the terminal state "
        "cannot be judged without them."
    ),
}

STOP_VERDICTS = {"STOP_OVERHARDENING", "STOP_MINOR_OPTIONAL", "STOP_ZERO_EDIT"}


def classify(qc_dir: Path) -> dict:
    floor_major = floor_minor = ceiling_findings = 0
    gates: list[str] = []
    unparsed: list[str] = []
    unknown_sev: list[str] = []
    for path in sorted(qc_dir.glob("*.json")):
        try:
            obj = json.loads(path.read_text(encoding="utf-8"))
        except (OSError, ValueError):
            continue
        g = _qc_findings.parse_gate(obj)
        if g is None:
            continue
        gates.append(g["name"])
        if not g["parsed"]:
            # a detector-keyed file with an unrecognised schema -- do NOT count it as clean
            unparsed.append(g["name"])
            continue
        unknown_sev.extend(g.get("unknown_severities") or [])
        if g["kind"] == "ceiling":
            ceiling_findings += g["major"] + g["minor"]
        else:
            floor_major += g["major"]
            floor_minor += g["minor"]

    if not gates:
        verdict = "INDETERMINATE"
    elif floor_major > 0:
        verdict = "CONTINUE"
    elif ceiling_findings > 0:
        verdict = "STOP_OVERHARDENING"
    elif floor_minor > 0:
        verdict = "STOP_MINOR_OPTIONAL"
    else:
        verdict = "STOP_ZERO_EDIT"

    rec = RECOMMENDATIONS[verdict].format(
        floor_major=floor_major,
        floor_minor=floor_minor,
        ceiling_findings=ceiling_findings,
    )
    if unknown_sev:
        rec += (f" (WARNING: severity word(s) no controller knows: "
                f"{', '.join(sorted(set(unknown_sev)))} — counted as Major so the loop continues "
                f"rather than stopping over a verdict nobody classified)")
    if unparsed:
        rec += (f" (WARNING: {len(unparsed)} gate artifact(s) had an unrecognised schema and were "
                f"NOT counted -- this verdict may understate the floor: "
                f"{', '.join(sorted(set(unparsed)))})")
    return {
        "tool": TOOL,
        "verdict": verdict,
        "stop": verdict in STOP_VERDICTS,
        "floor_major": floor_major,
        "floor_minor": floor_minor,
        "ceiling_findings": ceiling_findings,
        "gates_read": sorted(set(gates)),
        "gates_unparsed": sorted(set(unparsed)),
        "unknown_severities": sorted(set(unknown_sev)),
        "recommendation": rec,
    }


def render(result: dict, qc_dir_display: str) -> str:
    fixed = "  (fixed point)" if result["floor_major"] == 0 and result["verdict"] != "INDETERMINATE" else ""
    gates = ", ".join(result["gates_read"]) if result["gates_read"] else "(none)"
    lines = [
        f"Refinement terminal-state: {result['verdict']}",
        f"  Floor gates:   {result['floor_major']} Major, {result['floor_minor']} Minor{fixed}",
        f"  Ceiling pass:  {result['ceiling_findings']} finding(s)",
        f"  Gates read:    {gates}",
    ]
    if result.get("unknown_severities"):
        lines.append(f"  Unknown sev:   {', '.join(result['unknown_severities'])}  "
                     f"(counted as Major — the loop continues rather than stopping on a guess)")
    if result.get("gates_unparsed"):
        lines.append(f"  Unparsed:      {', '.join(result['gates_unparsed'])}  (unrecognised schema — NOT counted)")
    lines.append(f"  qc dir:        {qc_dir_display}")
    lines.append(f"  -> {result['recommendation']}")
    return "\n".join(lines)


def main(argv=None) -> int:
    ap = argparse.ArgumentParser(
        description="Classify the refinement loop's terminal state from qc/*.json gate artifacts."
    )
    ap.add_argument("--qc-dir", required=True, help="directory holding the gates' qc/*.json artifacts")
    ap.add_argument("--out", help="optional JSON artifact path")
    ap.add_argument("--quiet", action="store_true", help="suppress the stdout summary")
    ap.add_argument("--strict", action="store_true", help="accepted for CLI parity; never blocks (advisory)")
    args = ap.parse_args(argv)

    qc_dir = Path(args.qc_dir)
    if not qc_dir.is_dir():
        # Absent qc dir is not a usage error in a pipeline where the gates may not have run
        # yet; report INDETERMINATE and exit 0 so the loop controller degrades gracefully.
        result = {
            "tool": TOOL,
            "verdict": "INDETERMINATE",
            "stop": False,
            "floor_major": 0,
            "floor_minor": 0,
            "ceiling_findings": 0,
            "gates_read": [],
            "gates_unparsed": [],
            "unknown_severities": [],
            "recommendation": RECOMMENDATIONS["INDETERMINATE"],
        }
    else:
        result = classify(qc_dir)

    result_out = {"qc_dir": str(args.qc_dir), **result}
    if args.out:
        Path(args.out).write_text(json.dumps(result_out, indent=2) + "\n", encoding="utf-8")
    if not args.quiet:
        print(render(result, str(args.qc_dir)))
    return 0


if __name__ == "__main__":
    sys.exit(main())

"""Strip a leading YAML front-matter block off a manuscript before prose analysis.

Several `--manuscript` detectors in this skill roll their own body extractor that filters
lines starting with `#`, `|`, `>`, `!`, list markers and code fences. A `---`-fenced YAML
front-matter block matches none of those, so the `status:`, changelog and build-note lines
that projects keep at the top of a pandoc manuscript were read as body prose. Two shipped
detectors fired on it: `check_citation_order` reported floats "cited out of order" from a
`status:` block narrating a display-item renumber, and `check_aphorism_density` listed build
notes among the manuscript's "very short declaratives".

`strip_frontmatter` removes exactly the pandoc/YAML front-matter block: an opening `---` fence
on the FIRST line and its matching closing `---` fence. If the first line is not a fence, or the
block is never closed, the whole text is returned unchanged (a lone `---` in the body — a
horizontal rule or a setext underline — is never mistaken for front matter). Same fence semantics
as `sync-submission/scripts/_yaml_frontmatter.py`; kept independent because skills are
self-contained and cross-skill imports are forbidden.

Private helper (leading underscore) so the detector-catalog glob (`check_*` / `detect_*` /
`derive_*` / `verify_refs`) never counts it. Consumers run with their own directory on
sys.path[0] (invoked as `python3 .../scripts/<name>.py`), so a sibling `from _frontmatter import
strip_frontmatter` resolves wherever the skill is installed or vendored.
"""
from __future__ import annotations

import re

_FENCE_RE = re.compile(r"^---\s*$")


def strip_frontmatter(text: str) -> str:
    """Return ``text`` with a leading ``---``-fenced YAML front-matter block removed.

    Returns ``text`` unchanged when there is no opening fence on the first line or the
    block is never closed. The trailing newline layout of the body is preserved so
    character offsets after the front matter shift by a fixed amount only.
    """
    lines = text.splitlines(keepends=True)
    if not lines or not _FENCE_RE.match(lines[0].rstrip("\r\n")):
        return text
    for i in range(1, len(lines)):
        if _FENCE_RE.match(lines[i].rstrip("\r\n")):
            return "".join(lines[i + 1:])
    # Opening fence but no closing fence — not front matter; leave the text intact.
    return text

"""Body-prose extraction shared by the prose-rhythm detectors.

`check_aphorism_density.py` and `check_rhetorical_density.py` measure different tells — negative
definitions and short-declarative rhythm on one side, antithesis and cleft constructions on the
other — over *the same text*: the manuscript's body prose with front matter, headings, tables,
block quotes, code fences, list items, citation markers and inline markup removed. Both carried a
byte-identical copy of that extractor. Two copies of one definition is one drift away from two
detectors reporting densities over different denominators and no longer being comparable.

WHAT IS **NOT** SHARED, DELIBERATELY: sentence splitting. The two detectors genuinely differ there
and unifying them would change what they measure:

    aphorism    SENT_SPLIT_RE = (?<=[.!?])\\s+(?=[A-Z"“])          sentences: >= 2 words
    rhetorical  SENT_SPLIT_RE = (?<=[.!?])\\s+(?=["“(]?[A-Z0-9])   sentences: any non-empty

The rhetorical splitter starts a sentence at a digit or an opening parenthesis; the aphorism one
does not, and it drops one-word fragments so a run of them cannot masquerade as clipped
declaratives. Those choices belong to what each gate measures. Folding them together would silently
move every density in both detectors — a behaviour change wearing a refactor's clothes — so each
detector keeps its own splitter and its own sentence filter.

Same-directory import, like `_frontmatter`: skills are self-contained and cross-skill imports are
forbidden, so `humanize/scripts/check_sentence_variety.py` keeps its own extractor by design.

Stdlib only.
"""

from __future__ import annotations

import re

from _frontmatter import strip_frontmatter

FENCE_RE = re.compile(r"```.*?```", re.S)

CITE_RE = re.compile(r"\[@[^\]]+\]|\[\d+(?:[,–-]\d+)*\]")

INLINE_RE = re.compile(r"[*_`]")


def body_text(md: str) -> str:
    """Body prose only: no headings, tables, block quotes, code, citations, markup."""
    md = strip_frontmatter(md)   # a `status:`/build-note YAML block is not prose rhythm
    md = FENCE_RE.sub(" ", md)
    keep = []
    for line in md.splitlines():
        s = line.strip()
        if not s or s.startswith(("#", "|", ">", "!", "---")):
            continue
        if re.match(r"^\s*(?:[-*+]|\d+\.)\s", line):   # list items are not prose rhythm
            continue
        keep.append(s)
    txt = " ".join(keep)
    txt = CITE_RE.sub("", txt)
    txt = INLINE_RE.sub("", txt)
    return re.sub(r"\s+", " ", txt).strip()

"""Shared finding-extraction across the heterogeneous detector JSON schemas.

The detectors do **not** share one output envelope. Some list their findings under
`claims`, some under `findings`; per item the verdict is `verdict` | `kind` | `type`, the
severity casing varies (`Major` vs `MAJOR`), and the location is `where` | `location` |
`line` | `table_line`. The only contract `check_detector_envelopes` enforces is the
top-level `detector` key. The refinement loop controllers (`refinement_stop`,
`refinement_regression`) aggregate every gate's `qc/*.json`, so they must read all of these
shapes — and, critically, make an *unreadable* one LOUD, not silent: a controller that
quietly skips a detector whose schema it does not recognise can report a clean STOP_ZERO_EDIT
while a `findings`-schema gate held a Major.

`parse_gate(obj)` returns None when the object is not a gate artifact (this tool's own
`{"tool": ...}` output, a ledger line), else:
    {name, kind: "ceiling"|"floor", major, minor, keys: ["verdict@where", ...], parsed: bool}
`parsed` is False for a `detector`-keyed file whose finding list is under an unknown key —
the caller surfaces it (gates_unparsed) rather than counting it as clean.

Stdlib-only. Imported by refinement_stop.py / refinement_regression.py from the same dir.
"""

from __future__ import annotations

_LIST_KEYS = ("claims", "findings")
_VERDICT_KEYS = ("verdict", "kind", "type")
_WHERE_KEYS = ("where", "location", "line", "table_line")
# The severity vocabulary is not one word. Detectors were written independently and each picked its
# own, and `_MAJOR` knew two of them — so a gate that says a manuscript CANNOT be submitted was
# counted as an optional Minor. `check_placeholders` marks a leftover `TODO` as `blocker` and exits 1
# on it unconditionally; the stop controller read that as "no required edits, do not loop".
#
# Membership below is derived from each detector's OWN exit contract, not from what the word sounds
# like — the word had to make its detector return 1:
#   blocker  check_placeholders            `if s["blocker"]: return 1`        (no --strict needed)
#   hard     check_disclosure_availability `verdict == "BLOCKER"  -> 1`
#            check_summary_box             `NONCONFORMANT and --strict -> 1`
#            build_title_page_affiliations `rc = 1`
#   stale    check_checklist_version       docstring: "0 = in sync, 1 = stale / unverifiable"
#   unverif. check_checklist_version       same detector, same `return 0 if safe else 1`; its own
#                                          output line reads "FAIL: checklist is stale or
#                                          unverifiable". Found by the repo-wide assertion in
#                                          test_qc_severity_vocabulary.sh, not by enumeration —
#                                          which is the point of having that assertion.
#   FAIL     validate_pptx_mac_compat      `--strict and not ok   -> 1`
#
# `Flag` is deliberately NOT here, and that is the control that shows this is a derivation rather
# than a widening: check_generated_code computes `n_flag = len(claims) - n_major` and exits only on
# `n_major`, so its own contract says Flag is advisory. `soft` and `warn` likewise.
_MAJOR = {"MAJOR", "FATAL", "BLOCKER", "HARD", "STALE", "UNVERIFIABLE", "FAIL"}

# Known-advisory. Kept explicit so that a severity belonging to NEITHER set is a novel word rather
# than an assumption — see `_classify` below.
_MINOR = {"MINOR", "FLAG", "SOFT", "WARN", "WARNING", "INFO", "NOTE", "OK", "PASS", ""}


def _classify(severity: str) -> str:
    """Return "major" | "minor" | "unknown" for a raw severity string.

    Unknown counts as MAJOR. This module's docstring already states the rule for an unrecognised
    *schema* — make it loud, never silent, because a controller that quietly skips what it cannot
    read can report a clean STOP_ZERO_EDIT over a held Major. An unrecognised *severity* is the same
    hazard one level down, and it defaulted the other way: straight into `minor`, straight into
    "nothing to do". For a stop controller, guessing "major" costs one more loop; guessing "minor"
    ends the loop over an unfixed blocker.
    """
    s = str(severity).strip().upper()
    if s in _MAJOR:
        return "major"
    if s in _MINOR:
        return "minor"
    return "unknown"


def parse_gate(obj) -> dict | None:
    if not isinstance(obj, dict):
        return None
    summary = obj.get("summary") if isinstance(obj.get("summary"), dict) else {}
    items = None
    for k in _LIST_KEYS:
        if isinstance(obj.get(k), list):
            items = obj[k]
            break
    has_detector = "detector" in obj
    if items is None and not has_detector:
        return None  # not a gate artifact (e.g. a controller's own {"tool": ...} output)

    name = obj.get("detector") or "?"
    if items is None:
        # detector-keyed but no recognisable finding list: a novel schema. Flag it loudly.
        return {"name": name, "kind": "floor", "major": 0, "minor": 0, "keys": [], "parsed": False}

    dict_items = [it for it in items if isinstance(it, dict)]
    kind = "ceiling" if "by_action" in summary else "floor"

    # Prefer an authoritative summary.n_major (claims-schema gates); otherwise count Majors from
    # each item's severity (findings-schema gates carry no such summary).
    n_major_sum = summary.get("n_major")
    unknown_severities: list[str] = []
    if isinstance(n_major_sum, int):
        major = n_major_sum
        minor = max(0, len(dict_items) - major)
    else:
        major = minor = 0
        for it in dict_items:
            verdict = _classify(it.get("severity", ""))
            if verdict == "minor":
                minor += 1
            else:
                major += 1  # "major", and "unknown" fails toward the loop continuing
                if verdict == "unknown":
                    unknown_severities.append(str(it.get("severity", "")).strip())

    keys = []
    for it in dict_items:
        verdict = next((str(it[v]) for v in _VERDICT_KEYS if it.get(v)), "?")
        where = next((str(it[w]) for w in _WHERE_KEYS if it.get(w) is not None), "?")
        keys.append(f"{verdict}@{where}")

    return {"name": name, "kind": kind, "major": major, "minor": minor, "keys": keys,
            "parsed": True, "unknown_severities": sorted(set(unknown_severities))}

#!/usr/bin/env bash
# Regression test for the aphorism-density gate (P26 / §J — the sentence-rhythm AI tell).
# Synthetic, PII-free fixtures. Three cases:
#   (1) aphorism_dense.md  — the same argument written as epigrams -> APHORISM_DENSITY fires
#   (2) aphorism_clean.md  — the same argument written as explanation -> no finding
#   (3) aphorism_frontmatter.md — a `status:`/build-note YAML block full of short negative
#       definitions, over a body of ordinary explanatory prose. The front matter must be
#       stripped before the rhythm is measured; otherwise its lines are counted as body
#       "very short declaratives" and the detector fires on the changelog. Body-only rate
#       is 0/0, so the no-fire here is the fix, not the min-sentences floor (6 sentences).
# Uses --min-sentences 6 so the small A/B fixtures clear the noise floor. Stdlib-only.
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_aphorism_density.py"
FX="$HERE/fixtures"
OUT="$(mktemp -t aphorism_XXXX).json"
trap 'rm -f "$OUT"' EXIT

fail=0
check() { local label="$1"; shift
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}
run() { python3 "$SCRIPT" --manuscript "$1" --min-sentences 6 --out "$OUT" --quiet >/dev/null 2>&1; }
fired()     { python3 -c "import json,sys; sys.exit(0 if json.load(open('$OUT'))['findings'] else 1)"; }
not_fired() { python3 -c "import json,sys; sys.exit(0 if not json.load(open('$OUT'))['findings'] else 1)"; }

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

# (1) epigram-dense prose -> APHORISM_DENSITY
run "$FX/aphorism_dense.md"
check "epigram-dense fixture fires APHORISM_DENSITY" fired

# (2) explanatory prose (same argument) -> silent
run "$FX/aphorism_clean.md"
check "explanatory fixture does not fire" not_fired

# (3) YAML front-matter changelog must not be measured as body rhythm
run "$FX/aphorism_frontmatter.md"
check "front-matter build/status block does not fire (stripped before measuring)" not_fired
check "no front-matter line is counted as a short declarative" python3 -c "
import json
d=json.load(open('$OUT'))
lines=[s for f in d['findings'] for s in f.get('short_declaratives',[])]
assert not any('SSOT' in s or 'is not' in s for s in lines), lines
assert d['metrics']['sentences']==6, d['metrics']  # body-only sentence count
"

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression test for the artifact-coverage gate (self-review Phase 2.5f).
# Synthetic, PII-free fixtures reproduce: (a) a Methods-promised multiple-
# imputation analysis that never reaches Results (FORWARD), (b) an analysis-bearing
# output CSV (a DeLong nested added-value table) present on disk but unmentioned in
# the manuscript (REVERSE). The clean manuscript reports both and mentions the disk
# outputs, so it reconciles.
# Stdlib-only (python3).
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_artifact_coverage.py"
BAD="$HERE/fixtures/coverage_manuscript.md"
CLEAN="$HERE/fixtures/coverage_clean.md"
ADIR="$HERE/fixtures/coverage_analysis"
OUT="$(mktemp -t cov_XXXX).json"
trap 'rm -f "$OUT"' EXIT

fail=0
check() { local label="$1"; shift
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}
has_verdict() { python3 -c "
import json,sys
d=json.load(open('$OUT'))
assert any(c['verdict']=='$1' for c in d['claims']), '$1 not found'
"; }

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

# (1) bad manuscript + analysis dir: promised-absent + disk-unreported, Major -> exit 1
python3 "$SCRIPT" --manuscript "$BAD" --analysis-dir "$ADIR" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 under --strict (Major present)" test "$?" -eq 1
check "JSON artifact written" test -s "$OUT"
check "PROMISED_ABSENT detected (MI promised, absent from Results)" has_verdict PROMISED_ABSENT
check "DISK_UNREPORTED detected (delong nested CSV unmentioned)"    has_verdict DISK_UNREPORTED

# (2) clean manuscript: reports MI + sensitivity, mentions disk outputs -> exit 0
python3 "$SCRIPT" --manuscript "$CLEAN" --analysis-dir "$ADIR" --strict --quiet >/dev/null 2>&1
check "exit 0 on clean manuscript (all reconciled)" test "$?" -eq 0

# (3) a bound/ceiling/de-confounded AUC promised "is reported in Table S16" but
#     never given a numeric value anywhere -> PROMISED_STAT_NO_VALUE (Major), exit 1
PS="$HERE/fixtures/coverage_promised_stat.md"
python3 "$SCRIPT" --manuscript "$PS" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 (promised stat without a value)" test "$?" -eq 1
check "PROMISED_STAT_NO_VALUE detected" has_verdict PROMISED_STAT_NO_VALUE

# (4) same framing but the de-confounded AUC value (0.71) IS reported -> no fire, exit 0
PSOK="$HERE/fixtures/coverage_promised_stat_ok.md"
python3 "$SCRIPT" --manuscript "$PSOK" --out "$OUT" --quiet >/dev/null 2>&1
check "no PROMISED_STAT_NO_VALUE when the value is reported" python3 -c "
import json
d=json.load(open('$OUT'))
assert not any(c['verdict']=='PROMISED_STAT_NO_VALUE' for c in d['claims']), 'fired despite a reported value'
"
python3 "$SCRIPT" --manuscript "$PSOK" --strict --quiet >/dev/null 2>&1
check "exit 0 when the promised value is present" test "$?" -eq 0

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression test for the cross-script categorical / definition-consistency gate
# (Phase 2.5b/c). Synthetic, PII-free fixtures cover two failure modes:
#   BINNING_DRIFT     — a derived `age_band` binned with two different cut
#                       signatures (45/50/60 right=FALSE vs 44/49/59 right=TRUE)
#                       across two scripts, plus a clean pair sharing one signature.
#   DERIVED_DEF_DRIFT — a composite indicator (`mets_bp`/`mets_fg`) defined with a
#                       dropped OR-clause across two scripts, plus a clean pair that
#                       is identical up to clause order / whitespace / outer parens /
#                       commutative `&`-operand order.
# Stdlib-only (python3).
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_binning_consistency.py"
DRIFT="$HERE/fixtures/binning_drift"
CLEAN="$HERE/fixtures/binning_clean"
DDRIFT="$HERE/fixtures/derived_drift"
DCLEAN="$HERE/fixtures/derived_clean"
OUT="$(mktemp -t bin_XXXX).json"
trap 'rm -f "$OUT"' EXIT

fail=0
check() { local label="$1"; shift
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}
has_verdict() { python3 -c "
import json
d=json.load(open('$OUT'))
assert any(c['verdict']=='$1' for c in d['claims']), '$1 not found'
"; }

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

echo "test_binning_consistency:"

# (1) drift fixtures: BINNING_DRIFT (Major) -> exit 1 under --strict
python3 "$SCRIPT" --root "$DRIFT" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 under --strict (Major present)" test "$?" -eq 1
check "JSON artifact written" test -s "$OUT"
check "BINNING_DRIFT detected (45/50/60 right=FALSE vs 44/49/59 right=TRUE)" has_verdict BINNING_DRIFT

# (2) clean fixtures: identical cut signature -> exit 0, no claim
python3 "$SCRIPT" --root "$CLEAN" --strict --quiet >/dev/null 2>&1
check "exit 0 on consistent binning" test "$?" -eq 0
python3 "$SCRIPT" --root "$CLEAN" --out "$OUT" --quiet >/dev/null 2>&1
check "no BINNING_DRIFT on clean fixtures" bash -c "
python3 -c \"import json; d=json.load(open('$OUT')); assert not d['claims']\"
"

# (3) composite-definition drift: DERIVED_DEF_DRIFT (Major) -> exit 1 under --strict
python3 "$SCRIPT" --root "$DDRIFT" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 under --strict (composite clause dropped)" test "$?" -eq 1
check "DERIVED_DEF_DRIFT detected (mets_bp/mets_fg clause omission)" has_verdict DERIVED_DEF_DRIFT

# (4) clean composite fixtures: same atom SET (reordered / whitespace / parens /
#     commutative &) -> exit 0, no claim
python3 "$SCRIPT" --root "$DCLEAN" --strict --quiet >/dev/null 2>&1
check "exit 0 on order-/whitespace-/paren-equivalent composite defs" test "$?" -eq 0
python3 "$SCRIPT" --root "$DCLEAN" --out "$OUT" --quiet >/dev/null 2>&1
check "no DERIVED_DEF_DRIFT on clean composite fixtures" bash -c "
python3 -c \"import json; d=json.load(open('$OUT')); assert not d['claims']\"
"

# (5) parallel sensitivity cohort: SAME derived rule, different dataframe-receiver
#     object (v0[...] vs lenient_cohort[...]) -> NO DERIVED_DEF_DRIFT (regression).
DALIAS="$HERE/fixtures/derived_clean_dfalias"
python3 "$SCRIPT" --root "$DALIAS" --strict --quiet >/dev/null 2>&1
check "exit 0 on parallel df-alias cohort" test "$?" -eq 0
python3 "$SCRIPT" --root "$DALIAS" --out "$OUT" --quiet >/dev/null 2>&1
check "no DERIVED_DEF_DRIFT on parallel df-alias cohort" bash -c "
python3 -c \"import json; d=json.load(open('$OUT')); assert not any(c['verdict']=='DERIVED_DEF_DRIFT' for c in d['claims'])\"
"

if [[ "$fail" -eq 0 ]]; then echo "  ALL PASS"; else echo "  $fail FAILED"; fi
exit "$fail"

#!/usr/bin/env bash
# Regression test for the float citation-ORDER gate (journal technical-check pass).
# Synthetic, PII-free fixtures: a manuscript whose main Tables (4,2,1,3) and
# supplementary Tables (S3,S1,S8,S2,S6,S4) are cited out of numerical order, and
# a clean manuscript where every series is cited in ascending order (incl. a plural
# list "Tables S4, S5", a back-matter legends block that must be excluded, and a
# non-float "S1 through S6" sensitivity label that must NOT be parsed as tables).
# Stdlib-only (python3).
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_citation_order.py"
BAD="$HERE/fixtures/citation_order_bad.md"
GOOD="$HERE/fixtures/citation_order_good.md"
OUT="$(mktemp -t citorder_XXXX).json"
trap 'rm -f "$OUT"' EXIT

fail=0
check() { local label="$1"; shift
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}
count_order() { python3 -c "
import json
d=json.load(open('$OUT'))
n=sum(1 for c in d['claims'] if c['verdict']=='CITATION_ORDER')
assert n==$1, f'expected $1 CITATION_ORDER, got {n}'
"; }
no_falsepos() { python3 -c "
import json
d=json.load(open('$OUT'))
assert d['summary']['n_major']==0, d['summary']
"; }
count_uncited() { python3 -c "
import json
d=json.load(open('$OUT'))
n=sum(1 for c in d['claims'] if c['verdict']=='UNCITED_FLOAT')
assert n==$1, f'expected $1 UNCITED_FLOAT, got {n}'
"; }
count_verdict() { python3 -c "
import json
d=json.load(open('$OUT'))
n=sum(1 for c in d['claims'] if c['verdict']=='$1')
assert n==$2, f'expected $2 $1, got {n}: {[c[\"verdict\"] for c in d[\"claims\"]]}'
"; }
no_claims() { python3 -c "
import json
d=json.load(open('$OUT'))
assert not d['claims'], d['claims']
"; }

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

# (1) out-of-order manuscript -> 2 CITATION_ORDER (main Table + Suppl Table), exit 1
python3 "$SCRIPT" --manuscript "$BAD" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 under --strict (out-of-order present)" test "$?" -eq 1
check "2 CITATION_ORDER series flagged (Table + Supplementary Table)" count_order 2

# (2) clean manuscript: ascending order, plural list, excluded legends, S1-S6 label
python3 "$SCRIPT" --manuscript "$GOOD" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 0 on clean manuscript (no false positive)" test "$?" -eq 0
check "no Major on clean manuscript" no_falsepos

# (3) DANGLING_SECTION_XREF: "Section 3.4"/"Section 3" refs with UNNUMBERED headings -> Major
SBAD="$HERE/fixtures/citation_order_section_bad.md"
python3 "$SCRIPT" --manuscript "$SBAD" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 on Section-refs with unnumbered headings" test "$?" -eq 1
check "DANGLING_SECTION_XREF flagged" python3 -c "
import json
d=json.load(open('$OUT'))
assert any(c['verdict']=='DANGLING_SECTION_XREF' for c in d['claims']), 'not flagged'
"
# (4) numbered headings resolve the refs, and 'Supplementary Section 5' is exempt -> silent
SGOOD="$HERE/fixtures/citation_order_section_good.md"
python3 "$SCRIPT" --manuscript "$SGOOD" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 0 when Section refs resolve to numbered headings" test "$?" -eq 0
check "no DANGLING_SECTION_XREF when headings are numbered" python3 -c "
import json
d=json.load(open('$OUT'))
assert not any(c['verdict']=='DANGLING_SECTION_XREF' for c in d['claims']), 'false positive'
"

# (5) YAML front matter narrating a display-item renumber ("old Table 1 -> Supplementary
#     Table S2", "old Table 3 -> Box 1") must NOT be scanned as body citations — a
#     `status:`/changelog block is not prose. Body cites Supplementary Tables and figures
#     in ascending order and has no main-text tables.
FM="$HERE/fixtures/citation_order_frontmatter.md"
python3 "$SCRIPT" --manuscript "$FM" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 0 with an out-of-order renumber in YAML front matter (body clean)" test "$?" -eq 0
check "no CITATION_ORDER from a front-matter changelog" count_order 0
check "no Major from a front-matter changelog" no_falsepos

# (6) A float DEFINED by a legend/caption but never cited in the narrative body ->
#     UNCITED_FLOAT (Minor). The fixture cites Table 1, Figure 1 and Supplementary Table
#     S1 (all defined and cited), and defines Supplementary Figure S1 with a full caption
#     that no sentence ever cites.
UNC="$HERE/fixtures/citation_order_uncited.md"
python3 "$SCRIPT" --manuscript "$UNC" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 0 (UNCITED_FLOAT is Minor, not Major)" test "$?" -eq 0
check "one UNCITED_FLOAT for the defined-but-uncited float" count_uncited 1
check "the uncited claim names Supplementary Figure S1" python3 -c "
import json
d=json.load(open('$OUT'))
u=[c for c in d['claims'] if c['verdict']=='UNCITED_FLOAT']
assert u and u[0]['where']=='Supplementary Figure S1', [c['where'] for c in u]
"
# (7) the clean fixture defines nothing uncited -> no UNCITED_FLOAT (no over-fire).
python3 "$SCRIPT" --manuscript "$GOOD" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "no UNCITED_FLOAT on the clean manuscript (no over-fire)" count_uncited 0

# --- reference (in-text [N]) series: the fifth series the float scan never saw ----------
FX="$HERE/fixtures"

# (8) hand-typed [N] manuscript that cites [12] before [5] -> REFERENCE_ORDER (Major), exit 1
python3 "$SCRIPT" --manuscript "$FX/citation_order_ref_order_bad.md" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 when in-text references are out of order ([12] before [5])" test "$?" -eq 1
check "one REFERENCE_ORDER flagged" count_verdict REFERENCE_ORDER 1

# (9) references cited [1..6, 8] with 7 never cited -> REFERENCE_GAP (Minor), exit 0
python3 "$SCRIPT" --manuscript "$FX/citation_order_ref_gap.md" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 0 on a reference gap (Minor, not Major)" test "$?" -eq 0
check "one REFERENCE_GAP for the hole at [7]" count_verdict REFERENCE_GAP 1

# (10) NEGATIVE range trap: 5-10 and 13-14 sit INSIDE rendered ranges [4-11]/[13-15] ->
#      ranges are expanded, so NO false gap -> clean (the case the ad-hoc script got wrong)
python3 "$SCRIPT" --manuscript "$FX/citation_order_ref_range_ok.md" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 0 when the only 'gaps' sit inside a rendered range" test "$?" -eq 0
check "no claim from a reference range (range expanded before gap check)" no_claims

# (11) NEGATIVE clean: contiguous [1..5] in order with a matching 5-entry list -> no over-fire
python3 "$SCRIPT" --manuscript "$FX/citation_order_ref_good.md" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 0 on a clean reference series" test "$?" -eq 0
check "no claim on a clean contiguous reference series (no over-fire)" no_claims

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression test for the claim-vs-artifact cross-check (self-review Phase 2.5f).
# Synthetic fixture reproduces: (a) a primary re-designated at manuscript stage,
# (b) an E-value (3.10) that does not recompute from its stated primary HR 1.52,
# (c) a correctly-arithmetic E-value attached to a non-primary (cancer) estimate.
# Stdlib-only (python3).
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_claim_artifact.py"
MAN="$HERE/fixtures/claim_manuscript.md"
PRE="$HERE/fixtures/claim_prereg.md"
OUT="$(mktemp -t ca_XXXX).json"
trap 'rm -f "$OUT"' EXIT

fail=0
check() { local label="$1"; shift
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}
has_verdict() { python3 -c "
import json,sys
d=json.load(open('$OUT'))
assert any(c['verdict']=='$1' for c in d['claims']), '$1 not found'
"; }

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

python3 "$SCRIPT" --manuscript "$MAN" --prereg "$PRE" --out "$OUT" --strict >/dev/null 2>&1
check "exit 1 under --strict (Major present)" test "$?" -eq 1
check "JSON artifact written" test -s "$OUT"
check "PRIMARY_REASSIGNED detected"  has_verdict PRIMARY_REASSIGNED
check "EVALUE_ARITHMETIC detected (3.10 vs HR 1.52)" has_verdict EVALUE_ARITHMETIC
check "EVALUE_NON_PRIMARY detected (cancer sHR)"     has_verdict EVALUE_NON_PRIMARY

# Clean case: primary matches prereg, correct primary E-value, no reassignment.
CLEAN="$(mktemp -t ca_clean_XXXX).md"
trap 'rm -f "$OUT" "$CLEAN"' EXIT
cat > "$CLEAN" <<'EOF'
## Methods
The primary analysis was the association between emphysema and all-cause mortality
in the complete-case multivariable Cox model.
## Results
The E-value for the primary association (HR 1.52) was 2.41.
EOF
python3 "$SCRIPT" --manuscript "$CLEAN" --prereg "$PRE" --strict >/dev/null 2>&1
check "exit 0 on clean manuscript (matching primary, correct E-value)" test "$?" -eq 0

# Advisory case (less-defensive trim): a bare honest manuscript-stage disclosure —
# WITHOUT explicit re-designation/after-results language — is PRIMARY_DISCLOSURE_NOTE
# (advisory), NOT PRIMARY_REASSIGNED (Major). estimand-provenance guidance recommends
# writing this, so it must not fail --strict on its own.
DISC="$(mktemp -t ca_disc_XXXX).md"
trap 'rm -f "$OUT" "$CLEAN" "$DISC"' EXIT
cat > "$DISC" <<'EOF'
## Methods
The primary analysis was the association between emphysema and all-cause mortality
in the complete-case multivariable Cox model. Using the multiple-imputation model as
the estimation approach was a manuscript-stage analytical decision, disclosed here and
reported coequally with the pre-specified complete-case analysis.
## Results
The E-value for the primary association (HR 1.52) was 2.41.
EOF
python3 "$SCRIPT" --manuscript "$DISC" --prereg "$PRE" --out "$OUT" --strict >/dev/null 2>&1
check "exit 0 on honest manuscript-stage disclosure (advisory, not Major)" test "$?" -eq 0
check "PRIMARY_DISCLOSURE_NOTE emitted (advisory)" has_verdict PRIMARY_DISCLOSURE_NOTE
check "no PRIMARY_REASSIGNED on bare disclosure" python3 -c "
import json
d=json.load(open('$OUT'))
raise SystemExit(0 if not any(c['verdict']=='PRIMARY_REASSIGNED' for c in d['claims']) else 1)
"

# Structured-prereg anchor: a project.yaml with explicit primary_* keys + a
# manuscript whose primary is substantively consistent -> the estimand check anchors
# on the structured field VALUES (not a `# PRIMARY — locked` comment or a lexically
# dissimilar free-text paragraph) and does NOT allege ESTIMAND_DRIFT. Regression for
# the false Major at overlap 0.26 on a reconciled estimand.
SMAN="$HERE/fixtures/claim_manuscript_structured.md"
SPRE="$HERE/fixtures/claim_prereg_structured.md"
python3 "$SCRIPT" --manuscript "$SMAN" --prereg "$SPRE" --out "$OUT" >/dev/null 2>&1
check "no ESTIMAND_DRIFT on a structured, consistent prereg" python3 -c "
import json
d=json.load(open('$OUT'))
raise SystemExit(0 if not any(c['verdict']=='ESTIMAND_DRIFT' for c in d['claims']) else 1)
"
python3 "$SCRIPT" --manuscript "$SMAN" --prereg "$SPRE" --strict >/dev/null 2>&1
check "exit 0 on structured consistent prereg (no Major)" test "$?" -eq 0

# Code-label reconciliation (--scripts): a manuscript asserting a SINGLE primary vs an
# analysis script annotating a model 'co-primary' -> PRIMARY_LABEL_CODE_DRIFT (advisory,
# not Major). A consistent scripts dir and the no-flag backward-compatible default.
SP="$HERE/fixtures/claim_manuscript_single_primary.md"
python3 "$SCRIPT" --manuscript "$SP" --scripts "$HERE/fixtures/claim_scripts_coprimary" --out "$OUT" >/dev/null 2>&1
check "PRIMARY_LABEL_CODE_DRIFT on code co-primary vs single-primary manuscript" has_verdict PRIMARY_LABEL_CODE_DRIFT
python3 "$SCRIPT" --manuscript "$SP" --scripts "$HERE/fixtures/claim_scripts_coprimary" --strict >/dev/null 2>&1
check "code-label drift is advisory (exit 0 under --strict)" test "$?" -eq 0
python3 "$SCRIPT" --manuscript "$SP" --scripts "$HERE/fixtures/claim_scripts_consistent" --out "$OUT" >/dev/null 2>&1
check "no drift when scripts carry no co-primary label" python3 -c "
import json
d=json.load(open('$OUT'))
raise SystemExit(0 if not any(c['verdict']=='PRIMARY_LABEL_CODE_DRIFT' for c in d['claims']) else 1)
"

# Registration chronology (manuscript-internal, no --prereg needed): a
# "prospectively registered" claim whose registration date (16 Apr 2026) postdates
# search completion (31 Mar 2026) -> REGISTRATION_CHRONOLOGY (Major), exit 1.
RB="$HERE/fixtures/claim_registration_bad.md"
python3 "$SCRIPT" --manuscript "$RB" --out "$OUT" --strict >/dev/null 2>&1
check "exit 1 on retrospective registration under a prospective claim" test "$?" -eq 1
check "REGISTRATION_CHRONOLOGY detected" has_verdict REGISTRATION_CHRONOLOGY
# Silent when registration precedes search-end, and when no "prospective" claim is made.
RC="$HERE/fixtures/claim_registration_clean.md"
python3 "$SCRIPT" --manuscript "$RC" --strict >/dev/null 2>&1
check "exit 0 on genuinely-prospective + no-prospective-claim registrations" test "$?" -eq 0

# YAML front matter is not body prose. A project that honestly records "the primary
# endpoint was changed ..." in a `changelog:` block was handed PRIMARY_REASSIGNED — a P0 —
# for keeping a good record. The same sentence in the BODY is a real self-admission and
# must still fire, which is what makes the first assertion mean something.
FM="$HERE/fixtures/claim_frontmatter_changelog.md"
python3 "$SCRIPT" --manuscript "$FM" --out "$OUT" --strict >/dev/null 2>&1
check "a changelog in YAML front matter is not a self-admission" test "$?" -eq 0
check "...and no PRIMARY_REASSIGNED is recorded" python3 -c "
import json
d=json.load(open('$OUT'))
raise SystemExit(0 if not any(c['verdict']=='PRIMARY_REASSIGNED' for c in d['claims']) else 1)
"
BR="$HERE/fixtures/claim_body_reassign.md"
python3 "$SCRIPT" --manuscript "$BR" --out "$OUT" --strict >/dev/null 2>&1
check "the same sentence in the body still fires (P0 preserved)" test "$?" -eq 1
check "PRIMARY_REASSIGNED detected in body" has_verdict PRIMARY_REASSIGNED

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression test for the classical-style body lint (self-review §J).
# Synthetic, PII-free fixtures reproduce: a § symbol self-reference + an in-body
# AI-disclosure paragraph (both Major), eligibility prose, and mixed OR/HR decimals
# (Minor). The clean fixture uses a numbered eligibility list, consistent decimals,
# no § symbol, and no in-body disclosure.
# Stdlib-only (python3).
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_classical_style.py"
BAD="$HERE/fixtures/style_bad.md"
CLEAN="$HERE/fixtures/style_clean.md"
OUT="$(mktemp -t style_XXXX).json"
trap 'rm -f "$OUT"' EXIT

fail=0
check() { local label="$1"; shift
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}
has_verdict() { python3 -c "
import json,sys
d=json.load(open('$OUT'))
assert any(c['verdict']=='$1' for c in d['claims']), '$1 not found'
"; }

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

# (1) bad manuscript: Major (§ + in-body disclosure) -> exit 1
python3 "$SCRIPT" --manuscript "$BAD" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 under --strict (Major present)" test "$?" -eq 1
check "JSON artifact written" test -s "$OUT"
check "SECTION_SYMBOL detected"        has_verdict SECTION_SYMBOL
check "INBODY_AI_DISCLOSURE detected"  has_verdict INBODY_AI_DISCLOSURE
check "ELIGIBILITY_PROSE detected"     has_verdict ELIGIBILITY_PROSE
check "DECIMAL_INCONSISTENCY detected" has_verdict DECIMAL_INCONSISTENCY
check "PERCENT_DECIMALS detected (35.14%, 96.12%)" has_verdict PERCENT_DECIMALS

# (2) clean manuscript: numbered eligibility, consistent decimals, no §/disclosure,
#     no >1-dp percentages -> exit 0
python3 "$SCRIPT" --manuscript "$CLEAN" --strict --quiet >/dev/null 2>&1
check "exit 0 on clean manuscript" test "$?" -eq 0
python3 "$SCRIPT" --manuscript "$CLEAN" --out "$OUT" --quiet >/dev/null 2>&1
check "no PERCENT_DECIMALS false positive on clean manuscript" python3 -c "
import json
d=json.load(open('$OUT'))
assert not any(c['verdict']=='PERCENT_DECIMALS' for c in d['claims']), 'PERCENT_DECIMALS false positive'
"

# (3) structural em-dashes (table cells, ORCID, author/affiliation, panel labels)
#     must NOT count toward the prose threshold. With --em-dash-max 0, the fixture's
#     ~9 structural dashes are excluded and its prose has 0 → no EM_DASH_OVERUSE.
STRUCT="$HERE/fixtures/style_emdash_structural.md"
python3 "$SCRIPT" --manuscript "$STRUCT" --em-dash-max 0 --out "$OUT" --quiet >/dev/null 2>&1
check "structural em-dashes excluded (no EM_DASH_OVERUSE at max 0)" python3 -c "
import json
d=json.load(open('$OUT'))
assert not any(c['verdict']=='EM_DASH_OVERUSE' for c in d['claims']), 'structural dashes were counted as prose'
"

# (4) § used as author/affiliation footnote dagger (co-senior-author line, super-
#     script markers) must NOT fire SECTION_SYMBOL — only a § section cross-ref does.
DAGGER="$HERE/fixtures/style_dagger_footnote.md"
python3 "$SCRIPT" --manuscript "$DAGGER" --out "$OUT" --quiet >/dev/null 2>&1
check "no SECTION_SYMBOL on footnote daggers" python3 -c "
import json
d=json.load(open('$OUT'))
assert not any(c['verdict']=='SECTION_SYMBOL' for c in d['claims']), 'dagger § flagged as section symbol'
"
python3 "$SCRIPT" --manuscript "$DAGGER" --strict --quiet >/dev/null 2>&1
check "exit 0 on dagger-footnote manuscript" test "$?" -eq 0

# (5) a paper whose SUBJECT is AI-use disclosure carries disclosure phrasing as an
#     object of study, not as its own disclosure -> no INBODY_AI_DISCLOSURE.
METADOC="$HERE/fixtures/classical_metadoc.md"
python3 "$SCRIPT" --manuscript "$METADOC" --out "$OUT" --quiet >/dev/null 2>&1
check "no INBODY_AI_DISCLOSURE on an AI-disclosure-methods paper" python3 -c "
import json
d=json.load(open('$OUT'))
assert not any(c['verdict']=='INBODY_AI_DISCLOSURE' for c in d['claims']), 'meta-document flagged as in-body disclosure'
"
python3 "$SCRIPT" --manuscript "$METADOC" --strict --quiet >/dev/null 2>&1
check "exit 0 on AI-disclosure-methods paper" test "$?" -eq 0

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression test for the cohort-arithmetic gate (self-review Phase 2.5 / 2.5b).
# Synthetic, PII-free fixtures reproduce: (a) an incidence rate that does not
# recompute from its events/person-years, (b) a complete-case footnote that does
# not balance (total - missing != complete), (c) an ordinal tier partition whose
# stratum denominators and events sum above the stated total.
# Stdlib-only (python3).
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_cohort_arithmetic.py"
BAD="$HERE/fixtures/cohort_bad.md"
CLEAN="$HERE/fixtures/cohort_clean.md"
PART="$HERE/fixtures/cohort_partition.csv"
OUT="$(mktemp -t coh_XXXX).json"
trap 'rm -f "$OUT"' EXIT

fail=0
check() { local label="$1"; shift
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}
has_verdict() { python3 -c "
import json,sys
d=json.load(open('$OUT'))
assert any(c['verdict']=='$1' for c in d['claims']), '$1 not found'
"; }

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

# (1) bad manuscript: all three discrepancies, Major present -> exit 1 under --strict
python3 "$SCRIPT" --manuscript "$BAD" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 under --strict (Major present)" test "$?" -eq 1
check "JSON artifact written" test -s "$OUT"
check "RATE_BACKCALC detected (5.0 vs 120/50000*1000=2.4)" has_verdict RATE_BACKCALC
check "CASCADE_SUM detected (4252-583=3669 != 3667)"       has_verdict CASCADE_SUM
check "PARTITION_OVERLAP detected (sum 12498 != 12019)"     has_verdict PARTITION_OVERLAP

# (2) clean manuscript: everything balances -> exit 0
python3 "$SCRIPT" --manuscript "$CLEAN" --strict --quiet >/dev/null 2>&1
check "exit 0 on clean manuscript (all arithmetic balances)" test "$?" -eq 0

# (3) --data CSV partition: stratum n sum above total -> PARTITION_OVERLAP, exit 1
python3 "$SCRIPT" --manuscript "$CLEAN" --data "$PART" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 with overlapping --data partition CSV" test "$?" -eq 1
check "PARTITION_OVERLAP from --data CSV" has_verdict PARTITION_OVERLAP

# (4) analysis-unit: 10 records / 7 subjects + manuscript that discloses neither
#     the analysis unit nor a one-record-per-subject sensitivity -> ANALYSIS_UNIT_
#     UNDISCLOSED (auto-detected 'mockid' column), exit 1.
REPEAT="$HERE/fixtures/cohort_repeat_subjects.csv"
UNDISC="$HERE/fixtures/cohort_unit_undisclosed.md"
DISC="$HERE/fixtures/cohort_unit_disclosed.md"
python3 "$SCRIPT" --manuscript "$UNDISC" --data "$REPEAT" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 (analysis unit undisclosed, auto-detect)" test "$?" -eq 1
check "ANALYSIS_UNIT_UNDISCLOSED detected" has_verdict ANALYSIS_UNIT_UNDISCLOSED
check "reconciliation reports 7 unique subjects" python3 -c "
import json
d=json.load(open('$OUT'))
c=next(c for c in d['claims'] if c['verdict']=='ANALYSIS_UNIT_UNDISCLOSED')
assert 'unique_subjects=7' in c['detail'] and 'max_visits=3' in c['detail'], c['detail']
"

# (5) explicit --id-col also fires
python3 "$SCRIPT" --manuscript "$UNDISC" --data "$REPEAT" --id-col mockid --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 (analysis unit, explicit --id-col)" test "$?" -eq 1

# (6) disclosed manuscript (states analysis unit + first-visit sensitivity) -> no fire
python3 "$SCRIPT" --manuscript "$DISC" --data "$REPEAT" --strict --quiet >/dev/null 2>&1
check "exit 0 when analysis unit disclosed" test "$?" -eq 0

# (7) a tier label ("stratum 1") and "incident rate" sitting near a small integer
#     must NOT mis-bind the numerator: the rate recomputes from 882 events /
#     35,581 PY -> NO RATE_BACKCALC false positive, exit 0 (regression).
RFP="$HERE/fixtures/cohort_rate_tier_fp.md"
python3 "$SCRIPT" --manuscript "$RFP" --out "$OUT" --quiet >/dev/null 2>&1
check "no RATE_BACKCALC false positive (tier + incident-rate)" python3 -c "
import json
d=json.load(open('$OUT'))
assert not any(c['verdict']=='RATE_BACKCALC' for c in d['claims']), 'numerator mis-bound -> false RATE_BACKCALC'
"
python3 "$SCRIPT" --manuscript "$RFP" --strict --quiet >/dev/null 2>&1
check "exit 0 on correct-rate manuscript" test "$?" -eq 0

# (8) PROSE partition: an in-text exhaustive split whose counts do not sum to the
#     stated total (37 + 185 + 103 = 325 != 289, % = 112.4) -> PARTITION_OVERLAP,
#     exit 1.
PPROSE="$HERE/fixtures/cohort_partition_prose.md"
python3 "$SCRIPT" --manuscript "$PPROSE" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 on prose partition that does not reconcile" test "$?" -eq 1
check "PARTITION_OVERLAP from prose enumeration"          has_verdict PARTITION_OVERLAP

# (9) PRECISION: the corrected split (37+149+103=289, %=100), a no-% cross-tab,
#     and an overlapping-comorbidity enumeration WITH %s but no partition cue must
#     all stay silent -> exit 0. The last is the case a naive count-sum check
#     would false-fire on.
PPCLEAN="$HERE/fixtures/cohort_partition_prose_clean.md"
python3 "$SCRIPT" --manuscript "$PPCLEAN" --strict --quiet >/dev/null 2>&1
check "exit 0 on corrected + cross-tab + cue-less overlapping prose" test "$?" -eq 0

# (10) FOLLOWUP_VS_CRITERION: reported "median follow-up 102 days" against a ">= 24
#      months stability" criterion with no total-observation window -> Minor flag.
FUC="$HERE/fixtures/cohort_followup_criterion.md"
python3 "$SCRIPT" --manuscript "$FUC" --out "$OUT" --quiet >/dev/null 2>&1
check "FOLLOWUP_VS_CRITERION when follow-up < a criterion duration" has_verdict FOLLOWUP_VS_CRITERION
# (11) silent once the total-observation window is distinctly reported.
FUOK="$HERE/fixtures/cohort_followup_ok.md"
python3 "$SCRIPT" --manuscript "$FUOK" --out "$OUT" --quiet >/dev/null 2>&1
check "no FOLLOWUP_VS_CRITERION when total observation window is reported" python3 -c "
import json
d=json.load(open('$OUT'))
raise SystemExit(0 if not any(c['verdict']=='FOLLOWUP_VS_CRITERION' for c in d['claims']) else 1)
"

# (N) a subgroup rendered twice with divergent CIs: two rows share the SAME estimate AND
#     identical n/events but print different confidence intervals (independent bootstraps)
#     -> SUBGROUP_DUPLICATE_CI (Minor). Two DISTINCT subgroups with a coincidentally equal
#     estimate but different n/events must NOT fire (the precision guard).
DUPCI="$HERE/fixtures/cohort_dup_ci.md"
DUPCICLEAN="$HERE/fixtures/cohort_dup_ci_clean.md"
python3 "$SCRIPT" --manuscript "$DUPCI" --out "$OUT" --quiet >/dev/null 2>&1
check "SUBGROUP_DUPLICATE_CI on same estimate+n+events with divergent CI" has_verdict SUBGROUP_DUPLICATE_CI
python3 "$SCRIPT" --manuscript "$DUPCICLEAN" --out "$OUT" --quiet >/dev/null 2>&1
check "no SUBGROUP_DUPLICATE_CI when n/events differ (distinct subgroups, same OR)" python3 -c "
import json
d=json.load(open('$OUT'))
raise SystemExit(0 if not any(c['verdict']=='SUBGROUP_DUPLICATE_CI' for c in d['claims']) else 1)
"

# (N) nested prediction models all embedding a common covariate set (age + sex) report a
#     C-index but there is no base-model (age+sex-only) row and no incremental deltaC ->
#     NESTED_MODEL_NO_BASELINE (Minor). Adding the base-model row must suppress it.
NEST="$HERE/fixtures/cohort_nested_models.md"
NESTBASE="$HERE/fixtures/cohort_nested_models_base.md"
python3 "$SCRIPT" --manuscript "$NEST" --out "$OUT" --quiet >/dev/null 2>&1
check "NESTED_MODEL_NO_BASELINE when nested models share covariates with no base row" has_verdict NESTED_MODEL_NO_BASELINE
python3 "$SCRIPT" --manuscript "$NESTBASE" --out "$OUT" --quiet >/dev/null 2>&1
check "no NESTED_MODEL_NO_BASELINE when the base-model (age+sex) row is present" python3 -c "
import json
d=json.load(open('$OUT'))
raise SystemExit(0 if not any(c['verdict']=='NESTED_MODEL_NO_BASELINE' for c in d['claims']) else 1)
"

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# NOTE: `findings` is the DEFECT list (UNADJUSTED_IMBALANCED only); the full per-covariate
# audit table — including the ADJUSTED and EXPOSURE_DEFINING_EXEMPT status rows — is
# `covariates`. Assertions about whether a covariate was RESOLVED or EXEMPT read
# `covariates`; assertions about defects read `findings`. See confounding_findings_challenge.
# Regression test for the confounding-completeness gate (self-review Phase 2.5e).
# Synthetic, PII-free fixture mirroring the canonical failure pattern: five
# measured covariates imbalanced by exposure (uric acid, pack-years, HDL, total
# cholesterol, HbA1c) that are absent from an age/sex/BMI/HTN/DM adjustment set.
# Stdlib-only (python3); no pandas/statsmodels.
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_confounding_completeness.py"
FIXTURE="$HERE/fixtures/table1_by_exposure.csv"
OUT="$(mktemp -t cc_XXXX).json"
trap 'rm -f "$OUT"' EXIT

fail=0
ran=0
check() {  # check "label" expr...
    local label="$1"; shift
    ran=$((ran+1))
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}

[[ -f "$SCRIPT" ]]  || { echo "ENV-ERR: script missing"  >&2; exit 2; }
[[ -f "$FIXTURE" ]] || { echo "ENV-ERR: fixture missing" >&2; exit 2; }

# 1. Runs and writes JSON.
python3 "$SCRIPT" --table1 "$FIXTURE" \
    --adjusted-list "age, sex, BMI, hypertension, diabetes" \
    --out "$OUT" --strict >/dev/null 2>&1
rc=$?
check "exit 1 under --strict (unadjusted-imbalanced present)" test "$rc" -eq 1
check "JSON artifact written" test -s "$OUT"

# 2. Exactly five unadjusted-imbalanced covariates.
n=$(python3 -c "import json,sys; print(json.load(open('$OUT'))['n_unadjusted_imbalanced'])" 2>/dev/null)
check "n_unadjusted_imbalanced == 5" test "$n" = "5"

# 3. Each expected offender flagged; adjusted/balanced ones not.
for cov in "Uric acid" "Smoking, pack-years" "HDL" "Total cholesterol" "HbA1c"; do
    check "flagged: $cov" python3 -c "
import json
d=json.load(open('$OUT'))
assert any('$cov'.lower() in f['covariate'].lower() and f['verdict']=='UNADJUSTED_IMBALANCED' for f in d['findings'])
"
done
for cov in "Age" "BMI"; do
    check "not flagged: $cov" python3 -c "
import json
d=json.load(open('$OUT'))
assert not any('$cov'.lower() in f['covariate'].lower() and f['verdict']=='UNADJUSTED_IMBALANCED' for f in d['findings'])
"
done

# 4. '<0.001' p-value cell parsed as imbalanced (HDL row uses '<0.001').
check "verdict MAJOR_CANDIDATE" python3 -c "
import json; assert json.load(open('$OUT'))['verdict']=='MAJOR_CANDIDATE'
"

# 5. Clean case: adjusting for everything yields exit 0.
python3 "$SCRIPT" --table1 "$FIXTURE" \
    --adjusted-list "age, sex, BMI, hypertension, diabetes, uric acid, smoking, HDL, total cholesterol, HbA1c" \
    --strict >/dev/null 2>&1
check "exit 0 when all imbalanced covariates adjusted" test "$?" -eq 0

# 6. DB-code Table 1 + prose adjustment list: the alias map must resolve he_sbp ~
#    "systolic blood pressure" etc., so adjusted DB-code covariates are NOT
#    false-flagged; only the genuinely unadjusted ones (alcohol/waist/hemoglobin/
#    fasting glucose) remain ✗.
DBFIX="$HERE/fixtures/table1_by_exposure_dbcodes.csv"
[[ -f "$DBFIX" ]] || { echo "ENV-ERR: db-code fixture missing" >&2; exit 2; }
DBOUT="$(mktemp -t cc_db_XXXX).json"
trap 'rm -f "$OUT" "$DBOUT"' EXIT
python3 "$SCRIPT" --table1 "$DBFIX" \
    --adjusted-list "age, sex, body mass index, systolic blood pressure, diastolic blood pressure, total cholesterol, HDL cholesterol, triglycerides, uric acid, HbA1c" \
    --out "$DBOUT" --strict >/dev/null 2>&1
check "exit 1 (db-code: genuine unadjusted present)" test "$?" -eq 1
ndb=$(python3 -c "import json; print(json.load(open('$DBOUT'))['n_unadjusted_imbalanced'])" 2>/dev/null)
check "db-code: n_unadjusted_imbalanced == 4" test "$ndb" = "4"
for cov in he_sbp he_dbp b_chol_t b_chol_hdl b_tg b_uric b_hba1c he_bmi; do
    check "db-code adjusted (alias resolved): $cov" python3 -c "
import json
d=json.load(open('$DBOUT'))
assert any(f['covariate']=='$cov' and f['in_adjustment_set'] for f in d['covariates']), '$cov not resolved'
"
done
for cov in alc he_wc he_hb he_glu; do
    check "db-code unadjusted: $cov" python3 -c "
import json
d=json.load(open('$DBOUT'))
assert any(f['covariate']=='$cov' and f['verdict']=='UNADJUSTED_IMBALANCED' for f in d['findings']), '$cov should flag'
"
done

# 7. A3 — wide Table 1 with mean±SD group columns and NO p/SMD column: the gate
#    computes SMD itself and still runs. With only 'age' adjusted, the imbalanced
#    metabolic labs flag.
MSFIX="$HERE/fixtures/table1_meansd_wide.csv"
[[ -f "$MSFIX" ]] || { echo "ENV-ERR: mean±SD fixture missing" >&2; exit 2; }
MSOUT="$(mktemp -t cc_ms_XXXX).json"
trap 'rm -f "$OUT" "$DBOUT" "$MSOUT"' EXIT
python3 "$SCRIPT" --table1 "$MSFIX" --adjusted-list "age" --out "$MSOUT" --strict >/dev/null 2>&1
check "exit 1 (mean±SD: SMD computed, imbalanced present)" test "$?" -eq 1
check "smd_source == computed_from_mean_sd" python3 -c "
import json; assert json.load(open('$MSOUT'))['smd_source']=='computed_from_mean_sd'"
check "mean±SD: n_unadjusted_imbalanced == 5" python3 -c "
import json; assert json.load(open('$MSOUT'))['n_unadjusted_imbalanced']==5"
check "age (SMD<0.1) not flagged" python3 -c "
import json
d=json.load(open('$MSOUT'))
assert not any(f['covariate']=='age' for f in d['findings'])"

# 8. A4 — exposure-defining covariates (the exposure's diagnostic criteria) are
#    exempt from the residual-confounding flag; only the non-defining prognostic
#    covariate (fib-4) remains a Major.
python3 "$SCRIPT" --table1 "$MSFIX" --adjusted-list "age" \
    --exposure-defining-list "body mass index, systolic blood pressure, HbA1c, HDL cholesterol" \
    --out "$MSOUT" --strict >/dev/null 2>&1
check "exit 1 (A4: non-defining fib-4 still flags)" test "$?" -eq 1
check "A4: 4 exposure-defining exempt" python3 -c "
import json; assert json.load(open('$MSOUT'))['n_exposure_defining_exempt']==4"
check "A4: only 1 unadjusted-imbalanced (fib-4)" python3 -c "
import json
d=json.load(open('$MSOUT'))
assert d['n_unadjusted_imbalanced']==1
assert any(f['covariate']=='fib-4' and f['verdict']=='UNADJUSTED_IMBALANCED' for f in d['findings'])"
check "A4: defining covariate not a Major" python3 -c "
import json
d=json.load(open('$MSOUT'))
assert any(f['verdict']=='EXPOSURE_DEFINING_EXEMPT' for f in d['covariates'] if 'body mass' in f['covariate'])
assert not any('body mass' in f['covariate'] for f in d['findings'])"

# 9. A4 + adjust the non-defining prognostic covariate -> clean (exit 0)
python3 "$SCRIPT" --table1 "$MSFIX" --adjusted-list "age, FIB-4" \
    --exposure-defining-list "body mass index, systolic blood pressure, HbA1c, HDL cholesterol" \
    --strict >/dev/null 2>&1
check "exit 0 when defining exempt + non-defining adjusted" test "$?" -eq 0

echo "ran=$ran fail=$fail"
[[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression test for the feature-selection-outside-CV leakage gate.
# (bad) log-odds feature selection on the full dataset + 5-fold CV, no nesting ->
# CV_SELECTION_LEAKAGE; (clean) selection repeated within each training fold (nested
# CV) -> no flag.
set -u
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_cv_leakage.py"
BAD="$HERE/fixtures/cv_leakage_bad.md"
CLEAN="$HERE/fixtures/cv_leakage_clean.md"
OUT="$(mktemp -t cvl_XXXX).json"
trap 'rm -f "$OUT"' EXIT
fail=0
check() { local label="$1"; shift
  if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
  else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi; }
[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

python3 "$SCRIPT" --manuscript "$BAD" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 under --strict (Major present)" test "$?" -eq 1
check "CV_SELECTION_LEAKAGE on selection+CV without nesting" python3 -c "
import json
d=json.load(open('$OUT'))
assert any(c['verdict']=='CV_SELECTION_LEAKAGE' for c in d['claims']), 'not flagged'
"
python3 "$SCRIPT" --manuscript "$CLEAN" --strict --quiet >/dev/null 2>&1
check "exit 0 when selection is nested within each fold" test "$?" -eq 0
python3 "$SCRIPT" --manuscript "$CLEAN" --out "$OUT" --quiet >/dev/null 2>&1
check "no leakage flag on nested CV" python3 -c "
import json
d=json.load(open('$OUT'))
assert not d['claims'], d['claims']
"
echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression test for the editorial-impression / defensiveness gate (self-review §L).
# Synthetic, PII-free fixtures: (a) an over-defensive manuscript that trips all six
# probes (HEDGE_DENSITY, HEDGE_REPEAT, AUDIT_IN_BODY, LIMITATIONS_VOLUME,
# ABSTRACT_CAVEAT_LOAD, BURIED_DEFENSE); (b) a confident clean manuscript that trips
# none (false-positive guard). The gate is advisory and non-blocking — it must exit 0
# even under --strict, since it emits no Major.
# Stdlib-only (python3).
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_editorial_impression.py"
DEF="$HERE/fixtures/editorial_defensive.md"
CLEAN="$HERE/fixtures/editorial_clean.md"
OUT="$(mktemp -t editorial_XXXX).json"
trap 'rm -f "$OUT"' EXIT

fail=0
check() { local label="$1"; shift
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}
has_verdict() { python3 -c "
import json
d=json.load(open('$OUT'))
assert any(c['verdict']=='$1' for c in d['claims']), '$1 not found'
"; }

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

# (1) defensive fixture -> all six verdicts fire
python3 "$SCRIPT" --manuscript "$DEF" --out "$OUT" --quiet >/dev/null 2>&1
for v in HEDGE_DENSITY HEDGE_REPEAT AUDIT_IN_BODY LIMITATIONS_VOLUME ABSTRACT_CAVEAT_LOAD BURIED_DEFENSE; do
    check "$v detected (defensive)" has_verdict "$v"
done

# (2) every claim carries a SUBTRACTION action in {REMOVE, MOVE, TIGHTEN}
check "every claim has a REMOVE/MOVE/TIGHTEN action" python3 -c "
import json
d=json.load(open('$OUT'))
assert d['claims'], 'expected findings'
assert all(c.get('action') in ('REMOVE','MOVE','TIGHTEN') for c in d['claims']), 'bad action'
assert all(c.get('severity')=='Minor' for c in d['claims']), 'all findings must be Minor (advisory)'
"

# (3) advisory / non-blocking: exit 0 even under --strict on a fully-flagged manuscript
python3 "$SCRIPT" --manuscript "$DEF" --strict --quiet >/dev/null 2>&1
check "exit 0 under --strict (non-blocking)" test "$?" -eq 0

# (4) clean fixture -> zero claims (false-positive guard)
python3 "$SCRIPT" --manuscript "$CLEAN" --out "$OUT" --quiet >/dev/null 2>&1
check "clean manuscript yields no flags" python3 -c "
import json
d=json.load(open('$OUT'))
assert d['summary']['n_claims']==0, d['claims']
"
python3 "$SCRIPT" --manuscript "$CLEAN" --strict --quiet >/dev/null 2>&1
check "exit 0 on clean manuscript" test "$?" -eq 0

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression test for the inline-emphasis over-use gate (§J / humanize P25).
# (overuse) a paragraph with single-word + whole-clause italics -> EMPHASIS_OVERUSE;
# (clean) only allowlisted italics (P value, in vitro/in vivo, BRCA1, t) -> no flag.
set -u
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_emphasis_density.py"
BAD="$HERE/fixtures/emphasis_overuse.md"
CLEAN="$HERE/fixtures/emphasis_clean.md"
OUT="$(mktemp -t emph_XXXX).json"
trap 'rm -f "$OUT"' EXIT
fail=0
check() { local label="$1"; shift
  if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
  else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi; }
[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

python3 "$SCRIPT" --manuscript "$BAD" --out "$OUT" --quiet >/dev/null 2>&1
check "EMPHASIS_OVERUSE on over-italicised prose" python3 -c "
import json
d=json.load(open('$OUT'))
assert any(c['verdict']=='EMPHASIS_OVERUSE' for c in d['claims']), 'not flagged'
"
python3 "$SCRIPT" --manuscript "$CLEAN" --out "$OUT" --quiet >/dev/null 2>&1
check "no flag when only allowlisted italics (P/in vitro/BRCA1/t)" python3 -c "
import json
d=json.load(open('$OUT'))
assert not d['claims'], d['claims']
"
echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression test for the orphan figure/table gate (Phase 2.5d).
# (orphan) Figure 3 and Table 2 have captions but no in-text citation -> flagged;
# (clean) every captioned float is cited in the body -> no flag.
set -u
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_figure_citation.py"
ORPHAN="$HERE/fixtures/figure_orphan.md"
CLEAN="$HERE/fixtures/figure_clean.md"
OUT="$(mktemp -t figcite_XXXX).json"
trap 'rm -f "$OUT"' EXIT
fail=0
check() { local label="$1"; shift
  if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
  else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi; }
has_verdict() { python3 -c "
import json
d=json.load(open('$OUT'))
assert any(c['verdict']=='$1' for c in d['claims']), '$1 not found'
"; }
[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

python3 "$SCRIPT" --manuscript "$ORPHAN" --out "$OUT" --quiet >/dev/null 2>&1
check "FIGURE_ORPHAN on uncited Figure 3" has_verdict FIGURE_ORPHAN
check "TABLE_ORPHAN on uncited Table 2"   has_verdict TABLE_ORPHAN
check "no orphan for cited Figure 1 / Table 1" python3 -c "
import json
d=json.load(open('$OUT'))
orphans={(c['verdict'], c['detail'].split(' has')[0]) for c in d['claims']}
assert ('FIGURE_ORPHAN','Figure 1') not in orphans and ('TABLE_ORPHAN','Table 1') not in orphans
"
python3 "$SCRIPT" --manuscript "$CLEAN" --out "$OUT" --quiet >/dev/null 2>&1
check "no orphans/embed flags when every float is cited AND embedded" python3 -c "
import json
d=json.load(open('$OUT'))
assert not d['claims'], d['claims']
"

# FIGURE_NOT_EMBEDDED: captions present, cited, but no image link anywhere.
NE="$HERE/fixtures/figcite_not_embedded.md"
python3 "$SCRIPT" --manuscript "$NE" --out "$OUT" --quiet >/dev/null 2>&1
check "FIGURE_NOT_EMBEDDED when no image is embedded" has_verdict FIGURE_NOT_EMBEDDED
# advisory (Minor) by default -> exit 0 even under --strict
python3 "$SCRIPT" --manuscript "$NE" --strict --quiet >/dev/null 2>&1
check "advisory Minor by default (exit 0 under --strict)" test "$?" -eq 0
# submission context: --require-embedded escalates to Major -> exit 1 under --strict
python3 "$SCRIPT" --manuscript "$NE" --require-embedded --strict --quiet >/dev/null 2>&1
check "Major under --require-embedded (exit 1 under --strict)" test "$?" -eq 1
# a manuscript that embeds its figures stays silent
EMB="$HERE/fixtures/figcite_embedded.md"
python3 "$SCRIPT" --manuscript "$EMB" --require-embedded --strict --quiet >/dev/null 2>&1
check "silent when figures are embedded (even --require-embedded)" test "$?" -eq 0

# FIGURE_ATTR_STALE: Author Contributions attributes "Figure 4" but only 1-3 declared.
CB="$HERE/fixtures/figcite_credit_bad.md"
python3 "$SCRIPT" --manuscript "$CB" --out "$OUT" --quiet >/dev/null 2>&1
check "FIGURE_ATTR_STALE on a CRediT attribution to a nonexistent figure" has_verdict FIGURE_ATTR_STALE
python3 "$SCRIPT" --manuscript "$CB" --strict --quiet >/dev/null 2>&1
check "stale figure attribution is Major (exit 1 under --strict)" test "$?" -eq 1
# canonical CRediT roles (no figure numbers) -> silent
CO="$HERE/fixtures/figcite_credit_ok.md"
python3 "$SCRIPT" --manuscript "$CO" --strict --quiet >/dev/null 2>&1
check "exit 0 when CRediT uses canonical roles (no figure numbers)" test "$?" -eq 0

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression test: the summary line must name the defect it found, and a document-level fact must be
# stated once.
#
# `check_figure_citation` emits five verdicts, only two of which are orphans. Its summary line
# counted by SEVERITY and printed the result as a KIND:
#
#     REVIEW: 3 orphan float(s).
#
# — on the repository's own `demo/01_wisconsin_bc`, where the orphan count is zero and all three
# findings were FIGURE_NOT_EMBEDDED. A reader is told to go looking for uncited floats that do not
# exist.
#
# And FIGURE_NOT_EMBEDDED was emitted once per caption while its condition is document-level
# (`not IMG_LINK_RE.search(text)` — true or false for the whole file, never per figure). Three
# figures produced three claims of one fact; across the three demo manuscripts, 8 claims for 3
# documents, inflating every count downstream that treats a claim as a finding.
#
# Evidence for this fix comes from `demo/` only. `_corpus/heldout/` was not read — see CLAUDE.md.
set -u

REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
D="$REPO_ROOT/skills/self-review/scripts/check_figure_citation.py"
WORK="$(mktemp -d -t figcite_test.XXXXXX)"
trap 'rm -rf "$WORK"' EXIT

pass=0
fail=0
ck() {
  local label="$1" expected="$2" actual="$3"
  if [ "$expected" = "$actual" ]; then
    printf '  PASS  %-50s %s\n' "$label" "$actual"
    pass=$((pass + 1))
  else
    printf '  FAIL  %-50s expected=%s actual=%s\n' "$label" "$expected" "$actual"
    fail=$((fail + 1))
  fi
}

# --- fixtures ------------------------------------------------------------------------------------
# Captioned and cited, but the manuscript embeds no image at all.
cat > "$WORK/not_embedded.md" <<'EOF'
## Results

Enrolment is shown in Figure 1, survival in Figure 2 and calibration in Figure 3.

**Figure 1.** Study flow diagram.

**Figure 2.** Kaplan-Meier survival curves.

**Figure 3.** Calibration plot.
EOF

# A genuine orphan: Figure 2 is captioned and never cited. An image IS embedded, so the
# not-embedded branch stays silent and the orphan branch is the only thing left.
cat > "$WORK/orphan.md" <<'EOF'
## Results

Enrolment is shown in Figure 1.

**Figure 1.** Study flow diagram.

![flow](figures/flow.png)

**Figure 2.** A figure nobody mentions.
EOF

# Clean: captioned, cited, embedded.
cat > "$WORK/clean.md" <<'EOF'
## Results

Enrolment is shown in Figure 1.

**Figure 1.** Study flow diagram.

![flow](figures/flow.png)
EOF

summary_line() { python3 "$D" --manuscript "$WORK/$1" 2>/dev/null | tail -1; }
jq_field() {  # jq_field <fixture> <summary key>
  python3 "$D" --manuscript "$WORK/$1" --out "$WORK/$1.json" --quiet >/dev/null 2>&1
  python3 -c "import json,sys; print(json.load(open(sys.argv[1]))['summary'][sys.argv[2]])" \
    "$WORK/$1.json" "$2"
}

echo "==== the summary line must not report orphans that are not there ===="
ck "no 'orphan' in the not-embedded summary" no \
   "$(summary_line not_embedded.md | grep -qi orphan && echo yes || echo no)"
ck "it names what it did find" yes \
   "$(summary_line not_embedded.md | grep -qi 'no image embedded' && echo yes || echo no)"
ck "n_orphan is 0"        0 "$(jq_field not_embedded.md n_orphan)"
ck "n_not_embedded is 1"  1 "$(jq_field not_embedded.md n_not_embedded)"

echo "==== a document-level fact is stated once, and names every figure ===="
ck "3 captioned figures -> 1 claim" 1 "$(jq_field not_embedded.md n_claims)"
for n in 1 2 3; do
  ck "  claim names Figure $n" yes \
     "$(python3 -c "
import json,sys
d=json.load(open(sys.argv[1]))
print('yes' if 'Figure $n' in d['claims'][0]['detail'] else 'no')" "$WORK/not_embedded.md.json")"
done

echo "==== NEGATIVE CONTROLS — a real orphan is still an orphan ===="
ck "orphan fixture: n_orphan is 1"          1 "$(jq_field orphan.md n_orphan)"
ck "orphan fixture: summary says 'orphan'"  yes \
   "$(summary_line orphan.md | grep -qi 'orphan float' && echo yes || echo no)"
ck "orphan fixture: not_embedded is 0"      0 "$(jq_field orphan.md n_not_embedded)"
ck "clean manuscript: no claims"            0 "$(jq_field clean.md n_claims)"
ck "clean manuscript: says OK"              yes \
   "$(summary_line clean.md | grep -q '^OK:' && echo yes || echo no)"

echo "==== the documented exit contract is real: Major IS reachable ===="
python3 "$D" --manuscript "$WORK/not_embedded.md" --require-embedded --strict >/dev/null 2>&1
ck "--require-embedded --strict exits 1"    1 "$?"
python3 "$D" --manuscript "$WORK/not_embedded.md" --strict >/dev/null 2>&1
ck "without --require-embedded it exits 0"  0 "$?"

echo
echo "  passed=$pass failed=$fail"
[ "$fail" -eq 0 ] || exit 1
echo "OK: the summary names the defect it found, and one fact is stated once."

#!/usr/bin/env bash
# Regression test for the null-calibration gate (self-review §C).
# Synthetic, PII-free fixtures: (a) a headline "no synergy / not associated" null
# in the Abstract + Conclusion with no MDE/power/equivalence/CI-compatibility
# statement (CONFIRM_NULL_NO_MDE), (b) the same null but accompanied by a power
# calculation + CI-compatibility sentence (suppressed).
# Stdlib-only (python3).
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_null_calibration.py"
BAD="$HERE/fixtures/null_bad.md"
CLEAN="$HERE/fixtures/null_clean.md"
OUT="$(mktemp -t nullcal_XXXX).json"
trap 'rm -f "$OUT"' EXIT

fail=0
check() { local label="$1"; shift
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}
has_verdict() { python3 -c "
import json,sys
d=json.load(open('$OUT'))
assert any(c['verdict']=='$1' for c in d['claims']), '$1 not found'
"; }

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

# (1) headline null with no precision statement -> CONFIRM_NULL_NO_MDE, exit 1
python3 "$SCRIPT" --manuscript "$BAD" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 under --strict (Major present)" test "$?" -eq 1
check "JSON artifact written" test -s "$OUT"
check "CONFIRM_NULL_NO_MDE detected" has_verdict CONFIRM_NULL_NO_MDE

# (2) same null but with power + CI-compatibility -> suppressed, exit 0
python3 "$SCRIPT" --manuscript "$CLEAN" --out "$OUT" --quiet >/dev/null 2>&1
check "no CONFIRM_NULL_NO_MDE when precision present" python3 -c "
import json
d=json.load(open('$OUT'))
assert not any(c['verdict']=='CONFIRM_NULL_NO_MDE' for c in d['claims']), 'fired despite a precision statement'
"
python3 "$SCRIPT" --manuscript "$CLEAN" --strict --quiet >/dev/null 2>&1
check "exit 0 on power-aware null" test "$?" -eq 0

# (3) region-blind masking: a power/CI caveat co-located with the Abstract-Results
#     null does NOT license a bare "equivalence within the bound" in a far
#     Conclusion -> CONFIRM_NULL_NO_MDE still fires on the uncaveated claim site.
MASKED="$HERE/fixtures/null_region_masked.md"
python3 "$SCRIPT" --manuscript "$MASKED" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1: masked equivalence in a far Conclusion still flagged" test "$?" -eq 1
check "CONFIRM_NULL_NO_MDE on the uncaveated claim site" has_verdict CONFIRM_NULL_NO_MDE

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression test for the panel lens-diversity gate (self-review Phase 2.6).
# Synthetic, PII-free reviewer-output fixtures reproduce: (a) a healthy panel
# spanning three distinct axes (clean), (b) a monoculture where every major
# falls in one family AND two expected axes are uncovered (UNCOVERED_AXIS +
# FAMILY_MONOCULTURE), (c) a fully-redundant reviewer lens (LENS_COLLAPSE).
# Stdlib-only (python3).
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_panel_diversity.py"
GOOD="$HERE/fixtures/panel_good.json"
MONO="$HERE/fixtures/panel_monoculture.json"
COLLAPSE="$HERE/fixtures/panel_collapse.json"
STATS="$HERE/fixtures/panel_stats_lens.json"
ONE="$HERE/fixtures/panel_one_returned.json"
ROSTER4="$HERE/fixtures/roster_4.json"
ROSTER3="$HERE/fixtures/roster_3.json"
MONOSUB="$HERE/fixtures/roster_mono_substrate.json"
INDEPSUB="$HERE/fixtures/roster_indep_substrate.json"
OUT="$(mktemp -t paneldiv_XXXX).json"
trap 'rm -f "$OUT"' EXIT

fail=0
check() { local label="$1"; shift
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}
has_verdict() { python3 -c "
import json,sys
d=json.load(open('$OUT'))
assert any(c['verdict']=='$1' for c in d['claims']), '$1 not found'
"; }
no_verdict() { python3 -c "
import json,sys
d=json.load(open('$OUT'))
assert all(c['verdict']!='$1' for c in d['claims']), '$1 unexpectedly found'
"; }

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

# (1) healthy diverse panel (sr_ma) -> exit 0, no Major claims
python3 "$SCRIPT" --panel "$GOOD" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 0 (diverse panel)" test "$?" -eq 0
check "no UNCOVERED_AXIS on clean panel" no_verdict UNCOVERED_AXIS
check "no FAMILY_MONOCULTURE on clean panel" no_verdict FAMILY_MONOCULTURE

# (2) monoculture + uncovered axes -> exit 1 with both Major verdicts
python3 "$SCRIPT" --panel "$MONO" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 (monoculture)" test "$?" -eq 1
check "UNCOVERED_AXIS detected" has_verdict UNCOVERED_AXIS
check "FAMILY_MONOCULTURE detected" has_verdict FAMILY_MONOCULTURE

# (3) fully-redundant reviewer (no research type) -> LENS_COLLAPSE flag, exit 0
python3 "$SCRIPT" --panel "$COLLAPSE" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 0 (collapse is flag-only)" test "$?" -eq 0
check "LENS_COLLAPSE detected" has_verdict LENS_COLLAPSE
check "no UNCOVERED_AXIS without research type" no_verdict UNCOVERED_AXIS

# (4) a statistics reviewer using reader-study / agreement vocabulary (kappa, bootstrap,
#     permutation, odds ratio, ICC) must register as covering the 'statistics' axis, so an
#     sr_ma panel spanning all three expected axes fires NO UNCOVERED_AXIS. Regression:
#     before the statistics lexicon was broadened these classified as 'other' and the axis
#     looked uncovered, producing a false Major.
python3 "$SCRIPT" --panel "$STATS" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 0 (stats reviewer covers the statistics axis)" test "$?" -eq 0
check "no UNCOVERED_AXIS when statistics is covered by reader-study vocabulary" no_verdict UNCOVERED_AXIS

# (5) roster of 4 spawned reviewers, only 1 returned -> PANEL_UNDERRETURN (Major), exit 1.
#     The failure this exists for: reviewers spawn, return nothing, and the thin/empty panel
#     JSON reads as a completed run because nothing errors. The roster makes the absence visible.
python3 "$SCRIPT" --panel "$ONE" --roster "$ROSTER4" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 (1 of 4 rostered reviewers returned)" test "$?" -eq 1
check "PANEL_UNDERRETURN on under-return" has_verdict PANEL_UNDERRETURN

# (6) roster == returned set -> no PANEL_UNDERRETURN
python3 "$SCRIPT" --panel "$GOOD" --roster "$ROSTER3" --out "$OUT" --quiet >/dev/null 2>&1
check "no PANEL_UNDERRETURN when roster == returned" no_verdict PANEL_UNDERRETURN

# (7) roster-gated: without --roster the same 1-reviewer panel does NOT emit PANEL_UNDERRETURN
python3 "$SCRIPT" --panel "$ONE" --out "$OUT" --quiet >/dev/null 2>&1
check "no PANEL_UNDERRETURN without a roster (backward compatible)" no_verdict PANEL_UNDERRETURN

# (8) every returned reviewer shares the generator's substrate -> SUBSTRATE_MONOCULTURE (Major),
#     exit 1. A same-model panel inherits the generator's blind spots; it is not an independent
#     check. The roster ids match GOOD's returned set, so PANEL_UNDERRETURN does not confound.
python3 "$SCRIPT" --panel "$GOOD" --roster "$MONOSUB" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 (all reviewers share the generator substrate)" test "$?" -eq 1
check "SUBSTRATE_MONOCULTURE detected" has_verdict SUBSTRATE_MONOCULTURE

# (9) at least one different-substrate lens (codex, human) -> no SUBSTRATE_MONOCULTURE, exit 0
python3 "$SCRIPT" --panel "$GOOD" --roster "$INDEPSUB" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 0 (an independent lens breaks the monoculture)" test "$?" -eq 0
check "no SUBSTRATE_MONOCULTURE with an independent lens" no_verdict SUBSTRATE_MONOCULTURE

# (10) substrate-gated: a bare roster (no substrate fields) does NOT emit SUBSTRATE_MONOCULTURE
python3 "$SCRIPT" --panel "$GOOD" --roster "$ROSTER3" --out "$OUT" --quiet >/dev/null 2>&1
check "no SUBSTRATE_MONOCULTURE without substrate info (backward compatible)" no_verdict SUBSTRATE_MONOCULTURE

# (11) LENS_COLLAPSE must NOT fire on a reviewer declared on a DIFFERENT substrate from the
#      generator. In COLLAPSE, R3's families are fully subsumed by R1's; under INDEPSUB, R3 is
#      the non-claude lens — the very one whose presence stops SUBSTRATE_MONOCULTURE (case 9).
#      Firing here told the editor that the panel's only independent lens "added no independent
#      axis", i.e. to consider dropping it. Agreement reached from another substrate is
#      corroboration, not a redundant assignment. Observed live in a Codex-reviewer panel.
python3 "$SCRIPT" --panel "$COLLAPSE" --roster "$INDEPSUB" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 0 (cross-substrate reviewer is not a collapsed lens)" test "$?" -eq 0
check "no LENS_COLLAPSE on a cross-substrate reviewer" no_verdict LENS_COLLAPSE
check "the exemption is recorded, not silent" python3 -c "
import json
d=json.load(open('$OUT'))
ex=d['summary'].get('lens_collapse_substrate_exempt')
assert ex == ['R3'], f'expected R3 recorded as exempt, got {ex!r}'
"

# (12) ...and the exemption is NOT a blanket disable: the same panel with an all-same-substrate
#      roster must still raise LENS_COLLAPSE on R3. Without this, case (11) could be passed by
#      simply deleting the check.
python3 "$SCRIPT" --panel "$COLLAPSE" --roster "$MONOSUB" --out "$OUT" --quiet >/dev/null 2>&1
check "LENS_COLLAPSE still fires when the redundant lens shares the generator substrate" \
    has_verdict LENS_COLLAPSE
check "nothing exempted when every substrate matches the generator" python3 -c "
import json
d=json.load(open('$OUT'))
ex=d['summary'].get('lens_collapse_substrate_exempt')
assert ex == [], f'expected no exemptions, got {ex!r}'
"

# (13) substrate-gated, as everywhere else: with no substrate info the pre-existing behaviour
#      is unchanged — LENS_COLLAPSE fires exactly as it did before this exemption existed.
python3 "$SCRIPT" --panel "$COLLAPSE" --roster "$ROSTER3" --out "$OUT" --quiet >/dev/null 2>&1
check "LENS_COLLAPSE unchanged on a roster without substrate fields" has_verdict LENS_COLLAPSE

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Structural + PII regression tests for self-review --panel mode (Phase 2.6).
# Pure file checks — no agent invocation. Run from anywhere.

set -uo pipefail

REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
SKILL="$REPO_ROOT/skills/self-review/SKILL.md"
TEMPLATE="$REPO_ROOT/skills/self-review/references/panel_review_template.md"
PROBE_DIR="$REPO_ROOT/skills/self-review/references/domain-probes"

fail=0
ran=0
check() {
    local label="$1"; shift
    ran=$((ran + 1))
    if "$@" >/dev/null 2>&1; then
        printf '  PASS  %s\n' "$label"
    else
        printf '  FAIL  %s\n' "$label"
        fail=$((fail + 1))
    fi
}

[[ -f "$SKILL" ]] || { echo "ENV-ERR: SKILL.md missing" >&2; exit 2; }

# 1. Panel section + flag present.
check "Phase 2.6 panel section present"       grep -qE '^### Phase 2\.6: Multi-Agent Panel Review' "$SKILL"
check "--panel flag documented in Optional Flags" grep -qE '^- `--panel`:' "$SKILL"
check "default stays single-pass (off by default)" grep -qi 'off by default' "$SKILL"
check "--fix x --panel guard documented"       grep -qi 'Do \*\*not\*\* combine with `--fix`' "$SKILL"

# 2. Reviewer-set mapping names all six domain-probe modules.
for m in survival_prognostic sr_ma radiomics narrative_review observational_confounding ai_overclaiming; do
    check "reviewer-set table references $m module" grep -qE "domain-probes/$m\.md" "$SKILL"
done

# 3. Template exists and carries the schema fields + skeletons.
check "panel_review_template.md exists"         test -f "$TEMPLATE"
# The pointer must be REACHABLE from SKILL.md, not necessarily IN it. The panel phase now lives in
# references/phases/phase2_6_panel.md behind a --panel trigger row (whole-file token budget), so the
# chain is SKILL.md -> phase reference -> template. Asserting the pointer sits literally in SKILL.md
# would force the panel body back into the file the budget is trying to keep small.
PANEL_PHASE="$(dirname "$SKILL")/references/phases/phase2_6_panel.md"
check "SKILL.md points at the panel phase"      grep -qE 'references/phases/phase2_6_panel\.md' "$SKILL"
check "template reachable from the panel phase" grep -qE 'references/panel_review_template\.md' "$PANEL_PHASE"
check "template has reviewer schema fields"     grep -qE '"severity": "Fatal \| Fixable"' "$TEMPLATE"
check "template has editor synthesis skeleton"  grep -qi 'Editor synthesis prompt skeleton' "$TEMPLATE"

# 4. Vendored probe modules each reviewer loads exist.
for m in survival_prognostic sr_ma radiomics narrative_review observational_confounding ai_overclaiming; do
    check "vendored module present: $m.md"      test -f "$PROBE_DIR/$m.md"
done

# 5. PoC-content-leak scan on the PoC-derived template.
#    The authoritative PII gate for names / mentors / institutions / project
#    codes is scripts/check_precedent.py (SHA-256 hashed, run repo-wide by
#    validate_skills.sh). Do NOT duplicate those identifiers in cleartext here —
#    that would re-introduce the very PII as a public string (self-doxxing,
#    oss-publication-pii-guard §5). This check is belt-and-suspenders for the
#    non-identifying content markers of the source PoC manuscript (a personal
#    path, the study disease term, the cohort N) that would signal the template
#    was not fully generalized. POSIX-safe (no \b).
POC_MARKERS='/Users/|/home/|emphysema|41,?291'
ran=$((ran + 1))
if grep -nEi "$POC_MARKERS" "$TEMPLATE"; then
    printf '  FAIL  PoC-content-leak scan (panel_review_template.md)\n'
    fail=$((fail + 1))
else
    printf '  PASS  PoC-content-leak scan (panel_review_template.md)\n'
fi

echo ""
echo "ran=$ran fail=$fail"
[[ $fail -eq 0 ]]

#!/usr/bin/env bash
# Regression test for the parenthesis-span corruption gate (post em-dash reduction).
# Synthetic, PII-free fixtures: a manuscript where an em-dash→paren conversion
# wrapped an ordinal limitation ("Sixth, …") and a whole sentence inside parens
# (paren-balanced but broken), and a clean manuscript with only legitimate short
# parentheticals (CIs, citations, "Dr. Smith", "Fig. 2"). Stdlib-only (python3).
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_paren_spans.py"
BAD="$HERE/fixtures/paren_corrupt.md"
CLEAN="$HERE/fixtures/paren_clean.md"
OUT="$(mktemp -t paren_XXXX).json"
trap 'rm -f "$OUT"' EXIT

fail=0
check() { local label="$1"; shift
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}
has_verdict() { python3 -c "
import json,sys
d=json.load(open('$OUT'))
assert any(c['verdict']=='$1' for c in d['claims']), '$1 not found'
"; }

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

# (1) corrupt manuscript -> ordinal + sentence span, exit 1
python3 "$SCRIPT" --manuscript "$BAD" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 under --strict (corruption present)" test "$?" -eq 1
check "PAREN_SPAN_ORDINAL detected"  has_verdict PAREN_SPAN_ORDINAL
check "PAREN_SPAN_SENTENCE detected" has_verdict PAREN_SPAN_SENTENCE

# (2) clean manuscript: short legitimate parentheticals only -> exit 0, no false positive
python3 "$SCRIPT" --manuscript "$CLEAN" --strict --quiet >/dev/null 2>&1
check "exit 0 on clean manuscript (no false positive on CI/citation/Dr./Fig. parens)" test "$?" -eq 0

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression test: a gate that says "cannot submit" must not be counted as an optional Minor.
#
# `_qc_findings._MAJOR` knew two words, `MAJOR` and `FATAL`. The detectors were written
# independently and each picked its own vocabulary, so a severity outside those two fell into the
# `else` branch and was counted Minor. `check_placeholders` marks a leftover `TODO` as `blocker` and
# exits 1 on it unconditionally — and the stop controller read the same artifact and answered:
#
#     STOP_MINOR_OPTIONAL — "No required edits ... do not treat them as blocking and do not loop"
#
# Membership in the Major set is derived from each detector's own exit contract, so this test asserts
# behaviour per word, and — the part that closes the class — asserts that EVERY severity literal
# shipped anywhere in skills/*/scripts/*.py is classified deliberately. A newly invented word must
# fail this test rather than silently become an optional Minor.
set -u

REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
R="$REPO_ROOT/skills/self-review/scripts/refinement_stop.py"
Q="$REPO_ROOT/skills/self-review/scripts/_qc_findings.py"
WORK="$(mktemp -d -t qc_severity_test.XXXXXX)"
trap 'rm -rf "$WORK"' EXIT

pass=0
fail=0
ck() {
  local label="$1" expected="$2" actual="$3"
  if [ "$expected" = "$actual" ]; then
    printf '  PASS  %-50s %s\n' "$label" "$actual"
    pass=$((pass + 1))
  else
    printf '  FAIL  %-50s expected=%s actual=%s\n' "$label" "$expected" "$actual"
    fail=$((fail + 1))
  fi
}

verdict_for() {  # verdict_for <severity> -> the controller's terminal-state word
  local sev="$1" d="$WORK/qc_$RANDOM"
  mkdir -p "$d"
  python3 - "$d/gate.json" "$sev" <<'PY'
import json, sys
json.dump({"detector": "check_placeholders",
           "findings": [{"verdict": "PLACEHOLDER_LEFT", "severity": sys.argv[2], "line": 42}]},
          open(sys.argv[1], "w"), indent=1)
PY
  python3 "$R" --qc-dir "$d" 2>/dev/null | sed -n '1s/.*: //p'
}

echo "==== words whose own detector exits 1: the loop must CONTINUE ===="
for sev in blocker hard stale FAIL MAJOR FATAL Major major; do
  ck "severity '$sev' -> CONTINUE" CONTINUE "$(verdict_for "$sev")"
done

echo "==== NEGATIVE CONTROLS — advisory words must stay optional ===="
# check_generated_code computes n_flag = len(claims) - n_major and exits only on n_major, so its own
# contract says Flag is advisory. Widening indiscriminately would break this.
for sev in Flag Minor minor soft warn INFO; do
  ck "severity '$sev' -> STOP_MINOR_OPTIONAL" STOP_MINOR_OPTIONAL "$(verdict_for "$sev")"
done

echo "==== an unrecognised word fails toward the loop CONTINUING, and is named ===="
ck "unknown 'urgent' -> CONTINUE" CONTINUE "$(verdict_for urgent)"
d="$WORK/qc_unknown"; mkdir -p "$d"
python3 - "$d/gate.json" <<'PY'
import json, sys
json.dump({"detector": "check_x",
           "findings": [{"verdict": "V", "severity": "urgent", "line": 1}]},
          open(sys.argv[1], "w"), indent=1)
PY
ck "  and reported by name" "urgent" \
   "$(python3 "$R" --qc-dir "$d" --out "$d/stop.json" >/dev/null 2>&1; \
      python3 -c 'import json,sys; print(",".join(json.load(open(sys.argv[1])).get("unknown_severities",[])))' "$d/stop.json" 2>/dev/null || echo MISSING)"

echo "==== the class-closing assertion: every shipped severity word is classified ===="
unclassified="$(python3 - "$REPO_ROOT" "$Q" <<'PY'
import importlib.util, pathlib, re, sys
root = pathlib.Path(sys.argv[1])
spec = importlib.util.spec_from_file_location("q", sys.argv[2])
m = importlib.util.module_from_spec(spec)
sys.modules["q"] = m
spec.loader.exec_module(m)
pat = re.compile(r'"severity"\s*:\s*"([A-Za-z_][A-Za-z_ ]*)"')
words = set()
for p in root.glob("skills/*/scripts/*.py"):
    words |= set(pat.findall(p.read_text(encoding="utf-8", errors="replace")))
bad = sorted(w for w in words if m._classify(w) == "unknown")
print(",".join(bad))
PY
)"
ck "severity words no controller classifies" "" "$unclassified"

echo
echo "  passed=$pass failed=$fail"
[ "$fail" -eq 0 ] || exit 1
echo "OK: a blocker blocks, an advisory stays advisory, and a new word cannot join silently."

#!/usr/bin/env bash
# Regression test for the reference-adequacy gate (self-review Phase 2.5c-2 /
# write-paper Step 7.3c). Synthetic fixtures reproduce:
#   1. an original-research draft whose Statistical Analysis subsection names a
#      competing-risk model, multiple imputation, the E-value, and an eGFR
#      equation with ZERO citations (the highest-value failure mode);
#   2. the same draft with a citation added in each named-method paragraph;
#   3. a letter whose lower reference target must not false-fail.
# Stdlib-only (python3).
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_reference_adequacy.py"
FIX="$HERE/fixtures"
OUT="$(mktemp -t ra_XXXX).json"
trap 'rm -f "$OUT"' EXIT

fail=0
check() { local label="$1"; shift
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}
# assert a python boolean expression over the JSON at $OUT; `d` is the parsed dict.
# (No assertion message: the expression embeds single quotes — the check() label
# already names the case on FAIL.)
jassert() { python3 -c "
import json
d=json.load(open('$OUT'))
assert ($1)
"; }

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing: $SCRIPT" >&2; exit 2; }

echo "== Fixture 1: original research, Methods names methods with 0 citations =="
python3 "$SCRIPT" --manuscript "$FIX/refadeq_original_uncited.md" \
    --article-type original_article --out "$OUT" --strict >/dev/null 2>&1
check "exit 1 under --strict (Major present)"      test "$?" -eq 1
check "JSON artifact written"                       test -s "$OUT"
check "methods_zero_citations is true"              jassert "d['methods_zero_citations'] is True"
check "uncited_named_methods is non-empty"          jassert "len(d['uncited_named_methods']) > 0"
check "Fine-Gray flagged uncited"                   jassert "'Fine-Gray' in d['uncited_named_methods']"
check "reference_count_verdict BELOW_TARGET"        jassert "d['reference_count_verdict'] == 'BELOW_TARGET'"
check "a methods_zero_citations Major finding"      jassert "any(f['subtype']=='methods_zero_citations' and f['severity']=='major' for f in d['findings'])"
check "all findings fixable_by_ai=false"            jassert "all(f['fixable_by_ai'] is False for f in d['findings'])"

echo "== Fixture 2: same draft, each named method now cited =="
python3 "$SCRIPT" --manuscript "$FIX/refadeq_original_fixed.md" \
    --article-type original_article --out "$OUT" --strict >/dev/null 2>&1
check "exit 0 (no Major; Methods gap cleared)"      test "$?" -eq 0
check "methods_zero_citations is false"             jassert "d['methods_zero_citations'] is False"
check "no methods_named_method_uncited finding"     jassert "not any(f['subtype']=='methods_named_method_uncited' for f in d['findings'])"
check "adequacy_safe is true"                        jassert "d['adequacy_safe'] is True"

echo "== Fixture 3: letter (lower target must not false-fail) =="
python3 "$SCRIPT" --manuscript "$FIX/refadeq_letter.md" \
    --article-type letter --out "$OUT" --strict >/dev/null 2>&1
check "exit 0 (letter target met)"                  test "$?" -eq 0
check "verdict ADEQUATE for letter"                 jassert "d['reference_count_verdict'] == 'ADEQUATE'"
check "no adequacy findings"                         jassert "len(d['findings']) == 0"

echo "== Alias map: nhis_cohort routes to original_research target =="
python3 "$SCRIPT" --manuscript "$FIX/refadeq_original_uncited.md" \
    --article-type nhis_cohort --out "$OUT" --quiet >/dev/null 2>&1
check "nhis_cohort -> original_research bucket"      jassert "d['article_bucket'] == 'original_research'"
check "original_research target is [25,45]"         jassert "d['effective_target'] == [25,45]"

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression tests for self-review check_reviewer_team_consistency.py.

set -uo pipefail

REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
SCRIPT="$REPO_ROOT/skills/self-review/scripts/check_reviewer_team_consistency.py"
TMP="$(mktemp -d -t reviewer_team.XXXXXX)"
trap 'rm -rf "$TMP"' EXIT

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

fail=0
ran=0
assert_exit() {
    local label="$1" expected="$2" actual="$3"
    ran=$((ran + 1))
    if [[ "$expected" == "$actual" ]]; then
        printf '  PASS  %-50s exit=%s\n' "$label" "$actual"
    else
        printf '  FAIL  %-50s expected=%s actual=%s\n' "$label" "$expected" "$actual"
        fail=$((fail + 1))
    fi
}

# --------------------------------------------------------------------------
# Case 1: clean — dual review claimed, no limits confession.
# --------------------------------------------------------------------------
cat > "$TMP/c1.md" <<'EOF'
## **METHODS**
Two reviewers independently screened titles and abstracts.

## **DISCUSSION**
The cohort overlap reduces effective sample size.
EOF
python3 "$SCRIPT" --manuscript "$TMP/c1.md" \
    --out "$TMP/c1.md.audit" --quiet
assert_exit "case 1: dual claim, no limits confession" 0 $?

# --------------------------------------------------------------------------
# Case 2: fabrication-grade — Methods dual + Limitations single confession.
# --------------------------------------------------------------------------
cat > "$TMP/c2.md" <<'EOF'
## **METHODS**
Two reviewers independently screened titles and abstracts and extracted data.

## **DISCUSSION**

### Limitations
We used a single primary reviewer for data extraction; a 20% sample by an
additional reviewer is deferred to before submission.
EOF
python3 "$SCRIPT" --manuscript "$TMP/c2.md" \
    --out "$TMP/c2.md.audit" --quiet
assert_exit "case 2: dual + single confession (FAIL)" 1 $?

# Verify the markdown report flags both claim sides.
grep -q "MAJOR red flag" "$TMP/c2.md.audit" || { echo "  FAIL c2 markdown body"; fail=$((fail + 1)); }
grep -q "single primary reviewer" "$TMP/c2.md.audit" || { echo "  FAIL c2 markdown body"; fail=$((fail + 1)); }

# --------------------------------------------------------------------------
# Case 3: PROSPERO dual + Limitations single. Also FAIL.
# --------------------------------------------------------------------------
cat > "$TMP/c3.md" <<'EOF'
## **METHODS**
Records were screened against pre-specified eligibility criteria.

## **DISCUSSION**
### Limitations
A single primary reviewer extracted data due to resource constraints.
EOF
cat > "$TMP/c3_prospero.md" <<'EOF'
# PROSPERO record
Two independent reviewers will perform full-text screening and data extraction.
EOF
python3 "$SCRIPT" --manuscript "$TMP/c3.md" --prospero "$TMP/c3_prospero.md" \
    --out "$TMP/c3.md.audit" --quiet
assert_exit "case 3: PROSPERO dual + limits single (FAIL)" 1 $?

# --------------------------------------------------------------------------
# Case 4: single confession alone (no dual claim) => PASS.
# --------------------------------------------------------------------------
cat > "$TMP/c4.md" <<'EOF'
## **METHODS**
Data extraction was performed by the first reviewer.

## **DISCUSSION**
### Limitations
A single primary reviewer extracted data; this is a limitation of our review.
EOF
python3 "$SCRIPT" --manuscript "$TMP/c4.md" \
    --out "$TMP/c4.md.audit" --quiet
assert_exit "case 4: single confession only (PASS)" 0 $?

# --------------------------------------------------------------------------
# Case 5: extraction JSON names an LLM as a reviewer => fatal FAIL.
# --------------------------------------------------------------------------
cat > "$TMP/c5.md" <<'EOF'
## **METHODS**
Records were screened against pre-specified eligibility criteria.
EOF
cat > "$TMP/c5_extract.json" <<'EOF'
{"study": "Example 2024", "reviewer_1": "Claude", "reviewer_2": "Jane Doe"}
EOF
python3 "$SCRIPT" --manuscript "$TMP/c5.md" --extraction-json "$TMP/c5_extract.json" \
    --out "$TMP/c5.md.audit" --quiet
assert_exit "case 5: LLM-as-reviewer in extraction JSON (FAIL)" 1 $?
grep -q "LLM-AS-REVIEWER" "$TMP/c5.md.audit" || { echo "  FAIL c5 markdown body"; fail=$((fail + 1)); }

# --------------------------------------------------------------------------
# Case 6: future-tense deferred mitigation => MAJOR FAIL.
# --------------------------------------------------------------------------
cat > "$TMP/c6.md" <<'EOF'
## **METHODS**
Records were screened by the primary reviewer.

## **DISCUSSION**
### Limitations
A duplicate-screening check will be completed before submission.
EOF
python3 "$SCRIPT" --manuscript "$TMP/c6.md" \
    --out "$TMP/c6.md.audit" --quiet
assert_exit "case 6: deferred mitigation (FAIL)" 1 $?
grep -q "DEFERRED-MITIGATION" "$TMP/c6.md.audit" || { echo "  FAIL c6 markdown body"; fail=$((fail + 1)); }

# --------------------------------------------------------------------------
# Case 7: clean extraction JSON (human reviewers) => PASS (backward compat).
# --------------------------------------------------------------------------
cat > "$TMP/c7_extract.json" <<'EOF'
{"study": "Example 2024", "reviewer_1": "Jane Doe", "reviewer_2": "John Roe"}
EOF
python3 "$SCRIPT" --manuscript "$TMP/c1.md" --extraction-json "$TMP/c7_extract.json" \
    --out "$TMP/c7.md.audit" --quiet
assert_exit "case 7: human reviewers in extraction JSON (PASS)" 0 $?

echo ""
echo "ran=$ran fail=$fail"
[[ $fail -eq 0 ]]

#!/usr/bin/env bash
# Regression test for the rhetorical-construction density gate (P27 / §J — antithesis
# parallelism and cleft, the two sentence-structure AI tells a per-instance rule misses).
# Synthetic, PII-free fixtures. Two cases carrying the SAME argument, differing only in how
# their sentences are built:
#   (1) rhetorical_dense.md — a run of "rather than" / "not X but Y" / "X, not Y" plus
#       sentence-initial "What … is …" / "It is … that …" -> ANTITHESIS_DENSITY AND
#       CLEFT_DENSITY both fire.
#   (2) rhetorical_clean.md — the same argument written in plain subject-verb order, with
#       exactly ONE functional "rather than" and ONE cleft used sparingly -> silent. The
#       single cleft's density even clears the per-1000 line; it stays silent because the
#       raw count (1) is below the floor (3), which is the AND(floor, density) contract.
# Run at shipped defaults so the test exercises the real thresholds. Stdlib-only.
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_rhetorical_density.py"
FX="$HERE/fixtures"
OUT="$(mktemp -t rhetorical_XXXX).json"
trap 'rm -f "$OUT"' EXIT

fail=0
check() { local label="$1"; shift
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}
run() { python3 "$SCRIPT" --manuscript "$1" --out "$OUT" --quiet >/dev/null 2>&1; }
has_verdict() { python3 -c "import json,sys; d=json.load(open('$OUT')); sys.exit(0 if '$1' in {f['verdict'] for f in d['findings']} else 1)"; }
no_findings() { python3 -c "import json,sys; sys.exit(0 if not json.load(open('$OUT'))['findings'] else 1)"; }

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

# (1) antithesis + cleft dense prose -> both verdicts fire
run "$FX/rhetorical_dense.md"
check "dense fixture fires ANTITHESIS_DENSITY" has_verdict ANTITHESIS_DENSITY
check "dense fixture fires CLEFT_DENSITY" has_verdict CLEFT_DENSITY

# (2) explanatory prose (same argument, sparse functional use) -> silent
run "$FX/rhetorical_clean.md"
check "clean fixture does not fire (functional antithesis + one sparing cleft)" no_findings
check "clean fixture: one cleft below the count floor stays silent despite crossing density" python3 -c "
import json
d = json.load(open('$OUT'))
assert not d['findings'], d['findings']
# the single functional cleft pushes density over the 2.5 line, yet count (1) < floor (3)
assert d['metrics']['cleft_per_1000'] > 2.5, d['metrics']
"

# (3) the JSON envelope names its own detector (check_detector_envelopes contract)
check "envelope self-identifies the detector" python3 -c "
import json
assert json.load(open('$OUT'))['detector'] == 'check_rhetorical_density'
"

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression test for the rounded-component vs stated-difference gate (Phase 2.5a).
# Synthetic fixtures: (bad) components 0.70/0.73 with a stated difference 0.02 (shown
# gap is 0.03) -> ROUNDED_DELTA_MISMATCH; (clean) a correct 0.03 delta, a legit
# higher-precision unrounded 0.02 delta, and an unrelated decimal pair -> no flag.
set -u
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_rounded_delta.py"
BAD="$HERE/fixtures/rounded_delta_bad.md"
CLEAN="$HERE/fixtures/rounded_delta_clean.md"
OUT="$(mktemp -t rdelta_XXXX).json"
trap 'rm -f "$OUT"' EXIT
fail=0
check() { local label="$1"; shift
  if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
  else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi; }
has_verdict() { python3 -c "
import json
d=json.load(open('$OUT'))
assert any(c['verdict']=='$1' for c in d['claims']), '$1 not found'
"; }
[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

python3 "$SCRIPT" --manuscript "$BAD" --out "$OUT" --quiet >/dev/null 2>&1
check "ROUNDED_DELTA_MISMATCH on 0.70/0.73 vs stated 0.02" has_verdict ROUNDED_DELTA_MISMATCH
check "JSON artifact written" test -s "$OUT"

python3 "$SCRIPT" --manuscript "$CLEAN" --out "$OUT" --quiet >/dev/null 2>&1
check "no mismatch on correct/unrounded/unrelated decimals" python3 -c "
import json
d=json.load(open('$OUT'))
assert not d['claims'], d['claims']
"
echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression test for the scope-coherence gate (self-review §D).
# Synthetic, PII-free fixtures reproduce: (a) a cross-sectional design with a
# prognostic/surveillance conclusion (CROSS_SECTIONAL_PROGNOSTIC), (b) a binary
# surrogate endpoint driving a care directive (SURROGATE_CARE_DIRECTIVE). The clean
# fixture is a longitudinal cohort with an association conclusion.
# Stdlib-only (python3).
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_scope_coherence.py"
BAD="$HERE/fixtures/scope_bad.md"
SURR="$HERE/fixtures/scope_surrogate.md"
CLEAN="$HERE/fixtures/scope_clean.md"
GRAD="$HERE/fixtures/scope_gradient.md"
GRADTEST="$HERE/fixtures/scope_gradient_tested.md"
OUT="$(mktemp -t scope_XXXX).json"
trap 'rm -f "$OUT"' EXIT

fail=0
check() { local label="$1"; shift
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}
has_verdict() { python3 -c "
import json,sys
d=json.load(open('$OUT'))
assert any(c['verdict']=='$1' for c in d['claims']), '$1 not found'
"; }

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

# (1) cross-sectional + prognostic conclusion -> CROSS_SECTIONAL_PROGNOSTIC, exit 1
python3 "$SCRIPT" --manuscript "$BAD" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 (cross-sectional prognostic)" test "$?" -eq 1
check "CROSS_SECTIONAL_PROGNOSTIC detected" has_verdict CROSS_SECTIONAL_PROGNOSTIC

# (2) binary surrogate + care directive -> SURROGATE_CARE_DIRECTIVE, exit 1
python3 "$SCRIPT" --manuscript "$SURR" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 (surrogate care directive)" test "$?" -eq 1
check "SURROGATE_CARE_DIRECTIVE detected" has_verdict SURROGATE_CARE_DIRECTIVE

# (3) longitudinal cohort + association conclusion -> exit 0
python3 "$SCRIPT" --manuscript "$CLEAN" --strict --quiet >/dev/null 2>&1
check "exit 0 on clean manuscript" test "$?" -eq 0

# (4) cross-sectional + yield/detection-rate language, undefined -> Minor flag
YIELD="$HERE/fixtures/scope_yield.md"
YDEF="$HERE/fixtures/scope_yield_defined.md"
python3 "$SCRIPT" --manuscript "$YIELD" --out "$OUT" --quiet >/dev/null 2>&1
check "CROSS_SECTIONAL_YIELD_LANGUAGE detected" has_verdict CROSS_SECTIONAL_YIELD_LANGUAGE
python3 "$SCRIPT" --manuscript "$YIELD" --strict --quiet >/dev/null 2>&1
check "yield flag is Minor (no Major -> exit 0 under --strict)" test "$?" -eq 0

# (5) yield explicitly defined as cross-sectional prevalence -> suppressed
python3 "$SCRIPT" --manuscript "$YDEF" --out "$OUT" --quiet >/dev/null 2>&1
check "yield definition suppresses the flag" python3 -c "
import json
d=json.load(open('$OUT'))
assert not any(c['verdict']=='CROSS_SECTIONAL_YIELD_LANGUAGE' for c in d['claims'])
"

# (6) cross-sectional design + a DISCLAIMED surveillance/prognostic token
#     ("... rather than surveillance intervals ... which would require prospective
#     data ...") -> NO CROSS_SECTIONAL_PROGNOSTIC, exit 0 (regression).
DISC="$HERE/fixtures/scope_disclaimer.md"
python3 "$SCRIPT" --manuscript "$DISC" --out "$OUT" --quiet >/dev/null 2>&1
check "no CROSS_SECTIONAL_PROGNOSTIC when disclaimed" python3 -c "
import json
d=json.load(open('$OUT'))
assert not any(c['verdict']=='CROSS_SECTIONAL_PROGNOSTIC' for c in d['claims']), 'disclaimer flagged as prognostic claim'
"
python3 "$SCRIPT" --manuscript "$DISC" --strict --quiet >/dev/null 2>&1
check "exit 0 on disclaimer manuscript" test "$?" -eq 0

# (7) a methods/QC/detector paper whose SUBJECT is this anti-pattern NAMES the
#     cross-sectional+prognostic pattern rather than committing it -> no fire.
METADOC="$HERE/fixtures/scope_metadoc.md"
python3 "$SCRIPT" --manuscript "$METADOC" --out "$OUT" --quiet >/dev/null 2>&1
check "no CROSS_SECTIONAL_PROGNOSTIC on a meta-document" python3 -c "
import json
d=json.load(open('$OUT'))
assert not any(c['verdict']=='CROSS_SECTIONAL_PROGNOSTIC' for c in d['claims']), 'meta-document flagged as prognostic overclaim'
"
python3 "$SCRIPT" --manuscript "$METADOC" --strict --quiet >/dev/null 2>&1
check "exit 0 on meta-document" test "$?" -eq 0

# (8) an enumerated-defect list ("... flags ..., an unsupported prognostic claim
#     in a cross-sectional study, a fabricated citation, ...") LABELS the anti-pattern
#     as a defect rather than committing it. META_DOC_FRAME misses it (the framing
#     verb sits far from the match); ANTIPATTERN_LABEL suppresses it. -> no fire.
APLIST="$HERE/fixtures/scope_antipattern_list.md"
python3 "$SCRIPT" --manuscript "$APLIST" --out "$OUT" --quiet >/dev/null 2>&1
check "no CROSS_SECTIONAL_PROGNOSTIC on an enumerated-defect list" python3 -c "
import json
d=json.load(open('$OUT'))
assert not any(c['verdict']=='CROSS_SECTIONAL_PROGNOSTIC' for c in d['claims']), 'enumerated-defect label flagged as prognostic overclaim'
"
python3 "$SCRIPT" --manuscript "$APLIST" --strict --quiet >/dev/null 2>&1
check "exit 0 on enumerated-defect list" test "$?" -eq 0

# UNIVERSAL_NEGATIVE_UNSCOPED: a "no published system … first study to quantify"
# claim with no named discipline-scope qualifier.
UN="$HERE/fixtures/scope_universal_negative.md"
python3 "$SCRIPT" --manuscript "$UN" --out "$OUT" --quiet >/dev/null 2>&1
check "UNIVERSAL_NEGATIVE_UNSCOPED on an unscoped novelty claim" has_verdict UNIVERSAL_NEGATIVE_UNSCOPED
# a discipline-scope qualifier ("clinically published … in the radiology literature") suppresses it
UNOK="$HERE/fixtures/scope_universal_negative_ok.md"
python3 "$SCRIPT" --manuscript "$UNOK" --out "$OUT" --quiet >/dev/null 2>&1
check "no UNIVERSAL_NEGATIVE_UNSCOPED when a discipline-scope qualifier is present" python3 -c "
import json
d=json.load(open('$OUT'))
raise SystemExit(0 if not any(c['verdict']=='UNIVERSAL_NEGATIVE_UNSCOPED' for c in d['claims']) else 1)
"

# (N) cross-strata directional claim ("shortest in the high-risk tertile", "monotonically
#     across the age strata") with a stratification context but NO interaction test ->
#     GRADIENT_WITHOUT_INTERACTION (Minor). The SAME claim with an interaction test reported
#     (LRT / p-interaction) must NOT fire (the suppression guard).
python3 "$SCRIPT" --manuscript "$GRAD" --out "$OUT" --quiet >/dev/null 2>&1
check "GRADIENT_WITHOUT_INTERACTION on gradient-across-strata, no interaction test" has_verdict GRADIENT_WITHOUT_INTERACTION
python3 "$SCRIPT" --manuscript "$GRADTEST" --out "$OUT" --quiet >/dev/null 2>&1
check "no GRADIENT_WITHOUT_INTERACTION when the interaction is tested (LRT / p-interaction)" python3 -c "
import json
d=json.load(open('$OUT'))
raise SystemExit(0 if not any(c['verdict']=='GRADIENT_WITHOUT_INTERACTION' for c in d['claims']) else 1)
"

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression test for the supplement-hygiene gate (self-review §J supplement pass).
# Synthetic, PII-free fixtures reproduce reader-facing supplement residue: a §/§L
# internal label, an unfilled placeholder (SX / [Authors] / figure-glob / build-dir
# path), a build marker ([VERIFY]/TODO), response-to-reviewers framing, and pre-
# execution planning residue; plus a body↔supplement cross-reference that does not
# resolve. The clean fixture is a normal reader-facing supplement.
# Stdlib-only (python3).
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/check_supplement_hygiene.py"
DIRTY="$HERE/fixtures/supp_dirty.md"
CLEAN="$HERE/fixtures/supp_clean.md"
XBODY="$HERE/fixtures/supp_xref_body.md"
XSUPP="$HERE/fixtures/supp_xref_supp.md"
OUT="$(mktemp -t supphyg_XXXX).json"
trap 'rm -f "$OUT"' EXIT

fail=0
check() { local label="$1"; shift
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}
has_verdict() { python3 -c "
import json,sys
d=json.load(open('$OUT'))
assert any(c['verdict']=='$1' for c in d['claims']), '$1 not found'
"; }

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }

# (1) dirty supplement: all five residue verdicts, Major present -> exit 1 under --strict
python3 "$SCRIPT" --supplement "$DIRTY" --out "$OUT" --strict --quiet >/dev/null 2>&1
check "exit 1 under --strict (Major present)" test "$?" -eq 1
check "JSON artifact written" test -s "$OUT"
check "SUPP_INTERNAL_LABEL detected"   has_verdict SUPP_INTERNAL_LABEL
check "SUPP_PLACEHOLDER detected"      has_verdict SUPP_PLACEHOLDER
check "SUPP_BUILD_MARKER detected"     has_verdict SUPP_BUILD_MARKER
check "SUPP_RESPONSE_FRAMING detected" has_verdict SUPP_RESPONSE_FRAMING
check "SUPP_PLANNING_RESIDUE detected" has_verdict SUPP_PLANNING_RESIDUE

# (2) clean supplement: no residue -> exit 0
python3 "$SCRIPT" --supplement "$CLEAN" --strict --quiet >/dev/null 2>&1
check "exit 0 on clean supplement" test "$?" -eq 0

# (3) body cites Supplementary Table 2 (present) + Figure 9 (absent) -> exactly one
#     SUPP_XREF_UNRESOLVED for the unresolved callout
python3 "$SCRIPT" --supplement "$XSUPP" --manuscript "$XBODY" --out "$OUT" --quiet >/dev/null 2>&1
check "SUPP_XREF_UNRESOLVED detected" has_verdict SUPP_XREF_UNRESOLVED
check "only the unresolved callout fires (Table 2 resolves)" python3 -c "
import json
d=json.load(open('$OUT'))
x=[c for c in d['claims'] if c['verdict']=='SUPP_XREF_UNRESOLVED']
assert len(x)==1 and '9' in x[0]['detail'], x
"

# (4) missing --supplement -> usage error (exit 2)
python3 "$SCRIPT" --manuscript "$XBODY" --quiet >/dev/null 2>&1
check "exit 2 when no --supplement given" test "$?" -eq 2

# (5) participant-PII tie: a pseudonym + name tied to an individual response row ->
#     SUPP_PARTICIPANT_PII_TIE; a byline/roster with only aggregate responses -> clean.
PIILEAK="$HERE/fixtures/supplement_pii_tie.md"
PIICLEAN="$HERE/fixtures/supplement_pii_clean.md"
python3 "$SCRIPT" --supplement "$PIILEAK" --out "$OUT" --quiet >/dev/null 2>&1
check "SUPP_PARTICIPANT_PII_TIE on identity+individual-response row" python3 -c "
import json
d=json.load(open('$OUT'))
assert any(c['verdict']=='SUPP_PARTICIPANT_PII_TIE' for c in d['claims']), 'not flagged'
"
python3 "$SCRIPT" --supplement "$PIICLEAN" --out "$OUT" --quiet >/dev/null 2>&1
check "no PII tie on a byline/roster with aggregate responses" python3 -c "
import json
d=json.load(open('$OUT'))
assert not any(c['verdict']=='SUPP_PARTICIPANT_PII_TIE' for c in d['claims']), 'roster false positive'
"

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression test: an INFERRED denominator must earn its use.
#
# The most common table in clinical research is a Table 1 of independent binary characteristics with
# N stated in the CAPTION. It declares no column `n = N` and has no Total row, so the checker fell
# through to summing the column's counts — 79 + 53 + 40 + 26 = 198 for a study of 132 — and then
# accused all four correct cells of bad arithmetic, each with a specific wrong replacement
# percentage, at MAJOR, exit 1 under --strict. A gate that reds a correct submission and tells the
# author to change a right number to a wrong one is worse than one that stays quiet.
#
# Gating on `is_partition` is NOT the fix and this test pins that: that flag is derived from the
# printed percentages summing to ~100, so a partition containing a wrong percentage stops looking
# like a partition and the check would go silent on the very error it exists to catch. The rule is
# instead that an inferred denominator reconciling NOTHING is the wrong denominator, while a
# denominator the author DECLARED is never second-guessed.
set -u

REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
D="$REPO_ROOT/skills/self-review/scripts/check_table_percentages.py"
WORK="$(mktemp -d -t table_percent_test.XXXXXX)"
trap 'rm -rf "$WORK"' EXIT

pass=0
fail=0
ck() {
  local label="$1" expected="$2" actual="$3"
  if [ "$expected" = "$actual" ]; then
    printf '  PASS  %-50s %s\n' "$label" "$actual"
    pass=$((pass + 1))
  else
    printf '  FAIL  %-50s expected=%s actual=%s\n' "$label" "$expected" "$actual"
    fail=$((fail + 1))
  fi
}

rc_of() {  # rc_of <file> -> exit code, no pipe between the command and $?
  python3 "$D" --manuscript "$WORK/$1" --strict > "$WORK/$1.out" 2>&1
  echo $?
}
majors() { grep -c '^\[MAJOR\]' "$WORK/$1.out" || true; }
has_info() { grep -q 'PERCENT_DENOM_UNKNOWN' "$WORK/$1.out" && echo yes || echo no; }

# 1. The real-world false positive: caption N, independent binary rows, every percentage correct.
cat > "$WORK/caption_n.md" <<'EOF'
## Results

**Table 1.** Baseline characteristics of the 132 enrolled patients.

| Characteristic | Value |
|---|---|
| Male sex | 79 (59.8%) |
| Hypertension | 53 (40.2%) |
| Diabetes | 40 (30.3%) |
| Current smoker | 26 (19.7%) |
EOF

# 2. A genuine partition with one wrong percentage. The count-sum IS the denominator here and
#    reconciles 2 of 3 rows, so the wrong one must still be caught.
cat > "$WORK/partition_bad.md" <<'EOF'
## Results

**Table 2.** Tumour stage distribution.

| Stage | n (%) |
|---|---|
| I | 40 (99.0%) |
| II | 30 (30.0%) |
| III | 30 (30.0%) |
EOF

# 3. A correct partition: silent.
cat > "$WORK/partition_ok.md" <<'EOF'
## Results

**Table 3.** Tumour stage distribution.

| Stage | n (%) |
|---|---|
| I | 40 (40.0%) |
| II | 30 (30.0%) |
| III | 30 (30.0%) |
EOF

# 4. A DECLARED denominator that the arithmetic contradicts. Never second-guessed.
cat > "$WORK/declared_bad.md" <<'EOF'
## Results

**Table 4.** Characteristics.

| Characteristic | Value (n = 132) |
|---|---|
| Male sex | 79 (75.0%) |
EOF

echo "==== the false positive this fixes ===="
ck "caption-N Table 1: exit 0"            0   "$(rc_of caption_n.md)"
ck "caption-N Table 1: zero MAJOR"        0   "$(majors caption_n.md)"
ck "caption-N Table 1: says why (INFO)"   yes "$(has_info caption_n.md)"

echo "==== NEGATIVE CONTROLS — the check must still bite ===="
ck "partition with a wrong %: exit 1"     1   "$(rc_of partition_bad.md)"
ck "partition with a wrong %: 1 MAJOR"    1   "$(majors partition_bad.md)"
ck "declared n= contradicted: exit 1"     1   "$(rc_of declared_bad.md)"
ck "declared n= contradicted: 1 MAJOR"    1   "$(majors declared_bad.md)"
ck "declared n= is never downgraded"      no  "$(has_info declared_bad.md)"

echo "==== a correct partition stays silent ===="
ck "correct partition: exit 0"            0   "$(rc_of partition_ok.md)"
ck "correct partition: no findings at all" 0  "$(majors partition_ok.md)"
ck "correct partition: no INFO either"    no  "$(has_info partition_ok.md)"

echo
echo "  passed=$pass failed=$fail"
[ "$fail" -eq 0 ] || { for f in caption_n partition_bad declared_bad partition_ok; do
    echo "--- $f"; cat "$WORK/$f.md.out"; done; exit 1; }
echo "OK: an inferred denominator must reconcile something; a declared one is taken at its word."