@mknrt/autotests-overkill 1.2.2 → 1.2.5

package/docs/superpowers/plans/2026-04-20-fis-platform-backend-integration.md

@@ -1,980 +0,0 @@
-# FIS Platform Backend Integration 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:** Add focused `fis_platform` backend knowledge and an explainable API interaction map to `autotests-overkill` so MCP answers become materially better for `autotests2` test authoring, debugging, impact analysis, and CI/API triage.
-
-**Architecture:** Extend the existing `connectors -> extractors -> SQLite FTS -> domain -> MCP tools` pipeline with one explicit bridge object, `ApiDiscoveryCatalog`, plus two narrow knowledge layers: `api-interaction` and `backend-contract`. Build the catalog from `autotests2` support code first, pass it into `fis_platform` backend discovery explicitly, then store only evidence-backed documents with confidence metadata. Runtime API captures stay on-demand triage evidence in iteration 1; persistent runtime observation indexing is deferred until static interaction indexing proves useful.
-
-**Tech Stack:** TypeScript, Node.js, Zod, built-in node:sqlite/FTS5, Vitest, MCP SDK, Java source parsing via regex/structured text extraction.
-
----
-
-## File Structure
-
-### Existing files to modify
-
-- `src/config/consumerConfig.ts`
-  Responsibility: runtime config schema and path resolution.
-- `src/appContext.ts`
-  Responsibility: wiring connectors and database into the app context.
-- `src/connectors/autotests2Connector.ts`
-  Responsibility: expose request-helper and API-support sources for indexing.
-- `src/indexer/refreshPipeline.ts`
-  Responsibility: building knowledge documents and syncing them into SQLite.
-- `src/mcp/registerTools.ts`
-  Responsibility: MCP tool registry and tool contracts.
-- `src/domain/generateSpecBlueprint.ts`
-  Responsibility: reuse-first blueprint generation for new tests.
-- `src/domain/analyzeDiffImpact.ts`
-  Responsibility: mapping changed files to risky test scopes.
-- `src/domain/triageFailedRun.ts`
-  Responsibility: artifact-based failure triage and recommended next actions.
-- `README.md`
-  Responsibility: top-level usage, supported repos, and tool catalog summary.
-- `docs/tool-catalog.md`
-  Responsibility: operator-facing description of MCP tools.
-- `docs/operator-cookbook.md`
-  Responsibility: practical usage scenarios and indexing workflow.
-
-### New files to create
-
-- `src/connectors/fisPlatformConnector.ts`
-  Responsibility: focused backend source discovery in `fis_platform` using an explicit `ApiDiscoveryCatalog`.
-- `src/indexer/extractors/apiDiscoveryExtractor.ts`
-  Responsibility: build and score `ApiDiscoveryCatalog` from `autotests2` support code.
-- `src/indexer/extractors/backendContractExtractor.ts`
-  Responsibility: extract endpoint, params, async task semantics, feature flags, and error hints from selected Java sources.
-- `src/indexer/extractors/apiInteractionExtractor.ts`
-  Responsibility: convert selected `ApiDiscoveryCatalog` families into normalized API interaction documents.
-- `src/domain/findBackendTestContext.ts`
-  Responsibility: produce an evidence-backed answer that links `autotests2` request flows, captured API paths, and backend contracts.
-- `tests/connectors/fisPlatformConnector.test.ts`
-  Responsibility: verify source selection stays narrow and relevant.
-- `tests/indexer/apiDiscoveryExtractor.test.ts`
-  Responsibility: verify API family discovery, scoring, and explainability.
-- `tests/indexer/backendContractExtractor.test.ts`
-  Responsibility: verify extracted backend knowledge shape.
-- `tests/indexer/apiInteractionExtractor.test.ts`
-  Responsibility: verify API interaction records are normalized and linked to `autotests2` assets.
-- `tests/domain/findBackendTestContext.test.ts`
-  Responsibility: verify tool output includes API interaction evidence plus backend evidence for `autotests2` scenarios.
-- `tests/domain/generateSpecBlueprint.backend.test.ts`
-  Responsibility: verify backend hints appear only when relevant.
-- `tests/domain/analyzeDiffImpact.backend.test.ts`
-  Responsibility: verify backend diffs map to `autotests2` tests.
-- `tests/domain/triageFailedRun.backend.test.ts`
-  Responsibility: verify captured API paths enrich triage output.
-
-### `ApiDiscoveryCatalog` contract
-
-`ApiDiscoveryCatalog` is the bridge between `autotests2`, runtime triage, and `fis_platform`. It must be built before backend discovery and saved to `.overkill-cache/snapshots/api-discovery-catalog.json`.
-
-```ts
-export type ApiDiscoveryCatalog = {
-  families: ApiDiscoveryFamily[];
-  generatedAt: string;
-  warnings: string[];
-};
-
-export type ApiDiscoveryFamily = {
-  family: string;
-  normalizedPaths: string[];
-  consumerSignals: Array<{
-    kind: 'endpoint-constant' | 'request-wrapper' | 'capture-support' | 'spec-reference';
-    path: string;
-    name?: string;
-    snippet: string;
-  }>;
-  score: number;
-  whySelected: string[];
-};
-```
-
-Scoring for iteration 1 must be deterministic:
-
-```ts
-score =
-  endpointConstantHits * 4
-  + requestWrapperHits * 3
-  + apiCaptureSupportHits * 2
-  + specReferenceHits;
-```
-
-Only the top 2-3 families with at least two different signal kinds should be selected for backend matching. Families below that threshold may be stored in the snapshot as candidates, but they must not drive blueprint or impact answers.
-
-### Backend discovery rules for iteration 1
-
-- Scan `fis_platform` for Java REST/resource sources using structural signals such as `@Path`, `@GET`, `@POST`, `@PUT`, `@DELETE`, `@QueryParam`, `@HeaderParam`, `@Consumes`, `@Produces`.
-- Boost files that are also referenced from REST/OpenAPI registration or documentation modules.
-- Exclude obvious noise by rule, not by handpicked file list: `thirdparty`, generated sources, frontend assets, vendor directories, and test fixtures.
-- Keep only endpoints whose normalized path or resource name overlaps with selected families from `ApiDiscoveryCatalog`.
-- Produce a `confidence` score for every backend match. Only `confidence >= 0.7` can be used in blueprint, impact, and triage recommendations; lower confidence records can be returned only as exploratory evidence.
-
-### API discovery rules for iteration 1
-
-- Discover canonical API identities from `autotests2` support code, not from spec file names.
-- Scan `cypress/support/**/*.js`, then keep files with API signals such as `cy.request`, `Cypress.Commands.add`, URL/path constants, `fetch`, `XMLHttpRequest`, `apiCapture`, or `request`.
-- Extract consumer evidence such as endpoint constants, wrapper function names, request methods, and normalized request paths.
-- Treat specs as downstream evidence consumers, not as the source of truth for API aliases.
-
-### API identities that must be discoverable in iteration 1
-
-- The system must discover API families from `autotests2` support code first, then optionally enrich matching during triage with runtime capture evidence.
-- Iteration 1 should implement only the top 2-3 highest-signal API families after discovery, not a predeclared domain list.
-- Discovery output must be saved as evidence in snapshots so the chosen families are explainable and reviewable.
-- The exact consumer links must be derived from indexed support code and, during triage, matched against runtime capture evidence. They must not be maintained as a hardcoded alias-to-file map.
-- Runtime API capture files are read on demand by `triage_failed_run` in iteration 1. They should not be persisted as knowledge documents until we know the static catalog is useful and low-noise.
-
-## Task 1: Add `fis_platform` to runtime configuration and app context
-
-**Files:**
-- Modify: `src/config/consumerConfig.ts`
-- Modify: `src/appContext.ts`
-- Test: `tests/config/consumerConfig.test.ts`
-- Test: `tests/cli/runtimeAppContext.test.ts`
-
-- [ ] **Step 1: Write the failing config test**
-
-```ts
-it('parses fisPlatform repo path when provided', () => {
-  const config = parseConsumerConfig({
-    repos: {
-      autotests2: '../autotests2',
-      caseplatformWeb: '../caseplatform-web',
-      fisPlatform: '../fis_platform',
-    },
-    ci: {
-      artifactsRoot: '../autotests2/cypress',
-    },
-  }, 'C:/workspace');
-
-  expect(config.repos.fisPlatform).toBe('C:/fis_platform'.replaceAll('/', path.sep));
-});
-```
-
-- [ ] **Step 2: Run the config test to verify it fails**
-
-Run: `npm test -- tests/config/consumerConfig.test.ts`
-Expected: FAIL with a Zod/schema mismatch because `fisPlatform` is unknown.
-
-- [ ] **Step 3: Extend the config schema and defaults**
-
-```ts
-repos: z.object({
-  autotests2: z.string().min(1),
-  caseplatformWeb: z.string().min(1),
-  fisPlatform: z.string().min(1).optional(),
-}).strict(),
-```
-
-```ts
-repos: {
-  autotests2: resolveRepoPath(parsed.repos.autotests2, baseDir),
-  caseplatformWeb: resolveRepoPath(parsed.repos.caseplatformWeb, baseDir),
-  fisPlatform: parsed.repos.fisPlatform
-    ? resolveRepoPath(parsed.repos.fisPlatform, baseDir)
-    : undefined,
-},
-```
-
-```ts
-repos: {
-  autotests2: '../autotests2',
-  caseplatformWeb: '../caseplatform-web',
-  fisPlatform: '../fis_platform',
-},
-```
-
-- [ ] **Step 4: Wire the connector into app context**
-
-```ts
-import { FisPlatformConnector } from './connectors/fisPlatformConnector.js';
-```
-
-```ts
-export type AppContext = {
-  config: ConsumerConfig;
-  database: ReturnType<typeof createKnowledgeDatabase>;
-  autotests2: Autotests2Connector;
-  caseplatform: CaseplatformConnector;
-  fisPlatform?: FisPlatformConnector;
-  ciArtifacts: CiArtifactsConnector;
-  gitlab: GitLabConnector;
-  reportPortal: ReportPortalConnector;
-};
-```
-
-```ts
-fisPlatform: config.repos.fisPlatform
-  ? new FisPlatformConnector(config.repos.fisPlatform)
-  : undefined,
-```
-
-- [ ] **Step 5: Run the focused tests to verify they pass**
-
-Run: `npm test -- tests/config/consumerConfig.test.ts tests/cli/runtimeAppContext.test.ts`
-Expected: PASS
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/config/consumerConfig.ts src/appContext.ts tests/config/consumerConfig.test.ts tests/cli/runtimeAppContext.test.ts
-git commit -m "feat: add fis platform runtime config"
-```
-
-## Task 2: Build `ApiDiscoveryCatalog` from `autotests2`
-
-**Files:**
-- Modify: `src/connectors/autotests2Connector.ts`
-- Create: `src/indexer/extractors/apiDiscoveryExtractor.ts`
-- Test: `tests/indexer/apiDiscoveryExtractor.test.ts`
-
-- [ ] **Step 1: Write the failing API discovery test**
-
-```ts
-it('builds an explainable api discovery catalog from consumer support code', async () => {
-  const catalog = await buildApiDiscoveryCatalog({
-    root: fixturePaths.autotests2Root,
-    maxSelectedFamilies: 3,
-  });
-
-  expect(catalog.families.length).toBeGreaterThan(0);
-  expect(catalog.families.every((family) => family.score > 0)).toBe(true);
-  expect(catalog.families.every((family) => family.whySelected.length > 0)).toBe(true);
-  expect(catalog.families.every((family) => family.consumerSignals.length >= 2)).toBe(true);
-});
-```
-
-- [ ] **Step 2: Run the API discovery test to verify it fails**
-
-Run: `npm test -- tests/indexer/apiDiscoveryExtractor.test.ts`
-Expected: FAIL with module not found for `buildApiDiscoveryCatalog`.
-
-- [ ] **Step 3: Add API support source discovery to `Autotests2Connector`**
-
-```ts
-async findApiSupportSources() {
-  const files = await this.fs.glob(this.root, ['cypress/support/**/*.js']);
-
-  return files
-    .map((filePath) => ({ path: filePath, body: this.fs.read(filePath) }))
-    .filter((source) => /cy\.request|Cypress\.Commands\.add|fetch\(|XMLHttpRequest|apiCapture|request|\/platform\/|\/rs2\//i.test(source.body));
-}
-```
-
-- [ ] **Step 4: Implement `ApiDiscoveryCatalog` and deterministic scoring**
-
-```ts
-export type ApiDiscoveryCatalog = {
-  families: ApiDiscoveryFamily[];
-  generatedAt: string;
-  warnings: string[];
-};
-
-export type ApiDiscoveryFamily = {
-  family: string;
-  normalizedPaths: string[];
-  consumerSignals: Array<{
-    kind: 'endpoint-constant' | 'request-wrapper' | 'capture-support' | 'spec-reference';
-    path: string;
-    name?: string;
-    snippet: string;
-  }>;
-  score: number;
-  whySelected: string[];
-};
-```
-
-```ts
-const scoreFamily = (signals: ApiDiscoveryFamily['consumerSignals']) => {
-  const count = (kind: ApiDiscoveryFamily['consumerSignals'][number]['kind']) =>
-    signals.filter((signal) => signal.kind === kind).length;
-
-  return count('endpoint-constant') * 4
-    + count('request-wrapper') * 3
-    + count('capture-support') * 2
-    + count('spec-reference');
-};
-```
-
-```ts
-const hasEnoughEvidence = (family: ApiDiscoveryFamily) =>
-  new Set(family.consumerSignals.map((signal) => signal.kind)).size >= 2;
-```
-
-- [ ] **Step 5: Run the API discovery test**
-
-Run: `npm test -- tests/indexer/apiDiscoveryExtractor.test.ts`
-Expected: PASS
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/connectors/autotests2Connector.ts src/indexer/extractors/apiDiscoveryExtractor.ts tests/indexer/apiDiscoveryExtractor.test.ts
-git commit -m "feat: discover autotests2 api families"
-```
-
-## Task 3: Discover matching `fis_platform` backend sources from `ApiDiscoveryCatalog`
-
-**Files:**
-- Create: `src/connectors/fisPlatformConnector.ts`
-- Create: `src/indexer/extractors/backendContractExtractor.ts`
-- Test: `tests/connectors/fisPlatformConnector.test.ts`
-- Test: `tests/indexer/backendContractExtractor.test.ts`
-
-- [ ] **Step 1: Write the failing backend discovery test**
-
-```ts
-it('selects backend rest sources using an explicit api discovery catalog', async () => {
-  const connector = new FisPlatformConnector(fixturePaths.fisPlatformRoot);
-  const sources = await connector.listFocusedSources({
-    families: [
-      {
-        family: 'sample',
-        normalizedPaths: ['/platform/rs2/sample/action'],
-        consumerSignals: [
-          { kind: 'endpoint-constant', path: 'fixture/apiEndpoints.js', snippet: '/platform/rs2/sample/action' },
-          { kind: 'request-wrapper', path: 'fixture/api.commands.js', name: 'sampleAction', snippet: 'cy.request' },
-        ],
-        score: 7,
-        whySelected: ['fixture family with two signal kinds'],
-      },
-    ],
-    generatedAt: '2026-04-20T00:00:00.000Z',
-    warnings: [],
-  });
-
-  expect(sources.some((item) => item.path.includes('thirdparty'))).toBe(false);
-  expect(sources.every((item) => item.confidence >= 0 && item.confidence <= 1)).toBe(true);
-});
-```
-
-- [ ] **Step 2: Run the backend discovery test to verify it fails**
-
-Run: `npm test -- tests/connectors/fisPlatformConnector.test.ts`
-Expected: FAIL with module not found for `FisPlatformConnector`.
-
-- [ ] **Step 3: Implement backend discovery without consumer repo access**
-
-```ts
-export type FocusedFisSource = {
-  path: string;
-  body: string;
-  sourceKind: 'backend-resource' | 'backend-interface' | 'backend-openapi-config';
-  matchedFamily: string;
-  confidence: number;
-  whyMatched: string[];
-};
-```
-
-```ts
-async listFocusedSources(apiCatalog: ApiDiscoveryCatalog): Promise<FocusedFisSource[]> {
-  const files = await this.fs.glob(this.root, ['lib/**/*.java', 'lib/**/pom.xml']);
-
-  return files
-    .filter((filePath) => !/(thirdparty|extjs|oryx|generated|node_modules)/i.test(filePath))
-    .map((filePath) => ({ path: filePath, body: this.fs.read(filePath) }))
-    .filter((source) => /@Path|@(GET|POST|PUT|DELETE)|@QueryParam|@HeaderParam/.test(source.body))
-    .flatMap((source) => matchBackendSourceToFamilies(source, apiCatalog.families))
-    .filter((source) => source.confidence >= 0.4);
-}
-```
-
-- [ ] **Step 4: Write the failing backend contract extractor test**
-
-```ts
-it('extracts backend endpoint records with confidence and evidence paths', async () => {
-  const extraction = await extractBackendContracts({
-    sources: fixtureFocusedFisSources,
-  });
-
-  const endpointRecord = extraction.documents[0];
-
-  expect(endpointRecord.metadata.endpointPath).toBeTruthy();
-  expect(endpointRecord.metadata.evidencePaths.length).toBeGreaterThan(0);
-  expect(endpointRecord.metadata.confidence).toBeGreaterThanOrEqual(0.4);
-});
-```
-
-- [ ] **Step 5: Implement backend contract records**
-
-```ts
-export type BackendKnowledgeRecord = {
-  id: string;
-  title: string;
-  path: string;
-  body: string;
-  sourceKind: 'backend-endpoint';
-  repoKind: 'fis-platform';
-  metadata: {
-    httpMethod?: 'GET' | 'POST' | 'PUT' | 'DELETE';
-    endpointPath: string;
-    apiFamily: string;
-    paramNames: string[];
-    ruleHints: string[];
-    evidencePaths: string[];
-    confidence: number;
-    whyMatched: string[];
-  };
-};
-```
-
-```ts
-const endpointMatches = [
-  ...body.matchAll(/@(GET|POST|PUT|DELETE)|@Path\("([^"]+)"\)|@QueryParam\("([^"]+)"\)|@HeaderParam\("([^"]+)"\)/g),
-];
-```
-
-- [ ] **Step 6: Run backend discovery and extractor tests**
-
-Run: `npm test -- tests/connectors/fisPlatformConnector.test.ts tests/indexer/backendContractExtractor.test.ts`
-Expected: PASS
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add src/connectors/fisPlatformConnector.ts src/indexer/extractors/backendContractExtractor.ts tests/connectors/fisPlatformConnector.test.ts tests/indexer/backendContractExtractor.test.ts
-git commit -m "feat: discover backend contracts from api catalog"
-```
-
-## Task 4: Index API interactions and backend contracts
-
-**Files:**
-- Create: `src/indexer/extractors/apiInteractionExtractor.ts`
-- Modify: `src/indexer/refreshPipeline.ts`
-- Test: `tests/indexer/apiInteractionExtractor.test.ts`
-- Test: `tests/indexer/refreshPipeline.caseplatformIndex.test.ts`
-
-- [ ] **Step 1: Write the failing API interaction test**
-
-```ts
-it('converts selected api discovery families into api interaction documents', async () => {
-  const extraction = extractApiInteractions({
-    catalog: fixtureApiDiscoveryCatalog,
-  });
-
-  const record = extraction.documents[0];
-
-  expect(record.sourceKind).toBe('api-interaction');
-  expect(record.metadata.apiFamily).toBeTruthy();
-  expect(record.metadata.consumerSignalIds.length).toBeGreaterThan(0);
-  expect(record.metadata.confidence).toBeGreaterThanOrEqual(0.7);
-});
-```
-
-- [ ] **Step 2: Run the API interaction test to verify it fails**
-
-Run: `npm test -- tests/indexer/apiInteractionExtractor.test.ts`
-Expected: FAIL with module not found for `extractApiInteractions`.
-
-- [ ] **Step 3: Implement API interaction records**
-
-```ts
-export type ApiInteractionRecord = {
-  id: string;
-  title: string;
-  path: string;
-  body: string;
-  sourceKind: 'api-interaction';
-  repoKind: 'autotests2';
-  metadata: {
-    apiFamily: string;
-    normalizedPaths: string[];
-    consumerSignalIds: string[];
-    evidencePaths: string[];
-    confidence: number;
-    whySelected: string[];
-  };
-};
-```
-
-- [ ] **Step 4: Integrate catalog, interactions, and backend contracts into refresh pipeline**
-
-```ts
-const apiCatalog = await buildApiDiscoveryCatalog({
-  root: context.config.repos.autotests2,
-  maxSelectedFamilies: 3,
-});
-snapshotStore.write('api-discovery-catalog', apiCatalog);
-
-const apiInteractions = extractApiInteractions({ catalog: apiCatalog });
-snapshotStore.write('api-interactions', apiInteractions);
-
-for (const record of apiInteractions.documents) {
-  documents.push(documentFrom({
-    sourceKind: record.sourceKind,
-    repoKind: record.repoKind,
-    path: record.path,
-    title: record.title,
-    body: record.body,
-    metadata: record.metadata,
-    updatedAt: now,
-  }));
-}
-```
-
-```ts
-if (context.fisPlatform && context.config.repos.fisPlatform && fs.existsSync(context.config.repos.fisPlatform)) {
-  repoKindsToSync.push('fis-platform');
-  const backendSources = await context.fisPlatform.listFocusedSources(apiCatalog);
-  const backendContracts = await extractBackendContracts({ sources: backendSources });
-  snapshotStore.write('backend-contracts', backendContracts);
-
-  for (const record of backendContracts.documents) {
-    documents.push(documentFrom({
-      sourceKind: record.sourceKind,
-      repoKind: record.repoKind,
-      path: record.path,
-      title: record.title,
-      body: record.body,
-      metadata: record.metadata,
-      updatedAt: now,
-    }));
-  }
-}
-```
-
-- [ ] **Step 5: Run indexing tests**
-
-Run: `npm test -- tests/indexer/apiInteractionExtractor.test.ts tests/indexer/refreshPipeline.caseplatformIndex.test.ts`
-Expected: PASS
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/indexer/extractors/apiInteractionExtractor.ts src/indexer/refreshPipeline.ts tests/indexer/apiInteractionExtractor.test.ts
-git commit -m "feat: index api interactions and backend contracts"
-```
-
-## Task 5: Add `find_backend_test_context` MCP tool
-
-**Files:**
-- Create: `src/domain/findBackendTestContext.ts`
-- Modify: `src/mcp/registerTools.ts`
-- Test: `tests/domain/findBackendTestContext.test.ts`
-- Test: `tests/mcp/wave1Tools.test.ts`
-
-- [ ] **Step 1: Write the failing domain test**
-
-```ts
-it('returns api interaction evidence, backend evidence, and linked autotests2 specs for a discovered api flow', async () => {
-  const result = await findBackendTestContext({ query: 'discovered api flow' }, context);
-
-  expect(result.summary).toContain('API interaction');
-  expect(result.evidence.some((item) => item.label === 'api interaction')).toBe(true);
-  expect(result.evidence.some((item) => item.path?.includes('fis_platform'))).toBe(true);
-  expect(result.evidence.some((item) => item.path?.includes('autotests2'))).toBe(true);
-  expect(result.recommended_actions.some((item) => item.includes('required params'))).toBe(true);
-});
-```
-
-- [ ] **Step 2: Run the domain test to verify it fails**
-
-Run: `npm test -- tests/domain/findBackendTestContext.test.ts`
-Expected: FAIL with module not found for `findBackendTestContext`.
-
-- [ ] **Step 3: Implement the domain service**
-
-```ts
-const interactionHits = queryDocuments(context.database, input.query, {
-  repoKind: 'autotests2',
-  sourceKinds: ['api-interaction'],
-  limit: 6,
-}).filter((item) => {
-  const metadata = JSON.parse(item.metadata_json) as { confidence?: number };
-  return (metadata.confidence ?? 0) >= 0.7;
-});
-```
-
-```ts
-const backendHits = queryDocuments(context.database, input.query, {
-  repoKind: 'fis-platform',
-  sourceKinds: ['backend-endpoint'],
-  limit: 8,
-}).filter((item) => {
-  const metadata = JSON.parse(item.metadata_json) as { confidence?: number };
-  return (metadata.confidence ?? 0) >= 0.7;
-});
-```
-
-```ts
-const linkedSpecs = queryDocuments(context.database, [ ...interactionHits, ...backendHits ].flatMap((item) => {
-  const metadata = JSON.parse(item.metadata_json) as { consumerSignalIds?: string[]; evidencePaths?: string[] };
-  return [ ...(metadata.consumerSignalIds ?? []), ...(metadata.evidencePaths ?? []) ];
-}).join(' '), {
-  repoKind: 'autotests2',
-  sourceKinds: ['spec', 'command', 'helper'],
-  limit: 8,
-});
-```
-
-```ts
-return output(
-  `Found ${interactionHits.length} API interaction record(s), ${backendHits.length} backend context record(s), and ${linkedSpecs.length} autotests2 asset(s) for '${input.query}'.`,
-  [
-    ...interactionHits.map((item) => evidenceFile('api interaction', item.path, truncate(item.body, 220), { retrieval: 'knowledge-store' })),
-    ...backendHits.map((item) => evidenceFile('backend endpoint', item.path, truncate(item.body, 220), { retrieval: 'knowledge-store' })),
-    ...linkedSpecs.map((item) => evidenceFile('linked autotest asset', item.path, truncate(item.body, 180), { retrieval: 'knowledge-store' })),
-  ],
-  [
-    'Reuse the indexed API interaction flow before reconstructing request order by hand.',
-    'Check required params and backend feature flags before debugging selectors.',
-    'Reuse the linked autotests2 request flow instead of rebuilding API assumptions from scratch.',
-  ],
-);
-```
-
-- [ ] **Step 4: Register the MCP tool**
-
-```ts
-{
-  name: 'find_backend_test_context',
-  description: 'Finds autotests2 API interaction flows plus backend endpoint, validation, async-task, and error hints.',
-  inputSchema: z.object({ query: z.string().min(1) }),
-  outputSchema: toolOutputSchema,
-  execute: findBackendTestContext,
-},
-```
-
-- [ ] **Step 5: Run the domain and MCP tests**
-
-Run: `npm test -- tests/domain/findBackendTestContext.test.ts tests/mcp/wave1Tools.test.ts`
-Expected: PASS
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/domain/findBackendTestContext.ts src/mcp/registerTools.ts tests/domain/findBackendTestContext.test.ts tests/mcp/wave1Tools.test.ts
-git commit -m "feat: add backend test context mcp tool"
-```
-
-## Task 6: Upgrade `generate_spec_blueprint` with API and backend hints for API-heavy flows
-
-**Files:**
-- Modify: `src/domain/generateSpecBlueprint.ts`
-- Test: `tests/domain/generateSpecBlueprint.backend.test.ts`
-
-- [ ] **Step 1: Write the failing blueprint test**
-
-```ts
-it('adds backend hints for api-heavy scenarios', async () => {
-  const result = await generateSpecBlueprint({ feature: 'api-heavy scenario from discovered consumer flow', area: 'constructor' }, context);
-
-  expect(result.summary).toContain('spec draft');
-  expect(result.evidence.some((item) => item.label === 'backend hint')).toBe(true);
-  expect(result.recommended_actions.some((item) => item.includes('completion'))).toBe(true);
-});
-```
-
-- [ ] **Step 2: Run the blueprint test to verify it fails**
-
-Run: `npm test -- tests/domain/generateSpecBlueprint.backend.test.ts`
-Expected: FAIL because backend hints are absent.
-
-- [ ] **Step 3: Add optional backend retrieval inside blueprint generation**
-
-```ts
-const backendContext = queryDocuments(context.database, input.feature, {
-  repoKind: 'fis-platform',
-  sourceKinds: ['backend-endpoint'],
-  limit: 3,
-}).filter((item) => {
-  const metadata = JSON.parse(item.metadata_json) as { confidence?: number };
-  return (metadata.confidence ?? 0) >= 0.7;
-});
-```
-
-```ts
-const apiContext = queryDocuments(context.database, input.feature, {
-  repoKind: 'autotests2',
-  sourceKinds: ['api-interaction'],
-  limit: 3,
-}).filter((item) => {
-  const metadata = JSON.parse(item.metadata_json) as { confidence?: number };
-  return (metadata.confidence ?? 0) >= 0.7;
-});
-```
-
-```ts
-const backendGuidance = backendContext.length > 0 || apiContext.length > 0
-  ? [
-      `API flow: ${apiContext[0]?.title ?? backendContext[0]?.title}`,
-      'Preserve request order, required query params, and async task polling from the indexed flow.',
-      'If the scenario depends on async backend processing, verify completion signals before UI assertions.',
-    ]
-  : [];
-```
-
-```ts
-{
-  type: 'symbol',
-  label: 'backend hint',
-  snippet: backendGuidance.join('\n'),
-}
-```
-
-- [ ] **Step 4: Run the blueprint tests**
-
-Run: `npm test -- tests/domain/generateSpecBlueprint.integration.test.ts tests/domain/generateSpecBlueprint.backend.test.ts`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/domain/generateSpecBlueprint.ts tests/domain/generateSpecBlueprint.backend.test.ts
-git commit -m "feat: enrich spec blueprint with backend hints"
-```
-
-## Task 7: Upgrade diff impact analysis for backend changes
-
-**Files:**
-- Modify: `src/domain/analyzeDiffImpact.ts`
-- Test: `tests/domain/analyzeDiffImpact.backend.test.ts`
-
-- [ ] **Step 1: Write the failing backend impact test**
-
-```ts
-it('maps discovered backend api changes to relevant autotests2 tests', async () => {
-  const result = await analyzeDiffImpact({
-    changedFiles: [
-      `${fixturePaths.fisPlatformRoot}/lib/some-module/src/main/java/example/TransferResource.java`,
-    ],
-  }, context);
-
-  expect(result.summary).toContain('affected spec');
-  expect(result.evidence.some((item) => item.path?.includes('autotests2'))).toBe(true);
-});
-```
-
-- [ ] **Step 2: Run the impact test to verify it fails**
-
-Run: `npm test -- tests/domain/analyzeDiffImpact.backend.test.ts`
-Expected: FAIL because backend repo paths are ignored.
-
-- [ ] **Step 3: Extend impact analysis to use API interaction records as the bridge**
-
-```ts
-const backendFeatureText = deriveFeatureTextFromBackendSource({
-  filePath,
-  fileBody: maybeReadChangedFile(filePath),
-});
-```
-
-```ts
-const interactionHits = queryDocuments(context.database, backendFeatureText, {
-  repoKind: 'autotests2',
-  sourceKinds: ['api-interaction'],
-  limit: 8,
-}).filter((item) => {
-  const metadata = JSON.parse(item.metadata_json) as { confidence?: number };
-  return (metadata.confidence ?? 0) >= 0.7;
-});
-```
-
-```ts
-const linkedSpecs = queryDocuments(context.database, interactionHits.flatMap((item) => {
-  const metadata = JSON.parse(item.metadata_json) as { consumerSignalIds?: string[]; evidencePaths?: string[] };
-  return [ ...(metadata.consumerSignalIds ?? []), ...(metadata.evidencePaths ?? []) ];
-}).join(' '), {
-  repoKind: 'autotests2',
-  sourceKinds: ['spec', 'command', 'helper'],
-  limit: 8,
-});
-```
-
-- [ ] **Step 4: Run the impact tests**
-
-Run: `npm test -- tests/domain/analyzeDiffImpact.test.ts tests/domain/analyzeDiffImpact.backend.test.ts`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/domain/analyzeDiffImpact.ts tests/domain/analyzeDiffImpact.backend.test.ts
-git commit -m "feat: map backend diffs to autotests2 impact"
-```
-
-## Task 8: Upgrade failure triage with API-interaction-aware backend interpretation
-
-**Files:**
-- Modify: `src/domain/triageFailedRun.ts`
-- Test: `tests/domain/triageFailedRun.backend.test.ts`
-
-- [ ] **Step 1: Write the failing triage test**
-
-```ts
-it('adds backend hints when captured api traffic matches indexed interaction records', async () => {
-  const result = await triageFailedRun({
-    statsFile: fixturePaths.statsFile,
-    screenshotsRoot: fixturePaths.screenshotsRoot,
-    videosRoot: fixturePaths.videosRoot,
-    apiCaptureRoot: fixturePaths.apiCaptureRoot,
-  }, context);
-
-  expect(result.recommended_actions.some((item) => item.includes('backend contract'))).toBe(true);
-});
-```
-
-- [ ] **Step 2: Run the triage test to verify it fails**
-
-Run: `npm test -- tests/domain/triageFailedRun.backend.test.ts`
-Expected: FAIL because triage ignores backend knowledge.
-
-- [ ] **Step 3: Add API-interaction-aware endpoint enrichment**
-
-```ts
-const backendSignals = apiCaptures.flatMap((filePath) => {
-  const raw = JSON.parse(fs.readFileSync(filePath, 'utf8')) as Array<{ path?: string }>;
-  return raw.map((entry) => entry.path ?? '').filter(Boolean);
-});
-```
-
-```ts
-const interactionHits = queryDocuments(context.database, backendSignals.join(' '), {
-  repoKind: 'autotests2',
-  sourceKinds: ['api-interaction'],
-  limit: 6,
-}).filter((item) => {
-  const metadata = JSON.parse(item.metadata_json) as { normalizedPaths?: string[]; confidence?: number };
-  return (metadata.confidence ?? 0) >= 0.7
-    && (metadata.normalizedPaths ?? []).some((path) => backendSignals.some((signal) => signal.includes(path) || path.includes(signal)));
-});
-```
-
-```ts
-const backendHits = queryDocuments(context.database, interactionHits.map((item) => item.title).join(' '), {
-  repoKind: 'fis-platform',
-  sourceKinds: ['backend-endpoint'],
-  limit: 6,
-}).filter((item) => {
-  const metadata = JSON.parse(item.metadata_json) as { confidence?: number };
-  return (metadata.confidence ?? 0) >= 0.7;
-});
-```
-
-```ts
-if (interactionHits.length > 0 || backendHits.length > 0) {
-  actions.push('Compare the failing API capture with the indexed API interaction flow and backend contract before editing the test flow.');
-}
-```
-
-- [ ] **Step 4: Run the triage tests**
-
-Run: `npm test -- tests/domain/triageFailedRun.test.ts tests/domain/triageFailedRun.backend.test.ts`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/domain/triageFailedRun.ts tests/domain/triageFailedRun.backend.test.ts
-git commit -m "feat: enrich triage with backend api context"
-```
-
-## Task 9: Update documentation and verification coverage
-
-**Files:**
-- Modify: `README.md`
-- Modify: `docs/tool-catalog.md`
-- Modify: `docs/operator-cookbook.md`
-- Modify: `overkill.config.example.json`
-- Test: `tests/docs/readmeExamples.test.ts`
-
-- [ ] **Step 1: Write the failing docs expectation test**
-
-```ts
-it('documents fis_platform as an optional backend knowledge source', async () => {
-  const readme = fs.readFileSync('README.md', 'utf8');
-
-  expect(readme).toContain('fis_platform');
-  expect(readme).toContain('find_backend_test_context');
-  expect(readme).toContain('api-interaction');
-  expect(readme).toContain('ApiDiscoveryCatalog');
-});
-```
-
-- [ ] **Step 2: Run the docs test to verify it fails**
-
-Run: `npm test -- tests/docs/readmeExamples.test.ts`
-Expected: FAIL because README has no backend section.
-
-- [ ] **Step 3: Update config example and docs**
-
-```json
-{
-  "repos": {
-    "autotests2": "../autotests2",
-    "caseplatformWeb": "../caseplatform-web",
-    "fisPlatform": "../fis_platform"
-  }
-}
-```
-
-```md
-- `find_backend_test_context`: explain discovered API behavior with evidence from `fis_platform` and linked `autotests2` assets
-```
-
-```md
-- `api-interaction` indexing: normalize request helpers and endpoint aliases from `autotests2` so MCP can connect failing API captures to backend contracts
-```
-
-```md
-- `ApiDiscoveryCatalog`: explain which API families were selected, why they were selected, and which consumer evidence supports them
-```
-
-```md
-Use backend indexing when:
-- debugging request flows discovered from support code or API capture
-- generating blueprints for API-heavy specs
-- triaging failures with API captures
-```
-
-- [ ] **Step 4: Run the docs and full verification suite**
-
-Run: `npm run verify`
-Expected: PASS
-
-Run: `npm run mcp:smoke`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add README.md docs/tool-catalog.md docs/operator-cookbook.md overkill.config.example.json tests/docs/readmeExamples.test.ts
-git commit -m "docs: add fis platform backend integration guidance"
-```
-
-## Sequencing Notes
-
-- Implement Tasks 1-4 first. That produces the minimal useful index slice:
-  config + `ApiDiscoveryCatalog` + focused backend discovery + `api-interaction` and `backend-endpoint` documents.
-- Implement Task 5 only after Task 4 passes, because `find_backend_test_context` depends on indexed interaction and backend documents.
-- Implement Tasks 6-8 after the new backend tool is stable.
-- Keep complex backend resources narrow in iteration 1. Only infer path-level and validation-level hints; do not attempt full semantic parsing.
-
-## Verification Checklist
-
-- Unit tests use fixtures under `tests/fixtures/backend-integration/**`; real `C:\gitrep\autotests2` and `C:\gitrep\fis_platform` paths are allowed only in optional integration smoke checks.
-- `find_backend_test_context` returns at least one `fis_platform` evidence item for:
-  - a discovered API family from consumer support code
-  - a discovered API family with a high-confidence backend match
-- `find_backend_test_context` also returns at least one `api-interaction` evidence item for:
-  - a discovered API family from consumer support code
-- `triage_failed_run` uses runtime API capture evidence on demand without persisting raw captures into the knowledge store.
-- `generate_spec_blueprint` includes backend guidance for console/API-heavy scenarios and stays unchanged for pure frontend widget flows.
-- `analyze_diff_impact` maps discovered backend REST/resource changes to concrete `autotests2` specs through indexed API interactions.
-- `triage_failed_run` adds API-aware and backend-aware actions when captured API paths match indexed interaction records and backend endpoints.
-- No documents from `thirdparty`, `extjs`, or `oryx` are inserted into the knowledge store.
-
-## Deferred Work
-
-- Persist aggregated runtime API-capture observations into the knowledge store only after static API interaction indexing proves useful and low-noise.
-- Parse generated OpenAPI JSON/YAML if `fis_platform/lib/doc-rest` starts emitting build artifacts reliably.
-- Add a dedicated relation table for exact backend-to-test links only if FTS metadata becomes insufficient.
-- Expand beyond the first discovered high-signal API families only after iteration 1 proves useful in daily `autotests2` workflows.
-
-## Self-Review
-
-- Spec coverage: this plan covers config, connectors, extractor/indexer, API interaction mapping, backend knowledge reuse, MCP tooling, blueprint support, impact analysis, triage, docs, and tests.
-- Placeholder scan: no `TODO`, `TBD`, or “implement later” markers remain in executable tasks.
-- Type consistency: repo kind is consistently `fis-platform` for backend contracts and `autotests2` for API interaction records, source kinds are consistently `backend-endpoint` and `api-interaction`, and the new MCP entrypoint is consistently `find_backend_test_context`.