create-byan-agent 2.19.2 → 2.20.1

package/install/templates/.claude/skills/byan-native-dev-story/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: byan-native-dev-story
+description: Orchestrating conductor for the native dev-story workflow. Runs the autonomous red-green-refactor engine (.claude/workflows/dev-story.js) via the Workflow tool, then presents its verdict at a human gate and records FD/strict state via MCP. This is the Hybrid pattern incarnate - gate OUTSIDE the script, engine INSIDE.
+---
+
+# byan-native-dev-story - Conductor (gate outside, engine inside)
+
+You are the human-gated conductor for the native dev-story workflow. The
+autonomous work runs in `.claude/workflows/dev-story.js` (the in-CLI Workflow
+tool); YOU own the human gate and the auditable state. This split is the whole
+point of Phase 1: the engine is native and deterministic, the gate stays on a
+real main-thread turn where the BYAN hooks fire.
+
+## Why this skill exists
+
+A launched Workflow script is autonomous and cannot pause mid-run to ask a
+human, and the main-thread enforcement hooks do not fire inside it. So the
+script must not decide completion or mutate BYAN state on its own. It returns
+DATA; this skill turns that data into a gated decision.
+
+## Protocol
+
+### 1. Resolve the workflow (dual-path)
+
+Prefer the native script. If `.claude/workflows/dev-story.js` exists, use it.
+Otherwise fall back to the markdown workflow from the manifest
+(`_byan/workflow/simple/4-implementation/dev-story/workflow.yaml`). The
+programmatic resolver is `resolveWorkflow('dev-story')` in
+`_byan/mcp/byan-mcp-server/lib/workflows-generator.js`.
+
+### 2. (If inside an FD or strict session) read state via MCP
+
+State mutations go through the MCP tools ONLY - direct writes to `fd-state.json`
+or `.byan-strict/` are out of bounds:
+
+- FD: `byan_fd_status` to read the phase; a dev-story run is BUILD-phase work.
+- Strict: if a strict session is engaged, the story implementation is in scope;
+  do not lock a second scope here.
+
+### 3. Run the engine
+
+Invoke the Workflow tool:
+
+```
+Workflow({ name: 'dev-story', args: { story: '<path-or-key, or omit for next ready-for-dev>' } })
+```
+
+The script runs the red-green-refactor loop with a real 3-cycle convergence
+counter (`lib/native-loop.js` `convergenceGuard`) and returns a structured
+verdict:
+
+```json
+{ "workflow": "dev-story", "story": "...",
+  "status": "review-ready | aborted-no-convergence | in-progress",
+  "green": true, "cycles": 2, "maxCycles": 3, "blocking": [],
+  "reason": "green", "needsHumanGate": true }
+```
+
+### 4. HUMAN GATE (mandatory - do not skip)
+
+Present the verdict to the user and HALT for a decision. Do not auto-advance.
+
+- `status: review-ready` (green) - summarize cycles + files touched; ask the
+  user to approve moving the story to **review**. Only on approval, record the
+  transition via MCP, then stop.
+- `status: aborted-no-convergence` - the engine hit the 3-cycle cap without
+  green. Surface the `blocking` issues verbatim. Propose REFACTOR (targeted
+  fixes, re-run) or, if mis-scoped, a return to PRUNE. Leave the story not-done.
+- `status: in-progress` - report remaining work; ask whether to continue.
+
+### 5. Record state via MCP (only after the gate)
+
+After the user decides, record the outcome through `byan_fd_*` / `byan_strict_*`
+so the audit trail stays in the MCP authority. State files are mutated through
+the MCP tools, not by direct edit.
+
+## Invariants
+
+- The script returns data; THIS skill owns completion and state. (Enforcement
+  contract: see `docs/native-workflows-contract.md`.)
+- The human gate stays on a real main-thread turn, outside the script.
+- Dual-path: native `.js` preferred, markdown fallback. No silent downgrade.
+- No emoji in outputs (IA-23).

package/install/templates/.claude/workflows/INDEX.md

