# Important Repos Analysis Audit

## Goal

Determine whether the current scan outputs for important repositories are sufficient to support efficient and accurate cross-module logical analysis.

This is an audit task document, not a conclusion-only note.
It defines:

- what "analysis-ready" means
- which repositories must be checked first
- which evidence is required
- how to judge gaps and next actions

## Core Question

The target is not "did we scan many repos".
The target is:

Can the knowledge base answer cross-module questions with high confidence, low lookup cost, and explicit evidence?

Examples:

- Given an external request, can we trace the entrypoint, internal module path, downstream service calls, and deployment/runtime impact?
- Given a config key or rollout change, can we trace where it is defined, propagated, deployed, and consumed?
- Given a service change, can we identify affected modules, dependent services, deployment repos, and likely blast radius?

## Analysis-Ready Criteria

A repository set is considered analysis-ready only if all of the following are available together.

### 1. Runtime Interface Evidence

For service repositories:

- binary entrypoints are identified
- exposed gRPC/HTTP/CLI interfaces are enumerated
- method-level dependencies exist
- important runtime side effects are captured
- interface and dependency files are schema-aligned

### 2. Deployment and Configuration Evidence

For deployment/configuration repositories:

- ownership boundary is explicit
- environment model is explicit
- deployment targets are explicit
- config source-of-truth is explicit
- triggers and delivery paths are explicit
- links to runtime services are explicit

### 3. Cross-Repo Joinability

The knowledge base must support joins across these layers:

`request/interface -> runtime service -> downstream dependency -> config source -> deployment repo -> target environment`

If one layer is missing, cross-module analysis becomes partial and confidence drops sharply.

## Audit Scope

Apply repository filtering before any repo-set operation:

- filter source: `.local/review-history/repos-filtered.txt`

Initial important repositories:

1. `tidb-management-service`
2. `app-delivery`
3. `aws-shared-cd`
4. `infra-cd`
5. `oneconfig`

These five should be treated as the first validation slice because together they span:

- runtime service logic
- application delivery
- infrastructure delivery
- centralized configuration

## Audit Dimensions

Each target repository should be scored across the following dimensions.

| Dimension | Question |
|-----------|----------|
| Repository role clarity | Is the repo's responsibility explicit and bounded? |
| Interface coverage | Are externally reachable interfaces documented? |
| Method dependency coverage | Can we trace per-method downstream calls and conditions? |
| Runtime side effects | Are lifecycle, worker, proxy, event, and config-loading paths captured? |
| Config linkage | Can we map config definitions to consuming services or modules? |
| Deployment linkage | Can we map the repo to environments, stacks, namespaces, or rollout targets? |
| Source-of-truth clarity | Is it clear which repo is authoritative for a given concern? |
| Cross-repo joinability | Can this repo be connected to adjacent repos without manual guessing? |
| Evidence quality | Are claims backed by tracked files or only by summary notes? |
| Review state | Has the output been approved, skipped, or left incomplete? |

Suggested score per dimension:

- `Strong`
- `Partial`
- `Weak`
- `Missing`

## Required Evidence by Repo Type

### Runtime Service Repos

Expected evidence:

- `knowledge/repos/{repo}/meta.json`
- `knowledge/repos/{repo}/deep-scan-state.json`
- `knowledge/repos/{repo}/interfaces/*.json`
- `knowledge/repos/{repo}/service-mapping/*.json`

Acceptance checks:

- every primary service binary is either scanned or explicitly skipped with reason
- every exposed method has a matching dependency entry
- target interface identifiers are canonical and stable
- conditions are specific enough to support reasoning, not collapsed into `Always`

### Deployment or Config Repos

The current scan model is not enough for these repositories because they often have no binaries.

Expected evidence should instead include:

- environment mapping
- stack/project/module inventory
- ownership boundaries
- delivery triggers
- rollout path
- config namespace/key grouping
- links to runtime services or platforms

Minimum tracked output that should exist for these repos:

- a repo-level analysis file under `knowledge/repos/{repo}/`
- or a dedicated deployment/config scan schema if standardized later

