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.
• depends_on decides readiness; file dependencies inform. depends_on names sibling directories; a task can start once each one, own or inherited, is implemented, approved, or revise. File edges between steps order builds and are reported as inputs, never gating: Effective Dependencies.
• 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        # ready tasks, each with its inputs whose producer is stale, missing, or failed
./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-sample-design
---

## 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

To do X	See
Create / rename / link / move tasks; bulk status propagation; append results programmatically	references/commands.md
Read or resolve task comments (the read/resolve loop; comments also surface via superra task read)	references/commands.md §Comments
Validate tree structure, fix status inconsistencies, diagnose orphaned depends_on entries	references/commands.md §Diagnostics
Rebuild steps, inspect change impact, or accept reviewed results	commands.md §Reproduction
Task-file anatomy, fields, status/dependencies, inherited context, results shape, stale-content, figure embedding	references/task-file-contract.md
Task companion-file classification, placement, reproducibility, promotion, and maturation	../using-superra/references/task-companion-files.md
Objective writing, task splitting, placement, durable homes, update-task lifecycle, retroactive task-tree creation	../superplan/references/task-tree-design.md
Migrate legacy PLAN.md + RESULTS.md, or upgrade superRA/ v1 → v2	references/internals.md §Migration
Dashboard server mechanics (idempotent ensure-running, task URLs, artifact export)	references/internals.md §Dashboard
Modify the skill itself (data layer, hooks, scripts)	references/internals.md; hook coverage details live in §Hook Architecture

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.