Content Refinement Agent

#!/usr/bin/env python3
"""
apply_worklog.py — Append a timestamped iteration entry to worklog.json.

The worklog is the canonical history of the refinement loop: every
iteration's review, score, decision, and actions taken. The orchestrator
reads it at the end to identify the best snapshot to promote.

Usage:
    python apply_worklog.py \\
        --worklog workspace/refinement/worklog.json \\
        --iter 2 \\
        --review iter2/review.json \\
        --score iter2/score.json \\
        --decision ACCEPT_IMPROVED \\
        --actions iter2/worklog_entry.json   # the agent's emitted worklog block

The script creates worklog.json if it doesn't exist.
"""
import argparse
import datetime as dt
import json
import os
import sys


def load_json(path: str | None) -> dict | list | None:
    if not path or not os.path.exists(path):
        return None
    with open(path) as f:
        return json.load(f)


def main() -> int:
    p = argparse.ArgumentParser(description=__doc__)
    p.add_argument("--worklog", required=True, help="path to worklog.json")
    p.add_argument("--iter", type=int, required=True, help="iteration number (0-indexed)")
    p.add_argument("--review", help="path to review.json for this iteration")
    p.add_argument("--score", help="path to score.json for this iteration")
    p.add_argument("--decision", required=True,
                   help="ACCEPT_IMPROVED / ACCEPT_TIED_NON_NEGATIVE / "
                        "REVERT_OVERALL_DECREASED / REVERT_TIED_NEGATIVE_SUBAXIS")
    p.add_argument("--actions", help="path to the agent's worklog block JSON "
                                     "(addressed_weaknesses, integrated_answers, actions_taken)")
    p.add_argument("--halted-because", help="reason if this iteration triggers a halt")
    args = p.parse_args()

    if os.path.exists(args.worklog):
        with open(args.worklog) as f:
            wl = json.load(f)
    else:
        wl = {"iterations": [], "halted_because": None, "best_iter": None}

    entry = {
        "iter": args.iter,
        "timestamp": dt.datetime.now(dt.timezone.utc).isoformat(),
        "decision": args.decision,
        "review": load_json(args.review),
        "score": load_json(args.score),
        "actions": load_json(args.actions),
    }
    wl["iterations"].append(entry)

    if args.halted_because:
        wl["halted_because"] = args.halted_because

    # Re-compute best_iter: highest accepted overall_score
    accepted = [
        it for it in wl["iterations"]
        if it.get("decision", "").startswith("ACCEPT") and it.get("score")
    ]
    if accepted:
        best = max(accepted, key=lambda it: it["score"].get("overall_score", 0))
        wl["best_iter"] = best["iter"]

    os.makedirs(os.path.dirname(os.path.abspath(args.worklog)) or ".", exist_ok=True)
    with open(args.worklog, "w") as f:
        json.dump(wl, f, indent=2, ensure_ascii=False)

    print(f"OK: appended iter {args.iter} ({args.decision}) to {args.worklog}")
    if wl["best_iter"] is not None:
        print(f"    current best_iter: {wl['best_iter']}")
    return 0


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

#!/usr/bin/env python3
"""
concession_guard.py — Enforce the Devil's Advocate concession-threshold protocol
deterministically (references/da-reviewer.md).

The DA reviewer challenges the paper's core claims. A simulated reviewer left to
its own devices tends to *cave*: it concedes an attack as soon as the author
pushes back, even when the rebuttal is weak — sycophancy that defeats the point
of an adversarial reviewer. This script makes the protocol non-negotiable by
checking the DA's concession log against two hard rules, so the LLM cannot quietly
relax them:

  Rule 1 — Concession requires evidence.
      A finding may be conceded only if its rebuttal_score is >= 4 (the protocol's
      "rebuttal directly / strongly addresses the attack with evidence"). Conceding
      at rebuttal_score <= 3 is caving: the concession is REJECTED and the finding
      is restored to "standing".

  Rule 2 — No consecutive concessions (IRON RULE).
      The DA may make at most one valid concession per two review rounds.
      A concession in a round immediately following another conceding round is
      REJECTED and the finding is restored to "standing".

A CRITICAL finding that is still standing after these rules (not resolved by the
revision, and not validly conceded) BLOCKS the "refinement accepted" decision —
the host must treat the iteration as REVERT, regardless of rubric scores.

Concession log schema (--log):
    {
      "rounds": [
        {
          "round": 1,
          "findings": [
            {
              "id": "F1",
              "severity": "critical" | "major" | "minor",
              "attack": "Causal overclaiming: Sec 4 says X *causes* Y from corr only.",
              "rebuttal_score": 2,      # 1-5, DA's score of the author's rebuttal
              "conceded": false,        # did the DA drop the attack this round?
              "resolved": false         # was the underlying issue fixed in the revision?
            }
          ]
        }
      ]
    }

Usage:
    python concession_guard.py --log workspace/refinement/da_concessions.json
    python concession_guard.py --log da_concessions.json --out guard_report.json

Exit codes:
    0  CLEAR — no standing critical, no protocol violations → accept may proceed
    1  BLOCK — a critical finding is still standing → host must REVERT this iteration
    2  WARN  — protocol violation(s) found but no critical blocked → DA must restate;
              the rejected concession does not by itself force a revert
    3  input / schema error
"""
import argparse
import json
import sys

