@esquadrao/cli 0.0.0-stage → 1.6.0

package/src/roles/authority.js

@@ -0,0 +1,129 @@
+// Structural Authority Matrix and Permission Guard for Engineering Roles.
+// Zero-dependency native Node.js implementation.
+
+import { definition as productManager } from './productManager.js';
+import { definition as systemAnalyst } from './systemAnalyst.js';
+import { definition as softwareArchitect } from './softwareArchitect.js';
+import { definition as techLead } from './techLead.js';
+import { definition as securityEngineer } from './securityEngineer.js';
+import { definition as softwareEngineer } from './softwareEngineer.js';
+import { definition as codeReviewer } from './codeReviewer.js';
+import { definition as sreEngineer } from './sreEngineer.js';
+import { definition as qaEngineer } from './qaEngineer.js';
+import { definition as technicalWriter } from './technicalWriter.js';
+import { definition as engineeringManager } from './engineeringManager.js';
+import { definition as mediaProducer } from './mediaProducer.js';
+
+const ROLE_DEFINITIONS = {
+  'product-manager': productManager,
+  'system-analyst': systemAnalyst,
+  'software-architect': softwareArchitect,
+  'tech-lead': techLead,
+  'security-engineer': securityEngineer,
+  'software-engineer': softwareEngineer,
+  'code-reviewer': codeReviewer,
+  'sre-engineer': sreEngineer,
+  'qa-engineer': qaEngineer,
+  'technical-writer': technicalWriter,
+  'engineering-manager': engineeringManager,
+  'media-producer': mediaProducer,
+};
+
+export const LEGACY_ALIASES = {
+  mission_compiler: 'product-manager',
+  cartographer: 'system-analyst',
+  chief_architect: 'software-architect',
+  architecture_adjudicator: 'tech-lead',
+  spec_critic: 'security-engineer',
+  implementer: 'software-engineer',
+  reviewer: 'code-reviewer',
+  failure_diagnostician: 'sre-engineer',
+  critical_acceptance: 'qa-engineer',
+  documentation: 'technical-writer',
+  next_mission_generator: 'engineering-manager',
+  studio_director: 'media-producer',
+};
+
+export const FORBIDDEN_COMMAND_PATTERNS = [
+  /git\s+push\b.*?\b(main|master)\b/i,
+  /git\s+push\b.*?\s+(-f|--force)\b/i,
+  /git\s+merge\b.*?\b(main|master)\b/i,
+  /git\s+reset\s+--hard\b/i,
+  /rm\s+-rf\s+[\/\\]/i,
+];
+
+export const READ_ONLY_ROLES = new Set([
+  'system-analyst',
+  'security-engineer',
+  'code-reviewer',
+]);
+
+export const ALLOWED_READ_COMMAND_PREFIXES = [
+  'git status',
+  'git diff',
+  'git log',
+  'git rev-parse',
+  'git branch',
+  'node -v',
+  'npm test',
+  'dir',
+  'ls',
+  'find',
+];
+
+export function checkCommandExecution(roleId, command) {
+  const cmd = (command || '').trim();
+  for (const pattern of FORBIDDEN_COMMAND_PATTERNS) {
+    if (pattern.test(cmd)) {
+      throw new Error(`Structural violation: Command matches forbidden pattern '${pattern}' for role '${roleId}'.`);
+    }
+  }
+
+  const normalized = (roleId || '').toLowerCase().replace(/_/g, '-');
+  const canonical = LEGACY_ALIASES[roleId?.toLowerCase()] || normalized;
+  if (READ_ONLY_ROLES.has(roleId) || READ_ONLY_ROLES.has(canonical)) {
+    const isAllowed = ALLOWED_READ_COMMAND_PREFIXES.some((prefix) =>
+      cmd.toLowerCase().startsWith(prefix.toLowerCase())
+    );
+    if (!isAllowed) {
+      throw new Error(`Structural violation: Role '${roleId}' is strictly read-only and cannot execute mutating command: '${cmd}'.`);
+    }
+  }
+}
+
+export function checkOutputWrite(roleId, filePath) {
+  const normalized = (roleId || '').toLowerCase().replace(/_/g, '-');
+  const canonical = LEGACY_ALIASES[roleId?.toLowerCase()] || normalized;
+  const def = ROLE_DEFINITIONS[canonical];
+
+  if (!def) {
+    throw new Error(`Structural violation: Unknown role '${roleId}'.`);
+  }
+
+  const prefixes = def.allowedOutputPrefixes || def.allowedOutputs || [];
+  if (prefixes.includes('*')) {
+    return;
+  }
+
+  // ponytail: relative prefix and exact match only; upgrade to glob engine if complex wildcard patterns needed
+  const normalizedPath = filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+  const isAllowed = prefixes.some((prefix) => {
+    if (prefix.endsWith('/')) {
+      return normalizedPath.startsWith(prefix) || normalizedPath === prefix.slice(0, -1);
+    }
+    return normalizedPath === prefix;
+  });
+
+  if (!isAllowed) {
+    throw new Error(`Structural violation: File '${filePath}' violates allowed output prefixes for role '${roleId}'. Allowed: ${prefixes.join(', ')}`);
+  }
+}
+
+export function checkFileWrite(roleId, filePath) {
+  const normalized = (roleId || '').toLowerCase().replace(/_/g, '-');
+  const canonical = LEGACY_ALIASES[roleId?.toLowerCase()] || normalized;
+  if (READ_ONLY_ROLES.has(roleId) || READ_ONLY_ROLES.has(canonical)) {
+    throw new Error(`Structural violation: Role '${roleId}' is strictly read-only. File write denied for '${filePath}'.`);
+  }
+  checkOutputWrite(roleId, filePath);
+}

