@dzhechkov/skills-feature-adr 1.3.50 → 1.3.52

package/README.md

@@ -410,6 +410,25 @@ Fixed roles map to fixed stages (`product-vision`→design+QE, `critic`→QE, `b
 open `extra` list adds guidance to any stage. `dz project-skills` prints the who-injected report. Absent ⇒ a
 normal generic run. (See `dz mr-rakes --gen-critic` to auto-generate the `critic` skill from your recurring rakes.)
 
+### Adversarial plan-gate at the L/XL checkpoint (needs `dz` ≥ 0.3.117)
+
+Cross-model QE (Step 8) catches problems *after* the code is written. At the **checkpoint-after-plan** the
+pipeline now also runs an adversarial **challenge panel** on the plan itself — a FRESH reviewer that did **not**
+write the plan tries to BREAK it across a fixed C1-C8 owner-question set (arch-anti-cement, prod-ready, test
+sufficiency + honesty, overengineering, silent decisions, runtime consistency, scope, executability):
+
+- **Panel ≠ plan author** (hard invariant): if Claude wrote the plan the adversary is Codex (honest `codex exec`,
+  never a fire-and-forget stub); if Codex wrote it the adversary is a fresh Claude. An unknown family never
+  silently claims cross-family.
+- **Every P0/P1 is cross-validated** by a second independent agent, matched by index (never by title), and the
+  non-validated ones are dropped — theory never reaches you. If the validator can't cover them, they are
+  surfaced **UNVALIDATED**, never silently dropped.
+- **Advisory** — the verdict returns as `challengeVerdict` alongside the ADR + plan; it **never auto-blocks**.
+- Calibrated by `architecture/vision.md` + `testing.md` + `map.json` + `architecture/degradations.md` (a
+  deviation from a pattern registered in the degradations file is **not** flagged). Run it ad-hoc with
+  `dz challenge --plan <plan.md>` or the `challenge-panel` skill; scaffold the degradations registry via
+  `dz feature-adr-setup --from-spec <spec with {"degradations":true}> --apply`.
+
 ### ADR quality gate (Step 3 generates → Step 8 enforces)
 
 Step 3 and Step 8 share an ADR best-practices contract distilled from the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/skills-feature-adr",
-  "version": "1.3.50",
+  "version": "1.3.52",
   "description": "Adaptive Feature Development skill pack for Claude Code — 11-step pipeline with Complexity Router (S/M/L/XL), ADR-driven architecture, 15 agentic-qe skills, multi-agent fleet QE. Supports --full-qe, --full-qe-extended, --with-learning, and --knowledge-extractor modes.",
   "bin": {
     "skills-feature-adr": "./bin/cli.js"

package/templates/.claude/skills/challenge-panel/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: challenge-panel
+description: >-
+  Adversarial plan-gate. BEFORE code, a FRESH reviewer (never the plan author) tries to BREAK an
+  implementation plan across a fixed C1-C8 owner-question set, every serious finding is cross-validated,
+  and the verdict is surfaced as ADVICE — never an auto-block. Trigger on "прогони challenge", "челлендж
+  плана", "challenge the plan", "adversarial review of this plan", or from the feature-adr plan checkpoint.
+---
+
+# Challenge Panel — adversarial plan-gate
+
+feature-adr's cross-model QE (Step 8) catches problems AFTER the code is written. The most expensive
+mistakes — overengineering, silent decisions, cemented degradations, test-theater, unrealistic scope —
+cement at the PLAN stage, and the plan's author structurally cannot find their own gaps (author bias).
+This skill runs a "break the plan, don't confirm it" panel at the plan stage, by a FRESH agent that did
+NOT write the plan, with cross-validated findings. **Advise, not block.**
+
+## Hard invariant (never relax)
+
+**The panel is NEVER the plan's own author.** Dispatch the adversary on a DIFFERENT model family than the
+one that wrote the plan:
+- plan written by Claude → adversary = Codex (cross-family). Run it through the honest synchronous path
+  (`codex exec` / `safeCodexAgent`), never a fire-and-forget wrapper — a stub reads exactly like a clean
+  review. If Codex is unavailable, fall back LOUDLY to a fresh Claude agent and say it was NOT cross-family.
+- plan written by Codex → adversary = a fresh Claude agent (already cross-family).
+- ad-hoc / unknown author → a fresh agent that did not participate in writing the plan.
+
+`dz challenge --author <model>` prints which cross-family adversary to dispatch.
+
+## Protocol
+
+1. **Assemble the WIDE context (deterministic).** Run:
+   ```bash
+   dz challenge --plan <path/to/06_implementation_plan.md>
+   ```
+   This prints the challenge brief: the plan + `architecture/vision.md` + `architecture/testing.md` +
+   `architecture/map.json` + `architecture/degradations.md` inlined (missing docs degrade gracefully) +
+   the fixed C1-C8 questions + the verdict JSON schema. A WIDE context is load-bearing — hand a reviewer a
+   narrow slice and you get findings about the slice.
+   - `--context-only` shows just what the panel will read (and the chosen adversary).
+   - `--json` emits the context + brief + adversary as JSON for a subagent.
+
+2. **Fire the panel (fresh adversary ≠ author).** Dispatch a subagent on the cross-family model with the
+   brief. It answers C1-C8 in "break it" mode and returns the verdict JSON:
+   | # | Question |
+   |---|----------|
+   | C1 | Architecture anti-cement — cements a NEW bad pattern/boundary? (deviating from a REGISTERED accepted degradation is NOT a finding) |
+   | C2 | Production-ready — where does it fall over? name the concrete input/condition |
+   | C3 | Test sufficiency + honesty BOTH ways — an ADR-named "never X" with no falsifying test? tests that are theater? |
+   | C4 | Overengineering sweep — built for a requirement nobody stated? the simpler thing? |
+   | C5 | Silent decisions — a policy made without surfacing it as a decision the owner could refuse |
+   | C6 | Runtime consistency — contradicts an existing convention (error shape, config source, ESM, naming)? |
+   | C7 | Scope — > ~1.5× what the request needs? the concrete cut list |
+   | C8 | Executability — could a non-author complete every step without coming back to ask? |
+
+   Each finding: `c` (C-number), `severity` (P0/P1/P2), `title`, `why` (a concrete failing input/condition —
+   never a general worry), optional `where`.
+
+3. **Cross-validate every P0/P1 (mandatory anti-noise).** Dispatch a SECOND, independent agent: for each
+   P0/P1, "real and reachable, or FP/theory?" — default to false when uncertain. **Drop** every P0/P1 that
+   is not confirmed. Theory never reaches the owner (a false gate kills trust). P2 pass through.
+
+4. **Surface the verdict — ADVISE, never block.** Present the cross-validated P0/P1 prominently + P2 as
+   notes. Do NOT auto-abort. The owner decides whether to revise the plan, accept a finding into
+   `architecture/degradations.md`, or proceed.
+
+## Calibration docs (optional, improve precision)
+
+- `architecture/vision.md` — boundaries + principles (what the product deliberately does NOT do).
+- `architecture/testing.md` — what "done" and an honest test mean here.
+- `architecture/degradations.md` — the accepted-degradations registry: patterns you KNOW are imperfect but
+  keep on purpose. **C1 does not flag a deviation from anything registered here.** Scaffold a starter with
+  `dz feature-adr-setup --from-spec <spec with {"degradations":true}> --apply`.
+
+Absent docs never error — the panel simply runs with less calibration.
+
+## In the feature-adr pipeline
+
+At the L/XL **checkpoint-after-plan**, feature-adr runs this panel automatically (a fresh adversary ≠ the
+Step-6 planner), cross-validates, and returns `challengeVerdict` alongside the ADR + plan — advisory. In
+**plain** `/feature-adr`, offer the panel at the planning checkpoint before coding.

package/templates/.claude/skills/configure-feature-adr/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: configure-feature-adr
+description: |
+  Guided, conversational setup that makes feature-adr aware of THIS product — vision, architecture map,
+  testing/verification rules, and (optionally) a review critic — WITHOUT the user knowing any manifest schema.
+  Complex inside, simple outside.
+
+  TRIGGERS: "настрой feature-adr под мой продукт", "помоги настроить feature-adr", "configure feature-adr
+  for my product", "какие документы нужны для feature-adr и куда их добавить", "onboard feature-adr".
+
+  Uses the deterministic engine `dz feature-adr-setup` (plan → scaffold-from-spec, propose-confirm,
+  augment-never-clobber). Reuses `dz architecture` (map) and `dz mr-rakes --gen-critic` (auto critic).
+allowed-tools: Bash, Read, Write, Edit, AskUserQuestion
+---
+
+# Configure feature-adr for this product
+
+Turn a generic feature-adr into a **project-aware** one by scaffolding four committed files under
+`architecture/` and wiring `project-skills.json` — through a short conversation, not a schema lesson.
+
+**Golden rule:** you NEVER hand-write manifest JSON in front of the user, and you NEVER overwrite an existing
+file. The engine scaffolds; you interview only for what can't be auto-derived.
+
+## Protocol
+
+### 1. Read the current state (never writes)
+```bash
+dz feature-adr-setup --plan --json
+```
+Report in plain language: which of `vision.md` / `subsystems.manifest.json` / `testing.md` /
+`project-skills.json` already exist, how many workspace packages were discovered (a map can be
+auto-scaffolded), and whether a review corpus exists (a critic can be auto-generated). Tell the user exactly
+which documents are still missing — this is the "which docs, and where?" answer.
+
+### 2. Auto-derive what you can (confirm, don't dictate)
+- **Map:** take the discovered packages and propose a starter subsystem grouping (foundation / arsenal / your
+  app subsystems). Show it; ask the user to rename/split to their real subsystems. (Their product, their call.)
+- **Critic (optional):** if a review corpus exists, offer to run `dz mr-rakes --gen-critic
+  architecture/project-critic/SKILL.md --apply` to generate the critic role from their recurring rakes.
+
+### 3. Short interview — only the un-derivable
+Ask, ONE topic at a time (this is the whole point of the skill — keep it to a handful of questions):
+- **Product vision** — what the product IS (one paragraph), where it's going, and 1-3 things it consciously
+  does NOT do. Seed your draft from the repo README's "why/what" section, then confirm.
+- **Testing / verification** — the commands that prove "done" here (e.g. `pnpm test -- --run`), what "done"
+  means in this project, and any required gates (coverage, lint, typecheck). This becomes the `testing` role.
+- **Optional roles** — ask briefly whether they have a code implementation bar (`impl-bar`) or brand/UI rules
+  (`brand`) to point at; skip if not.
+
+### 4. Fill the SPEC and scaffold (propose-confirm)
+Write the collected answers to a spec file, then preview:
+```bash
+# spec shape: { vision:{core,direction?,boundaries?[],principles?[]}, testing:{commands?[],doneDefinition?,gates?[]},
+#               subsystems:[…], roles:{critic?:"auto"|path, brand?:path, "impl-bar"?:path}, extra?:[…] }
+dz feature-adr-setup --from-spec /tmp/feature-adr-spec.json          # preview: create / augment / unchanged per file
+```
+Show the preview. An **existing file is `unchanged` (never clobbered)**; a structured file is **augmented**
+(existing content kept, new added). On the user's explicit "yes":
+```bash
+dz feature-adr-setup --from-spec /tmp/feature-adr-spec.json --apply
+```
+
+### 5. Verify + hand off
+```bash
+dz project-skills          # confirm the roles resolve (product-vision, testing, critic, …)
+dz architecture --revise   # confirm no drift
+```
+Tell the user: from now on every `/feature-adr` in this repo folds their vision into design + QE, their
+testing rules into Step 8, and their critic into review — automatically. Re-run this skill any time the
+product grows; it only augments (new packages, fresh rakes), never overwrites.
+
+## Notes
+- **Re-run = update.** The same flow, idempotent: step 1 surfaces only what's new.
+- **Nothing is written without the user's confirmation**, and no hand-edited file is ever overwritten.
+- If `dz` is not set up, install it first (`npm i -g @dzhechkov/harness-cli`); the engine needs `dz` ≥ 0.3.116.

package/templates/.claude/skills/feature-adr/modules/06-implementation-plan.md

@@ -169,6 +169,21 @@ Estimated {K} files to create/modify
 ═══════════════════════════════════════════════════════
 ```
 
+## Challenge panel (adversarial plan-gate — before coding)
+
+Before leaving the plan checkpoint for code (especially L/XL), offer the **`challenge-panel`** skill — a
+FRESH adversary (never the plan author) tries to BREAK the plan across the fixed C1-C8 owner questions,
+every P0/P1 is cross-validated, and the verdict is ADVISORY (never an auto-block):
+
+```bash
+dz challenge --plan features/<slug>/06_implementation_plan.md --author <planner-model>
+```
+
+Dispatch the panel on the CROSS-FAMILY model (`--author` prints which): plan by Claude → Codex adversary
+(honest `codex exec`, never a stub); plan by Codex → fresh Claude. Drop any P0/P1 the cross-validator does
+not confirm. A finding the owner accepts can be recorded in `architecture/degradations.md` so C1 stops
+re-flagging it. In the ultracode workflow this врезка runs automatically and returns `challengeVerdict`.
+
 ## Quality Gates
 
 - [ ] Every task has clear done criteria

package/templates/.claude/workflows/feature-adr.js

@@ -663,6 +663,73 @@ if (plan === null) {
   plan = claudePlan ? { wrote: claudePlan.wrote, summary: claudePlan.summary, planner: planIsCodex ? 'claude-fallback' : 'claude' } : null
 }
 
+// ── R6 challenge panel: adversarial plan-gate at the checkpoint (ADVISE, never block) ──
+// The panel is NEVER the plan's own author (ADR §1 hard invariant): author=Claude → a cross-family Codex
+// adversary via the HONEST synchronous codex exec path (safeCodexAgent — a stub would read as a clean
+// review, so it is never used for this data-returning verdict); author=Codex → a FRESH Claude adversary.
+// The adversary loads the WIDE context via `dz challenge` (plan + vision + testing + map + degradations),
+// answers C1-C8 in break-it mode, then every P0/P1 is cross-validated by an independent agent and the
+// non-validated ones are dropped (anti-noise). Failure anywhere degrades LOUDLY to a fresh Claude panel.
+const CHALLENGE_SCHEMA = { type: 'object', additionalProperties: false, required: ['findings', 'summary'], properties: { findings: { type: 'array', items: { type: 'object', additionalProperties: false, required: ['c', 'severity', 'title', 'why'], properties: { c: { type: 'string' }, severity: { type: 'string', enum: ['P0', 'P1', 'P2'] }, title: { type: 'string' }, why: { type: 'string' }, where: { type: 'string' } } } }, summary: { type: 'string' } } }
+const CHALLENGE_CIDS = new Set(['C1', 'C2', 'C3', 'C4', 'C5', 'C6', 'C7', 'C8'])
+// sh-quote for safe interpolation into a Bash string (QE #13 injection via REPO path / dzBin).
+function shq(s) { return "'" + String(s).replace(/'/g, "'\\''") + "'" }
+// Validate a raw adversary payload → {findings,summary} or null (QE #7: {} / {findings:[]} / [null] are not
+// a fake-clean pass). A value without a findings ARRAY is null → loud fallback; junk findings are dropped.
+function sanitizeChallengeVerdict(raw) {
+  if (!raw || typeof raw !== 'object' || !Array.isArray(raw.findings)) return null
+  const findings = raw.findings.filter((f) => f && typeof f === 'object' && CHALLENGE_CIDS.has(String(f.c)) && (f.severity === 'P0' || f.severity === 'P1' || f.severity === 'P2') && typeof f.title === 'string' && f.title !== '' && typeof f.why === 'string' && f.why !== '')
+  return { findings: findings, summary: typeof raw.summary === 'string' ? raw.summary : '' }
+}
+async function runChallengePanel(planRel, plannerName) {
+  const authorIsCodex = /codex|gpt|openai|\bo[1-9]\b/i.test(String(plannerName || ''))
+  const dzChallenge = 'cd ' + shq(REPO) + ' && ' + shq(DZ) + ' challenge --plan ' + shq(planRel) + ' --author ' + shq(plannerName || 'claude')
+  // Preflight (QE #11): the plan artifact must EXIST and be non-empty, else an adversary hallucinates a
+  // verdict on a missing file. Surface a loud status instead of a fake review.
+  const pre = await agent('Run EXACTLY this via Bash and reply with ONLY its stdout: ' + 'cd ' + shq(REPO) + ' && (test -s ' + shq(planRel) + ' && echo PLAN_OK || echo PLAN_MISSING)', { label: 'challenge:preflight', phase: 'Plan', effort: 'low' })
+  if (!/PLAN_OK/.test(String(pre || ''))) { log('Challenge panel: plan artifact missing/empty (' + planRel + ') — panel skipped'); return { status: 'no-plan', adversary: null, findings: [], summary: '', note: 'Challenge panel skipped — the implementation plan artifact was missing or empty.' } }
+  let verdict = null
+  let adversary = authorIsCodex ? 'claude' : 'codex'
+  if (!authorIsCodex) {
+    // author=Claude → Codex adversary (cross-family). Compact prompt: Codex reads the files itself (no 24k
+    // brief inlined). safeCodexAgent is the honest exec path; null/invalid ⇒ loud Claude fallback below.
+    const cx = await safeCodexAgent('You are a FRESH adversarial reviewer of an implementation plan you did NOT write. Read these files: ' + planRel + ' , architecture/vision.md , architecture/degradations.md (relative to repo ' + REPO + '). BREAK the plan, do not confirm it. Answer C1 arch-anti-cement (deviating from a pattern in the degradations registry is NOT a finding), C2 prod-ready, C3 test sufficiency+honesty both ways, C4 overengineering, C5 silent decisions, C6 runtime consistency, C7 scope>1.5x, C8 executability. Output ONLY minified JSON {"findings":[{"c","severity":"P0|P1|P2","title","why","where"}],"summary"}.', { label: 'challenge:codex-adversary', phase: 'Plan' })
+    if (cx) { try { verdict = sanitizeChallengeVerdict(JSON.parse(String(cx).replace(/^[^{]*/, '').replace(/[^}]*$/, ''))) } catch { verdict = null } }
+    if (!verdict) { log('Challenge panel: Codex adversary unavailable/unparseable/invalid — falling back to a FRESH Claude panel (NOT cross-family; run `dz challenge` + codex manually for a cross-family pass)'); adversary = 'claude-fallback' }
+  }
+  if (!verdict) {
+    // Claude adversary (fresh instance ≠ the author): loads the WIDE brief via dz, then answers the schema.
+    const raw = await agent('You are a FRESH adversarial reviewer. You did NOT write this plan. First run EXACTLY this via Bash to load the wide challenge brief (plan + vision + testing + map + degradations + the C1-C8 questions): ' + dzChallenge + '\nThen BREAK the plan per C1-C8 (do NOT confirm it): a finding is a concrete failing input/condition, never a general worry; deviating from a pattern in the degradations registry is NOT a finding. Return the verdict.', { label: 'challenge:claude-adversary', phase: 'Plan', schema: CHALLENGE_SCHEMA })
+    verdict = sanitizeChallengeVerdict(raw)
+  }
+  if (!verdict) { log('Challenge panel: no usable verdict from any adversary — surfacing unavailable status (advisory)'); return { status: 'adversary-unavailable', adversary: adversary, findings: [], summary: '', note: 'Challenge panel could not produce a verdict — run `dz challenge` + the panel manually.' } }
+  // Cross-validate P0/P1 by INDEX (QE #5: never by title — duplicate titles cross-contaminate). Deterministic
+  // sorted order shared with the validator; results[i] aligns to pp[i].
+  const rank = { P0: 3, P1: 2, P2: 1 }
+  const pp = verdict.findings.filter((f) => f.severity === 'P0' || f.severity === 'P1').sort((a, b) => (rank[b.severity] - rank[a.severity]) || (a.c < b.c ? -1 : a.c > b.c ? 1 : 0))
+  let confirmed = verdict.findings.filter((f) => f.severity === 'P2')
+  let status = 'ok'
+  if (pp.length > 0) {
+    const numbered = pp.map((f, i) => ({ i: i, c: f.c, severity: f.severity, title: f.title, why: f.why }))
+    const cv = await agent('Independently CROSS-VALIDATE these adversarial plan findings against the plan at ' + planRel + ' (repo ' + REPO + '). For EACH by its "i" index, decide if it is REAL and reachable, or FP/theory. Default to real=false when uncertain. Findings JSON (with stable index i): ' + JSON.stringify(numbered) + '\nReturn {"results":[{"i":<the index>,"real":true|false}...]} covering EVERY index exactly once.', { label: 'challenge:cross-validate', phase: 'Plan', schema: { type: 'object', additionalProperties: false, required: ['results'], properties: { results: { type: 'array', items: { type: 'object', additionalProperties: false, required: ['i', 'real'], properties: { i: { type: 'number' }, real: { type: 'boolean' } } } } } } })
+    const realByIndex = new Map((cv && Array.isArray(cv.results) ? cv.results : []).map((r) => [Number(r.i), r.real === true]))
+    // QE #8: a validator OUTAGE (missing indices) must NOT read as "clean" — do not silently drop the P0/P1.
+    const covered = pp.every((_, i) => realByIndex.has(i))
+    if (!covered) {
+      status = 'cross-validation-incomplete'
+      log('Challenge panel: cross-validator did not cover every P0/P1 — surfacing them UNVALIDATED (not dropped, not confirmed)')
+      for (const f of pp) confirmed.push(Object.assign({}, f, { crossValidated: false, unvalidated: true }))
+    } else {
+      pp.forEach((f, i) => { if (realByIndex.get(i) === true) confirmed.push(Object.assign({}, f, { crossValidated: true })) })
+    }
+  }
+  confirmed.sort((a, b) => (rank[b.severity] - rank[a.severity]) || (a.c < b.c ? -1 : a.c > b.c ? 1 : 0))
+  const note = status === 'cross-validation-incomplete'
+    ? 'ADVISORY — cross-validation was INCOMPLETE; P0/P1 shown are UNVALIDATED (verify manually). Nothing blocks.'
+    : 'ADVISORY — the owner decides; nothing blocks. Cross-validated P0/P1 + all P2 shown.'
+  return { status: status, adversary: adversary, findings: confirmed, summary: verdict.summary, note: note }
+}
+
 // Hybrid checkpoint for L/XL
 const stopHere = STOP_AFTER === 'plan' || (isLplus && STOP_AFTER !== 'none')
 if (stopHere) {
@@ -673,7 +740,11 @@ if (stopHere) {
   const qePlanned = qeShouldUseCodex() ? modelLabel(resolveStageModel('qe')) : modelLabel(mergeOpts({ agentType: 'qe-code-reviewer' }, resolveStageModel('qe')))
   const plannedModels = mergeOpts(modelsUsed, { code: codePlanned + ' (planned)', qe: qePlanned + ' (planned)' })
   if (isLplus) plannedModels.fleet = modelLabel(resolveStageModel('fleet')) + ' (planned)'
-  return { tier: tier, phase: 'checkpoint-after-plan', artifactsDir: FDIR, planner: (plan ? plan.planner : null), plan: (plan ? plan.summary : null), modelsUsed: plannedModels, usageEvents: usageEvents, usageThreshold: USAGE_THRESHOLD, polymorphism: POLY.hasManifest ? POLY.report : null, note: 'L/XL checkpoint - review the ADR + plan (+ the planned code/qe/fleet models), then re-invoke with args.stopAfter="none" to implement + QE.' }
+  // R6 врезка: adversarial plan-gate (advise). Panel ≠ plan author; wrapped so a panel failure never blocks the checkpoint.
+  let challengeVerdict = null
+  try { challengeVerdict = plan ? await runChallengePanel('features/' + SLUG + '/06_implementation_plan.md', plan.planner) : null }
+  catch (e) { log('Challenge panel errored (advisory, ignored): ' + (e && e.message ? e.message : String(e))) }
+  return { tier: tier, phase: 'checkpoint-after-plan', artifactsDir: FDIR, planner: (plan ? plan.planner : null), plan: (plan ? plan.summary : null), modelsUsed: plannedModels, challengeVerdict: challengeVerdict, usageEvents: usageEvents, usageThreshold: USAGE_THRESHOLD, polymorphism: POLY.hasManifest ? POLY.report : null, note: 'L/XL checkpoint - review the ADR + plan (+ the planned code/qe/fleet models) + the challenge panel verdict (advisory), then re-invoke with args.stopAfter="none" to implement + QE.' }
 }
 
 // Step 7: Code (optional Codex fallback on Claude-limit exhaustion)