@blxzer/cursor-trellis 0.3.0 → 0.3.2

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

@@ -1,587 +1,587 @@
-#!/usr/bin/env python3
-"""
-Search durable Trellis markdown artifacts.
-
-This module is intentionally dependency-free because it is generated into user
-projects as part of the Trellis Python runtime.
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import re
-import sys
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Iterable
-
-from .paths import DIR_TASKS, DIR_WORKFLOW, DIR_WORKSPACE, get_repo_root
-
-
-MAX_SNIPPETS = 3
-VALID_CATEGORIES = {"spec", "task", "workspace"}
-VALID_KINDS = {
-    "spec",
-    "task_prd",
-    "task_design",
-    "task_implement",
-    "task_research",
-    "task_verify",
-    "task_handoff",
-    "task_artifact",
-    "workspace",
-}
-
-
-@dataclass
-class Artifact:
-    path: Path
-    rel_path: str
-    kind: str
-    category: str
-    frontmatter: dict[str, object]
-    body: str
-    body_start_line: int
-    title: str | None
-    headings: list[tuple[int, str, str]]
-
-
-@dataclass
-class FilterSpec:
-    raw: str
-    key: str
-    op: str
-    values: list[str]
-
-
-@dataclass
-class Snippet:
-    line: int
-    text: str
-    anchor: str | None = None
-
-    def to_json(self) -> dict[str, object]:
-        data: dict[str, object] = {"line": self.line, "text": self.text}
-        if self.anchor:
-            data["anchor"] = self.anchor
-        return data
-
-
-@dataclass
-class SearchResult:
-    artifact: Artifact
-    score: int
-    matched_fields: set[str] = field(default_factory=set)
-    snippets: list[Snippet] = field(default_factory=list)
-
-    def to_json(self) -> dict[str, object]:
-        return {
-            "path": self.artifact.rel_path,
-            "kind": self.artifact.kind,
-            "category": self.artifact.category,
-            "title": self.artifact.title,
-            "frontmatter": self.artifact.frontmatter,
-            "matched_fields": sorted(self.matched_fields),
-            "snippets": [snippet.to_json() for snippet in self.snippets],
-            "score": self.score,
-        }
-
-
-def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        description="Search local .trellis markdown artifacts.",
-    )
-    parser.add_argument(
-        "--query",
-        "-q",
-        default="",
-        help="Whitespace-token AND query over path, title, headings, frontmatter, and body.",
-    )
-    parser.add_argument(
-        "--filter",
-        action="append",
-        default=[],
-        help="Frontmatter filter: key=value or key~=substring. Use a|b for OR values.",
-    )
-    parser.add_argument(
-        "--kind",
-        action="append",
-        choices=sorted(VALID_KINDS),
-        default=[],
-        help="Restrict to an artifact kind. May be repeated.",
-    )
-    parser.add_argument(
-        "--category",
-        action="append",
-        choices=sorted(VALID_CATEGORIES),
-        default=[],
-        help="Restrict to an artifact category. May be repeated.",
-    )
-    parser.add_argument(
-        "--limit",
-        type=int,
-        default=20,
-        help="Maximum results to return. Use 0 for no limit.",
-    )
-    parser.add_argument(
-        "--json",
-        action="store_true",
-        help="Emit stable JSON for agents and tests.",
-    )
-    parser.add_argument(
-        "--root",
-        help="Repository root. Defaults to nearest parent containing .trellis/.",
-    )
-    return parser.parse_args(argv)
-
-
-def main(argv: list[str] | None = None) -> int:
-    args = parse_args(argv)
-    try:
-        filters = [parse_filter(raw) for raw in args.filter]
-    except ValueError as error:
-        print(f"Error: {error}", file=sys.stderr)
-        return 2
-
-    if args.limit < 0:
-        print("Error: --limit must be >= 0", file=sys.stderr)
-        return 2
-
-    repo_root = Path(args.root).resolve() if args.root else get_repo_root()
-    results = search_artifacts(
-        repo_root=repo_root,
-        query=args.query,
-        filters=filters,
-        kinds=set(args.kind),
-        categories=set(args.category),
-        limit=args.limit,
-    )
-
-    payload = {
-        "query": args.query,
-        "filters": args.filter,
-        "kinds": args.kind,
-        "categories": args.category,
-        "total": len(results),
-        "results": [result.to_json() for result in results],
-    }
-
-    if args.json:
-        print(json.dumps(payload, ensure_ascii=False, indent=2))
-    else:
-        print_human(payload)
-
-    return 0
-
-
-def search_artifacts(
-    repo_root: Path,
-    query: str,
-    filters: list[FilterSpec],
-    kinds: set[str],
-    categories: set[str],
-    limit: int,
-) -> list[SearchResult]:
-    tokens = tokenize(query)
-    results: list[SearchResult] = []
-
-    for path in iter_artifact_paths(repo_root):
-        artifact = load_artifact(path, repo_root)
-        if artifact is None:
-            continue
-        if kinds and artifact.kind not in kinds:
-            continue
-        if categories and artifact.category not in categories:
-            continue
-
-        filter_fields = matched_filter_fields(artifact, filters)
-        if filter_fields is None:
-            continue
-
-        result = score_artifact(artifact, tokens)
-        if result is None:
-            continue
-
-        result.matched_fields.update(filter_fields)
-        if filter_fields and not tokens:
-            result.score += len(filter_fields)
-        if not result.snippets:
-            result.snippets = fallback_snippets(artifact)
-        results.append(result)
-
-    results.sort(key=lambda item: (-item.score, item.artifact.rel_path))
-    if limit:
-        return results[:limit]
-    return results
-
-
-def iter_artifact_paths(repo_root: Path) -> Iterable[Path]:
-    roots = [
-        repo_root / DIR_WORKFLOW / "spec",
-        repo_root / DIR_WORKFLOW / DIR_TASKS,
-        repo_root / DIR_WORKFLOW / DIR_WORKSPACE,
-    ]
-    seen: set[Path] = set()
-    for root in roots:
-        if not root.is_dir():
-            continue
-        for path in sorted(root.rglob("*.md"), key=lambda item: item.as_posix()):
-            if not path.is_file():
-                continue
-            resolved = path.resolve()
-            if resolved in seen:
-                continue
-            seen.add(resolved)
-            yield path
-
-
-def load_artifact(path: Path, repo_root: Path) -> Artifact | None:
-    try:
-        content = path.read_text(encoding="utf-8", errors="replace")
-    except OSError:
-        return None
-
-    rel_path = to_repo_path(path, repo_root)
-    kind = classify_kind(rel_path)
-    if kind is None:
-        return None
-
-    frontmatter, body, body_start_line = split_frontmatter(content)
-    headings = extract_headings(body, body_start_line)
-    title = discover_title(frontmatter, headings)
-    category = category_for_kind(kind)
-    return Artifact(
-        path=path,
-        rel_path=rel_path,
-        kind=kind,
-        category=category,
-        frontmatter=frontmatter,
-        body=body,
-        body_start_line=body_start_line,
-        title=title,
-        headings=headings,
-    )
-
-
-def to_repo_path(path: Path, repo_root: Path) -> str:
-    try:
-        return path.resolve().relative_to(repo_root.resolve()).as_posix()
-    except ValueError:
-        return path.as_posix()
-
-
-def classify_kind(rel_path: str) -> str | None:
-    normalized = rel_path.replace("\\", "/")
-    if normalized.startswith(f"{DIR_WORKFLOW}/spec/"):
-        return "spec"
-    if normalized.startswith(f"{DIR_WORKFLOW}/{DIR_WORKSPACE}/"):
-        return "workspace"
-    if not normalized.startswith(f"{DIR_WORKFLOW}/{DIR_TASKS}/"):
-        return None
-
-    name = normalized.rsplit("/", 1)[-1]
-    if "/research/" in normalized:
-        return "task_research"
-    if name == "prd.md":
-        return "task_prd"
-    if name == "design.md":
-        return "task_design"
-    if name == "implement.md":
-        return "task_implement"
-    if name == "verify.md":
-        return "task_verify"
-    if name == "handoff.md":
-        return "task_handoff"
-    return "task_artifact"
-
-
-def category_for_kind(kind: str) -> str:
-    if kind == "spec":
-        return "spec"
-    if kind == "workspace":
-        return "workspace"
-    return "task"
-
-
-def split_frontmatter(content: str) -> tuple[dict[str, object], str, int]:
-    lines = content.splitlines()
-    if not lines or lines[0].strip() != "---":
-        return {}, content, 1
-
-    for idx in range(1, len(lines)):
-        if lines[idx].strip() == "---":
-            frontmatter_lines = lines[1:idx]
-            body_lines = lines[idx + 1 :]
-            frontmatter = parse_frontmatter(frontmatter_lines)
-            return frontmatter, "\n".join(body_lines), idx + 2
-
-    return {}, content, 1
-
-
-def parse_frontmatter(lines: list[str]) -> dict[str, object]:
-    data: dict[str, object] = {}
-    current_list_key: str | None = None
-
-    for raw_line in lines:
-        if not raw_line.strip() or raw_line.lstrip().startswith("#"):
-            continue
-        stripped = raw_line.strip()
-        if stripped.startswith("- "):
-            if current_list_key is None:
-                continue
-            value = unquote(stripped[2:].strip())
-            items = data.setdefault(current_list_key, [])
-            if isinstance(items, list):
-                items.append(value)
-            continue
-
-        if ":" not in stripped:
-            current_list_key = None
-            continue
-
-        key, value = stripped.split(":", 1)
-        key = key.strip()
-        value = strip_inline_comment(value).strip()
-        if not key:
-            current_list_key = None
-            continue
-        if value:
-            data[key] = unquote(value)
-            current_list_key = None
-        else:
-            data[key] = []
-            current_list_key = key
-
-    return data
-
-
-def strip_inline_comment(value: str) -> str:
-    in_quote: str | None = None
-    for idx, char in enumerate(value):
-        if in_quote:
-            if char == in_quote:
-                in_quote = None
-            continue
-        if char in ("'", '"'):
-            in_quote = char
-            continue
-        if char == "#" and (idx == 0 or value[idx - 1].isspace()):
-            return value[:idx]
-    return value
-
-
-def unquote(value: str) -> str:
-    if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
-        return value[1:-1]
-    return value
-
-
-def extract_headings(body: str, body_start_line: int) -> list[tuple[int, str, str]]:
-    headings: list[tuple[int, str, str]] = []
-    for offset, line in enumerate(body.splitlines()):
-        match = re.match(r"^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$", line)
-        if not match:
-            continue
-        text = normalize_space(match.group(1))
-        headings.append((body_start_line + offset, text, slugify_heading(text)))
-    return headings
-
-
-def discover_title(
-    frontmatter: dict[str, object],
-    headings: list[tuple[int, str, str]],
-) -> str | None:
-    raw_title = frontmatter.get("title")
-    if isinstance(raw_title, str) and raw_title.strip():
-        return raw_title.strip()
-    for _, heading, _ in headings:
-        return heading
-    return None
-
-
-def parse_filter(raw: str) -> FilterSpec:
-    op = "~=" if "~=" in raw else "="
-    if op not in raw:
-        raise ValueError(f"invalid filter {raw!r}; expected key=value or key~=value")
-    key, value = raw.split(op, 1)
-    key = key.strip()
-    values = [item.strip() for item in value.split("|") if item.strip()]
-    if not key or not values:
-        raise ValueError(f"invalid filter {raw!r}; expected key=value or key~=value")
-    return FilterSpec(raw=raw, key=key, op=op, values=values)
-
-
-def matched_filter_fields(
-    artifact: Artifact,
-    filters: list[FilterSpec],
-) -> set[str] | None:
-    matched: set[str] = set()
-    for item in filters:
-        raw_value = artifact.frontmatter.get(item.key)
-        values = normalized_values(raw_value)
-        if not values:
-            return None
-        if item.op == "=":
-            ok = any(value == candidate for value in values for candidate in lower_all(item.values))
-        else:
-            ok = any(candidate in value for value in values for candidate in lower_all(item.values))
-        if not ok:
-            return None
-        matched.add(f"frontmatter.{item.key}")
-    return matched
-
-
-def score_artifact(artifact: Artifact, tokens: list[str]) -> SearchResult | None:
-    if not tokens:
-        return SearchResult(artifact=artifact, score=0)
-
-    field_values = searchable_fields(artifact)
-    combined = "\n".join(value for _, value in field_values).lower()
-    if any(token not in combined for token in tokens):
-        return None
-
-    result = SearchResult(artifact=artifact, score=0)
-    for token in tokens:
-        if token in artifact.rel_path.lower():
-            result.score += 8
-            result.matched_fields.add("path")
-        if artifact.title and token in artifact.title.lower():
-            result.score += 7
-            result.matched_fields.add("title")
-        for key, value in artifact.frontmatter.items():
-            if any(token in item for item in normalized_values(value)):
-                result.score += 6
-                result.matched_fields.add(f"frontmatter.{key}")
-        if any(token in heading.lower() for _, heading, _ in artifact.headings):
-            result.score += 4
-            result.matched_fields.add("headings")
-        if token in artifact.body.lower():
-            result.score += 2
-            result.matched_fields.add("body")
-
-    result.snippets = query_snippets(artifact, tokens)
-    return result
-
-
-def searchable_fields(artifact: Artifact) -> list[tuple[str, str]]:
-    frontmatter = " ".join(flatten_frontmatter_values(artifact.frontmatter))
-    headings = " ".join(heading for _, heading, _ in artifact.headings)
-    return [
-        ("path", artifact.rel_path),
-        ("title", artifact.title or ""),
-        ("frontmatter", frontmatter),
-        ("headings", headings),
-        ("body", artifact.body),
-    ]
-
-
-def query_snippets(artifact: Artifact, tokens: list[str]) -> list[Snippet]:
-    snippets: list[Snippet] = []
-    seen_lines: set[int] = set()
-    current_anchor: str | None = None
-    heading_by_line = {line: anchor for line, _, anchor in artifact.headings}
-
-    for offset, raw_line in enumerate(artifact.body.splitlines()):
-        line_number = artifact.body_start_line + offset
-        if line_number in heading_by_line:
-            current_anchor = heading_by_line[line_number]
-        line = normalize_space(raw_line)
-        if not line:
-            continue
-        lower = line.lower()
-        if not any(token in lower for token in tokens):
-            continue
-        if line_number in seen_lines:
-            continue
-        snippets.append(Snippet(line=line_number, text=line, anchor=current_anchor))
-        seen_lines.add(line_number)
-        if len(snippets) >= MAX_SNIPPETS:
-            break
-
-    return snippets
-
-
-def fallback_snippets(artifact: Artifact) -> list[Snippet]:
-    current_anchor: str | None = None
-    heading_by_line = {line: anchor for line, _, anchor in artifact.headings}
-    for offset, raw_line in enumerate(artifact.body.splitlines()):
-        line_number = artifact.body_start_line + offset
-        if line_number in heading_by_line:
-            current_anchor = heading_by_line[line_number]
-        text = normalize_space(raw_line)
-        if text:
-            return [Snippet(line=line_number, text=text, anchor=current_anchor)]
-    return []
-
-
-def tokenize(query: str) -> list[str]:
-    return [token.lower() for token in re.findall(r"\S+", query) if token.strip()]
-
-
-def lower_all(values: Iterable[str]) -> list[str]:
-    return [value.lower() for value in values]
-
-
-def normalized_values(value: object) -> list[str]:
-    if isinstance(value, list):
-        return [str(item).lower() for item in value]
-    if value is None:
-        return []
-    return [str(value).lower()]
-
-
-def flatten_frontmatter_values(frontmatter: dict[str, object]) -> list[str]:
-    values: list[str] = []
-    for key, value in frontmatter.items():
-        values.append(key)
-        if isinstance(value, list):
-            values.extend(str(item) for item in value)
-        elif value is not None:
-            values.append(str(value))
-    return values
-
-
-def normalize_space(value: str) -> str:
-    return re.sub(r"\s+", " ", value).strip()
-
-
-def slugify_heading(value: str) -> str:
-    slug = re.sub(r"[^a-z0-9\s-]", "", value.lower())
-    return re.sub(r"[\s-]+", "-", slug).strip("-")
-
-
-def print_human(payload: dict[str, object]) -> None:
-    total = int(payload["total"])
-    noun = "artifact" if total == 1 else "artifacts"
-    print(f"Found {total} {noun}")
-    print()
-
-    results = payload["results"]
-    if not isinstance(results, list):
-        return
-
-    for idx, result in enumerate(results, start=1):
-        if not isinstance(result, dict):
-            continue
-        print(
-            f"{idx}. {result['path']} [{result['kind']}] "
-            f"score={result['score']}"
-        )
-        title = result.get("title")
-        if title:
-            print(f"   title: {title}")
-        matched = result.get("matched_fields")
-        if isinstance(matched, list) and matched:
-            print(f"   matched: {', '.join(str(item) for item in matched)}")
-        snippets = result.get("snippets")
-        if isinstance(snippets, list):
-            for snippet in snippets:
-                if not isinstance(snippet, dict):
-                    continue
-                print(f"   L{snippet.get('line')}: {snippet.get('text')}")
-
-
-if __name__ == "__main__":
-    sys.exit(main())
-
+#!/usr/bin/env python3
+"""
+Search durable Trellis markdown artifacts.
+
+This module is intentionally dependency-free because it is generated into user
+projects as part of the Trellis Python runtime.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable
+
+from .paths import DIR_TASKS, DIR_WORKFLOW, DIR_WORKSPACE, get_repo_root
+
+
+MAX_SNIPPETS = 3
+VALID_CATEGORIES = {"spec", "task", "workspace"}
+VALID_KINDS = {
+    "spec",
+    "task_prd",
+    "task_design",
+    "task_implement",
+    "task_research",
+    "task_verify",
+    "task_handoff",
+    "task_artifact",
+    "workspace",
+}
+
+
+@dataclass
+class Artifact:
+    path: Path
+    rel_path: str
+    kind: str
+    category: str
+    frontmatter: dict[str, object]
+    body: str
+    body_start_line: int
+    title: str | None
+    headings: list[tuple[int, str, str]]
+
+
+@dataclass
+class FilterSpec:
+    raw: str
+    key: str
+    op: str
+    values: list[str]
+
+
+@dataclass
+class Snippet:
+    line: int
+    text: str
+    anchor: str | None = None
+
+    def to_json(self) -> dict[str, object]:
+        data: dict[str, object] = {"line": self.line, "text": self.text}
+        if self.anchor:
+            data["anchor"] = self.anchor
+        return data
+
+
+@dataclass
+class SearchResult:
+    artifact: Artifact
+    score: int
+    matched_fields: set[str] = field(default_factory=set)
+    snippets: list[Snippet] = field(default_factory=list)
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            "path": self.artifact.rel_path,
+            "kind": self.artifact.kind,
+            "category": self.artifact.category,
+            "title": self.artifact.title,
+            "frontmatter": self.artifact.frontmatter,
+            "matched_fields": sorted(self.matched_fields),
+            "snippets": [snippet.to_json() for snippet in self.snippets],
+            "score": self.score,
+        }
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Search local .cstl markdown artifacts.",
+    )
+    parser.add_argument(
+        "--query",
+        "-q",
+        default="",
+        help="Whitespace-token AND query over path, title, headings, frontmatter, and body.",
+    )
+    parser.add_argument(
+        "--filter",
+        action="append",
+        default=[],
+        help="Frontmatter filter: key=value or key~=substring. Use a|b for OR values.",
+    )
+    parser.add_argument(
+        "--kind",
+        action="append",
+        choices=sorted(VALID_KINDS),
+        default=[],
+        help="Restrict to an artifact kind. May be repeated.",
+    )
+    parser.add_argument(
+        "--category",
+        action="append",
+        choices=sorted(VALID_CATEGORIES),
+        default=[],
+        help="Restrict to an artifact category. May be repeated.",
+    )
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=20,
+        help="Maximum results to return. Use 0 for no limit.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit stable JSON for agents and tests.",
+    )
+    parser.add_argument(
+        "--root",
+        help="Repository root. Defaults to nearest parent containing .cstl/.",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    try:
+        filters = [parse_filter(raw) for raw in args.filter]
+    except ValueError as error:
+        print(f"Error: {error}", file=sys.stderr)
+        return 2
+
+    if args.limit < 0:
+        print("Error: --limit must be >= 0", file=sys.stderr)
+        return 2
+
+    repo_root = Path(args.root).resolve() if args.root else get_repo_root()
+    results = search_artifacts(
+        repo_root=repo_root,
+        query=args.query,
+        filters=filters,
+        kinds=set(args.kind),
+        categories=set(args.category),
+        limit=args.limit,
+    )
+
+    payload = {
+        "query": args.query,
+        "filters": args.filter,
+        "kinds": args.kind,
+        "categories": args.category,
+        "total": len(results),
+        "results": [result.to_json() for result in results],
+    }
+
+    if args.json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        print_human(payload)
+
+    return 0
+
+
+def search_artifacts(
+    repo_root: Path,
+    query: str,
+    filters: list[FilterSpec],
+    kinds: set[str],
+    categories: set[str],
+    limit: int,
+) -> list[SearchResult]:
+    tokens = tokenize(query)
+    results: list[SearchResult] = []
+
+    for path in iter_artifact_paths(repo_root):
+        artifact = load_artifact(path, repo_root)
+        if artifact is None:
+            continue
+        if kinds and artifact.kind not in kinds:
+            continue
+        if categories and artifact.category not in categories:
+            continue
+
+        filter_fields = matched_filter_fields(artifact, filters)
+        if filter_fields is None:
+            continue
+
+        result = score_artifact(artifact, tokens)
+        if result is None:
+            continue
+
+        result.matched_fields.update(filter_fields)
+        if filter_fields and not tokens:
+            result.score += len(filter_fields)
+        if not result.snippets:
+            result.snippets = fallback_snippets(artifact)
+        results.append(result)
+
+    results.sort(key=lambda item: (-item.score, item.artifact.rel_path))
+    if limit:
+        return results[:limit]
+    return results
+
+
+def iter_artifact_paths(repo_root: Path) -> Iterable[Path]:
+    roots = [
+        repo_root / DIR_WORKFLOW / "spec",
+        repo_root / DIR_WORKFLOW / DIR_TASKS,
+        repo_root / DIR_WORKFLOW / DIR_WORKSPACE,
+    ]
+    seen: set[Path] = set()
+    for root in roots:
+        if not root.is_dir():
+            continue
+        for path in sorted(root.rglob("*.md"), key=lambda item: item.as_posix()):
+            if not path.is_file():
+                continue
+            resolved = path.resolve()
+            if resolved in seen:
+                continue
+            seen.add(resolved)
+            yield path
+
+
+def load_artifact(path: Path, repo_root: Path) -> Artifact | None:
+    try:
+        content = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+
+    rel_path = to_repo_path(path, repo_root)
+    kind = classify_kind(rel_path)
+    if kind is None:
+        return None
+
+    frontmatter, body, body_start_line = split_frontmatter(content)
+    headings = extract_headings(body, body_start_line)
+    title = discover_title(frontmatter, headings)
+    category = category_for_kind(kind)
+    return Artifact(
+        path=path,
+        rel_path=rel_path,
+        kind=kind,
+        category=category,
+        frontmatter=frontmatter,
+        body=body,
+        body_start_line=body_start_line,
+        title=title,
+        headings=headings,
+    )
+
+
+def to_repo_path(path: Path, repo_root: Path) -> str:
+    try:
+        return path.resolve().relative_to(repo_root.resolve()).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+def classify_kind(rel_path: str) -> str | None:
+    normalized = rel_path.replace("\\", "/")
+    if normalized.startswith(f"{DIR_WORKFLOW}/spec/"):
+        return "spec"
+    if normalized.startswith(f"{DIR_WORKFLOW}/{DIR_WORKSPACE}/"):
+        return "workspace"
+    if not normalized.startswith(f"{DIR_WORKFLOW}/{DIR_TASKS}/"):
+        return None
+
+    name = normalized.rsplit("/", 1)[-1]
+    if "/research/" in normalized:
+        return "task_research"
+    if name == "prd.md":
+        return "task_prd"
+    if name == "design.md":
+        return "task_design"
+    if name == "implement.md":
+        return "task_implement"
+    if name == "verify.md":
+        return "task_verify"
+    if name == "handoff.md":
+        return "task_handoff"
+    return "task_artifact"
+
+
+def category_for_kind(kind: str) -> str:
+    if kind == "spec":
+        return "spec"
+    if kind == "workspace":
+        return "workspace"
+    return "task"
+
+
+def split_frontmatter(content: str) -> tuple[dict[str, object], str, int]:
+    lines = content.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}, content, 1
+
+    for idx in range(1, len(lines)):
+        if lines[idx].strip() == "---":
+            frontmatter_lines = lines[1:idx]
+            body_lines = lines[idx + 1 :]
+            frontmatter = parse_frontmatter(frontmatter_lines)
+            return frontmatter, "\n".join(body_lines), idx + 2
+
+    return {}, content, 1
+
+
+def parse_frontmatter(lines: list[str]) -> dict[str, object]:
+    data: dict[str, object] = {}
+    current_list_key: str | None = None
+
+    for raw_line in lines:
+        if not raw_line.strip() or raw_line.lstrip().startswith("#"):
+            continue
+        stripped = raw_line.strip()
+        if stripped.startswith("- "):
+            if current_list_key is None:
+                continue
+            value = unquote(stripped[2:].strip())
+            items = data.setdefault(current_list_key, [])
+            if isinstance(items, list):
+                items.append(value)
+            continue
+
+        if ":" not in stripped:
+            current_list_key = None
+            continue
+
+        key, value = stripped.split(":", 1)
+        key = key.strip()
+        value = strip_inline_comment(value).strip()
+        if not key:
+            current_list_key = None
+            continue
+        if value:
+            data[key] = unquote(value)
+            current_list_key = None
+        else:
+            data[key] = []
+            current_list_key = key
+
+    return data
+
+
+def strip_inline_comment(value: str) -> str:
+    in_quote: str | None = None
+    for idx, char in enumerate(value):
+        if in_quote:
+            if char == in_quote:
+                in_quote = None
+            continue
+        if char in ("'", '"'):
+            in_quote = char
+            continue
+        if char == "#" and (idx == 0 or value[idx - 1].isspace()):
+            return value[:idx]
+    return value
+
+
+def unquote(value: str) -> str:
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+        return value[1:-1]
+    return value
+
+
+def extract_headings(body: str, body_start_line: int) -> list[tuple[int, str, str]]:
+    headings: list[tuple[int, str, str]] = []
+    for offset, line in enumerate(body.splitlines()):
+        match = re.match(r"^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$", line)
+        if not match:
+            continue
+        text = normalize_space(match.group(1))
+        headings.append((body_start_line + offset, text, slugify_heading(text)))
+    return headings
+
+
+def discover_title(
+    frontmatter: dict[str, object],
+    headings: list[tuple[int, str, str]],
+) -> str | None:
+    raw_title = frontmatter.get("title")
+    if isinstance(raw_title, str) and raw_title.strip():
+        return raw_title.strip()
+    for _, heading, _ in headings:
+        return heading
+    return None
+
+
+def parse_filter(raw: str) -> FilterSpec:
+    op = "~=" if "~=" in raw else "="
+    if op not in raw:
+        raise ValueError(f"invalid filter {raw!r}; expected key=value or key~=value")
+    key, value = raw.split(op, 1)
+    key = key.strip()
+    values = [item.strip() for item in value.split("|") if item.strip()]
+    if not key or not values:
+        raise ValueError(f"invalid filter {raw!r}; expected key=value or key~=value")
+    return FilterSpec(raw=raw, key=key, op=op, values=values)
+
+
+def matched_filter_fields(
+    artifact: Artifact,
+    filters: list[FilterSpec],
+) -> set[str] | None:
+    matched: set[str] = set()
+    for item in filters:
+        raw_value = artifact.frontmatter.get(item.key)
+        values = normalized_values(raw_value)
+        if not values:
+            return None
+        if item.op == "=":
+            ok = any(value == candidate for value in values for candidate in lower_all(item.values))
+        else:
+            ok = any(candidate in value for value in values for candidate in lower_all(item.values))
+        if not ok:
+            return None
+        matched.add(f"frontmatter.{item.key}")
+    return matched
+
+
+def score_artifact(artifact: Artifact, tokens: list[str]) -> SearchResult | None:
+    if not tokens:
+        return SearchResult(artifact=artifact, score=0)
+
+    field_values = searchable_fields(artifact)
+    combined = "\n".join(value for _, value in field_values).lower()
+    if any(token not in combined for token in tokens):
+        return None
+
+    result = SearchResult(artifact=artifact, score=0)
+    for token in tokens:
+        if token in artifact.rel_path.lower():
+            result.score += 8
+            result.matched_fields.add("path")
+        if artifact.title and token in artifact.title.lower():
+            result.score += 7
+            result.matched_fields.add("title")
+        for key, value in artifact.frontmatter.items():
+            if any(token in item for item in normalized_values(value)):
+                result.score += 6
+                result.matched_fields.add(f"frontmatter.{key}")
+        if any(token in heading.lower() for _, heading, _ in artifact.headings):
+            result.score += 4
+            result.matched_fields.add("headings")
+        if token in artifact.body.lower():
+            result.score += 2
+            result.matched_fields.add("body")
+
+    result.snippets = query_snippets(artifact, tokens)
+    return result
+
+
+def searchable_fields(artifact: Artifact) -> list[tuple[str, str]]:
+    frontmatter = " ".join(flatten_frontmatter_values(artifact.frontmatter))
+    headings = " ".join(heading for _, heading, _ in artifact.headings)
+    return [
+        ("path", artifact.rel_path),
+        ("title", artifact.title or ""),
+        ("frontmatter", frontmatter),
+        ("headings", headings),
+        ("body", artifact.body),
+    ]
+
+
+def query_snippets(artifact: Artifact, tokens: list[str]) -> list[Snippet]:
+    snippets: list[Snippet] = []
+    seen_lines: set[int] = set()
+    current_anchor: str | None = None
+    heading_by_line = {line: anchor for line, _, anchor in artifact.headings}
+
+    for offset, raw_line in enumerate(artifact.body.splitlines()):
+        line_number = artifact.body_start_line + offset
+        if line_number in heading_by_line:
+            current_anchor = heading_by_line[line_number]
+        line = normalize_space(raw_line)
+        if not line:
+            continue
+        lower = line.lower()
+        if not any(token in lower for token in tokens):
+            continue
+        if line_number in seen_lines:
+            continue
+        snippets.append(Snippet(line=line_number, text=line, anchor=current_anchor))
+        seen_lines.add(line_number)
+        if len(snippets) >= MAX_SNIPPETS:
+            break
+
+    return snippets
+
+
+def fallback_snippets(artifact: Artifact) -> list[Snippet]:
+    current_anchor: str | None = None
+    heading_by_line = {line: anchor for line, _, anchor in artifact.headings}
+    for offset, raw_line in enumerate(artifact.body.splitlines()):
+        line_number = artifact.body_start_line + offset
+        if line_number in heading_by_line:
+            current_anchor = heading_by_line[line_number]
+        text = normalize_space(raw_line)
+        if text:
+            return [Snippet(line=line_number, text=text, anchor=current_anchor)]
+    return []
+
+
+def tokenize(query: str) -> list[str]:
+    return [token.lower() for token in re.findall(r"\S+", query) if token.strip()]
+
+
+def lower_all(values: Iterable[str]) -> list[str]:
+    return [value.lower() for value in values]
+
+
+def normalized_values(value: object) -> list[str]:
+    if isinstance(value, list):
+        return [str(item).lower() for item in value]
+    if value is None:
+        return []
+    return [str(value).lower()]
+
+
+def flatten_frontmatter_values(frontmatter: dict[str, object]) -> list[str]:
+    values: list[str] = []
+    for key, value in frontmatter.items():
+        values.append(key)
+        if isinstance(value, list):
+            values.extend(str(item) for item in value)
+        elif value is not None:
+            values.append(str(value))
+    return values
+
+
+def normalize_space(value: str) -> str:
+    return re.sub(r"\s+", " ", value).strip()
+
+
+def slugify_heading(value: str) -> str:
+    slug = re.sub(r"[^a-z0-9\s-]", "", value.lower())
+    return re.sub(r"[\s-]+", "-", slug).strip("-")
+
+
+def print_human(payload: dict[str, object]) -> None:
+    total = int(payload["total"])
+    noun = "artifact" if total == 1 else "artifacts"
+    print(f"Found {total} {noun}")
+    print()
+
+    results = payload["results"]
+    if not isinstance(results, list):
+        return
+
+    for idx, result in enumerate(results, start=1):
+        if not isinstance(result, dict):
+            continue
+        print(
+            f"{idx}. {result['path']} [{result['kind']}] "
+            f"score={result['score']}"
+        )
+        title = result.get("title")
+        if title:
+            print(f"   title: {title}")
+        matched = result.get("matched_fields")
+        if isinstance(matched, list) and matched:
+            print(f"   matched: {', '.join(str(item) for item in matched)}")
+        snippets = result.get("snippets")
+        if isinstance(snippets, list):
+            for snippet in snippets:
+                if not isinstance(snippet, dict):
+                    continue
+                print(f"   L{snippet.get('line')}: {snippet.get('text')}")
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+