feat: GitHub Actions for review, guardrails, and orchestration

.devcontainer/devcontainer.json

@@ -1,4 +1,4 @@
 {
   "name": "agent-workflow",
   "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
   "remoteUser": "vscode",
@@ -6,7 +6,10 @@
     "source=${localEnv:HOME}/.claude,target=/home/vscode/.claude,type=bind,consistency=cached"
   ],
   "features": {
-    "ghcr.io/devcontainers/features/github-cli:1": {}
+    "ghcr.io/devcontainers/features/github-cli:1": {},
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "lts"
+    }
   },
   "postCreateCommand": "curl -fsSL https://claude.ai/install.sh | bash"
 }

.github/ISSUE_TEMPLATE/review-finding.yml

@@ -0,0 +1,46 @@
+name: Review Finding
+description: An issue found during automated or manual code review.
+title: ""
+labels: ["review-finding"]
+body:
+  - type: textarea
+    id: finding-description
+    attributes:
+      label: Finding description
+      description: Describe the problem found during review.
+      placeholder: Explain what is wrong and why it matters.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: severity
+    attributes:
+      label: Severity
+      description: How critical is this finding?
+      options:
+        - blocking
+        - should-fix
+        - suggestion
+    validations:
+      required: true
+
+  - type: textarea
+    id: affected-files
+    attributes:
+      label: Affected files
+      description: List the files and line numbers where the issue was found.
+      placeholder: |
+        - path/to/file1.ts:42
+        - path/to/file2.ts:15-23
+      render: markdown
+    validations:
+      required: true
+
+  - type: textarea
+    id: suggested-fix
+    attributes:
+      label: Suggested fix
+      description: How should this finding be addressed?
+      placeholder: Describe the recommended approach to fix this issue.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/task.yml

@@ -0,0 +1,60 @@
+name: Task
+description: A structured task created during planning. Scoped to be completable in a single agent session.
+title: ""
+labels: ["task"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What needs to be done and why.
+      placeholder: Describe the task in 1-3 sentences.
+    validations:
+      required: true
+
+  - type: textarea
+    id: files-to-modify
+    attributes:
+      label: Files to modify
+      description: List all files that should be created or changed for this task.
+      placeholder: |
+        - path/to/file1.ts
+        - path/to/file2.ts
+      render: markdown
+    validations:
+      required: true
+
+  - type: textarea
+    id: implementation-steps
+    attributes:
+      label: Implementation steps
+      description: Ordered steps to complete the task. Each step should be concrete and verifiable.
+      placeholder: |
+        1. First step
+        2. Second step
+        3. Third step
+      render: markdown
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: Acceptance criteria
+      description: Conditions that must be true for this task to be considered complete.
+      placeholder: |
+        - [ ] Criterion 1
+        - [ ] Criterion 2
+      render: markdown
+    validations:
+      required: true
+
+  - type: textarea
+    id: dependencies
+    attributes:
+      label: Dependencies
+      description: Other issues that must be completed before this task can start. Use issue references.
+      placeholder: |
+        Blocked by #XX, #YY
+    validations:
+      required: false

.github/agent-workflow/commitlint.config.js

@@ -0,0 +1,7 @@
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    // Enforce 72 char limit on subject line
+    'header-max-length': [2, 'always', 72],
+  }
+};

.github/agent-workflow/scripts/guardrail-api-surface.js

