sinapse-ai 1.15.0 → 1.17.0

package/.sinapse-ai/core/orchestration/route-command.js

@@ -0,0 +1,97 @@
+/**
+ * Route Command — read-only doc-first routing observability.
+ *
+ * Renders the deterministic routing decision for a briefing: project type →
+ * workflow → required upstream docs (exist/missing) → doc-first gate verdict.
+ *
+ * Intentionally lightweight: requires ONLY `doc-first-resolver` (fs + constants)
+ * and chalk. It does NOT pull the heavy orchestration index, so it has no side
+ * effects and no agent spawning.
+ *
+ * NOTE: a machine-readable `--json` mode was intentionally deferred — the
+ * framework emits an activation/cleanup summary to stdout on process exit
+ * (the same trailing line seen on `sinapse orchestrate`), which would corrupt
+ * strict JSON output. Programmatic consumers should require `doc-first-resolver`
+ * directly (clean, no side effects) instead of parsing this command's stdout.
+ *
+ * @module core/orchestration/route-command
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { resolveDocFirstState } = require('./doc-first-resolver');
+
+let chalk;
+try {
+  chalk = require('chalk');
+} catch {
+  const id = (s) => s;
+  chalk = {
+    green: id, red: id, yellow: id, cyan: Object.assign(id, { bold: id }),
+    gray: id, bold: id, dim: id,
+  };
+}
+
+/**
+ * Execute the `route` command.
+ *
+ * @param {string} brief - User briefing (e.g. "criar um site pra X")
+ * @param {Object} [options]
+ * @param {string} [options.projectRoot] - Project root path
+ * @param {string} [options.type] - Explicit project_type override
+ * @returns {Promise<{success:boolean, exitCode:number, state:Object}>}
+ */
+async function route(brief, options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const state = resolveDocFirstState({ projectRoot, brief, projectType: options.type });
+
+  const ok = (b) => (b ? chalk.green('✓') : chalk.red('✗'));
+  const briefLabel = brief ? `"${brief}"` : '(no brief — using project state only)';
+
+  console.log(chalk.cyan('\n═══════════════════════════════════════════════════════════'));
+  console.log(chalk.cyan.bold('  🧭 SINAPSE Doc-First Routing'));
+  console.log(chalk.cyan('═══════════════════════════════════════════════════════════\n'));
+
+  console.log(`Brief:        ${chalk.gray(briefLabel)}`);
+  console.log(
+    `Project type: ${chalk.bold(state.projectType)}` +
+      (state.classified ? '' : chalk.gray('  (default — not matched from brief)')),
+  );
+  console.log(`Workflow:     ${chalk.bold(state.workflow || 'SDC (no upstream re-doc)')}\n`);
+
+  if (state.artifacts.length) {
+    console.log(chalk.bold('Required upstream documents:'));
+    console.log(chalk.gray('  ┌──────────────────┬────────────────────────────────────┬────────┐'));
+    console.log(chalk.gray('  │ Document         │ Path                               │ Status │'));
+    console.log(chalk.gray('  ├──────────────────┼────────────────────────────────────┼────────┤'));
+    for (const a of state.artifacts) {
+      console.log(`  │ ${a.id.padEnd(16)} │ ${a.path.padEnd(34)} │   ${ok(a.exists)}    │`);
+    }
+    console.log(chalk.gray('  └──────────────────┴────────────────────────────────────┴────────┘\n'));
+  }
+
+  console.log(chalk.bold('Doc-first gate (required before code):'));
+  if (state.isLightType) {
+    console.log(chalk.gray('  (light task — rides on existing project; only a Ready story is required)'));
+    console.log(`  ${ok(state.gate.readyStory)} Story (status >= Ready)`);
+  } else {
+    console.log(`  ${ok(state.gate.prd)} PRD            ${chalk.gray('docs/prd.md')}`);
+    console.log(`  ${ok(state.gate.epic)} Epic           ${chalk.gray('docs/epics/')}`);
+    console.log(`  ${ok(state.gate.readyStory)} Story (Ready)  ${chalk.gray('docs/stories/')}`);
+  }
+
+  console.log('');
+  if (state.gate.satisfied) {
+    console.log(chalk.green.bold('  ✅ GATE SATISFIED — implementation may proceed.\n'));
+  } else {
+    console.log(chalk.red.bold('  🚫 GATE BLOCKED — missing: ' + state.gate.missing.join(', ')));
+    console.log(
+      chalk.gray(`     Run the ${state.workflow || 'SDC'} flow to produce these before any code.\n`),
+    );
+  }
+
+  return { success: true, exitCode: 0, state };
+}
+
+module.exports = { route };

