@bx-h/meta-flow 0.1.0

package/plugin/scripts/new_task.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import os
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+from _common import write_json
+
+
+ROOT = Path(os.environ.get("META_FLOW_ROOT", Path.cwd() / ".meta-flow"))
+DEFAULT_TASKS_ROOT = ROOT / "tasks"
+
+
+def slugify(text: str) -> str:
+    slug = re.sub(r"[^A-Za-z0-9]+", "-", text.strip().lower()).strip("-")
+    return slug[:48] or "task"
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Create a new meta-flow task directory.")
+    parser.add_argument("raw_request", nargs="?", help="Raw user request text.")
+    parser.add_argument("--raw-request-file", type=Path, help="File containing raw request text.")
+    parser.add_argument("--task-id", help="Override generated task id.")
+    parser.add_argument("--tasks-root", type=Path, default=DEFAULT_TASKS_ROOT, help="Task root directory.")
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    if args.raw_request and args.raw_request_file:
+        raise SystemExit("Use either raw_request or --raw-request-file, not both.")
+    if args.raw_request_file:
+        raw_request = args.raw_request_file.read_text(encoding="utf-8")
+    elif args.raw_request:
+        raw_request = args.raw_request
+    else:
+        raise SystemExit("A raw request is required.")
+
+    now = datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+    task_id = args.task_id or f"{datetime.now(timezone.utc).strftime('%Y%m%d-%H%M%S')}-{slugify(raw_request)}"
+    task_dir = args.tasks_root / task_id
+    task_dir.mkdir(parents=True, exist_ok=False)
+
+    state = {
+        "task_id": task_id,
+        "phase": "INTAKE",
+        "created_at": now,
+        "updated_at": now,
+        "proposal_review_round": 0,
+        "direction_adjustment_round": 0,
+        "current_milestone_id": None,
+        "current_task_id": None,
+        "max_proposal_rework_rounds": 3,
+        "max_task_repair_rounds": 2,
+        "max_direction_adjustment_rounds": 2,
+        "status": "active",
+        "last_route_decision": "Task initialized from raw request.",
+        "history": [
+            {
+                "at": now,
+                "from_phase": "NONE",
+                "to_phase": "INTAKE",
+                "reason": "Raw request captured.",
+            }
+        ],
+    }
+
+    write_json(task_dir / "state.json", state)
+    (task_dir / "raw-request.md").write_text(raw_request.rstrip() + "\n", encoding="utf-8")
+    print(task_dir)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugin/scripts/status.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+from _common import load_json
+
+
+ROOT = Path(os.environ.get("META_FLOW_ROOT", Path.cwd() / ".meta-flow"))
+
+
+NEXT_ACTION_BY_PHASE = {
+    "INTAKE": "Run questioner and create questioning-report.json.",
+    "QUESTIONING": "Resolve blocking questions or record assumptions.",
+    "GOAL_CONTRACT_DRAFTED": "Validate goal-contract.json, then run researcher_proposer.",
+    "RESEARCH_AND_PROPOSAL": "Produce proposal.md and send it to reviewers.",
+    "PROPOSAL_REVIEW": "Run aggregate_reviews.py, then invoke adjudicator.",
+    "ADJUDICATION": "Route according to adjudication-report.json.",
+    "PROPOSAL_REWORK": "Rework proposal, respecting proposal_review_round limit.",
+    "PROPOSAL_SUMMARY": "Summarize proposal for user confirmation.",
+    "USER_PROPOSAL_CONFIRMATION": "Ask user to accept or reject the proposal.",
+    "PROPOSAL_ACCEPTED": "Run planner.",
+    "PLANNING": "Create milestone-plan.json.",
+    "USER_PLAN_CONFIRMATION": "Ask user to confirm milestone-plan.json.",
+    "MILESTONE_SELECTED": "Run task_decomposer for current milestone.",
+    "TASK_DECOMPOSITION": "Validate task-list.json and select the next concrete task.",
+    "TASK_EXECUTION": "Run executor for current concrete task.",
+    "TASK_VERIFICATION": "Run result_verifier for current concrete task.",
+    "TASK_REPAIR": "Return to executor with minimal repair instructions.",
+    "MILESTONE_COMPLETED": "Run direction_evaluator.",
+    "DIRECTION_EVALUATION": "Route based on direction-evaluation.json.",
+    "CONTINUE_NEXT_MILESTONE": "Select the next milestone.",
+    "REPLAN": "Return to planner or task_decomposer.",
+    "GOAL_ADJUSTMENT_REQUIRED": "Ask user to confirm contract patch before returning to proposal phase.",
+    "FINAL_SUMMARY": "Run final_summarizer.",
+    "USER_FINAL_CONFIRMATION": "Ask user to confirm final result.",
+    "DONE": "No next action.",
+    "BLOCKED": "Ask user for a decision or unblock input.",
+}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Print current meta-flow task status.")
+    parser.add_argument("task", type=Path, help="Task directory path, or task id under .meta-flow/tasks.")
+    return parser.parse_args()
+
+
+def resolve_task_dir(value: Path) -> Path:
+    if value.exists():
+        return value
+    candidate = ROOT / "tasks" / str(value)
+    if candidate.exists():
+        return candidate
+    raise SystemExit(f"Task directory not found: {value}")
+
+
+def collect_blocked_issues(task_dir: Path) -> list[str]:
+    issues: list[str] = []
+    for path in task_dir.rglob("*.json"):
+        data = load_json(path)
+        if isinstance(data, dict):
+            if data.get("status") == "blocked" and isinstance(data.get("summary"), str):
+                issues.append(f"{path.name}: {data['summary']}")
+            if data.get("decision") == "block":
+                reason = data.get("minimal_repair_instructions") or data.get("block_reason") or data.get("rationale")
+                if reason:
+                    issues.append(f"{path.name}: {reason}")
+    return issues
+
+
+def main() -> int:
+    task_dir = resolve_task_dir(parse_args().task)
+    state = load_json(task_dir / "state.json")
+    phase = state.get("phase", "UNKNOWN")
+    print(f"task: {state.get('task_id', task_dir.name)}")
+    print(f"status: {state.get('status', 'unknown')}")
+    print(f"current phase: {phase}")
+    print(f"current milestone: {state.get('current_milestone_id')}")
+    print(f"current task: {state.get('current_task_id')}")
+    print(f"last route decision: {state.get('last_route_decision', '')}")
+    blocked = collect_blocked_issues(task_dir)
+    print("blocked issues:")
+    if blocked:
+        for issue in blocked:
+            print(f"- {issue}")
+    else:
+        print("- none")
+    print(f"next recommended action: {NEXT_ACTION_BY_PHASE.get(phase, 'Inspect state.json and route manually.')}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugin/scripts/validate_adjudication.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from _common import fail, load_json, ok, require_dict, require_non_empty_string
+
+
+ALLOWED_NEXT_PHASES = {
+    "accept": {"PROPOSAL_SUMMARY", "USER_PROPOSAL_CONFIRMATION", "PROPOSAL_ACCEPTED"},
+    "revise_proposal": {"PROPOSAL_REWORK", "RESEARCH_AND_PROPOSAL", "PROPOSAL_REVIEW"},
+    "ask_user": {"QUESTIONING", "USER_PROPOSAL_CONFIRMATION", "USER_PLAN_CONFIRMATION", "USER_FINAL_CONFIRMATION", "GOAL_ADJUSTMENT_REQUIRED"},
+    "adjust_goal": {"GOAL_ADJUSTMENT_REQUIRED", "QUESTIONING", "RESEARCH_AND_PROPOSAL"},
+    "replan": {"REPLAN", "PLANNING", "TASK_DECOMPOSITION"},
+    "block": {"BLOCKED", "ADJUDICATION"},
+}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Validate a meta-flow adjudication-report.json file.")
+    parser.add_argument("path", type=Path, nargs="?", default=Path("adjudication-report.json"))
+    return parser.parse_args()
+
+
+def main() -> int:
+    data = require_dict(load_json(parse_args().path), "adjudication report", errors := [])
+    require_non_empty_string(data, "task_id", errors)
+    require_non_empty_string(data, "source", errors)
+    require_non_empty_string(data, "rationale", errors)
+    require_non_empty_string(data, "instructions_for_next_agent", errors)
+    decision = data.get("decision")
+    next_phase = data.get("next_phase")
+    if decision not in ALLOWED_NEXT_PHASES:
+        errors.append(f"decision must be one of {sorted(ALLOWED_NEXT_PHASES)}")
+    elif next_phase not in ALLOWED_NEXT_PHASES[decision]:
+        errors.append(f"next_phase {next_phase!r} is not consistent with decision {decision!r}")
+    if not isinstance(data.get("requires_user_confirmation"), bool):
+        errors.append("requires_user_confirmation must be a boolean")
+    if errors:
+        fail(errors)
+    ok(f"OK: adjudication valid ({decision} -> {next_phase}).")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugin/scripts/validate_goal_contract.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from _common import fail, load_json, ok, require_dict, require_list, require_non_empty_string
+
+
+VALID_METHODS = {"manual", "test", "lint", "typecheck", "script", "review", "user_confirmation"}
+VALID_RISKS = {"low", "medium", "high"}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Validate a meta-flow goal-contract.json file.")
+    parser.add_argument("path", type=Path, nargs="?", default=Path("goal-contract.json"))
+    return parser.parse_args()
+
+
+def main() -> int:
+    data = require_dict(load_json(parse_args().path), "goal contract", errors := [])
+    require_non_empty_string(data, "refined_goal", errors)
+    require_non_empty_string(data, "problem_boundary", errors)
+    require_non_empty_string(data, "success_definition", errors)
+
+    non_goals = require_list(data.get("non_goals"), "non_goals", errors)
+    constraints = require_list(data.get("constraints"), "constraints", errors)
+    criteria = require_list(data.get("acceptance_criteria"), "acceptance_criteria", errors)
+    if not criteria:
+        errors.append("acceptance_criteria must not be empty")
+    for idx, item in enumerate(criteria, start=1):
+        item_obj = require_dict(item, f"acceptance_criteria[{idx}]", errors)
+        require_non_empty_string(item_obj, "id", errors)
+        require_non_empty_string(item_obj, "criterion", errors)
+        require_non_empty_string(item_obj, "evidence_required", errors)
+        method = item_obj.get("verification_method")
+        if method not in VALID_METHODS:
+            errors.append(f"acceptance_criteria[{idx}].verification_method must be one of {sorted(VALID_METHODS)}")
+
+    if data.get("risk_level") not in VALID_RISKS:
+        errors.append(f"risk_level must be one of {sorted(VALID_RISKS)}")
+    if "non_goals" not in data:
+        errors.append("non_goals key must exist")
+    if "constraints" not in data:
+        errors.append("constraints key must exist")
+    if not isinstance(data.get("requires_user_confirmation"), bool):
+        errors.append("requires_user_confirmation must be a boolean")
+
+    if errors:
+        fail(errors)
+    ok(f"OK: goal contract valid ({len(non_goals)} non-goals, {len(constraints)} constraints, {len(criteria)} criteria).")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugin/scripts/validate_milestone_plan.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from _common import fail, load_json, ok, require_dict, require_list, require_non_empty_string, warn
+
+
+VALID_RISKS = {"low", "medium", "high"}
+VALID_STATUSES = {"pending", "in_progress", "done", "blocked"}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Validate a meta-flow milestone-plan.json file.")
+    parser.add_argument("path", type=Path, nargs="?", default=Path("milestone-plan.json"))
+    return parser.parse_args()
+
+
+def main() -> int:
+    data = require_dict(load_json(parse_args().path), "milestone plan", errors := [])
+    milestones = require_list(data.get("milestones"), "milestones", errors)
+    if not milestones:
+        errors.append("milestones must not be empty")
+    warnings: list[str] = []
+    for idx, milestone in enumerate(milestones, start=1):
+        item = require_dict(milestone, f"milestones[{idx}]", errors)
+        for key in ("id", "objective"):
+            require_non_empty_string(item, key, errors)
+        for key in ("scope", "acceptance_checks"):
+            value = require_list(item.get(key), f"milestones[{idx}].{key}", errors)
+            if key == "acceptance_checks" and not value:
+                errors.append(f"milestones[{idx}].acceptance_checks must not be empty")
+            if key == "scope" and len(value) > 7:
+                warnings.append(f"milestone {item.get('id', idx)} has scope larger than 7 items")
+        if item.get("risk") not in VALID_RISKS:
+            errors.append(f"milestones[{idx}].risk must be one of {sorted(VALID_RISKS)}")
+        if item.get("status") not in VALID_STATUSES:
+            errors.append(f"milestones[{idx}].status must be one of {sorted(VALID_STATUSES)}")
+    if warnings:
+        warn(warnings)
+    if errors:
+        fail(errors)
+    ok(f"OK: milestone plan valid ({len(milestones)} milestones).")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugin/scripts/validate_task_list.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from _common import fail, load_json, ok, require_dict, require_list, require_non_empty_string, warn
+
+
+VALID_RISKS = {"low", "medium", "high"}
+VALID_STATUSES = {"pending", "in_progress", "passed", "failed", "blocked"}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Validate a meta-flow task-list.json file.")
+    parser.add_argument("path", type=Path, nargs="?", default=Path("task-list.json"))
+    return parser.parse_args()
+
+
+def main() -> int:
+    data = require_dict(load_json(parse_args().path), "task list", errors := [])
+    require_non_empty_string(data, "task_id", errors)
+    require_non_empty_string(data, "milestone_id", errors)
+    tasks = require_list(data.get("tasks"), "tasks", errors)
+    if not tasks:
+        errors.append("tasks must not be empty")
+    warnings: list[str] = []
+    for idx, task in enumerate(tasks, start=1):
+        item = require_dict(task, f"tasks[{idx}]", errors)
+        for key in ("id", "objective"):
+            require_non_empty_string(item, key, errors)
+        for key in ("expected_outputs", "acceptance_checks", "dependencies"):
+            value = require_list(item.get(key), f"tasks[{idx}].{key}", errors)
+            if key in {"expected_outputs", "acceptance_checks"} and not value:
+                errors.append(f"tasks[{idx}].{key} must not be empty")
+        allowed_files = require_list(item.get("allowed_files"), f"tasks[{idx}].allowed_files", errors)
+        require_list(item.get("forbidden_files"), f"tasks[{idx}].forbidden_files", errors)
+        if not allowed_files:
+            warnings.append(f"task {item.get('id', idx)} has empty allowed_files")
+        if len(allowed_files) > 10:
+            warnings.append(f"task {item.get('id', idx)} may be too broad: more than 10 allowed files")
+        if len(item.get("expected_outputs", [])) > 6:
+            warnings.append(f"task {item.get('id', idx)} may be too broad: more than 6 expected outputs")
+        if item.get("risk") not in VALID_RISKS:
+            errors.append(f"tasks[{idx}].risk must be one of {sorted(VALID_RISKS)}")
+        if item.get("status") not in VALID_STATUSES:
+            errors.append(f"tasks[{idx}].status must be one of {sorted(VALID_STATUSES)}")
+        if not isinstance(item.get("repair_attempts", 0), int):
+            errors.append(f"tasks[{idx}].repair_attempts must be an integer")
+    if warnings:
+        warn(warnings)
+    if errors:
+        fail(errors)
+    ok(f"OK: task list valid ({len(tasks)} concrete tasks).")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugin/scripts/validate_task_verification.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from _common import fail, load_json, ok, require_dict, require_list, require_non_empty_string
+
+
+VALID_DECISIONS = {"pass", "revise", "block"}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Validate a meta-flow task-verification-report.json file.")
+    parser.add_argument("path", type=Path, nargs="?", default=Path("task-verification-report.json"))
+    return parser.parse_args()
+
+
+def main() -> int:
+    data = require_dict(load_json(parse_args().path), "task verification report", errors := [])
+    for key in ("task_id", "milestone_id", "concrete_task_id"):
+        require_non_empty_string(data, key, errors)
+    decision = data.get("decision")
+    if decision not in VALID_DECISIONS:
+        errors.append(f"decision must be one of {sorted(VALID_DECISIONS)}")
+    failed = require_list(data.get("failed_checks"), "failed_checks", errors)
+    new_findings = require_list(data.get("new_findings"), "new_findings", errors)
+    require_list(data.get("checks_run"), "checks_run", errors)
+    require_list(data.get("passed_checks"), "passed_checks", errors)
+    require_list(data.get("evidence_refs"), "evidence_refs", errors)
+
+    repair = data.get("minimal_repair_instructions", "")
+    block_reason = data.get("block_reason", "")
+    if decision == "pass" and failed:
+        errors.append("failed_checks must be empty when decision is pass")
+    if decision in {"revise", "block"} and not str(repair).strip() and not str(block_reason).strip():
+        errors.append("revise/block decisions require minimal_repair_instructions or block_reason")
+    if data.get("should_trigger_direction_evaluation") is True and not new_findings:
+        errors.append("new_findings must not be empty when should_trigger_direction_evaluation is true")
+    if not isinstance(data.get("should_trigger_direction_evaluation"), bool):
+        errors.append("should_trigger_direction_evaluation must be a boolean")
+    if errors:
+        fail(errors)
+    ok(f"OK: task verification valid ({decision}).")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugin/skills/meta-flow/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: meta-flow
+description: Use this workflow for vague, multi-step, high-reliability tasks that need questioning, proposal, review, adjudication, planning, task-level execution, verification, direction evaluation, and user confirmation before completion.
+---
+
+# Meta-Flow
+
+Meta-flow turns a vague request into a controlled Codex workflow with proposal review, user gates, milestone planning, concrete-task execution, verification, and direction checks.
+
+Use it when reliability matters more than speed. Do not use it for small direct edits, one-off answers, simple code explanations, or tasks without observable acceptance criteria.
+
+## Trigger Conditions
+
+- The request is vague or has unclear boundaries.
+- The task crosses files, modules, stages, or external systems.
+- The user asks for a proposal before implementation.
+- The task needs high-reliability execution and review.
+- New findings during execution may change the goal.
+- The work needs milestones, concrete tasks, and verification loops.
+
+## Non-Triggers
+
+- The user wants a direct answer.
+- The user wants code explained.
+- The user specified a small, low-risk edit.
+- The task has no executable result.
+- The task has no observable verification path.
+
+## State Machine
+
+Proposal phase:
+
+```text
+INTAKE
+-> QUESTIONING
+-> GOAL_CONTRACT_DRAFTED
+-> RESEARCH_AND_PROPOSAL
+-> PROPOSAL_REVIEW
+-> ADJUDICATION
+-> PROPOSAL_REWORK
+-> PROPOSAL_SUMMARY
+-> USER_PROPOSAL_CONFIRMATION
+-> PROPOSAL_ACCEPTED
+```
+
+Execution phase:
+
+```text
+PLANNING
+-> USER_PLAN_CONFIRMATION
+-> MILESTONE_SELECTED
+-> TASK_DECOMPOSITION
+-> TASK_EXECUTION
+-> TASK_VERIFICATION
+-> TASK_REPAIR
+-> MILESTONE_COMPLETED
+-> DIRECTION_EVALUATION
+-> CONTINUE_NEXT_MILESTONE
+-> REPLAN
+-> GOAL_ADJUSTMENT_REQUIRED
+-> FINAL_SUMMARY
+-> USER_FINAL_CONFIRMATION
+-> DONE
+```
+
+Allowed loops:
+
+- `PROPOSAL_REVIEW -> ADJUDICATION -> PROPOSAL_REWORK -> PROPOSAL_REVIEW`
+- `USER_PROPOSAL_CONFIRMATION -> ADJUDICATION -> QUESTIONING | RESEARCH_AND_PROPOSAL`
+- `TASK_VERIFICATION -> TASK_REPAIR -> TASK_EXECUTION -> TASK_VERIFICATION`
+- `DIRECTION_EVALUATION -> GOAL_ADJUSTMENT_REQUIRED -> QUESTIONING | RESEARCH_AND_PROPOSAL`
+- `DIRECTION_EVALUATION -> REPLAN -> PLANNING | TASK_DECOMPOSITION`
+
+Stop conditions:
+
+- Proposal review/rework: max 3 rounds.
+- Concrete task repair: max 2 rounds per task.
+- Direction adjustment: max 2 rounds.
+- When a limit is exceeded, generate a blocked report and ask the user for a decision.
+
+## Proposal Phase Procedure
+
+1. Create a task directory:
+
+   ```bash
+   python3 .meta-flow/scripts/new_task.py "<raw request>"
+   ```
+
+2. Save the raw request in `raw-request.md`.
+3. Invoke `questioner`.
+4. If blocking questions exist, ask the user before continuing.
+5. Generate `goal-contract.json`.
+6. Validate it:
+
+   ```bash
+   python3 .meta-flow/scripts/validate_goal_contract.py <task-dir>/goal-contract.json
+   ```
+
+7. Invoke `researcher_proposer` to create `proposal.md`.
+8. Invoke `product_reviewer`, `technical_reviewer`, `risk_reviewer`, and `verification_reviewer`, preferably in parallel.
+9. Run the mechanical aggregator:
+
+   ```bash
+   python3 .meta-flow/scripts/aggregate_reviews.py --reviews-dir <task-dir>/reviews --output <task-dir>/review-aggregate.json
+   ```
+
+10. Invoke `adjudicator`.
+11. Validate `adjudication-report.json`.
+12. If the decision is `revise_proposal`, return to `researcher_proposer`.
+13. If the decision is `ask_user`, ask the user.
+14. If the decision is `accept`, invoke `proposal_summarizer`.
+15. Show `proposal-summary.md` to the user and require confirmation.
+
+## Execution Phase Procedure
+
+1. Invoke `planner` to create `milestone-plan.json`.
+2. Validate it and ask the user to confirm the plan.
+3. Select one current milestone.
+4. Invoke `task_decomposer` to create `task-list.json`.
+5. Validate the task list.
+6. Process concrete tasks by dependency order.
+7. For each concrete task:
+   - Invoke `executor` for exactly one concrete task.
+   - Invoke `result_verifier` for exactly that concrete task.
+   - On `revise`, return to executor for repair, max 2 attempts.
+   - On `block`, stop the milestone and route to adjudicator or user.
+8. After all concrete tasks in a milestone pass, invoke `direction_evaluator`.
+9. Route from `direction-evaluation.json`:
+   - `continue`: select next milestone.
+   - `replan`: return to `planner` or `task_decomposer`.
+   - `adjust_goal`: ask user to confirm a contract patch, then return to proposal phase.
+   - `ask_user`: ask user before continuing.
+   - `abort`: generate blocked/final report as appropriate.
+10. After all milestones complete, invoke `final_summarizer`.
+11. Show `final-report.md` and require final user confirmation.
+12. Mark `state.json.status = done` and `phase = DONE`.
+
+## Role Boundaries
+
+- User confirmation gates are not agents.
+- Reviewers review; they do not decide the route.
+- Adjudicator decides the route; it does not write code or edit proposals.
+- Planner creates milestones; it does not create concrete task specs.
+- Task decomposer creates concrete tasks; it does not execute or verify.
+- Executor changes only files allowed by the current task spec.
+- Result verifier verifies one concrete task and does not fix code.
+- Direction evaluator checks whether the goal, proposal, or plan is still valid.
+
+## Reference Files
+
+- `references/role-contracts.md`
+- `references/review-rubric.md`
+- `references/adjudication-policy.md`
+- `references/execution-policy.md`
+- `references/direction-evaluation-policy.md`
+
+## Required Artifacts
+
+Task directories should use the templates in `.meta-flow/templates/` and keep state in `state.json`. Scripts in `.meta-flow/scripts/` provide initialization, validation, aggregation, and status reporting.

package/plugin/skills/meta-flow/references/adjudication-policy.md

@@ -0,0 +1,30 @@
+# Adjudication Policy
+
+Adjudication is not mechanical aggregation. `aggregate_reviews.py` only computes a mechanical result. The adjudicator decides the route.
+
+## Inputs
+
+- reviewer reports
+- review aggregate
+- user feedback
+- direction evaluator output
+- current state and round counters
+
+## Decisions
+
+- `accept`: proposal can move to user-facing summary.
+- `revise_proposal`: proposal needs specific rework.
+- `ask_user`: user input is required.
+- `adjust_goal`: goal contract needs a user-confirmed patch.
+- `replan`: execution plan or task decomposition needs changes.
+- `block`: the workflow cannot continue safely or meaningfully.
+
+## Conflict Handling
+
+A reviewer `block` does not automatically stop the workflow. The adjudicator must decide whether the block is valid, whether it can be mitigated, and whether the next route is user input, goal adjustment, proposal rework, or blocked state.
+
+## Round Limits
+
+- Proposal rework over 3 rounds: block and ask user.
+- Direction adjustment over 2 rounds: block and ask user.
+- Task repair over 2 rounds: block the concrete task and escalate.

package/plugin/skills/meta-flow/references/direction-evaluation-policy.md

@@ -0,0 +1,24 @@
+# Direction Evaluation Policy
+
+Direction evaluation runs after every completed milestone and whenever a verifier reports a major new finding.
+
+## Questions
+
+- Does the original goal still hold?
+- Did execution disprove a proposal assumption?
+- Did the milestone expose a new boundary?
+- Are the acceptance criteria still valid?
+- Is user input now required?
+- Would continuing create wrong results or wasted effort?
+
+## Decisions
+
+- `continue`: proceed to the next milestone.
+- `replan`: plan or task decomposition needs changes, but the goal is still valid.
+- `adjust_goal`: goal contract needs a user-confirmed patch.
+- `ask_user`: user decision is required before routing.
+- `abort`: continuing is unsafe or meaningless.
+
+## Contract Patch Rule
+
+The direction evaluator may propose a contract patch. It must not modify `goal-contract.json` directly. User confirmation is required before goal changes take effect.