@@ -0,0 +1,172 @@
+const { hasNonStaleApproval } = require('./lib/approval.js');
+const { detectAPIChanges } = require('./lib/api-patterns.js');
+
+module.exports = async function({ github, context, core }) {
+  const owner = context.repo.owner;
+  const repo = context.repo.repo;
+  const prNumber = context.payload.pull_request.number;
+  const headSha = context.payload.pull_request.head.sha;
+  const checkName = 'guardrail/api-surface';
+  const configuredConclusion = process.env.CONCLUSION || 'action_required';
+
+  // Check for non-stale PR approval override
+  const reviews = await github.rest.pulls.listReviews({
+    owner,
+    repo,
+    pull_number: prNumber,
+  });
+  const hasValidApproval = hasNonStaleApproval(reviews.data, headSha);
+
+  if (hasValidApproval) {
+    await github.rest.checks.create({
+      owner,
+      repo,
+      head_sha: headSha,
+      name: checkName,
+      status: 'completed',
+      conclusion: 'neutral',
+      output: {
+        title: 'API surface check: approved by reviewer',
+        summary: 'A non-stale PR approval overrides this guardrail.',
+      },
+    });
+    return;
+  }
+
+  // Get PR files and scan for API surface changes
+  const files = await github.paginate(github.rest.pulls.listFiles, {
+    owner,
+    repo,
+    pull_number: prNumber,
+  });
+
+  // OpenAPI / Swagger file patterns
+  const openApiFilePatterns = [
+    /openapi\.(ya?ml|json)$/i,
+    /swagger\.(ya?ml|json)$/i,
+    /api-spec\.(ya?ml|json)$/i,
+  ];
+
+  const annotations = [];
+  let totalApiChanges = 0;
+
+  for (const file of files) {
+    // Skip removed files
+    if (file.status === 'removed') continue;
+
+    // Check if this is an OpenAPI/Swagger spec file
+    const isOpenApiFile = openApiFilePatterns.some((p) => p.test(file.filename));
+    if (isOpenApiFile) {
+      totalApiChanges++;
+      annotations.push({
+        path: file.filename,
+        start_line: 1,
+        end_line: 1,
+        annotation_level: 'warning',
+        message: `OpenAPI/Swagger spec file modified: ${file.filename}. API contract changes require careful review.`,
+      });
+      continue;
+    }
+
+    // Use API pattern detection from shared library
+    if (!file.patch) continue;
+
+    const apiChanges = detectAPIChanges(file.patch, file.filename);
+    if (apiChanges.length > 0) {
+      totalApiChanges += apiChanges.length;
+
+      // Parse patch for line numbers
+      const lines = file.patch.split('\n');
+      let currentLine = 0;
+      let changeIndex = 0;
+
+      for (const line of lines) {
+        // Track line numbers from hunk headers
+        const hunkMatch = line.match(/^@@\s+-\d+(?:,\d+)?\s+\+(\d+)(?:,\d+)?\s+@@/);
+        if (hunkMatch) {
+          currentLine = parseInt(hunkMatch[1], 10);
+          continue;
+        }
+
+        // Only look at added lines
+        if (line.startsWith('+') && !line.startsWith('+++')) {
+          if (changeIndex < apiChanges.length) {
+            annotations.push({
+              path: file.filename,
+              start_line: currentLine,
+              end_line: currentLine,
+              annotation_level: 'warning',
+              message: `API surface change: ${apiChanges[changeIndex]} - ${line.substring(1).trim()}`,
+            });
+            changeIndex++;
+          }
+        }
+
+        // Advance line counter for added and context lines
+        if (!line.startsWith('-')) {
+          currentLine++;
+        }
+      }
+    }
+  }
+
+  // Report results
+  if (totalApiChanges === 0) {
+    await github.rest.checks.create({
+      owner,
+      repo,
+      head_sha: headSha,
+      name: checkName,
+      status: 'completed',
+      conclusion: 'success',
+      output: {
+        title: 'API surface check: no changes detected',
+        summary: 'No API surface changes found in this PR.',
+      },
+    });
+  } else {
+    // GitHub API limits annotations to 50 per call
+    const batchSize = 50;
+    const batches = [];
+    for (let i = 0; i < annotations.length; i += batchSize) {
+      batches.push(annotations.slice(i, i + batchSize));
+    }
+
+    const summary = [
+      `Found ${totalApiChanges} API surface change(s) across the PR.`,
+      '',
+      'API surface changes have outsized downstream impact. Review these changes carefully.',
+      '',
+      'To override: approve the PR to signal these changes are intentional.',
+    ].join('\n');
+
+    // Create the check run with the first batch of annotations
+    const checkRun = await github.rest.checks.create({
+      owner,
+      repo,
+      head_sha: headSha,
+      name: checkName,
+      status: 'completed',
+      conclusion: configuredConclusion,
+      output: {
+        title: `API surface check: ${totalApiChanges} change(s) detected`,
+        summary,
+        annotations: batches[0] || [],
+      },
+    });
+
+    // If there are more annotations, update the check run with additional batches
+    for (let i = 1; i < batches.length; i++) {
+      await github.rest.checks.update({
+        owner,
+        repo,
+        check_run_id: checkRun.data.id,
+        output: {
+          title: `API surface check: ${totalApiChanges} change(s) detected`,
+          summary,
+          annotations: batches[i],
+        },
+      });
+    }
+  }
+};

