caucus 0.1.0__tar.gz

caucus-0.1.0/.github/codex/prompts/review.md

@@ -0,0 +1,48 @@
+You are reviewing a pull request for Caucus, an open-source Python framework for MCP-grounded multi-agent consensus with an auditable, hash-chained decision record.
+
+Prioritize concrete defects over style preferences:
+
+- broken installs, runtime errors, and CLI regressions
+- defects in decision-record integrity: hash chaining, append-only semantics, schema versioning
+- security issues, secret exposure, prompt-injection surfaces, unsafe dependency or workflow changes
+- logic bugs that would make deliberation, consensus, or the recorded dissent behave incorrectly
+- integration bugs across changed files, including CI sequencing and environment assumptions
+- missing tests or verification when the changed behavior is risky
+
+Use the repository diff, commit history, changed file context, and important repository context as the source of truth. Review the PR as a whole product change, not only as isolated syntax edits.
+Keep feedback concise, concrete, and actionable. Prefer human-style code review comments that explain the user-visible or operational impact.
+If there are no material issues, approve the PR, say that clearly, and mention any residual test or deployment risk.
+
+Additional guidance to reduce false positives:
+
+- Use the "Commit History (newest first)" section to understand the PR's evolution. If an issue introduced in an early commit is already resolved by a later commit in the same PR, do NOT flag it as an open finding.
+- Use the "Quality Gate Output" section as ground truth for formatting, lint, and test failures. Do not speculate about failures that are absent from that output. Only flag a lint or test issue if it appears explicitly there.
+
+Decision guidance:
+
+- Use "request_changes" for blocker/high findings or any issue that should block merge.
+- Use "comment" for medium non-blocking findings or when you have useful risk notes without a blocking defect.
+- Use "approve" when no material findings remain after applying the configured threshold.
+
+Return JSON only. Do not wrap it in Markdown.
+
+Use this shape:
+{
+"summary": "One or two sentences describing the review result.",
+"decision": "approve" | "comment" | "request_changes",
+"findings": [
+{
+"severity": "blocker" | "high" | "medium" | "low" | "nit",
+"category": "logic" | "security" | "runtime" | "deploy" | "test" | "maintainability" | "style" | "info",
+"path": "relative/path/from/repo/root",
+"line": 123,
+"title": "Short issue title",
+"body": "Concrete explanation of the issue and what should change.",
+"confidence": 0.0,
+"suggested_fix": "Optional short fix guidance.",
+"should_block_merge": false
+}
+]
+}
+
+Only put a line number on a changed RIGHT-side line from the diff. If a finding is important but cannot be anchored to a changed line, still include it with the closest changed line and explain the anchor in the body.

caucus-0.1.0/.github/codex/review-config.json

@@ -0,0 +1,21 @@
+{
+  "minimumSeverity": "medium",
+  "blockingSeverities": ["blocker", "high"],
+  "enabledCategories": [
+    "logic",
+    "security",
+    "runtime",
+    "deploy",
+    "test",
+    "maintainability"
+  ],
+  "ignoredPaths": [
+    "**/*.png",
+    "**/*.jpg",
+    "**/*.gif",
+    "**/*.lock",
+    "uv.lock"
+  ],
+  "maxInlineComments": 20,
+  "summaryCommentMarker": "<!-- caucus-codex-review-summary -->"
+}

caucus-0.1.0/.github/codex/review-rules.md