package/.sinapse-ai/data/entity-registry.yaml

@@ -1,7 +1,7 @@
 metadata:
   version: 1.0.0
-  lastUpdated: '2026-06-24T13:49:06.535Z'
-  entityCount: 792
+  lastUpdated: '2026-06-25T14:57:04.344Z'
+  entityCount: 796
   checksumAlgorithm: sha256
   resolutionRate: 100
 entities:
@@ -650,6 +650,7 @@ entities:
         - chrome-brain-installer
         - cli
         - component-generator
+        - route-command
       externalDeps: []
       plannedDeps:
         - logger
@@ -660,8 +661,8 @@ entities:
         score: 0.7
         constraints: []
         extensionPoints: []
-      checksum: sha256:01cae0d9971b1acaec7e62025570cc5a629fe60e91d226fde6818bf359913c78
-      lastVerified: '2026-06-21T05:24:05.627Z'
+      checksum: sha256:5ee1c859ceedbbaa2cea1463677462985f1ce9472963d4b51589bdbfc5302395
+      lastVerified: '2026-06-25T14:57:04.173Z'
     collab-start:
       path: bin/utils/collab-start.js
       layer: L1
@@ -1927,8 +1928,8 @@ entities:
         score: 0.8
         constraints: []
         extensionPoints: []
-      checksum: sha256:86d38d0a9872d7e1e57edb2aa2be1e8a74a9e5ff78b9047ab15bc463fcf1cad6
-      lastVerified: '2026-06-15T00:26:26.247Z'
+      checksum: sha256:c59435108b2a016040bafbcf6bbcf1a9ce3502446871ef5a3af908f38602cbfa
+      lastVerified: '2026-06-25T14:35:16.949Z'
     create-next-story:
       path: .sinapse-ai/development/tasks/create-next-story.md
       layer: L2
@@ -1966,8 +1967,8 @@ entities:
         score: 0.8
         constraints: []
         extensionPoints: []
-      checksum: sha256:8a42add94bb0e1233d6f47203786ff57ec53bac148be37ec6ac3ca2cb3e5e2b8
-      lastVerified: '2026-06-15T00:26:26.248Z'
+      checksum: sha256:5e3d0b592821b1136db7dcfa911ee5080055d76b2f390fe0497e8702b06f330d
+      lastVerified: '2026-06-25T14:35:16.949Z'
     create-service:
       path: .sinapse-ai/development/tasks/create-service.md
       layer: L2
@@ -5625,6 +5626,32 @@ entities:
         extensionPoints: []
       checksum: sha256:702907ff987ef8db70bc7dba93aadcf40ba9d080321f8305dad7f9e2de10d1b2
       lastVerified: '2026-06-15T00:26:26.297Z'
+    spec-analyze:
+      path: .sinapse-ai/development/tasks/spec-analyze.md
+      layer: L2
+      type: task
+      purpose: Provar, antes de gastar geração de código, que cada requisito virou task e que nada contradiz a
+      keywords:
+        - spec
+        - analyze
+        - 'pipeline:'
+        - cross-consistency
+      usedBy:
+        - spec-pipeline
+      dependencies:
+        - architect
+      externalDeps: []
+      plannedDeps:
+        - spec
+        - constitution
+        - tasks
+      lifecycle: production
+      adaptability:
+        score: 0.8
+        constraints: []
+        extensionPoints: []
+      checksum: sha256:5a73974cb88ca58274f907416839e8c864a3e35cf832668d3b2c582de3f6b26a
+      lastVerified: '2026-06-24T15:49:40.276Z'
     spec-assess-complexity:
       path: .sinapse-ai/development/tasks/spec-assess-complexity.md
       layer: L2
@@ -5651,6 +5678,29 @@ entities:
         extensionPoints: []
       checksum: sha256:7ef9f00dad98113dcf6c273e0d56333aece4fa892c91fff8935d3c3c552748ae
       lastVerified: '2026-06-15T00:26:26.298Z'
+    spec-clarify:
+      path: .sinapse-ai/development/tasks/spec-clarify.md
+      layer: L2
+      type: task
+      purpose: Desambiguar a especificação ANTES do QA gate e do plano. Roda DEPOIS de `write` (spec escrita)
+      keywords:
+        - spec
+        - clarify
+        - 'pipeline:'
+        - specification
+      usedBy:
+        - spec-pipeline
+      dependencies: []
+      externalDeps: []
+      plannedDeps:
+        - spec
+      lifecycle: production
+      adaptability:
+        score: 0.8
+        constraints: []
+        extensionPoints: []
+      checksum: sha256:e4eee7ea80f146a697433462287aaff138536b148705337f2f32d66d2a83db5c
+      lastVerified: '2026-06-24T15:49:40.277Z'
     spec-critique:
       path: .sinapse-ai/development/tasks/spec-critique.md
       layer: L2
