@mindfoldhq/trellis 0.5.0-beta.10 → 0.5.0-beta.12

package/dist/templates/markdown/spec/guides/cross-platform-thinking-guide.md.txt

@@ -69,6 +69,30 @@ subprocess.run(["python3", "other_script.py"])
 subprocess.run([sys.executable, "other_script.py"])
 ```
 
+**Rule 4**: Don't assume the Python version your AI CLI uses matches your shell's `python3`. Your terminal may resolve `python3` → 3.11 (via homebrew/pyenv), but AI CLI hosts often spawn hook subprocesses with a minimal PATH that resolves `python3` → the system Python (3.9 on macOS). Any `.py` file run as an AI-CLI hook must be written for the lowest plausible Python version.
+
+Concrete failure: PEP 604 union syntax (`str | None`) requires Python 3.10+. If your hook file uses it, start with `from __future__ import annotations` so annotations become lazy strings and work on Python 3.7+:
+
+```python
+#!/usr/bin/env python3
+"""My hook."""
+from __future__ import annotations     # REQUIRED for PEP 604 annotations
+
+def handler(x: str | None) -> dict | None:   # OK — lazy annotation
+    ...
+```
+
+```python
+# BAD — crashes on Python < 3.10:
+#   TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'
+def handler(x: str | None) -> dict | None:
+    ...
+```
+
+Note: `from __future__ import annotations` only covers **annotations**. Runtime expressions like `isinstance(x, int | str)` still require Python 3.10+. Avoid them in hook scripts.
+
+Applies to anything the AI CLI executes as a hook: `match/case` statements (3.10+), `tomllib` (3.11+), `ExceptionGroup` / `except*` (3.11+) — all crash on older Python regardless of `__future__`.
+
 ### 2. Path Handling
 
 | Assumption | macOS/Linux | Windows |

package/dist/templates/opencode/agents/trellis-implement.md

@@ -23,12 +23,15 @@ Otherwise, load context yourself:
 
 1. Read `.trellis/.current-task` → get task directory (e.g., `.trellis/tasks/xxx`)
 2. Read `{task_dir}/implement.jsonl`
-3. For each entry in JSONL:
-   - If `path` is a file → Read it
-   - If `path` is a directory → Read all `.md` files in it
+3. For each entry in JSONL (JSON object per line):
+   - Skip rows without a `"file"` field (e.g. `{"_example": "..."}` seed rows)
+   - If `file` points at a file → Read it
+   - If `file` ends with `/` (directory) → Read all `.md` files in it
 4. Read `{task_dir}/prd.md` for requirements
 5. Read `{task_dir}/info.md` for technical design (if exists)
 
+**If `implement.jsonl` has no curated entries (only a seed row, or the file is missing)**: read `prd.md` to understand the task domain, then decide which specs apply based on `.trellis/spec/` layout. You can list available specs with `python3 ./.trellis/scripts/get_context.py --mode packages`. Do not block on the missing jsonl — proceed with prd-only context plus your own spec judgment.
+
 Then proceed with the workflow below using the loaded context.
 
 ---

package/dist/templates/opencode/plugins/session-start.js

@@ -15,6 +15,33 @@ import { TrellisContext, contextCollector, debugLog } from "../lib/trellis-conte
 const PYTHON_CMD = platform() === "win32" ? "python" : "python3"
 
 
+/**
+ * Return true iff jsonl has at least one row with a `file` field.
+ * A freshly seeded jsonl only contains a `{"_example": ...}` row (no `file`
+ * key) — that is NOT "ready". Readiness requires at least one curated entry.
+ * Matches the contract used by `shared-hooks/inject-subagent-context.py`.
+ */
+function hasCuratedJsonlEntry(jsonlPath) {
+  try {
+    const content = readFileSync(jsonlPath, "utf-8")
+    for (const rawLine of content.split(/\r?\n/)) {
+      const line = rawLine.trim()
+      if (!line) continue
+      try {
+        const row = JSON.parse(line)
+        if (row && typeof row === "object" && typeof row.file === "string" && row.file) {
+          return true
+        }
+      } catch {
+        // Ignore malformed line — move on.
+      }
+    }
+  } catch {
+    return false
+  }
+  return false
+}
+
 /**
  * Check current task status and return structured status string.
  * JavaScript equivalent of _get_task_status in Claude's session-start.py.
@@ -52,27 +79,20 @@ function getTaskStatus(ctx) {
   let hasContext = false
   for (const jsonlName of ["implement.jsonl", "check.jsonl"]) {
     const jsonlPath = join(taskDir, jsonlName)
-    if (existsSync(jsonlPath)) {
-      try {
-        const st = statSync(jsonlPath)
-        if (st.size > 0) {
-          hasContext = true
-          break
-        }
-      } catch {
-        // Ignore stat errors
-      }
+    if (existsSync(jsonlPath) && hasCuratedJsonlEntry(jsonlPath)) {
+      hasContext = true
+      break
     }
   }
 
   const hasPrd = existsSync(join(taskDir, "prd.md"))
 
   if (!hasPrd) {
-    return `Status: NOT READY\nTask: ${taskTitle}\nMissing: prd.md not created\nNext: Write PRD, then research → init-context → start`
+    return `Status: NOT READY\nTask: ${taskTitle}\nMissing: prd.md not created\nNext: Write PRD (see workflow.md Phase 1.1) then curate implement.jsonl per Phase 1.3`
   }
 
   if (!hasContext) {
-    return `Status: NOT READY\nTask: ${taskTitle}\nMissing: Context not configured (no jsonl files)\nNext: Complete Phase 2 (research → init-context → start) before implementing`
+    return `Status: NOT READY\nTask: ${taskTitle}\nMissing: implement.jsonl / check.jsonl missing or empty\nNext: Curate entries per workflow.md Phase 1.3 (spec + research files only), then \`task.py start\``
   }
 
   return `Status: READY\nTask: ${taskTitle}\nNext: Continue with implement or check`

