Cover Letter

interface:
  display_name: "Cover Letter"
  short_description: "Generate, optimize, align-check, and journal-fit-check a submission cover letter against an existing LaTeX manuscript"
  default_prompt: "Generate, optimize, align-check, or journal-fit-check a submission cover letter for a LaTeX paper; infer the right mode from the request, read the manuscript when available for claim alignment, and apply the chosen journal template plus tier strategy."

{
  "skill_name": "cover-letter",
  "evals": [
    {
      "id": 1,
      "prompt": "Generate a Nature cover letter from this LaTeX manuscript: evals/fixtures/generate_fixture.tex.",
      "expected_output": "Route to generate mode, run extract_manuscript_facts.py, synthesize the letter using templates/nature.md plus references/LETTER_STRUCTURE.md, and append an align-check + presubmission block.",
      "files": ["evals/fixtures/generate_fixture.tex"],
      "assertions": [
        {
          "type": "regex",
          "pattern": "(generate|extract_manuscript_facts)",
          "description": "generate mode invoked"
        },
        {
          "type": "regex",
          "pattern": "(Nature|broad scientific|paradigm)",
          "description": "Nature framing used"
        },
        {
          "type": "regex",
          "pattern": "(ALIGNCHECK|PRESUBMISSION|align-check)",
          "description": "default integration verified"
        }
      ]
    },
    {
      "id": 2,
      "prompt": "Polish my draft cover letter at evals/fixtures/optimize_fixture_letter.md for an IEEE TPAMI submission and verify it does not overclaim relative to evals/fixtures/generate_fixture.tex.",
      "expected_output": "Route to optimize mode, run presubmission_check.py + align_check.py, surface AI-tone + opener-cliché + overclaim findings, return diff-style suggestions without overwriting the file.",
      "files": [
        "evals/fixtures/optimize_fixture_letter.md",
        "evals/fixtures/generate_fixture.tex"
      ],
      "assertions": [
        {
          "type": "regex",
          "pattern": "(optimize|presubmission_check|align_check)",
          "description": "optimize mode invoked"
        },
        {
          "type": "regex",
          "pattern": "(AI-tone|opener|cliché|groundbreaking|revolutionary)",
          "description": "AI-tone or cliché finding present"
        },
        {
          "type": "regex",
          "pattern": "\\[Severity:",
          "description": "LaTeX-comment finding format"
        }
      ]
    },
    {
      "id": 3,
      "prompt": "Check whether my cover letter at evals/fixtures/align_check_fixture_letter.md overclaims compared to evals/fixtures/generate_fixture.tex.",
      "expected_output": "Route to align-check mode, run align_check.py, surface unsupported claims (e.g. the $1.2M cost savings or 12 sensor modalities not in manuscript).",
      "files": [
        "evals/fixtures/align_check_fixture_letter.md",
        "evals/fixtures/generate_fixture.tex"
      ],
      "assertions": [
        {
          "type": "regex",
          "pattern": "(align-check|align_check|claim_accuracy|claim_strength)",
          "description": "align-check terms"
        },
        {
          "type": "regex",
          "pattern": "(unsupported|missing|overclaim)",
          "description": "overclaim language present"
        }
      ]
    },
    {
      "id": 4,
      "prompt": "Is this Nature cover letter at evals/fixtures/journal_fit_fixture_letter.md actually framed for Nature, or should I retarget to IEEE TPAMI?",
      "expected_output": "Route to journal-fit mode, run journal_fit_check.py twice (nature, ieee-trans), report per-axis HIGH/MEDIUM/LOW and recommend the better-fit venue.",
      "files": ["evals/fixtures/journal_fit_fixture_letter.md"],
      "assertions": [
        {
          "type": "regex",
          "pattern": "(journal-fit|journal_fit_check|scope_fit|novelty_framing)",
          "description": "journal-fit mode invoked"
        },
        {
          "type": "regex",
          "pattern": "(HIGH|MEDIUM|LOW)",
          "description": "categorical verdict"
        },
        {
          "type": "regex",
          "pattern": "(nature|ieee-trans|tpami)",
          "description": "venue comparison"
        }
      ]
    },
    {
      "id": 5,
      "prompt": "Run a pre-submission check on evals/fixtures/optimize_fixture_letter.md against the NeurIPS template.",
      "expected_output": "Route to presubmission_check.py with --journal neurips, surface AI-tone, opener-cliché, banned-phrase findings; absence of LaTeX label / equation rules.",
      "files": ["evals/fixtures/optimize_fixture_letter.md"],
      "assertions": [
        {
          "type": "regex",
          "pattern": "(presubmission|PRESUBMISSION)",
          "description": "presubmission scope"
        },
        {
          "type": "regex",
          "pattern": "(neurips|dual_submission|reproducibility)",
          "description": "venue-conditional check"
        },
        {
          "type": "not_contains",
          "text": "L4",
          "description": "no equation rule applied"
        }
      ]
    },
    {
      "id": 6,
      "prompt": "Generate a CVPR cover letter from evals/fixtures/generate_fixture.tex, then verify the result against the manuscript before printing.",
      "expected_output": "Two-step run: generate (with CVPR template) → align-check; ensure quantitative anchors trace to manuscript headline_numbers (47% and 2.1x).",
      "files": ["evals/fixtures/generate_fixture.tex"],
      "assertions": [
        {
          "type": "regex",
          "pattern": "(CVPR|cvpr|vision)",
          "description": "CVPR framing"
        },
        {
          "type": "regex",
          "pattern": "(47%|2\\.1x)",
          "description": "manuscript numbers preserved"
        },
        {
          "type": "regex",
          "pattern": "(align-check|ALIGNCHECK)",
          "description": "default verification ran"
        }
      ]
    }
  ]
}

\documentclass[conference]{IEEEtran}
\usepackage{cite}

\title{Adaptive Latency-Aware Inference for Streaming Anomaly Detection}

\author{
  \IEEEauthorblockN{Jia Wei, Sara Patel, Michael Reyes}
  \IEEEauthorblockA{Department of Computer Science, Example University, USA}
}

\begin{document}
\maketitle

\begin{abstract}
We address the problem of anomaly detection on streaming sensor data under
tight latency budgets. We introduce ALAI, an adaptive inference framework that
combines lightweight feature gating with a learned exit policy. On the
SWaT-Stream benchmark, ALAI reduces inference latency by 47\% with no F1
degradation. On WADI-Stream, ALAI matches the F1 of the strongest baseline
while running 2.1x faster. The framework requires no architectural change to
the underlying detector.
\end{abstract}

\section{Introduction}
Industrial monitoring increasingly relies on streaming anomaly detection
\cite{aud24,sl23}. Existing detectors prioritize accuracy and run at
fixed depth regardless of input complexity. We argue that streaming
deployment requires a latency-aware policy that gates computation when the
detector is confident.

\section{Our Contributions}
\begin{itemize}
\item We propose ALAI, an adaptive inference framework that gates intermediate
features in a pretrained streaming anomaly detector based on an exit policy
learned with reinforcement signal.
\item We show that ALAI reduces inference latency by 47\% on SWaT-Stream with
no measurable F1 loss compared to the full-depth detector.
\item We provide an open evaluation protocol on SWaT-Stream and WADI-Stream and
release the gating policy weights.
\end{itemize}

