Task Tree

Core Concepts

• Task — an immediate subdirectory of a task directory or the rootless ./superRA forest that contains task.md. attachments/ is always an asset container, never a task. A leaf task has no child task directories.
• Filesystem hierarchy is the task hierarchy. walk_plan() discovers children by scanning subdirectories.
• Retained files are companions, not task nodes — classification, placement, and lifecycle in ../using-superra/references/task-companion-files.md.
• Dependencies are sibling-only. depends_on values are sibling directory names within the same parent.
• Parent status rolls up from children automatically — approved only when all active (non-parked) children are approved; archived and postponed children are excluded.
• DAG order vs. display order. The dependency DAG controls execution order; numeric directory prefixes (01-load, 02-merge) control display order only. Independent.

CLI Setup

Bootstrap a fresh project's wrapper from the loaded skill directory (<skill-dir> = the directory holding this SKILL.md; substitute the real path), then use the wrapper for everything after:

uv run --script <skill-dir>/scripts/cli.py wrapper init   # writes superRA/superra (planner/main bootstrap)
./superRA/superra wrapper init                             # refresh an existing wrapper; idempotent

Reading the Tree

Run the committed ./superRA/superra wrapper created above — contributors inside the superRA checkout substitute uv run --script skills/task-tree/scripts/cli.py. Every superra … example below and in the references denotes it:

./superRA/superra task tree            # tree with status badges
./superRA/superra task frontier        # dispatchable leaf tasks
./superRA/superra task dag 01-data     # dependency DAG for a subtree (Mermaid)
./superRA/superra task tree --json     # JSON output
./superRA/superra dashboard --no-open  # idempotent; starts or reuses a server and prints this worktree's scoped URL

Deep-link a dashboard task: append #/<task-path> to the scoped URL from dashboard --no-open. <task-path> is the task read locator (no superRA/ prefix, empty for the tree root). Use the emitted URL as-is — its URL-encoded ?wt= selector handles worktree-name collisions.

Task File Format

---
title: "Merge with Fund Characteristics"
status: not-started
depends_on:
  - 01-load-raw-data
---

## Objective

Left join holdings with fund characteristics on fund_id x date.
Use CRSP-style merge conventions. Validate row counts post-merge.

## Results

Left join preserved all 4.7M holdings rows.
Quarterly characteristics were matched to monthly holdings by nearest prior date.

## Review Notes
> [BLOCKING] Inner join used instead of left join

Field-by-field anatomy and body-section ownership: references/task-file-contract.md §Task Anatomy.

Routing — operate on the tree

Intentional task path changes go through superra task move (task rename for same-parent compatibility), never raw mv / git mv. It resolves the fallout — relative Markdown links tree-wide and sibling-only depends_on edges — so run the move directly rather than rewriting links or rewiring dependencies by hand first. Mechanics and cross-parent dependency rules: references/commands.md §Move / rename a task.