@nitra/cursor 3.5.0 → 3.6.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [3.6.1] - 2026-06-01
+
+### Fixed
+
+- flow: resolveArtifact обирає артефакт за mtime + пріоритетом slug гілки замість лексикографічного (spec/plan фіксували не той doc при кількох на одну дату)
+
+## [3.6.0] - 2026-06-01
+
+### Added
+
+- flow: команда gate — структурований вердикт релізної готовності (PASS/CONCERNS/FAIL + score + причини, синтез verify-гейтів і review-findings); release м'яко попереджає на FAIL
+
 ## [3.5.0] - 2026-06-01
 
 ### Added

package/package.json

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

package/rules/flow/flow.mdc

@@ -79,7 +79,17 @@ Composer, Claude Code) працює **Пасивний Турнікет**: ти,
 7. **На провал** — виправ код за виводом і виклич `flow verify` знову. Максимум
    **3 спроби**; якщо не вдається — зупинись і поклич людину.
 
-8. **Фініш** — лише після зеленого `verify`:
+8. **Gate (вердикт готовності)** — перед фінішем:
+
+   ```
+   npx @nitra/cursor flow gate
+   ```
+
+   Синтезує verify-гейти і review-findings у `PASS / CONCERNS / FAIL` + score +
+   причини (пише у `.flow.json`). `FAIL` (провалений gate або high-severity
+   finding) → код 1; `release` на FAIL лише попередить (рішення за тобою).
+
+9. **Фініш** — після зеленого `verify` і бажано `gate` ≠ FAIL:
 
    ```
    npx @nitra/cursor flow release --bump <patch|minor|major> --section <Added|Changed|Fixed> --message "<що зроблено>"

package/scripts/dispatcher/index.mjs

@@ -9,6 +9,7 @@
  */
 import { cancel, repair, resume, run } from './lib/active.mjs'
 import { init, release, verify } from './lib/commands.mjs'
+import { gate } from './lib/gate.mjs'
 import { plan } from './lib/plan.mjs'
 import { review } from './lib/review.mjs'
 import { spec } from './lib/spec.mjs'
@@ -20,6 +21,7 @@ const USAGE = [
   '  npx @nitra/cursor flow plan [--panel]     # Фасад A: фаза плану → docs/plans/<…> + state',
   '  npx @nitra/cursor flow verify             # Фасад A: Quality Gates (pass/fail)',
   '  npx @nitra/cursor flow review             # Фасад A: adversarial diff-review (за level)',
+  '  npx @nitra/cursor flow gate               # Фасад A: вердикт PASS/CONCERNS/FAIL (verify+review)',
   '  npx @nitra/cursor flow release            # Фасад A: .changes + completion snapshot',
   '  npx @nitra/cursor flow run "<опис>"       # Фасад B: повний 5-фазний цикл',
   '  npx @nitra/cursor flow resume             # продовжити з чекпойнта',
@@ -28,13 +30,13 @@ const USAGE = [
 ].join('\n')
 
 /** Підкоманди flow. */
-export const SUBCOMMANDS = ['init', 'spec', 'plan', 'verify', 'review', 'release', 'run', 'resume', 'cancel', 'repair']
+export const SUBCOMMANDS = ['init', 'spec', 'plan', 'verify', 'review', 'gate', 'release', 'run', 'resume', 'cancel', 'repair']
 
 /**
  * Усі handler-и реальні (Ф1 Spec/Plan + Ф2 Турнікет + Ф4 Активний Раннер).
  * @type {Record<string, (rest: string[], deps: object) => Promise<number>>}
  */
-export const DEFAULT_HANDLERS = { init, spec, plan, verify, review, release, run, resume, cancel, repair }
+export const DEFAULT_HANDLERS = { init, spec, plan, verify, review, gate, release, run, resume, cancel, repair }
 
 /**
  * Точка входу `case 'flow'` у `bin/n-cursor.js`. Парсить підкоманду й

package/scripts/dispatcher/lib/artifact.mjs

@@ -6,24 +6,36 @@
  * Лінки front-matter (`spec.plan`/`plan.spec`/`plan.flow`) пише сам агент за
  * контрактом `flow.mdc` — тут лише ВЕРИФІКАЦІЯ (мутатора `trace link` нема).
  */
-import { existsSync, readdirSync } from 'node:fs'
+import { existsSync, readdirSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { runTraceCli } from '../trace.mjs'
 
 /**
- * Найсвіжіший `docs/<kind>/*.md` (лексикографічно — дата у префіксі назви).
+ * Резолвить артефакт у `docs/<kind>/`. Пріоритет: файли, чия назва містить
+ * хвіст гілки (slug, напр. `flow-gate` з `claude/flow-gate`); серед них (або
+ * серед усіх, якщо збігу нема) — **найсвіжіший за mtime**. Лексикографічний
+ * вибір був хибним при кількох артефактах на одну дату (виявлено dogfood'ом).
  * @param {string} cwd корінь worktree
  * @param {'specs' | 'plans'} kind підкаталог `docs`
+ * @param {string} [branch] гілка задачі — для пріоритету за slug
  * @returns {string | null} абсолютний шлях або null, якщо каталог/файли відсутні
  */