package/src/roles/codeReviewer.js

@@ -0,0 +1,65 @@
+// Code Reviewer (formerly reviewer)
+// Independent verification, anti-slop pattern linting, code quality inspection, and anti-self-review enforcement.
+
+export const definition = {
+  id: 'code-reviewer',
+  title: 'Code Reviewer',
+  formerName: 'reviewer',
+  category: 'quality',
+  description: 'Conducts independent peer code reviews, filters out boilerplate/slop, validates diff correctness, and enforces anti-self-review.',
+  requiredCapabilities: ['chat'],
+  readOnly: true,
+  allowedOutputPrefixes: ['reports/'],
+};
+
+export function buildPrompt(params = {}) {
+  const { diff = '', objective = '', implementerId = '', reviewerId = '' } = params;
+
+  if (implementerId && reviewerId && implementerId === reviewerId) {
+    throw new Error(`Anti-self-review violation: Reviewer '${reviewerId}' cannot review its own work from '${implementerId}'.`);
+  }
+
+  return `You are acting as an Independent Code Reviewer.
+Inspect the provided diff with adversarial scrutiny.
+Verify that the diff is minimal, adheres strictly to requirements, avoids speculative abstractions, and includes tests.
+
+Objective:
+${objective}
+
+Git Diff:
+\`\`\`diff
+${diff}
+\`\`\`
+
+Anti-Slop Checklist:
+- No unused interfaces or single-implementation factories.
+- No empty catch blocks or suppressed errors.
+- No unrequested dependencies.
+- No decorative/tautological comments.
+- Test coverage present and passing.
+
+Output Requirements:
+Return a structured JSON object with:
+{
+  "verdict": "PASS | FAIL_MINOR | FAIL_MAJOR | BLOCKER",
+  "findings": [
+    {
+      "severity": "INFO | MINOR | MAJOR | BLOCKER",
+      "file": "path/to/file.ext",
+      "line": 42,
+      "issue": "Specific description of bug or violation",
+      "suggestion": "How to fix"
+    }
+  ],
+  "recommendation": "Ready to merge | Requires targeted fixes | Reject"
+}`;
+}
+
+export function validateContract(data) {
+  if (!data || typeof data !== 'object') throw new Error('Contract must be an object');
+  if (!['PASS', 'FAIL_MINOR', 'FAIL_MAJOR', 'BLOCKER'].includes(data.verdict)) {
+    throw new Error('Invalid review verdict');
+  }
+  if (!Array.isArray(data.findings)) throw new Error('"findings" must be an array');
+  return true;
+}

