@pennixrv/trellis 0.6.45 → 0.7.0-beta.10

package/dist/templates/trellis/scripts/common/workflow_selection.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""
+Per-task workflow selection.
+
+Resolves which workflow markdown file consumers should read. A task may pin
+a workflow variant by storing `"workflow": "<id>"` in its task.json; the
+variant body lives at `.trellis/workflows/<id>.md` (user-managed library).
+
+Resolution precedence (single source of truth for all consumers), highest
+to lowest — each layer resolves an id to `.trellis/workflows/<id>.md` and
+falls through when unset, invalid, or pointing at a missing file:
+    1. Per-task pin  - active task's task.json `workflow` (session-bound,
+       explicit; a bad id or missing file warns once on stderr, then falls
+       through rather than aborting).
+    2. Personal      - `.developer` `workflow=<id>` (gitignored, per-developer;
+       outranks the team default). Silent on miss.
+    3. Team default  - config.yaml `default_workflow` (git-tracked, shared).
+       Silent on miss.
+    4. Global        - `.trellis/workflow.md`.
+With neither a per-task pin nor the personal/team keys set, this is identical
+to reading the global `.trellis/workflow.md`. Never raises.
+
+Provides:
+    workflow_md_for_task - Full precedence for an already-resolved task dir
+    resolve_workflow_md  - Session-aware wrapper via the active task resolver
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+from .paths import DIR_WORKFLOW, FILE_TASK_JSON
+
+# Workflow variant library directory under .trellis/ (plural on purpose:
+# `.trellis/workflow/` is reserved by the YAML-manifest migration).
+DIR_WORKFLOWS = "workflows"
+
+# Workflow ids must be plain slugs; anything else (path separators, dots)
+# is rejected so a task.json value can never escape .trellis/workflows/.
+WORKFLOW_ID_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def _global_workflow_md(repo_root: Path) -> Path:
+    return repo_root / DIR_WORKFLOW / "workflow.md"
+
+
+def _library_variant(repo_root: Path, workflow_id: str | None) -> Path | None:
+    """Map a workflow id to its library file if valid and present, else None.
+
+    Shared by every layer (per-task pin, personal, team). An id with path
+    separators/dots/blanks, or one whose `.trellis/workflows/<id>.md` file does
+    not exist, returns None so the caller falls through. Never raises.
+    """
+    if not isinstance(workflow_id, str) or not workflow_id:
+        return None
+    if not WORKFLOW_ID_RE.match(workflow_id):
+        return None
+    variant = repo_root / DIR_WORKFLOW / DIR_WORKFLOWS / f"{workflow_id}.md"
+    return variant if variant.is_file() else None
+
+
+def _developer_workflow_id(repo_root: Path) -> str | None:
+    """Personal override id from the gitignored .developer file (fail-open)."""
+    try:
+        from .paths import get_developer_workflow
+
+        return get_developer_workflow(repo_root)
+    except Exception:
+        return None
+
+
+def _config_default_id(repo_root: Path) -> str | None:
+    """Team-shared default id from config.yaml `default_workflow` (fail-open)."""
+    try:
+        from .config import get_default_workflow
+
+        return get_default_workflow(repo_root)
+    except Exception:
+        return None
+
+
+def _default_workflow_md(repo_root: Path) -> Path:
+    """Resolve the non-per-task default: personal -> team -> global.
+
+    Personal (`.developer` `workflow=`) outranks the team-shared
+    (config.yaml `default_workflow`) layer; both fall through to the global
+    `.trellis/workflow.md` when unset, invalid, or naming a missing file. These
+    layers are silent on miss (they are defaults, not an explicit per-task
+    choice — a per-turn warning would be noise).
+    """
+    for get_id in (_developer_workflow_id, _config_default_id):
+        variant = _library_variant(repo_root, get_id(repo_root))
+        if variant is not None:
+            return variant
+    return _global_workflow_md(repo_root)
+
+
+def _task_pin_variant(repo_root: Path, task_dir: Path | None) -> Path | None:
+    """Return the per-task pinned variant path, or None to fall through.
+
+    Emits a stderr warning on an invalid id or a missing variant file (an
+    explicit per-task choice that cannot be honored), then returns None so
+    resolution continues with the personal/team defaults. Never raises.
+    """
+    if task_dir is None:
+        return None
+
+    try:
+        raw = json.loads((task_dir / FILE_TASK_JSON).read_text(encoding="utf-8"))
+        if not isinstance(raw, dict):
+            return None
+
+        workflow_id = raw.get("workflow")
+        if not isinstance(workflow_id, str) or not workflow_id:
+            return None
+
+        if not WORKFLOW_ID_RE.match(workflow_id):
+            print(
+                f"Warning: task '{task_dir.name}' has invalid workflow id "
+                f"{workflow_id!r}; using default workflow resolution",
+                file=sys.stderr,
+            )
+            return None
+
+        variant = _library_variant(repo_root, workflow_id)
+        if variant is not None:
+            return variant
+
+        print(
+            f"Warning: task '{task_dir.name}' selects workflow '{workflow_id}' but "
+            f"{DIR_WORKFLOW}/{DIR_WORKFLOWS}/{workflow_id}.md is missing; "
+            f"using default workflow resolution",
+            file=sys.stderr,
+        )
+        return None
+    except Exception:
+        return None
+
+
+def workflow_md_for_task(repo_root: Path, task_dir: Path | None) -> Path:
+    """Return the workflow.md path for an already-resolved task dir (or None).
+
+    Applies the full precedence documented in the module docstring:
+    per-task pin -> personal (.developer) -> team (config.yaml) -> global.
+    Never raises; any failure falls through toward the global workflow path.
+    """
+    pin = _task_pin_variant(repo_root, task_dir)
+    if pin is not None:
+        return pin
+    return _default_workflow_md(repo_root)
+
+
+def resolve_workflow_md(
+    repo_root: Path,
+    input_data: dict | None = None,
+    platform: str | None = None,
+) -> Path:
+    """Resolve the session-aware active task, then apply the resolution rule.
+
+    ``input_data`` is the raw hook payload (session/conversation identity);
+    CLI callers may omit it — the active-task resolver then falls back to
+    environment context. Never raises; any failure resolves to the global
+    `.trellis/workflow.md`.
+    """
+    try:
+        from .active_task import resolve_active_task, resolve_task_ref
+
+        active = resolve_active_task(repo_root, input_data, platform)
+        task_dir: Path | None = None
+        if active.task_path:
+            task_dir = resolve_task_ref(active.task_path, repo_root)
+        return workflow_md_for_task(repo_root, task_dir)
+    except Exception:
+        return _global_workflow_md(repo_root)