-export function resolveArtifact(cwd, kind) {
+export function resolveArtifact(cwd, kind, branch) {
   const dir = join(cwd, 'docs', kind)
   if (!existsSync(dir)) return null
-  const md = readdirSync(dir)
-    .filter(f => f.endsWith('.md'))
-    .toSorted()
-  return md.length > 0 ? join(dir, md.at(-1)) : null
+  const md = readdirSync(dir).filter(f => f.endsWith('.md'))
+  if (md.length === 0) return null
+
+  const slug = branch ? branch.split('/').pop() : null
+  const matched = slug ? md.filter(f => f.includes(slug)) : []
+  const pool = matched.length > 0 ? matched : md
+
+  const best = pool
+    .map(f => ({ f, mtime: statSync(join(dir, f)).mtimeMs }))
+    .toSorted((a, b) => a.mtime - b.mtime || (a.f < b.f ? -1 : 1))
+    .at(-1)
+  return join(dir, best.f)
 }
 
 /** Маркер критерію приймання в рядку кроку (порівняння — case-insensitive). */

package/scripts/dispatcher/lib/commands.mjs

@@ -179,6 +179,10 @@ export async function release(rest, deps = {}) {
     log('release: стану нема — спершу `flow init`')
     return 1
   }
+  // М'які ворота: FAIL-гейт — лише попередження, рішення за людиною.
+  if (state.gate?.verdict === 'FAIL') {
+    log(`⚠️ release: gate = FAIL (score ${state.gate.score}) — релізиш свідомо? (див. flow gate)`)
+  }
 
   const ch = run('npx', ['@nitra/cursor', 'change', ...rest], { cwd })
   if ((ch.status ?? 1) !== 0) {

package/scripts/dispatcher/lib/gate.mjs

@@ -0,0 +1,83 @@
+/**
+ * `flow gate` — структурований вердикт релізної готовності (ідея BMAD qa-gate, у
+ * нашому стані). Синтезує механічні гейти `verify` (`state.gates`) і adversarial
+ * findings `review` (`state.review.findings`) у єдине PASS/CONCERNS/FAIL + score
+ * + причини. Дає traceability «чому готово/не готово». `gate` лише агрегує —
+ * рішення verify/review не дублює.
+ *
+ * Уся IO (`now`) ін'єктується; `computeGate` — чиста (тестується без стану на диску).
+ */
+import { cwd as processCwd } from 'node:process'
+
+import { flowEventsPath } from './events.mjs'
+import { flowStatePath, readState, recordTransition } from './state-store.mjs'
+
+/** Штрафи score за кожен тип проблеми. */
+const PENALTY = { failedGate: 40, high: 25, med: 8, noVerify: 15 }
+
+/**
+ * Чистий синтез вердикту з наявного стану.
+ * @param {{ gates?: { name: string, ok: boolean }[], review?: { findings?: { severity?: string }[] } }} state стан flow
+ * @returns {{ verdict: 'PASS' | 'CONCERNS' | 'FAIL', score: number, reasons: string[] }} вердикт
+ */
+export function computeGate(state) {
+  const gates = state.gates ?? []
+  const findings = state.review?.findings ?? []
+  const failedGates = gates.filter(g => !g.ok)
+  const high = findings.filter(f => f.severity === 'high')
+  const med = findings.filter(f => f.severity === 'med')
+  const noVerify = gates.length === 0
+
+  const reasons = []
+  for (const g of failedGates) reasons.push(`gate «${g.name}» провалено`)
+  if (high.length > 0) reasons.push(`${high.length} high-severity review finding(s)`)
+  if (med.length > 0) reasons.push(`${med.length} med-severity review finding(s)`)
+  if (noVerify) reasons.push('verify ще не запускався')
+
+  let verdict = 'PASS'
+  if (failedGates.length > 0 || high.length > 0) {
+    verdict = 'FAIL'
+  } else if (med.length > 0 || noVerify) {
+    verdict = 'CONCERNS'
+  }
+
+  const penalty =
+    PENALTY.failedGate * failedGates.length +
+    PENALTY.high * high.length +
+    PENALTY.med * med.length +
+    (noVerify ? PENALTY.noVerify : 0)
+  const score = Math.max(0, Math.min(100, 100 - penalty))
+
+  return { verdict, score, reasons }
+}
+
+/**
+ * `flow gate` — обчислює й фіксує вердикт у `.flow.json`.
+ * @param {string[]} _rest аргументи (не використовуються)
+ * @param {{ cwd?: string, log?: (m: string) => void, now?: () => number }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code (FAIL → 1; PASS/CONCERNS → 0)
+ */
+export async function gate(_rest, deps = {}) {
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const now = deps.now ?? Date.now
+
+  const statePath = flowStatePath(cwd)
+  const state = readState(statePath)
+  if (!state) {
+    log('gate: стану нема — спершу `flow init`')
+    return 1
+  }
+
+  const result = computeGate(state)
+  recordTransition(
+    { statePath, eventsPath: flowEventsPath(cwd) },
+    { type: 'gate', verdict: result.verdict },
+    s => ({ ...s, gate: { ...result, at: new Date(now()).toISOString() } }),
+    now
+  )
+
+  log(`gate: ${result.verdict} (score ${result.score})`)
+  for (const r of result.reasons) log(`  · ${r}`)
+  return result.verdict === 'FAIL' ? 1 : 0
+}

package/scripts/dispatcher/lib/plan.mjs

@@ -35,7 +35,7 @@ export async function plan(rest, deps = {}) {
     log('plan: дизайн ще не зафіксовано — рекомендовано спершу `flow spec` (не блокує)')
   }
 
-  const doc = rest.find(a => a.endsWith('.md')) ?? resolveArtifact(cwd, 'plans')
+  const doc = rest.find(a => a.endsWith('.md')) ?? resolveArtifact(cwd, 'plans', state.branch)
   let steps
   if (rest.includes('--panel')) {
     let runner = deps.runner

package/scripts/dispatcher/lib/spec.mjs

@@ -48,7 +48,7 @@ export async function spec(rest, deps = {}) {
     }
   }
 
-  const doc = rest.find(a => a.endsWith('.md')) ?? resolveArtifact(cwd, 'specs')
+  const doc = rest.find(a => a.endsWith('.md')) ?? resolveArtifact(cwd, 'specs', state.branch)
   if (!doc || !existsSync(doc)) {
     log('spec: нема docs/specs/<date>-<slug>.md — спершу пройди brainstorm (див. flow.mdc)')
     return 1