VALID_SEVERITY = {"critical", "major", "minor"}
CONCESSION_MIN_REBUTTAL = 4  # rebuttal_score >= this to allow a concession


def analyze(rounds: list) -> dict:
    violations = []
    valid_concessions = []
    standing_criticals = []
    last_conceded_round = None  # round index of the previous *valid* concession

    for r in rounds:
        rnum = r.get("round")
        conceded_this_round = False
        for fnd in r.get("findings", []):
            fid = fnd.get("id", "?")
            sev = fnd.get("severity", "minor")
            conceded = bool(fnd.get("conceded", False))
            resolved = bool(fnd.get("resolved", False))
            score = fnd.get("rebuttal_score")

            concession_valid = False
            if conceded:
                # Rule 1 — evidence threshold
                if score is None or score < CONCESSION_MIN_REBUTTAL:
                    violations.append({
                        "round": rnum, "id": fid, "type": "caving",
                        "detail": f"conceded at rebuttal_score={score} "
                                  f"(< {CONCESSION_MIN_REBUTTAL}); concession rejected",
                    })
                # Rule 2 — no consecutive concessions
                elif last_conceded_round is not None and rnum == last_conceded_round + 1:
                    violations.append({
                        "round": rnum, "id": fid, "type": "consecutive_concession",
                        "detail": f"concession in round {rnum} immediately follows a "
                                  f"concession in round {last_conceded_round}; "
                                  f"rejected (max one per two rounds)",
                    })
                else:
                    concession_valid = True
                    conceded_this_round = True
                    valid_concessions.append({"round": rnum, "id": fid, "severity": sev})

            # A critical is "standing" unless resolved OR validly conceded.
            if sev == "critical" and not resolved and not concession_valid:
                standing_criticals.append({
                    "round": rnum, "id": fid, "attack": fnd.get("attack", ""),
                })

        if conceded_this_round:
            last_conceded_round = rnum

    block = bool(standing_criticals)
    if block:
        action = "REVERT"
    elif violations:
        action = "DA_RESTATE"
    else:
        action = "PROCEED"

    return {
        "rounds_analyzed": len(rounds),
        "valid_concessions": valid_concessions,
        "violations": violations,
        "standing_criticals": standing_criticals,
        "block_accept": block,
        "recommended_action": action,
    }


def main() -> int:
    p = argparse.ArgumentParser(description=__doc__,
                                formatter_class=argparse.RawDescriptionHelpFormatter)
    p.add_argument("--log", required=True, help="Concession log JSON path")
    p.add_argument("--out", default=None, help="Optional path to write the guard report JSON")
    args = p.parse_args()

    try:
        with open(args.log) as f:
            log = json.load(f)
    except (OSError, json.JSONDecodeError) as e:
        print(f"ERROR: cannot read concession log: {e}", file=sys.stderr)
        return 3

    rounds = log.get("rounds")
    if not isinstance(rounds, list) or not rounds:
        print("ERROR: log['rounds'] must be a non-empty list", file=sys.stderr)
        return 3

    # Light schema validation — fail loudly rather than silently mis-classify.
    for r in rounds:
        for fnd in r.get("findings", []):
            sev = fnd.get("severity", "minor")
            if sev not in VALID_SEVERITY:
                print(f"ERROR: finding {fnd.get('id','?')} has invalid severity "
                      f"'{sev}' (expected one of {sorted(VALID_SEVERITY)})", file=sys.stderr)
                return 3
            score = fnd.get("rebuttal_score")
            if score is not None and not (1 <= score <= 5):
                print(f"ERROR: finding {fnd.get('id','?')} rebuttal_score={score} "
                      f"out of range 1-5", file=sys.stderr)
                return 3

    report = analyze(rounds)

    if args.out:
        with open(args.out, "w") as f:
            json.dump(report, f, indent=2, ensure_ascii=False)

    # Human-readable summary.
    print(f"DA concession guard: {report['rounds_analyzed']} round(s)  "
          f"valid_concessions={len(report['valid_concessions'])}  "
          f"violations={len(report['violations'])}  "
          f"standing_criticals={len(report['standing_criticals'])}")
    for v in report["violations"]:
        print(f"  VIOLATION [{v['type']}] round {v['round']} {v['id']}: {v['detail']}")
    for c in report["standing_criticals"]:
        print(f"  STANDING CRITICAL round {c['round']} {c['id']}: {c['attack']}")
    print(f"  → recommended action: {report['recommended_action']}")

    if report["block_accept"]:
        return 1
    if report["violations"]:
        return 2
    return 0


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