@@ -0,0 +1,35 @@
+# BYAN Native Workflows
+
+> Registre des workflows portables vers l'outil Workflow natif de Claude Code.
+> Genere automatiquement — ne pas editer a la main. Source : `_byan/_config/workflow-manifest.csv`.
+> Regenerer : `node _byan/mcp/byan-mcp-server/bin/byan-build-workflows.js`.
+>
+> Resolution dual-path : le skill prefere `.claude/workflows/<name>.js` s'il existe,
+> sinon il retombe sur le workflow markdown du manifest. Les workflows gated (a gate
+> humain par etape) restent markdown interprete — ils ne sont pas portables.
+
+## autonomous (11)
+
+- `create-story` — native — source `_byan/workflow/simple/4-implementation/create-story/workflow.yaml`
+- `dev-story` — native — source `_byan/workflow/simple/4-implementation/dev-story/workflow.yaml`
+- `qa-automate` — native — source `_byan/workflow/simple/qa/automate/workflow.yaml`
+- `testarch-atdd` — native — source `_byan/workflow/simple/testarch/atdd/workflow.yaml`
+- `testarch-automate` — native — source `_byan/workflow/simple/testarch/automate/workflow.yaml`
+- `testarch-ci` — native — source `_byan/workflow/simple/testarch/ci/workflow.yaml`
+- `testarch-framework` — native — source `_byan/workflow/simple/testarch/framework/workflow.yaml`
+- `testarch-nfr` — native — source `_byan/workflow/simple/testarch/nfr-assess/workflow.yaml`
+- `testarch-test-design` — native — source `_byan/workflow/simple/testarch/test-design/workflow.yaml`
+- `testarch-test-review` — native — source `_byan/workflow/simple/testarch/test-review/workflow.yaml`
+- `testarch-trace` — native — source `_byan/workflow/simple/testarch/trace/workflow.yaml`
+
+## pipeline (9)
+
+- `check-implementation-readiness` — native — source `_byan/workflow/simple/3-solutioning/check-implementation-readiness/workflow.md`
+- `code-review` — native — source `_byan/workflow/simple/4-implementation/code-review/workflow.yaml`
+- `create-excalidraw-dataflow` — native — source `_byan/workflow/simple/excalidraw-diagrams/create-dataflow/workflow.yaml`
+- `create-excalidraw-diagram` — native — source `_byan/workflow/simple/excalidraw-diagrams/create-diagram/workflow.yaml`
+- `create-excalidraw-flowchart` — native — source `_byan/workflow/simple/excalidraw-diagrams/create-flowchart/workflow.yaml`
+- `create-excalidraw-wireframe` — native — source `_byan/workflow/simple/excalidraw-diagrams/create-wireframe/workflow.yaml`
+- `document-project` — native — source `_byan/workflow/simple/document-project/workflow.yaml`
+- `quick-dev` — native — source `_byan/workflow/simple/bmad-quick-flow/quick-dev/workflow.md`
+- `sprint-planning` — native — source `_byan/workflow/simple/4-implementation/sprint-planning/workflow.yaml`

package/install/templates/.claude/workflows/check-implementation-readiness.js

