Skip to main content

ADR-006 — Effort workflow as the training-trace engine (GitHub is SoT; MDX plans retired)

canonical · tech-lead · updated 2026-06-20 · source

Status​

Accepted (José, 2026-06-20). Builds on ADR-004 (plans→graph) and ADR-005 (tasks→graph); implements their direction with GitHub as the operative source of truth until the graph lands.

Context​

Two recurring failures and one new requirement converged:

  1. Board drift — the close path closed GitHub issues but never set the Projects v2 Status to Done (the Done step lived only in the skippable kit-task-close), and every in-worktree board mutation silently no-op'd because scripts/.project-ids.env was gitignored + absent in worktrees. Result: 185 closed/merged items still showing active. Fixed by #532.
  2. Plan drift — MDX plans in apps/admin/src/plans/ carried a hand-maintained status: and a ## Deliverables PR table: a second copy of what issues/PRs already said, which drifted (most plans marked Active/Draft while their tracking issue was CLOSED). A separate plan file is one more thing to sync.
  3. Training traces — the dev workflow is the corpus for the tedos builder model. The structured workflow (goal → plan → patch → verify → outcome) is exactly a builder-agent trajectory dataset.

Decision​

GitHub is the single source of truth. The effort schema is the dataset schema.

  • Effort model — 1 effort = 1 parent issue · 1 branch · 1 worktree · 1 PR. No forced tiny PRs; big effort-PRs are fine while building. 1 effort = N native GitHub sub-issues (parallel | sequential, assessed at scoping). Sub-issues run in their own worktrees, merge into a local effort/<N> integration branch, and the effort opens one PR to develop.
  • Plans live in the parent issue, not in MDX. The parent issue body IS the plan (Goal · Scope · ## For agents · Verification · sub-issue DAG). The MDX-plan requirement is removed. Strategy/roadmap narrative → knowledge/ (selectively, what is still true). /plans + /roadmap (static lib/roadmap.ts) are replaced by one GraphQL issue-state view generated from GitHub.
  • kit-effort-close is one deterministic op: merge the effort PR → close parent + all sub-issues → set board Done for all → snapshot each sub-branch diff (BEFORE squash) into the trace → kit-gc prune worktrees/branches.
  • Training trace — builder-agent full trajectory; per-sub-issue diffs preserved pre-squash; the Plan Engine graph (ADR-004/005) is the canonical store, GitHub-operative + graph-ingestable until then; labels auto from outcome (merged=positive · abandoned/reverted=negative) + a manual gold flag.

The operational contract (lifecycle + parent-issue template) lives in .claude/rules/effort-model.md.

Consequences​

  • One source (GitHub) replaces three drifting surfaces (MDX status:, lib/roadmap.ts, the board).
  • Board + plan state are correct by construction (the close op owns them), not by discipline.
  • The dev workflow emits a clean builder-trajectory dataset for free.
  • Migration is staged (6 phases) so no data is lost and no UI breaks: data lands in issues before MDX is deleted; MDX is deleted only after the GraphQL view is live.

Hard rules​

  • Secrets scrubbed from diffs/bodies before they enter an issue or the dataset.
  • Tenant/client data never mixes with the dev-workflow corpus (two datasets; connectors are product).
  • Artifacts English (also = a clean monolingual corpus).