#!/usr/bin/env python3
"""
decision_band.py — Map a 0-100 overall score to a deterministic decision band.

The reviewer rubric (references/reviewer-rubric.md) produces a weighted 0-100
`overall_score` plus a free-form qualitative `decision`. That free-form label is
advisory; this script computes the *canonical* band the refinement loop reasons
about, so the band is reproducible and never drifts from the number it claims to
summarize.

Default bands (override with flags):
    >= 80          Accept
    65 .. 79       Minor Revision
    50 .. 64       Major Revision
    <  50          Reject

The bands give the loop an *absolute* quality target to complement the
*relative* accept/revert delta logic in score_delta.py: a paper can keep
improving relative to its previous self yet still sit in "Major Revision", and
conversely the loop can stop once it reaches "Accept" rather than burning
iterations chasing marginal gains.

Usage:
    python decision_band.py --score 74.6
    python decision_band.py --score-json workspace/refinement/iter2/score.json
    python decision_band.py --score 81 --accept-min 80 --minor-min 65 --major-min 50

Exit codes:
    0  band computed (always, on valid input)
    2  usage / input error
"""
import argparse
import json
import sys

DEFAULT_ACCEPT_MIN = 80
DEFAULT_MINOR_MIN = 65
DEFAULT_MAJOR_MIN = 50

ACCEPT = "Accept"
MINOR = "Minor Revision"
MAJOR = "Major Revision"
REJECT = "Reject"

# Ordered worst -> best, so callers can compare band strength numerically.
BAND_RANK = {REJECT: 0, MAJOR: 1, MINOR: 2, ACCEPT: 3}


def band_for(score: float,
             accept_min: float = DEFAULT_ACCEPT_MIN,
             minor_min: float = DEFAULT_MINOR_MIN,
             major_min: float = DEFAULT_MAJOR_MIN) -> str:
    """Return the decision band for an overall score. Importable by other scripts."""
    if score >= accept_min:
        return ACCEPT
    if score >= minor_min:
        return MINOR
    if score >= major_min:
        return MAJOR
    return REJECT


def main() -> int:
    p = argparse.ArgumentParser(description=__doc__,
                                formatter_class=argparse.RawDescriptionHelpFormatter)
    src = p.add_mutually_exclusive_group(required=True)
    src.add_argument("--score", type=float, help="Overall score 0-100")
    src.add_argument("--score-json", help="Path to a score.json with an overall_score field")
    p.add_argument("--accept-min", type=float, default=DEFAULT_ACCEPT_MIN)
    p.add_argument("--minor-min", type=float, default=DEFAULT_MINOR_MIN)
    p.add_argument("--major-min", type=float, default=DEFAULT_MAJOR_MIN)
    args = p.parse_args()

    if not (args.accept_min > args.minor_min > args.major_min):
        print("ERROR: thresholds must satisfy accept-min > minor-min > major-min",
              file=sys.stderr)
        return 2

    if args.score is not None:
        score = args.score
    else:
        try:
            with open(args.score_json) as f:
                data = json.load(f)
            score = float(data["overall_score"])
        except (OSError, json.JSONDecodeError, KeyError, ValueError, TypeError) as e:
            print(f"ERROR: cannot read overall_score from {args.score_json}: {e}",
                  file=sys.stderr)
            return 2

    band = band_for(score, args.accept_min, args.minor_min, args.major_min)
    out = {
        "overall_score": score,
        "decision_band": band,
        "band_rank": BAND_RANK[band],
        "thresholds": {
            "accept_min": args.accept_min,
            "minor_min": args.minor_min,
            "major_min": args.major_min,
        },
    }
    print(json.dumps(out, indent=2))
    return 0


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

#!/usr/bin/env python3
"""
score_delta.py — Apply the PaperOrchestra refinement halt rules from two
score JSONs.

Encodes the halt rules from arXiv:2604.05018 §4 Step 5:

  - ACCEPT if curr.overall > prev.overall
  - ACCEPT if curr.overall == prev.overall AND net sub-axis delta >= 0
  - REVERT (overall_decreased) if curr.overall < prev.overall
  - REVERT (tied_negative_subaxis) if curr.overall == prev.overall AND
            net sub-axis delta < 0

Additionally encodes the plateau early-stop rule (not in the original paper
but added to match its cost budget of ~5-7 LLM calls):

  - HALT_PLATEAU if the improvement is accepted but overall_delta is below
    --plateau-threshold for --plateau-streak or more consecutive iterations.
    Exit code 4.  The loop should stop — further iterations are unlikely to
    yield meaningful gains.

And the decision-band target halt (see decision_band.py):

  - HALT_TARGET_MET if an accepted iteration reaches the "Accept" band
    (overall >= --accept-threshold, default 80). Exit code 5. The paper now
    clears the acceptance bar, so the loop stops on the current draft rather
    than risk regressing it chasing marginal gains. Takes precedence over the
    plateau halt. Disable with --no-target-halt.

Every output JSON also carries the prev/curr decision band (Accept / Minor
Revision / Major Revision / Reject) so the run report can show an absolute
quality trajectory, not just relative deltas.

Exit codes:
    0  ACCEPT (improved or tied non-negative; below Accept band; no plateau)
    1  REVERT (overall decreased)
    2  REVERT (tied with negative sub-axis delta)
    3  argument or input error
    4  HALT_PLATEAU (accepted but diminishing returns detected)
    5  HALT_TARGET_MET (accepted and reached the Accept band)

Score JSON shape (see references/reviewer-rubric.md):
    {
      "axis_scores": {
        "scientific_depth":     {"score": 65, ...},
        "technical_execution":  {"score": 70, ...},
        "logical_flow":         {"score": 60, ...},
        "writing_clarity":      {"score": 55, ...},
        "evidence_presentation":{"score": 72, ...},
        "academic_style":       {"score": 68, ...}
      },
      "overall_score": 64.5,
      ...
    }

Usage:
    python score_delta.py --prev iter0/score.json --curr iter1/score.json
    python score_delta.py --prev iter2/score.json --curr iter3/score.json \\
        --plateau-threshold 1.0 --plateau-streak 2 --consecutive-small 2
"""
import argparse
import json
import os
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from decision_band import band_for, BAND_RANK  # noqa: E402

