document-haness/.agents/skills/analyzing-codebase-for-tech-log/references/queue-contract.md

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

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.