@elalfner/relevo 0.0.0-stage → 0.3.0

package/scripts/lib/plan.mjs

@@ -0,0 +1,256 @@
+// Decides what `go` does with every candidate issue. Pure function: data in, decisions out.
+// Implements openspec/specs/go/spec.md (trigger, gates, queue, limits).
+//
+// Input:
+//   config     effective configuration (see config.mjs)
+//   issues     [{ number, title, body, state, labels: [names], assignees: [logins],
+//                 milestone: { number, due_on } | null,
+//                 ready_at: ISO | null,   // when the ready label was last applied
+//                 ready_by: login | null  // who applied it }]
+//   completed  issue numbers closed as completed (their pull request merged)
+//   running    issue numbers with an agent run in progress
+//   permissions  { login: 'admin' | 'maintain' | 'write' | 'triage' | 'read' | 'none' }
+//
+// Output: { decisions: [...], summary }, in the order the issues were processed.
+
+import { parseIssueBody } from './issue-parse.mjs';
+import { resolveLabelNames, transition } from './labels.mjs';
+import { branchName, changeId } from './branch.mjs';
+import { issueHash } from './issue-hash.mjs';
+import { resolvePlatform } from './platform-of.mjs';
+
+const MAY_TRIGGER = new Set(['admin', 'maintain', 'write']);
+// In a public repository only maintainers may start work: anyone with write access could otherwise start a
+// run from an issue written by a stranger.
+const MAY_TRIGGER_PUBLIC = new Set(['admin', 'maintain']);
+
+function byReadyAt(a, b) {
+  const ta = a.ready_at ? Date.parse(a.ready_at) : Number.POSITIVE_INFINITY;
+  const tb = b.ready_at ? Date.parse(b.ready_at) : Number.POSITIVE_INFINITY;
+  if (ta !== tb) return ta - tb;
+  return a.number - b.number;
+}
+
+/**
+ * Without a model credential in the repository the cloud cannot build: a `start` decision becomes `local`, which
+ * claims nothing and moves no label, and says to run `go` on a machine or to add the secret.
+ * Every other decision is returned as it is.
+ */
+export function withoutCredential(decisions, issues = []) {
+  return decisions.map((d) => {
+    if (d.action !== 'start') return d;
+    const issue = issues.find((i) => i.number === d.issue);
+    return {
+      issue: d.issue,
+      action: 'local',
+      reason: 'the repository has no model credential, so the cloud cannot build it',
+      labels: { add: [], remove: [] },
+      comment: { kind: 'cloud_not_configured', data: { issue: d.issue, actor: issue?.ready_by ?? d.assignee } },
+      assign: null,
+    };
+  });
+}
+
+export function planGo({ config, issues, completed = [], completedExternal = [], unreadable = [], repo = null, running = [], permissions = {} }) {
+  const names = resolveLabelNames(config.labels);
+  const has = (issue, key) => issue.labels.includes(names[key]);
+  const open = issues.filter((i) => i.state === 'open');
+  const completedSet = new Set(completed);
+  const completedExternalSet = new Set(completedExternal.map((r) => r.toLowerCase()));
+  const unreadableSet = new Set(unreadable.map((r) => r.toLowerCase()));
+  const linked = (config.links ?? []);
+  const own = repo ? repo.toLowerCase() : null;
+
+  const runningSet = new Set(running);
+  open.filter((i) => has(i, 'building')).forEach((i) => runningSet.add(i.number));
+  let freeSlots = Math.max(0, config.limits.concurrent_agents - runningSet.size);
+
+  const builtBy = new Map();
+  open.filter((i) => has(i, 'built')).forEach((i) => {
+    const owner = i.assignees[0];
+    if (owner) builtBy.set(owner, (builtBy.get(owner) ?? 0) + 1);
+  });
+
+  const candidates = open
+    .filter((i) => has(i, 'ready') || has(i, 'queued') || has(i, 'blocked'))
+    .sort(byReadyAt);
+
+  const decisions = [];
+
+  function decision(issue, action, reason, extra = {}) {
+    const labels = extra.labels ?? { add: [], remove: [] };
+    const out = {
+      issue: issue.number,
+      action,
+      reason,
+      labels,
+      comment: extra.comment ?? null,
+      assign: extra.assign ?? null,
+    };
+    if (action === 'start') Object.assign(out, extra.start);
+    decisions.push(out);
+  }
+
+  const moveTo = (issue, key) => transition(issue.labels, key, config.labels);
+  const dropReady = (issue) => ({ add: [], remove: issue.labels.filter((l) => l === names.ready) });
+
+  candidates.forEach((issue) => {
+    if (runningSet.has(issue.number)) {
+      decision(issue, 'skip', 'an agent is already running for this issue');
+      return;
+    }
+
+    const parsed = parseIssueBody(issue.body);
+    const assignee = issue.assignees[0] ?? null;
+    // The platform the issue is for. When it cannot be resolved that is a missing part of the specification.
+    const platform = resolvePlatform({ platforms: config.platforms, body: issue.body });
+    // Dependencies: the own repository in full is a local reference; a repository outside `links` is a missing part
+    // of the specification (nothing is read from it); a token that is not a reference is too.
+    const localDeps = [...parsed.dependsOn];
+    const externalDeps = [];
+    parsed.dependsOnExternal.forEach((d) => {
+      if (own && d.repo.toLowerCase() === own) {
+        if (!localDeps.includes(d.number)) localDeps.push(d.number);
+      } else externalDeps.push(d);
+    });
+    const linkProblems = [
+      ...parsed.dependsOnInvalid.map((t) => `a valid Depends-on reference instead of "${t}" (write #12, or owner/repo#12 for a linked repository)`),
+      ...[...new Set(externalDeps.map((d) => d.repo))].filter((r) => !linked.some((l) => l.toLowerCase() === r.toLowerCase()))
+        .map((r) => `a Depends-on that names ${r}, which is not in links of relevo.yml (${linked.length ? linked.join(', ') : 'no repository is linked'})`),
+    ];
+    // A question left open in the issue is an ambiguity, not a missing part: the writer has to decide, not just add text.
+    const openQuestion = parsed.openQuestions[0]?.replace(/^[-*+]\s+/, '').slice(0, 120);
+    const ambiguity = [
+      ...(openQuestion ? [`an answer to the open question "${openQuestion}"`] : []),
+      ...(parsed.needsClarification ? ['the text NEEDS CLARIFICATION resolved'] : []),
+    ];
+    const missing = [...parsed.missing, ...(platform.ok ? [] : [platform.message]), ...linkProblems, ...ambiguity];
+    const needsSpec = () => {
+      const specWriter = config.team.spec_writer ?? issue.ready_by;
+      decision(issue, 'needs-spec', `the spec is incomplete: ${missing.join('; ')}`, {
+        labels: moveTo(issue, 'needs-spec'),
+        assign: [specWriter],
+        comment: {
+          kind: 'needs_spec',
+          data: { spec_writer: specWriter, issue: issue.number, title: issue.title, missing: missing.join('; '), reason: ambiguity.length > 0 ? 'ambiguous' : 'missing' },
+        },
+      });
+    };
+
+    if (has(issue, 'ready')) {
+      // Trigger: only people with write access may start work.
+      const permission = issue.ready_by ? permissions[issue.ready_by] : undefined;
+      const isPublic = config.trust === 'public';
+      if (!issue.ready_by || !(isPublic ? MAY_TRIGGER_PUBLIC : MAY_TRIGGER).has(permission)) {
+        decision(issue, 'denied', isPublic ? 'the ready label was not applied by a maintainer (trust is public)' : 'the ready label was not applied by someone with write access', {
+          labels: dropReady(issue),
+          comment: { kind: isPublic ? 'ready_denied_maintainer' : 'ready_denied', data: { issue: issue.number, actor: issue.ready_by ?? undefined } },
+        });
+        return;
+      }
+      if (!issue.milestone) {
+        decision(issue, 'no-milestone', 'the issue has no milestone', {
+          labels: dropReady(issue),
+          comment: { kind: 'no_milestone', data: { issue: issue.number, actor: issue.ready_by } },
+        });
+        return;
+      }
+      if (!assignee) {
+        decision(issue, 'no-assignee', 'the issue has no assignee', {
+          labels: dropReady(issue),
+          comment: { kind: 'no_assignee', data: { issue: issue.number, actor: issue.ready_by } },
+        });
+        return;
+      }
+      // Gate 1: the spec. The agent never invents scenarios.
+      if (missing.length > 0) {
+        needsSpec();
+        return;
+      }
+    }
+
+    // An issue that was edited after it passed the gate can still name a repository that is not linked.
+    if (linkProblems.length > 0) {
+      needsSpec();
+      return;
+    }
+
+    // Gate 2: dependencies must be merged, in this repository or in a linked one.
+    const blockers = [
+      ...localDeps.filter((n) => !completedSet.has(n)).map((n) => `#${n}`),
+      ...externalDeps.filter((d) => !completedExternalSet.has(`${d.repo}#${d.number}`.toLowerCase()))
+        .map((d) => {
+          const ref = `${d.repo}#${d.number}`;
+          return unreadableSet.has(ref.toLowerCase()) ? `${ref} (could not be read: check the RELEVO_LINKS_TOKEN secret and that ${d.repo} is in links)` : ref;
+        }),
+    ];
+    if (blockers.length > 0) {
+      const entering = !has(issue, 'blocked');
+      decision(issue, 'block', `waiting for ${blockers.join(', ')}`, {
+        labels: moveTo(issue, 'blocked'),
+        comment: entering
+          ? { kind: 'blocked_notice', data: { issue: issue.number, title: issue.title, blockers: blockers.join(', ') } }
+          : null,
+      });
+      return;
+    }
+
+    // Gate 3: capacity of the assignee.
+    const built = assignee ? builtBy.get(assignee) ?? 0 : 0;
+    if (assignee && built >= config.limits.built_unreviewed_per_person) {
+      decision(issue, 'queue', `${assignee} already has ${built} built issues waiting for review`, {
+        labels: moveTo(issue, 'queued'),
+        comment: has(issue, 'queued')
+          ? null
+          : { kind: 'queued_capacity', data: { issue: issue.number, title: issue.title, assignee, built, limit: config.limits.built_unreviewed_per_person } },
+      });
+      return;
+    }
+
+    // Global limit on concurrent agents.
+    if (freeSlots <= 0) {
+      decision(issue, 'queue', 'the limit of concurrent agents is reached', {
+        labels: moveTo(issue, 'queued'),
+        comment: has(issue, 'queued') ? null : { kind: 'queued_agents', data: { issue: issue.number, title: issue.title } },
+      });
+      return;
+    }
+
+    // A queued or blocked issue was edited after it passed the gate: it goes back for the platform, not to a build.
+    if (!platform.ok) {
+      needsSpec();
+      return;
+    }
+
+    freeSlots -= 1;
+    runningSet.add(issue.number);
+    decision(issue, 'start', 'all gates passed', {
+      labels: moveTo(issue, 'building'),
+      start: {
+        branch: branchName(issue.number, issue.title),
+        change_id: changeId(issue.number, issue.title),
+        base: config.branches.base,
+        assignee,
+        title: issue.title,
+        qa_retries: config.qa.retries,
+        run_max_turns: config.limits.run_max_turns,
+        run_max_cost: config.limits.run_max_cost,
+        // The text the issue had when it was claimed: `go` checks it before it writes the specification.
+        issue_hash: issueHash({ title: issue.title, body: issue.body }),
+        // Dependency files the issue lets the change touch (see "Protected paths").
+        allow_paths: parsed.allowPaths,
+        // Which platform the build is for: the agents use its profile, its folder and its targets.
+        platform: platform.name,
+        stack: platform.entry.stack,
+        path: platform.entry.path,
+        targets: platform.entry.targets,
+      },
+    });
+  });
+
+  const summary = {};
+  decisions.forEach((d) => {
+    summary[d.action] = (summary[d.action] ?? 0) + 1;
+  });
+  return { decisions, summary };
+}

