Canvas Humanizer Loop

Input docx
  ↓
[§4]  iter loop (max_iter=3):
  ↓
  [§4.1] Skill(canvas-humanizer, current_draft, hard_locks=converged_seg_texts)
         → humanized_<N>.docx + humanizer_log.json
  ↓
  [§4.2] Agent × 3 parallel (audit subagent)
         → 3 × residual_issues_audit.json
  ↓
  [§4.3] Majority-vote merge → merged_audit.json
  ↓
  [§4.4] Structural-drift check (split_sentences re-check per paragraph)
  ↓
  [§4.5] Update verdict history per (doc_paragraph_index, intra_para_index)
  ↓
  [§4.6] Convergence guards (3 layered):
         (a) MUST_FIX == 0 → return current humanized (status=ok)
         (b) Per-seg verdict monotonicity violated → return best historical iter (status=partial)
         (c) Same paragraph drifts 2 iters in a row → return best historical iter (status=partial)
         (d) iter == max_iter → return best historical iter (status=partial)
  ↓
  [§4.7] Agent × N parallel (rewrite-subagent), N = broken segs count
         → splice rewrites into humanized_<N> → rewritten_<N>.docx
  ↓
  [§4.8] Build converged_seg_texts for next iter's hard_locks
         (with uniqueness pre-flight per §10)
  ↓
[§5-12] Write loop_log.json + select best iter's docx as output_path

# Loop state
best_iter_index = None
best_severity = float("inf")
verdict_history = {}      # (para_idx, intra_idx) -> list of verdicts across iters
drift_strikes = {}        # (para_idx) -> consecutive drift count
iter_artifacts = []       # list of per-iter dicts for loop_log.json
current_draft_path = draft_v0

for iter_num in range(1, max_iter + 1):
    iter_dir = output_dir / f"_loop_iter_{iter_num}"
    iter_dir.mkdir(exist_ok=True)

    # §4.1 — Run humanizer (with converged segs as hard_locks from iter ≥ 2)
    converged_seg_texts = _build_converged_locks(verdict_history, iter_num, current_draft_path)
    invoke_skill(
        "canvas-humanizer",
        draft_path=current_draft_path,
        output_path=iter_dir / "humanized.docx",
        voice_register=voice_register,
        hard_locks=converged_seg_texts,  # via overlay or runtime arg
    )
    humanizer_log = load_json(iter_dir / "humanizer_log.json")
    humanized_path = iter_dir / "humanized.docx"

    # §4.2-4.3 — 3 parallel audits, majority-vote merge
    audit_paths = dispatch_parallel_audits(humanized_path, draft_v0, humanizer_log, iter_dir)
    merged_audit = merge_audits_majority_vote(audit_paths)
    save_json(iter_dir / "merged_audit.json", merged_audit)

    # §4.4 — Structural-drift check
    drifted_paragraphs = detect_structural_drift(humanized_path, humanizer_log)
    for para_idx in drifted_paragraphs:
        drift_strikes[para_idx] = drift_strikes.get(para_idx, 0) + 1

    # §4.5 — Update verdict history
    for sent_entry in merged_audit["per_sentence"]:
        key = (sent_entry["doc_paragraph_index"], sent_entry["intra_para_index"])
        verdict_history.setdefault(key, []).append(sent_entry["verdict"])

    # Compute severity_score
    must_fix = merged_audit["aggregate_stats"]["total_MUST_FIX"]
    should_fix = merged_audit["aggregate_stats"]["total_SHOULD_FIX"]
    nice = merged_audit["aggregate_stats"]["total_NICE_TO_FIX"]
    severity_score = must_fix * 3 + should_fix * 2 + nice * 1

    # Track best iter
    if severity_score < best_severity:
        best_iter_index = iter_num
        best_severity = severity_score

    iter_artifacts.append({
        "iter": iter_num,
        "humanized_path": str(humanized_path),
        "merged_audit_path": str(iter_dir / "merged_audit.json"),
        "audit_paths": [str(p) for p in audit_paths],
        "severity_score": severity_score,
        "broken_segs": _extract_broken_segs(merged_audit),
        "structurally_drifted_paras": list(drifted_paragraphs),
    })

    # §4.6 — Convergence guards
    if must_fix == 0:
        return _finalize(best_iter_index=iter_num, reason="MUST_FIX==0", status="ok")

    if iter_num > 1 and _oscillation_detected(verdict_history):
        return _finalize(best_iter_index, reason="oscillation", status="partial")

    if any(c >= 2 for c in drift_strikes.values()):
        return _finalize(best_iter_index, reason="structural_drift_persistent", status="partial")

    if iter_num == max_iter:
        return _finalize(best_iter_index, reason="max_iter_hit", status="partial")

    # §4.7 — Dispatch rewrites for broken segs (parallel)
    broken_segs = _extract_broken_segs(merged_audit)
    rewrites = dispatch_parallel_rewrites(broken_segs, humanized_path, draft_v0, voice_register)

    # §4.7 — Splice rewrites back; mark any split_required segs as drift
    rewritten_path = iter_dir / "rewritten.docx"
    splice_status = splice_rewrites(humanized_path, rewrites, rewritten_path)
    for seg in splice_status["split_required_segs"]:
        para_idx = seg["doc_paragraph_index"]
        drift_strikes[para_idx] = drift_strikes.get(para_idx, 0) + 1

    iter_artifacts[-1]["rewritten_segs"] = rewrites
    current_draft_path = rewritten_path