@@ -0,0 +1,12 @@
+# Caucus Review Rules
+
+These rules tune automated Codex reviews. Keep them explicit and reviewable instead of relying on hidden memory.
+
+- Caucus's core promise is an auditable, tamper-evident decision record. Treat any defect in record integrity (hash chaining, append-only semantics, schema versioning) as blocking, even if the code otherwise works.
+- Prioritize prompt-injection surfaces: anywhere fetched or tool-provided text could be interpreted as instructions must be flagged.
+- Secrets never belong in tracked files; configuration goes in `config.yaml` (gitignored) or `.env`. Flag any hardcoded path, account identifier, or credential.
+- The project deliberately keeps dependencies minimal and storage boring (JSONL, SQLite, Markdown). Flag new dependencies or storage engines that are not clearly justified by the PR.
+- Treat style-only feedback as non-blocking unless it hides a concrete bug or maintainability risk.
+- For documentation-only diffs, avoid inline comments unless there is a real correctness, security, or workflow issue.
+- When a PR changes GitHub Actions, verify permissions, secret handling, trigger scope, and whether the workflow can run safely on same-repo PRs.
+- Do not block on speculative missing environment variables when CI passes. Mention residual configuration risk in the summary unless the diff proves a runtime failure or exposes a real secret.

caucus-0.1.0/.github/codex/scripts/build-review-prompt.mjs