package/scripts/lib/platform-of.mjs

@@ -0,0 +1,32 @@
+// Which platform an issue belongs to. Implements "An issue belongs to one platform" of the platforms specification.
+//
+// One pure function, used by the planner, the issue check, `platform-of.mjs` and the tests, so that they cannot
+// disagree about what an issue says.
+
+import { parseIssueBody } from './issue-parse.mjs';
+
+const names = (platforms) => Object.keys(platforms).join(', ');
+
+/**
+ * `platforms` is the validated registry of relevo.yml ({ name: { stack, path, targets } }); `body` is the issue text.
+ * Returns { ok: true, name, entry } or { ok: false, reason: 'missing' | 'unknown' | 'conflict', message }.
+ * With one platform the line is optional; with several it is required.
+ */
+export function resolvePlatform({ platforms, body }) {
+  const registry = platforms ?? {};
+  const known = Object.keys(registry);
+  const written = [...new Set(parseIssueBody(body).platform)];
+
+  if (written.length > 1) {
+    return { ok: false, reason: 'conflict', message: `the issue names two platforms (${written.join(', ')}); an issue belongs to one, so split it into one issue per platform with Depends-on` };
+  }
+  if (written.length === 1) {
+    const name = written[0];
+    if (!Object.hasOwn(registry, name)) {
+      return { ok: false, reason: 'unknown', message: `the issue says Platform: ${name}, which is not a platform of relevo.yml (${names(registry)})` };
+    }
+    return { ok: true, name, entry: registry[name] };
+  }
+  if (known.length === 1) return { ok: true, name: known[0], entry: registry[known[0]] };
+  return { ok: false, reason: 'missing', message: `Platform: line naming one of the platforms of relevo.yml (${names(registry)})` };
+}

