@jaimevalasek/aioson 1.33.1 → 1.37.0

package/docs/pt/README.md

@@ -22,7 +22,7 @@ Esta é a porta de entrada da documentação em português. Não é um índice a
 ### Quero uma receita pronta para o meu caso
 
 **Trilhas canônicas — como features chegam ao dev:**
-1. **[Feature completa com @sheldon](./3-receitas/feature-completa-com-sheldon.md)** — a trilha principal: `@product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev → @qa` (com gates opcionais de `@tester` e `@pentester`)
+1. **[Feature completa com @sheldon](./3-receitas/feature-completa-com-sheldon.md)** — as duas trilhas: **SMALL lean** `@product → @sheldon → @dev → @qa` e **MEDIUM maestro** `@product → @orchestrator → @dev → @pentester → @qa` (com detours opt-in de `@tester`, `@validator`)
 2. [Da ideia ao PRD via @briefing](./3-receitas/da-ideia-ao-prd-via-briefing.md) — quando a ideia ainda é vaga
 3. [Plans externos para @product](./3-receitas/plans-externos-para-product.md) — quando você planejou em ChatGPT/Claude.io e quer trazer
 
@@ -37,7 +37,7 @@ Esta é a porta de entrada da documentação em português. Não é um índice a
 11. [Continuidade entre sessões](./3-receitas/continuidade-entre-sessoes.md) — feature dossier, dev-resume, drift detection
 
 ### Quero a referência técnica de um agente ou comando
-- **[Fichas dos 29 agentes (30 entradas com 1 alias)](./4-agentes/README.md)** — uma ficha por agente, com diálogo típico, saídas em disco e handoff
+- **[Fichas dos 29 agentes (30 entradas com 1 alias)](./4-agentes/README.md)** — uma ficha por agente, com diálogo típico, saídas em disco e handoff
 - **[Referência técnica completa](./5-referencia/README.md)** — 32 docs organizados em 5 categorias (novos 2026, artefatos, CLI/config, agentes/squads, skills/design)
 - [Guia de agentes (legado)](./agentes.md) — visão tabular alternativa
 
@@ -83,7 +83,7 @@ npx @jaimevalasek/aioson init meu-projeto
 cd meu-projeto
 
 # 3. Abra seu cliente AI (Claude Code, Codex e OpenCode) e digite:
-/aioson:agent:setup
+/aioson:agent:setup
 ```
 
 A partir daí, os agentes guiam você. Detalhes em [Primeiro projeto do zero](./2-comecar/primeiro-projeto.md).
@@ -99,7 +99,7 @@ Atualmente só PT está em reforma. EN/ES/FR continuam usando os arquivos legado
 ## Status desta documentação
 
 **Fase A (entender + começar)** — concluída · 8 docs em `1-entender/` e `2-comecar/`.
-**Fase B (receitas práticas + ficha por agente)** — concluída · 11 receitas em `3-receitas/` + 29 fichas em `4-agentes/`.
+**Fase B (receitas práticas + ficha por agente)** — concluída · 11 receitas em `3-receitas/` + 29 fichas em `4-agentes/`.
 **Fase C (referência técnica completa)** — concluída · 32 docs em `5-referencia/`, com 6 totalmente novos cobrindo features 2026 antes não documentadas em PT.
 **Fase D (trilhas de workflow)** — concluída · 3 trilhas canônicas de feature: briefing→PRD, plans externos, e trilha completa com @sheldon.
 

package/docs/pt/agentes.md

@@ -1,8 +1,8 @@
 # Guia de Agentes
 
-> **Versão tabular alternativa (legado).** Para fichas individuais detalhadas com diálogos, saídas em disco e handoff, veja [`4-agentes/README.md`](./4-agentes/README.md).
-
-> `@pair` é alias de `@deyvin` e não possui ficha separada.
+> **Versão tabular alternativa (legado).** Para fichas individuais detalhadas com diálogos, saídas em disco e handoff, veja [`4-agentes/README.md`](./4-agentes/README.md).
+
+> `@pair` é alias de `@deyvin` e não possui ficha separada.
 
 > Quando usar cada agente, o que ele entrega e como ativá-lo.
 
@@ -15,11 +15,11 @@ O AIOSON tem agentes oficiais de projeto e também pode criar agentes de squad.
 ```
 @setup        ← sempre o primeiro
 @product      ← gera o PRD base vivo e roteia o fluxo