@@ -0,0 +1,217 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+const baseRef = process.env.BASE_REF
+const headRef = process.env.HEAD_REF
+const prNumber = process.env.PR_NUMBER
+const reviewWorktree = process.env.REVIEW_WORKTREE || '.'
+const qualityOutputPath = process.env.QUALITY_OUTPUT || ''
+const output = process.argv[2] || 'codex-review-prompt.md'
+
+if (!baseRef || !headRef || !prNumber) {
+  throw new Error('BASE_REF, HEAD_REF, and PR_NUMBER are required.')
+}
+
+function git(args, options = {}) {
+  return execFileSync('git', ['-C', reviewWorktree, ...args], {
+    encoding: 'utf8',
+    maxBuffer: 20 * 1024 * 1024,
+    ...options,
+  }).trimEnd()
+}
+
+function readIfExists(filePath) {
+  return existsSync(filePath) ? readFileSync(filePath, 'utf8') : ''
+}
+
+function readTargetIfExists(filePath) {
+  const targetPath = path.join(reviewWorktree, filePath)
+  return existsSync(targetPath) ? readFileSync(targetPath, 'utf8') : ''
+}
+
+function truncate(value, maxChars) {
+  if (value.length <= maxChars) return value
+  return `${value.slice(0, maxChars)}\n...[truncated ${value.length - maxChars} chars]`
+}
+
+function parseChangedLines(diff) {
+  const result = new Map()
+  let currentFile = null
+  let newLine = 0
+
+  for (const line of diff.split('\n')) {
+    if (line.startsWith('+++ b/')) {
+      currentFile = line.slice('+++ b/'.length)
+      if (!result.has(currentFile)) result.set(currentFile, new Set())
+      continue
+    }
+
+    if (!currentFile) continue
+
+    const hunk = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/)
+    if (hunk) {
+      newLine = Number(hunk[1])
+      continue
+    }
+
+    if (line.startsWith('+') && !line.startsWith('+++')) {
+      result.get(currentFile).add(newLine)
+      newLine += 1
+    } else if (line.startsWith('-') && !line.startsWith('---')) {
+      continue
+    } else if (!line.startsWith('\\')) {
+      newLine += 1
+    }
+  }
+
+  return [...result.entries()]
+    .map(
+      ([file, lines]) =>
+        `${file}: ${[...lines].sort((a, b) => a - b).join(', ') || '(no added lines)'}`,
+    )
+    .join('\n')
+}
+
+const base = `origin/${baseRef}`
+const prompt = readIfExists('.github/codex/prompts/review.md')
+const config = readIfExists('.github/codex/review-config.json')
+const rules = readIfExists('.github/codex/review-rules.md')
+const diffStat = git(['diff', '--stat', `${base}...HEAD`])
+const diffNameOnly = git(['diff', '--name-only', `${base}...HEAD`])
+const diff = git(['diff', `${base}...HEAD`])
+const commitLog = git(['log', '--reverse', '--format=%h %s', `${base}..HEAD`])
+const commitDetails = git([
+  'log',
+  '--reverse',
+  '--stat',
+  '--format=commit %H%nAuthor: %an <%ae>%nSubject: %s%nBody:%n%b',
+  `${base}..HEAD`,
+])
+const repoFiles = git(['ls-files'])
+
+// Commit history newest-first with +/-line stats for multi-commit false-positive reduction.
+const commitHistoryNewestFirst = git([
+  'log',
+  '--format=## %h %s',
+  '--stat',
+  `${base}..HEAD`,
+])
+
+// Output of the real quality gates (ruff format/lint + pytest) run against the PR's
+// merged code — gives the model ground truth instead of guesses.
+const qualityOutput = qualityOutputPath
+  ? readIfExists(qualityOutputPath) || '(quality output file was empty)'
+  : '(quality checks were not run)'
+
+const contextFiles = [
+  'README.md',
+  'AGENT_SETUP.md',
+  'pyproject.toml',
+  '.github/workflows/ci.yml',
+  '.github/workflows/codex-review.yml',
+  '.github/codex/review-config.json',
+  '.github/codex/review-rules.md',
+].filter((file) => existsSync(path.join(reviewWorktree, file)))
+
+const changedFiles = diffNameOnly.split('\n').filter(Boolean)
+const changedFileContext = changedFiles
+  .filter((file) => existsSync(path.join(reviewWorktree, file)))
+  .slice(0, 30)
+  .map((file) => {
+    const body = truncate(readTargetIfExists(file), 12000)
+    return `### ${file}\n\n\`\`\`\n${body}\n\`\`\``
+  })
+  .join('\n\n')
+
+const staticContext = contextFiles
+  .map((file) => {
+    const body = truncate(readTargetIfExists(file), 8000)
+    return `### ${file}\n\n\`\`\`\n${body}\n\`\`\``
+  })
+  .join('\n\n')
+
+const finalPrompt = `# Review Instructions
+
+${prompt}
+
+# Review Configuration
+
+\`\`\`json
+${config}
+\`\`\`
+
+# Repository Review Rules
+
+${rules}
+
+# Pull Request Metadata
+
+- Base branch: ${baseRef}
+- Head branch: ${headRef}
+- PR number: ${prNumber}
+- Working directory: ${path.resolve('.')}
+- Review worktree: ${path.resolve(reviewWorktree)}
+
+# Commit History (newest first)
+
+Use this to understand the PR's evolution. If an early commit introduced an issue that a later commit already fixed, do NOT flag it as an open finding.
+
+\`\`\`
+${truncate(commitHistoryNewestFirst, 12000)}
+\`\`\`
+
+# Pull Request Commit History
+
+\`\`\`
+${truncate(commitLog, 12000)}
+\`\`\`
+
+# Pull Request Commit Details
+
+\`\`\`
+${truncate(commitDetails, 40000)}
+\`\`\`
+
+# Quality Gate Output
+
+This is the output of \`ruff format --check\`, \`ruff check\`, and \`pytest\` run against the PR's merged code. Use this as ground truth for formatting, lint, and test failures — do not speculate about issues that are absent from this output.
+
+\`\`\`
+${truncate(qualityOutput, 16000)}
+\`\`\`
+
+# Repository File List
+
+\`\`\`
+${truncate(repoFiles, 12000)}
+\`\`\`
+
+# Changed RIGHT-side Lines Eligible for Inline Comments
+
+\`\`\`
+${parseChangedLines(diff)}
+\`\`\`
+
+# Important Repository Context
+
+${staticContext || '(none)'}
+
+# Changed File Context
+
+${changedFileContext || '(none)'}
+
+# Diff Stat
+
+\`\`\`
+${diffStat}
+\`\`\`
+
+# Full Diff
+
+\`\`\`diff
+${truncate(diff, 120000)}
+\`\`\`
+`
+
+writeFileSync(output, finalPrompt)

caucus-0.1.0/.github/codex/scripts/normalize-review-output.mjs