@@ -0,0 +1,280 @@
+export const meta = {
+  name: 'check-implementation-readiness',
+  description: 'Adversarial readiness gate: validates PRD, Architecture, Epics & Stories, and UX for completeness and alignment before Phase 4 implementation. Mirrors the 6-step BYAN check-implementation-readiness pipeline and returns a structured verdict.',
+  phases: [
+    { title: 'DOCUMENT_DISCOVERY' },
+    { title: 'PRD_ANALYSIS' },
+    { title: 'EPIC_COVERAGE_VALIDATION' },
+    { title: 'UX_ALIGNMENT' },
+    { title: 'EPIC_QUALITY_REVIEW' },
+    { title: 'FINAL_ASSESSMENT' }
+  ]
+}
+
+// FD/STRICT CONTRACT (re-asserted): this script returns data only. It never
+// imports lib/fd-state.js, never writes fd-state.json, and records no platform
+// state. The orchestrating skill records FD/strict state via MCP at the human
+// gate (duplicate resolution + the proceed-as-is / fix decision live OUTSIDE
+// this script). No wall-clock, no randomness: any date/id is passed via args
+// so the runtime can resume deterministically.
+
+const planningArtifacts = (args && args.planningArtifacts) || '_bmad-output/planning-artifacts'
+const reportDate = (args && args.date) || 'unspecified'
+const role = 'an expert Product Manager and Scrum Master specialized in requirements traceability and spotting gaps in planning artifacts. Be adversarial: your job is to find the failures others missed, not to reassure.'
+
+// ---------------------------------------------------------------------------
+// STEP 1 - Document Discovery (mirrors step-01-document-discovery.md)
+// Inventory PRD / Architecture / Epics / UX (whole + sharded), flag duplicates
+// and missing docs. The human resolution gate stays out of the script: we
+// surface duplicates/missing as data for the orchestrating skill to gate on.
+// ---------------------------------------------------------------------------
+phase('DOCUMENT_DISCOVERY')
+const inventory = await agent(
+  `You are ${role}\n` +
+  `STEP 1 - Document Discovery. Inventory all planning documents under "${planningArtifacts}".\n` +
+  `For each of these four types, search BOTH whole and sharded forms:\n` +
+  `- PRD: ${planningArtifacts}/*prd*.md and ${planningArtifacts}/*prd*/index.md\n` +
+  `- Architecture: ${planningArtifacts}/*architecture*.md and ${planningArtifacts}/*architecture*/index.md\n` +
+  `- Epics & Stories: ${planningArtifacts}/*epic*.md and ${planningArtifacts}/*epic*/index.md\n` +
+  `- UX Design: ${planningArtifacts}/*ux*.md and ${planningArtifacts}/*ux*/index.md\n` +
+  `Group sharded files with their folder. Flag CRITICAL duplicates (a type existing as BOTH whole.md AND a sharded folder) and WARN on missing required docs. ` +
+  `Do NOT analyze contents yet - only locate and organize. Pick the version to use per type (or null if absent).`,
+  {
+    label: 'document-discovery',
+    phase: 'DOCUMENT_DISCOVERY',
+    schema: {
+      type: 'object',
+      required: ['documents', 'duplicates', 'missing'],
+      properties: {
+        documents: {
+          type: 'object',
+          properties: {
+            prd: { type: 'array', items: { type: 'string' } },
+            architecture: { type: 'array', items: { type: 'string' } },
+            epics: { type: 'array', items: { type: 'string' } },
+            ux: { type: 'array', items: { type: 'string' } }
+          }
+        },
+        chosen: { type: 'object' },
+        duplicates: { type: 'array', items: { type: 'string' } },
+        missing: { type: 'array', items: { type: 'string' } }
+      }
+    }
+  }
+)
+log(`Discovery: ${inventory.duplicates.length} duplicate conflict(s), ${inventory.missing.length} missing doc(s)`)
+
+// ---------------------------------------------------------------------------
+// STEP 2 - PRD Analysis (mirrors step-02-prd-analysis.md)
+// Read the PRD completely (whole or all sharded files) and extract EVERY FR
+// and NFR verbatim with numbering. No summarizing.
+// ---------------------------------------------------------------------------
+phase('PRD_ANALYSIS')
+const prd = await agent(
+  `You are ${role}\n` +
+  `STEP 2 - PRD Analysis. Read the chosen PRD completely (if sharded, read ALL files in the folder). ` +
+  `Extract EVERY Functional Requirement (FR1, FR2, ...) and Non-Functional Requirement (NFR: performance, security, usability, reliability, scalability, compliance) with full text - do NOT summarize. ` +
+  `Also note constraints, assumptions, integration requirements not labeled FR/NFR. Give an initial PRD completeness/clarity assessment.\n` +
+  `PRD source(s): ${JSON.stringify(inventory.documents && inventory.documents.prd)}`,
+  {
+    label: 'prd-analysis',
+    phase: 'PRD_ANALYSIS',
+    schema: {
+      type: 'object',
+      required: ['functionalRequirements', 'nonFunctionalRequirements'],
+      properties: {
+        functionalRequirements: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['id', 'text'],
+            properties: { id: { type: 'string' }, text: { type: 'string' } }
+          }
+        },
+        nonFunctionalRequirements: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['id', 'text'],
+            properties: { id: { type: 'string' }, category: { type: 'string' }, text: { type: 'string' } }
+          }
+        },
+        additionalRequirements: { type: 'array', items: { type: 'string' } },
+        completenessAssessment: { type: 'string' }
+      }
+    }
+  }
+)
+log(`PRD: ${prd.functionalRequirements.length} FR, ${prd.nonFunctionalRequirements.length} NFR`)
+
+// ---------------------------------------------------------------------------
+// STEP 3 - Epic Coverage Validation (mirrors step-03-epic-coverage-validation.md)
+// Compare every PRD FR against the epics' coverage. Build a traceability matrix.
+// Every uncovered FR is a documented gap; flag epic-only FRs not in PRD too.
+// ---------------------------------------------------------------------------
+phase('EPIC_COVERAGE_VALIDATION')
+const coverage = await agent(
+  `You are ${role}\n` +
+  `STEP 3 - Epic Coverage Validation. Read the epics & stories document completely. Extract its FR coverage map. ` +
+  `For EACH PRD FR below, determine whether it is covered (which epic/story) or MISSING. Also flag any FR present in epics but NOT in the PRD. Build a coverage matrix and compute coverage statistics.\n` +
+  `Epics source(s): ${JSON.stringify(inventory.documents && inventory.documents.epics)}\n` +
+  `PRD FRs to trace: ${JSON.stringify(prd.functionalRequirements)}`,
+  {
+    label: 'epic-coverage',
+    phase: 'EPIC_COVERAGE_VALIDATION',
+    schema: {
+      type: 'object',
+      required: ['matrix', 'missingFRs', 'totalFRs', 'coveredFRs', 'coveragePercent'],
+      properties: {
+        matrix: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['fr', 'status'],
+            properties: {
+              fr: { type: 'string' },
+              epicCoverage: { type: 'string' },
+              status: { type: 'string', enum: ['covered', 'missing'] }
+            }
+          }
+        },
+        missingFRs: { type: 'array', items: { type: 'string' } },
+        extraEpicFRs: { type: 'array', items: { type: 'string' } },
+        totalFRs: { type: 'integer' },
+        coveredFRs: { type: 'integer' },
+        coveragePercent: { type: 'number' }
+      }
+    }
+  }
+)
+log(`Coverage: ${coverage.coveredFRs}/${coverage.totalFRs} FRs covered (${coverage.coveragePercent}%), ${coverage.missingFRs.length} missing`)
+
+// ---------------------------------------------------------------------------
+// STEP 4 - UX Alignment (mirrors step-04-ux-alignment.md)
+// If UX exists: check UX<->PRD and UX<->Architecture alignment. If absent:
+// assess whether UX/UI is IMPLIED (user-facing app) and warn accordingly.
+// ---------------------------------------------------------------------------
+phase('UX_ALIGNMENT')
+const ux = await agent(
+  `You are a UX VALIDATOR ensuring user experience is properly addressed.\n` +
+  `STEP 4 - UX Alignment. UX source(s): ${JSON.stringify(inventory.documents && inventory.documents.ux)}.\n` +
+  `If a UX document exists: validate (A) UX<->PRD alignment (user journeys match use cases; UX needs reflected in PRD) and (B) UX<->Architecture alignment (architecture supports UX, performance/responsiveness, all UI components backed). ` +
+  `If no UX document: assess whether UX/UI is IMPLIED (PRD mentions UI, web/mobile components, user-facing app) and issue a warning if implied-but-missing. Document every alignment gap.\n` +
+  `Architecture source(s): ${JSON.stringify(inventory.documents && inventory.documents.architecture)}`,
+  {
+    label: 'ux-alignment',
+    phase: 'UX_ALIGNMENT',
+    schema: {
+      type: 'object',
+      required: ['uxStatus', 'alignmentIssues', 'warnings'],
+      properties: {
+        uxStatus: { type: 'string', enum: ['found', 'not-found-implied', 'not-found-not-needed'] },
+        alignmentIssues: { type: 'array', items: { type: 'string' } },
+        warnings: { type: 'array', items: { type: 'string' } }
+      }
+    }
+  }
+)
+log(`UX: ${ux.uxStatus}, ${ux.alignmentIssues.length} alignment issue(s), ${ux.warnings.length} warning(s)`)
+
+// ---------------------------------------------------------------------------
+// STEP 5 - Epic Quality Review (mirrors step-05-epic-quality-review.md)
+// Enforce create-epics-and-stories best practices: epics deliver USER value
+// (not technical milestones), epic independence (no Epic N -> Epic N+1),
+// no forward story dependencies, just-in-time DB/entity creation, BDD ACs,
+// starter-template / greenfield-vs-brownfield checks. Classify by severity.
+// ---------------------------------------------------------------------------
+phase('EPIC_QUALITY_REVIEW')
+const quality = await agent(
+  `You are an EPIC QUALITY ENFORCER. Validate the epics & stories against create-epics-and-stories best practices, rigorously and without compromise.\n` +
+  `STEP 5 - Epic Quality Review. Check, for every epic and story:\n` +
+  `- User value: epic title/goal is user-centric; reject technical milestones ("Setup Database", "API Development", "Infrastructure Setup").\n` +
+  `- Epic independence: Epic N must function on Epic 1..N-1 only; NEVER require Epic N+1; no circular deps.\n` +
+  `- Story dependencies: each story independently completable; NO forward references ("depends on Story 1.4").\n` +
+  `- DB/entity timing: tables created just-in-time per story, NOT all upfront in Epic 1 Story 1.\n` +
+  `- Acceptance criteria: Given/When/Then, testable, covers errors not just happy path, specific not vague.\n` +
+  `- Starter template: if Architecture specifies one, Epic 1 Story 1 must set up the project from it.\n` +
+  `- Greenfield vs brownfield: greenfield needs setup/env/CI-CD early; brownfield needs integration/migration stories.\n` +
+  `- Traceability to FRs maintained.\n` +
+  `Classify findings as critical / major / minor, each with a specific example and remediation.\n` +
+  `Epics source(s): ${JSON.stringify(inventory.documents && inventory.documents.epics)}\n` +
+  `Architecture source(s): ${JSON.stringify(inventory.documents && inventory.documents.architecture)}`,
+  {
+    label: 'epic-quality',
+    phase: 'EPIC_QUALITY_REVIEW',
+    schema: {
+      type: 'object',
+      required: ['critical', 'major', 'minor'],
+      properties: {
+        critical: { type: 'array', items: { type: 'string' } },
+        major: { type: 'array', items: { type: 'string' } },
+        minor: { type: 'array', items: { type: 'string' } },
+        recommendations: { type: 'array', items: { type: 'string' } }
+      }
+    }
+  }
+)
+log(`Quality: ${quality.critical.length} critical, ${quality.major.length} major, ${quality.minor.length} minor`)
+
+// ---------------------------------------------------------------------------
+// STEP 6 - Final Assessment (mirrors step-06-final-assessment.md)
+// Compile all findings into one objective verdict: READY / NEEDS WORK /
+// NOT READY, with the critical issues and concrete next steps. The script
+// computes the verdict; it does NOT decide whether to proceed - that human
+// "proceed as-is or fix" gate is owned by the orchestrating skill.
+// ---------------------------------------------------------------------------
+phase('FINAL_ASSESSMENT')
+const final = await agent(
+  `You are ${role}\n` +
+  `STEP 6 - Final Assessment. Compile all findings into one objective readiness verdict. Be direct - do NOT soften the message. ` +
+  `Determine overall status: READY (no critical issues, full FR coverage), NEEDS WORK (gaps/major issues but fixable), or NOT READY (critical violations or missing core docs). ` +
+  `List the critical issues that must be addressed and concrete next-step action items. Do NOT decide whether to proceed - just report the state of readiness.\n` +
+  `Discovery: ${JSON.stringify({ duplicates: inventory.duplicates, missing: inventory.missing })}\n` +
+  `PRD: ${prd.functionalRequirements.length} FR / ${prd.nonFunctionalRequirements.length} NFR; completeness: ${prd.completenessAssessment || 'n/a'}\n` +
+  `Coverage: ${coverage.coveragePercent}% (${coverage.coveredFRs}/${coverage.totalFRs}); missing FRs: ${JSON.stringify(coverage.missingFRs)}\n` +
+  `UX: ${ux.uxStatus}; issues: ${JSON.stringify(ux.alignmentIssues)}; warnings: ${JSON.stringify(ux.warnings)}\n` +
+  `Epic quality: ${JSON.stringify({ critical: quality.critical, major: quality.major, minor: quality.minor })}`,
+  {
+    label: 'final-assessment',
+    phase: 'FINAL_ASSESSMENT',
+    schema: {
+      type: 'object',
+      required: ['readinessStatus', 'criticalIssues', 'nextSteps'],
+      properties: {
+        readinessStatus: { type: 'string', enum: ['READY', 'NEEDS WORK', 'NOT READY'] },
+        criticalIssues: { type: 'array', items: { type: 'string' } },
+        nextSteps: { type: 'array', items: { type: 'string' } },
+        finalNote: { type: 'string' }
+      }
+    }
+  }
+)
+log(`Readiness verdict: ${final.readinessStatus}`)
+
+const totalIssues =
+  inventory.duplicates.length +
+  inventory.missing.length +
+  coverage.missingFRs.length +
+  ux.alignmentIssues.length +
+  ux.warnings.length +
+  quality.critical.length +
+  quality.major.length +
+  quality.minor.length
+
+return {
+  workflow: 'check-implementation-readiness',
+  summary: `Implementation readiness: ${final.readinessStatus} - ${totalIssues} issue(s) across discovery, PRD coverage, UX, and epic quality.`,
+  steps: 6,
+  reportDate,
+  planningArtifacts,
+  needsHumanGate: true,
+  result: {
+    discovery: inventory,
+    prd: { frCount: prd.functionalRequirements.length, nfrCount: prd.nonFunctionalRequirements.length, completenessAssessment: prd.completenessAssessment },
+    coverage,
+    ux,
+    epicQuality: quality,
+    final
+  },
+  totalIssues
+}

