@jahanxu/trellis 0.5.0 → 0.5.5

package/dist/templates/claude/commands/trellis/handoff.md

@@ -1,148 +1,82 @@
-# Handoff - Complete Task and Add to Pool
-
-Complete the current task, generate a HANDOFF.md document, and add the deliverable to the appropriate pool.
-
 ---
-
-## Prerequisites
-
-- Must have a current task set (`.trellis/.current-task`)
-- Task must have deliverable files in the output directory
-
+description: "Complete current phase and generate handoff document for downstream roles"
 ---
 
-## Process `[AI]`
-
-### Step 1: Read Current Task
-
-```bash
-python3 ./.trellis/scripts/get_context.py
-```
-
-Read the task's `task.json` to get:
-- `output_dir`: where deliverables are stored
-- `role`: which role completed this task
-- `title`: task title
-- `slug`: task slug / deliverable ID
-
-If no current task is set, inform the user and stop.
-
-### Step 2: Check Deliverables
-
-Verify that the output directory exists and contains files:
-
-```bash
-ls -la <output_dir>/
-```
+You are executing the **HANDOFF** workflow for a collaborative project.
 
-If empty or missing, warn the user:
-> "The output directory `<output_dir>` appears empty. Would you like to continue anyway?"
+## Step 1: Identify Context
 
-### Step 3: Generate HANDOFF.md
+1. Read `.trellis/.developer` to get the current developer name
+2. Read `.trellis/roles.json` to determine the role and bound output directory
+3. If roles.json doesn't exist or current developer has no role mapping, abort with:
+   "Error: No role binding found. Run `trellis init -u <role>-<name> -d <dir>` first."
 
-Analyze all files in the output directory and generate a `HANDOFF.md` document.
+## Step 2: Check Deliverables
 
-**For PM role (requirements pool):**
+1. List all files in the bound output directory
+2. If the directory is empty, warn: "Output directory is empty. Are you sure you want to proceed?" and wait for confirmation
+3. Run `git diff --name-only` scoped to the output directory to identify recent changes
 
-```markdown
-# {Title} - Requirements Handoff
+## Step 3: Generate HANDOFF.md
 
-## Task Info
-- **Feature ID**: {slug}
-- **Title**: {title}
-- **Completed by**: {developer}
-- **Completed at**: {timestamp}
-
-## Core Requirements
-(AI-generated summary of PRD key points, 2-3 paragraphs)
-
-## Deliverable Files
-- `prd.md` - Product requirements document
-- (list all files)
-
-## Key Design Points
-1. (extracted from PRD)
-2. ...
-
-## Special Notes for Downstream
-- (important details the Designer should know)
-- (constraints, edge cases, specific UI requirements)
+Create or overwrite `HANDOFF.md` **inside the output directory** with the following structure:
 
-## Related Resources
-- (links if any)
-```
-
-**For Designer role (prototypes pool):**
-
-```markdown
-# {Title} - Prototype Handoff
+````
+# {Feature/Task Name} - Handoff Document
 
 ## Task Info
-- **Feature ID**: {slug}
-- **Based on**: {source requirement}
-- **Completed by**: {developer}
-- **Completed at**: {timestamp}
+- **Role**: {current role}
+- **Developer**: {developer name}
+- **Output Directory**: {bound directory}
+- **Completed**: {current timestamp}
 
-## Design Notes
-(AI-generated summary of design approach, 2-3 paragraphs)
+## Summary
+(Summarize what was done in 2-3 paragraphs, based on git diff + conversation context)
 
 ## Deliverable Files
-- (list all component files)
-
-## Component Structure
-(component tree overview)
-
-## Mock Data Notes
-Current mock data used:
-```typescript
-// Document all mock data and their locations
-// Include file name and line numbers
-```
-
-## Logic for Frontend to Implement
-1. Replace mock login handler with real API call (file:line)
-2. Add error handling for network failures
-3. Implement loading state management
-4. ...
-
-## Special Notes for Downstream
-- (interactions to preserve)
-- (SDK dependencies)
-- (form validation already implemented)
-```
+(List all files in the output directory with one-line descriptions)
 