\section{Method}
ALAI consists of a feature gating module and a learned exit head. Section~3
details the training objective; Section~4 the streaming inference loop.

\section{Experiments}
On SWaT-Stream, ALAI achieves F1 of 0.91 against a full-depth baseline of 0.91,
with 47\% latency reduction. On WADI-Stream, ALAI achieves F1 of 0.86 at
2.1x speedup over the strongest baseline.

\section{Discussion}
Our results suggest that streaming anomaly detectors can be made latency-aware
without sacrificing accuracy. We do not claim improvements outside the two
benchmarks tested.

\section{Conclusion}
We presented ALAI, a latency-aware adaptive inference framework for streaming
anomaly detection. ALAI delivers a 47\% latency reduction on SWaT-Stream and a
2.1x speedup on WADI-Stream while matching baseline F1.

\bibliographystyle{IEEEtran}
\bibliography{refs}
\end{document}

\documentclass[conference]{IEEEtran}
\usepackage{cite}

\title{Adaptive Latency-Aware Inference for Streaming Anomaly Detection}

\author{\IEEEauthorblockN{Jia Wei, Sara Patel}
  \IEEEauthorblockA{Department of Computer Science, Example University, USA}}

\begin{document}
\maketitle

% main.tex is an include skeleton — the real content lives in sections/.
\input{sections/abstract}
\input{sections/experiments}

\bibliographystyle{IEEEtran}
\bibliography{refs}
\end{document}

\begin{abstract}
We address anomaly detection on streaming sensor data under tight latency
budgets and introduce ALAI, an adaptive inference framework. On the SWaT-Stream
benchmark, ALAI reduces inference latency by 47\% with no F1 degradation.
\end{abstract}

\section{Experiments}
On SWaT-Stream, ALAI achieves F1 of 0.91 against a full-depth baseline of 0.91,
with a 47\% latency reduction. On WADI-Stream, ALAI achieves F1 of 0.86 at a
2.1x speedup over the strongest baseline.

\documentclass{article}
\usepackage{neurips_2024}

% NeurIPS-style author block: names carry \thanks footnotes, affiliations follow
% on \\-separated lines, and authors are separated by \And. The title carries a
% nested-brace formatting command plus a \thanks funding statement that must NOT
% leak into the extracted title.
\title{Adaptive \textbf{Latency-Aware} Inference for {Streaming} Detection%
  \thanks{This work was supported by NSF grant CCF-12345 and a gift from \emph{Example Corp}.}}

\author{%
  David S.~Hippocampus\thanks{Use footnote for further information about the
  author (webpage, alternative address)---\emph{not} for funding agencies.} \\
  Department of Computer Science \\
  Cranberry-Lemon University \\
  Pittsburgh, PA 15213 \\
  \texttt{hippo@cs.cranberry-lemon.edu} \\
  \And
  Elias D.~Striatum \\
  Department of Electrical Engineering \\
  Mountains State University \\
  \texttt{striate@ee.mountains.edu} \\
}

\begin{document}
\maketitle

\begin{abstract}
We study latency-aware inference for streaming anomaly detection and introduce
an adaptive exit policy that gates computation under tight latency budgets.
\end{abstract}

\section{Introduction}
Streaming deployment requires latency-aware inference.

\end{document}

{
  "skill_name": "cover-letter",
  "queries": [
    {
      "query": "Write me a Nature cover letter for the paper in main.tex.",
      "should_trigger": true,
      "category": "core"
    },
    {
      "query": "Help me draft a submission letter for my IEEE TPAMI manuscript at main.tex.",
      "should_trigger": true,
      "category": "core"
    },
    {
      "query": "Check whether my cover letter overclaims compared to my LaTeX manuscript.",
      "should_trigger": true,
      "category": "core"
    },
    {
      "query": "请帮我给这篇 LaTeX 论文写一份 Nature 投稿信。",
      "should_trigger": true,
      "category": "core"
    },
    {
      "query": "Is this CVPR cover letter framed correctly, or should I retarget to TPAMI?",
      "should_trigger": true,
      "category": "core"
    },
    {
      "query": "Polish my cover_letter.md for a NeurIPS submission, but keep it under 400 words.",
      "should_trigger": true,
      "category": "edge"
    },
    {
      "query": "Run a pre-submission readiness check on my Nature cover letter; what declarations am I missing?",
      "should_trigger": true,
      "category": "edge"
    },
    {
      "query": "I need an editor letter that summarizes the contributions in main.tex without exaggerating.",
      "should_trigger": true,
      "category": "edge"
    },
    {
      "query": "Act as a strict reviewer and write a peer-review report on my paper with major/minor issues.",
      "should_trigger": false,
      "category": "negative-overlap-paper-audit"
    },
    {
      "query": "Gate-check my submission and tell me whether the paper itself is ready to send.",
      "should_trigger": false,
      "category": "negative-overlap-paper-audit"
    },
    {
      "query": "Proofread my IEEE conference paper main.tex and tighten the abstract.",
      "should_trigger": false,
      "category": "negative-overlap-latex-paper-en"
    },
    {
      "query": "Search my references.bib for Mamba forecasting papers after 2024.",
      "should_trigger": false,
      "category": "negative-overlap-bib-search-citation"
    },
    {
      "query": "Help me write a Typst-formatted cover letter from main.typ.",
      "should_trigger": false,
      "category": "negative-typst-unsupported"
    },
    {
      "query": "Draft a tailored cover letter for a software engineer job application at a startup.",
      "should_trigger": false,
      "category": "negative-unrelated"
    },
    {
      "query": "Help me write a vacation request email to my manager.",
      "should_trigger": false,
      "category": "negative-unrelated"
    },
    {
      "query": "Reply to reviewers point-by-point for my rebuttal letter.",
      "should_trigger": false,
      "category": "negative-response-letter-deferred"
    },
    {
      "query": "帮我核对一下投稿信里的主张有没有超出 main.tex 稿件能支持的范围。",
      "should_trigger": true,
      "category": "core"
    },
    {
      "query": "我这封致编辑的信投 IEEE TPAMI 合适吗，还是应该改投会议？",
      "should_trigger": true,
      "category": "core"
    },
    {
      "query": "投稿前帮我预检这封 Nature 投稿信，看缺哪些必需声明。",
      "should_trigger": true,
      "category": "edge"
    },
    {
      "query": "帮我写一封投递互联网大厂算法岗的求职信。",
      "should_trigger": false,
      "category": "negative-unrelated"
    },
    {
      "query": "帮我审一下这篇论文本体能不能投，给出大修小修的审稿意见。",
      "should_trigger": false,
      "category": "negative-overlap-paper-audit"
    }
  ]
}

"""Cross-cutting align-check orchestrator.

Verifies that claims in a cover letter are supported by visible evidence in the
corresponding LaTeX manuscript. Pipes ``extract_manuscript_facts`` →
``build_letter_claim_map`` → ``verify_letter_against_manuscript``, then emits
findings using the simplified cover-letter ISSUE_SCHEMA.

Importable as a module by ``generate`` and ``optimize`` flows:

    from align_check import run_align_check
    issues = run_align_check(letter_path, manuscript_path)
"""

