@jaimevalasek/aioson 1.21.5 → 1.21.6

package/docs/en/1-understand/ecosystem-map.md

@@ -71,8 +71,8 @@
 The default order depends on the classification:
 
 **MICRO:** `@setup → @product (optional) → @dev`
-**SMALL:** `@setup → @product → @sheldon (optional) → @analyst → @architect → @dev → @qa`
-**MEDIUM:** `@setup → @product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa`
+**SMALL:** `@setup → @product → @sheldon (optional) → @analyst → @scope-check → @architect → @dev → @qa`
+**MEDIUM:** `@setup → @product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev → @qa`
 
 > **Why does `@sheldon` appear so early?** It is the **PRD quality guardian** — it runs *between* `@product` and `@analyst` to detect gaps, validate technical assumptions with web research, and decide between enriching the PRD in-place or creating a phased plan in `.aioson/plans/{slug}/`. Can be invoked N times on the same PRD. Skipping this step on serious features is expensive later.
 

package/docs/en/1-understand/glossary.md

@@ -73,7 +73,7 @@ Terms in alphabetical order. Each entry has a **short definition** + **concrete
 
 **How it works:**
 - 0–1 points → **MICRO** (`@setup → @product → @dev`)
-- 2–3 points → **SMALL** (`@setup → @product → @analyst → @architect → @dev → @qa`)
+- 2–3 points → **SMALL** (`@setup → @product → @analyst → @scope-check → @architect → @dev → @qa`)
 - 4–6 points → **MEDIUM** (full workflow, all gates, all artifacts)
 
 **Where it appears:** `classification:` in the `project.context.md` frontmatter.

package/docs/en/2-start/initial-decisions.md

@@ -41,7 +41,7 @@ The sum of three factors (each worth 0, 1, or 2 points):
 - Static portfolio page
 - Mini API with 3 endpoints
 
-#### SMALL — `@setup → @product → @analyst → @architect → @dev → @qa`
+#### SMALL — `@setup → @product → @analyst → @scope-check → @architect → @dev → @qa`
 
 - For: most real apps.
 - Full discovery+development+QA cycle.

package/docs/en/3-recipes/README.md

@@ -8,7 +8,7 @@ These three trails show **how features reach development** in AIOSON. You almost
 
 | Trail | When to use | Key agents |
 |---|---|---|
-| **[Full feature with @sheldon](./full-feature-with-sheldon.md)** | You have a PRD in mind and want the complete canonical trail (most used) | @product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa |
+| **[Full feature with @sheldon](./full-feature-with-sheldon.md)** | You have a PRD in mind and want the complete canonical trail (most used) | @product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev → @qa |
 | [From idea to PRD via @briefing](./from-idea-to-prd-via-briefing.md) | Your idea is still vague, several loose notes | @briefing → @product |
 | [External plans for @product](./external-plans-for-product.md) *(coming soon)* | You already planned in another chat (ChatGPT, Claude.io Web) | @product (reads `/plans/`) |
 

package/docs/en/3-recipes/full-feature-with-sheldon.md

@@ -10,7 +10,7 @@
 ## The trail in one line
 
 ```
-/aioson:agent:product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev
+/aioson:agent:product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev
                                                               │
                                               (@qa ↔ @dev)  ← autonomous loop
                                                               │
@@ -299,7 +299,7 @@ Six months from now, anyone (or any AI) reads these files and understands **ever
 `@product → @dev → @qa`. Skip `@sheldon`, `@analyst`, `@architect`, `@ux-ui`, `@pm`, `@orchestrator`. The Constitution Article II (*Right-Sized Process*) protects you from unnecessary ceremony.
 
 ### SMALL without UI
-`@product → @sheldon → @analyst → @architect → @dev → @qa`. Skip `@ux-ui`, `@pm`, `@orchestrator`.
+`@product → @sheldon → @analyst → @scope-check → @architect → @dev → @qa`. Skip `@ux-ui`, `@pm`, `@orchestrator`.
 
 ### Full MEDIUM
 The complete trail above.

package/docs/en/5-reference/cli-reference.md

@@ -255,7 +255,7 @@ aioson agent:prompt dev --tool=opencode --json
 ```
 
 **Arguments:**
-- `<agent>` — agent id: `setup`, `product`, `analyst`, `architect`, `ux-ui`, `pm`, `dev`, `qa`, `orchestrator`.
+- `<agent>` — agent id: `setup`, `product`, `analyst`, `scope-check`, `architect`, `ux-ui`, `pm`, `dev`, `qa`, `orchestrator`.
 
 **Options:**
 - `--tool=codex|claude|opencode` — formats the prompt for the target CLI. Default: `codex`.