package/scripts/lib/platform-scope.mjs

@@ -0,0 +1,32 @@
+// An issue changes only its own platform. Implements "An issue changes only its platform" of the go specification.
+//
+// A commit of an unattended run may touch the folder of the platform of the issue, the specification of the change
+// itself, GLOSSARY.md and docs/adr/ (the documentation the issue carries), and any path the issue lists in its
+// `Allow-paths:` line. A platform whose folder is `.` is not restricted.
+
+import { matchesGlob } from './protected-paths.mjs';
+
+const clean = (path) => String(path ?? '').trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '').replace(/\/+$/, '');
+
+/** Paths that every platform may change, whatever its folder. */
+function isShared(path, change) {
+  if (path === 'GLOSSARY.md' || path.startsWith('docs/adr/')) return true;
+  return Boolean(change) && (path === `openspec/changes/${change}` || path.startsWith(`openspec/changes/${change}/`));
+}
+
+/**
+ * The paths outside the platform. `within` is the platform folder (`.` or empty: no restriction), `change` is the
+ * change id (its specification folder is always allowed), `allow` the globs of the issue's `Allow-paths:` line.
+ * Returns violations like those of `checkProtected`: [{ path, tier: 'scope', rule: within }].
+ */
+export function checkScope(paths, { within = '.', change = null, allow = [] } = {}) {
+  const folder = clean(within);
+  if (folder === '' || folder === '.') return { ok: true, violations: [] };
+  const violations = [];
+  [...new Set((paths ?? []).map(clean).filter(Boolean))].forEach((path) => {
+    const inside = path === folder || path.startsWith(`${folder}/`);
+    if (inside || isShared(path, change) || allow.some((pattern) => matchesGlob(path, pattern))) return;
+    violations.push({ path, tier: 'scope', rule: folder });
+  });
+  return { ok: violations.length === 0, violations };
+}

