@surlymochan/evalid 0.0.0-stage → 0.3.1

package/xflow/scripts/doctor.py

@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+sys.path.append(str(Path(__file__).resolve().parent))
+
+from common import (  # noqa: E402
+    find_git_root,
+    get_current_branch,
+    get_remote_url,
+    gh_json,
+    load_status,
+    remote_branch_exists,
+    resolve_project_context,
+)
+
+
+def extract_repo_from_remote_url(remote_url: str) -> str | None:
+    import re
+
+    match = re.search(r"github\.com[:/](?P<repo>[^/]+/[^/.]+?)(?:\.git)?$", remote_url.strip(), flags=re.IGNORECASE)
+    if not match:
+        return None
+    return str(match.group("repo"))
+
+
+def check(name: str, ok: bool, detail: str, *, value: Any | None = None, severity: str = "error") -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "name": name,
+        "ok": ok,
+        "detail": detail,
+        "severity": severity,
+    }
+    if value is not None:
+        payload["value"] = value
+    return payload
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Validate Superflow repo / remote / issue / branch / project / status.json consistency.")
+    parser.add_argument("--project-root", default=".", help="Project root containing specs/changes.")
+    parser.add_argument("--change-id", required=True, help="Superflow change id.")
+    parser.add_argument("--repo", help="Override target repo from status.json.")
+    parser.add_argument("--issue-number", type=int, help="Override issue number from status.json.")
+    parser.add_argument("--branch-name", help="Override linked branch from status.json.")
+    parser.add_argument("--checkout-path", help="Override checkout path from status.json.")
+    parser.add_argument("--json", action="store_true", help="Print machine-readable JSON output.")
+    return parser.parse_args()
+
+
+def issue_branch_comment_present(repo: str, issue_number: int, branch_name: str) -> bool:
+    marker = "<!-- xflow:branch-link -->"
+    try:
+        comments = gh_json(["api", f"repos/{repo}/issues/{issue_number}/comments"])
+    except subprocess.CalledProcessError:
+        return False
+    for comment in comments:
+        body = comment.get("body") or ""
+        if marker in body and f"`{branch_name}`" in body:
+            return True
+    return False
+
+
+def run_doctor_checks(
+    *,
+    project_root: str | Path,
+    change_id: str,
+    repo: str | None = None,
+    issue_number: int | None = None,
+    branch_name: str | None = None,
+    checkout_path_override: str | Path | None = None,
+) -> dict[str, Any]:
+    status_path, status = load_status(project_root, change_id)
+
+    repo = repo or status.get("issue_repo") or status.get("target_repo")
+    issue_number = issue_number or status.get("issue_number")
+    branch_name = branch_name or status.get("branch_name")
+    checkout_path_value = str(checkout_path_override) if checkout_path_override else status.get("checkout_path")
+    code_repo = status.get("code_repo")
+    checkout_path = None
+    checks: list[dict[str, Any]] = []
+
+    checks.append(
+        check(
+            "status-file",
+            status_path.exists(),
+            f"Loaded status file {status_path}" if status_path.exists() else f"Missing status file {status_path}",
+            value=str(status_path),
+        )
+    )
+    checks.append(check("status-issue-repo", bool(repo), "issue_repo is present" if repo else "issue_repo missing from status.json"))
+    checks.append(check("status-issue-number", bool(issue_number), "issue_number is present" if issue_number else "issue_number missing from status.json"))
+    checks.append(check("status-branch-name", bool(branch_name), "branch_name is present" if branch_name else "branch_name missing from status.json"))
+    checks.append(check("status-code-repo", bool(code_repo), "code_repo is present" if code_repo else "code_repo missing from status.json", value=code_repo, severity="warn"))
+    checks.append(
+        check(
+            "status-checkout-path",
+            bool(checkout_path_value),
+            "checkout_path is present" if checkout_path_value else "checkout_path missing from status.json",
+            value=checkout_path_value,
+        )
+    )
+
+    if checkout_path_value:
+        try:
+            checkout_path = Path(checkout_path_value).expanduser().resolve()
+            checks.append(check("checkout-resolve", True, f"Resolved checkout {checkout_path}", value=str(checkout_path)))
+        except Exception as exc:
+            checks.append(check("checkout-resolve", False, f"Unable to resolve checkout path: {exc}", severity="error"))
+    else:
+        try:
+            checkout_path = find_git_root(project_root)
+            checks.append(check("checkout-resolve", True, f"Resolved checkout {checkout_path} from project root", value=str(checkout_path)))
+        except subprocess.CalledProcessError as exc:
+            checks.append(check("checkout-resolve", False, f"Unable to resolve checkout from project root: {exc}", severity="error"))
+
+    checkout_remote_url = None
+    checkout_repo = None
+    if checkout_path:
+        try:
+            checkout_remote_url = get_remote_url(checkout_path)
+            checkout_repo = extract_repo_from_remote_url(checkout_remote_url)
+            checks.append(check("checkout-remote", True, "Resolved checkout remote", value={"remote_url": checkout_remote_url, "checkout_repo": checkout_repo}))
+        except subprocess.CalledProcessError as exc:
+            checks.append(check("checkout-remote", False, f"Unable to resolve checkout remote: {exc}", severity="error"))
+
+    if code_repo and checkout_repo:
+        checks.append(
+            check(
+                "checkout-code-repo-match",
+                code_repo == checkout_repo,
+                "checkout remote matches recorded code_repo" if code_repo == checkout_repo else "checkout remote differs from recorded code_repo",
+                value={"recorded_code_repo": code_repo, "checkout_repo": checkout_repo},
+            )
+        )
+
+    current_branch = None
+    if checkout_path:
+        try:
+            current_branch = get_current_branch(checkout_path)
+            checks.append(check("current-branch", True, "Current branch resolved", value=current_branch))
+        except subprocess.CalledProcessError as exc:
+            checks.append(check("current-branch", False, f"Unable to resolve current branch: {exc}", severity="error"))
+
+    if branch_name and checkout_path:
+        linked_branch_exists = bool(current_branch == branch_name or remote_branch_exists(checkout_path, branch_name))
+        checks.append(
+            check(
+                "linked-branch-local-or-remote",
+                linked_branch_exists,
+                f"Linked branch {branch_name} exists locally or on origin" if linked_branch_exists else f"Linked branch {branch_name} not found locally or on origin",
+                value=branch_name,
+            )
+        )
+        if current_branch is not None:
+            checks.append(
+                check(
+                    "linked-branch-current-match",
+                    current_branch == branch_name,
+                    f"Current branch matches linked branch {branch_name}" if current_branch == branch_name else f"Current branch {current_branch} differs from linked branch {branch_name}",
+                    value={"current_branch": current_branch, "linked_branch": branch_name},
+                )
+            )
+        checks.append(
+            check(
+                "branch-worktree-ready",
+                linked_branch_exists and current_branch == branch_name,
+                "Linked branch is available and the current checkout matches it"
+                if (linked_branch_exists and current_branch == branch_name)
+                else f"Linked branch/worktree is not ready: current={current_branch}, linked={branch_name}",
+                value={
+                    "current_branch": current_branch,
+                    "linked_branch": branch_name,
+                    "checkout_path": str(checkout_path),
+                },
+            )
+        )
+
+    issue_data = None
+    if repo and issue_number:
+        try:
+            issue_data = gh_json(
+                [
+                    "issue",
+                    "view",
+                    str(issue_number),
+                    "--repo",
+                    repo,
+                    "--json",
+                    "number,title,url,state,projectItems",
+                ]
+            )
+            checks.append(check("issue-exists", True, f"Issue {repo}#{issue_number} exists", value={"url": issue_data.get("url"), "state": issue_data.get("state")}))
+        except subprocess.CalledProcessError as exc:
+            checks.append(check("issue-exists", False, f"Unable to resolve issue {repo}#{issue_number}: {exc}", severity="error"))
+
+    if repo and issue_number and branch_name:
+        has_branch_comment = issue_branch_comment_present(repo, int(issue_number), branch_name)
+        checks.append(
+            check(
+                "issue-branch-comment-link",
+                has_branch_comment,
+                "Found Superflow branch-link comment on issue" if has_branch_comment else "Missing Superflow branch-link comment on issue",
+                value=branch_name,
+                severity="warn",
+            )
+        )
+
+    project_context = None
+    if repo and issue_number:
+        project_context = resolve_project_context(repo, int(issue_number))
+        checks.append(
+            check(
+                "project-context",
+                project_context is not None,
+                f"Resolved project context {project_context['owner']}#{project_context['number']}" if project_context else "No unique project context discovered from issue",
+                value=project_context,
+                severity="warn",
+            )
+        )
+
+    recorded_project = status.get("project_status") or status.get("project_done") or status.get("project_context")
+    if recorded_project and project_context:
+        same_owner = recorded_project.get("owner") == project_context.get("owner")
+        same_number = int(recorded_project.get("number")) == int(project_context.get("number"))
+        checks.append(
+            check(
+                "project-record-match",
+                same_owner and same_number,
+                "Recorded project context matches discovered project context" if (same_owner and same_number) else "Recorded project context differs from discovered project context",
+                value={"recorded": recorded_project, "discovered": project_context},
+                severity="warn",
+            )
+        )
+
+    ok = all(item["ok"] or item["severity"] == "warn" for item in checks)
+    hard_failures = [item for item in checks if (not item["ok"] and item["severity"] != "warn")]
+    warnings = [item for item in checks if (not item["ok"] and item["severity"] == "warn")]
+
+    result = {
+        "change_id": change_id,
+        "ok": ok,
+        "hard_failures": len(hard_failures),
+        "warnings": len(warnings),
+        "checks": checks,
+    }
+    return result
+
+
+def main() -> int:
+    args = parse_args()
+    result = run_doctor_checks(
+        project_root=args.project_root,
+        change_id=args.change_id,
+        repo=args.repo,
+        issue_number=args.issue_number,
+        branch_name=args.branch_name,
+        checkout_path_override=args.checkout_path,
+    )
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"Superflow doctor: {args.change_id}")
+        print(f"Overall: {'OK' if result['ok'] else 'FAIL'}")
+        for item in result["checks"]:
+            icon = "PASS" if item["ok"] else ("WARN" if item["severity"] == "warn" else "FAIL")
+            print(f"- [{icon}] {item['name']}: {item['detail']}")
+
+    return 0 if result["ok"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/xflow/scripts/sync_installed_xflow_skill.sh

@@ -0,0 +1,134 @@
+#!/bin/sh
+# Sync the repo-owned xflow skill into installed skill dirs without pruning
+# skills that are managed by companion repositories.
+
+set -eu
+
+SCRIPT_PATH=$0
+case "$SCRIPT_PATH" in
+  /*) ;;
+  *) SCRIPT_PATH=$(pwd)/$SCRIPT_PATH ;;
+esac
+
+SCRIPT_DIR=$(cd "$(dirname "$SCRIPT_PATH")" && pwd)
+PROJECT_ROOT=$(cd "$SCRIPT_DIR/../.." && pwd)
+
+config_value() {
+  key_path=$1
+  node -e '
+const fs = require("fs");
+const path = require("path");
+const root = process.argv[1];
+const keyPath = process.argv[2].split(".");
+const configPath = path.join(root, ".as-xflow", "config.json");
+if (!fs.existsSync(configPath)) process.exit(0);
+const expandHome = (value) => typeof value === "string" && value.startsWith("~/")
+  ? path.join(process.env.HOME || "", value.slice(2))
+  : value;
+let value = JSON.parse(fs.readFileSync(configPath, "utf8"));
+for (const key of keyPath) value = value && value[key];
+if (Array.isArray(value)) console.log(value.map(expandHome).join("\n"));
+else if (value) console.log(expandHome(value));
+' "$PROJECT_ROOT" "$key_path"
+}
+
+CONFIG_SYNC_SCRIPT=$(config_value skills.sync_script)
+CONFIG_EXTRA_SOURCE_DIRS=$(config_value skills.extra_source_dirs)
+CONFIG_TARGET_DIRS=$(config_value skills.installed_dir)
+
+default_target_dirs() {
+  if [ -d "$HOME/.codex/skills" ]; then
+    printf '%s\n' "$HOME/.codex/skills"
+    return 0
+  fi
+
+  printf '%s\n' "$HOME/.agents/skills"
+}
+
+SYNC_SCRIPT=${XFLOW_SKILL_SYNC_SCRIPT:-${SKILLHUB_SYNC_SCRIPT:-${CONFIG_SYNC_SCRIPT:-$HOME/Documents/workspace/pro/as-skillhub/skills/skills_sync.sh}}}
+EXTRA_SOURCE_DIRS=${XFLOW_SKILL_SYNC_EXTRA_SOURCE_DIRS:-${SKILL_SYNC_EXTRA_SOURCE_DIRS:-${CONFIG_EXTRA_SOURCE_DIRS:-$HOME/Documents/workspace/pro/as-skillhub/skills}}}
+TARGET_DIRS=${SKILL_SYNC_TARGET_DIRS:-${CONFIG_TARGET_DIRS:-$(default_target_dirs)}}
+DEFAULT_XMEM_SOURCE_DIR=$(cd "$PROJECT_ROOT/../as-xmem" 2>/dev/null && pwd || true)
+XMEM_SOURCE_DIR=${XFLOW_XMEM_SOURCE_DIR:-$DEFAULT_XMEM_SOURCE_DIR}
+
+if [ ! -f "$SYNC_SCRIPT" ]; then
+  printf 'sync_installed_xflow_skill.sh: missing skills sync script: %s\n' "$SYNC_SCRIPT" >&2
+  exit 1
+fi
+
+if [ ! -d "$PROJECT_ROOT/xflow" ]; then
+  printf 'sync_installed_xflow_skill.sh: missing source xflow dir: %s\n' "$PROJECT_ROOT/xflow" >&2
+  exit 1
+fi
+
+extra_source_found=$(mktemp)
+printf '%s\n' "$EXTRA_SOURCE_DIRS" | while IFS= read -r source_dir; do
+  [ -n "$source_dir" ] || continue
+  [ -d "$source_dir" ] || continue
+  printf 'yes\n' >"$extra_source_found"
+done
+
+if [ ! -s "$extra_source_found" ]; then
+  rm -f "$extra_source_found"
+  printf 'sync_installed_xflow_skill.sh: no extra source dir exists in:\n%s\n' "$EXTRA_SOURCE_DIRS" >&2
+  printf 'Set XFLOW_SKILL_SYNC_EXTRA_SOURCE_DIRS or SKILL_SYNC_EXTRA_SOURCE_DIRS to the as-skillhub skills dir.\n' >&2
+  exit 1
+fi
+rm -f "$extra_source_found"
+
+SKILLHUB="$PROJECT_ROOT" \
+SKILL_SYNC_EXTRA_SOURCE_DIRS="$EXTRA_SOURCE_DIRS" \
+SKILL_SYNC_TARGET_DIRS="$TARGET_DIRS" \
+  sh "$SYNC_SCRIPT" xflow
+
+install_xmem_skill_family() {
+  [ -n "$XMEM_SOURCE_DIR" ] || return 0
+  [ -d "$XMEM_SOURCE_DIR" ] || return 0
+  [ -f "$XMEM_SOURCE_DIR/skill.md" ] || return 0
+
+  printf '%s\n' "$TARGET_DIRS" | while IFS= read -r target_dir; do
+    [ -n "$target_dir" ] || continue
+    target_xmem=$target_dir/xmem
+
+    rm -rf "$target_xmem"
+    cp -RL "$XMEM_SOURCE_DIR" "$target_xmem"
+    rm -f "$target_xmem/.xmem-root-skill.tmp"
+    mv "$target_xmem/skill.md" "$target_xmem/.xmem-root-skill.tmp"
+    mv "$target_xmem/.xmem-root-skill.tmp" "$target_xmem/SKILL.md"
+    rm -f "$target_xmem/.skillhub-source"
+    printf '%s\n' "$XMEM_SOURCE_DIR" >"$target_xmem/.xflow-source"
+
+    find "$target_xmem" -type d -name '__pycache__' -prune -exec rm -rf {} +
+    find "$target_xmem" -type f -name '*.pyc' -delete
+    printf 'verified xmem skill sync target: %s\n' "$target_xmem"
+  done
+}
+
+install_xmem_skill_family
+
+printf '%s\n' "$TARGET_DIRS" | while IFS= read -r target_dir; do
+  [ -n "$target_dir" ] || continue
+  target_xflow=$target_dir/xflow
+
+  if [ ! -d "$target_xflow" ]; then
+    printf 'sync_installed_xflow_skill.sh: target xflow dir missing after sync: %s\n' "$target_xflow" >&2
+    exit 1
+  fi
+
+  find "$target_xflow" -type d -name '__pycache__' -prune -exec rm -rf {} +
+  find "$target_xflow" -type f -name '*.pyc' -delete
+
+  diff_file=$(mktemp)
+  filtered_file=$(mktemp)
+  diff -qr "$PROJECT_ROOT/xflow" "$target_xflow" >"$diff_file" 2>&1 || true
+  grep -v -E 'Only in .*/xflow: \.skillhub-source$|__pycache__|\.pyc$' "$diff_file" >"$filtered_file" || true
+
+  if [ -s "$filtered_file" ]; then
+    cat "$filtered_file" >&2
+    rm -f "$diff_file" "$filtered_file"
+    exit 1
+  fi
+
+  rm -f "$diff_file" "$filtered_file"
+  printf 'verified xflow skill sync target: %s\n' "$target_xflow"
+done

package/xflow/takein/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: xflow:takein
+description: 通过读取项目根目录的规范 `HANDOFF.md`，提取当前目标、进展、阻塞、经验和下一步动作，并在执行前完成一次轻量级仓库状态摄入，从而在新线程中接手工作。适用于用户要求在新线程继续、接管项目、根据 handoff 衔接、恢复上次会话，或从 `HANDOFF.md` 启动上下文时。
+---
+
+# Superflow Takein
+
+This skill is for new-thread takeover.
+
+Your primary source of truth is:
+
+- project root `.xflow/GOAL.md` (if present)
+- project root `HANDOFF.md`
+- project root `AHA.md`
+- project root `DESIGN.md` (if frontend project)
+
+Do not start by reading a large random slice of the repository.
+Start from `HANDOFF.md`, then validate only the minimum additional context needed to begin the task safely.
+
+## Goal
+
+Build a correct working context for the new thread fast enough to act, without redoing full-project discovery.
+
+## Required Intake Output
+
+Before substantial implementation work, produce an intake summary covering:
+
+1. project background
+2. architecture and invariants
+3. current objective
+4. verified progress
+5. blockers / risks / open problems
+6. lessons learned / operational gotchas
+7. recommended first action in this thread
+
+If `HANDOFF.md` is missing or stale, say so explicitly and repair the situation instead of pretending the context is complete.
+
+## Workflow
+
+1. Read project root `.xflow/GOAL.md` if present.
+2. Read project root `HANDOFF.md`.
+3. Read project root `AHA.md` if present.
+4. Read project root `DESIGN.md` if present (frontend projects).
+5. Extract the current objective, verified state, blockers, recommendations, and any active constraints.
+6. Run a lightweight repo-state check:
+   - `git status -sb`
+   - `npm run drift:scan` when the project exposes it; for evalid this is required before substantial implementation
+   - inspect directly relevant files only
+7. Compare current repo reality against `.xflow/GOAL.md`, `HANDOFF.md`, `AHA.md`, and `DESIGN.md`.
+8. Call out any mismatch between goal, handoff, aha log, design decisions, and repo state.
+9. State the first concrete action you will take next.
+10. Then proceed with execution.
+
+## Scope Control
+
+Keep intake tight.
+
+- do not re-read the entire codebase unless the handoff is clearly insufficient
+- do not expand into open-ended architecture exploration unless blocked
+- do not overwrite `HANDOFF.md` during takein unless the user asks, or the file is clearly dangerously stale
+
+## Guardrails
+
+- treat `HANDOFF.md` as canonical until contradicted by repo evidence
+- treat `AHA.md` as canonical for durable discussion insights until contradicted by repo evidence
+- prefer verified repo truth over stale handoff claims
+- distinguish verified facts from assumptions
+- surface drift immediately if handoff and code disagree
+- surface drift immediately if current design or implementation conflicts with a recorded aha
+- always end intake with a recommended first action
+
+## Script
+
+The agent autonomously calls this helper to generate intake digest:
+
+```bash
+python3 ~/.codex/skills/xflow/takein/scripts/takein_digest.py --project-root .
+```
+
+Agent uses digest as starting point, then validates repo reality.
+User invokes skill, agent handles execution.

package/xflow/takein/scripts/takein_digest.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+import argparse
+from pathlib import Path
+
+
+SECTION_HEADERS = [
+    "Current State",
+    "Context Pack",
+    "Project Background",
+    "Architecture",
+    "Current Objective",
+    "Progress",
+    "Open Problems",
+    "Lessons Learned",
+    "Recommendations",
+    "Key Files",
+]
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Extract a compact digest from the canonical root HANDOFF.md and AHA.md.",
+    )
+    parser.add_argument(
+        "--project-root",
+        default=".",
+        help="Project root containing HANDOFF.md and optional AHA.md.",
+    )
+    return parser.parse_args()
+
+
+def extract_sections(text: str) -> list[tuple[str, list[str]]]:
+    sections: list[tuple[str, list[str]]] = []
+    current_name = "Preamble"
+    current_lines: list[str] = []
+
+    for line in text.splitlines():
+        if line.startswith("## "):
+            sections.append((current_name, current_lines))
+            current_name = line[3:].strip()
+            current_lines = []
+            continue
+        current_lines.append(line)
+
+    sections.append((current_name, current_lines))
+    return sections
+
+
+def first_content_lines(lines: list[str], limit: int = 3) -> list[str]:
+    content = [line.strip() for line in lines if line.strip()]
+    return content[:limit]
+
+
+def main() -> int:
+    args = parse_args()
+    project_root = Path(args.project_root).expanduser().resolve()
+    handoff_path = project_root / "HANDOFF.md"
+    aha_path = project_root / "AHA.md"
+    if not handoff_path.exists():
+      raise SystemExit(f"Missing canonical handoff: {handoff_path}")
+
+    text = handoff_path.read_text(encoding="utf-8")
+    sections = dict(extract_sections(text))
+
+    print(f"HANDOFF: {handoff_path}")
+    for name in SECTION_HEADERS:
+        lines = sections.get(name)
+        if not lines:
+            continue
+        digest = first_content_lines(lines)
+        if not digest:
+            continue
+        print(f"\n[{name}]")
+        for line in digest:
+            print(line)
+
+    if aha_path.exists():
+        aha_lines = [line.strip() for line in aha_path.read_text(encoding="utf-8").splitlines() if line.strip()]
+        digest = aha_lines[:12]
+        if digest:
+            print(f"\n[AHA] {aha_path}")
+            for line in digest:
+                print(line)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/xflow/yolo/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: xflow:yolo
+description: "轻量轨交付工作流：从 change-init 到 archive。适用于后端、文档、基础设施和小型 UI 改动。可复用 xflow:plan 产物，或在缺少 plan 时先补一轮通用规划。"
+---
+
+# Superflow Yolo — Track Execution Driver
+
+This skill drives the lite workflow. It does not own a separate planning
+track; planning is shared with `xflow:plan`.
+
+## How to run
+
+```bash
+xflow workflow validate workflows/yolo.yaml
+```
+
+Then execute the workflow phases in order.
+
+For a full run:
+
+```bash
+xflow workflow run workflows/yolo.yaml --title "<中文标题>" --change-type backend
+```
+
+## Plan reuse rule
+
+- Read `.xflow/GOAL.md` before execution when present. State whether the current
+  change aligns with it, intentionally narrows it, or conflicts with it.
+- Reuse `specs/changes/${CHANGE_ID}/plan.md` when it is current.
+- If the plan is missing or still a scaffold placeholder, create it once before continuing.
+- Planning stays track-neutral; do not decide yolo vs corps here.
+
+## State and context
+
+- Project root: `process.env.XFLOW_PROJECT_ROOT || cwd`
+- Project goal: `.xflow/GOAL.md` when present; use it as direction context only
+- Change root: `specs/changes/${CHANGE_ID}/`
+- Status file: `specs/changes/${CHANGE_ID}/status.json`
+
+## Phase playbook
+
+1. `change-init`
+2. `brainstorm`
+3. `design-check` if the change is frontend/UI
+4. `proposal-freeze`
+5. `proposal-consistency-check`
+6. `plan`
+7. `openissue`
+8. `set-in-progress`
+9. `tdd`
+10. `execute`
+11. `verify-consistency`
+12. `archive`
+
+The workflow YAML is the canonical execution source for atom order, gates, and
+artifact checks. This skill only explains the contract.
+
+## Guardrails
+
+- Keep the plan reusable and track-neutral
+- Do not introduce a separate tasks artifact
+- Do not re-plan if a current `plan.md` already exists
+- Do not treat `.xflow/GOAL.md` as executable scope; it is alignment context
+  that must be reflected in the final verification summary
+- Do not enter `set-in-progress` or `execute` unless doctor confirms the linked branch and checkout are ready
+- Do not expose deleted top-level xflow utility skills as entry points