from __future__ import annotations

import argparse
import json
import sys
from dataclasses import asdict, dataclass
from pathlib import Path

from build_letter_claim_map import STRONG_CLAIM_PATTERN, build_claim_map
from extract_manuscript_facts import extract_facts, load_manuscript_text
from verify_letter_against_manuscript import verify_claim_candidates

MODULE = "ALIGNCHECK"

# STRONG_CLAIM_PATTERN is owned by build_letter_claim_map (single source of
# truth) so claim-strength wording and severity classification stay in sync.


@dataclass
class AlignCheckIssue:
    """Cover-letter align-check finding (simplified ISSUE_SCHEMA)."""

    title: str
    quote: str
    explanation: str
    comment_type: str
    severity: str
    priority: str
    source_kind: str
    confidence: str
    source_section: str
    manuscript_section_anchor: str
    evidence_anchor: list[dict[str, str]]
    claim_strength: str
    missing_evidence: list[str]
    allowed_wording: str
    forbidden_wording: list[str]
    quote_verified: bool


def _section_anchor_for_claim(candidate: dict, facts: dict) -> str:
    """Heuristic mapping from claim text to a manuscript section anchor."""
    text = (candidate.get("claim", "") or "").lower()
    anchors = facts.get("section_anchors") or {}
    # Direct hint words → section keys
    hints = [
        ("conclu", "conclusion"),
        ("discuss", "discussion"),
        ("result", "result"),
        ("experiment", "experiment"),
        ("method", "method"),
        ("approach", "method"),
        ("introduction", "introduction"),
        ("background", "introduction"),
        ("abstract", "abstract"),
    ]
    for hint, key in hints:
        if hint in text and key in anchors:
            return key
    # Fallback to whichever section we have most evidence in.
    if "result" in anchors:
        return "result"
    if "abstract" in anchors:
        return "abstract"
    return "none"


def _classify_severity(candidate: dict) -> str:
    strength = candidate.get("claim_strength", "unsupported")
    has_strong_wording = bool(STRONG_CLAIM_PATTERN.search(candidate.get("claim", "") or ""))
    if strength == "unsupported" and has_strong_wording:
        return "major"
    if strength == "unsupported":
        return "moderate"
    if strength == "observed" and has_strong_wording:
        return "moderate"
    if strength == "observed" and not (
        bool(candidate.get("quote_verified")) or bool(candidate.get("manuscript_supported"))
    ):
        return "moderate"
    return "minor"


def _priority_for_severity(severity: str) -> str:
    if severity == "major":
        return "P1"
    if severity == "moderate":
        return "P2"
    return "P3"


def _has_scope_or_wording_risk(candidate: dict) -> bool:
    """Return True when an observed claim still deserves a finding.

    ``observed`` means the letter sentence contains local evidence such as a
    metric. If the same claim is anchored in the manuscript and has no strong
    wording, it is an acceptable cover-letter claim and should not be reported.
    """
    claim = candidate.get("claim", "") or ""
    has_strong_wording = bool(STRONG_CLAIM_PATTERN.search(claim))
    lacks_anchor = not (
        bool(candidate.get("quote_verified")) or bool(candidate.get("manuscript_supported"))
    )
    return has_strong_wording or lacks_anchor


def candidate_to_issue(candidate: dict, facts: dict) -> AlignCheckIssue | None:
    """Convert a verified claim candidate to an AlignCheckIssue."""
    strength = candidate.get("claim_strength")
    if strength == "observed" and not _has_scope_or_wording_risk(candidate):
        return None
    if strength != "unsupported" and strength != "observed":
        return None
    severity = _classify_severity(candidate)
    section_anchor = _section_anchor_for_claim(candidate, facts)
    return AlignCheckIssue(
        title="Cover letter claim lacks manuscript support",
        quote=candidate.get("claim", "")[:280],
        explanation=(
            "The claim sentence in the cover letter could not be matched to a supporting"
            " passage in the manuscript with the same scope, numbers, or evidence anchors."
            " Either soften the wording to match what the manuscript demonstrates, or add"
            " a matching passage to the manuscript."
        ),
        comment_type="claim_accuracy",
        severity=severity,
        priority=_priority_for_severity(severity),
        source_kind="script",
        confidence=candidate.get("confidence", "unverified"),
        source_section="contributions",
        manuscript_section_anchor=section_anchor,
        evidence_anchor=candidate.get("evidence_anchor", []),
        claim_strength=candidate.get("claim_strength", "unsupported"),
        missing_evidence=candidate.get("missing_evidence", []),
        allowed_wording=candidate.get("allowed_wording", ""),
        forbidden_wording=candidate.get("forbidden_wording", []),
        quote_verified=bool(candidate.get("quote_verified")),
    )


def run_align_check(
    letter_path: str | Path,
    manuscript_path: str | Path,
) -> tuple[list[AlignCheckIssue], dict]:
    """Run the full align-check pipeline. Returns ``(issues, claim_map)``."""
    letter_text = Path(letter_path).read_text(encoding="utf-8", errors="replace")
    # Expand \input/\include so a multi-file manuscript (main.tex skeleton) is
    # anchored against its assembled body — otherwise facts come back empty and
    # genuinely-supported letter claims are all mis-reported as unsupported.
    manuscript_text = load_manuscript_text(manuscript_path)

    facts = extract_facts(manuscript_text)
    claim_map = build_claim_map(letter_text, manuscript_facts=facts)
    verified_candidates = verify_claim_candidates(
        claim_map.get("claim_candidates", []),
        manuscript_text,
    )
    claim_map["claim_candidates"] = verified_candidates

    issues: list[AlignCheckIssue] = []
    for candidate in verified_candidates:
        issue = candidate_to_issue(candidate, facts)
        if issue is not None:
            issues.append(issue)
    return issues, claim_map


def _format_protocol_issue(issue: AlignCheckIssue) -> str:
    return (
        f"% {MODULE} [Severity: {issue.severity}] "
        f"[Priority: {issue.priority}] "
        f"[Section: {issue.source_section} → {issue.manuscript_section_anchor}]: "
        f"{issue.title}\n"
        f"% Quote:        {issue.quote}\n"
        f"% Manuscript:   {'verified' if issue.quote_verified else 'not found'}\n"
        f"% Strength:     {issue.claim_strength}\n"
        f"% Allowed:      {issue.allowed_wording[:200]}\n"
    )