AXES = [
    "scientific_depth",
    "technical_execution",
    "logical_flow",
    "writing_clarity",
    "evidence_presentation",
    "academic_style",
]

DEFAULT_PLATEAU_THRESHOLD = 1.0  # points
DEFAULT_PLATEAU_STREAK = 3       # consecutive iterations below threshold → halt


def load(path: str) -> dict:
    with open(path) as f:
        return json.load(f)


def main() -> int:
    p = argparse.ArgumentParser(description=__doc__)
    p.add_argument("--prev", required=True, help="Score JSON from previous accepted iteration")
    p.add_argument("--curr", required=True, help="Score JSON from just-completed iteration")
    p.add_argument(
        "--plateau-threshold", type=float, default=DEFAULT_PLATEAU_THRESHOLD,
        metavar="POINTS",
        help=f"Minimum overall_delta to not count as a 'small' improvement "
             f"(default: {DEFAULT_PLATEAU_THRESHOLD})",
    )
    p.add_argument(
        "--plateau-streak", type=int, default=DEFAULT_PLATEAU_STREAK,
        metavar="N",
        help=f"Number of consecutive small improvements before HALT_PLATEAU "
             f"(default: {DEFAULT_PLATEAU_STREAK})",
    )
    p.add_argument(
        "--consecutive-small", type=int, default=0,
        metavar="N",
        help="Number of consecutive small-delta accepted iterations so far "
             "(maintained by the calling loop; default: 0)",
    )
    p.add_argument(
        "--accept-threshold", type=float, default=80.0, metavar="SCORE",
        help="Overall score at/above which the paper is in the Accept band; "
             "an accepted iteration here triggers HALT_TARGET_MET (default: 80)",
    )
    p.add_argument(
        "--no-target-halt", action="store_true",
        help="Do not halt on reaching the Accept band (still reports the band)",
    )
    args = p.parse_args()

    try:
        prev = load(args.prev)
        curr = load(args.curr)
    except (OSError, json.JSONDecodeError) as e:
        print(f"ERROR: failed to load score JSONs: {e}", file=sys.stderr)
        return 3

    p_overall = float(prev.get("overall_score", 0))
    c_overall = float(curr.get("overall_score", 0))
    overall_delta = c_overall - p_overall

    p_axes = prev.get("axis_scores") or {}
    c_axes = curr.get("axis_scores") or {}
    deltas: dict[str, float] = {}
    for ax in AXES:
        ps = float((p_axes.get(ax) or {}).get("score", 0))
        cs = float((c_axes.get(ax) or {}).get("score", 0))
        deltas[ax] = cs - ps
    net_subaxis = sum(deltas.values())

    # --- Primary accept/revert decision ---
    if c_overall > p_overall:
        decision = "ACCEPT_IMPROVED"
        exit_code = 0
    elif c_overall == p_overall:
        if net_subaxis >= 0:
            decision = "ACCEPT_TIED_NON_NEGATIVE"
            exit_code = 0
        else:
            decision = "REVERT_TIED_NEGATIVE_SUBAXIS"
            exit_code = 2
    else:
        decision = "REVERT_OVERALL_DECREASED"
        exit_code = 1

    # --- Decision bands (absolute quality, independent of the delta) ---
    band_prev = band_for(p_overall, args.accept_threshold)
    band_curr = band_for(c_overall, args.accept_threshold)

    # --- Plateau early-stop (only applies to accepted iterations) ---
    is_small_delta = overall_delta < args.plateau_threshold
    new_consecutive_small = (args.consecutive_small + 1) if is_small_delta else 0
    plateau_triggered = False

    # --- Target-met halt takes precedence over plateau ---
    target_met = False
    if exit_code == 0 and not args.no_target_halt and c_overall >= args.accept_threshold:
        decision = "HALT_TARGET_MET"
        exit_code = 5
        target_met = True
    elif exit_code == 0 and new_consecutive_small >= args.plateau_streak:
        decision = "HALT_PLATEAU"
        exit_code = 4
        plateau_triggered = True

    out = {
        "decision":            decision,
        "exit_code":           exit_code,
        "overall_prev":        p_overall,
        "overall_curr":        c_overall,
        "overall_delta":       overall_delta,
        "decision_band_prev":  band_prev,
        "decision_band_curr":  band_curr,
        "band_improved":       BAND_RANK[band_curr] > BAND_RANK[band_prev],
        "target_met":          target_met,
        "accept_threshold":    args.accept_threshold,
        "subaxis_deltas":      deltas,
        "net_subaxis":         net_subaxis,
        "is_small_delta":      is_small_delta,
        "consecutive_small":   new_consecutive_small,
        "plateau_threshold":   args.plateau_threshold,
        "plateau_streak":      args.plateau_streak,
        "plateau_triggered":   plateau_triggered,
    }
    print(json.dumps(out, indent=2))
    return exit_code


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

