@blulotus/trellis 0.7.0 → 0.7.2

package/dist/templates/shared-hooks/inject-shell-session-context.py

@@ -1,292 +0,0 @@
-#!/usr/bin/env python3
-"""Pre-shell hook: bridge the host's session identity into task.py.
-
-No researched platform exports a session id into its shell tool's child
-process, but every hook-capable one puts that id on hook stdin. So the hook
-that fires just before a shell command writes a short-lived runtime ticket
-whenever the pending command calls `task.py start/current/finish`, and the
-task script consumes it when it has no native session environment.
-
-Registered on whichever pre-shell event the host provides — Cursor's
-`beforeShellExecution`, Claude-shaped `PreToolUse`, Gemini's `BeforeTool` —
-which is why the only thing here that knows about payload variation is
-`_pending_shell_command`.
-"""
-from __future__ import annotations
-
-import hashlib
-import json
-import os
-import shlex
-import sys
-import time
-from pathlib import Path
-from typing import Any
-
-# Hook hosts send UTF-8 JSON regardless of the process locale.
-_stdin_reconfigure = getattr(sys.stdin, "reconfigure", None)
-if callable(_stdin_reconfigure):
-    try:
-        _stdin_reconfigure(encoding="utf-8", errors="replace")
-    except (OSError, ValueError):
-        pass
-
-
-DIR_WORKFLOW = ".trellis"
-DIR_RUNTIME = ".runtime"
-DIR_SHELL_TICKETS = "shell-tickets"
-SESSION_SUBCOMMANDS = {"start", "current", "finish"}
-TICKET_TTL_SECONDS = 30
-CONTEXT_IDENTITY_KEYS = (
-    "session_id",
-    "sessionId",
-    "sessionID",
-    "conversation_id",
-    "conversationId",
-    "conversationID",
-    "transcript_path",
-    "transcriptPath",
-    "transcript",
-)
-# Tool-call payloads nest the command one level down; same casing spread as
-# CONTEXT_IDENTITY_KEYS above.
-TOOL_INPUT_KEYS = ("tool_input", "toolInput")
-# Answering a shell-execution event with an explicit allow is what keeps
-# Cursor from re-prompting for a command Trellis itself asked for. Tool-call
-# hosts read a different response schema, so they get no answer at all rather
-# than a key they would have to ignore.
-SHELL_EVENT_RESPONSE = {"permission": "allow"}
-
-
-def _string_value(value: Any) -> str | None:
-    if isinstance(value, str):
-        stripped = value.strip()
-        return stripped or None
-    return None
-
-
-def _resolve_trellis_root(hook_input: dict[str, Any]) -> Path | None:
-    """Locate the project root, trying the payload cwd and then our own.
-
-    Hosts disagree about what `cwd` means. CodeBuddy IDE 4.10.4 sends `"/"` for
-    every PreToolUse event, so trusting the payload alone finds no `.trellis`
-    and the bridge silently does nothing — the hook is invoked, writes no
-    ticket, and `task.py start` degrades. Observed with a wildcard probe:
-
-        {"cwd": "/", "tool_name": "Bash", "tool_input": {"command": "ls …"}}
-
-    The hook's own cwd is reliable where the payload is not: hosts launch it
-    from the project root, which is why a relative `command` in settings.json
-    resolves at all. Try the payload first (it is right on hosts that set it,
-    and survives a host that runs hooks from elsewhere), then fall back.
-    """
-    candidates: list[Path] = []
-    payload_cwd = _string_value(hook_input.get("cwd"))
-    if payload_cwd:
-        candidates.append(Path(payload_cwd))
-    try:
-        candidates.append(Path(os.getcwd()))
-    except OSError:
-        pass
-
-    for candidate in candidates:
-        root = _find_trellis_root(candidate)
-        if root is not None:
-            return root
-    return None
-
-
-def _find_trellis_root(start: Path) -> Path | None:
-    current = start.resolve()
-    while True:
-        if (current / DIR_WORKFLOW).is_dir():
-            return current
-        if current == current.parent:
-            return None
-        current = current.parent
-
-
-def _runtime_ticket_dir(root: Path) -> Path:
-    return root / DIR_WORKFLOW / DIR_RUNTIME / DIR_SHELL_TICKETS
-
-
-def _pending_shell_command(hook_input: dict[str, Any]) -> tuple[str, dict[str, Any] | None]:
-    """Read the pending shell command out of either hook payload shape.
-
-    Returns the command plus the response envelope that shape expects:
-
-    - shell-execution event (Cursor `beforeShellExecution`) — the command sits
-      at the top level and the host wants a permission decision back;
-    - tool-call event (`PreToolUse`, `BeforeTool`) — the command sits under
-      `tool_input`, and the host reads a schema this hook has no opinion on.
-
-    An ordered fallback, not a platform switch: a third payload shape extends
-    the same function. Anything else yields ("", None) so main() no-ops.
-    """
-    command = _string_value(hook_input.get("command"))
-    if command:
-        return command, SHELL_EVENT_RESPONSE
-
-    for key in TOOL_INPUT_KEYS:
-        tool_input = hook_input.get(key)
-        if not isinstance(tool_input, dict):
-            continue
-        command = _string_value(tool_input.get("command"))
-        if command:
-            return command, None
-
-    return "", None
-
-
-def _host_platform_name() -> str | None:
-    """Name the host from the config directory this hook was installed into.
-
-    Every platform puts its hooks under its own dotted directory
-    (`.cursor/hooks/`, `.factory/hooks/`, …), so the deepest dotted path
-    segment identifies the host without a table of platform names here. It
-    matters because the context key must agree with the one the platform's
-    other hooks compute — a ticket keyed differently would write a session
-    file no later hook ever reads.
-    """
-    for part in reversed(Path(sys.argv[0]).parts):
-        if part.startswith(".") and part not in (".", "..") and len(part) > 1:
-            return part[1:]
-    return None
-
-
-def _load_active_task_resolver(root: Path):
-    scripts_dir = root / DIR_WORKFLOW / "scripts"
-    if str(scripts_dir) not in sys.path:
-        sys.path.insert(0, str(scripts_dir))
-    from common.active_task import resolve_context_key  # type: ignore[import-not-found]
-
-    return resolve_context_key
-
-
-def _extract_task_subcommands(command: str) -> list[dict[str, str]]:
-    try:
-        tokens = shlex.split(command, posix=os.name != "nt")
-    except ValueError:
-        return []
-
-    subcommands: list[dict[str, str]] = []
-    for index, token in enumerate(tokens[:-1]):
-        if Path(token.strip("\"'")).name != "task.py":
-            continue
-        name = tokens[index + 1]
-        if name not in SESSION_SUBCOMMANDS:
-            continue
-        item = {"name": name}
-        if name == "start" and index + 2 < len(tokens):
-            item["task_ref"] = tokens[index + 2]
-        subcommands.append(item)
-    return subcommands
-
-
-def _cleanup_expired_tickets(ticket_dir: Path, now: float) -> None:
-    if not ticket_dir.is_dir():
-        return
-    for ticket_path in ticket_dir.glob("*.json"):
-        try:
-            data = json.loads(ticket_path.read_text(encoding="utf-8"))
-        except (json.JSONDecodeError, OSError):
-            continue
-        expires_at = data.get("expires_at_epoch")
-        if isinstance(expires_at, (int, float)) and expires_at < now:
-            try:
-                ticket_path.unlink()
-            except OSError:
-                pass
-
-
-def _has_context_identity(hook_input: dict[str, Any]) -> bool:
-    return any(_string_value(hook_input.get(key)) for key in CONTEXT_IDENTITY_KEYS)
-
-
-def _write_ticket(
-    root: Path,
-    hook_input: dict[str, Any],
-    context_key: str,
-    command: str,
-    platform_name: str | None,
-    subcommands: list[dict[str, str]],
-) -> None:
-    now = time.time()
-    ticket_dir = _runtime_ticket_dir(root)
-    ticket_dir.mkdir(parents=True, exist_ok=True)
-    _cleanup_expired_tickets(ticket_dir, now)
-
-    digest = hashlib.sha256(
-        f"{context_key}\0{command}\0{now}".encode("utf-8"),
-    ).hexdigest()[:16]
-    ticket_path = ticket_dir / f"{int(now * 1000)}-{digest}.json"
-
-    payload = {
-        # Debugging metadata. The consumer accepts a ticket on freshness, repo
-        # and subcommand — never on this field.
-        "platform": platform_name,
-        "context_key": context_key,
-        "conversation_id": _string_value(hook_input.get("conversation_id")),
-        "session_id": _string_value(hook_input.get("session_id")),
-        "generation_id": _string_value(hook_input.get("generation_id")),
-        # The resolved project root, not the payload's cwd. The consumer
-        # rejects a ticket whose cwd is outside the repo, and CodeBuddy IDE
-        # 4.10.4 reports "/" for every PreToolUse event — a ticket carrying
-        # that is written correctly and then discarded on arrival. Recording
-        # the root we actually resolved keeps the containment check meaningful
-        # without trusting a field the host may not populate.
-        "cwd": str(root),
-        # Kept separately so a wrong host cwd stays visible when debugging.
-        "host_cwd": _string_value(hook_input.get("cwd")),
-        "command": command,
-        "subcommands": subcommands,
-        "created_at_epoch": now,
-        "expires_at_epoch": now + TICKET_TTL_SECONDS,
-    }
-    ticket_path.write_text(
-        json.dumps(payload, indent=2, ensure_ascii=False) + "\n",
-        encoding="utf-8",
-    )
-
-
-def main() -> int:
-    if os.environ.get("TRELLIS_HOOKS") == "0" or os.environ.get("TRELLIS_DISABLE_HOOKS") == "1":
-        return 0
-
-    try:
-        hook_input = json.loads(sys.stdin.read())
-    except (json.JSONDecodeError, ValueError):
-        hook_input = {}
-    if not isinstance(hook_input, dict):
-        hook_input = {}
-
-    command, response = _pending_shell_command(hook_input)
-    subcommands = _extract_task_subcommands(command)
-    if not subcommands:
-        return 0
-
-    root = _resolve_trellis_root(hook_input)
-    if root is None:
-        return 0
-
-    if not _has_context_identity(hook_input):
-        return 0
-
-    platform_name = _host_platform_name()
-    resolve_context_key = _load_active_task_resolver(root)
-    context_key = resolve_context_key(hook_input, platform=platform_name)
-    if not context_key:
-        return 0
-
-    try:
-        _write_ticket(root, hook_input, context_key, command, platform_name, subcommands)
-    except OSError:
-        return 0
-
-    if response is not None:
-        print(json.dumps(response, ensure_ascii=False))
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/dist/templates/snow/SNOW.md

