⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

academic-humanizer

dongshuyan@dongshuyan⭐ 768 stars· last commit 9d ago· 0 open issues

>-

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐ 768 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Start here: Use & develop your own Skill ecosystem

A practical tutorial for using SKILL.md, auditing reusable skills, drafting skills with AI, extracting real workflows, and building a local Skill ecosystem.

npx skills add dongshuyan/compass-skills --skill '*' -a claude-code

COMPASS Skills gives AI agents ten local skills: five runtime collaboration skills, two run-history skill-engineering skills, two writing and communication skills, and one local hiring-support skill. It also includes an optional Codex session-title plugin, installed separately.

The project currently ships ten SKILL.md skills:

SkillPurpose
task-clarifierAligns goals, scope, evidence, acceptance criteria, and risk boundaries before ambiguous, costly, or externally visible work.
task-forestMaintains a repo-local task forest / DAG with goals, subtasks, dependencies, progress, deviations, todos, decisions, and conversation history.
pause-and-resumeCooperatively pauses unfinished work at a safe boundary and resumes it from a precise checkpoint in the same AI conversation.
session-handoff-promptCompresses the current AI conversation's goal, progress, constraints, and next steps into a paste-ready prompt for a new AI conversation.
user-profile-keeperMaintains a local, auditable, correctable collaboration profile for communication preferences, risk style, and recurring working context.
run-history-skill-builderTurns completed or repeatedly refined run history into a new reusable skill package or a reviewed skill-design plan.
run-history-skill-upgraderAutomatically turns session evidence from real execution, encountered and resolved difficulties, validation results, and user feedback into an upgrade plan for an existing skill, forming the simplest controlled self-evolution loop; it applies changes only after explicit approval.
clear-communicationOrganizes explanations, reports, comparisons, and instructions around the reader’s task while preserving facts, conditions, uncertainty, and verification state.
academic-humanizerHelps write or revise English and Chinese academic prose by removing formulaic AI-like patterns and restoring a natural scholarly voice while preserving claims, evidence strength, and logical relations.
assess-interview-candidateTurns an authorized resume and job description into an auditable evidence layer and a concise three-part offline interviewer report, with locally sanitized resume portraits and bounded timeline-age estimates kept outside scoring.

The optional Agent Clarity title plugin lives under plugins/clarity-session-titles/; it has a separate installer and is not one of these ten portable skills.

For multi-skill repositories, install only the functions you actually need. Use pause-and-resume when the same AI conversation will remain available; use session-handoff-prompt when work must move to a fresh conversation. The run-history pair supports skill engineering. Use clear-communication to organize explanations for the reader, and academic-humanizer to improve academic prose without changing its claims.

Quick Start

List the available skills before installing:

npx skills add dongshuyan/compass-skills --list

Install all skills for Claude Code:

npx skills add dongshuyan/compass-skills --skill '*' -a claude-code

Install all skills for both Codex and Claude Code:

npx skills add dongshuyan/compass-skills --skill '*' -a codex -a claude-code

After installation, invoke the skills directly in an AI conversation:

$task-clarifier
$task-forest
$pause-and-resume
$session-handoff-prompt
$user-profile-keeper
$run-history-skill-builder
$run-history-skill-upgrader
$clear-communication
$academic-humanizer
$assess-interview-candidate

For manual installation, copy the required folders under skills/ into the agent's local skills directory and keep their references/, scripts/, assets/, evals/, and agents/ subdirectories intact.

Why COMPASS Exists

Long-running agent work needs five kinds of state:

  • User context: communication preferences, risk boundaries, recurring omissions, and collaboration style.
  • Project context: where the current request fits, what it depends on, and how far it has progressed.
  • Goal context: how the current task contributes to the original objective and whether it still matches it.
  • Pause context: the safe stopping point, remaining work, non-repeatable effects, and first action when the same AI conversation resumes.
  • Handoff context: what a new AI conversation needs to continue the current task without replaying the whole transcript.

COMPASS organizes that state into five local workflows:

  1. A local profile that the user can inspect and correct.
  2. A repo-local task graph that survives AI conversation boundaries.
  3. A cooperative pause checkpoint for continuing in the same AI conversation.
  4. A paste-ready continuation prompt for a new AI conversation.
  5. A clarification gate before ambiguous or risky execution.

How The Core And Meta Skills Work Together

task-clarifier is the entry point for ambiguous, high-cost, high-risk, evidence-sensitive, or externally visible work. It first identifies the user-owned decisions that must be made, asks up to three focused questions with recommended answers when open decisions remain, and can ask no questions when lookup resolves them. It always confirms shared understanding before searching or executing.

task-forest records long-running work structure: why a task exists, where it fits, how far it progressed, what changed, and what remains unresolved.

pause-and-resume stops an unfinished task at the nearest safe boundary, records what must and must not be repeated, and continues from that checkpoint when the user returns to the same AI conversation. It creates no file solely for pausing.

session-handoff-prompt turns the current AI conversation, explicit transcripts, workspace evidence, and optional task-forest exports into a concise prompt for the next AI conversation. It reads task-forest as structured context but never modifies it.

user-profile-keeper stores collaboration preferences locally. Future AI conversations use the profile to ask relevant questions and apply the right risk boundary. Current files, logs, and user-provided context remain the authority; secrets stay out of the profile.