-@deyvin       ← companheiro tecnico para continuidade e pequenas implementacoes
-@discovery-design-doc ← quando precisa clarear escopo e gerar design doc vivo
-@analyst      ← projetos SMALL e MEDIUM
-@scope-check  ← valida alinhamento antes de codar ou depois de fix relevante
-@architect    ← projetos SMALL e MEDIUM
+@deyvin       ← companheiro tecnico para continuidade e pequenas implementacoes
+@discovery-design-doc ← quando precisa clarear escopo e gerar design doc vivo
+@analyst      ← projetos SMALL e MEDIUM
+@scope-check  ← valida alinhamento antes de codar ou depois de fix relevante
+@architect    ← projetos SMALL e MEDIUM
 @ux-ui        ← UI/UX quando há interfaces (SMALL e MEDIUM)
 @pm           ← apenas MEDIUM
 @orchestrator ← apenas MEDIUM
@@ -55,9 +55,11 @@ O AIOSON tem agentes oficiais de projeto e também pode criar agentes de squad.
 
 Quando o projeto ja existe e voce roda `scan:project`, o handoff correto agora e:
 
-```text
-scan:project -> @analyst -> @scope-check -> @architect -> @dev
-```
+```text
+scan:project -> @analyst -> @scope-check -> @dev (ou @architect quando o full-merged opt-in do SMALL estiver ativo)
+```
+
+> Desde a lane lean (v1.35.0), `@analyst`/`@architect` nao sao mais hops obrigatorios do fluxo padrao apos o scan. A classificacao decide a lane: SMALL segue `@sheldon` como autoridade unica de spec (`@product -> @sheldon -> @dev`), MEDIUM segue o maestro `@orchestrator` (que dispara `@analyst`/`@architect`/`@pm` como sub-agentes do fan-out). Um `@analyst` isolado logo apos o scan continua valido como detour opt-in para mapear o dominio existente antes de abrir a primeira feature.
 
 Regras do fluxo:
 - os artefatos locais do scan (`scan-index.md`, `scan-folders.md`, `scan-<pasta>.md`, `scan-aioson.md`) servem como mapas brutos do codigo
@@ -81,7 +83,7 @@ Regras do fluxo:
 
 **Como ativar:**
 ```
-/aioson:agent:setup
+/aioson:agent:setup
 ```
 
 **O que ele pergunta:**
@@ -138,7 +140,7 @@ O `@product` detecta esses arquivos automaticamente e pergunta se deve usá-los
 
 **Como ativar:**
 ```
-/aioson:agent:product
+/aioson:agent:product
 ```
 
 **Entrega:** Arquivo `.aioson/context/prd.md` ou `.aioson/context/prd-{slug}.md` com:
@@ -182,12 +184,12 @@ O `@product` detecta esses arquivos automaticamente e pergunta se deve usá-los
 
 **Como ativar:**
 ```
-/aioson:agent:deyvin
+/aioson:agent:deyvin
 ```
 
 Alias compativel:
 ```text
-/aioson:agent:pair
+/aioson:agent:pair
 ```
 
 **Exemplos bons de uso:**
@@ -227,7 +229,7 @@ Alias compativel:
 
 **Como ativar:**
 ```
-/aioson:agent:analyst
+/aioson:agent:analyst
 ```
 
 **Exemplo de perguntas que ele faz:**
@@ -268,7 +270,7 @@ Em **modo feature**, entrega adicionalmente:
 
 **Como ativar:**
 ```
-/aioson:agent:discovery-design-doc
+/aioson:agent:discovery-design-doc
 ```
 
 **Entrega:**
@@ -300,7 +302,7 @@ Em **modo feature**, entrega adicionalmente:
 
 **Como ativar:**
 ```
-/aioson:agent:architect
+/aioson:agent:architect
 ```
 
 **Estruturas que ele propõe (exemplo Laravel SMALL):**
@@ -341,7 +343,7 @@ tests/
 
 **Como ativar o agente UI/UX:**
 ```
-/aioson:agent:ux-ui
+/aioson:agent:ux-ui
 ```
 
 **Submodos disponíveis:**
@@ -384,7 +386,7 @@ tests/
 
 **Como ativar:**
 ```
-/aioson:agent:pm
+/aioson:agent:pm
 ```
 
 **Regra de ouro do @pm:** O documento deve ter no máximo 2 páginas. Se passar disso, corte funcionalidades do MVP.
