Thesis Control

---
name: thesis-control
description: Use when AI-assisted thesis or manuscript edits risk claim drift, scope creep, loss of intended use, experiment-role promotion, or repeated revisions that fail to converge; provides author-intent control, lightweight or strict contracts, drift audits, revision escalation, and human gates.
allowed-tools: Read, Glob, Grep, Edit, Write, Bash
---

# /thesis-control - Thesis Drift Control

## Purpose

Prevent AI-assisted writing from becoming fluent but distorted. Use this before and after substantive thesis or manuscript edits when the risk is not spelling or style, but loss of author control: project-level reframing, deletion of the real-world task or intended use, a primary domain becoming a secondary example, a changed research object or question, auxiliary analyses becoming primary, widened claims, blurred section purpose, missing caveats, unsynchronised adjacent paragraphs, or local edits that weaken the paper spine.

## Trigger Words

This skill activates on: `thesis control`, `drift audit`, `edit contract`, `spine card`, `claim drift`, `author control`, `loss of control`, `scope creep`, `rewrite risk`, `/thesis-control`.

## Core Rule

Do not edit thesis prose until the project intent, current manuscript contract,
global thesis audit, section spine, and intended local change form one explicit
and traceable contract chain.

The contract must answer:

```text
This edit is allowed to change [specific local issue] in [specific unit], while preserving [spine sentence], [scope boundary], [core claims], and [do-not-change items].
```

If this sentence cannot be written, stop and diagnose the section instead of rewriting it.

The control hierarchy is:

```text
Author-approved Project Intent
→ Author-approved Manuscript Contract
→ Passed Global Thesis Audit
→ Section Spine Card
→ Edit Contract
→ Post-edit Drift Audit
```

A lower layer cannot amend a higher one. If the title, abstract, primary
domain, research object, research question, contribution scope, or manuscript
structure no longer matches the approved intent, stop. Revise or roll back the
manuscript, or create a new explicitly approved intent version that preserves
the earlier row as history.

## Control Files

Choose one control profile and name it as canonical.

For a lightweight single-manuscript workflow, read
`references/author_control_lightweight.md` and use:

- `00_AUTHOR_INTENT.md`
- `01_EVIDENCE_AND_CLAIMS.md`
- `02_REVISION_LOG.md`

Create and check the bundled templates with:

```bash
python {skill_dir}/scripts/scaffold_author_control.py <project_root>
python {skill_dir}/scripts/check_author_control.py <project_root> --strict
```

The lightweight checker validates structure, approval state, and unresolved
placeholders. It does not infer semantic alignment. Do not use the lightweight
profile to bypass a gate that already requires the durable packet.

Use a `thesis_control/` directory when the project needs durable tracking:

- `project_intent.csv`
- `manuscript_contracts.csv`
- `global_thesis_audits.csv`
- `spine_cards.csv`
- `edit_contracts.csv`
- `drift_audits.csv`
- `revision_escalations.csv`

Run the optional validator when Python is available:

```bash
python {skill_dir}/scripts/check_thesis_control.py <project_root> --strict
```

Strict validation requires the project-intent layer. It blocks approved or
applied edit contracts unless they reference a passed global thesis audit for
the active author-approved intent and manuscript contract. Non-strict mode can
still inspect legacy packets that do not yet have this layer.

The validator checks packet structure and recorded gate consistency. It does
not infer semantic alignment or judge scholarly truth. The author or reviewer
must compare the manuscript with the intent and record each alignment field
honestly; the validator then prevents an unresolved or drifted audit from being
used as authorisation.

Strict validation requires revision-tracking schema v3. Upgrade a complete
legacy packet without guessing historical revision families:

```bash
python {skill_dir}/scripts/upgrade_thesis_control_revision_tracking.py <project_root>
```

To create a draft packet from a real Markdown unit before editing prose:

```bash
python {skill_dir}/scripts/scaffold_thesis_control.py <project_root> \
  --source chapters/ch1_introduction.md \
  --start-line 71 \
  --end-line 104 \
  --revision-issue-id ri-ch1-gap-clarity \
  --attempt-no 1 \
  --copy-source
```