package/scripts/lib/platforms.mjs

@@ -0,0 +1,90 @@
+// The platform registry of relevo.yml. Implements "Platforms are declared in a registry" of the platforms specification.
+//
+// `platforms` is a map of name to { stack, path, targets, checks }. The legacy `platform: flutter-android` is the
+// same as one platform with stack `flutter`, path `.` and targets `[android]`.
+
+export const LEGACY_PLATFORMS = {
+  'flutter-android': { stack: 'flutter', path: '.', targets: ['android'] },
+};
+
+const NAME_RE = /^[a-z][a-z0-9-]*$/;
+const STACK_RE = /^[a-z][a-z0-9-]*$/;
+const ENTRY_KEYS = new Set(['stack', 'path', 'targets', 'checks']);
+
+const isMap = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** A relative path inside the repository: not absolute, no `..` segment. */
+export function isRepoRelativePath(value) {
+  if (typeof value !== 'string' || value.trim() === '') return false;
+  const p = value.replace(/\\/g, '/');
+  return !p.startsWith('/') && !/^[A-Za-z]:/.test(p) && !p.split('/').includes('..');
+}
+
+/**
+ * Turn the `platform` / `platforms` settings of a parsed relevo.yml into one map.
+ *   raw            { platform, platforms } as written (either may be undefined)
+ *   knownTargets   optional function (stack) -> list of targets the stack defines, or null when unknown;
+ *                  when given, targets are checked against it
+ * Returns { platforms, errors }; `platforms` is always a map (the legacy default when nothing is set).
+ */
+export function normalizePlatforms({ platform, platforms } = {}, { knownTargets = null } = {}) {
+  const errors = [];
+  const has = (v) => v !== undefined && v !== null;
+
+  if (has(platform) && has(platforms)) {
+    errors.push({ path: 'platforms', message: 'set either platform (the legacy shortcut) or platforms, not both: keep only platforms' });
+    return { platforms: {}, errors };
+  }
+  if (!has(platforms)) {
+    const key = has(platform) ? platform : 'flutter-android';
+    const legacy = LEGACY_PLATFORMS[key];
+    if (!legacy) {
+      errors.push({ path: 'platform', message: `platform has invalid value ${JSON.stringify(key)}; allowed values: ${Object.keys(LEGACY_PLATFORMS).map((k) => `"${k}"`).join(', ')}, or use platforms` });
+      return { platforms: {}, errors };
+    }
+    return { platforms: { app: structuredClone(legacy) }, errors };
+  }
+  if (!isMap(platforms) || Object.keys(platforms).length === 0) {
+    errors.push({ path: 'platforms', message: 'platforms must be a map of platform name to its settings, with at least one entry' });
+    return { platforms: {}, errors };
+  }
+
+  const out = {};
+  Object.entries(platforms).forEach(([name, entry]) => {
+    const at = `platforms.${name}`;
+    if (!NAME_RE.test(name)) errors.push({ path: at, message: `${at}: the platform name must be lowercase letters, digits and hyphens` });
+    if (!isMap(entry)) {
+      errors.push({ path: at, message: `${at} must be a map with at least a stack` });
+      return;
+    }
+    Object.keys(entry).forEach((key) => {
+      if (!ENTRY_KEYS.has(key)) errors.push({ path: `${at}.${key}`, message: `unknown setting "${at}.${key}"; allowed: ${[...ENTRY_KEYS].join(', ')}` });
+    });
+    if (typeof entry.stack !== 'string' || !STACK_RE.test(entry.stack)) {
+      errors.push({ path: `${at}.stack`, message: `${at}.stack must name a stack, for example "flutter" (got ${JSON.stringify(entry.stack)})` });
+    }
+    const path = has(entry.path) ? entry.path : '.';
+    if (!isRepoRelativePath(path)) errors.push({ path: `${at}.path`, message: `${at}.path must be a folder inside the repository, without a leading "/" or ".." (got ${JSON.stringify(path)})` });
+
+    let targets = [];
+    if (has(entry.targets)) {
+      if (!Array.isArray(entry.targets) || entry.targets.some((t) => typeof t !== 'string' || t.trim() === '')) {
+        errors.push({ path: `${at}.targets`, message: `${at}.targets must be a list of target names` });
+      } else {
+        targets = [...new Set(entry.targets)];
+        const known = typeof entry.stack === 'string' && knownTargets ? knownTargets(entry.stack) : null;
+        if (known) {
+          targets.filter((t) => !known.includes(t)).forEach((t) => {
+            errors.push({ path: `${at}.targets`, message: `${at}.targets has unknown target "${t}"; the stack "${entry.stack}" defines: ${known.length ? known.join(', ') : 'no targets'}` });
+          });
+        }
+      }
+    }
+    const checks = has(entry.checks) ? entry.checks : {};
+    if (!isMap(checks) || Object.values(checks).some((v) => typeof v !== 'string' || v.trim() === '')) {
+      errors.push({ path: `${at}.checks`, message: `${at}.checks must map a command name to the command that replaces it` });
+    }
+    out[name] = { stack: entry.stack, path: typeof path === 'string' ? path.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '') || '.' : '.', targets, ...(isMap(checks) && Object.keys(checks).length ? { checks } : {}) };
+  });
+  return { platforms: out, errors };
+}