#!/usr/bin/env python3
"""
score_trajectory.py — Track per-dimension score deltas across refinement iterations
and detect regression or plateau conditions.

Exit codes:
  0 — OK: no regression or plateau detected
  1 — REGRESSION or PLATEAU: issue detected (see output for details)
"""

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


DIMENSIONS = [
    "scientific_depth",
    "technical_execution",
    "logical_flow",
    "writing_clarity",
    "evidence_presentation",
    "academic_style",
]

COLUMN_WIDTH = 22


def load_scores(scores_dir: str) -> list:
    """
    Load all iterN/scores.json files from scores_dir in order.
    Returns list of (iter_number, scores_dict) sorted by iter_number.
    """
    scores_dir_path = Path(scores_dir)
    if not scores_dir_path.is_dir():
        print(f"[ERROR] scores-dir not found: {scores_dir}", file=sys.stderr)
        sys.exit(1)

    entries = []
    for item in scores_dir_path.iterdir():
        match = re.match(r"^iter(\d+)$", item.name)
        if match and item.is_dir():
            scores_file = item / "scores.json"
            if scores_file.exists():
                try:
                    with open(scores_file, "r", encoding="utf-8") as f:
                        data = json.load(f)
                    entries.append((int(match.group(1)), data))
                except (json.JSONDecodeError, IOError) as e:
                    print(
                        f"[WARN] Could not load {scores_file}: {e}",
                        file=sys.stderr,
                    )

    entries.sort(key=lambda x: x[0])
    return entries


def compute_overall(scores: dict) -> float:
    """Compute mean of all 6 dimensions."""
    values = [scores.get(d, 0) for d in DIMENSIONS]
    return sum(values) / len(values)


def compute_deltas(prev: dict, curr: dict) -> dict:
    """Compute per-dimension delta (curr - prev)."""
    return {d: curr.get(d, 0) - prev.get(d, 0) for d in DIMENSIONS}


def print_score_table(entries: list):
    """Print a formatted table of scores per dimension across iterations."""
    iter_labels = [f"iter{n}" for n, _ in entries]

    # Header
    header = f"{'Dimension':<{COLUMN_WIDTH}}" + "".join(
        f"{label:>10}" for label in iter_labels
    )
    print(header)
    print("-" * len(header))

    # Rows per dimension
    for dim in DIMENSIONS:
        row = f"{dim:<{COLUMN_WIDTH}}"
        for _, scores in entries:
            val = scores.get(dim, "N/A")
            if isinstance(val, (int, float)):
                row += f"{val:>10.1f}"
            else:
                row += f"{'N/A':>10}"
        print(row)

    # Overall row
    print("-" * len(header))
    overall_row = f"{'OVERALL':<{COLUMN_WIDTH}}"
    for _, scores in entries:
        overall = compute_overall(scores)
        overall_row += f"{overall:>10.1f}"
    print(overall_row)
    print()

    # Delta rows (if more than 1 iteration)
    if len(entries) > 1:
        print("Per-dimension deltas (current vs previous iteration):")
        delta_header = f"{'Dimension':<{COLUMN_WIDTH}}" + "".join(
            f"{f'Δ{iter_labels[i]}':>10}" for i in range(1, len(iter_labels))
        )
        print(delta_header)
        print("-" * len(delta_header))

        for dim in DIMENSIONS:
            row = f"{dim:<{COLUMN_WIDTH}}"
            for i in range(1, len(entries)):
                prev_scores = entries[i - 1][1]
                curr_scores = entries[i][1]
                delta = curr_scores.get(dim, 0) - prev_scores.get(dim, 0)
                sign = "+" if delta > 0 else ""
                row += f"{sign}{delta:>9.1f}"
            print(row)

        # Overall delta row
        overall_delta_row = f"{'OVERALL Δ':<{COLUMN_WIDTH}}"
        for i in range(1, len(entries)):
            prev_overall = compute_overall(entries[i - 1][1])
            curr_overall = compute_overall(entries[i][1])
            delta = curr_overall - prev_overall
            sign = "+" if delta > 0 else ""
            overall_delta_row += f"{sign}{delta:>9.1f}"
        print("-" * len(delta_header))
        print(overall_delta_row)
        print()