The scaffold writes schema v4 draft project-intent and manuscript contracts, a
pending global thesis audit, `human_approved=false`, `status=draft`, and
`AUTHOR_REVIEW_REQUIRED` fields. Replace those fields with concrete author
judgement before applying a substantive edit. A scaffolded packet may be
structurally valid while remaining non-executable. Its default contract id
includes the attempt number, so attempts 1 and 2 become `ec-<unit>-001` and
`ec-<unit>-002`. Reuse an explicit `revision_issue_id` for retries.

The migration helper stops without writing when revision metadata is partial or
when a legacy escalation cannot be classified from current contracts and
resolved audits. It preserves named extension columns and converts one- or
two-trigger legacy rows to `early_diagnostic`; a three-trigger row becomes a
`cycle_gate` only when it already matches one completed failure group.

Upgrade a complete schema-v3 packet into a deliberately blocked schema-v4
draft without guessing author intent:

```bash
python {skill_dir}/scripts/upgrade_thesis_control_project_intent.py \
  <project_root> --json
```

The helper adds `manuscript_id` and `global_audit_id` links, preserves named
extension columns, and creates `AUTHOR_REVIEW_REQUIRED` draft intent,
manuscript, and global-audit rows through one atomic batch. Previously approved
or applied edits remain blocked. Replace the draft fields with real author
judgement, approve the active intent and manuscript contract, and resolve the
global audit before strict validation can pass. A partial project-intent schema
stops without mutation.

## Workflow

### 0. Establish The Project Intent And Manuscript Contract

Before section-level planning, record:

- the real-world problem and intended user or beneficiary
- the intended application and the present method or software task
- the primary scholarly domain
- the research object
- the core research question
- the primary experiment that directly answers that question
- supporting, robustness, exploratory, failed-development, and out-of-scope analyses
- the strongest evidence-licensed headline claim
- the current validation and evidence boundaries
- the target venue or audience
- concepts that must remain visible in the title or abstract
- reframes that require fresh author approval
- the current title, abstract focus, contribution scope, and structure
- concrete approval evidence and the active version ids

Keep one active author-approved project intent and one active author-approved
manuscript contract. A later intent version must identify the immediately
previous version in `supersedes_intent_id`, record the amendment reason, and
leave the earlier version as `superseded`. Do not overwrite the original row.

Run a global thesis audit whenever the title, abstract, primary domain,
research object, research question, contribution scope, or overall structure
changes. Record each dimension as `aligned`, `drifted`, or `not_assessed`.
Only a fully aligned audit with `detected_reframe=false` can have
`status=passed` and `human_decision=accept`.

If any dimension is `drifted`, set `human_review_required=true` and use
`needs_review` or `failed`. The author must choose to revise the manuscript,
roll back, or approve a versioned intent amendment. Merely accepting the audit
cannot authorise the reframe.

Keep intended use and current validation separate. Narrow evidence may narrow
the empirical or headline claim, but it must not silently delete a legitimate
application problem or recast the evidence boundary as the paper's research
object. Record future application as intended use and untested hardware,
clinical, causal, deployment, or transfer outcomes as unvalidated boundaries.

Before admitting a completed analysis into the paper, record whether it
directly answers the core question, whether the main conclusion survives its
removal, its one-sentence argumentative function, its role, destination, and
author decision. Completion alone does not make an analysis a main
contribution. Use the role and placement defaults in
`references/author_control_lightweight.md`.

### 1. Establish Or Read The Spine Card

Before editing a chapter, section, or paragraph cluster, identify:

- unit id
- source path
- section title
- spine sentence
- scope boundary
- core claims
- do-not-change items
- the active manuscript contract id

The spine sentence should be narrow:

```text
This unit argues that [specific claim] by showing [specific basis], so the chapter can [specific function].
```

If the current text does not support a clear spine sentence, produce a diagnosis and ask for author direction before changing prose.

### 2. Create The Edit Contract

For every substantive edit, state:

- target unit and file range
- change scope: `local_patch`, `section_restructure`, or `full_reframe`
- allowed changes
- forbidden changes
- evidence baseline: the ref, artifact, data, configuration, table, or frozen numbers inherited
- argument baseline: the author-approved intent and manuscript version inherited
- adjacent context that must be checked
- acceptance checks
- whether human approval is required before editing
- the passed global thesis audit id that covers the spine card's manuscript contract

When using the scaffold helper, treat its output as a draft control packet, not
as approval. A generated contract becomes actionable only after the author has
replaced the `AUTHOR_REVIEW_REQUIRED` fields and explicitly approved the scope.