package/scripts/lib/preflight.mjs

@@ -0,0 +1,71 @@
+// The checks `go` makes before it claims work or creates a branch, in one place.
+// Implements "Go checks its environment before changing anything" of the go specification.
+//
+// Everything outside the process is injected, so the checks can be tested without OpenSpec, git or GitHub:
+//   readConfig() -> the text of relevo.yml (throws when it cannot be read)
+//   run(command, args) -> { status, stdout, stderr }
+
+import { loadConfig } from './config.mjs';
+
+export const CHECKS = ['config', 'openspec', 'openspec-root', 'clean-tree', 'gh'];
+export const DEFAULT_CHECKS = ['config', 'openspec', 'openspec-root', 'clean-tree'];
+
+const pass = (check) => ({ check, ok: true });
+const fail = (check, message, fix) => ({ check, ok: false, message, fix });
+
+function checkConfig({ readConfig }) {
+  let text;
+  try {
+    text = readConfig();
+  } catch {
+    return fail('config', 'relevo.yml was not found', 'run /relevo:init to create it');
+  }
+  const loaded = loadConfig(text);
+  if (loaded.ok) return pass('config');
+  return fail('config', `relevo.yml is not valid:\n${loaded.errors.map((e) => `  - ${e.message}`).join('\n')}`, 'fix it, and check it with node scripts/validate-config.mjs relevo.yml');
+}
+
+function checkOpenspec({ run }) {
+  const r = run('openspec', ['--version']);
+  return r.status === 0 ? pass('openspec') : fail('openspec', 'the OpenSpec command line does not run', 'run /relevo:doctor');
+}
+
+function checkOpenspecRoot({ run }) {
+  const r = run('openspec', ['list', '--json']);
+  let root = null;
+  try {
+    root = JSON.parse(r.stdout || '{}').root ?? null;
+  } catch {
+    root = null;
+  }
+  // `root: null` is OpenSpec's own answer for "no openspec/ directory here"; it also exits with an error.
+  return root && typeof root === 'object' ? pass('openspec-root') : fail('openspec-root', 'OpenSpec finds no root for this repository', 'run /relevo:doctor (and openspec init if the project is not set up)');
+}
+
+function checkCleanTree({ run }) {
+  const r = run('git', ['status', '--porcelain']);
+  if (r.status !== 0) return fail('clean-tree', 'git could not read the working tree', 'run it inside the repository');
+  const lines = r.stdout.split('\n').filter(Boolean);
+  if (lines.length === 0) return pass('clean-tree');
+  const shown = lines.slice(0, 5).map((l) => `  ${l}`).join('\n');
+  return fail('clean-tree', `the working tree has uncommitted changes:\n${shown}${lines.length > 5 ? `\n  ... and ${lines.length - 5} more` : ''}`, 'commit or stash them first');
+}
+
+function checkGh({ run }) {
+  return run('gh', ['auth', 'status']).status === 0 ? pass('gh') : fail('gh', 'the GitHub command line is not signed in', 'run gh auth login');
+}
+
+const IMPLEMENTATION = { config: checkConfig, openspec: checkOpenspec, 'openspec-root': checkOpenspecRoot, 'clean-tree': checkCleanTree, gh: checkGh };
+
+/** Run the named checks, in order. Returns { ok, results: [{ check, ok, message?, fix? }] }. */
+export function runPreflight({ checks = DEFAULT_CHECKS, readConfig, run }) {
+  const unknown = checks.filter((c) => !IMPLEMENTATION[c]);
+  if (unknown.length > 0) throw new Error(`unknown check "${unknown[0]}": expected one of ${CHECKS.join(', ')}`);
+  const results = checks.map((check) => IMPLEMENTATION[check]({ readConfig, run }));
+  return { ok: results.every((r) => r.ok), results };
+}
+
+export function formatPreflight({ ok, results }) {
+  if (ok) return `preflight ok (${results.map((r) => r.check).join(', ')})`;
+  return results.filter((r) => !r.ok).map((r) => `${r.check}: ${r.message}\n  fix: ${r.fix}`).join('\n');
+}