package/dist/templates/shared-hooks/inject-subagent-context.py

@@ -19,6 +19,7 @@ Context Source: .trellis/.current-task points to task directory
 - info.md         - Technical design
 - codex-review-output.txt - Code Review results
 """
+from __future__ import annotations
 
 # IMPORTANT: Suppress all warnings FIRST
 import warnings
@@ -31,7 +32,7 @@ from pathlib import Path
 
 # IMPORTANT: Force stdout to use UTF-8 on Windows
 # This fixes UnicodeEncodeError when outputting non-ASCII characters
-if sys.platform == "win32":
+if sys.platform.startswith("win"):
     import io as _io
     if hasattr(sys.stdout, "reconfigure"):
         sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
@@ -167,15 +168,27 @@ def read_jsonl_entries(base_path: str, jsonl_path: str) -> list[tuple[str, str]]
     Schema:
         {"file": "path/to/file.md", "reason": "..."}
         {"file": "path/to/dir/", "type": "directory", "reason": "..."}
+        {"_example": "..."}          # seed row — skipped (no `file` field)
+
+    Rows without a ``file`` field (e.g. the self-describing seed line written
+    by ``task.py create`` before the agent has curated entries) are skipped
+    silently. If the resulting entry list is empty, a stderr warning is
+    emitted so the operator can debug missing context.
 
     Returns:
         [(path, content), ...]
     """
     full_path = os.path.join(base_path, jsonl_path)
     if not os.path.exists(full_path):
+        print(
+            f"[inject-subagent-context] WARN: {jsonl_path} not found — "
+            f"sub-agent will receive only prd.md",
+            file=sys.stderr,
+        )
         return []
 
     results = []
+    saw_real_entry = False
     try:
         with open(full_path, "r", encoding="utf-8") as f:
             for line in f:
@@ -188,8 +201,10 @@ def read_jsonl_entries(base_path: str, jsonl_path: str) -> list[tuple[str, str]]
                     entry_type = item.get("type", "file")
 
                     if not file_path:
+                        # Seed / comment row — skip silently
                         continue
 
+                    saw_real_entry = True
                     if entry_type == "directory":
                         # Read all .md files in directory
                         dir_contents = read_directory_contents(base_path, file_path)