package/src/roles/engineeringManager.js

@@ -0,0 +1,53 @@
+// Engineering Delivery Manager / Agile Coach (formerly next_mission_generator)
+// Derives follow-up engineering milestones, roadmap planning, and task backlogs from actual execution evidence.
+
+export const definition = {
+  id: 'engineering-manager',
+  title: 'Engineering Manager',
+  formerName: 'next_mission_generator',
+  category: 'management',
+  description: 'Synthesizes completed project evidence into follow-up milestones, roadmap iterations, and next sprint tasks.',
+  requiredCapabilities: ['chat'],
+  readOnly: false,
+  allowedOutputPrefixes: ['docs/', 'reports/', 'NEXT_MISSION.md'],
+};
+
+export function buildPrompt(params = {}) {
+  const { completedTask = '', verdict = '', remainingDebt = [] } = params;
+  return `You are acting as an Engineering Delivery Manager and Agile Lead.
+Derive the next actionable milestone and sprint backlog based on verified execution evidence.
+
+Completed Task:
+${completedTask}
+
+Acceptance Verdict:
+${verdict}
+
+Remaining Technical Debt / Future Scope:
+${remainingDebt.map((d) => `- ${d}`).join('\n') || '- None noted'}
+
+Output Requirements:
+Return a structured JSON object with:
+{
+  "next_milestone": "Concise title of the subsequent milestone",
+  "priority": "P0 | P1 | P2",
+  "objectives": ["concrete objective 1", "concrete objective 2"],
+  "tasks": [
+    {
+      "id": "TASK-01",
+      "title": "Task title",
+      "assigned_role": "role identifier",
+      "description": "Short description of expected output"
+    }
+  ],
+  "invariants_to_preserve": ["system guarantees that remain protected"]
+}`;
+}
+
+export function validateContract(data) {
+  if (!data || typeof data !== 'object') throw new Error('Contract must be an object');
+  if (!data.next_milestone || typeof data.next_milestone !== 'string') throw new Error('Missing "next_milestone"');
+  if (!Array.isArray(data.objectives)) throw new Error('"objectives" must be an array');
+  if (!Array.isArray(data.tasks) || data.tasks.length === 0) throw new Error('"tasks" must be a non-empty array');
+  return true;
+}

package/src/roles/index.js

@@ -0,0 +1,80 @@
+// Canonical Registry of Industry Roles for AI Agent Orchestration.
+// Zero dependencies - Node.js stdlib only.
+
+import * as productManager from './productManager.js';
+import * as systemAnalyst from './systemAnalyst.js';
+import * as softwareArchitect from './softwareArchitect.js';
+import * as techLead from './techLead.js';
+import * as securityEngineer from './securityEngineer.js';
+import * as softwareEngineer from './softwareEngineer.js';
+import * as codeReviewer from './codeReviewer.js';
+import * as sreEngineer from './sreEngineer.js';
+import * as qaEngineer from './qaEngineer.js';
+import * as technicalWriter from './technicalWriter.js';
+import * as engineeringManager from './engineeringManager.js';
+import * as mediaProducer from './mediaProducer.js';
+import { checkCommandExecution, checkFileWrite, checkOutputWrite, READ_ONLY_ROLES, FORBIDDEN_COMMAND_PATTERNS } from './authority.js';
+
+export const ROLES = {
+  'product-manager': productManager,
+  'system-analyst': systemAnalyst,
+  'software-architect': softwareArchitect,
+  'tech-lead': techLead,
+  'security-engineer': securityEngineer,
+  'software-engineer': softwareEngineer,
+  'code-reviewer': codeReviewer,
+  'sre-engineer': sreEngineer,
+  'qa-engineer': qaEngineer,
+  'technical-writer': technicalWriter,
+  'engineering-manager': engineeringManager,
+  'media-producer': mediaProducer,
+};
+
+// Legacy name alias mapping for backwards compatibility
+export const LEGACY_ALIASES = {
+  mission_compiler: 'product-manager',
+  cartographer: 'system-analyst',
+  chief_architect: 'software-architect',
+  architecture_adjudicator: 'tech-lead',
+  spec_critic: 'security-engineer',
+  implementer: 'software-engineer',
+  reviewer: 'code-reviewer',
+  failure_diagnostician: 'sre-engineer',
+  critical_acceptance: 'qa-engineer',
+  documentation: 'technical-writer',
+  next_mission_generator: 'engineering-manager',
+  studio_director: 'media-producer',
+};
+
+export function getRole(idOrAlias) {
+  if (!idOrAlias) return null;
+  const normalized = idOrAlias.toLowerCase().replace(/_/g, '-');
+  if (ROLES[normalized]) return ROLES[normalized];
+  const mapped = LEGACY_ALIASES[idOrAlias.toLowerCase()];
+  if (mapped && ROLES[mapped]) return ROLES[mapped];
+  return null;
+}
+
+export function listRoles() {
+  return Object.values(ROLES).map((mod) => mod.definition);
+}
+
+export {
+  checkCommandExecution,
+  checkFileWrite,
+  checkOutputWrite,
+  READ_ONLY_ROLES,
+  FORBIDDEN_COMMAND_PATTERNS,
+  productManager,
+  systemAnalyst,
+  softwareArchitect,
+  techLead,
+  securityEngineer,
+  softwareEngineer,
+  codeReviewer,
+  sreEngineer,
+  qaEngineer,
+  technicalWriter,
+  engineeringManager,
+  mediaProducer,
+};