package/scripts/lib/protected-paths.mjs

@@ -0,0 +1,102 @@
+// Paths the unattended agent must not change. Implements "Protected paths" of the security specification.
+//
+// Two tiers:
+//   hard  never allowed, whatever the issue says: workflows, the Relevo configuration, the folders of skills and
+//         the file with the project rules (a defect is fixed in the code, not by rewriting the rule).
+//   soft  dependency manifests and lock files: allowed only when the issue lists them in an `Allow-paths:` line.
+
+export const HARD_PATTERNS = ['.github/', 'relevo.yml', '.relevo/', '.claude/skills/', '.agents/skills/', 'skills-lock.json'];
+
+export const SOFT_FILES = [
+  'pubspec.yaml', 'pubspec.lock',
+  'package.json', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock',
+  'composer.json', 'composer.lock',
+  'Gemfile', 'Gemfile.lock',
+];
+
+const clean = (path) => String(path ?? '').trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+
+const escapeRe = (s) => s.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+
+/** Convert a glob (`*`, `**`, `?`) to a regular expression. A pattern without `/` matches at any depth, like .gitignore. */
+function globToRegExp(pattern) {
+  let p = clean(pattern);
+  if (p.endsWith('/')) p += '**';
+  const anyDepth = !p.includes('/');
+  let re = '';
+  for (let i = 0; i < p.length; i += 1) {
+    const c = p[i];
+    if (c === '*' && p[i + 1] === '*') {
+      i += 1;
+      if (p[i + 1] === '/') {
+        i += 1;
+        re += '(?:.*/)?';
+      } else re += '.*';
+    } else if (c === '*') re += '[^/]*';
+    else if (c === '?') re += '[^/]';
+    else re += escapeRe(c);
+  }
+  return new RegExp(`^${anyDepth ? '(?:.*/)?' : ''}${re}$`);
+}
+
+/** Does `path` match `pattern`? */
+export function matchesGlob(path, pattern) {
+  return globToRegExp(pattern).test(clean(path));
+}
+
+/** The rules file setting is one name or a list (`qa.rules_from`); both give a list of cleaned names. */
+const ruleFiles = (rulesFile) => [].concat(rulesFile ?? []).filter(Boolean).map(clean);
+
+function hardPatterns(rulesFile) {
+  return [...HARD_PATTERNS, ...ruleFiles(rulesFile)];
+}
+
+// Hard patterns are anchored at the root of the repository; `relevo.yml` and the rules file are exact files.
+const matchesHard = (path, pattern) => {
+  const p = clean(path);
+  const rule = clean(pattern);
+  return rule.endsWith('/') ? p.startsWith(rule) : p === rule;
+};
+
+/** The hard rule a path breaks, or null. */
+export function hardRule(path, { rulesFile = null } = {}) {
+  return hardPatterns(rulesFile).find((pattern) => matchesHard(path, pattern)) ?? null;
+}
+
+/** Is the file a dependency manifest or lock file (soft tier)? */
+export const isSoftProtected = (path) => SOFT_FILES.includes(clean(path).split('/').pop());
+
+/**
+ * Check the paths of a diff. `allow` is the list of globs from the issue's `Allow-paths:` line.
+ * Returns { ok, violations: [{ path, tier: 'hard' | 'soft', rule }] }.
+ */
+export function checkProtected(paths, { allow = [], rulesFile = null } = {}) {
+  const violations = [];
+  [...new Set((paths ?? []).map(clean).filter(Boolean))].forEach((path) => {
+    const hard = hardRule(path, { rulesFile });
+    if (hard) {
+      violations.push({ path, tier: 'hard', rule: hard });
+      return;
+    }
+    if (isSoftProtected(path) && !allow.some((pattern) => matchesGlob(path, pattern))) {
+      violations.push({ path, tier: 'soft', rule: clean(path).split('/').pop() });
+    }
+  });
+  return { ok: violations.length === 0, violations };
+}
+
+/** Entries of an `Allow-paths:` list that name (or would cover) a hard-protected path: they can never be allowed. */
+export function hardPathsInAllow(allow, { rulesFile = null } = {}) {
+  const probes = [...HARD_PATTERNS.map((pattern) => (pattern.endsWith('/') ? `${pattern}x` : pattern)), ...ruleFiles(rulesFile)].filter(Boolean);
+  return (allow ?? []).filter((entry) => hardRule(entry, { rulesFile }) || probes.some((probe) => matchesGlob(probe, entry)));
+}
+
+export function formatViolations(violations) {
+  return violations
+    .map((v) => {
+      if (v.tier === 'hard') return `${v.path}  protected path (${v.rule}): it is never changed by an unattended run`;
+      if (v.tier === 'scope') return `${v.path}  outside the platform (${v.rule}): an issue changes only its platform; list the path in an Allow-paths: line to allow it`;
+      return `${v.path}  dependency file: the issue must list it in an Allow-paths: line`;
+    })
+    .join('\n');
+}

