feat: add project intent drift gate

Author: yha9806

.claude/skills/thesis-control/SKILL.md

@@ -8,15 +8,17 @@ allowed-tools: Read, Glob, Grep, Edit, Write, Bash
 
 ## Purpose
 
-Prevent AI-assisted writing from becoming fluent but distorted. Use this before and after substantive thesis edits when the risk is not spelling or style, but loss of author control: widened claims, blurred section purpose, missing caveats, unsynchronised adjacent paragraphs, or local edits that weaken the chapter spine.
+Prevent AI-assisted writing from becoming fluent but distorted. Use this before and after substantive thesis edits when the risk is not spelling or style, but loss of author control: project-level reframing, a primary domain becoming a secondary example, a changed research object or question, widened claims, blurred section purpose, missing caveats, unsynchronised adjacent paragraphs, or local edits that weaken the chapter 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 intended change has an explicit contract.
+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:
 
@@ -26,10 +28,30 @@ This edit is allowed to change [specific local issue] in [specific unit], while
 
 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
 
 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`
@@ -41,7 +63,16 @@ Run the optional validator when Python is available:
 python {skill_dir}/scripts/check_thesis_control.py <project_root> --strict
 ```
 
-The validator checks packet structure and gate consistency. It does not judge scholarly truth.
+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:
@@ -62,10 +93,12 @@ python {skill_dir}/scripts/scaffold_thesis_control.py <project_root> \
   --copy-source
 ```
 
-The scaffold writes `human_approved=false`, `status=draft`, and
+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. Its default contract id includes
-the attempt number, so attempts 1 and 2 become `ec-<unit>-001` and
+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
@@ -74,8 +107,53 @@ 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 primary scholarly domain
+- the research object
+- the core research question
+- 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.
+
 ### 1. Establish Or Read The Spine Card
 
 Before editing a chapter, section, or paragraph cluster, identify:
@@ -87,6 +165,7 @@ Before editing a chapter, section, or paragraph cluster, identify:
 - scope boundary
 - core claims
 - do-not-change items
+- the active manuscript contract id
 
 The spine sentence should be narrow:
 
@@ -107,6 +186,7 @@ For every substantive edit, state:
 - 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
@@ -120,10 +200,13 @@ Always require human approval for:
 - 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
 
 ### 3. Apply Only Approved Changes
 
-After approval, edit only the approved scope.
+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.
 
@@ -285,3 +368,6 @@ Stop and ask for author direction if:
 - 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
+- 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

.claude/skills/thesis-control/scripts/check_thesis_control.py

@@ -16,6 +16,7 @@
 from pathlib import Path
 from typing import Dict, Iterable, List, Mapping, Optional, Sequence, Set, Tuple
 
+from project_intent_control import validate_project_intent_layer
 from thesis_control_io import CsvShapeError, read_csv_table
 
 
@@ -203,6 +204,7 @@ def add_issue(issues: List[dict], kind: str, location: str, message: str) -> Non
 def validate_packet(
     root: Path,
     strict: bool = False,
+    require_project_intent: Optional[bool] = None,
     table_overrides: Optional[
         Mapping[str, Tuple[Sequence[str], Sequence[Mapping[str, str]]]]
     ] = None,
@@ -232,15 +234,27 @@ def validate_packet(
         column in contract_fields for column in REVISION_CONTRACT_COLUMNS
     )
 
+    intent_state, intent_issues = validate_project_intent_layer(
+        root,
+        required=strict if require_project_intent is None else require_project_intent,
+        table_overrides=overrides,
+    )
+    intent_tracking = intent_state["enabled"]
+
+    spine_columns = list(REQUIRED_FILES["spine_cards.csv"])
+    if intent_tracking:
+        spine_columns.append("manuscript_id")
     spine_rows, spine_issues = validate_columns(
         root,
         "spine_cards.csv",
-        REQUIRED_FILES["spine_cards.csv"],
+        spine_columns,
         table=overrides.get("spine_cards.csv"),
     )
     contract_columns = list(REQUIRED_FILES["edit_contracts.csv"])
     if revision_tracking:
         contract_columns.extend(REVISION_CONTRACT_COLUMNS)
+    if intent_tracking:
+        contract_columns.append("global_audit_id")
     contract_rows, contract_issues = validate_columns(
         root,
         "edit_contracts.csv",
@@ -269,9 +283,16 @@ def validate_packet(
             allow_empty=True,
             table=overrides.get("revision_escalations.csv"),
         )
-    issues.extend(spine_issues + contract_issues + audit_issues + escalation_issues)
+    issues.extend(
+        intent_issues
+        + spine_issues
+        + contract_issues
+        + audit_issues
+        + escalation_issues
+    )
 
     spine_ids = set()
+    spine_manuscripts: Dict[str, str] = {}
     for index, row in enumerate(spine_rows):
         location = row_location("spine_cards.csv", index)
         unit_id = row.get("unit_id", "").strip()
@@ -299,6 +320,31 @@ def validate_packet(
         )
         if path_issue:
             add_issue(issues, "invalid-source-path", location, path_issue)
+        if intent_tracking:
+            manuscript_id = row.get("manuscript_id", "").strip()
+            if not manuscript_id:
+                add_issue(
+                    issues,
+                    "missing-manuscript-id",
+                    location,
+                    "spine card has no manuscript_id",
+                )
+            elif not is_valid_identifier(manuscript_id):
+                add_issue(
+                    issues,
+                    "invalid-manuscript-id",
+                    location,
+                    "manuscript_id must be a safe identifier",
+                )
+            elif manuscript_id not in intent_state["manuscripts_by_id"]:
+                add_issue(
+                    issues,
+                    "unknown-manuscript-id",
+                    location,
+                    f"spine card references unknown manuscript_id: {manuscript_id}",
+                )
+            if unit_id and manuscript_id:
+                spine_manuscripts[unit_id] = manuscript_id
 
     contract_ids = set()
     applied_contracts = set()
@@ -315,6 +361,7 @@ def validate_packet(
         approved = parse_bool(row.get("human_approved", ""))
         revision_issue_id = row.get("revision_issue_id", "").strip()
         attempt_text = row.get("attempt_no", "").strip()
+        global_audit_id = row.get("global_audit_id", "").strip()
 
         if not contract_id:
             add_issue(issues, "missing-contract-id", location, "edit contract has no contract_id")
@@ -350,6 +397,49 @@ def validate_packet(
         if status in {"approved", "applied"} and approved is not True:
             add_issue(issues, "missing-human-approval", location, "approved/applied contracts require human_approved=true")
 
+        if intent_tracking:
+            if not global_audit_id:
+                add_issue(
+                    issues,
+                    "missing-global-audit-id",
+                    location,
+                    "edit contract has no global_audit_id",
+                )
+            elif not is_valid_identifier(global_audit_id):
+                add_issue(
+                    issues,
+                    "invalid-global-audit-id",
+                    location,
+                    "global_audit_id must be a safe identifier",
+                )
+            elif global_audit_id not in intent_state["audits_by_id"]:
+                add_issue(
+                    issues,
+                    "unknown-global-audit-id",
+                    location,
+                    f"edit contract references unknown global_audit_id: {global_audit_id}",
+                )
+            else:
+                audit_record = intent_state["audits_by_id"][global_audit_id]
+                spine_manuscript = spine_manuscripts.get(unit_id)
+                if spine_manuscript and audit_record["manuscript_id"] != spine_manuscript:
+                    add_issue(
+                        issues,
+                        "contract-global-audit-mismatch",
+                        location,
+                        "edit contract global audit does not cover the spine card's manuscript contract",
+                    )
+                if (
+                    status in {"approved", "applied"}
+                    and global_audit_id not in intent_state["ready_audit_ids"]
+                ):
+                    add_issue(
+                        issues,
+                        "global-thesis-gate-required",
+                        location,
+                        "approved/applied edits require a passed global thesis audit for the active project intent and manuscript contract",
+                    )
+
         for column in ["change_scope", "allowed_changes", "forbidden_changes", "adjacent_context", "acceptance_checks"]:
             if is_empty(row.get(column, "")):
                 add_issue(issues, "empty-contract-field", location, f"edit contract field is empty: {column}")
@@ -759,6 +849,27 @@ def validate_packet(
                                 f"contract {contract_id} cannot proceed before revision issue {revision_issue_id} has an approved cycle_gate for {trigger_list}",
                             )
 
+    executable_contracts = [
+        contract_id
+        for contract_id, status in contract_statuses.items()
+        if status in {"approved", "applied"}
+    ]
+    if intent_tracking and executable_contracts:
+        if len(intent_state["active_intent_ids"]) != 1:
+            add_issue(
+                issues,
+                "active-project-intent-required",
+                "thesis_control/project_intent.csv",
+                "approved/applied edits require exactly one active author-approved project intent",
+            )
+        if len(intent_state["active_manuscript_ids"]) != 1:
+            add_issue(
+                issues,
+                "active-manuscript-contract-required",
+                "thesis_control/manuscript_contracts.csv",
+                "approved/applied edits require exactly one active author-approved manuscript contract",
+            )
+
     if strict:
         missing_audits = sorted(applied_contracts - audited_contracts)
         for contract_id in missing_audits:
@@ -780,6 +891,10 @@ def validate_packet(
             "revision_escalations": len(escalation_rows),
             "revision_tracking": revision_tracking,
             "escalation_schema_version": 3 if escalation_v3 else 2,
+            "project_intent_tracking": intent_tracking,
+            "project_intents": len(intent_state["intent_rows"]),
+            "manuscript_contracts": len(intent_state["manuscript_rows"]),
+            "global_thesis_audits": len(intent_state["audit_rows"]),
         },
         "issues": issues,
         "issue_count": len(issues),