@@ -410,7 +412,7 @@ tests/
 
 **Como ativar:**
 ```
-/aioson:agent:orchestrator
+/aioson:agent:orchestrator
 ```
 
 **Ou via CLI para preparar os arquivos:**
@@ -455,7 +457,7 @@ npx @jaimevalasek/aioson parallel:status
 
 **Como ativar:**
 ```
-/aioson:agent:squad
+/aioson:agent:squad
 ```
 
 **Entrega:**
@@ -481,7 +483,7 @@ npx @jaimevalasek/aioson parallel:status
 
 **Como ativar:**
 ```
-/aioson:agent:genome
+/aioson:agent:genome
 ```
 
 **Entrega:**
@@ -517,7 +519,7 @@ Depois disso, ela passa a ser parte real do pacote local da squad e deve ser con
 
 **Como ativar:**
 ```
-/aioson:agent:dev
+/aioson:agent:dev
 ```
 
 **Princípios que ele aplica em qualquer stack:**
@@ -570,7 +572,7 @@ Se o usuário pedir para pular o teste, o `@dev` resiste, explica, e só cede ap
 
 **Como ativar:**
 ```
-/aioson:agent:qa
+/aioson:agent:qa
 ```
 
 **Entrega:**
@@ -634,7 +636,7 @@ O root de `.aioson/context/` fica limpo automaticamente. O desenvolvedor não pr
 
 **Como ativar:**
 ```
-/aioson:agent:tester
+/aioson:agent:tester
 ```
 
 **Entrega:**
@@ -669,7 +671,7 @@ O root de `.aioson/context/` fica limpo automaticamente. O desenvolvedor não pr
 
 **Como ativar:**
 ```
-/aioson:agent:sheldon
+/aioson:agent:sheldon
 ```
 
 **Entrega:**
@@ -698,7 +700,7 @@ Agentes que nao fazem parte do fluxo principal de entrega, mas entram sob demand
 
 **Como ativar:**
 ```
-/aioson:agent:committer
+/aioson:agent:committer
 ```
 
 **Entrega:**
@@ -719,7 +721,7 @@ Agentes que nao fazem parte do fluxo principal de entrega, mas entram sob demand
 
 **Como ativar:**
 ```
-/aioson:agent:copywriter
+/aioson:agent:copywriter
 ```
 
 **Entrega:**
@@ -741,7 +743,7 @@ Agentes que nao fazem parte do fluxo principal de entrega, mas entram sob demand
 
 **Como ativar:**
 ```
-/aioson:agent:briefing
+/aioson:agent:briefing
 ```
 
 **Entrega:**
@@ -762,7 +764,7 @@ Agentes que nao fazem parte do fluxo principal de entrega, mas entram sob demand
 
 **Como ativar:**
 ```
-/aioson:agent:design-hybrid-forge
+/aioson:agent:design-hybrid-forge
 ```
 
 **Entrega:**
@@ -782,7 +784,7 @@ Agentes que nao fazem parte do fluxo principal de entrega, mas entram sob demand
 
 **Como ativar:**
 ```
-/aioson:agent:discover
+/aioson:agent:discover
 ```
 
 **Ou via CLI:**
@@ -809,7 +811,7 @@ npx @jaimevalasek/aioson scan:project . --folder=src
 
 **Como ativar:**
 ```
-/aioson:agent:neo
+/aioson:agent:neo
 ```
 
 **Entrega:**
@@ -830,7 +832,7 @@ npx @jaimevalasek/aioson scan:project . --folder=src
 
 **Como ativar:**
 ```
-/aioson:agent:orache
+/aioson:agent:orache
 ```
 
 **Entrega:**
@@ -852,7 +854,7 @@ npx @jaimevalasek/aioson scan:project . --folder=src
 
 **Como ativar:**
 ```
-/aioson:agent:pentester
+/aioson:agent:pentester
 ```
 
 **Entrega:**
@@ -873,7 +875,7 @@ npx @jaimevalasek/aioson scan:project . --folder=src
 
 **Como ativar:**
 ```
-/aioson:agent:profiler-researcher
+/aioson:agent:profiler-researcher
 ```
 
 **Entrega:**
@@ -892,7 +894,7 @@ npx @jaimevalasek/aioson scan:project . --folder=src
 
 **Como ativar:**
 ```
-/aioson:agent:profiler-enricher
+/aioson:agent:profiler-enricher
 ```
 
 **Entrega:**