package/install/templates/.claude/workflows/code-review.js

@@ -0,0 +1,179 @@
+export const meta = {
+  name: 'code-review',
+  description: 'Native port of the BYAN code-review workflow: an ADVERSARIAL Senior Developer review that validates a story file against the actual implementation and git reality, hunts a minimum of 3-10 specific issues (AC validation, task audit, code quality, test quality), and returns a structured verdict. The fix/action-items human decision stays OUT of the script.',
+  phases: [
+    { title: 'LOAD', detail: 'load story + discover actual changes via git, cross-reference File List' },
+    { title: 'PLAN', detail: 'build the adversarial review attack plan' },
+    { title: 'REVIEW', detail: 'execute the review; enforce the >=3-issue floor with a bounded re-scan' },
+    { title: 'FINDINGS', detail: 'categorize HIGH/MEDIUM/LOW; return a verdict (no auto-fix here)' },
+    { title: 'VERDICT', detail: 'compute proposed story status + sprint-sync intent for the human gate' },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// FD / STRICT STATE CONTRACT  (re-asserted inline — enforcement-bridge).
+//
+// The in-CLI Workflow tool runs this script OUTSIDE the conversation turn, so
+// BYAN's main-thread hooks (fd-phase-guard, strict-scope-guard, strict-stop-
+// guard, mantra-validate) DO NOT fire here. This script therefore:
+//   - NEVER imports/requires _byan/.../lib/fd-state.js and NEVER writes
+//     fd-state.json directly  (enforced by byan-lint-workflows.js).
+//   - uses NO wall-clock / NO randomness primitive (wall-clock, RNG,
+//     a wall-clock read break resume) — any date/id is passed via args.
+//   - returns DATA only. The orchestrating skill is the human-gated conductor;
+//     IT records FD/strict state via the byan_fd_* / byan_strict_* MCP tools
+//     AT the gate, and AT the gate it asks the human the fix/action-items
+//     decision (source step 4) and applies the chosen story-status update
+//     + sprint-status.yaml sync (source step 5).
+// ---------------------------------------------------------------------------
+
+// Issue-floor guard — turns the source's prose rule ("Find 3-10 issues; if
+// total_issues_found < 3 -> NOT LOOKING HARD ENOUGH, re-examine") into a real
+// JS counter the model cannot silently overrun. Bounded re-scan: one extra
+// adversarial pass, never an unbounded loop.
+const MIN_ISSUES = 3
+const MAX_RESCANS = 1
+
+const REVIEW_SCHEMA = {
+  type: 'object',
+  required: ['totalIssues', 'high', 'medium', 'low', 'findings'],
+  properties: {
+    totalIssues: { type: 'integer', description: 'total specific, actionable issues found' },
+    high: { type: 'integer', description: 'count of HIGH severity (must-fix) issues' },
+    medium: { type: 'integer', description: 'count of MEDIUM (should-fix) issues' },
+    low: { type: 'integer', description: 'count of LOW (nice-to-fix) issues' },
+    gitDiscrepancies: { type: 'integer', description: 'git-vs-story File List discrepancies' },
+    acMissing: { type: 'integer', description: 'Acceptance Criteria found MISSING or PARTIAL' },
+    tasksFalselyComplete: { type: 'integer', description: 'tasks marked [x] but NOT actually done (CRITICAL)' },
+    findings: {
+      type: 'array',
+      description: 'each: severity + description + file:line evidence',
+      items: {
+        type: 'object',
+        required: ['severity', 'description'],
+        properties: {
+          severity: { type: 'string', enum: ['HIGH', 'MEDIUM', 'LOW'] },
+          category: { type: 'string', description: 'ac|task|security|performance|error-handling|quality|test|git-discrepancy' },
+          description: { type: 'string' },
+          evidence: { type: 'string', description: 'file:line or git proof' },
+        },
+      },
+    },
+  },
+}
+
+const story = (args && args.story) || (args && args.story_path) || 'the story file under review'
+const reviewer = (args && args.user_name) || 'reviewer'
+
+// --- Step 1: Load story and discover changes -------------------------------
+phase('LOAD')
+const loaded = await agent(
+  `You are code-review (BYAN ADVERSARIAL Senior Developer reviewer). Target story: ${JSON.stringify(story)}.\n` +
+    `Read the COMPLETE story file. Set story_key from the filename (e.g. "1-2-user-auth.md" -> "1-2-user-auth") or metadata. ` +
+    `Parse: Story, Acceptance Criteria, Tasks/Subtasks (note [x] vs [ ]), Dev Agent Record -> File List, Change Log, Status.\n` +
+    `Then DISCOVER ACTUAL CHANGES via git (if a git repo is present): run "git status --porcelain", ` +
+    `"git diff --name-only", and "git diff --cached --name-only"; compile the list of actually changed files. ` +
+    `Cross-reference the story File List against git reality and note discrepancies: ` +
+    `(a) files in git but NOT in the story File List, (b) files in the File List with NO git change, ` +
+    `(c) undocumented uncommitted changes.\n` +
+    `Load project-context.md for coding standards if it exists. ` +
+    `EXCLUDE from review: _byan/, _byan-output/, and IDE/CLI config folders (.cursor/, .windsurf/, .claude/). ` +
+    `If the story cannot be found or read, say so explicitly — do not invent one.`,
+  { label: 'load-story', phase: 'LOAD' }
+)
+
+// --- Step 2: Build review attack plan --------------------------------------
+phase('PLAN')
+const plan = await agent(
+  `Build the adversarial review attack plan for story ${JSON.stringify(story)}.\n` +
+    `Context from load: ${loaded}\n` +
+    `Extract ALL Acceptance Criteria, ALL Tasks/Subtasks with completion status, and the claimed File List changes. ` +
+    `Produce the four-axis plan: (1) AC Validation — verify each AC is actually implemented; ` +
+    `(2) Task Audit — verify each [x] task is really done; (3) Code Quality — security, performance, maintainability; ` +
+    `(4) Test Quality — real assertions vs placeholder tests. ` +
+    `List the comprehensive review file set = story File List UNION git-discovered files.`,
+  { label: 'attack-plan', phase: 'PLAN' }
+)
+
+// --- Step 3: Execute adversarial review (with bounded >=3-issue floor) ------
+phase('REVIEW')
+let review = { totalIssues: 0, high: 0, medium: 0, low: 0, findings: [] }
+let rescans = 0
+while (true) {
+  const harder =
+    rescans === 0
+      ? ''
+      : `\nPREVIOUS PASS FOUND ONLY ${review.totalIssues} issue(s) — NOT LOOKING HARD ENOUGH. ` +
+        `Re-examine for: edge cases & null handling, architecture violations, documentation gaps, ` +
+        `integration issues, dependency problems, git commit message quality. Find at least 3 MORE.`
+  review = await agent(
+    `Execute the ADVERSARIAL review for story ${JSON.stringify(story)}. VALIDATE EVERY CLAIM against git reality.\n` +
+      `Plan: ${plan}\n` +
+      `Score git-vs-story discrepancies: files changed but not in File List -> MEDIUM; ` +
+      `story lists files but no git change -> HIGH (false claim); undocumented uncommitted changes -> MEDIUM.\n` +
+      `For EACH Acceptance Criterion: search the implementation for evidence -> IMPLEMENTED / PARTIAL / MISSING; ` +
+      `MISSING or PARTIAL = HIGH finding.\n` +
+      `For EACH task marked [x]: search files for proof it was actually done; if marked [x] but NOT done = CRITICAL finding ` +
+      `(record file:line proof).\n` +
+      `For EACH file in the comprehensive review set: check Security (injection, missing validation, auth), ` +
+      `Performance (N+1, inefficient loops, missing caching), Error Handling (missing try/catch, poor messages), ` +
+      `Code Quality (complex functions, magic numbers, poor naming), Test Quality (real assertions vs placeholders).\n` +
+      `Do NOT accept "looks good". Find a MINIMUM of ${MIN_ISSUES} specific, actionable issues; aim for 3-10. ` +
+      `Every finding needs file:line (or git) evidence.${harder}`,
+    { label: rescans === 0 ? 'adversarial-review' : `adversarial-rescan-${rescans}`, phase: 'REVIEW', schema: REVIEW_SCHEMA }
+  )
+  const enough = (review.totalIssues || 0) >= MIN_ISSUES
+  log(`review pass ${rescans + 1}: ${review.totalIssues} issues (H${review.high}/M${review.medium}/L${review.low}) -> ${enough ? 'floor met' : 'below floor'}`)
+  if (enough || rescans >= MAX_RESCANS) break
+  rescans += 1
+}
+
+// --- Step 4: Present findings (DECISION stays at the human gate) ------------
+phase('FINDINGS')
+// Source step 4 asks the human: 1) auto-fix, 2) create action items, 3) details.
+// That branch is a human gate — kept OUT of the script. We only categorize and
+// emit fix-ready action-item lines so the orchestrating skill can offer them.
+const findings = await agent(
+  `Categorize and present the review findings for story ${JSON.stringify(story)} (reviewer: ${JSON.stringify(reviewer)}).\n` +
+    `Review result: ${JSON.stringify(review)}\n` +
+    `Group findings into HIGH (must fix), MEDIUM (should fix), LOW (nice to fix). ` +
+    `For each finding, also produce a ready-to-paste story action-item line in the form ` +
+    `"- [ ] [AI-Review][Severity] Description [file:line]". ` +
+    `Do NOT auto-fix anything and do NOT prompt the user — the fix/action-items/details decision belongs to the human gate. ` +
+    `Output a clear findings report plus the action-item lines.`,
+  { label: 'present-findings', phase: 'FINDINGS' }
+)
+
+// --- Step 5: Compute proposed status (the human gate applies it) ------------
+phase('VERDICT')
+// Source step 5: status = "done" iff all HIGH+MEDIUM fixed AND all ACs implemented,
+// else "in-progress"; then sync sprint-status.yaml. No fixes have been applied in
+// this autonomous pass, so unresolved HIGH/MEDIUM or missing ACs => proposed
+// "in-progress". The skill writes the story Status + sprint sync at the gate.
+const blockingIssues = (review.high || 0) + (review.medium || 0)
+const acGap = (review.acMissing || 0) > 0 || (review.tasksFalselyComplete || 0) > 0
+const cleanForDone = blockingIssues === 0 && !acGap
+const proposedStatus = cleanForDone ? 'done' : 'in-progress'
+
+// Return DATA only. The skill presents this at the human gate, asks the
+// fix/action-items decision, applies the story-status update + sprint sync,
+// and records FD/strict state via MCP.
+return {
+  workflow: 'code-review',
+  story,
+  totalIssues: review.totalIssues || 0,
+  high: review.high || 0,
+  medium: review.medium || 0,
+  low: review.low || 0,
+  gitDiscrepancies: review.gitDiscrepancies || 0,
+  acMissing: review.acMissing || 0,
+  tasksFalselyComplete: review.tasksFalselyComplete || 0,
+  metMinimumIssueFloor: (review.totalIssues || 0) >= MIN_ISSUES,
+  rescans,
+  findings: review.findings || [],
+  presentation: findings,
+  proposedStatus,
+  needsHumanGate: true,
+  gateDecision: ['auto-fix', 'create-action-items', 'show-details'],
+  syncSprintStatusOnGate: true,
+}