@elalfner/relevo 0.0.0-stage → 0.3.1

package/scripts/lib/messages.mjs

@@ -0,0 +1,341 @@
+// Hand-off messages. Implements the hand-off requirements of
+// openspec/specs/issue-lifecycle/spec.md.
+//
+// A line is dropped when any of its {{placeholders}} has no value, so optional
+// parts (riskiest area, due time, log link) simply disappear when unknown.
+// Long values are shortened: long logs are linked, never embedded.
+
+import { shortHash } from './issue-hash.mjs';
+import { pickLanguage, SUPPORTED_LANGUAGES } from './language.mjs';
+import { nextStep, nextStepPrefix } from './next-step.mjs';
+
+// Kept here as well so that existing imports keep working.
+export { pickLanguage, SUPPORTED_LANGUAGES };
+
+const MAX_VALUE_LENGTH = 400;
+
+const REQUIRED = {
+  built: ['assignee', 'issue', 'title', 'tasks_done', 'tasks_total', 'branch', 'scenarios'],
+  qa_failed: ['assignee', 'issue', 'title', 'finding', 'branch'],
+  needs_spec: ['spec_writer', 'issue', 'title', 'missing'],
+  changes_requested: ['author', 'issue', 'reviewer', 'summary'],
+  needs_reviewer: ['spec_writer', 'issue', 'title', 'pr'],
+  approved: ['recipient', 'issue', 'reviewer'],
+  review_reminder: ['reviewer', 'issue', 'pr', 'hours'],
+  review_escalation: ['spec_writer', 'issue', 'pr', 'reviewer', 'hours'],
+  no_milestone: ['actor', 'issue'],
+  cloud_not_configured: ['actor', 'issue'],
+  no_assignee: ['actor', 'issue'],
+  ready_denied: ['issue'],
+  ready_denied_maintainer: ['issue'],
+  blocked_notice: ['issue', 'title', 'blockers'],
+  queued_capacity: ['issue', 'title', 'assignee', 'built', 'limit'],
+  queued_agents: ['issue', 'title'],
+  fix_done: ['issue', 'title', 'summary', 'qa', 'commit', 'iteration'],
+};
+
+// The lifecycle state whose next step each message shows (see next-step.mjs, the only place that knows the commands).
+const STATE_OF = {
+  built: 'built',
+  qa_failed: 'qa-failed',
+  needs_spec: 'needs-spec',
+  changes_requested: 'changes-requested',
+  approved: 'pr-open',
+};
+
+const CATALOG = {
+  en: {
+    built: [
+      '@{{assignee}} #{{issue}} "{{title}}" is built ✅',
+      '',
+      'What happened: {{tasks_done}} of {{tasks_total}} tasks done, QA passed.',
+      'Branch: {{branch}}',
+      'Built from the issue text: {{issue_hash_short}}',
+      'What to test: {{scenarios}} scenarios (checklist below)',
+      'Riskiest area, check it first: {{risk}}',
+      'Your next step: {{command}}',
+      'Expected by: {{due}}',
+      '',
+      '{{checklist}}',
+    ],
+    qa_failed: [
+      '@{{assignee}} #{{issue}} "{{title}}" failed QA ❌',
+      '',
+      'What happened: QA still rejected it after the retries{{reason_suffix}}.',
+      'Finding: {{finding}}{{location_suffix}}',
+      '{{branch_line}}',
+      'Full QA report: {{log_url}}',
+      '{{next_line}}',
+    ],
+    needs_spec: [
+      '@{{spec_writer}} #{{issue}} "{{title}}" is back with you: the spec needs work',
+      '',
+      'What is missing: {{missing}}',
+      '{{next_line}}',
+    ],
+    changes_requested: [
+      '@{{author}} #{{issue}}: {{reviewer}} requested changes',
+      '',
+      'Summary: {{summary}}',
+      'Full review: {{pr}}',
+      'Your next step: {{command}}',
+    ],
+    approved: [
+      '@{{recipient}} #{{issue}} was approved by {{reviewer}} ✅',
+      '',
+      'Pull request: {{pr}}',
+      'Your next step: {{command}}',
+    ],
+    needs_reviewer: [
+      '@{{spec_writer}} #{{issue}} "{{title}}" has no available reviewer',
+      '',
+      'Pull request: {{pr}}',
+      'Your next step: assign a reviewer or ask someone to take it.',
+    ],
+    review_reminder: [
+      '@{{reviewer}} reminder: #{{issue}} has been waiting for your review for {{hours}} hours',
+      '',
+      'Pull request: {{pr}}',
+    ],
+    review_escalation: [
+      '@{{spec_writer}} #{{issue}} has waited {{hours}} hours without a review from @{{reviewer}}',
+      '',
+      'Pull request: {{pr}}',
+      'Your next step: decide who reviews it.',
+    ],
+    cloud_not_configured: [
+      '#{{issue}} is ready, but the cloud cannot build it: this repository has no model credential',
+      '',
+      '@{{actor}} your next step: run `/relevo:go {{issue}}` on your machine, or add the secret ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN so that the cloud can build it. The issue stays ready.',
+    ],
+    no_milestone: [
+      '#{{issue}} was not started: it has no milestone',
+      '',
+      '@{{actor}} your next step: add the issue to a milestone and label it ready again.',
+    ],
+    no_assignee: [
+      '#{{issue}} was not started: it has no assignee',
+      '',
+      '@{{actor}} your next step: assign the issue to the person who will review it and label it ready again.',
+    ],
+    ready_denied: [
+      '#{{issue}} was not started: only people with write access can mark an issue ready, so the label was removed',
+      'Applied by: @{{actor}}',
+    ],
+    ready_denied_maintainer: [
+      '#{{issue}} was not started: this repository is public, so only maintainers can mark an issue ready, and the label was removed',
+      'Applied by: @{{actor}}',
+    ],
+    blocked_notice: [
+      '#{{issue}} "{{title}}" is blocked',
+      '',
+      'Waiting for {{blockers}} to be merged. It starts automatically when they are.',
+    ],
+    queued_capacity: [
+      '#{{issue}} "{{title}}" is queued',
+      '',
+      '{{assignee}} already has {{built}} built issues waiting for review (the limit is {{limit}}). It starts automatically when one of them is reviewed.',
+    ],
+    queued_agents: [
+      '#{{issue}} "{{title}}" is queued',
+      '',
+      'The limit of concurrent agents is reached. It starts automatically when a run finishes.',
+    ],
+    fix_done: [
+      '#{{issue}} "{{title}}" fixed (iteration {{iteration}})',
+      '',
+      'What changed: {{summary}}',
+      'QA: {{qa}}',
+      'Commit: {{commit}}',
+      '@{{recipient}} {{ask}}',
+    ],
+  },
+  es: {
+    built: [
+      '@{{assignee}} #{{issue}} "{{title}}" está construida ✅',
+      '',
+      'Qué pasó: {{tasks_done}} de {{tasks_total}} tareas hechas, QA aprobado.',
+      'Rama: {{branch}}',
+      'Construida con el texto del issue: {{issue_hash_short}}',
+      'Qué probar: {{scenarios}} escenarios (checklist abajo)',
+      'Zona más riesgosa, revísala primero: {{risk}}',
+      'Tu siguiente paso: {{command}}',
+      'Esperada para: {{due}}',
+      '',
+      '{{checklist}}',
+    ],
+    qa_failed: [
+      '@{{assignee}} #{{issue}} "{{title}}" no pasó QA ❌',
+      '',
+      'Qué pasó: QA la rechazó otra vez tras los reintentos{{reason_suffix}}.',
+      'Hallazgo: {{finding}}{{location_suffix}}',
+      '{{branch_line}}',
+      'Reporte completo de QA: {{log_url}}',
+      '{{next_line}}',
+    ],
+    needs_spec: [
+      '@{{spec_writer}} #{{issue}} "{{title}}" regresa contigo: la spec necesita trabajo',
+      '',
+      'Qué falta: {{missing}}',
+      '{{next_line}}',
+    ],
+    changes_requested: [
+      '@{{author}} #{{issue}}: {{reviewer}} pidió cambios',
+      '',
+      'Resumen: {{summary}}',
+      'Revisión completa: {{pr}}',
+      'Tu siguiente paso: {{command}}',
+    ],
+    approved: [
+      '@{{recipient}} #{{issue}} fue aprobada por {{reviewer}} ✅',
+      '',
+      'Pull request: {{pr}}',
+      'Tu siguiente paso: {{command}}',
+    ],
+    needs_reviewer: [
+      '@{{spec_writer}} #{{issue}} "{{title}}" no tiene revisor disponible',
+      '',
+      'Pull request: {{pr}}',
+      'Tu siguiente paso: asigna un revisor o pide que alguien lo tome.',
+    ],
+    review_reminder: [
+      '@{{reviewer}} recordatorio: #{{issue}} lleva {{hours}} horas esperando tu revisión',
+      '',
+      'Pull request: {{pr}}',
+    ],
+    review_escalation: [
+      '@{{spec_writer}} #{{issue}} lleva {{hours}} horas sin revisión de @{{reviewer}}',
+      '',
+      'Pull request: {{pr}}',
+      'Tu siguiente paso: decide quién lo revisa.',
+    ],
+    cloud_not_configured: [
+      '#{{issue}} está listo, pero la nube no puede construirlo: este repositorio no tiene una credencial del modelo',
+      '',
+      '@{{actor}} tu siguiente paso: ejecuta `/relevo:go {{issue}}` en tu máquina, o agrega el secreto ANTHROPIC_API_KEY o CLAUDE_CODE_OAUTH_TOKEN para que la nube pueda construirlo. El issue sigue en ready.',
+    ],
+    no_milestone: [
+      '#{{issue}} no se inició: no tiene milestone',
+      '',
+      '@{{actor}} tu siguiente paso: agrega el issue a un milestone y márcalo como ready otra vez.',
+    ],
+    no_assignee: [
+      '#{{issue}} no se inició: no tiene responsable',
+      '',
+      '@{{actor}} tu siguiente paso: asigna el issue a quien lo va a revisar y márcalo como ready otra vez.',
+    ],
+    ready_denied: [
+      '#{{issue}} no se inició: solo quienes tienen acceso de escritura pueden marcar un issue como ready, así que se quitó la etiqueta',
+      'Aplicada por: @{{actor}}',
+    ],
+    ready_denied_maintainer: [
+      '#{{issue}} no se inició: este repositorio es público, así que solo quienes mantienen el proyecto pueden marcar un issue como ready, y se quitó la etiqueta',
+      'Aplicada por: @{{actor}}',
+    ],
+    blocked_notice: [
+      '#{{issue}} "{{title}}" está bloqueado',
+      '',
+      'Espera a que se fusionen {{blockers}}. Empieza solo cuando lo estén.',
+    ],
+    queued_capacity: [
+      '#{{issue}} "{{title}}" está en cola',
+      '',
+      '{{assignee}} ya tiene {{built}} issues construidos esperando revisión (el límite es {{limit}}). Empieza solo cuando se revise uno.',
+    ],
+    queued_agents: [
+      '#{{issue}} "{{title}}" está en cola',
+      '',
+      'Se alcanzó el límite de agentes simultáneos. Empieza solo cuando termine una ejecución.',
+    ],
+    fix_done: [
+      '#{{issue}} "{{title}}" corregido (iteración {{iteration}})',
+      '',
+      'Qué cambió: {{summary}}',
+      'QA: {{qa}}',
+      'Commit: {{commit}}',
+      '@{{recipient}} {{ask}}',
+    ],
+  },
+};
+
+export const MESSAGE_KINDS = Object.keys(REQUIRED);
+
+// ", N of M tasks are done" for the work that was kept, when the numbers are known.
+function tasksInfo(values, es) {
+  if (!present(values.tasks_done) || !present(values.tasks_total)) return '';
+  return es ? ` (${values.tasks_done} de ${values.tasks_total} tareas hechas)` : ` (${values.tasks_done} of ${values.tasks_total} tasks done)`;
+}
+
+function present(value) {
+  return value !== undefined && value !== null && String(value).trim() !== '';
+}
+
+function shorten(value) {
+  const text = String(value);
+  return text.length > MAX_VALUE_LENGTH ? `${text.slice(0, MAX_VALUE_LENGTH)}… (truncated; see the full log)` : text;
+}
+
+export function renderMessage(kind, data = {}, language = 'en') {
+  if (!REQUIRED[kind]) throw new Error(`unknown message kind "${kind}"`);
+  const values = { ...data };
+  REQUIRED[kind].forEach((field) => {
+    if (!present(values[field])) throw new Error(`message "${kind}" needs "${field}"`);
+  });
+  const language_ = pickLanguage(language);
+  const es = language_ === 'es';
+  if (kind === 'built' && present(values.issue_hash)) values.issue_hash_short = shortHash(values.issue_hash);
+
+  // The next step comes from one table. needs-spec depends on why the issue came back, qa-failed on what the branch holds.
+  if (STATE_OF[kind]) {
+    const reason = kind === 'needs_spec' ? values.reason ?? 'missing' : kind === 'qa_failed' ? values.recovery ?? (values.branch_state === 'kept' ? 'kept' : 'fix') : null;
+    const step = nextStep({ state: STATE_OF[kind], reason, issue: values.issue, language: language_ });
+    if (!present(values.command) && step.command) values.command = step.command;
+    if (kind === 'needs_spec') values.next_line = `${nextStepPrefix(language_)}: ${step.command}: ${step.hint}.`;
+    if (kind === 'qa_failed') {
+      // For kept work the next step says what the command does and the other way forward; the others are the bare command.
+      const kept = step.reason === 'kept';
+      values.next_line = step.command ? `${nextStepPrefix(language_)}: ${values.command ?? step.command}${kept ? ` (${step.hint})` : ''}` : `${nextStepPrefix(language_)}: ${step.hint}.`;
+    }
+  }
+  if (kind === 'qa_failed') {
+    const location = present(values.file) ? `${values.file}${present(values.line) ? `:${values.line}` : ''}` : '';
+    values.location_suffix = location ? ` (${location})` : '';
+    // `pushed: false` is the older way to say that the branch was not pushed because of a credential or a marker.
+    const state = values.branch_state ?? (values.pushed === false ? 'unsafe' : 'pushed');
+    if (!['pushed', 'unsafe', 'not_pushed', 'existing', 'kept'].includes(state)) throw new Error(`message "qa_failed" has an unknown branch_state "${state}"`);
+    if (state === 'existing' && !present(values.recovery)) throw new Error('message "qa_failed" needs "recovery" when the branch already existed');
+    const branchLines = {
+      pushed: es
+        ? `La rama ${values.branch} está subida; el estado no avanzó y no se abrió ningún pull request.`
+        : `The branch ${values.branch} is pushed; the state did not advance and no pull request was opened.`,
+      unsafe: es
+        ? `La rama ${values.branch} NO se subió (se encontró una posible credencial, un marcador temporal o una ruta protegida); el estado no avanzó y no se abrió ningún pull request.`
+        : `The branch ${values.branch} was NOT pushed (a possible credential, a temporary marker or a protected path was found); the state did not advance and no pull request was opened.`,
+      not_pushed: es
+        ? `La rama ${values.branch} no se subió; el estado no avanzó y no se abrió ningún pull request.`
+        : `The branch ${values.branch} was not pushed; the state did not advance and no pull request was opened.`,
+      kept: es
+        ? `La rama ${values.branch} tiene el trabajo que QA no aprobó${tasksInfo(values, es)}; se guardó como trabajo en curso para que no se pierda. El estado no avanzó y no se abrió ningún pull request.`
+        : `The branch ${values.branch} holds the work that QA did not approve${tasksInfo(values, es)}; it was kept as work in progress so nothing is lost. The state did not advance and no pull request was opened.`,
+      existing: es
+        ? `La rama ${values.branch} ya existía en el remoto, así que no se tocó; el estado no avanzó y no se abrió ningún pull request.`
+        : `The branch ${values.branch} already existed on the remote, so it was not touched; the state did not advance and no pull request was opened.`,
+    };
+    values.branch_line = branchLines[state];
+    values.reason_suffix = present(values.reason) ? ` (${values.reason})` : '';
+  }
+
+  const lines = CATALOG[pickLanguage(language)][kind];
+  const out = [];
+  lines.forEach((template) => {
+    const names = [...template.matchAll(/\{\{(\w+)\}\}/g)].map((m) => m[1]);
+    const optionalEmpty = names.some((n) => !present(values[n]) && !n.endsWith('_suffix'));
+    if (names.length > 0 && optionalEmpty) return;
+    out.push(template.replace(/\{\{(\w+)\}\}/g, (_, n) => (n === 'checklist' ? String(values[n] ?? '') : shorten(values[n] ?? ''))));
+  });
+
+  // Collapse repeated blank lines and trim the ends.
+  const collapsed = out.filter((l, i) => !(l === '' && (out[i - 1] === '' || i === 0)));
+  while (collapsed.length > 0 && collapsed[collapsed.length - 1] === '') collapsed.pop();
+  return collapsed.join('\n');
+}