@@ -302,18 +302,18 @@ Notes:
 
 **Sequences by classification:**
 - `MICRO`: `@setup → @product (optional) → @dev`
-- `SMALL`: `@setup → @product → @analyst → @architect → @dev → @qa`
-- `MEDIUM`: `@setup → @product → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa`
+- `SMALL`: `@setup → @product → @analyst → @scope-check → @architect → @dev → @qa`
+- `MEDIUM`: `@setup → @product → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev → @qa`
 
 **Feature development workflow (after initial setup):**
 
 Once the project is set up, each new feature follows a shorter sequence — no `@setup` required:
 
 ```
-/aioson:agent:product → @analyst → @dev → @qa
+/aioson:agent:product → @analyst → @scope-check → @dev → @qa
 ```
 
-`@product` creates a feature-scoped `prd-{slug}.md` and registers the feature in `features.md`. `@analyst` produces `requirements-{slug}.md` and `spec-{slug}.md`. `@dev` reads the feature spec. `@qa` closes the feature by running `feature:close --verdict=PASS`, which updates `spec-{slug}.md` with a QA sign-off, marks it `done` in `features.md`, and automatically archives all feature artefacts to `.aioson/context/done/{slug}/`.
+`@product` creates a feature-scoped `prd-{slug}.md` and registers the feature in `features.md`. `@analyst` produces `requirements-{slug}.md` and `spec-{slug}.md`. `@scope-check` compares intent against the planned implementation before coding. `@dev` reads the feature spec. `@qa` closes the feature by running `feature:close --verdict=PASS`, which updates `spec-{slug}.md` with a QA sign-off, marks it `done` in `features.md`, and automatically archives all feature artefacts to `.aioson/context/done/{slug}/`.
 
 The `SMALL` and MEDIUM outputs include a note reminding you of this sequence.
 

package/docs/en/README.md

@@ -23,7 +23,7 @@ This is the entry door to the English documentation. It is not an alphabetical i
 ### I want a recipe ready for my case
 
 **Canonical trails — how features reach the dev:**
-1. **[Full feature with @sheldon](./3-recipes/full-feature-with-sheldon.md)** — the main trail: `@product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa` (with optional gates from `@tester` and `@pentester`)
+1. **[Full feature with @sheldon](./3-recipes/full-feature-with-sheldon.md)** — the main trail: `@product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev → @qa` (with optional gates from `@tester` and `@pentester`)
 2. [From idea to PRD via @briefing](./3-recipes/from-idea-to-prd-via-briefing.md) — when the idea is still vague
 3. [Continuity between sessions](./3-recipes/continuity-between-sessions.md) — feature dossier, dev-resume, drift detection
 

package/docs/pt/1-entender/glossario.md

@@ -73,7 +73,7 @@ Termos em ordem alfabética. Cada um tem **definição curta** + **exemplo concr
 
 **Como funciona:**
 - 0–1 ponto → **MICRO** (`@setup → @product → @dev`)
-- 2–3 pontos → **SMALL** (`@setup → @product → @analyst → @architect → @dev → @qa`)
+- 2–3 pontos → **SMALL** (`@setup → @product → @analyst → @scope-check → @architect → @dev → @qa`)
 - 4–6 pontos → **MEDIUM** (workflow completo, todos os gates, todos os artefatos)
 
 **Onde aparece:** `classification:` no frontmatter do `project.context.md`.

package/docs/pt/1-entender/mapa-do-ecossistema.md

@@ -71,8 +71,8 @@
 A ordem padrão depende da classificação:
 
 **MICRO:** `@setup → @product (opcional) → @dev`
-**SMALL:** `@setup → @product → @sheldon (opcional) → @analyst → @architect → @dev → @qa`
-**MEDIUM:** `@setup → @product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa`
+**SMALL:** `@setup → @product → @sheldon (opcional) → @analyst → @scope-check → @architect → @dev → @qa`
+**MEDIUM:** `@setup → @product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev → @qa`
 
 > **Por que `@sheldon` aparece tão cedo?** Ele é o **PRD quality guardian** — roda *entre* `@product` e `@analyst` para detectar gaps, validar premissas técnicas com pesquisa web, e decidir entre enriquecer o PRD in-place ou criar um phased plan em `.aioson/plans/{slug}/`. Pode ser invocado N vezes no mesmo PRD. Pular essa etapa em features sérias custa caro lá na frente.
 

