88 lines
6.1 KiB
Markdown
88 lines
6.1 KiB
Markdown
# 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 root-tree 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.
|