DongHyeonkaandClaude Fable 5.1
9d2a3725c5
리뷰 두 건을 반영했다. 계약 - tech-log-tree.json 하나가 분해 계약이자 색인이다. 사람이 읽는 트리·Node Specification· 후보 대장은 없어졌고, 문서에 남아 있던 그 개념을 걷어냈다 - candidateScope — 후보를 찾는 SSOT 범위. 접어 넣은 제2부·제3부는 근거이지 후보가 아니다 - sourceRepository — 분석한 저장소의 경로·리비전·판단 근거. 리비전을 모르면 null 로 두고 지어내지 않는다. 갈래가 여럿이면 revisions - 검사기: 계약 미채택·PENDING·PROMOTE↔글감 양방향·candidateScope·sourceRepository 를 error/warn 으로 센다. 옛 스키마도 검사를 피하지 못한다. 테스트 22 → 31 기록 쓰기 - 템플릿 5종에 source·sourceRevision·topicName, Question 에 닫는 조건, 본문 없는 종류에서 assets 제거. 고정 절 개수 삭제 - check_evidence.mjs — 인용한 코드가 SSOT 에 있는지, 앵커가 SSOT 를 가리키는지, 제목이 계약과 같은지, 리비전이 저장소에 있는지. 게시된 기록에서 SSOT 와 다른 URL 을 잡았다 문체 - 문체 규칙의 정본을 ai-tells.md 로. explaining.md 의 질문체 제목·절 끝 대조 반복·그림 예고 규칙을 삭제해 충돌을 없앴다. 첫 절 「설명 뒤에 평가를 붙이지 않는다」에 지우는 사례 네 유형 - voice 스킬의 「독자 쪽을 본다」를 자료에 오독 기록이 있을 때로 좁히고, 평가만 더한 예시를 교체 - check_prose: 안내 문장을 요구하던 경고 제거, 문장이 끝나지 않은 채 문단이 끝나는 조각 검사 추가 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
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 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.
|