@@ -5702,8 +5752,8 @@ entities:
         score: 0.8
         constraints: []
         extensionPoints: []
-      checksum: sha256:1a1b02926d2fc13d85caf9da0cbc84122cd4ec1e7ec8ec292b4d1cac190c70d3
-      lastVerified: '2026-06-15T00:26:26.299Z'
+      checksum: sha256:7ed12b65fca5657d218fbfaa40c0a05af5d3e14a17a332c089dd1147d7cb1ca9
+      lastVerified: '2026-06-25T14:35:16.977Z'
     spec-research-dependencies:
       path: .sinapse-ai/development/tasks/spec-research-dependencies.md
       layer: L2
@@ -7291,8 +7341,8 @@ entities:
         score: 0.5
         constraints: []
         extensionPoints: []
-      checksum: sha256:cc68f141e09386096f6add62717f63f0b56bb53f315eafcafc4bb649f151d25f
-      lastVerified: '2026-06-15T00:26:26.324Z'
+      checksum: sha256:ae365825677131fc9f5c6762c6a4a036be0737442bcbdb04cdbd4e3e3f547265
+      lastVerified: '2026-06-25T14:35:16.991Z'
     project-brief-tmpl:
       path: .sinapse-ai/product/templates/project-brief-tmpl.yaml
       layer: L2
@@ -7418,8 +7468,8 @@ entities:
         score: 0.5
         constraints: []
         extensionPoints: []
-      checksum: sha256:03a71c8a3758864c3d27e4f0865734d986f4259f64af477d9fa4244f8972c7eb
-      lastVerified: '2026-06-15T00:26:26.326Z'
+      checksum: sha256:58207c62ca73c18d9584232bc62ec43ee5f11dc4337d231eee5bf2cc87d15b78
+      lastVerified: '2026-06-24T15:32:36.159Z'
     state-persistence-tmpl:
       path: .sinapse-ai/product/templates/state-persistence-tmpl.yaml
       layer: L2
@@ -11831,6 +11881,28 @@ entities:
         extensionPoints: []
       checksum: sha256:14e91bfefde4f1ee9ecea1e2902bcc43a754719b1572d93f7d2ca357c87c8312
       lastVerified: '2026-06-15T00:26:26.404Z'
+    doc-first-resolver:
+      path: .sinapse-ai/core/orchestration/doc-first-resolver.js
+      layer: L1
+      type: module
+      purpose: Entity at .sinapse-ai\core\orchestration\doc-first-resolver.js
+      keywords:
+        - doc
+        - first
+        - resolver
+      usedBy:
+        - route-command
+      dependencies:
+        - greenfield-handler
+      externalDeps: []
+      plannedDeps: []
+      lifecycle: production
+      adaptability:
+        score: 0.4
+        constraints: []
+        extensionPoints: []
+      checksum: sha256:e3c8c695ef0b4f268a3e02a0d4258fef1ae90aaec0b281ee8c5c5fb3bd475939
+      lastVerified: '2026-06-25T14:57:04.259Z'
     epic-context-accumulator:
       path: .sinapse-ai/core/orchestration/epic-context-accumulator.js
       layer: L1
@@ -12035,6 +12107,7 @@ entities:
         - handler
       usedBy:
         - bob-orchestrator
+        - doc-first-resolver
       dependencies:
         - workflow-executor
         - surface-checker
@@ -12141,6 +12214,27 @@ entities:
         extensionPoints: []
       checksum: sha256:cfbf41b69336548b2fc4179a5513243491ca6eb501de3426f98254f118b074e7
       lastVerified: '2026-06-15T00:26:26.411Z'
+    route-command:
+      path: .sinapse-ai/core/orchestration/route-command.js
+      layer: L1
+      type: module
+      purpose: Entity at .sinapse-ai\core\orchestration\route-command.js
+      keywords:
+        - route
+        - command
+      usedBy:
+        - sinapse
+      dependencies:
+        - doc-first-resolver
+      externalDeps: []
+      plannedDeps: []
+      lifecycle: production
+      adaptability:
+        score: 0.4
+        constraints: []
+        extensionPoints: []
+      checksum: sha256:b7a5aa520936eb819d7b577fd7b15bcee8c7f8e9e147c6fa3db9fd12a493b7f3
+      lastVerified: '2026-06-25T14:57:04.262Z'
     session-state:
       path: .sinapse-ai/core/orchestration/session-state.js
       layer: L1
