문제 verify:documentation(FE-GATE-017)은 짝 백엔드 경로·링크를 옆 checkout의 작업 트리에서 찾았다. 그래서 같은 커밋이 놓인 곳마다 결과가 달랐다. desktop은 옆 checkout이 ef947e5(9월)에 미커밋 변경까지 있어 문서와 무관하게 rc=1, 짝이 없는 worktree는 PASS(17개 미확인)였다. 옆 checkout이 pin보다 새로우면 pin에 없는 파일을 적어도 통과하고, 저장소 이름을 틀린 `../` 링크는 "확인 못 함"으로 통과했다. config/contracts/backend-contract-pin.json은 읽지 않았다. 고른 방법 - 짝 저장소 목록과 기준 커밋을 pin 파일에서 읽는다. pin은 문서와 같이 작업 디렉터리에서 읽는다(문서가 어느 커밋을 설명하는지 적은 파일이라서). - 옆 checkout에 pin 커밋이 있으면 `git ls-tree -r -t <pin>`으로 그 커밋의 트리(파일과 폴더)를 한 번 읽어 찾는다. 작업 트리와 HEAD는 보지 않는다. hook이 넘긴 GIT_DIR 같은 GIT_* 변수는 지우고 git을 부른다. - checkout이 없거나, pin 커밋이 없거나, git이 읽지 못하면 실패 대신 unverifiedLinks로 남기고, 출력에 이유(짝 HEAD, pin 앞 12자)를 적는다. - `../`로 나가는 링크의 첫 폴더가 pin에 없는 저장소면 missingPaths로 실패한다. 실패하면 "pin 커밋에서 찾았다"는 줄을 stderr에 하나 더 적는다. - 버린 대안: 짝 HEAD가 pin과 다르면 전부 unverified(리뷰 (c)). 더 단순하지만 pin 뒤로 앞서 있는 흔한 checkout에서 아무것도 확인하지 못한다. 경로마다 `git cat-file -e`: 같은 결과지만 참조 수만큼 프로세스를 띄운다. 위험·한계 - pin 커밋을 fetch하지 않은 checkout(desktop 지금 상태)에서는 짝 참조가 전부 "not verified"다. 실패하지 않는 대신 확인도 하지 않는다. - 짝 저장소는 여전히 하나(pin 파일의 backend)다. 둘째 짝이 생기면 pin 모양부터 바꿔야 한다. - pin 파일이 없으면 짝 저장소가 없는 것으로 보고 `../` 링크를 전부 실패로 센다. - 보고서 schema는 그대로다(unverifiedLinks 주석만 고침). 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts, 그리고 corepack pnpm verify:documentation(옆 짝이 ef947e5인 desktop에서 PASS_SCOPED + not verified 기대). - RED 기대: "looks a reference up in the pinned commit, not in a later HEAD or the working tree", "reports the references as not verified when the checkout does not have the pinned commit", "fails a link out of the repository into a repository that is not paired". Refs: 1105/12-02
89 lines
8.5 KiB
Markdown
89 lines
8.5 KiB
Markdown
# 문서 색인
|
|
|
|
`docs/`의 문서를 세 묶음으로 나눈다.
|
|
|
|
```text
|
|
1. 현재 계약 지금 코드가 지키는 규칙. 게이트가 검사한다
|
|
2. 목표 설계 앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
|
|
3. 작업 이력 리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다
|
|
```
|
|
|
|
문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는
|
|
문서 안의 상태 값(`COMPOSED`, `AVAILABLE_NOT_COMPOSED`, `DESIGNED_NOT_IMPLEMENTED` 등)으로
|
|
확인한다. 상태 값의 뜻은 `README.md`의 "Support scope" 절에 있다.
|
|
|
|
README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.
|
|
|
|
## 1. 현재 계약
|
|
|
|
처음 읽을 입구 문서 6개다.
|
|
|
|
| 문서 | 정하는 것 |
|
|
|---|---|
|
|
| [`README.md`](../README.md) | 시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영 |
|
|
| [`architecture/frontend-application-foundation.md`](architecture/frontend-application-foundation.md) | 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계 |
|
|
| [`architecture/layers.md`](architecture/layers.md), [`architecture/overview.md`](architecture/overview.md) | 계층과 import 방향. `check:architecture`가 검사한다 |
|
|
| [`architecture/starter-experience.md`](architecture/starter-experience.md) | 기본 라우트, 인증 모드, 기능 추가·제거 절차 |
|
|
| [`architecture/optional-adapter-recipes.md`](architecture/optional-adapter-recipes.md) | 선택 기능(recipe)을 넣고 빼는 절차 |
|
|
| [`operations/ci-quality-gates.md`](operations/ci-quality-gates.md), [`testing/taxonomy.md`](testing/taxonomy.md) | 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선 |
|
|
|
|
입구 문서가 가리키는 세부 규칙:
|
|
|
|
- 새 기능 추가 매뉴얼(작업 순서, 단계별 판단 기준, `create:feature`): [`manual/`](manual/), [`manual/reference/`](manual/reference/). 한국어다
|
|
- 규모 설계(구조·소유·실행·트래픽·오류·검증·텔레메트리·릴리스 일관성)와 코드 주석 `scale-architecture.md §N`의 근거: [`architecture/scale-architecture.md`](architecture/scale-architecture.md). 절마다 현재 계약인지 기록만인지 머리말 표에 적었다
|
|
- 계약 소유와 호환성: [`architecture/contract-ownership.md`](architecture/contract-ownership.md), [`contracts/compatibility.md`](contracts/compatibility.md)
|
|
- 짝 백엔드 Envelope 판정과 쓰기 전 거절 표(지금 실행 규칙, `src/adapters/http/backend-envelope.ts`의 근거): [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md) 4.1·6·6.1절. 기준 커밋은 [`../config/contracts/backend-contract-pin.json`](../config/contracts/backend-contract-pin.json). 같은 문서의 나머지 절은 목표 설계다
|
|
- 정적 배포와 런타임 설정: [`architecture/static-delivery.md`](architecture/static-delivery.md)
|
|
- 기능 개발자가 알아야 하는 양: [`architecture/capability-consumer-experience.md`](architecture/capability-consumer-experience.md)
|
|
- 운영·복구: [`operations/`](operations/), [`runbooks/`](runbooks/)
|
|
- 보안과 공급망: [`security/browser-boundary.md`](security/browser-boundary.md), [`security/supply-chain.md`](security/supply-chain.md)
|
|
- 디자인 토큰과 수동 접근성 검토: [`styling/design-tokens.md`](styling/design-tokens.md), [`accessibility/manual-checklist.md`](accessibility/manual-checklist.md)
|
|
- 버전별 변경: [`../CHANGELOG.md`](../CHANGELOG.md)
|
|
|
|
`verify:documentation`은 이 파일과 이 절에서 링크한 문서(폴더 링크는 그 안의 `.md` 전부)에
|
|
적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지 검사한다. 명령(인라인 코드와
|
|
셸 코드 블록) 안의 경로 인자도 본다. 짝 백엔드 템플릿(`clean-architecture-backend-template`)의
|
|
경로와 링크는 `config/contracts/backend-contract-pin.json`이 고정한 커밋의 트리에서 찾는다.
|
|
이 checkout 옆에 있는 짝 checkout의 git 기록을 읽고, 그 작업 트리와 HEAD는 보지 않는다. 짝
|
|
checkout이 없거나 그 커밋이 없으면 실패 대신 확인하지 못한 것으로 출력과
|
|
`artifacts/quality/documentation-review.json`에 남긴다. repo 밖으로 나가는 링크가 짝 저장소를
|
|
가리키지 않으면(저장소 이름 오타 포함) 실패한다. `CHANGELOG.md`는
|
|
지난 상태를 적는 문서라 빼고, git이 무시하는 생성 산출물과 복사한 프로젝트가 지운 작업 이력은
|
|
없어도 된다. 설명·수치가 코드와 맞는지는 검사하지 않는다. 규칙과 예외의 정본은
|
|
`scripts/verify-documentation-readiness.ts`다.
|
|
|
|
게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.
|
|
|
|
| 파일 | 읽는 명령 |
|
|
|---|---|
|
|
| 이 파일, `architecture/review-ledger.json`, `architecture/review-evidence.md` | `verify:documentation` (FE-GATE-017) |
|
|
| repo 루트의 `artifacts/tests/a11y-manual/` 라우트별 기록 | `verify:documentation` (FE-GATE-017), `review:a11y-manual` (FE-GATE-009, FE-GATE-028) |
|
|
| `reviews/adapters/INVENTORY.md` | `check:adapter-inventory` (FE-GATE-010) |
|
|
| `operations/adapter-remediation-ledger.md`, `operations/adapter-remediation-dispositions.json` | `check:remediation-ledger` (게이트 밖. 이유는 `config/ci/ungated-scripts.json`) |
|
|
|
|
## 2. 목표 설계
|
|
|
|
설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.
|
|
|
|
- 런타임 capability 결정의 정본: [`architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md`](architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)
|
|
- 상태 원장: [`architecture/browser-data-capability-completion-ledger.md`](architecture/browser-data-capability-completion-ledger.md)
|
|
- 전체 검토와 로드맵: [`architecture/frontend-platform-capability-review.md`](architecture/frontend-platform-capability-review.md), [`architecture/frontend-platform-implementation-roadmap.md`](architecture/frontend-platform-implementation-roadmap.md)
|
|
- 포트·경계·데이터 흐름: [`architecture/frontend-ports-adapters-and-boundaries.md`](architecture/frontend-ports-adapters-and-boundaries.md), [`architecture/typescript-state-and-data-flow.md`](architecture/typescript-state-and-data-flow.md), [`architecture/routing-pages-and-patterns.md`](architecture/routing-pages-and-patterns.md)
|
|
- API와 서버 상태: [`architecture/api-contract-schema-mapper-and-server-state.md`](architecture/api-contract-schema-mapper-and-server-state.md), [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md), [`architecture/protobuf-browser-transport-and-rest-gateway.md`](architecture/protobuf-browser-transport-and-rest-gateway.md)
|
|
- 브라우저 데이터: [`architecture/client-cache-and-storage.md`](architecture/client-cache-and-storage.md), [`architecture/browser-file-and-origin-storage.md`](architecture/browser-file-and-origin-storage.md), [`architecture/presigned-transfer-and-image-cdn.md`](architecture/presigned-transfer-and-image-cdn.md), [`architecture/server-file-capability-infrastructure.md`](architecture/server-file-capability-infrastructure.md)
|
|
- 실시간: [`architecture/realtime-events-web-push-and-bounded-polling.md`](architecture/realtime-events-web-push-and-bounded-polling.md)
|
|
- 디자인 시스템과 테스트 전략: [`styling/design-system-platform.md`](styling/design-system-platform.md), [`testing/frontend-platform-testing-strategy.md`](testing/frontend-platform-testing-strategy.md)
|
|
- 결정 기록(ADR): [`architecture/decisions/`](architecture/decisions/) `VD-*.md`
|
|
|
|
## 3. 작업 이력·리뷰
|
|
|
|
템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다.
|
|
복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 `README.md`의
|
|
"Files you can delete after copying" 절에 있다.
|
|
|
|
| 경로 | 내용 |
|
|
|---|---|
|
|
| [`superpowers/`](superpowers/) | 과거 작업 계획과 스펙 |
|
|
| [`reviews/`](reviews/) | 리뷰 결과와 리뷰 가이드. `reviews/adapters/INVENTORY.md`만 게이트가 읽는다. `reviews/adapters/`는 지우지 않는다: INVENTORY의 행과 `operations/adapter-remediation-ledger.md`가 그 안의 리뷰로 링크한다 |
|
|
| [`../SPEC.md`](../SPEC.md), [`../tasks/`](../tasks/) | 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 `docs/` 밖에 그대로 둔다 |
|