package/docs/pt/2-comecar/decisoes-iniciais.md

@@ -41,7 +41,7 @@ Soma de três fatores (cada um vale 0, 1 ou 2 pontos):
 - Página estática de portfólio
 - Mini-API de 3 endpoints
 
-#### SMALL — `@setup → @product → @analyst → @architect → @dev → @qa`
+#### SMALL — `@setup → @product → @analyst → @scope-check → @architect → @dev → @qa`
 
 - Para: a maioria dos apps reais.
 - Tem o ciclo completo de discovery+desenvolvimento+QA.

package/docs/pt/3-receitas/README.md

@@ -8,7 +8,7 @@ Estas três trilhas mostram **como features chegam ao desenvolvimento** no AIOSO
 
 | Trilha | Quando usar | Agentes-chave |
 |---|---|---|
-| **[Feature completa com @sheldon](./feature-completa-com-sheldon.md)** | Você tem PRD em mente e quer a trilha canônica completa (a mais usada) | @product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa |
+| **[Feature completa com @sheldon](./feature-completa-com-sheldon.md)** | Você tem PRD em mente e quer a trilha canônica completa (a mais usada) | @product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev → @qa |
 | [Da ideia ao PRD via @briefing](./da-ideia-ao-prd-via-briefing.md) | Sua ideia ainda é vaga, várias anotações soltas | @briefing → @product |
 | [Plans externos para @product](./plans-externos-para-product.md) | Você já planejou em outro chat (ChatGPT, Claude.io Web) | @product (lê `/plans/`) |
 

package/docs/pt/3-receitas/feature-completa-com-sheldon.md

