@esquadrao/cli 0.0.0-stage → 1.6.0

package/src/roles/securityEngineer.js

@@ -0,0 +1,53 @@
+// Application Security Engineer (formerly spec_critic)
+// Adversarial security reviews, threat modeling, attack surface analysis, and edge case identification.
+
+export const definition = {
+  id: 'security-engineer',
+  title: 'Security Engineer',
+  formerName: 'spec_critic',
+  category: 'security',
+  description: 'Conducts adversarial audits, threat modeling, vulnerability assessments, and boundary validation.',
+  requiredCapabilities: ['chat'],
+  readOnly: true,
+  allowedOutputPrefixes: ['reports/'],
+};
+
+export function buildPrompt(params = {}) {
+  const { implementationContract = {}, architecture = '' } = params;
+  return `You are acting as an Application Security Engineer.
+Perform an adversarial security review of the technical design and contract. Search for trust boundary violations, injection vectors, authorization bypasses, and data-loss edge cases.
+
+Architecture / Contract:
+${JSON.stringify(implementationContract, null, 2)}
+${architecture}
+
+Output Requirements:
+Return a structured JSON object with:
+{
+  "verdict": "PASS | REVISE | BLOCK",
+  "findings": [
+    {
+      "severity": "INFO | MINOR | MAJOR | BLOCKER",
+      "category": "AUTH | INJECTION | DATA_LOSS | PRIVACY | RESOURCE_EXHAUSTION | EDGE_CASE",
+      "description": "Clear explanation of the risk",
+      "remediation": "Concrete action required to mitigate"
+    }
+  ],
+  "threat_model_summary": "Concise summary of evaluated attack vectors",
+  "recommended_mitigations": ["mitigation 1", "mitigation 2"]
+}`;
+}
+
+export function validateContract(data) {
+  if (!data || typeof data !== 'object') throw new Error('Contract must be an object');
+  if (!['PASS', 'REVISE', 'BLOCK'].includes(data.verdict)) {
+    throw new Error('verdict must be PASS, REVISE, or BLOCK');
+  }
+  if (!Array.isArray(data.findings)) throw new Error('"findings" must be an array');
+  for (const f of data.findings) {
+    if (!['INFO', 'MINOR', 'MAJOR', 'BLOCKER'].includes(f.severity)) {
+      throw new Error(`Invalid finding severity: ${f.severity}`);
+    }
+  }
+  return true;
+}

package/src/roles/softwareArchitect.js

@@ -0,0 +1,58 @@
+// Principal Software Architect (formerly chief_architect)
+// Strategic decomposition, interface contract synthesis, invariant definitions, and rollback criteria.
+
+export const definition = {
+  id: 'software-architect',
+  title: 'Principal Software Architect',
+  formerName: 'chief_architect',
+  category: 'architecture',
+  description: 'Decomposes complex systems, defines strict interface boundaries, establishes invariants, and authors implementation contracts.',
+  requiredCapabilities: ['chat', 'reasoning'],
+  readOnly: false,
+  allowedOutputPrefixes: ['docs/', 'reports/', 'schemas/'],
+};
+
+export function buildPrompt(params = {}) {
+  const { objective = '', requirements = {}, repoSummary = '', allowedCandidates = [] } = params;
+  return `You are acting as a Principal Software Architect.
+Synthesize an authoritative implementation contract with strict invariants and rollback criteria.
+
+Objective:
+${objective}
+
+Requirements & Constraints:
+${JSON.stringify(requirements, null, 2)}
+
+Codebase Context:
+${repoSummary}
+
+Candidate Files for Modification:
+${allowedCandidates.map((c) => `- ${c}`).join('\n') || '- None specified'}
+
+Output Requirements:
+Return a structured JSON object with:
+{
+  "architecture": "High-level technical solution design",
+  "decisions": [
+    {"decision": "choice made", "rationale": "why this choice was made"}
+  ],
+  "allowed_changes": ["concrete file paths authorized for modification, NO GLOBS"],
+  "forbidden_changes": ["files or paths strictly protected from modification"],
+  "invariants": ["system invariants that must not be broken"],
+  "rollback_conditions": ["observable failure states that trigger immediate abort/revert"],
+  "implementation_sequence": ["step 1", "step 2", "step 3"]
+}`;
+}
+
+export function validateContract(data) {
+  if (!data || typeof data !== 'object') throw new Error('Contract must be an object');
+  if (!data.architecture || typeof data.architecture !== 'string') throw new Error('Missing "architecture"');
+  if (!Array.isArray(data.allowed_changes)) throw new Error('"allowed_changes" must be an array');
+  if (!Array.isArray(data.invariants) || data.invariants.length === 0) {
+    throw new Error('"invariants" must be a non-empty array');
+  }
+  if (!Array.isArray(data.rollback_conditions) || data.rollback_conditions.length === 0) {
+    throw new Error('"rollback_conditions" must be a non-empty array');
+  }
+  return true;
+}