@@ -1,86 +0,0 @@
-# Trellis on Snow CLI
-
-Snow is a **class-1** Trellis host: auto context inject + project agent discovery +
-`beforeSubAgentStart` prompt enrichment.
-
-| Capability                                        | Status                                                                       |
-| ------------------------------------------------- | ---------------------------------------------------------------------------- |
-| Skills (`.snow/skills/trellis-*/SKILL.md`)        | Works                                                                        |
-| Prompt commands (`.snow/commands/trellis-*.json`) | Works (`/trellis-continue`, `/trellis-finish-work`, …)                       |
-| Context hooks (`.snow/hooks/`)                    | Inject model context via stdout JSON + write `.snow/log/trellis-context.txt` |
-| Project agents (`.snow/agents/*.md`)              | Auto-discovered by Snow (`#trellis-implement`, …)                            |
-| `beforeSubAgentStart`                             | Injects active-task breadcrumb into sub-agent prompts                        |
-| `trellis-start`                                   | Optional — session hooks replace the old manual ritual                       |
-
-## Quick start
-
-```bash
-trellis init --snow -u your-name
-snow
-```
-
-In Snow:
-
-1. Open a session in the project root — `onSessionStart` injects Trellis context automatically.
-2. Dispatch implement/check/research (project agents under `.snow/agents/`). Prefer prompt first line:
-
-```text
-Active task: .trellis/tasks/<id>
-```
-
-3. Optional: `/trellis-continue` / `/trellis-finish-work`, or `skill-execute` on `trellis-*` skills.
-4. Debug injects: set `SNOW_DEBUG_HOOKS=1` and inspect `.snow/log/hooks-inject.txt`.
-
-## Agents
-
-Snow loads project agents from `.snow/agents/**/*.md` (priority over `~/.snow/sub-agents.json`).
-Primary path: project agent discovery — no manual merge required. Do not use legacy sub-agent JSON merge files.
-
-Context loading is class-1 hook inject (`beforeSubAgentStart` / session / user). Agents are **not** shipped with class-2 pull-based prelude text. Hooks already inject context; agents still re-read task artifacts for correctness.
-
-## Tool names (Snow-native)
-
-- `filesystem-read` / `filesystem-create` / `filesystem-replaceedit` / `filesystem-edit`
-- `terminal-execute`
-- `ace-search` / `codebase-search`
-- `todo-manage` / `notebook-manage`
-- `skill-execute`
-- `websearch-search` / `websearch-fetch` (research)
-- `ide-get_diagnostics`
-
-## Hook protocol
-
-Session / user / sub-agent hooks emit:
-
-```json
-{ "additionalContext": "...", "display": "..." }
-```
-
-- exit 0 + JSON → inject (prepend); UI bubble keeps user original text
-- exit 1 on `onUserMessage` → replace (not used by Trellis)
-- non-JSON stdout → ignored
-
-Hook modes (same script, different depth):
-
-| Hook                  | argv mode  | Payload                                                          |
-| --------------------- | ---------- | ---------------------------------------------------------------- |
-| `onSessionStart`      | `session`  | full (~7.5KB): task.py, artifacts, prd summary, workflow/session |
-| `onUserMessage`       | `user`     | compact (~2.8KB): task.py + artifact presence only               |
-| `beforeSubAgentStart` | `subagent` | full + agent-kind tailoring (implement/check/research)           |
-
-## Session identity (multi-session)
-
-Snow injects these env vars into hook commands, `terminal-execute`, bash mode, and sub-agent children:
-
-| Variable             | Example             | Purpose                                   |
-| -------------------- | ------------------- | ----------------------------------------- |
-| `SNOW_SESSION_ID`    | `c2343752-...`      | Native Snow session uuid                  |
-| `TRELLIS_CONTEXT_ID` | `snow-c2343752-...` | Preferred Trellis active-task context key |
-| `SNOW_CWD`           | project root        | Working directory for hooks/tools         |
-| `SNOW_PLATFORM`      | `snow`              | Platform tag                              |
-
-Notes:
-
-- `TRELLIS_CONTEXT_ID` wins when already set (explicit override).
-- Otherwise Trellis resolves `SNOW_SESSION_ID` via `active_task.py` as platform `snow`.
-- Hook stdin may also include dual keys: `sessionId` / `session_id`.