-Write the generated HANDOFF.md to `<output_dir>/HANDOFF.md`.
+## Key Design Decisions
+(Numbered list of important decisions and rationale)
 
-### Step 4: Ask for Handoff Message (Optional)
+## Notes for Downstream
+(Specific items the next role should pay attention to)
 
-Ask the user:
-> "Any additional notes for the downstream role? (Press Enter to skip)"
+## Contact
+Questions? Reach out to {developer name}
+````
 
-If provided, append to the Special Notes section.
+## Step 4: Update CHANGELOG.md
 
-### Step 5: Add to Pool
+1. If `CHANGELOG.md` doesn't exist in the output directory, create it with the standard header:
+   ````
+   # CHANGELOG - {directory name}
 
-Determine the target pool based on role:
-- `pm` -> `requirements`
-- `designer` -> `prototypes`
-- `frontend-impl` or `frontend` -> `implementations`
+   > 变更记录表，由 AI 自动维护（/trellis:handoff 时追加）。
 
-```bash
-python3 ./.trellis/scripts/pool.py add <pool> <slug> "<title>" <output_dir>
-```
+   | 日期 | 作者 | 类型 | 摘要 | 关联文件 |
+   |------|------|------|------|----------|
+   ````
+2. Append one row to the changelog table:
+   - Date: current datetime (YYYY-MM-DD HH:mm)
+   - Author: developer name from .developer
+   - Type: Infer from git diff (新增/修改/删除/重构)
+   - Summary: One sentence (max 80 chars) summarizing the changes
+   - Files: Key files changed
 
-### Step 6: Report
+## Step 5: User Review
 
-Output a summary:
-```
-Handoff complete!
-- Deliverable: <slug>
-- Pool: <pool>
-- HANDOFF.md: <output_dir>/HANDOFF.md
-- Status: available
+1. Show the generated HANDOFF.md content to the user
+2. Show the new CHANGELOG.md entry
+3. Ask: "Please review the handoff document. Reply with changes or confirm to finalize."
+4. If the user requests changes, modify and re-show
+5. Once confirmed, remind:
+   - `git add {output_dir}/` to stage changes
+   - `git commit` and `git push`
+   - Notify the downstream developer offline
 
-Next: The downstream role can pick this up with:
-  /trellis:pick-task <pool> <slug>
-```
+## Constraints
 
-Remind the user to commit and push so the downstream role can access the deliverables.
+- **NEVER** write files outside the bound output directory
+- HANDOFF.md and CHANGELOG.md must be placed at the **root** of the output directory
+- If `--message` argument is provided, include it in the HANDOFF.md Notes section

