@polymorphism-tech/morph-spec 8.44.0 → 8.46.0

package/src/dashboard/app/lib/format.js

@@ -67,3 +67,8 @@ export function splitFrontmatter(text) {
   }
   return { meta, body: text.slice(m[0].length) };
 }
+
+export function verdictLabel(f) {
+  if (!f?.verdict) return null;
+  return f.blockers ? `${f.verdict} · ${f.blockers} bloq.` : f.verdict;
+}

package/src/dashboard/app/main.jsx

@@ -1,13 +1,13 @@
-import { StrictMode } from 'react';
-import { createRoot } from 'react-dom/client';
-import { BrowserRouter } from 'react-router-dom';
-import App from './App.jsx';
-import './styles/index.css';
-
-createRoot(document.getElementById('root')).render(
-  <StrictMode>
-    <BrowserRouter>
-      <App />
-    </BrowserRouter>
-  </StrictMode>
-);
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter } from 'react-router-dom';
+import App from './App.jsx';
+import './styles/index.css';
+
+createRoot(document.getElementById('root')).render(
+  <StrictMode>
+    <BrowserRouter>
+      <App />
+    </BrowserRouter>
+  </StrictMode>
+);

package/src/dashboard/app/pages/FeatureDetail.jsx

@@ -13,7 +13,7 @@ import { usePref, useNow } from '../hooks/usePref.js';
 import { Segmented, isWorking } from './Features.jsx';
 import { apiBase, projectHref } from '../lib/project.js';
 import { PHASES, GATE_LABEL, STATUS_LABEL, LOCATION_LABEL, phaseMeta } from '../lib/phases.js';
