지속적 리팩터링

리팩터 검사

감지하되, 결코 작성하지 마세요. 마지막 검사 이후 해결된 것은 무엇인지, 다음에 작업할 내용은 무엇인지 제안합니다 — 이슈를 제기하거나 결과를 결정하지 않습니다. refactor-design이 선택된 내용에 대해 이슈를 제기하고, refactor-learn이 이 스킬이 감지한 내용을 바탕으로 조치를 취합니다.

프로세스

1. 사전 조건 확인

• Git 저장소가 없음 → 검사를 중단하고 보고하며, 아무것도 제안하지 않습니다.
• refactor:candidate 이슈가 5개 이상 열려 있음 → 중단하고, 새로 제안하지 않습니다. 기존 작업이 먼저 처리되도록 합니다.

2. 보류 중인 작업 우선 재개

리팩터링 노트의 bookkeeping.md에 있는 Pending candidates 필드를 읽습니다(skills/continuous-refactoring/references/refactoring-bookkeeping.md). 여기에 이슈가 명시되어 있다면, 이전 검사의 refactor-design이 이슈를 제기했지만 병합 요청이 따라오기 전에 중단된 것입니다. 정확히 그 이슈를 제안하고 중단합니다 — 새로운 작업을 제안하기 전에 보류 중인 작업을 완료하는 것이 우선입니다.

3. 종료/병합된 기억 상태 감지