package/scripts/lib/requeue.mjs

@@ -0,0 +1,23 @@
+// Queue re-evaluation. Implements "Queue re-evaluation" of openspec/specs/go/spec.md.
+// The planner decides; this module only says which issues may be handed to a build run now.
+
+/**
+ * The decisions the queue is responsible for: those about issues that are already waiting (`queued` or `blocked`).
+ * An issue that has just been marked `ready` belongs to the `go` workflow that the label itself started; if the
+ * queue acted on it too, both would apply the same decision (a duplicated comment) or dispatch the same build.
+ */
+export function ownedByQueue(decisions, issues, names) {
+  const waiting = new Set(issues.filter((i) => i.labels.includes(names.queued) || i.labels.includes(names.blocked)).map((i) => i.number));
+  return decisions.filter((d) => waiting.has(d.issue));
+}
+
+/** Issue numbers whose decision is `start`, oldest first (the planner already sorted them). */
+export function startable(decisions) {
+  return decisions.filter((d) => d.action === 'start').map((d) => d.issue);
+}
+
+/** The unattended runs to dispatch: one per startable issue, never more than the free slots. */
+export function toDispatch(decisions, { alreadyRunning = 0, limit }) {
+  const free = Math.max(0, limit - alreadyRunning);
+  return startable(decisions).slice(0, free);
+}

