feat: round-aware TASK_SPEC — brief reference on round 2+ to save context window

[lukstafi]

Summary

• Add taskSpecBriefText() in src/orchestration/skills.ts that returns a compact 2–3 line reference: task ID, title, and proposal file path
• Make TASK_SPEC in buildSkillContext() use the full form on round 1 and the brief form on round 2+, reducing context-window usage in multi-round sessions
• Add TASK_SPEC_BRIEF as an always-brief companion variable for templates that want explicit control

Test plan

• bun run typecheck — clean
• bun test src/orchestration/skills.test.ts — 18 tests pass (was 13; 3 new cases added)
• Existing full-form proposal tests pinned to round: 1 to preserve their intent
• New tests: round-conditional behaviour (round 1 full / round 2+ brief / round 3 still brief), TASK_SPEC_BRIEF always brief, no-taskId fallback

Closes task-bc93f2af.

🤖 Generated with Claude Code

[lukstafi]

Refactor Notes — task-bc93f2af (Coder)

What I'd do differently next time

1. Avoid reading the task file twice in buildSkillContext()

buildSkillContext() already reads the task file to extract proposalPath (lines 218–223). taskSpecBriefText() then reads the same file again independently. A cleaner approach would be to extract the proposal path once, pass it as a parameter, or factor out a shared readTaskFrontmatter() helper that both callers use. This eliminates a redundant readFileSync on every context build on round 2+.

// Proposed helper
function readTaskProposalRef(taskId: string): string {
  const content = readFileIfExists(join(harnessDir(), "tasks", `${taskId}.md`));
  const m = content?.match(/^proposal:\s*(.+)$/m);
  const v = m?.[1]?.trim().replace(/^["']|["']$/g, "") ?? "";
  return v && v !== "inline" && v.toLowerCase() !== "null" ? v : "";
}

2. Pass proposalRef directly to taskSpecBriefText()

Rather than re-deriving the proposal path, buildSkillContext() could pass the already-computed proposalPath to taskSpecBriefText():

function taskSpecBriefText(state: OrchestrationState, proposalRef: string): string { ... }
// called as:
TASK_SPEC: state.round <= 1 ? taskSpecText(state) : taskSpecBriefText(state, proposalPath),
TASK_SPEC_BRIEF: taskSpecBriefText(state, proposalPath),

This makes the data flow explicit and avoids the double read.

3. Consider a TASK_SPEC_FULL escape hatch

Currently there's no way for a template to force the full form on round 2+. Adding TASK_SPEC_FULL: taskSpecText(state) would give templates full control without conditional logic in buildSkillContext(). However, this adds an unconditional full read on every context build (negating the optimization for the common case), so it should only be added if a real use-case emerges.

4. Test helper for task fixture setup

The three new tests each repeat the same fixture scaffolding (mkdir harness/tasks, write task file, set env var, cleanup). A small withTaskFixture(taskId, frontmatter, callback) helper would reduce boilerplate and make future tests easier to write.