# Codex Rescan Guide

## Overview

Codex rescan validates that an already scanned repository still matches the current source-backed runtime truth.

For each primary service binary, the rescan must verify:
1. All API/gRPC endpoints
2. Per-method service dependencies
3. Conditions for external service calls
4. Implementation details that affect dependency behavior

### Goal

Build and maintain a source-backed **service-level dependency graph** for each binary.

Combined with deployment configuration, this enables:
- service-to-service relationships in production
- high-level data flow between deployed components
- deployment ordering based on dependency chains

Example insight:
```text
dm-master -> depends on etcd, mysql, dm-worker
dm-worker -> depends on mysql, kafka

=> In production: dm-master must start after etcd + mysql, dm-worker after mysql + kafka
```

**Scope:**
- service/binary level dependencies
- interface/method level dependencies with `target_interface` where applicable

## Objective

Run a fresh codex rescan for a repo, verify the existing scan outputs against source, and update the rescan trail in `deep-scan-state.json`.

## Highest Priority Rule

All compact requirements in this document are highest priority rules.
- if any normal workflow step conflicts with a compact boundary, the compact boundary wins
- do not delay, bypass, or reorder a required compact for convenience or momentum
- do not start, continue, or resume repo-level source inspection when a required compact is still pending

Before starting a fresh scan or codex rescan for any new repo:
- if the context-window waterline is above 50%, stop immediately
- organize the current TODO state first
- perform a context compact next
- start the repo scan only after the compact is complete

After finishing any repo:
- do not start the next repo in the same context window
- organize the carry-forward TODO state first
- perform a context compact immediately
- start the next repo only after the compact is complete

This rule has higher priority than the normal workflow order below.

Hard gate:
- do not begin source inspection, file review, or runtime verification for a new repo when the session is already above the 50% context-waterline threshold
- the TODO handoff must preserve the current repo, next repo, blockers, and partially verified findings so the scan can resume cleanly after compact
- even when the waterline is healthy, completing one repo still requires an immediate compact before the next repo begins
- every pending compact requirement in this document blocks further repo work until the compact is complete

Minimize-interruption rule:
- ask the user as little as possible
- if a reasonable assumption can be made safely, make it and continue
- do not pause a scan or codex rescan to ask avoidable questions
- keep pushing the scan forward until the current repo reaches a real stopping point

Allowed exceptions:
- a destructive action needs explicit approval
- access, permission, or tool authorization is blocked
- continuing would create a high-risk chance of corrupting outputs or misrepresenting runtime truth

## Repo Target State

A single repo reaches codex-rescan complete state only when all of the following are true:
- source-backed fresh codex rescan completed
- `deep-scan-state.json` includes `codex_rescan_at`
- `deep-scan-state.json` records both `codex_rescan_verdict` and `codex_rescan_note`

## Task Progress State

Task-tracker updates are separate from repo rescan completion.

When this repo is being processed under a task runner such as:
- `.local/codex-approval-completion.md`

the local task trail should be updated only after:
- the repo rescan itself is complete
- the repo-specific PR workflow defined by the task runner is finished
- the task runner is ready to advance to the next repo

## Required Inputs

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

If repo lists are involved, filter them first with:
- `.local/review-history/repos-filtered.txt`

## Directory Structure

```text
knowledge/repos/{repo-name}/
├── meta.json
├── deep-scan-state.json
├── interfaces/
│   └── {path-based-name}.json
└── service-mapping/
    └── {path-based-name}.json

.local/
├── repos/{repo-name}/path.json
└── codex-approval-completion.md
```

**Collision-safe naming:** binary path `cmd/foo-server` maps to output file `cmd-foo-server.json`.

## Workflow

### 0. Check context budget before starting a repo

Apply the highest-priority context rule before any repo-level scan work:
- if the context-window waterline is above 50%, first organize the current TODO state
- then perform a context compact
- only start the repo scan after the compact is complete
- if the previous repo was just finished, compact first even if the waterline is still below 50%

Context-budget rule:
- do not begin source inspection for a new repo when the session is already above the 50% context-waterline threshold
- the TODO handoff should preserve the current repo, next repo, blockers, and any partially verified findings so the scan can resume cleanly after compact
- one completed repo is a mandatory compact boundary before any next repo starts
- this section is governed by the highest-priority compact rule above, not by the normal workflow order

### 1. Read repository metadata

Read:
- `knowledge/repos/{repo}/meta.json`
- `knowledge/repos/{repo}/deep-scan-state.json`
- `.local/repos/{repo}/path.json`

Use them to determine:
- repo identity and local source path
- expected binaries
- binary roles
- interface types
- existing scan and rescan history

### 2. Decide what must be scanned

Route by each binary's `interfaces` and `role`, not only by `repo_kind`.

Usually rescan:
- `primary_service`
- service binaries in `multi_service` or `multi_binary` repos

Usually skip:
- `admin_cli`
- pure CLI tools
- examples
- libraries
- deployment-only repos
- docs-only repos

