@houseofwolvesllc/claude-scrum-skill 1.8.1 → 2.1.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-scrum-skill",
   "description": "Complete scrum pipeline — PRD to production release with Claude as scrum master. Includes project scaffolding, sprint planning, status tracking, sprint releases, and full-project emulation testing.",
-  "version": "1.3.0",
+  "version": "2.1.0",
   "author": {
     "name": "House of Wolves LLC"
   },

package/README.md

@@ -4,6 +4,8 @@ An open-source npm package of Claude Code skills that give you a complete scrum
 
 Includes project scaffolding, sprint planning, status tracking, sprint releases, full-project emulation testing, autonomous orchestration, and project cleanup.
 
+It is also an **opinionated spec-and-implementation process**: its engineering guidance is grounded in the principles of four foundational software texts — Robert C. Martin's *Clean Code*, Kent Beck's *Test-Driven Development: By Example*, Eric Evans's *Domain-Driven Design*, and the Gang of Four's *Design Patterns* — distilled into an always-on engineering baseline plus on-demand design-pattern and domain-modeling guidance. See [Acknowledgments](#acknowledgments).
+
 ```
 Manual mode — you invoke each skill:
 
@@ -54,12 +56,15 @@ PRD (optional)  -->  /project-orchestrate
 - [Autonomous Orchestration](#autonomous-orchestration)
 - [Customization](#customization)
 - [Tips](#tips)
+- [Acknowledgments](#acknowledgments)
 - [License](#license)
 
 ---
 
 ## Installation
 
+> **v2.0.0 runtime requirement:** v2.0.0 invokes Claude Code's [Workflow tool](https://docs.claude.com/claude-code) for internal fan-out. Your Claude Code must include the Workflow tool (latest CLI, desktop app, web app, and IDE extensions all do). If you're on a stale CLI install without auto-update, run `npm update -g @anthropic-ai/claude-code` first — or install the v1.8.x fallback: `npm install --save-dev @houseofwolvesllc/claude-scrum-skill@1.8.1`.
+
 ### npm (recommended)
 
 ```bash
@@ -346,9 +351,13 @@ Create a fine-grained Personal Access Token:
 | **project-emulate** | `/project-emulate` | Integration seams, layer contracts, cross-service payloads, full lifecycle walkthrough |
 | **project-orchestrate** | `/project-orchestrate [prd] [repo]` | Autonomous lifecycle driver |
 | **project-cleanup** | `/project-cleanup [path] [--fix]` | Build, lint, dead code, and test coverage |
+| **design-patterns** | `/design-patterns` | Gang of Four pattern guidance, counterweight-first; composed by `spec` (design) and `project-orchestrate` (core-domain implementation) |
+| **domain-modeling** | `/domain-modeling` | Tactical Domain-Driven Design guidance; composed by `spec` and `project-orchestrate` for core-domain epics |
 
 The `[owner/repo]` argument is only needed in GitHub mode. Jira, Trello, and local modes read from config.
 
+`design-patterns` and `domain-modeling` are **situational guidance** layered on top of the always-on engineering baseline (`skills/shared/references/ENGINEERING_BASELINE.md`). They are pulled in automatically by `spec` and `project-orchestrate` for `core`-classified subdomains, and are also invocable directly. See [Acknowledgments](#acknowledgments) for their sources.
+
 ---
 
 ## Branch Strategy
@@ -482,6 +491,59 @@ Run `/project-scaffold` with a new PRD — it detects the existing project and o
 
 ---
 
+## Architecture (v2.0.0+)
+
+claudescrumskill ships in two cooperating layers. The split is documented in detail in [ADR-0003](docs/adrs/0003-workflow-backed-re-plumbing.md).
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  Skills — markdown SKILL.md (the opinion + the surface)    │
+│  - Slash commands users type                                │
+│  - Phase / step structure                                   │
+│  - Durable repo artifacts (state files, ADRs, CONTEXT.md)   │
+│  - Installed at ~/.claude/skills/<skill>/SKILL.md           │
+└──────────────────────┬─────────────────────────────────────┘
+                       │  invokes via Workflow tool
+                       ▼
+┌────────────────────────────────────────────────────────────┐
+│  Workflows — JavaScript at lib/workflows/ (the substrate)  │
+│  - Fan-out (parallel, pipeline) up to 16 concurrent agents  │
+│  - Schema-validated structured returns                      │
+│  - Journal-based in-session resume                          │
+│  - Installed at ~/.claude/skills/_workflows/                │
+└──────────────────────┬─────────────────────────────────────┘
+                       │  spawns
+                       ▼
+┌────────────────────────────────────────────────────────────┐
+│  Agents — the workers that implement stories, review        │
+│  diffs, verify findings, etc.                               │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Workflow scripts shipped in v2.0.0
+
+| Script | Purpose | Used by |
+|--------|---------|---------|
+| `sprint_pipeline.js` | per-story pipeline: implement → review → verify → openPR | `/project-orchestrate` Phase 1 Step 3 |
+| `elaborate_epics.js` | Pass 2 of two-pass scaffolding, in parallel | `/project-scaffold` |
+| `adversarial_verify.js` | claimant/skeptic/judge per emulation finding | `/project-emulate` |
+| `review_panel.js` | multi-lens (correctness/security/style/tests) review | `/project-cleanup`, `/code-review` |
+
+### Schemas at `lib/workflows/schemas/`
+
+JSON Schema Draft 2020-12. The cross-skill type system: `SpecSchema`, `EpicSchema`, `StorySchema`, `EmulationFindingSchema`, `ReviewVerdictSchema`, `SprintStoryReturnSchema`, `ScaffoldOutputSchema`, `PRDFrontmatterSchema`. Schemas live alongside workflows and are referenced from `agent({ schema: ... })` calls.
+
+### Adding a workflow
+
+Contributors adding fan-out heavy skills (large parallel work, multi-stage pipelines, judge panels) should:
+
+1. Author the workflow at `lib/workflows/<name>.js` per the patterns in existing scripts.
+2. Add any new schemas to `lib/workflows/schemas/`.
+3. Reference the workflow from the skill markdown via the Path Resolution Algorithm documented in each affected SKILL.md (`<skills-root>/_workflows/<name>.js`).
+4. Bump the package version per SemVer (new workflow + new schema → minor; breaking schema change → major).
+
+---
+
 ## Shared References
 
 All skills reference shared configuration and standards from `skills/shared/`:
@@ -510,6 +572,29 @@ skills/shared/
 
 ---
 
+## Acknowledgments
+
+The engineering guidance in this package — the always-on baseline plus the
+`design-patterns` and `domain-modeling` skills — is grounded in the principles of
+four foundational software texts. The guidance is expressed in this project's own
+words; these works are credited as its intellectual sources. Their authors are not
+affiliated with and do not endorse this project.
+
+- **Robert C. Martin**, *Clean Code: A Handbook of Agile Software Craftsmanship*
+  (Prentice Hall, 2008) — the engineering baseline's naming, function, comment, and
+  code-quality principles.
+- **Kent Beck**, *Test-Driven Development: By Example* (Addison-Wesley, 2002) — the
+  baseline's red/green/refactor discipline and simple-design rules.
+- **Eric Evans**, *Domain-Driven Design: Tackling Complexity in the Heart of
+  Software* (Addison-Wesley, 2003) — the `domain-modeling` skill's tactical
+  building blocks and ubiquitous-language guidance.
+- **Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides** ("the Gang of
+  Four"), *Design Patterns: Elements of Reusable Object-Oriented Software*
+  (Addison-Wesley, 1994) — the `design-patterns` skill's pattern catalog.
+
+If you find this guidance useful, read the originals — they go far deeper than any
+distillation can.
+
 ## License
 
 Apache 2.0 — See [LICENSE](LICENSE) for details.

package/bin/install.js

@@ -5,6 +5,7 @@ const path = require('path');
 
 const HOME = process.env.HOME || process.env.USERPROFILE;
 const SOURCE_DIR = path.join(__dirname, '..', 'skills');
+const WORKFLOWS_SOURCE_DIR = path.join(__dirname, '..', 'lib', 'workflows');
 const IS_GLOBAL = process.env.npm_config_global === 'true';
 
 // Global install → ~/.claude/skills/
@@ -76,6 +77,14 @@ for (const skill of skills) {
   }
 }
 
+// Copy lib/workflows/ → <skillsDir>/_workflows/ (v2.0.0+).
+// Underscore prefix prevents Claude Code from registering as a skill.
+if (fs.existsSync(WORKFLOWS_SOURCE_DIR)) {
+  const workflowsDest = path.join(skillsDir, '_workflows');
+  copyRecursive(WORKFLOWS_SOURCE_DIR, workflowsDest);
+  console.log('  ⚙️  _workflows (lib/workflows + schemas)');
+}
+
 // Add .claude-scrum-skill to .gitignore if not already present (local install only)
 if (!IS_GLOBAL) {
   const projectRoot = path.resolve(skillsDir, '..', '..');

package/lib/workflows/adversarial_verify.js

@@ -0,0 +1,148 @@
+// adversarial_verify.js — Claimant / skeptic / judge verification of
+// emulation findings. Replaces "trust the emulator" with structured verdicts.
+//
+// Invoked by /project-emulate after raw findings are produced.
+//
+// args: {
+//   findings: EmulationFinding[],     // EmulationFindingSchema-shaped
+//   codebaseContext?: { projectRoot: string, languages: string[] }
+// }
+//
+// returns: Array<{ finding, claim, skeptic, verdict }>
+
+export const meta = {
+  name: 'adversarial-verify',
+  description: 'Claimant / skeptic / judge verification of emulation findings.',
+  phases: [
+    { title: 'Argue' },
+    { title: 'Judge' },
+  ],
+}
+
+const EVIDENCE_SCHEMA = {
+  type: 'object',
+  required: ['summary', 'evidence'],
+  properties: {
+    summary: { type: 'string' },
+    evidence: { type: 'array', items: { type: 'string' }, minItems: 1 },
+    confidence: { type: 'string', enum: ['low', 'medium', 'high'] },
+  },
+}
+
+const VERDICT_SCHEMA = {
+  type: 'object',
+  required: ['isReal', 'rationale'],
+  properties: {
+    isReal: { type: 'boolean' },
+    rationale: { type: 'string' },
+    confidence: { type: 'string', enum: ['low', 'medium', 'high'] },
+    severity_adjustment: {
+      type: 'string',
+      enum: ['raise', 'lower', 'unchanged'],
+      description: 'Whether to raise or lower severity vs original finding.',
+    },
+  },
+}
+
+const { findings, codebaseContext = {} } = args
+
+if (!findings || findings.length === 0) {
+  log('No findings to verify — exiting.')
+  return []
+}
+
+log(`Verifying ${findings.length} findings with claimant/skeptic/judge.`)
+
+phase('Argue')
+phase('Judge')
+
+function claimantPrompt(finding) {
+  return `You are arguing that the following emulation finding IS real and accurate.
+
+Finding (severity: ${finding.severity}):
+  Title: ${finding.title}
+  Category: ${finding.category}
+  Body: ${finding.body}
+  Affected files: ${(finding.affected_files || []).join(', ') || '(none)'}
+
+Argue the case. Read the affected files. Produce evidence supporting the finding. Cite specific lines / patterns. Default toward "real" unless evidence clearly contradicts.
+
+Return: summary, evidence (array of citations), confidence.`
+}
+
+function skepticPrompt(finding) {
+  return `You are arguing that the following emulation finding is a FALSE POSITIVE or overstated.
+
+Finding (severity: ${finding.severity}):
+  Title: ${finding.title}
+  Category: ${finding.category}
+  Body: ${finding.body}
+  Affected files: ${(finding.affected_files || []).join(', ') || '(none)'}
+
+Argue the case. Read the affected files. Look for: missing context the emulator didn't see, project-specific conventions that make this fine, downstream code that handles the concern, scope-narrowing facts that reduce severity, alternative interpretations.
+
+Return: summary, evidence (array of citations), confidence.`
+}
+
+function judgePrompt(finding, claim, skeptic) {
+  return `You are the third agent. Two prior agents argued opposing positions on this emulation finding.
+
+Finding:
+  Title: ${finding.title}
+  Body: ${finding.body}
+
+Claimant argued REAL:
+  Summary: ${claim.summary}
+  Evidence: ${(claim.evidence || []).join('\n  ')}
+  Confidence: ${claim.confidence || 'unspecified'}
+
+Skeptic argued FALSE POSITIVE:
+  Summary: ${skeptic.summary}
+  Evidence: ${(skeptic.evidence || []).join('\n  ')}
+  Confidence: ${skeptic.confidence || 'unspecified'}
+
+Judge: is this finding real or false-positive? Provide rationale. Optionally suggest a severity adjustment (raise / lower / unchanged).
+
+Return: isReal (bool), rationale, confidence, severity_adjustment.`
+}
+
+async function verifyOne(finding) {
+  const [claim, skeptic] = await parallel([
+    () =>
+      agent(claimantPrompt(finding), {
+        label: `claim:${finding.id}`,
+        phase: 'Argue',
+        schema: EVIDENCE_SCHEMA,
+      }),
+    () =>
+      agent(skepticPrompt(finding), {
+        label: `skeptic:${finding.id}`,
+        phase: 'Argue',
+        schema: EVIDENCE_SCHEMA,
+      }),
+  ])
+
+  if (!claim || !skeptic) {
+    log(`Skipping judge for finding ${finding.id} — claimant or skeptic agent failed.`)
+    return null
+  }
+
+  const verdict = await agent(judgePrompt(finding, claim, skeptic), {
+    label: `judge:${finding.id}`,
+    phase: 'Judge',
+    schema: VERDICT_SCHEMA,
+  })
+
+  if (!verdict) return null
+
+  return { finding, claim, skeptic, verdict }
+}
+
+const verified = await parallel(findings.map(f => () => verifyOne(f)))
+const successful = verified.filter(Boolean)
+
+const realCount = successful.filter(v => v.verdict.isReal).length
+const falsePositiveCount = successful.length - realCount
+log(`Verified ${successful.length}/${findings.length} findings: ${realCount} real, ${falsePositiveCount} false-positive.`)
+
+return verified

package/lib/workflows/elaborate_epics.js

@@ -0,0 +1,136 @@
+// elaborate_epics.js — Pass 2 of two-pass scaffolding.
+//
+// Invoked by /project-scaffold when two-pass mode is selected.
+// Replaces the v1.x Task-spawning prose with one parallel wave.
+//
+// args: {
+//   skeleton: {
+//     project: { name, description, global_preamble, non_functional_requirements: string[] },
+//     epics: Array<{
+//       name, slug, description,
+//       slice: { start_line: int, end_line: int },
+//       depends_on: string[],
+//       shared_design_concerns: string[]
+//     }>
+//   },
+//   prdPath: string,                       // for slicing
+//   conventionsPath?: string               // shared/references/CONVENTIONS.md
+// }
+//
+// returns: Epic[] with stories[] populated. Failed epics return null;
+//          the calling skill marks their stories needs-context.
+
+export const meta = {
+  name: 'elaborate-epics',
+  description: 'Pass 2 of two-pass scaffolding: per-epic elaboration in parallel.',
+  phases: [{ title: 'Elaborate Epics' }],
+}
+
+const EPIC_SCHEMA = {
+  type: 'object',
+  required: ['name', 'slug', 'description', 'stories'],
+  properties: {
+    name: { type: 'string' },
+    slug: { type: 'string', pattern: '^[a-z0-9]+(-[a-z0-9]+)*$' },
+    description: { type: 'string' },
+    depends_on: { type: 'array', items: { type: 'string' } },
+    shared_design_concerns: { type: 'array', items: { type: 'string' } },
+    stories: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['title', 'slug', 'acceptance_criteria', 'points', 'executor'],
+        properties: {
+          title: { type: 'string' },
+          slug: { type: 'string', pattern: '^[a-z0-9]+(-[a-z0-9]+)*$' },
+          acceptance_criteria: { type: 'array', items: { type: 'string' }, minItems: 1 },
+          technical_context: { type: 'string' },
+          points: { type: 'integer', enum: [1, 2, 3, 5, 8, 13] },
+          executor: { type: 'string', enum: ['claude', 'human', 'cowork'] },
+          priority: { type: 'string', enum: ['P0-critical', 'P1-high', 'P2-medium', 'P3-low'] },
+          persona: { type: 'string', enum: ['impl', 'ops', 'research'] },
+          blocked_by: { type: 'array', items: { type: 'string' } },
+          blocks: { type: 'array', items: { type: 'string' } },
+          labels: { type: 'array', items: { type: 'string' } },
+        },
+      },
+      minItems: 1,
+    },
+  },
+}
+
+const { skeleton, prdPath, conventionsPath } = args
+
+if (!skeleton || !skeleton.epics || skeleton.epics.length === 0) {
+  log('Empty skeleton — exiting.')
+  return []
+}
+
+log(`Pass 2: elaborating ${skeleton.epics.length} epics from ${prdPath}.`)
+
+phase('Elaborate Epics')
+
+function buildElaboratePrompt(epic) {
+  const siblings = skeleton.epics
+    .filter(e => e.slug !== epic.slug)
+    .map(e => `  - ${e.slug}: ${e.description}`)
+    .join('\n')
+
+  const sharedConcerns = (epic.shared_design_concerns || []).map(c => `  - ${c}`).join('\n')
+
+  return `You are elaborating epic "${epic.name}" (slug: ${epic.slug}) for project "${skeleton.project.name}".
+
+== Project global preamble ==
+${skeleton.project.global_preamble || ''}
+
+== Project NFRs ==
+${(skeleton.project.non_functional_requirements || []).map(n => `  - ${n}`).join('\n')}
+
+== This epic ==
+Description: ${epic.description}
+PRD slice: lines ${epic.slice.start_line}–${epic.slice.end_line} of ${prdPath}
+Depends on: ${(epic.depends_on || []).join(', ') || 'none'}
+Shared design concerns this epic introduces:
+${sharedConcerns || '  (none)'}
+
+== Sibling epics (for dependency awareness, NOT for elaboration) ==
+${siblings || '  (none)'}
+
+== Your task ==
+Read the PRD slice (lines ${epic.slice.start_line}–${epic.slice.end_line}). Produce the complete story list for THIS epic. Each story needs:
+  - title (concise imperative)
+  - slug (kebab-case)
+  - acceptance_criteria (at least one specific, testable item)
+  - technical_context (architecture notes, relevant files, approach)
+  - points (Fibonacci: 1, 2, 3, 5, 8, 13 per CONVENTIONS.md)
+  - executor (claude | human | cowork; per CONVENTIONS.md guidelines)
+  - persona (impl | ops | research; default impl)
+  - priority (P0/P1/P2/P3)
+  - blocked_by, blocks (within this epic or referencing other epics' slugs)
+  - labels (per CONVENTIONS.md taxonomy)
+
+${conventionsPath ? `Reference ${conventionsPath} for the label taxonomy and story point guidelines.` : ''}
+
+Return an Epic shape with name, slug, description, depends_on, shared_design_concerns, and stories[] populated.`
+}
+
+const elaborated = await parallel(
+  skeleton.epics.map(epic => () =>
+    agent(buildElaboratePrompt(epic), {
+      label: `elaborate:${epic.slug}`,
+      phase: 'Elaborate Epics',
+      schema: EPIC_SCHEMA,
+    })
+  )
+)
+
+const successes = elaborated.filter(Boolean)
+log(`Pass 2 complete: ${successes.length}/${skeleton.epics.length} epics elaborated successfully.`)
+if (successes.length < skeleton.epics.length) {
+  const failed = skeleton.epics
+    .filter((_, i) => !elaborated[i])
+    .map(e => e.slug)
+  log(`Failed epics (calling skill should mark stories needs-context): ${failed.join(', ')}`)
+}
+
+return elaborated

package/lib/workflows/review_panel.js

@@ -0,0 +1,166 @@
+// review_panel.js — Multi-lens parallel review with aggregated verdict.
+//
+// Invoked by /project-cleanup and /code-review for the review gate.
+//
+// args: {
+//   diff: string,
+//   files: Array<{ path: string, contents: string }>,
+//   lenses?: Array<"correctness" | "security" | "style" | "tests">,
+//   projectConventionsPath?: string    // CLAUDE.md
+// }
+//
+// returns: {
+//   panelVerdict: ReviewVerdict (aggregated),
+//   perLensVerdicts: Record<lens, ReviewVerdict>
+// }
+
+export const meta = {
+  name: 'review-panel',
+  description: 'Multi-lens parallel review with aggregated verdict.',
+  phases: [
+    { title: 'Per-Lens Review' },
+    { title: 'Aggregate' },
+  ],
+}
+
+const REVIEW_VERDICT_SCHEMA = {
+  type: 'object',
+  required: ['recommendation', 'findings', 'summary'],
+  properties: {
+    recommendation: { type: 'string', enum: ['accept', 'accept-with-followups', 'block'] },
+    findings: {
+      type: 'object',
+      required: ['critical', 'warning', 'info'],
+      properties: {
+        critical: { type: 'array' },
+        warning: { type: 'array' },
+        info: { type: 'array' },
+      },
+    },
+    summary: { type: 'string' },
+    lens: { type: 'string' },
+  },
+}
+
+const DEFAULT_LENSES = ['correctness', 'security', 'style', 'tests']
+
+const { diff, files, lenses = DEFAULT_LENSES, projectConventionsPath } = args
+
+if (!diff && (!files || files.length === 0)) {
+  log('No diff and no files — nothing to review.')
+  return {
+    panelVerdict: {
+      recommendation: 'accept',
+      findings: { critical: [], warning: [], info: [] },
+      summary: 'Nothing to review.',
+    },
+    perLensVerdicts: {},
+  }
+}
+
+log(`Review panel: ${lenses.length} lenses (${lenses.join(', ')}).`)
+
+phase('Per-Lens Review')
+phase('Aggregate')
+
+const LENS_INSTRUCTIONS = {
+  correctness: `Focus on: does the code do what the acceptance criteria / change description requires? Are there logic errors, off-by-ones, missed branches, broken invariants? Are edge cases handled?`,
+  security: `Focus on: injection sinks (SQL, shell, HTML, path), missing authentication checks, broken authorization, secret exposure, unvalidated user input reaching dangerous APIs, permission expansion without justification.`,
+  style: `Focus on: project convention adherence (per CLAUDE.md), naming consistency, file organization, import ordering. Do NOT bikeshed style the project doesn't enforce.`,
+  tests: `Focus on: are new behaviors covered by tests? Are existing tests still meaningful? Are tests testing behavior or implementation? Coverage at integration seams?`,
+}
+
+function buildLensPrompt(lens) {
+  const conventions = projectConventionsPath
+    ? `Read ${projectConventionsPath} first — review against the project's actual conventions, not generic standards.`
+    : `Read the project CLAUDE.md if it exists — review against the project's actual conventions, not generic standards.`
+  return `You are reviewing a code change through the **${lens}** lens.
+
+${conventions}
+
+Lens focus: ${LENS_INSTRUCTIONS[lens] || '(no specific instructions for this lens)'}
+
+== Diff ==
+${diff || '(no diff provided; review the files below directly)'}
+
+== Changed files (full contents) ==
+${(files || []).map(f => `--- ${f.path} ---\n${f.contents}`).join('\n\n')}
+
+Return a ReviewVerdict for THIS LENS ONLY:
+  - recommendation (accept | accept-with-followups | block)
+  - findings grouped by severity (critical | warning | info)
+  - summary (one-paragraph)
+  - lens: "${lens}"
+
+Be specific. "This could be better" is not a finding. Cite file:line where applicable.`
+}
+
+const perLensResults = await parallel(
+  lenses.map(lens => () =>
+    agent(buildLensPrompt(lens), {
+      label: `review:${lens}`,
+      phase: 'Per-Lens Review',
+      schema: REVIEW_VERDICT_SCHEMA,
+    })
+  )
+)
+
+const perLensVerdicts = {}
+lenses.forEach((lens, i) => {
+  if (perLensResults[i]) {
+    perLensVerdicts[lens] = perLensResults[i]
+  }
+})
+
+const validVerdicts = Object.values(perLensVerdicts)
+
+if (validVerdicts.length === 0) {
+  log('All lens reviewers failed — returning a default block verdict.')
+  return {
+    panelVerdict: {
+      recommendation: 'block',
+      findings: {
+        critical: [{
+          title: 'Review panel failed to produce any verdict',
+          severity: 'critical',
+          body: 'All lens reviewers returned null.',
+        }],
+        warning: [],
+        info: [],
+      },
+      summary: 'Review panel non-functional.',
+    },
+    perLensVerdicts: {},
+  }
+}
+
+// Aggregation rule: any block → panel block; any accept-with-followups → panel accept-with-followups; else accept.
+let panelRecommendation = 'accept'
+if (validVerdicts.some(v => v.recommendation === 'block')) {
+  panelRecommendation = 'block'
+} else if (validVerdicts.some(v => v.recommendation === 'accept-with-followups')) {
+  panelRecommendation = 'accept-with-followups'
+}
+
+// Union findings across lenses, preserving lens attribution.
+const findings = { critical: [], warning: [], info: [] }
+for (const [lens, verdict] of Object.entries(perLensVerdicts)) {
+  for (const sev of ['critical', 'warning', 'info']) {
+    for (const f of verdict.findings[sev] || []) {
+      findings[sev].push({ ...f, lens })
+    }
+  }
+}
+
+const summary = `Panel verdict: ${panelRecommendation}. ${validVerdicts.length}/${lenses.length} lenses reported. ${findings.critical.length} critical, ${findings.warning.length} warning, ${findings.info.length} info findings (union across lenses).`
+
+log(summary)
+
+return {
+  panelVerdict: {
+    recommendation: panelRecommendation,
+    findings,
+    summary,
+  },
+  perLensVerdicts,
+}

package/lib/workflows/schemas/EmulationFindingSchema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/houseofwolvesllc/claudescrumskill/schemas/EmulationFindingSchema.json",
+  "title": "EmulationFindingSchema",
+  "description": "Single finding produced by /project-emulate; consumed by adversarial_verify.js.",
+  "type": "object",
+  "required": ["id", "severity", "category", "title", "body"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique finding identifier (e.g., C1, W3, I7)."
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["critical", "warning", "info"]
+    },
+    "category": {
+      "type": "string",
+      "description": "Free-form classification (e.g., 'Integration/Dockerfile/COPY', 'Layer/ResponseFormat', 'Documentation/Consistency')."
+    },
+    "title": {
+      "type": "string",
+      "description": "One-line finding summary."
+    },
+    "body": {
+      "type": "string",
+      "description": "Detailed finding description including reproduction or evidence."
+    },
+    "affected_files": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Repo-relative paths of files implicated by the finding."
+    }
+  },
+  "additionalProperties": false
+}