package/src/roles/mediaProducer.js

@@ -0,0 +1,223 @@
+// Media Producer / Creative Director Role
+// Portable specification and validation engine for local-first short-form video pipelines.
+
+import { getCaptionTemplate } from '../captionTemplates.js';
+
+export const definition = {
+  id: 'media-producer',
+  title: 'Media Producer',
+  formerName: 'studio_director',
+  category: 'media',
+  description: 'Authors and validates short-form video edit plans, timeline cuts, audio gain parameters, NFC text normalization, and media QA contracts.',
+  requiredCapabilities: ['chat'],
+  readOnly: false,
+  allowedOutputPrefixes: ['media/', 'reports/', 'packages/'],
+};
+
+export function normalizeNfc(text = '') {
+  return typeof text === 'string' ? text.normalize('NFC') : '';
+}
+
+export function validateCutInterval(interval) {
+  if (!interval || typeof interval !== 'object') throw new Error('CutInterval must be an object');
+  const { in_ms, out_ms } = interval;
+  if (!Number.isInteger(in_ms) || !Number.isInteger(out_ms)) {
+    throw new Error(`Interval bounds must be integers: [${in_ms}, ${out_ms})`);
+  }
+  if (in_ms < 0) throw new Error(`in_ms cannot be negative: ${in_ms}`);
+  if (out_ms <= in_ms) throw new Error(`Invalid interval: in_ms (${in_ms}) >= out_ms (${out_ms})`);
+  if (out_ms - in_ms < 100) throw new Error(`Interval duration too short (< 100ms): ${out_ms - in_ms}ms`);
+  return true;
+}
+
+export function validateVideoClip(clip) {
+  if (!clip || typeof clip !== 'object') throw new Error('VideoClip must be an object');
+  if (clip.kind !== 'video') throw new Error('VideoClip.kind must be "video"');
+  if (clip.speed !== undefined && clip.speed !== 1) throw new Error('V1 speed must be 1');
+  if (clip.timeline_start_ms < 0) throw new Error('timeline_start_ms cannot be negative');
+  validateCutInterval({ in_ms: clip.in_ms, out_ms: clip.out_ms });
+  return true;
+}
+
+export function validateTextClip(clip) {
+  if (!clip || typeof clip !== 'object') throw new Error('TextClip must be an object');
+  if (clip.kind !== 'text') throw new Error('TextClip.kind must be "text"');
+  const norm = normalizeNfc(clip.text);
+  if (norm.length < 1 || norm.length > 200) {
+    throw new Error(`TextClip text length must be between 1 and 200 NFC characters, got ${norm.length}`);
+  }
+  if (norm.includes('<') || norm.includes('>')) {
+    throw new Error('TextClip cannot contain HTML markup');
+  }
+  if (!Number.isInteger(clip.duration_ms) || clip.duration_ms < 100 || clip.duration_ms > 600000) {
+    throw new Error(`TextClip duration_ms must be between 100 and 600000ms, got ${clip.duration_ms}`);
+  }
+  if (clip.timeline_start_ms < 0) throw new Error('TextClip timeline_start_ms cannot be negative');
+  return true;
+}
+
+export function validateAudioTrack(track) {
+  if (!track || typeof track !== 'object') throw new Error('AudioTrack must be an object');
+  if (track.kind !== 'source') throw new Error('AudioTrack.kind must be "source"');
+  if (typeof track.gain_db !== 'number' || track.gain_db < -60 || track.gain_db > 12) {
+    throw new Error(`gain_db must be between -60 and +12 dB, got ${track.gain_db}`);
+  }
+  return true;
+}
+
+export function validateEditPlan(plan) {
+  if (!plan || typeof plan !== 'object') throw new Error('EditPlan must be an object');
+  if (plan.schema_version !== 1) throw new Error(`Unsupported schema_version: ${plan.schema_version}`);
+  if (!['edit_only', 'dark', 'podcast_clip'].includes(plan.mode)) {
+    throw new Error(`Unsupported mode: ${plan.mode}`);
+  }
+
+  if (plan.caption_template) getCaptionTemplate(plan.caption_template);
+  if (Array.isArray(plan.captions)) {
+    for (const caption of plan.captions) {
+      if (caption.template) getCaptionTemplate(caption.template);
+    }
+  }
+
+  // Clips validation
+  if (plan.mode === 'edit_only') {
+    if (!Array.isArray(plan.clips) || plan.clips.length !== 2) {
+      throw new Error(`V1 edit_only slice requires exactly 2 clips, got ${plan.clips?.length}`);
+    }
+    let timelinePos = 0;
+    for (let i = 0; i < plan.clips.length; i++) {
+      const c = plan.clips[i];
+      validateVideoClip(c);
+      if (c.timeline_start_ms !== timelinePos) {
+        throw new Error(`Clips must be contiguous: clip ${i} starts at ${c.timeline_start_ms}, expected ${timelinePos}`);
+      }
+      timelinePos += c.out_ms - c.in_ms;
+    }
+
+    if (!Array.isArray(plan.audio_tracks) || plan.audio_tracks.length !== plan.clips.length) {
+      throw new Error('Each video clip must have an accompanying source audio track');
+    }
+    for (let i = 0; i < plan.audio_tracks.length; i++) {
+      const a = plan.audio_tracks[i];
+      validateAudioTrack(a);
+      if (a.clip_id !== plan.clips[i].clip_id) {
+        throw new Error(`Audio track ${i} clip_id mismatch: expected ${plan.clips[i].clip_id}`);
+      }
+    }
+  } else if (plan.mode === 'dark') {
+    if (!Array.isArray(plan.clips) || plan.clips.length === 0) {
+      throw new Error('Dark mode requires at least one TextClip');
+    }
+    for (const c of plan.clips) {
+      validateTextClip(c);
+    }
+  } else if (plan.mode === 'podcast_clip') {
+    if (!Array.isArray(plan.clips) || plan.clips.length === 0) {
+      throw new Error('podcast_clip mode requires at least 1 video clip');
+    }
+    let timelinePos = 0;
+    for (let i = 0; i < plan.clips.length; i++) {
+      const c = plan.clips[i];
+      validateVideoClip(c);
+      if (c.timeline_start_ms !== timelinePos) {
+        throw new Error(`Clips must be contiguous: clip ${i} starts at ${c.timeline_start_ms}, expected ${timelinePos}`);
+      }
+      timelinePos += c.out_ms - c.in_ms;
+    }
+
+    if (!Array.isArray(plan.audio_tracks) || plan.audio_tracks.length !== plan.clips.length) {
+      throw new Error('Each video clip must have an accompanying source audio track');
+    }
+    for (let i = 0; i < plan.audio_tracks.length; i++) {
+      const a = plan.audio_tracks[i];
+      validateAudioTrack(a);
+      if (a.clip_id !== plan.clips[i].clip_id) {
+        throw new Error(`Audio track ${i} clip_id mismatch: expected ${plan.clips[i].clip_id}`);
+      }
+    }
+
+    if (plan.captions) {
+      if (!Array.isArray(plan.captions)) {
+        throw new Error('captions must be an array');
+      }
+      for (const cap of plan.captions) {
+        const norm = normalizeNfc(cap.text);
+        if (norm.length < 1 || norm.length > 200) {
+          throw new Error(`Caption text length must be between 1 and 200 NFC characters, got ${norm.length}`);
+        }
+        if (norm.includes('<') || norm.includes('>')) {
+          throw new Error('Caption cannot contain HTML markup');
+        }
+      }
+    }
+  }
+
+  // B-roll overlays validation
+  if (plan.overlays) {
+    if (!Array.isArray(plan.overlays)) {
+      throw new Error('overlays must be an array');
+    }
+    for (const ov of plan.overlays) {
+      if (!ov || typeof ov !== 'object') throw new Error('Overlay must be an object');
+      if (!ov.asset_id && !ov.source_asset) throw new Error('Overlay requires asset_id');
+      if (typeof ov.in_ms !== 'number' || ov.in_ms < 0) throw new Error('Overlay in_ms must be >= 0');
+      if (typeof ov.out_ms !== 'number' || ov.out_ms <= ov.in_ms) throw new Error('Overlay out_ms must be > in_ms');
+      if (typeof ov.timeline_start_ms !== 'number' || ov.timeline_start_ms < 0) {
+        throw new Error('Overlay timeline_start_ms must be >= 0');
+      }
+      if (ov.layout && !['fullscreen', 'pip', 'split_bottom', 'split_top'].includes(ov.layout)) {
+        throw new Error(`Unsupported overlay layout: ${ov.layout}`);
+      }
+    }
+  }
+
+  // Background music tracks validation
+  if (plan.music_tracks) {
+    if (!Array.isArray(plan.music_tracks)) {
+      throw new Error('music_tracks must be an array');
+    }
+    for (const m of plan.music_tracks) {
+      if (!m || typeof m !== 'object') throw new Error('music_track must be an object');
+      if (!m.asset_id && !m.source_asset) throw new Error('music_track requires asset_id');
+      if (m.gain_db !== undefined && (typeof m.gain_db !== 'number' || m.gain_db < -60 || m.gain_db > 12)) {
+        throw new Error('music_track gain_db must be between -60 and +12');
+      }
+    }
+  }
+
+  // Output specification
+  const output = plan.output || {};
+  const validDimensions =
+    (output.width === 1080 && output.height === 1920) ||
+    (output.width === 1920 && output.height === 1080);
+  if (!validDimensions) {
+    throw new Error(`Output dimensions must be 1080x1920 (vertical) or 1920x1080 (horizontal), got ${output.width}x${output.height}`);
+  }
+  if (output.fps_num !== 30 || output.fps_den !== 1) {
+    throw new Error('Output FPS must be 30/1');
+  }
+  if (output.video_codec !== 'h264' || output.audio_codec !== 'aac') {
+    throw new Error('Output codecs must be h264 and aac');
+  }
+
+  return true;
+}
+
+export const validateContract = validateEditPlan;
+
+export function buildPrompt(params = {}) {
+  const { mode = 'edit_only', assets = [] } = params;
+  return `You are acting as a Media Producer and Video Pipeline Director.
+Generate a valid EditPlan contract for short-form video creation.
+
+Mode: ${mode}
+Available Assets:
+${assets.map((a) => `- ${a}`).join('\n') || '- None provided'}
+
+Rules:
+1. Mode edit_only requires exactly 2 contiguous video clips from source media, each >= 100ms.
+2. Mode dark requires TextClips with 1-200 NFC characters and zero HTML.
+3. Mode podcast_clip requires >= 1 contiguous video clip(s) with accompanying source audio track(s) and optional captions.
+4. Audio gain must stay between -60 dB and +12 dB.
+5. Output must be 1080x1920 vertical @ 30fps with h264/aac encoding.`;
+}