## First-Batch Audit Matrix

Current known state from tracked repository outputs:

| Repo | Type | Current state | Analysis readiness |
|------|------|---------------|--------------------|
| `tidb-management-service` | runtime multi-service | scan outputs exist for 6 primary-service binaries; interface and mapping files are present; review is still marked pending | `Partial to Strong` inside runtime scope |
| `app-delivery` | deployment_config | `deep-scan-state.json` exists but status is `skipped` because there are no binaries | `Weak` for cross-repo analysis |
| `aws-shared-cd` | deployment_config | `deep-scan-state.json` exists but status is `skipped` because there are no binaries | `Weak` for cross-repo analysis |
| `infra-cd` | deployment_config | `meta.json` exists; no tracked deep-scan-state file found | `Missing` in tracked audit state |
| `oneconfig` | deployment_config | `meta.json` exists; no tracked deep-scan-state file found | `Missing` in tracked audit state |

## Current Working Hypothesis

The current knowledge base likely supports:

- service-internal logic analysis for selected runtime repositories
- method-level dependency analysis inside well-scanned service repos

The current knowledge base likely does not yet support:

- reliable config-to-runtime tracing
- reliable deployment-to-runtime tracing
- reliable cross-repo blast-radius analysis
- efficient end-to-end reasoning across runtime, config, and deployment layers

In short:

The runtime half is progressing, but the deployment/config half is not yet represented in a comparable analysis-ready form.

## Audit Procedure

For each important repo, perform the audit in this order.

### Step 1. Confirm Tracked Evidence

Check whether these tracked artifacts exist and are internally consistent.

For runtime repos:

- `meta.json`
- `deep-scan-state.json`
- `interfaces/*.json`
- `service-mapping/*.json`

For deployment/config repos:

- `meta.json`
- any tracked repo-analysis outputs
- any documented environment/deployment/config mapping

### Step 2. Validate Real Join Paths

Test whether the knowledge base can answer at least these three joins:

1. runtime interface -> downstream service dependency
2. config definition -> runtime consumer
3. deployment definition -> target runtime service or platform

If any join requires opening raw source trees and manually inferring relationships, mark the relevant dimension as `Weak` or `Missing`.

### Step 3. Run Gold Scenarios

Use a small number of end-to-end questions as acceptance tests.

Recommended gold scenarios:

1. Trace one externally exposed API in `tidb-management-service` to downstream services and identify which deployment/config repos influence its behavior.
2. Trace one representative `oneconfig` change to environment, namespace, delivery mechanism, and runtime service consumer.
3. Trace one rollout path from `app-delivery` or `aws-shared-cd` to the actual service or platform boundary it changes.

### Step 4. Record Blocking Gaps

Capture blockers in concrete terms, such as:

- missing repo-level output
- missing environment mapping
- missing service linkage
- unresolved source-of-truth conflict
- scan schema unsuitable for this repo type

## Recommended Deliverables

Produce these outputs during the audit:

1. A filled audit matrix for the five important repos.
2. A gap list grouped by repo type:
   - runtime scan gaps
   - deployment analysis gaps
   - config analysis gaps
3. A prioritized follow-up plan for the minimum work needed to make cross-module analysis reliable.

## Immediate Next Actions

The recommended order is:

1. Audit `oneconfig` as the config source-of-truth candidate.
2. Audit `infra-cd` as the infra ownership boundary candidate.
3. Audit `aws-shared-cd` as the environment/platform deployment candidate.
4. Audit `app-delivery` as the application rollout candidate.
5. Re-check `tidb-management-service` only after the above joins are available.

Reason:

The main current gap is not additional runtime method extraction.
The main gap is the missing bridge between runtime outputs and deployment/config outputs.

## Exit Criteria

This audit is complete only when we can state, with evidence:

- which important repos are analysis-ready
- which important repos are not analysis-ready
- which missing artifacts block cross-module reasoning
- what minimum additional scanning or modeling work is required

If those four statements cannot be made precisely, the audit is incomplete.