@@ -10,7 +10,7 @@
 ## A trilha em uma linha
 
 ```
-@product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev
+@product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev
                                                               │
                                               (@qa ↔ @dev)  ← ciclo autônomo
                                                               │
@@ -299,7 +299,7 @@ Daqui a 6 meses, qualquer pessoa (ou IA) lê esses arquivos e entende **tudo**:
 `@product → @dev → @qa`. Pule `@sheldon`, `@analyst`, `@architect`, `@ux-ui`, `@pm`, `@orchestrator`. A Constitution Article II (*Right-Sized Process*) protege você de cerimônia desnecessária.
 
 ### SMALL sem UI
-`@product → @sheldon → @analyst → @architect → @dev → @qa`. Pule `@ux-ui`, `@pm`, `@orchestrator`.
+`@product → @sheldon → @analyst → @scope-check → @architect → @dev → @qa`. Pule `@ux-ui`, `@pm`, `@orchestrator`.
 
 ### MEDIUM puro
 A trilha completa acima.

package/docs/pt/5-referencia/comandos-cli.md

@@ -521,8 +521,8 @@ Importante:
 - `scan:project` sozinho nao gera `discovery.md`
 - `scan:project` nunca gera `architecture.md`
 - se `discovery.md` e `skeleton-system.md` ja existirem e voce rodar com `--with-llm`, o scanner agora entra em modo de atualizacao por padrao: usa os arquivos atuais como memoria base, gera a nova versao consolidada e cria backup automatico em `.aioson/backups/` antes de sobrescrever
-- em projetos SMALL brownfield, o fluxo tipico depois do scan completo e `@analyst` -> `@architect` -> `@dev`
-- sem API LLM configurada, o fluxo local tambem e valido: `scan:project --folder=...` -> `@analyst` no seu Codex/Claude -> `@architect` -> `@dev`
+- em projetos SMALL brownfield, o fluxo tipico depois do scan completo e `@analyst` -> `@scope-check` -> `@architect` -> `@dev`
+- sem API LLM configurada, o fluxo local tambem e valido: `scan:project --folder=...` -> `@analyst` no seu Codex/Claude -> `@scope-check` -> `@architect` -> `@dev`
 
 O parâmetro `--folder` agora é obrigatório. Ele define quais pastas do projeto devem ganhar um mapa completo com pastas e arquivos. Você pode informar uma pasta ou várias separadas por vírgula.
 
@@ -574,8 +574,8 @@ Quando usar cada modo:
 
 Fluxos recomendados:
 
-- **Com API no aioson:** `scan:project --folder=src --with-llm --provider=...` -> `@analyst` -> `@architect` -> `@dev`
-- **Sem API no aioson:** `scan:project --folder=src` -> abrir seu AI CLI -> `@analyst` -> `@architect` -> `@dev`
+- **Com API no aioson:** `scan:project --folder=src --with-llm --provider=...` -> `@analyst` -> `@scope-check` -> `@architect` -> `@dev`
+- **Sem API no aioson:** `scan:project --folder=src` -> abrir seu AI CLI -> `@analyst` -> `@scope-check` -> `@architect` -> `@dev`
 - **Com contexto mínimo para tarefa específica:** `scan:project --folder=src` -> `context:pack --agent=dev --goal="..." --module=src`
 - Se o seu cliente nao entender `@analyst`, gere um prompt pronto com `aioson agent:prompt analyst --tool=codex` ou troque `--tool` para o cliente correto
 

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 → @dev → @qa` (com gates opcionais de `@tester` e `@pentester`)
+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`)
 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.21.5",
+  "version": "1.21.6",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",

package/src/commands/agents.js

@@ -20,17 +20,51 @@ const { readAutonomyProtocol, resolveEffectiveMode } = require('../autonomy-poli
 const { readAgentManifest, buildAgentCapabilitySummary } = require('../agent-manifests');
 const { emitSecurityRuntimeEvent } = require('../lib/security/runtime-events');
 
-const WORKFLOW_AGENT_IDS = new Set([
-  'setup',
-  'product',
-  'analyst',
-  'architect',
+const WORKFLOW_AGENT_IDS = new Set([
+  'setup',
+  'product',
+  'analyst',
+  'scope-check',
+  'architect',
   'ux-ui',
   'pm',
   'orchestrator',
   'dev',
-  'qa'
-]);
+  'qa'
+]);
+const SCOPE_CHECK_MODES = new Set(['pre-dev', 'post-dev', 'post-fix', 'final']);
+
+function normalizeScopeCheckMode(input) {
+  const mode = String(input || '').trim().toLowerCase();
+  return SCOPE_CHECK_MODES.has(mode) ? mode : null;
+}
+
+function getScopeCheckModeOption(options = {}) {
+  return normalizeScopeCheckMode(
+    options.scopeMode ||
+    options['scope-mode'] ||
+    options.checkMode ||
+    options['check-mode'] ||
+    options.mode
+  );
+}
+
+function buildScopeCheckActivationContext(options = {}) {
+  const mode = getScopeCheckModeOption(options) || 'pre-dev';
+  const lines = [`Scope-check mode: ${mode}.`];
+  const featureSlug = String(options.feature || options.slug || '').trim();
+  if (featureSlug) lines.push(`Feature slug: ${featureSlug}.`);
+  if (mode === 'pre-dev') {
+    lines.push('Compare user intent against planning artifacts before implementation.');
+  } else if (mode === 'post-dev') {
+    lines.push('Compare the approved planning artifacts against the actual implementation diff and changed files before QA.');
+  } else if (mode === 'post-fix') {
+    lines.push('Compare approved scope, QA/tester/pentester findings, and correction diff; confirm the fix did not change product intent.');
+  } else if (mode === 'final') {
+    lines.push('Reconcile intent, plan, delivered behavior, and remaining exclusions before close/commit/release.');
+  }
+  return lines.join('\n');
+}
 
 function normalizePentesterTargetMode(input) {
   const mode = String(input || '').trim().toLowerCase();
@@ -173,10 +207,12 @@ async function runAgentPrompt({ args, options, logger, t }) {
 
   if (!prompt) {
     instructionPath = await resolveExistingInstructionPath(targetDir, promptAgent, locale);
-    if (promptAgent.id === 'pentester') {
-      pentesterTargetMode = normalizePentesterTargetMode(options.mode);
-      activationContext = buildPentesterActivationContext(options, t);
-    }
+    if (promptAgent.id === 'pentester') {
+      pentesterTargetMode = normalizePentesterTargetMode(options.mode);
+      activationContext = buildPentesterActivationContext(options, t);
+    } else if (promptAgent.id === 'scope-check') {
+      activationContext = buildScopeCheckActivationContext(options);
+    }
     const autonomyProtocol = await readAutonomyProtocol(targetDir);
     const manifest = await readAgentManifest(targetDir, promptAgent.id);
     effectiveMode = resolveEffectiveMode({
@@ -184,7 +220,7 @@ async function runAgentPrompt({ args, options, logger, t }) {
       tool,
       agentId: promptAgent.id,
       manifest,
-      requestedMode: options.mode || null
+      requestedMode: promptAgent.id === 'scope-check' && getScopeCheckModeOption(options) ? null : options.mode || null
     });
     prompt = buildAgentPrompt(promptAgent, tool, {
       instructionPath,

package/src/commands/workflow-next.js

@@ -26,15 +26,16 @@ const { emitDossierEvent } = require('../lib/dossier-telemetry');
 
 const STATE_RELATIVE_PATH = '.aioson/context/workflow.state.json';
 const CONFIG_RELATIVE_PATH = '.aioson/context/workflow.config.json';
-const EVENTS_RELATIVE_PATH = '.aioson/context/workflow.events.jsonl';
+const EVENTS_RELATIVE_PATH = '.aioson/context/workflow.events.jsonl';
+const SCOPE_CHECK_MODES = new Set(['pre-dev', 'post-dev', 'post-fix', 'final']);
 
 const DEFAULT_FEATURE_WORKFLOW_BY_CLASSIFICATION = {
   MICRO: ['product', 'dev', 'qa'],
-  SMALL: ['product', 'analyst', 'architect', 'discovery-design-doc', 'dev', 'qa'],
-  MEDIUM: ['product', 'analyst', 'architect', 'discovery-design-doc', 'dev', 'pentester', 'qa']
+  SMALL: ['product', 'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'dev', 'qa'],
+  MEDIUM: ['product', 'analyst', 'architect', 'discovery-design-doc', 'scope-check', 'dev', 'pentester', 'qa']
 };
 
-function normalizeAgentName(input) {
+function normalizeAgentName(input) {
   return String(input || '')
     .trim()
     .toLowerCase()
@@ -52,8 +53,8 @@ function buildDefaultWorkflowConfig() {
     version: 1,
     project: {
       MICRO: ['setup', 'dev'],
-      SMALL: ['setup', 'product', 'analyst', 'architect', 'discovery-design-doc', 'dev', 'qa'],
-      MEDIUM: ['setup', 'product', 'analyst', 'architect', 'discovery-design-doc', 'ux-ui', 'pm', 'orchestrator', 'dev', 'qa']
+      SMALL: ['setup', 'product', 'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'dev', 'qa'],
+      MEDIUM: ['setup', 'product', 'analyst', 'architect', 'discovery-design-doc', 'ux-ui', 'pm', 'orchestrator', 'scope-check', 'dev', 'qa']
     },
     feature: DEFAULT_FEATURE_WORKFLOW_BY_CLASSIFICATION,
     rules: {
@@ -82,6 +83,21 @@ function parseFeaturesMarkdown(markdown) {
     .filter((row) => !/^-+$/ .test(row.slug));
 }
 
+function normalizeScopeCheckMode(input) {
+  const mode = String(input || '').trim().toLowerCase();
+  return SCOPE_CHECK_MODES.has(mode) ? mode : null;
+}
+
+function getScopeCheckModeOption(options = {}) {
+  return normalizeScopeCheckMode(
+    options.scopeMode ||
+    options['scope-mode'] ||
+    options.checkMode ||
+    options['check-mode'] ||
+    options.mode
+  );
+}
+
 function chooseActiveFeature(features, preferredSlug = null) {
   const activeFeatures = (features || []).filter((feature) => feature.status === 'in_progress');
   if (preferredSlug) {
@@ -253,18 +269,25 @@ async function validateStageArtifacts(targetDir, state, stage) {
     return await exists(path.join(base, 'prd.md'));
   }
 
-  if (stage === 'analyst') {
-    if (state.mode === 'feature' && slug) {
-      const requirements = path.join(base, `requirements-${slug}.md`);
-      const spec = path.join(base, `spec-${slug}.md`);
-      return (await exists(requirements)) && (await exists(spec));
-    }
-    return await exists(path.join(base, 'discovery.md'));
-  }
-
-  if (stage === 'architect') {
-    return await exists(path.join(base, 'architecture.md'));
-  }
+  if (stage === 'analyst') {
+    if (state.mode === 'feature' && slug) {
+      const requirements = path.join(base, `requirements-${slug}.md`);
+      const spec = path.join(base, `spec-${slug}.md`);
+      return (await exists(requirements)) && (await exists(spec));
+    }
+    return await exists(path.join(base, 'discovery.md'));
+  }
+
+  if (stage === 'scope-check') {
+    if (state.mode === 'feature' && slug) {
+      return await exists(path.join(base, `scope-check-${slug}.md`));
+    }
+    return await exists(path.join(base, 'scope-check.md'));
+  }
+
+  if (stage === 'architect') {
+    return await exists(path.join(base, 'architecture.md'));
+  }
 
   if (stage === 'ux-ui') {
     return await exists(path.join(base, 'ui-spec.md'));
@@ -403,11 +426,11 @@ function reconcileWorkflowState(state) {
   };
 }
 
-function isInferableStage(stage) {
-  return ['setup', 'product', 'analyst', 'architect', 'ux-ui', 'orchestrator'].includes(
-    normalizeAgentName(stage)
-  );
-}
+function isInferableStage(stage) {
+  return ['setup', 'product', 'analyst', 'scope-check', 'architect', 'ux-ui', 'orchestrator'].includes(
+    normalizeAgentName(stage)
+  );
+}
 
 function isSecurityGateBlocked(contractCheck, state, stageName) {
   if (normalizeAgentName(stageName) !== 'qa' || state.mode !== 'feature' || !state.featureSlug) {
@@ -905,6 +928,36 @@ function normalizeContextDependency(relPath) {
 }
 
 async function resolveStageDependencies(targetDir, state, stageName, agent) {
+  if (stageName === 'scope-check') {
+    const contextDir = path.join(targetDir, '.aioson', 'context');
+    const slug = state.featureSlug;
+    const candidates = [
+      'project.context.md',
+      'features.md',
+      slug ? `prd-${slug}.md` : 'prd.md',
+      slug ? `requirements-${slug}.md` : 'discovery.md',
+      slug ? `spec-${slug}.md` : 'spec.md',
+      slug ? `sheldon-enrichment-${slug}.md` : 'sheldon-enrichment.md',
+      'architecture.md',
+      slug ? `design-doc-${slug}.md` : null,
+      slug ? `readiness-${slug}.md` : null,
+      'design-doc.md',
+      'readiness.md',
+      'ui-spec.md',
+      slug ? `implementation-plan-${slug}.md` : 'implementation-plan.md',
+      'dev-state.md',
+      'last-handoff.json',
+      'project-pulse.md'
+    ].filter(Boolean);
+    const existing = [];
+    for (const candidate of candidates) {
+      if (await exists(path.join(contextDir, candidate))) {
+        existing.push(normalizeContextDependency(candidate));
+      }
+    }
+    return existing.length > 0 ? existing : agent.dependsOn;
+  }
+
   if (stageName === 'discovery-design-doc') {
     const contextDir = path.join(targetDir, '.aioson', 'context');
     const slug = state.featureSlug;
@@ -956,6 +1009,8 @@ async function resolveStageDependencies(targetDir, state, stageName, agent) {
     `readiness-${slug}.md`,
     'design-doc.md',
     'readiness.md',
+    `scope-check-${slug}.md`,
+    'scope-check.md',
     `implementation-plan-${slug}.md`
   ];
   const existing = [];
@@ -967,7 +1022,41 @@ async function resolveStageDependencies(targetDir, state, stageName, agent) {
   return existing.length > 0 ? existing : agent.dependsOn;
 }
 
-function buildStageActivationContext(state, stageName, dependencies) {
+function inferScopeCheckMode(state, requestedMode = null) {
+  if (requestedMode) return requestedMode;
+  const completed = Array.isArray(state.completed) ? state.completed.map(normalizeAgentName) : [];
+  const current = normalizeAgentName(state.current || state.next);
+  if (completed.includes('dev')) return 'post-dev';
+  if (completed.includes('qa') || completed.includes('tester') || completed.includes('pentester')) return 'post-fix';
+  if (current === 'scope-check') return 'pre-dev';
+  return 'pre-dev';
+}
+
+function buildScopeCheckActivationContext(state, mode) {
+  const resolvedMode = inferScopeCheckMode(state, mode);
+  const lines = [
+    `Scope-check mode: ${resolvedMode}`,
+    `Workflow mode: ${state.mode || 'unknown'}`,
+    `Classification: ${state.classification || 'unknown'}`
+  ];
+  if (state.featureSlug) lines.push(`Feature slug: ${state.featureSlug}`);
+  if (resolvedMode === 'pre-dev') {
+    lines.push('Compare user intent against planning artifacts before implementation.');
+  } else if (resolvedMode === 'post-dev') {
+    lines.push('Compare the approved scope-check/design artifacts against the actual implementation diff and changed files before QA.');
+  } else if (resolvedMode === 'post-fix') {
+    lines.push('Compare approved scope, QA/tester/pentester findings, and the correction diff; confirm the fix did not change product intent.');
+  } else if (resolvedMode === 'final') {
+    lines.push('Reconcile intent, plan, delivered behavior, and remaining exclusions before close/commit/release.');
+  }
+  return lines.join('\n');
+}
+
+function buildStageActivationContext(state, stageName, dependencies, scopeCheckMode = null) {
+  if (stageName === 'scope-check') {
+    return buildScopeCheckActivationContext(state, scopeCheckMode);
+  }
+
   if (stageName !== 'dev' || state.mode !== 'feature' || !state.featureSlug) return '';
   return [
     `Feature slug: ${state.featureSlug}`,
@@ -979,7 +1068,7 @@ function buildStageActivationContext(state, stageName, dependencies) {
   ].join('\n');
 }
 
-async function activateStage(targetDir, state, locale, tool, explicitAgent = null, requestedMode = null) {
+async function activateStage(targetDir, state, locale, tool, explicitAgent = null, requestedMode = null, scopeCheckMode = null) {
   const stageName = normalizeAgentName(explicitAgent || state.current || state.next);
   if (!stageName) {
     return {
@@ -1087,7 +1176,7 @@ async function activateStage(targetDir, state, locale, tool, explicitAgent = nul
     autonomyMode: effectiveMode,
     capabilitySummary: buildAgentCapabilitySummary(agentManifest, tool),
     dependsOn: dependencies,
-    activationContext: buildStageActivationContext(state, stageName, dependencies)
+    activationContext: buildStageActivationContext(state, stageName, dependencies, scopeCheckMode)
   });
 
   if (testBriefing) {
@@ -1358,7 +1447,10 @@ async function runWorkflowNext({ args, options, logger, t }) {
     requestedAgent = 'validator';
   }
 
-  const activation = await activateStage(targetDir, state, locale, tool, requestedAgent, options.mode || null);
+  const activationAgent = normalizeAgentName(requestedAgent || state.current || state.next);
+  const scopeCheckMode = activationAgent === 'scope-check' ? getScopeCheckModeOption(options) : null;
+  const requestedAutonomyMode = scopeCheckMode && activationAgent === 'scope-check' ? null : options.mode || null;
+  const activation = await activateStage(targetDir, state, locale, tool, requestedAgent, requestedAutonomyMode, scopeCheckMode);
   state = activation.state;
 
   // ── Living Memory: if a reflect manifest is pending (created above by the

package/src/commands/workflow-plan.js

@@ -3,11 +3,11 @@
 const path = require('node:path');
 const { validateProjectContextFile } = require('../context');
 
-const WORKFLOW_BY_CLASSIFICATION = {
-  MICRO: ['setup', 'dev'],
-  SMALL: ['setup', 'product', 'analyst', 'architect', 'dev', 'qa'],
-  MEDIUM: ['setup', 'product', 'analyst', 'architect', 'ux-ui', 'pm', 'orchestrator', 'dev', 'qa']
-};
+const WORKFLOW_BY_CLASSIFICATION = {
+  MICRO: ['setup', 'dev'],
+  SMALL: ['setup', 'product', 'analyst', 'scope-check', 'architect', 'dev', 'qa'],
+  MEDIUM: ['setup', 'product', 'analyst', 'architect', 'ux-ui', 'pm', 'orchestrator', 'scope-check', 'dev', 'qa']
+};
 
 function normalizeClassification(value, fallback = 'MICRO') {
   const text = String(value || '').trim().toUpperCase();

package/src/commands/workflow-status.js

@@ -427,11 +427,20 @@ async function runWorkflowStatus({ args, options, logger, t }) {
     if (handoff) {
       logger.log('Last handoff:');
       if (handoff.last_agent) logger.log(`  Agent: ${handoff.last_agent}`);
-      if (handoff.what_was_done) logger.log(`  Done: ${handoff.what_was_done}`);
-      if (handoff.what_comes_next) logger.log(`  Next: ${handoff.what_comes_next}`);
-      if (handoff.session_ended_at) logger.log(`  When: ${timeSince(handoff.session_ended_at)} ago`);
-      logger.log('');
-    }
+      if (handoff.what_was_done) logger.log(`  Done: ${handoff.what_was_done}`);
+      if (handoff.what_comes_next) logger.log(`  Next: ${handoff.what_comes_next}`);
+      if (Array.isArray(handoff.optional_handoffs) && handoff.optional_handoffs.length > 0) {
+        logger.log('  Optional handoffs:');
+        for (const optional of handoff.optional_handoffs) {
+          const label = optional.agent || '@unknown';
+          const mode = optional.mode ? ` (${optional.mode})` : '';
+          const command = optional.command ? ` — ${optional.command}` : '';
+          logger.log(`    - ${label}${mode}${command}`);
+        }
+      }
+      if (handoff.session_ended_at) logger.log(`  When: ${timeSince(handoff.session_ended_at)} ago`);
+      logger.log('');
+    }
 
     if (handoffProtocol) {
       logger.log('Handoff protocol:');

package/src/constants.js

@@ -6,10 +6,11 @@ const MANAGED_FILES = [
   'OPENCODE.md',
   '.aioson/config.md',
   '.aioson/agents/setup.md',
-  '.aioson/agents/discovery-design-doc.md',
-  '.aioson/agents/discover.md',
-  '.aioson/agents/analyst.md',
-  '.aioson/agents/architect.md',
+  '.aioson/agents/discovery-design-doc.md',
+  '.aioson/agents/discover.md',
+  '.aioson/agents/analyst.md',
+  '.aioson/agents/scope-check.md',
+  '.aioson/agents/architect.md',
   '.aioson/agents/ux-ui.md',
   '.aioson/agents/product.md',
   '.aioson/agents/deyvin.md',
@@ -59,10 +60,13 @@ const MANAGED_FILES = [
   '.aioson/docs/dev/stack-conventions.md',
   '.aioson/docs/dev/execution-discipline.md',
   '.aioson/docs/quality/code-health-analysis.md',
-  '.aioson/skills/process/decision-presentation/SKILL.md',
-  '.aioson/skills/process/decision-presentation/references/jargon-map.en.yaml',
-  '.aioson/skills/process/decision-presentation/references/jargon-map.pt-BR.yaml',
-  '.aioson/skills/static/laravel-conventions.md',
+  '.aioson/skills/process/decision-presentation/SKILL.md',
+  '.aioson/skills/process/decision-presentation/references/jargon-map.en.yaml',
+  '.aioson/skills/process/decision-presentation/references/jargon-map.pt-BR.yaml',
+  '.aioson/skills/process/prompt-sharpener/SKILL.md',
+  '.aioson/skills/process/prompt-sharpener/references/prompt-diagnostics.md',
+  '.aioson/skills/process/prompt-sharpener/agents/openai.yaml',
+  '.aioson/skills/static/laravel-conventions.md',
   '.aioson/skills/static/tall-stack-patterns.md',
   '.aioson/skills/static/jetstream-setup.md',
   '.aioson/skills/static/rails-conventions.md',
@@ -213,17 +217,30 @@ const AGENT_DEFINITIONS = [
     dependsOn: ['.aioson/context/project.context.md'],
     output: 'small code changes + continuity notes in spec.md + runtime logs/tasks'
   },
-  {
-    id: 'analyst',
-    displayName: 'Analyst',
-    description: 'Domain discovery and entity mapping (SMALL/MEDIUM)',
-    command: '@analyst',
-    path: '.aioson/agents/analyst.md',
-    dependsOn: ['.aioson/context/project.context.md'],
-    output: '.aioson/context/discovery.md'
-  },
-  {
-    id: 'architect',
+  {
+    id: 'analyst',
+    displayName: 'Analyst',
+    description: 'Domain discovery and entity mapping (SMALL/MEDIUM)',
+    command: '@analyst',
+    path: '.aioson/agents/analyst.md',
+    dependsOn: ['.aioson/context/project.context.md'],
+    output: '.aioson/context/discovery.md'
+  },
+  {
+    id: 'scope-check',
+    displayName: 'Scope Check',
+    description: 'Scope alignment before development and optional post-dev drift checks',
+    command: '@scope-check',
+    path: '.aioson/agents/scope-check.md',
+    dependsOn: [
+      '.aioson/context/project.context.md',
+      '.aioson/context/prd.md or .aioson/context/prd-{slug}.md',
+      '.aioson/context/discovery.md or .aioson/context/requirements-{slug}.md + .aioson/context/spec-{slug}.md'
+    ],
+    output: '.aioson/context/scope-check.md or .aioson/context/scope-check-{slug}.md'
+  },
+  {
+    id: 'architect',
     displayName: 'Architect',
     description: 'Project structure and technical decisions (SMALL/MEDIUM)',
     command: '@architect',