@@ -0,0 +1,120 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+
+const input = process.argv[2] || 'codex-review.raw.md'
+const output = process.argv[3] || 'codex-review.json'
+const configPath = process.argv[4] || '.github/codex/review-config.json'
+
+const severityRank = {
+  nit: 0,
+  low: 1,
+  medium: 2,
+  high: 3,
+  blocker: 4,
+}
+
+function extractJson(text) {
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i)
+  if (fenced) {
+    return JSON.parse(fenced[1])
+  }
+
+  const start = text.indexOf('{')
+  if (start === -1)
+    throw new Error('Codex review output did not contain a JSON object.')
+
+  let depth = 0
+  let inString = false
+  let escaped = false
+
+  for (let index = start; index < text.length; index += 1) {
+    const char = text[index]
+
+    if (inString) {
+      if (escaped) {
+        escaped = false
+      } else if (char === '\\') {
+        escaped = true
+      } else if (char === '"') {
+        inString = false
+      }
+      continue
+    }
+
+    if (char === '"') inString = true
+    if (char === '{') depth += 1
+    if (char === '}') depth -= 1
+
+    if (depth === 0) {
+      return JSON.parse(text.slice(start, index + 1))
+    }
+  }
+
+  throw new Error('Codex review output had an unterminated JSON object.')
+}
+
+function matchesPattern(filePath, pattern) {
+  if (pattern.startsWith('**/*.')) {
+    return filePath.endsWith(pattern.slice(4))
+  }
+
+  if (pattern.startsWith('*.')) {
+    return filePath.endsWith(pattern.slice(1))
+  }
+
+  return filePath === pattern
+}
+
+const raw = readFileSync(input, 'utf8')
+const config = JSON.parse(readFileSync(configPath, 'utf8'))
+const parsed = extractJson(raw)
+const minimumRank = severityRank[config.minimumSeverity] ?? severityRank.medium
+const enabledCategories = new Set(config.enabledCategories || [])
+const ignoredPaths = config.ignoredPaths || []
+
+const findings = Array.isArray(parsed.findings) ? parsed.findings : []
+const normalizedFindings = findings
+  .map((finding) => ({
+    severity: String(finding.severity || 'medium').toLowerCase(),
+    category: String(finding.category || 'maintainability').toLowerCase(),
+    path: String(finding.path || ''),
+    line: Number(finding.line),
+    title: String(finding.title || 'Review finding').trim(),
+    body: String(finding.body || '').trim(),
+    confidence: Number.isFinite(Number(finding.confidence))
+      ? Number(finding.confidence)
+      : 0.5,
+    suggested_fix: finding.suggested_fix
+      ? String(finding.suggested_fix).trim()
+      : '',
+    should_block_merge: Boolean(finding.should_block_merge),
+  }))
+  .filter((finding) => severityRank[finding.severity] !== undefined)
+  .filter((finding) => severityRank[finding.severity] >= minimumRank)
+  .filter(
+    (finding) =>
+      !enabledCategories.size || enabledCategories.has(finding.category),
+  )
+  .filter(
+    (finding) =>
+      finding.path &&
+      !ignoredPaths.some((pattern) => matchesPattern(finding.path, pattern)),
+  )
+  .filter((finding) => finding.body)
+
+const hasBlocking = normalizedFindings.some(
+  (finding) =>
+    (config.blockingSeverities || []).includes(finding.severity) ||
+    finding.should_block_merge,
+)
+
+const report = {
+  summary: String(parsed.summary || '').trim() || 'Codex completed the review.',
+  decision: hasBlocking
+    ? 'request_changes'
+    : normalizedFindings.length
+      ? 'comment'
+      : 'approve',
+  findings: normalizedFindings,
+}
+
+writeFileSync(output, `${JSON.stringify(report, null, 2)}\n`)

caucus-0.1.0/.github/codex/scripts/post-review.cjs

