@nitra/cursor 3.6.1 → 3.8.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [3.8.0] - 2026-06-01
+
+### Added
+
+- flow: контракт — advanced elicitation (меню технік поглиблення вимог у фазі spec: Expand/Contract, Critique&Refine, Identify Risks, Tree-of-Thoughts, Stakeholder Roundtable, Self-Consistency; Elicitation History у спеці)
+
+## [3.7.0] - 2026-06-01
+
+### Added
+
+- flow: risk-aware глибина review — detectRisk у init + risk зі spec-frontmatter керують кількістю рецензентів (max за рівнем і ризиком) і безпековим фокусом промпта
+
 ## [3.6.1] - 2026-06-01
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "3.6.1",
+  "version": "3.8.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/flow/flow.mdc

@@ -21,9 +21,11 @@ Composer, Claude Code) працює **Пасивний Турнікет**: ти,
 
    Створює ізольований worktree (`.worktrees/<branch>/`) і стан задачі. Якщо ти
    вже в worktree — новий не вкладається. `init` визначає **рівень** задачі
-   (L0 тривіальне … L3 архітектурне) за описом: для L0 (fix/typo/bump) фази
-   Spec/План можна пропустити; для L≥1 вони рекомендовані. Рівень також керує
-   глибиною `review`.
+   (L0 тривіальне … L3 архітектурне) і **ризик** (low/med/high — за описом:
+   security/auth/secret → high) за описом: для L0 (fix/typo/bump) фази Spec/План
+   можна пропустити; для L≥1 вони рекомендовані. Рівень **і ризик** разом керують
+   глибиною та фокусом `review`. Ризик можна уточнити полем `risk:` у frontmatter
+   spec — `flow spec` його підхопить.
 
 2. **Spec (дизайн)** — рекомендовано, не блокує. Brainstorm нашими термінами
    (НЕ викликаючи superpowers):
@@ -33,6 +35,20 @@ Composer, Claude Code) працює **Пасивний Турнікет**: ти,
    - **agent↔agent:** `npx @nitra/cursor flow spec --panel` — панель персон
      (architect/skeptic/tester) → суддя-синтез; презентуй синтез людині.
 
+   **Поглиблення (advanced elicitation, за потреби).** Якщо чернетка дизайну
+   «сира» чи є непевність — запропонуй людині одну з технік (по одній за раз),
+   застосуй обрану, повтори до «досить»:
+
+   - **Expand / Contract** — розгорнути деталь, що бракує, або згорнути зайве до суті;
+   - **Critique & Refine** — самокритика чернетки (слабкі місця, припущення), тоді доопрацювання;
+   - **Identify Risks** — явно перелічити ризики/граничні випадки (наповнює поле `risk:` у frontmatter);
+   - **Tree-of-Thoughts** — кілька гілок рішення паралельно, обрати найкращу з обґрунтуванням;
+   - **Stakeholder Roundtable** — пройтись поглядами ролей (user / ops / security / maintainer);
+   - **Self-Consistency** — 2-3 незалежні версії відповіді, звірити на суперечності.
+
+   Що застосовано — фіксуй коротко в секції `## Elicitation History` спеки
+   (traceability рішень).
+
    Збережи дизайн → `docs/specs/<date>-<slug>.md` (`kind: nitra-spec`,
    `plan: null`), тоді зафіксуй:
 