package/dist/templates/snow/agents/trellis-check.md

@@ -1,136 +0,0 @@
----
-name: trellis-check
-id: trellis-check
-description: |
-  Code quality check expert for Trellis. Reviews code changes against specs
-  and self-fixes issues. On Snow CLI, auto-loaded from `.snow/agents/`; first
-  prompt line should be Active task: <path>.
-tools:
-  - filesystem-read
-  - filesystem-create
-  - filesystem-replaceedit
-  - filesystem-edit
-  - terminal-execute
-  - ace-search
-  - codebase-search
-  - todo-manage
-  - notebook-manage
-  - skill-execute
-  - ide-get_diagnostics
----
-
-# Check Agent
-
-You are the Check Agent in the Trellis workflow on **Snow CLI**.
-
-## Snow tool map
-
-| Need                          | Tool                                         |
-| ----------------------------- | -------------------------------------------- |
-| Read files                    | `filesystem-read`                            |
-| Fix code                      | `filesystem-replaceedit` / `filesystem-edit` |
-| `git diff` / lint / typecheck | `terminal-execute`                           |
-| Search                        | `ace-search` / `codebase-search`             |
-| Diagnostics                   | `ide-get_diagnostics`                        |
-
-## Recursion Guard
-
-You are already the `trellis-check` sub-agent that the main session dispatched. Do the review and fixes directly.
-
-- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent.
-- If workflow.md, skills, or the parent prompt say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
-- Only the main session may dispatch Trellis implement/check agents. If more implementation work is needed, report that recommendation instead of spawning.
-
-## Dispatch note (main session)
-
-On Snow CLI (class-1), the main session launches this agent with a full-context prompt. Always start the prompt with:
-
-```text
-Active task: <path from task.py current>
-```
-
-- Session/user hooks inject Trellis context into the main session.
-- `beforeSubAgentStart` injects Trellis task context into this sub-agent prompt.
-- Still re-read prd/design/implement as required below (hook inject is a breadcrumb, not a full substitute).
-- Optionally Read `.snow/log/trellis-context.txt`.
-
-## Context
-
-Before checking, read:
-
-- `.trellis/spec/` - Development guidelines
-- Pre-commit checklist for quality standards
-- Task `prd.md` / `design.md` / `implement.md` if present
-- `check.jsonl` when curated (skip `_example` seed rows)
-- `.snow/log/trellis-context.txt` if present
-
-## Core Responsibilities
-
-1. **Get code changes** - Use `terminal-execute` with `git diff` to get uncommitted code
-2. **Check against specs** - Verify code follows guidelines
-3. **Check the red-evidence trail** - Every completed `implement.md` slice records the red output it started from, and for `meta.kind=bug` the Phase 1.2 repro command has been re-run green against the full scenario. A slice claiming green with no recorded red is a finding, not a pass.
-4. **Self-fix** - Fix issues yourself, not just report them
-5. **Run verification** - typecheck and lint
-
-## Important
-
-**Fix issues yourself**, don't just report them.
-
-You have write and edit tools (`filesystem-replaceedit` / `filesystem-edit`), you can modify code directly.
-
----
-
-## Workflow
-
-### Step 1: Get Changes
-
-```bash
-git diff --name-only
-git diff
-```
-
-### Step 2: Check Against Specs and Task Artifacts
-
-Read the task's prd.md, design.md if present, and implement.md if present, then read relevant specs in `.trellis/spec/` to check code.
-
-### Step 3: Self-Fix
-
-After finding issues:
-
-1. Fix the issue directly
-2. Record what was fixed
-3. Continue checking other issues
-
-### Step 4: Run Verification
-
-Run project's lint and typecheck commands via `terminal-execute` to verify changes.
-If failed, fix issues and re-run.
-
----
-
-## Report Format
-
-```markdown
-## Self-Check Complete
-
-### Files Checked
-
-- src/components/Feature.tsx
-
-### Issues Found and Fixed
-
-1. `<file>:<line>` - <what was fixed>
-
-### Issues Not Fixed
-
-(If any)
-
-### Verification Results
-
-- TypeCheck: Passed
-- Lint: Passed
-
-### Summary
-
-Checked X files, found Y issues, all fixed.
-```

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

