@voidlabs.gg/voidshift-agents 0.4.4 → 0.5.0

package/dist/manage.js

@@ -1,10 +1,66 @@
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { AGENTS, STEPS, describeTrigger, triggerSpec } from "./config.js";
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { AGENTS, AGENT_FILE, OUTPUTS, STEP_ID, isBuiltin, readAgentFolder, stepFile, describeTrigger, triggerSpec } from "./config.js";
 import { parseCron } from "./cron.js";
 const isInt = (v, min, max) => typeof v === 'number' && Number.isInteger(v) && v >= min && v <= max;
+// The line a step's prompt must ask for, so the runner can read the result.
+const RESULT_LINE = { plan: 'RESULT:', commits: 'RESULT:', verdict: 'VERDICT:' };
+// Everything wrong with one step. `dir` is the agent folder its files are in.
+export function validateStep(step, config, dir) {
+    if (typeof step === 'string') {
+        if (!isBuiltin(step))
+            return [`Unknown step ${step}.`];
+        return config.enabled.length && !config.enabled.includes(step) ? [`Step ${step} is not enabled.`] : [];
+    }
+    if (!isObj(step))
+        return ['A step must be a step id or an object.'];
+    const problems = [];
+    const id = typeof step.id === 'string' && STEP_ID.test(step.id) ? step.id : null;
+    if (!id)
+        problems.push(`Step id ${String(step.id)} must be lowercase letters, digits and dashes.`);
+    else if (isBuiltin(id))
+        problems.push(`Step id ${id} is a built-in step; use "${id}" on its own, or another id.`);
+    const name = id ?? 'A step';
+    if (!OUTPUTS.includes(step.output))
+        problems.push(`${name} output must be one of: ${OUTPUTS.join(', ')}.`);
+    if (step.label !== undefined && typeof step.label !== 'string')
+        problems.push(`${name} label must be text.`);
+    if (step.prompt !== undefined && typeof step.prompt !== 'string')
+        problems.push(`${name} prompt must be a file name.`);
+    if (step.skill !== undefined && typeof step.skill !== 'string')
+        problems.push(`${name} skill must be a name or a folder.`);
+    const sources = [step.skill, step.prompt].filter((v) => v !== undefined).length;
+    if (step.output === 'publish') {
+        if (sources)
+            problems.push(`${name} only pushes the branch, so it takes no skill or prompt.`);
+    }
+    else if (sources !== 1)
+        problems.push(`${name} needs exactly one of skill or prompt.`);
+    else if (typeof (step.prompt ?? step.skill) === 'string') {
+        const file = stepFile(step, dir);
+        if (!file || !existsSync(file))
+            problems.push(`${name} ${step.prompt ? 'prompt' : 'skill'} ${file ?? ''} does not exist.`);
+        else {
+            const want = RESULT_LINE[step.output];
+            if (want && !readFileSync(file, 'utf8').includes(want))
+                problems.push(`${name} prompt never asks for a ${want} line.`);
+        }
+    }
+    if (step.engine !== undefined && step.engine !== 'claude' && step.engine !== 'codex')
+        problems.push(`${name} engine must be claude or codex.`);
+    if (step.model !== undefined && typeof step.model !== 'string')
+        problems.push(`${name} model must be text.`);
+    if (step.timeoutMinutes !== undefined && !isInt(step.timeoutMinutes, 1, 480))
+        problems.push(`${name} timeoutMinutes must be a whole number from 1 to 480.`);
+    if (step.write !== undefined && typeof step.write !== 'boolean')
+        problems.push(`${name} write must be true or false.`);
+    else if (step.write === false && step.output === 'commits')
+        problems.push(`${name} makes commits, so write cannot be false.`);
+    return problems;
+}
 // Everything wrong with one workflow, in plain words. Empty means it is fine.
