surplus

name	surplus
description	Surplus Burn Mode — find + rank the highest value-density backlog work to consume unused Claude usage productively. Phase 1 (--plan) scans and ranks. Phase 2 (+<budget>) auto-executes ranked tasks within a budget envelope (SAFETY tasks routed to needs-you list).
trigger	*surplus, *surplus --plan, *surplus +<budget> (e.g. +2M), or user asks to surface highest-value backlog work to use up surplus usage.

Surplus Burn Mode — Phase 1 (Scan + Rank)

Read-only. Phase 1 does NO execution and NO mutation of any backlog source. It writes exactly two artifacts: the ranked plan (.md) and its machine-readable sidecar (.json). Nothing else on disk changes.

What this mode does

Scans TAD's backlog sources + one OBJECTIVES-driven generator, ranks every candidate value-first (expected_value = value × confidence; density is only an efficiency tiebreaker), tags risk/safety, and produces a ranked plan you can act on to consume unused weekly Claude usage on the highest-value work.

It does not pick anything up and run it. Choosing what to execute (and actually executing it) is Phase 2 — see below.

Commands

*surplus --plan (and bare *surplus)

1. Stamp the date. Compute today's date string YYYY-MM-DD (the date lives at this SKILL boundary so the workflow stays free of Date.now() / new Date()). Call it <stamp>. Use the same <stamp> for the filename and the artifact header.
2. Invoke the scan workflow:

   Workflow({
     name: 'surplus-scan',
     args: {
       date: '<stamp>',
       output_path: '.tad/active/SURPLUS-PLAN-<stamp>.md'
     }
   })
   

3. Persist the two artifacts. The workflow runtime is sandboxed (no filesystem access), so it returns the rendered content. Write them yourself with the Write tool:
   • result.plan_markdown → result.plan_path (.tad/active/SURPLUS-PLAN-<stamp>.md)
   • result.sidecar_json → result.json_path (.tad/active/SURPLUS-PLAN-<stamp>.json) The .json sidecar is the Phase-2 contract — Phase 2 reads JSON, never the Markdown.
4. Display the ranked plan table + the totals summary (total / dropped / stale / auto-eligible / needs-human) and point the user at the 🔒 Needs You section.

*surplus +<budget> (e.g. *surplus +500K, *surplus +2M)

Phase 2: Auto-execute ranked surplus tasks within a budget.

1. Parse budget. Extract the numeric value: +500K → 500000, +2M → 2000000. If the format is unrecognized, print an error and stop.
2. Read the latest sidecar:

   ls -t .tad/active/SURPLUS-PLAN-*.json | head -1
   

   Parse the JSON. If no sidecar exists, tell the user to run *surplus --plan first.
3. Stamp the date. Same YYYY-MM-DD stamping as --plan.
4. Invoke the execution workflow:

   Workflow({
     scriptPath: '.claude/workflows/surplus-execute.workflow.js',
     args: {
       sidecar_rows: <parsed JSON .rows array>,
       date: '<stamp>'
     }
   })
   

5. Persist the report. Write result.report_markdown to result.report_path (.tad/active/SURPLUS-REPORT-<stamp>.md).
6. Display summary:
   • Executed: N tasks (tokens spent)
   • Failed: N tasks (skipped)
   • Needs You: N SAFETY tasks
   • Point user to the full report path.

Hard boundaries (Phase 1)

• No execution. This mode never picks up a ranked item and works on it. It only scans, ranks, and reports.
• No mutation of backlog sources (.tad/active/ideas/, epics/, NEXT.md, OBJECTIVES.md). Read-only.
• Exactly two writes: the plan .md and its .json sidecar, both under .tad/active/ at the SURPLUS-PLAN-<stamp> stem. Any other write is a violation.
• auto_eligible is advisory only in Phase 1 — it flags what would be safe to auto-run later. Phase 1 runs nothing regardless of the flag.

Phase 2 — Budget-Loop Auto-Execution

Phase 2 is wired via *surplus +<budget>. It reads the JSON sidecar, filters auto-eligible rows (SAFETY tasks routed to "needs-you"), synthesizes ephemeral Epics, and runs each through yolo-epic within the budget envelope.

Key safety properties:

• SAFETY zero-execution: safety_flag === true tasks are never executed (strict equality)
• Sidecar validation: fail-closed (throw on malformed rows, not silent skip)
• Circuit breaker: 3 consecutive failures → stop loop
• Budget guard: stops when budget.remaining() < 250K reserve
• yolo-epic contract: 7 explicit keys, result.error/stop_reason for failures (no try/catch)