@mindfoldhq/trellis 0.6.9 → 0.7.0-beta.0

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

@@ -0,0 +1,395 @@
+#!/usr/bin/env python3
+"""
+Path-scoped spec matching for on-demand spec injection.
+
+Spec files under `.trellis/spec/**/*.md` MAY start with a YAML-like
+frontmatter block declaring which repo paths they govern:
+
+    ---
+    name: commands-workflow
+    description: workflow command conventions
+    paths:
+      - packages/cli/src/commands/workflow.ts
+      - packages/cli/src/utils/workflow-resolver.ts
+    ---
+
+The parser is hand-rolled (house pattern, modeled on
+``trellis_config.parse_simple_yaml`` — no YAML dependency) and reads only a
+bounded head of each file (16 KiB / 200 lines, whichever ends first). Only
+files whose first line is exactly ``---`` are considered. ``name:`` /
+``description:`` single-line strings are recognized (description is reused in
+index lines). ``paths:`` accepts both a block list (``- <glob>`` items) and a
+flow sequence (``paths: [a, b]``).
+
+The parser is deliberately tolerant — a spec is prose that happens to carry a
+routing hint, not a config file. Unknown keys, unrecognized line shapes and
+stray ``- item`` lines are ignored; block scalars (``key: >`` / ``key: |``)
+consume their more-indented continuation lines, so a SKILL.md-style
+``description: >`` paragraph does not disqualify the file. An opening ``---``
+with no recognized key before the closing marker is not frontmatter at all
+(a Markdown horizontal rule opening the prose) and is ignored silently. Two
+things are errors, and both warn + skip the whole file rather than route on a
+half-read block: a malformed ``paths:`` (a scalar where a list belongs — that
+key is the one thing the rest of the pipeline depends on), and a frontmatter
+block that is still open when the head bound is reached.
+
+Glob grammar (repo-relative, POSIX separators):
+
+- ``*``  matches within a single path segment (never crosses ``/``)
+- ``?``  matches exactly one character within a segment
+- ``**`` as a whole segment matches zero or more segments
+- a trailing ``/`` is sugar for ``/**``
+- ``**`` embedded in a segment with other characters degrades to ``*``
+
+Validation rejects only what is unsafe or meaningless: empty globs, a leading
+``/`` (globs are repo-relative), ``..`` segments, backslashes (POSIX
+separators only) and control characters. Everything else is legal — real
+repositories carry ``@scope`` packages, ``[slug]`` routes, ``(marketing)``
+groups and non-ASCII directories, and the translation escapes literals
+character by character. An invalid glob is skipped with a stderr warning; the
+rest of the file's globs still apply.
+
+Translation examples (glob → matches / non-matches):
+
+    packages/cli/src/commands/update.ts
+        matches only that exact file
+    packages/cli/src/commands/*.ts
+        matches packages/cli/src/commands/update.ts
+        not     packages/cli/src/commands/channel/spawn.ts
+    packages/cli/src/templates/**
+        matches packages/cli/src/templates/trellis/index.ts (any depth)
+        not     packages/cli/src/templates (the directory itself)
+    packages/**/index.ts
+        matches packages/index.ts and packages/cli/src/index.ts
+    src/util?.py
+        matches src/utils.py, not src/util.py or src/utilXY.py
+    packages/cli/
+        same as packages/cli/**
+
+Provides:
+    SpecMatch               - frozen match record (spec_path, rel_path, description)
+    match_specs_for_file    - map an edited file to the specs that govern it
+    normalize_repo_relative - the canonical repo-relative path normalization
+    parse_spec_frontmatter  - parse the optional frontmatter head block
+    glob_to_regex           - deterministic glob → compiled regex translation
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import unicodedata
+from dataclasses import dataclass
+from pathlib import Path
+
+from .paths import DIR_SPEC, DIR_WORKFLOW
+from .trellis_config import _strip_inline_comment, _unquote
+
+# Bounded head-read limits for frontmatter scanning (design contract).
+HEAD_MAX_BYTES = 16384
+HEAD_MAX_LINES = 200
+
+# Recognized frontmatter keys. An opening `---` block that declares none of
+# them is prose under a horizontal rule, not frontmatter.
+_KNOWN_KEYS = ("paths", "name", "description")
+
+_GLOB_CONTROL_RE = re.compile(r"[\x00-\x1f\x7f]")
+_KEY_RE = re.compile(r"^([A-Za-z_][A-Za-z0-9_-]*):(.*)$")
+# YAML block-scalar introducers; the value lives in the indented lines below.
+_BLOCK_SCALARS = ("|", ">", "|-", ">-", "|+", ">+")
+
+# macOS and Windows filesystems are case-insensitive: the very same file can
+# be handed to us in a case the glob author never wrote. Match case-insensitively
+# there — over-injecting a spec is the safe side of the asymmetry.
+_CASE_INSENSITIVE_FS = sys.platform == "darwin" or sys.platform.startswith("win")
+_GLOB_FLAGS = re.IGNORECASE if _CASE_INSENSITIVE_FS else 0
+
+
+@dataclass(frozen=True)
+class SpecFrontmatter:
+    """Parsed frontmatter head. ``paths`` is None when the key is absent."""
+
+    paths: tuple[str, ...] | None
+    name: str | None
+    description: str | None
+
+
+@dataclass(frozen=True)
+class SpecMatch:
+    spec_path: Path
+    """Absolute path to the spec file."""
+    rel_path: str
+    """Repo-relative POSIX path, for display."""
+    description: str | None
+    """Frontmatter ``description:`` value, if declared."""
+
+
+def _warn(message: str) -> None:
+    print(f"[WARN] spec_match: {message}", file=sys.stderr)
+
+
+def _parse_flow_sequence(value: str) -> list[str]:
+    """Split a YAML flow sequence body (``[a, b]``) into unquoted items.
+
+    Commas separate; each item is trimmed and unquoted. Empty items (a
+    trailing comma, ``[]``) collapse away.
+    """
+    inner = value[1:-1]
+    items = (_unquote(part.strip()).strip() for part in inner.split(","))
+    return [item for item in items if item]
+
+
+def _read_head(path: Path) -> str:
+    """Read at most HEAD_MAX_BYTES from the file, decoded as UTF-8."""
+    with open(path, "rb") as f:
+        data = f.read(HEAD_MAX_BYTES)
+    return data.decode("utf-8", errors="replace")
+
+
+def parse_spec_frontmatter(head_text: str) -> SpecFrontmatter | None:
+    """Parse the optional frontmatter block from a spec file's head.
+
+    Returns None when the file has no frontmatter: either the first line is not
+    ``---``, or the block declares no recognized key before its closing marker
+    (a horizontal rule opening a prose file — silent, not an error).
+
+    Raises ValueError on a malformed ``paths:`` key (a scalar where a list
+    belongs) and on a block that is still open when the head bound
+    (HEAD_MAX_LINES / HEAD_MAX_BYTES) is reached — routing on a half-read
+    frontmatter would be worse than skipping the file loudly. Every other line
+    shape is tolerated and ignored.
+    """
+    lines = head_text.splitlines()[:HEAD_MAX_LINES]
+    if not lines:
+        return None
+    first = lines[0].lstrip("\ufeff")  # tolerate a UTF-8 BOM
+    if first != "---":
+        return None
+
+    paths: list[str] | None = None
+    name: str | None = None
+    description: str | None = None
+    pending_key: str | None = None
+    block_indent: int | None = None
+    saw_known_key = False
+    closed = False
+
+    for line in lines[1:]:
+        stripped = line.strip()
+        indent = len(line) - len(line.lstrip())
+
+        if block_indent is not None:
+            # Inside a block scalar: everything more indented (and blank lines)
+            # is its value. A dedent ends the block; that line still counts.
+            if not stripped or indent > block_indent:
+                continue
+            block_indent = None
+
+        if stripped == "---":
+            closed = True
+            break
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        if stripped == "-" or stripped.startswith("- "):
+            if pending_key == "paths" and paths is not None:
+                item = _unquote(_strip_inline_comment(stripped[1:].strip()).strip())
+                paths.append(item)
+            # List items outside `paths:` are tolerated and ignored.
+            continue
+
+        key_match = _KEY_RE.match(stripped)
+        if key_match is None:
+            continue  # Unrecognized line shape — tolerated and ignored.
+
+        key = key_match.group(1)
+        saw_known_key = saw_known_key or key in _KNOWN_KEYS
+        raw_value = key_match.group(2).strip()
+        if raw_value in _BLOCK_SCALARS:
+            if key == "paths":
+                raise ValueError("'paths' must be a list of globs")
+            pending_key = None
+            block_indent = indent
+            continue
+
+        value = _unquote(_strip_inline_comment(raw_value).strip())
+        if value:
+            pending_key = None
+            if key == "paths":
+                if not (value.startswith("[") and value.endswith("]")):
+                    raise ValueError("'paths' must be a list of globs")
+                paths = _parse_flow_sequence(value)
+            elif key == "name":
+                name = value
+            elif key == "description":
+                description = value
+            # Unknown scalar keys are tolerated and ignored.
+        else:
+            pending_key = key
+            if key == "paths":
+                paths = []
+
+    if not saw_known_key:
+        # An opening `---` with no recognized key is a horizontal rule, not a
+        # frontmatter block. Silent by design: prose files are not malformed.
+        return None
+    if not closed:
+        raise ValueError(
+            f"frontmatter block never closed within the head bound "
+            f"({HEAD_MAX_BYTES} bytes / {HEAD_MAX_LINES} lines)"
+        )
+
+    return SpecFrontmatter(
+        paths=tuple(paths) if paths is not None else None,
+        name=name,
+        description=description,
+    )
+
+
+def validate_glob(glob: str) -> str | None:
+    """Return an error message for an invalid glob, or None when valid.
+
+    Deny-list, not allow-list: only what is unsafe or meaningless is rejected
+    (see module docstring). Everything else — ``@scope``, ``[slug]``,
+    ``(marketing)``, non-ASCII directory names — is a legal path in a real
+    repository and translates fine.
+    """
+    if not glob:
+        return "empty glob"
+    if glob.startswith("/"):
+        return "absolute paths are not allowed (globs are repo-relative)"
+    if ".." in glob.split("/"):
+        return "'..' segments are not allowed"
+    if "\\" in glob:
+        return "backslashes are not allowed (globs use POSIX '/' separators)"
+    if _GLOB_CONTROL_RE.search(glob):
+        return "contains control characters"
+    return None
+
+
+def glob_to_regex(glob: str) -> re.Pattern[str]:
+    """Translate a validated glob to a compiled full-match regex.
+
+    Deterministic, segment-based translation (see module docstring for the
+    grammar and examples): ``**`` as a whole segment spans zero or more
+    segments; ``*`` becomes ``[^/]*``; ``?`` becomes ``[^/]``; everything
+    else is escaped literally. A trailing ``/`` is expanded to ``/**`` first.
+    On case-insensitive filesystems (macOS, Windows) the pattern compiles with
+    ``re.IGNORECASE`` — see ``_CASE_INSENSITIVE_FS``.
+    """
+    if glob.endswith("/"):
+        glob += "**"
+    segments = glob.split("/")
+    parts: list[str] = []
+    for i, seg in enumerate(segments):
+        is_last = i == len(segments) - 1
+        if seg == "**":
+            # Last: consume the rest of the path (at least the separator
+            # boundary is already emitted by the previous segment). Not last:
+            # zero or more whole segments including their separators.
+            parts.append(".*" if is_last else r"(?:[^/]+/)*")
+            continue
+        piece = "".join(
+            "[^/]*" if ch == "*" else "[^/]" if ch == "?" else re.escape(ch)
+            for ch in seg
+        )
+        parts.append(piece if is_last else piece + "/")
+    return re.compile("^" + "".join(parts) + "$", _GLOB_FLAGS)
+
+
+def normalize_repo_relative(repo_root: Path, file_path: str | Path) -> str | None:
+    """Canonical repo-relative POSIX path — the one normalization in the
+    pipeline, used both for matching and for display.
+
+    Root and file are fully resolved (``strict=False``, so a file that no
+    longer exists still normalizes): symlinked repo roots, macOS's
+    ``/tmp`` → ``/private/tmp`` and ``..`` segments cannot make one file look
+    like two different paths. The result is NFC-normalized (macOS hands out
+    NFD filenames). Relative inputs are taken as repo-relative. Returns None
+    when the file resolves outside the repo.
+    """
+    try:
+        root = Path(repo_root).resolve(strict=False)
+        candidate = Path(file_path)
+        if not candidate.is_absolute():
+            text = str(file_path).replace("\\", "/")
+            while text.startswith("./"):
+                text = text[2:]
+            if not text:
+                return None
+            candidate = root / text
+        rel = candidate.resolve(strict=False).relative_to(root).as_posix()
+    except (OSError, ValueError):
+        return None
+    return unicodedata.normalize("NFC", rel)
+
+
+def match_specs_for_file(repo_root: Path, file_path: str | Path) -> list[SpecMatch]:
+    """Return specs whose frontmatter ``paths:`` globs match file_path.
+
+    ``file_path`` may be absolute or repo-relative. More specific matching
+    globs are returned first; ``rel_path`` is the deterministic tie-break.
+    Scans ``.trellis/spec/**/*.md`` with bounded head-reads only. Never raises;
+    unreadable or malformed spec files are skipped with a stderr warning.
+    """
+    try:
+        repo_root = Path(repo_root).resolve()
+        spec_dir = repo_root / DIR_WORKFLOW / DIR_SPEC
+        if not spec_dir.is_dir():
+            return []
+        rel = normalize_repo_relative(repo_root, file_path)
+        if rel is None:
+            return []
+
+        matches: list[SpecMatch] = []
+        specificity: dict[str, tuple[int, int, int, int]] = {}
+        for spec_file in spec_dir.rglob("*.md"):
+            spec_rel = spec_file.relative_to(repo_root).as_posix()
+            try:
+                head = _read_head(spec_file)
+            except OSError as exc:
+                _warn(f"cannot read {spec_rel}: {exc}")
+                continue
+            try:
+                frontmatter = parse_spec_frontmatter(head)
+            except ValueError as exc:
+                _warn(f"malformed frontmatter in {spec_rel}: {exc}")
+                continue
+            if frontmatter is None or not frontmatter.paths:
+                continue
+            for glob in frontmatter.paths:
+                error = validate_glob(glob)
+                if error is not None:
+                    _warn(f"invalid glob {glob!r} in {spec_rel}: {error}")
+                    continue
+                if glob_to_regex(glob).match(rel):
+                    scored_glob = glob + "**" if glob.endswith("/") else glob
+                    wildcard_count = scored_glob.count("*") + scored_glob.count("?")
+                    segments = scored_glob.split("/")
+                    literal_segments = sum(
+                        "*" not in segment and "?" not in segment
+                        for segment in segments
+                    )
+                    specificity[spec_rel] = (
+                        0 if wildcard_count == 0 else 1,
+                        -literal_segments,
+                        wildcard_count,
+                        -(len(scored_glob) - wildcard_count),
+                    )
+                    matches.append(
+                        SpecMatch(
+                            spec_path=spec_file,
+                            rel_path=spec_rel,
+                            description=frontmatter.description,
+                        )
+                    )
+                    break
+
+        # Payload assembly spends its budget in this order. Exact and narrowly
+        # scoped matches must therefore outrank broad tree globs; alphabetic
+        # order is only a deterministic tie-break.
+        matches.sort(key=lambda m: (*specificity[m.rel_path], m.rel_path))
+        return matches
+    except Exception as exc:  # Never raise — callers are hooks/context tools.
+        _warn(f"spec scan failed: {exc}")
+        return []

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

@@ -236,20 +236,22 @@ def _validate_jsonl(jsonl_file: Path, repo_root: Path, task_dir: Path | None = N
         if extension in _CODE_FILE_EXTENSIONS and not _is_exempt_from_code_file_warning(
             file_path, task_rel
         ):
-            print(
-                f"  {colored(f'{file_name}:{line_num}: Warning: {file_path} looks like a code file — '
-                             'implement/check.jsonl should reference spec/research docs; '
-                             'agents read code themselves', Colors.YELLOW)}"
+            warning_message = (
+                f"{file_name}:{line_num}: Warning: {file_path} looks like a code file — "
+                "implement/check.jsonl should reference spec/research docs; "
+                "agents read code themselves"
             )
+            print(f"  {colored(warning_message, Colors.YELLOW)}")
 
         if max_file_bytes:
             size = full_path.stat().st_size
             if size > max_file_bytes:
-                print(
-                    f"  {colored(f'{file_name}:{line_num}: Warning: {file_path} is {size} bytes, '
-                                 f'exceeds context_injection.max_file_bytes ({max_file_bytes}); '
-                                 'injection will truncate it', Colors.YELLOW)}"
+                warning_message = (
+                    f"{file_name}:{line_num}: Warning: {file_path} is {size} bytes, "
+                    f"exceeds context_injection.max_file_bytes ({max_file_bytes}); "
+                    "injection will truncate it"
                 )
+                print(f"  {colored(warning_message, Colors.YELLOW)}")
 
     if errors == 0:
         print(f"  {colored(f'{file_name}: ✓ ({real_entries} entries)', Colors.GREEN)}")

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

@@ -56,6 +56,7 @@ from .task_utils import (
     resolve_task_dir,
     run_task_hooks,
 )
+from .workflow_selection import DIR_WORKFLOWS, WORKFLOW_ID_RE
 
 
 # =============================================================================
@@ -254,6 +255,31 @@ def cmd_create(args: argparse.Namespace) -> int:
         # Inferred: default_package → None (no task.json yet for create)
         package = resolve_package(repo_root=repo_root)
 
+    # Validate --workflow (CLI source: fail-fast on invalid id; a missing
+    # library file only warns — it may be saved later via `trellis workflow --save`)
+    workflow_id: str | None = getattr(args, "workflow", None)
+    if workflow_id:
+        if not WORKFLOW_ID_RE.match(workflow_id):
+            print(
+                colored(
+                    f"Error: invalid workflow id '{workflow_id}' (allowed: letters, digits, '-', '_')",
+                    Colors.RED,
+                ),
+                file=sys.stderr,
+            )
+            return 1
+        workflow_md = repo_root / DIR_WORKFLOW / DIR_WORKFLOWS / f"{workflow_id}.md"
+        if not workflow_md.is_file():
+            print(
+                colored(
+                    f"Warning: {DIR_WORKFLOW}/{DIR_WORKFLOWS}/{workflow_id}.md does not exist yet; "
+                    "default workflow resolution is used until it is saved "
+                    "(trellis workflow --save).",
+                    Colors.YELLOW,
+                ),
+                file=sys.stderr,
+            )
+
     # Default assignee to current developer
     assignee = args.assignee
     if not assignee:
@@ -385,6 +411,10 @@ def cmd_create(args: argparse.Namespace) -> int:
         "notes": "",
         "meta": meta,
     }
+    # Optional per-task workflow selection: key present only when opted in,
+    # so tasks without a selection keep today's task.json shape byte-for-byte.
+    if workflow_id:
+        task_data["workflow"] = workflow_id
 
     write_json(task_json_path, task_data)
 

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

@@ -22,11 +22,12 @@ from __future__ import annotations
 
 import re
 
-from .paths import DIR_WORKFLOW, get_repo_root
+from . import workflow_selection
+from .paths import get_repo_root
 
 
 def _workflow_md_path():
-    return get_repo_root() / DIR_WORKFLOW / "workflow.md"
+    return workflow_selection.resolve_workflow_md(get_repo_root())
 
 # Match a line that *is* a platform marker: "[A, B, C]" or "[/A, B, C]"
 _MARKER_RE = re.compile(r"^\[(/?)([A-Za-z][^\[\]]*)\]\s*$")

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)