Canvas Humanizer Surgical

canvas-humanizer-surgical v3 — per-position differentiated ESL

§1 — Identity & contract (caller-facing)

Inputs (parsed from caller's prose context line):

Outputs:

• output_path — surgical-fixed .docx
• <output_dir>/surgical_log.json — full execution trace

Status return:

• ok — every MUST_FIX issue addressed AND all Stage E doc-level gates PASS
• partial — ≥1 MUST_FIX fell back to current_humanized OR a doc gate WARNs
• error — input validation failure

§2 — Why surgical v3 (per-position differentiation)

v1 surgical failure (per-role gating + ESL fallback) regressed Grammarly AI score 28% → 48%. Root cause: 15 MUST_FIX issues all in gate-sensitive role (intro_opener / TS / quote integration / conclusion_thesis_restate); ESL was gated off there; P-academic restoration pulled prose back to LLM-training-distribution center.

v2 design rejected ("ESL primary everywhere"): would put visible grammar errors in rubric-graded positions. An academic-writing instructor's grading sample observed during calibration: Draft 1 (57 grammar errors) → 68/100; Draft 2 (clean) → 83/100. ESL with SVA slip + article omission in intro_opener / TS / conclusion thesis restate = R9 deduction in the most-graded positions.

v3 (this skill): differentiate by position type.

Plus: expand fix scope from MUST_FIX-only to MUST_FIX + body SHOULD_FIX so body ESL has segments to fire on (v1's body roles had 0 MUST_FIX and were left untouched).

Honest framing: ESL register strategies as distribution escape are tested for the first time here. P-esl-register-clean (gate positions) is hypothesis — syntax-only ESL may not move detector signal enough without grammar markers. P-esl-chinese-full (body positions) is the higher-confidence lever because grammar-error patterns are truly outside LLM training distribution. Expected Grammarly delta: 28% → 18-25% (still a hypothesis; v1 surgical's reality was 28% → 48% which proves clean academic restoration hurts).

§3 — Pipeline overview (3-layer nested)

Level 1: doc orchestrator
  ├─ Stage A: load audit data (per-sentence issues + roles)
  ├─ Stage B: build expanded fix queue (MUST_FIX all + body SHOULD_FIX)
  ├─ Stage C: cluster by paragraph; spawn workers in parallel
  ├─ Stage D: reassemble
  └─ Stage E: doc-level verify (R8 4-variant regex / R2 markers / quote count / word count / locks / R9 grammar tally)

Level 2: paragraph worker (one per paragraph, parallel)
  ├─ Receive paragraph + fix_goals + roles
  ├─ Spawn segment workers parallel
  └─ Assemble paragraph

Level 3: segment surgical worker (parallel within paragraph)
  ├─ Determine role → primary strategy + backup per §S2 of plan
  ├─ Generate K candidates per §6 (K varies by severity × role)
  ├─ Score per §7
  ├─ Pick winner (primary preferred)
  └─ Fallback chain: primary → backup → P-academic-minimal → current_humanized

Concurrency: 25 fix ops × K2.5 avg × 3 LLM calls each ≈ ~190 calls. Parallel candidate dispatch collapses wallclock to 5-15 min.

§4 — Stage A: audit (role tagging + issue detection)

Skip if caller passed audit_path to a pre-derived audit JSON. Default: load runs/2026-05-22/_humanizer_v2_smoketest/residual_issues_audit.json (derived from earlier v2 humanized essay).

When running fresh, spawn 1 audit agent per v2 SKILL.md §4 (with role taxonomy below + low-confidence fallback).

§4a — Role taxonomy (10 roles, position-typed)

Gate-sensitive (use P-esl-register-clean):

• intro_opener — sentence 1 of intro; R8 strict (pub info + author + title + date)
• intro_thesis — last sentence of intro; R2 thesis statement
• intro_setup — middle sentences of intro
• body_TS — first sentence of body paragraph; R2 + instructor mandate (judgment statement in writer's words)
• body_quote_lead_in — sentence immediately preceding a quoted span
• body_quote_follow_up — sentence immediately after quoted span; explains the quote
• conclusion_thesis_restate — first sentence of conclusion; R2 thesis restatement
• conclusion_structural — conclusion sentences referencing source data / policy lever

Body (use P-esl-chinese-full):

• body_elaboration — body sentences developing argument
• body_anecdote — personal experience (cousin / friends / Chinese intuition sentences)
• conclusion_closing — final sentence(s)

Locked (never touched):

• body_quoted_sentence — sentence containing verbatim [Author A] quote

§4b — Role classification prompt

Same shape as v2 humanizer §4b (worked examples + low-confidence fallback). When confidence < 0.70, default to most restrictive role (treat ambiguous body_elaboration as body_TS) — prevents ESL-chinese-full from accidentally firing in gate-sensitive positions.

§4c — Issue dimensions (per v2 humanizer §4c)

D1 rubric_violation, D2 grammar_tortured, D3 unnatural_syntax, D4 voice_register_drift, D5 new_AI_tell_introduced, D6 meaning_distortion, D7 lock_or_credential_loss. Severity ∈ {MUST_FIX, SHOULD_FIX, NICE_TO_FIX}.

§5 — Stage B + C + D: paragraph worker dispatch

§5a — Build fix queue

fix_queue = []
for fix_goal in audit["prioritized_fix_goals"]:
    role = audit["per_sentence"][fix_goal["target_seg_id"]]["role"]
    severity = fix_goal["severity"]
    if severity == "MUST_FIX":
        fix_queue.append(fix_goal)
    elif severity == "SHOULD_FIX" and role in BODY_ROLES:
        if include_should_fix:
            fix_queue.append(fix_goal)
    elif severity == "NICE_TO_FIX" and role in BODY_ROLES:
        if include_nice_to_fix:
            fix_queue.append(fix_goal)
    # SHOULD_FIX / NICE_TO_FIX in gate roles → skip (don't risk breaking R8/R2 for non-critical fix)

BODY_ROLES = {"body_elaboration", "body_anecdote", "conclusion_closing"}.

§5b — Doc-level budget envelope

doc_budget = {
    "esl_marker_per_para_target": {"body": 5, "gate_segment": 1},  # body para 3-5 markers; gate segments 0-1
    "esl_marker_per_para_warn": {"body": 8, "gate_segment": 2},    # warn thresholds
    "word_count_band": (550, 650),
}

§5c — Spawn paragraph workers in parallel

Standard pattern (same as v1 surgical §5c).

§6 — Stage Level-3: per-segment K-candidate generation

For each fix_goal, segment worker determines role → strategy assignment → K candidates.

§6a — Strategy assignment matrix

K = (primary count + backup count). E.g. K=3 for MUST_FIX body = 2 × P-esl-chinese-full + 1 × P-esl-register-clean.

§6b — Strategy P-esl-register-clean (gate positions)

Task: rewrite this sentence to fix {fix_directive}. Use Chinese-student ESL register but with CLEAN grammar (no agreement errors, no missing articles).

Apply 2-3 of these ESL syntax/phrasing markers (do NOT introduce grammar errors):

• Native-prep choice ESL: "on [Publication]" instead of "in [Publication]"; "on Etsy" / "on YouTube" stay native (these are platform names, not registers)
• Direct-translation idiom: "as I see" (从我看来) instead of "in my view"; "more and more" (越来越) instead of "increasingly"; "comes from" (来自) for causation
• Topic-prominent syntax: "About X, ..." or "As for Y, ..." sentence opener
• Simpler tense: drop past perfect / future perfect where simple past / future suffices ("had been breaking" → "was breaking")
• Genitive-fronted possessive: "[Author A]'s article" instead of "[Author A]'s article in/of/by"
• Soft connective: "But" / "And" sentence-initial instead of "However" / "Moreover"

STRICT prohibitions (these are R9 grammar fails — never apply at gate positions):

• NO subject-verb agreement slip ("[Author A] argue" / "data show" where native is "[Author A] argues" / "data shows") — KEEP correct agreement
• NO article omission ("the diagnosis" must stay "the diagnosis")
• NO dropped auxiliary ("she writing" instead of "she is writing")

Constraints:

• Preserve every [LOCK_N] placeholder byte-for-byte.
• Word count within ±20% of original (sliding band per §6h of v2 humanizer).
• Preserve meaning faithfully.

Original (already humanized): {current_humanized_segment} Issue to fix: {fix_directive} Role: {role} (gate-sensitive — clean grammar required)

Output ONLY the rewritten sentence, no preamble.

§6c — Strategy P-esl-chinese-full (body positions)

Task: rewrite this sentence to fix {fix_directive}. Use Chinese-student ESL register WITH visible grammar markers.

Apply 2-3 of these patterns:

• Article omission: drop "the" or "a" 1-2 times per sentence ("the diagnosis" → "diagnosis"; "a classmate" → "one classmate")
• Subject-verb agreement slip: bare-stem 3rd-person singular verb 1 per 50 words ("[Author A] argues" → "[Author A] argue"; "the data show" — actually this is sometimes correct; pick clear cases)
• Direct-translation idiom: "as I see" / "more and more" / "from one side ... from other side"
• Topic-prominent syntax: "About X, ..."
• Simpler tense: drop past perfect
• Native-prep choice ESL: "on [Publication]"
• Chinese emphatic: "they two both step" (中式 "他们两个都")
• Dropped auxiliary: "she writing" / "they not offering" (use sparingly — only when adjacent context supports)

Cap: max 3 marker types per sentence. Errors must look like authentic Chinese-English ESL, NOT broken-text caricature. Reader must still understand the sentence.

Constraints:

• Preserve every [LOCK_N] placeholder byte-for-byte. Article omission must NOT drop the article preceding [LOCK_N] placeholder.
• Word count within ±20% of original.
• Preserve meaning faithfully.

Original (already humanized): {current_humanized_segment} Issue to fix: {fix_directive} Role: {role} (body — ESL markers allowed)

Output ONLY the rewritten sentence, no preamble.

§6d — Strategy P-academic-minimal (backup)

Same as v1 surgical §6b — minimal lexical sub + adjacent-clause swap in academic register, no structural transformation.

§6e — Lock substitution + word-count gate (sliding tolerance)

Same as v2 humanizer §4d + §6h.

§7 — Scoring + selection

§7a — Gate evaluation (LLM-judge + deterministic)

For each candidate, evaluate:

1. satisfies_fix_goal (LLM-judge binary, with NICE_TO_FIX relaxation): does candidate address {fix_directive}? For NICE_TO_FIX: "improvement is sufficient, perfect fix not required."
2. structural_rubric_pass (deterministic):
   • If role is intro_opener: R8 opener regex matches first sentence (4-variant alternation per §S5 of plan)
   • If role is body_TS: contains R2 TS marker (convincingly argues / I agree / could have strengthened / etc.)
   • If role is conclusion_thesis_restate: contains thesis-restate language
3. meaning_preserved (LLM-judge binary)
4. locks_intact (deterministic — check [LOCK_N] count + position post-substitute)

§7b — Levenshtein divergence

Same as v1 surgical §7c.

§7c — Final score

def candidate_score(c) -> float:
    if not c["meaning_preserved"]: return -1
    if not c["satisfies_fix_goal"]: return -1
    if not c["structural_rubric_pass"]: return -1
    if not c["locks_intact"]: return -1
    return -c["divergence"]  # negate so max(score) = min divergence

Pick argmax. Primary-strategy candidates get tiebreak preference when multiple candidates have score within 0.05 of each other.

§7d — Fallback chain (per §S6 of plan)

primary candidate(s) pass gates? → pick min divergence among them
else: backup candidate(s) pass gates? → pick min divergence among them
else: spawn 1 × P-academic-minimal as last-resort → if passes, use
else: fall back to current_humanized (mark fallback_to_humanized: true, log in surgical_log)

§8 — Doc-level verify (Stage E)

Six checks, plus informational R9 grammar tally:

1. R8 opener regex (4-variant alternation from plan §S5):

R8_OPENER_PATTERNS = [
    # Standard MLA: In "Title" (Publication, Date), Author ...
    r'^In\s+["“][^"”]+["”]\s*\([^)]+,\s*\d+\s+\w+\s+\d{4}\)\s*,\s*[A-Z][\w\.]+',
    # ESL variant 1: In article "Title" on Publication, Date, Author ...
    r'^In\s+article\s+["“][^"”]+["”]\s+on\s+[A-Z][\w\s]+,\s*\d+\s+\w+\s+\d{4}\s*,\s*[A-Z][\w\.]+',
    # ESL variant 2: In Author's article "Title" on Publication (Date), ...
    r'^In\s+[A-Z][\w\.]+\'s\s+article\s+["“][^"”]+["”]\s+on\s+[A-Z][\w\s]+\s*\(',
    # American date order: In "Title" (Pub, Month Day, Year), Author ...
    r'^In\s+["“][^"”]+["”]\s*\([^)]+,\s*\w+\s+\d+,\s*\d{4}\)\s*,\s*[A-Z][\w\.]+',
]
intro_first_sentence = split_sentences(intro_text)[0]
r8_pass = any(re.match(p, intro_first_sentence) for p in R8_OPENER_PATTERNS)

2. R2 body TS markers (each body paragraph's first sentence contains a TS marker):

BODY_TS_MARKERS = [
    r'\bconvincingly\s+argues?\b', r'\bI\s+agree\b', r'\bcould\s+have\s+strengthened\b',
    r'\bone\s+idea\s+I\s+find\b', r'\bI\s+find\b', r'\b[Author A]\s+fails?\b',
]

3. R2 conclusion thesis restatement (first conclusion sentence has restate language):

CONC_RESTATE_MARKERS = [
    r'\bargument\s+(?:is|holds?)\s+strongest', r'\bdefensible\s+version',
    r'\bstructural\s+diagnosis', r'\b[Author A].{0,30}(?:argue|claim|case|argument)',
]

4. R8 quote count: intro 0, body 1 each, conclusion 0.

5. R9 word count band: total in [550, 650].

6. Locks: 17/17 byte-for-byte present.

R9 grammar tally (informational): count visible ESL markers per paragraph. Body 3-5 markers/para target; if > 8 → WARN. Gate segments 0-1 markers; if > 2 → WARN. Log to surgical_log.json regardless.

If any gate WARNs (not FAILs) → status=partial. Caller decides re-invoke vs accept.

§9 — Atomic single pass; caller iterates

Same design as v1 surgical §9 + v2 humanizer §9. Skill is one atomic pass. Caller decides re-invoke based on Grammarly score + human read of grammar marker density.

§10 — Write artifacts

surgical_log.json (extends v1 surgical schema)

{
  "version": 3,
  "draft_path": "...",
  "output_path": "...",
  "config": {
    "include_should_fix": true,
    "include_nice_to_fix": false,
    "strategies": ["P-esl-register-clean", "P-esl-chinese-full", "P-academic-minimal"],
    "fix_queue_size": 25
  },
  "audit": {
    "total_sentences": 23,
    "fix_queue_breakdown": {
      "MUST_FIX_gate": 8,
      "MUST_FIX_body": 0,
      "SHOULD_FIX_body": 10,
      "NICE_TO_FIX_body": 0
    },
    "role_distribution": {...}
  },
  "doc_level_gates": {
    "R8_opener_regex_4_variant": "PASS|FAIL",
    "R2_body_TS_markers": "PASS|FAIL",
    "R2_conclusion_restate": "PASS|FAIL",
    "R8_quote_count": "PASS|FAIL",
    "R9_word_count": "PASS|FAIL (N)",
    "locks_intact": "PASS|FAIL (17/17)",
    "R9_grammar_tally": {"body_per_para": [4, 5, 3], "gate_segments": [0, 1, 0, 0, 2], "warnings": []}
  },
  "status": "ok|partial|error",
  "fallback_segments": <int>,
  "segments_modified": <int>,
  "strategy_usage": {"P-esl-register-clean": <int>, "P-esl-chinese-full": <int>, "P-academic-minimal": <int>},
  "total_llm_calls": <int>,
  "wallclock_seconds": <float>,
  "segments": [...]
}

§11 — Token budget + cross-layer coordination

Inherit from v1 surgical §11. Parallel candidate dispatch within segment; sequential per paragraph (level 2); parallel paragraphs (level 1).