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
Owner

무엇을, 왜

PR #20 뒤에 남은 후속 셋을 처리한다.

  1. desktop FE-GATE-013 판정(결정 D8). 이 게이트를 어떻게 셀지가 결정 대기라, desktop merge 판정은 매번 「merge 가능 여부는 소유자가 정한다」로 끝났다. 소유자 결정(2026-11-11, 「그 조건이 되는 실행 환경을 찾아 초록으로」)에 따라 총괄이 권하는 안으로 정했다(2026-11-12).
    • merge 판정에서 빼는 조건은 둘이다. 실패가 사전 점검의 user namespace 제한 하나뿐이어야 하고, scripts/verify.sh parts FE-GATE-013의 뒤 명령이 모두 rc=0이어야 한다.
    • 게이트 「충족」은 조건을 갖춘 runner에서 FE-GATE-013이 통과한 것으로만 센다.
    • 고친 곳:
      • docs/work/reference/decisions.md: 3.1절에서 빼고 2.2절에 결정을 적었다.
      • 새 규칙과 보고 문구를 적은 곳: gates.md 3절, improve.md 멈춤 조건 3, operate.md 4.1절, new-feature.md 완료 기준, desktop-gates 스킬 6단계, evidence.md.
  2. 스킬 절 인용 대조. 스킬이 「절 이름」·「N절」로 가리키는 절이 그 문서에 있는지 보는 시험을 scripts/tests/test_claude_setup.py에 더했다. 문서 검사는 경로만 봐서, 번역으로 사라진 절 9곳을 놓치고 있었다. 9곳은 지금 제목으로 고쳤다.
    • fe-structure: 「Decision rule」→「판단 규칙」, 「The adapter kernel」→「adapter kernel」
    • fe-a11y: 「What the automated run scans」→「자동 실행이 검사하는 것」, 「Included primitives」→「들어 있는 primitive」
    • fe-design-system: 「Arbitrary-value policy」→「임의 값(arbitrary value) 정책」
    • fe-performance: 「Service Worker steps」→「Service Worker 절차」
    • fe-ux: 「routing 6.4절」을 routing 설계서의 전체 경로로 바꿨다. 앞 인용(typescript 설계서)에는 6.4절이 없다.
    • desktop-gates: 경로 없이 쓴 gates.md·operate.md를 전체 경로로 바꿨다.
  3. config/ci/ungated-tests.json reason 6개를 한국어로 옮겼다.
  4. desktop의 임시 ref 넷을 지웠다. claude/fe-b-docs-followup, -r1~-r3이다. 저장소 변경은 아니다.

고른 방법과 버린 대안

  • D8에서 버린 안은 「runner에서 통과할 때까지 merge 판정을 미충족으로 두기」다. 그 runner가 아직 없어서 모든 PR의 merge 판정이 막힌다.
  • 뒤 명령 목록은 옮겨 적지 않았다. gates.md 3절은 config/ci/gates.json의 FE-GATE-013 commandIds를 가리킨다.
  • 절 대조 시험은 문서 검사(scripts/lib/docs-system.ts)가 아니라 test_claude_setup.py에 두었다. 스킬 구성의 다른 규칙이 이미 그 파일에 있고, 노트북에서 scripts/verify.sh hooks로 바로 돈다.
  • 시험이 읽는 인용 꼴: 경로.md 「이름」, 경로.md N절(3·4절, 6.1·11절), 경로.md N절 「이름」, 같은 문서 N절, fe-x 「이름」(다른 스킬의 절).
  • 시험이 받는 제목:
    • 앞 번호와 끝 괄호를 뗀 꼴도 받는다. 예: 토큰 CSS 검사 규칙 (check:design-system).
    • 「이름:」만 있는 소제목 줄도 받는다. 예: 임의 값(arbitrary value) 정책:.
    • 코드 블록 안 제목은 보지 않는다.
    • 파서와 제목 읽기를 따로 고정하는 시험 둘을 함께 두었다.