package/src/roles/softwareEngineer.js

@@ -0,0 +1,76 @@
+// Senior Software Engineer (formerly implementer)
+// Generates production-grade atomic code patches, unit tests, and minimal working diffs.
+
+export const definition = {
+  id: 'software-engineer',
+  title: 'Senior Software Engineer',
+  formerName: 'implementer',
+  category: 'engineering',
+  description: 'Implements production code within strictly authorized scope, authors focused unit tests, and delivers clean atomic patches.',
+  requiredCapabilities: ['chat', 'tool_calling'],
+  readOnly: false,
+  allowedOutputPrefixes: ['*'],
+};
+
+export function buildPrompt(params = {}) {
+  const {
+    objective = '',
+    allowedChanges = [],
+    forbiddenChanges = [],
+    invariants = [],
+    existingContext = '',
+  } = params;
+
+  return `You are acting as a Senior Software Engineer.
+Implement the requested feature or fix within the authorized scope.
+Follow the "laziness" principle: minimal working diff, native stdlib first, zero unrequested dependencies.
+
+Objective:
+${objective}
+
+Authorized Files (allowed_changes):
+${allowedChanges.map((f) => `- ${f}`).join('\n')}
+
+Forbidden Files (do NOT touch):
+${forbiddenChanges.map((f) => `- ${f}`).join('\n') || '- None'}
+
+Invariants to Preserve:
+${invariants.map((i) => `- ${i}`).join('\n')}
+
+Relevant Existing Code Context:
+${existingContext}
+
+Output Requirements:
+Your code deliverables must be provided in clean FILE blocks in the following format:
+FILE: path/to/file.ext
+\`\`\`
+// file content
+\`\`\`
+
+Rules:
+1. Every modified or created file must have its full content inside a FILE block.
+2. Touch ONLY files listed in Authorized Files.
+3. Include at least one runnable test verifying the core logic.
+4. Do not include speculative boilerplate or unused abstractions.`;
+}
+
+export function parseFileBlocks(text = '') {
+  const fileRegex = /FILE:\s*([^\r\n]+)\r?\n```[^\r\n]*\r?\n([\s\S]*?)```/g;
+  const files = [];
+  let match;
+  while ((match = fileRegex.exec(text)) !== null) {
+    files.push({
+      path: match[1].trim(),
+      content: match[2],
+    });
+  }
+  return files;
+}
+
+export function validateContract(data) {
+  if (!data || typeof data !== 'object') throw new Error('Contract must be an object');
+  if (!Array.isArray(data.files_changed) && !Array.isArray(data.files)) {
+    throw new Error('Must provide files_changed or files list');
+  }
+  return true;
+}

package/src/roles/sreEngineer.js