-export function validateWorkflow(config, workflow) {
+// `dir` is the agent folder a folder workflow comes from.
+export function validateWorkflow(config, workflow, dir) {
     const problems = [];
     if (!workflow.triggers?.length)
         problems.push('Needs at least one trigger.');
@@ -26,16 +82,50 @@ export function validateWorkflow(config, workflow) {
     }
     if (!workflow.steps?.length)
         problems.push('Needs at least one step.');
-    for (const s of workflow.steps ?? []) {
-        if (!(s in STEPS))
-            problems.push(`Unknown step ${s}.`);
-        else if (config.enabled.length && !config.enabled.includes(s))
-            problems.push(`Step ${s} is not enabled.`);
+    const ids = new Set();
+    for (const s of Array.isArray(workflow.steps) ? workflow.steps : []) {
+        problems.push(...validateStep(s, config, dir));
+        const id = typeof s === 'string' ? s : isObj(s) ? s.id : undefined;
+        if (typeof id === 'string' && !isBuiltin(id)) {
+            if (ids.has(id))
+                problems.push(`Step id ${id} is used twice.`);
+            ids.add(id);
+        }
     }
     if (!config.projects[workflow.project])
         problems.push(`Project ${workflow.project} does not exist.`);
     if (!isInt(workflow.maxRounds, 1, 9))
         problems.push('Rounds must be a whole number from 1 to 9.');
+    const wb = workflow.writeBack;
+    if (wb !== undefined) {
+        if (!isObj(wb))
+            problems.push('writeBack must be an object.');
+        else {
+            if (wb.labels !== undefined && typeof wb.labels !== 'boolean')
+                problems.push('writeBack.labels must be true or false.');
+            if (wb.comment !== undefined && typeof wb.comment !== 'boolean')
+                problems.push('writeBack.comment must be true or false.');
+            if (wb.state !== undefined && wb.state !== null && (typeof wb.state !== 'string' || !wb.state.trim()))
+                problems.push('writeBack.state must be a state name, or null to never move the card.');
+        }
+    }
+    return problems;
+}
+// Everything wrong with an agent folder: its agent.json, its workflow and
+// prompt files, and a name config.json already uses.
+export function validateAgentFolder(dir, config) {
+    let workflow;
+    try {
+        workflow = readAgentFolder(dir);
+    }
+    catch (err) {
+        return [`${AGENT_FILE}: ${err.message}`];
+    }
+    const problems = validateWorkflow(config, workflow, dir);
+    const name = basename(dir);
+    const from = config.folders?.[name];
+    if (config.workflows[name] && (!from || resolve(from) !== resolve(dir)))
+        problems.push(`config.json already has a workflow named ${name}, and it wins. Rename the folder.`);
     return problems;
 }
 export const TRIGGER_FORMS = 'TEAM:LABEL (Linear), voidtrack:TEAM:LABEL, or cron:SCHEDULE:TASK';
@@ -121,6 +211,8 @@ export function validateConfig(value, saved) {
     }
     if (!Array.isArray(value.enabled) || value.enabled.some((a) => typeof a !== 'string' || !(a in AGENTS)))
         problems.push(`enabled must list agents from: ${Object.keys(AGENTS).join(', ')}.`);
+    if (value.commits !== undefined && (!isObj(value.commits) || Object.entries(value.commits).some(([k, v]) => !['signOff', 'dropAiTrailers'].includes(k) || typeof v !== 'boolean')))
+        problems.push('commits may only set signOff and dropAiTrailers, each true or false.');
     if (!Array.isArray(value.homes) || value.homes.some((h) => !isObj(h) || (h.kind !== 'claude' && h.kind !== 'codex') || typeof h.dir !== 'string'))
         problems.push('homes must be a list of { kind: claude or codex, dir }.');
     if (!isObj(value.workflows))
@@ -128,6 +220,9 @@ export function validateConfig(value, saved) {
     else {
         const ctx = { enabled: Array.isArray(value.enabled) ? value.enabled : [], projects: (projects ?? {}) };
         for (const [name, w] of Object.entries(value.workflows)) {
+            // Folder workflows are checked with their folder, by vsf agents validate.
+            if (isObj(value.folders) && value.folders[name])
+                continue;
             if (!isObj(w))
                 problems.push(`Workflow ${name} must be an object.`);
             else {

package/dist/memory.d.ts

@@ -1,2 +1,3 @@
 export declare function vaultPath(configDir: string): string | undefined;
 export declare function recall(selfCommand: string[], configDir: string, text: string): string;
+export declare function syncMemory(selfCommand: string[], configDir: string): string;

package/dist/memory.js

@@ -35,3 +35,15 @@ export function recall(selfCommand, configDir, text) {
         return '';
     }
 }
+// Brings the vault up to date through its git remote, or shares the notes
+// agents wrote. Never fails a run: returns a line worth logging, or ''.
+export function syncMemory(selfCommand, configDir) {
+    if (!vaultPath(configDir) || !selfCommand.length)
+        return '';
+    const [cmd, ...args] = selfCommand;
+    const r = spawnSync(cmd, [...args, 'memory', 'sync', '--quiet'], { encoding: 'utf8', timeout: 90_000 });
+    const out = `${r.stdout ?? ''}${r.stderr ?? ''}`.trim();
+    if (r.error)
+        return `memory sync did not run (${r.error.message})`;
+    return r.status === 0 ? out : out || 'memory sync failed';
+}

package/dist/names.d.ts

@@ -5,4 +5,5 @@ export declare function resolveName(names: string[], input: string, kind: string
     error: string;
 };
 export declare function parseStep(input: string): StepId | null;
+export declare const parseFrom: (input: string) => string | null;
 export declare const stepNames: () => string;

package/dist/names.js

@@ -1,4 +1,4 @@
-import { STEPS } from "./config.js";
+import { STEPS, STEP_ID } from "./config.js";
 // A workflow or project named in a command: the exact name, or the start of
 // exactly one name, e.g. "tether" for tether-relay-build.
 export function resolveName(names, input, kind) {
@@ -23,4 +23,7 @@ export function parseStep(input) {
     }
     return null;
 }
+// A step for --from: a built-in step by any of its names, or any id a custom
+// step could have. Whether the workflow has it is checked once it is known.
+export const parseFrom = (input) => parseStep(input) ?? (STEP_ID.test(input) ? input : null);
 export const stepNames = () => Object.keys(STEPS).map((id) => id.replace(/^vs-/, '')).join(', ');

package/dist/profile.d.ts

@@ -0,0 +1,10 @@
+import type { Check } from './types.ts';
+export declare const profileDir: (configDir: string) => string;
+export declare const RULES_FILE = "RULES.md";
+export declare const CLAUDE_SETTINGS = "claude-settings.json";
+export declare function readRules(configDir: string): string;
+export declare function renderClaudeSettings(configDir: string): string | null;
+export declare function claudeSettingsFile(configDir: string, runDir: string): string | undefined;
+export declare const rulesSection: (rules: string) => string;
+export declare function initProfile(configDir: string): string[];
+export declare function profileChecks(configDir: string): Check[];

package/dist/profile.js

@@ -0,0 +1,70 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { agentsDir } from "./config.js";
+// Your profile: what every agent run carries, on any machine, without touching
+// a Claude or Codex folder. RULES.md is added to every step's prompt, and
+// claude-settings.json is passed to Claude runs, with {{profile}} standing for
+// this folder so hooks can live in it.
+export const profileDir = (configDir) => join(agentsDir(configDir), 'profile');
+export const RULES_FILE = 'RULES.md';
+export const CLAUDE_SETTINGS = 'claude-settings.json';
+export function readRules(configDir) {
+    const path = join(profileDir(configDir), RULES_FILE);
+    return existsSync(path) ? readFileSync(path, 'utf8').trim() : '';
+}
+// The Claude settings with {{profile}} filled in, as text, or null when there
+// are none. Throws when the file is not a JSON object.
+export function renderClaudeSettings(configDir) {
+    const dir = profileDir(configDir);
+    const path = join(dir, CLAUDE_SETTINGS);
+    if (!existsSync(path))
+        return null;
+    const text = readFileSync(path, 'utf8').replaceAll('{{profile}}', dir);
+    const value = JSON.parse(text);
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${CLAUDE_SETTINGS} must be a JSON object`);
+    return text;
+}
+// Writes the rendered settings into a run folder and returns the path, or
+// undefined when the profile has none.
+export function claudeSettingsFile(configDir, runDir) {
+    const text = renderClaudeSettings(configDir);
+    if (text === null)
+        return undefined;
+    const out = join(runDir, CLAUDE_SETTINGS);
+    writeFileSync(out, text);
+    return out;
+}
+// The prompt section for your rules, empty when there are none.
+export const rulesSection = (rules) => (rules ? `# Your rules\n\nFollow these in everything you write, including commits and comments.\n\n${rules}` : '');
+const STARTER_RULES = `<!-- Rules every agent follows on every run, on every machine.
+     Write them as you would tell a teammate. Delete this comment. -->
+`;
+// Creates the folder with a starter RULES.md. Existing files are kept.
+export function initProfile(configDir) {
+    const dir = profileDir(configDir);
+    mkdirSync(dir, { recursive: true });
+    const made = [];
+    const rules = join(dir, RULES_FILE);
+    if (!existsSync(rules)) {
+        writeFileSync(rules, STARTER_RULES);
+        made.push(RULES_FILE);
+    }
+    return made;
+}
+export function profileChecks(configDir) {
+    const dir = profileDir(configDir);
+    if (!existsSync(dir))
+        return [];
+    const parts = [];
+    if (readRules(configDir).replace(/<!--[\s\S]*?-->/g, '').trim())
+        parts.push('rules');
+    try {
+        if (renderClaudeSettings(configDir) !== null)
+            parts.push('Claude settings');
+    }
+    catch (err) {
+        return [{ name: 'agent profile', status: 'fail', detail: `${CLAUDE_SETTINGS}: ${err.message}`, fix: `fix ${join(dir, CLAUDE_SETTINGS)}` }];
+    }
+    return [parts.length ? { name: 'agent profile', status: 'ok', detail: parts.join(', ') } : { name: 'agent profile', status: 'warn', detail: 'empty', fix: `add rules to ${join(dir, RULES_FILE)}` }];
+}

package/dist/runner.d.ts

@@ -1,4 +1,4 @@
-import { type AgentsConfig, type Workflow, type Project, type StepId, type Trigger } from './config.ts';
+import { type AgentsConfig, type Workflow, type Project, type Trigger } from './config.ts';
 import type { Card } from './linear.ts';
 import { type Tracker, type Trackers } from './tracker.ts';
 export interface RunContext {
@@ -10,7 +10,7 @@ export interface RunContext {
 }
 export declare function summarize(output: string): string;
 export declare function runCard(card: Card, trigger: Trigger, workflowName: string, workflow: Workflow, project: Project, rc: RunContext, opts?: {
-    from?: StepId;
+    from?: string;
 }): Promise<'verified' | 'changes' | 'parked'>;
 type Job = {
     card: Card;
@@ -25,6 +25,6 @@ export declare function nextJob(rc: RunContext, only?: string, workflowName?: st
 export declare function cancelCard(tracker: Tracker, configDir: string, cardId: string, label: string, source?: 'linear' | 'voidtrack'): Promise<boolean>;
 export declare function tick(rc: RunContext, only?: string, opts?: {
     workflow?: string;
-    from?: StepId;
+    from?: string;
 }): Promise<number>;
 export {};

package/dist/runner.js

@@ -1,16 +1,14 @@
-import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync } from 'node:fs';
 import { basename, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { LABELS, PLAN_HEADING, buildPrompt, findingsFor, fixTarget, isStatusLabel, latestPlan, parseDevResult, parseVerdict, planBody, qaPassed, stageLabels, verdictBlock, } from "./workflow.js";
-import { STEPS, agentsDir, hasWork, isCardTrigger, isProducer } from "./config.js";
+import { agentsDir, hasWork, isCardTrigger, resolveStep, stepId, stepIdLabel } from "./config.js";
 import { lastDue, parseCron } from "./cron.js";
 import { runAgent, stopAgents } from "./engine.js";
-import { commitsAhead, defaultBranch, ensureDraftPr, ensureWorktree, headSha, markReady, push, resetWorktree, waitForChecks, waitForPrHead } from "./git.js";
+import { commitsAhead, enforceCommitPolicy, defaultBranch, ensureDraftPr, ensureWorktree, headSha, markReady, push, resetWorktree, waitForChecks, waitForPrHead } from "./git.js";
 import { noTracker } from "./tracker.js";
-import { recall, vaultPath } from "./memory.js";
+import { recall, syncMemory, vaultPath } from "./memory.js";
+import { claudeSettingsFile, readRules, rulesSection } from "./profile.js";
 import { bootTime, clearCurrent, isPaused, ours, readCurrent, readPending, writeCurrent, writePending, writeRun, readCronState, writeCronState } from "./state.js";
-const packDir = fileURLToPath(new URL('../pack/', import.meta.url));
-const skill = (name) => readFileSync(join(packDir, name, 'SKILL.md'), 'utf8');
 const stamp = () => new Date().toISOString().replace(/[:.]/g, '-');
 class Park extends Error {
 }
@@ -37,7 +35,10 @@ export function summarize(output) {
 }
 // The run in progress, so a cancel signal can mark it.
 let active = null;
-const isVerdict = (s) => STEPS[s].output === 'verdict';
+const isVerdict = (d) => d.output === 'verdict';
+const isProducer = (d) => d.output === 'plan' || d.output === 'commits';
+// The card label for a step: its own for a built-in step, a generic one otherwise.
+const stageOf = (d) => LABELS.stage[d.builtin ?? ''] ?? LABELS.working;
 // One card through a trigger's workflow. Steps run in order. A failed check (or a
 // run of consecutive checks) sends its findings back to the nearest earlier
 // step that produces something, Plan or Dev, and the workflow continues from
@@ -50,7 +51,9 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
     const runDir = join(agentsDir(rc.configDir), 'runs', card.identifier, stamp());
     mkdirSync(runDir, { recursive: true });
     const say = (line) => log(`${card.identifier} ${line}`);
-    const steps = workflow.steps;
+    // Write back settings apply to card runs; a scheduled run has nothing to write to.
+    const writeBack = isCardTrigger(trigger) ? (workflow.writeBack ?? {}) : {};
+    const labelsOn = writeBack.labels !== false;
     const startedAt = new Date().toISOString();
     const record = { card: card.identifier, title: card.title, url: card.url || undefined, workflow: workflowName, trigger: label || (trigger.source === 'cron' ? trigger.schedule : ''), source: trigger.source, steps: [], outcome: 'running', startedAt };
     active = { record, runDir };
@@ -61,8 +64,8 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
     const mark = (step) => writeCurrent(rc.configDir, { pid: process.pid, card: card.identifier, title: card.title, workflow: workflowName, step, round: loops, startedAt, runDir, source: trigger.source });
     // Written before the first tracker call, so a cancel always knows the card.
     mark('Starting');
-    const begin = (step) => {
-        const rec = { step, label: STEPS[step].label, startedAt: new Date().toISOString() };
+    const begin = (def) => {
+        const rec = { step: def.id, label: def.label, startedAt: new Date().toISOString() };
         record.steps.push(rec);
         mark(rec.label);
         save();
@@ -89,7 +92,13 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
     const setRound = (n) => {
         loops = n;
     };
-    const stage = (name, round) => linear.setLabels(card, stageLabels(card.labels, label, name, round));
+    const stage = async (name, round) => {
+        if (labelsOn)
+            await linear.setLabels(card, stageLabels(card.labels, label, name, round));
+    };
+    // How a run ends on the card: a stage label, or with labels off only the
+    // trigger taken away so the card is not picked up again.
+    const endLabels = (name, round) => linear.setLabels(card, labelsOn ? stageLabels(card.labels, label, name, round) : card.labels.filter((l) => l !== label));
     // The tracker hears from the runner twice: the plan once it has passed review,
     // and one final comment. Findings stay here until the final one.
     let lastFindings = '';
@@ -103,40 +112,55 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
     async function park(reason) {
         say(`parked: ${reason}`);
         const comment = `**Parked:** ${reason}${lastFindings ? `\n\n${lastFindings}` : ''}\n\nFix the cause, then add \`${label}\` again to retry.`;
-        const add = [LABELS.parked, ...(loops ? [LABELS.version(loops)] : [])];
+        const add = labelsOn ? [LABELS.parked, ...(loops ? [LABELS.version(loops)] : [])] : [];
         let commented = false;
         try {
             await postPlan();
             await linear.comment(card, comment);
             commented = true;
-            await linear.setLabels(card, stageLabels(card.labels, label, LABELS.parked, loops || undefined));
+            await endLabels(LABELS.parked, loops || undefined);
         }
         catch (err) {
             if (!isCardTrigger(trigger))
                 return done('parked', reason);
             say(`could not reach ${trigger.source === 'voidtrack' ? 'VoidTrack' : 'Linear'} to park it (${err.message}). Will retry next minute.`);
             // An empty comment is skipped on retry, so it is not posted twice.
-            writePending(rc.configDir, [...readPending(rc.configDir), { card: card.identifier, comment: commented ? '' : comment, drop: [label], add, dropStatus: true, source: trigger.source }]);
+            writePending(rc.configDir, [...readPending(rc.configDir), { card: card.identifier, comment: commented ? '' : comment, drop: [label], add, dropStatus: labelsOn, source: trigger.source }]);
         }
         return done('parked', reason);
     }
     try {
         if (!existsSync(join(project.path, '.git')))
             throw new Park(`The project folder ${project.path} is not a git repository on this Mac.`);
-        const from = opts.from ? steps.indexOf(opts.from) : 0;
+        const steps = workflow.steps.map((s) => resolveStep(s, config, config.folders?.[workflowName]));
+        const from = opts.from ? steps.findIndex((d) => d.id === opts.from) : 0;
         if (from < 0)
-            throw new Park(`Workflow ${workflowName} has no ${STEPS[opts.from].label} step.`);
+            throw new Park(`Workflow ${workflowName} has no ${stepIdLabel(opts.from)} step.`);
         // A scheduled run has no card to plan on, so its task is the plan unless a Plan step writes one.
         let plan = isCardTrigger(trigger) ? latestPlan(await linear.comments(card.identifier)) : card.description ?? null;
-        const firstPlan = steps.indexOf('vs-plan', from);
-        const needsPlan = steps.findIndex((s, n) => n >= from && (s === 'vs-dev' || s === 'vs-plan-review'));
+        const firstPlan = steps.findIndex((d, n) => n >= from && d.output === 'plan');
+        // A check before any commits is a check on the plan, like Plan review.
+        const needsPlan = steps.findIndex((d, n) => n >= from && (d.output === 'commits' || (d.output === 'verdict' && d.builtin !== 'vs-qa')));
         if (!plan && needsPlan >= 0 && (firstPlan < 0 || firstPlan > needsPlan)) {
             throw new Park('No plan comment (starting with "## Plan") was found. Publish a plan first, or start the workflow with Plan.');
         }
-        await stage(LABELS.stage[steps[from]]);
+        await stage(stageOf(steps[from]));
         const base = project.base || defaultBranch(project.path);
         const vault = vaultPath(rc.configDir);
-        const known = [recall(rc.selfCommand, rc.configDir, `${workflow.project} ${card.title}\n${card.description ?? ''}`), vault ? memoryNote(vault) : ''].filter(Boolean).join('\n\n');
+        // Your profile rides along on every step: rules in the prompt, Claude settings as a file.
+        let settingsFile;
+        try {
+            settingsFile = claudeSettingsFile(rc.configDir, runDir);
+        }
+        catch (err) {
+            throw new Park(`Your agent profile's Claude settings are broken: ${err.message}`);
+        }
+        const rules = rulesSection(readRules(rc.configDir));
+        // Latest notes from every machine before recall reads them.
+        const pulled = syncMemory(rc.selfCommand, rc.configDir);
+        if (pulled)
+            say(pulled);
+        const known = [recall(rc.selfCommand, rc.configDir, `${workflow.project} ${card.title}\n${card.description ?? ''}`), vault ? memoryNote(vault) : '', rules].filter(Boolean).join('\n\n');
         const worktree = join(agentsDir(rc.configDir), 'worktrees', card.identifier);
         ensureWorktree(project.path, worktree, card.branchName, base);
         say(`working in ${worktree} on ${card.branchName}`);
@@ -145,13 +169,12 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         let prUrl = '';
         let logs = 0;
         const planText = () => plan ?? '(No plan was posted on this card. Check the work against the card itself.)';
-        const timeoutMs = config.timeoutMinutes * 60_000;
         const logFile = (name) => join(runDir, `${String(logs++).padStart(2, '0')}-${name}.log`);
-        async function check(step, round) {
-            const label = STEPS[step].label;
-            const rec = begin(step);
+        async function check(def, round) {
+            const label = def.label;
+            const rec = begin(def);
             let ciNote = '';
-            if (step === 'vs-qa') {
+            if (def.builtin === 'vs-qa') {
                 if (commitsAhead(worktree, base) === 0) {
                     end(rec, 'SKIP', 'No changes on the branch yet.');
                     return { step: label, verdict: 'SKIP', report: 'No changes on the branch yet.' };
@@ -179,12 +202,12 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                     ciNote = ci.verdict === 'SHIP' ? '# CI\n\nCI passed on this branch.' : '# CI\n\nThis repo has no CI checks.';
                 }
             }
-            const log = logFile(step);
+            const log = logFile(def.id);
             const r = await runAgent({
-                engine: config.engine, model: config.models.review, cwd: worktree, vault, write: step === 'vs-qa', logFile: log, timeoutMs,
-                prompt: buildPrompt({ skill: skill(step), card, plan: planText(), base, round, extra: [known, ciNote, UNATTENDED].filter(Boolean).join('\n\n') }),
+                engine: def.engine, model: def.model, cwd: worktree, vault, settingsFile, write: def.write, logFile: log, timeoutMs: def.timeoutMs,
+                prompt: buildPrompt({ skill: def.prompt(), card, plan: planText(), base, round, extra: [known, ciNote, UNATTENDED].filter(Boolean).join('\n\n') }),
             });
-            if (step === 'vs-qa')
+            if (def.builtin === 'vs-qa')
                 resetWorktree(worktree);
             const verdict = parseVerdict(r.output);
             end(rec, verdict, r.output, log);
@@ -192,18 +215,18 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         }
         let i = from;
         while (i < steps.length) {
-            const step = steps[i];
-            say(`${STEPS[step].label}`);
-            if (isVerdict(step)) {
+            const def = steps[i];
+            say(def.label);
+            if (isVerdict(def)) {
                 const [start, end] = verdictBlock(steps, i, isVerdict);
                 const target = fixTarget(steps, start, isProducer);
                 const producer = target >= 0 ? steps[target] : undefined;
                 // The round being checked: how many times its producer has run.
-                const round = Math.max(producer === 'vs-plan' ? runs.plan : runs.dev, 1);
+                const round = Math.max(producer?.output === 'plan' ? runs.plan : runs.dev, 1);
                 setRound(round);
                 const results = [];
                 for (const s of steps.slice(start, end)) {
-                    await stage(LABELS.stage[s], round);
+                    await stage(stageOf(s), round);
                     results.push(await check(s, round));
                 }
                 if (qaPassed(results)) {
@@ -215,26 +238,26 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                 if (target < 0) {
                     await postPlan();
                     await linear.comment(card, `**Changes needed.**\n\n${notes}`);
-                    await linear.setLabels(card, stageLabels(card.labels, label, LABELS.changes, round));
+                    await endLabels(LABELS.changes, round);
                     say('changes requested');
                     return done('changes');
                 }
                 // Rounds caps how many times Plan or Dev runs, counting the first.
                 if (round >= workflow.maxRounds) {
-                    throw new Park(`Checks still failed after ${round} ${producer === 'vs-plan' ? 'plan' : 'dev'} rounds.${prUrl ? ` PR: ${prUrl}` : ''}`);
+                    throw new Park(`Checks still failed after ${round} ${producer?.output === 'plan' ? 'plan' : 'dev'} rounds.${prUrl ? ` PR: ${prUrl}` : ''}`);
                 }
                 findings.set(target, notes);
                 i = target;
                 continue;
             }
-            if (step === 'vs-plan') {
+            if (def.output === 'plan') {
                 setRound(runs.plan + 1);
-                await stage(LABELS.stage[step], runs.plan + 1);
-                const rec = begin(step);
-                const log = logFile('plan');
+                await stage(stageOf(def), runs.plan + 1);
+                const rec = begin(def);
+                const log = logFile(def.builtin ? 'plan' : def.id);
                 const r = await runAgent({
-                    engine: config.engine, model: config.models.dev, cwd: worktree, vault, write: false, logFile: log, timeoutMs,
-                    prompt: buildPrompt({ skill: skill('vs-plan'), card, plan: plan ?? '(none yet, you are writing it)', base, round: runs.plan + 1, findings: findings.get(i), extra: [known, UNATTENDED].filter(Boolean).join('\n\n') }),
+                    engine: def.engine, model: def.model, cwd: worktree, vault, settingsFile, write: def.write, logFile: log, timeoutMs: def.timeoutMs,
+                    prompt: buildPrompt({ skill: def.prompt(), card, plan: plan ?? '(none yet, you are writing it)', base, round: runs.plan + 1, findings: findings.get(i), extra: [known, UNATTENDED].filter(Boolean).join('\n\n') }),
                 });
                 const result = parseDevResult(r.output);
                 end(rec, result.status === 'blocked' ? 'blocked' : 'done', r.output, log);
@@ -244,22 +267,22 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                 planToPost = plan;
                 runs.plan++;
             }
-            else if (step === 'vs-publish') {
+            else if (def.output === 'publish') {
                 await postPlan();
-                const rec = begin(step);
+                const rec = begin(def);
                 push(worktree, card.branchName);
                 end(rec, 'pushed');
             }
-            else if (step === 'vs-dev') {
+            else if (def.output === 'commits') {
                 await postPlan();
                 setRound(runs.dev + 1);
-                await stage(LABELS.stage[step], runs.dev + 1);
-                const rec = begin(step);
-                const log = logFile('dev');
+                await stage(stageOf(def), runs.dev + 1);
+                const rec = begin(def);
+                const log = logFile(def.builtin ? 'dev' : def.id);
                 const before = headSha(worktree);
                 const dev = await runAgent({
-                    engine: config.engine, model: config.models.dev, cwd: worktree, vault, write: true, logFile: log, timeoutMs,
-                    prompt: buildPrompt({ skill: skill('vs-dev'), card, plan: planText(), base, round: runs.dev + 1, findings: findings.get(i), extra: [known, UNATTENDED].filter(Boolean).join('\n\n') }),
+                    engine: def.engine, model: def.model, cwd: worktree, vault, settingsFile, write: def.write, logFile: log, timeoutMs: def.timeoutMs,
+                    prompt: buildPrompt({ skill: def.prompt(), card, plan: planText(), base, round: runs.dev + 1, findings: findings.get(i), extra: [known, UNATTENDED].filter(Boolean).join('\n\n') }),
                 });
                 const result = parseDevResult(dev.output);
                 end(rec, result.status === 'blocked' ? 'blocked' : 'done', dev.output, log);
@@ -271,23 +294,42 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                 // just check the same commit again.
                 if (runs.dev > 0 && headSha(worktree) === before)
                     throw new Park('The dev agent made no new commits this round.');
+                // Only this round's commits, which are not pushed yet.
+                const fixed = enforceCommitPolicy(worktree, before, config.commits ?? {});
+                if (fixed)
+                    say(`applied the commit policy to ${fixed} commit${fixed === 1 ? '' : 's'}`);
                 push(worktree, card.branchName);
                 prUrl = ensureDraftPr(worktree, card.branchName, base, `${card.identifier}: ${card.title}`, card.url);
                 record.prUrl = prUrl;
                 save();
                 runs.dev++;
             }
+            else {
+                // A step with no output the workflow reads: it runs once and must finish.
+                await stage(stageOf(def), loops || undefined);
+                const rec = begin(def);
+                const log = logFile(def.id);
+                const r = await runAgent({
+                    engine: def.engine, model: def.model, cwd: worktree, vault, settingsFile, write: def.write, logFile: log, timeoutMs: def.timeoutMs,
+                    prompt: buildPrompt({ skill: def.prompt(), card, plan: plan ?? '(none)', base, round: loops || 1, extra: [known, UNATTENDED].filter(Boolean).join('\n\n') }),
+                });
+                end(rec, r.ok ? 'done' : 'failed', r.output, log);
+                if (!r.ok)
+                    throw new Park(`The ${def.label} step failed or timed out.`);
+            }
             findings.delete(i);
             i++;
         }
         await postPlan();
-        let moved = false;
-        if (hasWork(workflow)) {
+        // Unset moves a card with commits to reviewState; a state always moves it; null never does.
+        const state = writeBack.state === undefined ? (hasWork(workflow) ? config.reviewState : null) : writeBack.state;
+        if (hasWork(workflow))
             markReady(worktree, card.branchName);
-            moved = await linear.moveTo(card, config.reviewState);
+        const moved = state ? await linear.moveTo(card, state) : true;
+        await endLabels(LABELS.verified, loops || undefined);
+        if (writeBack.comment !== false) {
+            await linear.comment(card, `**All checks passed.**${prUrl ? ` PR ready: ${prUrl}` : ''}${!moved ? `\n\n(No "${state}" state on this team, so the card was not moved.)` : ''}`);
         }
-        await linear.setLabels(card, stageLabels(card.labels, label, LABELS.verified, loops || undefined));
-        await linear.comment(card, `**All checks passed.**${prUrl ? ` PR ready: ${prUrl}` : ''}${hasWork(workflow) && !moved ? `\n\n(No "${config.reviewState}" state on this team, so the card was not moved.)` : ''}`);
         say('verified');
         return done('verified');
     }
@@ -298,6 +340,10 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
     }
     finally {
         active = null;
+        // Share whatever notes the agents wrote, whatever the outcome.
+        const shared = syncMemory(rc.selfCommand, rc.configDir);
+        if (shared)
+            say(shared);
     }
 }
 // A scheduled run's stand-in for a card: the task, on a branch of its own.
@@ -504,8 +550,8 @@ export async function tick(rc, only, opts = {}) {
             rc.log(`Workflow ${job.workflow} points at a missing project ${workflow.project}. Run vsf agents workflow edit to fix it.`);
             return 1;
         }
-        if (opts.from && !workflow.steps.includes(opts.from)) {
-            rc.log(`Workflow ${job.workflow} has no ${STEPS[opts.from].label} step.`);
+        if (opts.from && !workflow.steps.some((s) => stepId(s) === opts.from)) {
+            rc.log(`Workflow ${job.workflow} has no ${stepIdLabel(opts.from)} step.`);
             return 2;
         }
         const outcome = await runCard(job.card, job.trigger, job.workflow, workflow, project, rc, { from: opts.from });

package/dist/state.d.ts

@@ -1,4 +1,4 @@
-import { type StepId, type Trigger } from './config.ts';
+import { type Trigger } from './config.ts';
 export interface Current {
     pid: number;
     card?: string;
@@ -32,7 +32,7 @@ export declare function readPending(configDir: string): Pending[];
 export declare function writePending(configDir: string, pending: Pending[]): void;
 export type Outcome = 'running' | 'verified' | 'changes' | 'parked' | 'cancelled';
 export interface StepRecord {
-    step: StepId;
+    step: string;
     label: string;
     startedAt: string;
     endedAt?: string;