위험과 영향

  • desktop에서 test:system의 provider 테스트는 여전히 돌지 않는다. 그 몫의 결함은 runner가 FE-GATE-013을 돌 때까지 merge 판정에서 보이지 않는다. 그래서 「충족」은 runner 통과로만 센다.
  • 절 대조 시험의 위험:
    • 거짓 실패: 「 」 안의 말이 절 이름이 아닌데 경로 바로 뒤에 붙으면 실패한다. 경로 뒤의 —, 괄호, 문장 끝에서 읽기를 멈춰서, 지금 인용 196개에는 그런 경우가 없다.
    • 줄여 쓴 문서 이름: 「routing 6.4절」처럼 다른 문서를 줄여 부르면 앞 경로의 절로 읽는다. 전체 경로로 써야 한다.
    • 게이트 밖: 이 시험은 게이트가 아니라 hooks 단계(python3 -m unittest discover -s scripts/tests)에서 돈다.
  • 자기 문서의 절 이름을 바꾸는 다운스트림은 그 절을 인용하는 스킬도 같이 고쳐야 시험이 통과한다. CHANGELOG에 적었다.
  • guardian 시험의 3초 lease 문제는 이 PR 밖이다. FE-A가 시간 제한 문제와 함께 맡는다.
  • desktop에 #15 때 올린 claude/fe-b-docs-korean-645f55 ref가 남아 있다. 이번 지시의 범위 밖이라 지우지 않았다.

검증

desktop의 깨끗한 checkout(~/workspace/clean-architecture-frontend-template-lanes/FEB/wt)에서 돌렸다. head는 c8b70f5a, base는 main d2239c67이다. 잠금 flock /tmp/claude-gates/heavy.lock을 한 번 잡고 그 안에서 돌렸고, load average는 약 2.5였다.

검사 결과
FE-GATE-017 (verify:documentation) PASS. 문서 검사 여섯 가지 모두 0건이다. 짝 백엔드 checkout이 없어 백엔드 참조는 확인하지 못했다(PASS_SCOPED, 전과 같음)
FE-GATE-029 (검사기 자기 시험, check:ci:gating) PASS
관련 단위 시험 9개 파일 107개 통과. ungated-tests·ungated-scripts·test-all-paths·template-contract-documents·documentation-readiness·docs-system·deletable-history-documents·feature-tracked-files·runbook-drill
scripts/verify.sh docs (작업 문서) OK. 지난 ID 줄 0
scripts/verify.sh hooks (python 시험) 71개 통과. 노트북에서도 같다
  • 절 대조 시험은 먼저 실패하는 것을 봤다. 고치기 전에 진짜 깨진 인용 9곳이 나왔다. 처음 판은 제목 끝 괄호와 「이름:」 소제목 줄을 몰라 거짓 실패도 2곳 냈고, 이 둘은 시험을 고쳐 받게 했다.
  • 고친 뒤 인용 196개가 모두 맞는다.
  • merge 단계 전체는 돌리지 않았다. 이 PR은 문서·스킬·python 시험·설정 설명 칸만 바꾸고, 바꾼 파일을 읽는 시험은 위에서 돌렸다. 바로 앞 PR #20의 merge 단계 결과는 그 PR 본문에 있다.

리뷰어가 볼 곳

  • docs/work/reference/gates.md 3절의 두 조건과 보고 문구. 결정 색인 2.2절 D8 행과 뜻이 같은지 본다.
  • scripts/tests/test_claude_setup.py의 cited_sections·headings와 자기 시험 둘.

관련

  • PR #15, PR #20, docs/work/reference/decisions.md 2.2절