package/dist/templates/claude/hooks/enforce-output-dir.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+PreToolUse Hook: Enforce output directory constraint.
+
+Intercepts Edit/Write/MultiEdit tool calls and verifies the target
+file path is within the developer's allowed output directory.
+
+Non-collaboration projects (no roles.json) are unaffected.
+Fail-open: any infrastructure error results in allow.
+"""
+
+# IMPORTANT: Suppress all warnings FIRST
+import warnings
+warnings.filterwarnings("ignore")
+
+import json
+import os
+import sys
+from pathlib import Path
+
+# IMPORTANT: Force stdout to use UTF-8 on Windows
+if sys.platform == "win32":
+    import io as _io
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+    elif hasattr(sys.stdout, "detach"):
+        sys.stdout = _io.TextIOWrapper(sys.stdout.detach(), encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+
+
+def _allow():
+    """Output allow decision and exit."""
+    print(json.dumps({"decision": "allow"}))
+
+
+def _block(reason: str):
+    """Output block decision with reason and exit."""
+    print(json.dumps({"decision": "block", "reason": reason}))
+
+
+def main():
+    # Read hook event from stdin
+    try:
+        event = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, EOFError, OSError):
+        _allow()
+        return
+
+    tool_name = event.get("tool_name", "")
+    tool_input = event.get("tool_input", {})
+
+    # Only intercept file-writing tools
+    if tool_name not in ("Edit", "Write", "MultiEdit"):
+        _allow()
+        return
+
+    # Get file path from tool input
+    file_path = tool_input.get("file_path", "")
+    if not file_path:
+        _allow()
+        return
+
+    # Resolve role constraint via .trellis/scripts/common/roles.py
+    try:
+        project_dir = Path(os.environ.get("CLAUDE_PROJECT_DIR", ".")).resolve()
+        scripts_parent = project_dir / ".trellis"
+        if scripts_parent.is_dir():
+            sys.path.insert(0, str(scripts_parent))
+
+        from scripts.common.roles import resolve_role_constraint
+        role, output_dir = resolve_role_constraint(project_dir)
+    except Exception:
+        # Fail-open: can't resolve constraint -> allow
+        _allow()
+        return
+
+    # No constraint = non-collaboration project, allow everything
+    if not role or not output_dir:
+        _allow()
+        return
+
+    # Normalize paths for comparison
+    try:
+        resolved_file = Path(file_path).resolve()
+        resolved_output = (project_dir / output_dir).resolve()
+        resolved_trellis = (project_dir / ".trellis").resolve()
+    except Exception:
+        _allow()
+        return
+
+    # Allow writes to .trellis/ (workflow files are always writable)
+    try:
+        resolved_file.relative_to(resolved_trellis)
+        _allow()
+        return
+    except ValueError:
+        pass
+
+    # Check if file is within the allowed output directory
+    try:
+        resolved_file.relative_to(resolved_output)
+        _allow()
+        return
+    except ValueError:
+        pass
+
+    # Block: file is outside allowed directory
+    _block(
+        f"Role '{role}' can only write to '{output_dir}' and '.trellis/'. "
+        f"Target file '{file_path}' is outside the allowed directory."
+    )
+
+
+if __name__ == "__main__":
+    main()

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

@@ -3,7 +3,6 @@
 """
 Session Start Hook - Inject structured context
 """
-from __future__ import annotations
 
 # IMPORTANT: Suppress all warnings FIRST
 import warnings
@@ -66,167 +65,96 @@ def run_script(script_path: Path) -> str:
         return "No context available"
 
 
-def detect_role(trellis_dir: Path) -> str | None:
-    """Detect role from developer name ({role}-{name} convention)."""
-    dev_file = trellis_dir / ".developer"
-    if not dev_file.is_file():
-        return None
-    try:
-        content = dev_file.read_text(encoding="utf-8")
-        for line in content.splitlines():
-            if line.startswith("name="):
-                name = line.split("=", 1)[1].strip()
-                # Parse role from {role}-{name} pattern
-                if "-" in name:
-                    role = name.split("-", 1)[0]
-                    if role in ("pm", "designer", "frontend", "frontend-impl"):
-                        return role
-    except (OSError, IOError):
-        pass
-    return None
-
-
-def inject_upstream_context(trellis_dir: Path, project_dir: Path, output: StringIO) -> None:
-    """Inject upstream context when source.json exists in current task."""
-    current_task_file = trellis_dir / ".current-task"
-    if not current_task_file.is_file():
-        return
+def inject_role_context(project_dir: Path, output):
+    """Inject role context and upstream handoff/changelog if in collaboration mode.
 
