Commit Graph
6 Commits
Author SHA1 Message Date
DongHyeonka fbd8f7d148 chore(review): 1103 게이트·드릴 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 02-06 11-06 12-09 10-01 11-03~11-05 12-02 12-04 12-05 12-08 14-04 16-02

# Conflicts:
#	docs/manual/01-add-a-feature.md
#	docs/manual/02-decision-tables.md
#	docs/manual/reference/patterns.md
2026-11-04 23:08:05 +09:00
DongHyeonka e20b5bfe3a chore(review): 1103 업로드·전송 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 01-01 01-02 01-03
2026-11-04 21:50:46 +09:00
DongHyeonka e1b4e2880d fix(scaffold): 기능 생성 드릴이 merge 단계 명령을 gates.json에서 뽑아 돈다
문제
create:feature는 "모든 merge 게이트를 통과하는 가장 작은 기능"을 만든다고
적고, test:feature-scaffold(FE-GATE-020)가 그 주장을 지키는 유일한 드릴이다.
그런데 드릴은 손으로 적은 15개 명령만 돌았고 merge 단계는 명령 참조가
88개다. 그 범위 밖(시각 회귀, a11y, 번들, 계약·스키마·시나리오 테스트 등)에서
생성 기능을 깨는 템플릿 변경이 생겨도 FE-GATE-020은 통과했다(12-01·12-03이
실제로 그렇게 생겼다). 또 제품 기능 제거 드릴
(test:sample-removal -- --feature=<id>)은 어떤 게이트도 돌지 않아, 빈 사유
결함(16-02)이 드러나지 않았다.

고른 방법
- 새 scripts/lib/feature-scaffold-drill.ts가 fixture의 config/ci/gates.json
  merge 단계를 단계 순서대로, 명령마다 한 번 뽑는다. 음성 fixture 명령은
  run-ci-gate.ts처럼 등록된 종료 코드와 진단 ID로 판정한다.
- 돌지 않는 명령은 SCAFFOLD_DRILL_EXCLUDED_SCRIPTS에 이유와 함께 둔다:
  브라우저 명령 7개(FE-GATE-020 job에 브라우저가 없다. merge_gate matrix
  browser: false), test:system(bubblewrap·systemd·cgroup 필요, 기능과 무관한
  provider 샌드박스 검사), verify:lockfile(연결한 node_modules에 install한다),
  제거 드릴 5개(저장소를 다시 복사한다. 이 드릴 자신 포함). merge 단계에 없는
  스크립트를 제외 목록에 두면 실패한다.
- 생성 기능을 merge 명령 뒤에 test:sample-removal -- --feature=scaffold-feature로
  다시 지운다(16-02 둘째 절반).
- 생성 명령의 주석·Next 출력과 매뉴얼 두 곳의 주장을 실제 범위로 고쳤다.
- 버린 대안: 손 목록에 빠진 명령 더하기. 다음 merge 명령이 다시 빠진다. 복사본
  에서 브라우저 게이트까지 전부(리뷰 5.1 (d)). 드릴 job에 브라우저가 없고 수십
  분이 든다. 생성 경로만 도는 chromium a11y·시각 1회(5.1 (c)). 12-01·12-03을
  고치는 다른 작업이 진행 중이라 지금 넣으면 그 수정 전까지 드릴이 실패한다.
  그 둘이 들어오면 제외 목록에서 빼는 것을 다시 본다.

위험·한계
- 드릴 시간이 크게 는다(빌드·release candidate·coverage·제거 드릴 한 번).
  FE-GATE-020 job(45분)의 임계 경로를 넘으면 리뷰 5.1 재검토 조건대로 줄인다.
  tests/unit이 한 merge에서 도는 횟수(1101/10-06)도 는다.
- 이 커밋 메시지에는 드릴 전체 실행 결과를 적지 않았다(공유 잠금 대기).

검증
- RED: 새 tests/unit/feature-scaffold-drill.test.ts의 "is what
  test:feature-scaffold runs"가 수정 전 실패.
- 수정 뒤 feature-scaffold-drill 5건(merge 명령 전부가 실행 또는 제외, 음성
  fixture 기대 유지, merge 단계에 명령을 더하면 드릴이 돈다, 낡은 제외 거부,
  드릴이 이 목록을 씀), create-feature, removal-fixture 합계 43건 통과.
  verify:documentation PASS_SCOPED, check:types 통과, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-02
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-02
2026-11-04 21:20:04 +09:00
DongHyeonka f3fd10f17c docs(manual): 짝 백엔드에 처음 붙이기 절을 더한다
문제: 제품이 짝 백엔드에 처음 붙을 때 볼 문서가 없다. owner 작성자는
SessionGateway 주석, subject·scope fence 규칙, R-3.2, recover 규약을
여러 파일에서 모아야 하고, 백엔드가 무엇을 주고 무엇을 안 주는지(realm의
브라우저 client, 로그인·로그아웃·세션 엔드포인트)는 백엔드 코드를 읽어야
안다.

