@nitra/cursor 3.2.2 → 3.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [3.3.0] - 2026-06-01
+
+### Added
+
+- flow: фази spec і plan (brainstorm human↔agent + agent↔agent --panel), trace простежує лінк plan→flow, verify м'яко попереджає про відсутній план
+
+## [3.2.3] - 2026-06-01
+
+### Fixed
+
+- k8s `workloadAppLabel`: CronJob/workload без `spec` (чи `spec: null`) повертає `null` замість TypeError — `check k8s` більше не падає на неповному маніфесті
+
 ## [3.2.2] - 2026-06-01
 
 ### Changed

package/package.json

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

package/rules/flow/flow.mdc

@@ -1,5 +1,5 @@
 ---
-description: Контракт Пасивного Турнікета n-cursor flow — IDE-агент сам пише код, але ізолює/перевіряє/релізить через flow init/verify/release.
+description: Контракт Пасивного Турнікета n-cursor flow — IDE-агент сам пише код, але ізолює/планує/перевіряє/релізить через flow init/spec/plan/verify/release.
 globs:
 alwaysApply: true
 ---
@@ -22,9 +22,38 @@ Composer, Claude Code) працює **Пасивний Турнікет**: ти,
    Створює ізольований worktree (`.worktrees/<branch>/`) і стан задачі. Якщо ти
    вже в worktree — новий не вкладається.
 
-2. **Пиши код** сам, кроками. TDD: спершу падаючі тести, тоді реалізація.
+2. **Spec (дизайн)** — рекомендовано, не блокує. Brainstorm нашими термінами
+   (НЕ викликаючи superpowers):
 
-3. **Перевіряй** після кожного логічного кроку:
+   - **human↔agent (дефолт):** питання по одному (перевага multiple-choice) →
+     2-3 підходи з рекомендацією → дизайн секціями з апрувом людини;
+   - **agent↔agent:** `npx @nitra/cursor flow spec --panel` — панель персон
+     (architect/skeptic/tester) → суддя-синтез; презентуй синтез людині.
+
+   Збережи дизайн → `docs/specs/<date>-<slug>.md` (`kind: nitra-spec`,
+   `plan: null`), тоді зафіксуй:
+
+   ```
+   npx @nitra/cursor flow spec
+   ```
+
+3. **План** — декомпозиція дизайну в кроки:
+
+   - збережи `docs/plans/<date>-<slug>.md` (`kind: nitra-plan`, `spec:` → лінк на
+     spec, `flow:` → шлях `.flow.json`; секція `## Кроки` — нумерований список
+     `N. <task> — acceptance: <критерій>`);
+   - зафіксуй (`--panel` — для agent↔agent синтезу кроків):
+
+   ```
+   npx @nitra/cursor flow plan
+   ```
+
+   Команда дзеркалить кроки у `.flow.json` (`status: planned`) і запускає `trace`
+   для перевірки ланцюга spec↔plan↔flow. `verify` без плану лише попередить.
+
+4. **Пиши код** сам, кроками. TDD: спершу падаючі тести, тоді реалізація.
+
+5. **Перевіряй** після кожного логічного кроку:
 
    ```
    npx @nitra/cursor flow verify
@@ -33,10 +62,10 @@ Composer, Claude Code) працює **Пасивний Турнікет**: ти,
    Проганяє Quality Gates (lint + coverage). Повертає `0` (pass) або `1` із
    виводом проваленого gate.
 
-4. **На провал** — виправ код за виводом і виклич `flow verify` знову. Максимум
+6. **На провал** — виправ код за виводом і виклич `flow verify` знову. Максимум
    **3 спроби**; якщо не вдається — зупинись і поклич людину.
 
-5. **Фініш** — лише після зеленого `verify`:
+7. **Фініш** — лише після зеленого `verify`:
 
    ```
    npx @nitra/cursor flow release --bump <patch|minor|major> --section <Added|Changed|Fixed> --message "<що зроблено>"
@@ -49,3 +78,5 @@ Composer, Claude Code) працює **Пасивний Турнікет**: ти,
 - Не обходь `verify` — це єдиний критерій «готово».
 - Не редагуй `version` чи `CHANGELOG.md` вручну (це робить CI з `.changes/`).
 - Не коміть стан `.worktrees/<branch>.flow.json` у гілку — він поза git.