def _render_protocol(issues: list[AlignCheckIssue]) -> str:
    return "\n".join(_format_protocol_issue(issue) for issue in issues)


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        description="Align-check a cover letter against a LaTeX manuscript"
    )
    parser.add_argument("--letter", required=True, help="Cover letter path (.md or .tex)")
    parser.add_argument("--manuscript", required=True, help="Manuscript path (.tex)")
    parser.add_argument("--json", action="store_true", help="Emit JSON")
    parser.add_argument(
        "--output",
        "-o",
        help="Optional output path (issues JSON when --json, protocol text otherwise)",
    )
    args = parser.parse_args(argv)

    letter_path = Path(args.letter).resolve()
    manuscript_path = Path(args.manuscript).resolve()
    if not letter_path.exists():
        print(f"File not found: {args.letter}", file=sys.stderr)
        return 2
    if not manuscript_path.exists():
        print(f"File not found: {args.manuscript}", file=sys.stderr)
        return 2
    if manuscript_path.suffix.lower() != ".tex":
        print(
            f"Unsupported manuscript format: {manuscript_path.suffix}; expected .tex",
            file=sys.stderr,
        )
        return 2

    issues, _ = run_align_check(letter_path, manuscript_path)

    if args.json:
        payload = json.dumps([asdict(issue) for issue in issues], indent=2, ensure_ascii=False)
    else:
        payload = _render_protocol(issues)

    if args.output:
        Path(args.output).write_text(payload, encoding="utf-8")
    elif payload:
        print(payload)

    if any(issue.severity == "major" for issue in issues):
        return 2
    if issues:
        return 1
    return 0


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

"""Build a claim map for a cover letter, scored against manuscript evidence.

Adapted from ``paper-audit/scripts/build_claim_map.py``:
* claim patterns retuned for cover-letter style ("we report," "our work demonstrates," ...)
* accepts ``--manuscript-facts facts.json`` so claim_strength reflects evidence
  visible in the manuscript, not just in the letter itself.
"""

from __future__ import annotations

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

LETTER_CLAIM_PATTERNS = (
    r"\bwe (?:report|present|show|demonstrate|find|propose|introduce|describe|provide)\b",
    r"\bour (?:work|study|method|approach|results?|findings?|manuscript|framework|system)\b",
    r"\bthis (?:work|study|paper|manuscript) (?:reports|presents|describes|introduces|demonstrates)\b",
    r"\bthe (?:main|key|central|primary) contribution\b",
    r"\bwe (?:argue|conclude|claim|establish)\b",
    r"\bthe (?:first|only|main) (?:framework|method|approach|tool|system)\b",
    # Sentences that name a concrete metric or improvement — claim-bearing even
    # when subject is not "we" / "our" (common in cover-letter prose):
    r"\b\d+(?:\.\d+)?\s*(?:%|pp|x|×|ms|MB|GB|FLOPs?)\s*.{0,80}\b(?:reduc\w*|improv\w*|speedup|gain|increas\w*|decreas\w*|faster|better|higher|lower)\b",
    r"\b(?:reduc\w*|improv\w*|speedup|gain|increas\w*|decreas\w*|faster|better|higher|lower)\b.{0,80}\b\d+(?:\.\d+)?\s*(?:%|pp|x|×|ms|MB|GB|FLOPs?)",
    # Domain-count and money claims do not always use an improvement verb but
    # still need manuscript support before appearing in a cover letter.
    r"\b\d+(?:\.\d+)?\s+(?:sensor\s+)?modalit(?:y|ies)\b",
    r"(?:\$|USD\s*)\s*\d+(?:\.\d+)?\s*(?:[kKmMbB]|million|billion)?\b",
    # Deployment / production claims that often appear in cover letters but are
    # easy to overshoot relative to manuscripts:
    r"\b(?:has been |was )?deployed (?:in|to|across)\b",
    r"\b(?:cost savings|adopted by|production use|industrial pilot|pilot studies)\b",
)

ANCHOR_PATTERNS = {
    "citation": (
        r"\\cite(?:[a-zA-Z*]+)?(?:\[[^\]]*\]){0,2}\{[^}]+\}",
        r"\[[A-Z][A-Za-z0-9_-]+(?:\d{4})?[^\]]*\]",
        r"\b[A-Z][A-Za-z-]+ et al\.\s*\(?\d{4}\)?",
    ),
    "figure_or_table": (r"\b(?:Fig\.|Figure|Table|Tab\.|Algorithm|Alg\.|Equation|Eq\.)\s*~?\d+",),
    "metric": (
        r"\b\d+(?:\.\d+)?\s*(?:%|pp|x|×|ms|s|MB|GB|FLOPs?)",
        r"\b\d+(?:\.\d+)?\s+(?:sensor\s+)?modalit(?:y|ies)\b",
        r"(?:\$|USD\s*)\s*\d+(?:\.\d+)?\s*(?:[kKmMbB]|million|billion)?\b",
        r"\b(?:accuracy|f1|auc|precision|recall|rmse|mae|latency|throughput|speedup|"
        r"error rate|memory|footprint|cost savings|p\s*[<=>]\s*0\.\d+)\b",
    ),
    "section": (r"\b(?:Section|Sec\.|Appendix)\s*~?\d+",),
}

STRONG_CLAIM_PATTERN = re.compile(
    r"\b("
    r"state-of-the-art|best|outperform|outperforms|superior|significant(?:ly)?|prove|"
    r"guarantee|always|never|all|novel|first|comprehensive|broadly|substantial(?:ly)?"
    r")\b",
    re.IGNORECASE,
)


def split_sentences(text: str) -> list[str]:
    parts = re.split(r"(?<=[.!?])\s+(?=[A-Z0-9\"'])", text.replace("\n", " "))
    return [part.strip() for part in parts if part.strip()]


def extract_claims(text: str, max_items: int | None = None) -> list[str]:
    """Return likely claim-bearing sentences from the cover letter.

    ``max_items=None`` (default) returns every claim sentence so callers can
    report the true total; pass an int to cap the scan.
    """
    claims: list[str] = []
    for sentence in split_sentences(text):
        if any(re.search(p, sentence, re.IGNORECASE) for p in LETTER_CLAIM_PATTERNS):
            claims.append(sentence)
        if max_items is not None and len(claims) >= max_items:
            break
    return claims


def _detect_anchors(text: str) -> list[dict[str, str]]:
    anchors: list[dict[str, str]] = []
    for anchor_type, patterns in ANCHOR_PATTERNS.items():
        for pattern in patterns:
            for match in re.finditer(pattern, text, re.IGNORECASE):
                anchors.append({"type": anchor_type, "text": match.group(0)})
    return anchors


def _claim_strength_local(anchors: list[dict[str, str]]) -> str:
    """Claim strength based on local anchors visible inside the sentence."""
    anchor_types = {anchor["type"] for anchor in anchors}
    if {"metric", "figure_or_table"} <= anchor_types:
        return "strong"
    if "metric" in anchor_types:
        return "observed"
    if anchors:
        return "supported"
    return "unsupported"