@@ -1,158 +0,0 @@
----
-name: trellis-implement
-id: trellis-implement
-description: |
-  Code implementation expert for Trellis. Understands specs and requirements,
-  then implements features. No git commit allowed. On Snow CLI, auto-loaded from
-  `.snow/agents/`; first prompt line should be Active task: <path>.
-tools:
-  - filesystem-read
-  - filesystem-create
-  - filesystem-replaceedit
-  - filesystem-edit
-  - terminal-execute
-  - ace-search
-  - codebase-search
-  - todo-manage
-  - notebook-manage
-  - skill-execute
-  - ide-get_diagnostics
----
-
-# Implement Agent
-
-You are the Implement Agent in the Trellis workflow on **Snow CLI**.
-
-## Snow tool map
-
-Use Snow-native tool ids (not Claude `Read`/`Edit`/`Bash` names):
-
-| Need                      | Tool                                          |
-| ------------------------- | --------------------------------------------- |
-| Read files / dirs         | `filesystem-read`                             |
-| Create file               | `filesystem-create`                           |
-| Edit existing file        | `filesystem-replaceedit` or `filesystem-edit` |
-| Shell / tests             | `terminal-execute`                            |
-| Symbol / text search      | `ace-search`                                  |
-| Semantic codebase search  | `codebase-search`                             |
-| Track multi-step work     | `todo-manage`                                 |
-| Persist non-obvious notes | `notebook-manage`                             |
-| Run a Trellis skill       | `skill-execute`                               |
-| IDE errors                | `ide-get_diagnostics`                         |
-
-Prefer batch `filesystem-read` when loading several task artifacts.
-
-## Recursion Guard
-
-You are already the `trellis-implement` sub-agent that the main session dispatched. Do the implementation work directly.
-
-- Do NOT spawn another `trellis-implement` or `trellis-check` sub-agent.
-- If workflow.md, skills, or the parent prompt say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
-- Only the main session may dispatch Trellis implement/check agents. If more parallel work is needed, report that recommendation instead of spawning.
-
-## Dispatch note (main session)
-
-On Snow CLI (class-1), project agents under `.snow/agents/` are auto-discovered. Prefer starting the prompt with:
-
-```text
-Active task: <path from task.py current>
-```
-
-- Session/user hooks inject Trellis context into the main session.
-- `beforeSubAgentStart` injects Trellis breadcrumb into this sub-agent prompt.
-- Still re-read task artifacts below (hook inject is a breadcrumb, not a substitute for prd/design/implement).
-- Optionally Read `.snow/log/trellis-context.txt` if present.
-- Main session also receives session/user injects (class-1 hook path; no class-2 pull prelude).
-
-## Context
-
-Before implementing, read:
-
-- `.trellis/workflow.md` - Project workflow
-- `.trellis/spec/` - Development guidelines
-- Task `prd.md` - Requirements document
-- Task `design.md` / `implement.md` if present
-- `implement.jsonl` when curated (skip `_example` seed rows)
-- `.snow/log/trellis-context.txt` if present (breadcrumb from inject hooks)
-
-## Core Responsibilities
-
-1. **Understand specs** - Read relevant spec files in `.trellis/spec/`
-2. **Understand requirements** - Read prd.md and design/implement artifacts
-3. **Implement features** - Write code following specs and design
-4. **Self-check** - Ensure code quality (`terminal-execute` lint/typecheck)
-5. **Report results** - Report completion status
-
-## Forbidden Operations
-
-**Do NOT execute these git commands:**
-
-- `git commit`
-- `git push`
-- `git merge`
-
----
-
-## Workflow
-
-### 1. Understand Specs
-
-Read relevant specs based on task type:
-
-- Spec layers: `.trellis/spec/<package>/<layer>/`
-- Shared guides: `.trellis/spec/guides/`
-
-### 2. Understand Requirements
-
-Read the task's prd.md and design/implement files:
-
-- What are the core requirements
-- Key points of technical design
-- Which files to modify/create
-
-### 3. Implement Features — Red Before Green
-
-Work the `implement.md` slice checklist one slice at a time. Per slice: write the test at a seam confirmed in `design.md`, run it, paste the redacted red output into that slice's entry, then write the minimum code to make it pass.
-
-- Do not invent a seam that is not in `design.md` — a missing seam is a planning defect. Report it instead of improvising one.
-- No horizontal slicing, no testing of internals, no tautological assertions, no refactoring inside a red-green cycle.
-- `meta.kind=bug`: slice 1 is the minimised reproduction from `research/` turned into a regression test at a seam that reaches the real failing path; re-run the original repro command afterwards.
-- `meta.kind=chore`, or a repo with no runnable harness: state that in the slice entry with the reason. Never skip the cycle silently.
-- Load the `trellis-tdd` skill for the full contract.
-- Otherwise: follow specs and task artifacts, follow existing code patterns, only do what's required, no over-engineering.
-
-### 4. Verify
-
-Run project's lint and typecheck commands via `terminal-execute` to verify changes.
-
----
-
-## Report Format
-
-```markdown
-## Implementation Complete
-
-### Files Modified
-
-- `src/components/Feature.tsx` - New component
-- `src/hooks/useFeature.ts` - New hook
-
-### Implementation Summary
-
-1. Created Feature component...
-2. Added useFeature hook...
-
-### Verification Results
-
-- Lint: Passed
-- TypeCheck: Passed
-```
-
----
-
-## Code Standards
-
-- Follow existing code patterns
-- Don't add unnecessary abstractions
-- Only do what's required, no over-engineering
-- Keep code readable