+- Не лінкуй spec↔plan неконсистентно — тримай `spec.plan`/`plan.spec`/`plan.flow`
+  у front-matter; `flow spec`/`flow plan` перевіряють їх через `trace`.

package/rules/k8s/js/manifests.mjs

@@ -4044,13 +4044,13 @@ function appLabelFromPodTemplate(spec) {
 export function workloadAppLabel(manifest) {
   const kind = manifest.kind
   if (typeof kind !== 'string') return null
+  const spec = getNestedObject(manifest, 'spec')
+  if (spec === null) return null
   if (kind === 'CronJob') {
-    const jobTemplate = getNestedObject(getNestedObject(manifest, 'spec'), 'jobTemplate')
+    const jobTemplate = getNestedObject(spec, 'jobTemplate')
     const jobSpec = jobTemplate === null ? null : getNestedObject(jobTemplate, 'spec')
     return jobSpec === null ? null : appLabelFromPodTemplate(jobSpec)
   }
-  const spec = getNestedObject(manifest, 'spec')
-  if (spec === null) return null
   if (kind === 'Job') return appLabelFromPodTemplate(spec)
   return appLabelFromSpecSelector(spec)
 }

package/scripts/dispatcher/index.mjs

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

package/scripts/dispatcher/lib/artifact.mjs

@@ -0,0 +1,67 @@
+/**
+ * Спільні утиліти фаз `spec`/`plan` (Пасивний Турнікет): резолв traceable-
+ * артефакту в `docs/<kind>/`, екстракт кроків плану зі секції `## Кроки`, і
+ * read-only перевірка цілісності ланцюга через `n-cursor trace` (`trace.mjs`).
+ *
+ * Лінки front-matter (`spec.plan`/`plan.spec`/`plan.flow`) пише сам агент за
+ * контрактом `flow.mdc` — тут лише ВЕРИФІКАЦІЯ (мутатора `trace link` нема).
+ */
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { runTraceCli } from '../trace.mjs'
+
+/**
+ * Найсвіжіший `docs/<kind>/*.md` (лексикографічно — дата у префіксі назви).
+ * @param {string} cwd корінь worktree
+ * @param {'specs' | 'plans'} kind підкаталог `docs`
+ * @returns {string | null} абсолютний шлях або null, якщо каталог/файли відсутні
+ */
+export function resolveArtifact(cwd, kind) {
+  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
+}
+
+/** Маркер критерію приймання в рядку кроку (порівняння — case-insensitive). */
+const ACCEPTANCE_MARK = '— acceptance:'
+/** Лише цифри — перевірка нумерації кроку (лінійний, без backtracking). */
+const DIGITS_RE = /^\d+$/u
+
+/**
+ * Кроки зі секції плану — нумерований список `N. <task> — acceptance: <crit>`.
+ * Best-effort парсинг через `indexOf` (без regex-backtracking): рядки поза
+ * форматом ігноруються.
+ * @param {string} text вміст plan-doc
+ * @returns {{ task: string, acceptance?: string }[]} кроки у порядку появи
+ */
+export function extractSteps(text) {
+  const steps = []
+  for (const raw of String(text).split('\n')) {
+    const line = raw.trim()
+    const dot = line.indexOf('. ')
+    if (dot <= 0 || !DIGITS_RE.test(line.slice(0, dot))) continue
+    const body = line.slice(dot + 2).trim()
+    const sep = body.toLowerCase().indexOf(ACCEPTANCE_MARK)
+    if (sep === -1) {
+      steps.push({ task: body })
+    } else {
+      steps.push({ task: body.slice(0, sep).trim(), acceptance: body.slice(sep + ACCEPTANCE_MARK.length).trim() })
+    }
+  }
+  return steps
+}
+
+/**
+ * Read-only перевірка цілісності ланцюга артефактів (не мутує — лише сигнал).
+ * @param {string} cwd корінь worktree
+ * @param {(cwd: string) => number} [runTrace] runner trace (0 — цілісно, 1 — розрив); ін'єкція для тестів
+ * @returns {boolean} true, якщо ланцюг цілісний
+ */
+export function verifyTrace(cwd, runTrace) {
+  const run = runTrace ?? (c => runTraceCli([], { cwd: c, log: () => {} }))
+  return run(cwd) === 0
+}

package/scripts/dispatcher/lib/commands.mjs

@@ -126,6 +126,13 @@ export async function verify(_rest, deps = {}) {
   const log = deps.log ?? console.error
   const fingerprint = deps.fingerprint ?? (() => worktreeFingerprint())
 
+  const statePath = flowStatePath(cwd)
+  const state = readState(statePath)
+  // М'які ворота: відсутній план — лише попередження, exit-код визначають gate-и.
+  if (state && !(state.plan?.length)) {
+    log('⚠️ verify: плану не зафіксовано (`flow plan`) — рекомендовано спершу сформувати план')
+  }
+
   const verdict = runReview({ run, cwd, fingerprint })
 
   for (const g of verdict.gates) {
@@ -134,8 +141,7 @@ export async function verify(_rest, deps = {}) {
   if (!verdict.pass && verdict.failedOutput) log(verdict.failedOutput)
   log(verdict.pass ? '✅ verify: усі gate-и пройдено' : '❌ verify: провалено')
 
-  const statePath = flowStatePath(cwd)
-  if (readState(statePath)) {
+  if (state) {
     recordTransition(
       { statePath, eventsPath: flowEventsPath(cwd) },
       { type: 'verify', pass: verdict.pass },

package/scripts/dispatcher/lib/plan-panel.mjs

@@ -0,0 +1,76 @@
+/**
+ * Agent↔agent brainstorm (bmad party-mode + superpowers dispatching у наших
+ * термінах): персони-субагенти пропонують погляди, суддя-субагент синтезує одну
+ * відповідь. Спільний для фази `spec` (mode: 'spec' — підходи) і `plan`
+ * (mode: 'plan' — JSON-кроки). Перевикористовує runner-інтерфейс Фасада B
+ * (`runStep(prompt, opts) => { ok, output }`, як `planner.mjs`/`active.mjs`).
+ *
+ * HITL: panel лише ПОВЕРТАЄ синтез — апрув людини й збереження артефакту робить
+ * агент за контрактом `flow.mdc` (фіксація — окрема команда `flow spec`/`flow plan`).
+ */
+
+/** Персони панелі: [ім'я, системний промпт]. */
+const PERSONAS = [
+  ['architect', 'Ти — architect. Запропонуй найчистішу архітектуру розв’язання. Стисло, по суті.'],
+  ['skeptic', 'Ти — skeptic. Назви ризики, граничні випадки і що може піти не так. Стисло.'],
+  ['tester', 'Ти — tester. Опиши, які тести доведуть коректність. Стисло.']
+]
+
+/**
+ * Промпт судді за режимом.
+ * @param {'spec' | 'plan'} mode режим синтезу
+ * @param {string} proposals склеєні думки персон
+ * @param {string} task опис задачі
+ * @returns {string} промпт судді
+ */
+function judgePrompt(mode, proposals, task) {
+  const head =
+    mode === 'plan'
+      ? [
+          'Синтезуй із думок персон ОДИН покроковий план реалізації.',
+          'Кожен крок — ≤ 5 хв розробки, з критерієм приймання.',
+          'Поверни ЛИШЕ JSON-масив без коментарів: [{ "task": "...", "acceptance": "..." }, ...].'
+        ]
+      : [
+          'Синтезуй із думок персон 2-3 підходи до розв’язання з рекомендацією й коротким дизайном.',
+          'Поверни людино-читабельний текст (Markdown).'
+        ]
+  return [...head, '', proposals, '', `Задача: ${task}`].join('\n')
+}
+
+/**
+ * Проводить панель і повертає синтез.
+ * @param {{ task: string, cwd: string, runner: { runStep: (p: string, o?: object) => { ok: boolean, output: string } | Promise<{ ok: boolean, output: string }> }, log?: (m: string) => void, mode?: 'spec' | 'plan' }} input ін'єкції
+ * @returns {Promise<{ task: string, acceptance?: string }[] | string | null>} кроки (plan), текст (spec) або null (фейл)
+ */
+export async function runPanel({ task, cwd, runner, log = console.error, mode = 'plan' }) {
+  if (!runner) {
+    log('panel: нема runner — режим --panel недоступний')
+    return null
+  }
+  const proposals = await Promise.all(
+    PERSONAS.map(async ([name, sys]) => {
+      const r = await runner.runStep(`${sys}\n\nЗадача: ${task}`, { cwd })
+      return `### ${name}\n${r.ok ? r.output : '(порожньо)'}`
+    })
+  )
+  const judge = await runner.runStep(judgePrompt(mode, proposals.join('\n\n'), task), { cwd })
+  if (!judge.ok) {
+    log('panel: суддя-синтез завершився помилкою')
+    return null
+  }
+  if (mode === 'spec') return judge.output
+
+  const start = judge.output.indexOf('[')
+  const end = judge.output.lastIndexOf(']')
+  if (start === -1 || end === -1 || end < start) {
+    log('panel: суддя не повернув JSON-план')
+    return null
+  }
+  try {
+    return JSON.parse(judge.output.slice(start, end + 1))
+  } catch {
+    log('panel: невалідний JSON синтезу')
+    return null
+  }
+}

package/scripts/dispatcher/lib/plan.mjs

@@ -0,0 +1,80 @@
+/**
+ * `flow plan [--panel] [<plan.md>]` — фаза плану (Пасивний Турнікет, lifecycle
+ * §4). Фіксує `docs/plans/<date>-<slug>.md`: дзеркалить кроки (`## Кроки`) у
+ * `.flow.json plan[]`, виставляє `status: planned`, верифікує ланцюг через
+ * read-only `trace`. Код не пише; лінки front-matter (`spec`/`flow`) пише агент.
+ *
+ * Brainstorm: human↔agent (агент пише plan-doc у діалозі) або agent↔agent
+ * (`--panel`: панель персон → суддя синтезує кроки).
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { cwd as processCwd } from 'node:process'
+
+import { extractSteps, resolveArtifact, verifyTrace } from './artifact.mjs'
+import { flowEventsPath } from './events.mjs'
+import { parsePlan } from './planner.mjs'
+import { runPanel } from './plan-panel.mjs'
+import { createRunner } from './subagent-runner.mjs'
+import { flowStatePath, readState, recordTransition } from './state-store.mjs'
+
+/**
+ * @param {string[]} rest аргументи (`--panel`, опц. `<plan.md>`)
+ * @param {{ cwd?: string, log?: (m: string) => void, runner?: object, trace?: (cwd: string) => number, now?: () => number }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code (0 ok, 1 нема стану/доку/невалідний план)
+ */
+export async function plan(rest, deps = {}) {
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const statePath = flowStatePath(cwd)
+  const state = readState(statePath)
+  if (!state) {
+    log('plan: стану нема — спершу `flow init`')
+    return 1
+  }
+  if (state.status !== 'spec' && !state.spec_doc) {
+    log('plan: дизайн ще не зафіксовано — рекомендовано спершу `flow spec` (не блокує)')
+  }
+
+  const doc = rest.find(a => a.endsWith('.md')) ?? resolveArtifact(cwd, 'plans')
+  let steps
+  if (rest.includes('--panel')) {
+    let runner = deps.runner
+    if (!runner) {
+      try {
+        runner = await createRunner(deps)
+      } catch (error) {
+        log(`plan: ${error.message}`)
+        return 1
+      }
+    }
+    steps = await runPanel({ task: state.branch, cwd, runner, log, mode: 'plan' })
+    if (!steps) return 1
+  } else {
+    if (!doc || !existsSync(doc)) {
+      log('plan: нема docs/plans/<date>-<slug>.md — спершу пройди brainstorm (див. flow.mdc)')
+      return 1
+    }
+    steps = extractSteps(readFileSync(doc, 'utf8'))
+  }
+
+  let normalized
+  try {
+    normalized = parsePlan(JSON.stringify(steps))
+  } catch (error) {
+    log(`plan: ${error.message}`)
+    return 1
+  }
+
+  if (!verifyTrace(cwd, deps.trace)) {
+    log('⚠️ plan: trace виявив розрив ланцюга — перевір лінки spec/plan/flow')
+  }
+
+  recordTransition(
+    { statePath, eventsPath: flowEventsPath(cwd) },
+    { type: 'plan', steps: normalized.length },
+    s => ({ ...s, plan: normalized, plan_doc: doc ?? null, status: 'planned' }),
+    deps.now ?? Date.now
+  )
+  log(`plan: зафіксовано ${normalized.length} кроків → status: planned`)
+  return 0
+}

package/scripts/dispatcher/lib/planner.mjs

@@ -4,6 +4,9 @@
  * Нормалізує кроки до `{ step, task, status: 'pending', retry_count: 0 }`.
  */
 
+/** Заборонені плейсхолдер-значення `task` (план із ними — не план, fail-closed). */
+const PLACEHOLDER = /^(tbd|todo|fixme|\.\.\.|placeholder)$/i
+
 /**
  * Системно-користувацький промпт планувальника.
  * @param {string} task опис фічі
@@ -45,6 +48,10 @@ export function parsePlan(text) {
     if (!task || typeof task !== 'string') {
       throw new Error(`planner: крок ${i} без текстового поля task — fail-closed`)
     }
+    const trimmed = task.trim()
+    if (!trimmed || PLACEHOLDER.test(trimmed)) {
+      throw new Error(`planner: крок ${i} — placeholder/порожній task (${task}) — fail-closed`)
+    }
     const step = { step: i, task, status: 'pending', retry_count: 0 }
     if (s?.acceptance) step.acceptance = String(s.acceptance)
     return step

package/scripts/dispatcher/lib/spec.mjs

@@ -0,0 +1,68 @@
+/**
+ * `flow spec [--panel] [<spec.md>]` — фаза дизайну (Пасивний Турнікет, lifecycle
+ * §3). Фіксує `docs/specs/<date>-<slug>.md` (дизайн із brainstorm) у стані й
+ * верифікує ланцюг через read-only `trace`. Код не пише; лінки front-matter
+ * пише агент за контрактом `flow.mdc`.
+ *
+ * Brainstorm: human↔agent — у діалозі IDE-агента (контракт); agent↔agent —
+ * `--panel` (панель персон → суддя, синтез презентується людині).
+ */
+import { existsSync } from 'node:fs'
+import { cwd as processCwd } from 'node:process'
+
+import { resolveArtifact, verifyTrace } from './artifact.mjs'
+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'
+
+/**
+ * @param {string[]} rest аргументи (`--panel`, опц. `<spec.md>`)
+ * @param {{ cwd?: string, log?: (m: string) => void, runner?: object, trace?: (cwd: string) => number, now?: () => number }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code (0 ok, 1 нема стану/доку)
+ */
+export async function spec(rest, deps = {}) {
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const statePath = flowStatePath(cwd)
+  const state = readState(statePath)
+  if (!state) {
+    log('spec: стану нема — спершу `flow init`')
+    return 1
+  }
+
+  if (rest.includes('--panel')) {
+    let runner = deps.runner
+    if (!runner) {
+      try {
+        runner = await createRunner(deps)
+      } catch (error) {
+        log(`spec: ${error.message}`)
+        return 1
+      }
+    }
+    const synth = await runPanel({ task: state.branch, cwd, runner, log, mode: 'spec' })
+    if (synth) {
+      log('spec: панель синтезувала підходи (нижче) — збережи дизайн у docs/specs/ і повтори `flow spec`:')
+      log(typeof synth === 'string' ? synth : JSON.stringify(synth))
+    }
+  }
+
+  const doc = rest.find(a => a.endsWith('.md')) ?? resolveArtifact(cwd, 'specs')
+  if (!doc || !existsSync(doc)) {
+    log('spec: нема docs/specs/<date>-<slug>.md — спершу пройди brainstorm (див. flow.mdc)')
+    return 1
+  }
+  if (!verifyTrace(cwd, deps.trace)) {
+    log('⚠️ spec: trace виявив розрив ланцюга — перевір лінки front-matter (adr/spec/plan)')
+  }
+
+  recordTransition(
+    { statePath, eventsPath: flowEventsPath(cwd) },
+    { type: 'spec' },
+    s => ({ ...s, spec_doc: doc, status: 'spec' }),
+    deps.now ?? Date.now
+  )
+  log(`spec: зафіксовано ${doc} → status: spec`)
+  return 0
+}

package/scripts/dispatcher/trace.mjs

@@ -11,7 +11,7 @@ import { join } from 'node:path'
 import { cwd as processCwd } from 'node:process'
 
 /** Поля-лінки у front-matter, що утворюють ланцюг. */
-const LINK_FIELDS = ['adr', 'spec', 'plan', 'change', 'task']
+const LINK_FIELDS = ['adr', 'spec', 'plan', 'flow', 'change', 'task']
 
 /** Каталоги з traceable-артефактами. */
 const DIRS = ['docs/tasks', 'docs/specs', 'docs/plans', 'docs/adr']