def _manuscript_supports(
    sentence: str,
    manuscript_facts: dict | None,
) -> tuple[bool, list[dict[str, str]]]:
    """Check whether the manuscript facts blob supports the claim.

    Returns ``(supported, evidence_anchors)``. ``supported`` is True when at
    least one numeric token or contribution string from the manuscript appears
    in the claim sentence, indicating the letter's claim has a matching
    statement in the manuscript.
    """
    if not manuscript_facts:
        return False, []
    anchors: list[dict[str, str]] = []
    lowered = sentence.lower()
    sent_str = " ".join(re.findall(r"\b[\w'-]+\b", lowered))
    # Check headline numbers
    for number in manuscript_facts.get("headline_numbers", []):
        if number.lower() in lowered:
            anchors.append({"type": "metric", "text": number})
    # Check contribution overlap: any shared 4-gram counts as support.
    for contribution in manuscript_facts.get("contributions", []):
        contrib_tokens = re.findall(r"\b[\w'-]+\b", contribution.lower())
        if len(contrib_tokens) < 4:
            continue
        for i in range(len(contrib_tokens) - 3):
            fragment = " ".join(contrib_tokens[i : i + 4])
            if fragment in sent_str:
                anchors.append({"type": "section", "text": contribution[:80]})
                break
    return bool(anchors), anchors


def _missing_evidence(sentence: str, anchors: list[dict[str, str]], supported: bool) -> list[str]:
    if supported:
        return []
    if STRONG_CLAIM_PATTERN.search(sentence):
        return [
            "Strong wording in cover letter; manuscript does not visibly support this claim."
            " Soften, narrow scope, or add a matching statement to the manuscript."
        ]
    if not anchors:
        return ["Add a manuscript-anchored figure, table, metric, or section reference."]
    return []


def _allowed_wording(sentence: str, supported: bool) -> str:
    if supported:
        return sentence

    softened = sentence
    softened = re.sub(
        r"\b(?:with )?reported cost savings of (?:\$|USD\s*)\s*\d+(?:\.\d+)?\s*(?:[kKmMbB]|million|billion)?(?:\s+per\s+\w+)?",
        "with potential operational implications that should be described without a dollar amount unless the manuscript reports it",
        softened,
        flags=re.IGNORECASE,
    )
    softened = re.sub(
        r"\b(?:\$|USD\s*)\s*\d+(?:\.\d+)?\s*(?:[kKmMbB]|million|billion)?\b",
        "a manuscript-supported cost estimate",
        softened,
        flags=re.IGNORECASE,
    )
    softened = re.sub(
        r"\b(?:has been |was )?deployed (?:in|to|across) [^.;]+",
        "was evaluated in the manuscript's reported experimental setting",
        softened,
        flags=re.IGNORECASE,
    )
    softened = re.sub(
        r"\bachieves a \d+(?:\.\d+)?\s*(?:%|pp)\s+reduction in memory footprint\b",
        "shows lower memory use in the evaluated setting",
        softened,
        flags=re.IGNORECASE,
    )
    softened = re.sub(
        r"\b\d+(?:\.\d+)?\s*(?:%|pp)\s+reduction in memory footprint\b",
        "lower memory use in the evaluated setting",
        softened,
        flags=re.IGNORECASE,
    )
    softened = re.sub(
        r"\bsupports \d+(?:\.\d+)?\s+(?:sensor\s+)?modalit(?:y|ies)(?: including [^.;]+)?",
        "was evaluated on the manuscript-reported sensor streams",
        softened,
        flags=re.IGNORECASE,
    )
    softened = re.sub(
        r"\bstate-of-the-art\b",
        "improved in the reported setting",
        softened,
        flags=re.IGNORECASE,
    )
    softened = re.sub(
        r"\b(?:outperforms|surpasses) (?:all\s+)?prior(?: work)?\b",
        "improves over the evaluated baselines",
        softened,
        flags=re.IGNORECASE,
    )
    softened = re.sub(
        r"\b(?:significantly|substantially)\b",
        "measurably",
        softened,
        flags=re.IGNORECASE,
    )
    softened = re.sub(
        r"\bthe first\b",
        "to our knowledge the first",
        softened,
        flags=re.IGNORECASE,
    )
    return softened


def _forbidden_wording(sentence: str, supported: bool) -> list[str]:
    if supported:
        return []
    forbidden = []
    if STRONG_CLAIM_PATTERN.search(sentence):
        forbidden.append("unbounded superiority, novelty, or significance wording")
    return forbidden or ["unqualified conclusion without manuscript-visible evidence"]


def build_claim_candidate(
    sentence: str,
    index: int,
    manuscript_facts: dict | None,
) -> dict:
    """Build an additive claim candidate record."""
    local_anchors = _detect_anchors(sentence)
    supported, m_anchors = _manuscript_supports(sentence, manuscript_facts)
    all_anchors = local_anchors + m_anchors
    local_strength = _claim_strength_local(local_anchors)
    # If manuscript supports, upgrade strength when local was lower
    if supported and local_strength == "unsupported":
        strength = "supported"
    elif supported and local_strength == "supported":
        strength = "strong"
    else:
        strength = local_strength

    return {
        "id": f"letter:{index + 1}",
        "section_key": "letter",
        "claim": sentence,
        "evidence_anchor": all_anchors,
        "claim_strength": strength,
        "missing_evidence": _missing_evidence(sentence, all_anchors, supported),
        "allowed_wording": _allowed_wording(sentence, supported),
        "forbidden_wording": _forbidden_wording(sentence, supported),
        "manuscript_supported": supported,
    }


def build_claim_map(letter_text: str, manuscript_facts: dict | None, max_items: int = 12) -> dict:
    """Build the cover letter claim map.

    Detailed candidates are capped at ``max_items`` to bound work, but the full
    claim-sentence count is reported via ``total_claim_sentences`` and
    ``truncated`` so nothing is silently dropped (claims beyond the cap still
    surface as a count for the caller to act on).
    """
    all_claims = extract_claims(letter_text)
    total = len(all_claims)
    claims = all_claims[:max_items]
    candidates = [
        build_claim_candidate(claim, index=i, manuscript_facts=manuscript_facts)
        for i, claim in enumerate(claims)
    ]
    return {
        "letter_claims": claims,
        "claim_candidates": candidates,
        "total_claim_sentences": total,
        "truncated": total > max_items,
        "manuscript_supported_count": sum(1 for c in candidates if c.get("manuscript_supported")),
        "unsupported_count": sum(1 for c in candidates if c.get("claim_strength") == "unsupported"),
    }


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        description="Build a cover-letter claim map against manuscript evidence"
    )
    parser.add_argument("letter", help="Path to cover letter (.md or .tex)")
    parser.add_argument(
        "--manuscript-facts",
        help="Path to facts.json emitted by extract_manuscript_facts.py",
    )
    parser.add_argument("--output", "-o", help="Optional output path")
    args = parser.parse_args(argv)

    letter_path = Path(args.letter).resolve()
    if not letter_path.exists():
        print(f"File not found: {args.letter}", file=sys.stderr)
        return 2

    letter_text = letter_path.read_text(encoding="utf-8", errors="replace")

    manuscript_facts = None
    if args.manuscript_facts:
        facts_path = Path(args.manuscript_facts).resolve()
        if not facts_path.exists():
            print(f"Manuscript facts file not found: {args.manuscript_facts}", file=sys.stderr)
            return 2
        manuscript_facts = json.loads(facts_path.read_text(encoding="utf-8"))

    claim_map = build_claim_map(letter_text, manuscript_facts)
    payload = json.dumps(claim_map, indent=2, ensure_ascii=False)

    if args.output:
        Path(args.output).write_text(payload, encoding="utf-8")
    else:
        print(payload)

    return 1 if claim_map["unsupported_count"] > 0 else 0


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

