@michaelxwb/code-flow 0.8.1 → 1.0.0

package/lib/task.js

@@ -0,0 +1,258 @@
+'use strict';
+const path = require('node:path');
+const fs = require('node:fs');
+const f = require('./fs');
+const config = require('./config');
+const session = require('./session');
+const taskdoc = require('./taskdoc');
+const repo = require('./repo');
+
+const STATES = taskdoc.STATES;
+
+function loadDocument(root, relative, writable = false) {
+  f.string(relative, 'task path');
+  const normalized = relative.replace(/\\/g, '/').replace(/^\.\//, '');
+  f.demand(/^\.code-flow\/tasks\/(?:archived\/)?\d{4}-\d{2}-\d{2}\/[^/]+\/[^/]+\.md$/.test(normalized),
+    'task_path', 'Expected complete task document path: ' + relative, 2);
+  f.demand(!normalized.includes('/./'), 'task_path', 'Task path must be canonical', 2);
+  f.demand(!/\.(prd|design|scenarios)\.md$/.test(normalized), 'task_path', 'Expected task document, not PRD/design/scenarios', 2);
+  f.demand(!writable || !normalized.startsWith('.code-flow/tasks/archived/'),
+    'task_archived', 'Cannot mutate an archived task document', 2);
+  const file = f.inside(root, normalized);
+  const raw = f.readText(file, 1024 * 1024);
+  f.demand(raw !== null, 'task_missing', 'Missing task document: ' + relative, 2);
+  const document = taskdoc.parse(raw, file);
+  return { ...document, file, relative: normalized, raw };
+}
+
+function resolveTask(document, taskId) {
+  if (taskId) return taskdoc.find(document, taskId);
+  f.demand(document.tasks.length === 1, 'task_id_required',
+    'Task document has multiple TASK sections; pass --task TASK-NNN', 2);
+  return document.tasks[0];
+}
+
+function loadTask(root, relative, taskId = '', writable = false) {
+  const document = loadDocument(root, relative, writable);
+  const task = resolveTask(document, taskId);
+  return taskdoc.taskFrom(document, task);
+}
+
+function load(root, relative, taskId = '') {
+  return loadTask(root, relative, taskId);
+}
+
+function writeDocument(document) {
+  f.atomicWrite(document.file, taskdoc.write(document), document.raw);
+}
+
+async function withDocumentLock(root, relative, operation) {
+  for (let attempt = 0; attempt < 200; attempt++) {
+    try { return await f.withLock(root, 'doc:' + relative, operation); } catch (error) {
+      if (error.code !== 'locked') throw error;
+      await new Promise(resolve => setTimeout(resolve, 10));
+    }
+  }
+  throw new f.FlowError('locked', 'Document write lock timed out: ' + relative, 1);
+}
+
+function withTaskLock(root, relative, taskId, operation) {
+  return f.withLock(root, 'task:' + relative + '#' + taskId, () =>
+    withDocumentLock(root, relative, operation));
+}
+
+async function start(root, relative, taskId, value) {
+  config.load(root);
+  if (value) session.location(root, value);
+  const initial = loadTask(root, relative, taskId, true);
+  return withTaskLock(root, initial.relative, initial.id, async () => {
+    const task = loadTask(root, initial.relative, initial.id, true);
+    f.demand(task.status !== 'done', 'task_state', 'Use task reopen for a done task', 1);
+    let document = task.document;
+    if (task.status !== 'in-progress') {
+      document = taskdoc.updateTask(document, task.id,
+        { status: 'in-progress', log: 'started tests=' + taskdoc.testsDigest(task) });
+      writeDocument({ ...document, raw: document.raw });
+    }
+    const updated = loadTask(root, initial.relative, initial.id);
+    const result = require('./render').inject(root, { taskFile: updated.relative, taskId: updated.id, session: value });
+    const diagnostics = result.diagnostics;
+    if (value) {
+      try { await session.bind(root, value, updated.relative, updated.id); } catch (error) {
+        diagnostics.push({ code: 'binding_failed', message: 'Task started; binding failed: ' + error.message });
+      }
+    }
+    return { ok: true, action: 'start', task: updated.relative + '#' + updated.id, ...result, diagnostics };
+  });
+}
+
+async function transition(root, relative, taskId, action, reason) {
+  config.load(root); f.string(reason, 'reason');
+  const initial = loadTask(root, relative, taskId, true);
+  return withTaskLock(root, initial.relative, initial.id, async () => {
+    const task = loadTask(root, initial.relative, initial.id, true);
+    const from = action === 'block' ? 'in-progress' : 'done';
+    f.demand(task.status === from, 'task_state', action + ' requires status ' + from, 1);
+    const document = taskdoc.updateTask(task.document, task.id, {
+      status: action === 'block' ? 'blocked' : 'in-progress', log: action + ': ' + reason
+    });
+    writeDocument(document);
+    return { ok: true, action, task: task.relative + '#' + task.id };
+  });
+}
+
+function isTaskDocument(relative) {
+  const match = /^\.code-flow\/tasks\/(?:archived\/)?\d{4}-\d{2}-\d{2}\/([^/]+)\/([^/]+)\.md$/.exec(relative);
+  return Boolean(match) && match[1] === match[2];
+}
+
+function list(root, directory = '.code-flow/tasks') {
+  const base = f.inside(root, directory);
+  f.demand(fs.existsSync(base), 'task_missing', 'Task directory missing: ' + directory, 1);
+  const relative = path.relative(root, base).split(path.sep).join('/');
+  f.demand(relative === '.code-flow/tasks' || relative.startsWith('.code-flow/tasks/'),
+    'task_path', 'Expected task directory', 2);
+  const names = require('./spec').walk(base).filter(name => name.endsWith('.md'));
+  const items = [], diagnostics = [];
+  let ignored = 0;
+  for (const name of names.filter(name => !name.startsWith('archived/'))) {
+    const taskPath = relative + '/' + name;
+    if (!isTaskDocument(taskPath)) {
+      if (!/\.(prd|design|scenarios)\.md$/.test(name)) ignored++;
+      continue;
+    }
+    try {
+      const document = loadDocument(root, taskPath);
+      for (const task of document.tasks) {
+        const verification = task.text.match(/^- \d{4}-[^\r\n]*(?:PASS|FAIL|SKIPPED)[^\r\n]*/gm) || [];
+        const summary = verification.at(-1) ?? null;
+        const head = summary ? /\bhead=([a-f0-9]{7,40}|none)\b/.exec(summary)?.[1] ?? null : null;
+        items.push({ task: taskPath + '#' + task.id, task_file: taskPath, task_id: task.id,
+          status: task.status, depends: task.depends, tests: task.tests.length,
+          spec_refs: task.specRefs, scenarios: task.scenarios, verification: summary,
+          verified_head: head === 'none' ? null : head,
+          tests_changed: Boolean(summary && /\btests-changed\b/.test(summary)) });
+      }
+    } catch (error) { diagnostics.push({ source: taskPath, code: error.code, message: error.message }); }
+  }
+  return { ok: diagnostics.length === 0, items, diagnostics, ignored };
+}
+
+async function verify(root, relative, taskId, options = {}) {
+  const settings = config.load(root), task = loadTask(root, relative, taskId);
+  const tests = task.tests;
+  if (tests.length === 0) {
+    f.demand(task.skipTests, 'tests_missing', 'Declare tests or skip_tests with skip_reason', 1);
+    return { ok: true, action: 'verify', skipped: task.skipReason, results: [], executed: 0, deduped: 0 };
+  }
+  const env = options.env ?? require('./runs').workerEnv(root);
+  return { action: 'verify', ...await require('./verify').run(root, tests, settings.tests, { ...options, env }) };
+}
+
+function verificationLines(result, meta = {}) {
+  const label = result.skipped ? 'SKIPPED' : result.ok ? 'PASS' : 'FAIL';
+  const summary = '- ' + new Date().toISOString() + ' ' + label + ' commands=' +
+    result.results.filter(item => item.status === 'pass').length + '/' + result.results.length +
+    ' executed=' + result.executed + ' deduped=' + result.deduped +
+    (result.elapsed_ms === undefined ? '' : ' elapsed=' + Math.round(result.elapsed_ms) + 'ms') +
+    ' tests=' + (meta.tests ?? 'unknown') +
+    ' head=' + (meta.head ? String(meta.head).slice(0, 12) : 'none') +
+    ' dirty=' + (meta.dirty === null || meta.dirty === undefined ? 'unknown' : meta.dirty ? '1' : '0') +
+    (meta.testsChanged ? ' tests-changed' : '') +
+    (result.skipped ? ' reason=' + result.skipped : '');
+  return [summary, ...result.results.map(item => '  - ' + item.id + ' ' + item.status.toUpperCase() +
+    (item.exit_code === undefined ? '' : ' exit=' + item.exit_code))];
+}
+
+async function finish(root, relative, taskId, options = {}) {
+  const initial = loadTask(root, relative, taskId, true);
+  return f.withLock(root, 'task:' + initial.relative + '#' + initial.id, async () => {
+    const task = loadTask(root, initial.relative, initial.id, true);
+    f.demand(task.status === 'in-progress', 'task_state', 'finish requires in-progress', 1);
+    const declared = taskdoc.testsDigest(task), started = taskdoc.startedTests(task.text);
+    const gitState = repo.state(root);
+    const result = await verify(root, task.relative, task.id, options), diagnostics = [];
+    try { require('./learn').deltas(task); } catch (error) {
+      diagnostics.push({ code: error.code, message: error.message });
+    }
+    return withDocumentLock(root, task.relative, async () => {
+      const current = loadTask(root, task.relative, task.id, true);
+      f.demand(current.text === task.text, 'concurrent_change',
+        'Concurrent change: Task section changed during finish', 1);
+      const document = taskdoc.updateTask(current.document, task.id, {
+        status: result.ok ? 'done' : 'in-progress',
+        verification: verificationLines(result, { tests: declared,
+          testsChanged: started !== null && started !== declared,
+          head: gitState.head, dirty: gitState.dirty })
+      });
+      writeDocument(document);
+      return { ...result, action: 'finish', task: task.relative + '#' + task.id, diagnostics };
+    });
+  });
+}
+
+function requirement(root, relative) {
+  const normalized = relative.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/$/, '');
+  f.demand(/^\.code-flow\/tasks\/\d{4}-\d{2}-\d{2}\/[^/]+$/.test(normalized),
+    'requirement_path', 'Expected unarchived requirement directory', 2);
+  const directory = f.inside(root, normalized);
+  const name = path.basename(normalized) + '.md';
+  const taskPath = normalized + '/' + name;
+  f.demand(fs.existsSync(path.join(root, taskPath)), 'tasks_missing', 'Requirement task document missing: ' + taskPath, 1);
+  const document = loadDocument(root, taskPath, true);
+  f.demand(document.tasks.length > 0, 'tasks_missing', 'Requirement has no TASK sections', 1);
+  const tasks = document.tasks.map(task => taskdoc.taskFrom(document, task));
+  f.demand(tasks.every(task => task.status === 'done'), 'tasks_unfinished', 'All tasks must be done', 1);
+  const target = f.inside(root, '.code-flow/tasks/archived/' + normalized.slice('.code-flow/tasks/'.length));
+  f.demand(!fs.existsSync(target), 'archive_conflict', 'Archive target exists: ' + target, 1);
+  return { directory, target, document, tasks, normalized, name };
+}
+
+function removeEmptyDirectory(directory) {
+  try { fs.rmdirSync(directory); } catch (error) {
+    if (error.code !== 'ENOTEMPTY' && error.code !== 'ENOENT') throw error;
+  }
+}
+
+async function archive(root, relative, options = {}) {
+  config.load(root);
+  require('./repo').requireCoordinator(root, 'task archive');
+  require('./runs').assertArchiveAllowed(root, relative);
+  const initial = requirement(root, relative), learn = require('./learn');
+  if (options.dryRun) return {
+    ...(options.noLearn ? { ok: true, dry_run: true, results: [] } : learn.preview(learn.plan(root, initial.tasks))),
+    action: 'archive', archived_to: initial.target };
+  return require('./locks').withRepository(root, () => f.withLock(root, 'write', async () => {
+    require('./repo').requireCoordinator(root, 'task archive');
+    require('./runs').assertArchiveAllowed(root, relative);
+    const current = requirement(root, relative);
+    let learned = { results: [], learning_skipped: Boolean(options.noLearn) };
+    if (!options.noLearn) learned = learn.commit(learn.plan(root, current.tasks));
+    f.demand(f.readText(current.document.file) === current.document.raw,
+      'concurrent_change', 'Task document changed during archive', 1);
+    f.demand(!fs.existsSync(current.target), 'archive_conflict', 'Archive target appeared', 1);
+    fs.mkdirSync(path.dirname(current.target), { recursive: true });
+    fs.renameSync(current.directory, current.target);
+    removeEmptyDirectory(path.dirname(current.directory));
+    return { ...learned, ok: true, action: 'archive', archived_to: current.target };
+  }));
+}
+
+async function learn(root, relative, taskId, dryRun = false) {
+  config.load(root);
+  require('./repo').requireCoordinator(root, 'spec learn');
+  require('./runs').assertLearnAllowed(root);
+  const task = loadTask(root, relative, taskId, true);
+  if (dryRun) return require('./learn').apply(root, [task], true);
+  return require('./locks').withRepository(root, () => {
+    require('./repo').requireCoordinator(root, 'spec learn');
+    require('./runs').assertLearnAllowed(root);
+    return f.withLock(root, 'task:' + task.relative + '#' + task.id,
+      () => require('./learn').apply(root, [loadTask(root, task.relative, task.id, true)]));
+  });
+}
+
+module.exports = {
+  STATES, archive, finish, learn, list, load, loadDocument, loadTask,
+  requirement, start, transition, validateTests: taskdoc.validateTests, verify
+};