.github/agent-workflow/scripts/guardrail-dependencies.js

@@ -0,0 +1,87 @@
+const { hasNonStaleApproval } = require('./lib/approval.js');
+const { isDependencyFile } = require('./lib/file-patterns.js');
+
+module.exports = async function({ github, context, core }) {
+  const CHECK_NAME = 'guardrail/dependency-changes';
+  const configuredConclusion = process.env.CONCLUSION || 'action_required';
+
+  // Check for non-stale approving PR review (override mechanism)
+  const { data: reviews } = await github.rest.pulls.listReviews({
+    owner: context.repo.owner,
+    repo: context.repo.repo,
+    pull_number: context.payload.pull_request.number
+  });
+
+  const lastCommitSha = context.payload.pull_request.head.sha;
+  const hasValidApproval = hasNonStaleApproval(reviews, lastCommitSha);
+
+  if (hasValidApproval) {
+    await github.rest.checks.create({
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      head_sha: context.sha,
+      name: CHECK_NAME,
+      status: 'completed',
+      conclusion: 'neutral',
+      output: {
+        title: 'Dependency changes: approved by reviewer',
+        summary: 'A non-stale PR approval overrides this guardrail check.'
+      }
+    });
+    return;
+  }
+
+  // Get PR changed files
+  const files = await github.paginate(
+    github.rest.pulls.listFiles,
+    {
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      pull_number: context.payload.pull_request.number,
+      per_page: 100
+    }
+  );
+
+  const changedDependencyFiles = files.filter(f => isDependencyFile(f.filename));
+
+  // No dependency files changed: success
+  if (changedDependencyFiles.length === 0) {
+    await github.rest.checks.create({
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      head_sha: context.sha,
+      name: CHECK_NAME,
+      status: 'completed',
+      conclusion: 'success',
+      output: {
+        title: 'Dependency changes: no dependency files modified',
+        summary: 'No dependency manifest or lock files were changed in this PR.'
+      }
+    });
+    return;
+  }
+
+  // Dependency files changed: requires human review
+  const fileList = changedDependencyFiles.map(f => '- `' + f.filename + '`').join('\n');
+  const annotations = changedDependencyFiles.map(f => ({
+    path: f.filename,
+    start_line: 1,
+    end_line: 1,
+    annotation_level: 'warning',
+    message: 'Dependency file modified. Human review required before merge.'
+  }));
+
+  await github.rest.checks.create({
+    owner: context.repo.owner,
+    repo: context.repo.repo,
+    head_sha: context.sha,
+    name: CHECK_NAME,
+    status: 'completed',
+    conclusion: configuredConclusion,
+    output: {
+      title: `Dependency changes: ${changedDependencyFiles.length} file(s) modified`,
+      summary: `Dependency files were modified and require human review before merge.\n\n**Changed dependency files:**\n${fileList}\n\n**To resolve:** A maintainer must submit an approving PR review. The approval must be on the current head commit (non-stale).`,
+      annotations: annotations
+    }
+  });
+};