작성일: 2026-02-27
목적: StepSeq v3.0a 명세 기반 리팩토링을 안전하게 진행하기 위한 브랜치 생성 및 운영 가이드

git status

• working tree clean이면 이상적
• Untracked 파일은 브랜치 생성에 문제 없음
• 단, 실수로 커밋되지 않도록 .gitignore 정리 권장

git switch main
git pull

git switch -c refactor/stepseq-v3.0a

브랜치 확인:

git branch --show-current

예시 단계:

1. viewBar / playBar / queuedViewBar 도입
2. BAR looper boundary switching 구현
3. Count-in 입력 차단 정리
4. OVWR 세션 정책 정리
5. OVDB Replace 정책 정리
6. Quantized Live Record 정리

커밋 예:

git add APS/aps_stepseq.py
git commit -m "Refactor: Introduce viewBar/playBar separation"

명세 변경과 코드 변경은 별도 커밋 권장:

git add docs/Ardule_StepSeq_Integrated_Spec_v3.0a_KO.docx
git commit -m "Add StepSeq v3.0a integrated specification"

git push -u origin refactor/stepseq-v3.0a

이후부터는 git push만 입력해도 됨.

main과 차이 보기:

git diff main..refactor/stepseq-v3.0a -- APS/aps_stepseq.py

브랜치 이동:

git switch main
git switch refactor/stepseq-v3.0a

git reset --soft HEAD~1

git reset --hard HEAD~1

git restore APS/aps_stepseq.py

git switch main
git merge --no-ff refactor/stepseq-v3.0a
git push

--no-ff는 리팩토링 작업 단위를 명확히 기록함.

• main은 항상 실행 가능한 상태 유지
• 리팩토링은 별도 브랜치에서
• 작은 단위 커밋
• 문서와 코드 동기화
• 자주 푸시하여 백업

이 가이드는 StepSeq 구조 리팩토링과 같은 대규모 변경 작업에 최적화되어 있다.

이 체크리스트는 Ardule StepSeq Integrated Spec v3.0a(Transport/REC/Policy 직교 구조, OVDB=Replace)를 aps_stepseq.py에 적용할 때 “되던 것을 깨지 않기” 위한 최소 점검 항목이다.

• [ ] 리팩토링은 refactor/stepseq-v3.0a 같은 독립 브랜치에서 시작했다.
• [ ] 1기능 = 1커밋으로 쪼갰다(변수 도입 → 경계 전환 → 세션 정책…).
• [ ] 각 커밋은 git diff HEAD~1로 변화 범위가 설명 가능할 정도로 작다.
• [ ] 큰 실험을 하기 전 “안전 시점” 태그를 찍었다(선택).

• [ ] Transport(playing/loop), REC(rec_armed), Policy(OVWR/OVDB)가 서로를 암묵적으로 변경하지 않는다.
  • 예: playing 때문에 REC가 자동으로 켜지지 않음
  • 예: OVDB 선택이 loop를 강제로 켜지지 않음(명시적으로만)
• [ ] REC=OFF일 때는 어떤 입력도 패턴 데이터를 변경하지 않는다.
• [ ] Policy(OVWR/OVDB)는 REC=ON일 때만 실제 쓰기 로직에 영향을 준다.

• [ ] 편집/기록 대상은 항상 viewBar다.
• [ ] 재생 대상은 playBar다.
• [ ] BAR looper에서 [/]는 viewBar만 즉시 변경하고, playBar는 마디 경계에서만 바뀐다.
• [ ] queuedViewBar가 설정되었을 때 상태 표시(NEXT 등)가 UI에 드러난다(권장).
• [ ] loop OFF 또는 scope 변경 시 queuedViewBar는 반드시 clear된다.

• [ ] playhead wrap(예: step 15→0 또는 loop_end→loop_start) 지점이 단일 블록/단일 함수로 정리되어 있다.
• [ ] 다음 처리는 경계에서만 발생한다:
  • queued 적용(playBar 전환)
  • 루프 카운트/세션 상태 업데이트
  • count-in 종료→recording 진입 전환(해당 시)

• [ ] Count-in 중에는 입력 이벤트가 완전 무시된다(Preview/Record 모두).
• [ ] Count-in 종료 시점이 재생/기록 전환과 충돌하지 않는다(경계 처리와 일치).

• [ ] Preview는 “즉시 1회 출력”이며 그리드/플레이헤드와 독립이다.
• [ ] Playback은 “그리드 기반 재생”이며 loop/playBar 규칙만 따른다.
• [ ] Record는 “Quantize 후 그리드 쓰기”이며 REC/policy/viewBar 규칙만 따른다.
• [ ] “두 번 들림” 방지를 위해 Preview와 Playback이 같은 트리거로 중복 호출되지 않는다.

• [ ] OVWR:
  • [ ] 녹음 시작 시 기존 데이터를 버퍼에서 초기화(즉시 파괴 금지)한다.
  • [ ] 단일 패스(루프 없음)로 동작한다.
  • [ ] 중단 시 rollback, 정상 종료 시 commit이 가능하다.
• [ ] OVDB(Replace):
  • [ ] 기존 데이터를 유지한다.
  • [ ] 루프 기반 세션으로 동작한다(명시적 loopEnabled/loopScope).
  • [ ] 입력이 들어오면 해당 셀을 Replace(덮어쓰기) 한다.
  • [ ] 중단해도 “현재까지 결과 유지” 정책이 유지된다.

• [ ] BAR looper ON에서 [/]를 눌러도 즉시 점프하지 않고, 다음 마디 경계에서 전환된다.
• [ ] REC OFF에서 아무리 입력해도 패턴이 바뀌지 않는다.
• [ ] Count-in 중 패드를 쳐도 기록/프리뷰가 발생하지 않는다.
• [ ] OVWR는 시작 시 초기화되고 중단 시 원상복구(rollback) 된다(가능한 구현이라면).
• [ ] OVDB(Replace)는 같은 스텝에 다시 입력하면 해당 셀이 덮어써진다.
• [ ] Preview가 Playback과 겹쳐서 “이중 출력”되지 않는다.

• [ ] .gitignore로 *.bak, data/, patterns/, *.zip 등 로컬 산출물이 커밋되지 않도록 했다(권장).
• [ ] 브랜치에서 주기적으로 git push 하여 원격 백업을 유지한다.
• [ ] main 병합 전, git merge main으로 충돌을 미리 해소하고 테스트했다.