@@ -72,9 +88,10 @@ Composer, Claude Code) працює **Пасивний Турнікет**: ти,
    ```
 
    Незалежний субагент читає ЛИШЕ `git diff` від `base_commit` і шукає логічні
-   баги/ризики, яких не ловлять механічні гейти. Кількість рецензентів — за
-   рівнем (L0→1 … L3→3). Findings пишуться у `.flow.json` (не блокує); high-
-   severity варто виправити перед фінішем.
+   баги/ризики, яких не ловлять механічні гейти. Кількість рецензентів —
+   `max(рівень, ризик)` (L0→1 … L3→3; high-risk → 3, з безпековим фокусом
+   промпта). Findings пишуться у `.flow.json` (не блокує); high-severity варто
+   виправити перед фінішем.
 
 7. **На провал** — виправ код за виводом і виклич `flow verify` знову. Максимум
    **3 спроби**; якщо не вдається — зупинись і поклич людину.

package/scripts/dispatcher/lib/commands.mjs

@@ -12,7 +12,7 @@ import { cwd as processCwd } from 'node:process'
 import { worktreePaths } from '../../lib/worktree.mjs'
 import { worktreeFingerprint } from '../../utils/worktree-fingerprint.mjs'
 import { flowEventsPath } from './events.mjs'
-import { detectLevel } from './level.mjs'
+import { detectLevel, detectRisk } from './level.mjs'
 import { runReview } from './reviewer.mjs'
 import { buildCompletionSnapshot, writeSummaryToTaskRecord } from './snapshot.mjs'
 import { flowStatePath, readState, recordTransition, writeState } from './state-store.mjs'
@@ -103,15 +103,17 @@ export async function init(rest, deps = {}) {
   const log = deps.log ?? console.error
   const statePath = flowStatePath(ew.worktreeDir)
   const level = detectLevel(ew.desc)
+  const risk = detectRisk(ew.desc)
   writeState(statePath, {
     branch: ew.branch,
     status: 'in_progress',
     started_at: new Date(now()).toISOString(),
     metadata: { base_commit: ew.baseCommit },
     level,
+    risk,
     plan: []
   })
-  log(`init: ${ew.branch} (level ${level}) → ${statePath}`)
+  log(`init: ${ew.branch} (level ${level}, risk ${risk}) → ${statePath}`)
   return 0
 }
 

package/scripts/dispatcher/lib/level.mjs

@@ -1,7 +1,8 @@
 /**
- * Scale-adaptive рівень задачі (ідея з BMAD project-levels, у наших термінах).
- * `init` визначає рівень за описом; рівень right-size'ить, скільки adversarial-
- * рецензентів спавнить `flow review`, і які фази рекомендовані (контракт).
+ * Scale-adaptive рівень + ризик задачі (ідея з BMAD project-levels/risk-profile,
+ * у наших термінах). `init` визначає рівень і ризик за описом; разом вони
+ * right-size'ять, скільки adversarial-рецензентів спавнить `flow review` (і його
+ * фокус), і які фази рекомендовані (контракт).
  *
  * Детекція — підрядками (case-insensitive), без regex (уникаємо slow-regex і
  * проблем зі словомежами для кирилиці).
@@ -30,7 +31,7 @@ export function detectLevel(desc) {
 }
 
 /**
- * Скільки adversarial-рецензентів спавнити для рівня (глибина review за ризиком).
+ * Скільки adversarial-рецензентів спавнити для рівня (глибина review за розміром).
  * @param {number} level рівень 0..3
  * @returns {number} кількість рецензентів (1..3)
  */
@@ -39,3 +40,42 @@ export function reviewersForLevel(level) {
   if (level === 2) return 2
   return 1
 }
+
+/** Ключові слова високого ризику (безпека/гроші/доступи). */
+const HIGH_RISK_KEYS = ['security', 'auth', 'crypto', 'payment', 'secret', 'token', 'permission', 'password', 'безпек']
+/** Ключові слова середнього ризику (дані/незворотність). */
+const MED_RISK_KEYS = ['data', ' db', 'database', 'migration', 'delete', 'gateway', 'міграц', 'видален']
+
+/**
+ * Рівень ризику задачі за описом: low | med | high.
+ * @param {string} desc опис задачі
+ * @returns {'low' | 'med' | 'high'} ризик
+ */
+export function detectRisk(desc) {
+  const d = String(desc ?? '').toLowerCase()
+  const has = keys => keys.some(k => d.includes(k))
+  if (has(HIGH_RISK_KEYS)) return 'high'
+  if (has(MED_RISK_KEYS)) return 'med'
+  return 'low'
+}
+
+/**
+ * Скільки рецензентів диктує сам ризик.
+ * @param {string} risk low|med|high
+ * @returns {number} 1..3
+ */
+export function reviewersForRisk(risk) {
+  if (risk === 'high') return 3
+  if (risk === 'med') return 2
+  return 1
+}
+
+/**
+ * Підсумкова глибина review: максимум вимог за рівнем і за ризиком (кап 3).
+ * @param {number} level рівень 0..3
+ * @param {string} [risk] low|med|high
+ * @returns {number} кількість рецензентів (1..3)
+ */
+export function reviewersFor(level, risk) {
+  return Math.min(3, Math.max(reviewersForLevel(level), reviewersForRisk(risk)))
+}

package/scripts/dispatcher/lib/review.mjs

@@ -11,7 +11,7 @@ import { cwd as processCwd } from 'node:process'
 
 import { realRun } from './commands.mjs'
 import { flowEventsPath } from './events.mjs'
-import { reviewersForLevel } from './level.mjs'
+import { reviewersFor } from './level.mjs'
 import { flowStatePath, readState, recordTransition } from './state-store.mjs'
 import { createRunner } from './subagent-runner.mjs'
 
@@ -32,18 +32,27 @@ export function diffFromBase(base, run, cwd) {
 }
 
 /**
- * Промпт adversarial-рецензента (читає ЛИШЕ diff).
+ * Промпт adversarial-рецензента (читає ЛИШЕ diff). Для high-risk додає
+ * безпекову лінзу.
  * @param {string} diff текст diff
+ * @param {string} [risk] low|med|high — фокус перевірки
  * @returns {string} промпт
  */
-export function reviewerPrompt(diff) {
+export function reviewerPrompt(diff, risk) {
+  const lens =
+    risk === 'high'
+      ? 'ОСОБЛИВА УВАГА БЕЗПЕЦІ: auth/доступи, секрети/токени, ін\'єкції, валідація входу, незворотні операції.'
+      : ''
   return [
     'Ти — прискіпливий adversarial-рецензент. Знайди баги, ризики й smells ЛИШЕ в цьому diff.',
+    lens,
     'Поверни ЛИШЕ JSON-масив: [{ "severity": "high|med|low", "file": "...", "issue": "...", "suggestion": "..." }].',
     'Якщо проблем нема — поверни [].',
     '',
     diff.slice(0, DIFF_LIMIT)
-  ].join('\n')
+  ]
+    .filter(Boolean)
+    .join('\n')
 }
 
 /**
@@ -128,8 +137,8 @@ export async function review(_rest, deps = {}) {
     }
   }
 
-  const reviewers = reviewersForLevel(state.level ?? 1)
-  const prompt = reviewerPrompt(diff)
+  const reviewers = reviewersFor(state.level ?? 1, state.risk)
+  const prompt = reviewerPrompt(diff, state.risk)
   const results = await Promise.all(Array.from({ length: reviewers }, () => runner.runStep(prompt, { cwd })))
   const findings = dedupeFindings(results.flatMap(r => (r.ok ? parseFindings(r.output) : [])))
 

package/scripts/dispatcher/lib/spec.mjs

@@ -7,7 +7,7 @@
  * Brainstorm: human↔agent — у діалозі IDE-агента (контракт); agent↔agent —
  * `--panel` (панель персон → суддя, синтез презентується людині).
  */
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { cwd as processCwd } from 'node:process'
 
 import { resolveArtifact, verifyTrace } from './artifact.mjs'
@@ -15,6 +15,26 @@ import { flowEventsPath } from './events.mjs'
 import { runPanel } from './plan-panel.mjs'
 import { createRunner } from './subagent-runner.mjs'
 import { flowStatePath, readState, recordTransition } from './state-store.mjs'
+import { parseFrontMatter } from '../trace.mjs'
+
+/** Допустимі значення ризику у spec-frontmatter. */
+const RISKS = new Set(['low', 'med', 'high'])
+
+/**
+ * Зчитує `risk` зі spec-frontmatter, якщо валідний (інакше — поточний у стані).
+ * Так risk-нотатка у spec керує глибиною подальшого `flow review`.
+ * @param {string} doc шлях spec-doc
+ * @param {string | undefined} current поточний risk у стані
+ * @returns {string | undefined} ризик
+ */
+function riskFromSpec(doc, current) {
+  try {
+    const fm = parseFrontMatter(readFileSync(doc, 'utf8'))
+    return fm && RISKS.has(fm.risk) ? fm.risk : current
+  } catch {
+    return current
+  }
+}
 
 /**
  * @param {string[]} rest аргументи (`--panel`, опц. `<spec.md>`)
@@ -57,12 +77,13 @@ export async function spec(rest, deps = {}) {
     log('⚠️ spec: trace виявив розрив ланцюга — перевір лінки front-matter (adr/spec/plan)')
   }
 
+  const risk = riskFromSpec(doc, state.risk)
   recordTransition(
     { statePath, eventsPath: flowEventsPath(cwd) },
     { type: 'spec' },
-    s => ({ ...s, spec_doc: doc, status: 'spec' }),
+    s => ({ ...s, spec_doc: doc, risk, status: 'spec' }),
     deps.now ?? Date.now
   )
-  log(`spec: зафіксовано ${doc} → status: spec`)
+  log(`spec: зафіксовано ${doc} → status: spec (risk ${risk ?? '—'})`)
   return 0
 }