문제: FE-GATE-013의 test:system은 provider sandbox를 실제로 띄운다.
systemd user manager(systemd-run --user --scope)와 cgroup v2 위임,
bubblewrap(--unshare-net 등)이 필요하다. runner의 job 컨테이너는
entrypoint가 sleep이라 systemd가 없고 bwrap도 없어 사전 점검에서 실패한다
(run 56·80·81). desktop 호스트는 다 있지만 Ubuntu 24.04의
apparmor_restrict_unprivileged_userns=1이 비특권 bwrap을 막는다.
그래서 이 게이트는 runner와 desktop 어디서도 초록인 적이 없다.
고른 방법(소유자 결정 2026-11-11 5절 e: 조건이 되는 실행 환경을 찾는다):
- config/ci/system-container.Dockerfile: Ubuntu 24.04(digest 고정) +
systemd PID 1 + root linger + bubblewrap 등 hostRequirements의 도구.
- scripts/run-in-system-container.sh: 이미지(Dockerfile 해시 태그)가 없으면
만들고, privileged·자체 cgroup namespace로 띄워 systemd와 root user
manager를 기다린 뒤, 작업 트리·git 이력·호출한 쪽의 node와 corepack을
복사해 명령을 root로 돌리고 artifacts/를 되가져온 다음 지운다. root는
호스트의 userns 제한을 받지 않는다.
- gates.json 게이트 필드 hostEnvironment: "system-container"(FE-GATE-013).
생성기는 그 게이트의 run 줄에 래퍼를 붙이고, 실행 검사
(workflowGateExecutionFailures)는 계약이 정한 접두어로 돈 줄만 센다.
scripts/verify.sh gate·parts·stage도 같은 래퍼로 돌린다.
- CI에서는 runner의 Docker proxy로 안쪽 dind daemon을 쓴다(platform-core
gitea-runner README가 「남은 위험」으로 적은 길: proxy가 privileged
컨테이너를 막지 않는다).
- 버린 대안: 전용 VM runner(문서 조건을 그대로 만족하지만 platform-core
변경과 VM 자원·runner 등록이 필요), 호스트 AppArmor profile(호스트
userns 제한을 푸는 보안 설정 변경, 소유자 sudo).
위험·한계:
- root로 돌아 「비특권 runner에서 bwrap userns」 조건 자체는 증명하지
않는다. release 단계 provider job 둘은 아직 job 컨테이너에서 돈다(범위
밖, 같은 래퍼나 VM runner가 필요).
- runner가 rootless dind로 바뀌면 privileged 컨테이너를 못 띄워 깨진다.
- 래퍼 준비(이미지 확인·기동·복사)에 desktop에서 50~60초가 든다.
검증(desktop): 래퍼로 check-system-test-prerequisites → PASS(root),
tests/system/ci-runner/provider-process-group.test.ts 1개 통과.
python3 -m unittest scripts.tests.test_verify 통과, check:ci PASS(게이트 28),
ci-workflow-generation 시험 통과. 게이트 전체(test:system 116개 포함)는 이
브랜치 끝의 merge 단계에서 돈다.
문제: `scripts/verify.sh parts <ID>`는 게이트의 명령을 하나씩 돌리면서
config/ci/gates.json 명령의 `script`만 읽고 `args`를 버린다. 그래서
FE-GATE-009의 `review:a11y-manual -- --format-only`가 인자 없이 돌아
release 증거를 찾다가 rc=1이 되고, production 게이트의
`drill:runbook -- FE-RB-00N --release-root …` 여섯 개도 다른 명령이 된다.
ci:gate(run-ci-gate.ts)는 `pnpm <script> ...args`로 돌려 영향이 없다.
desktop 측정에서 parts만 009를 실패로 냈다.
고른 방법: 계약을 읽는 python이 필드를 \x1f로, args를 \x1e로 나눠
내보내고 bash가 배열로 받아 `corepack pnpm -s <script> ...args`로
돌린다. 탭 구분은 빈 expectedExitCode 칸이 이어지는 탭과 합쳐져
다음 칸이 밀리므로 쓰지 않았다.
위험·한계: args 안에 \x1e·\x1f가 들어가면 잘못 나뉜다. 지금 계약에는
없다.
검증(노트북): python3 -m unittest discover -s scripts/tests 통과.
새 시험은 args가 있는 게이트 7개 모두에서 수정 전 실패, 수정 뒤 통과.
desktop(트리 04bb0e0e)에서 두 가지가 실패했다.
- FE-GATE-010·020: check:adapter-inventory가 "total does not equal 143
tracked files"로 멈췄다. src/adapters의 AGENTS.md·CLAUDE.md 두 행은
더했지만 INVENTORY.md 끝의 합계 줄(141/141)을 고치지 않았다.
- scripts/verify.sh parts FE-GATE-013: verify:reproducible-build,
build:release-candidate, verify:local-evidence가 "missing required CI build
environment: SOURCE_DATE_EPOCH"로 실패했다. ci:gate는 HEAD에서 이 값을
만들지만 parts·script는 명령을 직접 부른다.
합계를 143/143으로 고치고, ci_env가 HEAD 커밋 시각으로 SOURCE_DATE_EPOCH를
준다(ci:gate와 같은 값).
검증: python3 -m unittest discover -s scripts/tests 통과(ci_env가 HEAD
SHA·커밋 시각·digest 꼴 이미지를 주는 시험 추가). desktop 재실행은 이
커밋 트리에서.
계층별 규칙이 Claude만 읽는 .claude/rules/에만 있어 다른 에이전트에는
보이지 않았다. 하네스 자료의 3단계는 레이어마다 그 폴더에 AGENTS.md다.
src/의 9개 계층 폴더마다 AGENTS.md(16~20줄)를 둔다: 그 폴더가 하는 일,
그 폴더에만 걸리는 import 금지(.dependency-cruiser.json에서 from이 그
폴더에 맞는 규칙을 뽑아 이름과 함께), 검사하는 게이트, 테스트 위치. 모든
폴더에 걸리는 규칙은 루트 AGENTS.md와 layers.md를 가리킨다. 옆에
@AGENTS.md 한 줄 CLAUDE.md를 둬 Claude Code가 그 폴더 파일을 열 때 같은
책을 읽는다(백엔드와 같은 짝).
- .claude/rules/adapters·features는 폴더 AGENTS.md를 가리키게 줄였다.
- scripts/check-work-docs.py: src/**/AGENTS.md도 이력 ID 0·200줄·짝·링크를
본다. 훅 N5는 이 파일들을 노트북 확인 파일로 친다.
- docs/reviews/adapters/INVENTORY.md: check:adapter-inventory가 src/adapters
아래 추적 파일을 모두 요구하므로 두 행(142·143)을 더했다.
- 루트 AGENTS.md 지도가 가장 가까운 src/<계층>/AGENTS.md와 비전·문제 정의
양식을 가리킨다.
버린 대안: .claude/rules/만 두기(다른 에이전트가 못 읽는다), 폴더 CLAUDE.md
없이 AGENTS.md만(Claude Code는 같은 폴더에 CLAUDE.md가 없고 Read로 열 때만
읽어 백엔드와 갈린다).
위험·한계: 규칙 이름은 지금 규칙 파일에서 뽑았다. 규칙을 더하거나 바꾸면
이 문서도 손으로 고쳐야 한다(정본은 규칙 파일과 check:architecture).
검증: scripts/verify.sh docs rc=0(src/**/AGENTS.md 9개, 최대 20/200),
python3 -m unittest discover -s scripts/tests 62건 통과.
cold-read 시험에서 두 곳이 막혔다. script 단계가 인자를 넘기지 못해
test:sample-removal -- --feature=<id>를 돌릴 수 없었고, desktop에서
만든 파일(create:feature, 초기 JS 기록 다시 쓰기)을 노트북으로 가져올
길이 없었다. dry-run은 공백 든 인자를 실제와 다르게 보였다.
- script <이름> -- <인자…>: 인자는 script가 하나일 때만 넘긴다.
- exec -- <명령…>: 한 테스트 파일이나 package script가 아닌 node 스크립트.
- 원격에서 바뀐 파일은 로그 폴더의 changes.patch에 남고, --apply-back이면
노트북 작업 트리에 얹는다.
- VERIFY_SNAPSHOT=1이면 artifacts·dist·test-results를 snapshot/에 복사한다
(리뷰어가 함께 읽는 사본). VERIFY_INSTALL=0은 설치를 건너뛴다(시험용).
- dry-run이 인자를 %q로 보인다.
- 원격 호출은 단계 다음에 --on here를 둔다. 뒤에 두면 `--` 뒤 명령
인자가 되어 원격이 자기를 다시 원격으로 보냈다(시험에서 잠금 교착으로
드러났다).
- 원격 준비가 일찍 실패해도 /tmp의 패치 파일을 지운다.
위험·한계: --apply-back은 노트북 작업 트리가 원격 기준과 다르면 패치가
얹히지 않는다. 그때는 rc=4와 원격 패치 경로를 알린다.
검증: python3 -m unittest scripts/tests/test_verify.py 통과(인자 전달,
exec, 잘못된 인자 10가지가 원격 호출 0, 가짜 ssh로 원격에서 만든 파일
둘을 돌려받음, 바뀐 것 없는 단계의 changes.patch는 빈 파일).
작업마다 착수할 때의 예측과 끝날 때의 실측을 남길 곳이 프론트에 없었다.
소유자 결정(2026-11-07 Q11)은 repo마다 docs/ledger/estimates.jsonl이다.
docs/ledger/README.md(백엔드와 같은 형식)와 estimates.jsonl을 두고,
여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않게 .gitattributes가
merge=union을 준다. 첫 줄은 이 작업(fe-c-harness)의 착수 예측이다.
위험·한계: 복사한 프로젝트는 템플릿의 줄을 받는다. README 지워도 되는
표에 "줄을 비운다"로 적는다(뒤 커밋).
검증: python3 -m unittest scripts/tests/test_ledger.py 통과.
Refs: design-docs harness/01-harness-design.md 10절·13절 Q11
desktop에서 게이트를 돌리는 법이 문서와 세션마다 다른 손 절차였다
(checkout 바꾸기·되돌리기, CI env 넣기, runner 스크립트 복사). 같은 빈틈이
되풀이됐고, 공유 checkout의 브랜치를 바꾼 채 두는 위험이 있었다.
scripts/verify.sh <단계>는 claude-harness template/scripts/verify.sh의
운반부를 쓰고 단계를 채운다.
- 단계: config/ci/gates.json의 stage id(merge·release·production·field·
documentation)는 그 gateIds 전부를 ci:gate로, gate <ID>…, parts <ID>(그
게이트의 명령을 하나씩 끝까지, FE-GATE-013 진단용), script <이름>…,
docs·hooks(노트북). stage는 실패가 있어도 끝까지 돌고 게이트마다 rc와
초를 남긴다.
- desktop: 지금 트리를 기준 커밋에 대한 패치로 보내 공유 checkout에서 새
worktree를 만들고, 트리 해시를 맞춘 뒤 commit-tree로 깨끗한 HEAD를 만든다.
CI=true pnpm install --frozen-lockfile --offline 뒤 flock 잠금 아래 CI
env(CI, VITE_COMMIT_SHA, VITE_BUILD_ID, RELEASE_ID, CI_RUNNER_IMAGE)로
돌리고, /tmp/claude-gates/<이름>/에 summary·로그·게이트 산출물·
status-after를 남긴 뒤 worktree를 지운다. push하지 않는다.
- 잘못된 단계·게이트는 desktop에 보내기 전에 노트북에서 거절한다.
버린 대안: 공유 checkout의 브랜치를 잠금 안에서 바꾸고 되돌리기(지금 손
절차). 다른 세션의 checkout을 건드리고, 끝나지 않으면 바뀐 채 남는다.
위험·한계: 새 worktree의 오프라인 설치는 desktop pnpm store에 의존한다.
없으면 온라인 설치로 넘어간다. CI workflow가 아직 이 스크립트를 부르지
않는다(CI 재편 몫).
검증: python3 -m unittest scripts/tests/test_verify.py 통과(stage마다
계약의 gateIds, parts의 명령, 잘못된 인자는 원격 호출 0, 가짜 ssh로
패치 → 같은 트리 해시 → 로그 → worktree 정리, 없는 원격 repo는 rc=4).
desktop에서 실제 운반을 한 번 돌려 트리 해시 일치와 worktree 정리를 봤다.
Refs: design-docs harness/01-harness-design.md 6절
경계 위반, 늘어난 skip·only, 작업 매뉴얼 규칙 위반은 desktop 게이트에서야
드러났고, desktop 검증 없이 턴을 끝내도 아무것도 알리지 않았다.
scripts/hooks/hooks.py(백엔드 hooks.py와 같은 모양, 표준 라이브러리와
git만)를 .claude/settings.json에 단다.
- N3: src TypeScript를 고치면 import를 .dependency-cruiser.json의 forbidden
규칙(path·pathNot·$1)에 그대로 대 본다. 규칙 파일을 읽으므로 규칙이
바뀌면 따라간다.
- N6: 테스트에 .skip·.only·.fixme·.todo가 마지막 커밋보다 늘거나, 예산·
기준선·ungated 목록·스냅숏을 고치면 알린다.
- N2: .md를 고치면 scripts/check-work-docs.py의 실패 줄을 알린다.
- N5: desktop만 확인할 수 있는 파일을 고친 뒤 desktop 실행이 없으면 턴
끝을 한 번 막고 이유를 준다.
모두 넛지다. repo 안 편집에 되돌릴 수 없는 것이 없어 차단 훅은 없다.
고른 방법: 노트북에서는 정적 검사만 하고 포맷·린트·타입은 desktop
scripts/verify.sh에 둔다(brief, 2026-11-08). 설계 13절 Q6은 편집 훅에서
한 파일 eslint를 골랐지만, 프론트 eslint는 pnpm·node_modules가 필요해
"pnpm은 desktop에서만" 규칙과 부딪친다.
위험·한계: N3는 정규식으로 import를 뽑아 주석 속 따옴표 같은 드문
모양을 놓칠 수 있다. 정본은 check:architecture다. 훅 시험은 아직 CI
workflow가 부르지 않는다. 훅은 세션 시작에 읽혀 이 세션에서는 돌지
않았다.
검증: python3 -m unittest scripts/tests/test_hooks.py 26건 통과. 실제
규칙과 src 377개 파일에서 N3 알림 0(거짓 양성 시험). 조건 하나씩 끈
변이 10개를 모두 시험이 잡았다.
Refs: design-docs harness/01-harness-design.md 5.2·5.3절
Claude Code 세션이 테스트·문서·adapter·게이트 기준·기능 폴더를 고칠 때
읽을 규칙이 루트 한 파일에 섞여 있었고, desktop 실행과 새 기능 절차를
부르는 스킬, 결과만 받는 리뷰어 정의가 없었다.
- .claude/rules/: tests, docs, adapters, gates-and-budgets, features.
paths로 그 파일을 열 때만 읽힌다.
- .claude/skills/: desktop-gates(scripts/verify.sh로 desktop에서 돌리기),
new-feature(create:feature부터). 소유자 결정대로 모델이 부르고, 설명에
발동 조건을 문단으로 쓴다. 본문은 정본 playbook을 가리킨다.
- .claude/agents/: arch-reviewer(경계 규칙), verify-app(desktop에서
빌드·브라우저 확인), code-simplifier. 쓰기 도구가 없다.
- .claude/settings.json: 하네스 플러그인 harness@claude-harness를 켜고
실제 .env 읽기·쓰기를 막는다. Agent deny는 두지 않는다.
- .gitignore: .claude/는 이 넷만 추적하고 worktree·훅 상태·
settings.local.json은 무시한다.
버린 대안: Agent deny 유지(소유자 결정 2026-11-07 Q5가 풀었다), 스킬을
사용자 호출 전용으로(Q9가 모델 호출을 골랐다).
위험·한계: 규칙 paths는 지금 있는 파일로 시험하지만 Claude Code가 실제로
읽는지는 이 세션에서 보지 않았다(설정은 세션 시작에 읽힌다).
검증: python3 -m unittest scripts/tests/test_claude_setup.py 통과
(서브에이전트 쓰기 도구 없음, 스킬 설명 길이와 발동 조건, 규칙 paths가
가리키는 파일 있음).
Refs: design-docs harness/01-harness-design.md 13절 Q3·Q5·Q9
루트에는 리뷰 기준만 담은 CLAUDE.md(26줄)가 있었다. 꼭 지킬 경계 규칙,
지도, 검증 진입점, 맡은 일 라우터가 없었고, "서브에이전트를 병렬로"는
소유자 결정(2026-11-07)과 맞지 않았다.
AGENTS.md(35줄)에 무엇인가 · 꼭 지킬 것 5 · 지도 · 맡은 일 · 검증 ·
일하는 방식을 둔다. CLAUDE.md는 @AGENTS.md와 Claude 전용 줄(10줄)이다:
settings·훅, 하네스 플러그인과 비대화형 설치 두 명령, 규칙·스킬·
서브에이전트 위치, 리뷰 기준이 옮겨 간 곳, 소유자 환경. 리뷰 기준과
전체 리뷰 절차는 docs/work/reference/review-criteria.md와
docs/work/improve.md 4.1절로 옮겼다.
scripts/check-work-docs.py는 백엔드 검사기를 옮긴 것이다: 지도 40줄,
CLAUDE.md 15줄, README 80줄, playbook 150줄, 진입 경로 350줄, 9절 뼈대,
진입 문서의 이력 ID 0, 상대 링크. 이력 패턴에 이 repo의 꼴(1105 README,
P-43·O-12·D-14)을 더했다. 표준 라이브러리만 써서 노트북에서 돈다.
버린 대안: CLAUDE.md만 두기(다른 에이전트가 못 읽는다), 심볼릭 링크
(Claude 전용 줄을 둘 수 없다).
위험·한계: 지도 40줄은 자료와 백엔드에 맞춘 값이다. brief 상한 80보다
좁다.
검증: python3 scripts/check-work-docs.py rc=0,
python3 -m unittest scripts/tests/test_check_work_docs.py 통과.
Refs: design-docs harness/01-harness-design.md 4.3절·13절 Q1·Q2