위생: 액션 핀 `# vN` 주석 staleness 감지 — 게이트가 구조적으로 못 잡는 무신호 드리프트

[pdw96]

문제 — 게이트가 통과시키는 정책 위반

.semgrep/guardian.yml 은 정책을 이렇게 선언한다:

모든 uses: 는 40자 커밋 SHA 로 핀하고 # vN 주석을 단다

그런데 권위적 강제인 scripts/skills-lint.mjs 의 scanWorkflowPins() 는 주석을 검증하지 않는다. 주석을 ref 추출 전에 버린다:

// scripts/skills-lint.mjs
.replace(/\s+#.*$/, '')                 // L49: 주석 제거
...
if (/^[0-9a-f]{40}$/.test(ref)) return  // L57: 완전 SHA 핀 = 통과(주석 유무 무관)

이는 우발적 누락이 아니라 scripts/skills-lint.test.ts:51-54 로 고정된 의도된 동작이다(주석 유/무 양쪽 통과를 단언).

⇒ SHA 와 # vN 주석이 어긋나도 CI 신호가 0이다.

실제 발생 (2026-07-21, #234)

Dependabot 이 actions/setup-node 를 6.4.0 → 7.0.0 으로 올리며 SHA 는 갱신했으나 트레일러 주석은 # v6 그대로 뒀다 — 6곳 전부. skills:lint GREEN, PR 체크 전부 SUCCESS. 사람이 gh api repos/actions/setup-node/git/refs/tags 로 수동 대조해서야 적발했다(머지 전 6cabfba 로 정정).

주석은 6곳에서 유일한 사람-판독 버전 표식인데 거짓을 말하고 있었다. #137 이 이 관례를 도입한 목적(리뷰어가 핀 메이저를 즉시 판별) 자체가 무력화된다. 그리고 SHA 를 바꾸는 다음 범프까지 무기한 잔존한다.

왜 scanWorkflowPins 확장이 답이 아닌가

주석 staleness 실검증은 SHA → 태그 해석이 필요하고 이는 네트워크 의존이다. scanWorkflowPins 는 zero-dep·오프라인 설계이고(Node/Electron CI 에 Python semgrep 툴체인을 더하지 않으려던 #137 의 결정과 동일 계열), 여기에 네트워크를 넣으면 그 설계가 깨진다.

제안 — 별도 주기 워크플로

.github/workflows/ 의 모든 uses: 에 대해 SHA → 태그를 GitHub API 로 해석하고 트레일러 주석과 대조하는 독립 워크플로. 불일치 시 이슈 생성 또는 실패.

• 트리거: weekly cron (+ workflow_dispatch)
• PR 게이트로 걸지 말 것 — 네트워크/레이트리밋 의존이라 required check 로 만들면 flaky 하다. 위생 감시자이지 관문이 아니다.
• 롤링 태그 주의: v1·v6 같은 major alias 는 이동한다. anthropics/claude-code-action 은 의도적으로 # v1(메이저 라인 표기)을 쓰므로 정확 태그 요구는 오탐이 된다 → 정책은 "주석이 SHA 가 속한 태그 집합 중 하나와 정합" 수준이어야 한다.
• 참고: v6 태그는 현재 v6.5.0 을 가리키는데 핀은 v6.4.0 이었다 — 롤링 태그를 베이스라인으로 쓰면 안 된다(chore(deps): bump actions/setup-node from 6.4.0 to 7.0.0 #234 조사에서 실제로 잘못된 델타를 만들었다).

대안 (더 싼 길)

Dependabot 이 트레일러 주석을 갱신하도록 설정할 수 있는지 먼저 확인. 가능하면 이 워크플로 자체가 불필요해진다. 착수 전 이것부터 조사할 것.

참고

• 실측: [[fleet-dependabot-ci-blindspot]] 2026-07-21 2회차
• 정정 커밋: 6cabfba → chore(deps): bump actions/setup-node from 6.4.0 to 7.0.0 #234 (0ed81f9)
• 선행: 보안: GitHub Actions 전부 SHA 핀 + .semgrep/guardian.yml 핀 정책 작성 (관례→강제) #137 (SHA 핀 게이트 도입)

[pdw96]

설계 체크포인트 (착수 전 · 독립 리뷰 요청) — 원안 기각 제안

구현 착수 전 설계 검증을 요청한다. 코드 변경 없음. 본문이 제안한 "별도 주기 워크플로"를 기각하고 더 싼 대체 설계를 제안한다 — 본문 스스로 지시한 "착수 전 Dependabot 대안 조사"의 결과가 전제를 뒤집었기 때문이다.

조사 결과 — Dependabot 이 이미 주석을 갱신한다, 단 조건부로

• Dependabot 은 2022-10-31 부터 SHA 핀 트레일러 주석을 자동 갱신한다(dependabot-core#5951).
• 메커니즘: 주석에서 "이전 버전 문자열"을 찾아 새 버전으로 치환. 따라서 # v6 같은 메이저-only 주석에는 v6.4.0 문자열이 없어 갱신이 침묵으로 스킵된다. chore(deps): bump actions/setup-node from 6.4.0 to 7.0.0 #234 에서 6곳이 stale 로 남은 구조적 원인이 정확히 이것이다.
• 레포 실측 교차확인: 열린 PR chore(deps): bump anthropics/claude-code-action from 1.0.178 to 1.0.179 #238(claude-code-action 1.0.178→1.0.179)도 # v1 을 그대로 두고 SHA 만 갱신 중 — 주석에 1.0.178 이 없어 치환 대상이 아니다. 반면 완전버전형 주석은 치환 대상이 된다(메이저 교차 포함: 주석 속 v6.4.0 → v7.0.0).
• 현재 레포 주석 스타일은 혼재: 메이저-only(# v7 10곳·# v1 2곳·# v4 1곳) vs 완전버전형(# v5.0.0·# v8.0.1·# v7.0.1). 같은 액션(upload-artifact)조차 두 스타일이 공존한다.
• 한정(dependabot-core#7912): 이미 틀린(이전 버전과 불일치하는) 주석은 고쳐주지 않는다 → 최초 마이그레이션이 정확해야 한다.

대체 설계 (2단 · 네트워크 워크플로 0개)

1. 1회성 마이그레이션 PR — .github/workflows/ 전체 uses: 주석을 완전버전형(# vX.Y.Z)으로 통일. SHA→정확 태그 해석은 이 PR 작성 시 1회만 수행하되, 롤링 태그를 베이스라인으로 쓰지 않고 git/refs/tags 전수 대조(chore(deps): bump actions/setup-node from 6.4.0 to 7.0.0 #234 조사 교훈). 이후 Dependabot 이 매 범프마다 주석을 자동 유지한다.
2. scanWorkflowPins 형식 게이트 확장 — "완전 SHA 핀 + 트레일러 주석이 # vX.Y.Z 형식일 것"을 요구. 형식 검사는 오프라인·zero-dep 이므로 보안: GitHub Actions 전부 SHA 핀 + .semgrep/guardian.yml 핀 정책 작성 (관례→강제) #137 의 설계 원칙(CI 네트워크 금지)을 깨지 않으면서 메이저-only 주석의 재유입(수동 편집 경로)을 CI 에서 차단한다. 역할 분리: 게이트=형식, 정합성=Dependabot 자동 갱신.

부수 효과: 본문이 우려한 anthropics/claude-code-action 의 의도적 # v1 오탐 문제는 완전버전형 전환으로 소멸한다(정확 태그 존재·Dependabot 이 매 범프 갱신).

잔여 리스크 (정직 고지)

• 사람이 수동으로 SHA 만 바꾸고 주석을 형식은 유효하지만 stale 한 완전버전으로 남기는 경로는 이 설계도 못 잡는다. 이 잔여를 위해 원안의 SHA→태그 해석 워크플로를 dispatch-only(수동 트리거) 부속으로 남길지는 선택 사항이며 필수가 아니라고 판단한다 — 수동 SHA 편집은 이 레포에서 사실상 일어나지 않는 경로다(전부 Dependabot 경유).

검증 설계

• 마이그레이션 정확성: 각 주석이 해당 SHA 가 속한 태그와 일치함을 PR 본문에 전수 대조표로 첨부.
• 게이트: skills-lint.test.ts 에 형식 위반(메이저-only 주석·주석 부재) fail 케이스 추가 — 기존 테스트 L51-54(주석 유무 양쪽 통과 단언)는 의도 변경으로 갱신된다.
• 실효 검증: 다음 Dependabot 액션 범프 PR 에서 주석 자동 갱신 여부를 관찰(완주 조건).

[pdw96]

@codex review

[chatgpt-codex-connector]

리뷰 결과

변경 요청 — P1: 제안된 대체 설계만으로는 “주석 정합성”을 지속적으로 보장하지 못합니다.

완전버전 형식 게이트는 # vX.Y.Z라는 문자열 모양만 확인합니다. 따라서 사람이 아래처럼 SHA만 수정하면:

uses: owner/action@<new-sha> # v1.2.3

주석이 실제로는 낡았더라도 형식 검사를 통과합니다. Dependabot도 이미 SHA가 바뀐 이후의 잘못된 주석을 사후 복구하지 않는다는 전제이므로, 이 상태는 다음 업데이트까지 무신호로 남습니다. 이는 원래 제기된 “SHA와 버전 주석이 어긋나도 CI 신호가 없다”는 문제를 Dependabot 경로에 대해서만 줄일 뿐, 저장소 불변식으로 해결하지는 않습니다.

현재 검사기는 주석을 명시적으로 제거한 후 SHA만 확인하며, 주석이 없는 완전 SHA도 통과하도록 테스트로 고정되어 있습니다. 또한 실제 워크플로에는 # v1·# v7 같은 메이저 전용 표기가 존재하므로, 제안된 형식 게이트를 적용하려면 전수 마이그레이션이 필요한 것도 확인됩니다.

따라서 다음 중 하나를 설계에 포함해야 합니다.

1. 권장: 비-required 주기 검사 또는 수동 검사를 유지하여 SHA가 실제 태그로 해석되는지 검증합니다.
2. 또는 “정합성은 저장소가 강제하는 불변식이 아니며 Dependabot 생성 PR에만 의존한다”고 명시적으로 범위를 축소하고, 수동 액션 SHA 변경을 리뷰 정책으로 금지합니다.

추가로, 마이그레이션 시 git/refs/tags의 object.sha를 커밋 SHA와 단순 비교하면 annotated tag를 놓칠 수 있습니다. 태그 객체인 경우 최종 커밋까지 역참조한 뒤 비교해야 합니다.

확인

• ✅ sed -n '1,180p' brain.md
• ✅ sed -n '1,180p' scripts/skills-lint.mjs
• ✅ sed -n '1,150p' scripts/skills-lint.test.ts
• ✅ rg -n '^\s*-?\s*uses:' .github/workflows
• ⚠️ curl -L --fail https://github.com/... — 실행 환경에서 GitHub가 HTTP 403을 반환하여 링크된 upstream 이슈·PR의 실시간 내용은 직접 재검증하지 못했습니다.
• ✅ git status --short --branch — 작업 트리가 깨끗하며 리뷰 대상 코드 변경도 없어, 커밋이나 후속 PR은 만들지 않았습니다.

View task →

[pdw96]

설계 개정 v2 (P1 반영 · 재리뷰 요청)

직전 리뷰 P1(형식 게이트는 문자열 모양만 검증 → 수동 SHA 편집 + stale-but-정형 주석 경로가 무신호)을 수용하고 권장안(옵션 1)을 채택한다. 옵션 2(리뷰 정책 의존 범위 축소)는 이 레포의 방향성(#137·#140: 관례 강제화가 아닌 기계 강제)에 역행하므로 불채택. 아래가 개정된 전체 설계이며 이 코멘트가 직전 설계 코멘트를 대체한다(자기완결).

설계 (3단)

1. 1회성 마이그레이션 PR — .github/workflows/ 전체 uses: 주석을 완전버전형(# vX.Y.Z)으로 통일. SHA→정확 태그 해석은 git/refs/tags 전수 대조로 수행하되(롤링 태그 베이스라인 금지 — chore(deps): bump actions/setup-node from 6.4.0 to 7.0.0 #234 교훈), P1 부속 지적 반영: annotated tag 는 refs/tags 의 object.sha 가 tag 객체를 가리킬 수 있으므로 object.type == "tag" 이면 git/tags/{sha} 로 최종 커밋까지 역참조(peel)한 뒤 비교한다. 정확성 근거는 PR 본문에 전수 대조표로 첨부. 이후 Dependabot 이 매 범프마다 주석을 자동 갱신한다(주석이 이전 완전버전 문자열을 포함할 때 치환 — 메이저 교차 포함).
2. scanWorkflowPins 형식 게이트 확장 (오프라인·zero-dep 유지) — "완전 SHA 핀 + 트레일러 주석이 # vX.Y.Z 형식일 것" 요구. 메이저-only 주석·주석 부재의 재유입을 CI 에서 차단. skills-lint.test.ts 의 기존 "주석 유무 양쪽 통과" 단언(L51-54)은 의도 변경으로 갱신.
3. 정합성 안전망: 비-required 주기 조정(reconciliation) 워크플로 (P1 수용으로 원안 워크플로를 안전망 역할로 편입) — weekly cron + workflow_dispatch. 모든 uses: 의 SHA 를 GitHub API 로 태그 해석(1과 동일한 annotated-tag peel 포함)하고 트레일러 주석과 대조, 불일치 시 이슈 생성(실패 required check 아님 — 네트워크/레이트리밋 의존이라 관문 부적격, 원 이슈 본문의 판단 유지). 완전버전형 관례 하에서는 "주석 == SHA 가 속한 태그" 정확 일치를 요구할 수 있어 원안이 우려한 major-alias 오탐(# v1)이 소멸 — 대조 정책이 단순해진다.

역할 분리 (개정)

층	담당	강제 수준
형식 (# vX.Y.Z 존재·모양)	scanWorkflowPins (오프라인)	CI 관문 (required)
정합 유지 (Dependabot 경로)	Dependabot 주석 자동 치환	자동
정합 검증 (수동 편집 포함 전 경로)	주기 조정 워크플로	비-required 안전망 (불일치 → 이슈)

수동 SHA 편집 + stale 정형 주석 경로는 3층에서 최대 1주 지연으로 적발된다 — "무기한 무신호"(원 문제)가 "유계 지연 신호"로 바뀐다.

검증 설계

• 마이그레이션: PR 본문 전수 대조표(annotated peel 결과 포함).
• 게이트: 형식 위반 fail 케이스 테스트(메이저-only·주석 부재·비정형).
• 조정 워크플로: workflow_dispatch 수동 1회 실행으로 현행 전수 GREEN 확인 + 의도적 stale 주석 브랜치로 불일치 적발 1회 실증.
• 실효 관찰: 다음 Dependabot 액션 범프 PR 에서 주석 자동 갱신 확인(완주 조건).

[pdw96]

@codex review

[chatgpt-codex-connector]

리뷰 결과

승인 — 설계 개정 v2에서 추가 P0/P1 차단 이슈를 찾지 못했습니다.

직전 리뷰의 핵심 문제였던 수동 SHA 변경 후 형식상 유효하지만 오래된 주석이 무기한 남는 경로가 3단계의 비-required 주기 정합성 검사에 포함됐습니다. 현재 구현은 주석을 제거한 뒤 SHA만 검사하고 있으며, 주석이 없는 SHA도 통과하도록 테스트되어 있으므로 제안된 형식 게이트와 테스트 갱신이 실제 공백을 정확히 겨냥합니다.

현재 워크플로도 실제로 완전버전 주석과 메이저 전용 주석을 혼용하고 있으므로, 전수 마이그레이션 → 형식 게이트 활성화 순서가 타당합니다. 예를 들어 CI의 checkout과 setup-node는 현재 각각 # v7로 표시되어 있습니다.

구현 시 유지할 세부 조건

아래는 차단 의견은 아니지만 구현 단계에서 테스트 또는 워크플로 계약으로 고정하는 것이 좋습니다.

• 정합성 검사에서는 전체 태그를 매주 전수 조회하기보다, 주석의 정확한 vX.Y.Z 태그를 직접 조회하고 그 태그가 선언된 SHA로 peel되는지 확인하면 API 호출과 레이트리밋 위험을 줄일 수 있습니다.
• annotated tag는 대상이 다시 tag 객체인 경우도 고려해 commit 객체가 나올 때까지 재귀적으로 peel해야 합니다. 비정상 순환이나 과도한 깊이에 대한 상한도 두는 편이 안전합니다.
• 동일한 불일치가 다음 주에도 남았을 때 이슈가 반복 생성되지 않도록 고정 marker나 fingerprint로 기존 열린 이슈를 찾아 갱신하는 멱등성이 필요합니다.
• 해결된 불일치가 사라졌을 때 기존 이슈를 자동 종료할지, 수동 종료할지 정책을 명시하면 “조정(reconciliation)”의 완료 조건이 명확해집니다.
• 외부 액션을 저장소별로 캐시하여 동일 owner/repo + tag 조회를 재사용하고, pagination·404·403·rate-limit은 “정합함”으로 처리하지 말고 검사 자체의 불확실한 실패로 명확히 보고해야 합니다.
• 새 워크플로에는 최소 권한 원칙을 적용해 기본 contents: read와 이슈 생성 단계에 필요한 issues: write만 부여해야 합니다.

외부 GitHub 자료의 실시간 교차검증은 이 환경에서 수행하지 못했지만, 개정 설계의 저장소 내부 전제와 현재 검사 동작은 확인했습니다. 코드 변경 요청이 아닌 설계 리뷰였고 작업 트리가 깨끗했으므로, 커밋이나 후속 PR은 만들지 않았습니다.

확인

• ✅ sed -n '1,180p' brain.md
• ✅ cat AGENTS.md
• ✅ sed -n '1,180p' scripts/skills-lint.mjs
• ✅ sed -n '1,140p' scripts/skills-lint.test.ts
• ✅ rg -n '^\s*-?\s*uses:' .github/workflows
• ✅ find .github/workflows -maxdepth 1 -type f -print | sort
• ✅ nl -ba scripts/skills-lint.mjs | sed -n '35,72p'
• ✅ nl -ba scripts/skills-lint.test.ts | sed -n '35,70p'
• ✅ nl -ba .github/workflows/ci.yml | sed -n '18,36p'
• ✅ git diff --check
• ✅ git status --short --branch
• ⚠️ curl -LfsS https://github.blog/changelog/2022-10-31-dependabot-now-updates-comments-in-github-actions-workflows-referencing-action-versions/ (GitHub가 해당 환경의 요청에 HTTP 403을 반환)
• ⚠️ gh api repos/dependabot/dependabot-core/pulls/5951 --jq '{title,body,merged_at}' (gh CLI가 환경에 설치되어 있지 않음)

View task →