@@ -204,6 +219,14 @@ def read_jsonl_entries(base_path: str, jsonl_path: str) -> list[tuple[str, str]]
     except Exception:
         pass
 
+    if not saw_real_entry:
+        print(
+            f"[inject-subagent-context] WARN: {jsonl_path} has no curated "
+            f"entries (only seed / empty) — sub-agent will receive only "
+            f"prd.md. See workflow.md Phase 1.3 for curation guidance.",
+            file=sys.stderr,
+        )
+
     return results
 
 
@@ -391,7 +414,11 @@ Finish checklist and requirements:
 def get_research_context(repo_root: str, task_dir: str | None) -> str:
     """
     Context for Research Agent — project structure overview for spec directories.
+
+    `task_dir` kept for signature parity with get_implement_context / get_check_context
+    so the dispatcher can call them uniformly.
     """
+    _ = task_dir
     context_parts = []
 
     # 1. Project structure overview (dynamically discover spec directories)

package/dist/templates/shared-hooks/session-start.py

@@ -3,6 +3,7 @@
 """
 Session Start Hook - Inject structured context
 """
+from __future__ import annotations
 
 # IMPORTANT: Suppress all warnings FIRST
 import warnings
@@ -17,7 +18,7 @@ from pathlib import Path
 
 # IMPORTANT: Force stdout to use UTF-8 on Windows
 # This fixes UnicodeEncodeError when outputting non-ASCII characters
-if sys.platform == "win32":
+if sys.platform.startswith("win"):
     import io as _io
     if hasattr(sys.stdout, "reconfigure"):
         sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
@@ -26,6 +27,29 @@ if sys.platform == "win32":
 
 
 
+def _has_curated_jsonl_entry(jsonl_path: Path) -> bool:
+    """Return True iff jsonl has at least one row with a ``file`` field.
+
+    A freshly seeded jsonl only contains a ``{"_example": ...}`` row (no
+    ``file`` key) — that is NOT "ready". Readiness requires at least one
+    curated entry. Matches the contract used by ``inject-subagent-context.py``.
+    """
+    try:
+        for line in jsonl_path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                row = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(row, dict) and row.get("file"):
+                return True
+    except (OSError, UnicodeDecodeError):
+        return False
+    return False
+
+
 def should_skip_injection() -> bool:
     """Check if any platform's non-interactive flag is set."""
     non_interactive_vars = [
@@ -169,11 +193,25 @@ def _get_task_status(trellis_dir: Path) -> str:
             "inline in the main session. Findings go to `{task_dir}/research/*.md`; PRD only links to them."
         )
 