고른 방법: docs/manual/04-paired-backend-session.md를 새로 둔다.
- 두 모드 비교표와 근거 위치(백엔드 bbe944bd의 SecurityConfig,
  security.yml, application-local.yml, realm JSON).
- 공통 준비: AUTH_MODE external, 백엔드 local CORS 출처
  http://localhost:3000에 맞춘 dev 포트, owner context 필드, recipe는
  복사(import 금지).
- jwt: 흐름도, realm에 더할 public client JSON(audience mapper 포함),
  제품 설정 키 OIDC_ISSUER·OIDC_CLIENT_ID, product-composition 예시,
  하지 않는 것(새로고침 로그아웃, ID token 서명, id_token_hint).
- redis-session: 흐름도, 제품이 더할 엔드포인트 셋과 CSRF 토큰 읽기,
  프로필을 product-contracts.ts에 옮겨 적는 이유, 예시, 같은 host 조건.
- 상태 전이 표, 확인 방법(실제 백엔드 e2e는 아직 없음), 증상별 원인.
매뉴얼 README·02 §5, starter-experience·foundation·optional-adapter-
recipes에는 위치만 가리키는 줄을 더했다. 백엔드 표는 복사하지 않고 위치만
적었다(매뉴얼 README 규칙).

위험·한계: 백엔드 설정이 바뀌면 이 문서가 낡는다. 기준 커밋을 문서
첫머리에 적었다. Keycloak client JSON은 실제 Keycloak에 넣어 보지 않았다.

검증: verify:documentation PASS_SCOPED(새 문서와 고친 문서 모두 경로·
명령·게이트 ID 누락 0).

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-03
2026-11-04 20:51:51 +09:00
DongHyeonka af4ebacb68 docs(browser-transfer): presigned 업로드 레시피가 짝 백엔드와 맞지 않음을 적는다
문제: 프론트 업로드 레시피(PRESIGNED_MULTIPART_V1, 브라우저가 object
store에 직접 PUT)를 받는 서버가 짝 백엔드 템플릿에 없다. 짝 백엔드는
2026-09-25에 presigned·direct multipart 코드를 지웠고, 파일은 자기
Fileserver가 직접 받는다(POST /v1/files, POST /v1/files:raw, tus). 그런데
서버 handoff 문서는 아직 "서버 구현 대기", "이후 서버 template에서 구현"
이라고 적고, docs/manual에는 업로드 언급이 없다. 팀은 조립 단계에서야
짝이 아님을 안다.

고친 방법(리뷰 D1 (다)):
- server-file-capability-infrastructure.md 상태 줄을 "짝 백엔드 템플릿은
  구현하지 않음(2026-09-25 제거)"으로, 대상을 "제품 backend가 직접 구현"
  으로 고치고 짝 아님 안내를 머리에 둔다.
- presigned-transfer-and-image-cdn.md 머리에 같은 안내를 둔다. presigned
  다운로드와 private Image CDN descriptor 발급 서버도 짝 백엔드에 없다.
- 레시피 카탈로그 file-transfer의 fallback에 짝 백엔드 경로(Fileserver
  POST /v1/files)를 적는다.
- docs/manual/02-decision-tables.md에 7절 "파일 업로드"를 더한다. 두 경로
  비교와 고르는 기준이다. 매뉴얼 README의 목차 줄도 고친다.

위험·한계: 문서만 바꾼다. 짝 백엔드로 파일을 올리는 프론트 client는 이
커밋에 없다(다음 커밋, D1 (나-1)). 백엔드 매뉴얼에 같은 안내를 적는 일은
백엔드 repo 몫이라 하지 않았다.

검증:
- verify:documentation PASS_SCOPED
- check:optional-recipes:source PASS (file-transfer 56,084/57,800)

Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01
2026-11-04 20:42:36 +09:00
DongHyeonka 8b2048763b docs(manual): 새 기능 추가 매뉴얼을 docs/manual에 쓴다 (U9, 1101/16-01)
문제
- 새 기능을 추가하는 절차가 starter-experience.md의 영어 단계 7개와
  폴더 밖 파일 표뿐이다. 무엇을 고르는지(context, 계약 출처, 재시도 의미,
  결과 불명, 인증, 페이지 템플릿), 어느 검사가 무엇을 못 잡는지, 실패
  메시지가 어느 파일을 가리키는지는 리뷰 문서(16 영역 8절)에만 있다.
  리뷰 문서는 복사한 프로젝트가 지울 수 있는 작업 이력이다.
