easy-coding-harness 0.6.0 → 0.7.0

package/templates/shared-hooks/easy_coding_state.py

@@ -3,6 +3,7 @@ import argparse
 import hashlib
 import json
 import os
+import re
 from datetime import datetime, timezone
 from pathlib import Path
 import sys
@@ -26,7 +27,6 @@ MANDATORY_DEV_SPEC_HEADERS: list[str] = [
     "### 需求解析",
     "### 现状",
     "### 冲突摘要",
-    "### 待用户决策",
     "### 影响面分析",
     "### 改动范围",
     "### 修改方案",
@@ -39,7 +39,7 @@ VALID_TRANSITIONS: dict[str, set[str]] = {
     "idle": {"INIT"},
     "INIT": {"ANALYSIS", "CLOSED"},
     "ANALYSIS": {"IMPLEMENT", "CLOSED"},
-    "IMPLEMENT": {"REVIEW", "ANALYSIS", "CLOSED"},
+    "IMPLEMENT": {"REVIEW", "VERIFICATION", "ANALYSIS", "COMPLETE", "CLOSED"},
     "REVIEW": {"VERIFICATION", "IMPLEMENT", "ANALYSIS", "CLOSED"},
     "VERIFICATION": {"MEMORY", "IMPLEMENT", "CLOSED"},
     "MEMORY": {"COMPLETE", "CLOSED"},
@@ -47,6 +47,19 @@ VALID_TRANSITIONS: dict[str, set[str]] = {
     "CLOSED": set(),
 }
 
+ALWAYS_AUTO_TRANSITIONS = {
+    ("INIT", "ANALYSIS"),
+    ("MEMORY", "COMPLETE"),
+}
+READ_ONLY_COMPLETION_TRANSITION = ("IMPLEMENT", "COMPLETE")
+NO_CODE_TASK_TYPES = {"analysis", "doc", "report"}
+CONFIRM_MODES = {"approve", "guard", "auto"}
+DEFAULT_CONFIRM_MODE = "guard"
+GUARD_CONFIRM_TRANSITIONS = {
+    ("ANALYSIS", "IMPLEMENT"),
+    ("VERIFICATION", "MEMORY"),
+}
+
 LEGACY_STAGE_MAP = {
     "WAITING_CONFIRM": "ANALYSIS",
     "MEMORY_SHORT": "MEMORY",
@@ -55,6 +68,24 @@ LEGACY_STAGE_MAP = {
 
 DEFAULT_SHORT_TERM_MAX = 10
 DEFAULT_SHORT_TERM_KEEP = 5
+DEV_SPEC_PLACEHOLDER_PATTERN = re.compile(r"\[\[EC_TODO:[^\]\n]+\]\]")
+MARKDOWN_HEADING_PATTERN = re.compile(r"^(#{1,6})\s+(.+?)\s*$")
+TABLE_HEADER_CELLS = {
+    "改动文件",
+    "改动类型",
+    "文件编码",
+    "改动核心内容",
+    "单元",
+    "说明",
+    "类型",
+    "涉及文件",
+    "依赖",
+    "测试点",
+    "级别",
+    "归属单元",
+    "方式",
+    "验证命令",
+}
 
 
 class StateError(Exception):
@@ -140,6 +171,51 @@ def read_memory_config(root: Path) -> dict[str, int]:
     return config
 
 
+def read_project_confirm_mode(root: Path) -> str:
+    path = root / ".easy-coding" / "config.yaml"
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return DEFAULT_CONFIRM_MODE
+
+    in_behavior = False
+    behavior_indent = 0
+    for raw_line in lines:
+        without_comment = raw_line.split("#", 1)[0].rstrip()
+        stripped = without_comment.strip()
+        if not stripped:
+            continue
+        indent = len(without_comment) - len(without_comment.lstrip(" "))
+        if stripped == "behavior:":
+            in_behavior = True
+            behavior_indent = indent
+            continue
+        if in_behavior and indent <= behavior_indent:
+            in_behavior = False
+        if not in_behavior or ":" not in stripped:
+            continue
+        key, value = stripped.split(":", 1)
+        if key != "confirm_mode":
+            continue
+        mode = value.strip().strip("'\"")
+        if mode not in CONFIRM_MODES:
+            raise StateError(
+                "Invalid behavior.confirm_mode in .easy-coding/config.yaml: "
+                "expected approve, guard, or auto."
+            )
+        return mode
+    return DEFAULT_CONFIRM_MODE
+
+
+def resolve_confirm_mode(root: Path, session: dict) -> tuple[str, str | None, str]:
+    project_mode = read_project_confirm_mode(root)
+    session_mode = session.get("confirm_mode")
+    if session_mode is not None and session_mode not in CONFIRM_MODES:
+        raise StateError("Invalid session confirm_mode: expected approve, guard, or auto.")
+    effective_mode = str(session_mode or project_mode)
+    return project_mode, str(session_mode) if session_mode else None, effective_mode
+
+
 def short_memory_entries(root: Path) -> list[dict[str, object]]:
     short_dir = root / ".easy-coding" / "memory" / "short"
     if not short_dir.is_dir():
@@ -455,6 +531,378 @@ def append_execution_record(root: Path, task_id: str, record: dict) -> None:
         handle.write(json.dumps(record, ensure_ascii=False) + "\n")
 
 
+def is_non_empty_string(value: object) -> bool:
+    return isinstance(value, str) and bool(value.strip())
+
+
+def is_string_list(value: object, allow_empty: bool = True) -> bool:
+    return (
+        isinstance(value, list)
+        and (allow_empty or len(value) > 0)
+        and all(is_non_empty_string(item) for item in value)
+    )
+
+
+def has_acyclic_dependencies(dependencies_by_unit: dict[str, set[str]]) -> bool:
+    remaining = {unit_id: set(dependencies) for unit_id, dependencies in dependencies_by_unit.items()}
+    resolved: set[str] = set()
+    while remaining:
+        ready = {
+            unit_id for unit_id, dependencies in remaining.items() if dependencies.issubset(resolved)
+        }
+        if not ready:
+            return False
+        resolved.update(ready)
+        for unit_id in ready:
+            remaining.pop(unit_id)
+    return True
+
+
+def is_valid_execution_plan(plan: object, allow_empty_files: bool = False) -> bool:
+    if not isinstance(plan, dict):
+        return False
+    strategy = plan.get("strategy")
+    units = plan.get("units")
+    if strategy not in {"single", "sequential", "parallel"} or not isinstance(units, list):
+        return False
+    if not units or (strategy == "single" and len(units) != 1):
+        return False
+    if strategy == "parallel" and len(units) < 2:
+        return False
+
+    unit_ids: list[str] = []
+    has_empty_file_scope = False
+    for unit in units:
+        if not isinstance(unit, dict):
+            return False
+        if not all(is_non_empty_string(unit.get(field)) for field in ("id", "title", "type")):
+            return False
+        if not is_string_list(unit.get("files"), allow_empty=allow_empty_files):
+            return False
+        if not unit["files"]:
+            has_empty_file_scope = True
+        if not is_string_list(unit.get("depends_on")):
+            return False
+        for optional_list in ("rules_sections", "abstract_modules"):
+            if optional_list in unit and not is_string_list(unit.get(optional_list)):
+                return False
+        unit_ids.append(str(unit["id"]))
+
+    if has_empty_file_scope and (not allow_empty_files or strategy != "single" or len(units) != 1):
+        return False
+
+    if len(set(unit_ids)) != len(unit_ids):
+        return False
+    known_ids = set(unit_ids)
+    dependencies_by_unit: dict[str, set[str]] = {}
+    for unit in units:
+        unit_id = str(unit["id"])
+        dependencies = set(unit["depends_on"])
+        if unit_id in dependencies or not dependencies.issubset(known_ids):
+            return False
+        dependencies_by_unit[unit_id] = dependencies
+    if not has_acyclic_dependencies(dependencies_by_unit):
+        return False
+
+    if strategy == "parallel":
+        parallel_groups = plan.get("parallel_groups")
+        if not isinstance(parallel_groups, list) or not parallel_groups:
+            return False
+        grouped_ids: list[str] = []
+        group_levels: set[int] = set()
+        level_by_unit: dict[str, int] = {}
+        for group in parallel_groups:
+            level = group.get("level") if isinstance(group, dict) else None
+            if (
+                not isinstance(group, dict)
+                or type(level) is not int
+                or level < 0
+                or level in group_levels
+                or not is_string_list(group.get("units"), allow_empty=False)
+            ):
+                return False
+            group_levels.add(level)
+            grouped_ids.extend(group["units"])
+            for unit_id in group["units"]:
+                level_by_unit[unit_id] = level
+        if len(grouped_ids) != len(set(grouped_ids)) or set(grouped_ids) != known_ids:
+            return False
+        for unit_id, dependencies in dependencies_by_unit.items():
+            if any(level_by_unit[dependency] >= level_by_unit[unit_id] for dependency in dependencies):
+                return False
+
+    return True
+
+
+def is_read_only_execution_plan(plan: object) -> bool:
+    return (
+        is_valid_execution_plan(plan, allow_empty_files=True)
+        and isinstance(plan, dict)
+        and plan.get("strategy") == "single"
+        and len(plan["units"]) == 1
+        and plan["units"][0].get("files") == []
+    )
+
+
+def has_valid_execution_plan(root: Path, task_id: str) -> bool:
+    path = execution_log_path(root, task_id)
+    if not path.exists():
+        return False
+    latest_plan: dict | None = None
+    try:
+        for line in path.read_text(encoding="utf-8").splitlines():
+            if not line.strip():
+                continue
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                return False
+            if isinstance(record, dict) and record.get("type") == "plan":
+                latest_plan = record
+    except OSError:
+        return False
+    task = load_task(root, task_id)
+    task_type = str(task.get("type") or "").strip().lower() if task else ""
+    if task_type in NO_CODE_TASK_TYPES:
+        return is_read_only_execution_plan(latest_plan)
+    return is_valid_execution_plan(latest_plan)
+
+
+def validate_read_only_completion(root: Path, task_id: str) -> None:
+    task = load_task(root, task_id)
+    task_type = str(task.get("type") or "").strip().lower() if task else ""
+    reasons: list[str] = []
+    if task_type not in NO_CODE_TASK_TYPES:
+        reasons.append("task type is not doc, analysis, or report")
+
+    path = execution_log_path(root, task_id)
+    records: list[dict] = []
+    if not path.exists():
+        reasons.append("execution.jsonl is missing")
+    else:
+        try:
+            for line in path.read_text(encoding="utf-8").splitlines():
+                if not line.strip():
+                    continue
+                record = json.loads(line)
+                if not isinstance(record, dict):
+                    reasons.append("execution.jsonl contains a non-object record")
+                    break
+                records.append(record)
+        except (OSError, json.JSONDecodeError):
+            reasons.append("execution.jsonl cannot be read as valid JSONL")
+
+    latest_plan_index: int | None = None
+    for index, record in enumerate(records):
+        if record.get("type") == "plan":
+            latest_plan_index = index
+
+    unit_id = ""
+    if latest_plan_index is None:
+        reasons.append("execution.jsonl has no plan record")
+    else:
+        plan = records[latest_plan_index]
+        if not is_read_only_execution_plan(plan):
+            reasons.append("latest plan record is invalid")
+        else:
+            units = plan["units"]
+            unit_id = str(units[0]["id"])
+
+    unit_records: list[dict] = []
+    if latest_plan_index is not None and unit_id:
+        for record in records[latest_plan_index + 1 :]:
+            if record.get("unit_id") == unit_id and record.get("type") in {"dispatch", "result"}:
+                unit_records.append(record)
+    latest_result = (
+        unit_records[-1]
+        if unit_records and unit_records[-1].get("type") == "result"
+        else None
+    )
+    if latest_result is None:
+        reasons.append("latest read-only unit has no result record")
+    else:
+        matching_dispatch = unit_records[-2] if len(unit_records) >= 2 else None
+        if matching_dispatch is None or matching_dispatch.get("type") != "dispatch":
+            reasons.append("latest read-only result has no matching dispatch record")
+        elif not is_non_empty_string(matching_dispatch.get("timestamp")):
+            reasons.append("latest read-only dispatch record has no timestamp")
+        if latest_result.get("changed_files") != []:
+            reasons.append("read-only result must contain changed_files:[]")
+        if not is_non_empty_string(latest_result.get("deliverable")):
+            reasons.append("read-only result must contain a non-empty deliverable")
+        if latest_result.get("issues") != []:
+            reasons.append("read-only result must contain issues:[]")
+        if latest_result.get("needs_attention") != []:
+            reasons.append("read-only result must contain needs_attention:[]")
+
+    if reasons:
+        raise StateError(
+            "Read-only IMPLEMENT cannot complete before its report is ready: " + "; ".join(reasons)
+        )
+
+
+def markdown_headings(content: str) -> list[tuple[int, int, str]]:
+    headings: list[tuple[int, int, str]] = []
+    fence_marker: str | None = None
+    for index, line in enumerate(content.splitlines()):
+        stripped = line.lstrip()
+        if stripped.startswith(("```", "~~~")):
+            marker = stripped[:3]
+            if fence_marker is None:
+                fence_marker = marker
+            elif fence_marker == marker:
+                fence_marker = None
+            continue
+        if fence_marker is not None:
+            continue
+        match = MARKDOWN_HEADING_PATTERN.match(line.strip())
+        if match:
+            headings.append((index, len(match.group(1)), match.group(2).strip()))
+    return headings
+
+
+def has_meaningful_markdown_body(content: str) -> bool:
+    for line in content.splitlines():
+        stripped = line.strip()
+        if not stripped or MARKDOWN_HEADING_PATTERN.match(stripped):
+            continue
+        if stripped.startswith(">"):
+            continue
+        if re.fullmatch(r"[-|: ]+", stripped):
+            continue
+        if stripped == "（若 single：单一实施单元，派发 1 个子代理执行）":
+            continue
+        if stripped.startswith("|") and stripped.endswith("|"):
+            cells = {cell.strip() for cell in stripped.strip("|").split("|") if cell.strip()}
+            if cells and cells.issubset(TABLE_HEADER_CELLS):
+                continue
+        plain = re.sub(r"[`*_]", "", stripped)
+        plain = re.sub(r"^[-+]\s*", "", plain).strip()
+        if re.fullmatch(r"[^:：|]+[:：]", plain):
+            continue
+        return True
+    return False
+
+
+def validate_mandatory_dev_spec_sections(content: str) -> tuple[list[str], list[str]]:
+    lines = content.splitlines()
+    headings = markdown_headings(content)
+    missing: list[str] = []
+    empty: list[str] = []
+
+    title_heading = next(
+        (
+            (line_index, level, title)
+            for line_index, level, title in headings
+            if level == 2 and (title == "技术方案" or title.startswith(("技术方案：", "技术方案:")))
+        ),
+        None,
+    )
+    if title_heading is None:
+        missing.append("## 技术方案")
+    else:
+        title = title_heading[2]
+        title_value = title.removeprefix("技术方案").lstrip("：:").strip()
+        if not title_value:
+            empty.append("## 技术方案")
+
+    for header in MANDATORY_DEV_SPEC_HEADERS[1:]:
+        expected_title = header.removeprefix("### ")
+        heading_index = next(
+            (
+                index
+                for index, (_, level, title) in enumerate(headings)
+                if level == 3 and title == expected_title
+            ),
+            None,
+        )
+        if heading_index is None:
+            missing.append(header)
+            continue
+        line_index, level, _ = headings[heading_index]
+        next_line_index = len(lines)
+        for candidate_line, candidate_level, _ in headings[heading_index + 1 :]:
+            if candidate_level <= level:
+                next_line_index = candidate_line
+                break
+        body = "\n".join(lines[line_index + 1 : next_line_index])
+        if not has_meaningful_markdown_body(body):
+            empty.append(header)
+
+    return missing, empty
+
+
+def validate_analysis_readiness(root: Path, task_id: str) -> None:
+    task_dir = task_json_path(root, task_id).parent
+    task = load_task(root, task_id)
+    task_type = str(task.get("type") or "").strip().lower() if task else ""
+    is_read_only_task = task_type in NO_CODE_TASK_TYPES
+    dev_spec = task_dir / "dev-spec.md"
+    skeleton = root / ".easy-coding" / "templates" / "dev-spec-skeleton.md"
+    test_strategy = task_dir / "test-strategy.md"
+    reasons: list[str] = []
+
+    dev_spec_content = ""
+    if not dev_spec.exists():
+        reasons.append("dev-spec.md is missing")
+    else:
+        try:
+            dev_spec_content = dev_spec.read_text(encoding="utf-8")
+            if not dev_spec_content.strip():
+                reasons.append("dev-spec.md is empty")
+        except OSError:
+            reasons.append("dev-spec.md cannot be read")
+
+    if dev_spec_content:
+        missing_headers, empty_sections = validate_mandatory_dev_spec_sections(dev_spec_content)
+        if is_read_only_task:
+            empty_sections = [
+                header for header in empty_sections if header != "### 改动范围"
+            ]
+        if missing_headers:
+            reasons.append(
+                "dev-spec.md is missing mandatory headers: "
+                + ", ".join(header.lstrip("# ") for header in missing_headers)
+            )
+        if empty_sections:
+            reasons.append(
+                "dev-spec.md has empty mandatory sections: "
+                + ", ".join(header.lstrip("# ") for header in empty_sections)
+            )
+        if "[阶段：ANALYSIS]" in dev_spec_content or "### 待用户决策" in dev_spec_content:
+            reasons.append("dev-spec.md contains forbidden analysis-only sections")
+
+        if not skeleton.exists():
+            reasons.append("dev-spec skeleton template is missing")
+        else:
+            try:
+                skeleton_content = skeleton.read_text(encoding="utf-8")
+                if not DEV_SPEC_PLACEHOLDER_PATTERN.search(skeleton_content):
+                    reasons.append("dev-spec skeleton template has no EC_TODO markers")
+                if DEV_SPEC_PLACEHOLDER_PATTERN.search(dev_spec_content):
+                    reasons.append("dev-spec.md contains unresolved template placeholders")
+            except OSError:
+                reasons.append("dev-spec skeleton template cannot be read")
+
+    if not has_valid_execution_plan(root, task_id):
+        reasons.append("execution.jsonl has no valid plan record")
+    if is_read_only_task:
+        if test_strategy.exists():
+            reasons.append("read-only task must not create test-strategy.md")
+    else:
+        try:
+            if not test_strategy.exists() or not test_strategy.read_text(encoding="utf-8").strip():
+                reasons.append("test-strategy.md is missing or empty")
+        except OSError:
+            reasons.append("test-strategy.md cannot be read")
+
+    if reasons:
+        raise StateError(
+            "ANALYSIS cannot advance to IMPLEMENT before analysis artifacts are ready: "
+            + "; ".join(reasons)
+        )
+
+
 def latest_handoff_record(root: Path, task_id: str) -> dict | None:
     path = execution_log_path(root, task_id)
     if not path.exists():
@@ -493,10 +941,43 @@ def get_pending_init_version(root: Path) -> str | None:
     return None
 
 
-def validate_transition(previous: str, current: str) -> str | None:
+def transition_requires_confirmation(
+    previous: str,
+    current: str,
+    task_type: str,
+    confirm_mode: str,
+) -> bool:
+    if (previous, current) in ALWAYS_AUTO_TRANSITIONS:
+        return False
+    if current == "CLOSED":
+        return True
+    if confirm_mode == "auto":
+        return False
+    if confirm_mode == "guard":
+        return (previous, current) in GUARD_CONFIRM_TRANSITIONS
+    if confirm_mode == "approve":
+        return True
+    raise StateError(f"Unknown confirm mode: {confirm_mode}")
+
+
+def is_automatic_transition(
+    previous: str,
+    current: str,
+    task_type: str,
+    confirm_mode: str,
+) -> bool:
+    return not transition_requires_confirmation(previous, current, task_type, confirm_mode)
+
+
+def validate_transition(previous: str, current: str, task_type: str = "") -> str | None:
     if previous == current:
         return None
-    allowed = VALID_TRANSITIONS.get(previous, set())
+    normalized_task_type = task_type.strip().lower()
+    allowed = set(VALID_TRANSITIONS.get(previous, set()))
+    if previous == "IMPLEMENT" and normalized_task_type in NO_CODE_TASK_TYPES:
+        allowed = {"ANALYSIS", "COMPLETE", "CLOSED"}
+    elif previous == "IMPLEMENT":
+        allowed.discard("COMPLETE")
     if current in allowed:
         return None
     return (
@@ -532,6 +1013,10 @@ def snapshot_state(
         missing = False
         status = "idle"
 
+    project_confirm_mode, session_confirm_mode, effective_confirm_mode = resolve_confirm_mode(
+        root, resolved_session
+    )
+
     return {
         "session_file": display_path(root, session_path),
         "current_task": str(task_id) if task_id else None,
@@ -544,6 +1029,10 @@ def snapshot_state(
         "last_agent": task.get("last_agent") if task else None,
         "project_init_required": is_project_init_required(root),
         "pending_init_version": get_pending_init_version(root),
+        "project_confirm_mode": project_confirm_mode,
+        "session_confirm_mode": session_confirm_mode,
+        "effective_confirm_mode": effective_confirm_mode,
+        "harness_disabled": resolved_session.get("harness_disabled") is True,
     }
 
 
@@ -589,7 +1078,11 @@ def build_machine_breadcrumbs(
     task = state["task"]
     stage = str(state["status"]) if task else "idle"
     resolved_session_file = str(state["session_file"])
-    lines = [f"[workflow-state:{stage}]", f"[easy-coding:session-file:{resolved_session_file}]"]
+    lines = [
+        f"[workflow-state:{stage}]",
+        f"[easy-coding:session-file:{resolved_session_file}]",
+        f"[easy-coding:confirm-mode:{state['effective_confirm_mode']}]",
+    ]
 
     if task_id:
         lines.append(f"[current-task:{task_id}]")
@@ -604,7 +1097,16 @@ def build_machine_breadcrumbs(
             target = str(pending.get("to") or "")
             if target:
                 lines.append(f"[easy-coding:pending-transition:{source}->{target}]")
-                lines.append("[easy-coding:transition-confirmation-required]")
+                task_type = str(task.get("type") or "") if task else ""
+                if is_automatic_transition(
+                    source,
+                    target,
+                    task_type,
+                    str(state["effective_confirm_mode"]),
+                ):
+                    lines.append(f"[easy-coding:auto-transition-ready:{source}->{target}]")
+                else:
+                    lines.append("[easy-coding:transition-confirmation-required]")
 
     if is_project_init_required(root):
         lines.append("[easy-coding:init-required]")
@@ -648,6 +1150,14 @@ def build_status_context(
     agent: str | None = None,
     session_file: str | Path | None = None,
 ) -> str:
+    if session.get("harness_disabled") is True:
+        session_path = resolve_session_path(root, session_file)
+        return "\n".join(
+            [
+                "[easy-coding:no-harness]",
+                f"[easy-coding:session-file:{display_path(root, session_path)}]",
+            ]
+        )
     return "\n".join(
         [
             build_status_line(root, session, agent, session_file),
@@ -667,7 +1177,7 @@ def attach_status_context(
     if session is None:
         session = default_session()
     context = build_status_context(root, session, agent, resolved_session_file)
-    first_line = context.splitlines()[0] if context else ""
+    first_line = context.splitlines()[0] if context.startswith("> ") else ""
     enriched = dict(data)
     enriched["status_line"] = first_line
     enriched["status_context"] = context
@@ -742,6 +1252,55 @@ def clear_current_task(root: Path, agent: str, session_file: str | Path | None =
     return snapshot_state(root, session_file, session)
 
 
+def set_session_confirm_mode(
+    root: Path,
+    mode: str,
+    agent: str,
+    session_file: str | Path | None = None,
+) -> dict:
+    if mode not in CONFIRM_MODES:
+        raise StateError("Invalid confirm mode: expected approve, guard, or auto.")
+    session = ensure_session(root, session_file)
+    session["confirm_mode"] = mode
+    session["last_agent"] = agent
+    write_session(root, session, session_file)
+    snapshot = snapshot_state(root, session_file, session)
+    snapshot["action"] = "set-confirm-mode"
+    return snapshot
+
+
+def clear_session_confirm_mode(
+    root: Path,
+    agent: str,
+    session_file: str | Path | None = None,
+) -> dict:
+    session = ensure_session(root, session_file)
+    session.pop("confirm_mode", None)
+    session["last_agent"] = agent
+    write_session(root, session, session_file)
+    snapshot = snapshot_state(root, session_file, session)
+    snapshot["action"] = "clear-confirm-mode"
+    return snapshot
+
+
+def set_harness_disabled(
+    root: Path,
+    disabled: bool,
+    agent: str,
+    session_file: str | Path | None = None,
+) -> dict:
+    session = ensure_session(root, session_file)
+    if disabled:
+        session["harness_disabled"] = True
+    else:
+        session.pop("harness_disabled", None)
+    session["last_agent"] = agent
+    write_session(root, session, session_file)
+    snapshot = snapshot_state(root, session_file, session)
+    snapshot["action"] = "disable-harness" if disabled else "enable-harness"
+    return snapshot
+
+
 def handoff_task(
     root: Path,
     agent: str,
@@ -881,17 +1440,21 @@ def request_transition(
         raise StateError(f"Unknown stage: {stage}")
     session, resolved_task_id, task = resolve_current_task(root, task_id, session_file)
     previous = str(task.get("status") or "idle")
+    task_type = str(task.get("type") or "")
+    confirm_mode = resolve_confirm_mode(root, session)[2]
     if previous == stage:
         raise StateError(f"Transition target must differ from current stage: {stage}")
 
-    violation = validate_transition(previous, stage)
+    violation = validate_transition(previous, stage, task_type)
     if violation:
         raise StateError(violation)
-    if previous == "MEMORY" and stage == "COMPLETE":
-        progress = task.get("memory_progress")
-        if not isinstance(progress, dict) or progress.get("completed") is not True:
-            raise StateError("MEMORY cannot advance to COMPLETE before memory processing completes.")
-
+    if is_automatic_transition(previous, stage, task_type, confirm_mode):
+        raise StateError(
+            f"Transition {previous} -> {stage} is automatic in {confirm_mode} mode; "
+            "use auto-transition instead."
+        )
+    if previous == "ANALYSIS" and stage == "IMPLEMENT":
+        validate_analysis_readiness(root, resolved_task_id)
     existing = task.get("pending_transition")
     if isinstance(existing, dict):
         if existing.get("from") != previous or existing.get("to") != stage:
@@ -926,9 +1489,18 @@ def apply_transition(
     session, resolved_task_id, task = resolve_current_task(root, task_id, session_file)
 
     previous = str(task.get("status") or "idle")
-    violation = validate_transition(previous, stage)
+    task_type = str(task.get("type") or "")
+    violation = validate_transition(previous, stage, task_type)
     if violation:
         raise StateError(violation)
+    if previous == "ANALYSIS" and stage == "IMPLEMENT":
+        validate_analysis_readiness(root, resolved_task_id)
+    if previous == "MEMORY" and stage == "COMPLETE":
+        progress = task.get("memory_progress")
+        if not isinstance(progress, dict) or progress.get("completed") is not True:
+            raise StateError("MEMORY cannot advance to COMPLETE before memory processing completes.")
+    if (previous, stage) == READ_ONLY_COMPLETION_TRANSITION:
+        validate_read_only_completion(root, resolved_task_id)
     if previous != stage:
         task["status"] = stage
         append_stage_history(task, stage, agent)
@@ -949,6 +1521,36 @@ def apply_transition(
     return snapshot_state(root, session_file, session)
 
 
+def auto_transition(
+    root: Path,
+    stage: str,
+    agent: str,
+    task_id: str | None = None,
+    session_file: str | Path | None = None,
+) -> dict:
+    session, _, task = resolve_current_task(root, task_id, session_file)
+    previous = str(task.get("status") or "idle")
+    task_type = str(task.get("type") or "")
+    confirm_mode = resolve_confirm_mode(root, session)[2]
+    if not is_automatic_transition(previous, stage, task_type, confirm_mode):
+        raise StateError(
+            f"Automatic transition is not allowed in {confirm_mode} mode: {previous} -> {stage}."
+        )
+
+    pending = task.get("pending_transition")
+    if isinstance(pending, dict) and (
+        pending.get("from") != previous or pending.get("to") != stage
+    ):
+        raise StateError(
+            "A different transition is already pending. Cancel it before automatic transition."
+        )
+
+    snapshot = apply_transition(root, stage, agent, task_id, session_file)
+    snapshot["action"] = "auto-transition"
+    snapshot["automatic_transition"] = {"from": previous, "to": stage}
+    return snapshot
+
+
 def confirm_transition(
     root: Path,
     agent: str,
@@ -956,11 +1558,13 @@ def confirm_transition(
     task_id: str | None = None,
     session_file: str | Path | None = None,
 ) -> dict:
-    _, _, task = resolve_current_task(root, task_id, session_file)
+    session, _, task = resolve_current_task(root, task_id, session_file)
     pending = task.get("pending_transition")
     if not isinstance(pending, dict):
         raise StateError("No transition is pending user confirmation.")
     previous = str(task.get("status") or "idle")
+    task_type = str(task.get("type") or "")
+    confirm_mode = resolve_confirm_mode(root, session)[2]
     source = str(pending.get("from") or "")
     target = str(pending.get("to") or "")
     if source != previous:
@@ -969,6 +1573,11 @@ def confirm_transition(
         )
     if stage and stage != target:
         raise StateError(f"Pending transition targets {target}, not {stage}.")
+    if is_automatic_transition(source, target, task_type, confirm_mode):
+        raise StateError(
+            f"Transition {source} -> {target} is automatic in {confirm_mode} mode; "
+            "use auto-transition instead."
+        )
 
     snapshot = apply_transition(root, target, agent, task_id, session_file)
     snapshot["action"] = "confirm-transition"
@@ -1191,7 +1800,9 @@ def record_seen_stage(
 
     violation = None
     if last_seen_task == task_id and last_seen_stage:
-        violation = validate_transition(str(last_seen_stage), stage)
+        task = load_task(root, task_id)
+        task_type = str(task.get("type") or "") if task else ""
+        violation = validate_transition(str(last_seen_stage), stage, task_type)
 
     if last_seen_task != task_id or last_seen_stage != stage:
         session["last_seen_task"] = task_id
@@ -1243,6 +1854,19 @@ def main() -> int:
     clear_current = subcommands.add_parser("clear-current", parents=[common])
     clear_current.add_argument("--agent", required=True)
 
+    set_confirm_mode_parser = subcommands.add_parser("set-confirm-mode", parents=[common])
+    set_confirm_mode_parser.add_argument("--mode", required=True, choices=sorted(CONFIRM_MODES))
+    set_confirm_mode_parser.add_argument("--agent", required=True)
+
+    clear_confirm_mode_parser = subcommands.add_parser("clear-confirm-mode", parents=[common])
+    clear_confirm_mode_parser.add_argument("--agent", required=True)
+
+    disable_harness_parser = subcommands.add_parser("disable-harness", parents=[common])
+    disable_harness_parser.add_argument("--agent", required=True)
+
+    enable_harness_parser = subcommands.add_parser("enable-harness", parents=[common])
+    enable_harness_parser.add_argument("--agent", required=True)
+
     handoff = subcommands.add_parser("handoff-task", parents=[common])
     handoff.add_argument("--agent", required=True)
     handoff.add_argument("--summary", required=True)
@@ -1263,6 +1887,11 @@ def main() -> int:
     confirm_transition_parser.add_argument("--agent", required=True)
     confirm_transition_parser.add_argument("--task-id")
 
+    auto_transition_parser = subcommands.add_parser("auto-transition", parents=[common])
+    auto_transition_parser.add_argument("--stage", required=True)
+    auto_transition_parser.add_argument("--agent", required=True)
+    auto_transition_parser.add_argument("--task-id")
+
     # Compatibility alias: pre-0.6 callers still consume the pending gate instead of bypassing it.
     transition = subcommands.add_parser("transition", parents=[common])
     transition.add_argument("--stage")
@@ -1342,6 +1971,42 @@ def main() -> int:
                     session_file,
                 )
             )
+        elif command == "set-confirm-mode":
+            emit(
+                attach_status_context(
+                    root,
+                    set_session_confirm_mode(root, args.mode, args.agent, session_file),
+                    args.agent,
+                    session_file,
+                )
+            )
+        elif command == "clear-confirm-mode":
+            emit(
+                attach_status_context(
+                    root,
+                    clear_session_confirm_mode(root, args.agent, session_file),
+                    args.agent,
+                    session_file,
+                )
+            )
+        elif command == "disable-harness":
+            emit(
+                attach_status_context(
+                    root,
+                    set_harness_disabled(root, True, args.agent, session_file),
+                    args.agent,
+                    session_file,
+                )
+            )
+        elif command == "enable-harness":
+            emit(
+                attach_status_context(
+                    root,
+                    set_harness_disabled(root, False, args.agent, session_file),
+                    args.agent,
+                    session_file,
+                )
+            )
         elif command == "handoff-task":
             emit(
                 attach_status_context(
@@ -1385,6 +2050,15 @@ def main() -> int:
                     session_file,
                 )
             )
+        elif command == "auto-transition":
+            emit(
+                attach_status_context(
+                    root,
+                    auto_transition(root, args.stage, args.agent, args.task_id, session_file),
+                    args.agent,
+                    session_file,
+                )
+            )
         elif command == "cancel-transition":
             emit(
                 attach_status_context(