@besales/ops-framework 0.1.0

package/bin/lib/check-context-utils.test.mjs

@@ -0,0 +1,497 @@
+import { describe, expect, it } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  analyzePlanQualityGates,
+  buildCheckerContextPack,
+  buildCheckContext,
+  classifyRisk,
+  computeTaskContextInputs,
+  determineOptimizationTier,
+  readRelevantPlaybookMetadata,
+  readRelevantPlaybooks,
+  riskRootWarnings,
+  selectRelevantPlaybookNames,
+  inspectComplexityPerformanceBudget,
+  inspectOptimizationStrategy,
+  inspectProductionRolloutGate,
+  inspectSourceSyncProviderGate,
+  inspectUiAcceptanceScenarios,
+  parseMarkdownSections,
+  requiresOptimizationStrategy,
+  validateExecutionEvidenceForPlan,
+} from './check-context-utils.mjs';
+
+describe('agent pipeline quality gates', () => {
+  it('requires use-case UI acceptance scenarios for UI-visible plans', () => {
+    const plan = [
+      '# Plan',
+      '',
+      '## Затронутые модули и файлы',
+      '',
+      '- `web/app/src/features/example/page.tsx`',
+      '',
+      '## План проверки',
+      '',
+      '- Open the page and confirm it renders.',
+    ].join('\n');
+
+    const result = analyzePlanQualityGates({
+      planContent: plan,
+      risk: {
+        riskProfile: 'medium',
+        riskTriggers: ['panel-ui', 'ui-visible-api'],
+      },
+    });
+
+    expect(result.uiRequired).toBe(true);
+    expect(result.uiAcceptance.present).toBe(false);
+    expect(result.missingSignals).toContain('UI-visible risk detected but `## UI Acceptance Scenarios` is missing or incomplete.');
+  });
+
+  it('accepts UI acceptance scenarios with intent, steps, expected visible result and must-catch regressions', () => {
+    const sections = parseMarkdownSections([
+      '# Plan',
+      '',
+      '## UI Acceptance Scenarios',
+      '',
+      '| ID | User intent | Setup/data | Steps | Expected visible result | Must catch |',
+      '| --- | --- | --- | --- | --- | --- |',
+      '| UI-001 | Compare modes | April data | Switch mode and expand row | Visible totals and child rows update | stale mode, missing child rows |',
+    ].join('\n'));
+
+    const result = inspectUiAcceptanceScenarios(sections);
+
+    expect(result.present).toBe(true);
+    expect(result.scenarioCount).toBe(1);
+    expect(result.hasMustCatch).toBe(true);
+  });
+
+  it('uses project-configured roots for UI and worker risk triggers', () => {
+    const risk = classifyRisk({
+      structuralLines: [
+        '- `web/app/src/page.tsx`',
+        '- `workers/backend/jobs/example.ts`',
+      ],
+      referencedFiles: [
+        'web/app/src/page.tsx',
+        'workers/backend/jobs/example.ts',
+      ],
+      planSections: new Map(),
+      riskConfig: {
+        uiRoots: ['web/app'],
+        workerRoots: ['workers/backend'],
+      },
+    });
+
+    expect(risk.riskTriggers).toContain('panel-ui');
+    expect(risk.riskTriggers).toContain('worker-queue');
+  });
+
+  it('warns when project risk roots are empty', () => {
+    expect(riskRootWarnings({ uiRoots: [], backendRoots: [], workerRoots: [] })).toEqual([
+      'risk.uiRoots is empty; path-based UI detection is disabled until the project config is filled.',
+      'risk.backendRoots is empty; path-based user-visible API detection is limited to text signals.',
+      'risk.workerRoots is empty; path-based worker detection is limited to text signals.',
+    ]);
+  });
+
+  it('requires complexity budget for hot-path triggers', () => {
+    const plan = [
+      '# Plan',
+      '',
+      '## Затронутые модули и файлы',
+      '',
+      '- `platform/backend-core/src/core/app/example/get-summary.use-case.ts`',
+    ].join('\n');
+
+    const result = analyzePlanQualityGates({
+      planContent: plan,
+      risk: {
+        riskProfile: 'high',
+        riskTriggers: ['dto-readmodel', 'materializer'],
+      },
+    });
+
+    expect(result.complexityRequired).toBe(true);
+    expect(result.complexityBudget.present).toBe(false);
+    expect(result.missingSignals).toContain('Complexity/performance risk detected but `## Complexity / Performance Budget` is missing or incomplete.');
+  });
+
+  it('accepts complexity budget with hot paths, data size, risks and budget', () => {
+    const sections = parseMarkdownSections([
+      '# Plan',
+      '',
+      '## Complexity / Performance Budget',
+      '',
+      '- Hot paths: summary read model and table render.',
+      '- Expected data size / row counts: 150k rows for April.',
+      '- Complexity risks: N+1 queries and nested scans.',
+      '- Planned mitigation: batch queries and map-based grouping.',
+      '- Budget / stop rule: API response < 3 seconds.',
+    ].join('\n'));
+
+    const result = inspectComplexityPerformanceBudget(sections);
+
+    expect(result.present).toBe(true);
+    expect(result.hasHotPaths).toBe(true);
+    expect(result.hasDataSize).toBe(true);
+    expect(result.hasRisks).toBe(true);
+    expect(result.hasBudget).toBe(true);
+  });
+
+  it('classifies optimization tiers from risk triggers', () => {
+    expect(determineOptimizationTier(['materializer'])).toBe('O3');
+    expect(determineOptimizationTier(['source-sync-provider'])).toBe('O3');
+    expect(determineOptimizationTier(['panel-ui'])).toBe('O2');
+    expect(determineOptimizationTier(['dto-readmodel'])).toBe('O2');
+    expect(determineOptimizationTier(['docs-only'])).toBe('O0');
+    expect(determineOptimizationTier([])).toBe('O0');
+    expect(requiresOptimizationStrategy('O1')).toBe(false);
+    expect(requiresOptimizationStrategy('O2')).toBe(true);
+    expect(requiresOptimizationStrategy('O3')).toBe(true);
+  });
+
+  it('requires optimization strategy for O2 and O3 plans', () => {
+    const result = analyzePlanQualityGates({
+      planContent: [
+        '# Plan',
+        '',
+        '## Complexity / Performance Budget',
+        '',
+        '- Hot paths: summary read model.',
+        '- Expected data size / row counts: 150k rows.',
+        '- Complexity risks: N+1 queries.',
+        '- Budget / stop rule: < 3 seconds.',
+      ].join('\n'),
+      risk: {
+        riskProfile: 'high',
+        riskTriggers: ['dto-readmodel'],
+      },
+    });
+
+    expect(result.optimizationTier).toBe('O2');
+    expect(result.optimizationRequired).toBe(true);
+    expect(result.optimizationStrategy.present).toBe(false);
+    expect(result.missingSignals).toContain('Optimization tier O2 detected but `## Optimization Strategy` is missing or incomplete.');
+  });
+
+  it('accepts optimization strategy with tier, hot paths, size, approach, anti-patterns and budget', () => {
+    const sections = parseMarkdownSections([
+      '# Plan',
+      '',
+      '## Optimization Strategy',
+      '',
+      '- Optimization tier: O3 measured review.',
+      '- Hot paths: worker materializer and summary read model.',
+      '- Expected data size / row counts: 150k rows.',
+      '- Chosen efficient approach: batch query, map-based grouping and indexed lookup.',
+      '- Anti-patterns avoided: N+1 queries, repeated scans and O(n^2) nested loops.',
+      '- Optimizer budget / stop rule: one focused review plus one timing measurement; defer speculative ideas.',
+    ].join('\n'));
+
+    const result = inspectOptimizationStrategy(sections);
+
+    expect(result.present).toBe(true);
+    expect(result.tier).toBe('O3');
+    expect(result.hasHotPaths).toBe(true);
+    expect(result.hasDataSize).toBe(true);
+    expect(result.hasApproach).toBe(true);
+    expect(result.hasAntiPatterns).toBe(true);
+    expect(result.hasBudget).toBe(true);
+  });
+
+  it('builds a checker context pack with exact quality-gate questions', () => {
+    const taskArtifacts = new Map([
+      ['status.md', '## Следующий шаг\n\nValidate Human Gate readiness.\n\n## Active slice\n\nSlice A.'],
+      ['plan.md', '## UI Acceptance Scenarios\n\n| ID | User intent | Setup/data | Steps | Expected visible result | Must catch |\n| --- | --- | --- | --- | --- | --- |\n| UI-001 | Inspect table | Data | Click | Row updates | stale rows |'],
+    ]);
+    const risk = {
+      riskProfile: 'high',
+      riskTriggers: ['panel-ui', 'dto-readmodel'],
+    };
+    const qualityGates = analyzePlanQualityGates({
+      planContent: taskArtifacts.get('plan.md'),
+      risk,
+    });
+
+    const pack = buildCheckerContextPack({
+      taskId: 'TASK-999-example',
+      risk,
+      qualityGates,
+      referencedFiles: ['web/app/src/features/example/page.tsx'],
+      structuralLines: ['- `web/app/src/features/example/page.tsx`'],
+      taskArtifacts,
+    });
+
+    expect(pack).toContain('## Checker Questions');
+    expect(pack).toContain('## Relevant Playbooks');
+    expect(pack).toContain('UI Acceptance (`ui-acceptance`)');
+    expect(pack).not.toContain('UI Acceptance Playbook');
+    expect(pack).toContain('Will the UI Acceptance Scenarios catch the concrete regressions a user would care about?');
+    expect(pack).toContain('Does the plan avoid N+1 queries');
+  });
+
+  it('selects relevant playbooks from risk triggers and includes project overlays', () => {
+    const projectPlaybooksRoot = path.join(process.cwd(), 'ops', 'agent-pipeline', 'playbooks');
+    fs.mkdirSync(projectPlaybooksRoot, { recursive: true });
+    fs.writeFileSync(path.join(projectPlaybooksRoot, 'ui-acceptance.md'), '# Project UI Overlay\n\nProject route notes.\n');
+
+    expect(selectRelevantPlaybookNames(['panel-ui', 'production-runtime'])).toEqual([
+      'complexity-performance',
+      'production-rollout',
+      'ui-acceptance',
+    ]);
+
+    const playbooks = readRelevantPlaybooks(['panel-ui']);
+    const uiPlaybook = playbooks.find((playbook) => playbook.name === 'ui-acceptance');
+
+    expect(uiPlaybook.sharedContent).toContain('UI Acceptance Playbook');
+    expect(uiPlaybook.projectContent).toContain('Project UI Overlay');
+
+    const metadata = readRelevantPlaybookMetadata(['panel-ui']);
+    const uiMetadata = metadata.find((playbook) => playbook.name === 'ui-acceptance');
+    expect(uiMetadata.sharedSha).toMatch(/^sha256:/);
+    expect(uiMetadata.projectSha).toMatch(/^sha256:/);
+    expect(uiMetadata).not.toHaveProperty('sharedContent');
+    expect(uiMetadata).not.toHaveProperty('projectContent');
+  });
+
+  it('stores relevant playbook metadata, not full text, in check context', () => {
+    const taskDir = path.join(process.cwd(), 'ops', 'agent-pipeline', 'tasks', 'TASK-999-playbook-metadata');
+    fs.mkdirSync(taskDir, { recursive: true });
+    fs.writeFileSync(path.join(taskDir, 'brief.md'), '# Brief\n\nTest.\n');
+    fs.writeFileSync(path.join(taskDir, 'research.md'), '# Research\n\n## Findings\n\n- `web/app/src/page.tsx`\n');
+    fs.writeFileSync(path.join(taskDir, 'plan.md'), [
+      '# Plan',
+      '',
+      '## Затронутые модули и файлы',
+      '',
+      '- `web/app/src/page.tsx`',
+      '',
+      '## UI Acceptance Scenarios',
+      '',
+      '| ID | User intent | Setup/data | Steps | Expected visible result | Must catch |',
+      '| --- | --- | --- | --- | --- | --- |',
+      '| UI-001 | Inspect | Data | Open page | Visible page | blank page |',
+    ].join('\n'));
+    fs.writeFileSync(path.join(taskDir, 'status.md'), '# Status\n\n## Текущий этап\n\nplan\n');
+
+    const context = buildCheckContext({
+      taskId: 'TASK-999-playbook-metadata',
+      inputs: computeTaskContextInputs(taskDir),
+      createdAt: null,
+    });
+    const serialized = JSON.stringify(context);
+
+    expect(context.relevantPlaybooks[0]).toHaveProperty('sharedSha');
+    expect(context.relevantPlaybooks[0]).not.toHaveProperty('sharedContent');
+    expect(serialized).not.toContain('UI Acceptance Playbook');
+  });
+
+  it('pre-verify evidence gate blocks missing UI and complexity evidence', () => {
+    const plan = [
+      '# Plan',
+      '',
+      '## UI Acceptance Scenarios',
+      '',
+      '| ID | User intent | Setup/data | Steps | Expected visible result | Must catch |',
+      '| --- | --- | --- | --- | --- | --- |',
+      '| UI-001 | Inspect table | Data | Click | Row updates | stale rows |',
+      '',
+      '## Complexity / Performance Budget',
+      '',
+      '- Hot paths: summary read model.',
+      '- Expected data size / row counts: 150k rows.',
+      '- Complexity risks: N+1 queries.',
+      '- Budget / stop rule: < 3 seconds.',
+    ].join('\n');
+    const execution = [
+      '# Execution',
+      '',
+      '## Краткое summary',
+      '',
+      'Implemented.',
+    ].join('\n');
+
+    const issues = validateExecutionEvidenceForPlan({
+      planContent: plan,
+      executionContent: execution,
+    });
+
+    expect(issues).toEqual([
+      {
+        category: 'ui_verification_gap',
+        message: 'Plan contains UI Acceptance Scenarios but execution.md is missing UI Acceptance Evidence.',
+      },
+      {
+        category: 'unrun_required_check',
+        message: 'Plan contains Complexity / Performance Budget but execution.md is missing Complexity / Performance Evidence.',
+      },
+    ]);
+  });
+
+  it('pre-verify evidence gate accepts scenario and performance evidence', () => {
+    const plan = [
+      '# Plan',
+      '',
+      '## UI Acceptance Scenarios',
+      '',
+      '| ID | User intent | Setup/data | Steps | Expected visible result | Must catch |',
+      '| --- | --- | --- | --- | --- | --- |',
+      '| UI-001 | Inspect table | Data | Click | Row updates | stale rows |',
+      '',
+      '## Complexity / Performance Budget',
+      '',
+      '- Hot paths: summary read model.',
+      '- Expected data size / row counts: 150k rows.',
+      '- Complexity risks: N+1 queries.',
+      '- Budget / stop rule: < 3 seconds.',
+    ].join('\n');
+    const execution = [
+      '# Execution',
+      '',
+      '## UI Acceptance Evidence',
+      '',
+      '| Scenario ID | Result | Observed evidence / screenshot / payload | Notes |',
+      '| --- | --- | --- | --- |',
+      '| UI-001 | pass | observed visible updated row, screenshot `/tmp/ui.png` | ok |',
+      '',
+      '## Complexity / Performance Evidence',
+      '',
+      '| Hot path / budget | Result | Timing / rows / EXPLAIN / N+1 evidence | Notes |',
+      '| --- | --- | --- | --- |',
+      '| summary read model < 3s | pass | duration 1200ms, rows 150000, no N+1 | ok |',
+    ].join('\n');
+
+    const issues = validateExecutionEvidenceForPlan({
+      planContent: plan,
+      executionContent: execution,
+    });
+
+    expect(issues).toEqual([]);
+  });
+
+  it('pre-verify evidence gate blocks missing optimization evidence for O2 and O3 plans', () => {
+    const plan = [
+      '# Plan',
+      '',
+      '## Optimization Strategy',
+      '',
+      '- Optimization tier: O2 focused review.',
+      '- Hot paths: dashboard read model.',
+      '- Expected data size / row counts: 25k rows.',
+      '- Chosen efficient approach: map-based grouping and indexed lookup.',
+      '- Anti-patterns avoided: N+1 queries and repeated scans.',
+      '- Optimizer budget / stop rule: one focused review; defer speculative ideas.',
+    ].join('\n');
+    const execution = '# Execution\n\nImplemented.';
+
+    const issues = validateExecutionEvidenceForPlan({
+      planContent: plan,
+      executionContent: execution,
+    });
+
+    expect(issues).toEqual([
+      {
+        category: 'unrun_required_check',
+        message: 'Plan contains O2/O3 Optimization Strategy but execution.md is missing Optimization Review Evidence.',
+      },
+    ]);
+  });
+
+  it('pre-verify evidence gate accepts optimization review evidence', () => {
+    const plan = [
+      '# Plan',
+      '',
+      '## Optimization Strategy',
+      '',
+      '- Optimization tier: O3 measured review.',
+      '- Hot paths: materializer.',
+      '- Expected data size / row counts: 150k rows.',
+      '- Chosen efficient approach: batch query and map-based grouping.',
+      '- Anti-patterns avoided: N+1 queries and O(n^2) nested loops.',
+      '- Optimizer budget / stop rule: one focused review plus one benchmark; defer speculative ideas.',
+    ].join('\n');
+    const execution = [
+      '# Execution',
+      '',
+      '## Optimization Review Evidence',
+      '',
+      '| Hot path | Review result | Measurement / finding | Notes |',
+      '| --- | --- | --- | --- |',
+      '| materializer | pass | reviewed for N+1 and repeated scan; benchmark 1200ms / 150000 rows | no obvious hotspot |',
+    ].join('\n');
+
+    const issues = validateExecutionEvidenceForPlan({
+      planContent: plan,
+      executionContent: execution,
+    });
+
+    expect(issues).toEqual([]);
+  });
+
+  it('requires production rollout gate for production runtime triggers', () => {
+    const result = analyzePlanQualityGates({
+      planContent: '# Plan\n\n## Затронутые модули и файлы\n\n- deploy runtime env variable for worker',
+      risk: {
+        riskProfile: 'high',
+        riskTriggers: ['production-runtime'],
+      },
+    });
+
+    expect(result.productionRolloutRequired).toBe(true);
+    expect(result.productionRollout.present).toBe(false);
+    expect(result.missingSignals).toContain('Production rollout risk detected but `## Production Rollout Gate` is missing or incomplete.');
+  });
+
+  it('accepts production rollout gate with impact env rollback and post-deploy evidence', () => {
+    const sections = parseMarkdownSections([
+      '# Plan',
+      '',
+      '## Production Rollout Gate',
+      '',
+      '- Impact / blast radius: one worker queue.',
+      '- Environment / deploy variables: RAILWAY env flag.',
+      '- Rollback / disable path: revert env flag and redeploy.',
+      '- Post-deploy evidence: logs, metrics and smoke.',
+    ].join('\n'));
+
+    const result = inspectProductionRolloutGate(sections);
+
+    expect(result.present).toBe(true);
+    expect(result.hasRollback).toBe(true);
+  });
+
+  it('requires source sync provider gate for source sync triggers', () => {
+    const result = analyzePlanQualityGates({
+      planContent: '# Plan\n\n## Затронутые модули и файлы\n\n- source sync worker retry and raw records',
+      risk: {
+        riskProfile: 'high',
+        riskTriggers: ['source-sync-provider'],
+      },
+    });
+
+    expect(result.sourceSyncProviderRequired).toBe(true);
+    expect(result.sourceSyncProvider.present).toBe(false);
+    expect(result.missingSignals).toContain('Source sync/provider risk detected but `## Source Sync / Provider Gate` is missing or incomplete.');
+  });
+
+  it('accepts source sync provider gate with scope idempotency failure handling and coverage', () => {
+    const sections = parseMarkdownSections([
+      '# Plan',
+      '',
+      '## Source Sync / Provider Gate',
+      '',
+      '- Scope / provider window: GetCourse stream for May, paginated by window.',
+      '- Idempotency / duplicate handling: idempotency key and dedupe on retry.',
+      '- Failure handling / retry boundaries: backoff, timeout and partial failure resume.',
+      '- Coverage / parity evidence: count audit and raw record samples.',
+    ].join('\n'));
+
+    const result = inspectSourceSyncProviderGate(sections);
+
+    expect(result.present).toBe(true);
+    expect(result.hasCoverageEvidence).toBe(true);
+  });
+});