Decision rule:
- if a binary serves production traffic or acts as a service entrypoint, it belongs in rescan scope
- if a binary is only an operator tool, migration helper, local example, or build utility, it should normally be skipped
- if the repo contains mixed binaries, decide per binary and record skipped items explicitly in `deep-scan-state.json`

### 3. Verify the source-backed runtime truth

For each binary that should be scanned:
- inspect the current source code
- inspect the existing `interfaces/` output
- inspect the existing `service-mapping/` output
- confirm the outputs still match the code paths that actually serve requests or emit downstream calls

Verification must cover:
- exposed HTTP, gRPC, or other service interfaces
- handler-to-method mapping
- downstream service calls
- infrastructure usage such as mysql, redis, kafka, s3, or message buses
- conditions that gate those calls
- error-path-only calls where they materially affect runtime behavior

Runtime-truth judgment rule:
- prefer entrypoints, router registration, gRPC service registration, and concrete client callsites over comments or stale generated artifacts
- when generated outputs and source disagree, source wins
- when multiple code paths exist, record only the paths that are actually reachable under supported runtime behavior

### 4. Rebuild or correct stale outputs

If the old scan is stale, incomplete, or schema-inconsistent:
- regenerate or fix the affected files under `interfaces/`
- regenerate or fix the affected files under `service-mapping/`

Keep the outputs source-backed. Do not preserve old entries that are no longer supported by code.

Typical reasons to rebuild:
- endpoint was added, removed, or renamed
- downstream dependency changed
- `target_interface` is missing or wrong
- condition modeling is incomplete
- file naming or schema no longer matches repo conventions

### 5. Update `deep-scan-state.json`

Record the fresh rescan trail:
- `codex_rescan_at`
- `codex_rescan_verdict`
- `codex_rescan_note`

Also update scan bookkeeping if needed so it reflects the current reality of:
- expected binaries
- scanned binaries
- skipped binaries
- generated files

Rescan record rule:
- do not write only `codex_rescan_at`
- a repo should be treated as complete only when timestamp, verdict, and note are all present and reflect the latest source-backed verification

### 6. Clear the task trail

If this repo is being processed under an external task runner, update the active local task tracker such as `.local/codex-approval-completion.md` only after the repo-specific PR has been merged and you have returned to `main`.

Task-trail rule:
- local task trackers are not part of the repo-specific output PR scope
- repo-specific PR creation and merge flow are owned by the external task runner, not by this scan guide
- remove the repo from the task tracker only after the rescan record is complete
- remove the repo only after the repo-specific PR is merged and `main` is up to date locally
- do not clear the task item when only partial state updates exist

### 7. Compact before the next repo

After the current repo is fully finished:
- capture the current repo outcome, merged PR state, next repo, and any carry-forward blockers
- perform a context compact immediately
- do not inspect, read, or verify the next repo before the compact is complete

Next-repo rule:
- "repo finished" means the repo-specific rescan work is done, the repo-specific PR workflow is done, and any external task tracker has been updated on `main`
- after that point, compact is mandatory, not optional
- the next repo always starts in the post-compact context
- this compact boundary has highest priority over every later workflow action

## File Format Notes

### `meta.json`

`meta.json` records the repository scan baseline, including:
- repo identity
- language
- repo classification
- binaries
- detected interfaces
- binary roles

Important rule:
- `repo_kind` is informational
- actual scan decisions should be made from binary-level `interfaces` and `role`

### `deep-scan-state.json`

Rescan work should preserve the existing deep-scan state and append the codex rescan trail.

Minimal rescan additions:

```json
{
  "codex_rescan_at": "2026-03-28T10:00:00+08:00",
  "codex_rescan_verdict": "fresh",
  "codex_rescan_note": "Verified interfaces and service mappings against current source."
}
```

Suggested verdict values:
- `fresh`
- `updated`
- `stale_fixed`
- `blocked`

Suggested note content:
- what was verified
- whether outputs were unchanged or corrected
- any important scope decision, such as skipped binaries

## Dependency Categories

Dependencies are split into two categories:

| Category | Description | Examples | Has target_interface |
|----------|-------------|----------|----------------------|
| infrastructure | Non-service infrastructure | mysql, redis, kafka, s3 | No |
| services | Service-to-service calls | auth-svc, worker-svc | Yes |

Infrastructure examples:

| Type | Operations | Client |
|------|------------|--------|
| mysql | SELECT, INSERT, UPDATE, DELETE | `gorm.io/gorm` |
| redis | GET, SET, DEL | `go-redis/redis` |
| kafka | PUBLISH, SUBSCRIBE | `confluent-kafka-go` |
| s3 | GET, PUT, DELETE | `aws-sdk-go-v2` |

## Condition Types

| Type | Description |
|------|-------------|
| `Always` | Always executes |
| `Conditional` | Executes only under configuration or data conditions |
| `error_path` | Executes only on error handling paths |

## Output Standard

A codex rescan is complete only when:
- current source has been inspected
- `interfaces/` matches the actual exposed interface surface
- `service-mapping/` matches actual downstream behavior
- stale or incorrect outputs have been corrected
- `deep-scan-state.json` contains a complete rescan trail with `codex_rescan_at`, `codex_rescan_verdict`, and `codex_rescan_note`