@@ -0,0 +1,60 @@
+// Site Reliability Engineer / Debugging Specialist (formerly failure_diagnostician)
+// Root-cause analysis of test failures, stack traces, and deterministic fix-contract synthesis.
+
+export const definition = {
+  id: 'sre-engineer',
+  title: 'Site Reliability Engineer',
+  formerName: 'failure_diagnostician',
+  category: 'operations',
+  description: 'Performs deep root-cause analysis on failing test runs, runtime crashes, and synthesizes targeted fix contracts.',
+  requiredCapabilities: ['chat', 'reasoning'],
+  readOnly: false,
+  allowedOutputPrefixes: ['reports/'],
+};
+
+export function buildPrompt(params = {}) {
+  const { errorLog = '', failureHistory = [], testFile = '' } = params;
+  return `You are acting as a Site Reliability Engineer and Debugging Specialist.
+Analyze the test failure, error logs, and execution traces to produce an immutable Root Cause Analysis and Fix Contract.
+
+Failing Test:
+${testFile || 'Unknown'}
+
+Error Logs:
+\`\`\`
+${errorLog}
+\`\`\`
+
+Failure History:
+${JSON.stringify(failureHistory, null, 2)}
+
+Output Requirements:
+Return a structured JSON object with:
+{
+  "root_cause_analysis": {
+    "summary": "Precise mechanical explanation of why the failure occurred",
+    "failing_symbol_or_line": "function, line, or invariant that broke",
+    "flaw_category": "BOUNDARY_CONDITION | CONCURRENCY | REGRESSION | TYPE_ERROR | NETWORK | TIMEOUT",
+    "revised_assumptions": ["incorrect assumption previously held"]
+  },
+  "fix_contract": {
+    "targeted_files": ["exact file paths that must be fixed"],
+    "required_invariants": ["invariants that the fix must uphold"],
+    "regression_test_strategy": "description of unit test to prevent recurrence"
+  }
+}`;
+}
+
+export function validateContract(data) {
+  if (!data || typeof data !== 'object') throw new Error('Contract must be an object');
+  if (!data.root_cause_analysis || typeof data.root_cause_analysis !== 'object') {
+    throw new Error('Missing root_cause_analysis object');
+  }
+  if (!data.fix_contract || typeof data.fix_contract !== 'object') {
+    throw new Error('Missing fix_contract object');
+  }
+  if (!Array.isArray(data.fix_contract.targeted_files) || data.fix_contract.targeted_files.length === 0) {
+    throw new Error('fix_contract.targeted_files must be a non-empty array');
+  }
+  return true;
+}

package/src/roles/systemAnalyst.js

@@ -0,0 +1,45 @@
+// Systems Analyst / Codebase Navigator (formerly cartographer)
+// Maps repository structure, dependencies, entry points, and identifies affected modules.
+
+export const definition = {
+  id: 'system-analyst',
+  title: 'Systems Analyst',
+  formerName: 'cartographer',
+  category: 'engineering',
+  description: 'Navigates codebases, extracts module dependency graphs, maps architectural boundaries, and identifies touchpoints.',
+  requiredCapabilities: ['chat'],
+  readOnly: true,
+  allowedOutputPrefixes: ['reports/'],
+};
+
+export function buildPrompt(params = {}) {
+  const { files = [], objective = '' } = params;
+  return `You are acting as a Systems Analyst and Codebase Navigator.
+Perform read-only repository reconnaissance and map structural dependencies for the stated objective.
+
+Objective:
+${objective}
+
+Discovered File Tree (sample):
+${files.slice(0, 100).map((f) => `- ${f}`).join('\n')}
+
+Output Requirements:
+Return a structured JSON object with:
+{
+  "summary": "High-level summary of relevant codebase modules",
+  "entrypoints": ["main entrypoint files"],
+  "affected_components": ["components likely impacted"],
+  "dependency_graph": {
+    "moduleA": ["dependsOnB", "dependsOnC"]
+  },
+  "suggested_scope": ["concrete file paths to inspect or modify"]
+}`;
+}
+
+export function validateContract(data) {
+  if (!data || typeof data !== 'object') throw new Error('Contract must be an object');
+  if (!data.summary || typeof data.summary !== 'string') throw new Error('Missing or invalid "summary"');
+  if (!Array.isArray(data.entrypoints)) throw new Error('"entrypoints" must be an array');
+  if (!Array.isArray(data.suggested_scope)) throw new Error('"suggested_scope" must be an array');
+  return true;
+}

