# Durable tasks for T3 Code — design exploration (rev. 2, post-feedback)

Artifacts (open `index.html` for the maintainer-facing recommended direction):

| File | Contents |
|---|---|
| `concept-a-inbox.html` | Concept A — global email-like task inbox (triage: sweep, snooze, done) |
| `concept-b-ledger.html` | Concept B — dedicated per-project task ledger with detail panel |
| `concept-c-conversation.html` | Concept C — conversation-first; chips in threads + overlay index |
| `concept-d-workbench.html` | Concept D — intent-above-execution workbench (task → attempts) |
| `index.html` | Maintainer-facing presentation (the hosted root) |
| `ledger-annotated.html` | Full annotated design frames behind the presentation |
| `explorations.html` | Linked tour of the four earlier concepts and the recommended direction |
| `SPEC.md` | Shared token/component spec derived from the real codebase |
| `FEEDBACK.md` | Product feedback that drove revision 2 |
| `CLAUDE-REVISION-BRIEF.md` | Maintainer-facing copy and responsive redesign brief |

Note: the four concept sheets predate revision 2 and retain the original bare-`#` capture
syntax; `index.html` and this document are the revised, current direction.

---

## 1 · The problem, restated

During weeks of agent-assisted work, a developer constantly notices work that is real but not
now: bugs, debt, missing tests, deferred decisions. Today those findings have only two homes —
the conversation (which compacts, scrolls away, and is provider memory at best) or an external
tracker (which demands ceremony the finding doesn't deserve yet). What's missing is a durable,
near-zero-friction record of **agreed outstanding work** that both the user and any agent can
write and read, months later, without reconstructing the conversation that produced it.

The central test: *casually record a finding today, trust it is safe, understand it months
later, start it without archaeology.*

## 2 · Mental model

**A ledger, not a tracker.** Tasks record **intent**; threads record **execution**; an
**attempt** is the explicit link between them — one bounded episode of work toward a task.
A task may sit quietly for weeks; that is a healthy state, not a red badge.

Foundational invariants (treat as product law):

- A Task can exist without a Thread; a Thread can exist without a Task.
- A Task can have several Attempts; a Thread can participate in several Tasks;
  one Thread can hold several Attempts. Manual completion is a completion **event** with
  evidence — no Attempt is manufactured for it (the schema still allows threadless attempts,
  e.g. work done outside T3 that the user wants recorded as an episode).
- Provider plans/todos belong to Turns, never Tasks.
- Completing an Attempt does not complete the Task — the agent proposes, the human closes.
  ("Close automatically after verified completion" may become a preference later.)
- Deleting an origin thread never deletes the Task (the excerpt is copied at capture).
- Original capture text is immutable; enrichment is additive and attributable.
- Task lifecycle vocabulary (Open / Done / Dropped) is disjoint from run vocabulary
  (Working / Failed / …); run state renders only as an attempt chip in thread-status colors.

**Terminology.** Keep **Task** for the durable record and **Thread** for conversation. Mobile's
existing "New Task" draft flow collides with this; the leading option is renaming it to
"New thread" / "Start work", but renaming an established primary action needs its own
validation — options are tabulated in FEEDBACK.md and the decision is deliberately left open.

## 3 · Capture semantics (revised)

**`#` references; `/task` and explicit actions create.** Bare `#` had too many collisions
(markdown headings, issue refs, shell comments, pasted code) and gave one token two meanings.
`#245` remains the identity and autocomplete trigger everywhere.

Two capture paths, chosen by construction — T3 never classifies composer text or silently
reroutes a message:

| User action | Active agent sees it? | Who writes the brief? |
|---|---|---|
| `/task …` in the composer | No | Auxiliary text-gen model |
| ⌘⇧T quick capture / palette | No | Auxiliary text-gen model |
| Select conversation text → **Log as task** | No | Auxiliary model, seeded with the selection |
| "Log that as a task" in chat | Yes | The active agent via `t3_task_create` |
| Agent proposes a follow-up | (agent-initiated) | User accepts the proposed record |

Out-of-band capture is the guaranteed-non-interrupting path; conversational capture is the
context-richer path (the agent knows what "that" means). Both create the same canonical task
and the same timeline chip.

**Raw-first storage.** The sequence is: user invokes capture → exact words stored → id
assigned → chip confirms it's safe → enrichment lands asynchronously → original capture
remains permanently. If enrichment fails, the task is merely less polished, never lost.

**Enrichment** reuses T3's existing text-generation service (default `gpt-5.6-luna`, low
effort — the same path that writes thread titles, branch names, and commit messages), with a
bounded capture packet modeled on title regeneration: capture text, originating user message,
a small conversation window, attachment descriptors, file paths/symbols (not contents).
Structured response: title, description, optional repro steps, files each labelled with a
`basis` — `mentioned` / `recently-changed` / `inferred` — and open questions. Enrich lightly
at capture; deep investigation (re-reading origin, checking staleness, reproduction) belongs
to the full agent when the task is *started*, weeks later, against current code.
**Automatic enrichment remains contingent on the billing/telemetry decision** — it is
asynchronous and nonessential by design, so disabling it degrades gracefully to raw captures
that are fully functional tasks. Reuse the global text-gen model selection rather than adding
a new setting.