@@ -0,0 +1,246 @@
+const fs = require('node:fs')
+
+const severityLabel = {
+  blocker: 'Blocker',
+  high: 'High',
+  medium: 'Medium',
+  low: 'Low',
+  nit: 'Nit',
+}
+
+function parseChangedLines(patch) {
+  const lines = new Set()
+  let newLine = 0
+
+  for (const line of (patch || '').split('\n')) {
+    const hunk = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/)
+    if (hunk) {
+      newLine = Number(hunk[1])
+      continue
+    }
+
+    if (line.startsWith('+') && !line.startsWith('+++')) {
+      lines.add(newLine)
+      newLine += 1
+    } else if (line.startsWith('-') && !line.startsWith('---')) {
+      continue
+    } else if (!line.startsWith('\\')) {
+      newLine += 1
+    }
+  }
+
+  return lines
+}
+
+function formatFinding(finding) {
+  const pieces = [
+    `**${severityLabel[finding.severity] || finding.severity} / ${finding.category}: ${finding.title}**`,
+    '',
+    finding.body,
+  ]
+
+  if (finding.suggested_fix) {
+    pieces.push('', `Suggested fix: ${finding.suggested_fix}`)
+  }
+
+  pieces.push('', `Confidence: ${Math.round(finding.confidence * 100)}%`)
+
+  return pieces.join('\n')
+}
+
+function normalizeDecision(report, shouldRequestChanges) {
+  if (shouldRequestChanges) return 'request_changes'
+  if (report.decision === 'approve' && !report.findings?.length)
+    return 'approve'
+  if (report.decision === 'request_changes') return 'request_changes'
+  return report.findings?.length ? 'comment' : 'approve'
+}
+
+function decisionLabel(decision) {
+  if (decision === 'request_changes') return '🛑 Request changes'
+  if (decision === 'approve') return '✅ Approved'
+  return '💬 Comment'
+}
+
+module.exports = async ({ github, context, core }) => {
+  const report = JSON.parse(fs.readFileSync('codex-review.json', 'utf8'))
+  const config = JSON.parse(
+    fs.readFileSync('.github/codex/review-config.json', 'utf8'),
+  )
+  const marker =
+    config.summaryCommentMarker || '<!-- siteally-codex-review-summary -->'
+  const pull = context.payload.pull_request
+
+  if (!pull) {
+    core.info('No pull_request payload found; skipping review post.')
+    return
+  }
+
+  const files = await github.paginate(github.rest.pulls.listFiles, {
+    owner: context.repo.owner,
+    repo: context.repo.repo,
+    pull_number: pull.number,
+    per_page: 100,
+  })
+
+  const changedLinesByPath = new Map(
+    files.map((file) => [file.filename, parseChangedLines(file.patch)]),
+  )
+
+  const inlineComments = []
+  const summaryOnlyFindings = []
+
+  const maxInlineComments = Number(config.maxInlineComments || 20)
+
+  for (const finding of report.findings || []) {
+    const changedLines = changedLinesByPath.get(finding.path)
+
+    if (
+      changedLines?.has(finding.line) &&
+      inlineComments.length < maxInlineComments
+    ) {
+      inlineComments.push({
+        path: finding.path,
+        line: finding.line,
+        side: 'RIGHT',
+        body: formatFinding(finding),
+      })
+    } else {
+      summaryOnlyFindings.push(finding)
+    }
+  }
+
+  const blockingSeverities = new Set(
+    config.blockingSeverities || ['blocker', 'high'],
+  )
+  const shouldRequestChanges = (report.findings || []).some(
+    (finding) =>
+      blockingSeverities.has(finding.severity) || finding.should_block_merge,
+  )
+  const decision = normalizeDecision(report, shouldRequestChanges)
+  // Non-blocking findings do not gate merges (the workflow files them as
+  // issues), so a 'comment' decision submits an APPROVE review: GitHub only
+  // supersedes a reviewer's earlier changes-requested review on approval or
+  // explicit dismissal, and a lingering COMMENT would leave reviewDecision
+  // stuck at CHANGES_REQUESTED forever even after every finding is fixed.
+  const reviewEvent =
+    decision === 'request_changes' ? 'REQUEST_CHANGES' : 'APPROVE'
+
+  let submittedReviewEvent = reviewEvent
+  let reviewFallbackNote = ''
+
+  try {
+    const reviewBody =
+      decision === 'comment'
+        ? `${report.summary}\n\nNon-blocking findings are posted inline and tracked as issues; approving per repository merge policy.`
+        : report.summary
+
+    const reviewPayload = {
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      pull_number: pull.number,
+      commit_id: pull.head.sha,
+      event: reviewEvent,
+      body: reviewBody,
+    }
+
+    if (inlineComments.length > 0) {
+      reviewPayload.comments = inlineComments
+    }
+
+    await github.rest.pulls.createReview(reviewPayload)
+  } catch (error) {
+    if (reviewEvent !== 'APPROVE') {
+      throw error
+    }
+
+    submittedReviewEvent = 'COMMENT'
+    reviewFallbackNote =
+      'GitHub did not allow this workflow to approve the PR. Enable repository workflow permission `Allow GitHub Actions to create and approve pull requests` if approvals should be posted by the bot.'
+    core.warning(reviewFallbackNote)
+
+    const fallbackPayload = {
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      pull_number: pull.number,
+      commit_id: pull.head.sha,
+      event: 'COMMENT',
+      body: `${report.summary}\n\n${reviewFallbackNote}`,
+    }
+
+    if (inlineComments.length > 0) {
+      fallbackPayload.comments = inlineComments
+    }
+
+    await github.rest.pulls.createReview(fallbackPayload)
+  }
+
+  const counts = (report.findings || []).reduce((acc, finding) => {
+    acc[finding.severity] = (acc[finding.severity] || 0) + 1
+    return acc
+  }, {})
+
+  const countText =
+    Object.entries(counts)
+      .map(([severity, count]) => `${severity}: ${count}`)
+      .join(', ') || 'none'
+
+  const summaryLines = [
+    marker,
+    '## 🤖 Codex Review Summary',
+    '',
+    report.summary,
+    '',
+    '| Item | Result |',
+    '| --- | --- |',
+    `| 🧭 Review event | **${decisionLabel(decision)}** |`,
+    `| 📬 Submitted as | **${decisionLabel(submittedReviewEvent.toLowerCase())}** |`,
+    `| 🔎 Findings after threshold filtering | ${countText} |`,
+    `| 💬 Inline comments posted | ${inlineComments.length} |`,
+  ]
+
+  if (reviewFallbackNote) {
+    summaryLines.push('', `⚠️ Note: ${reviewFallbackNote}`)
+  }
+
+  if (summaryOnlyFindings.length > 0) {
+    summaryLines.push('', '📌 Findings that could not be anchored inline:')
+    for (const finding of summaryOnlyFindings) {
+      summaryLines.push(
+        `- **${finding.severity}/${finding.category}** ${finding.path}:${finding.line || '?'} - ${finding.title}: ${finding.body}`,
+      )
+    }
+  }
+
+  if (!report.findings?.length) {
+    summaryLines.push('', '✅ No findings met the configured review threshold.')
+  }
+
+  const body = summaryLines.join('\n')
+  const comments = await github.paginate(github.rest.issues.listComments, {
+    owner: context.repo.owner,
+    repo: context.repo.repo,
+    issue_number: pull.number,
+    per_page: 100,
+  })
+
+  const existing = comments.find(
+    (comment) => comment.user?.type === 'Bot' && comment.body?.includes(marker),
+  )
+
+  if (existing) {
+    await github.rest.issues.updateComment({
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      comment_id: existing.id,
+      body,
+    })
+  } else {
+    await github.rest.issues.createComment({
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      issue_number: pull.number,
+      body,
+    })
+  }
+}

caucus-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## Summary
+
+-
+
+## Slice
+
+- Which vertical slice / roadmap item this advances:
+
+## Verification
+
+- How this was tested locally: