small-scripts/specs/auto-draft.spec.md

auto-draft

Purpose

Scan the writing dossiers for AI-pipeline work and schedule jobs in priority order, using only the "spare" capacity of the current subscription window. Designed to be run from a cron job (hourly) so that it picks up work as spare capacity appears.

The script is dryrun-only in this revision: it shows the spare capacity and the three priority queues, but does not execute any jobs. Job execution is a later stage.

Usage

auto-draft --provider <provider> --threshold <pct> --polish-score <0-10> [OPTIONS]

Required:
  --provider PROVIDER     Subscription provider to draw capacity from: anthropic or minimax
  --threshold PERCENT     Maximum subscription utilisation allowed over the period, as a
                          percentage (e.g. 50 = use up to 50% of the weekly allowance).
                          The script computes the linear limit at the current point in the
                          period and reports the spare capacity.
  --polish-score N        Paragraph score below which a paragraph is queued for polishing
                          (e.g. 7 means "polish any paragraph with score < 7").

Options:
  --base-dir PATH         Root directory to scan for dossier files. Defaults to ".".
                          Recurses into subdirectories.
  -n, --dryrun            Show capacity and queues without executing. This is the default
                          behaviour for this revision; the flag is explicit so the cron
                          command line is self-documenting.
  -h, --help              Show this help message and exit.

Behaviour

1. Probe the live subscription for the given provider. The script shells out to agent-subscriptions --output json and reads the relevant provider's seven_day window.
2. Compute the spare capacity against the supplied threshold:
   • last_renewed = reset_at - 7 days (the weekly window is treated as a rolling 7-day period)
   • period_seconds = 7 * 86400
   • elapsed_seconds = max(0, now - last_renewed)
   • limit_pct = elapsed_seconds / period_seconds * threshold (the linear allowance at this point in the period)
   • spare_pct = limit_pct - utilization_pct (positive = under budget, negative = over budget)
3. Discover titles by scanning for *.overview.md source files under --base-dir (recursively). Each title is the stem of the source file (e.g. 01-ai-is-an-amplifier); the numeric ID is the leading digits before the first -.
4. Build three priority queues, in priority order:
   • Polish queue (highest priority) — for every title whose *.ai_score.<provider>.md exists, parse the file and find paragraphs with score < polish_score and not marked exempt. If any such paragraph exists, the whole title is queued for polish.
   • Scoring queue (second priority) — for every title whose *.ai_generated.<provider>.md exists but whose *.ai_score.<provider>.md does not. The job is to score the generated file.
   • Generation queue (lowest priority) — for every title whose *.ai_generated.<provider>.md does not exist. The job is to generate the draft from the source brief.
5. Sort each queue by numeric ID ascending (titles without a numeric ID sort last).
6. Print the spare capacity and the three sorted queues.

Score file format

The *.ai_score.<provider>.md files embed per-paragraph scores and an exempt marker as inline HTML comments after each paragraph:

This is a great paragraph with polish. <!-- score: 9 -->

This is a middling paragraph. <!-- score: 6 -->

This is already reviewed and acceptable. <!-- score: 5 --><!-- exempt: true -->

Regex patterns:

• Score: <!--\s*score:\s*(\d+)\s*-->
• Exempt: <!--\s*exempt:\s*true\s*-->

A paragraph is queued for polish if it has a score comment with a value below polish-score AND does not have an exempt comment. Paragraphs without a score comment are not eligible for polishing (they are skipped), even if the file contains other scored paragraphs.

Spare capacity output

[auto-draft] Spare capacity for Anthropic
  Reset at:        2026-08-07T23:00:00+00:00
  Renewed at:      2026-07-31T23:00:00+00:00
  Elapsed:         16h 18m of 7d (9.7%)
  Threshold:       50.0%
  Linear limit:    4.9%
  Current usage:   41.2%
  Spare capacity:  -36.4% (over budget; do not queue any work)

For a healthy budget:

  Spare capacity:  23.5% (under budget)

Queue output

[auto-draft] Polish queue (priority 1) — 3 items
  01-ai-is-an-amplifier          2 paragraphs below 7 (of 4 scored)
  02-five-layers-of-an-agent-harness  1 paragraph below 7
  05-the-compound-engineering-loop   3 paragraphs below 7

[auto-draft] Scoring queue (priority 2) — 1 item
  03-shadow-agents-are-the-new-shadow-it

[auto-draft] Generation queue (priority 3) — 8 items
  04-risk-proportionate-delivery
  06-backpressure-is-coming-for-your-ci
  07-tests-are-law-llms-are-not-the-judge
  ...

Edge cases

• If the provider probe fails (available: false), print a warning and skip the capacity section. Still build and print the queues.
• If the seven-day reset_at is missing, skip the capacity section (cannot compute last_renewed). Still build and print the queues.
• If a title has no numeric ID prefix, sort it last in every queue.
• If the base directory contains no source files, print all three queues as empty.
• If a source file's directory also contains the ai_score and ai_generated files, the title is in the polish queue (or none, if all paragraphs pass). Otherwise scoring or generation.
• Exit 0 unless the CLI args are invalid. The script is informational; one bad provider probe should not fail the cron.

Dryrun behaviour

This revision is dryrun-only. The script always prints the capacity and queues. Job execution is out of scope until the design is approved.

Examples

auto-draft --provider anthropic --threshold 50 --polish-score 7
auto-draft --provider anthropic --threshold 50 --polish-score 7 --base-dir /home/paul/dev/claude/writing/oreillyconsulting
auto-draft --provider minimax --threshold 70 --polish-score 8 --dryrun