package/scripts/lib/next-step.mjs

@@ -0,0 +1,153 @@
+// The next step of an issue, from one table, in the language of the repository.
+// Implements "The next step comes from one source" of the issue-lifecycle specification.
+//
+// Every message and report that tells a person what to do next asks this table, so the command, who runs it and
+// the short hint cannot drift apart. A test checks that every lifecycle state has an entry.
+
+import { pickLanguage } from './language.mjs';
+
+// command: the command to run (`{n}` is the issue number), or null when nobody has to act yet.
+// who:     the role that runs it; the words for each role are in WHO.
+const TABLE = {
+  ready: {
+    command: null,
+    who: 'nobody',
+    hint: { en: 'the agent starts it by itself', es: 'el agente la empieza solo' },
+  },
+  queued: {
+    command: null,
+    who: 'nobody',
+    hint: { en: 'it starts when the assignee has capacity', es: 'empieza cuando la persona asignada tenga capacidad' },
+  },
+  building: {
+    command: null,
+    who: 'nobody',
+    hint: { en: 'the agent is building it', es: 'el agente la está construyendo' },
+  },
+  blocked: {
+    command: null,
+    who: 'nobody',
+    hint: { en: 'it starts when the issues it depends on are merged', es: 'empieza cuando se fusionen los issues de los que depende' },
+  },
+  built: {
+    command: '/relevo:review {n}',
+    who: 'assignee',
+    hint: { en: 'review it on a device', es: 'revísala en un dispositivo' },
+  },
+  'in-review': {
+    command: '/relevo:review {n}',
+    who: 'assignee',
+    hint: { en: 'continue the review; if something fails, run /relevo:fix {n}', es: 'continúa la revisión; si algo falla, ejecuta /relevo:fix {n}' },
+  },
+  'pr-open': {
+    command: '/relevo:ship {n}',
+    who: 'approver',
+    hint: { en: 'after someone other than the author approves the pull request on GitHub', es: 'cuando alguien que no sea el autor apruebe el pull request en GitHub' },
+  },
+  'needs-spec': {
+    // The reason decides what the spec writer has to do.
+    missing: {
+      command: '/relevo:issue {n}',
+      who: 'spec_writer',
+      hint: { en: 'complete what is missing, then label it ready again', es: 'completa lo que falta y vuelve a ponerle ready' },
+    },
+    ambiguous: {
+      command: '/relevo:issue {n}',
+      who: 'spec_writer',
+      hint: {
+        en: 'decide the open question (run /relevo:think #{n} first if you need to explore it), then label it ready again',
+        es: 'decide la pregunta abierta (ejecuta antes /relevo:think #{n} si necesitas explorarla) y vuelve a ponerle ready',
+      },
+    },
+  },
+  'qa-failed': {
+    // The recovery depends on what is on the branch.
+    fix: {
+      command: '/relevo:fix {n}',
+      who: 'assignee',
+      hint: { en: 'describe what QA found', es: 'describe lo que encontró QA' },
+    },
+    // The branch holds the work that QA rejected, committed as work in progress: correct it, or rethink the issue.
+    kept: {
+      command: '/relevo:fix {n}',
+      who: 'assignee',
+      hint: {
+        en: 'it checks and corrects the work that was kept; to rethink the issue instead, use /relevo:think and then /relevo:issue {n}',
+        es: 'verifica y corrige el trabajo que se guardó; para repensar el issue, usa /relevo:think y luego /relevo:issue {n}',
+      },
+    },
+    'delete-branch': {
+      command: null,
+      who: 'assignee',
+      hint: {
+        en: 'the branch holds only the specification: delete the remote branch and label the issue ready again',
+        es: 'la rama solo tiene la especificación: borra la rama remota y vuelve a ponerle ready al issue',
+      },
+    },
+  },
+  'changes-requested': {
+    command: '/relevo:fix {n}',
+    who: 'author',
+    hint: { en: 'fix what the reviewer asked for', es: 'corrige lo que pidió quien revisa' },
+  },
+  'needs-reviewer': {
+    command: null,
+    who: 'spec_writer',
+    hint: { en: 'assign a reviewer or ask someone to take it', es: 'asigna a alguien que revise o pide que alguien lo tome' },
+  },
+};
+
+const WHO = {
+  en: { assignee: 'the assignee', spec_writer: 'the spec writer', author: 'the author', approver: 'whoever merges', nobody: '' },
+  es: { assignee: 'la persona asignada', spec_writer: 'quien escribe las specs', author: 'el autor', approver: 'quien fusiona', nobody: '' },
+};
+
+const PREFIX = {
+  en: { act: 'Your next step', wait: 'Nothing to do now' },
+  es: { act: 'Tu siguiente paso', wait: 'Nada que hacer ahora' },
+};
+
+/** The states that have an entry: every lifecycle state. */
+export const NEXT_STEP_STATES = Object.keys(TABLE);
+
+/** Reasons for the states whose next step depends on one. */
+export const NEXT_STEP_REASONS = {
+  'needs-spec': ['missing', 'ambiguous'],
+  'qa-failed': ['fix', 'kept', 'delete-branch'],
+};
+
+const fill = (text, issue) => String(text).replaceAll('{n}', String(issue ?? ''));
+
+/**
+ * The next step for an issue in `state`.
+ * `reason` picks the variant of `needs-spec` (`missing` by default, or `ambiguous`) and of `qa-failed`
+ * (`fix` by default, `kept` when the branch holds the work that QA rejected, or `delete-branch` when the branch holds only the specification).
+ * Returns { state, reason, command, who, hint, line }; `command` is null when nobody has to act yet.
+ */
+export function nextStep({ state, reason = null, issue = null, language = 'en' } = {}) {
+  const entry = TABLE[state];
+  if (!entry) throw new Error(`unknown state "${state}": expected one of ${NEXT_STEP_STATES.join(', ')}`);
+  const variants = NEXT_STEP_REASONS[state];
+  let chosen = entry;
+  let used = null;
+  if (variants) {
+    used = reason ?? variants[0];
+    chosen = entry[used];
+    if (!chosen) throw new Error(`unknown reason "${reason}" for "${state}": expected one of ${variants.join(', ')}`);
+  }
+  const lang = pickLanguage(language);
+  const needsIssue = [chosen.command, chosen.hint.en].some((t) => String(t).includes('{n}'));
+  if (needsIssue && (issue === null || issue === undefined || issue === '')) throw new Error(`the next step of "${state}" needs the issue number`);
+
+  const command = chosen.command === null ? null : fill(chosen.command, issue);
+  const hint = fill(chosen.hint[lang], issue);
+  const who = WHO[lang][chosen.who];
+  const person = who ? ` (${who})` : '';
+  const line = command === null
+    ? `${chosen.who === 'nobody' ? PREFIX[lang].wait : PREFIX[lang].act}: ${hint}${chosen.who === 'nobody' ? '' : person}.`
+    : `${PREFIX[lang].act}: ${command}${person}: ${hint}.`;
+  return { state, reason: used, command, who: chosen.who, hint, line };
+}
+
+/** The words that open a next-step line in a language ("Your next step"), for messages that build their own line. */
+export const nextStepPrefix = (language) => PREFIX[pickLanguage(language)].act;

