sinapse-ai 1.21.0 → 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/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,6 +403,9 @@ 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

package/.sinapse-ai/core/orchestration/executors/epic-3-executor.js

@@ -14,6 +14,7 @@
 const fs = require('fs-extra');
 const path = require('path');
 const EpicExecutor = require('./epic-executor');
+const { classifyComplexity } = require('../spec-complexity');
 
 /**
  * Spec Pipeline phases
@@ -131,14 +132,26 @@ class Epic3Executor extends EpicExecutor {
       this._addArtifact('spec', specPath);
 
       // Collect complexity and requirements from phases
-      const complexity = phaseResults['assess-complexity']?.complexity || 'STANDARD';
+      const assess = phaseResults['assess-complexity'] || {};
+      const complexity = assess.complexity || 'STANDARD';
       const requirements = phaseResults['gather-requirements']?.requirements || [];
 
+      // M4 (AF-20260704 #9b): turn the COMPLEX≥16 rule from prose into a
+      // deterministic classification. Prefer the numeric dimension score when the
+      // assess phase provides one; otherwise fall back to the level string.
+      const classification = classifyComplexity(
+        typeof assess.score === 'number' ? assess.score : assess.dimensions || complexity,
+      );
+
       // Honesty invariant (epic: orchestration-consolidation, F0a):
       // if the spec was auto-stubbed (no real agent ran), report STUB, not success.
       const specResult = {
         specPath,
-        complexity,
+        complexity: classification.level,
+        complexityScore: classification.score,
+        requiresRevisionCycle: classification.requiresRevisionCycle,
+        requiresFullSpecPipeline: classification.requiresFullSpecPipeline,
+        specPipelinePhases: classification.phases,
         requirements,
         phases: Object.keys(phaseResults),
       };

package/.sinapse-ai/core/orchestration/executors/epic-4-executor.js

@@ -193,12 +193,14 @@ class Epic4Executor extends EpicExecutor {
   async _executeViaBuildOrchestrator(storyId, context) {
     try {
       const { BuildOrchestrator } = require('../../execution/build-orchestrator');
+      // buildOptions is passed once, via build() — which already merges it over
+      // the constructor config ({...this.config, ...options}). Passing it in both
+      // places (AF-20260704 Lote B) was redundant, not wrong.
       const builder = new BuildOrchestrator({
         rootPath: this.projectRoot,
         useWorktree: false,
         autoMerge: false,
         runQA: false,
-        ...(context.buildOptions || {}),
       });
       return await builder.build(storyId, context.buildOptions || {});
     } catch (err) {

package/.sinapse-ai/core/orchestration/index.js

@@ -158,6 +158,8 @@ const {
 
 module.exports = {
   // Main orchestrators
+  // @deprecated WorkflowOrchestrator has no internal consumers (AF-20260704);
+  // kept exported because the barrel is public package API. Prefer MasterOrchestrator.
   WorkflowOrchestrator,
   MasterOrchestrator, // Epic 0: ADE Master Orchestrator
 
@@ -290,6 +292,9 @@ module.exports = {
   STALE_SNAPSHOT_DAYS,
 
   // Story 12.4: Epic Context Accumulator (Projeto Bob)
+  // @deprecated EpicContextAccumulator has no internal consumers (AF-20260704;
+  // multi-story orchestration was measured and rejected — see KNOWN-LIMITATIONS.md).
+  // Kept exported because the barrel is public package API.
   EpicContextAccumulator,
   createEpicContextAccumulator,
   CompressionLevel,

package/.sinapse-ai/core/orchestration/spec-complexity.js

@@ -0,0 +1,141 @@
+/**
+ * Spec-Pipeline Complexity — deterministic threshold + phase plan.
+ *
+ * The COMPLEX≥16 rule lived only in prose (`workflow-execution.md` §3,
+ * `documentation-first.md` complexity gate): "score ≥16 → COMPLEX → run the full
+ * Spec Pipeline (6 phases + revision cycle) FIRST". Nothing in code enforced the
+ * threshold or derived the phase plan from it, so the assessment was advisory.
+ *
+ * This module turns the threshold and the per-level phase plan into deterministic,
+ * tested code (Story rodada2-m4, AF-20260704 #9b). It does NOT invent HOW the five
+ * dimensions are scored — those values come from the `assess-complexity` phase; it
+ * only encodes the mapping score → level → required phases, canonically defined in
+ * `workflow-execution.md`.
+ *
+ * @module core/orchestration/spec-complexity
+ */
+
+'use strict';
+
+/** The five complexity dimensions, each scored 1-5 (min 5, max 25). */
+const DIMENSIONS = Object.freeze(['scope', 'integration', 'infrastructure', 'knowledge', 'risk']);
+
+/**
+ * Canonical thresholds (`workflow-execution.md` §3):
+ *   score <= 8  → SIMPLE
+ *   9..15       → STANDARD
+ *   score >= 16 → COMPLEX
+ */
+const THRESHOLDS = Object.freeze({ SIMPLE_MAX: 8, COMPLEX_MIN: 16 });
+
+const LEVELS = Object.freeze({ SIMPLE: 'SIMPLE', STANDARD: 'STANDARD', COMPLEX: 'COMPLEX' });
+
+/**
+ * Phase plans per level (`workflow-execution.md` §3 table):
+ *   SIMPLE   → gather → spec → critique                                   (3)
+ *   STANDARD → gather → assess → research → spec → critique → plan        (6)
+ *   COMPLEX  → the 6 phases + a revision cycle                            (6 + revision)
+ */
+const PHASES_BY_LEVEL = Object.freeze({
+  SIMPLE: Object.freeze(['gather-requirements', 'write-spec', 'critique']),
+  STANDARD: Object.freeze([
+    'gather-requirements',
+    'assess-complexity',
+    'research-dependencies',
+    'write-spec',
+    'critique',
+    'plan',
+  ]),
+  COMPLEX: Object.freeze([
+    'gather-requirements',
+    'assess-complexity',
+    'research-dependencies',
+    'write-spec',
+    'critique',
+    'plan',
+  ]),
+});
+
+/**
+ * Map a numeric complexity score to its level. Deterministic; no side effects.
+ * @param {number} score - Sum of the five dimensions (nominally 5..25).
+ * @returns {'SIMPLE'|'STANDARD'|'COMPLEX'}
+ */
+function scoreToLevel(score) {
+  const n = Number(score);
+  if (!Number.isFinite(n)) return LEVELS.STANDARD; // conservative default
+  if (n <= THRESHOLDS.SIMPLE_MAX) return LEVELS.SIMPLE;
+  if (n >= THRESHOLDS.COMPLEX_MIN) return LEVELS.COMPLEX;
+  return LEVELS.STANDARD;
+}
+
+/** Normalize a level-ish input (a level string, in any case) to a canonical level. */
+function normalizeLevel(level) {
+  const u = String(level || '').trim().toUpperCase();
+  return LEVELS[u] || null;
+}
+
+/**
+ * Sum an object of dimension → score (1-5). Missing dimensions count as 0.
+ * @param {Record<string, number>} dimensions
+ * @returns {number}
+ */
+function sumDimensions(dimensions) {
+  if (!dimensions || typeof dimensions !== 'object') return NaN;
+  return DIMENSIONS.reduce((total, d) => {
+    const v = Number(dimensions[d]);
+    return total + (Number.isFinite(v) ? v : 0);
+  }, 0);
+}
+
+/**
+ * Classify complexity from either a numeric score, a dimensions object, or an
+ * already-decided level string. Returns the deterministic plan.
+ *
+ * @param {number|string|Record<string, number>} input
+ * @returns {{
+ *   level: 'SIMPLE'|'STANDARD'|'COMPLEX',
+ *   score: number|null,
+ *   phases: string[],
+ *   requiresRevisionCycle: boolean,
+ *   requiresFullSpecPipeline: boolean
+ * }}
+ */
+function classifyComplexity(input) {
+  let level;
+  let score = null;
+
+  if (typeof input === 'number') {
+    score = input;
+    level = scoreToLevel(input);
+  } else if (typeof input === 'string') {
+    level = normalizeLevel(input) || LEVELS.STANDARD;
+  } else if (input && typeof input === 'object') {
+    const s = sumDimensions(input);
+    score = Number.isFinite(s) ? s : null;
+    level = Number.isFinite(s) ? scoreToLevel(s) : LEVELS.STANDARD;
+  } else {
+    level = LEVELS.STANDARD; // conservative default when nothing usable is given
+  }
+
+  return {
+    level,
+    score,
+    phases: [...PHASES_BY_LEVEL[level]],
+    // COMPLEX is the only level that adds the revision cycle.
+    requiresRevisionCycle: level === LEVELS.COMPLEX,
+    // SIMPLE runs the trimmed 3-phase pipeline; STANDARD/COMPLEX run the full one.
+    requiresFullSpecPipeline: level !== LEVELS.SIMPLE,
+  };
+}
+
+module.exports = {
+  DIMENSIONS,
+  THRESHOLDS,
+  LEVELS,
+  PHASES_BY_LEVEL,
+  scoreToLevel,
+  normalizeLevel,
+  sumDimensions,
+  classifyComplexity,
+};