+    Fail-safe: any error is silently caught so it never breaks session start.
+    """
     try:
-        task_rel = current_task_file.read_text(encoding="utf-8").strip()
-    except (OSError, IOError):
-        return
-
-    if not task_rel:
-        return
-
-    task_dir = project_dir / task_rel
-    source_file = task_dir / "source.json"
-    if not source_file.is_file():
-        return
+        trellis_dir = project_dir / ".trellis"
+        if trellis_dir.is_dir():
+            sys.path.insert(0, str(trellis_dir))
+
+        from scripts.common.roles import (
+            resolve_role_constraint,
+            load_roles_json,
+            get_upstream_dirs,
+        )
+    except ImportError:
+        return  # roles module not available, skip silently
 
     try:
-        source = json.loads(source_file.read_text(encoding="utf-8"))
-    except (json.JSONDecodeError, OSError):
-        return
-
-    based_on = source.get("based_on")
-    if not based_on:
-        return
-
-    output.write("<upstream-context>\n")
-    output.write("## Based on Upstream Deliverable\n")
-    output.write(f"- Type: {based_on.get('type', '?')}\n")
-    output.write(f"- ID: {based_on.get('id', '?')}\n")
-    output.write(f"- Path: {based_on.get('path', '?')}\n\n")
-
-    # Read HANDOFF document
-    handoff_path = project_dir / based_on.get("handoff_doc", "")
-    if handoff_path.is_file():
-        output.write("### Handoff Document\n")
-        handoff_content = read_file(handoff_path)
-        if len(handoff_content) > 3000:
-            handoff_content = handoff_content[:3000] + "\n... (truncated)"
-        output.write(handoff_content)
-        output.write("\n\n")
-
-    # Read upstream deliverable files
-    source_path = project_dir / based_on.get("path", "")
-    if source_path.is_dir():
-        output.write("### Upstream Deliverable Files\n")
-        total_size = 0
-        text_exts = {".md", ".txt", ".tsx", ".ts", ".jsx", ".js", ".vue", ".css", ".json", ".yaml", ".yml", ".html"}
-        for fpath in sorted(source_path.rglob("*")):
-            if not fpath.is_file():
-                continue
-            if fpath.name == "HANDOFF.md":
-                continue
-            if fpath.suffix not in text_exts:
+        role, output_dir = resolve_role_constraint(project_dir)
+        if not role:
+            return  # Not in collaboration mode
+
+        # --- Role context ---
+        output.write("<role-context>\n")
+        output.write(f"## Current Role: {role}\n")
+        output.write(f"## Output Directory: {output_dir}\n")
+        output.write("\n")
+
+        # Role spec files
+        role_dir_map = {"pm": "pm", "designer": "designer", "frontend": "frontend-impl"}
+        spec_dir = project_dir / ".trellis" / "spec" / "roles"
+        role_spec_dir = spec_dir / role_dir_map.get(role, role)
+        if role_spec_dir.is_dir():
+            for spec_file in sorted(role_spec_dir.glob("*.md")):
+                if spec_file.is_file():
+                    try:
+                        rel = spec_file.relative_to(project_dir)
+                    except ValueError:
+                        rel = spec_file.name
+                    output.write(f"### {rel}\n")
+                    content = spec_file.read_text(encoding="utf-8")
+                    output.write(content[:3000])
+                    if len(content) > 3000:
+                        output.write("\n... (truncated)")
+                    output.write("\n\n")
+
+        output.write("</role-context>\n\n")
+
+        # --- Upstream context ---
+        roles_json = load_roles_json(project_dir)
+        if not roles_json:
+            return
+
+        upstream_dirs = get_upstream_dirs(role, roles_json)
+        if not upstream_dirs:
+            return
+
+        output.write("<upstream-context>\n")
+        for upstream_dir in upstream_dirs:
+            upstream_path = project_dir / upstream_dir
+            if not upstream_path.is_dir():
                 continue
-            if total_size >= 50000:
-                output.write("\n(total size cap reached, remaining files omitted)\n")
-                break
-            try:
-                content = fpath.read_text(encoding="utf-8")
-            except (OSError, UnicodeDecodeError):
-                continue
-            rel = fpath.relative_to(source_path)
-            output.write(f"\n#### {rel}\n")
-            ext = fpath.suffix[1:] if fpath.suffix else ""
-            if len(content) > 3000:
-                content = content[:3000] + "\n... (truncated)"
-            output.write(f"```{ext}\n{content}\n```\n")
-            total_size += len(content)
-
-    output.write("</upstream-context>\n\n")
-
-
-def inject_pool_summary(trellis_dir: Path, output: StringIO) -> None:
-    """Inject available tasks summary from pool files."""
-    pool_dir = trellis_dir / "pool"
-    if not pool_dir.is_dir():
-        return
-
-    pool_files = sorted(pool_dir.glob("*.json"))
-    if not pool_files:
-        return
-
-    has_available = False
-    pool_output = StringIO()
-
-    for pool_file in pool_files:
-        try:
-            data = json.loads(pool_file.read_text(encoding="utf-8"))
-        except (json.JSONDecodeError, OSError):
-            continue
-
-        available = [
-            i for i in data.get("available", [])
-            if i.get("status") == "available"
-        ]
-        if not available:
-            continue
-
-        has_available = True
-        pool_name = pool_file.stem
-        pool_output.write(f"## Available in {pool_name} ({len(available)})\n")
-        for item in available:
-            completed_by = item.get("completed_by", "?")
-            completed_at = item.get("completed_at", "?")
-            pool_output.write(
-                f"- {item.get('id', '?')}: {item.get('title', '?')} "
-                f"(by {completed_by}, {completed_at})\n"
-            )
-        pool_output.write("\n")
-
-    if has_available:
-        output.write("<available-tasks>\n")
-        output.write(pool_output.getvalue())
-        output.write("Use `/trellis:pick-task <pool> <id>` to start working on an available item.\n")
-        output.write("</available-tasks>\n\n")
-
-
-def inject_role_guidelines(trellis_dir: Path, role: str | None, output: StringIO) -> None:
-    """Inject role-specific guidelines if role is detected."""
-    if not role:
-        return
-
-    role_dir_map = {
-        "pm": "pm",
-        "designer": "designer",
-        "frontend": "frontend-impl",
-        "frontend-impl": "frontend-impl",
-    }
-
-    role_dir = role_dir_map.get(role)
-    if not role_dir:
-        return
-
-    role_index = trellis_dir / "spec" / "roles" / role_dir / "index.md"
-    if role_index.is_file():
-        output.write(f"## Role: {role}\n")
-        output.write(read_file(role_index))
-        output.write("\n\n")
+            # HANDOFF files
+            for handoff in sorted(upstream_path.rglob("HANDOFF.md")):
+                try:
+                    rel = handoff.relative_to(project_dir)
+                except ValueError:
+                    rel = handoff.name
+                output.write(f"### {rel}\n")
+                content = handoff.read_text(encoding="utf-8")
+                output.write(content[:3000])
+                if len(content) > 3000:
+                    output.write("\n... (truncated)")
+                output.write("\n\n")
+            # CHANGELOG files
+            for changelog in sorted(upstream_path.rglob("CHANGELOG.md")):
+                try:
+                    rel = changelog.relative_to(project_dir)
+                except ValueError:
+                    rel = changelog.name
+                output.write(f"### {rel}\n")
+                content = changelog.read_text(encoding="utf-8")
+                output.write(content[:3000])
+                if len(content) > 3000:
+                    output.write("\n... (truncated)")
+                output.write("\n\n")
+        output.write("</upstream-context>\n\n")
+    except Exception:
+        pass  # Fail-safe: never break session start
 
 
 def main():
@@ -258,10 +186,6 @@ Read and follow all instructions below carefully.
 
     output.write("<guidelines>\n")
 
-    # Detect role and inject role-specific guidelines
-    role = detect_role(trellis_dir)
-    inject_role_guidelines(trellis_dir, role, output)
-
     output.write("## Frontend\n")
     frontend_index = read_file(
         trellis_dir / "spec" / "frontend" / "index.md", "Not configured"
@@ -284,11 +208,8 @@ Read and follow all instructions below carefully.
 
     output.write("\n</guidelines>\n\n")
 
-    # Inject upstream context (from source.json in current task)
-    inject_upstream_context(trellis_dir, project_dir, output)
-
-    # Inject pool summary (available tasks)
-    inject_pool_summary(trellis_dir, output)
+    # Inject role context and upstream handoff/changelog (collaboration mode)
+    inject_role_context(project_dir, output)
 
     output.write("<instructions>\n")
     start_md = read_file(

package/dist/templates/claude/settings.json

@@ -22,6 +22,16 @@
             "timeout": 30
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "{{PYTHON_CMD}} .claude/hooks/enforce-output-dir.py",
+            "timeout": 10
+          }
+        ]
       }
     ],
     "SubagentStop": [