package/scripts/lib/review-adapters.mjs

@@ -0,0 +1,37 @@
+// How `review` gets a log and captures for a platform and a target, and whether the agent may drive it.
+// Implements "The review picks its adapter from the platform and the target" of openspec/specs/review/spec.md.
+
+const DEFAULT_TARGET = { flutter: 'android', vue: 'web' };
+
+const ADAPTERS = {
+  'flutter/android': { kind: 'device', log: 'adb logcat', capture: 'adb screencap', driver: 'flutter_driver', needs: ['adb'] },
+  'flutter/web': { kind: 'browser', log: 'the browser runner', capture: 'the browser runner', driver: 'flutter_driver', needs: ['a browser'] },
+  'vue/web': { kind: 'browser', log: 'the browser runner', capture: 'the browser runner', driver: 'playwright', needs: ['playwright'] },
+};
+
+const NOT_AVAILABLE = {
+  'flutter/ios': 'the review of iOS is not available yet: it needs a macOS machine with a simulator (xcrun), and nothing in Relevo has been run there',
+};
+
+/** The target a platform is reviewed on when none is given: its first target, or the usual one of its stack. */
+export function targetOf({ stack, targets = [] }) {
+  return targets[0] ?? DEFAULT_TARGET[stack] ?? null;
+}
+
+/**
+ * Returns { supported, stack, target, kind, log, capture, driver, needs, reason }.
+ * `reason` says why a combination is not supported.
+ */
+export function adapterFor({ stack, target }) {
+  const key = `${stack}/${target}`;
+  if (ADAPTERS[key]) return { supported: true, stack, target, ...ADAPTERS[key], reason: null };
+  return {
+    supported: false, stack, target, kind: null, log: null, capture: null, driver: null, needs: [],
+    reason: NOT_AVAILABLE[key] ?? (target ? `there is no review adapter for the stack "${stack}" on the target "${target}"` : `the platform of stack "${stack}" names no target to review`),
+  };
+}
+
+/** Whether a review of this adapter can run at all with the given autopilot mode: a browser has no manual way. */
+export function needsAutopilot(adapter) {
+  return adapter.supported && adapter.kind === 'browser';
+}