@mindfoldhq/trellis 0.4.0 → 0.5.0-beta.1

package/dist/templates/claude/hooks/ralph-loop.py

@@ -1,396 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""
-Ralph Loop - SubagentStop Hook for Check Agent Loop Control
-
-Based on the Ralph Wiggum technique for autonomous agent loops.
-Uses completion promises to control when the check agent can stop.
-
-Mechanism:
-- Intercepts when check subagent tries to stop (SubagentStop event)
-- If verify commands configured in worktree.yaml, runs them to verify
-- Otherwise, reads check.jsonl to get dynamic completion markers ({reason}_FINISH)
-- Blocks stopping until verification passes or all markers found
-- Has max iterations as safety limit
-
-State file: .trellis/.ralph-state.json
-- Tracks current iteration count per session
-- Resets when task changes
-"""
-
-# IMPORTANT: Suppress all warnings FIRST
-import warnings
-warnings.filterwarnings("ignore")
-
-import json
-import os
-import subprocess
-import sys
-from datetime import datetime
-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":
-    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]
-
-# =============================================================================
-# Configuration
-# =============================================================================
-
-MAX_ITERATIONS = 5  # Safety limit to prevent infinite loops
-STATE_TIMEOUT_MINUTES = 30  # Reset state if older than this
-STATE_FILE = ".trellis/.ralph-state.json"
-WORKTREE_YAML = ".trellis/worktree.yaml"
-DIR_WORKFLOW = ".trellis"
-FILE_CURRENT_TASK = ".current-task"
-
-# Only control loop for check agent
-TARGET_AGENT = "check"
-
-
-def find_repo_root(start_path: str) -> str | None:
-    """Find git repo root from start_path upwards"""
-    current = Path(start_path).resolve()
-    while current != current.parent:
-        if (current / ".git").exists():
-            return str(current)
-        current = current.parent
-    return None
-
-
-def get_current_task(repo_root: str) -> str | None:
-    """Read current task directory path"""
-    current_task_file = os.path.join(repo_root, DIR_WORKFLOW, FILE_CURRENT_TASK)
-    if not os.path.exists(current_task_file):
-        return None
-
-    try:
-        with open(current_task_file, "r", encoding="utf-8") as f:
-            content = f.read().strip()
-            if not content:
-                return None
-            normalized = content.replace("\\", "/")
-            while normalized.startswith("./"):
-                normalized = normalized[2:]
-            if normalized.startswith("tasks/"):
-                normalized = f".trellis/{normalized}"
-            return normalized
-    except Exception:
-        return None
-
-
-def get_verify_commands(repo_root: str) -> list[str]:
-    """
-    Read verify commands from worktree.yaml.
-
-    Returns list of commands to run, or empty list if not configured.
-    Uses simple YAML parsing without external dependencies.
-    """
-    yaml_path = os.path.join(repo_root, WORKTREE_YAML)
-    if not os.path.exists(yaml_path):
-        return []
-
-    try:
-        with open(yaml_path, "r", encoding="utf-8") as f:
-            content = f.read()
-
-        # Simple YAML parsing for verify section
-        # Look for "verify:" followed by list items
-        lines = content.split("\n")
-        in_verify_section = False
-        commands = []
-
-        for line in lines:
-            stripped = line.strip()
-
-            # Check for section start
-            if stripped.startswith("verify:"):
-                in_verify_section = True
-                continue
-
-            # Check for new section (not indented, ends with :)
-            if (
-                not line.startswith(" ")
-                and not line.startswith("\t")
-                and stripped.endswith(":")
-                and stripped != ""
-            ):
-                in_verify_section = False
-                continue
-
-            # If in verify section, look for list items
-            if in_verify_section:
-                # Skip comments and empty lines
-                if stripped.startswith("#") or stripped == "":
-                    continue
-                # Parse list item (- command)
-                if stripped.startswith("- "):
-                    cmd = stripped[2:].strip()
-                    if cmd:
-                        commands.append(cmd)
-
-        return commands
-    except Exception:
-        return []
-
-
-def run_verify_commands(repo_root: str, commands: list[str]) -> tuple[bool, str]:
-    """
-    Run verify commands and return (success, message).
-
-    All commands must pass for success.
-    """
-    for cmd in commands:
-        try:
-            result = subprocess.run(
-                cmd,
-                shell=True,
-                cwd=repo_root,
-                capture_output=True,
-                timeout=120,  # 2 minute timeout per command
-            )
-            if result.returncode != 0:
-                stderr = result.stderr.decode("utf-8", errors="replace")
-                stdout = result.stdout.decode("utf-8", errors="replace")
-                error_output = stderr or stdout
-                # Truncate long output
-                if len(error_output) > 500:
-                    error_output = error_output[:500] + "..."
-                return False, f"Command failed: {cmd}\n{error_output}"
-        except subprocess.TimeoutExpired:
-            return False, f"Command timed out: {cmd}"
-        except Exception as e:
-            return False, f"Command error: {cmd} - {str(e)}"
-
-    return True, "All verify commands passed"
-
-
-def get_completion_markers(repo_root: str, task_dir: str) -> list[str]:
-    """
-    Read check.jsonl and generate completion markers from reasons.
-
-    Each entry's "reason" field becomes {REASON}_FINISH marker.
-    Example: {"file": "...", "reason": "TypeCheck"} -> "TYPECHECK_FINISH"
-    """
-    check_jsonl_path = os.path.join(repo_root, task_dir, "check.jsonl")
-    markers = []
-
-    if not os.path.exists(check_jsonl_path):
-        # Fallback: if no check.jsonl, use default marker
-        return ["ALL_CHECKS_FINISH"]
-
-    try:
-        with open(check_jsonl_path, "r", encoding="utf-8") as f:
-            for line in f:
-                line = line.strip()
-                if not line:
-                    continue
-                try:
-                    item = json.loads(line)
-                    reason = item.get("reason", "")
-                    if reason:
-                        # Convert to uppercase and add _FINISH suffix
-                        marker = f"{reason.upper().replace(' ', '_')}_FINISH"
-                        if marker not in markers:
-                            markers.append(marker)
-                except json.JSONDecodeError:
-                    continue
-    except Exception:
-        pass
-
-    # If no markers found, use default
-    if not markers:
-        markers = ["ALL_CHECKS_FINISH"]
-
-    return markers
-
-
-def load_state(repo_root: str) -> dict:
-    """Load Ralph Loop state from file"""
-    state_path = os.path.join(repo_root, STATE_FILE)
-    if not os.path.exists(state_path):
-        return {"task": None, "iteration": 0, "started_at": None}
-
-    try:
-        with open(state_path, "r", encoding="utf-8") as f:
-            return json.load(f)
-    except Exception:
-        return {"task": None, "iteration": 0, "started_at": None}
-
-
-def save_state(repo_root: str, state: dict) -> None:
-    """Save Ralph Loop state to file"""
-    state_path = os.path.join(repo_root, STATE_FILE)
-    try:
-        # Ensure directory exists
-        os.makedirs(os.path.dirname(state_path), exist_ok=True)
-        with open(state_path, "w", encoding="utf-8") as f:
-            json.dump(state, f, indent=2, ensure_ascii=False)
-    except Exception:
-        pass
-
-
-def check_completion(agent_output: str, markers: list[str]) -> tuple[bool, list[str]]:
-    """
-    Check if all completion markers are present in agent output.
-
-    Returns:
-        (all_complete, missing_markers)
-    """
-    missing = []
-    for marker in markers:
-        if marker not in agent_output:
-            missing.append(marker)
-
-    return len(missing) == 0, missing
-
-
-def main():
-    try:
-        input_data = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        # If can't parse input, allow stop
-        sys.exit(0)
-
-    # Get event info
-    hook_event = input_data.get("hook_event_name", "")
-
-    # Only handle SubagentStop event
-    if hook_event != "SubagentStop":
-        sys.exit(0)
-
-    # Get subagent info
-    # Field names per Claude Code SubagentStop event schema:
-    #   agent_type, last_assistant_message, agent_id, agent_transcript_path, cwd
-    # The event does NOT carry a `prompt` field, so finish-phase detection
-    # based on a `[finish]` marker in the user prompt is no longer possible
-    # here; finish-phase skip logic should be reintroduced via task.json
-    # state (e.g. current_phase) in a follow-up.
-    agent_type = input_data.get("agent_type", "")
-    last_assistant_message = input_data.get("last_assistant_message", "")
-    cwd = input_data.get("cwd", os.getcwd())
-
-    # Only control check agent
-    if agent_type != TARGET_AGENT:
-        sys.exit(0)
-
-    # Find repo root
-    repo_root = find_repo_root(cwd)
-    if not repo_root:
-        sys.exit(0)
-
-    # Get current task
-    task_dir = get_current_task(repo_root)
-    if not task_dir:
-        sys.exit(0)
-
-    # Load state
-    state = load_state(repo_root)
-
-    # Reset state if task changed or state is too old
-    should_reset = False
-    if state.get("task") != task_dir:
-        should_reset = True
-    elif state.get("started_at"):
-        try:
-            started = datetime.fromisoformat(state["started_at"])
-            if (datetime.now() - started).total_seconds() > STATE_TIMEOUT_MINUTES * 60:
-                should_reset = True
-        except (ValueError, TypeError):
-            should_reset = True
-
-    if should_reset:
-        state = {
-            "task": task_dir,
-            "iteration": 0,
-            "started_at": datetime.now().isoformat(),
-        }
-
-    # Increment iteration
-    state["iteration"] = state.get("iteration", 0) + 1
-    current_iteration = state["iteration"]
-
-    # Save state
-    save_state(repo_root, state)
-
-    # Safety check: max iterations
-    if current_iteration >= MAX_ITERATIONS:
-        # Allow stop, reset state for next run
-        state["iteration"] = 0
-        save_state(repo_root, state)
-        output = {
-            "decision": "allow",
-            "reason": f"Max iterations ({MAX_ITERATIONS}) reached. Stopping to prevent infinite loop.",
-        }
-        print(json.dumps(output, ensure_ascii=False))
-        sys.exit(0)
-
-    # Check if verify commands are configured
-    verify_commands = get_verify_commands(repo_root)
-
-    if verify_commands:
-        # Use programmatic verification
-        passed, message = run_verify_commands(repo_root, verify_commands)
-
-        if passed:
-            # All verify commands passed, allow stop
-            state["iteration"] = 0
-            save_state(repo_root, state)
-            output = {
-                "decision": "allow",
-                "reason": "All verify commands passed. Check phase complete.",
-            }
-            print(json.dumps(output, ensure_ascii=False))
-            sys.exit(0)
-        else:
-            # Verification failed, block stop
-            output = {
-                "decision": "block",
-                "reason": f"Iteration {current_iteration}/{MAX_ITERATIONS}. Verification failed:\n{message}\n\nPlease fix the issues and try again.",
-            }
-            print(json.dumps(output, ensure_ascii=False))
-            sys.exit(0)
-    else:
-        # No verify commands, fall back to completion markers
-        markers = get_completion_markers(repo_root, task_dir)
-        all_complete, missing = check_completion(last_assistant_message, markers)
-
-        if all_complete:
-            # All checks complete, allow stop
-            state["iteration"] = 0
-            save_state(repo_root, state)
-            output = {
-                "decision": "allow",
-                "reason": "All completion markers found. Check phase complete.",
-            }
-            print(json.dumps(output, ensure_ascii=False))
-            sys.exit(0)
-        else:
-            # Missing markers, block stop and continue
-            output = {
-                "decision": "block",
-                "reason": f"""Iteration {current_iteration}/{MAX_ITERATIONS}. Missing completion markers: {", ".join(missing)}.
-
-IMPORTANT: You must ACTUALLY run the checks, not just output the markers.
-- Did you run lint? What was the output?
-- Did you run typecheck? What was the output?
-- Did they actually pass with zero errors?
-
-Only output a marker (e.g., LINT_FINISH) AFTER:
-1. You have executed the corresponding command
-2. The command completed with zero errors
-3. You have shown the command output in your response
-
-Do NOT output markers just to escape the loop. The loop exists to ensure quality.""",
-            }
-            print(json.dumps(output, ensure_ascii=False))
-            sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

package/dist/templates/codebuddy/commands/trellis/before-dev.md

@@ -1,29 +0,0 @@
-Read the relevant development guidelines before starting your task.
-
-Execute these steps:
-
-1. **Discover packages and their spec layers**:
-   ```bash
-   python3 ./.trellis/scripts/get_context.py --mode packages
-   ```
-
-2. **Identify which specs apply** to your task based on:
-   - Which package you're modifying (e.g., `cli/`, `docs-site/`)
-   - What type of work (backend, frontend, unit-test, docs, etc.)
-
-3. **Read the spec index** for each relevant module:
-   ```bash
-   cat .trellis/spec/<package>/<layer>/index.md
-   ```
-   Follow the **"Pre-Development Checklist"** section in the index.
-
-4. **Read the specific guideline files** listed in the Pre-Development Checklist that are relevant to your task. The index is NOT the goal — it points you to the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). Read those files to understand the coding standards and patterns.
-
-5. **Always read shared guides**:
-   ```bash
-   cat .trellis/spec/guides/index.md
-   ```
-
-6. Understand the coding standards and patterns you need to follow, then proceed with your development plan.
-
-This step is **mandatory** before writing any code.

package/dist/templates/codebuddy/commands/trellis/break-loop.md

@@ -1,107 +0,0 @@
-# Break the Loop - Deep Bug Analysis
-
-When debug is complete, use this command for deep analysis to break the "fix bug -> forget -> repeat" cycle.
-
----
-
-## Analysis Framework
-
-Analyze the bug you just fixed from these 5 dimensions:
-
-### 1. Root Cause Category
-
-Which category does this bug belong to?
-
-| Category | Characteristics | Example |
-|----------|-----------------|---------|
-| **A. Missing Spec** | No documentation on how to do it | New feature without checklist |
-| **B. Cross-Layer Contract** | Interface between layers unclear | API returns different format than expected |
-| **C. Change Propagation Failure** | Changed one place, missed others | Changed function signature, missed call sites |
-| **D. Test Coverage Gap** | Unit test passes, integration fails | Works alone, breaks when combined |
-| **E. Implicit Assumption** | Code relies on undocumented assumption | Timestamp seconds vs milliseconds |
-
-### 2. Why Fixes Failed (if applicable)
-
-If you tried multiple fixes before succeeding, analyze each failure:
-
-- **Surface Fix**: Fixed symptom, not root cause
-- **Incomplete Scope**: Found root cause, didn't cover all cases
-- **Tool Limitation**: grep missed it, type check wasn't strict
-- **Mental Model**: Kept looking in same layer, didn't think cross-layer
-
-### 3. Prevention Mechanisms
-
-What mechanisms would prevent this from happening again?
-
-| Type | Description | Example |
-|------|-------------|---------|
-| **Documentation** | Write it down so people know | Update thinking guide |
-| **Architecture** | Make the error impossible structurally | Type-safe wrappers |
-| **Compile-time** | TypeScript strict, no any | Signature change causes compile error |
-| **Runtime** | Monitoring, alerts, scans | Detect orphan entities |
-| **Test Coverage** | E2E tests, integration tests | Verify full flow |
-| **Code Review** | Checklist, PR template | "Did you check X?" |
-
-### 4. Systematic Expansion
-
-What broader problems does this bug reveal?
-
-- **Similar Issues**: Where else might this problem exist?
-- **Design Flaw**: Is there a fundamental architecture issue?
-- **Process Flaw**: Is there a development process improvement?
-- **Knowledge Gap**: Is the team missing some understanding?
-
-### 5. Knowledge Capture
-
-Solidify insights into the system:
-
-- [ ] Update `.trellis/spec/guides/` thinking guides
-- [ ] Update `.trellis/spec/backend/` or `frontend/` docs
-- [ ] Create issue record (if applicable)
-- [ ] Create feature ticket for root fix
-- [ ] Update check commands if needed
-
----
-
-## Output Format
-
-Please output analysis in this format:
-
-```markdown
-## Bug Analysis: [Short Description]
-
-### 1. Root Cause Category
-- **Category**: [A/B/C/D/E] - [Category Name]
-- **Specific Cause**: [Detailed description]
-
-### 2. Why Fixes Failed (if applicable)
-1. [First attempt]: [Why it failed]
-2. [Second attempt]: [Why it failed]
-...
-
-### 3. Prevention Mechanisms
-| Priority | Mechanism | Specific Action | Status |
-|----------|-----------|-----------------|--------|
-| P0 | ... | ... | TODO/DONE |
-
-### 4. Systematic Expansion
-- **Similar Issues**: [List places with similar problems]
-- **Design Improvement**: [Architecture-level suggestions]
-- **Process Improvement**: [Development process suggestions]
-
-### 5. Knowledge Capture
-- [ ] [Documents to update / tickets to create]
-```
-
----
-
-## Core Philosophy
-
-> **The value of debugging is not in fixing the bug, but in making this class of bugs never happen again.**
-
-Three levels of insight:
-1. **Tactical**: How to fix THIS bug
-2. **Strategic**: How to prevent THIS CLASS of bugs
-3. **Philosophical**: How to expand thinking patterns
-
-30 minutes of analysis saves 30 hours of future debugging.

package/dist/templates/codebuddy/commands/trellis/check-cross-layer.md

@@ -1,153 +0,0 @@
-# Cross-Layer Check
-
-Check if your changes considered all dimensions. Most bugs come from "didn't think of it", not lack of technical skill.
-
-> **Note**: This is a **post-implementation** safety net. Ideally, read the [Pre-Implementation Checklist](.trellis/spec/guides/pre-implementation-checklist.md) **before** writing code.
-
----
-
-## Related Documents
-
-| Document | Purpose | Timing |
-|----------|---------|--------|
-| [Pre-Implementation Checklist](.trellis/spec/guides/pre-implementation-checklist.md) | Questions before coding | **Before** writing code |
-| [Code Reuse Thinking Guide](.trellis/spec/guides/code-reuse-thinking-guide.md) | Pattern recognition | During implementation |
-| **`/trellis:check-cross-layer`** (this) | Verification check | **After** implementation |
-
----
-
-## Execution Steps
-
-### 1. Identify Change Scope
-
-```bash
-git status
-git diff --name-only
-```
-
-### 2. Select Applicable Check Dimensions
-
-Based on your change type, execute relevant checks below:
-
----
-
-## Dimension A: Cross-Layer Data Flow (Required when 3+ layers)
-
-**Trigger**: Changes involve 3 or more layers
-
-| Layer | Common Locations |
-|-------|------------------|
-| API/Routes | `routes/`, `api/`, `handlers/`, `controllers/` |
-| Service/Business Logic | `services/`, `lib/`, `core/`, `domain/` |
-| Database/Storage | `db/`, `models/`, `repositories/`, `schema/` |
-| UI/Presentation | `components/`, `views/`, `templates/`, `pages/` |
-| Utility | `utils/`, `helpers/`, `common/` |
-
-**Checklist**:
-- [ ] Read flow: Database -> Service -> API -> UI
-- [ ] Write flow: UI -> API -> Service -> Database
-- [ ] Types/schemas correctly passed between layers?
-- [ ] Errors properly propagated to caller?
-- [ ] Loading/pending states handled at each layer?
-
-**Detailed Guide**: `.trellis/spec/guides/cross-layer-thinking-guide.md`
-
----
-
-## Dimension B: Code Reuse (Required when modifying constants/config)
-
-**Trigger**: 
-- Modifying UI constants (label, icon, color)
-- Modifying any hardcoded value
-- Seeing similar code in multiple places
-- Creating a new utility/helper function
-- Just finished batch modifications across files
-
-**Checklist**:
-- [ ] Search first: How many places define this value?
-  ```bash
-  # Search in source files (adjust extensions for your project)
-  grep -r "value-to-change" src/
-  ```
-- [ ] If 2+ places define same value -> Should extract to shared constant
-- [ ] After modification, all usage sites updated?
-- [ ] If creating utility: Does similar utility already exist?
-
-**Detailed Guide**: `.trellis/spec/guides/code-reuse-thinking-guide.md`
-
----
-
-## Dimension B2: New Utility Functions
-
-**Trigger**: About to create a new utility/helper function
-
-**Checklist**:
-- [ ] Search for existing similar utilities first
-  ```bash
-  grep -r "functionNamePattern" src/
-  ```
-- [ ] If similar exists, can you extend it instead?
-- [ ] If creating new, is it in the right location (shared vs domain-specific)?
-
----
-
-## Dimension B3: After Batch Modifications
-
-**Trigger**: Just modified similar patterns in multiple files
-
-**Checklist**:
-- [ ] Did you check ALL files with similar patterns?
-  ```bash
-  grep -r "patternYouChanged" src/
-  ```
-- [ ] Any files missed that should also be updated?
-- [ ] Should this pattern be abstracted to prevent future duplication?
-
----
-
-## Dimension C: Import/Dependency Paths (Required when creating new files)
-
-**Trigger**: Creating new source files
-
-**Checklist**:
-- [ ] Using correct import paths (relative vs absolute)?
-- [ ] No circular dependencies?
-- [ ] Consistent with project's module organization?
-
----
-
-## Dimension D: Same-Layer Consistency
-
-**Trigger**: 
-- Modifying display logic or formatting
-- Same domain concept used in multiple places
-
-**Checklist**:
-- [ ] Search for other places using same concept
-  ```bash
-  grep -r "ConceptName" src/
-  ```
-- [ ] Are these usages consistent?
-- [ ] Should they share configuration/constants?
-
----
-
-## Common Issues Quick Reference
-
-| Issue | Root Cause | Prevention |
-|-------|------------|------------|
-| Changed one place, missed others | Didn't search impact scope | `grep` before changing |
-| Data lost at some layer | Didn't check data flow | Trace data source to destination |
-| Type/schema mismatch | Cross-layer types inconsistent | Use shared type definitions |
-| UI/output inconsistent | Same concept in multiple places | Extract shared constants |
-| Similar utility exists | Didn't search first | Search before creating |
-| Batch fix incomplete | Didn't verify all occurrences | grep after fixing |
-
----
-
-## Output
-
-Report:
-1. Which dimensions your changes involve
-2. Check results for each dimension
-3. Issues found and fix suggestions