@@ -911,7 +913,7 @@ npx @jaimevalasek/aioson scan:project . --folder=src
 
 **Como ativar:**
 ```
-/aioson:agent:profiler-forge
+/aioson:agent:profiler-forge
 ```
 
 **Entrega:**
@@ -930,7 +932,7 @@ npx @jaimevalasek/aioson scan:project . --folder=src
 
 **Como ativar:**
 ```
-/aioson:agent:site-forge
+/aioson:agent:site-forge
 ```
 
 **Exemplos de uso:**
@@ -956,7 +958,7 @@ Extraia o design de https://exemplo.com como uma skill
 
 **Como ativar:**
 ```
-/aioson:agent:validator
+/aioson:agent:validator
 ```
 
 **Entrega:**
@@ -972,22 +974,20 @@ Extraia o design de https://exemplo.com como uma skill
 ```
 Duração típica: minutos a horas. Sem análise, sem arquitetura formal.
 
-### SMALL
+### SMALL — lean lane (padrão v1.35.0)
 ```
-@setup → @product → [@sheldon] → @analyst → @architect → @dev → @qa → [@tester]
+@setup → @product → @sheldon → @dev → @qa → [@tester]
 ```
-Duração típica: horas a dias. Análise leve, estrutura clara.
+Duração típica: horas a dias. `@sheldon` é a autoridade única de spec: produz requirements + decisões técnicas + plano faseado + harness-contract (Gates A/B/C) em uma passada. `@analyst`, `@architect`, `@scope-check` são detours opt-in.
 
-### MEDIUM
+### MEDIUM — maestro lane (v1.35.0)
 ```
