sinapse-ai 1.20.1 → 1.22.0

package/.claude/rules/safe-collaboration.md

@@ -1,185 +1,44 @@
 # Safe Collaboration — Git Safety Net (NON-NEGOTIABLE)
 
 > **Applies to ALL agents, ALL projects using SINAPSE.**
-> Users are product builders, NOT git experts.
-> Agents MUST handle ALL git complexity automatically and safely.
+> Users are product builders, NOT git experts. Agents handle ALL git complexity.
+> This is the always-on CORE (the law). Operational detail (branch naming tables,
+> step-by-step checklists, conflict matrices, communication templates) lives in
+> `safe-collaboration-reference.md` and loads when you work on files.
 
 ## Golden Rule
 
 **Users focus on WHAT to build. Agents handle HOW to save and share it safely.**
-
-Users should NEVER need to:
-- Resolve merge conflicts manually
-- Decide which branch to use
-- Remember to pull before working
-- Worry about overwriting each other's code
-- Understand git rebase, cherry-pick, or force-push
-
-## Automatic Safety Protocol (every session)
-
-### 1. Session Start — Auto-Sync (MANDATORY)
-
-Before ANY work begins in a session, the agent MUST:
-
-```
-1. git fetch origin
-2. Check if local main is behind origin/main
-3. If behind → git pull origin main (fast-forward only)
-4. If diverged → STOP, inform user, resolve safely
-5. Create work branch if not already on one
-6. Verify branch protection is active on main
-```
-
-**NEVER start work on `main` directly.** Always create a feature branch.
-
-### 2. Branch Naming — Automatic
-
-The agent creates the branch. The user never needs to name it.
-
-| Who | Branch Pattern | Example |
-|-----|---------------|---------|
-| Caio's session | `caio/{type}/{short-desc}` | `caio/feat/installer-ux` |
-| Matheus's session | `soier/{type}/{short-desc}` | `soier/fix/agent-config` |
-| AI agent | `agent/{squad}/{agent-id}/{type}-{desc}` | `agent/core/pixel/feat-dark-mode` |
-| Unknown | `dev/{type}/{short-desc}` | `dev/feat/new-feature` |
-
-Types: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`
-
-**User Detection (priority order):**
-1. `git config user.name` -> lookup in mapping table (case-insensitive)
-2. `$USERNAME` (Windows) or `$USER` (Unix) -> lookup in mapping table
-3. Fallback: `dev/`
-
-**Mapping Table:**
-
-| git config / env var contains | Branch prefix |
-|-------------------------------|---------------|
-| caio (case-insensitive)       | `caio/`       |
-| matheus OR soier              | `soier/`      |
-| (anything else)               | `dev/`        |
-
-### 3. Before Every Commit — Safety Checks (MANDATORY)
-
-```
-1. git status — verify only expected files changed
-2. git diff --stat — show summary to user
-3. SECRET SCAN — reject if ANY of these are staged:
-   - .env files (except .env.example with placeholders)
-   - Files containing API keys, tokens, passwords in plaintext
-   - Private keys (RSA, SSH, PGP)
-   - Database connection strings with credentials
-   - Webhook URLs with embedded tokens
-4. Commit with conventional message + story reference
-```
-
-**If secrets detected → BLOCK commit, warn user, remove file from staging.**
-
-### 4. Before Push — Conflict Prevention (MANDATORY)
-
-```
-1. git fetch origin main
-2. git merge origin/main --no-edit (into feature branch)
-3. If conflicts → AGENT resolves them (not the user)
-   - For simple conflicts (whitespace, imports): auto-resolve
-   - For complex conflicts: show both versions, ask user which to keep
-4. Run tests after merge
-5. Only then: git push origin {branch}
-```
-
-### 5. PR Creation — Automatic
-
-After push, the agent MUST:
-```
-1. gh pr create with clear title and description (uses PR template)
-2. Auto-assign reviewer based on who is pushing:
-   - Maintainer's PR → can merge directly (admin bypass)
-   - Collaborator's PR → assign maintainer as reviewer (required approval)
-3. Inform the user: "PR criado"
-```
-
-### 6. After PR Merge — Cleanup
-
-```
-1. git checkout main
-2. git pull origin main
-3. Delete local feature branch
-4. Inform user: "Branch limpa, pronto para proximo trabalho"
-```
-
-## Conflict Resolution Rules
-
-| Scenario | Agent Action |
-|----------|-------------|
-| Same file, different sections | Auto-merge (git handles) |
-| Same file, same lines | Show diff, ask user which version to keep |
-| Package.json version conflict | Always take higher version |
-| Generated files (lock, build) | Regenerate after merge |
-| Story/doc files | Merge both contents (additive) |
-
-**NEVER use `--force` push. Use `--force-with-lease` ONLY as last resort with user confirmation.**
-
-## Communication Protocol
-
-When working in parallel, agents MUST inform users about:
-
-| Event | Message |
-|-------|---------|
-| Session start | "Atualizando seu projeto... X mudancas novas do {outro}." |
-| Branch created | "Criada area segura para trabalhar: `caio/feat/xxx`" |
-| Pre-push conflict found | "{outro} mudou {file}. Resolvendo automaticamente..." |
-| Secret detected | "BLOQUEADO: encontrei {tipo} em {file}. Removendo antes de salvar." |
-| PR created | "Enviei para revisao. {outro} precisa aprovar no GitHub." |
-| PR merged by other | "{outro} aprovou suas mudancas. Atualizando seu projeto..." |
-
-## Destructive Operations — BLOCKED BY DEFAULT
-
-These operations require EXPLICIT user confirmation before execution:
-
-| Operation | Risk | Confirmation Required |
-|-----------|------|----------------------|
-| `git push --force` / `--force-with-lease` | Overwrite remote history | YES + explain risk |
-| `git reset --hard` | Destroy local uncommitted work | YES + explain risk |
-| `git branch -D` | Delete branch with unmerged commits | YES + explain risk |
-| `git clean -f` | Delete untracked files permanently | YES + explain risk |
-| Delete remote branch | Affects other collaborators | YES |
+Users NEVER resolve conflicts, pick branches, remember to pull, or touch rebase/force-push.
+
+## The Law (every session, every commit, every push)
+
+1. **Session start — auto-sync (MANDATORY):** `git fetch origin` → sync local with
+   origin (fast-forward; if diverged → STOP and resolve safely) → create a work
+   branch. **NEVER start work on `main` directly.**
+2. **Auto-branch:** the agent creates and names the branch (`{user}/{type}/{desc}`);
+   the user never needs to.
+3. **Before every commit:** `git status` first; **SECRET SCAN — if any secret,
+   credential, key, or real `.env` is staged → BLOCK the commit**, warn, unstage.
+4. **Before push:** fetch + merge `origin/main` into the feature branch; the AGENT
+   resolves conflicts (simple → auto; complex → show both versions, ask which to
+   keep); run tests after merging; only then push.
+5. **After push:** create the PR automatically with reviewer assignment; after
+   merge, clean up and re-sync.
+6. **Destructive operations are BLOCKED by default** (`--force`, `reset --hard`,
+   `branch -D`, `clean -f`, deleting remote branches): they require EXPLICIT user
+   confirmation plus a risk explanation. **NEVER `push --force`**;
+   `--force-with-lease` only as a last resort with user confirmation.
 
 ## Anti-Patterns (FORBIDDEN)
 
-- Letting user work on `main` directly
-- Pushing to `main` without PR (branch protection enforces this)
-- Ignoring `git fetch` at session start
-- Letting conflicts accumulate (merge frequently)
-- Using `git push --force` without explicit user confirmation
-- Assuming the other person isn't working on the same area
-- Committing without checking `git status` first
+- Letting the user work on `main` directly, or pushing to `main` without a PR
+- Skipping `git fetch` at session start; letting conflicts accumulate
+- Committing without checking `git status`; committing secrets or credentials
 - Skipping tests after resolving conflicts
-- Committing files containing secrets or credentials
-- Running destructive git operations without user confirmation
-
-## For Projects Using SINAPSE (not just sinapse-ai repo)
-
-These same rules apply to ANY project where SINAPSE agents operate:
-1. Auto-branch before work
-2. Auto-sync before starting
-3. Secret scan before every commit
-4. Auto-resolve simple conflicts
-5. Auto-PR with reviewer assignment
-6. User never touches git directly
-
-## User Cheat Sheet (the ONLY things users do manually)
-
-```
-! git push origin main          ← when agent can't push (hook block)
-! npm publish                   ← when publishing to NPM
-```
-
-Everything else: **ask the agent to do it.**
-
-## PR Quality Standards
-
-| Metric | Target | Warning |
-|--------|--------|---------|
-| PR size | < 200 lines | > 400 lines |
-| PR cycle time | < 1 day | > 3 days |
+- Running destructive git operations without explicit user confirmation
+- Assuming the other person isn't working on the same area
 
-**DORA Targets (Elite):** Deploy multiple/day, lead time < 1 day, failure rate < 4%, recovery < 1 hour.
+> **Detail (loads on file work):** branch naming + user-detection tables, per-phase
+> checklists, conflict-resolution matrix, communication protocol messages, PR
+> quality/DORA targets, user cheat sheet — see `safe-collaboration-reference.md`.

package/.sinapse-ai/core/doctor/checks/index.js

@@ -1,7 +1,7 @@
 /**
  * Doctor Check Registry
  *
- * Exports all 15 check modules in execution order.
+ * Exports all 16 default check modules (plus 1 deep-only) in execution order.
  *
  * @module sinapse-ai/doctor/checks
  * @story INS-4.1, INS-4.8

package/.sinapse-ai/core/execution/build-orchestrator.js

@@ -87,9 +87,10 @@ const DEFAULT_CONFIG = {
   globalTimeout: 45 * 60 * 1000, // 45 minutes
   subtaskTimeout: 10 * 60 * 1000, // 10 minutes per subtask
 
-  // Epic 10: Parallel Execution
-  parallelMode: false, // Enable wave-based parallel execution
-  maxParallel: 4, // Max concurrent tasks per wave
+  // NOTE: dead `parallelMode`/`maxParallel` flags lived here (Epic 10) — never
+  // read by this orchestrator (waves were measured and rejected; see
+  // docs/epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md). Removed
+  // with `useSubagentDispatch` rationale below (AF-20260704 Lote B).
   // NOTE: a dead `useSubagentDispatch` flag lived here — it was never read.
   // Agent routing happens one level up: epic-4 delegates to this BuildOrchestrator,
   // which builds via executeSubtaskWithClaude. Removed to kill the false affordance

package/.sinapse-ai/core/execution/subagent-dispatcher.js

@@ -262,8 +262,8 @@ class SubagentDispatcher extends EventEmitter {
       return this.agentMapping[task.type.toLowerCase()];
     }
 
-    // F2: if the task names a real agent id directly (any of the 189 squad/
-    // framework personas), honor it instead of inferring a generic one.
+    // F2: if the task names a real agent id directly (any squad/framework
+    // persona known to the resolver), honor it instead of inferring a generic one.
     if (this.agentResolver && task.name && this.agentResolver.has(task.name)) {
       return `@${this.agentResolver.resolve(task.name).id}`;
     }

package/.sinapse-ai/core/ideation/ideation-engine.js

@@ -2,7 +2,8 @@
  * Ideation Engine
  * Story 11.1 - Enhanced Capabilities
  *
- * AI-powered analysis for codebase improvements.
+ * Heuristic static analysis for codebase improvements (pure-Node scanners: grep,
+ * line counts, npm audit, madge — no LLM calls).
  * Suggests optimizations for performance, security, code quality, and UX.
  */
 

package/.sinapse-ai/core/orchestration/brownfield-progress.js

@@ -0,0 +1,219 @@
+/**
+ * Brownfield Discovery — deterministic progress + QA gate in code.
+ *
+ * Story onda3-s3-brownfield-progress-gate (AF-20260702 item 3.3).
+ *
+ * The 10 phases of brownfield-discovery.yaml are executed by agents (prose,
+ * orchestrate-then-handoff). What was missing — and what this module adds —
+ * is the DETERMINISTIC layer around that prose:
+ *
+ *   1. resolveBrownfieldProgress(): where the assessment actually stands,
+ *      measured from artifacts ON DISK (not from what anyone claims), giving
+ *      an exact resume point per phase.
+ *   2. evaluateQaGate() / recordRework(): the Phase 7 verdict (APPROVED /
+ *      NEEDS WORK) parsed from docs/reviews/qa-review.md by code, with a
+ *      persisted rework counter capped at MAX_REWORK — the NEEDS WORK loop
+ *      escalates instead of spinning forever.
+ *
+ * Honesty contract: an unfilled template ("[APPROVED / NEEDS WORK]") is
+ * PENDING, not a verdict. Autonomous fan-out of phases 1-3 remains gated on
+ * a measured pilot (same pre-registered gate as epic waves — see the epic
+ * README of epic-onda3-estrutural); this module is the safe deterministic
+ * substrate either way.
+ *
+ * @module core/orchestration/brownfield-progress
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { fileHasContent } = require('./doc-first-resolver');
+
+const QA_REVIEW_RELPATH = path.join('docs', 'reviews', 'qa-review.md');
+const STATE_RELPATH = path.join('.sinapse', 'workflow-state', 'brownfield-discovery.json');
+
+/** Rework ceiling for the Phase 7 loop (NEEDS WORK → fix → re-review). */
+const MAX_REWORK = 2;
+
+/** Normalize a step's `creates` (string | string[]) into a string list. */
+function listArtifacts(step) {
+  if (!step || !step.creates) return [];
+  const raw = Array.isArray(step.creates) ? step.creates : [step.creates];
+  return raw.filter((a) => typeof a === 'string' && a.trim().length > 0);
+}
+
+/** Glob-ish artifacts ("story-X.X-*.md") cannot be verified deterministically. */
+function isCheckable(artifact) {
+  return !artifact.includes('*');
+}
+
+/**
+ * Resolve the real state of the brownfield discovery from disk.
+ *
+ * @param {string} projectRoot
+ * @param {Object} workflow - Parsed `workflow` node (needs `.sequence`)
+ * @returns {{phases: Array, nextPhase: ?number, complete: boolean}}
+ */
+function resolveBrownfieldProgress(projectRoot, workflow) {
+  const sequence = (workflow && Array.isArray(workflow.sequence)) ? workflow.sequence : [];
+  const byPhase = new Map();
+
+  for (const step of sequence) {
+    if (!step || typeof step.phase !== 'number') continue;
+    if (!byPhase.has(step.phase)) {
+      byPhase.set(step.phase, { phase: step.phase, name: step.phase_name || null, steps: [] });
+    }
+    const artifacts = listArtifacts(step).map((artifact) => {
+      const checkable = isCheckable(artifact);
+      return {
+        path: artifact,
+        checkable,
+        exists: checkable ? fileHasContent(path.join(projectRoot, artifact)) : null,
+      };
+    });
+    byPhase.get(step.phase).steps.push({
+      id: step.step || step.id || null,
+      agent: step.agent || null,
+      conditional: Boolean(step.condition),
+      condition: step.condition || null,
+      artifacts,
+    });
+  }
+
+  const phases = [...byPhase.values()].sort((a, b) => a.phase - b.phase);
+
+  for (const phase of phases) {
+    // Required = checkable artifacts of unconditional steps. Conditional steps
+    // (e.g. project_has_database) never block completeness — but when their
+    // artifacts DO exist they are reported, so nothing done is invisible.
+    const required = phase.steps
+      .filter((s) => !s.conditional)
+      .flatMap((s) => s.artifacts.filter((a) => a.checkable));
+    const present = required.filter((a) => a.exists);
+    phase.requiredCount = required.length;
+    phase.presentCount = present.length;
+    if (required.length === 0) {
+      phase.status = 'unverifiable';
+    } else if (present.length === required.length) {
+      phase.status = 'complete';
+    } else if (present.length > 0) {
+      phase.status = 'partial';
+    } else {
+      phase.status = 'pending';
+    }
+  }
+
+  const firstIncomplete = phases.find(
+    (p) => p.status === 'pending' || p.status === 'partial',
+  );
+
+  return {
+    phases,
+    nextPhase: firstIncomplete ? firstIncomplete.phase : null,
+    complete: phases.length > 0 && !firstIncomplete,
+  };
+}
+
+/**
+ * Parse the Phase 7 verdict out of qa-review.md content.
+ *
+ * @param {string} content
+ * @returns {'approved'|'needs_work'|'pending'|'malformed'}
+ */
+function parseQaGateStatus(content) {
+  if (typeof content !== 'string') return 'malformed';
+  const m = content.match(/gate status:\s*(.*)$/im);
+  if (!m) return 'pending';
+  const value = m[1].trim();
+  const hasApproved = /approved/i.test(value);
+  const hasNeedsWork = /needs\s+work/i.test(value);
+  // The unfilled template is "[APPROVED / NEEDS WORK]" — both tokens present
+  // means the reviewer never picked. That is PENDING, never a verdict.
+  if (hasApproved && hasNeedsWork) return 'pending';
+  if (hasApproved) return 'approved';
+  if (hasNeedsWork) return 'needs_work';
+  return 'malformed';
+}
+
+function statePath(projectRoot) {
+  return path.join(projectRoot, STATE_RELPATH);
+}
+
+function readState(projectRoot) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(statePath(projectRoot), 'utf8'));
+    return { reworkCount: 0, ...parsed };
+  } catch {
+    return { reworkCount: 0 };
+  }
+}
+
+function writeState(projectRoot, state) {
+  const file = statePath(projectRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * Evaluate the Phase 7 QA gate deterministically (read-only — never mutates
+ * the rework counter; that is recordRework's job).
+ *
+ * @param {string} projectRoot
+ * @returns {{verdict: string, reworkCount: number, maxRework: number, escalate: boolean, reviewPath: string, reason?: string}}
+ */
+function evaluateQaGate(projectRoot) {
+  const reviewPath = path.join(projectRoot, QA_REVIEW_RELPATH);
+  const state = readState(projectRoot);
+  const base = {
+    reworkCount: state.reworkCount,
+    maxRework: MAX_REWORK,
+    reviewPath: QA_REVIEW_RELPATH,
+  };
+
+  if (!fileHasContent(reviewPath)) {
+    return { ...base, verdict: 'pending', escalate: false, reason: 'qa-review.md ausente ou vazio' };
+  }
+
+  let content;
+  try {
+    content = fs.readFileSync(reviewPath, 'utf8');
+  } catch (error) {
+    return { ...base, verdict: 'malformed', escalate: false, reason: `qa-review.md ilegível: ${error.message}` };
+  }
+
+  const verdict = parseQaGateStatus(content);
+  const escalate = verdict === 'needs_work' && state.reworkCount >= MAX_REWORK;
+  return { ...base, verdict, escalate };
+}
+
+/**
+ * Record one NEEDS WORK → rework loop iteration. Call it when the flow
+ * returns to Phase 4 after a NEEDS WORK verdict. At MAX_REWORK the gate
+ * escalates instead of looping.
+ *
+ * @param {string} projectRoot
+ * @returns {{reworkCount: number, escalate: boolean}}
+ */
+function recordRework(projectRoot) {
+  const state = readState(projectRoot);
+  state.reworkCount += 1;
+  state.lastReworkAt = new Date().toISOString();
+  writeState(projectRoot, state);
+  return { reworkCount: state.reworkCount, escalate: state.reworkCount >= MAX_REWORK };
+}
+
+/** Reset the rework counter (new assessment cycle). */
+function resetQaGateState(projectRoot) {
+  writeState(projectRoot, { reworkCount: 0 });
+}
+
+module.exports = {
+  resolveBrownfieldProgress,
+  parseQaGateStatus,
+  evaluateQaGate,
+  recordRework,
+  resetQaGateState,
+  MAX_REWORK,
+};

package/.sinapse-ai/core/orchestration/cli-commands.js

@@ -73,6 +73,14 @@ async function orchestrate(storyId, options = {}) {
   console.log(chalk.cyan.bold(`  🚀 SINAPSE Orchestrator: ${storyId}`));
   console.log(chalk.cyan('═══════════════════════════════════════════════════════════\n'));
 
+  // Measured-scope guard (AF-20260704 Lote B): the help text already states the
+  // 1-story-per-run limit, but nothing said it at runtime — where it matters.
+  console.log(
+    chalk.dim(
+      'Scope: 1 story per run — multi-story chaining is not supported (see KNOWN-LIMITATIONS.md).\n',
+    ),
+  );
+
   if (options.phaseLimit) {
     console.log(
       chalk.yellow(
@@ -107,6 +115,11 @@ async function orchestrate(storyId, options = {}) {
     // Start from specific epic (AC5)
     if (options.epic) {
       console.log(chalk.yellow(`Starting from Epic ${options.epic}...`));
+      console.log(
+        chalk.yellow(
+          '⚠️  --epic resumes THIS story from the given epic — it does not chain multiple stories.',
+        ),
+      );
       result = await orchestrator.resumeFromEpic(options.epic);
     } else {
       console.log(chalk.green('Starting full pipeline...'));

package/.sinapse-ai/core/orchestration/doc-first-resolver.js

@@ -198,6 +198,66 @@ function storyStatusIsReady(file) {
   return VALID_STORY_STATUSES.includes(status);
 }
 
+// ═══════════════════════════════════════════════════════════════════════════════════
+//                    SPEC SUBSTANCE (AF-20260704 M2)
+// ═══════════════════════════════════════════════════════════════════════════════════
+// A story can be `Ready` yet empty. The status gate alone lets a substanceless
+// story unlock implementation, which violates No Invention (Art. IV). These checks
+// verify the story actually carries the required sections + at least one acceptance
+// criterion, and flag missing traceability as a (non-blocking) concern.
+
+const STORY_SECTION_PATTERNS = Object.freeze({
+  acceptanceCriteria: /^#{1,4}\s*(acceptance criteria|crit[eé]rios? de aceita)/im,
+  scope: /^#{1,4}\s*(scope|escopo)/im,
+  description: /^#{1,4}\s*(description|descri[cç][aã]o)/im,
+});
+/** A markdown checkbox item with real content. */
+const AC_CHECKBOX = /^\s*[-*]\s*\[[ xX]\]\s+\S/m;
+/** A Given/When/Then triple (executable AC form). */
+const AC_GWT = /given[\s\S]{0,120}when[\s\S]{0,120}then/i;
+/** Signals that the story traces to evidence/requirement (No Invention). */
+const AC_TRACEABILITY = /(evid[eê]ncia|\bFR-\d|\bNFR-\d|\bCON-\d|\bAC\d|\bepic\b|\bstory\b|audit)/i;
+
+/**
+ * Inspect a story file for substance (required sections + ≥1 acceptance criterion).
+ * Never throws — a read error degrades open (warn-and-proceed), so a filesystem
+ * hiccup can never block development (circuit-breaker principle).
+ * @param {string} file
+ * @returns {{ok:boolean, missingSections:string[], hasAcItem:boolean, hasTraceability:boolean, degraded?:boolean}}
+ */
+function storyHasSubstance(file) {
+  let content;
+  try {
+    content = fs.readFileSync(file, 'utf8');
+  } catch {
+    return { ok: true, missingSections: [], hasAcItem: true, hasTraceability: true, degraded: true };
+  }
+  const missingSections = [];
+  if (!STORY_SECTION_PATTERNS.description.test(content)) missingSections.push('Descrição/Description');
+  if (!STORY_SECTION_PATTERNS.acceptanceCriteria.test(content)) missingSections.push('Acceptance Criteria');
+  if (!STORY_SECTION_PATTERNS.scope.test(content)) missingSections.push('Escopo/Scope');
+  const hasAcItem = AC_CHECKBOX.test(content) || AC_GWT.test(content);
+  const hasTraceability = AC_TRACEABILITY.test(content);
+  const ok = missingSections.length === 0 && hasAcItem;
+  return { ok, missingSections, hasAcItem, hasTraceability };
+}
+
+/**
+ * Substance verdict across a project's Ready stories. A project satisfies the
+ * substance gate when AT LEAST ONE Ready story is substantive (mirrors how
+ * `hasReadyStory` treats "some Ready story exists"). Returns the best verdict.
+ * @param {string} projectRoot
+ */
+function readyStorySubstance(projectRoot) {
+  const dir = path.join(projectRoot, 'docs', 'stories');
+  const readyFiles = walkMarkdown(dir).filter((f) => storyStatusIsReady(f));
+  if (readyFiles.length === 0) {
+    return { ok: false, missingSections: [], hasAcItem: false, hasTraceability: false, noReadyStory: true };
+  }
+  const verdicts = readyFiles.map(storyHasSubstance);
+  return verdicts.find((v) => v.ok) || verdicts[0];
+}
+
 // ═══════════════════════════════════════════════════════════════════════════════════
 //                              MAIN RESOLVER
 // ═══════════════════════════════════════════════════════════════════════════════════
@@ -237,17 +297,37 @@ function resolveDocFirstState(opts = {}) {
   const prd = hasPrd(projectRoot);
   const epic = hasEpic(projectRoot);
   const readyStory = hasReadyStory(projectRoot);
+  // M2: a Ready story must also carry substance (sections + ≥1 AC). Evaluated
+  // only when a Ready story exists, so this never changes the "no story" message.
+  const substance = readyStory
+    ? readyStorySubstance(projectRoot)
+    : { ok: false, missingSections: [], hasAcItem: false, hasTraceability: false };
 
   // Light types ride on an existing project: the minimal gate is "a Ready story"
   // (the existing story-gate). Full projects additionally need PRD + epic.
   const missing = [];
-  if (!readyStory) missing.push('story (status >= Ready)');
+  if (!readyStory) {
+    missing.push('story (status >= Ready)');
+  } else if (!substance.ok) {
+    // Block: a Ready story without required sections / any AC is not implementable.
+    const lack = substance.missingSections.length
+      ? substance.missingSections.join(', ')
+      : 'nenhum acceptance criterion';
+    missing.push(`story substance (falta: ${lack})`);
+  }
   if (!isLightType) {
     if (!prd) missing.push('PRD (docs/prd.md)');
     if (!epic) missing.push('epic (docs/epics/)');
   }
   const satisfied = missing.length === 0;
 
+  // Non-blocking concerns (Art. IV No Invention): a substantive story that lacks
+  // any traceability signal to evidence/requirement is flagged, not blocked.
+  const concerns = [];
+  if (readyStory && substance.ok && !substance.hasTraceability) {
+    concerns.push('story sem rastreabilidade explícita (Art. IV) — cite evidência/requisito/AC');
+  }
+
   return {
     brief,
     projectType,
@@ -255,7 +335,15 @@ function resolveDocFirstState(opts = {}) {
     isLightType,
     workflow,
     artifacts,
-    gate: { prd, epic, readyStory, satisfied, missing },
+    gate: {
+      prd,
+      epic,
+      readyStory,
+      substance: substance.ok,
+      satisfied,
+      missing,
+      concerns,
+    },
     maturity: assessProjectMaturity(projectRoot),
   };
 }
@@ -315,8 +403,14 @@ module.exports = {
   classifyProjectType,
   resolveDocFirstState,
   assessProjectMaturity,
+  // M2 (AF-20260704): spec substance checks, exported for reuse + testing.
+  storyHasSubstance,
+  readyStorySubstance,
   REQUIRED_ARTIFACTS_BY_WORKFLOW,
   TYPE_KEYWORDS,
   // re-exported for callers that want the raw map
   GREENFIELD_WORKFLOW_BY_TYPE,
+  // Onda3-S2 (AF-20260702 item 3.4): exported so artifact gates share ONE
+  // definition of "artifact exists and is non-empty" instead of forking it.
+  fileHasContent,
 };