@@ -13655,6 +13749,7 @@ entities:
         - plan-create-context
         - plan-create-implementation
         - qa-review-build
+        - spec-analyze
         - spec-assess-complexity
         - spec-critique
         - spec-gather-requirements
@@ -15074,7 +15169,9 @@ entities:
         - spec-assess-complexity
         - spec-research-dependencies
         - spec-write-spec
+        - spec-clarify
         - spec-critique
+        - spec-analyze
         - architect
         - analyst
       externalDeps: []
@@ -15086,8 +15183,8 @@ entities:
         score: 0.4
         constraints: []
         extensionPoints: []
-      checksum: sha256:890753d02dd6469441fe82a5eba0ecf48a3ac7969cfda3cd888c94cb74695c39
-      lastVerified: '2026-06-15T00:26:26.489Z'
+      checksum: sha256:fc739f0f5ec927ed9daecbd0fc74b68017ed548ce445c40b9b1ecd5f1ff2ff4b
+      lastVerified: '2026-06-25T14:35:17.067Z'
     story-development-cycle:
       path: .sinapse-ai/development/workflows/story-development-cycle.yaml
       layer: L2

package/.sinapse-ai/development/agents/snps-orqx.md

@@ -80,6 +80,15 @@ Caio's runtime test (2026-05-07) showed the framework treating fresh installs as
 > **This step runs AFTER the Initial State Audit, BEFORE the routing decision. No exceptions.**
 > Without it, Imperator routes large-project requests directly to a domain orchestrator and skips the doc-first pipeline (Article III violation).
 
+### Deterministic engine (source of truth — never hand-classify)
+
+The classification below is NOT done by reasoning from memory. It is computed by the **doc-first resolver** (`.sinapse-ai/core/orchestration/doc-first-resolver.js`) — the single source of truth shared by the CLI and the enforcement hook, so the agent and the gate can never drift:
+
+- **Observe the decision** with `sinapse route "<brief>"` — read-only, no side effects. It returns the resolved `projectType`, the required greenfield `workflow`, the upstream `artifacts` (brief → prd → spec → architecture), and whether the doc-first `gate` is already satisfied.
+- **Enforcement is automatic** — the `doc-first-gate.cjs` PreToolUse hook HARD-BLOCKS code writes in a greenfield project until PRD + epic + a `Ready` story exist. The framework repo and existing (brownfield) projects are exempt; escape with `SINAPSE_SKIP_DOCFIRST=1` only when explicitly justified.
+
+Run `sinapse route` first and let its output drive Steps 1–4 below. Steps 1–4 are the human-readable explanation of what the resolver already decided — when prose and resolver disagree, the resolver wins.
+
 After the audit reports the maturity level, classify the request **before** consulting the routing table:
 
 ### Step 1 — Detect intent

package/.sinapse-ai/development/tasks/create-doc.md

@@ -238,7 +238,7 @@ If a YAML Template has not been provided, list all templates from .sinapse-ai/pr
 
 **YOU MUST:**
 
-1. Present section content
+1. Present section content. **If the section content is a list of artifacts (epics, requirements, stories, tasks, risks), render it as a scannable approval table FIRST, following `.sinapse-ai/development/templates/approval-table.md` (verdict header → table → decision prompt). Never report a list as a count or as prose when a table schema fits.**
 2. Provide detailed rationale (explain trade-offs, assumptions, decisions made)
 3. **STOP and present numbered options 1-9:**
    - **Option 1:** Always "Proceed to next section"

package/.sinapse-ai/development/tasks/create-next-story.md

@@ -773,9 +773,8 @@ Use the primary agent from "Specialized Agent Assignment" to determine which sel
 - Ensure tasks align with both epic requirements and architecture constraints
 - Update status to "Draft" and save the story file
 - Execute `sinapse-ai/tasks/execute-checklist` `sinapse-ai/checklists/story-draft-checklist`
-- Provide summary to user including:
-  - Story created: `{devStoryLocation}/{epicNum}.{storyNum}.story.md`
-  - Status: Draft
+- Provide summary to user as a scannable **story approval table** per `.sinapse-ai/development/templates/approval-table.md` (Story summary schema: a `| Field | Value |` table + an `| AC# | Criterion | Tasks |` table), not a plain bullet list. The table MUST surface:
+  - Story created (path), Status (Draft), Acceptance count, Tasks count (linked to ACs), Dependencies
   - Key technical components included from architecture docs
   - Any deviations or conflicts noted between epic and architecture
   - Checklist Results