-@setup → @product → [@sheldon] → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @pentester → @qa → [@tester]
+@setup → @product → [@sheldon] → @orchestrator → @dev → @pentester → @qa → [@tester]
 ```
-Duração típica: dias a semanas. Análise completa, paralelismo, backlog formal, revisao adversarial obrigatoria.
-
-> O `@pentester` entra obrigatoriamente em projetos MEDIUM entre `@dev` e `@qa`. Em projetos sensiveis ou com requisitos de seguranca, ative-o tambem em SMALL.
+Duração típica: dias a semanas. `@orchestrator` é o maestro de spec: faz fan-out para `@analyst` + `@architect` + `@pm` (+ `@ux-ui` quando UI-heavy) como sub-agentes, consolida e verifica os artefatos. `@pentester` é inline (entre `@dev` e `@qa`).
 
-`[@sheldon]` — opcional, recomendado antes de iniciar a cadeia de execução para validar o PRD.
-`[@tester]` — opcional, recomendado quando a cobertura de testes for insuficiente após `@dev`.
+> `[@sheldon]` — opcional no MEDIUM como pré-etapa antes do `@orchestrator` para endurecer o PRD.
+> `[@tester]` — opcional, recomendado quando a cobertura de testes for insuficiente após `@dev`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.33.1",
+  "version": "1.37.0",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",
@@ -42,7 +42,7 @@
     "test:genome-2.0:block-a": "node scripts/smoke/genome-2.0-smoke.js && npm run test:genome && npm test && npm run lint",
     "test:genome-2.0:rollout": "node scripts/testing/genome-2.0-rollout.js",
     "lint": "node scripts/check-js.js",
-    "sync:agents": "node src/commands/sync-agents-preflight.js && rsync -av --progress --exclude='config.md' --exclude='runtime/' --exclude='backups/' --exclude='mcp/servers.local.json' template/ ./",
+    "sync:agents": "node src/commands/sync-agents-preflight.js && node src/commands/sync-agents-copy.js",
     "ci": "npm run lint && npm test"
   },
   "dependencies": {

package/src/agents.js

@@ -67,7 +67,7 @@ function buildAgentPrompt(agent, tool, options = {}) {
     '',
     `**Language boundary:** Agent instructions are canonical in English. All user-facing communication must be in ${interactionLanguage}.`,
     '',
-    `**Scope boundary:** You operate exclusively as ${agent.command}. Do not perform work that belongs to another agent. When your work is complete, output only the handoff — which agent is next and why. Do not continue into that agent\'s territory.${autoHandoff ? ' Exception: autopilot handoff is active for this stage — follow `.aioson/docs/autopilot-handoff.md` and auto-invoke the next agent\'s skill when no stop condition applies. The chain stops before the first `@dev` activation (human clears context and starts implementation) and continues through the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their triggers fire → `@validator`); it NEVER auto-runs `feature:close`/publish — those require explicit human approval.' : ''}`,
+    `**Scope boundary:** You operate exclusively as ${agent.command}. Do not perform work that belongs to another agent. When your work is complete, output only the handoff — which agent is next and why. Do not continue into that agent\'s territory.${autoHandoff ? ' Exception: autopilot handoff is active for this stage — follow `.aioson/docs/autopilot-handoff.md` and auto-invoke the next agent\'s skill when no stop condition applies. The chain runs the whole feature: the spec authority (`@sheldon`/`@orchestrator`) seeds the agentic scheme and crosses into `@dev` via the `dev-state.md` cold-start packet once its own gates/decisions are settled, and the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their triggers fire → `@validator`) continues automatically. It stops only for a genuine human decision or a stop condition, and NEVER auto-runs `feature:close`/publish — those require explicit human approval.' : ''}`,
   ].join('\n');
 
   if (safeTool === 'claude') {

package/src/artifact-kinds.js

@@ -0,0 +1,111 @@
+'use strict';
+
+/**
+ * Canonical map: which agents produce a `verify:artifact`-checkable artifact at
+ * session end, the kind, and how that artifact's path is resolved.
+ *
+ *   needs: 'none'  — self-resolving (fixed path); the engine can prove it at
+ *                    `agent:done` with no extra input.
+ *   needs: 'slug'  — path keyed by --slug; the agent threads it into agent:done.
+ *   needs: 'file'  — date-stamped / caller-known path, threaded via --file.
+ *   needs: 'dir'   — a generated-site root, via --dir (advisory static floor only
+ *                    at agent:done; the full `npm run build` stays in the agent's
+ *                    explicit Done gate).
+ *
+ * This is the bridge that makes the periphery's done-gates AUTO-FIRE: instead of
+ * relying on each agent to remember its `## Done gate` line, `agent:done` runs the
+ * check itself (advisory, best-effort). Keep in sync with the RULESETS/ADAPTERS
+ * registry in commands/verify-artifact.js and the per-agent Done gates — it is one
+ * of the workflow agent-enumeration sites.
+ */
+const AGENT_ARTIFACT_KIND = {
+  setup: { kind: 'project-context', needs: 'none' },
+  discover: { kind: 'bootstrap', needs: 'none' },
+  committer: { kind: 'commit-message', needs: 'none' },
+  genome: { kind: 'genome', needs: 'slug' },
+  'profiler-forge': { kind: 'genome', needs: 'slug' },
+  'profiler-researcher': { kind: 'research-report', needs: 'slug' },
+  'profiler-enricher': { kind: 'enriched-profile', needs: 'slug' },
+  'design-hybrid-forge': { kind: 'hybrid-skill', needs: 'slug' },
+  copywriter: { kind: 'copy', needs: 'slug' },
+  orache: { kind: 'orache-report', needs: 'file' },
+  'site-forge': { kind: 'site', needs: 'dir', opts: { noBuild: true } },
+  'briefing-refiner': { kind: 'review', needs: 'slug' }
+};
+
+const NEEDS_FLAG = { slug: '--slug=<slug>', file: '--file=<path>', dir: '--dir=<dir>' };
+
+/** Resolve an agent name (with or without a leading @) to its artifact mapping, or null. */
+function resolveAgentArtifact(agent) {
+  const name = String(agent || '').trim().replace(/^@/, '');
+  return AGENT_ARTIFACT_KIND[name] || null;
+}
+
+/**
+ * Best-effort advisory `verify:artifact` for the calling agent at `agent:done`.
+ *
+ * Returns `null` when the agent produces no checkable artifact (the common case —
+ * product, dev, qa, …). Otherwise a uniform advisory descriptor:
+ *   { kind, ok, skipped, issues?, reason }
+ * - self-resolving kinds, or locator-keyed kinds whose locator was threaded into
+ *   agent:done, run the real check (advisory — never blocks).
+ * - a locator-keyed kind with no locator yields `skipped:true` plus a one-line
+ *   hint naming the exact command, so it is surfaced instead of silently missing.
+ *
+ * Never throws — a failure here must never break the session-end registration.
+ */
+async function verifyAgentArtifact({ targetDir, agent, options = {} }) {
+  const mapping = resolveAgentArtifact(agent);
+  if (!mapping) return null;
+  const { kind, needs } = mapping;
+  const slug = options.slug ? String(options.slug).trim() : null;
+  const file = options.file ? String(options.file).trim() : null;
+  const dir = options.dir ? String(options.dir).trim() : null;
+
+  const missingLocator =
+    (needs === 'slug' && !slug) || (needs === 'file' && !file) || (needs === 'dir' && !dir);
+  if (missingLocator) {
+    const flag = NEEDS_FLAG[needs];
+    return {
+      kind,
+      ok: true,
+      skipped: true,
+      reason: `needs ${flag} — run: aioson verify:artifact . --kind=${kind} ${flag} --advisory`
+    };
+  }
+
+  try {
+    const { runVerifyArtifact } = require('./commands/verify-artifact');
+    const report = await runVerifyArtifact({
+      args: [targetDir],
+      options: {
+        kind,
+        slug,
+        file,
+        dir,
+        advisory: true,
+        suppressExitCode: true,
+        json: true,
+        ...(mapping.opts && mapping.opts.noBuild ? { 'no-build': true } : {})
+      },
+      logger: { log() {}, error() {}, warn() {} }
+    });
+    if (!report) return null;
+    const issues = report.issues || [];
+    const head = issues.slice(0, 3).join('; ');
+    const more = issues.length > 3 ? ` (+${issues.length - 3} more)` : '';
+    return {
+      kind,
+      ok: Boolean(report.ok),
+      skipped: false,
+      issues,
+      reason: report.ok
+        ? null
+        : `${head}${more} — advisory; see .aioson/context/verify-artifact-${kind}.json`
+    };
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { AGENT_ARTIFACT_KIND, resolveAgentArtifact, verifyAgentArtifact };

package/src/autopilot-signal.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * Autopilot activation signal — the single source of truth for "is autopilot
+ * on?" outside the agent markdown files.
+ *
+ * Contract (docs/autopilot-handoff.md "Activation"), highest precedence first:
+ *   - A scheme for the CURRENT feature with `agentic_policy.enabled: false`
+ *     (the `--step` disarm) → OFF, even over `auto_handoff: true` — an explicit
+ *     per-feature choice always wins over the project default.
+ *   - `auto_handoff: true` in project.context.md frontmatter → ON (project default).
+ *   - `auto_handoff: false` → OFF, even if a seeded scheme is lying around
+ *     (step-by-step is the standing choice; a leftover scheme must not override it).
+ *   - flag absent → ON only when `.aioson/context/workflow-execute.json` exists
+ *     with `agentic_policy.enabled: true` (the per-feature "Autopilot" choice,
+ *     which deliberately does NOT persist the frontmatter flag). When a slug is
+ *     provided, the scheme counts only if it was seeded for THAT feature — a
+ *     scheme left by a different/closed feature does not.
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { validateProjectContextFile } = require('./context');
+
+const EXECUTION_STATE_RELATIVE_PATH = '.aioson/context/workflow-execute.json';
+
+async function readSeededScheme(targetDir) {
+  try {
+    const raw = await fs.readFile(path.join(targetDir, EXECUTION_STATE_RELATIVE_PATH), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function resolveAutopilotSignal(targetDir, { slug = null, projectContext = null } = {}) {
+  let flag;
+  try {
+    const context = projectContext || await validateProjectContextFile(targetDir);
+    flag = context && context.data && Object.prototype.hasOwnProperty.call(context.data, 'auto_handoff')
+      ? context.data.auto_handoff === true
+      : null;
+  } catch {
+    flag = null;
+  }
+
+  const scheme = await readSeededScheme(targetDir);
+  const slugMatches = Boolean(
+    scheme && (!slug || !scheme.feature || String(scheme.feature) === String(slug))
+  );
+
+  // Explicit per-feature disarm (--step) beats the project-wide flag.
+  if (
+    scheme && scheme.agentic_policy && scheme.agentic_policy.enabled === false &&
+    slugMatches
+  ) {
+    return { enabled: false, source: 'scheme_disarmed' };
+  }
+
+  if (flag === true) return { enabled: true, source: 'frontmatter' };
+  if (flag === false) return { enabled: false, source: 'frontmatter_off' };
+
+  const schemeEnabled = Boolean(scheme && scheme.agentic_policy && scheme.agentic_policy.enabled === true);
+  if (!schemeEnabled) return { enabled: false, source: null };
+  if (!slugMatches) return { enabled: false, source: 'scheme_other_feature' };
+  return { enabled: true, source: 'seeded_scheme' };
+}
+
+module.exports = {
+  resolveAutopilotSignal
+};