package/bin/lib/execution-ledger-utils.mjs

@@ -0,0 +1,162 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export function collectGitExecutionState({ repoRoot, taskDir }) {
+  const statusLines = runGitLines(repoRoot, ['status', '--short']);
+  const unstagedDiff = runGitLines(repoRoot, ['diff', '--name-only']);
+  const stagedDiff = runGitLines(repoRoot, ['diff', '--cached', '--name-only']);
+  const taskRelativePath = normalizePath(path.relative(repoRoot, taskDir));
+
+  const statusEntries = statusLines.map(parseGitStatusLine).filter(Boolean);
+  const changedFiles = mergeChangedFiles({
+    statusEntries,
+    unstagedDiff,
+    stagedDiff,
+    taskRelativePath,
+  });
+
+  return {
+    statusEntries,
+    changedFiles,
+    taskRelativePath,
+  };
+}
+
+export function buildExecutionLedger({
+  taskId,
+  taskDir,
+  repoRoot,
+  planSha,
+  executionSha,
+  createdAt = new Date().toISOString(),
+}) {
+  const git = collectGitExecutionState({ repoRoot, taskDir });
+  const taskArtifacts = listTaskArtifacts(taskDir);
+
+  return {
+    schemaVersion: 1,
+    taskId,
+    createdAt,
+    planSha,
+    executionSha,
+    git: {
+      taskRelativePath: git.taskRelativePath,
+      changedFiles: compactLedgerFiles(git.changedFiles),
+      unrelatedDirtyFiles: compactLedgerFiles(git.changedFiles.filter((file) => !file.isTaskArtifact && !file.isOpsFrameworkFile)),
+    },
+    taskArtifacts,
+    notes: [
+      'This ledger is generated from git status/diff and task artifact presence.',
+      'Executor must still summarize semantic intent in execution.md.',
+    ],
+  };
+}
+
+function compactLedgerFiles(files) {
+  return files.map((file) => ({
+    path: file.path,
+    status: file.status,
+    isTaskArtifact: file.isTaskArtifact,
+    isOpsFrameworkFile: file.isOpsFrameworkFile,
+  }));
+}
+
+export function parseGitStatusLine(line) {
+  if (!line || line.length < 4) {
+    return null;
+  }
+  const status = line.slice(0, 2);
+  const rawPath = line.slice(3).trim();
+  if (!rawPath) {
+    return null;
+  }
+  const renameParts = rawPath.split(' -> ');
+  const filePath = normalizePath(renameParts.at(-1));
+  return {
+    status,
+    path: filePath,
+    originalPath: renameParts.length > 1 ? normalizePath(renameParts[0]) : null,
+  };
+}
+
+export function mergeChangedFiles({
+  statusEntries,
+  unstagedDiff,
+  stagedDiff,
+  taskRelativePath,
+}) {
+  const byPath = new Map();
+  for (const entry of statusEntries) {
+    byPath.set(entry.path, {
+      path: entry.path,
+      status: entry.status,
+      staged: stagedDiff.includes(entry.path) || entry.status[0] !== ' ' && entry.status[0] !== '?',
+      unstaged: unstagedDiff.includes(entry.path) || entry.status[1] !== ' ',
+      untracked: entry.status === '??',
+      originalPath: entry.originalPath,
+    });
+  }
+  for (const filePath of [...unstagedDiff, ...stagedDiff]) {
+    const normalizedPath = normalizePath(filePath);
+    const existing = byPath.get(normalizedPath) || {
+      path: normalizedPath,
+      status: '',
+      staged: false,
+      unstaged: false,
+      untracked: false,
+      originalPath: null,
+    };
+    existing.staged = existing.staged || stagedDiff.includes(filePath);
+    existing.unstaged = existing.unstaged || unstagedDiff.includes(filePath);
+    byPath.set(normalizedPath, existing);
+  }
+
+  return Array.from(byPath.values())
+    .map((entry) => ({
+      ...entry,
+      isTaskArtifact: entry.path === taskRelativePath || entry.path.startsWith(`${taskRelativePath}/`),
+      isOpsFrameworkFile: isFrameworkOwnedPath(entry.path)
+        && !(entry.path === taskRelativePath || entry.path.startsWith(`${taskRelativePath}/`)),
+    }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function isFrameworkOwnedPath(filePath) {
+  return filePath.startsWith('shared-platform/packages/ops-framework/')
+    || filePath.startsWith('ops/agent-pipeline/bin/')
+    || filePath.startsWith('ops/agent-pipeline/config/')
+    || filePath.startsWith('ops/agent-pipeline/prompts/')
+    || filePath.startsWith('ops/agent-pipeline/templates/')
+    || filePath === 'ops/agent-pipeline/README.md'
+    || filePath === 'ops/agent-pipeline/vitest.config.ts';
+}
+
+function listTaskArtifacts(taskDir) {
+  if (!fs.existsSync(taskDir)) {
+    return [];
+  }
+  return fs.readdirSync(taskDir)
+    .filter((fileName) => fs.statSync(path.join(taskDir, fileName)).isFile())
+    .sort()
+    .map((fileName) => ({
+      fileName,
+      sizeBytes: fs.statSync(path.join(taskDir, fileName)).size,
+    }));
+}
+
+function runGitLines(repoRoot, args) {
+  const result = spawnSync('git', args, {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+  if (result.status !== 0) {
+    const detail = `${result.stdout || ''}${result.stderr || ''}`.trim();
+    throw new Error(`git ${args.join(' ')} failed: ${detail}`);
+  }
+  return result.stdout.split('\n').map((line) => line.trimEnd()).filter(Boolean);
+}
+
+function normalizePath(value) {
+  return value.split(path.sep).join('/');
+}