## 무엇을, 왜 PR #20 뒤에 남은 후속 셋을 처리한다. 1. **desktop FE-GATE-013 판정(결정 D8).** 이 게이트를 어떻게 셀지가 결정 대기라, desktop merge 판정은 매번 「merge 가능 여부는 소유자가 정한다」로 끝났다. 소유자 결정(2026-11-11, 「그 조건이 되는 실행 환경을 찾아 초록으로」)에 따라 총괄이 권하는 안으로 정했다(2026-11-12). - merge 판정에서 빼는 조건은 둘이다. 실패가 사전 점검의 user namespace 제한 하나뿐이어야 하고, `scripts/verify.sh parts FE-GATE-013`의 뒤 명령이 모두 rc=0이어야 한다. - 게이트 「충족」은 조건을 갖춘 runner에서 FE-GATE-013이 통과한 것으로만 센다. - 고친 곳: - `docs/work/reference/decisions.md`: 3.1절에서 빼고 2.2절에 결정을 적었다. - 새 규칙과 보고 문구를 적은 곳: `gates.md` 3절, `improve.md` 멈춤 조건 3, `operate.md` 4.1절, `new-feature.md` 완료 기준, `desktop-gates` 스킬 6단계, `evidence.md`. 2. **스킬 절 인용 대조.** 스킬이 「절 이름」·「N절」로 가리키는 절이 그 문서에 있는지 보는 시험을 `scripts/tests/test_claude_setup.py`에 더했다. 문서 검사는 경로만 봐서, 번역으로 사라진 절 9곳을 놓치고 있었다. 9곳은 지금 제목으로 고쳤다. - `fe-structure`: 「Decision rule」→「판단 규칙」, 「The adapter kernel」→「adapter kernel」 - `fe-a11y`: 「What the automated run scans」→「자동 실행이 검사하는 것」, 「Included primitives」→「들어 있는 primitive」 - `fe-design-system`: 「Arbitrary-value policy」→「임의 값(arbitrary value) 정책」 - `fe-performance`: 「Service Worker steps」→「Service Worker 절차」 - `fe-ux`: 「routing 6.4절」을 routing 설계서의 전체 경로로 바꿨다. 앞 인용(typescript 설계서)에는 6.4절이 없다. - `desktop-gates`: 경로 없이 쓴 `gates.md`·`operate.md`를 전체 경로로 바꿨다. 3. **`config/ci/ungated-tests.json` reason 6개를 한국어로 옮겼다.** 4. **desktop의 임시 ref 넷을 지웠다.** `claude/fe-b-docs-followup`, `-r1`~`-r3`이다. 저장소 변경은 아니다. ## 고른 방법과 버린 대안 - D8에서 버린 안은 「runner에서 통과할 때까지 merge 판정을 미충족으로 두기」다. 그 runner가 아직 없어서 모든 PR의 merge 판정이 막힌다. - 뒤 명령 목록은 옮겨 적지 않았다. `gates.md` 3절은 `config/ci/gates.json`의 FE-GATE-013 `commandIds`를 가리킨다. - 절 대조 시험은 문서 검사(`scripts/lib/docs-system.ts`)가 아니라 `test_claude_setup.py`에 두었다. 스킬 구성의 다른 규칙이 이미 그 파일에 있고, 노트북에서 `scripts/verify.sh hooks`로 바로 돈다. - 시험이 읽는 인용 꼴: `경로.md` 「이름」, `경로.md` N절(`3·4절`, `6.1·11절`), `경로.md` N절 「이름」, 같은 문서 N절, `fe-x` 「이름」(다른 스킬의 절). - 시험이 받는 제목: - 앞 번호와 끝 괄호를 뗀 꼴도 받는다. 예: `토큰 CSS 검사 규칙 (`check:design-system`)`. - 「이름:」만 있는 소제목 줄도 받는다. 예: `임의 값(arbitrary value) 정책:`. - 코드 블록 안 제목은 보지 않는다. - 파서와 제목 읽기를 따로 고정하는 시험 둘을 함께 두었다. ## 위험과 영향 - desktop에서 `test:system`의 provider 테스트는 여전히 돌지 않는다. 그 몫의 결함은 runner가 FE-GATE-013을 돌 때까지 merge 판정에서 보이지 않는다. 그래서 「충족」은 runner 통과로만 센다. - 절 대조 시험의 위험: - 거짓 실패: 「 」 안의 말이 절 이름이 아닌데 경로 바로 뒤에 붙으면 실패한다. 경로 뒤의 —, 괄호, 문장 끝에서 읽기를 멈춰서, 지금 인용 196개에는 그런 경우가 없다. - 줄여 쓴 문서 이름: 「routing 6.4절」처럼 다른 문서를 줄여 부르면 앞 경로의 절로 읽는다. 전체 경로로 써야 한다. - 게이트 밖: 이 시험은 게이트가 아니라 hooks 단계(`python3 -m unittest discover -s scripts/tests`)에서 돈다. - 자기 문서의 절 이름을 바꾸는 다운스트림은 그 절을 인용하는 스킬도 같이 고쳐야 시험이 통과한다. CHANGELOG에 적었다. - guardian 시험의 3초 lease 문제는 이 PR 밖이다. FE-A가 시간 제한 문제와 함께 맡는다. - desktop에 #15 때 올린 `claude/fe-b-docs-korean-645f55` ref가 남아 있다. 이번 지시의 범위 밖이라 지우지 않았다. ## 검증 desktop의 깨끗한 checkout(`~/workspace/clean-architecture-frontend-template-lanes/FEB/wt`)에서 돌렸다. head는 `c8b70f5a`, base는 main `d2239c67`이다. 잠금 `flock /tmp/claude-gates/heavy.lock`을 한 번 잡고 그 안에서 돌렸고, load average는 약 2.5였다. | 검사 | 결과 | | --- | --- | | FE-GATE-017 (`verify:documentation`) | PASS. 문서 검사 여섯 가지 모두 0건이다. 짝 백엔드 checkout이 없어 백엔드 참조는 확인하지 못했다(`PASS_SCOPED`, 전과 같음) | | FE-GATE-029 (검사기 자기 시험, `check:ci:gating`) | PASS | | 관련 단위 시험 9개 파일 | 107개 통과. ungated-tests·ungated-scripts·test-all-paths·template-contract-documents·documentation-readiness·docs-system·deletable-history-documents·feature-tracked-files·runbook-drill | | `scripts/verify.sh docs` (작업 문서) | OK. 지난 ID 줄 0 | | `scripts/verify.sh hooks` (python 시험) | 71개 통과. 노트북에서도 같다 | - 절 대조 시험은 먼저 실패하는 것을 봤다. 고치기 전에 진짜 깨진 인용 9곳이 나왔다. 처음 판은 제목 끝 괄호와 「이름:」 소제목 줄을 몰라 거짓 실패도 2곳 냈고, 이 둘은 시험을 고쳐 받게 했다. - 고친 뒤 인용 196개가 모두 맞는다. - merge 단계 전체는 돌리지 않았다. 이 PR은 문서·스킬·python 시험·설정 설명 칸만 바꾸고, 바꾼 파일을 읽는 시험은 위에서 돌렸다. 바로 앞 PR #20의 merge 단계 결과는 그 PR 본문에 있다. ## 리뷰어가 볼 곳 - `docs/work/reference/gates.md` 3절의 두 조건과 보고 문구. 결정 색인 2.2절 D8 행과 뜻이 같은지 본다. - `scripts/tests/test_claude_setup.py`의 `cited_sections`·`headings`와 자기 시험 둘. ## 관련 - PR #15, PR #20, `docs/work/reference/decisions.md` 2.2절
donghyeon.kang added 4 commits 2026-11-12 01:52:14 +00:00
문제: 스킬은 정본 문서의 절을 「이름」이나 「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개를 확인했다.
문제: 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에서 돌린다.
문제: 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에서 돌린다.
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
c8b70f5a2b
문제: desktop FE-GATE-013 판정 규칙, 스킬 절 인용 시험, ungated-tests
reason 번역이 변경 이력에 없다. 절 인용 시험은 자기 문서의 절 이름을 바꾼
다운스트림이 스킬도 같이 고쳐야 통과한다.

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

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

검증: 문서 검사는 desktop에서 돌린다.
donghyeon.kang merged commit 6b4f703c59 into main 2026-11-12 01:58:16 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-frontend-template#21