def main():
    parser = argparse.ArgumentParser(
        description=(
            "Track score trajectory across refinement iterations "
            "and detect regression or plateau."
        )
    )
    parser.add_argument(
        "--scores-dir",
        required=True,
        help="Directory containing iterN/ subdirectories with scores.json files",
    )
    parser.add_argument(
        "--regression-threshold",
        type=float,
        default=-3.0,
        help=(
            "Minimum allowed per-dimension delta in the latest iteration. "
            "If any dimension drops more than this, trigger REGRESSION. "
            "(default: -3, i.e., flag if any dimension drops by more than 3 points)"
        ),
    )
    parser.add_argument(
        "--report-path",
        default=None,
        help="Optional path to write a JSON report",
    )
    args = parser.parse_args()

    entries = load_scores(args.scores_dir)

    if not entries:
        print("[ERROR] No iterN/scores.json files found in scores-dir.", file=sys.stderr)
        sys.exit(1)

    if len(entries) == 1:
        print(f"Only one iteration found (iter{entries[0][0]}). No trajectory to analyze.")
        print_score_table(entries)
        if args.report_path:
            report = {
                "status": "ok",
                "latest_deltas": {},
                "history": [{"iter": entries[0][0], "scores": entries[0][1]}],
            }
            with open(args.report_path, "w", encoding="utf-8") as f:
                json.dump(report, f, indent=2)
        sys.exit(0)

    print_score_table(entries)

    # Analyze latest iteration for regression
    latest_idx = len(entries) - 1
    prev_scores = entries[latest_idx - 1][1]
    curr_scores = entries[latest_idx][1]
    latest_deltas = compute_deltas(prev_scores, curr_scores)
    latest_overall_delta = compute_overall(curr_scores) - compute_overall(prev_scores)

    # Check for REGRESSION in latest iteration
    regression_dims = [
        dim
        for dim, delta in latest_deltas.items()
        if delta < args.regression_threshold
    ]

    # Check for PLATEAU: overall delta < 1.0 for 2+ consecutive iterations
    plateau_count = 0
    for i in range(1, len(entries)):
        prev_overall = compute_overall(entries[i - 1][1])
        curr_overall = compute_overall(entries[i][1])
        if abs(curr_overall - prev_overall) < 1.0:
            plateau_count += 1
        else:
            plateau_count = 0  # reset on non-plateau iteration

    plateau_detected = plateau_count >= 2

    # Build history for report
    history = []
    for i, (iter_num, scores) in enumerate(entries):
        entry = {"iter": iter_num, "scores": scores, "overall": compute_overall(scores)}
        if i > 0:
            prev = entries[i - 1][1]
            entry["deltas"] = compute_deltas(prev, scores)
            entry["overall_delta"] = compute_overall(scores) - compute_overall(prev)
        history.append(entry)

    # Determine status
    status = "ok"
    exit_code = 0
    messages = []

    if regression_dims:
        status = "regression"
        exit_code = 1
        for dim in regression_dims:
            delta = latest_deltas[dim]
            messages.append(
                f"REGRESSION: {dim} dropped {delta:.1f} points in "
                f"iter{entries[latest_idx][0]} "
                f"(threshold: {args.regression_threshold})"
            )

    if plateau_detected and status == "ok":
        status = "plateau"
        exit_code = 1
        messages.append(
            f"PLATEAU: overall score change < 1.0 for {plateau_count} "
            f"consecutive iterations — further refinement unlikely to yield gains"
        )

    # Print status
    if messages:
        for msg in messages:
            print(f"[{status.upper()}] {msg}")
        print()
    else:
        print(f"[OK] No regression or plateau detected in latest iteration.")
        print(
            f"     Overall delta iter{entries[latest_idx-1][0]} → "
            f"iter{entries[latest_idx][0]}: "
            f"{latest_overall_delta:+.1f}"
        )

    # Write report if requested
    if args.report_path:
        report = {
            "status": status,
            "latest_deltas": latest_deltas,
            "history": history,
        }
        report_path = Path(args.report_path)
        report_path.parent.mkdir(parents=True, exist_ok=True)
        with open(report_path, "w", encoding="utf-8") as f:
            json.dump(report, f, indent=2)
        print(f"Report written to: {args.report_path}")

    sys.exit(exit_code)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
snapshot.py — Copy a paper.tex (and optionally paper.pdf) into a refinement
iteration directory, so reverts are real, not symbolic.

The PaperOrchestra refinement halt rules require the loop to roll back to
the previous iteration on overall-score decrease or tied negative sub-axis
delta. To do that physically, every iteration's draft must be preserved.

Usage:
    python snapshot.py --src paper.tex --dst iter2/
    python snapshot.py --src paper.tex --src-pdf paper.pdf --dst iter2/
"""
import argparse
import os
import shutil
import sys


def main() -> int:
    p = argparse.ArgumentParser(description=__doc__)
    p.add_argument("--src", required=True, help="source paper.tex path")
    p.add_argument("--src-pdf", help="optional source paper.pdf path")
    p.add_argument("--dst", required=True, help="destination iteration directory")
    args = p.parse_args()

    if not os.path.isfile(args.src):
        print(f"ERROR: {args.src} not found", file=sys.stderr)
        return 1

    os.makedirs(args.dst, exist_ok=True)
    dst_tex = os.path.join(args.dst, "paper.tex")
    shutil.copy2(args.src, dst_tex)
    print(f"OK: snapshot {args.src} → {dst_tex}")

    if args.src_pdf:
        if not os.path.isfile(args.src_pdf):
            print(f"WARN: {args.src_pdf} not found, skipping PDF snapshot",
                  file=sys.stderr)
        else:
            dst_pdf = os.path.join(args.dst, "paper.pdf")
            shutil.copy2(args.src_pdf, dst_pdf)
            print(f"OK: snapshot {args.src_pdf} → {dst_pdf}")
    return 0


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

#!/usr/bin/env python3
"""
update_critique_memory.py — Build and maintain a structured critique memory
across content-refinement iterations (AutoSci-inspired persistent context).