package/scripts/lib/openspec-commands.mjs

@@ -0,0 +1,44 @@
+// The OpenSpec commands each part of Relevo may use. Implements "OpenSpec commands come from a closed list" of the
+// go specification. A test (tests/openspec-commands.test.mjs) compares this table with the text of the skill and the
+// agents, so a command cannot be added to a prompt without being added here, on purpose.
+//
+// Commands are written the way `openspecSubcommand` normalises them:
+//   `--version`, `list`, `new change`, `status`, `validate`, `instructions apply`, `instructions <artifact>`.
+
+export const OPENSPEC_COMMANDS = {
+  go: ['--version', 'list', 'new change', 'status', 'instructions <artifact>', 'instructions apply', 'validate'],
+  // The developer and QA only read the state of the change; they never create or archive anything.
+  dev: ['status', 'instructions apply'],
+  qa: ['status', 'instructions apply'],
+  // `think` and `issue` only read: the specifications and the changes that exist.
+  think: ['list', 'show', 'status'],
+  issue: ['list', 'show'],
+  // `review` only finds the change folder.
+  review: ['list'],
+};
+
+/** Subcommands that no unattended run may use, whatever the list says. */
+export const NEVER = ['init', 'archive', 'update', 'sync'];
+
+/**
+ * Normalise what follows `openspec` in a command into the form used by the table.
+ * `['instructions', 'apply', '--change', 'x']` -> `instructions apply`; `['instructions', 'specs']` -> `instructions <artifact>`.
+ * Returns null when there is nothing to normalise.
+ */
+export function openspecSubcommand(tokens) {
+  const [first, second] = tokens.filter(Boolean);
+  if (!first) return null;
+  if (first === '--version' || first === '-V') return '--version';
+  if (first === 'new') return second === 'change' ? 'new change' : 'new';
+  if (first === 'instructions') {
+    if (!second || second.startsWith('-')) return 'instructions';
+    return ['apply', 'archive'].includes(second) ? `instructions ${second}` : 'instructions <artifact>';
+  }
+  return first;
+}
+
+/** Is the command (the tokens after `openspec`) allowed for `part` (`go`, `dev`, `qa`, `think`, `issue` or `review`)? */
+export function isAllowed(part, tokens) {
+  const sub = openspecSubcommand(tokens);
+  return Boolean(sub) && (OPENSPEC_COMMANDS[part] ?? []).includes(sub);
+}

package/scripts/lib/openspec-status.mjs

@@ -0,0 +1,16 @@
+// Reads the JSON of `openspec status --change <id> --json`.
+// Implements "The specification is complete before it is validated" of the go specification.
+
+/** Artifacts that are neither done nor skipped, in the order OpenSpec lists them. */
+export function pendingArtifacts(status) {
+  return (status?.artifacts ?? []).filter((a) => !['done', 'skipped'].includes(a.status)).map((a) => a.id);
+}
+
+/**
+ * Is the specification of the change complete? True when it has artifacts and every one is `done` or `skipped`
+ * (a change that declares `skip_specs` has its specs artifact `skipped`, and that is complete).
+ */
+export function planningComplete(status) {
+  const artifacts = status?.artifacts ?? [];
+  return artifacts.length > 0 && pendingArtifacts(status).length === 0;
+}