package/src/roles/productManager.js

@@ -0,0 +1,50 @@
+// Product Manager Role (formerly mission_compiler)
+// Synthesizes business & human intent into validated requirement contracts and bounded scope.
+
+export const definition = {
+  id: 'product-manager',
+  title: 'Product Manager',
+  formerName: 'mission_compiler',
+  category: 'product',
+  description: 'Compiles initial product briefs, synthesizes user intent into formal requirements, constraints, and scope boundaries.',
+  requiredCapabilities: ['chat'],
+  readOnly: false,
+  allowedOutputPrefixes: ['docs/', 'reports/', 'requirements/'],
+};
+
+export function buildPrompt(params = {}) {
+  const { intent = '', constraints = [], scopeHint = [] } = params;
+  return `You are acting as a Staff Product Manager.
+Analyze the human intent and produce a crisp, canonical requirements contract.
+
+Input Intent:
+${intent}
+
+Constraints:
+${constraints.map((c) => `- ${c}`).join('\n') || '- None provided'}
+
+Scope Hint:
+${scopeHint.map((s) => `- ${s}`).join('\n') || '- None provided'}
+
+Output Requirements:
+Return a structured JSON object with the following fields:
+{
+  "objective": "A single concise statement of the primary goal",
+  "problem_statement": "Detailed description of the issue or feature",
+  "scope": ["concrete in-scope item 1", "concrete in-scope item 2"],
+  "out_of_scope": ["explicitly excluded items"],
+  "constraints": ["technical, operational, or business boundaries"],
+  "success_criteria": ["measurable criterion 1", "measurable criterion 2"],
+  "risk_level": "LOW | MEDIUM | HIGH | CRITICAL"
+}`;
+}
+
+export function validateContract(data) {
+  if (!data || typeof data !== 'object') throw new Error('Contract must be an object');
+  if (!data.objective || typeof data.objective !== 'string') throw new Error('Missing or invalid "objective"');
+  if (!Array.isArray(data.scope)) throw new Error('"scope" must be an array');
+  if (!Array.isArray(data.success_criteria) || data.success_criteria.length === 0) {
+    throw new Error('"success_criteria" must be a non-empty array');
+  }
+  return true;
+}