-    # Case 5: PRD ready — enter Execute phase
+    # Case 4b: PRD exists but implement.jsonl has only seed (no curated entries) — Phase 1.3 gate
+    implement_jsonl = task_dir / "implement.jsonl"
+    if implement_jsonl.is_file() and not _has_curated_jsonl_entry(implement_jsonl):
+        return (
+            f"Status: PLANNING (Phase 1.3)\nTask: {task_title}\n"
+            "Next-Action: Curate `implement.jsonl` and `check.jsonl` with the spec + research files "
+            "the Phase 2 sub-agents will need. Only spec paths (`.trellis/spec/**/*.md`) and research "
+            "files (`{TASK_DIR}/research/*.md`) — no code paths. Run "
+            "`python3 ./.trellis/scripts/get_context.py --mode packages` to list available specs, "
+            "then edit the jsonl files or use `python3 ./.trellis/scripts/task.py add-context`. "
+            "See `.trellis/workflow.md` Phase 1.3 for details."
+        )
+
+    # Case 5: PRD + curated jsonl (or agent-less platform with no jsonl) — enter Execute phase
     return (
         f"Status: READY\nTask: {task_title}\n"
-        "Next-Action: Load skill `trellis-before-dev` to read relevant specs, "
-        "then spawn `trellis-implement` sub-agent via the Task tool. "
+        "Next-Action: Follow Phase 2.1 for your platform. For agent-capable platforms, "
+        "spawn `trellis-implement` via the Task tool; if you stay in the main session, "
+        "load `trellis-before-dev` before writing code. "
         "After implementation, spawn `trellis-check` sub-agent for quality verification.\n"
         "Sub-agent roster: `trellis-implement` (writes code), `trellis-check` (verifies + self-fixes), "
         "`trellis-research` (persists findings to `research/*.md` — use when you'd otherwise do "

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

@@ -3,225 +3,29 @@
 Task JSONL context management.
 
 Provides:
-    cmd_init_context  - Initialize JSONL context files for a task
     cmd_add_context   - Add entry to JSONL context file
     cmd_validate      - Validate JSONL context files
     cmd_list_context  - List JSONL context entries
+
+Note:
+    ``cmd_init_context`` was removed in v0.5.0-beta.12. JSONL context files
+    are now seeded at ``task.py create`` time with a self-describing
+    ``_example`` line; the AI agent curates real entries during Phase 1.3 of
+    the workflow. See ``.trellis/workflow.md`` Phase 1.3 for the current
+    instructions.
 """
 
 from __future__ import annotations
 
 import argparse
 import json
-import sys
 from pathlib import Path
 
-from .cli_adapter import get_cli_adapter, get_cli_adapter_auto
-from .config import (
-    get_packages,
-    is_monorepo,
-    resolve_package,
-    validate_package,
-)
-from .io import read_json, write_json
 from .log import Colors, colored
-from .paths import (
-    DIR_SPEC,
-    DIR_WORKFLOW,
-    FILE_TASK_JSON,
-    get_repo_root,
-)
+from .paths import get_repo_root
 from .task_utils import resolve_task_dir
 
 
-# =============================================================================
-# JSONL Default Content Generators
-# =============================================================================
-
-def get_implement_base() -> list[dict]:
-    """Get base implement context entries."""
-    return [
-        {"file": f"{DIR_WORKFLOW}/workflow.md", "reason": "Project workflow and conventions"},
-    ]
-
-
-def get_implement_backend(package: str | None = None) -> list[dict]:
-    """Get backend implement context entries."""
-    spec_base = f"{DIR_SPEC}/{package}" if package else DIR_SPEC
-    return [
-        {"file": f"{DIR_WORKFLOW}/{spec_base}/backend/index.md", "reason": "Backend development guide"},
-    ]
-
-
-def get_implement_frontend(package: str | None = None) -> list[dict]:
-    """Get frontend implement context entries."""
-    spec_base = f"{DIR_SPEC}/{package}" if package else DIR_SPEC
-    return [
-        {"file": f"{DIR_WORKFLOW}/{spec_base}/frontend/index.md", "reason": "Frontend development guide"},
-    ]
-
-
-def get_check_context(repo_root: Path, platform: str | None = None) -> list[dict]:
-    """Get check context entries.
-
-    Args:
-        repo_root: Project root directory.
-        platform: Explicit platform override (e.g. "codex", "kiro"). When
-            provided, skip filesystem auto-detection and use this platform
-            directly. Caller (e.g. `cmd_init_context`) passes the
-            `--platform` CLI argument, which itself is substituted from
-            `{{CLI_FLAG}}` in skill/command templates rendered per platform.
-            Falls back to `get_cli_adapter_auto` when omitted (CLI-direct
-            users).
-    """
-    if platform:
-        adapter = get_cli_adapter(platform)
-    else:
-        adapter = get_cli_adapter_auto(repo_root)
-
-    return [
-        {"file": adapter.get_trellis_command_path("finish-work"), "reason": "Finish work checklist"},
-        {"file": adapter.get_trellis_command_path("check"), "reason": "Code quality check spec"},
-    ]
-
-
-def _write_jsonl(path: Path, entries: list[dict]) -> None:
-    """Write entries to JSONL file."""
-    lines = [json.dumps(entry, ensure_ascii=False) for entry in entries]
-    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
-
-
-# =============================================================================
-# Command: init-context
-# =============================================================================
-
-def cmd_init_context(args: argparse.Namespace) -> int:
-    """Initialize JSONL context files for a task."""
-    repo_root = get_repo_root()
-    target_dir = resolve_task_dir(args.dir, repo_root)
-    dev_type = args.type
-
-    if not dev_type:
-        print(colored("Error: Missing arguments", Colors.RED))
-        print("Usage: python3 task.py init-context <task-dir> <dev_type>")
-        print("  dev_type: backend | frontend | fullstack | test | docs")
-        return 1
-
-    if not target_dir.is_dir():
-        print(colored(f"Error: Directory not found: {target_dir}", Colors.RED))
-        return 1
-
-    # Resolve package: --package CLI → task.json.package → default_package
-    cli_package: str | None = getattr(args, "package", None)
-    package: str | None = None
-    if not is_monorepo(repo_root):
-        # Single-repo: ignore --package, no package prefix
-        if cli_package:
-            print(colored("Warning: --package ignored in single-repo project", Colors.YELLOW), file=sys.stderr)
-    elif cli_package:
-        if not validate_package(cli_package, repo_root):
-            packages = get_packages(repo_root)
-            available = ", ".join(sorted(packages.keys())) if packages else "(none)"
-            print(colored(f"Error: unknown package '{cli_package}'. Available: {available}", Colors.RED), file=sys.stderr)
-            return 1
-        package = cli_package
-    else:
-        # Read task.json.package as inferred source
-        task_json_path = target_dir / FILE_TASK_JSON
-        task_pkg_value = None
-        if task_json_path.is_file():
-            task_data = read_json(task_json_path)
-            if isinstance(task_data, dict):
-                task_pkg_value = task_data.get("package")
-        # Only pass string values to resolve_package (guard against malformed JSON)
-        task_package = task_pkg_value if isinstance(task_pkg_value, str) else None
-        package = resolve_package(task_package=task_package, repo_root=repo_root)
-
-        # Monorepo fallback prohibition
-        if package is None:
-            packages = get_packages(repo_root)
-            available = ", ".join(sorted(packages.keys())) if packages else "(none)"
-            print(colored(
-                f"Error: monorepo project requires --package (or set default_package in config.yaml). Available: {available}",
-                Colors.RED,
-            ), file=sys.stderr)
-            return 1
-
-    print(colored("=== Initializing Agent Context Files ===", Colors.BLUE))
-    print(f"Target dir: {target_dir}")
-    print(f"Dev type: {dev_type}")
-    if package:
-        print(f"Package: {package}")
-    print()
-
-    # implement.jsonl
-    print(colored("Creating implement.jsonl...", Colors.CYAN))
-    implement_entries = get_implement_base()
-    if dev_type in ("backend", "test"):
-        implement_entries.extend(get_implement_backend(package))
-    elif dev_type == "frontend":
-        implement_entries.extend(get_implement_frontend(package))
-    elif dev_type == "fullstack":
-        implement_entries.extend(get_implement_backend(package))
-        implement_entries.extend(get_implement_frontend(package))
-
-    implement_file = target_dir / "implement.jsonl"
-    _write_jsonl(implement_file, implement_entries)
-    print(f"  {colored('✓', Colors.GREEN)} {len(implement_entries)} entries")
-
-    # check.jsonl
-    platform: str | None = getattr(args, "platform", None)
-    print(colored("Creating check.jsonl...", Colors.CYAN))
-    check_entries = get_check_context(repo_root, platform=platform)
-    check_file = target_dir / "check.jsonl"
-    _write_jsonl(check_file, check_entries)
-    print(f"  {colored('✓', Colors.GREEN)} {len(check_entries)} entries")
-
-    # Update task.json dev_type and package
-    task_json_path = target_dir / FILE_TASK_JSON
-    if task_json_path.is_file():
-        task_data = read_json(task_json_path)
-        if isinstance(task_data, dict):
-            task_data["dev_type"] = dev_type
-            task_data["package"] = package  # Always sync to match resolved value
-            write_json(task_json_path, task_data)
-
-    print()
-    print(colored("✓ All context files created", Colors.GREEN))
-    print()
-
-    # Show what was auto-injected
-    all_injected = [e["file"] for e in implement_entries]
-    print(colored("Auto-injected (defaults only):", Colors.YELLOW))
-    for f in all_injected:
-        print(f"  - {f}")
-    print()
-
-    # Scan spec directory for available spec files the AI should consider
-    spec_base = repo_root / DIR_WORKFLOW / DIR_SPEC
-    if package:
-        spec_base = spec_base / package
-    available_specs: list[str] = []
-    if spec_base.is_dir():
-        for md_file in sorted(spec_base.rglob("*.md")):
-            rel = str(md_file.relative_to(repo_root))
-            if rel not in all_injected:
-                available_specs.append(rel)
-
-    if available_specs:
-        print(colored("Available spec files (not yet injected):", Colors.BLUE))
-        for spec in available_specs:
-            print(f"  - {spec}")
-        print()
-
-    print(colored("Next steps:", Colors.BLUE))
-    print("  1. Review the spec files above and add relevant ones for your task:")
-    print(f"     python3 task.py add-context <dir> implement <spec-path> \"<reason>\"")
-    print("  2. Set as current: python3 task.py start <dir>")
-
-    return 0
-
-
 # =============================================================================
 # Command: add-context
 # =============================================================================
@@ -309,7 +113,11 @@ def cmd_validate(args: argparse.Namespace) -> int:
 
 
 def _validate_jsonl(jsonl_file: Path, repo_root: Path) -> int:
-    """Validate a single JSONL file."""
+    """Validate a single JSONL file.
+
+    Seed rows (no ``file`` field — typically ``{"_example": "..."}``) are
+    skipped silently; they are self-describing comments, not real entries.
+    """
     file_name = jsonl_file.name
     errors = 0
 
@@ -318,6 +126,7 @@ def _validate_jsonl(jsonl_file: Path, repo_root: Path) -> int:
         return 0
 
     line_num = 0
+    real_entries = 0
     for line in jsonl_file.read_text(encoding="utf-8").splitlines():
         line_num += 1
         if not line.strip():
@@ -334,10 +143,10 @@ def _validate_jsonl(jsonl_file: Path, repo_root: Path) -> int:
         entry_type = data.get("type", "file")
 
         if not file_path:
-            print(f"  {colored(f'{file_name}:{line_num}: Missing file field', Colors.RED)}")
-            errors += 1
+            # Seed / comment row — skip silently
             continue
 
+        real_entries += 1
         full_path = repo_root / file_path
         if entry_type == "directory":
             if not full_path.is_dir():
@@ -349,7 +158,7 @@ def _validate_jsonl(jsonl_file: Path, repo_root: Path) -> int:
                 errors += 1
 
     if errors == 0:
-        print(f"  {colored(f'{file_name}: ✓ ({line_num} entries)', Colors.GREEN)}")
+        print(f"  {colored(f'{file_name}: ✓ ({real_entries} entries)', Colors.GREEN)}")
     else:
         print(f"  {colored(f'{file_name}: ✗ ({errors} errors)', Colors.RED)}")
 
@@ -380,6 +189,7 @@ def cmd_list_context(args: argparse.Namespace) -> int:
         print(colored(f"[{jsonl_name}]", Colors.CYAN))
 
         count = 0
+        seed_only = True
         for line in jsonl_file.read_text(encoding="utf-8").splitlines():
             if not line.strip():
                 continue
@@ -389,8 +199,13 @@ def cmd_list_context(args: argparse.Namespace) -> int:
             except json.JSONDecodeError:
                 continue
 
+            file_path = data.get("file")
+            if not file_path:
+                # Seed / comment row — don't count as a real entry
+                continue
+            seed_only = False
+
             count += 1
-            file_path = data.get("file", "?")
             entry_type = data.get("type", "file")
             reason = data.get("reason", "-")
 
@@ -400,6 +215,9 @@ def cmd_list_context(args: argparse.Namespace) -> int:
                 print(f"  {colored(f'{count}.', Colors.GREEN)} {file_path}")
             print(f"     {colored('→', Colors.YELLOW)} {reason}")
 
+        if seed_only:
+            print(f"  {colored('(no curated entries yet — only seed row)', Colors.YELLOW)}")
+
         print()
 
     return 0