Always require human approval for:

- changing the section spine
- adding or broadening claims
- deleting caveats or limitations
- moving evidence between sections
- rewriting more than one paragraph
- merging or splitting sections
- changing the title, abstract, primary domain, research object, research question, contribution scope, or manuscript structure
- changing the real-world problem, intended use, primary experiment, analysis prominence, headline claim, or evidence boundary

Treat any change to the title, abstract thesis, research object, core question,
primary experiment, contribution order, evidence chain, application purpose,
or paper-wide structure as a `full_reframe`, even when the request calls it
polishing. Before editing, show an old-versus-proposed spine comparison and
obtain explicit author approval.

### 3. Apply Only Approved Changes

After approval, edit only the approved scope. Do not apply the edit if the
linked global thesis audit is pending, failed, stale, drifted, or attached to a
different manuscript contract.

Keep mechanical fixes separate from argument changes. Do not bundle style, structure, evidence, and claim changes into one patch unless the contract explicitly allows it.

### 4. Run The Drift Audit

After editing, compare the new prose against the contract and report:

- changed claims
- changed boundaries or caveats
- new unsupported claims
- deleted evidence anchors
- missed adjacent updates
- section-spine change
- research-object or core-question change
- deleted, generalised, or demoted real-world task or intended use
- promoted auxiliary analysis
- evidence boundary rewritten as the paper topic
- loss of application meaning caused by over-cautious wording
- title, abstract, Introduction, Results, and Conclusion alignment
- decision: accept, partial accept, revise, or rollback

If any claim, boundary, or caveat changed, the result needs human review even if the prose is smoother.

Use audit `status=needs_review` only while the author's post-edit decision is
pending. Strict validation blocks an applied contract in that state. After the
author decides, record `status=passed` for `accept` or `partial_accept`, and
`status=failed` for `revise` or `rollback`. Do not treat a pending audit as a
completed unsuccessful attempt.

### 5. Record Human Gate Outcome

The author decides whether to accept, partially accept, revise, or rollback. Do not mark a high-risk edit as accepted without explicit human approval.

### 6. Run Post-Spine Readability Gates When Relevant

Only after the research spine is stable, use `/logic-review` to audit repeated
argument functions and `/self-review` to prepare the unfamiliar-reader packet.
Do not solve repetitive AI prose by generating synonyms. Remove duplicated
problem, gap, evidence, interpretation, or boundary functions while preserving
essential local qualifiers. A model simulation cannot pass a human unfamiliar-
reader gate; record it as advisory or `not_run` until an actual reader responds.

## Revision Escalation Rule

Treat three unsuccessful attempts on the same revision issue as an operational escalation threshold, not as evidence that every task fails after three turns. Use `revision_issue_id` to keep successive contract versions attached to that issue. Only count an attempt when its drift decision is `revise` or `rollback` and its audit status is `failed`. Only applied contracts count as unsuccessful attempts. Record author rejection as one of those decisions. Multiple failed audits of one contract still count as one attempt; contradictory passed and failed resolved audits are invalid. Clarifying discussion, pending human reviews, and unexecuted proposals do not count.

After three unsuccessful attempts, stop. Do not apply a fourth prose patch. Record a row in `revision_escalations.csv`; a later contract may become `approved` or `applied` only after the matching escalation has `human_approved=true` and `status=approved`.

An approved escalation closes only that group of three unsuccessful contracts. If three later contracts also receive `revise` or `rollback`, require a new escalation before another contract can proceed.

Only a `cycle_gate` whose three triggers exactly match one completed group of
unsuccessful contracts, in attempt order, may close that group. Set
`approved_after_attempt` to the final attempt number in that group. The gate is
effective only with `human_approved=true` and `status=approved`. One gate cannot
close more than one group. Do not repeat a trigger contract within a row or
create multiple rows for the same issue and trigger set.

Only an escalation whose trigger set exactly matches one completed group of three unsuccessful contracts may close that group. One escalation cannot close more than one group.

Record an earlier warning as `early_diagnostic` with one or two unique triggers
and an empty `approved_after_attempt`. It may be author-approved as a diagnosis,
but it never closes or pre-authorises a later completed group.

An earlier escalation with fewer than three trigger contracts does not close or pre-authorise a later completed group.

