Guard8-ai · Eliran79 · Dec 21, 2025 · Dec 21, 2025 · Dec 21, 2025 · Dec 21, 2025
diff --git a/AGENTIC_AI_TASKGUARD_GUIDE.md b/AGENTIC_AI_TASKGUARD_GUIDE.md
@@ -5,15 +5,20 @@
 ```bash
 # Core commands
 taskguard init                                    # Initialize
-taskguard create --title "Task" --area backend    # Create task
+taskguard create --title "Task" --area backend \
+  --dependencies "setup-001"                      # Create (deps REQUIRED)
 taskguard list                                    # List tasks
 taskguard validate                                # Check dependencies
+taskguard validate --orphans                      # Check orphan tasks
 taskguard update status <id> doing                # Update status
 
-# Full create (recommended)
+# Full create (ALWAYS use --dependencies)
 taskguard create --title "Task" --area backend --priority high \
   --complexity 7 --dependencies "setup-001" --estimate "4h"
 
+# Orphan escape hatch (not recommended)
+taskguard create --title "Spike" --allow-orphan-task
+
 # Update commands (format: update <field> <id> <value>)
 taskguard update status <id> doing
 taskguard update status <id> done
@@ -31,14 +36,25 @@ taskguard archive                                 # Archive done tasks
 taskguard restore <id>                            # Restore archived
 ```
 
+## Causality Tracking (v0.4.0+)
+
+**Every task MUST have dependencies.** `setup-001` is auto-created by `taskguard init`.
+
+```
+setup-001 → backend-001 → api-001 → testing-001
+         ↘ frontend-001 → integration-001
+```
+
+If CAUTION appears: `taskguard update dependencies <id> "parent-id"`
+
 ## Workflow
 
 1. **Init**: `taskguard init && taskguard validate`
-2. **Create**: One task per area, set dependencies at creation
-3. **Start**: Read dependency task files first (check Session Handoff for context)
+2. **Create**: `--dependencies "setup-001"` or `"previous-task-id"`
+3. **Start**: Read dependency task files first
 4. **Validate**: `taskguard validate` after each change
 5. **Update**: Use CLI commands, not manual file editing
-6. **Complete**: `taskguard update status <id> done` + fill Session Handoff
+6. **Complete**: `taskguard update status <id> done`
 7. **Commit**: `git add -A && git commit -m "feat(area): description"`
 
 ## Areas
@@ -53,43 +69,22 @@ taskguard restore <id>                            # Restore archived
 
 `todo` → `doing` → `review` → `done` (or `blocked`)
 
-## Dependency Chain Example
-
-```
-setup-001 → backend-001 → api-001 → testing-001
-         ↘ frontend-001 → integration-001
-```
-
 ## Common Mistakes
 
 | Wrong | Right |
 |-------|-------|
-| All tasks in one area | Spread across areas |
+| No dependencies | **ALWAYS use `--dependencies`** |
+| Ignore CAUTION | Fix orphans immediately |
 | Manual YAML editing | Use CLI commands |
 | No validation | `taskguard validate` frequently |
-| No dependencies | Set with `--dependencies` flag |
 
 ## Troubleshooting
 
 ```bash
-taskguard validate          # See parse errors & blocked tasks
-taskguard list --area X     # Filter by area
-gh auth status              # Check GitHub auth (for sync)
-```
-
-## GitHub Sync
-
-```bash
-# Setup: create .taskguard/github.toml
-owner = "username"
-repo = "repo"
-project_number = 1
-
-# Sync workflow
-taskguard sync --github     # Push to GitHub
-taskguard archive           # Archive done (closes issues)
-taskguard restore <id>      # Restore (reopens issue)
+taskguard validate --orphans # See orphan tasks
+taskguard list --area X      # Filter by area
+gh auth status               # Check GitHub auth
 ```
 
 ---
-**Rule**: Use CLI for all metadata. TaskGuard manages flow, you execute tasks.
+**Rule**: Use CLI for metadata. Always use `--dependencies`. No orphans.
diff --git a/AI_IMPORT_MD_GUIDE.md b/AI_IMPORT_MD_GUIDE.md
@@ -70,6 +70,65 @@ TaskGuard uses **zero-padded 3-digit IDs**:
 
 Import-md automatically generates IDs in this format.
 