Reads the refinement worklog.json plus the current iteration's review.json
and produces/updates workspace/refinement/critique_memory.json, which tracks:

  - persistent_issues   : weaknesses flagged in 2+ iterations without resolution
  - resolved_issues     : weaknesses addressed and not re-flagged
  - da_critical_unresolved : Devil's Advocate CRITICAL findings still open
  - focus_on            : short prompts the next reviewer should prioritise
  - do_not_reflag       : resolved issues the next reviewer must NOT re-flag

The content-refinement-agent passes critique_memory.json to the reviewer
prompt at the start of every iteration so the reviewer has memory of prior
rounds.

Exit codes:
    0  OK
    1  Input error (missing file, bad JSON)

Usage:
    python update_critique_memory.py \\
        --worklog workspace/refinement/worklog.json \\
        --review  workspace/refinement/iter2/review.json \\
        --iter    2 \\
        --out     workspace/refinement/critique_memory.json
"""
import argparse
import json
import os
import sys
from difflib import SequenceMatcher


# ── helpers ─────────────────────────────────────────────────────────────────

def load_json(path: str) -> dict | list:
    try:
        with open(path) as f:
            return json.load(f)
    except FileNotFoundError:
        print(f"ERROR: file not found: {path}", file=sys.stderr)
        sys.exit(1)
    except json.JSONDecodeError as e:
        print(f"ERROR: invalid JSON in {path}: {e}", file=sys.stderr)
        sys.exit(1)


def _similarity(a: str, b: str) -> float:
    """Return a 0–1 similarity ratio between two strings (case-insensitive)."""
    return SequenceMatcher(None, a.lower(), b.lower()).ratio()


def _find_match(finding: str, pool: list[str], threshold: float = 0.55) -> str | None:
    """Return the closest string in pool if similarity >= threshold, else None."""
    best, best_score = None, 0.0
    for item in pool:
        s = _similarity(finding, item)
        if s > best_score:
            best, best_score = item, s
    return best if best_score >= threshold else None


def _extract_weaknesses(review: dict) -> list[dict]:
    """
    Extract weakness entries from a review.json.
    Supports both flat list and dict-with-axis variants:

      {"weaknesses": ["...", ...]}
      {"weaknesses": [{"text": "...", "axis": "...", "da_critical": bool}]}
    """
    raw = review.get("weaknesses") or []
    out = []
    for item in raw:
        if isinstance(item, str):
            out.append({"text": item, "axis": None, "da_critical": False})
        elif isinstance(item, dict):
            out.append({
                "text": item.get("text") or item.get("finding") or str(item),
                "axis": item.get("axis"),
                "da_critical": bool(item.get("da_critical", False)),
            })
    # Also pick up top-level da_critical findings from worklog entry format
    for item in review.get("da_critical_findings") or []:
        text = item if isinstance(item, str) else item.get("finding", str(item))
        out.append({"text": text, "axis": None, "da_critical": True})
    return out


def _extract_addressed(review: dict) -> list[str]:
    """
    Extract weaknesses that the revision addressed (from the worklog_entry /
    actions block emitted by the revision agent).
    """
    addressed = []
    for field in ("addressed_weaknesses", "actions_taken"):
        for item in review.get(field) or []:
            if isinstance(item, str):
                addressed.append(item)
            elif isinstance(item, dict):
                addressed.append(item.get("weakness") or item.get("action") or str(item))
    return addressed


# ── core logic ───────────────────────────────────────────────────────────────

def build_memory(worklog: dict, current_review: dict, current_iter: int) -> dict:
    """
    Produce an updated critique_memory dict.

    Algorithm:
      1. Collect all weakness texts across all previous iterations from worklog.
      2. Collect all "addressed" texts from revision agents in worklog.
      3. Merge with current_review weaknesses.
      4. A weakness is "persistent" if it (or a near-duplicate) was flagged in
         ≥2 distinct iterations and not matched by any "addressed" text.
      5. A weakness is "resolved" if it was flagged before and matched by an
         "addressed" text in a subsequent iteration, and not re-flagged since.
    """

    # ── build per-iter weakness and addressed maps from worklog ─────────────
    iter_weaknesses: dict[int, list[dict]] = {}   # iter → [{text, axis, da_critical}]
    iter_addressed: dict[int, list[str]] = {}     # iter → [addressed text]

    for entry in worklog.get("iterations", []):
        i = entry.get("iter", -1)
        review_block = entry.get("review") or {}
        actions_block = entry.get("actions") or {}
        # weaknesses from the review sub-block
        iter_weaknesses[i] = _extract_weaknesses(review_block)
        # addressed texts from the actions sub-block
        iter_addressed[i] = _extract_addressed(actions_block)

    # Add current iteration's weaknesses (not yet in worklog)
    iter_weaknesses[current_iter] = _extract_weaknesses(current_review)

    # ── collect all unique finding texts seen so far ─────────────────────────
    # Map canonical_text → {first_iter, iter_set, axis, da_critical}
    canonical: dict[str, dict] = {}

    all_iters_sorted = sorted(iter_weaknesses.keys())
    for i in all_iters_sorted:
        for w in iter_weaknesses[i]:
            text = w["text"].strip()
            if not text:
                continue
            existing = _find_match(text, list(canonical.keys()))
            if existing:
                canonical[existing]["iter_set"].add(i)
                if w["axis"]:
                    canonical[existing]["axis"] = w["axis"]
                if w["da_critical"]:
                    canonical[existing]["da_critical"] = True
            else:
                canonical[text] = {
                    "first_iter": i,
                    "iter_set": {i},
                    "axis": w["axis"],
                    "da_critical": w["da_critical"],
                }

    # ── collect all addressed texts across all iterations ───────────────────
    all_addressed: list[str] = []
    for i in sorted(iter_addressed.keys()):
        all_addressed.extend(iter_addressed[i])

    # ── classify each canonical finding ─────────────────────────────────────
    persistent_issues: list[dict] = []
    resolved_issues: list[dict] = []
    da_critical_unresolved: list[dict] = []

    for text, meta in canonical.items():
        times_flagged = len(meta["iter_set"])
        was_addressed = _find_match(text, all_addressed) is not None
        still_open = not was_addressed

        if meta["da_critical"] and still_open:
            da_critical_unresolved.append({
                "finding": text,
                "first_flagged_iter": meta["first_iter"],
                "times_flagged": times_flagged,
                "axis": meta["axis"],
            })
        elif times_flagged >= 2 and still_open:
            persistent_issues.append({
                "finding": text,
                "first_flagged_iter": meta["first_iter"],
                "times_flagged": times_flagged,
                "axis": meta["axis"],
            })
        elif was_addressed and not still_open:
            resolved_issues.append({
                "finding": text,
                "first_flagged_iter": meta["first_iter"],
                "resolved_by_iter": max(
                    (i for i in iter_addressed if _find_match(text, iter_addressed[i])),
                    default=current_iter,
                ),
                "axis": meta["axis"],
            })

    # Sort persistent by times_flagged DESC, then first_iter ASC
    persistent_issues.sort(key=lambda x: (-x["times_flagged"], x["first_flagged_iter"]))

    # ── build focus/do-not-reflag prompt fragments ───────────────────────────
    focus_on = [
        f"[iter {p['first_flagged_iter']}+, {p['times_flagged']}x] {p['finding']}"
        for p in persistent_issues[:5]
    ]
    focus_on = [
        f"[DA-CRITICAL, iter {d['first_flagged_iter']}+] {d['finding']}"
        for d in da_critical_unresolved
    ] + focus_on

    do_not_reflag = [
        f"{r['finding']}"
        for r in resolved_issues[-10:]  # cap at 10 to keep prompt size reasonable
    ]

    return {
        "current_iter": current_iter,
        "persistent_issues": persistent_issues,
        "resolved_issues": resolved_issues,
        "da_critical_unresolved": da_critical_unresolved,
        "focus_on": focus_on,
        "do_not_reflag": do_not_reflag,
        "_stats": {
            "total_unique_findings": len(canonical),
            "persistent_count": len(persistent_issues),
            "resolved_count": len(resolved_issues),
            "da_critical_open": len(da_critical_unresolved),
        },
    }


# ── main ─────────────────────────────────────────────────────────────────────

def main() -> int:
    p = argparse.ArgumentParser(description=__doc__)
    p.add_argument("--worklog", required=True, help="Path to worklog.json")
    p.add_argument("--review",  required=True, help="Path to current iter's review.json")
    p.add_argument("--iter",    type=int, required=True, help="Current iteration number")
    p.add_argument("--out",     required=True, help="Output path for critique_memory.json")
    args = p.parse_args()

    worklog = load_json(args.worklog) if os.path.exists(args.worklog) else {"iterations": []}
    current_review = load_json(args.review)

    memory = build_memory(worklog, current_review, args.iter)

    os.makedirs(os.path.dirname(os.path.abspath(args.out)) or ".", exist_ok=True)
    with open(args.out, "w") as f:
        json.dump(memory, f, indent=2, ensure_ascii=False)

    stats = memory["_stats"]
    print(f"OK: critique_memory.json updated for iter {args.iter}")
    print(f"    persistent: {stats['persistent_count']}  "
          f"resolved: {stats['resolved_count']}  "
          f"da_critical_open: {stats['da_critical_open']}")
    if memory["focus_on"]:
        print("    focus_on:")
        for line in memory["focus_on"]:
            print(f"      - {line}")
    if memory["do_not_reflag"]:
        print(f"    do_not_reflag: {len(memory['do_not_reflag'])} resolved issue(s) suppressed")
    return 0


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