ats: enforce Goal+Log task body format + fold triage into single-task get

normalizeTaskBody (core) lifts a buried goal to a ::wrapped:: # Goal at the top, gathers next-action + dated bullets under # Log, preserves other prose under ## Notes. Idempotent, non-destructive, no LLM. Wired into create/update (when content is written) and single-task 'tasks get', which also runs Haiku triage tagging in the same read and persists both. Adds 'ats tasks normalize' (structure-only backfill) and 'ats fmt' (stdin filter).

Cost-capped like the triage cron: per-call --max-budget-usd 0.05 (inherited via beads-triage classify) plus a rolling daily cap ATS_GET_TRIAGE_MAX_PER_DAY (default 25) that degrades to free structure-only normalize past the cap. find/list/search/hybrid/similar never auto-touch pulled-in tasks.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: renezander030

packages/cli/bin/ats.js

@@ -68,6 +68,8 @@ import {
   acknowledgeTaskEvents,
   snapshotTaskEvents,
   collectAndSpoolTaskEvents,
+  normalizeTaskBody,
+  TRIAGE_TAG,
 } from '@reneza/ats-core';
 import { scaffoldAdapter } from '../scaffold.js';
 import { runDoctor, formatDoctor } from '../doctor.js';
@@ -205,6 +207,9 @@ async function main() {
       case 'bench':
         handleBench();
         return;
+      case 'fmt':
+        handleFmt();
+        return;
       case 'sync':
         result = await handleSync();
         break;
@@ -365,7 +370,7 @@ function helpFor(command) {
 const COMPLETION_COMMANDS = [
   'setup', 'find', 'open', 'get', 'url', 'links', 'create', 'update', 'hybrid', 'similar',
   'intent', 'promote', 'hierarchy', 'lifecycle', 'link', 'reference', 'relate', 'graph', 'context', 'ledger', 'security', 'events',
-  'doctor', 'status', 'cache', 'bench', 'sync', 'adapter', 'init', 'config', 'auth',
+  'doctor', 'status', 'cache', 'bench', 'fmt', 'sync', 'adapter', 'init', 'config', 'auth',
   'projects', 'tasks', 'notes', 'help', 'completion',
 ];
 
@@ -647,6 +652,96 @@ function auditCliWrite(action, result, fallback, metadata, advanced = false) {
   }
 }
 
+// Cheap-model triage classifier (route/type/model/effort/do tags). Shells the
+// shared beads-triage.py in --emit-json mode so the LLM prompt has ONE source of
+// truth. Returns {tags:[], next:''} or null on any failure (caller degrades to
+// structure-only). No write happens here — the caller persists once.
+// Default location is Rene's checkout; override with ATS_TRIAGE_BIN. runTriageEmit's
+// existsSync guard means triage is simply skipped where the script isn't present.
+const TRIAGE_BIN = process.env.ATS_TRIAGE_BIN || path.join(os.homedir(), 'claude', 'beads-triage.py');
+
+// Cost caps mirror beads-triage.py: (1) PER-CALL — the shared classify() already
+// passes `--max-budget-usd 0.05`, inherited here automatically. (2) VOLUME — the cron
+// caps tasks/run (TRIAGE_MAX_PER_RUN) to protect the shared 5h budget from bursts;
+// get processes one task per call, so the analog is a rolling DAILY cap on get-triage
+// Haiku calls. Past the cap, get degrades to structure-only normalize (no loss — the
+// task still conforms and gets tagged on a later get or by the batch cron). 0 disables.
+const GET_TRIAGE_MAX_PER_DAY = parseInt(process.env.ATS_GET_TRIAGE_MAX_PER_DAY || '25', 10);
+function getTriageBudgetFile() {
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'ats', 'get-triage-budget.json');
+}
+function claimGetTriageBudget() {
+  if (!(GET_TRIAGE_MAX_PER_DAY > 0)) return false;
+  const day = new Date().toISOString().slice(0, 10);
+  const file = getTriageBudgetFile();
+  let st;
+  try { st = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { st = {}; }
+  if (st.day !== day) st = { day, count: 0 };
+  if (st.count >= GET_TRIAGE_MAX_PER_DAY) return false;
+  st.count += 1;
+  try { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, JSON.stringify(st)); } catch { /* best-effort */ }
+  return true;
+}
+
+function runTriageEmit(task) {
+  try {
+    if (!fs.existsSync(TRIAGE_BIN)) return null;
+    const env = { ...process.env };
+    delete env.CLAUDECODE; delete env.CLAUDE_CODE_ENTRYPOINT;
+    const r = spawnSync('python3', [TRIAGE_BIN, '--emit-json'], {
+      input: JSON.stringify([task]), encoding: 'utf8', timeout: 60000, env,
+    });
+    if (r.status !== 0 || !r.stdout) return null;
+    const line = r.stdout.trim().split('\n').filter(Boolean).pop();
+    const d = JSON.parse(line);
+    return { tags: d.tags || [], next: (d.next || '').trim() };
+  } catch { return null; }
+}
+
+// Single explicit `ats tasks get PROJECT_ID TASK_ID` = "the task at hand" → read
+// the context once, normalize the Goal+Log body, classify triage tags, and persist
+// BOTH in one write. Skips the LLM call when the task is already triaged AND its
+// body is already conforming (freshness guard). Never fires for find/list/search.
+async function formatTriageOnGet(t, adapter, proj, id, task) {
+  const fullProj = task.fullProjectId || task.projectId || proj;
+  const fullId = task.fullId || task.id || id;
+  const curTags = task.tags || [];
+  const norm = normalizeTaskBody(task.content || '');
+  const hasTriage = curTags.some((x) => TRIAGE_TAG.test(x));
+  const skip = args.options['no-triage'] === true || process.env.ATS_GET_NOTRIAGE;
+
+  let newTags = null;
+  let next = '';
+  if (!skip && (!hasTriage || norm.changed)) {
+    if (claimGetTriageBudget()) {
+      const r = runTriageEmit({ id: fullId, projectId: fullProj, title: task.title, content: norm.content });
+      if (r) { newTags = r.tags; next = r.next; }
+    } else {
+      process.stderr.write(`[ats] get-triage daily cap (${GET_TRIAGE_MAX_PER_DAY}) reached — structure-only this read; triage deferred to the batch cron.\n`);
+    }
+  }
+  const finalBody = next ? normalizeTaskBody(norm.content, { next }).content : norm.content;
+  const bodyChanged = finalBody.trim() !== (task.content || '').trim();
+  if (!bodyChanged && !newTags) return task; // already conforming + tagged → no write
+
+  const patch = { content: finalBody };
+  if (newTags) patch.tags = [...curTags.filter((x) => !TRIAGE_TAG.test(x)), ...newTags];
+  const res = t?.update
+    ? await t.update(proj, id, patch)
+    : await adapter.updateTask(proj, id, { ...patch, tags: tagsToArray(patch.tags) });
+  auditCliWrite('task.updated', res, { projectId: proj, taskId: id }, { fields: Object.keys(patch), via: 'get-format' });
+  return res.task || res;
+}
+
+// `ats fmt [--next "..."]` — pure stdin→stdout Goal+Log normalizer (no adapter,
+// no network). Lets other tools (e.g. beads-triage.py) reuse the one normalizer.
+function handleFmt() {
+  let body;
+  try { body = fs.readFileSync(0, 'utf8'); } catch { body = ''; }
+  const { content } = normalizeTaskBody(body, { next: args.options.next || '' });
+  process.stdout.write(content);
+}
+
 async function handleTasks() {
   const adapter = await loadAdapter();
   const t = adapter.__ext?.tasks; // optional: rich adapters (TickTick) provide it
@@ -655,9 +750,26 @@ async function handleTasks() {
     case 'list':
       if (!args.positional[0]) { console.error('Usage: ats tasks list PROJECT_ID'); process.exit(1); }
       return t?.list ? await t.list(args.positional[0]) : await adapter.listTasksInProject(args.positional[0]);
-    case 'get':
+    case 'get': {
       if (!args.positional[0] || !args.positional[1]) { console.error('Usage: ats tasks get PROJECT_ID TASK_ID'); process.exit(1); }
-      return t?.get ? await t.get(args.positional[0], args.positional[1]) : await adapter.getTask(args.positional[0], args.positional[1]);
+      const [gp, gid] = args.positional;
+      const got = t?.get ? await t.get(gp, gid) : await adapter.getTask(gp, gid);
+      if (args.options['no-format'] === true || process.env.ATS_GET_NOFORMAT) return got;
+      return await formatTriageOnGet(t, adapter, gp, gid, got);
+    }
+    case 'normalize': {
+      // Structure-only backfill (no triage/LLM): lift Goal, ensure Log, preserve Notes.
+      if (!args.positional[0] || !args.positional[1]) { console.error('Usage: ats tasks normalize PROJECT_ID TASK_ID'); process.exit(1); }
+      const [np, nid] = args.positional;
+      const task = t?.get ? await t.get(np, nid) : await adapter.getTask(np, nid);
+      const norm = normalizeTaskBody(task.content || '');
+      if (!norm.changed) return { task: { projectId: np, taskId: nid }, changed: false };
+      const res = t?.update
+        ? await t.update(np, nid, { content: norm.content })
+        : await adapter.updateTask(np, nid, { content: norm.content });
+      auditCliWrite('task.updated', res, { projectId: np, taskId: nid }, { fields: ['content'], via: 'normalize' });
+      return res.task || res;
+    }
     case 'create': {
       let projectId = args.options.project || '';
       let title = args.positional[0];
@@ -686,6 +798,9 @@ async function handleTasks() {
         console.error('Run without arguments for interactive mode.');
         process.exit(1);
       }
+      // Conform any body that's written (deterministic, no LLM). Bare quick-captures
+      // (no --content) stay clean; they get the Goal+Log skeleton on first `get`.
+      if (opts.content) opts.content = normalizeTaskBody(opts.content).content;
       const result = t?.create
         ? await t.create(projectId, title, opts)
         : await adapter.createTask({
@@ -726,6 +841,8 @@ async function handleTasks() {
         tags: args.options.tags,
         reminder: args.options.reminder,
       };
+      // Normalize the body whenever content is being written (no extra fetch when it isn't).
+      if (patch.content !== undefined) patch.content = normalizeTaskBody(patch.content).content;
       const result = t?.update
         ? await t.update(args.positional[0], args.positional[1], patch)
         : await adapter.updateTask(args.positional[0], args.positional[1], { ...patch, tags: tagsToArray(patch.tags) });

packages/core/index.js

@@ -60,3 +60,4 @@ export {
   scoreProgressEpisodes,
   formatProgressBenchmark,
 } from './progress-benchmark.js';
+export { normalizeTaskBody, TRIAGE_TAG } from './task-format.js';

packages/core/task-format.js

@@ -0,0 +1,115 @@
+/**
+ * task-format.js — deterministic Goal+Log body normalizer.
+ *
+ * Guarantees a task body STARTS with a `# Goal` section (goal wrapped in
+ * `::double-colons::`), immediately followed by a `# Log` section (next-action
+ * bullets first, then dated `- YYYY-MM-DD:` history). Any other prose is
+ * preserved under `## Notes`. No LLM, no reasoning — purely structural, so the
+ * format exists for high readability. Idempotent: re-running is a no-op.
+ *
+ * A buried goal (an existing `# Goal`/`## Goal` section anywhere, a `::…::`
+ * highlight, or a `goal:`/`ziel:` line) is lifted back to the top.
+ */
+
+const HEADING = /^(#{1,6})\s+(.+?)\s*$/;
+const HIGHLIGHT = /^\s*::(.+?)::\s*$/;
+const GOAL_LINE = /^\s*(goal|ziel)\s*:\s*(.+?)\s*$/i;
+const DATED = /^\s*[-*]\s*(\*\*)?\d{4}-\d{2}-\d{2}/;
+const ACTION = /^\s*[-*]\s*(\*\*)?\s*(next|todo|next best action|tbd)\b/i;
+const BULLET = /^\s*[-*]\s+/;
+
+// Triage tag namespaces — used by callers to decide whether a task is already classified.
+export const TRIAGE_TAG = /^(route|type|model|effort|do|tool|review)[:-]/;
+
+function promoteHeadings(content) {
+  // migrate any-level "## Goal"/"## Log" (old triage H2 form) to canonical H1
+  return content.replace(/^#{1,6}\s+(Goal|Ziel|Log)\b.*$/gim, (_m, w) =>
+    '# ' + (/log/i.test(w) ? 'Log' : 'Goal'));
+}
+
+function splitSections(content) {
+  // Break on ANY markdown heading so an H2 (e.g. "## Notes") starts its own
+  // section instead of being swallowed by the preceding H1. `raw` keeps the
+  // original heading line (with its level) so non-Goal/Log sections round-trip.
+  const out = [];
+  let cur = { heading: null, raw: null, lines: [] };
+  for (const ln of content.split('\n')) {
+    const m = ln.match(HEADING);
+    if (m) { out.push(cur); cur = { heading: m[2], raw: ln.trimEnd(), lines: [] }; }
+    else cur.lines.push(ln);
+  }
+  out.push(cur);
+  return out.filter((s, i) => i === 0 || s.heading !== null || s.lines.join('').trim());
+}
+
+function firstMeaningful(lines) {
+  for (const l of lines) { const t = l.trim(); if (t) return t; }
+  return '';
+}
+
+/**
+ * @param {string} content - existing task body (markdown)
+ * @param {{next?: string}} [opts] - next-step to fold in as the first Log action bullet
+ * @returns {{content: string, changed: boolean, goal: string|null}}
+ */
+export function normalizeTaskBody(content = '', opts = {}) {
+  const original = content || '';
+  const secs = splitSections(promoteHeadings(original));
+
+  let goal = null;
+  const logLines = [];
+  const preamble = [];       // heading-less leftover prose
+  const blocks = [];         // other headed sections, preserved with their level
+
+  for (const s of secs) {
+    const h = (s.heading || '').toLowerCase();
+    if (h === 'goal') {
+      if (goal == null) goal = firstMeaningful(s.lines).replace(HIGHLIGHT, '$1').replace(/^::|::$/g, '').trim();
+      continue;
+    }
+    if (h === 'log') {
+      for (const l of s.lines) if (l.trim()) logLines.push(l.replace(/\s+$/, ''));
+      continue;
+    }
+    const kept = [];
+    for (const l of s.lines) {
+      if (goal == null && HIGHLIGHT.test(l)) { goal = l.match(HIGHLIGHT)[1].trim(); continue; }
+      if (goal == null && GOAL_LINE.test(l)) { goal = l.match(GOAL_LINE)[2].trim(); continue; }
+      if (DATED.test(l) || ACTION.test(l)) { logLines.push(l.replace(/\s+$/, '')); continue; }
+      kept.push(l.replace(/\s+$/, ''));
+    }
+    if (s.raw) blocks.push({ heading: h, raw: s.raw, lines: kept });
+    else for (const l of kept) preamble.push(l);
+  }
+
+  // fold an explicit next-step in as the first action bullet (skip if already present)
+  const next = (opts.next || '').trim();
+  if (next) {
+    const already = logLines.some((l) => l.replace(/[*_`]/g, '').toLowerCase().includes(next.toLowerCase()));
+    if (!already) logLines.unshift(`- next: ${next}`);
+  }
+
+  const actions = logLines.filter((l) => ACTION.test(l));
+  const dated = logLines.filter((l) => DATED.test(l));
+  const otherLog = logLines.filter((l) => !ACTION.test(l) && !DATED.test(l) && BULLET.test(l));
+  let log = [...actions, ...dated, ...otherLog];
+  if (!log.length) log = ['- ', '- ', '- '];
+
+  // Leftover preamble prose folds under "## Notes" — into an existing Notes block
+  // if there is one (so re-runs don't stack headers), else a fresh one at the front.
+  const preText = preamble.join('\n').trim();
+  if (preText) {
+    const notes = blocks.find((b) => b.heading === 'notes');
+    if (notes) notes.lines = [...preText.split('\n'), '', ...notes.lines];
+    else blocks.unshift({ heading: 'notes', raw: '## Notes', lines: preText.split('\n') });
+  }
+
+  const parts = ['# Goal', goal ? `::${goal}::` : '::TODO — set goal::', '', '# Log', log.join('\n')];
+  for (const b of blocks) {
+    const body = b.lines.join('\n').trim();
+    parts.push('', b.raw);
+    if (body) parts.push(body);
+  }
+  const result = parts.join('\n').replace(/\n{3,}/g, '\n\n').trim() + '\n';
+  return { content: result, changed: result.trim() !== original.trim(), goal: goal || null };
+}

packages/core/test/task-format.test.js

@@ -0,0 +1,82 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { normalizeTaskBody } from '../task-format.js';
+
+test('lifts a buried goal: line to a wrapped # Goal at the top', () => {
+  const input = 'preamble\n\ngoal: ship the normalizer\n\n- 2026-06-20: drafted spec\n- next: write core';
+  const { content, goal, changed } = normalizeTaskBody(input);
+  assert.equal(goal, 'ship the normalizer');
+  assert.ok(changed);
+  assert.ok(content.startsWith('# Goal\n::ship the normalizer::'));
+  assert.ok(content.includes('# Log'));
+  // action bullet before dated bullet
+  assert.ok(content.indexOf('- next: write core') < content.indexOf('- 2026-06-20'));
+  // prose preserved
+  assert.ok(content.includes('## Notes'));
+  assert.ok(content.includes('preamble'));
+});
+
+test('lifts a ::highlight:: as the goal', () => {
+  const { goal } = normalizeTaskBody('notes\n::do the thing::\nmore');
+  assert.equal(goal, 'do the thing');
+});
+
+test('migrates old H2 ## Log / **Next** form to canonical H1', () => {
+  const input = '## Log\n- **Next:** write core\n\n---\n\nbody text';
+  const { content } = normalizeTaskBody(input);
+  assert.ok(content.startsWith('# Goal'));
+  assert.ok(/^# Log$/m.test(content));
+  assert.ok(content.includes('write core'));
+});
+
+test('no goal anywhere → TODO placeholder + empty action scaffold', () => {
+  const { content, goal } = normalizeTaskBody('just a thought');
+  assert.equal(goal, null);
+  assert.ok(content.includes('::TODO — set goal::'));
+  assert.ok(content.includes('# Log'));
+});
+
+test('idempotent: re-running a conforming body is a no-op', () => {
+  const once = normalizeTaskBody('goal: x\n- next: y\n- 2026-06-20: z').content;
+  const twice = normalizeTaskBody(once);
+  assert.equal(twice.content, once);
+  assert.equal(twice.changed, false);
+});
+
+test('folds an explicit next-step in as the first action bullet', () => {
+  const { content } = normalizeTaskBody('goal: x\n- 2026-06-20: z', { next: 'do the next thing' });
+  assert.ok(content.includes('- next: do the next thing'));
+  assert.ok(content.indexOf('- next: do the next thing') < content.indexOf('- 2026-06-20'));
+});
+
+test('does not duplicate a next-step already present', () => {
+  const body = 'goal: x\n- next: already here';
+  const { content } = normalizeTaskBody(body, { next: 'already here' });
+  assert.equal((content.match(/already here/g) || []).length, 1);
+});
+
+test('idempotent on its OWN output when a ## Notes section exists', () => {
+  const input = 'goal: ship\n\nprose to keep\n\n- 2026-06-20: did x\n\nmore prose';
+  const once = normalizeTaskBody(input);
+  assert.ok(once.content.includes('## Notes'));
+  assert.ok(once.content.includes('prose to keep'));
+  assert.ok(once.content.includes('more prose'));
+  const twice = normalizeTaskBody(once.content);
+  assert.equal(twice.content, once.content);     // no drift
+  assert.equal(twice.changed, false);
+  // exactly one Notes header — no stacking on re-run
+  assert.equal((twice.content.match(/^## Notes$/gm) || []).length, 1);
+});
+
+test('preserves a user H2 section that is not Notes', () => {
+  const { content } = normalizeTaskBody('goal: x\n\n## Refs\n- http://e.com');
+  assert.ok(content.includes('## Refs'));
+  assert.ok(content.includes('http://e.com'));
+  assert.equal(normalizeTaskBody(content).content, content); // idempotent
+});
+
+test('empty input yields the full scaffold', () => {
+  const { content } = normalizeTaskBody('');
+  assert.ok(content.startsWith('# Goal'));
+  assert.ok(content.includes('# Log'));
+});