package/src/roles/qaEngineer.js

@@ -0,0 +1,54 @@
+// Quality Assurance Engineer / Release Gate Lead (formerly critical_acceptance)
+// Verifies terminal operational criteria, test results, and issues definitive acceptance verdicts.
+
+export const definition = {
+  id: 'qa-engineer',
+  title: 'QA Engineer',
+  formerName: 'critical_acceptance',
+  category: 'quality',
+  description: 'Validates operational criteria, executes end-to-end acceptance gates, and certifies releases.',
+  requiredCapabilities: ['chat'],
+  readOnly: true,
+  allowedOutputPrefixes: ['reports/'],
+};
+
+export function buildPrompt(params = {}) {
+  const { criteria = [], testResults = {}, reviewVerdict = '' } = params;
+  return `You are acting as a Quality Assurance Lead and Release Acceptance Engineer.
+Perform the final acceptance evaluation against operational success criteria.
+
+Acceptance Criteria:
+${criteria.map((c) => `- ${c}`).join('\n')}
+
+Review Verdict:
+${reviewVerdict}
+
+Test Results:
+${JSON.stringify(testResults, null, 2)}
+
+Output Requirements:
+Return a structured JSON object with:
+{
+  "verdict": "APPROVED | REJECTED",
+  "criteria_results": [
+    {
+      "criterion": "Name of criterion",
+      "satisfied": true,
+      "evidence": "Observed test output or check"
+    }
+  ],
+  "open_risks": ["unresolved risks, if any"],
+  "release_readiness": "READY_FOR_PRODUCTION | BLOCKED"
+}`;
+}
+
+export function validateContract(data) {
+  if (!data || typeof data !== 'object') throw new Error('Contract must be an object');
+  if (!['APPROVED', 'REJECTED'].includes(data.verdict)) {
+    throw new Error('verdict must be APPROVED or REJECTED');
+  }
+  if (!Array.isArray(data.criteria_results)) {
+    throw new Error('"criteria_results" must be an array');
+  }
+  return true;
+}