"""Unified CLI for the cover-letter skill.

This is a lightweight orchestration wrapper around the existing deterministic
scripts. The single-purpose scripts remain supported; this entry point gives
the skill documentation one stable command surface:

    cover_letter.py --mode align-check --manuscript main.tex --letter cover.md --json
"""

from __future__ import annotations

import argparse
import json
import sys
from dataclasses import asdict, is_dataclass
from pathlib import Path
from typing import Any

from align_check import run_align_check
from extract_manuscript_facts import extract_facts, load_manuscript_text
from journal_fit_check import VENUES, findings_from_result, run_journal_fit
from presubmission_check import run_checks
from template_meta import load_template_meta

MODES = ("generate", "optimize", "align-check", "journal-fit", "presubmission")


def _jsonable(value: Any) -> Any:
    if is_dataclass(value) and not isinstance(value, type):
        return asdict(value)
    if isinstance(value, list):
        return [_jsonable(item) for item in value]
    if isinstance(value, dict):
        return {key: _jsonable(item) for key, item in value.items()}
    return value


def _exit_code(findings: list[Any]) -> int:
    severities = {
        str(getattr(finding, "severity", "") or finding.get("severity", "")).lower()
        for finding in findings
    }
    if "major" in severities:
        return 2
    if findings:
        return 1
    return 0


def _render_findings(findings: list[Any]) -> str:
    lines: list[str] = []
    for finding in findings:
        item = _jsonable(finding)
        code = item.get("code") or item.get("axis") or item.get("comment_type", "finding")
        title = item.get("title") or item.get("message") or "Cover-letter finding"
        lines.append(
            "% COVERLETTER "
            f"[Severity: {item.get('severity', 'minor')}] "
            f"[Priority: {item.get('priority', 'P3')}] "
            f"[Source: {item.get('source_kind', 'script')}] "
            f"[Type: {item.get('comment_type', 'presentation')}] "
            f"[{code}]: {title}"
        )
    return "\n".join(lines)


def _draft_cover_letter(facts: dict[str, Any], journal: str) -> str:
    title = facts.get("title") or "[Manuscript title to be confirmed]"
    corresponding_author = facts.get("corresponding_author") or "[Corresponding author]"
    contributions = facts.get("contributions") or []
    contribution_lines = "\n".join(f"- {item}" for item in contributions[:3])
    if not contribution_lines:
        contribution_lines = "- [Key contribution to be confirmed from manuscript]"

    return (
        "Dear Editor,\n\n"
        f'We submit "{title}" for consideration at {journal}. '
        "The manuscript presents the following evidence-backed contributions:\n\n"
        f"{contribution_lines}\n\n"
        "The manuscript has not been published elsewhere and is not under concurrent "
        "consideration. All authors have approved the submission. "
        "[Competing interests / data availability details to be confirmed against the "
        "target journal template.]\n\n"
        f"Sincerely,\n{corresponding_author}\n"
    )


def _require_path(value: str | None, flag: str, *, must_exist: bool = True) -> Path:
    if not value:
        raise ValueError(f"Missing required {flag}")
    path = Path(value).resolve()
    if must_exist and not path.exists():
        raise FileNotFoundError(f"File not found for {flag}: {value}")
    return path


def _run_generate(args: argparse.Namespace, journal: str) -> tuple[dict[str, Any], int]:
    manuscript = _require_path(args.manuscript, "--manuscript")
    if manuscript.suffix.lower() != ".tex":
        raise ValueError(f"Unsupported manuscript format: {manuscript.suffix}; expected .tex")
    facts = extract_facts(load_manuscript_text(manuscript))
    # Address the venue by its display name ("IEEE Transactions"), not the slug.
    skill_dir = Path(__file__).resolve().parent.parent
    meta = load_template_meta(skill_dir, journal) or {}
    venue_name = str(meta.get("venue") or journal)
    draft = _draft_cover_letter(facts, venue_name)
    missing = [key for key in ("title", "abstract") if not facts.get(key)]
    findings = [
        {
            "title": f"Manuscript fact `{key}` could not be extracted",
            "quote": "",
            "explanation": "Generation uses a placeholder until the missing field is confirmed.",
            "comment_type": "presentation",
            "severity": "minor",
            "priority": "P3",
            "source_kind": "script",
            "source_section": "opening",
        }
        for key in missing
    ]
    payload = {
        "mode": "generate",
        "journal": journal,
        "manuscript": str(manuscript),
        "facts": facts,
        "draft": draft,
        "findings": findings,
    }
    return payload, _exit_code(findings)


def _run_align_check(args: argparse.Namespace) -> tuple[dict[str, Any], int]:
    manuscript = _require_path(args.manuscript, "--manuscript")
    letter = _require_path(args.letter, "--letter")
    issues, claim_map = run_align_check(letter, manuscript)
    payload = {
        "mode": "align-check",
        "manuscript": str(manuscript),
        "letter": str(letter),
        "claim_map": claim_map,
        "findings": _jsonable(issues),
    }
    return payload, _exit_code(payload["findings"])


def _run_presubmission(args: argparse.Namespace, journal: str) -> tuple[dict[str, Any], int]:
    letter = _require_path(args.letter, "--letter")
    skill_dir = Path(__file__).resolve().parent.parent
    issues = run_checks(letter, journal=journal, skill_dir=skill_dir)
    payload = {
        "mode": "presubmission",
        "journal": journal,
        "letter": str(letter),
        "findings": _jsonable(issues),
    }
    return payload, _exit_code(payload["findings"])


def _run_journal_fit(args: argparse.Namespace, journal: str) -> tuple[dict[str, Any], int]:
    letter = _require_path(args.letter, "--letter")
    skill_dir = Path(__file__).resolve().parent.parent
    result = run_journal_fit(letter, journal, skill_dir)
    findings = findings_from_result(result)
    payload = {
        "mode": "journal-fit",
        "journal": journal,
        "letter": str(letter),
        "journal_fit": {
            "venue": result.venue,
            "tier": result.tier,
            "overall": result.overall,
            "axes": _jsonable(result.axes),
        },
        "findings": _jsonable(findings),
    }
    if result.overall == "LOW":
        return payload, 2
    if result.overall == "MEDIUM":
        return payload, max(1, _exit_code(payload["findings"]))
    return payload, _exit_code(payload["findings"])


def _run_optimize(args: argparse.Namespace, journal: str) -> tuple[dict[str, Any], int]:
    presub_payload, _ = _run_presubmission(args, journal)
    findings = list(presub_payload["findings"])
    claim_map: dict[str, Any] | None = None
    manuscript_path = None
    if args.manuscript:
        align_payload, _ = _run_align_check(args)
        findings.extend(align_payload["findings"])
        claim_map = align_payload["claim_map"]
        manuscript_path = align_payload["manuscript"]
    payload = {
        "mode": "optimize",
        "journal": journal,
        "letter": presub_payload["letter"],
        "manuscript": manuscript_path,
        "claim_map": claim_map,
        "findings": findings,
    }
    return payload, _exit_code(findings)


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="Unified cover-letter CLI: generate, optimize, align-check, journal-fit, or presubmission"
    )
    parser.add_argument("--mode", required=True, choices=MODES)
    parser.add_argument("--manuscript", help="LaTeX manuscript path (.tex)")
    parser.add_argument("--letter", help="Cover letter path (.md or .tex)")
    parser.add_argument(
        "--journal",
        "--venue",
        dest="journal",
        default="generic",
        choices=sorted(VENUES),
        help="Target bundled template / venue",
    )
    parser.add_argument("--json", action="store_true", help="Emit structured JSON")
    return parser


