sinapse-ai 1.14.0 → 1.16.0

package/.sinapse-ai/development/tasks/spec-clarify.md

@@ -0,0 +1,374 @@
+# Spec Pipeline: Clarify Specification
+
+> **Phase:** 4b - Clarify
+> **Owner Agent:** @project-lead
+> **Pipeline:** spec-pipeline
+
+---
+
+## Purpose
+
+Desambiguar a especificação ANTES do QA gate e do plano. Roda DEPOIS de `write` (spec escrita)
+e ANTES de `critique`. Varre o `spec.md` por uma taxonomia de 9 categorias de cobertura, faz no
+máximo 5 perguntas guiadas por (Impacto × Incerteza) — uma de cada vez — e integra cada resposta
+atomicamente no `spec.md`. Sub-especificação descoberta tarde é o retrabalho mais caro do pipeline;
+o clarify ataca isso cedo, perguntando apenas o que muda decisão downstream.
+
+---
+
+## autoClaude
+
+```yaml
+autoClaude:
+  version: '3.0'
+  pipelinePhase: spec-clarify
+
+  elicit: true # Interactive - asks the user clarifying questions
+  deterministic: false # Output depends on user answers
+  composable: true
+
+  selfCritique:
+    required: false
+
+  inputs:
+    - name: storyId
+      type: string
+      required: true
+
+    - name: spec
+      type: file
+      path: docs/stories/{storyId}/spec/spec.md
+      required: true
+
+    - name: requirements
+      type: file
+      path: docs/stories/{storyId}/spec/requirements.json
+      required: false
+
+  outputs:
+    - name: spec.md
+      type: file
+      path: docs/stories/{storyId}/spec/spec.md
+      mutation: append # Adds/updates the `## Clarifications` section + target sections
+
+  verification:
+    type: gate
+    blocking: false # Skippable with explicit rework-risk warning
+    completion_field: clarificationComplete
+
+  contextRequirements:
+    projectContext: true
+    filesContext: true
+    implementationPlan: false
+    spec: true
+```
+
+---
+
+## Coverage Taxonomy (9 categories)
+
+Varra o `spec.md` e marque cada categoria como **Clear / Partial / Missing**. Perguntas só nascem
+de categorias `Partial` ou `Missing` cujo esclarecimento muda uma decisão downstream.
+
+```yaml
+taxonomy:
+  - id: tax-1
+    name: 'Functional Scope & Behavior'
+    looks_for: 'Core actions, in/out of scope, behavioral edges'
+
+  - id: tax-2
+    name: 'Domain & Data Model'
+    looks_for: 'Entities, attributes, relationships, identity, lifecycle/state'
+
+  - id: tax-3
+    name: 'Interaction & UX Flow'
+    looks_for: 'Steps, states, error/empty states, accessibility intent'
+
+  - id: tax-4
+    name: 'Non-Functional Quality Attributes'
+    looks_for: 'Performance, scale, latency, availability, security targets (quantified)'
+
+  - id: tax-5
+    name: 'Integration & External Dependencies'
+    looks_for: 'External services, APIs, contracts, failure modes of integrations'
+
+  - id: tax-6
+    name: 'Edge Cases & Failure Handling'
+    looks_for: 'Boundary conditions, invalid input, partial failure, recovery'
+
+  - id: tax-7
+    name: 'Constraints & Tradeoffs'
+    looks_for: 'Hard constraints, rejected alternatives, explicit tradeoffs'
+
+  - id: tax-8
+    name: 'Terminology & Consistency'
+    looks_for: 'Consistent naming, no synonym drift, defined glossary terms'
+
+  - id: tax-9
+    name: 'Completion Signals'
+    looks_for: 'Measurable done criteria, acceptance signals, Success Criteria present'
+
+  - id: tax-misc
+    name: 'Misc / Signals'
+    looks_for: 'TODO / ??? placeholders, unquantified adjectives (fast/scalable/secure), [NEEDS CLARIFICATION] markers'
+```
+
+---
+
+## Question Selection (Impact × Uncertainty)
+
+```yaml
+selection:
+  heuristic: 'Impact × Uncertainty'
+
+  rule: |
+    Only include questions whose answers materially impact architecture, data modeling,
+    task decomposition, test design, UX behavior, operational readiness, or compliance
+    validation. Discard cosmetic questions that do not change a downstream decision.
+
+  prioritize:
+    - High impact + high uncertainty (ask first)
+    - High impact + medium uncertainty
+  discard:
+    - Low impact (any uncertainty)
+    - Already Clear in the taxonomy scan
+```
+
+---
+
+## Question Format
+
+```yaml
+question_format:
+  max_questions: 5
+  one_at_a_time: true # Ask, wait for answer, integrate, then next
+
+  styles:
+    - type: multiple_choice
+      options: '2 to 5 mutually exclusive options'
+      include_recommendation: true # Mark the recommended option
+    - type: short_answer
+      constraint: 'answer in <= 5 words'
+```
+
+---
+
+## Integration (atomic)
+
+Cada resposta é integrada IMEDIATAMENTE antes da próxima pergunta — registro + aplicação na seção-alvo.
+
+```yaml
+integration:
+  log_section:
+    create_if_missing: '## Clarifications'
+    subsection: '### Session {YYYY-MM-DD}'
+    entry_format: '- Q: {question} -> A: {answer}'
+
+  apply_change:
+    description: 'Apply the answer to the target section of the spec'
+    targets:
+      - Functional Requirements (FR-*)
+      - Key Entities / Data Model
+      - Success Criteria (SC-*)
+      - Edge Cases
+      - Constraints (CON-*)
+    rule: 'Never log an answer without applying it to the target section'
+```
+
+---
+
+## Stop Criteria
+
+```yaml
+stop_when:
+  any_of:
+    - 'All critical ambiguities resolved'
+    - 'User says proceed / done / skip'
+    - 'Reached 5 questions'
+    - 'No critical ambiguity detected in the taxonomy scan (zero questions is valid)'
+```
+
+---
+
+## Gate
+
+```yaml
+gate:
+  order: 'Run (and complete) clarify BEFORE the plan phase'
+  blocking: false
+
+  on_skip:
+    allowed: true
+    required_action: |
+      Warn explicitly: downstream rework risk increases when clarification is skipped.
+    message: |
+      ⚠️ Skipping clarification. Ambiguities in the spec may surface during plan/implement,
+      increasing rework cost. Proceeding at user request.
+```
+
+---
+
+## Execution Flow
+
+### Step 1: Scan Coverage
+
+```yaml
+scan:
+  action: scan_spec_against_taxonomy
+  for_each: category in taxonomy
+  process: |
+    1. Read spec.md
+    2. Mark category Clear / Partial / Missing
+    3. Note specific gap location (section)
+```
+
+### Step 2: Select Questions
+
+```yaml
+select:
+  action: rank_by_impact_uncertainty
+  process: |
+    1. Build candidate questions from Partial/Missing categories
+    2. Apply the materially-impacts filter (discard cosmetic)
+    3. Rank by Impact x Uncertainty
+    4. Cap the queue at 5
+```
+
+### Step 3: Ask & Integrate Loop
+
+```yaml
+ask_loop:
+  for_each: question in selected (max 5)
+  process: |
+    1. Ask ONE question (multiple-choice 2-5 opts w/ recommendation, OR short answer <=5 words)
+    2. Wait for the answer
+    3. Append `- Q: ... -> A: ...` under `## Clarifications` / `### Session {date}`
+    4. Apply the answer to the target spec section
+    5. Re-check stop criteria; break if met
+```
+
+### Step 4: Finalize
+
+```yaml
+finalize:
+  action: confirm_clarification_complete
+  process: |
+    1. Ensure every asked question was both logged AND applied
+    2. Set clarificationComplete = true
+    3. Hand off to critique
+```
+
+---
+
+## Integration
+
+### Command Integration (@project-lead)
+
+```yaml
+command:
+  name: '*clarify-spec'
+  syntax: '*clarify-spec {story-id}'
+  agent: pm
+
+  examples:
+    - '*clarify-spec STORY-42'
+```
+
+### Pipeline Integration
+
+```yaml
+pipeline:
+  phase: clarify
+  previous_phase: spec
+  next_phase: critique
+
+  requires:
+    - spec.md
+
+  optional:
+    - requirements.json
+
+  gate: true # Order gate: complete before plan
+  blocking: false # Skippable with rework-risk warning
+
+  pass_to_next:
+    - spec.md
+```
+
+---
+
+## Error Handling
+
+```yaml
+errors:
+  - id: missing-spec
+    condition: 'spec.md not found'
+    action: 'Halt - cannot clarify without a spec'
+    blocking: true
+
+  - id: no-ambiguity
+    condition: 'Taxonomy scan finds zero critical ambiguities'
+    action: 'Skip questions, set clarificationComplete=true, proceed to critique'
+    blocking: false
+
+  - id: user-defers
+    condition: 'User declines to answer / says proceed'
+    action: 'Warn of rework risk, set clarificationComplete=false, proceed'
+    blocking: false
+```
+
+---
+
+## Examples
+
+### Example: Clarify a vague NFR
+
+**Input:** spec.md says "the endpoint should be fast" (tax-4 = Partial, unquantified adjective)
+
+**Interaction:**
+
+```
+Q: What is the acceptable p95 latency for the endpoint?
+   A) < 100ms   B) < 300ms (recommended)   C) < 1s   D) No target needed
+A: B
+```
+
+**Spec mutation:**
+
+```markdown
+## Clarifications
+
+### Session 2026-06-24
+
+- Q: What is the acceptable p95 latency for the endpoint? → A: < 300ms (p95)
+
+<!-- and NFR section updated: -->
+| Category    | Requirement              | Target        |
+| ----------- | ------------------------ | ------------- |
+| Performance | Endpoint response (p95)  | < 300ms       |
+```
+
+---
+
+## Metadata
+
+```yaml
+metadata:
+  story: '3.4b'
+  epic: 'Epic 3 - Spec Pipeline'
+  created: '2026-06-24'
+  author: '@project-lead (Axis)'
+  version: '1.0.0'
+  source: 'GitHub Spec Kit — templates/commands/clarify.md'
+  tags:
+    - spec-pipeline
+    - clarify
+    - ambiguity
+    - elicitation
+    - product-lead
+```
+
+## Handoff
+next_agent: @quality-gate
+next_command: *critique-spec {story-id}
+condition: Clarification complete (no critical ambiguities open) OR user proceeds with rework-risk warning

package/.sinapse-ai/development/templates/chrome-brain/rules/chrome-brain-autoload.md

@@ -21,6 +21,10 @@ When the user's prompt matches ANY of these patterns, Chrome Brain is active:
 4. Track screenshot count — max 15 per session
 5. Handoff results to domain squad when applicable
 
+## Janela fixa & login (uma vez)
+
+A automação roda numa **janela de Chrome dedicada e fixa** (perfil `~/.chrome-debug-profile`), separada do Chrome pessoal do usuário. Ela é lançada **só quando uma tarefa de browser precisa** e **nunca é morta enquanto saudável** (o `chrome-ensure` só relança se a porta estiver realmente fora do ar). Na primeira vez que uma tarefa acessar um site que exige login, o usuário loga **uma vez** nessa janela — o perfil persiste, então não precisa logar de novo. Para logar proativamente em todas as contas de uma vez: `sinapse chrome-brain login`.
+
 ## Auto-Learning — MANDATORY
 
 After completing ANY browser automation task, evaluate:

package/.sinapse-ai/development/templates/chrome-brain/scripts/chrome-brain-log.cjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Chrome Brain — chrome-brain-log (Node, cross-platform).
+ *
+ * Called by the PostToolUse hook after every browser MCP tool. Appends a usage
+ * line and warns when the per-session screenshot count gets risky (the API has
+ * a ~20MB response cap). Node version of the old bash logger so it runs hidden
+ * on Windows (no console window) and needs no date/awk/grep.
+ *
+ * FAIL-SOFT: never throws, always exits 0.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function toolName() {
+  // Claude Code passes a JSON payload on stdin; fall back to env then 'unknown'.
+  try {
+    const raw = fs.readFileSync(0, 'utf8');
+    if (raw) {
+      const j = JSON.parse(raw);
+      return j.tool_name || j.toolName || process.env.HOOK_TOOL_NAME || 'unknown';
+    }
+  } catch {
+    /* no stdin / not JSON */
+  }
+  return process.env.HOOK_TOOL_NAME || 'unknown';
+}
+
+try {
+  const dir = path.join(os.homedir(), '.chrome-brain');
+  fs.mkdirSync(dir, { recursive: true });
+
+  const now = new Date();
+  const today = now.toISOString().slice(0, 10).replace(/-/g, ''); // YYYYMMDD
+  const time = now.toTimeString().slice(0, 8); // HH:MM:SS
+  const tool = toolName();
+
+  fs.appendFileSync(path.join(dir, `session-${today}.log`), `${time} ${tool}\n`);
+
+  if (/take_screenshot|take_snapshot/.test(tool)) {
+    const countFile = path.join(dir, '.screenshot-count');
+    const dateFile = path.join(dir, '.screenshot-date');
+
+    let lastDate = '';
+    try {
+      lastDate = fs.readFileSync(dateFile, 'utf8').trim();
+    } catch {
+      /* first run */
+    }
+    if (lastDate !== today) {
+      fs.writeFileSync(dateFile, today);
+      fs.writeFileSync(countFile, '0');
+    }
+
+    let count = 0;
+    try {
+      count = parseInt(fs.readFileSync(countFile, 'utf8'), 10) || 0;
+    } catch {
+      /* default 0 */
+    }
+    count += 1;
+    fs.writeFileSync(countFile, String(count));
+
+    if (count === 12) {
+      process.stderr.write('WARNING: 12 screenshots this session. Consider saving state and rotating.\n');
+    } else if (count >= 15) {
+      process.stderr.write('CRITICAL: 15+ screenshots. Session at risk of the API size cap. Save state NOW.\n');
+    }
+  }
+} catch {
+  /* fail-soft */
+}
+
+process.exit(0);

package/.sinapse-ai/development/templates/chrome-brain/scripts/chrome-ensure.cjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Chrome Brain — chrome-ensure (Node, cross-platform).
+ *
+ * Called by the PreToolUse hook before any browser MCP tool. Guarantees the
+ * SINGLE fixed-profile debug Chrome is up on the CDP port — and crucially:
+ *   - NEVER kills a healthy instance (the old bash script force-killed on a
+ *     flaky check, which dropped the live DevTools connection).
+ *   - Launches detached + windowsHide so NO console (CMD/PowerShell) window
+ *     ever pops (the old `#!/bin/bash` script spawned a console on Windows).
+ *   - Uses one fixed profile so the user logs in ONCE and stays logged in.
+ *
+ * Reads config from ~/.sinapse/chrome-brain.json (written at install time):
+ *   { "chromePath": "...", "port": 9222, "profile": "~/.chrome-debug-profile" }
+ *
+ * FAIL-SOFT: any error -> exit 0. A browser helper is never worth blocking a
+ * tool call (the MCP itself will surface a clear error if Chrome is truly down).
+ *
+ * Pass `--visible` (or run via `chrome-brain login`) to force a launch even when
+ * an instance is already up — used to open the window for first-time login.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const http = require('http');
+const { spawn } = require('child_process');
+
+const CONFIG_PATH = path.join(os.homedir(), '.sinapse', 'chrome-brain.json');
+
+function readConfig() {
+  try {
+    const c = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+    if (!c || !c.chromePath) return null;
+    return {
+      chromePath: c.chromePath,
+      port: Number(c.port) || 9222,
+      profile: c.profile || path.join(os.homedir(), '.chrome-debug-profile'),
+    };
+  } catch {
+    return null;
+  }
+}
+
+// True iff a debug Chrome is already answering CDP on the port. Short timeout so
+// the hook never stalls a tool call.
+function isAlive(port) {
+  return new Promise((resolve) => {
+    const req = http.get(
+      { host: '127.0.0.1', port, path: '/json/version', timeout: 1200 },
+      (res) => {
+        res.resume();
+        resolve(res.statusCode === 200);
+      }
+    );
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(false);
+    });
+  });
+}
+
+function launch(cfg) {
+  const args = [
+    `--remote-debugging-port=${cfg.port}`,
+    `--user-data-dir=${cfg.profile}`,
+    '--no-first-run',
+    '--no-default-browser-check',
+  ];
+  // detached + ignored stdio + unref: Chrome survives this short-lived hook
+  // process and keeps the fixed profile alive across the whole session.
+  // windowsHide hides any console wrapper (chrome.exe itself is a GUI app, so
+  // its own window still shows — that is intentional, the user logs in there).
+  const child = spawn(cfg.chromePath, args, {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+  });
+  child.unref();
+}
+
+async function main() {
+  const force = process.argv.includes('--visible') || process.argv.includes('--force');
+  const cfg = readConfig();
+  if (!cfg) process.exit(0); // not configured -> do nothing, never block
+
+  const alive = await isAlive(cfg.port);
+  if (alive && !force) process.exit(0); // healthy -> NEVER touch it, just return
+
+  try {
+    launch(cfg);
+  } catch {
+    process.exit(0);
+  }
+
+  // Poll until ready (~10s max). We never kill anything; if it does not come up
+  // we exit quietly and let the MCP report the connection error.
+  for (let i = 0; i < 20; i++) {
+    await new Promise((r) => setTimeout(r, 500));
+    if (await isAlive(cfg.port)) process.exit(0);
+  }
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));