Escalate earlier than three attempts when any of these signals is already visible:

- the section spine cannot be stated consistently
- the requested claim lacks supporting evidence
- a revision changes a claim, caveat, or scope boundary outside the contract
- the latest author-approved version cannot be identified
- old assumptions, duplicated explanations, or conflicting requirements indicate version contamination

### Required Escalation Check

Before editing again:

1. Consolidate the currently valid requirements into one brief.
2. Compare that brief with the spine card, evidence boundaries, current contract, and latest author-approved version.
3. Classify the failure as one primary category:
   - **underspecified or conflicting intent** — the target, audience, venue, constraint, or acceptance condition is missing or inconsistent, or the feedback is evaluative but not operational, such as “weak”, “unclear”, or “still not right” without a concrete change target
   - **local execution failure** — the contract is clear, but the edit did not implement it correctly
   - **structural mismatch** — the problem affects the section purpose, research question, gap, contribution, evidence chain, or manuscript structure
   - **evidence gap** — the requested claim is not supported by the available sources, data, experiments, or files
   - **version contamination** — accumulated patches mix incompatible assumptions, duplicate reasoning, or obscure which prose the author approved
4. Classify the writing scope:
   - **local patch** — wording or presentation changes that preserve the spine, claims, evidence, and adjacent-section relationships
   - **section-level restructure** — changes confined to one section without changing the research question, contribution, or evidence chain
   - **full reframing** — changes to the title, abstract, research question, gap, contribution, methods-results alignment, evidence chain, or discussion framing
5. Recommend the smallest valid next action and wait for author approval.

Use these default actions:

- For a local execution failure, create a corrected local contract.
- For underspecified or conflicting intent, ask for the missing decision before editing.
- For a structural mismatch, propose a section-level restructure or full reframing plan before editing.
- For an evidence gap, narrow, qualify, or remove the unsupported claim unless the author supplies more evidence.
- For version contamination, restore or copy the latest author-approved version, then apply a consolidated contract. Create a separate branch or manuscript version only when the approved scope requires structural work.

For full reframing, hand off a brief that states the target venue, old and
proposed real-world problem, intended use, research object, research question,
primary experiment, contribution order, headline claim, evidence boundary,
evidence baseline, argument baseline, available evidence, claims that must not
be made, and proposed new structure. Do not rewrite the manuscript until the
author approves that brief.

Return the escalation check in this form:

```text
## Revision Escalation Check

Revision issue:
Contract:
Unsuccessful attempts:
Trigger contracts:
Primary category:
Writing scope:
Why the revisions did not converge:
Valid requirements:
Missing or conflicting information:
Latest author-approved version:
Recommended next action:
Author decision required:
```

## Output Patterns

### Audit Only

Return:

- current spine diagnosis
- likely drift risks
- control gaps
- recommended edit contracts
- blocked items needing author decision

### Pre-Edit Contract

Return:

```text
## Edit Contract

Unit:
Spine sentence:
Scope: local_patch / section_restructure / full_reframe
Evidence baseline:
Argument baseline:
Allowed changes:
Forbidden changes:
Adjacent context to check:
Acceptance checks:
Human approval required:
Proceed only after approval:
```

### Post-Edit Drift Audit

Return:

```text
## Drift Audit

Contract:
Changed claims:
Changed boundaries:
New unsupported claims:
Missed adjacent updates:
Research object or question changed:
Intended use deleted or demoted:
Auxiliary analysis promoted:
Cross-section paper identity aligned:
Decision:
Human review required:
Recommended next action:
```

## Stop Conditions

Stop and ask for author direction if:

- the section spine cannot be stated clearly
- the requested edit would broaden a claim without evidence
- a local edit requires adjacent updates outside the approved scope
- the user asks for a full-chapter rewrite without a spine map
- previous AI edits cannot be distinguished from author-approved text
- the edit would remove caveats, limitations, or uncertainty language without explicit approval
- the active project intent or manuscript contract cannot be identified
- the real-world task, intended use, primary experiment, evidence baseline, or argument baseline cannot be identified
- a global thesis audit is missing, unresolved, stale, or records project-level drift
- a proposed local contract would preserve a section spine that conflicts with the author-approved project intent
- a full reframe lacks an approved old-versus-proposed spine comparison