기억된 집합을 가져옵니다 — docs/agents/issue-tracker.md가 네이티브 레이블 추적기(GitHub, GitLab)를 명시하면 → 열려 있는 모든 refactor:candidate 이슈와 각각이 연결된 풀 리퀘스트를 추적기의 네이티브 이슈↔종료 PR 교차 참조(Closes #<n> refactor-implement 5단계에서 이미 전달 MR에 넣음)를 통해 해결합니다. 아직 연결된 PR이 없는 이슈는 이 단계에서 조정할 내용이 없습니다. 그렇지 않으면 → 리팩터링 노트의 merge-requests.md에 있는 모든 항목에 대해, 외부 추적기/git에서 MR이 아직 열려 있는지, 이슈가 아직 열려 있는지 확인합니다.

gh/glab(또는 다른 forge API/토큰)을 사용할 수 없는 경우 → 이 단계를 건너뛰는 대신 Git 전용 조정으로 대체합니다(여기서 gh/glab를 설치하려고 시도하지 마십시오. 이들의 부재를 정확히 이 대체의 트리거로 간주합니다): skills/refactor-scan/references/git-only-reconciliation.md. 원격 저장소가 전혀 없는 경우(git remote -v가 비어 있음) → 동일한 파일의 로컬 전용 변형입니다. 기억된 후보가 opening-a-merge-request.md의 "Forge/원격 없음"에 따라 순수하게 로컬에서 작업하는 인간에 의해 병합되거나 거부되었을 수 있습니다.

• 병합됨 → 발견 사항: 전달되었습니다.

• 병합 없이 종료됨 → 발견 사항: 거부되었습니다 — 종료 댓글에 유지보수자의 구조적 이유(범위를 벗어난 자료)가 있는지 여부를 기록합니다.

• 아직 열려 있고, 검토자 활동(검토 또는 댓글)이 브랜치의 마지막 커밋보다 최신임 → 재개 후보이지, 발견 사항이 아닙니다 — 아무도 결정하지 않았으며, 다시 살펴볼 필요가 있습니다. API 접근 가능 → 타임스탬프와 함께 실제 검토 상태도 읽습니다(gh pr view <n> --json reviews,reviewDecision 또는 동등한 것) — "무언가 변경됨"에서 멈추지 마십시오:

  • CHANGES_REQUESTED, 해결되지 않음(검토보다 최신 커밋 없음) → 여전히 재개 후보이지만, 브랜치뿐만 아니라 검토의 댓글/본문도 함께 전달합니다. refactor-implement 1단계에서 해당 특정 피드백을 읽고 처리하며, 브랜치를 처음부터 다시 검토하지 않습니다.
  • 댓글, 또는 차단 피드백이 없는 APPROVED 검토 → 기존 일반 재개 후보 처리입니다. 첨부할 다른 내용이 없습니다.

  2단계가 Pending candidates 항목을 전달하는 것과 같은 방식으로 전달합니다: 바로 refactor-implement로, refactor-prioritize/refactor-design을 건너뜁니다(이미 설계와 열린 MR이 있습니다. 수정 루프만 적용됩니다 — refactor-implement 1단계는 이미 기존 브랜치 재개를 지원합니다). API 접근 불가(Git 전용 대체) → 검토 상태는 git-only-reconciliation.md에 이미 문서화된 대로 사용할 수 없습니다. 이 개선 사항은 거기에 적용되지 않습니다.

• 아직 열려 있고, 변경된 사항 없음 → 발견 사항 없음.

또한 리팩터링 노트의 out-of-scope/<node>.md에 있는 각 항목이 **Blocked by:** PHP >= X.Y 조건을 명시하는지 확인합니다(tooling_tree.py의 detect_nodes()가 실행 시 이를 직접 보고합니다. 수동으로는 대상의 현재 composer.json require.php/config.platform.php와 비교합니다) — 대상의 현재 PHP 버전이 이제 이를 충족하면, 이 거부가 취소되었음을 발견합니다. Blocked by: 필드가 없거나 조건이 여전히 충족되지 않으면 결코 발견 사항이 아닙니다.

모든 발견 사항을 refactor-learn에 전달합니다 — 이 스킬은 단지 감지만 할 뿐, 어떤 것도 done/wontfix로 표시하거나 리팩터링 노트의 out-of-scope/ 자체에 쓰지 않습니다.

3b. 외부에서 레이블링된 후보 감지

API 접근 가능(Git 전용 대체가 아님) → 또한 이미 처리되지 않은 열려 있는 refactor:candidate 이슈를 쿼리합니다: 2단계의 Pending candidates 항목도, 3단계의 기억된 집합(링크된 풀 리퀘스트가 있는 이슈는 이미 진행 중)도 아닙니다. 남은 것은 인간(또는 다른 프로세스)이 직접 레이블링했으며 이 루프가 설계하거나 구현한 적이 없는 후보입니다. 정상 운영에서는 스위트의 자체 후보가 항상 이 두 가지 중 하나로 처리되므로 "우리 것"과 "다른 사람의 것"을 구별하기 위해 추가 정보가 필요하지 않습니다. 각각을 제안으로 전달하며, 4단계의 도구링 트리 제안이 합류하는 동일한 목록입니다. refactor-prioritize가 일반적인 요소에 따라 다른 모든 것과 함께 순위를 매깁니다. 존재한다고 해서 대기열을 뛰어넘지 않고 자신의 장점으로 경쟁합니다. API 접근 불가(Git 전용 대체) → 이 단계를 완전히 건너뜁니다. git만으로는 레이블로 이슈를 열거할 수 없습니다.

4. 도구링 트리 노드 제안

2단계가 이미 보류 중인 후보를 제안한 경우 건너뜁니다.

python3 skills/refactor-scan/references/tooling_tree.py <target-repo>를 실행하고 JSON의 next 필드를 읽습니다 — 실제로 현재 차단되지 않은 집합이며, 거부된 노드(리팩터링 노트의 out-of-scope/<node>.md에 이미 있는 항목)는 제외됩니다. 항목 수에 관계없이 그대로 가져옵니다. roadmap이 아닙니다(오늘의 실제 옵션이 아닌 미래 시뮬레이션). 또한 withheld를 읽습니다: 그렇지 않으면 next에 포함될 수 있지만 아직 결정되지 않은 권장 상위 항목을 기다리는 노드입니다. 각 항목은 어떤 상위 항목을 기다리는지 명시합니다. python3가 없거나 허용되지 않는 경우 → skills/refactor-scan/references/tree-walk-prompt.md의 프롬프트({N}=all)와 함께 하위 에이전트를 파견합니다. 동일한 트리 문서를 수동으로 탐색합니다(먼저 리팩터링 노트의 bookkeeping.md에 있는 Fulfilled nodes를 읽어 캐시된 상태를 다시 도출하는 것을 건너뛰고, 범위 밖 항목이 있는 노드는 건너뜁니다). 하위 에이전트 메커니즘이 없는 경우 → 단계를 인라인으로 직접 실행합니다.

• 일반 도구링 노드(loop-config 및 언어 전문화 노드, 예: skills/refactor-scan/references/php-tooling-tree.md) — 이름(원시 슬러그가 아님)으로 제안됩니다. 각 노드는 이미 해당 트리 문서에 완전히 명시되어 있습니다.
• structural-scan — resolved 에지를 통해 연결된 모든 노드가 해결되면(충족되거나 리팩터링 노트의 out-of-scope/ 아래에서 명시적으로 거부됨) 제안됩니다: 일반 루트의 editorconfig와 활성 언어 전문화의 자체 집계 노드(PHP: php-structural-scan)입니다. php-structural-scan 자체는 자체 해결된 상위 항목이 모두 해결되면 해결됩니다(skills/refactor-scan/references/tooling-tree.md). structural-scan만이 이런 방식으로 제안됩니다. php-structural-scan은 순수한 배관이며 결코 후보가 아닙니다. 제안하는 것은 단지 이름을 지정하는 것입니다. 코드베이스 탐색은 실제로 선택된 노드에 대해서만 refactor-design에서 발생합니다.
• 인식된 언어 트리 없음: structural-scan은 여전히 일반 루트 리프인 editorconfig를 기다립니다. 적용되는 언어별 트리가 없기 때문에 즉시 제안할 수 없습니다.

출력

오케스트레이터에 의해 명확하게 전달됩니다:

• 검사를 중단시킨 사전 조건(해당하는 경우) — 이 검사에는 아래 내용이 적용되지 않습니다.
• 발견 사항(비어 있을 수 있음) → refactor-learn.
• 재개 후보가 감지된 경우 → refactor-prioritize/refactor-design을 우회하여 바로 refactor-implement로 전달됩니다.
• 제안 — 보류 중인 후보 단독, 또는 현재 차단되지 않은 각 노드의 이름(슬러그가 아니며 제한 없음)과 3b단계의 외부 레이블링 후보(있는 경우), 또는 없음 → refactor-prioritize로 전달됩니다. 현재 차단되지 않은 모든 노드(필요한 상위 항목이 충족되고, 거부되지 않았으며, 모든 권장 상위 항목이 이미 결정됨)는 우선 순위에 따라 잘린 하위 집합이 아닙니다. 함께, 각 withheld 노드와 기다리는 상위 항목을 명시합니다(예: "Rector: Type Coverage Set — 대기 중: PHP CS Fixer").

완료 기준

발견 사항(있는 경우)은 refactor-learn에 전달되고, 재개 후보(있는 경우)는 바로 refactor-implement에 전달되며, 제안(있는 경우)은 refactor-prioritize에 전달됩니다. 또는 사전 조건이 검사를 중단하고 보고서에 그 이유가 명시됩니다. 동일한 목록에 structural-scan 이후의 항목과 함께 노드가 포함되지 않습니다.