`run-history-skill-builder

// HOW IT'S BUILT

// FILES

14 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/academic-humanizer/SKILL.md17 KB9144b83d3a69upstream ↗
    ---
    name: academic-humanizer
    description: >-
      Draft, audit, or minimally revise English- or Chinese-language academic prose
      to reduce formulaic, vacuous, mechanically repetitive, or process-leaking
      language while preserving claims, evidence strength, logical relations,
      manuscript-wide terminology identity, document-level pattern variation, and
      scholarly register. Use for papers, abstracts, grants, cover letters, and
      reviewer responses when the user asks to de-AI, humanize, audit AI-like
      phrasing, or rewrite text without changing meaning. English is primary;
      Chinese is supported. Not for detector evasion, policy circumvention, pure
      translation, non-academic copy, or adding facts, citations, examples, or
      author experiences that the source does not contain.
    ---
    
    # Academic Humanizer
    
    Improve academic prose by removing observable writing defects, not by imitating
    imperfection or optimizing an authorship detector. Preserve the author's facts,
    argument, uncertainty, and disciplinary voice. This skill does not guarantee how
    any reader or detector will classify a text.
    
    ## Portability
    
    This skill is agent-agnostic. Its core behavior is defined by `SKILL.md` and
    `references/`; Python is optional and supports reproducible diagnostics.
    
    - Resolve `<skill-dir>` from the directory containing this `SKILL.md`.
    - Let `<python>` mean an available Python 3 launcher, such as `python3`, `py -3`,
      or `python`.
    - Let `<input-file>` mean a user-authorized local text file. Quote paths that
      contain spaces and use the host shell's path separator.
    - Do not assume a fixed skill root, home directory, shell, operating system,
      agent name, or path separator.
    - `agents/openai.yaml` is optional interface metadata. Core behavior does not
      depend on a particular agent runtime.
    - If Python is unavailable, skip the scripts and apply the same contracts
      directly.
    
    ## Load the operating references
    
    Read these before drafting or editing:
    
    1. [Semantic contract](references/semantic-contract.md) for claim preservation,
       locked spans, deletion safety, and the internal claim ledger.
    2. [Terminology contract](references/terminology-contract.md) for canonical terms,
       declared aliases, coined names, intentional distinctions, and the internal
       terminology ledger. Always load it for multi-span or manuscript-level work.
    3. [Global pattern contract](references/global-pattern-contract.md) for the
       local-to-document audit, distribution map, scope limits, and whole-document
       repair. Always load it for multi-sentence work.
    4. [Academic whitelist](references/whitelist-academic.md) for protected scholarly
       forms in both languages.
    5. [Contrast logic](references/contrast-logic.md) for false-opposition triage in
       English and Chinese. Always load it; this is a cross-language semantic rule.
    6. Route once by the majority language of editable prose, then read exactly one:
       [English rules](references/rules-en.md) or
       [Chinese rules](references/rules-zh.md).
    
    Read [worked examples](references/examples.md) on first use, after changing a
    rule, or whenever fact preservation, contrast, or over-correction is uncertain.
    Read [metrics specification](references/metrics-spec.md) before running
    `scripts/metrics.py`; its output is descriptive evidence only.
    
    ## Supported operations
    
    - **generate**: draft from user-supplied claims, outline, data, and sources.
    - **detect**: identify high-confidence defects without rewriting.
    - **rewrite**: minimally revise supplied prose; this is the default when the user
      asks to de-AI or humanize text.
    - **edit**: apply the same minimal revisions to a named file.
    
    Do not create another routing tree for paper section or discipline. Methods,
    Results, Discussion, reviewer responses, and grants use the same contracts; the
    whitelist handles legitimate register differences. Ask one direct question only
    when the requested genre changes what counts as acceptable and context does not
    resolve it.
    
    ## Language route
    
    Route on editable prose, excluding fenced code, formulas, block quotations, and
    a trailing reference list. Use orthographic tokens: each CJK character is one
    token and each contiguous Latin word is one token. This keeps embedded terms such
    as `Transformer` or `ImageNet` from outweighing the Chinese sentence around them:
    
    `r = CJK tokens / (CJK tokens + Latin word tokens)`
    
    - `r >= 0.5`: Chinese branch.
    - `r < 0.5`: English branch.
    - No countable prose: stop and ask for text or an intended output language.
    
    English terms in Chinese prose and Chinese terms in English prose remain
    verbatim. If Python is available and the route is genuinely unclear, optionally
    run `<python> "<skill-dir>/scripts/metrics.py" "<input-file>" --route`.
    Routing is internal and never appears in the clean artifact.
    
    ## Single arbitration order
    
    Earlier rows win. References may elaborate this table but must not define a
    second priority order.
    
    | Priority | Constraint | Operational meaning |
    |---|---|---|
    | **C0** | Artifact boundary | Process instructions, editor narration, and tool residue never enter the artifact. C0 applies only to process-layer text; it never authorizes deletion of real content. |
    | **C1** | Semantic fidelity | Every output claim maps to the source bundle; every material source claim remains represented. No added facts, relations, examples, citations, motivations, or limitations. |
    | **C2** | Locked-span protection | Quotations, formulas, code, references, citation keys, statistical notation, proper nouns, and requested verbatim text remain unchanged. |
    | **C3** | Terminology identity | One scientific concept uses one canonical term across the editable manuscript. Preserve declared full-name/abbreviation pairs, necessary grammatical forms, and intentional distinctions; never infer identity from similarity alone. |
    | **C4** | Academic register | Preserve functional hedging, passive voice, nominalization, discourse markers, and Chinese scholarly morphology. |
    | **C5** | Argument structure | Preserve causal strength, contrast, concession, addition, chronology, scope, and paragraph-level reasoning. Surface connectives may change when the relation survives. |
    | **C6** | Document patterning | Audit recurrence, clustering, dispersion, positional regularity, sentence rhythm, and rhetorical-function saturation across the complete editable scope. A count is evidence, never a verdict. |
    | **C7** | Local style repair | Apply language-specific rules only to locally unsupported, vacuous, mechanical, or stacked defects. |
    
    Examples of conflict resolution:
    
    - A style rule suggests adding a number, mechanism, baseline, or limitation that
      is absent from the source: C1 blocks the addition.
    - A leak and a result share one sentence: C0 removes only the process phrase;
      C1 and C5 preserve the result and its relation to adjacent sentences.
    - A coined method name drifts across the abstract, body, and caption: C3 restores
      the canonical term after C1 and C2 confirm that the referent and spans permit it.
    - A passive sentence is conventional in Methods: C4 blocks stylistic activation.
    - A contrast pattern is present but its two concrete claims lack surrounding
      evidence: C1 blocks automatic deletion; mark it uncertain in diagnostic output.
    - One dash, triad, connective, or emphatic sentence has a clear function: C4-C6
      protect it. Repeated functionless instances may activate C6 after a distribution
      audit, while C1-C5 still constrain every repair.
    
    ## Workflow
    
    ### 1. Read the complete editable scope
    
    Read all supplied title, abstract, body sections, captions, tables, appendices,
    and supplementary prose before changing anything. Identify which parts are
    editable and which are evidence or protected context. Separate content
    requirements from style/process instructions. For generation, treat only
    supplied claims, data, citations, and explicitly marked hypotheticals as content.
    
    ### 2. Lock spans and build the evidence and terminology ledgers
    
    Apply the semantic and terminology contracts. Build the claim/evidence ledger
    with source-to-output mappings and provenance status for:
    
    - numbers, units, entities, citations, datasets, methods, and study design;
    - negation, comparison direction and baseline;
    - association, causation, prediction, and attribution;
    - modality, uncertainty, limitations, population, time, and scope.
    
    The editable draft establishes what the author currently says; it does not by
    itself prove that a cited paper, result, quotation, or factual premise exists.
    Mark unsupported evidence assertions as `draft-only` and preserve or flag them
    instead of silently treating them as verified or extending the argument from them.
    
    Build a separate terminology ledger for scientific concepts, especially newly
    coined methods, modules, losses, metrics, datasets, and task names. Record:
    
    - `concept_id`, `canonical_term`, and the span that defines or first formally
      names the concept;
    - declared `allowed_forms`, including full-name/abbreviation pairs and necessary
      grammatical or bilingual mappings;
    - `observed_variants`, `distinguish_from`, and resolution `status`.
    
    Use explicit user terminology first, then formal definitions, then the first
    unambiguous formal naming. Frequency alone never selects the canonical term.
    Keep both ledgers internal unless the user asks for an audit trail.
    
    ### 3. Run the local candidate pass
    
    1. Find process leakage and tool residue.
    2. Audit terminology across the complete editable scope. Classify each apparent
       variation as **declared form**, **same-concept drift**, **intentional
       distinction**, **protected mention**, or **uncertain identity**.
    3. Triage contrast candidates as **protected**, **unsupported rhetorical**, or
       **uncertain** using `contrast-logic.md`.
    4. Apply the routed language rules to identify candidates with three questions:
       - **Load**: does the wording carry a claim or logical relation?
       - **Support**: can each claim be traced to the source bundle?
       - **Patterning**: is the defect mechanical, vacuous, or reinforced by other
         signals in the same span?
    
    A lone word or sentence form is not enough to infer authorship or poor quality.
    It can still be a local defect when it adds an unsupported claim, false relation,
    or empty evaluation. Multiple weak signals in one span form one finding, not
    several duplicate findings.
    
    ### 4. Build the distribution map and run the global pass
    
    For multi-sentence input, map candidates by section, paragraph, sentence,
    position, and rhetorical function using `global-pattern-contract.md`. Inspect:
    
    - sentence-initial discourse markers and punctuation such as dashes;
    - contrast scaffolds, parallel triads, flat enumeration, and exhaustive listing;
    - repeated sentence/paragraph templates and recurring paragraph closures;
    - sentence-length sequence and rhythm within each functional section;
    - unsupported certainty, elevation, and aphoristic peak saturation.
    
    Use within-document evidence and section function; never apply a universal count
    or ratio. A distribution map supports findings only about the supplied editable
    scope; an excerpt cannot support a whole-manuscript judgment. Optional metrics
    produce a distribution map, not an authorship or quality judgment.
    
    ### 5. Classify before editing
    
    Classify each finding as **local defect**, **distributional defect**,
    **functional/protected**, or **uncertain**. A distributional defect requires both
    repetition or positional regularity and redundant rhetorical function. Several
    valid ablation contrasts, method steps, reported metrics, or theorem consequences
    remain protected even when their surface forms repeat.
    
    ### 6. Make the smallest coherent edit
    
    - Remove process-layer text while retaining any content in the same sentence.
    - Normalize confirmed same-concept drift to the ledger's canonical term across
      every editable occurrence, including captions and tables. Preserve declared
      abbreviations and grammatical forms; do not replace protected mentions.
    - Keep terms separate when they name distinct concepts. If identity is uncertain,
      preserve the text and ask or flag it outside the clean artifact.
    - Prefer subtraction or direct wording when a phrase carries no proposition.
    - Use concrete material only when it already exists in the source.
    - Preserve both claims in additive forms such as `not only X but also Y` when X
      and Y are supported; removing the construction must not remove either claim.
    - Preserve or flag concrete negative claims when evidence is insufficient to
      decide whether the contrast is real. Do not silently erase them.
    - Repair the document as a system: remove redundant scaffolding, retain each
      supported proposition and relation, and vary syntax only when argument function
      warrants it. Do not randomize sentence length or replace one repeated template
      with another repeated template.
    - Reorganize flat enumeration only when the source already supplies a hierarchy.
      Never invent categories merely to make a list appear elegant.
    - Preserve an unverified citation or evidence claim in rewrite/edit mode and flag
      it outside the artifact; do not strengthen it or use it to generate new claims.
    - Leave already competent prose unchanged.
    
    ### 7. Run the whole-manuscript terminology gate
    
    Scan all editable sections together after revision. Every scientific concept
    must use its canonical term or a declared allowed form. Verify that coined names
    are unchanged after their formal introduction, captions and tables match the
    body, bilingual mappings are declared, and distinct concepts remain distinct.
    Any unresolved identity is a stop/flag result, not an automatic normalization.
    
    ### 8. Run the whole-document pattern gate
    
    Rebuild the distribution map after editing. Check that redundant clusters,
    mechanical paragraph templates, uniform rhetorical peaks, and unsupported
    certainty were resolved without erasing functional repetition or creating a new
    dominant pattern. If the supplied scope is shorter than the claimed scope, report
    the limitation and do not claim a whole-manuscript pass.
    
    ### 9. Run the second-pass semantic and style gate
    
    Re-read source and output side by side. The output fails if any answer is no:
    
    1. Does every output claim map to the source bundle?
    2. Does every material source claim remain?
    3. Are numbers, negation, modality, causal strength, baseline, attribution, and
       scope unchanged?
    4. Are locked spans byte-for-byte unchanged?
    5. Does the terminology ledger show one canonical term per concept, with only
       declared forms and intentional distinctions remaining?
    6. Are cited evidence, quotations, and factual premises supported by supplied or
       verified sources, or explicitly marked `draft-only` outside the artifact?
    7. Did the edit preserve academic register and logical relations?
    8. Did the whole-document pattern gate pass without threshold chasing?
    9. Is the artifact free of process labels, editor narration, placeholders filled
       by guesswork, and tool residue?
    10. Would a zero-edit result have been more accurate? If yes, restore the source.
    
    Run metrics only as an optional residual scan. A metric never overrides this gate.
    
    ## Output contract
    
    - **generate / rewrite**: return the clean artifact by default, with no routing
      line, score, checklist, leak line, or editor preface.
    - **detect**: return findings grouped by severity and scope (`local` or
      `distributional`). Each finding includes an exact source quote, rule ID,
      location/distribution evidence, reason, and one of `change`, `keep`, or
      `uncertain`.
    - **edit**: edit only the requested file, then summarize changes outside it.
    - Provide diagnostics after the artifact only when the user explicitly asks for
      them. Clearly separate diagnostics from text intended for the manuscript.
    - Use verified counts only. Never invent a count or aesthetic grade.
    
    ## Stop conditions
    
    Stop and ask instead of guessing when:
    
    - the requested rewrite requires a missing fact, citation, comparison, or source;
    - a concrete contrast cannot be validated from the available context;
    - the requested generation, verification, or downstream conclusion depends on a
      citation, result, quotation, or factual premise whose existence or provenance
      cannot be established from the source bundle;
    - two labels may refer to the same scientific concept but the manuscript does
      not establish their identity, or no canonical term can be grounded;
    - the input is mostly a protected quotation, formula, or reference list;
    - the user requests a whole-document judgment but supplies only an excerpt;
    - the requested language is neither English nor Chinese;
    - the request seeks detector evasion or circumvention of a disclosure policy.
    
    Do not invent specifics, personal experience, citations, data, mechanisms,
    baselines, or limitations to make prose sound more human. Do not casualize
    academic writing merely to make it look less generated.
    
  • skills/academic-humanizer/scripts/metrics.py27 KB349aa47101efupstream ↗
    #!/usr/bin/env python3
    """Descriptive diagnostics for academic-humanizer.
    
    The script reports reproducible candidates and counts. It does not identify an
    author, assign an AI probability, or decide whether prose needs revision.
    """
    
    import argparse
    import json
    import re
    import statistics
    import sys
    
    
    CJK_RE = re.compile(r"[㐀-䶿一-鿿]")
    LATIN_WORD_RE = re.compile(r"[A-Za-z]+(?:['-][A-Za-z]+)*")
    
    FENCED_CODE_RE = re.compile(r"```.*?```|~~~.*?~~~", re.S)
    INLINE_CODE_RE = re.compile(r"`[^`\n]*`")
    DISPLAY_MATH_RE = re.compile(
        r"\$\$.*?\$\$|\\\[.*?\\\]|\\begin\{(?:equation\*?|align\*?|gather\*?)\}.*?"
        r"\\end\{(?:equation\*?|align\*?|gather\*?)\}",
        re.S,
    )
    INLINE_MATH_RE = re.compile(r"(?<!\$)\$(?!\$)[^$\n]+(?<!\$)\$(?!\$)|\\\([^\n]*?\\\)")
    BLOCK_QUOTE_RE = re.compile(r"(?m)^[ \t]*>[^\n]*(?:\n|$)")
    REFERENCE_HEADINGS = frozenset(
        {
            "references",
            "bibliography",
            "works cited",
            "参考文献",
            "参考文献(references)",
            "参考文献 (references)",
            "references(参考文献)",
            "references (参考文献)",
        }
    )
    MARKDOWN_HEADING_PREFIX_RE = re.compile(r"^[ \t]{0,3}#{1,6}[ \t]*")
    SECTION_NUMBER_PREFIX_RE = re.compile(
        r"^(?:(?:\d+(?:\.\d+)*)|[一二三四五六七八九十百]+)"
        r"\s*(?:(?:[.))]|[、.::])\s*|\s+)"
    )
    TRAILING_HEADING_PUNCT_RE = re.compile(r"[ \t]*[::][ \t]*$")
    
    DOUBLE_QUOTE_RE = re.compile(r'"(?:\\.|[^"\\])*"', re.S)
    SINGLE_QUOTE_RE = re.compile(r"(?<![A-Za-z])'(?:\\.|[^'\\\n])+'(?![A-Za-z])")
    CURLY_DOUBLE_QUOTE_RE = re.compile(r"“[^”]*”", re.S)
    CURLY_SINGLE_QUOTE_RE = re.compile(r"‘[^’]*’", re.S)
    
    
    def _blank(match):
        """Mask a span without changing offsets or line boundaries."""
        return "".join("\n" if char == "\n" else " " for char in match.group(0))
    
    
    def _mask_regex(text, regex):
        return regex.sub(_blank, text)
    
    
    def _normalize_reference_heading(line):
        """Return a canonical reference heading or None for ordinary prose."""
        candidate = line.strip().lstrip("")
        candidate = MARKDOWN_HEADING_PREFIX_RE.sub("", candidate)
        candidate = SECTION_NUMBER_PREFIX_RE.sub("", candidate)
        candidate = TRAILING_HEADING_PUNCT_RE.sub("", candidate)
        candidate = " ".join(candidate.split()).casefold()
        return candidate if candidate in REFERENCE_HEADINGS else None
    
    
    def _reference_section_start(text):
        """Find the last standalone, normalized reference heading."""
        offset = 0
        start = None
        for line in text.splitlines(keepends=True):
            if _normalize_reference_heading(line.rstrip("\r\n")):
                start = offset
            offset += len(line)
        return start
    
    
    def mask_nonprose(text):
        """Mask code, math, block quotes, and a trailing reference section."""
        masked = text
        for regex in (
            FENCED_CODE_RE,
            INLINE_CODE_RE,
            DISPLAY_MATH_RE,
            INLINE_MATH_RE,
            BLOCK_QUOTE_RE,
        ):
            masked = _mask_regex(masked, regex)
    
        start = _reference_section_start(masked)
        if start is not None:
            masked = masked[:start] + "".join(
                "\n" if char == "\n" else " " for char in masked[start:]
            )
        return masked
    
    
    def mask_scan_protected(text):
        """Mask nonprose and direct-quotation spans for candidate scans."""
        masked = mask_nonprose(text)
        for regex in (
            DOUBLE_QUOTE_RE,
            SINGLE_QUOTE_RE,
            CURLY_DOUBLE_QUOTE_RE,
            CURLY_SINGLE_QUOTE_RE,
        ):
            masked = _mask_regex(masked, regex)
        return masked
    
    
    def route(text):
        """Return (branch, ratio, CJK tokens, Latin word tokens).
    
        CJK characters and Latin word runs are orthographic tokens. Treating an
        embedded technical term as one Latin token prevents a few long model names
        from overriding the grammar of a Chinese sentence.
        """
        prose = mask_nonprose(text)
        cjk = len(CJK_RE.findall(prose))
        latin = len(LATIN_WORD_RE.findall(prose))
        total = cjk + latin
        if total == 0:
            return "unknown", None, cjk, latin
        ratio = round(cjk / total, 4)
        return ("zh" if ratio >= 0.5 else "en"), ratio, cjk, latin
    
    
    EN_SENT_SPLIT_RE = re.compile(r"(?<=[.!?])\s+(?=[A-Z\"'(\[])")
    ZH_SENT_SPLIT_RE = re.compile(r"(?<=[。!?;])")
    
    
    def sentences(text, branch):
        prose = re.sub(r"\s*\n\s*", " ", mask_nonprose(text)).strip()
        if not prose:
            return []
        splitter = ZH_SENT_SPLIT_RE if branch == "zh" else EN_SENT_SPLIT_RE
        return [part.strip() for part in splitter.split(prose) if part.strip()]
    
    
    def sentence_length(sentence, branch):
        if branch == "zh":
            return len(CJK_RE.findall(sentence)) + len(LATIN_WORD_RE.findall(sentence))
        return len(LATIN_WORD_RE.findall(sentence))
    
    
    def lexical_diversity(text, branch):
        prose = mask_nonprose(text)
        if branch == "zh":
            tokens = CJK_RE.findall(prose)
            measure = "character_diversity"
            unit = "cjk_characters"
        elif branch == "en":
            tokens = [word.lower() for word in LATIN_WORD_RE.findall(prose)]
            measure = "word_ttr"
            unit = "latin_words"
        else:
            tokens = []
            measure = "unavailable"
            unit = "none"
        value = round(len(set(tokens)) / len(tokens), 4) if tokens else None
        return {
            "measure": measure,
            "value": value,
            "tokens": len(tokens),
            "unit": unit,
            "limitation": "length_sensitive_description_only",
        }
    
    
    def sentence_stats(text, branch):
        if branch not in {"en", "zh"}:
            return {"n": 0, "mean": None, "stdev": None, "min": None, "max": None}
        lengths = [
            sentence_length(sentence, branch)
            for sentence in sentences(text, branch)
            if sentence_length(sentence, branch) > 0
        ]
        if not lengths:
            return {"n": 0, "mean": None, "stdev": None, "min": None, "max": None}
        return {
            "n": len(lengths),
            "mean": round(statistics.mean(lengths), 2),
            "stdev": round(statistics.stdev(lengths), 2) if len(lengths) > 1 else 0.0,
            "min": min(lengths),
            "max": max(lengths),
        }
    
    
    EN_TRANSITIONS = (
        "moreover",
        "furthermore",
        "additionally",
        "in addition",
        "however",
        "therefore",
        "thus",
        "hence",
        "nevertheless",
        "nonetheless",
        "consequently",
        "accordingly",
        "specifically",
        "based on these results",
        "taken together",
    )
    ZH_TRANSITIONS = (
        "然而",
        "相比之下",
        "此外",
        "因此",
        "据此",
        "与此同时",
        "具体而言",
        "基于上述结果",
        "综上",
        "值得注意的是",
    )
    
    
    def transition_density(text, branch):
        spans = sentences(text, branch)
        if not spans:
            return 0.0, {}
        vocabulary = ZH_TRANSITIONS if branch == "zh" else EN_TRANSITIONS
        counts = {}
        for sentence in spans:
            head = sentence.lstrip('"“\'(').lower() if branch == "en" else sentence.lstrip('“"((')
            for marker in vocabulary:
                if head.startswith(marker):
                    counts[marker] = counts.get(marker, 0) + 1
                    break
        hits = sum(counts.values())
        return round(100.0 * hits / len(spans), 1), counts
    
    
    PASSIVE_PARTICIPLES = (
        "analyzed",
        "analysed",
        "applied",
        "assigned",
        "built",
        "calculated",
        "collected",
        "computed",
        "conducted",
        "defined",
        "derived",
        "drawn",
        "estimated",
        "evaluated",
        "excluded",
        "followed",
        "found",
        "given",
        "implemented",
        "included",
        "incubated",
        "measured",
        "observed",
        "obtained",
        "performed",
        "randomized",
        "randomised",
        "recorded",
        "reported",
        "selected",
        "shown",
        "tested",
        "trained",
        "used",
    )
    PASSIVE_CANDIDATE_RE = re.compile(
        r"\b(?:am|is|are|was|were|be|been|being)\s+(?:\w+ly\s+)?(?:"
        + "|".join(PASSIVE_PARTICIPLES)
        + r")\b",
        re.I,
    )
    
    
    def passive_candidates_en(text):
        """Return conservative candidates; absence is not evidence of active voice."""
        return [
            {"match": match.group(0), "sentence": sentence}
            for sentence in sentences(text, "en")
            for match in [PASSIVE_CANDIDATE_RE.search(sentence)]
            if match
        ]
    
    
    def dash_counts(text):
        fullwidth_double = len(re.findall(r"(?<!—)——(?!—)", text))
        without_pairs = re.sub(r"(?<!—)——(?!—)", "  ", text)
        return {
            "em_dash_single": without_pairs.count("—"),
            "fullwidth_double": fullwidth_double,
            "double_hyphen": len(re.findall(r"(?<!-)--(?!-)", text)),
            "en_dash_spaced": len(re.findall(r"\s–\s", text)),
        }
    
    
    ZH_CERTAINTY_RE = re.compile(r"毫无疑问|毋庸置疑|不容置疑|无疑|必然|一定|显然")
    EN_CERTAINTY_RE = re.compile(
        r"\b(?:without (?:a )?doubt|undoubtedly|certainly|inevitably|necessarily|clearly)\b",
        re.I,
    )
    ZH_ENDING_ELEVATION_RE = re.compile(
        r"(?:彰显|体现|反映|标志|凸显|印证)(?:了|着)?[^。!?;]{0,24}[。!?;]?$"
    )
    EN_ENDING_ELEVATION_RE = re.compile(
        r"\b(?:underscores?|highlights?|marks?|showcases?|is a testament to)\b"
        r"[^.!?]{0,30}[.!?]?$",
        re.I,
    )
    ZH_PARALLEL_ENUMERATION_RE = re.compile(
        r"[^,。!?;\n]{1,24}、[^,。!?;\n]{1,24}"
        r"(?:、|以及|和|及|与)[^,。!?;\n]{1,24}"
    )
    EN_PARALLEL_ENUMERATION_RE = re.compile(
        r"\b[A-Za-z][A-Za-z -]{0,24},\s+[A-Za-z][A-Za-z -]{0,24},\s+"
        r"(?:and|or)\s+[A-Za-z][A-Za-z -]{0,24}\b",
        re.I,
    )
    ZH_REPEATED_OPENING_PATTERNS = (
        ("从…角度看", re.compile(r"^从[^,。!?;]{1,12}角度(?:看|而言)[,,::]?")),
        ("更重要的是", re.compile(r"^更重要的是[,,::]?")),
        ("值得注意的是", re.compile(r"^值得注意的是[,,::]?")),
        ("此外", re.compile(r"^此外[,,::]?")),
        ("然而", re.compile(r"^然而[,,::]?")),
    )
    EN_REPEATED_OPENING_PATTERNS = (
        ("from … perspective", re.compile(r"^from (?:an?|the) [^,]{1,30} perspective,?", re.I)),
        ("more importantly", re.compile(r"^more importantly,?", re.I)),
        ("it is worth noting", re.compile(r"^it is worth noting that\b", re.I)),
        ("moreover", re.compile(r"^moreover,?", re.I)),
        ("however", re.compile(r"^however,?", re.I)),
    )
    
    
    def _profile_paragraphs(text):
        """Return protected-span-masked prose paragraphs for descriptive profiling."""
        masked = mask_scan_protected(text)
        blocks = re.split(r"\n\s*\n+", masked)
        return [block.strip() for block in blocks if CJK_RE.search(block) or LATIN_WORD_RE.search(block)]
    
    
    def _sentence_records(text, branch):
        records = []
        global_index = 0
        for paragraph_index, paragraph in enumerate(_profile_paragraphs(text), start=1):
            for sentence_index, sentence in enumerate(sentences(paragraph, branch), start=1):
                length = sentence_length(sentence, branch)
                if length == 0:
                    continue
                global_index += 1
                records.append(
                    {
                        "paragraph": paragraph_index,
                        "sentence": global_index,
                        "sentence_in_paragraph": sentence_index,
                        "length": length,
                        "text": sentence,
                    }
                )
        return records
    
    
    def _candidate_record(record, match):
        return {
            "paragraph": record["paragraph"],
            "sentence": record["sentence"],
            "match": match,
            "status": "candidate_only",
        }
    
    
    def _regex_candidates(records, regex):
        hits = []
        for record in records:
            match = regex.search(record["text"])
            if match:
                hits.append(_candidate_record(record, match.group(0)))
        return hits
    
    
    def _initial_marker_profile(records, branch):
        vocabulary = ZH_TRANSITIONS if branch == "zh" else EN_TRANSITIONS
        hits = []
        counts = {}
        for record in records:
            head = (
                record["text"].lstrip('“"((')
                if branch == "zh"
                else record["text"].lstrip('\"\'([').lower()
            )
            for marker in vocabulary:
                if head.startswith(marker):
                    counts[marker] = counts.get(marker, 0) + 1
                    hit = _candidate_record(record, marker)
                    hit["marker"] = marker
                    hits.append(hit)
                    break
        return {
            "count": len(hits),
            "by_marker": counts,
            "paragraphs": sorted({hit["paragraph"] for hit in hits}),
            "occurrences": hits,
            "status": "candidate_only",
        }
    
    
    def _dash_distribution(records):
        occurrences = []
        for record in records:
            counts = dash_counts(record["text"])
            count = sum(counts.values())
            if count:
                hit = _candidate_record(record, record["text"])
                hit["count"] = count
                hit["by_glyph"] = counts
                occurrences.append(hit)
        return {
            "count": sum(hit["count"] for hit in occurrences),
            "paragraphs": sorted({hit["paragraph"] for hit in occurrences}),
            "occurrences": occurrences,
            "status": "candidate_only",
        }
    
    
    def _repeated_opening_candidates(records, branch):
        patterns = ZH_REPEATED_OPENING_PATTERNS if branch == "zh" else EN_REPEATED_OPENING_PATTERNS
        grouped = {}
        for record in records:
            head = record["text"].lstrip('“"((').strip()
            for key, regex in patterns:
                if regex.search(head):
                    grouped.setdefault(key, []).append(record)
                    break
        return [
            {
                "pattern": key,
                "count": len(group),
                "paragraphs": sorted({record["paragraph"] for record in group}),
                "sentences": [record["sentence"] for record in group],
                "status": "candidate_only",
            }
            for key, group in grouped.items()
            if len(group) > 1
        ]
    
    
    def _contrast_distribution(records, branch):
        occurrences = []
        for record in records:
            for candidate in contrast_candidates(record["text"], branch):
                occurrences.append(
                    {
                        "paragraph": record["paragraph"],
                        "sentence": record["sentence"],
                        "rule": candidate["rule"],
                        "match": candidate["match"],
                        "status": "candidate_only",
                    }
                )
        return {
            "count": len(occurrences),
            "paragraphs": sorted({item["paragraph"] for item in occurrences}),
            "occurrences": occurrences,
            "status": "candidate_only",
        }
    
    
    def global_pattern_profile(text, branch):
        """Return a location-aware profile; semantic decisions remain model work."""
        if branch not in {"en", "zh"}:
            return {
                "scope": {"paragraphs": 0, "sentences": 0},
                "sentence_length_sequence": [],
                "sentence_initial_markers": {"count": 0, "by_marker": {}, "paragraphs": [], "occurrences": [], "status": "candidate_only"},
                "dash_distribution": {"count": 0, "paragraphs": [], "occurrences": [], "status": "candidate_only"},
                "contrast_distribution": {"count": 0, "paragraphs": [], "occurrences": [], "status": "candidate_only"},
                "parallel_enumeration_candidates": [],
                "certainty_candidates": [],
                "ending_elevation_candidates": [],
                "repeated_opening_candidates": [],
                "interpretation": "candidate_only_no_authorship_or_quality_verdict",
            }
    
        records = _sentence_records(text, branch)
        certainty_re = ZH_CERTAINTY_RE if branch == "zh" else EN_CERTAINTY_RE
        elevation_re = ZH_ENDING_ELEVATION_RE if branch == "zh" else EN_ENDING_ELEVATION_RE
        enumeration_re = ZH_PARALLEL_ENUMERATION_RE if branch == "zh" else EN_PARALLEL_ENUMERATION_RE
        return {
            "scope": {
                "paragraphs": len({record["paragraph"] for record in records}),
                "sentences": len(records),
            },
            "sentence_length_sequence": [
                {
                    "paragraph": record["paragraph"],
                    "sentence": record["sentence"],
                    "length": record["length"],
                }
                for record in records
            ],
            "sentence_initial_markers": _initial_marker_profile(records, branch),
            "dash_distribution": _dash_distribution(records),
            "contrast_distribution": _contrast_distribution(records, branch),
            "parallel_enumeration_candidates": _regex_candidates(records, enumeration_re),
            "certainty_candidates": _regex_candidates(records, certainty_re),
            "ending_elevation_candidates": _regex_candidates(records, elevation_re),
            "repeated_opening_candidates": _repeated_opening_candidates(records, branch),
            "interpretation": "candidate_only_no_authorship_or_quality_verdict",
        }
    
    
    ZH_PROCESS_TARGET = (
        r"(?:本文|本稿|本节|本段|此段|该段|本部分|此部分|该部分|"
        r"以下|下文|这里|此处|稿件|文本|版本|措辞|句式|表达|"
        r"控制|压缩|改写|修改|调整|采用|使用|删除|保留|限制|润色)"
    )
    ZH_REQUEST_LEAD = r"(?:按|按照|依照|根据)"
    ZH_REQUEST_ADDRESSEE = r"(?:您|你|用户)(?:的)?"
    ZH_REQUESTED_PROCESS_RE = re.compile(
        r"(?:"
        + ZH_REQUEST_LEAD
        + ZH_REQUEST_ADDRESSEE
        + r"(?:要求|指示)"
        r"|"
        + ZH_REQUEST_LEAD
        + r"(?:要求|指示)[,,::]?\s*[^。!?\n]{0,12}"
        + ZH_PROCESS_TARGET
        + r")"
    )
    ZH_DOCUMENT_SUBJECT = (
        r"(?:本文|本稿|本节|本段|此段|该段|文本|稿件|内容|表达|措辞|句式)"
    )
    ZH_AI_STYLE_SELF_REFERENCE_RE = re.compile(
        r"(?:"
        r"(?:为了|为|以)\s*(?:(?:避免|防止)\s*)?(?:不\s*)?"
        r"(?:(?:让|使)\s*)?"
        + ZH_DOCUMENT_SUBJECT
        + r"?\s*(?:显得|看起来|读起来|听起来)\s*像\s*AI(?:\s*生成)?"
        r"|(?:为了|为|以)\s*不\s*像\s*AI(?:\s*生成)?"
        r"|(?:为了|为|以)?\s*(?:避免|防止|消除|去除)\s*"
        r"(?:使用\s*)?AI\s*(?:味|腔|痕迹|写作痕迹|生成痕迹)"
        r")",
        re.I,
    )
    ZH_DISCUSSION_PREFIX_RE = re.compile(
        r"(?:"
        r"(?:研究|分析|评估|调查|讨论|考察|测试|检测)(?:了|中|表明|发现)?"
        r"|(?:提示词?|指令|问卷|语料|样本)(?:要求|包含|使用|出现)?"
        r"|模型(?:被)?要求"
        r")[^。!?\n]{0,18}$"
    )
    
    
    LEAK_PATTERNS = (
        (
            "en.requested_process",
            re.compile(
                r"\bAs (?:you )?(?:requested|instructed)(?!\s+by\b)"
                r"(?=\s*(?:[:,]|\bthis\b|\bthe\b|\bwe\b|\bI\b))",
                re.I,
            ),
        ),
        (
            "en.constraint_restatement",
            re.compile(
                r"\bPer (?:your|the) [\w -]{0,40}(?:constraint|requirement|word (?:limit|count))\b",
                re.I,
            ),
        ),
        (
            "en.ai_style_self_reference",
            re.compile(
                r"\bTo avoid (?:AI[- ]sounding|sounding like AI)(?:\s+(?:language|phrasing|prose))?"
                r"\s*,?\s*(?:this|the)\s+(?:paper|section|text|draft|manuscript)\b",
                re.I,
            ),
        ),
        (
            "en.editor_preface",
            re.compile(r"\bHere is the (?:revised|rewritten|humanized|updated) (?:version|text|draft)\b", re.I),
        ),
        (
            "en.assistant_identity",
            re.compile(r"\bAs an (?:AI|editor|assistant|language model)\b", re.I),
        ),
        (
            "zh.requested_process",
            ZH_REQUESTED_PROCESS_RE,
        ),
        (
            "zh.ai_style_self_reference",
            ZH_AI_STYLE_SELF_REFERENCE_RE,
        ),
        (
            "zh.editor_preface",
            re.compile(r"以下是(?:修改|改写|去\s*AI\s*味|润色)后的(?:版本|文本|内容)"),
        ),
        ("tool.tracking", re.compile(r"(?:utm_source=(?:chatgpt\.com|claude\.ai|openai|perplexity\.ai)|referrer=grok\.com)", re.I)),
        ("tool.citation_token", re.compile(r"citeturn\d|oaicite|\[attached_file:\d+\]", re.I)),
        ("placeholder.english", re.compile(r"\[(?:Your|INSERT|Add|Enter|Describe|Specify)[^\]\n]{0,60}\]", re.I)),
        ("placeholder.date", re.compile(r"\b\d{4}-XX(?:-XX)?\b", re.I)),
        ("placeholder.chinese", re.compile(r"XX(?:大学|学院|医院|公司|路|省|市)|[【\[](?:填写|待补充|待定)[】\]]")),
    )
    
    
    def _context(text, start, end, radius=45):
        return text[max(0, start - radius):min(len(text), end + radius)].replace("\n", " ")
    
    
    def _is_discussed_ai_style_example(rule, text, start):
        if rule != "zh.ai_style_self_reference":
            return False
        prefix = text[max(0, start - 40):start]
        return bool(ZH_DISCUSSION_PREFIX_RE.search(prefix))
    
    
    def leak_scan(text):
        masked = mask_scan_protected(text)
        hits = []
        for rule, regex in LEAK_PATTERNS:
            for match in regex.finditer(masked):
                if _is_discussed_ai_style_example(rule, masked, match.start()):
                    continue
                hits.append(
                    {
                        "rule": rule,
                        "status": "candidate_only",
                        "match": text[match.start():match.end()],
                        "context": _context(text, match.start(), match.end()),
                    }
                )
        return sorted(hits, key=lambda item: text.find(item["match"]))
    
    
    EN_CONTRAST_PATTERNS = (
        (
            "en.more_than_escalation",
            re.compile(
                r"\b(?:is|are|was|were)\s+more\s+than\s+"
                r"(?:(?:just|merely|simply)\s+)?(?:an?|the)\b[^.!?]{1,100}?"
                r"(?:;|,|—|--)\s*(?:it|this|they|the\s+\w+)\s+"
                r"(?:is|are|was|were)\b[^.!?]+",
                re.I,
            ),
        ),
        (
            "en.split_not",
            re.compile(
                r"\b(?:this|it|the\s+\w+)\s+(?:is|are|was|were)\s+not\s+"
                r"[^.!?]{1,100}[.!?]\s+(?:it|this|the\s+\w+)\s+"
                r"(?:is|are|was|were)\s+[^.!?]+",
                re.I,
            ),
        ),
        (
            "en.not_merely",
            re.compile(
                r"\bnot\s+(?:merely|just|simply)\b[^.!?]{1,120}?(?:;|,|—|--)"
                r"\s*(?:(?:but\s+)?(?:it\s+)?(?:is|are)\s+)?[^.!?]+",
                re.I,
            ),
        ),
        (
            "en.not_only",
            re.compile(
                r"\bnot\s+only\b[^.!?]{1,120}?"
                r"(?:\bbut\s+also\b|[,;]\s*(?:it|they|this|the\s+\w+)\s+also\b)"
                r"[^.!?]+",
                re.I,
            ),
        ),
        ("en.not_but", re.compile(r"\bnot\b[^.!?]{1,100}?\bbut\b[^.!?]+", re.I)),
        ("en.less_more", re.compile(r"\bless\s+about\b[^.!?]{1,100}?\bmore\s+about\b[^.!?]+", re.I)),
        ("en.rather_than", re.compile(r"\brather\s+than\b[^.!?]+", re.I)),
    )
    ZH_CONTRAST_PATTERNS = (
        (
            "zh.split_not",
            re.compile(
                r"(?:这|它)?不是[^。!?;]{1,60}[。!?]\s*"
                r"(?:这|它)?(?:是|意味着|构成)[^。!?;]+"
            ),
        ),
        ("zh.not_only", re.compile(r"(?:不仅仅?是|不只是|不单是|不仅)[^。!?;]{1,80}?(?:,|,)?(?:更是|而且|还|也)[^。!?;]*")),
        ("zh.not_but", re.compile(r"(?:不是|并非)[^。!?;]{1,80}?(?:,|,)?而是[^。!?;]*")),
        ("zh.not_where", re.compile(r"不在于[^。!?;]{1,80}?(?:,|,)?而在于[^。!?;]*")),
        ("zh.rather", re.compile(r"与其说[^。!?;]{1,80}?(?:,|,)?不如说[^。!?;]*")),
        (
            "zh.surface_essence",
            re.compile(
                r"表面(?:上)?[^。!?;]{1,80}?(?:,|,|;|;)?"
                r"(?:本质|实质)(?:上)?[^。!?;]*"
            ),
        ),
    )
    
    
    def contrast_candidates(text, branch):
        """Return surface candidates; semantic validity requires contrast-logic.md."""
        if branch not in {"en", "zh"}:
            return []
        masked = mask_scan_protected(text)
        patterns = ZH_CONTRAST_PATTERNS if branch == "zh" else EN_CONTRAST_PATTERNS
        raw = []
        for rule, regex in patterns:
            for match in regex.finditer(masked):
                raw.append((match.start(), match.end(), rule))
    
        # Prefer the widest match and collapse overlapping pattern families.
        raw.sort(key=lambda item: (item[0], -(item[1] - item[0])))
        selected = []
        for start, end, rule in raw:
            if any(start < existing_end and end > existing_start for existing_start, existing_end, _ in selected):
                continue
            selected.append((start, end, rule))
    
        return [
            {
                "rule": rule,
                "match": text[start:end],
                "context": _context(text, start, end),
                "status": "candidate_only",
            }
            for start, end, rule in sorted(selected)
        ]
    
    
    def analyze(text):
        branch, ratio, cjk, latin = route(text)
        transition_value, transition_counts = transition_density(text, branch)
        return {
            "route": {
                "branch": branch,
                "cjk_ratio": ratio,
                "cjk_tokens": cjk,
                "latin_word_tokens": latin,
                "unit": "orthographic_tokens",
            },
            "lexical_diversity": lexical_diversity(text, branch),
            "sentence_length": sentence_stats(text, branch),
            "transitions": {
                "value": transition_value,
                "unit": "per_100_sentences",
                "by_marker": transition_counts,
            },
            "passive_candidates": passive_candidates_en(text) if branch == "en" else [],
            "dashes": dash_counts(text),
            "leaks": leak_scan(text),
            "contrast_candidates": contrast_candidates(text, branch),
            "global_patterns": global_pattern_profile(text, branch),
            "interpretation": "descriptive_candidates_not_authorship_or_quality_verdict",
        }
    
    
    def main():
        parser = argparse.ArgumentParser(
            description="Descriptive diagnostics for academic-humanizer"
        )
        parser.add_argument("file", help="input file, or - for stdin")
        parser.add_argument("--json", action="store_true", help="print JSON")
        parser.add_argument("--route", action="store_true", help="print language route only")
        args = parser.parse_args()
    
        if args.file == "-":
            text = sys.stdin.read()
        else:
            with open(args.file, encoding="utf-8") as handle:
                text = handle.read()
    
        if args.route:
            branch, ratio, cjk, latin = route(text)
            print(
                f"branch={branch} cjk_ratio={ratio} "
                f"cjk_tokens={cjk} latin_word_tokens={latin}"
            )
            return
    
        report = analyze(text)
        if args.json:
            print(json.dumps(report, ensure_ascii=False, indent=2))
            return
    
        route_report = report["route"]
        print(
            f"[route] branch={route_report['branch']} "
            f"r={route_report['cjk_ratio']} "
            f"cjk={route_report['cjk_tokens']} "
            f"latin_words={route_report['latin_word_tokens']}"
        )
        diversity = report["lexical_diversity"]
        print(
            f"[lexical] measure={diversity['measure']} value={diversity['value']} "
            f"tokens={diversity['tokens']}"
        )
        length = report["sentence_length"]
        print(
            f"[sentences] n={length['n']} mean={length['mean']} "
            f"stdev={length['stdev']} range={length['min']}-{length['max']}"
        )
        transitions = report["transitions"]
        print(
            f"[transitions] {transitions['value']} per 100 sentences "
            f"{transitions['by_marker'] or ''}"
        )
        print(f"[passive candidates] {len(report['passive_candidates'])}")
        print(f"[dashes] {report['dashes']}")
        print(f"[leak candidates] {len(report['leaks'])}")
        print(f"[contrast candidates] {len(report['contrast_candidates'])}")
        global_patterns = report["global_patterns"]
        print(
            f"[global patterns] paragraphs={global_patterns['scope']['paragraphs']} "
            f"sentences={global_patterns['scope']['sentences']} "
            f"initial_markers={global_patterns['sentence_initial_markers']['count']} "
            f"dashes={global_patterns['dash_distribution']['count']}"
        )
    
    
    if __name__ == "__main__":
        main()
    
  • skills/academic-humanizer/scripts/terminology_audit.py5.6 KB10647a74564bupstream ↗
    #!/usr/bin/env python3
    """Report declared terminology variants without inferring or rewriting meaning."""
    
    from __future__ import annotations
    
    import argparse
    import json
    import re
    import sys
    from pathlib import Path
    from typing import Any
    
    
    PROTECTED_PATTERNS = (
        re.compile(r"```.*?```", re.DOTALL),
        re.compile(r"`[^`\n]+`"),
        re.compile(r'"(?:[^"\\]|\\.)*"'),
        re.compile(r"“[^”]*”"),
        re.compile(r"‘[^’]*’"),
        re.compile(r"\$\$.*?\$\$", re.DOTALL),
        re.compile(r"\$[^$\n]+\$"),
    )
    
    
    def _protected_intervals(text: str) -> list[tuple[int, int]]:
        intervals: list[tuple[int, int]] = []
        for pattern in PROTECTED_PATTERNS:
            intervals.extend((match.start(), match.end()) for match in pattern.finditer(text))
        return sorted(intervals)
    
    
    def _is_protected(start: int, end: int, intervals: list[tuple[int, int]]) -> bool:
        return any(start < protected_end and end > protected_start for protected_start, protected_end in intervals)
    
    
    def _term_pattern(term: str) -> re.Pattern[str]:
        escaped = re.escape(term)
        has_cjk = bool(re.search(r"[㐀-鿿]", term))
        prefix = r"(?<!\w)" if not has_cjk and term and (term[0].isalnum() or term[0] == "_") else ""
        suffix = r"(?!\w)" if not has_cjk and term and (term[-1].isalnum() or term[-1] == "_") else ""
        return re.compile(prefix + escaped + suffix, re.IGNORECASE)
    
    
    def validate_ledger(ledger: list[dict[str, Any]]) -> None:
        required = {"concept_id", "canonical_term", "allowed_forms", "observed_variants", "distinguish_from"}
        concept_ids: set[str] = set()
        for index, item in enumerate(ledger):
            missing = required - set(item)
            if missing:
                raise ValueError(f"term {index} is missing fields: {', '.join(sorted(missing))}")
            if not isinstance(item["concept_id"], str) or not item["concept_id"].strip():
                raise ValueError(f"term {index} has an invalid concept_id")
            if item["concept_id"] in concept_ids:
                raise ValueError(f"duplicate concept_id: {item['concept_id']}")
            concept_ids.add(item["concept_id"])
            if not isinstance(item["canonical_term"], str) or not item["canonical_term"].strip():
                raise ValueError(f"{item['concept_id']} has an invalid canonical_term")
            for field in ("allowed_forms", "observed_variants", "distinguish_from"):
                if not isinstance(item[field], list) or not all(isinstance(value, str) for value in item[field]):
                    raise ValueError(f"{item['concept_id']}.{field} must be a list of strings")
    
    
    def audit_text(text: str, ledger: list[dict[str, Any]]) -> list[dict[str, Any]]:
        """Return observed-variant findings outside common protected spans.
    
        The caller supplies all identity judgments in ``ledger``. This function only
        locates declared variants; it never treats lexical similarity as coreference.
        """
    
        validate_ledger(ledger)
        protected = _protected_intervals(text)
        findings: list[dict[str, Any]] = []
        for item in ledger:
            authorized = {item["canonical_term"].casefold()}
            authorized.update(form.casefold() for form in item["allowed_forms"])
            for variant in item["observed_variants"]:
                if not variant.strip() or variant.casefold() in authorized:
                    continue
                for match in _term_pattern(variant).finditer(text):
                    if _is_protected(match.start(), match.end(), protected):
                        continue
                    findings.append(
                        {
                            "concept_id": item["concept_id"],
                            "canonical_term": item["canonical_term"],
                            "variant": match.group(0),
                            "start": match.start(),
                            "end": match.end(),
                            "action": "review",
                        }
                    )
        return sorted(findings, key=lambda finding: (finding["start"], finding["concept_id"]))
    
    
    def _load_ledger(path: Path) -> list[dict[str, Any]]:
        payload = json.loads(path.read_text(encoding="utf-8"))
        ledger = payload.get("terms") if isinstance(payload, dict) else payload
        if not isinstance(ledger, list):
            raise ValueError("ledger must be a JSON list or an object with a 'terms' list")
        return ledger
    
    
    def _parser() -> argparse.ArgumentParser:
        parser = argparse.ArgumentParser(
            description="Report explicitly declared terminology variants without rewriting the manuscript."
        )
        parser.add_argument("text", type=Path, help="UTF-8 manuscript text file")
        parser.add_argument("--ledger", required=True, type=Path, help="JSON terminology ledger")
        parser.add_argument("--json", action="store_true", help="emit machine-readable JSON")
        return parser
    
    
    def main(argv: list[str] | None = None) -> int:
        args = _parser().parse_args(argv)
        try:
            text = args.text.read_text(encoding="utf-8")
            ledger = _load_ledger(args.ledger)
            findings = audit_text(text, ledger)
        except (OSError, UnicodeError, json.JSONDecodeError, ValueError) as exc:
            print(f"terminology audit error: {exc}", file=sys.stderr)
            return 2
    
        if args.json:
            print(json.dumps({"finding_count": len(findings), "findings": findings}, ensure_ascii=False, indent=2))
        elif findings:
            for finding in findings:
                print(
                    f"{finding['concept_id']}: {finding['variant']!r} -> "
                    f"review against {finding['canonical_term']!r} at {finding['start']}:{finding['end']}"
                )
        else:
            print("No declared terminology variants found.")
        return 1 if findings else 0
    
    
    if __name__ == "__main__":
        raise SystemExit(main())
    
  • skills/academic-humanizer/references/contrast-logic.md5.2 KB2c9a92b93f8aupstream ↗
    # Supported and unsupported contrast
    
    This cross-language rule handles false opposition in English and Chinese. It is
    semantic, not a phrase ban. A pattern match may open an audit; it never decides
    the result by itself.
    
    ## Contents
    
    1. Definition
    2. Candidate families
    3. Grounding test
    4. Three decisions
    5. Safe transformations
    6. Protected academic uses
    7. Anti-overfitting checks
    
    ## 1. Definition
    
    An **unsupported rhetorical contrast** introduces, denies, or downgrades X mainly
    to make Y sound deeper, broader, or more novel, even though X has no identifiable
    source or argumentative role.
    
    The defect is not negation itself. The defect is an unsupported X plus a contrast
    that adds ceremony or inflation instead of evidence.
    
    ## 2. Candidate families
    
    English candidates include:
    
    - `not X but Y`, `not merely/just/simply X; Y`;
    - `not only X but also Y`, `more than X`, `beyond X`;
    - `less about X and more about Y`, `rather than simply X, Y`;
    - `on the surface X, but fundamentally Y`;
    - split forms such as `This is not X. It is Y.`
    
    Chinese candidates include:
    
    - `不是/并非 X,而是 Y`;
    - `不只是/不仅仅是 X,更是 Y`;
    - `问题不在于 X,而在于 Y`;
    - `与其说 X,不如说 Y`;
    - `表面上是 X,本质上是 Y`;
    - `超越 X,成为 Y` and equivalent split-sentence forms.
    
    These lists are recall aids. Quoted language, cited language, and discussed-as-
    example spans are protected.
    
    ## 3. Grounding test
    
    For every candidate, identify X and Y, then ask in order:
    
    1. **Source**: Is X explicitly asserted, attributed, cited, hypothesized, requested
       by a reviewer, defined as a baseline, or otherwise present in the source bundle?
    2. **Need**: Would stating Y alone, or X and Y as a neutral addition, lose a real
       correction, exclusion, or comparison?
    3. **Evidence**: Does the available text support rejecting/downgrading X and
       supporting Y? An ablation, controlled comparison, negative result, definition,
       citation, or scope statement can provide support.
    4. **Specificity**: Is X a concrete, testable proposition or only a generic
       downgrader such as `a simple tool`, `an implementation detail`, `一次改进`?
    5. **Inflation**: Is Y an abstract escalation such as `paradigm`, `mindset`,
       `revolution`, `本质`, `格局`, or `范式变革` without source evidence?
    
    Frequency is not a validity test. One unsupported contrast is still unsupported;
    several valid experimental contrasts remain valid.
    
    ## 4. Three decisions
    
    ### A. Protected contrast: keep
    
    Choose **keep** when X has an identifiable source or technical role and evidence
    supports the distinction. Preserve its polarity, baseline, and relation.
    
    ### B. Unsupported rhetorical contrast: rewrite
    
    Choose **rewrite** only when X is generic evaluative scaffolding, contributes no
    independent content, and Y can be stated without adding or deleting a material
    claim. Remove the staged opposition and state the supported content directly.
    
    ### C. Concrete but unverified contrast: flag
    
    Choose **flag** when X or the X/Y relation is concrete but the available source
    does not establish it. Do not decide that the contrast is true or false. In detect
    mode, request evidence. In rewrite/edit mode, preserve the sentence or ask before
    changing it.
    
    ## 5. Safe transformations
    
    | Original relation | Safe action |
    |---|---|
    | generic X rejected to inflate Y | remove the empty downgrader; state supported Y directly |
    | `not only X but also Y`, with both claims supported | keep, or rewrite as neutral `X and Y`; preserve both claims |
    | concrete `not X but Y`, evidence present | keep the contrast; simplify only redundant wording |
    | concrete `not X but Y`, evidence absent | flag; do not delete X or assert Y |
    | `surface X / essence Y` with no analysis | state supported observation; remove unsupported essence claim |
    | reviewer or scope correction | keep the explicit boundary and its target |
    
    Never replace a vague contrast with a new number, mechanism, example, baseline,
    or limitation. If the source has no concrete substitute, use plainer wording.
    
    ## 6. Protected academic uses
    
    - a cited misconception or prior interpretation followed by a correction;
    - competing hypotheses distinguished by an experiment or analysis;
    - ablation-based attribution (`gain comes from Y rather than X`);
    - a negative result contrasted with a positive result;
    - a definition or scope exclusion (`optimizes latency, not throughput`);
    - reviewer-response clarification tied to the reviewer's actual concern;
    - a mathematical, legal, or technical distinction where polarity is substantive;
    - genuine additive findings where both X and Y are supported.
    
    ## 7. Anti-overfitting checks
    
    Before changing a candidate:
    
    - Ignore the surface pattern and restate its propositions. If a proposition would
      disappear, do not auto-rewrite.
    - Check at least the surrounding paragraph, supplied source, and cited antecedent.
    - Do not infer that an uncited X is false; absence of local evidence creates
      uncertainty, not permission to erase content.
    - Do not penalize contrast density in ablations, related work, error analysis,
      definitions, or reviewer responses.
    - A detector in `metrics.py` reports `candidate_only`. The language model must run
      this grounding test before choosing keep, rewrite, or flag.
    
  • skills/academic-humanizer/references/examples.md12 KB4be303a677cbupstream ↗
    # Worked examples
    
    Read these examples on first use, after rule changes, and for uncertain semantic
    boundaries. Expected rewrites use only information present in the displayed input.
    
    ## Contents
    
    1. English fact-safe rewrite
    2. Chinese fact-safe rewrite
    3. Process-leak removal
    4. Zero-edit academic control
    5. False-opposition triage
    6. Generation without invented contrast
    7. Manuscript-wide terminology control
    8. Local-to-document pattern analysis
    
    ## 1. English fact-safe rewrite
    
    **Input**
    
    > Heart failure represents a pivotal challenge in the evolving landscape of diabetes care, underscoring the critical importance of addressing cardiovascular comorbidities. Our groundbreaking findings showcase a remarkable 34% reduction in hospitalization—a testament to the transformative potential of this intervention—highlighting the need for a paradigm shift in clinical practice. Moreover, it is worth noting that these results may suggest that the treatment could potentially have the possibility of conferring benefits in select populations. Despite these challenges, the future looks bright for patients worldwide.
    
    **Findings**
    
    - E1: importance and novelty inflation;
    - E2: promotional metaphor;
    - E3: generic `-ing` tails;
    - E7: stacked hedging;
    - E9: unsupported ceremonial conclusion;
    - E13: decorative dash insertion.
    
    `Moreover` is not a defect. Its sentence is restructured because the surrounding
    wording changes.
    
    **Fact-safe rewrite**
    
    > Heart failure is a challenge in diabetes care, particularly when cardiovascular comorbidities are present. Our findings show a 34% reduction in hospitalization. The results suggest that the treatment may benefit selected populations.
    
    **Claim map**
    
    | Source claim | Output |
    |---|---|
    | heart failure is a challenge in diabetes care | sentence 1 |
    | cardiovascular comorbidities matter to that challenge | sentence 1 |
    | the findings report a 34% reduction in hospitalization | sentence 2 |
    | the treatment may benefit selected populations | sentence 3, with one hedge |
    
    The rewrite does not add a trial, comparator, absolute/relative interpretation,
    mechanism, prognosis claim, confirmatory study, or limitation.
    
    ## 2. Chinese fact-safe rewrite
    
    **输入**
    
    > 随着人工智能技术的不断发展,机器学习方法在医学影像领域的应用具有重要意义,为疾病诊断开启了新篇章。本研究不仅是一次方法上的改进,更是一场诊断范式的深刻变革。我们对模型进行了全面的、多维度的评估,结果极大地证明了该框架的先进性。综上所述,本方法赋能临床诊断,未来可期。
    
    **发现**
    
    - Z1:模板化开场;
    - Z2:空泛拔高;
    - Z3:无来源的修辞性对立;
    - Z5:装饰性强调;
    - Z6:商业黑话;
    - Z9:万能结尾。
    
    **事实安全改写**
    
    > 机器学习方法已应用于医学影像诊断。本研究改进了现有方法,并对模型进行了多方面评估。评估结果支持该框架的改进效果。
    
    **命题映射**
    
    | 原文命题 | 输出位置 |
    |---|---|
    | 机器学习用于医学影像诊断 | 第一句 |
    | 本研究包含方法改进 | 第二句 |
    | 对模型进行了多方面评估 | 第二句 |
    | 评估结果支持方法改进 | 第三句 |
    
    改写没有增加准确率、鲁棒性、推理效率、baseline、外部验证、临床适用
    范围或未来工作。原文没有提供这些内容,不能用它们替换空话。
    
    ## 3. Process-leak removal
    
    **Input**
    
    > As requested, this section avoids AI-sounding phrasing and passive constructions. We examined the association between sleep duration and cognitive decline in 4,821 adults. Per the 200-word constraint, details of the sensitivity analyses appear in Appendix B. Shorter sleep duration was associated with faster decline in episodic memory (β = −0.14, p = 0.006).
    
    **Clean artifact**
    
    > We examined the association between sleep duration and cognitive decline in 4,821 adults. Details of the sensitivity analyses appear in Appendix B. Shorter sleep duration was associated with faster decline in episodic memory (β = −0.14, p = 0.006).
    
    The first sentence is process-only. In the third source sentence, only the word-
    limit preface is process text; the Appendix B claim remains. All quantities and
    the association wording remain unchanged. No leak-check line is added to the
    clean artifact.
    
    If the user requested diagnostics, report the two removed spans after the clean
    artifact and clearly label that report as editor notes.
    
    ## 4. Zero-edit academic control
    
    **Input**
    
    > Although the sample was drawn from a single province, the direction of the association was consistent across all six sensitivity analyses. Participants were followed for a median of 8.2 years; loss to follow-up was 4.7%. Based on these results, we examined whether the association differed by baseline education. However, the interaction term was not statistically significant (p = 0.31), and the stratified estimates were similar. These findings should therefore be interpreted as exploratory, and they may not generalize to urban populations.
    
    **Decision: keep unchanged.**
    
    - `Although`, `Based on these results`, `However`, and `therefore` carry logic.
    - Method/Results passives are conventional.
    - `may not generalize` is evidence-calibrated hedging.
    - `statistically significant` is tied to a reported test.
    
    Zero edits are a successful result. Do not vary sentence length or remove a
    connective merely to demonstrate that the skill ran.
    
    ## 5. False-opposition triage
    
    ### 5.1 Unsupported rhetorical contrast: rewrite
    
    **English input**
    
    > The proposed cache is not merely an implementation detail; it is a paradigm shift in memory management.
    
    No prior claim, definition, or evidence establishes `implementation detail` as an
    alternative, and `paradigm shift` only escalates category. A fact-safe repair is:
    
    > The proposed cache changes the memory-management procedure.
    
    Do not add performance numbers, deployment claims, or an ablation.
    
    **中文输入**
    
    > 这不仅是一次参数压缩,更是一场推理范式的深刻变革。
    
    X 被无来源地降格,Y 使用抽象拔高。若这句话是可用的全部来源,可改为:
    
    > 该方法压缩了参数,并改变了推理流程。
    
    两个原有内容点仍在;没有增加准确率、延迟或部署效果。
    
    ### 5.2 Supported experimental contrast: keep
    
    > Prior work attributed the gain to larger batches [12]. With batch size fixed, the ablation retained a 2.1-point gain. The gain therefore reflects the normalization term rather than batch size.
    
    Keep the contrast. X comes from cited prior work, and the fixed-batch ablation
    supports the distinction. Removing `rather than batch size` would lose the result.
    
    > 已有工作将增益归因于更大的批量[12]。在批量固定的消融实验中,模型仍提升2.1个百分点。因此,增益来自归一化项,而非批量变化。
    
    同样保留。句式表面命中不能覆盖实验逻辑。
    
    ### 5.3 Concrete but unsupported contrast: flag
    
    > The improvement is not due to augmentation but to calibration.
    
    > 性能提升并非来自数据增强,而是来自校准策略。
    
    Both sides are concrete causal-attribution claims, but the displayed context has
    no evidence. Do not delete X, assert Y, or invent an ablation. In detect mode,
    flag and request support. In rewrite/edit mode, preserve or ask before changing.
    
    ### 5.4 Additive form with two supported claims: keep both
    
    > The method not only reduces memory use by 18% but also cuts latency by 9 ms.
    
    > 该方法不仅将显存占用降低18%,还将延迟减少9毫秒。
    
    Both clauses carry quantified findings. The construction may remain. A neutral
    addition is also possible, but any rewrite must preserve both values and claims.
    
    ## 6. Generation without invented contrast
    
    **Supplied facts**
    
    - latency decreased from 41 ms to 33 ms;
    - accuracy was unchanged.
    
    **Acceptable draft**
    
    > Latency decreased from 41 ms to 33 ms, while accuracy remained unchanged.
    
    Do not generate `This is not merely a speed improvement but a new efficiency
    paradigm`. That sentence invents a downgraded X and an unsupported Y.
    
    ## 7. Manuscript-wide terminology control
    
    ### 7.1 Coined-name drift: normalize
    
    **Definition in Methods**
    
    > We call this component the Adaptive Evidence Router.
    
    **Later caption**
    
    > The adaptive evidence routing module selects two passages.
    
    The definition establishes `Adaptive Evidence Router` as the canonical coined
    name. If no abbreviation was declared, revise the caption to:
    
    > The Adaptive Evidence Router selects two passages.
    
    The replacement changes no claim. Capitalization and wording remain stable
    across Methods, Results, and captions.
    
    ### 7.2 Declared abbreviation: keep
    
    > We introduce the Adaptive Evidence Router (AER). AER selects two passages.
    
    Keep both forms and record `AER` as allowed. The full name introduces the mapping;
    later use of the abbreviation is controlled variation, not drift.
    
    ### 7.3 Distinct concepts: keep separate
    
    > The evidence encoder embeds passages, whereas the Adaptive Evidence Router selects them.
    
    Do not normalize `evidence encoder` to `Adaptive Evidence Router`. Their reported
    functions differ, so the terminology ledger records an intentional distinction.
    
    ### 7.4 Uncertain identity: flag
    
    > 该框架生成候选证据。随后,该方法对候选证据进行排序。
    
    The excerpt does not establish whether `该框架` and `该方法` denote the same
    technical object. Preserve the text and ask the author; frequency or proximity
    cannot resolve identity.
    
    ### 7.5 Protected prior-work term: keep
    
    > Prior work calls this component the "confidence layer" [12]. We define our component as the calibration layer.
    
    The quoted historical term belongs to prior work and remains unchanged. The
    manuscript-owned component uses `calibration layer` elsewhere.
    
    ## 8. Local-to-document pattern analysis
    
    ### 8.1 A local form can be valid
    
    > 误差在区间内保持稳定——这一限定仅适用于测试集。
    
    Keep the dash. It introduces a material scope restriction. Neither punctuation
    type nor a single occurrence establishes a style defect.
    
    > 由定理2可知,在条件A下,误差必然为零。
    
    Keep `必然`. The supplied theorem and condition support a deductive consequence.
    
    ### 8.2 Distribution and redundant function create the defect
    
    **Input**
    
    > 模型在测试集上达到82%——这一结果十分亮眼。
    >
    > 延迟下降9 ms——这体现了方法优势。
    >
    > 显存减少12%——这彰显了框架潜力。
    
    Each first clause reports a result. Each dash tail repeats unsupported evaluation
    in the same paragraph position. The document-level repair is:
    
    > 模型在测试集上达到82%。
    >
    > 延迟下降9 ms。
    >
    > 显存减少12%。
    
    The decision uses recurrence, position, and redundant function together. It does
    not enforce a dash quota or add a new interpretation of the three results.
    
    ### 8.3 Repeated sentence-initial markers: preserve relations
    
    **Input**
    
    > 此外,模型降低了延迟。此外,模型减少了显存。此外,模型保持了准确率。
    
    The three findings are additive, but announcing every sentence with the same
    marker is redundant. A coherent repair is:
    
    > 模型降低了延迟、减少了显存,并保持了准确率。
    
    All findings and their additive relation remain. If the sentences occurred in
    different sections or `此外` marked genuinely separate additions, they could
    remain.
    
    ### 8.4 Draft-shaped evidence is not self-verifying
    
    > Smith等(2025)证明该方法在所有任务上均优于人类,因此本研究采用该结论作为理论依据。
    
    If no reference entry or source is supplied, preserve this sentence in rewrite
    mode and flag its evidence status as `draft-only` outside the clean artifact. Do
    not invent a DOI, silently endorse the universal claim, or derive additional
    claims from it. If the source is later supplied, verify the author, year, scope,
    and strength before revising.
    
    ### 8.5 Whole-document scope must be earned
    
    One paragraph permits local and within-paragraph findings. It cannot establish
    that the complete manuscript has uniform rhythm, repeated paragraph templates,
    or saturated rhetorical peaks. Report the inspected scope and request the
    remaining manuscript before claiming a whole-manuscript pass.
    
  • skills/academic-humanizer/references/global-pattern-contract.md8.9 KB2f71a8193513upstream ↗
    # Local-to-document pattern contract
    
    Use this contract for every multi-sentence generation, detection, rewrite, or
    file edit. It separates a locally defective expression from a pattern that only
    becomes defective through repetition, clustering, or positional regularity.
    
    ## Contents
    
    1. Evidence stance and scope
    2. Units and distribution map
    3. Candidate families
    4. Two-level activation test
    5. Protected recurrence
    6. Whole-document repair
    7. Optional deterministic profile
    8. Final gate
    
    ## 1. Evidence stance and scope
    
    Treat dashes, connectives, contrast, parallel lists, sentence length, and other
    surface forms as editing candidates, never proof of machine authorship. Their
    frequency varies with language, model, prompt, domain, genre, and section. A
    single occurrence is often legitimate; even a frequent form may be required by
    Methods, Results, formal proofs, definitions, or reviewer responses.
    
    Apply the global pass only to the supplied editable scope. A sentence supports a
    local judgment. Multiple paragraphs support a distributional judgment about
    those paragraphs. Only a complete supplied manuscript supports a claim of
    whole-manuscript review. State a scope limitation outside the clean artifact
    when the requested judgment exceeds the available text.
    
    Do not use a universal count, percentage, sentence-length target, or healthy
    range. Within-document distribution and rhetorical function control the audit.
    
    ## 2. Units and distribution map
    
    Build an internal map after locking nonprose and quoted spans. Record candidates
    at these levels:
    
    | Level | Record |
    |---|---|
    | sentence | pattern family, exact span, position, claim/relation load |
    | paragraph | sentence sequence, opening/closing function, candidate cluster |
    | section | genre function, expected parallelism, length sequence |
    | document | recurrence, dispersion, dominant template, cross-section transfer |
    
    For each candidate family, inspect five dimensions:
    
    1. **recurrence**: how often the form or rhetorical move returns;
    2. **dispersion**: whether it is isolated, clustered, or spread across sections;
    3. **position**: whether it repeatedly occupies sentence starts, paragraph ends,
       or the same step in a paragraph template;
    4. **function**: whether each occurrence expresses a necessary relation or merely
       repeats emphasis, coverage, or ceremony;
    5. **interaction**: whether several families reinforce one mechanical pattern.
    
    Counts and locations are descriptive evidence. They never make the decision.
    
    ## 3. Candidate families
    
    ### G1. Punctuation and sentence-initial routing
    
    Map dashes and repeated sentence-initial markers such as `此外`, `然而`, and
    `值得注意的是` or their English counterparts. Preserve punctuation that marks a
    real boundary and markers that disambiguate addition, contrast, cause, or scope.
    Audit repeated openings when the relation is already clear or every sentence is
    announced in the same way.
    
    ### G2. Opposition scaffolds
    
    Map repeated `not X but Y` / `不是 X 而是 Y` families, then run
    `contrast-logic.md` on every occurrence. Repetition can expose a dominant
    rhetorical template, but it never invalidates a supported contrast. Repair only
    unsupported staging or redundant recurrence.
    
    ### G3. Parallel triads and exhaustive coverage
    
    Map three-part lists, repeated adjective triples, `首先—其次—最后`, and flat
    coverage of every imaginable case. Preserve real metrics, contributions,
    conditions, steps, and taxonomies. A list is defective when its items are
    interchangeable abstractions, when enumeration replaces an available argument
    hierarchy, or when repeated triads manufacture completeness without evidence.
    
    Reorganize only with relations already present in the source. Do not invent a
    taxonomy, omit a condition, or collapse distinct cases for elegance.
    
    ### G4. Repeated templates and rhetorical moves
    
    Map recurring sentence openings, clause frames, paragraph sequences, and
    background-list-summary molds. Evaluate the function sequence, not only exact
    words. A document can repeat one template while changing vocabulary.
    
    Parallel Results, protocol steps, definitions, and structured abstracts may
    require repeated frames. Elsewhere, change structure only when the template
    obscures the actual reasoning.
    
    ### G5. Sentence rhythm
    
    Inspect the ordered sentence-length sequence within each functional section.
    Uniformly long, uniformly short, or mechanically alternating sentences are
    candidates when the rhythm conflicts with information structure. Do not vary
    length for its own sake. Split or combine sentences only where propositions and
    relations define a natural boundary.
    
    ### G6. Ending elevation and rhetorical-peak saturation
    
    Map unsupported elevation near sentence or paragraph endings, including repeated
    `彰显了`, `反映了`, `标志着`, generic importance, and aphoristic conclusions.
    One evidence-backed synthesis may be appropriate. Repeated abstract peaks are a
    distributional defect when several paragraphs end by restating importance rather
    than advancing or delimiting the argument.
    
    Delete empty elevation; retain a sourced implication, limitation, or synthesis.
    Do not manufacture a weaker slogan to replace a stronger slogan.
    
    ### G7. Certainty and epistemic calibration
    
    Map categorical expressions such as `一定`, `必然`, `毫无疑问`, `无疑`, and
    English equivalents. Compare each with the claim/evidence ledger. Preserve
    deductive consequences, definitions, proven invariants, and source-calibrated
    certainty. Repair certainty that exceeds observational, exploratory, incomplete,
    or unverified evidence.
    
    Repeated certainty is both a distribution signal and a semantic risk. C1 blocks
    weakening or strengthening until the source establishes the intended evidence
    level.
    
    ## 4. Two-level activation test
    
    Choose one classification:
    
    - **local defect**: the individual span is unsupported, vacuous, misleading, or
      semantically excessive even if it appears once;
    - **distributional defect**: individual instances can be grammatical, but their
      recurrence/position and redundant function dominate the supplied scope;
    - **functional/protected**: recurrence follows evidence, section convention, or
      an explicit parallel structure;
    - **uncertain**: available scope or evidence cannot support a decision.
    
    A distributional defect requires two findings together:
    
    1. recurrence, clustering, or positional regularity; and
    2. repeated rhetorical function that adds no necessary claim or relation.
    
    Lexical count alone is insufficient. A single unsupported factual claim or false
    causal relation remains a local defect under C1 even without repetition.
    
    ## 5. Protected recurrence
    
    Keep repeated forms when they encode:
    
    - parallel experimental conditions, metrics, outcomes, or error categories;
    - ordered method/protocol steps or a supplied taxonomy;
    - theorem premises and consequences;
    - repeated terminology required by `terminology-contract.md`;
    - citations, quotations, survey items, and attributed historical language;
    - genuine contrast, concession, or cause that would become ambiguous if removed;
    - venue-required structured labels or reviewer-by-reviewer responses.
    
    Do not replace canonical terminology with synonyms to create superficial variety.
    
    ## 6. Whole-document repair
    
    Repair the argument system, not a counter:
    
    1. preserve the claim, evidence, polarity, scope, and terminology ledgers;
    2. select the smallest redundant occurrences whose removal breaks the mechanical
       pattern;
    3. retain explicit connectives where the relation would otherwise be unclear;
    4. group lists only by source-supported hierarchy;
    5. let sentence boundaries follow proposition and relation boundaries;
    6. retain one justified synthesis where it performs real argumentative work;
    7. rescan the document to ensure the repair did not create a new repeated frame.
    
    Do not randomly swap synonyms, force long-short alternation, delete every dash or
    triad, or distribute a fixed number of rhetorical peaks. A zero-edit global pass
    is valid when all recurrence is functional.
    
    ## 7. Optional deterministic profile
    
    `scripts/metrics.py` can report paragraph/sentence scope, sentence-length
    sequence, candidate locations, and distributions for selected surface families.
    Use the profile to find where to read; do not use it to decide what to rewrite.
    It cannot identify semantic equivalence, argument hierarchy, a “golden sentence,”
    or authorship.
    
    ## 8. Final gate
    
    The supplied scope passes only when:
    
    - every changed local span has a supported reason;
    - every claimed distributional defect has both recurrence evidence and redundant
      function;
    - functional repetition and section conventions remain intact;
    - sentence rhythm follows information structure rather than a variation recipe;
    - unsupported elevation and certainty no longer dominate the supplied scope;
    - no repair added facts, categories, relations, or terminology variants;
    - the stated audit scope matches the text actually inspected.
    
    If any item fails, restore the safer wording or return an `uncertain` diagnostic.
    
  • skills/academic-humanizer/references/metrics-spec.md5.5 KBe9a4855dbf84upstream ↗
    # Metrics specification
    
    `scripts/metrics.py` provides reproducible descriptive diagnostics. It does not
    identify an author, assign an AI probability, or decide whether prose passes.
    
    Terminology identity is outside this script's scope. Use the explicit-ledger
    candidate helper documented in `terminology-contract.md` when a deterministic
    residual scan is useful; semantic coreference still requires manuscript context.
    The `global_patterns` profile supports `global-pattern-contract.md` by locating
    surface candidates and ordered sentence lengths. It does not decide whether a
    pattern is functional, defective, or machine-authored.
    
    ## Contents
    
    1. Routing
    2. Descriptive fields
    3. Protected-span masking
    4. Prohibited interpretations
    5. Optional runtime commands
    
    ## Routing
    
    Routing is based on editable prose after removing fenced/inline code, formulas,
    Markdown block quotations, and a trailing References/Bibliography/Works
    Cited/参考文献 section. Reference headings are normalized before matching:
    case, Markdown heading marks, an optional section number, surrounding whitespace,
    and a trailing ASCII or full-width colon do not affect recognition. Ordinary
    sentences that merely begin with `References` or `参考文献` remain prose.
    
    `r = CJK tokens / (CJK tokens + Latin word tokens)`
    
    Each CJK character is one orthographic token; each contiguous Latin word is one
    token. This practical tokenizer favors the surrounding Chinese grammar over a
    few long embedded technical names. `r >= 0.5` routes Chinese; otherwise English.
    No countable prose returns `unknown` rather than defaulting to English.
    
    ## Descriptive fields
    
    | Field | Unit | Interpretation limit |
    |---|---|---|
    | `lexical_diversity` | English word TTR or Chinese character diversity plus token count | length-sensitive description; no normal range |
    | `sentence_length` | word count (EN) or CJK characters + Latin words (ZH) | descriptive mean, spread, min, max |
    | `transitions` | sentence-initial candidates per 100 sentences | high or low values are not defects by themselves |
    | `passive_candidates` | conservative English sentence candidates | misses valid passives and may retain false positives; never a style target |
    | `dashes` | mutually exclusive glyph/pair counts | punctuation inventory only |
    | `leaks` | context-bearing regex candidates | quotations are masked; selected research-mention contexts are excluded; contextual review remains required |
    | `contrast_candidates` | pattern candidates | candidate only; use `contrast-logic.md` for the decision |
    | `global_patterns.scope` | prose paragraphs and sentences | describes only the supplied editable scope |
    | `global_patterns.sentence_length_sequence` | ordered length by paragraph/sentence | no target variance or rhythm |
    | `global_patterns.sentence_initial_markers` | marker, count, paragraph, sentence | relation and section function require review |
    | `global_patterns.dash_distribution` | glyph counts and locations | no universal dash budget |
    | `global_patterns.contrast_distribution` | contrast family and locations | semantic validity and repeated rhetorical function require review |
    | `global_patterns.parallel_enumeration_candidates` | surface list candidates | cannot decide whether three items are substantive |
    | `global_patterns.certainty_candidates` | lexical candidates and locations | compare with evidence strength before editing |
    | `global_patterns.ending_elevation_candidates` | ending-position candidates | cannot identify a justified synthesis or “golden sentence” |
    | `global_patterns.repeated_opening_candidates` | selected repeated opening families | incomplete recall; no syntactic parser |
    
    Chinese character diversity is not lexical TTR. Traditional TTR is sensitive to
    text length, so values from different lengths or languages are not comparable.
    
    ## Protected-span masking
    
    Leak, contrast, and global-pattern scans mask direct quotations, fenced/inline
    code, formulas, Markdown block quotations, and trailing references. This reduces
    false positives but cannot parse every document format. Findings remain candidates.
    
    Chinese process-leak rules distinguish three cases:
    
    - a direct second-person request cue, such as `根据您的要求`;
    - a generic request cue followed by a document target or editing action;
    - an AI-style self-reference cue, excluding quoted and explicitly discussed
      research examples.
    
    These distinctions improve candidate recall without turning a match into deletion
    authority.
    
    ## Prohibited interpretations
    
    Do not:
    
    - combine fields into a score or probability;
    - claim a universal healthy range;
    - rewrite until a threshold is crossed;
    - treat passive voice, transitions, sentence variance, or dashes as defects alone;
    - infer a universal threshold from one document, language, section, or model;
    - call a short excerpt a whole-document audit;
    - treat a parallel list, categorical theorem consequence, or ending synthesis as
      defective without checking its content and function;
    - use a regex candidate as automatic deletion evidence.
    
    ## Optional runtime commands
    
    These commands do not modify the input file:
    
    ```bash
    <python> "<skill-dir>/scripts/metrics.py" "<input-file>" --json
    <python> "<skill-dir>/scripts/metrics.py" "<input-file>" --route
    <python> "<skill-dir>/scripts/terminology_audit.py" "<input-file>" --ledger "<terms-file>" --json
    ```
    
    The terminology audit consumes an author-supplied ledger and reports candidates;
    it does not infer concept identity or rewrite the manuscript. The metrics profile
    locates selected local and distributional candidates without assigning authorship
    or quality.
    
  • skills/academic-humanizer/references/rules-en.md7.9 KBcdd2ed85f087upstream ↗
    # English academic rules
    
    Load this file only for English-majority editable prose. The semantic,
    terminology, global-pattern, whitelist, contrast, and SKILL arbitration contracts
    remain controlling.
    
    ## Contents
    
    1. Activation standard
    2. English pattern rules E1-E14
    3. Generation constraints
    4. Final language check
    
    ## 1. Activation standard
    
    Edit locally when wording is vacuous, unsupported, or misleading. Edit globally
    when recurrence and redundant function jointly create a dominant document
    pattern. A word or construction is not defective merely because language models
    often use it.
    
    Before activating a rule, ask:
    
    - What proposition or relation does the span carry?
    - Is that proposition supported by the source bundle?
    - Is the wording conventional in this section or discipline?
    - Would the proposed edit preserve modality, polarity, comparison, and scope?
    
    When uncertain, keep or flag. Do not force variation for its own sake.
    
    ## 2. English pattern rules
    
    ### E1. Empty significance and novelty inflation
    
    Candidates: `pivotal`, `groundbreaking`, `transformative`, `remarkable`,
    `paradigm shift`, `watershed`, `testament to`, `underscores the importance of`.
    
    Act when the phrase contributes only importance or novelty without a supplied
    reason. Delete the inflation or state the already-supplied result. Do not invent a
    number, comparison, mechanism, or implication to make the sentence concrete.
    
    Technical uses such as `statistically significant`, a defined `paradigm`, or a
    cited novelty claim remain protected.
    
    ### E2. Promotional metaphor and business vocabulary
    
    Candidates: `landscape`, `ecosystem`, `journey`, `unlock`, `unleash`, `leverage`,
    `harness`, `seamless`, `game-changing`, `at its core`, `cutting-edge`.
    
    Act when the word is metaphorical and replaceable by a direct technical action.
    Preserve literal or field-standard uses. If no direct action exists in the source,
    delete the ornament rather than supplying one.
    
    ### E3. Pseudo-analysis tails
    
    Candidate: an `-ing` clause appended after a result to add generic importance,
    applicability, or promise, for example `..., highlighting the broad potential...`.
    
    End at the result when the tail adds no claim. Preserve an `-ing` clause that
    states a sourced mechanism, condition, consequence, or simultaneous action.
    
    ### E4. Unsupported rhetorical contrast
    
    Candidates include `not X but Y`, `not merely X`, `not only X but also Y`,
    `less about X and more about Y`, and split-sentence variants.
    
    Apply [contrast logic](contrast-logic.md). Occurrence count does not determine
    validity. Preserve supported experimental, definitional, scope, and reviewer-
    response contrasts. Flag concrete but unverified contrasts instead of deleting
    them. In additive forms, preserve both supported claims.
    
    ### E5. Inflated copula substitutes
    
    Candidates: `serves as`, `stands as`, `represents`, `boasts`, `features` where
    `is` or `has` carries the same meaning.
    
    Use the plain verb when the original verb adds no relation. Preserve `represents`
    in mathematical, sampling, or explicit representational senses.
    
    ### E6. Ornamental intensifiers
    
    Candidates: `remarkably`, `dramatically`, `fundamentally`, `deeply`, `vastly`,
    `critically`, and unsupported `significantly`.
    
    Keep magnitude or statistical language backed by the source. Otherwise delete
    the intensifier; never manufacture a quantity.
    
    ### E7. Hedge stacking
    
    Compress constructions such as `may suggest that X could potentially...` to the
    minimum hedge that preserves the original evidence strength. Do not remove the
    last hedge from observational, exploratory, or uncertain claims.
    
    ### E8. Vague attribution
    
    Candidates: `experts argue`, `studies show`, `researchers believe` without a
    source or identifiable referent.
    
    Name the supplied source when present. Otherwise retain an appropriately limited
    claim or flag the missing attribution. Never invent an author or citation.
    
    ### E9. Generic challenge and conclusion formulas
    
    Candidates: `Despite these challenges`, `future research is warranted`, `the
    future looks bright`, `only time will tell`, and generic `opens new avenues`.
    
    Delete an empty closer or retain a specific finding, limitation, or open question
    already in the source. Do not add a plausible limitation or future-work item.
    
    ### E10. Template opening and meta-narration
    
    Candidates: `In today's rapidly evolving...`, `In recent years...` without a
    specific fact, `This section will explore...`, `Let us examine...`, assistant
    prefaces, and process commentary.
    
    Start with the actual subject or supplied context. Preserve conventional section
    signposting when the venue uses it. Process leakage is governed by C0.
    
    ### E11. Decorative enumeration and rule-of-three
    
    Preserve genuine three-part methods, outcomes, contributions, and criteria. Act
    only when repeated triads or list scaffolds package interchangeable abstractions
    without adding structure. Rewrite as direct prose; do not change the number of
    substantive items.
    
    For multi-paragraph recurrence, apply `global-pattern-contract.md`. Preserve a
    single or repeated three-part list when the source genuinely contains three
    metrics, contributions, stages, conditions, or outcomes.
    
    ### E12. False range and local lexical cycling
    
    - Repair `from X to Y` when X and Y do not define a scale or span.
    - Remove stylistic synonym cycling in ordinary prose when it obscures a stable
      referent.
    
    Preserve established taxonomy, true ranges, and terminology required by the
    field. Manuscript-wide scientific term identity, declared abbreviations, coined
    names, and intentional distinctions are governed by
    `terminology-contract.md`. Never merge genuinely different participant groups,
    variables, models, modules, objectives, or measurements.
    
    ### E13. Mechanical rhythm and document patterning
    
    Look for repeated sentence templates, repeated openings, decorative dash asides,
    or paragraphs that all perform the same rhetorical sequence. Repair only the
    repetition that impairs reading. A short Methods paragraph, parallel result list,
    or single purposeful dash does not require variation.
    
    Apply `global-pattern-contract.md` to sentence-initial connectives, ordered
    sentence lengths, paragraph closures, triads, certainty, and rhetorical-peak
    saturation. Do not impose sentence-length quotas or a universal dash budget.
    Sentence form follows content and section function.
    
    ### E14. Tool, format, and placeholder residue
    
    Flag or remove from the clean artifact:
    
    - assistant prefaces and sign-offs;
    - citation-rendering tokens and attachment markers;
    - AI-tool tracking parameters while preserving the clean URL;
    - Markdown markers inappropriate to the target format;
    - unresolved placeholders.
    
    Never fill a placeholder, repair a citation, or infer missing metadata without a
    verified source.
    
    ## 3. Generation constraints
    
    When drafting:
    
    1. Start from supplied claims rather than a generic historical zoom-out.
    2. Do not introduce a negative premise merely to reject it.
    3. Use discourse markers, passive voice, hedging, and terminology when they carry
       academic function.
    4. Vary syntax only as the content warrants; do not follow a sentence-length recipe.
    5. Use lists only for genuinely enumerable material.
    6. End on a supplied finding, boundary, or open question, or simply stop when the
       content is complete.
    7. Mark hypotheticals and missing information honestly.
    8. Treat a citation-shaped statement in the draft as a claim, not as proof that
       the cited evidence exists; preserve and flag missing provenance.
    
    ## 4. Final language check
    
    - No unsupported claim, attribution, comparison, mechanism, or limitation was added.
    - No concrete negation or contrast was erased without grounding analysis.
    - Functional hedging, passive voice, discourse relations, and domain terms remain.
    - Promotional language and empty ceremony were removed without casualizing prose.
    - Terminology has passed the manuscript-wide contract; ordinary referents are stable.
    - The global pattern gate passed without suppressing functional recurrence.
    - Process commentary and tool residue are absent from the clean artifact.
    
  • skills/academic-humanizer/references/rules-zh.md9.0 KB35b73b4f4335upstream ↗
    # 中文学术规则
    
    仅在可编辑正文以中文为主时加载。语义合同、术语合同、全稿模式合同、学术
    白名单、虚假对立规则和 `SKILL.md` 的统一仲裁顺序始终优先。
    
    ## 目录
    
    1. 启动标准
    2. 中文模式 Z1-Z14
    3. 生成期约束
    4. 最终语言检查
    
    ## 1. 启动标准
    
    规则有两个启动层级:单个表达已经空转、缺乏来源或改变语义时,按局部缺陷处理;
    单个表达可以成立但在段落、章节或全稿中机械占优时,按分布缺陷处理。一个词或
    句式经常出现在模型文本中,不代表它在当前论文中有问题,也不能证明作者身份。
    
    启动规则前依次判断:
    
    - 这段话承载了什么命题或逻辑关系?
    - 命题能否回指用户提供的正文、数据或来源?
    - 这种表达是否符合当前章节和学科惯例?
    - 修改后能否保持否定、模态、因果强度、比较对象和范围?
    - 问题来自这个表达本身,还是来自它在完整文本中的重复位置和功能?
    
    无法确定时保留或标记,不为制造变化而变化。
    
    ## 2. 中文模式
    
    ### Z1. 模板化开场
    
    候选包括“随着……的不断发展”“在当今……背景下”“近年来……日益受到广泛
    关注”。没有具体事实或引文时,直接进入研究对象;有明确时间、趋势、文献或
    问题界定时保留。
    
    ### Z2. 空泛拔高与句尾升华
    
    候选包括“具有重要意义”“标志着新阶段”“开启新篇章”“提供有力支撑”“奠定
    坚实基础”“彰显了”“反映了”。删去后命题不变,说明它只是评价。删除评价或
    直陈来源中已有的结果,不得补充数字、影响、应用或限制。若多个句尾或段尾都
    执行同一升华动作,按 `global-pattern-contract.md` 检查位置规律和功能冗余。
    
    基金和政策文本中的规定性表达按白名单处理,不得机械清除。
    
    ### Z3. 无来源的修辞性对立
    
    候选包括“不是 X,而是 Y”“不仅仅是 X,更是 Y”“问题不在于 X,而在于 Y”
    “表面上是 X,本质上是 Y”“与其说 X,不如说 Y”。
    
    必须执行 [虚假对立规则](contrast-logic.md)。核心判据是 X 的来源和论证功能,
    不是 Y 是否具体,也不是句式出现次数。真实反驳、消融归因、负结果、定义、范围
    界定和审稿回复予以保护;具体但缺乏证据的对立只标记,不自动改。加法结构中的
    X、Y 均有内容时,不得删掉任何一项。
    
    ### Z4. 英文直译腔
    
    候选包括机械的“作为一个 X”开场、过量主语代词、“这关于……”“这不仅仅关于
    ……”以及不符合中文信息顺序的长前置修饰。按中文话题和状语顺序重写,但保持
    主客体、否定、范围和因果关系。
    
    英文术语、引文和作者有意采用的跨语言表达不在此列。
    
    ### Z5. 装饰性强调与证据失配的确定性
    
    候选包括没有证据支撑的“极大地”“深刻地”“前所未有地”“显著地”“全面地”,
    以及“一定”“必然”“毫无疑问”“无疑”等确定性表达。功能性幅度词、有统计
    依据的“显著”、定义、定理和已证明不变量中的必然性保留。
    
    确定性必须与命题账本的证据强度一致。来源只支持探索性关联时,恢复其原有模态
    和关系;来源缺失时保留并标记,不能自行猜测一个较弱结论。
    
    ### Z6. 商业和宣传黑话
    
    候选包括“赋能”“抓手”“闭环”“底层逻辑”“一站式”“全方位”“开启新赛道”。
    仅在它们是空泛隐喻时改为来源已有的动作、机制或对象;政策原文、研究对象原话和
    领域内定义用法受保护。
    
    ### Z7. 机械分点、三项包装与穷举式周全
    
    连续论证被“首先、其次、最后”或编号强行切开,且各点并非真正并列时,恢复为
    连贯段落。方法步骤、贡献列表、评价维度和真实枚举保留,不改变项目数量。
    
    三个形容词或三个抽象优点连续出现,只在它们可互换、缺少来源或反复充当完整性
    装饰时处理。对“覆盖所有情况”的平铺清单,先找来源中已有的维度、因果或层级;
    只有层级确实存在时才据此组织。不得为了优雅而发明分类、合并条件或删去例外。
    
    ### Z8. 标点和插入语
    
    检查装饰性破折号、省略号、半角标点混入中文正文和过长插入语。能在不损失关系
    时可改为逗号、括号、冒号或独立句。公式、范围、引文和作者有意使用的标点保留。
    
    不设置统一“接近零”目标,也不以单个破折号判定问题。
    破折号频率本身不是稳定的模型作者标记。多段重复时只把位置分布作为候选证据,
    仍需确认每处是否承载必要的限定、转折或插入关系。
    
    ### Z9. 万能结尾与段落峰值饱和
    
    候选包括“未来可期”“任重而道远”“机遇与挑战并存”“需要多方共同努力”“为
    后续研究奠定基础”。没有具体内容时删除;来源已提供明确结论、边界或开放问题时
    以其收束。不得自行补一个合理的研究限制或未来方向。
    
    若每段都以“金句”、抽象判断或重要性宣告收束,检查这些句子是否推进、综合或
    限制了论证。保留有证据且承担综合功能的句子;删除只重复重要性的段尾,不按配额
    保留金句。
    
    ### Z10. 四字词堆叠和局部称呼轮换
    
    - 宣传性四字词连续堆叠且不增加信息时,改为直接陈述。
    - 普通指称在局部无理由更换多个称呼并造成阅读障碍时,恢复稳定指称。
    
    保留学科固定搭配、引文和对不同群体的真实区分。论文全局的科学术语一致性、
    新命名、全称与缩写、跨语言映射及有意区分,统一执行
    `terminology-contract.md`;不得合并真实不同的模型、模块、目标函数、变量或指标。
    
    ### Z11. 助手语气和过程残留
    
    “希望对您有帮助”“以下是修改后的版本”“按照要求本文避免……”等属于过程层,
    不进入成品。若同句包含正文命题,只移除过程片段并重建衔接。
    
    引文、问卷项目和对 AI 文风的学术讨论适用“提及而非使用”豁免。
    
    ### Z12. 格式、来源和占位符残留
    
    处理与目标格式不符的 Markdown 标记、工具引用标记和链接跟踪参数。占位符只标记
    待核对,不能猜测填充。可疑引文在正文外提示核验,不得自行改作者、年份或 DOI。
    
    ### Z13. 句首路标词的机械复用
    
    候选包括连续或跨段反复以“此外”“然而”“值得注意的是”“具体而言”等开头。
    连接词只有在明确加法、转折、强调或细化关系时才保留。关系已由结构和内容清楚
    表达时,可合并句子、调整信息顺序或删除冗余路标,但不能删除关系本身。
    
    不按词表封禁连接词。使用 `global-pattern-contract.md` 同时检查次数、分布、位置和
    功能;一个合法句首或多次承担不同逻辑功能的句首不构成缺陷。
    
    ### Z14. 机械结构、句子节奏和段落模板
    
    检查连续同构句、重复开头、每段都执行相同“背景—三点—总结”模板等现象。只有
    机械结构影响论证时才调整。方法步骤、平行实验结果、定义段和短段落不需要人为
    打乱。
    
    按章节功能查看有序句长序列,而非只看平均句长。全长句、全短句或机械长短交替
    只有在违背命题边界、降低可读性时才调整。句子拆分和合并必须服从命题及关系,
    不设置每段必须出现长短句、首句必须立论或每句必须有显式连接词的配方。
    
    ## 3. 生成期约束
    
    1. 从用户提供的研究对象、问题、方法或结果进入,不写空泛时代背景。
    2. 不凭空建立一个 X 再否定,以制造“不是 X,而是 Y”的深刻感。
    3. 合法连接词、hedging、必要被动、`进行+V` 和术语按功能使用。
    4. 句法随内容变化,不按字数配方制造节奏。
    5. 只在内容真正可枚举时使用列表。
    6. 以已有结论、边界或问题结束;内容说完即可结束,不补仪式性总结。
    7. 假设必须明示,缺失事实必须询问或保留为用户认可的占位符。
    8. 在继续论证前核对引用、结果和事实前提的来源状态;草稿中的陈述不能自证。
    
    ## 4. 最终语言检查
    
    - 没有新增事实、归因、比较、机制、意义、应用、限制或未来工作。
    - 没有在缺乏证据时删除具体否定或对立命题。
    - 合法 hedging、被动、连接关系、领域术语和中文学术形态均被保留。
    - 空泛拔高、宣传黑话和仪式性表达已在不降语域的前提下处理。
    - 局部与全稿模式合同均已执行;不存在未经功能复核的连接词、三项并列、破折号、
      段尾升华、确定性或机械模板清零目标。
    - 全稿术语合同已通过,普通指称稳定,标点符合目标格式。
    - 成品不含过程说明、助手自述、工具残留和猜测填充的占位符。
    
  • skills/academic-humanizer/references/semantic-contract.md6.9 KBe891db692041upstream ↗
    # Semantic preservation contract
    
    Use this contract for every generation, rewrite, or file edit. Style repair is
    valid only inside these boundaries.
    
    ## Contents
    
    1. Source bundle
    2. Locked spans
    3. Internal claim and evidence ledger
    4. Allowed transformations
    5. Prohibited transformations
    6. Deletion safety test
    7. Generation contract
    8. Final semantic gate
    
    ## 1. Source bundle
    
    The source bundle contains:
    
    - the editable text;
    - facts, data, citations, outline points, and sources supplied by the user;
    - explicit user decisions about intended meaning;
    - user-supplied glossaries, nomenclature, abbreviations, and terminology decisions;
    - clearly marked hypothetical premises.
    
    The editable draft is authoritative for the claim the author currently intends
    to express. It is not independent proof that a cited work, quotation, reported
    result, or external fact exists. Supplied data, reference entries, source files,
    and explicit user assertions provide provenance at different strengths; record
    the distinction instead of treating all manuscript sentences as verified facts.
    
    Style requests, checklists, word limits, editor instructions, and conversation
    about how to write belong to the process layer. They are not manuscript claims.
    
    ## 2. Locked spans
    
    Do not rewrite:
    
    - direct quotations and translated passages marked as quotations;
    - formulas, equations, code, variable names, units, and statistical notation;
    - reference-list entries, citation keys, and citation markers;
    - proper nouns, dataset/model/instrument names, formally established canonical
      coined names, and verbatim policy text;
    - text the user explicitly requires verbatim.
    
    You may flag a suspected error outside the clean artifact. Do not silently repair
    a locked span.
    
    ## 3. Internal claim and evidence ledger
    
    Before editing, map each material source claim to an internal ID. Record only what
    is needed to verify the rewrite:
    
    | Field | Preserve exactly |
    |---|---|
    | entities and setting | author/agent, population, dataset, method, place, time |
    | quantities | number, unit, sign, interval, uncertainty, denominator |
    | relation | association, cause, prediction, comparison, definition, attribution |
    | polarity | affirmation, negation, exception, absence, failure |
    | comparison | baseline, direction, dimension, scope |
    | strength | may, suggests, supports, shows, demonstrates, proves |
    | boundaries | limitation, condition, population, venue, intended use |
    | provenance | citation, quotation, user statement, supplied source |
    | evidence status | supplied source, user-asserted, draft-only, hypothetical, verified |
    
    After editing, map every output claim back to a source ID and verify that every
    material source ID remains represented.
    
    `draft-only` means the proposition exists in the draft but the evidence it cites
    or implies was not supplied or verified. In rewrite/edit mode, preserve the claim
    and flag the evidence gap outside the clean artifact. Do not silently validate,
    delete, or extend it. In generation mode, do not use a draft-only premise to
    create a new result, mechanism, citation, or downstream conclusion.
    
    Concept identity is recorded separately in the terminology ledger defined by
    `terminology-contract.md`. The claim ledger establishes what each concept does;
    the terminology ledger establishes which names may refer to it. Neither ledger
    may override the other.
    
    ## 4. Allowed transformations
    
    - delete process-layer leakage while preserving content in the same sentence;
    - delete or compress wording that carries no proposition or logical relation;
    - replace promotional or vague wording with a plainer expression of the same claim;
    - combine or split sentences when all claims and relations survive;
    - change a connective or sentence order when contrast, addition, cause,
      concession, chronology, and scope remain unchanged;
    - normalize confirmed terminology drift under `terminology-contract.md` and
      normalize repetition or punctuation without changing content;
    - reduce unsupported certainty or elevation when the supplied evidence already
      establishes a weaker relation;
    - turn a supported additive contrast into a neutral additive sentence while
      preserving both X and Y.
    
    ## 5. Prohibited transformations
    
    Do not add or infer:
    
    - a number, citation, comparator, baseline, dataset, population, or method detail;
    - a mechanism, motivation, example, author intention, or personal experience;
    - a limitation, future-work item, practical implication, or generalization;
    - causal force, certainty, novelty, significance, or scope beyond the source;
    - a negative premise introduced only so it can be rejected;
    - an actor such as `we observed` when the source does not identify that actor.
    
    Do not treat a citation-shaped string, plausible author/year pair, polished
    quotation, or confident sentence as verified evidence. Do not fabricate missing
    bibliographic details or replace an unverified claim with a plausible alternative.
    
    Do not infer that two labels denote the same concept merely because their words,
    locations, or functions appear similar. Uncertain identity must remain unchanged
    until the author resolves it.
    
    Do not delete a concrete negation, comparison, limitation, or attribution merely
    because its surface form resembles an AI pattern.
    
    ## 6. Deletion safety test
    
    Before deleting a span, ask:
    
    1. Does it assert, deny, quantify, attribute, limit, compare, or connect anything?
    2. Would deletion change what a reader believes about the evidence or argument?
    3. Does adjacent text depend on the relation it expresses?
    
    If any answer is yes, preserve the meaning through direct wording or flag the
    case as uncertain. If all are no, the span is eligible for subtraction.
    
    For false-opposition candidates, X is itself a proposition. A concrete X cannot
    be removed automatically just because it lacks local support; use the uncertainty
    path in `contrast-logic.md`.
    
    ## 7. Generation contract
    
    Build claims only from the supplied source bundle. Missing content remains
    missing: ask, use a visible user-approved placeholder, or omit the unsupported
    claim. Never generate a plausible citation, result, contrast, mechanism, example,
    or limitation.
    
    Hypotheticals must be marked as hypothetical. A model-generated illustration is
    not evidence and must not be presented as an observed case.
    
    ## 8. Final semantic gate
    
    The artifact passes only when:
    
    - output-to-source mapping has no unsupported claim;
    - source-to-output mapping has no material omission;
    - locked spans are unchanged;
    - polarity, modality, causal force, comparison direction, baseline, and scope match;
    - process text and tool residue are absent;
    - uncertainty remains uncertainty.
    - every evidence-bearing claim is either grounded in supplied/verified material
      or retained with a `draft-only` diagnostic outside the artifact;
    
    Run the whole-manuscript terminology gate in `terminology-contract.md` alongside
    this semantic gate, and the whole-document pattern gate in
    `global-pattern-contract.md`. Passing one gate does not compensate for failing
    another.
    
    Keep the ledger internal unless the user asks for it.
    
  • skills/academic-humanizer/references/terminology-contract.md6.9 KB98c234249d74upstream ↗
    # Manuscript-wide terminology contract
    
    Use this contract for every multi-span generation, rewrite, or file edit. Its
    purpose is referential precision: one scientific concept has one canonical term
    throughout the editable manuscript, while genuinely distinct concepts remain
    distinct.
    
    ## Contents
    
    1. Scope and invariant
    2. Terminology ledger
    3. Canonical-term authority
    4. Allowed forms
    5. Protected and distinct terms
    6. Resolution procedure
    7. Generation and revision rules
    8. Optional deterministic audit
    9. Final terminology gate
    
    ## 1. Scope and invariant
    
    Apply the contract jointly to all supplied editable prose:
    
    - title, abstract, keywords, and main text;
    - headings, figure and table captions, labels, and notes;
    - appendix and supplementary prose;
    - reviewer responses or cover letters when they describe the same manuscript.
    
    The invariant is concept-based, not word-based. The same concept uses its
    canonical term or an explicitly allowed form everywhere. Similar-looking labels
    for distinct models, modules, objectives, variables, cohorts, or measurements
    must not be collapsed.
    
    Newly coined names require the strongest protection. Once a method, component,
    loss, metric, dataset, benchmark, or task is formally named, later sections must
    reuse that name exactly unless the manuscript declares an abbreviation or
    bilingual equivalent.
    
    ## 2. Terminology ledger
    
    Build an internal ledger before style repair. Use one row per scientific concept:
    
    | Field | Meaning |
    |---|---|
    | `concept_id` | stable internal identifier |
    | `canonical_term` | exact preferred term for editable prose |
    | `definition_span` | definition or first formal naming that grounds the term |
    | `allowed_forms` | declared abbreviations, grammatical forms, or language mappings |
    | `observed_variants` | other labels that may denote the same concept |
    | `distinguish_from` | nearby concepts that must remain separate |
    | `language_mapping` | explicit Chinese-English correspondence when supplied |
    | `status` | `resolved`, `intentional-distinction`, or `uncertain` |
    
    The ledger records identity decisions; it does not invent definitions. Keep it
    internal unless the user requests diagnostics or an audit trail.
    
    ## 3. Canonical-term authority
    
    Choose the canonical term using this order:
    
    1. the user's glossary, nomenclature table, or explicit decision;
    2. a formal definition or explicit naming statement in the source bundle;
    3. the first unambiguous formal naming in the editable manuscript;
    4. an author-approved resolution requested when the preceding evidence is absent.
    
    Do not choose by raw frequency, stylistic preference, familiarity, or what sounds
    more natural. A frequent variant may be the error. Preserve capitalization,
    hyphenation, spacing, number, and acronym form when they are part of a coined
    name.
    
    ## 4. Allowed forms
    
    Variation is allowed only when it preserves a declared identity and serves a
    real grammatical or cross-language function:
    
    - a full name followed by its declared abbreviation, then the abbreviation;
    - singular/plural or possessive inflection that grammar requires;
    - a declared Chinese-English mapping in bilingual material;
    - a notation symbol explicitly mapped to the named quantity;
    - a short form explicitly introduced by the author.
    
    An allowed form must be recorded in the ledger. Do not treat free synonymy,
    paraphrase, generic hypernyms, or pronouns with unclear antecedents as declared
    forms. Ordinary anaphora may remain when its referent is unambiguous and no
    technical identity is lost.
    
    ## 5. Protected and distinct terms
    
    Do not normalize inside locked spans:
    
    - quotations, cited historical terminology, survey items, and verbatim policy;
    - formulas, code, variable names, citation keys, and reference entries;
    - proper names or user-locked text.
    
    When prior work uses a different term, preserve that term as an attributed
    mention. The manuscript's own term remains canonical for its concept.
    
    Do not merge labels merely because they share words or appear near each other.
    For example, an `evidence encoder` may embed passages while an `evidence router`
    selects them; a model, its training objective, and its loss are distinct unless
    the source explicitly equates them.
    
    ## 6. Resolution procedure
    
    For each apparent variation:
    
    1. identify the candidate occurrences across the complete editable scope;
    2. compare definitions, inputs, outputs, role, notation, and cited provenance;
    3. classify the pair as:
       - **declared form**: both forms are authorized;
       - **same-concept drift**: normalize editable occurrences;
       - **intentional distinction**: preserve both and record `distinguish_from`;
       - **protected mention**: preserve the quoted or attributed wording;
       - **uncertain identity**: preserve and ask or flag;
    4. verify the classification against the claim ledger before editing;
    5. after editing, rescan every supplied section, caption, table, and appendix.
    
    Semantic evidence controls the decision. Lexical similarity only identifies a
    candidate for review.
    
    ## 7. Generation and revision rules
    
    During generation:
    
    - establish a canonical term when a concept is first formally introduced;
    - declare an abbreviation before using it alone;
    - reuse the ledger during every later section;
    - avoid creating alternative names to achieve lexical variety.
    
    During revision:
    
    - normalize only confirmed same-concept drift;
    - make the smallest replacement that preserves syntax and every claim;
    - do not modify locked spans or attributed historical names;
    - do not rewrite one distinct concept into another;
    - do not silently resolve uncertain identity.
    
    If the requested edit covers only one excerpt, enforce local consistency and
    state outside the clean artifact that manuscript-wide consistency requires the
    remaining sections. Never claim a full-manuscript pass without seeing the full
    editable scope.
    
    ## 8. Optional deterministic audit
    
    `scripts/terminology_audit.py` checks an explicit JSON ledger against a text
    file. It reports occurrences of declared `observed_variants` outside common
    protected spans. The helper is candidate-level evidence only:
    
    ```bash
    python3 scripts/terminology_audit.py paper.txt --ledger terms.json --json
    ```
    
    The helper does not infer whether two terms denote the same concept and never
    rewrites the manuscript. An empty report means that the supplied variants were
    not found; it does not prove global conceptual consistency.
    
    ## 9. Final terminology gate
    
    The terminology layer passes only when:
    
    - every resolved scientific concept uses its canonical term or an allowed form;
    - coined names remain exact after their formal introduction;
    - title, abstract, body, captions, tables, and supplied appendices agree;
    - every abbreviation and bilingual equivalent is declared;
    - attributed terminology and locked spans remain unchanged;
    - distinct concepts remain distinct;
    - every uncertain identity is surfaced outside the clean artifact.
    
    Failure at this gate blocks a claim that the manuscript is fully revised. Ask
    for an author decision or return a precise diagnostic instead of guessing.
    
  • skills/academic-humanizer/references/whitelist-academic.md5.8 KB43177823d24aupstream ↗
    # Cross-language academic whitelist
    
    Load this file for both languages. Protected forms outrank style-repair rules.
    When evidence is insufficient, keep the text or flag uncertainty.
    
    ## Contents
    
    1. Locked content
    2. Functional discourse relations
    3. Evidence-calibrated hedging
    4. Passive voice and impersonal constructions
    5. Terminology and scholarly compression
    6. Chinese scholarly morphology and mixed text
    7. Legitimate contrast
    8. Register conventions
    9. Mention-versus-use escape
    10. Functional recurrence and certainty
    
    ## 1. Locked content
    
    Never rewrite:
    
    - direct quotations, interview excerpts, epigraphs, and marked translations;
    - formulas, equations, code, variables, units, and statistical notation;
    - reference-list entries, citation keys, and citation markers;
    - verbatim legal or policy text;
    - proper nouns, model/dataset/instrument names, and user-locked text.
    
    Suspected errors may be reported outside the clean artifact. Do not silently
    repair them.
    
    ## 2. Functional discourse relations
    
    Keep a discourse marker when it makes a real relation explicit:
    
    - EN: Although, Whereas, However, In contrast, Therefore, Thus, Accordingly,
      Moreover, Furthermore, Specifically, Based on these results, Taken together.
    - ZH: 然而、相比之下、因此、据此、此外、与此同时、具体而言、基于上述结果、综上。
    
    Surface wording may change if addition, contrast, concession, cause, chronology,
    or conclusion remains clear. Repetition alone justifies a local restructure, not
    deletion of the relation.
    
    For multi-sentence text, use `global-pattern-contract.md`: distribution can open
    an audit, but each retained or removed marker still depends on its logical load.
    
    ## 3. Evidence-calibrated hedging
    
    Preserve uncertainty that matches the evidence:
    
    - EN: may, might, could, appears to, suggests, is associated with, is consistent with.
    - ZH: 可能、或可、结果提示、与……有关、与……一致、尚不能排除。
    
    Observational or exploratory claims must not become causal or certain. Simplify
    stacked hedges only when one well-placed hedge preserves the original strength.
    
    ## 4. Passive voice and impersonal constructions
    
    Passive voice is normal in Methods and Results when procedure or outcome matters
    more than actor. Preserve examples such as `Samples were incubated`, `Participants
    were randomized`, `样本被随机分组`, and `数据经清洗后用于分析`.
    
    Only question a passive when it hides an actor whose identity is material to the
    claim. Passive density alone is not a defect.
    
    ## 5. Terminology and scholarly compression
    
    Field-standard terminology is precision, not jargon. Preserve terms such as
    heteroskedasticity, calibration error, weighted interval score, ablation study,
    鲁棒性、显著性、异质性、消融实验、倾向得分匹配.
    
    Apply [the terminology contract](terminology-contract.md) to manuscript-owned
    terms. Preserve declared full-name/abbreviation pairs, coined names, bilingual
    mappings, and intentional distinctions. Do not create synonyms for variety, and
    do not collapse separate concepts merely because their names overlap.
    
    Moderate nominalization and anaphoric compression (`this reduction`, `the
    observation that`) are normal. Repair only empty abstraction chains.
    
    ## 6. Chinese scholarly morphology and mixed text
    
    Protect:
    
    - `进行 + V` when it marks a procedure naturally;
    - established `性` / `化` terms;
    - necessary subjectless sentences and passives;
    - functional adverbs such as 约、略、基本、相对、持续;
    - English abbreviations, model names, variables, and formulas in Chinese prose.
    
    In English prose, preserve occasional Chinese names, cited titles, and terms.
    Cross-language equivalents count as the same allowed form only when the source
    or user declares the mapping.
    
    ## 7. Legitimate contrast
    
    Contrast is protected when it has a source and argumentative function:
    
    - cited prior interpretation or misconception;
    - competing hypothesis, baseline, or ablation attribution;
    - negative versus positive result;
    - technical definition or scope exclusion;
    - reviewer-response clarification tied to an actual comment;
    - additive findings where X and Y are both supported.
    
    Use `contrast-logic.md`; never decide from `not X but Y` / `不是 X 而是 Y`
    alone.
    
    ## 8. Register conventions
    
    Preserve when appropriate to the venue or requested genre:
    
    - Introduction signposting and contribution lists in fields that use them;
    - structured abstract labels;
    - explicit limitation and future-work statements with concrete content;
    - grant or policy language required by a form or call;
    - first person where the venue permits it;
    - interrogative framing when it genuinely organizes the research question.
    
    Ask when genre convention is outcome-determinative and context does not resolve it.
    
    ## 9. Mention-versus-use escape
    
    A phrase is not a defect when quoted, cited, or analyzed as language. Do not flag
    survey items such as `"To avoid sounding like AI"`, a paper discussing
    AI-sounding prose, or a quoted `not X but Y` construction as process leakage or
    false opposition in the surrounding paper.
    
    ## 10. Functional recurrence and certainty
    
    Protect repeated form when the content is genuinely parallel: method steps,
    experimental conditions, metrics, error categories, theorem cases, structured
    abstract labels, and reviewer-by-reviewer replies. A three-part list is normal
    when the source contains exactly three substantive items.
    
    Protect purposeful dashes, sentence-initial markers, and paragraph conclusions
    that carry a real boundary or relation. Protect categorical language grounded by
    a definition, proof, invariant, or source-supported certainty. Do not preserve
    unsupported ceremony merely because its grammar is conventional.
    
    Run the local-to-document classification in `global-pattern-contract.md`; never
    use recurrence alone as a reason to delete functional academic structure.
    
  • skills/academic-humanizer/agents/openai.yaml325 Be184c4434d70upstream ↗
    interface:
      display_name: "Academic Humanizer"
      short_description: "Fact-preserving local and whole-document academic editor"
      default_prompt: "Use $academic-humanizer to revise this academic manuscript with local and whole-document pattern analysis while preserving claims, evidence strength, and canonical terminology."
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/dongshuyan-compass-skills-skills-academic-humanizer.md

// REPO STATS

768 stars
0 open issues
Last commit: 9d ago