batch-article

/batch-article — Bulk full-pipeline content production

For agency-scale ops: give a list of keywords, get a list of published articles. Each goes through the COMPLETE /article pipeline — no shortcuts, no quality compromises.

When to invoke

• /batch-article --project my-site --file keywords.txt
• /batch-article --project my-site --keywords "kw1,kw2,kw3"
• /batch-article --resume <batch_id> — pick up after interruption
• /batch-article --status <batch_id> — check progress
• /batch-article --list — all known batches

Input file formats (auto-detected)

Plain text (.txt) — one keyword per line, optional comma-separated fields:

best fishing rods 2026, listicle
how to choose fishing rod, how-to-guide, professional, 4500
graphite vs fiberglass rods, comparison

CSV (.csv) — header with keyword column required:

keyword,format,voice,word_count
"best fishing rods 2026",listicle,professional,6000
"how to choose fishing rod",how-to-guide,casual,4500

JSON (.json) — array of objects:

[
  {"keyword": "best fishing rods 2026", "format": "listicle"},
  {"keyword": "how to choose fishing rod", "format": "how-to-guide", "word_count": 4500}
]

Workflow (Claude executes this)

Phase 1: Enqueue

python -m scripts._core.batch_queue enqueue \
    --project {project_slug} \
    --file {keywords_file}

This creates workspace/batches/{batch_id}/index.json with all entries pending. Output shows: batch_id + entry count + total estimated cost.

Contract notes (v3.41.0):

• Generated task_ids are underscore-form (art_YYYYmmddHHMMSS_NNN_hex) — they MUST satisfy schemas/state.schema.json :: task_id ^[a-z0-9_]{8,32}$, because assemble.py validates the full state against it mid-pipeline. The pre-v3.41.0 hyphenated ids passed the early stages then hard-failed at assembly (2026-07-17 project-lima batch). Pinned by tests/test_batch_queue_taskid_schema.py.
• daily_cost_cap_usd in the index comes from ~/.xuanran-seo/config.yaml :: cost_limits.daily_total_usd — never a hardcode. A stale index with an empty cap is backfilled from config on load.
• Task workspaces live under memory/workspace/{task_id}/ (the runner's WS_ROOT); the workspace/ root holds only batches/.
• FORMAT IDS (v3.41.4): the per-row format column validates against schemas/angle.schema.json :: format_id enum — the single source of truth, mirrored 1:1 by templates/*.md basenames. An unknown format still soft-falls back to the default, but now WARNS on stderr; pre-v3.41.4 the check ran against a stale hand-maintained 10-item literal, so a REAL format like buyers-guide was silently rewritten to listicle and the whole article was planned in the wrong format with no error anywhere (2026-07-24 project-india batch). Pinned by tests/test_batch_queue_format_enum_seam.py. Watch the enqueue output's format column — it must echo the format you asked for.