package/lib/taskdoc.js

@@ -0,0 +1,308 @@
+'use strict';
+const path = require('node:path');
+const f = require('./fs');
+const fm = require('./frontmatter');
+const config = require('./config');
+const glob = require('./glob');
+const markdown = require('./markdown');
+
+const STATES = ['draft', 'in-progress', 'done', 'blocked'];
+const RESERVED_ENV = new Set(['CF_WORKTREE_ID', 'CF_TASK_ID', 'CF_TASK_IDS', 'CF_RUN_ID',
+  'CF_PORT_OFFSET', 'CF_DB_SUFFIX']);
+const FIELDS = {
+  Status: 'status', Depends: 'depends', Source: 'source', Scenarios: 'scenarios',
+  'Spec-Refs': 'specRefs', Paths: 'paths', E2E: 'e2e',
+  'Skip-Tests': 'skipTests', 'Skip-Reason': 'skipReason'
+};
+
+function heading(line) {
+  const match = /^##[ \t]+(TASK-\d+):[ \t]*(.*)$/.exec(line.replace(/\r$/, ''));
+  return match ? { id: match[1], title: match[2].trim() } : null;
+}
+
+function splitSections(body) {
+  const lines = body.split('\n');
+  const headings = [];
+  let fence = null, offset = 0;
+  for (const line of lines) {
+    const marker = markdown.fenceMarker(line, fence);
+    if (marker) {
+      fence = marker.next;
+    } else if (!fence && /^##[ \t]/.test(line)) {
+      const parsed = heading(line);
+      if (parsed) headings.push({ ...parsed, start: offset });
+    }
+    offset += line.length + 1;
+  }
+  if (!headings.length) throw new f.FlowError('tasks_missing', 'Task document has no TASK sections', 2);
+  const preamble = body.slice(0, headings[0].start);
+  const sections = headings.map((item, index) => ({
+    ...item,
+    text: body.slice(item.start, index + 1 < headings.length ? headings[index + 1].start : body.length)
+  }));
+  return { preamble, sections };
+}
+
+function fieldEntries(text) {
+  const values = new Map();
+  let fence = null, offset = 0;
+  for (const line of text.split('\n')) {
+    const start = offset;
+    offset += line.length + 1;
+    const marker = markdown.fenceMarker(line, fence);
+    if (marker) {
+      fence = marker.next;
+      continue;
+    }
+    if (fence) continue;
+    const match = /^- \*\*([^*]+)\*\*:[ \t]*(.*)$/.exec(line.replace(/\r$/, ''));
+    if (match && Object.hasOwn(FIELDS, match[1])) {
+      const name = FIELDS[match[1]];
+      f.demand(!values.has(name), 'task_field_duplicate', 'Duplicate Task field: ' + match[1]);
+      values.set(name, { value: match[2].trim(), start, end: start + line.length });
+    }
+  }
+  return values;
+}
+
+function fieldMap(text) {
+  return Object.fromEntries([...fieldEntries(text)].map(([name, item]) => [name, item.value]));
+}
+
+function subsectionRange(text, name) {
+  let area = null, fence = null, offset = 0;
+  for (const line of text.split('\n')) {
+    const start = offset;
+    offset += line.length + 1;
+    const marker = markdown.fenceMarker(line, fence);
+    if (marker) {
+      fence = marker.next;
+      continue;
+    }
+    if (fence) continue;
+    if (area && /^###[ \t]/.test(line)) return { ...area, end: start };
+    if (line.replace(/\r$/, '') === '### ' + name) {
+      area = { start, contentStart: Math.min(offset, text.length) };
+    }
+  }
+  return area ? { ...area, end: text.length } : null;
+}
+
+function subsection(text, name) {
+  const area = subsectionRange(text, name);
+  return area ? text.slice(area.contentStart, area.end) : null;
+}
+
+function jsonArray(text, name) {
+  if (text === null) return [];
+  const match = /```(?:json)?[ \t]*\r?\n([\s\S]*?)\r?\n```/.exec(text);
+  if (!match) throw new f.FlowError('task_json_missing', 'Missing JSON block in ### ' + name, 2);
+  let value;
+  try { value = JSON.parse(match[1]); } catch (error) {
+    throw new f.FlowError('task_json_invalid', 'Invalid JSON in ### ' + name + ': ' + error.message, 2);
+  }
+  f.demand(Array.isArray(value), 'task_json_invalid', '### ' + name + ' must be a JSON array');
+  return value;
+}
+
+function parseList(value) {
+  return [...new Set(String(value ?? '').split(/[,\s]+/).map(item => item.trim()).filter(Boolean))];
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]));
+  }
+  return value;
+}
+
+function testsDigest(task) {
+  return f.hash(JSON.stringify(canonical(task.tests))).slice(0, 12);
+}
+
+function startedTests(text) {
+  const matches = [...String(text).matchAll(/^-[ \t]+\[[^\]]+\][ \t]+started[ \t]+tests=([a-f0-9]{12})/gm)];
+  return matches.length ? matches.at(-1)[1] : null;
+}
+
+function validateTests(tests) {
+  f.demand(Array.isArray(tests), 'task_tests', 'Task tests must be an array');
+  const ids = new Set();
+  for (const test of tests) {
+    f.object(test, 'test'); f.string(test.id, 'test.id');
+    f.demand(!/[\r\n]/.test(test.id), 'test_id', 'test.id must fit on one line');
+    f.demand(!ids.has(test.id), 'test_duplicate', 'Duplicate test ID: ' + test.id); ids.add(test.id);
+    f.demand((test.argv !== undefined) !== (test.run !== undefined), 'test_command', 'Exactly one of argv/run required');
+    if (test.argv !== undefined) {
+      f.demand(Array.isArray(test.argv) && test.argv.length > 0 &&
+        test.argv.every(arg => typeof arg === 'string' && !arg.includes('\0')), 'test_command', 'argv must be strings');
+      f.string(test.argv[0], 'argv executable');
+    } else f.string(test.run, 'test.run');
+    if (test.cwd !== undefined) f.string(test.cwd, 'test.cwd');
+    if (test.timeout !== undefined) f.positive(test.timeout, 'test.timeout');
+    if (test.parallel !== undefined) f.demand(typeof test.parallel === 'boolean', 'test_parallel', 'parallel must be boolean');
+    if (test.group !== undefined) f.string(test.group, 'test.group');
+    if (test.env !== undefined) {
+      f.object(test.env, 'test.env');
+      for (const [key, value] of Object.entries(test.env)) {
+        f.demand(/^[A-Za-z_][A-Za-z0-9_]*$/.test(key), 'test_env', 'Invalid test env name: ' + key);
+        f.demand(typeof value === 'string' && !value.includes('\0'), 'test_env',
+          'Test env values must be strings: ' + key);
+        f.demand(!RESERVED_ENV.has(key), 'test_env', 'Test env cannot override ' + key);
+      }
+    }
+  }
+  return tests;
+}
+
+function validateTask(task) {
+  f.demand(/^TASK-\d+$/.test(task.id), 'task_identity', 'Invalid TASK ID: ' + task.id);
+  f.demand(STATES.includes(task.status), 'task_status', task.id + ': invalid Status: ' + task.status);
+  for (const dep of task.depends) f.demand(/^TASK-\d+$/.test(dep) && dep !== task.id,
+    'task_depends', 'Invalid dependency for ' + task.id + ': ' + dep);
+  task.scenarios.forEach(id => f.demand(id.length <= 120 && !/[\r\n]/.test(id),
+    'task_scenario', 'Invalid scenario reference: ' + id));
+  task.specRefs.forEach(config.reference);
+  task.paths.forEach(glob.compile);
+  validateTests(task.tests);
+  f.demand(typeof task.skipTests === 'boolean', 'task_skip', 'skip_tests must be boolean');
+  if (task.skipTests) f.string(task.skipReason, 'skip_reason');
+  if (task.e2e) f.string(task.e2e, 'e2e');
+  f.demand(Array.isArray(task.specDelta), 'delta_invalid', 'Spec Delta must be an array');
+  return task;
+}
+
+function parseTask(section) {
+  const values = fieldMap(section.text);
+  if (values.skipTests !== undefined && values.skipTests !== '') {
+    f.demand(['true', 'false'].includes(values.skipTests), 'task_skip',
+      'Skip-Tests must be true or false');
+  }
+  f.demand(values.status !== undefined && values.status !== '', 'task_status',
+    section.id + ': missing Status field');
+  const tests = jsonArray(subsection(section.text, 'Tests'), 'Tests');
+  const specDelta = jsonArray(subsection(section.text, 'Spec Delta'), 'Spec Delta');
+  const task = {
+    id: section.id, title: section.title,
+    status: values.status || '',
+    depends: parseList(values.depends),
+    source: values.source || '',
+    scenarios: parseList(values.scenarios),
+    specRefs: parseList(values.specRefs),
+    paths: parseList(values.paths),
+    e2e: values.e2e || '',
+    skipTests: values.skipTests === 'true',
+    skipReason: values.skipReason || '',
+    tests, specDelta, text: section.text
+  };
+  return validateTask(task);
+}
+
+function validateSet(tasks) {
+  const ids = new Set();
+  for (const task of tasks) {
+    f.demand(!ids.has(task.id), 'task_duplicate', 'Duplicate TASK ID: ' + task.id);
+    ids.add(task.id);
+  }
+  for (const task of tasks) {
+    for (const dep of task.depends) {
+      f.demand(ids.has(dep), 'task_depends', task.id + ' depends on missing ' + dep);
+    }
+  }
+}
+
+function parse(raw, file) {
+  const document = fm.parse(raw);
+  f.demand(document.meta.version === 1, 'task_version', 'Task document version must be 1');
+  f.string(document.meta.requirement, 'task requirement');
+  f.demand(path.basename(file, '.md') === document.meta.requirement,
+    'task_requirement', 'Task document name must match requirement: ' + document.meta.requirement);
+  const split = splitSections(document.body);
+  const tasks = split.sections.map(parseTask);
+  validateSet(tasks);
+  return { ...document, tasks, preamble: split.preamble };
+}
+
+function taskFrom(document, task) {
+  return { ...task, body: task.text, document, file: document.file, relative: document.relative,
+    raw: document.raw, meta: task, documentMeta: document.meta };
+}
+
+function find(document, taskId) {
+  const task = document.tasks.find(item => item.id === taskId);
+  f.demand(task, 'task_missing', 'Missing TASK: ' + taskId, 2);
+  return task;
+}
+
+function batches(tasks) {
+  const ids = new Set(tasks.map(task => task.id));
+  const pending = new Set(tasks.filter(task => task.status !== 'done').map(task => task.id));
+  const finished = new Set(tasks.filter(task => task.status === 'done').map(task => task.id));
+  const deps = Object.fromEntries(tasks.map(task => [task.id, new Set(task.depends)]));
+  for (const task of tasks) {
+    for (const dep of task.depends) f.demand(ids.has(dep), 'task_depends', task.id + ' depends on missing ' + dep);
+  }
+  const result = [];
+  while (pending.size) {
+    const ready = [...pending].filter(id => [...deps[id]].every(dep => finished.has(dep))).sort();
+    f.demand(ready.length > 0, 'task_cycle', 'Dependency cycle among: ' + [...pending].sort().join(', '));
+    result.push(ready);
+    ready.forEach(id => { pending.delete(id); finished.add(id); });
+  }
+  return result;
+}
+
+function fieldLine(name, value) {
+  return '- **' + name + '**:' + (value ? ' ' + value : '');
+}
+
+function setField(section, name, value) {
+  const key = Object.keys(FIELDS).find(item => FIELDS[item] === name);
+  const line = fieldLine(key, value);
+  const field = fieldEntries(section).get(name);
+  if (field) return section.slice(0, field.start) + line + section.slice(field.end);
+  const firstBreak = section.indexOf('\n');
+  return firstBreak < 0 ? section + '\n' + line : section.slice(0, firstBreak + 1) + line + '\n' + section.slice(firstBreak + 1);
+}
+
+function appendSubsection(section, name, lines) {
+  const marker = '### ' + name;
+  const area = subsectionRange(section, name);
+  const addition = lines.join('\n') + '\n';
+  if (!area) return section.replace(/\s*$/, '') + '\n\n' + marker + '\n\n' + addition;
+  return section.slice(0, area.end).replace(/\s*$/, '') + '\n' + addition +
+    (area.end < section.length ? '\n' : '') + section.slice(area.end);
+}
+
+function replaceTask(document, taskId, updater) {
+  const task = find(document, taskId);
+  const sections = splitSections(document.body).sections;
+  const section = sections.find(item => item.id === taskId);
+  f.demand(section, 'task_missing', 'Missing TASK: ' + taskId, 2);
+  const updated = updater(section.text);
+  const body = document.body.slice(0, section.start) + updated +
+    document.body.slice(section.start + section.text.length);
+  return { ...document, body, tasks: document.tasks.map(item => item.id === taskId ? { ...item, text: updated } : item) };
+}
+
+function updateTask(document, taskId, { status, field, value, log, verification } = {}) {
+  return replaceTask(document, taskId, section => {
+    let text = section;
+    if (status) text = setField(text, 'status', status);
+    if (field) text = setField(text, field, value);
+    if (log) text = appendSubsection(text, 'Log', ['- [' + new Date().toISOString() + '] ' +
+      log.replace(/[\r\n]+/g, ' ')]);
+    if (verification) text = appendSubsection(text, 'Verification', verification);
+    return text;
+  });
+}
+
+function write(document, body = document.body) {
+  return fm.stringify(document, document.meta, body);
+}
+
+module.exports = {
+  STATES, batches, find, parse, startedTests, taskFrom, testsDigest, updateTask,
+  validateSet, validateTask, validateTests, write
+};