docs(work): FE-GATE-013 desktop 판정을 정하고 스킬 절 인용을 대조한다 #21

Merged
donghyeon.kang merged 4 commits from donghyeon.kang/claude/fe-b-docs-followup-2 AGit into main 2026-11-12 01:58:16 +00:00
4 Commits
Author SHA1 Message Date
DongHyeonka c8b70f5a2b docs(changelog): FE-GATE-013 판정·스킬 절 대조·ungated reason을 적는다
frontend-quality-gates / merge / tests (pull_request) Failing after 13m9s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 8m30s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / merge / static checks (pull_request) Successful in 2m18s
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
문제: desktop FE-GATE-013 판정 규칙, 스킬 절 인용 시험, ungated-tests
reason 번역이 변경 이력에 없다. 절 인용 시험은 자기 문서의 절 이름을 바꾼
다운스트림이 스킬도 같이 고쳐야 통과한다.

고른 방법: 「정리 단계」 절 머리에 이 브랜치 범위를 더하고 「그 밖의
수정」에 세 줄을 더한다.

위험: 커밋 해시는 이 브랜치의 것이다. main이 다시 바뀌어 rebase하면 함께
고친다.

검증: 문서 검사는 desktop에서 돌린다.
2026-11-12 10:49:49 +09:00
DongHyeonka ac19de85ac docs(ci): ungated-tests.json의 reason을 한국어로 옮긴다
문제: config/ci/ungated-tests.json의 reason 6개(같은 문장)가 영어다.
설정 파일의 사람이 읽는 설명 칸은 한국어로 쓴다(docs/README.md 2절).

고른 방법: scripts/lib/ungated-tests.ts는 빈 문자열만 막고, 시험은
reason 내용을 읽지 않는다. 경로·명령·게이트 ID·리뷰 ID는 그대로 두고
문장만 옮겼다. ungated-scripts.json의 같은 scale 이유와 말을 맞췄다.

위험: 없다고 본다. 읽는 코드가 내용을 보지 않는다(위 확인).

검증: diff가 reason 6줄뿐이다(키·순서·항목 수 같음). ungated-tests
시험과 check:ci:gating(FE-GATE-029)은 desktop에서 돌린다.
2026-11-12 10:49:34 +09:00
DongHyeonka bdda84f844 docs(work): desktop FE-GATE-013을 조건부로 merge 판정에서 빼기로 정한다
문제: FE-GATE-013을 멈춤 기준에서 어떻게 셀지가 결정 대기라, desktop에서
merge 판정을 하면 매번 「merge 가능 여부는 소유자가 정한다」로 끝났다.
desktop의 ssh 셸은 비특권 user namespace를 막아 test:system 사전 점검이
호스트 원인으로 실패한다.

고른 방법: 소유자 결정(2026-11-11, 「그 조건이 되는 실행 환경을 찾아
초록으로」)에 따라 총괄이 권하는 안으로 정했다(2026-11-12).
- merge 판정에서 빼는 조건 둘: 실패가 사전 점검의 user namespace 제한
  하나뿐이고, `scripts/verify.sh parts FE-GATE-013`의 뒤 명령이 모두 rc=0.
- 게이트 「충족」은 조건을 갖춘 runner에서 FE-GATE-013이 통과한 것으로만
  센다.
- decisions.md: 3.1절(열린 결정)에서 빼고 2.2절에 결정·버린 안·재검토
  조건을 적었다. evidence.md 행에 결정 번호를 더했다.
- gates.md 3절의 보고 문구, improve.md 멈춤 조건 3, operate.md 4.1절,
  new-feature.md 완료 기준, desktop-gates 스킬 6단계를 새 규칙으로 고쳤다.
버린 안: runner에서 통과할 때까지 merge 판정을 미충족으로 두기. 그
runner가 아직 없어 모든 PR의 merge 판정이 막힌다.

위험: desktop에서 test:system의 provider 테스트는 여전히 돌지 않는다.
그 몫의 결함은 runner가 FE-GATE-013을 돌 때까지 merge 판정에서 안 보인다.
뒤 명령 목록을 옮겨 적지 않고 gates.json `commandIds`를 가리킨다.

검증: python3 scripts/check-work-docs.py OK(지난 ID 줄 0),
python3 -m unittest discover -s scripts/tests 71개 통과. 문서 검사는
desktop에서 돌린다.
2026-11-12 10:49:34 +09:00
DongHyeonka 1b3eee41e3 test(claude): 스킬이 인용하는 절 이름을 문서 제목과 대조한다
문제: 스킬은 정본 문서의 절을 「이름」이나 「N절」로 가리킨다. 문서 검사
(verify:documentation)는 경로만 보므로, 문서를 번역하거나 절을 바꾸면
인용한 절이 사라져도 통과한다. 지금 9곳이 그렇다.
- fe-structure: 「Decision rule」(지금 「판단 규칙」), 「The adapter
  kernel」(지금 「adapter kernel」)
- fe-a11y: 「What the automated run scans」, 「Included primitives」
- fe-design-system: 「Arbitrary-value policy」
- fe-performance: 「Service Worker steps」
- fe-ux: 「routing 6.4절」이 앞 인용(typescript 설계서)의 6.4절로 읽힌다.
  그 설계서에는 6.4절이 없다.
- desktop-gates: 경로 없이 `gates.md`·`operate.md`라고만 쓴다.

고른 방법: scripts/tests/test_claude_setup.py의 SkillTest에 시험을 더한다.
- 모든 repo 스킬에서 읽는 인용 꼴: `경로.md` 「이름」, `경로.md` N절
  (3·4절, 6.1·11절), `경로.md` N절 「이름」, 같은 문서 N절,
  `fe-x` 「이름」(다른 스킬의 절).
- 인용마다 대상 파일에 그 제목이 있는지 본다. 제목은 앞 번호와 끝 괄호를
  뗀 꼴도 받는다. 「이름:」만 있는 소제목 줄도 받는다. 코드 블록 안 제목은
  보지 않는다.
- 파서와 제목 읽기를 따로 고정하는 시험 둘을 함께 둔다.
- 9곳은 지금 제목으로 고치고, 짧게 쓴 경로는 전체 경로로 쓴다.
버린 대안: 문서 검사(scripts/lib/docs-system.ts)에 넣는 방법. 스킬
구성의 다른 규칙이 이미 이 시험 파일에 있고, `scripts/verify.sh hooks`로
노트북에서 바로 돈다.

위험: 「 」 안의 말이 절 이름이 아닌데 경로 바로 뒤에 붙으면 거짓 실패가
난다. 경로 뒤의 —, 괄호, 문장 끝에서 읽기를 멈춰 지금 196개 인용에는 그런
경우가 없다. 「N절」이 다른 문서를 줄여 부르면(「routing 6.4절」) 앞 경로로
읽으니 전체 경로로 쓴다. 이 시험은 게이트가 아니라 hooks 단계에서 돈다.

검증: python3 -m unittest scripts.tests.test_claude_setup.
- 고치기 전: 새 시험이 9곳(과 처음 판에서 거짓 실패 2곳)을 냈다(RED).
- 고친 뒤: 24개 모두 통과했다. 인용 196개를 확인했다.
2026-11-12 10:49:20 +09:00