-import { timeAgo, dateTime, num, duration, bytes } from '../lib/format.js';
+import { timeAgo, dateTime, num, duration, bytes, verdictLabel } from '../lib/format.js';
 
 const TABS = [
   { id: 'overview', label: 'Visão geral' },
@@ -77,7 +77,7 @@ export function nextAction(f) {
   if (f.status === 'abandoned') return 'Abandonada.';
   const paused = f.gates.find((g) => g.paused);
   if (paused) return `O ${GATE_LABEL[paused.gate] || paused.gate} pausou${paused.reason ? `: ${paused.reason}` : ''}. A decisão é sua, no Claude Code.`;
-  if (f.inEvaluation) return 'O avaliador independente entregou o relatório. O Gate 3 decide pelo score.';
+  if (f.inEvaluation) return 'O avaliador independente entregou o relatório. O Gate 3 decide pelo veredito e pelos bloqueadores.';
   if (f.phase === 'implement' && f.tasksList?.length) {
     const open = f.tasksList.find((t) => t.status === 'in_progress') || f.tasksList.find((t) => t.status === 'pending');
     if (open) return `${f.tasks.done} de ${f.tasks.total} tasks feitas. Próxima: ${open.id}, ${open.title}.`;
@@ -149,24 +149,20 @@ function NodeChips({ nodes }) {
   );
 }
 
-function ScoreBlock({ f }) {
-  const score = f.score ?? f.legacyScore;
-  const proofs = f.proofScores ? Object.entries(f.proofScores) : [];
+function VerdictBlock({ f }) {
   return (
     <div>
       <p className="flex items-baseline gap-2">
-        <span className="text-4xl font-semibold tabular-nums tracking-tight">{score ?? '—'}</span>
-        <span className="text-sm text-[var(--color-dim)]">{score == null ? 'sem relatório do avaliador' : f.score != null ? 'Composite-Score do avaliador' : 'score legado'}</span>
+        <span className="text-4xl font-semibold tracking-tight">{f.verdict ?? '—'}</span>
+        <span className="text-sm text-[var(--color-dim)]">{f.verdict ? `${f.blockers ?? 0} bloqueador(es)` : 'sem veredito do avaliador'}</span>
       </p>
-      {proofs.length > 0 && (
-        <ul className="mt-4 space-y-1.5">
-          {proofs.map(([k, v]) => (
-            <li key={k} className="grid grid-cols-[5.5rem_minmax(0,1fr)_2rem] items-center gap-3 text-xs">
-              <span className="text-[var(--color-dim)]">{k}</span>
-              <span className="h-1 overflow-hidden rounded-full bg-white/[0.07]">
-                <span className="block h-full rounded-full" style={{ width: `${v * 10}%`, background: v >= 9 ? 'var(--color-ok)' : v >= 7 ? 'var(--color-phase-plan)' : 'var(--color-warn)' }} />
-              </span>
-              <span className="text-right font-mono tabular-nums text-[var(--color-dim)]">{v}</span>
+      {f.blockerList?.length > 0 && (
+        <ul className="mt-4 space-y-1.5 text-xs">
+          {f.blockerList.map((b) => (
+            <li key={b.id} className="grid grid-cols-[3rem_6rem_minmax(0,1fr)] gap-3">
+              <span className="font-mono text-[var(--color-dim)]">{b.id}</span>
+              <span className="text-[var(--color-warn)]">{b.type}</span>
+              <span className="truncate text-[var(--color-dim)]" title={b.evidence}>{b.where}</span>
             </li>
           ))}
         </ul>
@@ -212,7 +208,7 @@ function OverviewTab({ f, cost }) {
         <Panel title="Gates"><GateList f={f} /></Panel>
       </div>
       <div className="space-y-5">
-        <Panel title="Avaliação"><ScoreBlock f={f} /></Panel>
+        <Panel title="Avaliação"><VerdictBlock f={f} /></Panel>
         <Panel title="Último verify">
           {f.verification && (
             <p className="mb-3 text-xs text-[var(--color-faint)]">
@@ -256,7 +252,7 @@ function TaskRow({ t, f, open, onToggle, duration: secs, ready }) {
         <span className="hidden text-xs md:block">
           {verify ? <span className={verify.status === 'pass' ? 'text-[var(--color-ok)]' : 'text-[var(--color-bad)]'}>verify {verify.status}</span> : <span className="text-[var(--color-faint)]">—</span>}
         </span>
-        <span className="hidden text-right font-mono text-xs tabular-nums text-[var(--color-dim)] md:block">{t.score?.lastScore ?? verify?.score ?? '—'}</span>
+        <span className="hidden text-right font-mono text-xs tabular-nums text-[var(--color-dim)] md:block">{verify?.status ?? '—'}</span>
         <span className="hidden text-[var(--color-faint)] md:block">{open ? <CaretDown weight="light" size={14} /> : <CaretRight weight="light" size={14} />}</span>
       </button>
       {open && (
@@ -320,7 +316,6 @@ const BOARD_COLUMNS = [
 
 function TaskCard({ t, f, secs, ready }) {
   const reports = reportPathFor(f, t.id);
-  const score = t.score?.lastScore ?? t.verification?.score;
   return (
     <li className="rounded-xl bg-[var(--color-raised)] px-3.5 py-3 shadow-[inset_0_0_0_1px_var(--color-hair),inset_0_1px_0_rgb(255_255_255_/_0.05)]">
       <p className="flex items-baseline gap-2">
@@ -335,7 +330,6 @@ function TaskCard({ t, f, secs, ready }) {
       <div className="mt-2.5 flex items-center justify-between text-xs">
         <span className="flex items-center gap-2">
           {t.verification && <span className={t.verification.status === 'pass' ? 'text-[var(--color-ok)]' : 'text-[var(--color-bad)]'}>verify {t.verification.status}</span>}
-          {score != null && <span className="font-mono text-[var(--color-dim)]">{score}</span>}
         </span>
         <span className="text-[var(--color-faint)]">{secs ? duration(secs) : ''}</span>
       </div>
@@ -488,7 +482,7 @@ function DocsTab({ f, doc, onDoc, project }) {
 }
 
 export function FeatureDetailView({ f, tab, onTab, doc, onDoc, cost, latest = null, tasksView = 'list', onTasksView = () => {}, now = Date.now(), project, projectName }) {
-  const score = f.score ?? f.legacyScore;
+  const verdict = verdictLabel(f);
   const working = latest && isWorking({ ...f, lastActivity: latest }, now);
   return (
     <div className="mx-auto max-w-6xl px-4 pb-24 pt-8 md:px-10 md:pt-12">
@@ -507,7 +501,7 @@ export function FeatureDetailView({ f, tab, onTab, doc, onDoc, cost, latest = nu
             </div>
             <div className="flex shrink-0 gap-6 text-right">
               <div><p className="text-2xl font-semibold tabular-nums">{f.tasks.total ? `${f.tasks.done}/${f.tasks.total}` : '—'}</p><p className="text-xs text-[var(--color-faint)]">tasks</p></div>
-              <div><p className="text-2xl font-semibold tabular-nums">{score ?? '—'}</p><p className="text-xs text-[var(--color-faint)]">score</p></div>
+              <div><p className="text-2xl font-semibold">{verdict ?? '—'}</p><p className="text-xs text-[var(--color-faint)]">veredito</p></div>
             </div>
           </div>
           <div className="mt-8"><PhaseRail feature={f} size="lg" /></div>

package/src/dashboard/app/pages/Features.jsx

@@ -8,7 +8,7 @@ import PhaseRail from '../components/PhaseRail.jsx';
 import { useMorphQuery } from '../hooks/useMorphQuery.js';
 import { usePref, useNow } from '../hooks/usePref.js';
 import { PHASES, phaseMeta, LOCATION_LABEL } from '../lib/phases.js';
-import { timeAgo } from '../lib/format.js';
+import { timeAgo, verdictLabel } from '../lib/format.js';
 import { apiBase, featureHref } from '../lib/project.js';
 import { isFinished } from '../../scanner/feature-status.js';
 
@@ -21,7 +21,7 @@ const LOCATION_ICON = { worktree: GitBranch, archive: Archive, root: HouseSimple
 const SORTS = {
   updated: { label: 'Mais recentes', cmp: (a, b) => (lastTouch(b) || '').localeCompare(lastTouch(a) || '') },
   name: { label: 'Nome', cmp: (a, b) => a.name.localeCompare(b.name) },
-  score: { label: 'Score', cmp: (a, b) => (b.score ?? b.legacyScore ?? -1) - (a.score ?? a.legacyScore ?? -1) },
+  verdict: { label: 'Veredito', cmp: (a, b) => (a.blockers ?? 99) - (b.blockers ?? 99) },
 };
 
 function lastTouch(f) {
@@ -83,7 +83,7 @@ function subline(f, now) {
 
 export function FeatureRow({ f, now, project, projectName }) {
   const LocIcon = LOCATION_ICON[f.location] || HouseSimple;
-  const score = f.score ?? f.legacyScore;
+  const verdict = verdictLabel(f);
   return (
     <li>
       <Link
@@ -108,8 +108,8 @@ export function FeatureRow({ f, now, project, projectName }) {
         <div className="flex items-center gap-5 md:contents">
           <TaskMeter tasks={f.tasks} />
           <VerifyMark verification={f.verification} />
-          <span className="font-mono text-sm tabular-nums text-[var(--color-dim)]" title={score != null ? 'score do avaliador' : 'sem score'}>
-            {score != null ? score : '—'}
+          <span className="font-mono text-sm tabular-nums text-[var(--color-dim)]" title={verdict ? 'veredito do avaliador' : 'sem veredito'}>
+            {verdict ?? '—'}
           </span>
           <span className="flex items-center gap-1.5 text-xs text-[var(--color-faint)]" title={LOCATION_LABEL[f.location]}>
             <LocIcon weight="light" size={14} />
@@ -141,7 +141,7 @@ export function Section({ title, hint, features, now, project }) {
 }
 
 function BoardCard({ f, now, project }) {
-  const score = f.score ?? f.legacyScore;
+  const verdict = verdictLabel(f);
   const paused = f.gates.find((g) => g.paused);
   return (
     <li>
@@ -169,7 +169,7 @@ function BoardCard({ f, now, project }) {
         <div className="mt-2.5 flex items-center justify-between text-xs text-[var(--color-faint)]">
           <span className="flex items-center gap-2">
             <VerifyMark verification={f.verification} />
-            {score != null && <span className="font-mono tabular-nums text-[var(--color-dim)]">{score}</span>}
+            {verdict && <span className="font-mono tabular-nums text-[var(--color-dim)]">{verdict}</span>}
             {f.workType && f.workType !== 'feature' && <span>{f.workType}</span>}
           </span>
           <span>{timeAgo(lastTouch(f), now)}</span>

package/src/dashboard/app/pages/PhasePipeline.jsx

@@ -14,7 +14,7 @@ const GATE_CHECKS = {
   proposal: 'Confere o escopo da proposta: o problema, o que entra e o que fica de fora, antes de gastar esforço em design ou plano.',
   uiux: 'Confere o design das telas (mockups e checklist de tela). É opcional: só existe quando a feature passa pela fase de UI/UX.',
   plan: 'Confere a spec, as tasks e o plano de implementação. Depois dele a spec congela e a implementação começa.',
-  review: 'Confere a avaliação independente: um avaliador em contexto novo dá o score, que precisa ser pelo menos 9, com o verify verde.',
+  review: 'Confere a avaliação independente: um avaliador em contexto novo dá o veredito (SHIP ou FIX) e só bloqueia com evidência, com o verify verde.',
 };
 
 const GATE_PREFIX = 'gate-';

package/src/dashboard/app/pages/Rubrics.jsx

@@ -2,16 +2,12 @@ import morphData from 'virtual:morph-data';
 import KnowledgeMarkdown from '../components/KnowledgeMarkdown.jsx';
 import { useSelection } from '../components/EntityLink.jsx';
 
-const DOCS = morphData.docs || { rubrics: [], proofRubrics: [] };
-const README = DOCS.rubrics.find((r) => r.id === 'README');
-const DIMENSIONS = DOCS.rubrics.filter((r) => r.id !== 'README' && r.id !== 'condensed');
-const CONDENSED = DOCS.rubrics.find((r) => r.id === 'condensed');
+const DOCS = morphData.docs || { rubrics: [] };
+const CHECKLIST = DOCS.rubrics.find((r) => r.id === 'review-checklist');
 const VALIDATORS = morphData.rubrics || [];
 
 const GROUPS = [
-  { title: 'Dimensões do avaliador', hint: 'o score composto sai destas quatro', items: DIMENSIONS.map((r) => ({ key: `dim:${r.id}`, title: r.title, doc: r })) },
-  { title: 'Versão curta', hint: 'usada na avaliação por task', items: CONDENSED ? [{ key: 'dim:condensed', title: CONDENSED.title, doc: CONDENSED }] : [] },
-  { title: 'Provas', hint: 'o que o avaliador precisa ver acontecer', items: DOCS.proofRubrics.filter((r) => r.id !== 'README').map((r) => ({ key: `proof:${r.id}`, title: r.title, doc: r })) },
+  { title: 'Avaliador do Gate 3', hint: 'veredito e bloqueadores com evidência', items: CHECKLIST ? [{ key: 'dim:review-checklist', title: CHECKLIST.title, doc: CHECKLIST }] : [] },
   { title: 'Validadores determinísticos', hint: 'pesos por categoria no verify', items: VALIDATORS.map((v) => ({ key: `val:${v.id}`, title: `Rubrica ${v.id}`, validator: v })) },
 ].filter((g) => g.items.length);
 
@@ -35,7 +31,7 @@ function ValidatorRubric({ v }) {
           ))}
         </tbody>
       </table>
-      <p>Aprova com <strong>{v.thresholds?.approve ?? '—'}</strong>; abaixo de <strong>{v.thresholds?.retry ?? '—'}</strong> a task volta para correção.</p>
+      <p>O score é informativo: o nó de validadores do verify reprova por erro de validador, não pelo número.</p>
     </article>
   );
 }
@@ -47,7 +43,7 @@ export function RubricsView({ sel, onSel }) {
       <header className="rise mb-8">
         <h1 className="text-4xl font-semibold tracking-tight md:text-5xl">Rubricas</h1>
         <p className="mt-3 max-w-2xl text-sm leading-relaxed text-[var(--color-dim)]">
-          Com o que o trabalho é julgado. O avaliador independente pontua cada dimensão de 0 a 10, e o Gate 3 exige score composto 9.
+          Com o que o trabalho é julgado. O avaliador independente decide SHIP ou FIX, e só bloqueia com evidência de UC, teste, regressão ou segurança.
           Os validadores rodam no <span className="font-mono text-[var(--color-fg)]">morph-spec verify</span>, sem modelo.
         </p>
       </header>
@@ -59,7 +55,7 @@ export function RubricsView({ sel, onSel }) {
             aria-current={!current ? 'page' : undefined}
             className={['fluid mb-4 block w-full rounded-lg px-3 py-2 text-left text-sm transition-colors', !current ? 'bg-white/[0.08] text-[var(--color-fg)]' : 'text-[var(--color-dim)] hover:bg-white/[0.04]'].join(' ')}
           >
-            Como a nota é calculada
+            Como o Gate 3 decide
           </button>
           {GROUPS.map((g) => (
             <div key={g.title} className="mb-5">
@@ -85,7 +81,7 @@ export function RubricsView({ sel, onSel }) {
         </nav>
         <div className="bezel min-w-0">
           <div className="bezel-core min-w-0 px-6 py-8 md:px-12 md:py-10">
-            {!current && (README ? <KnowledgeMarkdown text={README.content} /> : <p className="text-sm text-[var(--color-dim)]">Escolha uma rubrica.</p>)}
+            {!current && (CHECKLIST ? <KnowledgeMarkdown text={CHECKLIST.content} /> : <p className="text-sm text-[var(--color-dim)]">Escolha uma rubrica.</p>)}
             {current?.doc && <KnowledgeMarkdown text={current.doc.content} />}
             {current?.validator && <ValidatorRubric v={current.validator} />}
           </div>

package/src/dashboard/scanner/docs-scanner.js

@@ -53,7 +53,6 @@ export function scanDocs(frameworkDir) {
 
   return {
     guide,
-    rubrics: mdDir(join(frameworkDir, 'evals', 'rubrics')),
-    proofRubrics: mdDir(join(frameworkDir, 'evals', 'proof-rubrics')),
+    rubrics: mdDir(join(frameworkDir, 'evals')).filter((d) => d.id === 'review-checklist'),
   };
 }

package/src/dashboard/scanner/features-scanner.js

@@ -221,8 +221,8 @@ function summarize(name, resolved) {
     verification: feature.verification
       ? { status: feature.verification.status ?? null, scope: feature.verification.scope ?? null, ts: feature.verification.ts ?? null }
       : null,
-    score: verdict?.score ?? null,
-    legacyScore: typeof feature.reviewScore === 'number' ? feature.reviewScore : null,
+    verdict: verdict?.verdict ?? null,
+    blockers: verdict?.verdict ? verdict.blockers.length : null,
     createdAt: feature.createdAt || null,
     updatedAt: feature.updatedAt || feature.archivedAt || feature.createdAt || null,
     archivedAt: feature.archivedAt || null,
@@ -325,13 +325,12 @@ export function readFeatureDetail(projectDir, name, { resolveTree = resolveFeatu
     tasksList: tasks.list.map((t) => ({
       ...t,
       verification: feature.taskVerifications?.[t.id] || null,
-      score: feature.taskScores?.[t.id] || null,
     })),
     tasksErrors: tasks.errors,
     gateDecisions: feature.gateDecisions || {},
     verificationNodes: feature.verification?.nodes || null,
     featureVerification: feature.verifications?.feature || null,
-    proofScores: verdict?.proofScores ?? null,
+    blockerList: verdict?.blockers ?? [],
     documents: listDocuments(resolved.dir),
     raw: resolved.feature,
   };

package/src/dashboard/scanner/rubrics-scanner.js

@@ -1,12 +1,12 @@
-import { readFileSync, readdirSync, existsSync } from 'fs';
-import { join } from 'path';
-
-export function scanRubrics(frameworkDir) {
-  const dir = join(frameworkDir, 'rubrics');
-  if (!existsSync(dir)) return [];
-  return readdirSync(dir).filter(f => f.endsWith('.json')).map(f => {
-    const d = JSON.parse(readFileSync(join(dir, f), 'utf8'));
-    return { id: d.id, version: d.version || '1.0.0', description: d.description || '',
-      categories: d.categories || {}, thresholds: d.thresholds || { approve: 9.0, retry: 6.0 } };
-  });
-}
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+export function scanRubrics(frameworkDir) {
+  const dir = join(frameworkDir, 'rubrics');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter(f => f.endsWith('.json')).map(f => {
+    const d = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+    return { id: d.id, version: d.version || '1.0.0', description: d.description || '',
+      categories: d.categories || {}, thresholds: d.thresholds || { approve: 9.0, retry: 6.0 } };
+  });
+}

package/src/dashboard/vite.config.js

@@ -1,24 +1,24 @@
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-import tailwindcss from '@tailwindcss/vite';
-import morphDataPlugin from './vite-plugin-morph-data.js';
-import { fileURLToPath } from 'url';
-import { dirname, resolve } from 'path';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const frameworkDir = resolve(__dirname, '..', '..', 'framework');
-const projectDir = process.env.MORPH_PROJECT_DIR || process.cwd();
-
-export default defineConfig({
-  root: __dirname,
-  plugins: [
-    react(),
-    tailwindcss(),
-    morphDataPlugin(frameworkDir, projectDir),
-  ],
-  server: {
-    port: 3200,
-  },
-});
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+import morphDataPlugin from './vite-plugin-morph-data.js';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const frameworkDir = resolve(__dirname, '..', '..', 'framework');
+const projectDir = process.env.MORPH_PROJECT_DIR || process.cwd();
+
+export default defineConfig({
+  root: __dirname,
+  plugins: [
+    react(),
+    tailwindcss(),
+    morphDataPlugin(frameworkDir, projectDir),
+  ],
+  server: {
+    port: 3200,
+  },
+});

package/src/lib/agents/output-collector.js

@@ -16,7 +16,6 @@ export const SOURCE_WEIGHTS = {
   proposal:       1.0,
   stackScan:      0.8,
   spec:           1.5,
-  mandate:        1.3,
   tasks:          1.3,
   decisions:      1.0,
   uiDesignSystem: 1.0,

package/src/lib/ci/ci-verify.js

@@ -0,0 +1,118 @@
+import { execFileSync } from 'child_process';
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { getHeadSha } from '../git/default-branch.js';
+import { treeMovedSince } from '../git/evidence-staleness.js';
+import { resolveGh } from '../git/gh.js';
+import {
+  CI_WORKFLOW_DIR, CI_WORKFLOW_FILE, ciAvailability, downloadResult, findCiWorkflow, pushBranch,
+  uncommittedCode, waitForRun, workflowPushProblem,
+} from './github-ci.js';
+import { renderCiWorkflow } from './workflow-scaffold.js';
+
+export const CI_WAIT_MS = 50 * 60 * 1000;
+const APPEAR_MS = Number(process.env.MORPH_CI_APPEAR_MS ?? 90 * 1000);
+
+export class CiUsageError extends Error {}
+
+const NODE_KEYS = ['build', 'tests', 'validators', 'e2e'];
+
+function isVerifyResult(result) {
+  return Boolean(result) && ['pass', 'fail'].includes(result.status) && result.scope === 'feature'
+    && NODE_KEYS.every((k) => typeof result.nodes?.[k]?.status === 'string');
+}
+
+function scaffoldWorkflow(root, config) {
+  const rel = `${CI_WORKFLOW_DIR}/${CI_WORKFLOW_FILE}`;
+  const abs = join(root, rel);
+  if (existsSync(abs)) return { error: `${rel} já existe e não chama morph-spec verify publicando o JSON` };
+  try {
+    mkdirSync(join(root, CI_WORKFLOW_DIR), { recursive: true });
+    writeFileSync(abs, renderCiWorkflow(root, config));
+    execFileSync('git', ['add', '--', rel], { cwd: root, stdio: 'pipe' });
+    execFileSync('git', ['commit', '-m', 'ci: workflow morph-verify (prova do Gate 3 no CI)', '--', rel], { cwd: root, stdio: 'pipe' });
+    return { path: rel };
+  } catch (err) {
+    return { error: `não consegui criar ${rel}: ${(err.stderr?.toString() || err.message).trim()}` };
+  }
+}
+
+function dispatchWorkflow(root, workflow, branch) {
+  try {
+    const { bin, prefix } = resolveGh();
+    execFileSync(bin, [...prefix, 'workflow', 'run', workflow, '--ref', branch], { cwd: root, stdio: 'pipe', timeout: 15000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `verify {f} --ci`: the feature-scope proof, run by the project's CI over the pushed commit.
+ * Every way CI cannot answer is `mode: 'local'` with the reason, and the caller runs the local
+ * verify: no CI is never a pause. Only the uploaded `verify --json` becomes a result, so the
+ * gate judges a CI run by the same stamp and the same rules as a local one.
+ *
+ * @returns {Promise<
+ *   { mode: 'local', reason: string } |
+ *   { mode: 'pending', reason: string, run: object|null } |
+ *   { mode: 'ci', result: object, run: object, created: string|null }>}
+ * @throws {CiUsageError} code CI would not see (uncommitted work)
+ */
+export async function runCiVerify(root, featureName, config, { log = () => {}, waitMs = CI_WAIT_MS, wait = waitForRun } = {}) {
+  const avail = ciAvailability(root, featureName, config);
+  if (!avail.ok) return { mode: 'local', reason: avail.reason };
+
+  const dirty = uncommittedCode(root);
+  if (dirty === null) return { mode: 'local', reason: 'git status não respondeu' };
+  if (dirty.length > 0) {
+    const shown = dirty.slice(0, 5).join(', ') + (dirty.length > 5 ? ` (+${dirty.length - 5})` : '');
+    throw new CiUsageError(`o CI só vê commits e há trabalho fora deles: ${shown}. Commite na branch da feature (git add <paths> && git commit) e rode de novo, ou rode sem --ci`);
+  }
+
+  let workflow = findCiWorkflow(root);
+  let created = null;
+  if (!workflow) {
+    const problem = workflowPushProblem(avail);
+    if (problem) return { mode: 'local', reason: problem };
+    const scaffold = scaffoldWorkflow(root, config);
+    if (scaffold.error) return { mode: 'local', reason: scaffold.error };
+    created = scaffold.path;
+    workflow = CI_WORKFLOW_FILE;
+    log(`workflow criado e commitado: ${created}`);
+  }
+
+  const pushError = pushBranch(root, avail.branch);
+  if (pushError) return { mode: 'local', reason: `push de ${avail.branch} falhou: ${pushError}` };
+
+  const head = getHeadSha(root);
+  const waitOpts = {
+    branch: avail.branch,
+    workflow,
+    isCurrent: (sha) => !treeMovedSince(root, sha, head),
+    timeoutMs: waitMs,
+    appearMs: APPEAR_MS,
+    onPending: (run) => log(`CI rodando: ${run.url}`),
+  };
+  let outcome = await wait(root, waitOpts);
+  if (outcome.state === 'no-run' && dispatchWorkflow(root, workflow, avail.branch)) {
+    log(`nenhum run para este commit; disparei ${workflow} manualmente`);
+    outcome = await wait(root, waitOpts);
+  }
+  if (outcome.state === 'no-run') return { mode: 'local', reason: `${workflow} não rodou para este commit` };
+  if (outcome.state === 'unknown') return { mode: 'local', reason: 'gh run list não respondeu' };
+  if (outcome.state === 'timeout') {
+    return { mode: 'pending', reason: `o CI não terminou em ${Math.round(waitMs / 60000)} min`, run: outcome.run ?? null };
+  }
+
+  const { run } = outcome;
+  const result = downloadResult(root, run.databaseId);
+  if (!isVerifyResult(result)) {
+    return {
+      mode: 'local',
+      reason: `run ${run.conclusion} sem o JSON do verify (${run.url}; gh run view ${run.databaseId} --log-failed)`,
+    };
+  }
+  const { persisted, reason, repeatOf, cleanup, ...verdict } = result;
+  return { mode: 'ci', result: verdict, run, created };
+}