@surlymochan/evalid 0.0.0-stage → 0.4.1

package/xflow/corps/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: xflow:corps
+description: "重型多 agent 全产品交付工作流。适用于复杂用户界面、设计闭环和多 agent 协作。可复用 xflow:plan 产物，或在缺少 plan 时先补一轮通用规划。"
+---
+
+# Superflow Corps
+
+`xflow:corps` is the heavy execution track. Planning is shared with
+`xflow:plan` and is not track-specific.
+
+## Single entry rule
+
+- Execute through `xflow corps --title "<title>" --change-type frontend --change-id <id>`.
+- Use `xflow corps --explain` before a first run when the operator needs the
+  compressed guide, proof contract, competitor-led inputs, and failure meanings.
+- Do not manually simulate the heavy workflow in chat, by ad hoc shell steps, or by treating partial file checks as completion.
+- `xflow workflow validate corps` is preflight only. It proves YAML shape, not workflow execution.
+- Completion requires `specs/changes/${CHANGE_ID}/corps_proof.json` with `ok=true`.
+- `corps_proof.json` must be backed by the built-in governed corps manifest, hash-linked execution-log records, `workflow_started`/`workflow_completed`, `phase_started`/`phase_completed` for every canonical phase, successful atom/gate witnesses, and zero `stub`, `task_queued`, or `pencil_stubbed` runtime fallback.
+- Project-local workflow config may customize normal workflow aliases, but the governed `xflow corps` entry and `xflow proof --track corps` use the built-in corps workflow so the heavy path cannot be shortened through config.
+- Heavy agent work must be issued by the workflow runtime/control plane and its `agent_invoke` task packages; the conversation AI should not improvise a parallel private workflow.
+- The conversation AI represents the human operator: clarify requirements before execution, let the governed `corps` entry auto-approve scripted human gates, and inspect final proof before accepting success.
+
+## Plan reuse rule
+
+- Read project root `.xflow/GOAL.md` when present and use it as direction
+  context only. Before executing, state how the product contract aligns with,
+  narrows, or intentionally diverges from the project goal.
+- 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 re-run it just because the workflow is heavy-track.
+
+## Optional long-run notes
+
+For research-heavy or long-running changes, keep optional `findings.md` and
+`progress.md` alongside the plan when they help the team stay aligned.
+These notes are auxiliary; they do not replace `plan.md`.
+If the change also affects workflow semantics, add a `merge-workflow.md`
+stub with an explicit capability delta section.
+
+## When to use corps
+
+- New user-facing screen or interaction pattern
+- Visual quality matters and needs Pencil + multimodal review
+- Multiple agents should propose or critique
+- The risk or scope requires formal sign-off
+
+## Execution contract
+
+The heavy workflow runs the same phase family as yolo, but with the full design
+loop and heavy-track gates. The workflow YAML is the canonical source for atom
+order and gates. The CLI entry owns the execution and proof boundary.
+
+## Guardrails
+
+- Keep planning track-neutral
+- Reuse an existing plan when present
+- Include goal alignment in the final proof review: `corps_proof.json ok=true`
+  is necessary, but the operator still has to check whether the proof satisfies
+  the project direction anchor.
+- Confirm the linked branch and checkout are ready before moving into execution
+- Do not expose deleted top-level utility skills as separate entry points
+- For competitor-led UI work, freeze the competitor reconstruction contract before execution:
+  - corps entry should treat competitor-led UI as strict mode by default, not as a best-effort hint: once competitor-led signals are present, benchmark evidence becomes mandatory before execution continues
+  - name the competitor product and target surfaces explicitly
+  - lock exactly one `primary_reference_surface`; supporting surfaces may refine but must not replace the primary anchor
+  - map the required modules and IA, not just one visible page slice
+  - record business-logic invariants that must not be violated
+  - require exactly one benchmark evidence path for `H6.visual.benchmark`:
+    - `reference_scenarios_json`, or
+    - `capture_url + reference_image`
+  - before visual generation, freeze the structured reconstruction artifacts:
+    - `reference_surface_lock.json`
+    - `reconstruction_pack.json`
+    - `generation_contract.json`
+    - `design_system_pack.json`
+  - treat those artifacts as generation-time instructions, not just review evidence:
+    - `reconstruction_pack.json` should expose page-local `component_blueprint` primitives and a `relationship_graph`
+    - `generation_contract.json` should expose staged component generation (`shell`, `primary_focus`, `secondary_focus`, `polish`) plus `geometry_hints` / `token_hints`
+    - `pencil_draft` should build by stage, not by whole-page freeform redraw
+    - `benchmark_repair_plan.json` should downshift unresolved evidence into component-local `repair_targets`
+    - `pencil_refine` should preserve non-target components by default and only modify named repair targets
+    - `generation_contract.json` should include `visual_constraints.aesthetic_standard`, `image_reference_generation`, and `pencil_role_boundary`
+    - `design_system_pack.json` should compile commercial/open UI generation practices into generic constraints: React/component-system stack defaults, component whitelist, required states, token policy, local preview/refine loop, and structured UI generation rules
+    - `image_reference_set.json` must materialize the required image-reference outputs (`primary_surface_reference_frame`, `component_density_sheet`, `state_polish_sheet`) and every listed reference must point to an existing artifact
+    - Pencil is the editable assembly/refinement layer, not the sole high-aesthetic engine; when the host has GPT/imagev2-style image generation available, use it to produce reference frames and component/state sheets, then translate those into editable UI and benchmark evidence
+    - `H6d.visual.aesthetic_review` must accept the final recheck before design acceptance: high aesthetic contract present, design-system practice pack materialized, image reference artifacts materialized, Pencil boundary explicit, benchmark scenarios passing, and score at or above threshold
+  - when fidelity needs to reach commercial-grade polish, add `visual_token_contract` and `observed_visual_tokens` so benchmark can emit deterministic `token_checks`
+  - prefer token contracts that cover typography rhythm and surface treatment, not only font family and color: `line_height_range`, `letter_spacing_range`, `border_width_range`, `border_styles_required`, `shadow_signatures_required`
+  - when the competitor surface depends on interaction states, pass `capture_states_json` on the `capture_url + reference_image` path so benchmark captures hover/open/selected variants instead of only the base frame
+  - when the workbench has key semantic states such as detail-open, active-filter, selected-item, or bulk-select, add `state_contract.required_workbench_states` so benchmark emits deterministic `state_contract_checks` instead of treating all captured states as equally important
+  - when dense commercial UI matters, include icon and surface-depth tokens such as `icon_density_range`, `icon_size_range`, `border_weight_tiers_required`, and `shadow_strength_tiers_required`
+- for iOS / Android / H5 surfaces, do not reuse desktop-only acceptance by habit: add mobile-oriented checks such as `min_touch_target_size` and mobile workspace patterns like `compact_top_nav`, `bottom_tabbar_docked`, or `bottom_sheet_over_content`
+- for iOS / Android / H5 surfaces, also add mobile-native hard gates when relevant: `safe_area_top_panels`, `safe_area_bottom_panels`, `keyboard_aware_panels`, `thumb_reach_primary_action_panels`, `bottom_sheet_handle_required`, and `tabbar_active_state_required`
+- for iOS / Android / H5 surfaces, keep going past layout: add mobile component signals such as `floating_primary_action_required` and `segmented_control_active_state_required`, and sample gesture states with `swipe_selector`, `drag_selector`, or `scroll_selector` when the target interaction depends on motion rather than static chrome
+- when the target fidelity depends on motion or platform transitions, do not stop at one end-state screenshot: add `expect_motion`, `sample_frames`, and `frame_interval_ms`, and use `benchmark_matrix_contract` / `viewport_variants_json` when the product needs multiple viewport baselines to count as “close enough”
+  - when the goal is platform-native feel, add `required_platform_physics_profiles` such as `ios_spring`, `android_ripple`, or `mobile_h5_smooth` so benchmark checks motion language instead of only final pixels
+  - when polish depends on same-family components staying visually consistent, add `component_family_consistency` checks for families such as `toolbar_controls`, `list_rows`, and `detail_blocks` instead of only checking global min/max ranges
+  - when polish depends on interaction states using the same motion/contrast language, add `state_family_contract` so benchmark checks variant coverage and spread within families like `toolbar_controls`
+  - when those state families also need token-level consistency, include `state_visual_tokens` or rely on the `capture_url` path so benchmark can enforce token rules such as surface-color distinctness, shadow-tier distinctness, timing-function coverage, transition-duration spread, radius spread, and border-width spread across variants
+  - let `capture_url` auto-detect semantic product states like `loading_state`, `skeleton_state`, `error_state`, and `search_active` instead of silently skipping them from the proof bundle
+  - when the surface has many interactive affordances, `auto_discover_states` can be used as a first-pass fallback to capture likely hover/click states without hand-authoring every selector
+  - when visual rhythm matters, prefer adding `alignment_grid_step` / `alignment_grid_tolerance` so benchmark checks that major panels stay on a shared grid instead of only matching approximate widths
+  - treat `xflow visual capture-page-evidence` as the helper entrypoint when pre-capturing screenshot, DOM snapshot, and `dom_rects` outside the phase
+  - use `xflow visual render-report` or the benchmark-generated `visual_benchmark_report.html` when reviewers need a side-by-side compare viewer instead of raw JSON
+  - unresolved benchmark evidence should converge through the scripted repair loop: advisory `llm_design_review` -> `benchmark_repair_plan.json` -> `pencil_refine` -> strict `llm_design_recheck`
+  - reject "looks similar" acceptance without primary journey and cross-module proof
+- Keep the pipeline generic: corps validates named competitors, product surfaces, journeys, and invariants, but it must not bake in any single business domain or product model.
+- Domain rules belong in the current change contract, not in the workflow itself. A todo/GTD rule, trading rule, CRM rule, or editor rule should be expressed through `business_logic_invariants` for that change.