+## Causality Tracking (v0.4.0+)
+
+TaskGuard enforces **causality tracking** - every task should connect to the task graph.
+
+### Why Causality Matters
+
+- **Traceability:** Know where each task came from
+- **AI Agent Focus:** Stay on critical paths, avoid drift
+- **Post-mortem:** Trace bugs back to originating features
+- **Priority:** Dependency chains determine execution order
+
+### The Root Task: setup-001
+
+Every TaskGuard project has `setup-001` as the root task (like Java's Object).
+New tasks should trace back to it directly or transitively:
+
+```
+setup-001 (root)
+    ├── backend-001 (depends on setup-001)
+    │   └── api-001 (depends on backend-001)
+    └── frontend-001 (depends on setup-001)
+```
+
+### Declaring Dependencies in Markdown
+
+**Always specify dependencies** when authoring import markdown:
+
+```markdown
+### Fix #1: Setup Database
+**Priority:** HIGH
+**Area:** backend
+**Dependencies:** [setup-001]
+
+Database configuration and setup.
+
+### Fix #2: Implement API
+**Priority:** HIGH
+**Area:** backend
+**Dependencies:** [backend-001]
+
+REST API implementation.
+```
+
+### What Happens Without Dependencies
+
+If tasks are imported without dependencies, you'll see a CAUTION:
+
+```
+⚠️  CAUTION: 2 orphan task(s) created (no dependencies, nothing depends on them):
+   - docs-001: API Documentation
+   - testing-001: Unit Test Setup
+
+   Orphan tasks break causality tracking. Add dependencies with:
+     taskguard update dependencies docs-001 "api-001"
+     taskguard update dependencies testing-001 "setup-001"
+```
+
+**IMPORTANT:** The import SUCCEEDS but you must fix orphans!
+
 ## Dependencies Best Practices
 
 ### Syntax
@@ -78,7 +137,7 @@ Import-md automatically generates IDs in this format.
 ```
 
 ### Critical Post-Import Step
-**ALWAYS run `taskguard validate` after import** to:
+**ALWAYS run `taskguard validate --orphans` after import** to:
 - Verify all dependency task IDs exist
 - Detect circular dependencies
 - Check for broken references
@@ -181,9 +240,13 @@ To update existing tasks, edit them directly - import-md won't overwrite.
 
 ## Tips for AI Agents
 
+- **Always declare dependencies:** Every task needs a parent in the graph
+- **Start from setup-001:** First tasks in your analysis should depend on setup-001
+- **Chain dependencies:** Task #2 should depend on Task #1 if order matters
+- **Fix orphans immediately:** When CAUTION appears, add dependencies before proceeding
+- **Use validate --orphans:** Check for orphan tasks with `taskguard validate --orphans`
 - **Always specify Area:** Without it, tasks go to `setup/` by default
 - **Use realistic effort estimates:** Helps with planning and prioritization
-- **Group related tasks:** Use dependencies to enforce order
 - **Run validation:** Catch dependency issues immediately after import
 - **Check for conflicts:** Import-md skips existing IDs - plan accordingly
 - **Sync after import (GitHub integration):** Run `taskguard sync --github` after importing to create GitHub issues
@@ -248,5 +311,5 @@ AI: I'll create an analysis markdown, import it, and sync to GitHub:
 
 ---
 
-**Version:** 0.3.0
-**Last Updated:** 2025-01-05
+**Version:** 0.4.0
+**Last Updated:** 2025-12-21
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,32 @@
 
 All notable changes to TaskGuard will be documented in this file.
 
+## [0.4.0] - 2025-12-21
+
+### Added
+
+- **Causality tracking** - Every task must have dependencies to maintain semantic cause-effect chains
+- **CAUTION enforcement** - `taskguard create` fails without `--dependencies` flag, shows clear guidance
+- **Orphan detection** - `taskguard validate --orphans` identifies tasks with no dependencies or dependents
+- **`--allow-orphan-task` flag** - Escape hatch for spikes/research tasks that truly have no dependencies
+- **Archive protection messaging** - Clear feedback showing which tasks depend on blocked archive targets
+- **Orphan detection in import** - `taskguard import-md` warns about orphan tasks after import
+
+### Changed
+
+- **Create command** - Now requires `--dependencies` flag or `--allow-orphan-task` for explicit control
+- **Validate command** - Added `--orphans` flag to show orphan task details
+- **Archive messaging** - Improved feedback when tasks can't be archived due to dependents
+- **AI guides updated** - AGENTIC_AI_TASKGUARD_GUIDE.md and AI_IMPORT_MD_GUIDE.md include causality workflow
+
+### Philosophy
+
+TaskGuard v0.4.0 enforces causality tracking to improve AI agent workflows:
+- **Semantic chains**: Tasks form cause-effect relationships, not isolated items
+- **Root task**: `setup-001` is auto-created by `taskguard init` as the universal root
+- **CAUTION keyword**: AI agents pay attention to CAUTION more than warnings
+- **Soft enforcement**: Import warns but doesn't fail; create fails without deps
+
 ## [0.3.1] - 2025-12-15
 
 ### Added

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "taskguard"
-version = "0.3.1"
+version = "0.4.0"
 edition = "2024"
 description = "AI-ready local task management with Git integration and GitHub sync"
 license = "MIT"

diff --git a/README.md b/README.md
@@ -171,16 +171,31 @@ taskguard restore backend-001
 - Status mapping: todo→Backlog, doing→In Progress, done→Done
 - Archive lifecycle: archiving closes issues, restoring reopens them
 
-## 🎯 Core Concept: Dependency Blocking
+## 🎯 Core Concept: Causality Tracking
 
-TaskGuard's key innovation is **dependency blocking** - tasks automatically become unavailable until their prerequisites are completed. This ensures work happens in the right order without manual tracking.
+TaskGuard v0.4.0 introduces **causality tracking** - every task must have dependencies to form semantic cause-effect chains. This ensures AI agents and developers always understand *why* a task exists and *what* enables it.
+
+**Key principles:**
+- Every task must specify `--dependencies` (or `--allow-orphan-task` for spikes)
+- `setup-001` is auto-created by `taskguard init` as the universal root
+- Orphan tasks (no deps, no dependents) are detected and flagged
+- Tasks with active dependents cannot be archived
 
 **Example workflow:**
-1. Create foundation tasks (setup, architecture decisions)
-2. Create implementation tasks that depend on foundations
-3. Create testing tasks that depend on implementations
-4. Use `taskguard validate` to see what's ready to work on
-5. Tasks automatically become available as dependencies complete
+```bash
+# Initialize project (auto-creates setup-001 as root)
+taskguard init
+
+# Create tasks with dependencies (required)
+taskguard create --title "User auth" --area backend --dependencies "setup-001"
+taskguard create --title "Auth tests" --area testing --dependencies "backend-001"
+
+# Check for orphan tasks
+taskguard validate --orphans
+
+# Validate dependency chain
+taskguard validate
+```
 
 ## 📋 Task Format
 
@@ -309,6 +324,13 @@ TaskGuard provides information and suggestions but never makes decisions for you
 - ✅ Restore command with GitHub issue reopening
 - ✅ Task-issue mapping persistence with archived state tracking
 
+**✅ Phase 6 (v0.4.0 - COMPLETED): Causality Tracking**
+- ✅ Mandatory dependencies for all tasks (except root and spikes)
+- ✅ Orphan task detection with `validate --orphans`
+- ✅ `--allow-orphan-task` escape hatch for research tasks
+- ✅ Archive protection for tasks with active dependents
+- ✅ CAUTION messaging for AI agent attention
+
 ## 🤖 For AI Agents & Automation
 
 TaskGuard is designed to work seamlessly with agentic AI systems like Claude Code. If you're building AI agents that need to manage tasks systematically:

diff --git a/docs/api-reference/commands.md b/docs/api-reference/commands.md
@@ -18,10 +18,10 @@ Creates `.taskguard/` config and `tasks/` directories.
 ---
 
 ### `taskguard create`
-Create a new task.
+Create a new task. **Dependencies are required** (v0.4.0+).
 
 ```bash
-taskguard create --title "Task name" --area backend [OPTIONS]
+taskguard create --title "Task name" --area backend --dependencies "setup-001"
 ```
 
 | Flag | Short | Description |
@@ -31,9 +31,15 @@ taskguard create --title "Task name" --area backend [OPTIONS]
 | `--priority` | `-p` | low, medium, high, critical |
 | `--complexity` | | 1-10 scale |
 | `--tags` | | Comma-separated tags |
-| `--dependencies` | `-d` | Comma-separated task IDs |
+| `--dependencies` | `-d` | Comma-separated task IDs (required unless `--allow-orphan-task`) |
 | `--assignee` | | Task assignee |
 | `--estimate` | `-e` | Time estimate (e.g., "4h") |
+| `--allow-orphan-task` | | Allow task without dependencies (for spikes/research) |
+
+**Causality Tracking (v0.4.0+):**
+- Every task must have dependencies to maintain semantic chains
+- Use `--allow-orphan-task` for root tasks or research spikes
+- Shows CAUTION if no dependencies specified
 
 ---
 
@@ -51,11 +57,20 @@ taskguard list items <task-id>    # List checklist items
 Check dependencies and show available tasks.
 
 ```bash
-taskguard validate
+taskguard validate [--orphans]
 ```
 
+| Flag | Description |
+|------|-------------|
+| `--orphans` | Show orphan tasks (no dependencies and no dependents) |
+
 Shows: available tasks, blocked tasks, parse errors, GitHub sync status.
 
+**Orphan Detection (v0.4.0+):**
+- Orphan = task with no dependencies AND nothing depends on it
+- `setup-001` is exempt (universal root)
+- Use `--orphans` to see detailed orphan task list
+
 ---
 
 ### `taskguard update`