@optitransfer/proofline 0.2.0-next.0 → 0.2.0-next.1

package/src/contract.mjs

@@ -1,7 +1,7 @@
 // Contract + plan model: proofline.json at the repo root (committed).
 import fs from 'node:fs';
 import path from 'node:path';
-import { readJson, writeJson, sha256, canon } from './util.mjs';
+import { readJson, writeJson, sha256, canon, git, matchAny } from './util.mjs';
 
 export const SCHEMA = 'proofline/1';
 export const PHASES = ['intake', 'design', 'plan', 'implement', 'verify', 'integrate', 'release', 'monitor'];
@@ -12,6 +12,26 @@ export const STATUS = {
 // Task status vocabulary (derived, never self-declared)
 export const TASK_STATUS = ['not_started', 'in_progress', 'verified', 'failed', 'blocked'];
 
+/** Stop rules a scaffolded task carries. brief and steer still run when a loaded task has none. */
+export const DEFAULT_STOP_RULES = [
+  "If a criterion cannot pass without weakening a rule, widening a bypass list, or signing with a key that is not the owner's: STOP and report. Never mark a boundary criterion passed by hand.",
+  'If the environment a criterion needs is missing (repository admin, the owner key, a container runtime, OIDC): report BLOCKED with the exact missing item.',
+];
+
+const KINDS = ['feature', 'docs', 'release'];
+
+/** A path the scaffold can place inside scope. Prefer `prefer` when it already matches. */
+function slotted(allow, prefer) {
+  if (matchAny(prefer, allow)) return prefer;
+  for (const g of allow) {
+    if (g.endsWith('/**')) {
+      const p = `${g.slice(0, -3)}/change.test.mjs`;
+      if (matchAny(p, allow)) return p;
+    }
+  }
+  return prefer;
+}
+
 export const DEFAULT_FORBIDDEN = {
   test_skip_only: true,          // .skip( .only( {skip: test.todo  it.skip  xit(
   timeout_raise: true,           // any numeric timeout increased in the diff
@@ -65,6 +85,39 @@ export function makeTask({ id, title, phase = 'implement', owner, depends_on = [
   };
 }
 
+/**
+ * Print-ready task: standard criteria and the default stop rules, for an agent to fill in.
+ * kind feature: a red-then-green test and the suite. docs: a grep. release: one command.
+ * Scope and pushed are always present. Does not write the contract.
+ */
+export function scaffoldTask({ title, scope, kind = 'feature', id = 'TASK' } = {}) {
+  if (!title || !String(title).trim()) throw new Error('scaffold needs a title');
+  if (!KINDS.includes(kind)) throw new Error('--kind must be feature, docs or release');
+  const allow = String(scope ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+  if (!allow.length) throw new Error('scaffold needs a scope');
+  const criteria = [];
+  const add = (statement, verifier) => criteria.push({ statement, verifier });
+  if (kind === 'docs') {
+    const file = allow.find((g) => !/[*?]/.test(g)) || slotted(allow, 'README.md').replace(/change\.test\.mjs$/, 'change.md');
+    add('the docs name the change', { type: 'grep', file, pattern: 'CHANGE', must: 'present' });
+  } else if (kind === 'release') {
+    add('the release check exits 0', { type: 'command', cmd: 'npm test', expect_exit: 0 });
+  } else {
+    add('the new behavior fails on the base and passes now', { type: 'test_red_green', test_file: slotted(allow, 'test/change.test.mjs'), cmd: 'node --test {test}' });
+    add('suite green', { type: 'command', cmd: 'npm test', expect_exit: 0 });
+  }
+  add('Changes stay in scope', { type: 'scope' });
+  add('Committed and pushed to main', { type: 'pushed' });
+  return makeTask({ id, title, phase: kind === 'release' ? 'release' : 'implement', scope: allow, criteria, stop_rules: DEFAULT_STOP_RULES });
+}
+
+/** Double-quoted `sh -c` / `bash -c` whose quotes contain `$`. The verifier runs bash -c itself, so an outer shell would expand `$` first. */
+function expandingShell(cmd) {
+  if (typeof cmd !== 'string') return false;
+  const m = cmd.match(/(?:^|[;&|]\s*)(?:sh|bash)\s+-c\s+"([^"]*)"/);
+  return !!(m && m[1].includes('$'));
+}
+
 const isName = (x) => typeof x === 'string' && x.trim() !== '';
 
 /** A task belongs to an owner's lane when it is theirs or has no owner. No owner given: every task. */
@@ -117,6 +170,49 @@ export function validate(c) {
   return errs;
 }
 
+/** The shapes contract validate refuses, on top of validate(). The hook keeps validate() so a fixture without these fields still gates. */
+function lintErrors(c) {
+  const errors = [];
+  for (const t of c.tasks || []) {
+    if (!Array.isArray(t.stop_rules) || !t.stop_rules.length || t.stop_rules.some((s) => typeof s !== 'string' || !s.trim())) errors.push(`${t.id}: no stop_rules`);
+    if (!(t.criteria || []).some((a) => a?.verifier?.type === 'scope')) errors.push(`${t.id}: no scope criterion`);
+    const allow = Array.isArray(t.scope?.allow) ? t.scope.allow : [];
+    for (const a of t.criteria || []) {
+      const v = a.verifier;
+      if (!v) continue;
+      for (const key of ['file', 'path', 'test_file', 'entry']) {
+        const rel = v[key];
+        if (typeof rel !== 'string' || !rel || !allow.length) continue;
+        if (!matchAny(rel, allow)) errors.push(`${t.id}/${a.id}: ${key} ${rel} is outside scope`);
+      }
+      if (expandingShell(v.cmd)) errors.push(`${t.id}/${a.id}: command is a double-quoted sh -c or bash -c that contains $`);
+    }
+  }
+  return errors;
+}
+
+/** Structural errors from validate, the scaffold lint, and a warning when a grep already matches on the base revision. */
+export function lint(c, { root, base } = {}) {
+  const errors = [...validate(c), ...lintErrors(c)];
+  const warnings = [];
+  if (!root || !base) return { errors, warnings };
+  const rev = git(['rev-parse', '--verify', `${base}^{commit}`], root);
+  if (!rev.ok) return { errors, warnings };
+  const sha = rev.out;
+  for (const t of c.tasks || []) {
+    for (const a of t.criteria || []) {
+      const v = a.verifier;
+      if (v?.type !== 'grep' || typeof v.file !== 'string' || typeof v.pattern !== 'string') continue;
+      const shown = git(['show', `${sha}:${v.file}`], root);
+      if (!shown.ok) continue;
+      let re;
+      try { re = new RegExp(v.pattern, v.flags || 'm'); } catch { continue; }
+      if (re.test(shown.out)) warnings.push(`${t.id}/${a.id}: grep /${v.pattern}/ already matches ${v.file} on ${sha}`);
+    }
+  }
+  return { errors, warnings };
+}
+
 export function topo(tasks) {
   const by = new Map(tasks.map((t) => [t.id, t])); const out = []; const st = new Map();
   const visit = (id) => {
@@ -160,4 +256,149 @@ export function weakenings(base, cur) {
   return out;
 }
 
+/** Fields whose canonical bytes differ. This is the refusal. weakenings() stays the explanation. */
+export function contractFieldChanges(base, cur) {
+  if (!base || !cur) return [];
+  if (contractHash(base) === contractHash(cur)) return [];
+  const out = [];
+  const walk = (a, b, path) => {
+    if (Object.is(a, b)) return;
+    const aArr = Array.isArray(a);
+    const bArr = Array.isArray(b);
+    if (aArr || bArr) {
+      const left = aArr ? a : [];
+      const right = bArr ? b : [];
+      const n = Math.max(left.length, right.length);
+      for (let i = 0; i < n; i++) {
+        const id = (right[i] && right[i].id) || (left[i] && left[i].id) || String(i);
+        walk(left[i], right[i], path ? `${path}/${id}` : String(id));
+      }
+      return;
+    }
+    if (a && b && typeof a === "object" && typeof b === "object") {
+      const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+      for (const k of keys) walk(a[k], b[k], path ? `${path}/${k}` : k);
+      return;
+    }
+    const shown = (v) => (v === undefined ? "absent" : JSON.stringify(v));
+    out.push(`${path}: ${shown(a)} -> ${shown(b)}`);
+  };
+  walk(base, cur, "");
+  return out;
+}
+
 export function loadFile(f) { return JSON.parse(fs.readFileSync(f, 'utf8')); }
+
+/** End index of the JSON array named `key`, so an append can keep every byte before it. */
+function arrayEnd(text, key) {
+  const marker = `"${key}"`;
+  const at = text.indexOf(marker);
+  if (at < 0) return null;
+  const bracket = text.indexOf('[', at);
+  if (bracket < 0) return null;
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  for (let i = bracket; i < text.length; i++) {
+    const c = text[i];
+    if (inStr) {
+      if (esc) esc = false;
+      else if (c === '\\') esc = true;
+      else if (c === '"') inStr = false;
+      continue;
+    }
+    if (c === '"') { inStr = true; continue; }
+    if (c === '[') depth++;
+    else if (c === ']') {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return null;
+}
+
+function insertValues(text, key, values) {
+  if (!values.length) return text;
+  const end = arrayEnd(text, key);
+  if (end == null) throw new Error(`no ${key} array`);
+  const body = text.slice(text.lastIndexOf('[', end) + 1, end);
+  const lines = values.map((v) => '    ' + JSON.stringify(v)).join(',\n');
+  const chunk = body.trim() ? `,\n${lines}` : `\n${lines}\n  `;
+  return text.slice(0, end) + chunk + text.slice(end);
+}
+
+function ownerTable(spec) {
+  const map = new Map();
+  if (!spec) return map;
+  for (const pair of String(spec).split(',')) {
+    const [from, to] = pair.split('=').map((s) => s.trim());
+    if (from && to) map.set(from, to);
+  }
+  return map;
+}
+
+/** The contract text with tasks appended. A duplicate id throws and the caller writes nothing. Existing bytes stay. */
+export function appendTaskText(text, tasks) {
+  const current = JSON.parse(text);
+  const have = new Set((current.tasks || []).map((t) => t.id));
+  for (const t of tasks) {
+    if (!t.id || have.has(t.id)) throw new Error(`duplicate task id ${t.id || '(missing)'}`);
+    have.add(t.id);
+  }
+  return insertValues(text, 'tasks', tasks);
+}
+
+/**
+ * Append a fragment's tasks and new owner rules. A duplicate id is refused and the file is left untouched.
+ * Existing bytes stay. The return is the sha256 of the file after the append.
+ */
+export function mergeContract(root, fragmentPath, { owners } = {}) {
+  const fragment = loadFile(fragmentPath);
+  const tasks = (Array.isArray(fragment) ? fragment : fragment.tasks || []).map((t) => ({ ...t }));
+  const rules = Array.isArray(fragment) ? [] : (fragment.owner_rules || []).filter((r) => typeof r === 'string');
+  const map = ownerTable(owners);
+  for (const t of tasks) if (typeof t.owner === 'string' && map.has(t.owner)) t.owner = map.get(t.owner);
+  const file = contractPath(root);
+  const before = fs.readFileSync(file, 'utf8');
+  const current = JSON.parse(before);
+  const haveRules = new Set(current.owner_rules || []);
+  const freshRules = rules.filter((r) => !haveRules.has(r));
+  let next = appendTaskText(before, tasks);
+  if (freshRules.length) {
+    if (arrayEnd(next, 'owner_rules') == null) throw new Error('no owner_rules array');
+    next = insertValues(next, 'owner_rules', freshRules);
+  }
+  if (next !== before) fs.writeFileSync(file, next);
+  const bytes = fs.readFileSync(file);
+  return { sha256: sha256(bytes), added: tasks.map((t) => t.id), owner_rules: freshRules };
+}
+
+/** One line per requirement id: the tasks that name it, or MISSING. An id a task names that the file does not list is unknown. */
+export function coverageReport(root, requirementsPath, { contracts } = {}) {
+  const text = fs.readFileSync(requirementsPath, 'utf8');
+  const ids = [];
+  for (const line of text.split(/\r?\n/)) {
+    const m = line.match(/^- ([^:]+):/);
+    if (m) ids.push(m[1].trim());
+  }
+  const known = new Set(ids);
+  const covered = new Map(ids.map((id) => [id, []]));
+  const unknown = [];
+  const files = contracts && contracts.length ? contracts : [contractPath(root)];
+  for (const f of files) {
+    const c = loadFile(f);
+    for (const t of c.tasks || []) {
+      for (const req of t.requirements || []) {
+        if (known.has(req)) covered.get(req).push(t.id);
+        else unknown.push(`${req} unknown ${t.id}`);
+      }
+    }
+  }
+  const lines = ids.map((id) => {
+    const tasks = covered.get(id);
+    return tasks.length ? `${id} ${tasks.join(',')}` : `${id} MISSING`;
+  });
+  lines.push(...unknown);
+  const ok = !lines.some((l) => l.endsWith(' MISSING') || l.includes(' unknown '));
+  return { ok, lines };
+}

package/src/engine.mjs

@@ -8,6 +8,7 @@ import { scanForbidden } from './forbidden.mjs';
 import { parseClaims, checkClaim } from './claims.mjs';
 import { record, readLog, verifyChain } from './evidence.mjs';
 import * as RC from './cache.mjs';
+import { resolveIsolation, COVERAGE_LIMITS } from './isolate.mjs';
 
 export const KNOWN_LIMITS = [
   'Proofline runs on the same machine as the agent: an agent with shell access could edit .proofline/ or proofline.json. The hash chain makes edits detectable, contract weakening vs the base revision is flagged, and CI re-verifies from a clean checkout; protect proofline.json with CODEOWNERS/branch protection for a hard boundary.',
@@ -43,14 +44,23 @@ export function baseTrailer(root) {
 
 /**
  * Where the base revision comes from, first match wins: --base, the task's own `base` in the contract,
- * the base pinned when the task started (`proofline next`), a Proofline-Base trailer on HEAD, the default
- * (defaults.base, else <defaults.remote>/<defaults.branch>).
+ * the most recent base pinned when the task started (`proofline next`, and a later `next --base`),
+ * a Proofline-Base trailer on HEAD, the default (defaults.base, else <defaults.remote>/<defaults.branch>).
  */
+export function latestStart(root, taskId) {
+  const log = readLog(root);
+  for (let i = log.length - 1; i >= 0; i--) {
+    const e = log[i];
+    if (e.type === 'task_started' && e.data?.task === taskId && e.data.base) return e.data.base;
+  }
+  return null;
+}
+
 export function baseFor(root, c, t, explicit) {
   if (explicit) return { ref: explicit, source: '--base' };
   if (t.base) return { ref: t.base, source: 'contract' };
-  const started = readLog(root).find((e) => e.type === 'task_started' && e.data.task === t.id);
-  if (started?.data.base) return { ref: started.data.base, source: 'pinned at start' };
+  const started = latestStart(root, t.id);
+  if (started) return { ref: started, source: 'pinned at start' };
   const tr = baseTrailer(root);
   if (tr) return { ref: tr, source: 'commit trailer' };
   return { ref: C.defaultBase(c), source: 'default' };
@@ -74,6 +84,26 @@ export function taskBase(root, c, t, explicit) {
   return { ref, source, base, problems };
 }
 
+/** One line when the working contract differs from `explicit` (or the default base) and no marker approves it. */
+export function unapprovedContractChange(root, explicit) {
+  const c = C.load(root);
+  const ref = explicit || C.defaultBase(c);
+  const base = resolveBase(root, ref);
+  if (!base) return null;
+  const s = git(['show', `${base}:proofline.json`], root);
+  if (!s.ok) return null;
+  let baseContract;
+  try { baseContract = JSON.parse(s.out); } catch { return null; }
+  if (C.contractHash(baseContract) === C.contractHash(c)) return null;
+  let raw;
+  try { raw = fs.readFileSync(path.join(root, 'proofline.json')); } catch { return null; }
+  if (approvalMarker(root, raw).approved) return null;
+  const weak = C.weakenings(baseContract, c);
+  return weak.length
+    ? `contract weakened vs base (needs owner approval): ${weak.join('; ')}`
+    : 'contract bytes changed vs base (needs owner approval)';
+}
+
 const BASE_NEXT = 'gate against the revision the task started from: pass --base <rev> (for one commit, its parent), or start the task with `proofline next`, which pins the base. Do not pick a base that hides part of the work.';
 
 /** The "## Base" section of a brief: which base verify and gate will use, and whether they can. */
@@ -84,31 +114,39 @@ export function baseBrief(root, c, t, explicit) {
   return L.join('\n');
 }
 
-export function verifyTask(root, taskId, { claims, only, skipTypes = [], base: explicitBase, machine, fresh = false } = {}) {
+export function verifyTask(root, taskId, opts = {}) {
+  const { claims, only, skipTypes = [], base: explicitBase, machine, fresh = false } = opts;
   const c = C.load(root);
   const t = taskById(c, taskId);
+  const iso = resolveIsolation(c, opts);
   const errs = C.validate(c);
   // Base is pinned when the task starts, so pushing the work does not move the goalposts.
   const { ref: baseRef, source: baseSource, base, problems: baseProblems } = taskBase(root, c, t, explicitBase);
-  const ctx = { root, contract: c, task: t, base, changed: base ? changedFiles(root, base) : new Map(), measured: {}, machine, baseline: c.baseline?.metrics, tolerancePct: c.defaults?.regression_tolerance_pct, flakyReruns: c.defaults?.flaky_reruns ?? 1 };
+  const ctx = { root, contract: c, task: t, base, changed: base ? changedFiles(root, base) : new Map(), measured: {}, machine, baseline: c.baseline?.metrics, tolerancePct: c.defaults?.regression_tolerance_pct, flakyReruns: c.defaults?.flaky_reruns ?? 1, sandbox: iso.sandbox };
   const results = [];
   const reuse = RC.settings(c);
   for (const a of t.criteria) {
     if (only && !only.includes(a.id)) continue;
     if (skipTypes.includes(a.verifier.type)) continue;
     let r;
-    // Reuse (opt-in): a command or metric PASS recorded on this HEAD with a clean tree is not run again; --fresh runs it.
-    const k = reuse.on && RC.REUSABLE.includes(a.verifier.type) ? RC.keyFor(root, a.verifier, ctx) : null;
-    const hit = k && !fresh ? RC.lookup(root, k.key, reuse) : null;
-    if (hit) {
-      r = RC.reusedResult(hit);
-      if (a.verifier.type === 'metric') ctx.measured[a.verifier.name || a.verifier.key] = hit.data.evidence.measured;
+    const sandboxed = ['command', 'test_red_green', 'metric'].includes(a.verifier.type);
+    if (iso.block && sandboxed) {
+      r = { status: 'error', detail: iso.block };
     } else {
-      try { r = verifiers[a.verifier.type](a.verifier, ctx); } catch (e) { r = { status: 'error', detail: `verifier crashed: ${e.message}` }; }
-      // Only a PASS is stored, and only if the tree is still the one the check started on and the log is intact.
-      if (k && r.status === 'pass' && RC.keyFor(root, a.verifier, ctx)?.key === k.key && verifyChain(root).ok) RC.store(root, k, t.id, a, r);
+      // Reuse (opt-in): a command or metric PASS recorded on this HEAD with a clean tree is not run again; --fresh runs it.
+      const k = reuse.on && RC.REUSABLE.includes(a.verifier.type) ? RC.keyFor(root, a.verifier, ctx) : null;
+      const hit = k && !fresh ? RC.lookup(root, k.key, reuse) : null;
+      if (hit) {
+        r = RC.reusedResult(hit);
+        if (a.verifier.type === 'metric') ctx.measured[a.verifier.name || a.verifier.key] = hit.data.evidence.measured;
+      } else {
+        try { r = verifiers[a.verifier.type](a.verifier, ctx); } catch (e) { r = { status: 'error', detail: `verifier crashed: ${e.message}` }; }
+        // Only a PASS is stored, and only if the tree is still the one the check started on and the log is intact.
+        if (k && r.status === 'pass' && RC.keyFor(root, a.verifier, ctx)?.key === k.key && verifyChain(root).ok) RC.store(root, k, t.id, a, r);
+      }
     }
-    results.push({ id: a.id, statement: a.statement, mandatory: a.mandatory !== false, type: a.verifier.type, ...r });
+    const heuristic = a.verifier.type === 'grep' || a.verifier.type === 'wiring';
+    results.push({ id: a.id, statement: a.statement, mandatory: a.mandatory !== false, type: a.verifier.type, ...(heuristic ? { heuristic: true } : {}), ...r });
   }
   const rules = { ...C.DEFAULT_FORBIDDEN, ...(c.forbidden || {}) };
   const forbidden = scanForbidden(root, base, rules);
@@ -117,9 +155,11 @@ export function verifyTask(root, taskId, { claims, only, skipTypes = [], base: e
   const weak = C.weakenings(baseContract, c);
   // The forbidden scan skips proofline.json (it declares the deny-list); a contract change is reported here instead.
   let contractChange = !base ? 'unknown' : !baseContract ? 'added' : C.contractHash(baseContract) === C.contractHash(c) ? 'unchanged' : 'changed';
+  const fields = baseContract ? C.contractFieldChanges(baseContract, c) : [];
   let marker = null;
-  const approveWeakening = () => {
-    if (!weak.length) return false;
+  const hashChanged = contractChange === 'changed';
+  const approveChange = () => {
+    if (!hashChanged) return false;
     let raw = null;
     try { raw = fs.readFileSync(path.join(root, 'proofline.json')); } catch { raw = null; }
     const mark = approvalMarker(root, raw);
@@ -134,7 +174,13 @@ export function verifyTask(root, taskId, { claims, only, skipTypes = [], base: e
   if (errs.length) blocked.push(...errs.map((e) => `contract invalid: ${e}`));
   blocked.push(...baseProblems);
   if (!chain.ok) blocked.push(`evidence log tampered at entry ${chain.at}: ${chain.reason}`);
-  if (!approveWeakening()) for (const w of weak) blocked.push(`contract weakened vs base (needs owner approval): ${w}`);
+  if (hashChanged && !approveChange()) {
+    // One blocked line. weakenings() is the explanation, so a real weakening stays length 1.
+    if (weak.length) blocked.push(`contract weakened vs base (needs owner approval): ${weak.join('; ')}`);
+    else blocked.push('contract bytes changed vs base (needs owner approval)');
+  } else if (!hashChanged) {
+    for (const w of weak) blocked.push(`contract weakened vs base (needs owner approval): ${w}`);
+  }
   for (const r of results) {
     if (r.status === 'error') blocked.push(`${r.id}: could not run: ${r.detail}`);
     else if (r.status === 'blocked') blocked.push(`${r.id}: ${r.detail}`);
@@ -161,7 +207,7 @@ export function verifyTask(root, taskId, { claims, only, skipTypes = [], base: e
   const pushed = pr ? pr.status === 'pass'
     : !!hi.head && !git(['status', '--porcelain'], root).out.split('\n').some((l) => l && !l.includes('.proofline/')) && git(['rev-parse', '--verify', '--quiet', `refs/remotes/${tgt.remote}/${tgt.branch}^{commit}`], root).out === hi.head;
   const reused = results.filter((r) => r.reused).map((r) => ({ id: r.id, type: r.type, ts: r.reused.ts, entry: r.reused.entry }));
-  return { pushed, task: t.id, title: t.title, phase: t.phase, decision, base, base_ref: baseRef, base_source: baseSource, ...hi, contract_hash: C.contractHash(c), results, reuse: !reuse.on ? 'off' : fresh ? 'fresh' : 'on', reused, forbidden, weakenings: weak, contract_change: contractChange, marker, blocked, failing, measured: ctx.measured, claims: claimResults, changed: [...ctx.changed.keys()], ts: new Date().toISOString() };
+  return { isolated: iso.isolated, env_digest: iso.env_digest, heuristic: true, coverage_limits: COVERAGE_LIMITS, pushed, task: t.id, title: t.title, phase: t.phase, decision, base, base_ref: baseRef, base_source: baseSource, ...hi, contract_hash: C.contractHash(c), results, reuse: !reuse.on ? 'off' : fresh ? 'fresh' : 'on', reused, forbidden, weakenings: weak, contract_fields: fields, contract_change: contractChange, marker, blocked, failing, measured: ctx.measured, claims: claimResults, changed: [...ctx.changed.keys()], ts: new Date().toISOString() };
 }
 
 /** Corrective prompt tied to each failed criterion. */
@@ -199,7 +245,7 @@ export function steer(v, c) {
   }
   for (const f of v.forbidden) L.push(`${n++}. FORBIDDEN ${f.rule} in ${f.file}: ${f.line}\n   Why: ${f.why}. Next step: revert it and fix the underlying cause.`);
   for (const cr of v.claims.filter((x) => !x.ok)) L.push(`${n++}. CLAIM REJECTED: "${cr.claim}"\n   ${cr.issues.join('\n   ')}\n   Next step: report only what the evidence shows.`);
-  L.push('', 'STOP RULES:', ...t.stop_rules.map((s) => `- ${s}`), '- After fixing, call verify again. Max corrective cycles: ' + (c.defaults?.max_corrective_cycles ?? 3) + '; after that report BLOCKED with root cause, what you tried, what you need.');
+  L.push('', 'STOP RULES:', ...(Array.isArray(t.stop_rules) ? t.stop_rules : []).map((s) => `- ${s}`), '- After fixing, call verify again. Max corrective cycles: ' + (c.defaults?.max_corrective_cycles ?? 3) + '; after that report BLOCKED with root cause, what you tried, what you need.');
   return L.join('\n');
 }
 
@@ -277,26 +323,29 @@ export function phaseStatus(root, c = C.load(root)) {
  * The next task. With `owner`, only that owner's tasks and unowned ones are handed out, and the phase gate
  * applies to that lane; depends_on still waits on any owner's task.
  */
-export function next(root, { owner } = {}) {
+export function next(root, { owner, skip = [] } = {}) {
   const c = C.load(root);
   C.checkOwner(c, owner);
   const st = taskStatus(root, c);
+  const skipSet = new Set(skip);
+  // A skipped task has landed. It does not stay active, and it does not keep its phase or its dependents waiting.
+  const open = (t) => st[t.id].status !== 'verified' && !skipSet.has(t.id);
   const lane = c.tasks.filter((t) => C.inLane(t, owner));
   const order = (C.topo(c.tasks) || c.tasks).filter((t) => C.inLane(t, owner));
-  const firstOpenPhase = C.PHASES.find((p) => lane.some((t) => t.phase === p && st[t.id].status !== 'verified'));
+  const firstOpenPhase = C.PHASES.find((p) => lane.some((t) => t.phase === p && open(t)));
   if (!firstOpenPhase && owner) {
-    const others = c.tasks.filter((t) => !C.inLane(t, owner) && st[t.id].status !== 'verified').map((t) => `${t.id} (${t.owner})`);
+    const others = c.tasks.filter((t) => !C.inLane(t, owner) && st[t.id].status !== 'verified' && !skipSet.has(t.id)).map((t) => `${t.id} (${t.owner})`);
     return { done: true, owner, message: `Every task for ${owner} and every unowned task is verified.${others.length ? ` Open for other owners: ${others.join(', ')}.` : ' Run `proofline gate --all` before release.'}` };
   }
   if (!firstOpenPhase) return { done: true, message: 'All tasks verified. Run `proofline gate --all` before release.' };
   for (const t of order) {
-    if (st[t.id].status === 'verified') continue;
+    if (!open(t)) continue;
     if (t.phase !== firstOpenPhase) continue; // phase gate: earlier phases must be fully verified
-    const deps = (t.depends_on || []).filter((d) => st[d]?.status !== 'verified');
+    const deps = (t.depends_on || []).filter((d) => st[d]?.status !== 'verified' && !skipSet.has(d));
     if (deps.length) continue;
     return { done: false, task: t.id, phase: t.phase, status: st[t.id].status, brief: brief(c, t, st) };
   }
-  const waiting = order.filter((t) => st[t.id].status !== 'verified').map((t) => `${t.id} (waits on ${(t.depends_on || []).filter((d) => st[d]?.status !== 'verified').join(', ') || 'phase gate'})`);
+  const waiting = order.filter((t) => open(t)).map((t) => `${t.id} (waits on ${(t.depends_on || []).filter((d) => st[d]?.status !== 'verified' && !skipSet.has(d)).join(', ') || 'phase gate'})`);
   return { done: false, task: null, message: `No task${owner ? ` for ${owner}` : ''} is unblocked in phase ${firstOpenPhase}: ${waiting.join('; ')}` };
 }
 
@@ -324,6 +373,6 @@ export function brief(c, t, st = {}) {
     '## Mandatory loop', '1. Write the failing test(s) first and run them: paste the failing output.', '2. Implement the cause-level fix on the default path (wired in, default config).', `3. \`proofline verify ${t.id}\` → fix until PASS. Read the corrective instruction it prints.`, `4. Commit (one task per commit), push to ${pushTarget(c, t).remote} ${pushTarget(c, t).branch} with hooks on.`, `5. \`proofline gate ${t.id} --claims "<your report line>"\` and paste the report.`, '',
     '## Forbidden (detected automatically)', `- skip/only/todo in tests; raising timeouts; net removal of assertions; deleting tests; --no-verify; env bypasses (${(f.bypass_env || []).join(', ')}); lowering protected values (${(f.protected_values || []).map((p) => p.file).join(', ') || 'none configured'}); editing thresholds/commands/criteria in proofline.json.`, '',
     '## Owner rules', ...(c.owner_rules || []).map((r) => `- ${r}`), '',
-    '## Stop rules', ...t.stop_rules.map((s) => `- ${s}`), '',
+    '## Stop rules', ...(Array.isArray(t.stop_rules) ? t.stop_rules : []).map((s) => `- ${s}`), '',
     '## Report line (exact format)', `${t.id} | done/partial/not done/blocked | <commit> | <test names> | <metric=value vs target> | <what is missing>`].join('\n');
 }