- create:feature(U7)가 생겼지만 그 인자, 만드는 파일, 사람이 해야 하는 일
  (a11y 서명, 자리표시자 계약 신원 교체)을 설명하는 문서가 없다.

고른 방법
- docs/manual/을 한국어로 쓴다(결정 5). README(독자, 읽는 순서, 두는 것과
  안 두는 것), 01 작업 순서 0~11단계, 02 결정표 6개, 03 기능 폴더 밖 파일,
  reference/ 4개(create-feature, global-ids, patterns, errors).
- 01은 1단계에서 create:feature로 시작하는 길을 기본으로 두고, 단계마다
  정할 것, 기준, 잡는 검사(명령·게이트 ID·메시지)와 못 잡는 것, 쓸 스킬을
  적는다. 리뷰 시점의 "못 잡음"은 지금 코드로 다시 확인해 고쳤다(예: 루트
  밖 라우트는 이제 앱 모듈이 적재 때 거부한다).
- 실패 메시지는 src·scripts의 문자열을 그대로 옮기고 값 자리만 <...>로
  바꿨다.
- 목록 대신 정본 위치를 적는다(공통 원칙 8). route ID는 ROUTE_REGISTRY,
  게이트는 config/ci/gates.json, 백엔드 멱등성 응답은 백엔드 템플릿
  docs/web/http-contract.md §2를 가리키고 표를 옮기지 않는다. 공통 원칙은
  design-docs의 conventions/feature-design-principles.md를 번호로만
  가리킨다.
- 03은 starter-experience.md의 폴더 밖 표를 정본으로 링크하고 복사하지
  않는다. 생성 명령이 하는 것 / 사람이 꼭 하는 것 / 조건부 / 고치지 않는
  것으로 나누고, 표에 없는 절차(a11y 서명, 자리표시자 교체, 기능 삭제)만
  더한다.
- 16 영역 8.4의 금지 목록(목표 디렉터리 구조 절, 예전 폴더 밖 표, 참조
  페이지의 경로 문자열)은 링크하지 않고 README에 그 이유를 적는다.
- 버린 대안: 리뷰 8절을 그대로 옮기기(리뷰 시점 사실이 지금 코드와 다르고
  지울 수 있는 이력에 기댄다), starter-experience.md에 한국어 절을 더하기
  (입구 문서는 영어이고 다른 에이전트 소유다), 실패 메시지를 요약해 쓰기
  (메시지로 문서를 검색할 수 없다).

위험·한계
- docs/README.md §1 링크는 넣지 않았다(오케스트레이터 몫). 링크하기 전에는
  verify:documentation이 이 폴더를 검사하지 않는다. 폴더 링크는 바로 아래
  .md만 검사하므로 reference/도 따로 링크해야 한다.
- 플랫폼 규칙 근거는 다른 에이전트가 옮기는 scale-architecture.md를 절
  번호로 가리킨다. 이 커밋에는 그 파일이 없어 링크 대신 백틱 이름으로 썼다.
- 매뉴얼로 막을 수 없는 것이 남는다. 기능 전용 e2e spec은 tests/e2e에만
  둘 수 있어 기능 폴더 밖이다. --context reference-context는 참조 기능
  테스트 하나를 깨뜨린다. 생성 드릴은 check:bundle을 돌리지 않는다.
- "실험 E를 매뉴얼만 보고 다시 하기"는 문서로만 점검했고 실제로 다시
  돌리지 않았다.

검증
- docs/README.md §1에 manual/, manual/reference/ 링크를 임시로 넣고
  node scripts/verify-documentation-readiness.ts: PASS_SCOPED. 7개 문서
  모두 missingPaths·missingScripts·unknownGateIds 0. 임시 링크는 되돌렸다.
- 변이: patterns.md에 없는 경로·script·게이트 ID를 넣으면 세 항목을 모두
  말하며 FAIL_UNVERIFIED.
- 메시지 대조 스크립트: 백틱 안 148개 문구 중 106개는 코드에 그대로 있고,
  42개는 코드가 조각을 이어 만드는 문구(접두어·필드 이름·값 채움)라 하나씩
  코드에서 확인했다.
- node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts
  tests/unit/deletable-history-documents.test.ts
  tests/unit/repository-file-inventory.test.ts: 3파일 38건 통과.
2026-11-03 07:27:36 +09:00