package/xflow/exec/scripts/set_issue_in_progress.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.append(str(Path(__file__).resolve().parents[2] / "scripts"))
+
+from doctor import run_doctor_checks  # noqa: E402
+from common import (  # noqa: E402
+    assert_status_transition_allowed,
+    assert_stage_transition_allowed,
+    ensure_branch_checked_out,
+    find_git_root,
+    get_current_branch,
+    get_remote_url,
+    load_status,
+    maybe_relative,
+    record_stage_transition,
+    record_value_transition,
+    resolve_project_context,
+    save_status,
+    set_project_single_select_status,
+    upsert_issue_comment,
+)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Move a Superflow issue into In Progress and sync status metadata.")
+    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 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 branch name from status.json.")
+    parser.add_argument("--checkout-path", help="Override checkout path from status.json.")
+    parser.add_argument("--project-owner", help="GitHub project owner login for project status updates.")
+    parser.add_argument("--project-number", type=int, help="GitHub project number for project status updates.")
+    parser.add_argument("--status-field-name", default="Status", help="Project single select field name.")
+    parser.add_argument("--target-status", default="In Progress", help="Project status option to apply.")
+    parser.add_argument("--skip-doctor-precheck", action="store_true", help="Skip the automatic doctor precheck before state transition.")
+    parser.add_argument("--skip-doctor-postcheck", action="store_true", help="Skip the automatic doctor postcheck after state transition.")
+    parser.add_argument("--json", action="store_true", help="Print machine-readable JSON output.")
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    status_path, status = load_status(args.project_root, args.change_id)
+
+    repo = args.repo or status.get("issue_repo") or status.get("target_repo")
+    issue_number = args.issue_number or status.get("issue_number")
+    branch_name = args.branch_name or status.get("branch_name")
+    checkout_path = Path(args.checkout_path or status.get("checkout_path") or find_git_root(args.project_root))
+    assert_stage_transition_allowed(status.get("current_stage"), "tdd", current_status=status.get("status"))
+    assert_status_transition_allowed(status.get("status"), "active")
+
+    if not repo or not issue_number or not branch_name:
+        raise SystemExit("status.json must include target_repo, issue_number, and branch_name or they must be passed explicitly.")
+
+    if not args.skip_doctor_precheck:
+        pre_result = run_doctor_checks(
+            project_root=args.project_root,
+            change_id=args.change_id,
+            repo=repo,
+            issue_number=int(issue_number),
+            branch_name=branch_name,
+            checkout_path_override=checkout_path,
+        )
+        if not pre_result["ok"]:
+            raise SystemExit("Doctor precheck failed before exec state transition. Run doctor.py for details.")
+
+    remote_url = get_remote_url(checkout_path)
+    ensure_branch_checked_out(checkout_path, branch_name)
+    current_branch = get_current_branch(checkout_path)
+    if current_branch != branch_name:
+        raise SystemExit(
+            f"Execution branch mismatch: current branch is {current_branch!r}, expected linked issue branch {branch_name!r}."
+        )
+
+    project_context = resolve_project_context(repo, int(issue_number), args.project_owner, args.project_number)
+    project_result = None
+    if project_context:
+        project_result = set_project_single_select_status(
+            project_context["owner"],
+            int(project_context["number"]),
+            args.status_field_name,
+            args.target_status,
+            repo,
+            int(issue_number),
+        )
+    else:
+        marker = "<!-- xflow:exec-state -->"
+        upsert_issue_comment(
+            repo,
+            int(issue_number),
+            marker,
+            f"Execution started on branch `{branch_name}`.\n\nNo GitHub Project context was provided, so Superflow recorded the active state via issue comment fallback.",
+        )
+
+    record_value_transition(status, "status", "active", reason="exec entered active implementation")
+    record_stage_transition(status, "tdd", reason="exec moved the linked issue into active implementation")
+    status["verification_status"] = "running"
+    status["next_action"] = "Implement on the linked branch, then verify and archive."
+    status["target_repo"] = repo
+    status["issue_repo"] = repo
+    status["issue_number"] = int(issue_number)
+    status["branch_name"] = branch_name
+    status["checkout_path"] = str(checkout_path)
+    status["execution_started"] = True
+    if project_result:
+        status["project_status"] = {
+            "owner": project_context["owner"],
+            "number": int(project_context["number"]),
+            "field_name": args.status_field_name,
+            "option_name": args.target_status,
+            "source": project_context.get("source", "explicit"),
+            **project_result,
+        }
+    save_status(status_path, status)
+    doctor_result = None
+    if not args.skip_doctor_postcheck:
+        doctor_result = run_doctor_checks(
+            project_root=args.project_root,
+            change_id=args.change_id,
+            repo=repo,
+            issue_number=int(issue_number),
+            branch_name=branch_name,
+            checkout_path_override=checkout_path,
+        )
+        if not doctor_result["ok"]:
+            raise SystemExit("Doctor postcheck failed after exec state transition. Run doctor.py for details.")
+
+    result = {
+        "change_id": args.change_id,
+        "repo": repo,
+        "issue_number": int(issue_number),
+        "branch_name": branch_name,
+        "checkout_path": str(checkout_path),
+        "remote_url": remote_url,
+        "project_status_updated": bool(project_result),
+        "project_context_source": project_context.get("source") if project_context else None,
+        "status_path": maybe_relative(status_path, base=args.project_root),
+    }
+    if doctor_result is not None:
+        result["doctor"] = {"ok": doctor_result["ok"], "hard_failures": doctor_result["hard_failures"], "warnings": doctor_result["warnings"]}
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"Execution prepared for {repo}#{issue_number}")
+        print(f"Branch: {branch_name}")
+        print(f"Checkout: {checkout_path}")
+        print(f"Remote: {remote_url}")
+        print(f"Project status updated: {'yes' if project_result else 'fallback issue comment'}")
+        print(f"Status: {status_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/xflow/goal/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: xflow:goal
+description: Use when the user wants to set, inspect, update, clear, or align an xflow project goal, thread goal, direction anchor, anti-drift objective, or Codex native goal for a project.
+---
+
+# xflow:goal
+
+`xflow:goal` keeps one simple project-level direction anchor.
+
+The MVP contract is intentionally small:
+
+```text
+.xflow/GOAL.md
+```
+
+Do not introduce session ids, named goal registries, active-goal pointers, or
+multiple goal files unless the user explicitly asks for that complexity.
+
+## Advantage Over Codex Native Goal
+
+Codex native goals are thread-local control and completion accounting. They are
+valuable, but they do not by themselves create a repo-level artifact that future
+threads, OpenCode, Claude Code, Cursor, or CI-visible workflow docs can inspect.
+
+`xflow:goal` is better only when it stays durable and consumable:
+
+- durable in `.xflow/GOAL.md`
+- portable across agent tools
+- read by `xflow:plan`, `xflow:yolo`, `xflow:corps`, `xflow:ralph`,
+  `xflow:handoff`, and `xflow:takein`
+- included in completion audits as alignment evidence
+
+If the current environment exposes Codex native goal controls, mirror the xflow
+project goal into the native thread goal. Do not treat native sync as the source
+of truth; the project artifact remains canonical for xflow.
+
+## When To Use
+
+Use this skill when the user wants to:
+
+- set a goal for the current project or thread
+- see the active xflow goal
+- audit whether the skill family still consumes the project goal
+- update or clear the project goal
+- make Ralph, yolo, corps, handoff, or takein stay aligned to a direction
+- make xflow mirror Codex native goal behavior
+
+## Native Codex Goal Sync
+
+When Codex native goal controls are available in the current environment,
+set or update the active thread goal to match the xflow goal.
+
+Do not hard-code a nonexistent CLI command such as `codex goal set`. If native
+goal controls are not exposed, continue with `.xflow/GOAL.md` and explicitly
+say that native thread-goal sync was unavailable.
+
+## Project Artifact
+
+Use the current project root:
+
+```text
+.xflow/GOAL.md
+```
+
+Create `.xflow/` if needed.
+
+Recommended file shape:
+
+```markdown
+# xflow Goal
+
+## Goal
+
+<one or a few paragraphs describing the project direction anchor>
+
+## Scope
+
+- <what this goal covers>
+
+## Non-Goals
+
+- <optional exclusions>
+
+## Updated
+
+YYYY-MM-DD
+```
+
+Keep it short enough to read at the start of later work.
+
+## Operations
+
+### Set
+
+When the user asks to set a goal:
+
+1. Inspect whether `.xflow/GOAL.md` already exists.
+2. If an existing goal is clearly unrelated, warn before overwriting unless the
+   user has already said to replace it.
+3. Write the new goal into `.xflow/GOAL.md`.
+4. Try native Codex goal sync when available.
+5. Report the file path and whether native sync happened.
+
+### Show
+
+When the user asks what the current goal is, read `.xflow/GOAL.md` and summarize
+it. If the file is missing, say there is no xflow project goal yet.
+
+### Audit
+
+When the user asks whether goal is useful, stale, or actually connected to the
+workflow family, run or recommend:
+
+```bash
+xflow goal audit --json
+```
+
+The audit should prove both sides of the claim: a durable `.xflow/GOAL.md`
+exists in the project, and the core skill family still declares that goal as
+direction context for plan, yolo, corps, Ralph, handoff, and takein.
+
+### Update
+
+When the user asks to update the goal, preserve still-current parts and patch
+only the changed intent. If the update changes the direction materially, call
+out that the goal changed.
+
+### Clear
+
+When the user asks to clear the goal, remove or blank `.xflow/GOAL.md` only
+after confirming they mean to remove the project direction anchor. If native
+goal controls are available, clear the active thread goal too.
+
+## Integration Rules
+
+- `xflow:ralph` should read `.xflow/GOAL.md` before planning substantial work
+  and include it in the completion audit.
+- `xflow:plan` should use `.xflow/GOAL.md` as context when writing or refreshing
+  `specs/changes/<change-id>/plan.md`.
+- `xflow:yolo` and `xflow:corps` should treat `.xflow/GOAL.md` as directional
+  context, not as a replacement for change scope, workflow status, or proof.
+- `xflow:handoff` should include the current goal when refreshing `HANDOFF.md`.
+- `xflow:takein` should read `.xflow/GOAL.md` when present so new threads
+  recover the project direction quickly.
+
+## Boundary
+
+`xflow:goal` is not an executor. It does not run implementation, tests,
+archive, or PR steps. Use `xflow:ralph`, `xflow:yolo`, or `xflow:corps` for
+execution.

package/xflow/handoff/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: xflow:handoff
+description: 在当前项目根目录的 `HANDOFF.md` 中创建或刷新规范的项目交接文档。适用于用户要求编写 handoff、会话总结、下次会话简报、项目交接说明，或把项目背景、架构、任务状态、进展、问题、经验和建议汇总到一个根级交接文档中时。
+---
+
+# Superflow Handoff
+
+Write handoff into exactly one canonical file:
+
+- project root `HANDOFF.md`
+
+Do not maintain parallel handoff files such as:
+
+- `MUST_READ_NEXT_SESSION.md`
+- `NEXT_SESSION.md`
+- `SESSION_SUMMARY.md`
+
+If those files exist and are only duplicating handoff intent, fold any still-useful content into `HANDOFF.md` and remove or reduce the duplicate file so `HANDOFF.md` remains the single source of truth.
+
+## Required Output
+
+Every handoff must cover these seven areas in root `HANDOFF.md`:
+
+1. project background
+2. architecture and non-negotiable invariants
+3. current task or objective
+4. progress / verified state
+5. open problems / risks / blockers
+6. lessons learned / operational gotchas
+7. concrete recommendations / next steps
+
+If some area is unknown, say so explicitly instead of omitting it.
+
+In addition, every handoff must include a high-density `Context Pack` section.
+
+`Context Pack` is the canonical place to preserve high-signal facts without relying on long thread history.
+It should be skimmable and referenceable (paths, commands, numbers, dates), and avoid long logs or full file dumps.
+
+## Workflow
+
+1. Inspect the current repo state first.
+2. Read project root `.xflow/GOAL.md` if present and include the current goal.
+3. Read the existing root `HANDOFF.md` if present.
+4. Search for any other handoff-style docs only if needed to recover useful context.
+5. Prefer evidence from the codebase, tests, recent tracker docs, and current repo status.
+6. Rewrite `HANDOFF.md` so it reflects the latest truth, not stale historical guesses.
+7. Keep the document concise but decision-useful.
+
+## Structure
+
+Use this structure unless the project has a stronger established convention:
+
+- title with project name and date
+- `Current State`
+- `Context Pack`
+- `Project Background`
+- `Architecture`
+- `Current Objective`
+- `Progress`
+- `Open Problems`
+- `Lessons Learned`
+- `Recommendations`
+- `Key Files`
+
+`Recommendations` should be action-oriented and ordered.
+
+### Context Pack Format
+
+Keep this section dense and easy to rehydrate after `/compact`:
+
+- `TL;DR` (<= 40 lines): objective, current status, next action, key risks
+- `Key Facts`: numbers, dates, invariants, known constraints (each with an anchor)
+- `Decisions`: what was decided and why (1-2 lines each)
+- `Commands`: 5-15 high-value commands (include flags and caveats)
+- `Pointers`: 5-15 key files/dirs + 1-line description each
+- `Gotchas`: sharp edges that caused real waste (rate limits, flaky tests, env vars, etc.)
+
+## Guardrails
+
+- `HANDOFF.md` is the only canonical handoff.
+- Do not scatter status across multiple root handoff docs.
+- Do not keep known-false claims once newer verification exists.
+- Distinguish verified facts from inferred judgments.
+- Prefer repo-relative operational truth over conversational memory.
+
+## Script
+
+The agent autonomously calls this scaffold when creating handoff:
+
+```bash
+python3 ~/.codex/skills/xflow/handoff/scripts/scaffold_handoff.py
+```
+
+Agent fills the scaffold with real project content.
+User invokes skill, agent handles execution.