# Analysis Queue Contract

`<분석 대상 저장소>/analysis-queue.yaml` is the first control file read by every detailed-analysis run. It is the SSOT for project order, active-project ownership, and explicit reanalysis requests.

## State model

Allowed project states:

- `PENDING` — queued, never started for the current analysis history;
- `IN_PROGRESS` — the project currently owned by the 09:00 analysis run;
- `COMPLETE` — all intended scopes and `final/document.md` are complete for the recorded source snapshot;
- `REANALYZE` — a previously completed project explicitly queued for another analysis cycle after source changes or a requested re-review;
- `BLOCKED` — the active project cannot continue because required source, instructions, or environment are unavailable;
- `SKIPPED` — explicitly excluded by the user or queue owner.

At most one project may be `IN_PROGRESS`. `activeProject` must be `null`, or name the project currently owned by the analysis worker. An owned project may be `IN_PROGRESS` or `BLOCKED`. A `REANALYZE` entry is queued, not active, until a scheduled run activates it.

## Mandatory run order

1. **Read `analysis-queue.yaml` before scanning project contents.**
2. Discover direct project directories under `<분석 대상 저장소>`. Ignore control files and hidden infrastructure directories.
3. Append newly discovered, unlisted projects to the **end** of `projects` as `PENDING`. Never insert them ahead of existing entries automatically.
4. If `activeProject` names an `IN_PROGRESS` project, continue only that project.
5. If `activeProject` names a `BLOCKED` project, do not start another project. Re-check only the blocking prerequisite; resume as `IN_PROGRESS` when resolved, otherwise leave it blocked and stop.
6. If there is no active project, scan queue entries from top to bottom and choose the first actionable entry whose state is `PENDING` or `REANALYZE`.
7. For `PENDING`, set it to `IN_PROGRESS`, set `activeProject`, initialize/continue `docs/<프로젝트>/state.json`, and run the normal exhaustive analysis cycle.
8. For `REANALYZE`, execute the reanalysis activation procedure below, then set it to `IN_PROGRESS` and set `activeProject`.
9. Continue the active project across scheduled runs until its required scopes are complete and `final/document.md` is synthesized for the target source snapshot.
10. Only then mark the entry `COMPLETE`, update the completed source revision, clear `activeProject`, and allow a later scheduled run to select the next actionable entry.

Do not begin another project in the same run after completing one. Completion creates a clean scheduling boundary.

## Reanalysis activation

`REANALYZE` is an explicit user request to analyze a project again **without deleting the previous detailed analysis**.

Before changing `REANALYZE` to `IN_PROGRESS`:

1. Read the existing `docs/<프로젝트>/state.json` and `final/document.md`.
2. Resolve the previous completed source snapshot. Prefer `finalDocument.sourceRevision`; fall back only to another explicitly recorded completed revision. If no trustworthy baseline exists, mark the project `BLOCKED` with a note rather than pretending this is incremental reanalysis.
3. Resolve the current target source revision. For Git repositories, record `git rev-parse HEAD` and working-tree status. Do not modify/reset source.
4. Compare baseline → target before reopening scopes. Record changed paths and the evidence used to map those paths to bounded scopes.
5. Set `reanalysis.baselineRevision`, `reanalysis.targetRevision`, `reanalysis.changedPaths`, `reanalysis.impactedScopes`, increment `analysisCycle`, and set `reanalysis.requestedAt`.
6. Choose a reanalysis mode:
   - `IMPACTED_SCOPES` when changed paths can be mapped confidently to bounded scopes and project/module boundaries remain stable;
   - `FULL_PROJECT` when module/build boundaries, shared contracts, architecture rules, cross-cutting configuration, migration ownership, generated sources, or scope mapping itself changed, or when impact cannot be bounded confidently.
7. Reopen only the impacted scopes for `IMPACTED_SCOPES`, but keep previous analysis as historical baseline. Rebuild the project-wide synthesis after those scopes complete.
8. For `FULL_PROJECT`, re-establish the project inventory and coverage ledger from the target snapshot and revalidate every intended scope.

A reanalysis cycle must never silently overwrite the fact that earlier documents described an earlier source snapshot. Preserve revision provenance in state and analysis prose where it matters.

## Reanalysis completion

When reanalysis finishes:

- update every reopened scope to complete for the target revision;
- synthesize `final/document.md` again, including material changes from the prior snapshot when relevant;
- set `finalDocument.sourceRevision` to the target revision;
- set `reanalysis.completedAt`;
- mark the queue entry `COMPLETE`;
- clear `activeProject`.

The 10:00 decomposition stage will see the changed final document and may then update decomposition/readiness. The 11:00 generation stage remains grounded in that updated tree.

## New projects and ordering

A new directory may appear while another project is being analyzed. Append it as `PENDING`; **do not preempt the active project**. `REANALYZE` also does not preempt the active project. The user may reorder queued `PENDING` and `REANALYZE` entries manually. Automatic runs never reorder existing entries.

## Blocked projects

If the active project disappears, cannot be read, lacks a trustworthy reanalysis baseline, or requires an unavailable prerequisite, mark it `BLOCKED`, retain it as `activeProject`, record the reason, and stop. Do not silently jump to the next project. Resuming means returning the same entry to `IN_PROGRESS`; skipping requires explicit `SKIPPED` and clearing `activeProject`.

## Example: explicit reanalysis request

```yaml
version: 1
activeProject: null
projects:
  - name: backend-clean-architecture
    status: REANALYZE
  - name: tech-log-backend
    status: PENDING
  - name: ca-tmpl
    status: PENDING
```

On the next run, if the first project has a trustworthy completed baseline, it becomes the active `IN_PROGRESS` project and begins a new analysis cycle.