package/dist/templates/trellis/scripts/subnode_artifact.py

@@ -22,10 +22,12 @@ from common.task_utils import is_within_tasks_dir, resolve_task_dir
 from common.tasks import load_task
 
 
-SCHEMA_VERSION = 1
+SCHEMA_VERSION = 2
 MAX_DRAFT_BYTES = 64 * 1024
 MAX_REPORT_BYTES = 128 * 1024
+MAX_WORKLOG_BYTES = 128 * 1024
 ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
+CHECKPOINT_RE = re.compile(r"^<!-- trellis-checkpoint: (?P<payload>\{.*\}) -->$", re.MULTILINE)
 SECRET_PATTERNS = (
     re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----"),
     re.compile(r"\bsk-[A-Za-z0-9]{20,}\b"),
@@ -305,7 +307,7 @@ def _validate_brief_file(
     return brief, raw, brief_path, node_dir, task_dir
 
 
-def _validate_evidence(value: Any) -> set[tuple[str, str]]:
+def _validate_evidence(value: Any) -> set[str]:
     if not isinstance(value, list):
         _fail("report.evidence must be a list")
     identities: set[tuple[str, str]] = set()
@@ -319,13 +321,100 @@ def _validate_evidence(value: Any) -> set[tuple[str, str]]:
         if identity in identities:
             _fail("report.evidence contains a duplicate evidence identity")
         identities.add(identity)
-    return identities
+    return {evidence_id for evidence_id, _locator in identities}
+
+
+def _validate_id_list(value: Any, field: str) -> list[str]:
+    if not isinstance(value, list):
+        _fail(f"{field} must be a list")
+    result = []
+    for index, item in enumerate(value):
+        result.append(_require_text(item, f"{field}[{index}]", max_len=128))
+    if len(result) != len(set(result)):
+        _fail(f"{field} must not contain duplicates")
+    return result
+
+
+def _validate_typed_notes(value: Any, field: str) -> None:
+    if not isinstance(value, list):
+        _fail(f"report.{field} must be a list")
+    for index, item in enumerate(value):
+        if not isinstance(item, dict):
+            _fail(f"report.{field}[{index}] must be an object")
+        _require_id(item.get("id"), f"report.{field}[{index}].id")
+        _require_text(item.get("type"), f"report.{field}[{index}].type", max_len=64)
+        _require_text(item.get("detail"), f"report.{field}[{index}].detail")
+        _validate_id_list(item.get("evidence_ids", []), f"report.{field}[{index}].evidence_ids")
+
+
+def _validate_checkpoint(node_dir: Path, evidence_ids: set[str], scope: list[str]) -> list[str]:
+    worklog_path = node_dir / "worklog.md"
+    if worklog_path.is_symlink():
+        _fail(f"refusing symlinked worklog: {worklog_path}")
+    try:
+        raw = worklog_path.read_bytes()
+    except FileNotFoundError:
+        _fail(f"worklog does not exist: {worklog_path}")
+    except OSError as exc:
+        _fail(f"could not read worklog {worklog_path}: {exc}")
+    if len(raw) > MAX_WORKLOG_BYTES:
+        _fail(f"worklog exceeds the {MAX_WORKLOG_BYTES} byte limit: {worklog_path}")
+    _reject_obvious_secrets(raw, "worklog")
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        _fail(f"worklog is not UTF-8: {worklog_path}")
+    matches = list(CHECKPOINT_RE.finditer(text))
+    if not matches:
+        return ["missing_worklog_checkpoint"]
+    concerns: list[str] = []
+    checkpoint_ids: set[str] = set()
+    for match in matches:
+        try:
+            checkpoint = json.loads(match.group("payload"))
+        except json.JSONDecodeError:
+            concerns.append("malformed_worklog_checkpoint")
+            continue
+        if not isinstance(checkpoint, dict):
+            concerns.append("malformed_worklog_checkpoint")
+            continue
+        try:
+            checkpoint_id = _require_id(checkpoint.get("id"), "worklog checkpoint.id")
+            if checkpoint_id in checkpoint_ids:
+                concerns.append("duplicate_worklog_checkpoint")
+            checkpoint_ids.add(checkpoint_id)
+            covered_scope = _require_text_list(
+                checkpoint.get("covered_scope"),
+                "worklog checkpoint.covered_scope",
+                allow_empty=True,
+            )
+            for item in covered_scope:
+                if item not in scope:
+                    concerns.append("checkpoint_scope_outside_brief")
+            checkpoint_evidence = _validate_id_list(
+                checkpoint.get("evidence_ids"), "worklog checkpoint.evidence_ids"
+            )
+            if any(item not in evidence_ids for item in checkpoint_evidence):
+                concerns.append("checkpoint_evidence_unresolved")
+            _require_text(
+                checkpoint.get("conclusion_or_blocker"),
+                "worklog checkpoint.conclusion_or_blocker",
+            )
+            _require_text_list(
+                checkpoint.get("unknowns"),
+                "worklog checkpoint.unknowns",
+                allow_empty=True,
+            )
+            _require_text(checkpoint.get("safe_resume_point"), "worklog checkpoint.safe_resume_point")
+        except ArtifactError:
+            concerns.append("malformed_worklog_checkpoint")
+    return sorted(set(concerns))
 
 
 def _validate_report_data(
     report: dict[str, Any],
     brief: dict[str, Any],
-) -> set[tuple[str, str]]:
+) -> tuple[set[str], list[str]]:
     if report.get("schema_version") != SCHEMA_VERSION:
         _fail(f"report.schema_version must be {SCHEMA_VERSION}")
     for field in ("task_id", "work_id", "subnode_id", "role_id"):
@@ -339,11 +428,52 @@ def _validate_report_data(
     if status not in {"complete", "blocked", "incomplete", "error"}:
         _fail("report.status must be complete, blocked, incomplete, or error")
     evidence = _validate_evidence(report.get("evidence"))
-    for field in ("findings", "uncertainties", "corrections"):
-        if not isinstance(report.get(field), list):
-            _fail(f"report.{field} must be a list")
+    assessment = report.get("scope_assessment")
+    if not isinstance(assessment, list) or len(assessment) != len(brief["scope"]):
+        _fail("report.scope_assessment must contain one item for every brief scope item")
+    concerns: list[str] = []
+    for index, item in enumerate(assessment):
+        if not isinstance(item, dict):
+            _fail(f"report.scope_assessment[{index}] must be an object")
+        if item.get("scope") != brief["scope"][index]:
+            _fail(f"report.scope_assessment[{index}].scope does not match brief.scope")
+        if item.get("status") not in {"covered", "inconclusive", "not-started"}:
+            _fail(f"report.scope_assessment[{index}].status is invalid")
+        _require_text(item.get("conclusion"), f"report.scope_assessment[{index}].conclusion")
+        assessment_evidence = _validate_id_list(
+            item.get("evidence_ids"), f"report.scope_assessment[{index}].evidence_ids"
+        )
+        if any(value not in evidence for value in assessment_evidence):
+            concerns.append("scope_assessment_evidence_unresolved")
+        if item["status"] != "covered":
+            concerns.append("incomplete_scope_coverage")
+        if item["status"] == "covered" and not assessment_evidence:
+            concerns.append("covered_scope_without_evidence")
+    findings = report.get("findings")
+    if not isinstance(findings, list):
+        _fail("report.findings must be a list")
+    finding_ids: set[str] = set()
+    for index, item in enumerate(findings):
+        if not isinstance(item, dict):
+            _fail(f"report.findings[{index}] must be an object")
+        finding_id = _require_id(item.get("id"), f"report.findings[{index}].id")
+        if finding_id in finding_ids:
+            _fail("report.findings contains duplicate ids")
+        finding_ids.add(finding_id)
+        _require_text(item.get("conclusion"), f"report.findings[{index}].conclusion")
+        finding_evidence = _validate_id_list(
+            item.get("evidence_ids"), f"report.findings[{index}].evidence_ids"
+        )
+        if not finding_evidence:
+            concerns.append("finding_without_evidence")
+        if any(value not in evidence for value in finding_evidence):
+            concerns.append("finding_evidence_unresolved")
+    _validate_typed_notes(report.get("uncertainties"), "uncertainties")
+    _validate_typed_notes(report.get("corrections"), "corrections")
     if status == "complete" and not evidence:
         _fail("a complete report requires at least one evidence item")
+    if status == "complete" and not findings:
+        _fail("a complete report requires at least one finding")
     if status != "complete":
         _require_text_list(
             report.get("completed_scope"),
@@ -351,13 +481,13 @@ def _validate_report_data(
             allow_empty=True,
         )
         _require_text(report.get("blocker"), "report.blocker")
-    return evidence
+    return evidence, sorted(set(concerns))
 
 
 def _validate_report_file(
     value: str,
     repo_root: Path,
-) -> tuple[dict[str, Any], set[tuple[str, str]], dict[str, Any], Path]:
+) -> tuple[dict[str, Any], set[str], dict[str, Any], Path, list[str]]:
     report_path, node_dir, _task_dir = _resolve_artifact_file(value, "report.json", repo_root)
     brief_path = node_dir / "brief.json"
     brief, _brief_raw, _brief_path, _brief_node, _brief_task = _validate_brief_file(
@@ -368,8 +498,9 @@ def _validate_report_file(
         _fail("brief.report_path does not point to the report being validated")
     report, raw = _read_json_object(report_path, MAX_REPORT_BYTES, "report")
     _reject_obvious_secrets(raw, "report")
-    evidence = _validate_report_data(report, brief)
-    return report, evidence, brief, node_dir
+    evidence, concerns = _validate_report_data(report, brief)
+    concerns.extend(_validate_checkpoint(node_dir, evidence, brief["scope"]))
+    return report, evidence, brief, node_dir, sorted(set(concerns))
 
 
 def _validate_disposition_data(
@@ -466,13 +597,20 @@ def _init(args: argparse.Namespace) -> None:
 
 def _validate(args: argparse.Namespace) -> None:
     repo_root = get_repo_root()
-    report, _evidence, _brief, _node_dir_value = _validate_report_file(args.report, repo_root)
+    report, _evidence, _brief, _node_dir_value, concerns = _validate_report_file(args.report, repo_root)
+    if concerns:
+        print(json.dumps({
+            "status": "review_concern",
+            "subnode_id": report["subnode_id"],
+            "concerns": concerns,
+        }))
+        return
     print(f"Validated pending-review report: {report['subnode_id']}")
 
 
 def _disposition(args: argparse.Namespace) -> None:
     repo_root = get_repo_root()
-    report, _evidence, brief, node_dir = _validate_report_file(args.report, repo_root)
+    report, _evidence, brief, node_dir, _concerns = _validate_report_file(args.report, repo_root)
     disposition_path = node_dir / "disposition.json"
     if disposition_path.exists() or disposition_path.is_symlink():
         _fail(f"disposition already exists and cannot be replaced: {disposition_path}")
@@ -514,10 +652,10 @@ def _validate_counter(args: argparse.Namespace) -> None:
         primary_dir = repo_root / primary_dir
     if not counter_dir.is_absolute():
         counter_dir = repo_root / counter_dir
-    primary_report, primary_evidence, primary_brief, primary_node = _validate_report_file(
+    primary_report, primary_evidence, primary_brief, primary_node, _primary_concerns = _validate_report_file(
         str(primary_dir / "report.json"), repo_root
     )
-    counter_report, counter_evidence, counter_brief, counter_node = _validate_report_file(
+    counter_report, counter_evidence, counter_brief, counter_node, _counter_concerns = _validate_report_file(
         str(counter_dir / "report.json"), repo_root
     )
     if primary_node == counter_node:

package/dist/templates/trellis/scripts/task.py

@@ -9,9 +9,11 @@ Usage:
     python3 task.py validate <dir>              # Validate jsonl files
     python3 task.py list-context <dir>          # List jsonl entries
     python3 task.py start <dir>                 # Set active task, record current branch
+    python3 task.py replan <dir> "<reason>"     # Return an in-progress task to planning
     python3 task.py current [--source] [--json] # Show active task
     python3 task.py ownership <operation> ...   # Manage formal handoff task ownership
     python3 task.py finish                      # Clear active task
+    python3 task.py workflow <id>|--clear       # Set/clear per-task workflow selection
     python3 task.py set-branch <dir> <branch>   # Set git branch
     python3 task.py set-base-branch <dir> <branch>  # Set PR target branch
     python3 task.py set-scope <dir> <scope>     # Set scope for PR title
@@ -28,7 +30,9 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import sys
+from datetime import datetime, timezone
 from pathlib import Path
 
 from common.log import Colors, colored
@@ -51,11 +55,13 @@ from common.active_task import (
 from common.git import current_branch_name
 from common.io import (
     describe_json_read_failure,
+    read_json,
     read_json_checked,
     write_json,
 )
 from common.task_utils import resolve_task_dir, run_task_hooks
 from common.tasks import iter_active_tasks, children_progress
+from common.workflow_selection import WORKFLOW_ID_RE, workflow_md_for_task
 
 # Import command handlers from split modules (also re-exports for plan.py compatibility)
 from common.task_store import (
@@ -298,6 +304,74 @@ def cmd_start(args: argparse.Namespace) -> int:
         return 1
 
 
+def cmd_replan(args: argparse.Namespace) -> int:
+    """Return an in-progress task to planning without losing its binding."""
+    repo_root = get_repo_root()
+    full_path = resolve_task_dir(args.dir, repo_root)
+    if full_path is None or not full_path.is_dir():
+        print(colored(f"Error: Task not found: {args.dir}", Colors.RED), file=sys.stderr)
+        return 1
+
+    try:
+        assert_task_mutation_allowed(repo_root, full_path)
+    except (OwnershipError, OSError) as exc:
+        print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
+        return 2
+
+    reason = " ".join(args.reason).strip()
+    if not reason:
+        print(colored("Error: replan reason must not be empty", Colors.RED), file=sys.stderr)
+        return 1
+
+    task_json_path = full_path / FILE_TASK_JSON
+    data, read_reason = read_json_checked(task_json_path)
+    if data is None:
+        problem, hint = describe_json_read_failure(task_json_path, read_reason)
+        print(colored(f"Error: {problem}", Colors.RED), file=sys.stderr)
+        print(hint, file=sys.stderr)
+        return 1
+    if data.get("status") != "in_progress":
+        print(
+            colored(
+                f"Error: replan requires status=in_progress (found {data.get('status')!r})",
+                Colors.RED,
+            ),
+            file=sys.stderr,
+        )
+        return 1
+
+    event = {
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "task": full_path.relative_to(repo_root).as_posix(),
+        "from_status": "in_progress",
+        "reason": reason,
+        "branch": data.get("branch"),
+    }
+    context_key = resolve_context_key()
+    if context_key:
+        event["session"] = context_key
+
+    replans_path = full_path / "replans.jsonl"
+    try:
+        with replans_path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(event, ensure_ascii=False) + "\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+    except OSError as exc:
+        print(colored(f"Error: could not record replan: {exc}", Colors.RED), file=sys.stderr)
+        return 1
+
+    data["status"] = "planning"
+    if not write_json(task_json_path, data):
+        print(colored("Error: replan event recorded but task status was not changed", Colors.RED), file=sys.stderr)
+        return 1
+
+    print(colored(f"✓ Task returned to planning: {full_path.relative_to(repo_root)}", Colors.GREEN))
+    print("Reason:", reason)
+    run_task_hooks("after_replan", task_json_path, repo_root)
+    return 0
+
+
 def cmd_finish(args: argparse.Namespace) -> int:
     """Clear active task."""
     repo_root = get_repo_root()
@@ -483,6 +557,72 @@ def cmd_ownership(args: argparse.Namespace) -> int:
         return 2
 
 
+# =============================================================================
+# Command: workflow
+# =============================================================================
+
+def cmd_workflow(args: argparse.Namespace) -> int:
+    """Set or clear the workflow selection on the current session's active task."""
+    repo_root = get_repo_root()
+
+    if args.clear and args.id:
+        print(colored("Error: pass either <id> or --clear, not both", Colors.RED))
+        return 1
+    if not args.clear and not args.id:
+        print(colored("Error: workflow id required (or --clear)", Colors.RED))
+        print("Usage: python3 task.py workflow <id> | --clear")
+        return 1
+
+    active = resolve_active_task(repo_root)
+    if not active.task_path:
+        print(colored("Error: No current task set", Colors.RED))
+        print("Hint: run task.py start <dir> first")
+        return 1
+
+    task_dir = repo_root / active.task_path
+    task_json_path = task_dir / FILE_TASK_JSON
+    if not task_json_path.is_file():
+        print(colored(f"Error: task.json not found at {task_dir}", Colors.RED))
+        return 1
+
+    data = read_json(task_json_path)
+    if not data:
+        print(colored(f"Error: failed to read {task_json_path}", Colors.RED))
+        return 1
+
+    if args.clear:
+        if data.pop("workflow", None) is None:
+            print(colored("No workflow selection set on this task", Colors.YELLOW))
+        else:
+            if not write_json(task_json_path, data):
+                print(colored("Error: failed to update task.json", Colors.RED))
+                return 1
+            print(colored("✓ Workflow selection cleared", Colors.GREEN))
+    else:
+        workflow_id = args.id
+        if not WORKFLOW_ID_RE.match(workflow_id):
+            print(colored(
+                f"Error: invalid workflow id '{workflow_id}' (allowed: letters, digits, '-', '_')",
+                Colors.RED,
+            ))
+            return 1
+        data["workflow"] = workflow_id
+        if not write_json(task_json_path, data):
+            print(colored("Error: failed to update task.json", Colors.RED))
+            return 1
+        print(colored(f"✓ Workflow set to: {workflow_id}", Colors.GREEN))
+
+    # workflow_md_for_task warns on stderr itself when the selected variant
+    # file is missing (it can be saved later via `trellis workflow --save`).
+    effective = workflow_md_for_task(repo_root, task_dir)
+    try:
+        effective_display = effective.relative_to(repo_root).as_posix()
+    except ValueError:
+        effective_display = str(effective)
+    print(f"Effective workflow: {effective_display}")
+    return 0
+
+
 # =============================================================================
 # Command: list
 # =============================================================================
@@ -665,12 +805,15 @@ Usage:
   python3 task.py create <title> --description <desc> --package <pkg>   Create task for a specific package
   python3 task.py create <title> --description <desc> --parent <dir>    Create task as child of parent
   python3 task.py create <title> --description <desc> --no-start        Create without making it active in this session
+  python3 task.py create <title> --description <desc> --workflow <id>   Create task pinned to a workflow variant
   python3 task.py add-context <dir> <jsonl> <path> [reason]  Add entry to jsonl
   python3 task.py validate <dir>                     Validate jsonl files
   python3 task.py list-context <dir>                 List jsonl entries
   python3 task.py start <dir>                        Set active task; records the checked-out branch when unset
   python3 task.py current [--source]                 Show active task
   python3 task.py finish                             Clear active task
+  python3 task.py workflow <id>                      Select workflow variant for active task
+  python3 task.py workflow --clear                   Clear selection (use default resolution)
   python3 task.py set-branch <dir> <branch>          Set git branch
   python3 task.py set-base-branch <dir> <branch>     Set PR target branch
   python3 task.py set-scope <dir> <scope>            Set scope for PR title
@@ -794,6 +937,10 @@ def main() -> int:
         action="store_true",
         help="Create the task without making it active in this session",
     )
+    p_create.add_argument(
+        "--workflow",
+        help="Workflow variant id for this task (.trellis/workflows/<id>.md)",
+    )
     p_create.add_argument(
         "--force",
         action="store_true",
@@ -824,6 +971,11 @@ def main() -> int:
         help="Start even when implement.jsonl / check.jsonl have no curated entries",
     )
 
+    # replan
+    p_replan = subparsers.add_parser("replan", help="Return an in-progress task to planning")
+    p_replan.add_argument("dir", help="Task directory")
+    p_replan.add_argument("reason", nargs="+", help="Material reason for returning to planning")
+
     # current
     p_current = subparsers.add_parser("current", help="Show active task")
     p_current.add_argument("--source", action="store_true",
@@ -889,6 +1041,12 @@ def main() -> int:
     # finish
     subparsers.add_parser("finish", help="Clear active task")
 
+    # workflow
+    p_workflow = subparsers.add_parser("workflow", help="Set/clear per-task workflow selection")
+    p_workflow.add_argument("id", nargs="?", help="Workflow id (.trellis/workflows/<id>.md)")
+    p_workflow.add_argument("--clear", action="store_true",
+                            help="Remove the workflow selection (use default resolution)")
+
     # set-branch
     p_branch = subparsers.add_parser("set-branch", help="Set git branch")
     p_branch.add_argument("dir", help="Task directory")
@@ -965,10 +1123,12 @@ def main() -> int:
         "validate": cmd_validate,
         "list-context": cmd_list_context,
         "start": cmd_start,
+        "replan": cmd_replan,
         "current": cmd_current,
         "continuity": cmd_continuity,
         "ownership": cmd_ownership,
         "finish": cmd_finish,
+        "workflow": cmd_workflow,
         "set-branch": cmd_set_branch,
         "set-base-branch": cmd_set_base_branch,
         "set-scope": cmd_set_scope,