**Multiline literalness:** once capture mode is entered (`/task`, shortcut, or selection),
everything typed or pasted is literal task content — subsequent lines beginning with `#`,
shell comments, code fences, and other syntax are content, never commands. This must be an
explicit test case.

**Attribution.** The detail view distinguishes, quietly but structurally: the user's exact
original capture (immutable) · excerpts copied from conversation · the model-written brief
(labelled) · per-file basis tags · facts later verified by an executing agent (in History).
A cheap model's confident guess must never masquerade as user fact for six weeks.

## 4 · The chip (timeline task reference)

One line, anchored at the capture point: `Task created · #245 · <title> · Current: Open`.
The creation event is immutable; the status is explicitly labelled **Current** — the chip is a
live reference, not a snapshot, so the historical transcript stays honest while still telling
you the task is now Done. States: raw ("saved · writing brief…") → enriched → live.

## 5 · Retrieval, start, completion, reopen

- **Retrieval:** ask conversationally (agent calls `t3_task_list`/`get`), open the ledger, or
  type `#245` anywhere.
- **Start:** default = new focused thread seeded with the task record (original capture,
  brief, files, prior attempts), standard provider/model picker — logged by Claude, executable
  by Codex. "Continue in current thread" one click away; conversational "let's work on #245"
  continues in place.
- **Completion:** attempt ends → task stays Open → agent proposes closure with summary +
  evidence (tests, screenshot, diff) → human clicks Done or says "close it".
- **Reopen:** one click, records who/why, preserves attempts and evidence for the next agent.

## 6 · Object model — target model

This is the mature schema the design grows into, **not** the V1 schema (V1 ships Open/Done
with no blocked/snooze/pin and no Dropped):

```
Project
├── Tasks
│   └── Task #245
│       ├── immutable original capture
│       ├── durable enriched brief (attributed)
│       ├── provenance references (+ copied excerpt)
│       ├── lifecycle: Open / Done / Dropped (+ blocked reason, snooze, pin)
│       └── Attempts
│           ├── Attempt 1 → Thread A / Turn 48 · provider/model · outcome · evidence
│           └── Attempt 2 → Thread B / Turn 1
└── Threads
    ├── Thread A — turns · provider plans · task-reference events
    └── Thread B
```

## 7 · Provider neutrality (revised)

T3 owns the canonical store and exposes `t3_task_create / get / update / list` to every
provider. **Do not alias Claude Code's native Task tools** — native Tasks are often internal
execution coordination (subagent fan-out, dependencies) and redirecting every `TaskCreate`
would flood the ledger with ephemeral steps. Instead, provider instructions teach the
distinction: durable future work → T3 tasks; current-execution coordination → native tools.
Import/export can come later if a real need emerges. Provider-owned and synced models remain
rejected (durability and trust respectively).

## 8 · Open product questions

- **Project identity:** users will expect `t3code#245` to mean the same work across
  environments, worktrees, clones, and devices. If tasks are environment-local that breaks;
  anchoring task-project identity (likely to repository identity rather than path) is a
  product-level decision that precedes storage design.
- **Mobile "New Task" naming** (above).
- **Auto-close preference** timing and defaults.

## 9 · V1 — slice vs. shipped (revised again)

**First implementation slice** — desktop/web validates capture, ledger, retrieval, and
execution linkage: T3-owned project tasks · explicit out-of-band capture (`/task` + shortcut)
· `t3_task_*` tools for one or two providers · stable `#n` ids · immutable capture + editable
title/description · Open/Done · origin excerpt + deep link · ledger + detail panel · Start in
a new thread · complete/reopen · the timeline chip.

**Shipped V1** — adds minimal mobile before the feature is called complete, because T3's
promise is multi-surface and mobile is where a thought is most likely to be lost: quick
capture (raw-first, offline-safe) · compact project task list · task detail sufficient to
understand and reference · `#245` deep links. Starting attempts, editing briefs, provenance
layers, evidence-based completion, and organization stay desktop-first.

Then, in order: ① continue-in-thread + richer attempt history ② snooze & pinning
③ blocked-by ④ evidence chips ⑤ remaining providers ⑥ external promotion / provider
import.

**Never:** boards, sprints, story points, assignees, due dates, required tags.

## 10 · Recommendation

**The Project Ledger #** — Concept B's chassis, Concept C's chip/provenance language,
Concept A's attention model, Concept D's attempt separation. See `index.html` for the maintainer presentation and `ledger-annotated.html` for the
polished mockup: the six-weeks-later ledger, the revised capture pair (S1 out-of-band `/task`,
S2b conversational), chip state anatomy, attribution in the detail panel, the
attempt-proposes/human-closes completion moment, reopening, mobile frames, and the object
model with its invariants.

**Next stage:** not another broad concept — interaction validation, focused on capture
(`/task` incl. multiline paste, conversational, agent-proposed), retrieval six weeks later,
and the Task → Attempt → Thread relationship.