@mknrt/autotests-overkill 1.1.0

package/docs/superpowers/plans/2026-04-19-autotests-overkill-v1.md

@@ -0,0 +1,600 @@
+# Autotests Ultimate Testing Overkill v1 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build a production-ready standalone Node.js platform that indexes `autotests2`, `caseplatform-web`, and CI artifacts, exposes normalized MCP tools for testing intelligence, and ships Codex-oriented skills/templates without mutating consumer repositories by default.
+
+**Architecture:** The repository will be a TypeScript Node.js workspace with a thin MCP server over focused domain services. Data flows through configurable connectors into a SQLite + FTS knowledge store plus JSON snapshots; each MCP tool is a small orchestration layer over reusable analyzers, not a monolithic “smart tool”. Skills and prompt templates sit on top of tool contracts, while integration docs and sample consumer config keep `autotests2` as a consumer, not a host.
+
+**Tech Stack:** Node.js, TypeScript, `@modelcontextprotocol/server`, `zod`, `better-sqlite3`, SQLite FTS5, `fast-glob`, `typescript`, `tsx`, `vitest`
+
+---
+
+## File Structure
+
+- `package.json`: scripts, dependency graph, local dev workflow
+- `tsconfig.json`: compiler settings for strict TypeScript output
+- `vitest.config.ts`: unit/integration test runner configuration
+- `src/config/`: consumer config schema, defaults, loader, path helpers
+- `src/contracts/`: normalized MCP output schema, tool input schemas, confidence/error model
+- `src/connectors/`: adapters for repo files, CI artifacts, ReportPortal metadata sources
+- `src/indexer/`: repo scanners, extractors, SQLite persistence, snapshot refresh pipeline
+- `src/knowledge/`: schema migrations, FTS queries, repositories, search primitives
+- `src/domain/`: bounded services for contracts, coverage, failures, diff impact, spec generation
+- `src/mcp/`: MCP server bootstrap and per-tool registration modules
+- `src/templates/`: blueprint builders, prompt stubs, skill-facing templates
+- `skills/`: Codex skill bundle for end-to-end workflows
+- `templates/`: human-readable prompt workflows and example requests
+- `docs/`: architecture, onboarding, operator cookbook, consumer integration guide
+- `tests/`: unit tests, fixture-backed integration tests, acceptance tests against real adjacent repos
+- `fixtures/`: captured test data and minimal snapshots for deterministic tests
+
+## Discovery Facts Locked In
+
+- `C:\gitrep\autotests-overkill` is not yet a git repository and currently contains only `PLAN.md`.
+- `C:\gitrep\autotests2` contains real Cypress specs, support commands, selectors, fixtures, `.codex/context.md`, `.codex/testing.md`, GitLab CI config, ReportPortal config, and local run artifacts under `cypress/reports`, `cypress/screenshots`, `cypress/videos`, and `cypress/logs`.
+- `C:\gitrep\caseplatform-web` contains real FormRunner and VCM widget sources. Example evidence target: `vcm/jqVCM/widget/caption/CaptionControl.ts`, `CaptionSingleton.ts`, and `CaptionHandlers.ts`.
+- Real coverage target exists in `autotests2`: `cypress/e2e/tests/formRunner/vcm/captions/caption.cy.js` and `captionInContainers.cy.js`.
+- Real CI summary input exists in `autotests2/cypress/reports/test-stats.json`, screenshots, videos, API capture JSON, and `.gitlab-ci/stage-collect-artifacts/artifacts.yml`.
+
+## Public Contracts To Implement
+
+- Consumer config file: `overkill.config.json`
+- MCP tool output envelope:
+
+```ts
+type NormalizedToolOutput = {
+  summary: string;
+  evidence: Array<{
+    type: 'file' | 'symbol' | 'test' | 'artifact' | 'report' | 'diff' | 'config';
+    label: string;
+    path?: string;
+    locator?: string;
+    snippet?: string;
+    metadata?: Record<string, unknown>;
+  }>;
+  recommended_actions: string[];
+  repo_paths: string[];
+  confidence: {
+    score: number;
+    level: 'low' | 'medium' | 'high';
+    rationale: string[];
+  };
+  warnings: string[];
+};
+```
+
+- Tool registration surface:
+  - `find_existing_test_assets`
+  - `find_test_area_context`
+  - `find_frontend_contract`
+  - `find_frontend_runtime_logic`
+  - `map_feature_to_existing_coverage`
+  - `analyze_test_gaps`
+  - `generate_spec_blueprint`
+  - `recommend_selector_strategy`
+  - `build_setup_teardown_plan`
+  - `analyze_diff_impact`
+  - `triage_failed_run`
+  - `build_rerun_scope`
+  - `summarize_ci_context`
+- Skill entrypoints:
+  - `overkill-generate-test`
+  - `overkill-find-gaps`
+  - `overkill-reuse-project-patterns`
+  - `overkill-generate-setup`
+  - `overkill-impact-analysis`
+  - `overkill-debug-failure`
+  - `overkill-review-test-draft`
+  - `overkill-onboard`
+  - `overkill-prompt-builder`
+
+### Task 1: Bootstrap Repository Foundations
+
+**Files:**
+- Create: `package.json`
+- Create: `tsconfig.json`
+- Create: `vitest.config.ts`
+- Create: `.gitignore`
+- Create: `src/index.ts`
+- Create: `src/config/consumerConfig.ts`
+- Create: `src/contracts/toolOutput.ts`
+- Create: `src/contracts/confidence.ts`
+- Create: `src/contracts/errors.ts`
+- Create: `docs/architecture/overview.md`
+- Test: `tests/config/consumerConfig.test.ts`
+
+- [ ] **Step 1: Write the failing config/schema test**
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { parseConsumerConfig } from '../../src/config/consumerConfig';
+
+describe('parseConsumerConfig', () => {
+  it('normalizes repo roots and artifact locations', () => {
+    const result = parseConsumerConfig({
+      repos: {
+        autotests2: '../autotests2',
+        caseplatformWeb: '../caseplatform-web',
+      },
+      ci: {
+        artifactsRoot: '../autotests2/cypress',
+      },
+    });
+
+    expect(result.repos.autotests2).toContain('autotests2');
+    expect(result.repos.caseplatformWeb).toContain('caseplatform-web');
+    expect(result.ci.artifactsRoot).toContain('cypress');
+  });
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `npm run test -- tests/config/consumerConfig.test.ts`
+Expected: FAIL because `parseConsumerConfig` does not exist yet.
+
+- [ ] **Step 3: Implement the minimal foundation**
+
+```ts
+export function parseConsumerConfig(input: ConsumerConfigInput): ConsumerConfig {
+  const parsed = consumerConfigSchema.parse(input);
+  return {
+    repos: {
+      autotests2: resolveRepoPath(parsed.repos.autotests2),
+      caseplatformWeb: resolveRepoPath(parsed.repos.caseplatformWeb),
+    },
+    ci: {
+      artifactsRoot: resolveRepoPath(parsed.ci.artifactsRoot),
+      reportPortal: parsed.ci.reportPortal ?? null,
+      gitlab: parsed.ci.gitlab ?? null,
+    },
+  };
+}
+```
+
+- [ ] **Step 4: Run the targeted test to verify it passes**
+
+Run: `npm run test -- tests/config/consumerConfig.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: Verify repository bootstrap**
+
+Run: `npm run build`
+Expected: TypeScript build succeeds and emits compiled output without errors.
+
+### Task 2: Build SQLite Knowledge Store And Snapshot Refresh
+
+**Files:**
+- Create: `src/knowledge/migrations.ts`
+- Create: `src/knowledge/database.ts`
+- Create: `src/knowledge/repositories.ts`
+- Create: `src/indexer/snapshotStore.ts`
+- Create: `src/indexer/refreshPipeline.ts`
+- Test: `tests/knowledge/database.test.ts`
+
+- [ ] **Step 1: Write the failing database test**
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { createKnowledgeDatabase } from '../../src/knowledge/database';
+
+describe('createKnowledgeDatabase', () => {
+  it('creates tables and fts indexes', () => {
+    const db = createKnowledgeDatabase(':memory:');
+    const tables = db.prepare(\"SELECT name FROM sqlite_master WHERE type='table'\").all();
+    expect(tables.map((row: { name: string }) => row.name)).toContain('documents_fts');
+  });
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `npm run test -- tests/knowledge/database.test.ts`
+Expected: FAIL because the database module is missing.
+
+- [ ] **Step 3: Implement the schema and migration runner**
+
+```ts
+db.exec(`
+  CREATE TABLE IF NOT EXISTS documents (
+    id TEXT PRIMARY KEY,
+    source_kind TEXT NOT NULL,
+    repo_kind TEXT NOT NULL,
+    path TEXT NOT NULL,
+    title TEXT NOT NULL,
+    body TEXT NOT NULL,
+    metadata_json TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  );
+  CREATE VIRTUAL TABLE IF NOT EXISTS documents_fts USING fts5(
+    id UNINDEXED,
+    path,
+    title,
+    body,
+    tokenize = 'porter unicode61'
+  );
+`);
+```
+
+- [ ] **Step 4: Run the targeted database test**
+
+Run: `npm run test -- tests/knowledge/database.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: Prove refresh writes snapshots without mutating consumer repos**
+
+Run: `npm run test -- tests/indexer/refreshPipeline.test.ts`
+Expected: PASS with snapshot files created only under this repository’s cache directory.
+
+### Task 3: Implement Source Connectors And Extractors For `autotests2` And `caseplatform-web`
+
+**Files:**
+- Create: `src/connectors/filesystemConnector.ts`
+- Create: `src/connectors/autotests2Connector.ts`
+- Create: `src/connectors/caseplatformConnector.ts`
+- Create: `src/indexer/extractors/testAssetExtractor.ts`
+- Create: `src/indexer/extractors/frontendContractExtractor.ts`
+- Create: `src/indexer/extractors/frontendRuntimeExtractor.ts`
+- Test: `tests/indexer/testAssetExtractor.test.ts`
+- Test: `tests/indexer/frontendContractExtractor.test.ts`
+
+- [ ] **Step 1: Write a failing extractor test for caption contracts**
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { extractFrontendContract } from '../../src/indexer/extractors/frontendContractExtractor';
+
+describe('extractFrontendContract', () => {
+  it('extracts properties, methods, and events from the caption widget', async () => {
+    const result = await extractFrontendContract({
+      root: 'C:/gitrep/caseplatform-web',
+      widgetHint: 'caption',
+    });
+
+    expect(result.properties).toContain('Label');
+    expect(result.methods).toContain('setLabel');
+    expect(result.events).toContain('on_click');
+  });
+});
+```
+
+- [ ] **Step 2: Run the contract extractor test**
+
+Run: `npm run test -- tests/indexer/frontendContractExtractor.test.ts`
+Expected: FAIL because the extractor is missing.
+
+- [ ] **Step 3: Implement file-system based extractors**
+
+```ts
+const controlFile = findFirstMatch([
+  `**/${widgetNamePascal}Control.ts`,
+  `**/${widgetNamePascal}Control.js`,
+]);
+const singletonFile = findFirstMatch([
+  `**/${widgetNamePascal}Singleton.ts`,
+  `**/${widgetNamePascal}Singleton.js`,
+]);
+const handlersFile = findFirstMatch([
+  `**/${widgetNamePascal}Handlers.ts`,
+  `**/${widgetNamePascal}Handlers.js`,
+]);
+```
+
+- [ ] **Step 4: Add failing reuse test for existing test assets**
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { extractTestAssets } from '../../src/indexer/extractors/testAssetExtractor';
+
+describe('extractTestAssets', () => {
+  it('finds caption specs and reusable commands', async () => {
+    const result = await extractTestAssets({
+      root: 'C:/gitrep/autotests2',
+      featureHint: 'caption',
+    });
+
+    expect(result.specs.some(spec => spec.path.includes('captions/caption.cy.js'))).toBe(true);
+    expect(result.commands.some(command => command.name.includes('getWidget'))).toBe(true);
+  });
+});
+```
+
+- [ ] **Step 5: Run both extractor suites**
+
+Run: `npm run test -- tests/indexer/frontendContractExtractor.test.ts tests/indexer/testAssetExtractor.test.ts`
+Expected: PASS
+
+### Task 4: Wave 1 MCP Tools And Skills
+
+**Files:**
+- Create: `src/domain/findExistingTestAssets.ts`
+- Create: `src/domain/findFrontendContract.ts`
+- Create: `src/domain/generateSpecBlueprint.ts`
+- Create: `src/mcp/server.ts`
+- Create: `src/mcp/registerTools.ts`
+- Create: `skills/overkill-generate-test/SKILL.md`
+- Create: `skills/overkill-reuse-project-patterns/SKILL.md`
+- Create: `templates/spec-blueprints/default.md`
+- Test: `tests/mcp/wave1Tools.test.ts`
+
+- [ ] **Step 1: Write the failing MCP tool contract test**
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { findFrontendContract } from '../../src/domain/findFrontendContract';
+
+describe('findFrontendContract', () => {
+  it('returns the normalized output envelope', async () => {
+    const result = await findFrontendContract({ widget: 'caption' }, testContext);
+    expect(result.summary.length).toBeGreaterThan(0);
+    expect(result.evidence.length).toBeGreaterThan(0);
+    expect(result.recommended_actions.length).toBeGreaterThan(0);
+    expect(result.confidence.level).toMatch(/low|medium|high/);
+  });
+});
+```
+
+- [ ] **Step 2: Run the Wave 1 tool test**
+
+Run: `npm run test -- tests/mcp/wave1Tools.test.ts`
+Expected: FAIL because the domain service is missing.
+
+- [ ] **Step 3: Implement normalized tool orchestration**
+
+```ts
+return buildToolOutput({
+  summary: `${widgetName} exposes ${properties.length} properties, ${events.length} events, and ${methods.length} methods.`,
+  evidence,
+  recommended_actions: [
+    `Reuse existing specs mapped to ${widgetName} before drafting a new test.`,
+    'Inspect runtime branches before concluding coverage is complete.',
+  ],
+  repo_paths: uniquePaths(evidence),
+  confidence: confidenceFromEvidence(evidence, warnings),
+  warnings,
+});
+```
+
+- [ ] **Step 4: Register tools with MCP**
+
+Run: `npm run test -- tests/mcp/wave1Tools.test.ts`
+Expected: PASS with `find_existing_test_assets`, `find_frontend_contract`, and `generate_spec_blueprint` registered.
+
+- [ ] **Step 5: Verify local MCP startup**
+
+Run: `npm run mcp:smoke`
+Expected: MCP server starts over stdio and a smoke client can call Wave 1 tools successfully.
+
+### Task 5: Wave 2 Coverage Intelligence
+
+**Files:**
+- Create: `src/domain/findFrontendRuntimeLogic.ts`
+- Create: `src/domain/mapFeatureToExistingCoverage.ts`
+- Create: `src/domain/analyzeTestGaps.ts`
+- Create: `src/domain/findTestAreaContext.ts`
+- Create: `src/domain/recommendSelectorStrategy.ts`
+- Create: `src/domain/buildSetupTeardownPlan.ts`
+- Create: `skills/overkill-find-gaps/SKILL.md`
+- Create: `skills/overkill-generate-setup/SKILL.md`
+- Test: `tests/domain/analyzeTestGaps.test.ts`
+
+- [ ] **Step 1: Write the failing gap-analysis test**
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { analyzeTestGaps } from '../../src/domain/analyzeTestGaps';
+
+describe('analyzeTestGaps', () => {
+  it('flags runtime methods that are not asserted by mapped specs', async () => {
+    const result = await analyzeTestGaps({ widget: 'caption' }, testContext);
+    expect(result.summary).toContain('gap');
+    expect(result.evidence.length).toBeGreaterThan(0);
+  });
+});
+```
+
+- [ ] **Step 2: Run the gap-analysis test**
+
+Run: `npm run test -- tests/domain/analyzeTestGaps.test.ts`
+Expected: FAIL
+
+- [ ] **Step 3: Implement coverage mapping heuristics**
+
+```ts
+const coveredSignals = new Set([
+  ...extractMethodMentions(specBody),
+  ...extractEventMentions(specBody),
+  ...extractWidgetAssertions(specBody),
+]);
+const uncoveredMethods = contract.methods.filter(method => !coveredSignals.has(method));
+const uncoveredEvents = contract.events.filter(event => !coveredSignals.has(event));
+```
+
+- [ ] **Step 4: Run Wave 2 tests**
+
+Run: `npm run test -- tests/domain/analyzeTestGaps.test.ts tests/domain/recommendSelectorStrategy.test.ts tests/domain/buildSetupTeardownPlan.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: Verify acceptance on real widget/spec pair**
+
+Run: `npm run acceptance:coverage -- --widget caption`
+Expected: PASS with evidence sourced from `caseplatform-web` and `autotests2`.
+
+### Task 6: Wave 3 Failure Intelligence
+
+**Files:**
+- Create: `src/connectors/ciArtifactsConnector.ts`
+- Create: `src/domain/triageFailedRun.ts`
+- Create: `src/domain/buildRerunScope.ts`
+- Create: `src/domain/summarizeCiContext.ts`
+- Create: `skills/overkill-debug-failure/SKILL.md`
+- Test: `tests/domain/triageFailedRun.test.ts`
+
+- [ ] **Step 1: Write the failing CI triage test**
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { triageFailedRun } from '../../src/domain/triageFailedRun';
+
+describe('triageFailedRun', () => {
+  it('uses real artifact metadata and returns evidence-backed hypotheses', async () => {
+    const result = await triageFailedRun({
+      statsFile: 'C:/gitrep/autotests2/cypress/reports/test-stats.json',
+      screenshotsRoot: 'C:/gitrep/autotests2/cypress/screenshots',
+      videosRoot: 'C:/gitrep/autotests2/cypress/videos',
+      apiCaptureRoot: 'C:/gitrep/autotests2/cypress/reports/api-capture',
+    }, testContext);
+
+    expect(result.evidence.length).toBeGreaterThan(0);
+    expect(result.recommended_actions.length).toBeGreaterThan(0);
+  });
+});
+```
+
+- [ ] **Step 2: Run the triage test**
+
+Run: `npm run test -- tests/domain/triageFailedRun.test.ts`
+Expected: FAIL
+
+- [ ] **Step 3: Implement artifact ingestion and rerun scope synthesis**
+
+```ts
+const stats = readJson(statsFileSchema.parse(input.statsFile));
+const screenshots = globSync('**/*.png', { cwd: screenshotsRoot, absolute: true });
+const videos = globSync('**/*.mp4', { cwd: videosRoot, absolute: true });
+const apiCaptures = globSync('**/*.json', { cwd: apiCaptureRoot, absolute: true });
+```
+
+- [ ] **Step 4: Run Wave 3 tests**
+
+Run: `npm run test -- tests/domain/triageFailedRun.test.ts tests/domain/buildRerunScope.test.ts tests/domain/summarizeCiContext.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: Verify acceptance against stored artifacts**
+
+Run: `npm run acceptance:failure`
+Expected: PASS with hypotheses referencing real screenshot/video/report paths.
+
+### Task 7: Wave 4 Change Intelligence
+
+**Files:**
+- Create: `src/connectors/diffConnector.ts`
+- Create: `src/domain/analyzeDiffImpact.ts`
+- Create: `skills/overkill-impact-analysis/SKILL.md`
+- Test: `tests/domain/analyzeDiffImpact.test.ts`
+
+- [ ] **Step 1: Write the failing diff-impact test**
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { analyzeDiffImpact } from '../../src/domain/analyzeDiffImpact';
+
+describe('analyzeDiffImpact', () => {
+  it('maps changed frontend files to affected tests and risk areas', async () => {
+    const result = await analyzeDiffImpact({
+      changedFiles: [
+        'C:/gitrep/caseplatform-web/vcm/jqVCM/widget/caption/CaptionSingleton.ts',
+      ],
+    }, testContext);
+
+    expect(result.repo_paths.some(path => path.includes('caption.cy.js'))).toBe(true);
+  });
+});
+```
+
+- [ ] **Step 2: Run the diff-impact test**
+
+Run: `npm run test -- tests/domain/analyzeDiffImpact.test.ts`
+Expected: FAIL
+
+- [ ] **Step 3: Implement graph-style impact mapping**
+
+```ts
+const impactedSpecs = mappedCoverage
+  .filter(item => changedSignals.some(signal => item.frontendPaths.includes(signal.path)))
+  .flatMap(item => item.specPaths);
+```
+
+- [ ] **Step 4: Run the Wave 4 tests**
+
+Run: `npm run test -- tests/domain/analyzeDiffImpact.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: Verify acceptance on a real widget diff**
+
+Run: `npm run acceptance:impact -- --file C:/gitrep/caseplatform-web/vcm/jqVCM/widget/caption/CaptionSingleton.ts`
+Expected: PASS with caption specs in the affected set.
+
+### Task 8: Wave 5 UX, Skills, Templates, And Docs
+
+**Files:**
+- Create: `skills/overkill-review-test-draft/SKILL.md`
+- Create: `skills/overkill-onboard/SKILL.md`
+- Create: `skills/overkill-prompt-builder/SKILL.md`
+- Create: `templates/prompts/*.md`
+- Create: `docs/operator-cookbook.md`
+- Create: `docs/consumer-integration.md`
+- Create: `docs/tool-catalog.md`
+- Create: `README.md`
+- Test: `tests/docs/readmeExamples.test.ts`
+
+- [ ] **Step 1: Write the failing docs example test**
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { loadReadmeExamples } from '../../tests/helpers/loadReadmeExamples';
+
+describe('README examples', () => {
+  it('reference valid commands and config keys', () => {
+    const examples = loadReadmeExamples();
+    expect(examples.commands).toContain('npm run index');
+    expect(examples.configKeys).toContain('repos.autotests2');
+  });
+});
+```
+
+- [ ] **Step 2: Run the docs example test**
+
+Run: `npm run test -- tests/docs/readmeExamples.test.ts`
+Expected: FAIL
+
+- [ ] **Step 3: Implement user-facing docs and skill bundle**
+
+```md
+## Quick Start
+
+1. Copy `overkill.config.example.json` to `overkill.config.json`.
+2. Point `repos.autotests2` and `repos.caseplatformWeb` to local clones.
+3. Run `npm install`.
+4. Run `npm run index`.
+5. Run `npm run mcp`.
+```
+
+- [ ] **Step 4: Run docs and template verification**
+
+Run: `npm run test -- tests/docs/readmeExamples.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: Run full project verification**
+
+Run: `npm run verify`
+Expected: PASS for build, lint, unit tests, and acceptance suites.
+
+## Risks To Track During Execution
+
+- `caseplatform-web` widget implementation styles vary between TypeScript and legacy JavaScript; extractors must allow both.
+- `autotests2` spec text is multilingual and often encoded inconsistently, so search/index normalization must be UTF-8 safe.
+- CI artifact directories can be large; ingestion must be incremental and snapshot-backed.
+- ReportPortal/GitLab network integrations must remain optional; local artifact parsing is the default path.
+- The platform must never edit `autotests2` or `caseplatform-web` by default; all write paths stay inside this repository.
+
+## Acceptance Matrix
+
+- `find_frontend_contract` must return properties/events/methods for caption widget with evidence from `CaptionControl.ts`, `CaptionSingleton.ts`, and `CaptionHandlers.ts`.
+- `find_existing_test_assets` must find `caption.cy.js`, `captionInContainers.cy.js`, and reusable Cypress helpers such as `getWidget`.
+- `generate_spec_blueprint` must generate a draft skeleton that reuses existing area/setup conventions from `autotests2`.
+- `analyze_test_gaps` must report at least one meaningful uncovered signal when coverage heuristics show missing runtime assertions.
+- `triage_failed_run` must cite real artifact paths from `autotests2/cypress/reports`, `screenshots`, `videos`, or `api-capture`.
+- `analyze_diff_impact` must connect changed caption widget files to caption-related specs.
+- Skills must be runnable end-to-end from documented prompts without manually grepping both source repositories.

package/docs/tool-catalog.md

@@ -0,0 +1,34 @@
+# Tool Catalog
+
+## Coverage Intelligence
+
+- `find_existing_test_assets`: locate reusable specs, commands, helpers, selectors
+- `find_test_area_context`: infer area-specific conventions and init flows
+- `find_frontend_contract`: extract properties, events, methods with source evidence
+- `find_frontend_runtime_logic`: extract runtime branches and event wiring
+- `map_feature_to_existing_coverage`: show mapped specs for a feature
+- `analyze_test_gaps`: identify uncovered runtime signals
+- `generate_spec_blueprint`: generate a project-aware draft skeleton
+- `recommend_selector_strategy`: recommend stable selector usage
+- `build_setup_teardown_plan`: propose reuse-first setup and teardown
+
+## Failure Intelligence
+
+- `triage_failed_run`: analyze artifacts and produce evidence-backed hypotheses
+- `build_rerun_scope`: build a minimal rerun pack
+- `summarize_ci_context`: summarize run metadata and artifact presence
+
+## Change Intelligence
+
+- `analyze_diff_impact`: map changed files to affected tests and risk areas
+
+## Output Contract
+
+Each tool returns the same envelope:
+
+- `summary`
+- `evidence`
+- `recommended_actions`
+- `repo_paths`
+- `confidence`
+- `warnings`

package/overkill.config.example.json

@@ -0,0 +1,16 @@
+{
+  "repos": {
+    "autotests2": "../autotests2",
+    "caseplatformWeb": "../caseplatform-web"
+  },
+  "ci": {
+    "artifactsRoot": "../autotests2/cypress",
+    "reportPortal": {
+      "endpoint": "http://reportportal.local/ui"
+    },
+    "gitlab": {
+      "baseUrl": "https://gitlab.example.local"
+    }
+  },
+  "cacheDir": ".overkill-cache"
+}