# Task System

Canonical lightweight task system for cross-session agent work on `ballbox-first`.

## Purpose

Use one simple stack:
- `BACKLOG.md` for loose ideas and research
- `TASKS.md` for concrete actionable work
- `DONE.md` for completed work log
- session `todo` for live short-horizon execution state
- per-task folders under `/home/sebas/work/tasks/` for notes and artifacts

This keeps shaping, execution, and history separate.

## Canonical files

- `/home/sebas/pi-config/docs/BACKLOG.md`
- `/home/sebas/pi-config/docs/TASKS.md`
- `/home/sebas/pi-config/docs/DONE.md`
- `/home/sebas/work/tasks/`

## Meanings

### Backlog
Use `BACKLOG.md` for work that is still being shaped.

Typical statuses:
- `idea`
- `researching`
- `ready`
- `blocked`
- `done`

A backlog item should stay here if scope, payoff, or boundaries are still unclear.

### Tasks
Use `TASKS.md` for work that is concrete enough to execute.

Typical statuses:
- `queued`
- `active`
- `blocked`
- `done`

If a task has a clear deliverable and next step, it belongs here.

Each task should have a folder:
- `/home/sebas/work/tasks/T-xxx/`

Minimum standard for a real task folder:
- `README.md`
- `STATE.md`
- `artifacts/` when durable outputs exist

Optional files when useful:
- `EVIDENCE.md`
- `DECISIONS.md`
- `TASKS.md` for local substeps
- `UPDATES.md` for chronological progress
- `scratch/` for disposable drafts/tmp notes

Meaning:
- `README.md`: stable task identity, goal, source, scope
- `STATE.md`: current status, done gate, reality constraints, next step, blockers, evidence pointers
- `artifacts/`: generated outputs, screenshots, logs, sample files, exported evidence

Root hygiene:
- docs at task root
- durable outputs in `artifacts/`
- low-value intermediate clutter in `scratch/`
- task-specific scripts only if worth keeping

Do not use task folders as the final home for durable project docs when those docs belong in a repo or control-plane doc tree.

### Done
Use `DONE.md` for concise durable completion history.

When a task is completed:
1. remove it from `TASKS.md`
2. add a short durable completion entry to `DONE.md`
3. keep any lasting deliverable in its proper repo/doc location

### Session todo
Use `todo` for the live plan inside the current chat/session.

Do not rely on `todo` as durable storage.

## Promotion rules

- vague or exploratory -> `BACKLOG.md`
- concrete and actionable -> `TASKS.md`
- completed -> `DONE.md`

If a backlog item gains a real deliverable and immediate next action, promote it to `TASKS.md`.

If a task loses clarity or becomes too fuzzy again, demote it back to `BACKLOG.md`.

## ID conventions

- backlog items: `BB-xxx`
- tasks: `T-xxx`
- done entries: `D-xxx`

Keep `source` links between them.

## Agent behavior

When starting work:
1. check `TASKS.md` for current actionable items
2. check `BACKLOG.md` if the request is still exploratory
3. lock intent if not explicit: objective, binary done gate, exclusions, and reality constraints
4. if interactive UI is available and intent is materially unclear, prefer the `questionnaire` tool to capture the kickoff frame in one pass
5. use or create the task folder if working on a `T-xxx` item
6. update the durable docs when task state changes materially

### Compact kickoff template

Use this when a task needs intent locked before execution.

- Objective:
- Done gate:
- Exclusions:
- Reality constraints:
- Validation plan:

Short guidance:
- `Objective`: real outcome, not activity
- `Done gate`: binary user-visible finish line
- `Exclusions`: what will not be handled now
- `Reality constraints`: backend truth, data truth, auth/env limits, or any condition that makes a feature fake vs real
- `Validation plan`: how the done gate will be proven

Ultra-compact variant:

```md
Objective: ...
Done: ...
Not doing: ...
Truth limits: ...
Prove by: ...
```

When creating a new concrete task:
1. add it to `TASKS.md`
2. create the task folder under `/home/sebas/work/tasks/T-xxx/`
3. create at least `README.md` and `STATE.md`
4. create `artifacts/` if outputs/evidence are expected
5. put working notes/artifacts there until a better permanent home exists
6. if useful, record the validation plan or done checklist in the task folder early

Helper:
- `bin/task-init T-xxx --goal "..." --source "..."`
- creates `README.md`, `STATE.md`, `artifacts/`, and `scratch/`

For deterministic phase-machine tasks:
- `bin/task-phase-init T-xxx --goal "..." --source "..." --repo /path/repo`
- creates phase-aware `STATE.md`, `EVIDENCE.md`, `artifacts/`, `scratch/`, and `artifacts/evidence.html`
- canonical human-readable state should include a clickable evidence link, not just local file paths

When completing work:
1. validate against the locked done gate, not just code changes
2. move durable completion summary to `DONE.md`
3. leave the lasting artifact in the correct repo/doc path
4. keep concise validation evidence or handoff notes when they will save future sessions
5. keep the task folder only if it still has useful notes/artifacts

## Repo-local subsystems

Repos can have their own task subsystems when useful.

Recommended pattern:
- global system stays the portfolio/control-plane layer
- repo-local system handles implementation detail for that repo

Suggested split:
- global `BACKLOG.md`: cross-project ideas, research, sequencing
- global `TASKS.md`: top-level actionable items that matter across sessions
- repo-local tracker: implementation plan, substeps, repo-specific notes

Example for `~/ballbox`:
- global task: `T-005 - Apply BB-002 patterns in Ballbox`
- repo-local doc: `~/ballbox/docs/tasks/T-005.md` or `~/ballbox/TASKS.md`
- repo-local items can break the global task into smaller work units

Rules for working together:
- global task stays short and outcome-oriented
- repo-local tracker holds implementation detail
- repo-local task IDs can be nested, e.g. `T-005.1`, `T-005.2`, or use a repo prefix
- always link repo-local work back to the global `source`
- if repo work becomes independently important across sessions, summarize it back into the global docs

Use repo-local systems when:
- a task has many implementation substeps
- the repo has its own cadence and context
- multiple chats/agents may touch the same repo work

Do not duplicate everything both globally and locally. Keep:
- global = what and why
- local = how