def main(argv: list[str] | None = None) -> int:
    parser = build_parser()
    args = parser.parse_args(argv)
    journal = args.journal or "generic"

    try:
        if args.mode == "generate":
            payload, code = _run_generate(args, journal)
        elif args.mode == "align-check":
            payload, code = _run_align_check(args)
        elif args.mode == "presubmission":
            payload, code = _run_presubmission(args, journal)
        elif args.mode == "journal-fit":
            payload, code = _run_journal_fit(args, journal)
        else:
            payload, code = _run_optimize(args, journal)
    except (FileNotFoundError, ValueError) as exc:
        print(str(exc), file=sys.stderr)
        return 2

    if args.json:
        print(json.dumps(payload, indent=2, ensure_ascii=False))
    elif args.mode == "generate":
        print(payload["draft"])
        rendered = _render_findings(payload["findings"])
        if rendered:
            print("\n" + rendered)
    else:
        rendered = _render_findings(payload["findings"])
        if rendered:
            print(rendered)

    return code


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

"""Extract structured facts from a LaTeX manuscript for cover-letter generation.

Emits a JSON facts blob consumed by ``generate`` mode (via SKILL.md guidance to
Claude) and by ``align_check.py`` (as the manuscript anchor set).

The extractor is deterministic: regex-based, no LLM calls. Best-effort across
common LaTeX templates (article, IEEEtran, ACM acmart, NeurIPS neurips,
Springer LNCS llncs).
"""

from __future__ import annotations

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

from parsers import (
    LatexParser,
    _extract_balanced_block,
    _strip_latex_markup,
    extract_abstract,
    extract_latex_citation_keys,
)
from tex_loader import assemble

# Author command prefixes across common LaTeX templates. We locate the command,
# then balanced-brace-capture its argument so that nested ``\thanks{...}`` (with
# its own braces) does not truncate the author block (the old ``[^}]+`` regex
# stopped at the first ``}`` inside ``\thanks``, dropping every author).
# IEEE: \IEEEauthorblockN{Name} / \IEEEauthorblockA{Affil}
# ACM acmart: \author{Name} ... \affiliation{...} ...
# NeurIPS: \author{Name1\thanks{...} \\ Affil}
# Article: \author{Name1 \and Name2}
AUTHOR_COMMAND_PREFIXES: tuple[str, ...] = (
    r"\\IEEEauthorblockN",
    r"\\author(?:\[[^\]]*\])?",
    r"\\authorinfo",
)

# Only an explicit corresponding-author command is trusted. The previous
# free-text fallback (``corresponding author: <name>``) reached into
# ``\thanks{Corresponding author: a@u.edu}`` and reported the email local part
# as a fabricated author, so it is intentionally removed; we fall back to the
# first extracted author instead.
CORRESPONDING_AUTHOR_PATTERNS: tuple[str, ...] = (r"\\corresponding(?:author)?\s*\{([^}]+)\}",)

CONTRIBUTIONS_HEADER_PATTERNS: tuple[str, ...] = (
    r"\\(?:sub)?section\*?\{(?:Our )?Contributions?\}",
    r"\\(?:sub)?section\*?\{Main\s+Contributions?\}",
    r"\\(?:sub)?section\*?\{Summary\s+of\s+Contributions?\}",
    r"\\paragraph\*?\{(?:Our )?Contributions?\}",
)

INLINE_CONTRIBUTIONS_PATTERNS: tuple[str, ...] = (
    r"(?:Our|The)\s+(?:main\s+|primary\s+)?contributions?\s+(?:are|include)\s*[:\.]",
    r"(?:In\s+summary|To\s+summarize),?\s+(?:our|the\s+main)\s+contributions?",
)


def load_manuscript_text(path: str | Path) -> str:
    """Read a manuscript, expanding ``\\input`` / ``\\include`` via tex_loader.

    Real papers often keep ``main.tex`` as an include skeleton; without assembly
    the facts blob comes back empty and align-check mis-reports every supported
    claim. ``assemble`` also applies the robust encoding fallback, so this works
    for single-file manuscripts too.
    """
    return assemble(Path(path)).content


def _clean(text: str) -> str:
    """Light cleanup: strip LaTeX commands but keep references like \\cite intact placeholder."""
    cleaned = re.sub(r"\\textbf\{([^}]*)\}", r"\1", text)
    cleaned = re.sub(r"\\emph\{([^}]*)\}", r"\1", cleaned)
    cleaned = re.sub(r"\\textit\{([^}]*)\}", r"\1", cleaned)
    cleaned = re.sub(r"\\\\", " ", cleaned)
    cleaned = re.sub(r"\\and\b", ",", cleaned)
    cleaned = re.sub(r"\\thanks\{[^}]*\}", "", cleaned)
    cleaned = re.sub(r"\\footnote\{[^}]*\}", "", cleaned)
    cleaned = cleaned.replace("~", " ")
    cleaned = re.sub(r"\s+", " ", cleaned)
    return cleaned.strip()


def _strip_balanced_commands(text: str, commands: tuple[str, ...]) -> str:
    """Remove ``\\<command>{...}`` spans with balanced-brace bodies.

    Unlike a ``\\thanks\\{[^}]*\\}`` regex, this also removes footnote/thanks
    blocks whose body contains nested braces (e.g. ``\\thanks{\\emph{x}}``),
    which would otherwise leak affiliation or funding text into the author /
    title fields.
    """
    for command in commands:
        opener = re.compile(r"\\" + command + r"\s*\{")
        while True:
            match = opener.search(text)
            if not match:
                break
            brace_idx = match.end() - 1
            body = _extract_balanced_block(text, brace_idx, "{", "}")
            end = brace_idx + len(body) + 2  # skip the opening '{' and closing '}'
            text = text[: match.start()] + " " + text[end:]
    return text


def _balanced_author_blocks(content: str) -> list[str]:
    """Return the balanced-brace argument of each author command in the source."""
    blocks: list[str] = []
    for prefix in AUTHOR_COMMAND_PREFIXES:
        for match in re.finditer(prefix + r"\s*\{", content):
            brace_idx = match.end() - 1
            block = _extract_balanced_block(content, brace_idx, "{", "}")
            if block:
                blocks.append(block)
    return blocks