return _finalize(best_iter_index, reason="max_iter_hit", status="partial")

You are an audit sub-agent for canvas-humanizer-loop. Your job: detect every segment in a humanized essay where humanizer broke meaning, structure, or rubric compliance — and classify each issue by 7-dimension taxonomy + 3-severity scale.

CONTEXT
- Original V0 essay (pre-humanizer): {v0_path} — read this fully
- Humanized version (current iter output): {humanized_path} — read this fully
- humanizer_log.json: {humanizer_log_path} — read for per-segment doc_paragraph_index / intra_para_index / winning_strategy_used
- Voice register contract: {voice_register}
- Rubric anchors (assignment-specific):
  - R8 opener: first sentence of intro must match regex ^In ["][^"]+["]\s*\([^)]+\),\s*[A-Z]\w+ (article title + publication + author + verb)
  - R8 person introduction: full name + credential on first mention, last name only after
  - R8 quote count: intro 0, body paragraphs 1 each, conclusion 0
  - R8 conclusion thesis-restatement: first sentence of conclusion must echo the intro's thesis claim
  - R9 word count band: {word_count_band} (e.g., 550-650)
  - R9 banned patterns: long em-dash strings, "in conclusion", "in summary", "delve into", "tapestry", "navigate the landscape"

TASK
For each sentence in the humanized doc, identify all issues across these 7 dimensions:

| Dim | Name | What to flag |
|---|---|---|
| D1 | rubric_violation | Concrete spec-anchor failures (R8/R9 above) |
| D2 | grammar_tortured | Garbled / ungrammatical output (NOT intentional ESL) |
| D3 | unnatural_syntax | Yoda-style fronting, pseudo-cleft chains, absolute-phrase openers, fronted-wh-clause subjects, parallel passive openers across consecutive sentences |
| D4 | voice_register_drift | Tone mismatch vs voice_register contract (e.g., slang in academic, archaisms beyond register) |
| D5 | new_AI_tell_introduced | Em-dash overuse (>2/paragraph), rhetorical inversion clusters, uniform cadence patterns the humanizer created |
| D6 | meaning_distortion | Claim direction reversed, hedge strength changed, numbers/quote text altered, anecdote subject moved out of first 1/3 of sentence |
| D7 | lock_or_credential_loss | Person introduced by last name only (missing first name + credential), quote text bytes differ, named entity lost |

For each issue:
- severity: MUST_FIX (rubric break / meaning reversed / cadence-cluster signature) | SHOULD_FIX (single instance, isolated) | NICE_TO_FIX (stylistic preference)
- anchor: ~10-word verbatim excerpt of the offending text
- rubric_ref: R-number if applicable (R2/R8/R9), else null
- fix_directive: 1-2 sentences telling a rewrite agent what to do (be concrete: "Restore opening to lead with full publication info" not "fix the syntax")

For each sentence:
- seg_id: "P{doc_paragraph_index}_S{intra_para_index}" — derive from humanizer_log.json segments[]
- paragraph: "intro" | "body 1" | "body 2" | "conclusion" (infer from doc_paragraph_index — paragraphs after name-block/title)
- v2_text: the sentence as it appears in humanized doc
- pre_humanize_text: the corresponding sentence from V0 (match by doc_paragraph_index + intra_para_index)
- issues: array of issue objects (can be empty)
- winning_strategy_used: read from humanizer_log.json
- verdict:
  - "broken" if any MUST_FIX issue, OR ≥2 SHOULD_FIX in cadence-cluster dimensions (D3 + D5)
  - "needs_surgical" if exactly 1 SHOULD_FIX with no MUST_FIX
  - "minor" otherwise (zero issues, or only NICE_TO_FIX, or 1 SHOULD_FIX in a non-cadence dimension)

OUTPUT FORMAT
Emit a single JSON object matching residual_issues_audit.json schema:

{
  "audit_date": "YYYY-MM-DD",
  "target_doc": "{humanized_path}",
  "doc_word_count": <int>,
  "doc_sentence_count": <int>,
  "doc_paragraph_count": <int>,
  "aggregate_stats": {
    "sentences_with_zero_issues": <int>,
    "sentences_with_one_issue": <int>,
    "sentences_with_multiple_issues": <int>,
    "total_MUST_FIX": <int>,
    "total_SHOULD_FIX": <int>,
    "total_NICE_TO_FIX": <int>,
    "issues_by_dimension": {"D1_rubric_violation": <int>, ...},
    "clustering": "Free-form 2-4 sentence summary of where issues concentrate"
  },
  "per_sentence": [
    {
      "seg_id": "P5_S0",
      "doc_paragraph_index": 5,
      "intra_para_index": 0,
      "paragraph": "intro",
      "v2_text": "...",
      "pre_humanize_text": "...",
      "issues": [
        {
          "dimension": "D1_rubric_violation",
          "severity": "MUST_FIX",
          "anchor": "...",
          "rubric_ref": "R8",
          "fix_directive": "..."
        }
      ],
      "winning_strategy_used": "clause_reorder",
      "verdict": "broken"
    }
  ]
}

CRITICAL CONSTRAINTS
- Do NOT speculate. Only flag what is concretely demonstrable from comparing v2_text vs pre_humanize_text against rubric anchors.
- Do NOT downgrade severity to avoid triggering downstream rewrites. Loop logic depends on accurate severity.
- Do NOT flag intentional ESL register markers (article omission, occasional SVA slip in body paragraphs) as D2 grammar_tortured — those are voice_register strategy.
- Quote the exact rubric anchor text in rubric_ref when D1 fires.

def merge_audits_majority_vote(audit_paths: list[Path]) -> dict:
    audits = [load_json(p) for p in audit_paths]

    # Build per-seg issue tables
    # key = (seg_id, dimension), value = list of (severity, anchor, rubric_ref, fix_directive)
    issue_votes = {}
    seg_verdicts = {}  # seg_id -> list of verdicts from 3 agents

    for audit in audits:
        for sent in audit["per_sentence"]:
            seg_id = sent["seg_id"]
            seg_verdicts.setdefault(seg_id, []).append(sent["verdict"])
            for issue in sent["issues"]:
                key = (seg_id, issue["dimension"])
                issue_votes.setdefault(key, []).append(issue)

    # Aggregation: keep an (seg_id, dimension) issue iff ≥2 of 3 agents flagged it
    # Severity = max severity across the agents that flagged it (MUST_FIX > SHOULD_FIX > NICE_TO_FIX)
    SEVERITY_RANK = {"MUST_FIX": 3, "SHOULD_FIX": 2, "NICE_TO_FIX": 1}

    confirmed_issues_per_seg = {}  # seg_id -> list of merged issue dicts
    for (seg_id, dim), votes in issue_votes.items():
        if len(votes) < 2:
            continue  # only 1 agent flagged; drop
        max_sev = max(votes, key=lambda v: SEVERITY_RANK[v["severity"]])
        merged_issue = {
            "dimension": dim,
            "severity": max_sev["severity"],
            "anchor": max_sev["anchor"],
            "rubric_ref": max_sev["rubric_ref"],
            "fix_directive": max_sev["fix_directive"],
            "votes": len(votes),
        }
        confirmed_issues_per_seg.setdefault(seg_id, []).append(merged_issue)

    # Verdict aggregation: majority of 3 (or break tie to broken > needs_surgical > minor)
    VERDICT_RANK = {"broken": 3, "needs_surgical": 2, "minor": 1}

    def pick_verdict(verdict_list):
        counts = {v: verdict_list.count(v) for v in set(verdict_list)}
        max_count = max(counts.values())
        winners = [v for v, c in counts.items() if c == max_count]
        return max(winners, key=lambda v: VERDICT_RANK[v])

    # Rebuild per_sentence with confirmed issues + voted verdict
    template_audit = audits[0]
    merged_per_sentence = []
    for sent in template_audit["per_sentence"]:
        seg_id = sent["seg_id"]
        merged_per_sentence.append({
            **sent,
            "issues": confirmed_issues_per_seg.get(seg_id, []),
            "verdict": pick_verdict(seg_verdicts.get(seg_id, [sent["verdict"]])),
        })

    # Recompute aggregate_stats from merged data
    aggregate_stats = _recompute_aggregate(merged_per_sentence)

    return {
        "audit_date": template_audit["audit_date"],
        "target_doc": template_audit["target_doc"],
        "doc_word_count": template_audit["doc_word_count"],
        "doc_sentence_count": template_audit["doc_sentence_count"],
        "doc_paragraph_count": template_audit["doc_paragraph_count"],
        "aggregate_stats": aggregate_stats,
        "per_sentence": merged_per_sentence,
    }

if merged_audit["aggregate_stats"]["total_MUST_FIX"] == 0:
    return _finalize(iter_num, reason="MUST_FIX==0", status="ok")

def _oscillation_detected(verdict_history: dict) -> bool:
    """Catch segments whose verdict regresses: broken→minor→broken, or needs_surgical→broken."""
    for seg_key, hist in verdict_history.items():
        if len(hist) < 2:
            continue
        # If a segment was "minor" or "needs_surgical" at some point and is "broken" later, oscillation
        ranks = [VERDICT_RANK[v] for v in hist]  # broken=3, needs_surgical=2, minor=1
        for i in range(1, len(ranks)):
            if ranks[i] > ranks[i-1]:  # got worse
                return True
    return False

if any(strikes >= 2 for strikes in drift_strikes.values()):
    return _finalize(best_iter_index, reason="structural_drift_persistent", status="partial")

if iter_num == max_iter:
    return _finalize(best_iter_index, reason="max_iter_hit", status="partial")

from src.humanizer_segmentation import split_sentences

def detect_structural_drift(humanized_docx_path: Path, humanizer_log: dict) -> set[int]:
    """Return set of doc_paragraph_index where re-split count != humanizer_log's count."""
    paragraphs = read_docx_paragraphs(humanized_docx_path)
    expected_counts = {}
    for seg in humanizer_log["segments"]:
        p = seg["doc_paragraph_index"]
        expected_counts[p] = max(expected_counts.get(p, 0), seg["intra_para_index"] + 1)
    actual_counts = {i: len(split_sentences(p)) for i, p in enumerate(paragraphs)}
    drifted = set()
    for p_idx in expected_counts:
        if actual_counts.get(p_idx, 0) != expected_counts[p_idx]:
            drifted.add(p_idx)
    return drifted

You are a rewrite sub-agent for canvas-humanizer-loop. Your single job: rewrite ONE sentence to fix issues identified by the audit, while staying invisible to AI detectors AND preserving the original meaning.

INPUTS
- v0_sentence (pre-humanizer original): "{v0_sentence}"
- v_humanized_sentence (current broken version): "{v_humanized_sentence}"
- broken_dimensions:
  {broken_dimensions_json}   # array of {dimension, severity, fix_directive}
- role: {role}                 # one of: intro_opener, intro_thesis, intro_setup, body_TS, body_quote_lead_in, body_quote_follow_up, body_elaboration, body_anecdote, conclusion_thesis_restate, conclusion_structural, conclusion_closing
- voice_register: {voice_register}
- context_prev_sentence: "{context_prev}"
- context_next_sentence: "{context_next}"

HARD CONSTRAINTS (all must pass; fail any → emit split_required=true and stop)

1. ONE-IN-ONE-OUT
   Output exactly ONE complete sentence. Do not split into two sentences. Do not merge with adjacent. If the fix_directive demands splitting (e.g., "split this overlong sentence"), refuse and set split_required=true.

2. NOT V0, NOT V_HUMANIZED
   Sentence-level edit distance must be > 0.3 vs BOTH v0_sentence AND v_humanized_sentence. (Approx: at least 30% of words must differ in either inflection, order, or choice from each baseline.) This is the avoid-detector-pattern constraint.

3. MEANING + RHETORICAL SETUP PRESERVED
   - Propositional content identical to v0_sentence: claim direction same, numbers same, quoted text byte-identical, person names identical
   - Rhetorical setup:
     • If role = body_anecdote: subject (the anecdote agent — "my cousin", "a classmate") MUST appear in the first 1/3 of the sentence
     • If role = body_TS or conclusion_thesis_restate: main claim must appear in first half of sentence (open with the point, don't bury it)
     • If role = intro_opener: must match regex ^In ["][^"]+["]\s*\([^)]+\),\s*[A-Z]\w+ (article title + publication + author + verb)
     • If role = body_quote_lead_in: must end with a clause that sets up the quote that follows (typically with "that," or a colon)

4. ROLE-AWARE REGISTER STRATEGY
   This determines HOW you rewrite (the policy that prevents re-introducing detector signal).

   IF role ∈ {intro_opener, intro_thesis, body_TS, body_quote_lead_in, body_quote_follow_up, conclusion_thesis_restate, conclusion_structural}:
       Strategy = ESL-register-clean
       - ESL-flavored syntax/word order OK (e.g., topicalization "What [Author A] argues is that...", non-standard but grammatical hedges)
       - Grammar must be CLEAN: no article omission, no SVA slip, correct tense
       - This protects R9 rubric compliance for grade-sensitive positions

   IF role ∈ {body_elaboration, body_anecdote, conclusion_closing}:
       Strategy = ESL-chinese-full
       - Visible article omission ("Chinese intuition I grew up with", not "the Chinese intuition...")
       - Occasional subject-verb agreement slip ("My cousin show...", "[Author B] trace...")
       - These create natural ESL distribution that detectors don't pattern-match as AI
       - Cap: at most 2 grammar-marker slips per sentence; do not stack 3+ markers (sounds tortured)

   Why two strategies: canvas-humanizer-surgical v1 used ESL-clean uniformly and detector climbed 28→48 because clean-register sentences re-entered LLM distribution. v3 used ESL-full in gates and broke R9 (instructor counts visible grammar errors as wrong). Per-role split is the empirical fix.

5. CONTEXT FIT
   - context_prev_sentence and context_next_sentence are provided so your rewrite reads as part of the flowing paragraph, not as an isolated unit
   - Do not duplicate language from either context sentence (avoid lexical repetition triplets that detectors flag)
   - Discourse connector (if any) must be appropriate to the prev→current relationship; do not introduce a "however" if the prev sentence already opened with "however"

OUTPUT (JSON)
{
  "rewritten_sentence": "<one complete English sentence>",
  "rationale": "<2-3 sentences: which broken_dimensions you fixed, which strategy you applied, how meaning was preserved>",
  "split_required": false,
  "edit_distance_from_v0": <0.0-1.0>,
  "edit_distance_from_v_humanized": <0.0-1.0>
}

If you cannot satisfy all 5 hard constraints, emit:
{
  "rewritten_sentence": "",
  "rationale": "<why constraint X cannot be met for this sentence>",
  "split_required": true,
  "blocked_constraint": "<one of: 1_one_in_one_out, 2_not_v0_or_v_humanized, 3_meaning_setup, 4_role_register, 5_context_fit>"
}

Do not include the original sentences in your output. Just the JSON above.

def build_converged_locks(verdict_history, iter_num, current_draft_path):
    """Return list of sentence strings to pass as hard_locks. Skips collision-prone segs."""
    if iter_num == 1:
        return []  # no locks first iter

    paragraphs = read_docx_paragraphs(current_draft_path)
    locks = []
    for (para_idx, intra_idx), hist in verdict_history.items():
        # A seg is "converged" if its LAST verdict was minor or needs_surgical (not broken)
        if not hist or hist[-1] == "broken":
            continue
        # Get the seg's current text
        sentences = split_sentences(paragraphs[para_idx])
        if intra_idx >= len(sentences):
            continue  # paragraph drifted; don't lock
        candidate = sentences[intra_idx]
        # Uniqueness pre-flight: count occurrences across the full doc
        full_text = "\n".join(paragraphs)
        if full_text.count(candidate) != 1:
            log(f"lock collision skipped: {candidate[:60]}...")
            continue
        locks.append(candidate)
    return locks