package/src/roles/techLead.js

@@ -0,0 +1,46 @@
+// Tech Lead / Architecture Arbiter (formerly architecture_adjudicator)
+// Arbitrates architectural disputes, evaluates technical trade-offs, and enforces engineering guidelines.
+
+export const definition = {
+  id: 'tech-lead',
+  title: 'Technical Lead',
+  formerName: 'architecture_adjudicator',
+  category: 'architecture',
+  description: 'Arbitrates architectural disagreements, evaluates trade-offs between competing proposals, and governs technical standards.',
+  requiredCapabilities: ['chat', 'reasoning'],
+  readOnly: false,
+  allowedOutputPrefixes: ['docs/', 'reports/'],
+};
+
+export function buildPrompt(params = {}) {
+  const { proposals = [], issue = '', constraints = [] } = params;
+  return `You are acting as the Technical Lead and Architecture Arbiter.
+Review the competing technical proposals, evaluate trade-offs against constraints, and make a binding adjudication.
+
+Dispute / Architecture Decision:
+${issue}
+
+Constraints:
+${constraints.map((c) => `- ${c}`).join('\n')}
+
+Proposals:
+${JSON.stringify(proposals, null, 2)}
+
+Output Requirements:
+Return a structured JSON object with:
+{
+  "verdict": "APPROVED_PROPOSAL_A | APPROVED_PROPOSAL_B | COMPROMISE | REJECTED",
+  "chosen_solution": "Summary of the accepted approach",
+  "rationale": "Clear technical justification citing simplicity, maintainability, and constraints",
+  "required_adjustments": ["mandatory modifications required before implementation"],
+  "technical_debt_impact": "LOW | MEDIUM | HIGH with explanation"
+}`;
+}
+
+export function validateContract(data) {
+  if (!data || typeof data !== 'object') throw new Error('Contract must be an object');
+  if (!data.verdict || typeof data.verdict !== 'string') throw new Error('Missing "verdict"');
+  if (!data.chosen_solution || typeof data.chosen_solution !== 'string') throw new Error('Missing "chosen_solution"');
+  if (!data.rationale || typeof data.rationale !== 'string') throw new Error('Missing "rationale"');
+  return true;
+}

package/src/roles/technicalWriter.js

@@ -0,0 +1,46 @@
+// Technical Writer (formerly documentation)
+// Authors developer documentation, API contracts, changelogs, and release summaries.
+
+export const definition = {
+  id: 'technical-writer',
+  title: 'Technical Writer',
+  formerName: 'documentation',
+  category: 'documentation',
+  description: 'Authors technical documentation, API specs, architectural decision records (ADRs), and user guides.',
+  requiredCapabilities: ['chat'],
+  readOnly: false,
+  allowedOutputPrefixes: ['docs/', 'README.md', 'CHANGELOG.md', 'reports/'],
+};
+
+export function buildPrompt(params = {}) {
+  const { changes = [], prTitle = '', architectureSummary = '' } = params;
+  return `You are acting as a Staff Technical Writer.
+Produce clear, accurate, and concise developer documentation reflecting the changes.
+
+Title / PR:
+${prTitle}
+
+Architecture Summary:
+${architectureSummary}
+
+Changes Delivered:
+${changes.map((c) => `- ${c}`).join('\n')}
+
+Output Requirements:
+Return a structured JSON object with:
+{
+  "summary": "Plain English summary of what was built and why",
+  "documentation_markdown": "Full markdown text for documentation or README updates",
+  "changelog_entry": "Markdown line formatted for CHANGELOG.md under Added/Changed/Fixed",
+  "affected_apis": ["list of endpoints, interfaces, or CLI flags updated"]
+}`;
+}
+
+export function validateContract(data) {
+  if (!data || typeof data !== 'object') throw new Error('Contract must be an object');
+  if (!data.summary || typeof data.summary !== 'string') throw new Error('Missing "summary"');
+  if (!data.documentation_markdown || typeof data.documentation_markdown !== 'string') {
+    throw new Error('Missing "documentation_markdown"');
+  }
+  return true;
+}