def extract_authors(content: str) -> list[str]:
    """Extract author names from a LaTeX manuscript.

    Author blocks are captured with balanced braces, ``\\thanks`` / ``\\footnote``
    are stripped first, then each ``\\and``-separated group contributes the text
    before its first ``\\\\`` line break (the name line; affiliations follow on
    later lines). ``\\IEEEauthorblockN`` lists several comma-separated names on
    one line.
    """
    candidates: list[str] = []
    for block in _balanced_author_blocks(content):
        # IEEE wraps the names in \IEEEauthorblockN sub-blocks (captured by their
        # own prefix); skip the outer \author{...} wrapper so its \IEEEauthorblockA
        # affiliation does not leak in as a fake author.
        if r"\IEEEauthorblockN" in block:
            continue
        block = re.sub(r"(?<!\\)%.*", "", block)  # drop line comments (e.g. \author{%)
        stripped = _strip_balanced_commands(block, ("thanks", "footnote"))
        for group in re.split(r"\\[aA]nd\b", stripped):
            name_line = re.split(r"\\\\", group)[0]
            for raw in re.split(r",", name_line):
                name = _clean(raw)
                if not name or "\\" in name or "{" in name or "}" in name:
                    continue
                if len(name.split()) >= 2 and name not in candidates:
                    candidates.append(name)
    return candidates


def extract_corresponding_author(content: str, authors: list[str]) -> str:
    """Corresponding author from an explicit command; falls back to first author.

    No free-text fallback: scraping ``corresponding author: ...`` reached into
    ``\\thanks`` blocks and reported email local parts as fabricated authors.
    """
    for pattern in CORRESPONDING_AUTHOR_PATTERNS:
        match = re.search(pattern, content, flags=re.IGNORECASE)
        if match:
            name = _clean(match.group(1))
            if name and "@" not in name:
                return name
    return authors[0] if authors else ""


def _extract_itemized(text: str, max_items: int = 5) -> list[str]:
    items: list[str] = []
    # \begin{itemize}\item ...\item ...\end{itemize}
    env = re.search(
        r"\\begin\{(?:itemize|enumerate)\}(.*?)\\end\{(?:itemize|enumerate)\}",
        text,
        flags=re.DOTALL,
    )
    if env:
        for raw in re.findall(r"\\item\s+(.+?)(?=\\item|\\end\{)", env.group(1), flags=re.DOTALL):
            cleaned = _clean(raw)
            if cleaned:
                items.append(cleaned)
            if len(items) >= max_items:
                break
    return items


def extract_contributions(content: str, max_items: int = 5) -> list[str]:
    """Extract contributions list from a LaTeX manuscript.

    Strategy: find a section/paragraph heading that names "Contributions," then
    look for an itemize/enumerate block inside the following ~2000 characters.
    Falls back to inline patterns like ``Our main contributions are: (1) ... (2) ...``.
    """
    items: list[str] = []
    for pattern in CONTRIBUTIONS_HEADER_PATTERNS:
        match = re.search(pattern, content, flags=re.IGNORECASE)
        if not match:
            continue
        window = content[match.end() : match.end() + 2500]
        items.extend(_extract_itemized(window, max_items=max_items))
        if items:
            return items[:max_items]

    # Inline numbered contributions: "Our main contributions are: (1) ...; (2) ...; (3) ..."
    for pattern in INLINE_CONTRIBUTIONS_PATTERNS:
        match = re.search(pattern, content, flags=re.IGNORECASE)
        if not match:
            continue
        window = content[match.end() : match.end() + 1500]
        numbered = re.findall(r"\(\d+\)\s+([^.;]+?[.;])", window)
        for item in numbered:
            cleaned = _clean(item.rstrip(".;"))
            if cleaned and cleaned not in items:
                items.append(cleaned)
            if len(items) >= max_items:
                break
        if items:
            return items[:max_items]

    return items


def extract_section_anchors(content: str) -> dict[str, tuple[int, int]]:
    """Return section names and their line ranges (via LatexParser.split_sections)."""
    parser = LatexParser()
    return parser.split_sections(content)


def _extract_title_local(content: str) -> str:
    """Extract the LaTeX title with balanced braces, stripping ``\\thanks``.

    ``parsers.extract_title`` still uses a non-greedy ``\\{(.+?)\\}`` that
    truncates nested-brace titles and leaks ``\\thanks`` funding statements into
    the letter opening. The cover-letter facts blob needs an accurate, clean
    title, so it is captured locally (parsers.py is owned by the en-family
    foundation task and is out of scope here).
    """
    match = re.search(r"\\title(?:\[[^\]]*\])?\s*\{", content)
    if not match:
        return ""
    body = _extract_balanced_block(content, match.end() - 1, "{", "}")
    if not body:
        return ""
    body = _strip_balanced_commands(body, ("thanks", "footnote"))
    return _strip_latex_markup(body)


def extract_facts(content: str) -> dict:
    """Build the manuscript facts blob."""
    title = _extract_title_local(content)
    abstract = extract_abstract(content)
    authors = extract_authors(content)
    corresponding = extract_corresponding_author(content, authors)
    contributions = extract_contributions(content)
    sections = extract_section_anchors(content)
    citations = sorted(extract_latex_citation_keys(content))

    # Headline numeric tokens (for cover-letter quantitative anchor lookup).
    # Accept either bare "47%" or LaTeX-escaped "47\%". No trailing \b because
    # `%` is a non-word character so the boundary would never satisfy.
    number_patterns = (
        r"\b\d+(?:\.\d+)?\s*(?:\\?%|pp|x|×|ms|MB|GB|FLOPs?)",
        r"(?:\$|USD\s*)\s*\d+(?:\.\d+)?\s*(?:[kKmMbB]|million|billion)?\b",
        r"\b\d+(?:\.\d+)?\s+(?:sensor\s+)?modalit(?:y|ies)\b",
    )
    numbers: list[str] = []
    for pattern in number_patterns:
        numbers.extend(re.findall(pattern, content, flags=re.IGNORECASE))
    # Normalize the LaTeX escape so downstream consumers can substring-match.
    unique_numbers = sorted({n.replace("\\", "") for n in numbers})[:20]

    return {
        "title": title,
        "abstract": abstract,
        "authors": authors,
        "corresponding_author": corresponding,
        "contributions": contributions,
        "section_anchors": {
            key: {"start_line": start, "end_line": end} for key, (start, end) in sections.items()
        },
        "citation_keys": citations,
        "headline_numbers": unique_numbers,
    }


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        description="Extract manuscript facts (title, abstract, authors, contributions) from .tex"
    )
    parser.add_argument("tex_file", help=".tex manuscript file")
    parser.add_argument("--output", "-o", help="Optional output JSON path")
    args = parser.parse_args(argv)

    path = Path(args.tex_file).resolve()
    if not path.exists():
        print(f"File not found: {args.tex_file}", file=sys.stderr)
        return 2
    if path.suffix.lower() != ".tex":
        print(f"Unsupported format: {path.suffix}; expected .tex", file=sys.stderr)
        return 2

    content = load_manuscript_text(path)
    facts = extract_facts(content)
    payload = json.dumps(facts, indent=2, ensure_ascii=False)

    if args.output:
        Path(args.output).write_text(payload, encoding="utf-8")
    else:
        print(payload)

    # Return non-zero when key facts are missing (so calling skill can flag).
    missing_keys = [k for k in ("title", "abstract") if not facts.get(k)]
    return 1 if missing_keys else 0


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