From 50b631e4cda812972ecbec29d64a110f2a3b250e Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:59:32 +0900 Subject: [PATCH 01/12] =?UTF-8?q?refactor(removal):=20=EC=A7=80=EC=9A=B8?= =?UTF-8?q?=20=EC=88=98=20=EC=9E=88=EB=8A=94=20=ED=85=9C=ED=94=8C=EB=A6=BF?= =?UTF-8?q?=20=EA=B8=B0=EB=8A=A5=20=EB=AA=A9=EB=A1=9D=EC=9D=84=20=ED=95=9C?= =?UTF-8?q?=20=EB=AA=A8=EB=93=88=EC=97=90=20=EB=91=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 템플릿은 지울 수 있는 기능을 둘 둔다. 참조 기능(README)과 예제 화면 기능 platform-examples-feature(starter-experience.md, CHANGELOG 6단계)다. 그 기능이 가진 경로는 제거 드릴의 SAMPLE_EXTRAS에만 있다. 그래서 문서 검사가 "이 경로는 지운 템플릿 기능의 것"을 알 길이 없다(1105/14-01, 14-03). 문서 검사가 따로 목록을 가지면 드릴과 갈라진다. 고른 방법 - scripts/lib/removable-template-features.ts에 두 기능을 적는다. 기능 ID(= src/features·tests/features 폴더 이름), 혼자 속한 context, 폴더 밖 전용 파일, 전용 package script. - 드릴은 참조 기능의 전용 파일·script를 이 모듈에서 읽는다. 목록 내용과 주석은 그대로 옮겼다. 동작은 바뀌지 않는다. - 예제 기능 항목은 다음 커밋(1105/14-01)의 문서 검사가 읽는다. 드릴은 예제 기능을 지금처럼 locateFeature로 찾는다. - 버린 대안: 문서 검사 안에 목록을 따로 두기. 드릴의 SAMPLE_EXTRAS와 두 벌이 된다. 위험·한계 - 동작 변경은 없다. 드릴 출력과 지우는 경로가 같다. 검증 - desktop batch에서 확인: corepack pnpm check:types, corepack pnpm lint, node scripts/run-vitest.ts run tests/unit/feature-removal-argument.test.ts Refs: 1105/14-01, 1105/14-03 --- scripts/lib/removable-template-features.ts | 62 ++++++++++++++++++++++ scripts/test-sample-removal.ts | 29 +++++----- 2 files changed, 74 insertions(+), 17 deletions(-) create mode 100644 scripts/lib/removable-template-features.ts diff --git a/scripts/lib/removable-template-features.ts b/scripts/lib/removable-template-features.ts new file mode 100644 index 00000000..415f56e7 --- /dev/null +++ b/scripts/lib/removable-template-features.ts @@ -0,0 +1,62 @@ +/** + * The features this template ships that a copied project may delete: the + * reference sample (README "Files you can delete after copying") and the + * example screens (docs/architecture/starter-experience.md, CHANGELOG "먼저 + * 할 일" 6). Each owns its folder under `src/features/` and `tests/features/` + * and the context it is the only feature of. The reference sample also owns + * files outside them, which `scripts/test-sample-removal.ts` deletes with it. + * + * This is the one list. The removal drill reads the reference sample's paths + * and scripts from it, and the documentation check reads the whole of it. + */ +export type RemovableTemplateFeature = Readonly<{ + /** Its FEATURE_MODULE_ID, also its folder under src/features and tests/features. */ + featureId: string; + /** The bounded context it is the only feature of; it goes with the feature. */ + contextDirectory: string; + /** Files outside those folders that only this feature uses. */ + extraPaths: readonly string[]; + /** Package scripts that only this feature uses. */ + scripts: readonly string[]; +}>; + +export const REMOVABLE_TEMPLATE_FEATURES: readonly RemovableTemplateFeature[] = Object.freeze([ + Object.freeze({ + featureId: "reference-feature", + contextDirectory: "src/contexts/reference-context", + // 0929/10-02. The HTTP scenario catalog (tests/mocks) and the negative + // type fixtures of the feature APIs run on the test contracts, so they + // are platform checks and stay (commonTestPaths in the drill). + extraPaths: Object.freeze([ + "tests/component/product-feature-switch.test.tsx", + "tests/e2e/reference-form.spec.ts", + "tests/e2e/reference-route.spec.ts", + "tests/e2e/reference-save.spec.ts", + // 11-04: the growth measurement copies this sample feature. + "tests/unit/feature-shape-growth.test.ts", + "scripts/scale/measure-feature-shape-growth.ts", + "config/scale/feature-shape-growth.json", + "config/scale/feature-shape-ceilings.json", + ]), + scripts: Object.freeze(["test:reference-feature"]), + }), + // 1103/09-04. The example screens /examples/ui, /examples/states and + // /examples/auth. The platform overview (/examples/platform) is a platform + // route and is not part of it. + Object.freeze({ + featureId: "platform-examples-feature", + contextDirectory: "src/contexts/platform-examples-context", + extraPaths: Object.freeze([]), + scripts: Object.freeze([]), + }), +]); + +/** Every path removing `feature` deletes: its folders, its context and its extra files. */ +export function removableTemplateFeaturePaths(feature: RemovableTemplateFeature): readonly string[] { + return Object.freeze([ + `src/features/${feature.featureId}`, + `tests/features/${feature.featureId}`, + feature.contextDirectory, + ...feature.extraPaths, + ]); +} diff --git a/scripts/test-sample-removal.ts b/scripts/test-sample-removal.ts index 8d91f788..8c4dbc10 100644 --- a/scripts/test-sample-removal.ts +++ b/scripts/test-sample-removal.ts @@ -29,6 +29,7 @@ import { sealRemovalFixtureRepository, type RemovalCheck, } from "./lib/removal-fixture.ts"; +import { REMOVABLE_TEMPLATE_FEATURES } from "./lib/removable-template-features.ts"; /** * 09-07 (D-10). Removes one installed feature, `--feature=` (default: the @@ -49,25 +50,19 @@ type FeatureExtras = Readonly<{ residue: RegExp; }>; +// The sample's own files and scripts outside its folders are declared with +// the other removable template features, which verify:documentation reads too. +const REFERENCE_SAMPLE = REMOVABLE_TEMPLATE_FEATURES.find( + (feature) => feature.featureId === "reference-feature", +); +if (REFERENCE_SAMPLE === undefined) { + throw new Error("scripts/lib/removable-template-features.ts does not declare reference-feature"); +} + const SAMPLE_EXTRAS: Readonly> = Object.freeze({ "reference-feature": Object.freeze({ - // 0929/10-02. The HTTP scenario catalog (tests/mocks) and the negative - // type fixtures of the feature APIs run on the test contracts, so they are - // platform checks and stay (commonTestPaths below). - paths: [ - "tests/component/product-feature-switch.test.tsx", - "tests/e2e/reference-form.spec.ts", - "tests/e2e/reference-route.spec.ts", - "tests/e2e/reference-save.spec.ts", - // 11-04: the growth measurement copies this sample feature. - "tests/unit/feature-shape-growth.test.ts", - "scripts/scale/measure-feature-shape-growth.ts", - "config/scale/feature-shape-growth.json", - "config/scale/feature-shape-ceilings.json", - ], - ciScripts: [ - "test:reference-feature", - ], + paths: REFERENCE_SAMPLE.extraPaths, + ciScripts: REFERENCE_SAMPLE.scripts, evidencePathFragments: [ "reference-feature.xml", ], From 332bfee9b8bbc6172d1ea74f53d0f05698d3f1ce Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 23:03:47 +0900 Subject: [PATCH 02/12] =?UTF-8?q?fix(docs):=20=EC=A7=80=EC=9A=B4=20?= =?UTF-8?q?=ED=85=9C=ED=94=8C=EB=A6=BF=20=EA=B8=B0=EB=8A=A5=EC=9D=98=20?= =?UTF-8?q?=EA=B2=BD=EB=A1=9C=EB=A5=BC=20=EB=AC=B8=EC=84=9C=20=EA=B2=80?= =?UTF-8?q?=EC=82=AC=EA=B0=80=20=EC=9A=94=EA=B5=AC=ED=95=98=EC=A7=80=20?= =?UTF-8?q?=EC=95=8A=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 CHANGELOG "먼저 할 일" 6단계는 예제를 지운 제품(tech-log)에게 예제 기능 폴더와 그 context를 지우라고 한다. 그런데 starter-experience.md가 그 세 폴더를 백틱 경로로 적어서, 지운 사본에서 verify:documentation과 FE-GATE-005의 documentation-readiness "passes the documents as they are"가 "starter-experience.md names paths that do not exist"로 실패한다(리뷰 14-R1). 그 문서가 안내한 드릴(test:sample-removal --feature=platform-examples-feature)도 같은 문서 검사와, 예제 기능 ID를 적은 tests/unit/hosting-probe.test.ts 때문에 잔여 검사에서 실패한다. PRODUCT.md는 예제 화면에 제거 드릴이 없다고 적는다. 지운 제품이 템플릿 문서를 고치면 동기화마다 그 줄이 충돌한다. 고른 방법 - 문서 검사는 scripts/lib/removable-template-features.ts의 기능마다, 그 기능이 설치돼 있으면(src/features//feature-module.ts가 있으면) 그 경로·script를 지금처럼 검사하고, 아니면 그 기능이 가진 경로(기능·테스트 폴더, context, 전용 파일)와 script를 없어도 되는 것으로 본다. 폴더가 아니라 feature-module.ts를 보는 것은 tech-log가 참조 기능 폴더를 계약 파일만 남긴 채 NOT_A_FEATURE로 두기 때문이다(CHANGELOG 옮기는 법 1). 목록에 없는 폴더(오타)는 그대로 실패한다. 지운 기능이 있으면 stdout에 그 ID를 적는다. - tests/unit/hosting-probe.test.ts의 FEATURE_OVERRIDES 키를 테스트 전용 기능 ID(fixture-feature)로 바꾼다. probe는 키 이름을 보지 않는다. - 새 테스트 tests/unit/template-feature-removal-documents.test.ts: 저장소 사본에서 기능마다 그 경로를 지우고 색인을 다시 만든 뒤 사본의 verify:documentation이 통과한다. 사본의 코드로 경로를 찾으므로 실제로 지운 상태다. 기능 ID는 목록에서 읽어 테스트에 적지 않는다(제거 드릴의 잔여 검사). 설치된 기능 아래의 없는 경로와 목록에 없는 폴더는 여전히 실패하는 것도 본다. 문서를 읽으므로 REMOVAL_FIXTURE_DOCUMENT_TESTS에 더했다. - PRODUCT.md, starter-experience.md(지우는 법과 문서 검사 규칙), docs/README.md 1절 검사 설명, CHANGELOG 6단계(테스트 폴더, generate:feature-index, 드릴, 두 절을 함께 받을 것)를 고쳤다. - 버린 대안: (a) 세 경로를 백틱 없이 적기(1103/14-04 방식). 검사가 또 좁아진다(1105/14-03). (b) 모든 src/features/ 아래 경로를 폴더가 없으면 통과시키기. 기능 폴더 이름 오타가 조용히 지나간다. (c) FE-GATE-020에 예제 기능 드릴을 더하기. job이 약 5분 는다. 문서 쪽은 새 unit 테스트가 merge 단계에서 본다. 위험·한계 - 새 테스트는 저장소 사본을 두 번 만든다(기능마다 cp·색인·검사). test:unit 시간이 몇 초 는다. 드릴이 test:all에서 이 파일을 다시 돈다. - 예제 기능 드릴 전체(test:all, build 등)는 이 커밋에서 돌리지 않았다. 알려진 남은 실패는 e2e·visual spec이 예제 화면을 여는 것이고 드릴 밖이다. - RED에서 새 테스트는 앞 커밋의 목록 모듈을 import하므로 그대로 돈다. 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/template-feature-removal-documents.test.ts tests/unit/hosting-probe.test.ts tests/unit/removal-fixture.test.ts tests/unit/documentation-readiness.test.ts, corepack pnpm verify:documentation, corepack pnpm test:sample-removal -- --feature=platform-examples-feature Refs: 1105/14-01 --- CHANGELOG.md | 4 +- PRODUCT.md | 2 +- docs/README.md | 3 + docs/architecture/starter-experience.md | 17 ++- scripts/lib/removable-template-features.ts | 3 +- scripts/lib/removal-fixture.ts | 2 + scripts/verify-documentation-readiness.ts | 36 +++++- tests/unit/hosting-probe.test.ts | 7 +- ...template-feature-removal-documents.test.ts | 110 ++++++++++++++++++ 9 files changed, 170 insertions(+), 14 deletions(-) create mode 100644 tests/unit/template-feature-removal-documents.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index b61bf5fc..75b63762 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -115,7 +115,7 @@ 6. **쓰는 곳이 있을 때만.** - V2 HTTP 클라이언트와 V2 API 행에서 지운 이름(아래 `048f490`·`12f3bb7` 행). 두 다운스트림은 앱 코드에서 V2 클라이언트를 부르지 않는다. 부르는 곳은 템플릿의 `tests/unit/runtime-adapters.test.ts`뿐이고 그 파일은 템플릿 것으로 바뀐다. - realtime: `BoundedPollOperationContract`를 지웠다. SSE·poll이 서버에 닿지 못한 실패는 `OFFLINE` 대신 `PROVIDER_UNAVAILABLE`이다. - - 예제 화면 3개(`EXAMPLES_UI`·`EXAMPLES_STATES`·`EXAMPLES_AUTH`)가 `platform-examples-feature`로 옮겼다. 예제를 지운 제품(tech-log)은 이 기능 폴더와 `src/contexts/platform-examples-context/`를 지운다. 예제 화면을 여는 제품 테스트는 그 기능을 설치해 두거나 제품 화면으로 옮긴다. memento의 `production-csp.spec.ts`·`old-tab-chunk-recovery.spec.ts`가 `/examples/states`·`/examples/ui`에서 시작한다. `/examples/platform`(플랫폼 구성 화면)은 플랫폼 라우트로 남는다. + - 예제 화면 3개(`EXAMPLES_UI`·`EXAMPLES_STATES`·`EXAMPLES_AUTH`)가 `platform-examples-feature`로 옮겼다. 예제를 지운 제품(tech-log)은 이 기능 폴더, `tests/features/platform-examples-feature/`, `src/contexts/platform-examples-context/`를 지우고 `corepack pnpm generate:feature-index`를 돈다. 지우기 전에 `corepack pnpm test:sample-removal -- --feature=platform-examples-feature`가 사본에서 같은 삭제로 게이트를 돈다. 템플릿 문서가 지운 폴더를 계속 적어도 `verify:documentation`과 FE-GATE-005가 통과하는 것은 위 절의 수정부터다(1105/14-01). 그래서 두 절을 함께 받는다. 예제 화면을 여는 제품 테스트는 그 기능을 설치해 두거나 제품 화면으로 옮긴다. memento의 `production-csp.spec.ts`·`old-tab-chunk-recovery.spec.ts`가 `/examples/states`·`/examples/ui`에서 시작한다. `/examples/platform`(플랫폼 구성 화면)은 플랫폼 라우트로 남는다. - 포트를 직접 구현한 코드: `OpfsJournalPort.countPartitionTransactions`·`removePartition`, worker gateway의 `removePartition`, `PublicCacheInspection.activePointer`가 필수 칸이다. - offline-indexeddb recipe 타입: `src`와 이름이 같은 34개가 `src` 타입을 다시 내보낸다. (1103/04-01, 1103/04-04, 1103/09-04, 1103/05-01, 0929/05-01, 1103/02-05, 0929/05-03) @@ -147,7 +147,7 @@ | [계약] | 기능 어댑터 기여는 실행 중에도 `needs`에 적은 capability만 받는다. cast로 다른 capability를 읽던 기능은 `undefined`를 받는다 (1103/09-08) | `src/features/feature-adapter-contribution.ts` | `e7d6358` | | [계약] | 기능 계약이 route id `APP_HOME`을 선언하면 플랫폼 홈을 대신한다. 둘이 선언하면 두 기능 id를 적고 실패한다. `src/contexts//context-layout.tsx`가 `CONTEXT_LAYOUT`을 내보내면 그 context의 라우트가 AppShell 대신 그 레이아웃 아래에 놓인다. 레이아웃은 skip link와 `
` 하나를 그려야 하고, `tests/component/layout-landmarks.test.tsx`가 설치된 레이아웃을 모두 실행해 본다 (1101/09-03) | `src/contracts/routes.ts`, `src/contexts/bounded-context-module.ts`, `scripts/generate-product-feature-index.ts`, `tests/component/layout-landmarks.test.tsx` | `ca16187`, `27f4523` | | [계약] | 앱 조립이 닿지 않는 기능 라우트를 앱 모듈을 평가할 때 throw로 거절한다. 소유 context 루트 밖의 라우트, 계약에 없는 route handle, 플랫폼 라우트가 먼저 받는 경로, 다른 기능과 같은 경로(파라미터 이름만 다른 것과 대소문자·끝 슬래시만 다른 것 포함)다. 시작할 런타임이 없는 선택 capability(realtime·webWorkers·offlineCommands)도 거절한다 (1101/09-06, 1101/09-07, 1103/08-04, 1101 README 14.4) | `src/apps/deployable-app-module.ts`, `src/contexts/bounded-context-module.ts`, `src/bootstrap/` | `7139c7c`, `d6e4e51`, `7d85589`, `8469554`, `851fded`, `48a4074` | -| [계약] **BREAKING** | 예제 화면 `EXAMPLES_UI`·`EXAMPLES_STATES`·`EXAMPLES_AUTH`가 끌 수 있는 기능 `platform-examples-feature`(context `platform-examples-context`, 루트 `examples/*`)로 옮겼다. 페이지 파일은 그 기능의 `presentation/`에 있다. `PLATFORM_ROUTE_REGISTRY`·`PLATFORM_ROUTE_RUNTIME_CONTRACT`·`PLATFORM_ROUTE_RUNTIME`에서 키가 빠졌다. 홈 문구 `home.starter.platform`·`ui`·`states`는 `home.starter.open({title})`로 바뀌었다. 예제를 지운 제품은 이 기능 폴더와 context를 지운다. `/examples/platform`은 플랫폼 라우트로 남는다 (1103/09-04) | `src/features/platform-examples-feature/`, `src/contexts/platform-examples-context/`, `src/contracts/routes.ts` | `b96d61d` | +| [계약] **BREAKING** | 예제 화면 `EXAMPLES_UI`·`EXAMPLES_STATES`·`EXAMPLES_AUTH`가 끌 수 있는 기능 `platform-examples-feature`(context `platform-examples-context`, 루트 `examples/*`)로 옮겼다. 페이지 파일은 그 기능의 `presentation/`에 있다. `PLATFORM_ROUTE_REGISTRY`·`PLATFORM_ROUTE_RUNTIME_CONTRACT`·`PLATFORM_ROUTE_RUNTIME`에서 키가 빠졌다. 홈 문구 `home.starter.platform`·`ui`·`states`는 `home.starter.open({title})`로 바뀌었다. 예제를 지운 제품은 이 기능 폴더, 그 테스트 폴더, context를 지운다(위 "먼저 할 일" 6단계). `/examples/platform`은 플랫폼 라우트로 남는다 (1103/09-04) | `src/features/platform-examples-feature/`, `src/contexts/platform-examples-context/`, `src/contracts/routes.ts` | `b96d61d` | | [계약] | 계약 기여의 출처는 `EXTERNAL_PACKAGE`이고, `TEMPLATE_FIXTURE`는 참조 기능만 하나 쓸 수 있다. 다른 출처 종류는 `unknown contribution source kind`로 거절한다 (1101/07-04) | `src/contracts/external-contract-runtime.ts` | `c063389` | | [계약] **BREAKING** | `useApplicationMutation`은 raw `{ execute, definitionId }`를 받지 않는다. `useServerStateScope()`의 scope로 만든 `BoundMutation`을 넘기고 `execute(input, { signal, intent })`로 부른다. `commandMutationIdentity()`가 `operationId`·`requiresIdempotencyKey`를 descriptor에서 준다. `QueryDefinition.owner`·`operationId`와 `BoundMutation.owner`는 아무도 읽지 않아 `@deprecated` 선택 칸으로 바꿨고 다음 릴리스에서 지운다. raw query는 남았다. 세션이 바뀌면 이전 결과가 보이지 않는다(JSDoc에 위험 표기) (1101/08-03, 1103/16-05, 1101/03-03, 1103/16-06) | `src/presentation/adapters/query/application-query.ts`, `src/presentation/adapters/query/` | `1fa5f3e`, `f59a806`, `68f94f5` | diff --git a/PRODUCT.md b/PRODUCT.md index de4e8dc6..5d612657 100644 --- a/PRODUCT.md +++ b/PRODUCT.md @@ -30,7 +30,7 @@ web - 하나의 디자인 시스템으로 세 종류의 서비스를 받칩니다. 업무용·관리 도구(대시보드, 어드민, 설정), 일반 사용자용 웹 서비스, 소개·랜딩 페이지입니다. - 디자인 시스템 위치는 `src/presentation/design-system/`입니다. 토큰은 primitive → semantic → component 세 단계로 파생됩니다(`tokens/primitive.css`, `semantic.css`, `component.css`). - 시각 회귀 골든이 `tests/visual/__snapshots__/`에 있습니다. 화면을 바꾸면 골든도 의도적으로 갱신해야 합니다. -- 참조 기능(`src/features/reference-feature/`)은 `test:sample-removal`로 지울 수 있습니다. 예제 라우트 4개(`/examples/platform`, `ui`, `states`, `auth`)와 홈은 기본 구성이고 제거 드릴이 없습니다. 그래서 예제 화면에만 넣은 디자인은 파생 서비스에 그대로 남습니다. +- 참조 기능(`src/features/reference-feature/`)은 `test:sample-removal`로 지울 수 있습니다. 예제 화면 3개(`/examples/ui`, `states`, `auth`)도 기능 `platform-examples-feature`라서 같은 드릴(`test:sample-removal -- --feature=platform-examples-feature`)로 지울 수 있습니다. 플랫폼 구성 화면(`/examples/platform`)과 홈은 기본 구성이고 제거 드릴이 없습니다. 그래서 예제 화면 3개에만 넣은 디자인은 예제를 지운 파생 서비스에서 함께 사라지고, 홈과 플랫폼 구성 화면에 넣은 디자인은 남습니다. - 어떤 서비스가 먼저 만들어질지, 서비스별 우선순위는 아직 정하지 않았습니다. ## Brand Commitments diff --git a/docs/README.md b/docs/README.md index f2f541aa..7d9393f8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -51,6 +51,9 @@ checkout이 없거나 그 커밋이 없으면 실패 대신 확인하지 못한 지난 상태를 적는 문서라 빼고, git이 무시하는 생성 산출물과 복사한 프로젝트가 지운 작업 이력은 없어도 된다. 설명·수치가 코드와 맞는지는 검사하지 않는다. 규칙과 예외의 정본은 `scripts/verify-documentation-readiness.ts`다. +복사한 프로젝트가 지울 수 있는 템플릿 기능(참조 기능, 예제 화면. 목록은 +`scripts/lib/removable-template-features.ts`)의 경로와 script는 그 기능이 설치돼 있을 때 +(`src/features//feature-module.ts`가 있을 때) 검사하고, 지운 뒤에는 없어도 된다. 게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다. diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index fa66ffdf..ea669dbd 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -104,11 +104,18 @@ layouts"). Its starter links are the first three screens of the navigation. The example screens `/examples/ui`, `/examples/states` and `/examples/auth` are one feature, `src/features/platform-examples-feature/`, in its own context `src/contexts/platform-examples-context/` (1103/09-04). A product turns them -off like any feature: leave the id out of `VITE_PRODUCT_FEATURES`, or remove -it with `corepack pnpm test:sample-removal -- --feature=platform-examples-feature` -as the drill. Their routes then leave the registry, the navigation, the -bundle and the manual accessibility list (FE-GATE-028). Their component tests -are in `tests/features/platform-examples-feature/` and go with them. +off like any feature: leave the id out of `VITE_PRODUCT_FEATURES`, or delete +the feature. To delete it, remove those two folders and +`tests/features/platform-examples-feature/` (its component tests), then run +`corepack pnpm generate:feature-index`; +`corepack pnpm test:sample-removal -- --feature=platform-examples-feature` +does the same in a copy of the repository and runs the gates there. Their +routes then leave the registry, the navigation, the bundle and the manual +accessibility list (FE-GATE-028). This document keeps naming the three +folders after they are gone: `verify:documentation` checks the paths of a +removable template feature (`scripts/lib/removable-template-features.ts`) +while the feature is installed and accepts them once its `feature-module.ts` +is gone (1105/14-01). The platform overview (`/examples/platform`, `src/presentation/examples/platform-overview-page.tsx`) stays a platform diff --git a/scripts/lib/removable-template-features.ts b/scripts/lib/removable-template-features.ts index 415f56e7..39e5aed2 100644 --- a/scripts/lib/removable-template-features.ts +++ b/scripts/lib/removable-template-features.ts @@ -7,7 +7,8 @@ * files outside them, which `scripts/test-sample-removal.ts` deletes with it. * * This is the one list. The removal drill reads the reference sample's paths - * and scripts from it, and the documentation check reads the whole of it. + * and scripts from it, and the documentation check reads the whole of it: a + * feature counts as deleted once its `feature-module.ts` is gone. */ export type RemovableTemplateFeature = Readonly<{ /** Its FEATURE_MODULE_ID, also its folder under src/features and tests/features. */ diff --git a/scripts/lib/removal-fixture.ts b/scripts/lib/removal-fixture.ts index 9222d777..e892a57c 100644 --- a/scripts/lib/removal-fixture.ts +++ b/scripts/lib/removal-fixture.ts @@ -74,6 +74,8 @@ export const REMOVAL_FIXTURE_DOCUMENT_TESTS = Object.freeze([ "tests/unit/backend-contract-pin.test.ts", // 1105/16-01. Reads the 03 manual and docs/architecture/starter-experience.md. "tests/unit/feature-tracked-files.test.ts", + // 1105/14-01 + "tests/unit/template-feature-removal-documents.test.ts", ] as const); /** The tests a fixture copied from `copyTargets` cannot run. */ diff --git a/scripts/verify-documentation-readiness.ts b/scripts/verify-documentation-readiness.ts index 7fda24b5..32f4b322 100644 --- a/scripts/verify-documentation-readiness.ts +++ b/scripts/verify-documentation-readiness.ts @@ -8,6 +8,10 @@ import { RETIRED_GATE_IDS } from "./contracts/ci-gates.ts"; import { documentationReviewArtifactSchema } from "./contracts/release-artifacts.ts"; import { RUNTIME_OVERRIDES } from "./generate-runtime-config.ts"; import { MANUAL_A11Y_ROUTE_IDS } from "./lib/manual-a11y-evidence.ts"; +import { + REMOVABLE_TEMPLATE_FEATURES, + removableTemplateFeaturePaths, +} from "./lib/removable-template-features.ts"; import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts"; /** @@ -183,6 +187,25 @@ const gateIds = new Set([ ).gates.map((gate) => gate.id), ...RETIRED_GATE_IDS, ]); +// 1105/14-01. A copy may delete the template features listed in +// scripts/lib/removable-template-features.ts, and the CHANGELOG tells +// tech-log to delete the example screens. The documents are the template's: +// a product that edited them to drop the feature's paths would conflict on +// every sync. While a feature is installed (its feature-module.ts exists), +// its paths and scripts are checked like any other; once it is not, they are +// not drift. tech-log keeps the reference sample's folder with its contracts +// but without its module, screens and tests (CHANGELOG "먼저 할 일" 1). A +// misspelt feature folder is not on the list and still fails. +const removedTemplateFeatures = REMOVABLE_TEMPLATE_FEATURES.filter( + (feature) => !exists(`src/features/${feature.featureId}/feature-module.ts`), +); +const removedTemplateFeaturePaths = removedTemplateFeatures.flatMap((feature) => + removableTemplateFeaturePaths(feature), +); +const removedTemplateFeatureScripts = new Set(removedTemplateFeatures.flatMap((feature) => feature.scripts)); +function missingScript(name: string): boolean { + return !scripts.has(name) && !removedTemplateFeatureScripts.has(name); +} // Generated output is what git ignores, so a document may name it before a // run has written it. const ignorePatterns = (await readFile(join(rootDirectory, ".gitignore"), "utf8").catch(() => "")) @@ -361,17 +384,18 @@ for (const document of contractDocuments) { !exists(trimmed) && !NOT_CREATED.has(trimmed) && !generated(trimmed) && - !deletedHistory.some((entry) => trimmed === entry || trimmed.startsWith(`${entry}/`)) + !deletedHistory.some((entry) => trimmed === entry || trimmed.startsWith(`${entry}/`)) && + !removedTemplateFeaturePaths.some((entry) => trimmed === entry || trimmed.startsWith(`${entry}/`)) ) { missingPaths.add(trimmed); } } const missingScripts = new Set(); for (const [, name = ""] of text.matchAll(/(?:corepack pnpm|`pnpm) (?:run )?([a-z](?:[\w:-]*\w)?)/gu)) { - if (!PNPM_COMMANDS.has(name) && !scripts.has(name)) missingScripts.add(name); + if (!PNPM_COMMANDS.has(name) && missingScript(name)) missingScripts.add(name); } for (const [, name = ""] of text.matchAll(/`([a-z][\w-]*:[\w:-]*\w)(?=[` ])/gu)) { - if (scriptPrefixes.has(name.split(":")[0]) && !scripts.has(name)) missingScripts.add(name); + if (scriptPrefixes.has(name.split(":")[0]) && missingScript(name)) missingScripts.add(name); } documentReferences.push({ path: document, @@ -486,6 +510,12 @@ if (!passed) { ); process.exit(1); } +if (removedTemplateFeatures.length > 0) { + process.stdout.write( + `Documentation readiness: paths and scripts of removed template features not required: ` + + `${removedTemplateFeatures.map((feature) => feature.featureId).join(", ")}\n`, + ); +} const unverified = documentReferences.flatMap((entry) => entry.unverifiedLinks); if (unverified.length > 0) { const reasons = [...pairedTrees].flatMap(([repository, tree]) => diff --git a/tests/unit/hosting-probe.test.ts b/tests/unit/hosting-probe.test.ts index 0bae3ed7..de9f2d3c 100644 --- a/tests/unit/hosting-probe.test.ts +++ b/tests/unit/hosting-probe.test.ts @@ -241,12 +241,15 @@ describe("SPA fallback and worker script surfaces (1101/13-04)", () => { }); // FE-RB-001 changes the two emergency switches without a rebuild; the - // probe after it must still pass. + // probe after it must still pass. 1105/14-01: the feature ID is the + // test-only one (tests/helpers/fixture-feature.tsx). It named the example + // screens' feature, so a copy that deleted them as the CHANGELOG says kept + // this file as residue and failed that feature's removal drill. it("passes a host whose config.json differs only in the emergency switches", async () => { const switched = JSON.stringify({ ...JSON.parse(CONFIG), CAPABILITY_OVERRIDES: { realtime: "DISABLED" }, - FEATURE_OVERRIDES: { "platform-examples-feature": false }, + FEATURE_OVERRIDES: { "fixture-feature": false }, }); expect( await failed({ ...RELEASE, "/__probe/deep-link": [200, INDEX], "/config.json": [200, switched] }), diff --git a/tests/unit/template-feature-removal-documents.test.ts b/tests/unit/template-feature-removal-documents.test.ts new file mode 100644 index 00000000..68d564e9 --- /dev/null +++ b/tests/unit/template-feature-removal-documents.test.ts @@ -0,0 +1,110 @@ +import { spawnSync } from "node:child_process"; +import { existsSync } from "node:fs"; +import { cp, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; + +import { describe, expect, it } from "vitest"; + +import { linkFixtureNodeModules } from "../../scripts/lib/fixture-node-modules.ts"; +import { + REMOVABLE_TEMPLATE_FEATURES, + removableTemplateFeaturePaths, +} from "../../scripts/lib/removable-template-features.ts"; +import { REMOVAL_FIXTURE_COPY_TARGETS } from "../../scripts/lib/removal-fixture.ts"; + +/** + * 1105/14-01. The CHANGELOG tells a product (tech-log) to delete the example + * screens' feature, and the template's own documents name that feature's + * folders. A copy that deleted them failed verify:documentation and the + * FE-GATE-005 copy of it ("passes the documents as they are"), and only the + * reference sample's removal was ever tried. The features come from + * scripts/lib/removable-template-features.ts, so no feature ID is written + * here: the removal drills refuse a test that still names the removed one. + */ +const CHECKER = "scripts/verify-documentation-readiness.ts"; +/** What verify:documentation reads besides the code. */ +const DOCUMENTS = Object.freeze(["README.md", "CHANGELOG.md", "docs", "artifacts/tests/a11y-manual"]); + +/** + * Runs verify:documentation in a copy of the repository without `removed`, + * as a product that deleted it has it. The code facts are the copy's: + * tests/unit/documentation-readiness.test.ts copies only the documents and + * looks paths up in this repository, where nothing is deleted. The feature + * index is generated again, as the product does after the deletion. + */ +async function verifyWithout(removed: readonly string[]) { + const parent = await mkdtemp(path.join(tmpdir(), "template-feature-removal-")); + const root = path.join(parent, "frontend"); + try { + for (const entry of [...REMOVAL_FIXTURE_COPY_TARGETS, ...DOCUMENTS]) { + // A drill runs this test in a copy that has already lost some of them. + if (!existsSync(entry)) continue; + await cp(entry, path.join(root, entry), { + recursive: true, + filter: (source) => !source.includes(`${path.sep}.generated`), + }); + } + await linkFixtureNodeModules(root); + for (const entry of removed) await rm(path.join(root, entry), { recursive: true, force: true }); + const generated = spawnSync( + process.execPath, + [path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`], + { encoding: "utf8" }, + ); + expect(generated.status, generated.stderr).toBe(0); + return spawnSync(process.execPath, [path.join(root, CHECKER)], { cwd: root, encoding: "utf8" }); + } finally { + await rm(parent, { recursive: true, force: true }); + } +} + +/** + * Runs this repository's verify:documentation on a copy of the documents + * with `mutate` applied to `document`; the code facts are this repository's. + */ +async function verifyDocuments(document: string, mutate: (text: string) => string) { + const parent = await mkdtemp(path.join(tmpdir(), "template-feature-documents-")); + const root = path.join(parent, "frontend"); + try { + // The pin says which commit of the paired backend the documents describe. + const inputs = ["README.md", "docs", "artifacts/tests/a11y-manual", "config/contracts/backend-contract-pin.json"]; + for (const entry of inputs) await cp(entry, path.join(root, entry), { recursive: true }); + const target = path.join(root, document); + await writeFile(target, mutate(await readFile(target, "utf8"))); + return spawnSync(process.execPath, [path.resolve(CHECKER)], { cwd: root, encoding: "utf8" }); + } finally { + await rm(parent, { recursive: true, force: true }); + } +} + +describe("verify:documentation after a template feature is deleted (1105/14-01)", () => { + it.each(REMOVABLE_TEMPLATE_FEATURES.map((feature) => [feature.featureId, feature] as const))( + "passes in a copy without %s", + async (_featureId, feature) => { + const result = await verifyWithout(removableTemplateFeaturePaths(feature)); + expect(result.status, result.stderr).toBe(0); + }, + 120_000, + ); + + // Only a deleted feature's paths are let through. While a feature is + // installed a missing path under it fails, and a folder that is not a + // removable template feature (a misspelt one) fails whether or not it exists. + it("still fails on a missing path under an installed template feature or an unknown folder", async () => { + const document = "docs/architecture/starter-experience.md"; + const missing = [ + ...REMOVABLE_TEMPLATE_FEATURES.filter((feature) => + existsSync(`src/features/${feature.featureId}/feature-module.ts`), + ).map((feature) => `src/features/${feature.featureId}/no-such-module.ts`), + "src/features/no-such-template-feature/feature-module.ts", + ]; + const result = await verifyDocuments( + document, + (text) => `${text}\n${missing.map((file) => `- \`${file}\``).join("\n")}\n`, + ); + expect(result.status).toBe(1); + expect(result.stderr).toContain(`${document} names paths that do not exist:`); + for (const file of missing) expect(result.stderr).toContain(file); + }, 60_000); +}); From 1dda18da30aa45b1f991d62460142a6bba5ab7a1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 23:08:46 +0900 Subject: [PATCH 03/12] =?UTF-8?q?fix(docs):=20=EC=B0=B8=EC=A1=B0=20?= =?UTF-8?q?=EA=B8=B0=EB=8A=A5=20=EA=B2=BD=EB=A1=9C=EB=A5=BC=20=EB=8B=A4?= =?UTF-8?q?=EC=8B=9C=20=EB=B0=B1=ED=8B=B1=EC=9C=BC=EB=A1=9C=20=EC=A0=81?= =?UTF-8?q?=EC=96=B4=20=EB=AC=B8=EC=84=9C=20=EA=B2=80=EC=82=AC=EA=B0=80=20?= =?UTF-8?q?=EB=B3=B8=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 1103/14-04 조치는 참조 기능을 지운 사본에서 문서 검사가 통과하도록 참조 기능·참조 context 경로와 그 전용 파일·script를 백틱 없이 다시 적었다. 검사기는 백틱 안·명령 안·링크의 경로만 보므로(verify-documentation- readiness.ts) 그 26줄은 참조 기능이 설치된 템플릿에서도 검사 밖이다. 참조 기능 파일 이름이 바뀌면 매뉴얼이 없는 경로를 가리켜도 어느 게이트도 실패하지 않는다. docs/manual/README.md의 "이 폴더 문서의 경로는 검사된다"가 예제 경로에서 거짓이다. 고른 방법 - 앞 커밋(1105/14-01)으로 검사기가 지운 템플릿 기능의 경로를 받으므로, README, starter-experience, static-delivery, compatibility, backend-api-and-server-state-contract, manual-checklist, adapter-remediation-ledger, performance-evidence, 매뉴얼 01·02·patterns의 참조 기능 경로와 test:reference-feature를 다시 백틱(또는 명령 한 줄)으로 적는다. 두 줄로 끊겨 검사되지 않던 measure 명령도 한 줄로 적었다. 1105/15-02·16-01 조치가 starter-experience.md 표와 매뉴얼 03(A 표, "기능을 지울 때")에 백틱 없이 더한 config/scale/feature-shape-ceilings.json과 measure 명령 세 줄도 같은 규칙으로 고쳤다. - patterns.md 첫머리 규칙("백틱 없이 적는다")과 README의 SAMPLE_EXTRAS 안내를 새 규칙(설치된 동안 검사, 지운 사본에서는 받음)과 목록 모듈 위치로 고쳤다. - 테스트: template-feature-removal-documents.test.ts에 "names their paths and scripts only where verify:documentation checks them"을 더했다. 검사기가 읽은 1절 문서 목록(documentation-review.json)을 받아, 지울 수 있는 템플릿 기능의 경로·script가 백틱 span·링크 대상·셸 블록 밖에 나오면 실패한다. 같은 우회가 다시 들어오는 것을 막는다. 지운 사본에서 통과하는 성질은 앞 커밋의 "passes in a copy without reference-feature"가 본다. - 버린 대안: 경로 존재만 보는 단위 테스트를 따로 두기(리뷰의 차선책). 검사기와 같은 규칙을 두 곳에 두게 된다. 위험·한계 - 다음에 참조 기능 경로를 백틱 없이 적는 문서 변경은 새 테스트가 막는다. 백틱으로 적으면 참조 기능을 지운 사본에서도 통과한다. - 언어 없는 펜스 블록은 검사기처럼 셸 블록으로 보고 넘긴다. 그 안의 명령이 아닌 줄(트리 그림 등)에 적은 경로는 검사기도 새 테스트도 보지 않는다. 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/template-feature-removal-documents.test.ts tests/unit/documentation-readiness.test.ts, corepack pnpm verify:documentation, corepack pnpm test:sample-removal Refs: 1105/14-03 --- README.md | 10 ++-- docs/accessibility/manual-checklist.md | 2 +- .../backend-api-and-server-state-contract.md | 4 +- docs/architecture/starter-experience.md | 10 ++-- docs/architecture/static-delivery.md | 2 +- docs/contracts/compatibility.md | 2 +- docs/manual/01-add-a-feature.md | 20 +++---- docs/manual/02-decision-tables.md | 2 +- docs/manual/03-outside-feature-folder.md | 4 +- docs/manual/reference/patterns.md | 6 +-- docs/operations/adapter-remediation-ledger.md | 4 +- docs/operations/performance-evidence.md | 12 +++-- ...template-feature-removal-documents.test.ts | 54 +++++++++++++++++-- 13 files changed, 91 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index e84a8d0b..81d6bd69 100644 --- a/README.md +++ b/README.md @@ -174,7 +174,7 @@ See `docs/architecture/frontend-application-foundation.md`, `docs/architecture/overview.md`, `docs/architecture/layers.md`, and `docs/architecture/starter-experience.md`. The removable vertical slice is -the reference sample, src/features/reference-feature; its domain, application input, HTTP +under `src/features/reference-feature`; its domain, application input, HTTP binding, contracts, route runtime, and presentation own their contributions. The central installed catalogs only aggregate selected contributions. The generic starter routes continue to typecheck, test, and build after that @@ -232,8 +232,12 @@ reads them, except the one file noted below The reference feature is not in this list: deleting its directory alone leaves tests, policy entries and CI scripts behind that fail the gates. `scripts/test-sample-removal.ts` removes it from a copy of -the repository and lists everything that has to go with it (its header comment -and `SAMPLE_EXTRAS`); do the same in your project and run the gates. +the repository and lists everything that has to go with it (its header comment, +and the files outside the feature's folders in +`scripts/lib/removable-template-features.ts`); do the same in your project and +run the gates. The documents keep naming the sample's paths: the documentation +check accepts them once `src/features/reference-feature/feature-module.ts` is +gone. ## Verification diff --git a/docs/accessibility/manual-checklist.md b/docs/accessibility/manual-checklist.md index 21804569..2e4158db 100644 --- a/docs/accessibility/manual-checklist.md +++ b/docs/accessibility/manual-checklist.md @@ -77,5 +77,5 @@ What the automated run scans: annotation. - The reference sample's list in its success, empty and error states, its detail, its form with submit errors and its status page, each after that - state is on screen (tests/e2e/reference-form.spec.ts, removed with the + state is on screen (`tests/e2e/reference-form.spec.ts`, removed with the sample). diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index f0526f2a..200015ea 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -283,8 +283,8 @@ backend idempotency를 대체하지 않는다. `src/presentation/adapters/query/application-query.ts` - Envelope operation의 거절 판정: `src/adapters/http/backend-envelope.ts` `REFUSED_BEFORE_WRITE`(6.1절 표) - - 참조 기능(Envelope 없음) 판정: src/features/reference-feature/contracts/reference-feature-contract-contribution.ts - (effect), src/features/reference-feature/adapters/reference-http-gateway.ts + - 참조 기능(Envelope 없음) 판정: `src/features/reference-feature/contracts/reference-feature-contract-contribution.ts` + (effect), `src/features/reference-feature/adapters/reference-http-gateway.ts` (code) ### 6.1 거절 code와 적용 여부 diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index ea669dbd..01843825 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -168,8 +168,7 @@ selected app. Every build and check script runs it first; run it yourself with invalidation, topic versions and the external `contractPackages` the release manifest is checked against at boot), its message catalogs, and `loadRuntime`, which imports `feature-runtime.ts` dynamically. - The reference sample's feature-module.ts (src/features/reference-feature, - while it is installed) is the complete example. + `src/features/reference-feature/feature-module.ts` is the complete example. 2. Create `src/features//feature-runtime.ts` with `defineFeatureRuntime`: the `schemas` (FE-REG-SCHEMA rows for the feature's route and API schemas), the adapter contributions @@ -179,8 +178,7 @@ selected app. Every build and check script runs it first; run it yourself with it (`application.features.load`) when one of the feature's routes is entered. Do not import it statically from anywhere: each feature would add its whole executable code to the initial chunk again, about 3.9 KB gzip - (tests/unit/feature-shape-growth.test.ts, which goes with the reference - sample, bounds one feature at 1 KiB). + (`tests/unit/feature-shape-growth.test.ts` bounds one feature at 1 KiB). An HTTP API is written once, as its contract contribution descriptor: it executes, and `check:registries` governs the FE-REG-API row projected from it (`projectApiOperationRows` in `src/contracts/api-operations.ts`). @@ -191,7 +189,7 @@ selected app. Every build and check script runs it first; run it yourself with `FEATURE_CONTEXT_ROUTES`. Page components are imported lazily here, and each route handle carries the route's params/search `codecs`; the owning context loads this file only when its route root is visited - (the reference sample's context-routes.ts shows one). Each handle's + (`src/features/reference-feature/context-routes.ts`). Each handle's `routeId` must be a route of a feature contract in the same context; the context refuses the routes when they load, naming the route, context and features (`src/contexts/bounded-context-module.ts`). @@ -223,7 +221,7 @@ Files outside the feature directory. Everything else a feature needs is in | --- | --- | --- | | `src/.generated/*` | never by hand: every build and check script regenerates it | — | | `public/release-manifest.json` (tracked, the dev server's manifest) | every added or removed feature: `create:feature` rewrites it (`node scripts/write-dev-release-manifest.ts`). Commit it with the feature. Two feature branches change its `setDigest` line; on a merge conflict take either side and run the command again (1105/16-01) | `test:unit` (`tests/unit/dev-release-manifest.test.ts`) names the command; the dev server does not boot (`CONTRACT_SET_PACKAGE_MISSING`) | -| config/scale/feature-shape-ceilings.json `initialJavascript` (tracked, only while the sample is installed) | every added or removed feature, and every template change that moves the initial JavaScript: node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write. Commit it with the change; on a merge conflict run the command again | `test:unit` (the feature-shape growth test compares it with a build) | +| `config/scale/feature-shape-ceilings.json` `initialJavascript` (tracked, only while the sample is installed) | every added or removed feature, and every template change that moves the initial JavaScript: `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`. Commit it with the change; on a merge conflict run the command again | `test:unit` (the feature-shape growth test compares it with a build) | | `src/contexts//context-module.ts` | the feature needs a new context | `generate:feature-index`: `Feature belongs to undeclared context ` | | `src/contexts//context-layout.tsx` | the context needs its own frame instead of `AppShell` (see "Product home and layouts" below) | nothing: without it the context renders in `AppShell` | | `artifacts/tests/a11y-manual/.md` | every route the feature adds. Copy a record and reset it to `Status: pending-manual-review` | `test:unit` (`tests/unit/manual-a11y-evidence.test.ts`), `verify:documentation` (names the route IDs) and FE-GATE-009 (`review:a11y-manual -- --format-only`). FE-GATE-028 requires the signed review at release | diff --git a/docs/architecture/static-delivery.md b/docs/architecture/static-delivery.md index f6765dd2..66caf133 100644 --- a/docs/architecture/static-delivery.md +++ b/docs/architecture/static-delivery.md @@ -43,7 +43,7 @@ immutable release has a coherent HTML/assets/config/API/manifest tuple. Serve the app over HTTP/2 or later. The entry preloads every initial JavaScript file in parallel (`initialJsFiles` in `config/performance/budgets.json` bounds how many; the current count is -`initialJavascript.files` in config/scale/feature-shape-ceilings.json, which goes with the sample feature). Over HTTP/1.1 they queue for six connections per +`initialJavascript.files` in `config/scale/feature-shape-ceilings.json`, which goes with the sample feature). Over HTTP/1.1 they queue for six connections per host, and the first screen on Fast 3G came about one second later than with the initial chunks grouped (2026-11-03). Over HTTP/2 the difference was under 100 ms, so the template keeps the chunks split. A product that can only serve diff --git a/docs/contracts/compatibility.md b/docs/contracts/compatibility.md index ce4d99c5..9185fd3b 100644 --- a/docs/contracts/compatibility.md +++ b/docs/contracts/compatibility.md @@ -25,7 +25,7 @@ reader that accepts it must ship before any writer sends it. | `FEATURE_OVERRIDES` | record; unknown feature id ignored | additive | `featureOverrideArtifactSchema` in `src/contracts/release-artifacts.ts` | | Release manifest V2 | strict object | breaking | `releaseManifestV2ArtifactSchema` in `src/contracts/release-artifacts.ts` | | HTTP success/failure envelope (V3 with `responseEnvelope: "ENVELOPE_V1"`) | strict object (`meta` strips) | breaking | `successEnvelopeSchema`, `failureEnvelopeSchema` in `src/adapters/http/backend-envelope.ts` | -| HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `referenceResourceDtoSchema` in the reference sample's contracts/reference-schemas.ts | +| HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `referenceResourceDtoSchema` in `src/features/reference-feature/contracts/reference-schemas.ts` | | Realtime envelope | exact key set; unknown `eventType` is `MALFORMED_EVENT` | breaking | `decodeUnsafe` in `src/adapters/realtime/event-codec.ts` | | Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `decodeTransportFailure` in `src/adapters/browser-rpc/browser-rpc-runtime.ts` | | Persisted client storage | versioned key; incompatible value discarded | use a new key version | `defineStorageKey` in `src/contracts/storage-keys.ts` | diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 5f5f3859..17121c2a 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -5,7 +5,7 @@ - 뼈대는 손으로 만들지 않는다. `corepack pnpm create:feature `로 만든다. - 뼈대를 실제 기능으로 바꾸는 순서가 아래 0~11단계다. -참조 기능(src/features/reference-feature/)을 복사해 이름을 바꾸는 방법은 쓰지 않는다. +참조 기능(`src/features/reference-feature/`)을 복사해 이름을 바꾸는 방법은 쓰지 않는다. 그 방법은 접두어 없는 전역 ID, 참조 전용 계약 출처, 기능 밖 테스트 의존 때문에 여러 번 막힌다. 생성 명령은 이 문제를 미리 피한 파일을 쓴다. @@ -151,7 +151,7 @@ corepack pnpm create:feature invoice-feature - 있으면 `domain/.ts`에 둔다. - 생성 함수에서 불변식을 검사하고 `Object.freeze`로 고정한다. - 이름은 와이어 필드가 아니라 업무 이름으로 짓는다(참조 기능은 `name`을 `displayName`으로 바꾼다). -- 예제(참조 기능): src/features/reference-feature/domain/ +- 예제(참조 기능): `src/features/reference-feature/domain/` - 길이 제한(예: 제목 100자)은 domain이 아니라 경계 검증에 둔다. - 경계 검증: 값이 앱에 들어오거나 나가는 자리(요청·응답 스키마, 폼 스키마)에서 하는 검사다. - 서버가 정한 제한이면 `contracts/-schemas.ts`에 상수로 두고 요청 스키마와 폼 스키마가 같은 상수를 쓴다. 숫자가 두 곳에서 갈라지지 않는다. @@ -241,7 +241,7 @@ DTO와 problem details(`type`·`title`·`status`)를 감싸지 않고 보내는 2. problem 스키마를 problem details 모양으로 바꾼다. 3. `classifyProblem`이 모든 판정을 정한다. 실행기가 먼저 정하는 판정은 없다. -참조 기능(src/features/reference-feature/)이 이 모양이다. 참조 기능의 MSW 본문도 DTO와 problem details다. +참조 기능(`src/features/reference-feature/`)이 이 모양이다. 참조 기능의 MSW 본문도 DTO와 problem details다. **입력과 스키마 메타데이터** @@ -378,7 +378,7 @@ projectRequest: (input) => Object.freeze({ - 참조 기능은 생성 operation에 목록 route(`REFERENCE_RESOURCE_LIST`)를 적었다. 실제로 보내는 화면은 폼 route다. 동작은 같고 기록의 이름표만 다르다. 새 기능은 위 기준을 따른다. - `needs`에는 실제로 쓰는 것만 적는다. - 템플릿이 만들지 않는 capability(예: `indexedDb`)는 `src/bootstrap/product-composition.ts`에서 만든다. 제품이 새로 만드는 capability의 타입은 `src/features/product-capabilities.ts`에 적는다. [03 문서](03-outside-feature-folder.md)를 본다. -- 문제 응답 매핑 예제(참조 기능): src/features/reference-feature/adapters/reference-http-gateway.ts +- 문제 응답 매핑 예제(참조 기능): `src/features/reference-feature/adapters/reference-http-gateway.ts` ③ **잡는 검사 / 못 잡는 것** @@ -422,8 +422,8 @@ projectRequest: (input) => Object.freeze({ ② **기준** - 경로는 계약에만 적는다. 페이지와 링크는 route ID와 `buildRouteUrl`로 URL을 만든다. 경로 문자열을 페이지에 다시 적지 않는다. -- 파라미터나 검색값이 있는 라우트는 `context-routes.ts`의 handle에 `codecs`를 싣는다. 예제(참조 기능): src/features/reference-feature/context-routes.ts. - - 링크용 URL 함수도 같은 codec을 `buildRouteUrl`의 세 번째 인자로 넘긴다. 기본 생성 판의 목록 라우트는 파라미터가 없어서 넘기지 않는다. `--with-create` 판의 상세 라우트는 codec을 넘긴다. 안 넘기면 `Unregistered route codec: `로 throw한다. codec ID는 계약 `routeRuntimeContracts`의 `paramsCodec`·`searchCodec` 값이다. 예제(참조 기능): src/features/reference-feature/presentation/reference-routes.ts. +- 파라미터나 검색값이 있는 라우트는 `context-routes.ts`의 handle에 `codecs`를 싣는다. 예제(참조 기능): `src/features/reference-feature/context-routes.ts`. + - 링크용 URL 함수도 같은 codec을 `buildRouteUrl`의 세 번째 인자로 넘긴다. 기본 생성 판의 목록 라우트는 파라미터가 없어서 넘기지 않는다. `--with-create` 판의 상세 라우트는 codec을 넘긴다. 안 넘기면 `Unregistered route codec: `로 throw한다. codec ID는 계약 `routeRuntimeContracts`의 `paramsCodec`·`searchCodec` 값이다. 예제(참조 기능): `src/features/reference-feature/presentation/reference-routes.ts`. - 상세 경로는 목록 경로 뒤에 `/items/:`을 붙인다. 예: `/notice/items/:noticeId`. `/notice/:noticeId`로 두지 않는다. - 라우터(React Router)는 같은 자리에서 정적 경로를 먼저 고른다. 작성 폼 `/notice/new`가 있으면 id가 `new`인 공지는 `/notice/:noticeId`로 열 수 없다. - `items/`를 끼우면 정적 경로와 겹치지 않는다. 참조 기능도 이렇게 한다(`/examples/reference-resources/items/:resourceId`). @@ -487,7 +487,7 @@ projectRequest: (input) => Object.freeze({ }); ``` - - 예제(참조 기능): src/features/reference-feature/presentation/use-reference-feature.ts의 생성 뮤테이션 정책. + - 예제(참조 기능): `src/features/reference-feature/presentation/use-reference-feature.ts`의 생성 뮤테이션 정책. ③ **잡는 검사 / 못 잡는 것** @@ -519,7 +519,7 @@ projectRequest: (input) => Object.freeze({ - 화면 문구는 모두 catalog에서 가져온다(`message(key)`). - 링크는 6단계의 URL 함수로 만든다. -- 결과 불명 화면 예제: `create:feature --with-create`의 `presentation/-create-page.tsx`(짝 백엔드 Envelope), 참조 기능의 src/features/reference-feature/presentation/reference-resource-form-page.tsx(problem details) +- 결과 불명 화면 예제: `create:feature --with-create`의 `presentation/-create-page.tsx`(짝 백엔드 Envelope), 참조 기능의 `src/features/reference-feature/presentation/reference-resource-form-page.tsx`(problem details) ③ **잡는 검사 / 못 잡는 것** @@ -616,7 +616,7 @@ projectRequest: (input) => Object.freeze({ expect(await posts[0]!.json()).toEqual({ title: "새 공지", body: "본문입니다." }); ``` - - 핸들러를 직접 써서 요청을 모으는 방법도 있다. 예제(참조 기능): tests/features/reference-feature/reference-production-vertical.test.tsx의 504 재전송 테스트. + - 핸들러를 직접 써서 요청을 모으는 방법도 있다. 예제(참조 기능): `tests/features/reference-feature/reference-production-vertical.test.tsx`의 504 재전송 테스트. - 빠르게 돌리기: `node scripts/run-vitest.ts run tests/features/` - CI에서는 `test:coverage`(FE-GATE-005)가 `tests/features`를 돈다. `test:unit`은 `tests/unit`만 돈다. @@ -676,7 +676,7 @@ corepack pnpm test:sample-removal -- --feature=invoice-feature - 지연 페이지가 셸과 같은 구성요소(`Button`, `SearchField` 등)를 쓰면 그 구성요소가 공유 청크로 떨어져 초기 파일 수도 하나 늘 수 있다. 파일 수 상한(`initialJsFiles`)은 여유가 있다. - 예산은 `config/performance/budgets.json`에 있다. 넘었을 때 고르는 법은 `docs/operations/performance-evidence.md`에 있다. 넘으면 예산을 올리기 전에 팀이 정한다. - 생성 명령의 드릴(`test:feature-scaffold`)도 merge 단계 명령으로 이 검사를 돈다. -- 참조 기능이 설치돼 있으면 초기 JS 기록(config/scale/feature-shape-ceilings.json)도 기능과 함께 바뀐다. test:unit이 빌드와 대조한다. 생성 명령 출력 `Next:` 3번의 명령으로 다시 쓰고 같은 커밋에 넣는다. 기능 제거 드릴(`test:sample-removal -- --feature=`)은 지운 뒤 기록을 다시 쓰고 검사한다. +- 참조 기능이 설치돼 있으면 초기 JS 기록(`config/scale/feature-shape-ceilings.json`)도 기능과 함께 바뀐다. `test:unit`이 빌드와 대조한다. 생성 명령 출력 `Next:` 3번의 명령으로 다시 쓰고 같은 커밋에 넣는다. 기능 제거 드릴(`test:sample-removal -- --feature=`)은 지운 뒤 기록을 다시 쓰고 검사한다. - 로컬에서 FE-GATE-013을 돌리려면 `VITE_COMMIT_SHA=$(git rev-parse HEAD)`를 준다. 없으면 release candidate가 `source.revision`을 거절한다. 실패한 게이트의 로그는 `artifacts/quality/gates/FE-GATE-.txt`에 있다. - workflow와 같은 조건으로 돌리려면 README 로컬 merge 게이트 반복문 아래의 env 블록대로 `CI=true`와 CI 빌드 식별값(`VITE_COMMIT_SHA`, `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE` digest)을 주고 깨끗한 clone에서 돌린다. 이 값 없이 통과해도 CI에서 떨어질 수 있다(1103/11-07, 11-08). - 게이트는 한 checkout에서 하나씩 돌린다. 게이트와 증거 검사는 `dist`와 `artifacts/`의 고정 경로를 읽는다. diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index cc61cf6b..a63a822e 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -209,7 +209,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 **정본**: 어떤 status·code가 "적용 안 됨"인지는 `clean-architecture-backend-template/docs/web/http-contract.md` §2다. -**어디에 적나**: `contracts/-contract-contribution.ts`의 `commandEffect`(`classifyProblem`, `classifyStatus`, Envelope operation이면 `refusedBeforeWrite`). 예제(참조 기능): src/features/reference-feature/contracts/reference-feature-contract-contribution.ts의 `CREATE_EFFECT`. +**어디에 적나**: `contracts/-contract-contribution.ts`의 `commandEffect`(`classifyProblem`, `classifyStatus`, Envelope operation이면 `refusedBeforeWrite`). 예제(참조 기능): `src/features/reference-feature/contracts/reference-feature-contract-contribution.ts`의 `CREATE_EFFECT`. **틀리면** diff --git a/docs/manual/03-outside-feature-folder.md b/docs/manual/03-outside-feature-folder.md index ed195250..69058b8c 100644 --- a/docs/manual/03-outside-feature-folder.md +++ b/docs/manual/03-outside-feature-folder.md @@ -38,7 +38,7 @@ | 파일 | 누가 쓰나 | 다시 쓰는 명령 | 안 넣으면 | |---|---|---|---| | `public/release-manifest.json` (dev server의 manifest) | `create:feature`가 생성 뒤 바로 쓴다. 설치된 계약 패키지 목록(`packages`)과 그 다이제스트(`setDigest`) | `node scripts/write-dev-release-manifest.ts` | `test:unit`(`tests/unit/dev-release-manifest.test.ts`)이 다시 쓰는 명령을 말하며 실패한다. dev server가 `CONTRACT_SET_PACKAGE_MISSING`으로 부팅하지 못한다 | -| config/scale/feature-shape-ceilings.json의 `initialJavascript` (초기 JS 기록) | 사람이 명령으로 쓴다. 참조 기능이 설치돼 있는 동안만 있다(참조 기능과 함께 지워진다) | node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write | `test:unit`이 빌드와 대조해 실패한다 | +| `config/scale/feature-shape-ceilings.json`의 `initialJavascript` (초기 JS 기록) | 사람이 명령으로 쓴다. 참조 기능이 설치돼 있는 동안만 있다(참조 기능과 함께 지워진다) | `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write` | `test:unit`이 빌드와 대조해 실패한다 | - **브랜치 둘이 충돌한다.** `setDigest`는 설치된 패키지 전체의 해시 한 줄이고, `initialJavascript`는 빌드 전체의 합계다. 기능을 하나씩 더한 두 브랜치는 같은 줄을 다른 값으로 바꾼다. 둘째 브랜치를 합칠 때 텍스트 충돌이 난다. - **충돌하면 손으로 값을 합치지 않는다.** 아무 쪽이나 고른 뒤 위 명령을 다시 돌려 그 결과를 커밋한다. 두 기능이 다 들어간 상태의 값이 나온다. 손으로 합친 값이 틀리면 `test:unit`이 같은 명령을 말하며 실패한다. @@ -212,7 +212,7 @@ src/features/product-capabilities.ts (SERVICE_WORKER = ACTIVE) - `config/testing/risk-coverage.json`에서 그 기능을 가리키는 행 - 그 기능만 쓰던 제품 capability, 제품 인증 프로필, 계약 패키지 의존성 -그다음 dev manifest(`public/release-manifest.json`)의 계약 패키지를 `node scripts/write-dev-release-manifest.ts`로 다시 쓰고, 참조 기능이 설치돼 있으면 초기 JS 기록(config/scale/feature-shape-ceilings.json)도 node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write로 다시 쓴다(위 A의 표). 그리고 레지스트리 기준선을 다시 찍는다. 행을 빼는 것은 breaking 변경이다. +그다음 dev manifest(`public/release-manifest.json`)의 계약 패키지를 `node scripts/write-dev-release-manifest.ts`로 다시 쓰고, 참조 기능이 설치돼 있으면 초기 JS 기록(`config/scale/feature-shape-ceilings.json`)도 `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`로 다시 쓴다(위 A의 표). 그리고 레지스트리 기준선을 다시 찍는다. 행을 빼는 것은 breaking 변경이다. ```bash REGISTRY_BASELINE_OWNER=<담당> REGISTRY_BASELINE_REASON=" removed" corepack pnpm update:registry-baseline diff --git a/docs/manual/reference/patterns.md b/docs/manual/reference/patterns.md index d529b831..cbcabd14 100644 --- a/docs/manual/reference/patterns.md +++ b/docs/manual/reference/patterns.md @@ -3,7 +3,7 @@ 기능을 만들 때 쓰는 패턴과, 그 패턴의 정의와 예제가 어디 있는지 적는다. - **정의**: 플랫폼(기능 밖)에서 패턴을 제공하는 파일. -- **예제**: 복사해 볼 수 있는 기능 코드. `생성 뼈대`는 `create:feature`가 만드는 코드다. `쓰기 slice`는 `create:feature --with-create`가 더 만드는 코드다(짝 백엔드 Envelope 모양). `참조 기능`은 src/features/reference-feature/다(Envelope가 아닌 problem details 모양). 참조 기능은 지울 수 있으므로 그 경로는 백틱 없이 적는다. 백틱 경로는 문서 검사(`verify:documentation`)가 존재를 확인한다. +- **예제**: 복사해 볼 수 있는 기능 코드. `생성 뼈대`는 `create:feature`가 만드는 코드다. `쓰기 slice`는 `create:feature --with-create`가 더 만드는 코드다(짝 백엔드 Envelope 모양). `참조 기능`은 `src/features/reference-feature/`다(Envelope가 아닌 problem details 모양). 참조 기능 경로도 다른 경로처럼 백틱으로 적는다. 문서 검사(`verify:documentation`)는 참조 기능이 있는 동안 그 경로가 있는지 확인하고, 참조 기능을 지운 사본에서는 없어도 된다고 본다(`scripts/lib/removable-template-features.ts`). - 예제가 없는 패턴은 **없음**이라고 적었다. 그 패턴은 정의를 읽고 직접 쓴다. 참조 기능은 예제일 뿐이다. 복사해 이름을 바꾸지 않는다. 모양을 보고 생성 뼈대에 옮긴다. @@ -13,12 +13,12 @@ | 패턴 | 정의 | 예제 | 검사 | |---|---|---|---| | 기능 모듈 등록 | `src/features/feature-module.ts` (`defineFeatureModule`, `defineFeatureRuntime`), 생성기 | 생성 뼈대 `feature-module.ts`, `feature-runtime.ts` | 생성기, 기능 ID와 계약 `featureId` 일치 | -| context 소속 선언 | `src/contexts/bounded-context-module.ts` | 참조 기능의 src/contexts/reference-context/context-module.ts | 생성기(없는 context, 예산), 앱 모듈(루트 밖 라우트) | +| context 소속 선언 | `src/contexts/bounded-context-module.ts` | 참조 기능의 `src/contexts/reference-context/context-module.ts` | 생성기(없는 context, 예산), 앱 모듈(루트 밖 라우트) | | context 전용 레이아웃 | `docs/architecture/starter-experience.md` "Product home and layouts" | `tests/helpers/fixture-layout-product.tsx` (테스트 fixture) | `tests/component/context-layouts.test.tsx` | | 앱 홈 대신하기 | `src/contracts/routes.ts`의 `FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS` | 없음 (기능 예제) | 조립 (두 기능이 `APP_HOME`을 선언하면 실패) | | 조립 기여(`needs`) | `src/features/feature-adapter-contribution.ts` | 생성 뼈대 `adapters/create--feature-input.ts` | 조립 (없는 capability, 다른 기능의 input) | | 제품 capability | `src/features/product-capabilities.ts`(타입), `src/bootstrap/product-composition.ts`(값), `src/bootstrap/product-composition-contract.ts` | `recipes/frontend-capabilities/indexeddb-feature-capability.ts` | `check:types` | -| 기능 끄기 | `config/runtime/.json`의 `FEATURE_OVERRIDES` | `config/runtime/local.json` | 참조 기능의 tests/component/product-feature-switch.test.tsx | +| 기능 끄기 | `config/runtime/.json`의 `FEATURE_OVERRIDES` | `config/runtime/local.json` | 참조 기능의 `tests/component/product-feature-switch.test.tsx` | ## 라우트 diff --git a/docs/operations/adapter-remediation-ledger.md b/docs/operations/adapter-remediation-ledger.md index 78819d06..5e48aab7 100644 --- a/docs/operations/adapter-remediation-ledger.md +++ b/docs/operations/adapter-remediation-ledger.md @@ -194,7 +194,7 @@ Captured after every correctness task landed. | `git diff --check` | 0 | clean | | `corepack pnpm test:component` | 0 | 126 passed | | `corepack pnpm test:integration` | 0 | 52 passed | -| test:reference-feature (the reference sample's script) | 0 | 26 passed | +| `corepack pnpm test:reference-feature` | 0 | 26 passed | | `corepack pnpm test:recipes` | 0 | 17 passed | | `corepack pnpm test:unit` | 1 | 1585 passed / 19 failed tests; the 19 are the unchanged pre-existing `ci-artifact-contract` sandbox failures | | `corepack pnpm check:registries` | 0 | 11 registries PASS | @@ -340,7 +340,7 @@ Run on the landed tree. Only what actually passed is claimed as passing. | `tests/unit` + `tests/integration`, no exclusions | — | 1643 passed / 1747; the 104 failures are the four environmental files below | | `corepack pnpm test:component` | 0 | 126 passed | | `corepack pnpm test:recipes` | 0 | 17 passed | -| test:reference-feature (the reference sample's script) | 0 | 26 passed | +| `corepack pnpm test:reference-feature` | 0 | 26 passed | ### Environmental failures, not claimed as green diff --git a/docs/operations/performance-evidence.md b/docs/operations/performance-evidence.md index 9e01948c..5c231aee 100644 --- a/docs/operations/performance-evidence.md +++ b/docs/operations/performance-evidence.md @@ -20,8 +20,9 @@ Performance evidence is deliberately split by measurement context: 보고 예산을 정한다. 기준선 숫자는 이 문서에 적지 않는다. 손으로 적은 숫자는 두 번 낡았다. 기록은 -config/scale/feature-shape-ceilings.json의 `initialJavascript` 한 곳이다. 이 파일과 아래 -측정 테스트는 참조 기능을 복사해 재므로 샘플과 함께 지워진다. 그래서 경로를 백틱 없이 적는다. +`config/scale/feature-shape-ceilings.json`의 `initialJavascript` 한 곳이다. 이 파일과 아래 +측정 테스트는 참조 기능을 복사해 재므로 샘플과 함께 지워진다. 문서 검사는 샘플을 지운 사본에서 +이 경로들을 요구하지 않는다(`scripts/lib/removable-template-features.ts`). | 칸 | 뜻 | |---|---| @@ -29,14 +30,15 @@ config/scale/feature-shape-ceilings.json의 `initialJavascript` 한 곳이다. | `perFeatureGzipBytes` | 있는 context에 참조 기능 모양 기능을 하나 더할 때 느는 초기 JS. 상한 1 KiB | | `perContextGzipBytes` | 새 context를 하나 더할 때 느는 초기 JS. 상한 512 B | -- tests/unit/feature-shape-growth.test.ts(unit, merge 단계)가 매번 빌드해 이 +- `tests/unit/feature-shape-growth.test.ts`(unit, merge 단계)가 매번 빌드해 이 값을 재고, 상한을 넘거나 기록과 다르면(합계 256 B 초과, 파일 수 불일치, 기능· context 비용 10% 초과) 실패한다. 실패 메시지에 잰 값이 나온다. - 합계의 허용 오차는 바이트로 둔다(1105/15-02). build id만 달라도 합계가 수십 B 움직이므로 0으로 둘 수 없다. 예전 1%(약 2 KB)는 남은 여유와 기능 하나보다 커서, 여유를 다 쓴 변경이 기록을 고치지 않고 지나갈 수 있었다. -- 기록을 고칠 때는 `node scripts/scale/measure-feature-shape-growth.ts - --initial-baseline --write`를 돌리고 같은 변경에 넣는다. +- 기록을 고칠 때는 + `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`를 + 돌리고 같은 변경에 넣는다. - 여유는 예산에서 `gzipBytes`를 뺀 값이다. 그것을 `perFeatureGzipBytes`로 나누면 더 넣을 수 있는 기능 수다. 새 context마다 `perContextGzipBytes`가 더 든다. - 기능 실행부(`feature-runtime.ts`)는 라우트에 들어갈 때 받는 lazy chunk다. diff --git a/tests/unit/template-feature-removal-documents.test.ts b/tests/unit/template-feature-removal-documents.test.ts index 68d564e9..a8de7cc2 100644 --- a/tests/unit/template-feature-removal-documents.test.ts +++ b/tests/unit/template-feature-removal-documents.test.ts @@ -62,8 +62,9 @@ async function verifyWithout(removed: readonly string[]) { /** * Runs this repository's verify:documentation on a copy of the documents * with `mutate` applied to `document`; the code facts are this repository's. + * `documents` are the ones it checked (docs/README.md §1 and what it links). */ -async function verifyDocuments(document: string, mutate: (text: string) => string) { +async function verifyDocuments(document: string, mutate: (text: string) => string = (text) => text) { const parent = await mkdtemp(path.join(tmpdir(), "template-feature-documents-")); const root = path.join(parent, "frontend"); try { @@ -72,7 +73,11 @@ async function verifyDocuments(document: string, mutate: (text: string) => strin for (const entry of inputs) await cp(entry, path.join(root, entry), { recursive: true }); const target = path.join(root, document); await writeFile(target, mutate(await readFile(target, "utf8"))); - return spawnSync(process.execPath, [path.resolve(CHECKER)], { cwd: root, encoding: "utf8" }); + const result = spawnSync(process.execPath, [path.resolve(CHECKER)], { cwd: root, encoding: "utf8" }); + const report = JSON.parse( + await readFile(path.join(root, "artifacts/quality/documentation-review.json"), "utf8"), + ) as { documentReferences: { path: string }[] }; + return { ...result, documents: report.documentReferences.map((entry) => entry.path) }; } finally { await rm(parent, { recursive: true, force: true }); } @@ -89,8 +94,8 @@ describe("verify:documentation after a template feature is deleted (1105/14-01)" ); // Only a deleted feature's paths are let through. While a feature is - // installed a missing path under it fails, and a folder that is not a - // removable template feature (a misspelt one) fails whether or not it exists. + // installed a missing path under it fails, and so does a feature folder + // that is not on the list (a misspelt one). it("still fails on a missing path under an installed template feature or an unknown folder", async () => { const document = "docs/architecture/starter-experience.md"; const missing = [ @@ -108,3 +113,44 @@ describe("verify:documentation after a template feature is deleted (1105/14-01)" for (const file of missing) expect(result.stderr).toContain(file); }, 60_000); }); + +/** Fenced blocks whose command lines verify:documentation reads. */ +const SHELL_FENCE = /^(?:bash|sh|shell|console|zsh)?$/u; + +/** + * 1105/14-03. The fix for 1103/14-04 wrote the reference sample's paths + * without backticks so that a copy without the sample passed, which also took + * 26 lines out of the check while the sample is installed: renaming one of + * its files left the manual pointing at nothing. Deleted features' paths are + * accepted now (above), so a current contract document names a removable + * template feature's path or script only where verify:documentation reads + * it: in an inline code span, a link target or a shell code block. + */ +describe("removable template features in the current contract documents (1105/14-03)", () => { + it("names their paths and scripts only where verify:documentation checks them", async () => { + const { documents } = await verifyDocuments("docs/README.md"); + const owned = REMOVABLE_TEMPLATE_FEATURES.flatMap((feature) => [ + ...removableTemplateFeaturePaths(feature), + ...feature.scripts, + ]); + const unchecked: string[] = []; + for (const document of documents) { + const lines = (await readFile(document, "utf8")).split("\n"); + let fence: string | null = null; + for (const [index, line] of lines.entries()) { + const marker = /^\s*```(\w*)/u.exec(line); + if (marker) { + fence = fence === null ? (marker[1] ?? "") : null; + continue; + } + if (fence !== null && SHELL_FENCE.test(fence)) continue; + const prose = line.replace(/`[^`\n]+`/gu, "").replace(/\]\([^)\s]+\)/gu, "]"); + for (const entry of owned) { + if (prose.includes(entry)) unchecked.push(`${document}:${index + 1}: ${entry}`); + } + } + } + expect(documents).toContain("docs/manual/01-add-a-feature.md"); + expect(unchecked).toEqual([]); + }, 60_000); +}); From e6b2a4f6bfb377b34afb3c498863d1ae265bad17 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 23:10:40 +0900 Subject: [PATCH 04/12] =?UTF-8?q?fix(manual):=20=EC=A7=9D=20=EB=B0=B1?= =?UTF-8?q?=EC=97=94=EB=93=9C=20OIDC=20=EC=84=A4=EC=A0=95=20=ED=82=A4=20?= =?UTF-8?q?=EC=98=88=EC=8B=9C=EC=9D=98=20FE-REG-ENV=20=ED=96=89=EC=97=90?= =?UTF-8?q?=20defaultValue=EB=A5=BC=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 매뉴얼 04 §3.2의 PRODUCT_ENV_REGISTRY 예시 두 행(OIDC_ISSUER, OIDC_CLIENT_ID)에 defaultValue가 없다. 행 타입은 defaultValue를 필수 칸으로 가진다(src/contracts/env.ts). 그래서 제품이 그대로 붙이면 check:types:app이 env.ts에서 TS2322로, env-registry-coverage가 `row {"required":false}`로 실패한다(리뷰 14-R3). 매뉴얼 03 C절과 product-contracts.ts 주석은 defaultValue를 쓴다. 고른 방법 - 두 행에 `defaultValue: null`을 더하고(.optional() 키), 행 칸의 규칙을 예시 아래 한 줄로 적었다. - 테스트 tests/unit/manual-paired-backend-settings.test.ts: 매뉴얼 §3.2의 ts 블록을 그대로 저장소 사본의 새 파일로 두고, 사본의 product-contracts.ts가 제품 자신의 파일(옆에 보존)에 그 키를 더해 내보낸다. 그 사본에서 tsconfig.app.json 타입 검사와, env-registry-coverage와 같은 행 대조(키가 없을 때 스키마가 내는 required·defaultValue)를 node로 돌린다. 제품 파일을 덮어쓰지 않으므로 다운스트림에서도 그대로 돈다(1105/09-01과 같은 방식). - 문서를 읽는 테스트라 REMOVAL_FIXTURE_DOCUMENT_TESTS에 더했다. 그 목록의 항목이 문서를 읽는지 보는 removal-fixture.test.ts 정규식에 `docs/`를 더했다. 문서 대상(REMOVAL_FIXTURE_DOCUMENT_TARGETS)에 docs가 있어 README나 CHANGELOG를 읽지 않는 문서 테스트도 있을 수 있다. 목록의 뜻은 그대로다. - 버린 대안: 예시 행을 recipe에서 export하고 recipe 테스트가 그것으로 조립하기(리뷰 ②). contracts가 recipe를 import할 수 없어 매뉴얼이 다시 복사를 시킨다. 이번 테스트가 매뉴얼 블록 자체를 지킨다. 위험·한계 - 행 대조는 env-registry-coverage의 schemaDeclaration을 이 테스트 안에 다시 적었다(사본에서 vitest를 띄우지 않으려고). 규칙이 바뀌면 둘을 함께 고친다. - §3.3·§4.3의 코드 예시는 여전히 컴파일하지 않는다(recipe를 복사한 뒤의 모양이라 사본 구성이 더 크다). - 테스트가 저장소 사본을 만들고 tsc app 프로그램을 돈다. test:unit이 몇 초 는다. 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/manual-paired-backend-settings.test.ts tests/unit/removal-fixture.test.ts, corepack pnpm verify:documentation Refs: 1105/14-02 --- docs/manual/04-paired-backend-session.md | 5 +- scripts/lib/removal-fixture.ts | 2 + .../manual-paired-backend-settings.test.ts | 145 ++++++++++++++++++ tests/unit/removal-fixture.test.ts | 3 +- 4 files changed, 152 insertions(+), 3 deletions(-) create mode 100644 tests/unit/manual-paired-backend-settings.test.ts diff --git a/docs/manual/04-paired-backend-session.md b/docs/manual/04-paired-backend-session.md index a09a40c8..9a9b6b2c 100644 --- a/docs/manual/04-paired-backend-session.md +++ b/docs/manual/04-paired-backend-session.md @@ -126,12 +126,13 @@ export const PRODUCT_RUNTIME_CONFIG_FIELDS = Object.freeze({ }); export const PRODUCT_ENV_REGISTRY = Object.freeze({ - OIDC_ISSUER: { phase: "runtime", classification: "public", required: false }, - OIDC_CLIENT_ID: { phase: "runtime", classification: "public", required: false }, + OIDC_ISSUER: { phase: "runtime", classification: "public", required: false, defaultValue: null }, + OIDC_CLIENT_ID: { phase: "runtime", classification: "public", required: false, defaultValue: null }, } as const); ``` - `.optional()`로 둔다. 값이 비면 owner는 `integration-failed`로 닫힌다. 잘못된 곳으로 로그인하지 않는다. +- 행의 `required`·`defaultValue`는 그 키가 없을 때 스키마가 하는 것과 같아야 한다. `.optional()`이면 `required: false, defaultValue: null`이다(`tests/unit/env-registry-coverage.test.ts`). 이 블록은 그대로 `tests/unit/manual-paired-backend-settings.test.ts`가 타입 검사와 그 대조를 돌린다. - `config/runtime/local.json`에 `"OIDC_ISSUER": "http://localhost:8081/realms/ca-skeleton"`, `"OIDC_CLIENT_ID": "ca-frontend"`를 더한다. - `OIDC_ISSUER`는 백엔드 `APP_SECURITY_JWT_ISSUER`와 글자 하나까지 같아야 한다. 끝의 `/`도 같아야 한다. - 원격 issuer는 HTTPS만 받는다. HTTP는 `localhost`, `127.0.0.1`, `[::1]`에서만 받는다. diff --git a/scripts/lib/removal-fixture.ts b/scripts/lib/removal-fixture.ts index e892a57c..2eee70cf 100644 --- a/scripts/lib/removal-fixture.ts +++ b/scripts/lib/removal-fixture.ts @@ -76,6 +76,8 @@ export const REMOVAL_FIXTURE_DOCUMENT_TESTS = Object.freeze([ "tests/unit/feature-tracked-files.test.ts", // 1105/14-01 "tests/unit/template-feature-removal-documents.test.ts", + // 1105/14-02. Reads a code block of docs/manual. + "tests/unit/manual-paired-backend-settings.test.ts", ] as const); /** The tests a fixture copied from `copyTargets` cannot run. */ diff --git a/tests/unit/manual-paired-backend-settings.test.ts b/tests/unit/manual-paired-backend-settings.test.ts new file mode 100644 index 00000000..8615b9e3 --- /dev/null +++ b/tests/unit/manual-paired-backend-settings.test.ts @@ -0,0 +1,145 @@ +import { spawnSync } from "node:child_process"; +import { existsSync } from "node:fs"; +import { cp, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; + +import { afterAll, describe, expect, it } from "vitest"; + +import { linkFixtureNodeModules } from "../../scripts/lib/fixture-node-modules.ts"; +import { REMOVAL_FIXTURE_COPY_TARGETS } from "../../scripts/lib/removal-fixture.ts"; + +/** + * 1105/14-02. docs/manual/04-paired-backend-session.md §3.2 is the block a + * product pastes into src/contracts/product-contracts.ts for the OIDC + * settings of the paired backend's jwt mode. Its FE-REG-ENV rows had no + * `defaultValue`, so pasted as written `check:types` failed (TS2322 in + * src/contracts/env.ts) and so did env-registry-coverage. This puts the + * block, unchanged, into a copy of the repository next to the product's own + * settings and runs the app typecheck program and that row check on it. + */ +const MANUAL = "docs/manual/04-paired-backend-session.md"; +const PRODUCT_CONTRACTS = "src/contracts/product-contracts.ts"; +/** Reserved for this test, so a product's own files are never overwritten. */ +const MANUAL_SETTINGS = "src/contracts/manual-04-product-settings.ts"; +const KEPT_CONTRACTS = "src/contracts/manual-04-kept-product-contracts.ts"; +const ROW_CHECK = "manual-04-env-rows.ts"; + +/** The first ts block of the manual's §3.2. */ +function settingsBlock(manual: string): string { + const section = manual.split(/^### 3\.2 /mu)[1]?.split(/^### /mu)[0] ?? ""; + const block = /```ts\n([\s\S]*?)\n```/u.exec(section)?.[1]; + if (block === undefined) throw new Error(`${MANUAL} §3.2 has no ts block`); + return `${block}\n`; +} + +/** product-contracts.ts: the product's own file, kept beside it, plus the manual's keys. */ +const PRODUCT_CONTRACTS_SOURCE = `import { + PRODUCT_ENV_REGISTRY as KEPT_PRODUCT_ENV_REGISTRY, + PRODUCT_RUNTIME_CONFIG_FIELDS as KEPT_PRODUCT_RUNTIME_CONFIG_FIELDS, +} from "./${path.posix.basename(KEPT_CONTRACTS)}"; +import { + PRODUCT_ENV_REGISTRY as MANUAL_PRODUCT_ENV_REGISTRY, + PRODUCT_RUNTIME_CONFIG_FIELDS as MANUAL_PRODUCT_RUNTIME_CONFIG_FIELDS, +} from "./${path.posix.basename(MANUAL_SETTINGS)}"; + +export * from "./${path.posix.basename(KEPT_CONTRACTS)}"; + +export const PRODUCT_RUNTIME_CONFIG_FIELDS = Object.freeze({ + ...KEPT_PRODUCT_RUNTIME_CONFIG_FIELDS, + ...MANUAL_PRODUCT_RUNTIME_CONFIG_FIELDS, +}); + +export const PRODUCT_ENV_REGISTRY = Object.freeze({ + ...KEPT_PRODUCT_ENV_REGISTRY, + ...MANUAL_PRODUCT_ENV_REGISTRY, +} as const); +`; + +/** + * The rule of tests/unit/env-registry-coverage.test.ts, for the manual's + * keys: each has a runtime row whose `required` and `defaultValue` are what + * the schema field does with an absent key. + */ +const ROW_CHECK_SOURCE = `import { isDeepStrictEqual } from "node:util"; + +import { ENV_REGISTRY } from "./src/contracts/env.ts"; +import { PRODUCT_ENV_REGISTRY } from "./${MANUAL_SETTINGS}"; +import { runtimeConfigV2ArtifactSchema } from "./src/contracts/release-artifacts.ts"; + +const shape = runtimeConfigV2ArtifactSchema.shape as Record< + string, + { safeParse(value: unknown): { success: boolean; data?: unknown } } +>; +const rows = ENV_REGISTRY as Record; +const problems = Object.keys(PRODUCT_ENV_REGISTRY).flatMap((key) => { + const field = shape[key]; + const row = rows[key]; + if (field === undefined || row?.phase !== "runtime") return [key + ": no runtime config field or runtime row"]; + const parsed = field.safeParse(undefined); + const expected = parsed.success + ? { required: false, defaultValue: parsed.data ?? null } + : { required: true, defaultValue: null }; + const declared = { required: row.required, defaultValue: row.defaultValue }; + return isDeepStrictEqual(declared, expected) + ? [] + : [key + ": row " + JSON.stringify(declared) + ", schema " + JSON.stringify(expected)]; +}); +process.stdout.write(JSON.stringify(problems)); +`; + +const roots: string[] = []; + +afterAll(async () => { + await Promise.all(roots.map((root) => rm(root, { recursive: true, force: true }))); +}); + +async function copyRepository(): Promise { + const root = await mkdtemp(path.join(tmpdir(), "manual-paired-backend-settings-")); + roots.push(root); + for (const entry of REMOVAL_FIXTURE_COPY_TARGETS) { + // A removal drill runs this test in a copy that has already lost some. + if (!existsSync(path.resolve(entry))) continue; + await cp(path.resolve(entry), path.join(root, entry), { + recursive: true, + filter: (source) => !source.includes(`${path.sep}.generated`), + }); + } + await linkFixtureNodeModules(root); + return root; +} + +describe("docs/manual/04 §3.2 product settings, pasted as written (1105/14-02)", () => { + it("typechecks and states the FE-REG-ENV rows as the schema reads the keys", async () => { + const block = settingsBlock(await readFile(MANUAL, "utf8")); + expect(block).toContain("PRODUCT_ENV_REGISTRY"); + const root = await copyRepository(); + for (const reserved of [MANUAL_SETTINGS, KEPT_CONTRACTS, ROW_CHECK]) { + expect(existsSync(path.join(root, reserved)), reserved).toBe(false); + } + await rename(path.join(root, PRODUCT_CONTRACTS), path.join(root, KEPT_CONTRACTS)); + await writeFile(path.join(root, MANUAL_SETTINGS), block); + await writeFile(path.join(root, PRODUCT_CONTRACTS), PRODUCT_CONTRACTS_SOURCE); + await writeFile(path.join(root, ROW_CHECK), ROW_CHECK_SOURCE); + + const generated = spawnSync( + process.execPath, + [path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`], + { encoding: "utf8" }, + ); + expect(generated.stderr).toBe(""); + expect(generated.status).toBe(0); + + const typecheck = spawnSync( + path.resolve("node_modules/.bin/tsc"), + ["--project", path.join(root, "tsconfig.app.json")], + { encoding: "utf8" }, + ); + expect(typecheck.stdout + typecheck.stderr).toBe(""); + expect(typecheck.status).toBe(0); + + const rows = spawnSync(process.execPath, [path.join(root, ROW_CHECK)], { cwd: root, encoding: "utf8" }); + expect(rows.stderr).toBe(""); + expect(JSON.parse(rows.stdout)).toEqual([]); + }, 120_000); +}); diff --git a/tests/unit/removal-fixture.test.ts b/tests/unit/removal-fixture.test.ts index e48b8283..017aa20e 100644 --- a/tests/unit/removal-fixture.test.ts +++ b/tests/unit/removal-fixture.test.ts @@ -157,7 +157,8 @@ describe("document tests in a removal fixture", () => { for (const test of REMOVAL_FIXTURE_DOCUMENT_TESTS) { expect(existsSync(test), test).toBe(documentsPresent); if (documentsPresent) { - await expect(readFile(test, "utf8")).resolves.toMatch(/README\.md|CHANGELOG\.md/u); + // 1105/14-02. docs/ is one of the document targets too. + await expect(readFile(test, "utf8")).resolves.toMatch(/README\.md|CHANGELOG\.md|docs\//u); } } }); From 832774f475a6681ac032021ff963274ecdbe2539 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 23:15:00 +0900 Subject: [PATCH 05/12] =?UTF-8?q?docs(changelog):=2011-03=20=EC=A0=88?= =?UTF-8?q?=EC=9D=98=20=EC=B4=88=EA=B8=B0=20=ED=8C=8C=EC=9D=BC=20=EC=83=81?= =?UTF-8?q?=ED=95=9C=EA=B3=BC=20=EC=95=8C=EB=A0=A4=EC=A7=84=20=EC=A0=9C?= =?UTF-8?q?=ED=95=9C=20=EA=B8=B0=EC=A4=80=EC=9D=84=20=EB=81=9D=20=EC=BB=A4?= =?UTF-8?q?=EB=B0=8B=EC=97=90=20=EB=A7=9E=EC=B6=98=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 미출시 11-03 절(752a61f → fix/maturity-review-2026-11-03)은 머리 규칙이 "최종 상태만 적는다"인데 세 곳이 중간 상태나 틀린 이름을 적는다. - 초기 JS 파일 상한: BREAKING 7단계와 FE-GATE-012 [계약] 행이 "26개"다. 코드는 32다(config/performance/budgets.json, 2fef27d). 같은 절의 X2 줄은 32라고 적는다. [계약] 행이 인용한 1b8cb12(26으로 올림)는 범위 안에서 2fef27d가 다시 바꾼 중간 상태다. - 알려진 제한 머리가 "이 절을 쓴 끝 커밋(f887817)"이다. 범위 끝은 8a44226이다. - "옮긴 뒤 확인" 2단계가 "로컬 merge 게이트 14개 중" 목록에 verify:documentation(FE-GATE-017)과 제품 기능 제거 드릴을 둔다. FE-GATE-017은 documentation 단계이고(config/ci/gates.json), 제품 기능 드릴은 어느 게이트도 돌리지 않는다(FE-GATE-020은 참조 기능만). 고른 방법 - 두 곳의 상한을 32(템플릿 26 + 기능 여유)로 고치고, [계약] 행 커밋을 1b8cb12 대신 2fef27d로 적었다. 템플릿 자체의 파일 수 26은 따로 적었다. - 알려진 제한 머리를 범위 끝 8a44226 기준으로 바꿨다. 2026-11-05 리뷰 영역 14가 8a44226에서 그 줄들을 대조했다(낡은 줄은 지난 라운드에 빠짐). 위 절(2026-11-05 조치)이 바꾼 줄은 위 절에 적는다고 밝혔다. - merge 단계에서 문서 검사를 하는 것은 FE-GATE-005의 documentation-readiness라 test:unit 줄에 넣고, FE-GATE-017과 제품 기능 드릴은 "merge 게이트 밖" 단계로 나눴다. 위험·한계 - 문서만 바꿨다. 1,873 B 여유는 기록 값이다(빌드마다 수십 B 다르다). - 위 절이 바꾸는 알려진 제한 줄(기능 라우트 첫 진입, SW composeProduct 칸 등)은 위 절 행을 쓸 때 함께 고친다. 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts Refs: 1103/14-01, 1103/15-02 --- CHANGELOG.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 75b63762..3ad295cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -119,7 +119,7 @@ - 포트를 직접 구현한 코드: `OpfsJournalPort.countPartitionTransactions`·`removePartition`, worker gateway의 `removePartition`, `PublicCacheInspection.activePointer`가 필수 칸이다. - offline-indexeddb recipe 타입: `src`와 이름이 같은 34개가 `src` 타입을 다시 내보낸다. (1103/04-01, 1103/04-04, 1103/09-04, 1103/05-01, 0929/05-01, 1103/02-05, 0929/05-03) -7. **초기 JS 예산.** 예산은 gzip 204,800 B와 초기 파일 26개다(`config/performance/budgets.json`, merge 게이트 FE-GATE-012의 `check:bundle`). 템플릿 자체가 202,927 B를 쓴다. 여유는 1,873 B다. 측정용 기능 복사본 하나를 같은 context에 더하면 +768 B, 새 context 하나는 +233 B다(`config/scale/feature-shape-ceilings.json`. `tests/unit/feature-shape-growth.test.ts`가 기능 1 KiB·context 512 B로 막는다). 제품 기능의 선언(라우트 표, 문구)은 초기 청크에 들어간다. memento-web(라우트 14개)과 기능 모듈로 바꾼 TechLog의 크기는 템플릿이 재지 않았다. `build` 뒤 `check:bundle`이 넘은 한도와 초과량을 적는다. 예산을 올릴 때는 `docs/operations/performance-evidence.md`대로 기준선·새 측정값·이유를 같은 변경에 적는다. 초기 파일 수는 HTTP/2 서빙이 전제다. +7. **초기 JS 예산.** 예산은 gzip 204,800 B와 초기 파일 32개다(`config/performance/budgets.json`, merge 게이트 FE-GATE-012의 `check:bundle`). 템플릿 자체가 202,927 B와 파일 26개를 쓴다. 여유는 1,873 B다. 측정용 기능 복사본 하나를 같은 context에 더하면 +768 B, 새 context 하나는 +233 B다(`config/scale/feature-shape-ceilings.json`. `tests/unit/feature-shape-growth.test.ts`가 기능 1 KiB·context 512 B로 막는다). 제품 기능의 선언(라우트 표, 문구)은 초기 청크에 들어간다. memento-web(라우트 14개)과 기능 모듈로 바꾼 TechLog의 크기는 템플릿이 재지 않았다. `build` 뒤 `check:bundle`이 넘은 한도와 초과량을 적는다. 예산을 올릴 때는 `docs/operations/performance-evidence.md`대로 기준선·새 측정값·이유를 같은 변경에 적는다. 초기 파일 수는 HTTP/2 서빙이 전제다. (1101/15-01, 1103/15-02, 1103/15-03, 1103/15-04, 1103/15-05) #### 옮긴 뒤 확인 @@ -127,12 +127,13 @@ 1. 로컬 merge 게이트 14개를 돈다(README "CI and evidence"의 반복문). `config/ci/product-gates.json`에 적은 `PRODUCT-GATE-NNN`은 workflow의 `product_merge_gate` job이 돈다. 2. 그중 이 묶음 때문에 먼저 볼 것: - `check:registries`: `11 registries PASS`. 기준선을 다시 승인한 뒤에는 `compatibility=none`. - - `test:unit`: `schema-metadata-policy`, `env-registry-coverage`, `feature-shape-growth`. + - `test:unit`: `schema-metadata-policy`, `env-registry-coverage`, `feature-shape-growth`, `documentation-readiness`(문서 검사. 참조 기능을 지운 제품도 통과한다). - `test:component`: `layout-landmarks`, `context-layouts`. - `build` 뒤 `check:bundle`: 예산 안. - - `verify:documentation`(FE-GATE-017): 참조 기능을 지운 제품도 통과한다. - - `test:sample-removal -- --feature=<제품 기능 id>`: 그 기능을 지운 사본이 게이트를 통과한다. -3. 배포가 있는 제품: FE-GATE-019는 TLS ALPN `h2`와 entry 응답의 `Content-Encoding`(br·gzip·zstd)을 요구한다. HTTP/1.1이나 압축하지 않는 호스트는 FAIL이다. +3. merge 게이트 밖에서 한 번 돈다. + - `verify:documentation`(FE-GATE-017, documentation 단계). merge 단계에서는 FE-GATE-005의 `documentation-readiness`가 같은 스크립트를 돈다. + - `test:sample-removal -- --feature=<제품 기능 id>`: 그 기능을 지운 사본이 게이트를 통과한다. FE-GATE-020은 참조 기능만 지워 본다. +4. 배포가 있는 제품: FE-GATE-019는 TLS ALPN `h2`와 entry 응답의 `Content-Encoding`(br·gzip·zstd)을 요구한다. HTTP/1.1이나 압축하지 않는 호스트는 FAIL이다. ### 보안·계약 변경 @@ -228,7 +229,7 @@ | 표시 | 변경 | 영향 경로 | 커밋 | |---|---|---|---| -| [계약] | 번들 예산 게이트 FE-GATE-012가 merge 단계에서 돈다. 예산은 gzip 204,800 B와 초기 파일 26개(`initialJsFiles`)다. `check:bundle`은 넘은 한도와 초과량을 적고, `bundle.json`에 `initialJsFiles`·`initialFilesPassed`가 있다. 초기 JS 기준선은 `config/scale/feature-shape-ceilings.json`의 `initialJavascript`(지금 202,927 B, 26개, 기능 하나 +768 B, context 하나 +233 B)이고 `test:unit`이 빌드와 대조한다 (1101/15-01, 1103/15-05, 1103/15-03, 1103/15-02, 1103/15-04) | `config/ci/gates.json`, `config/performance/budgets.json`, `scripts/check-bundle.ts`, `config/scale/` | `f41e3d5`, `46dfe23`, `1b8cb12`, `c9e7bab`, `f887817` | +| [계약] | 번들 예산 게이트 FE-GATE-012가 merge 단계에서 돈다. 예산은 gzip 204,800 B와 초기 파일 32개(`initialJsFiles`, 템플릿 26개 + 기능 여유)다. `check:bundle`은 넘은 한도와 초과량을 적고, `bundle.json`에 `initialJsFiles`·`initialFilesPassed`가 있다. 초기 JS 기준선은 `config/scale/feature-shape-ceilings.json`의 `initialJavascript`(지금 202,927 B, 26개, 기능 하나 +768 B, context 하나 +233 B)이고 `test:unit`이 빌드와 대조한다 (1101/15-01, 1103/15-05, 1103/15-03, 1103/15-02, 1103/15-04) | `config/ci/gates.json`, `config/performance/budgets.json`, `scripts/check-bundle.ts`, `config/scale/` | `f41e3d5`, `46dfe23`, `2fef27d`, `c9e7bab`, `f887817` | | [계약] | 호스팅 계약: 파일이 없는 모든 경로에 그 release의 `index.html`을 HTML 헤더로 준다(SPA fallback, `appRoute`). 워커를 싣는 빌드의 `service-worker.js`는 `no-cache`다. live probe는 사전 캐시 확장자마다 `Content-Type`을 확인한다. nginx 예시는 `docs/operations/release-cache-rollback.md` (1101/13-04, 1103/06-03) | `config/hosting/cache-policy.json`, `scripts/lib/hosting-probe.ts`, `scripts/verify-hosting-headers.ts` | `629c8f0`, `0f58abb` | | [계약] | FE-GATE-019(production 단계)는 workflow의 `deployment` 슬롯이 배포한 승격 release를 본다. 슬롯이 비어 있으면 `UNVERIFIED`다. 배포된 `release-manifest.json`의 buildId·releaseId, `config.json`(비상 스위치 제외), `index.html` entry가 후보와 다르면 FAIL이다. TLS ALPN `h2`와 entry `Content-Encoding`(br·gzip·zstd)을 요구한다(`config/hosting/cache-policy.json`). HTTP/1.1이나 비압축 호스트는 FAIL이다. nginx 예시가 http2·gzip을 켠다 (1101/13-01, 1103/13-01, 1103/13-02) | `.gitea/workflows/quality-gates.yml`, `config/ci/gates.json`, `config/hosting/cache-policy.json`, `scripts/verify-hosting-headers.ts` | `de379ea`, `4bce8bf`, `2e12d2f` | | [계약] | 제품 소유 `config/ci/product-gates.json`: 배포(`deployment`, package script와 `vars.*`·`secrets.*` 바인딩)와 제품 merge 검사(`PRODUCT-GATE-NNN`, job `product_merge_gate`). 템플릿은 승격 후보를 받아 `CANDIDATE_ARCHIVE_SHA256`으로 확인하고 푸는 단계를 만든다. 배포 슬롯은 `gates.json`이 아니라 여기서 채운다 (1103/12-07, 1103/13-01) | `config/ci/product-gates.json`, `scripts/contracts/product-ci-overlay.ts`, `scripts/generate-ci-workflow.ts` | `4c4248a`, `2e12d2f` | @@ -270,7 +271,7 @@ ### 알려진 제한 -이 절을 쓴 끝 커밋(`f887817`)에서 사실인 것만 적었다. +이 절의 범위 끝(브랜치 `fix/maturity-review-2026-11-03`의 `8a44226`)에서 사실인 것만 적었다. 위 절이 바꾼 것은 위 절에 적는다. - 다운스트림 이행: 위 안내를 두 제품 코드에 적용해 게이트를 돌려 보지 않았다. memento-web의 숫자(descriptor 29개, schemaId 42개 + `MementoProblem`)는 memento `d3810a0`을 정적으로 센 값이다. - 직접 조립 제품(tech-log의 TechLog): 템플릿에 그 자리가 없다. 기능 모듈로 바꾸는 길은 fixture(`tests/helpers/fixture-layout-product.tsx`)로만 검사했고 TechLog 화면으로는 해 보지 않았다. 직접 조립을 유지하면 FE-REG-API·FE-REG-SCHEMA와 스키마 메타 대조 테스트가 TechLog descriptor를 보지 않는다. From 1e576ef1aa4d7b9ee58ddc9e9eed1d1fd21762cb Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 23:15:47 +0900 Subject: [PATCH 06/12] =?UTF-8?q?docs(changelog):=2011-03=20=EC=A0=88=20po?= =?UTF-8?q?ll=20=ED=96=89=EC=97=90=20=EB=8D=98=EC=A7=80=EB=8A=94=20execute?= =?UTF-8?q?=20=EA=B7=9C=EC=B9=99=EC=9D=B4=20=EB=B0=94=EB=80=8C=EC=97=88?= =?UTF-8?q?=EB=8B=A4=EA=B3=A0=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 11-03 절의 realtime BREAKING 행은 "poll은 던지는 execute도 lease 안에서 다시 시도한다"고 적는다. 그 범위 끝(8a44226)에서는 사실이지만, 같은 동기화 때 함께 받는 위 절의 05330e3(1105/04-02)이 던지는 execute를 재시도 없이 PROTOCOL_MISMATCH로 끝내게 바꿨다. 두 절을 함께 받는 제품은 아래 절의 문장대로 재시도를 기대한다. 그 커밋 본문도 이 행이 맞지 않는다고 적는다. 고른 방법 - 아래 절 행은 그 범위 끝의 사실로 두고, 위 절에서 바뀐 것과 새 결과를 한 문장으로 붙였다. 위 절의 BREAKING 행은 PR B 행을 쓸 때 05330e3 본문으로 적는다. - 버린 대안: 아래 절 문장을 지우기. 그 절은 한 동기화 단위의 순 요약이라 위 절만 받지 않은 프로젝트가 읽을 수 있다. 위험·한계 - 문서만 바꿨다. 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts Refs: 1105/04-02 --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ad295cb..454f276e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -210,7 +210,7 @@ | 표시 | 변경 | 영향 경로 | 커밋 | |---|---|---|---| | [계약] **BREAKING** | `BoundedPollOperationContract`(V2 어휘)를 지웠다. `createBoundedPollCoordinator`의 operation과 `assertBoundedPollOperation`의 둘째 인자는 V3 descriptor(`BoundedPollOperation`)다. 조립된 행을 넘기고, `frontend.retryBudget` 0인 poll 전용 operation을 등록한다. 0이 아니면 생성 때 거절한다 (1103/04-01) | `src/adapters/realtime/` | `a65df74` | -| [계약] **BREAKING** | SSE의 fetch·reader 거절과 bounded poll의 execute 거절은 `OFFLINE` 대신 `PROVIDER_UNAVAILABLE`(retryable)로 끝난다. 브라우저가 online이면 online 이벤트를 기다리지 않고 backoff로 다시 시도하고 상한에서 끝난다. poll은 던지는 execute도 lease 안에서 다시 시도한다. `OFFLINE`은 환경 신호에서만 나온다 (1103/04-04, 0929/04-01) | `src/adapters/realtime/` | `af00067`, `4d27b20` | +| [계약] **BREAKING** | SSE의 fetch·reader 거절과 bounded poll의 execute 거절은 `OFFLINE` 대신 `PROVIDER_UNAVAILABLE`(retryable)로 끝난다. 브라우저가 online이면 online 이벤트를 기다리지 않고 backoff로 다시 시도하고 상한에서 끝난다. poll은 이 범위 끝에서 던지는 execute를 lease 안에서 다시 시도했다. 위 절에서 다시 바뀌어, 던지는 execute는 재시도 없이 `PROTOCOL_MISMATCH`로 끝난다(1105/04-02). `OFFLINE`은 환경 신호에서만 나온다 (1103/04-04, 0929/04-01) | `src/adapters/realtime/` | `af00067`, `4d27b20` | | [계약] | stream coordinator와 live-poll handoff coordinator의 마감 실패가 `IDLE_TIMEOUT` 대신 `APPLY_FAILED`·`PROVIDER_UNAVAILABLE`로 나온다. stream coordinator의 `RealtimeObservation.reason`도 같다. `IDLE_TIMEOUT`은 전송 idle에만 쓴다 (1101/04-02) | `src/adapters/realtime/stream-coordinator.ts`, `src/adapters/realtime/` | `1196b86`, `17fa8d1` | | [계약] | realtime 배럴이 결과 생성 함수 `realtimeSuccess`·`realtimeFailure`를 내보낸다. 동결이 필요한 경계에 직접 만든 결과를 넘기던 코드는 이 함수로 바꾼다 (1101/04-01) | `src/adapters/realtime/index.ts` | `3fe28de` | | [계약] | Service Worker 빌드가 `public/`을 다시 복사하지 않는다(`publicDir: false`). 전에는 SW를 켠 빌드의 `dist/config.json`이 local 문서로 덮어써졌다 (0929/06-01) | `vite.service-worker.config.ts`, `scripts/build-frontend.ts` | `c7b9cb8` | From f4be42685c5eb5804e39f99f1af168f0c59aa85c Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 23:16:06 +0900 Subject: [PATCH 07/12] =?UTF-8?q?docs(changelog):=20=EB=91=90=20=EC=A0=9C?= =?UTF-8?q?=ED=92=88=EC=9D=B4=20=EA=B3=A0=EC=B9=9C=20=ED=85=9C=ED=94=8C?= =?UTF-8?q?=EB=A6=BF=20=ED=8C=8C=EC=9D=BC=EC=9D=84=20=EC=98=AE=EA=B8=B8=20?= =?UTF-8?q?=EA=B3=B3=EA=B3=BC=20=EC=9E=90=EB=A6=AC=20=EC=97=86=EB=8A=94=20?= =?UTF-8?q?=EA=B2=83=EC=9C=BC=EB=A1=9C=20=EB=82=98=EB=88=88=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 "옮기기 전" 2단계는 "제품이 고친 템플릿 파일을 뽑는다"며 memento 7개, tech-log 11개를 적는다. 실제로 af3d8e6 뒤 고친 템플릿 src 파일(기능· context 폴더 밖)은 memento 26개(수정 23, 추가 3), tech-log 40개(수정 38, 추가 2)다(리뷰 영역 14 E-4). 빠진 파일 중 일부는 이 묶음에 옮길 제품 소유 자리가 있고, 일부는 없다. 목록에 없으면 동기화 때 충돌이나 조용한 유지로 드러난다. 고른 방법 - 두 다운스트림(memento d3810a0, tech-log 7a4e201a)에서 `git diff --name-status af3d8e6 HEAD -- src`와 파일별 diff를 읽어(쓰기 없음) 2단계에 세 항목을 더했다. - 자리가 있는 것: tech-log release-artifacts.ts의 TECH_LOG_*_SOURCE → PRODUCT_RUNTIME_CONFIG_FIELDS, memento offset-upload.ts와 HTTP 배럴 export → product-composition 쪽 제품 파일(그 파일은 contracts만 import한다), tech-log 라우팅 파일과 참조 기능 계약의 layoutGroup → 3단계 기능 모듈 길. - 자리가 아직 없는 것: memento의 if-match 요청 헤더, SW 오프라인 shell과 사전 캐시 확장자, 저장소·OPFS 이름, 앱 이름 문구, 브랜드 토큰· primitive. tech-log의 AppFailure.detail, BoundMutation.identity, null을 빈 상태로 보기, 폼, 디자인 시스템, 문구, 전역 스타일 import. - 템플릿 결함 후보: tech-log application-query.ts의 "마운트한 같은 턴의 저장" 수정. 템플릿은 재현하지 않았다. - 알려진 제한에 "자리 없는 것은 이 묶음이 옮길 곳을 주지 않는다"를 더했다. - 버린 대안: 파일마다 옮길 곳을 정하기. 템플릿에 자리를 만들지는 각각 설계 결정이다(결정 대기). 위험·한계 - 일부다. 자리 없는 항목마다 템플릿이 자리를 줄지, 제품 fork로 둘지는 정하지 않았다. 안내를 제품 코드에 적용해 게이트를 돌리지 않았다. - 분류는 diff를 읽은 판단이다. 파일 안의 모든 변경을 확인하지는 않았다 (예: tech-log 디자인 시스템 primitive 3개는 줄 수만 봤다). 검증 - 문서만. desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts Refs: 1103/14-02, 0929/14-03, 0929/14-06 --- CHANGELOG.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 454f276e..522da435 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -52,6 +52,10 @@ 2. 제품이 고친 템플릿 파일을 뽑는다. 이 묶음은 그 일을 받을 제품 소유 파일을 새로 둔다(옮기는 법 2단계). 템플릿 파일을 고친 채로 두면 동기화마다 충돌한다. - memento: `src/bootstrap/runtime-adapters.ts`, `src/features/feature-adapter-contribution.ts`(capability `offsetUpload`·`runtime`), `src/contracts/rest-profiles.ts`(`MEMENTO_BFF_READ`·`MEMENTO_BFF_WRITE`), `src/contracts/external-contract-runtime.ts`(출처 종류 `PRODUCT_LOCAL_CONTRACT`), `src/features/installed-feature-contracts.ts`(`APP_HOME` 다리), `src/features/installed-runtime-capabilities.ts`(Service Worker `ACTIVE`), `src/presentation/routes/app-router.tsx`(`ownsShell` 다리). - tech-log: `src/contracts/env.ts`(`TECH_LOG_STUDIO_SOURCE`·`TECH_LOG_PUBLIC_SOURCE` 행), `src/bootstrap/create-runtime-composition.ts`(부트 전 BFF 세션 owner), `src/contracts/rest-profiles.ts`(`TECH_LOG_STUDIO_SESSION`·`TECH_LOG_STUDIO_BOOTSTRAP`), `src/bootstrap/runtime-adapters.ts`, `src/bootstrap/runtime-config-schema.ts`, `src/features/installed-*` 다섯 개(TechLog 직접 조립. 그중 `installed-feature-runtimes.tsx`는 템플릿이 지웠다), `src/presentation/routes/app-router.tsx`(PUBLIC/STUDIO 라우터). + - 위 목록은 일부다. `af3d8e6` 뒤 두 제품이 고친 템플릿 `src` 파일(기능·context 폴더 밖, `git diff --name-status af3d8e6 HEAD -- src`)은 memento 26개(수정 23, 추가 3), tech-log 40개(수정 38, 추가 2, 그 밖에 삭제. 추가 중 `reference-feature/NOT_INSTALLED`는 옮기는 법 1단계)다. 2026-11-05에 두 repo의 diff를 읽어 나눴다(1103/14-02). + - 제품 소유 자리가 있는 것. tech-log `src/contracts/release-artifacts.ts`의 `TECH_LOG_STUDIO_SOURCE`·`TECH_LOG_PUBLIC_SOURCE` 필드는 `PRODUCT_RUNTIME_CONFIG_FIELDS`로 간다(옮기는 법 2단계). memento `src/adapters/http/offset-upload.ts`(추가)와 `src/adapters/http/index.ts`의 그 export는 capability `offsetUpload`를 만드는 제품 코드라 `src/bootstrap/product-composition.ts` 쪽 제품 파일로 옮기고 HTTP 배럴은 템플릿 것으로 되돌린다. tech-log의 라우팅 파일(`src/contracts/routes.ts`·`route-runtime-contract.ts`의 `layoutGroup`과 플랫폼 라우트 삭제, 참조 기능 계약 `reference-feature-contract.ts`의 `layoutGroup`, `src/presentation/routes/` 6개와 추가 `route-url-builder.ts`)은 직접 조립의 일부라 3단계 끝의 기능 모듈 길로 바꾸면 템플릿 것으로 돌아간다. + - 제품 소유 자리가 아직 없는 것. 템플릿이 자리를 정하지 않았다. 동기화 때 충돌하거나 제품이 고친 채로 남는다(알려진 제한). memento: 요청 헤더 `if-match`(`http-contract-bridge.ts`, `http-execution-v3.ts`. V3 descriptor에는 요청 헤더 칸이 없다), Service Worker 오프라인 navigation shell(`service-worker-lifecycle.ts`)과 사전 캐시 확장자 `.html`·`.jpg`(`service-worker-static-manifest.ts`), 저장소 이름 `APP_NAMESPACE`(`storage-keys.ts`)와 OPFS 이름(`opfs-policy.ts`, `indexeddb-opfs-journal.ts`), 앱 이름 문구(`catalog.ts`의 `common.appName`·`route.APP_HOME.title`), 브랜드 토큰·글꼴·primitive(`design-system/tokens/` CSS 3개와 `token-contract.ts`, `primitives/core.tsx`, `design-system/index.ts`, `styles/theme.css`, 추가 폴더 `design-system/memento/`). tech-log: `AppFailure.detail`(`errors.ts`, `feature-http-binding.ts`), `BoundMutation.identity`(`server-state.ts`)와 그것을 쓰는 `application-query.ts`, `deriveAsyncState`와 조회 훅이 `null`을 데이터 없음이 아닌 빈 상태로 보는 것(`async-state.ts`, `application-query.ts`), 폼(`use-app-form.ts`의 select, `use-dirty-navigation-guard.tsx`), 디자인 시스템(`primitives/core.tsx`·`forms.tsx`·`navigation.tsx`, `patterns/common-patterns.tsx`, `design-system/index.ts`, `page-templates.tsx`, `app-shell.tsx`), 문구(`catalog.ts`, `message-contract.ts`), 전역 글꼴·스타일 import(`src/bootstrap/main.tsx`). + - 템플릿 결함 후보. tech-log `application-query.ts`는 마운트한 같은 이벤트 턴에 저장하면 결과 불명 채널이 아직 없어 거절되던 것을 고쳤다(채널을 제출 때도 얻는다). 템플릿은 이것을 재현하지 않았다. 3. 기능마다 HTTP descriptor를 센다. method, `retrySemantics`, `responseEnvelope`, 입력·응답·실패 검증기의 schemaId, 그 검증기가 zod인지. 옮기는 법 4·5단계의 작업량이 이 숫자로 정해진다. - memento-web: descriptor 29개. 입력·응답 schemaId 42개와 실패 본문 `MementoProblem` 1개. 검증기는 zod가 아니라 손으로 쓴 `isRecord` 검사다. `responseEnvelope`는 없다. GET은 `SAFE`, 쓰기는 `KEYED`·`IDEMPOTENT`·`NEVER`다. - TechLog: 검증기는 `zodValidator`다. 출력은 Envelope 뼈대만 검사하고 본문은 통과시킨다. `responseEnvelope`는 없다. GET은 `SAFE`, 쓰기는 `KEYED`나 `NEVER`(둘 다 `retryBudget` 0)다. @@ -274,6 +278,7 @@ 이 절의 범위 끝(브랜치 `fix/maturity-review-2026-11-03`의 `8a44226`)에서 사실인 것만 적었다. 위 절이 바꾼 것은 위 절에 적는다. - 다운스트림 이행: 위 안내를 두 제품 코드에 적용해 게이트를 돌려 보지 않았다. memento-web의 숫자(descriptor 29개, schemaId 42개 + `MementoProblem`)는 memento `d3810a0`을 정적으로 센 값이다. +- 두 제품이 고친 템플릿 파일 중 제품 소유 자리가 없는 것("옮기기 전" 2단계의 셋째 항목: memento의 `if-match`·오프라인 shell·저장소 이름·브랜드 토큰, tech-log의 `AppFailure.detail`·`BoundMutation.identity`·`null` 빈 상태·디자인 시스템 등)은 이 묶음이 옮길 곳을 주지 않는다. 동기화 때 충돌하거나 제품이 고친 채로 남는다. 어느 것을 템플릿에 들일지는 정하지 않았다. - 직접 조립 제품(tech-log의 TechLog): 템플릿에 그 자리가 없다. 기능 모듈로 바꾸는 길은 fixture(`tests/helpers/fixture-layout-product.tsx`)로만 검사했고 TechLog 화면으로는 해 보지 않았다. 직접 조립을 유지하면 FE-REG-API·FE-REG-SCHEMA와 스키마 메타 대조 테스트가 TechLog descriptor를 보지 않는다. - 제품 안에 적은 계약(memento `PRODUCT_LOCAL_CONTRACT`)에 줄 출처 종류가 없다. `EXTERNAL_PACKAGE` 신원을 어떻게 정할지(패키지 없이 digest를 붙이는 법)는 템플릿이 정하지 않았다. - 참조 기능은 `responseEnvelope`를 선언하지 않아 DTO와 problem details만 읽는다. 짝 백엔드에 붙는 완성 예시는 `create:feature --with-create`가 만드는 기능이다. From b834b8d7eccf2aa6c3f882347892f281adc53dbe Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 23:17:30 +0900 Subject: [PATCH 08/12] =?UTF-8?q?docs(changelog):=20=EB=A6=AC=EB=B7=B0=20R?= =?UTF-8?q?EADME=20=EC=A0=88=EA=B3=BC=20=EC=98=81=EC=97=AD=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=20ID=EC=9D=98=20=EA=BC=B4=EC=9D=84=20=EB=A8=B8?= =?UTF-8?q?=EB=A6=AC=EC=97=90=20=EC=A0=81=EA=B3=A0=20=ED=85=8C=EC=8A=A4?= =?UTF-8?q?=ED=8A=B8=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 CHANGELOG 머리는 리뷰 ID를 `MMDD/NN-MM`과 `F-N`으로만 정한다. 본문에는 `1101 README 14.3`, `1103 07 영역 P-07-06`, `백엔드 리뷰 1101/02-01`, "리뷰 조치 X2"가 섞여 있다. 마지막은 라운드가 없어 어느 리뷰인지 찾을 수 없다. changelog-review-ids 테스트는 `NN-MM`·`F-N`만 본다(1101/14-02 잔여). 고른 방법 - 머리에 세 꼴을 적었다: `MMDD README N.N`(다시 돌린 항목은 뒤에 `X2`), `MMDD NN 영역 P-NN-NN`, `백엔드 리뷰 MMDD/NN-MM`. 지금 본문의 참조는 이 꼴이다. - "리뷰 조치 X2"를 `1103 README 14.6 X2`로 고쳤다(2fef27d 등의 Refs가 그 절을 가리킨다). - 테스트 "cites README sections and other review references with their round": 괄호 안 토큰 중 README 절·X 번호·P-ID·백엔드 리뷰를 담은 것이 이 꼴과 다르면 실패한다. - 버린 대안: README 절도 `MMDD/README-14.3` 같은 한 꼴로 바꾸기. 본문 9곳과 커밋 Refs의 쓰임을 함께 바꿔야 해서 얻는 것보다 바꿀 것이 많다. 위험·한계 - 괄호 밖에 적은 참조는 보지 않는다(기존 테스트와 같다). 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts RED: 부모 CHANGELOG에서 새 테스트가 ["리뷰 조치 X2"]로 실패한다. Refs: 1101/14-02 --- CHANGELOG.md | 4 +-- tests/unit/changelog-review-ids.test.ts | 33 ++++++++++++++++++++++--- 2 files changed, 31 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 522da435..1e6fdc6d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ - **[보안]** 복사한 프로젝트도 가져가야 하는 보안·개인정보 수정이다. - **[계약]** 백엔드, 배포 설정, CI, 또는 기능 코드가 함께 바뀌어야 하는 변경이다(헤더, 변수, 게이트, 공개 포트). - 표시가 없으면 템플릿 안에서 끝나는 수정이다. -- 괄호 안 ID는 리뷰 발견 ID다. `MMDD/NN-MM`으로 적는다. `MMDD`는 리뷰 폴더 `docs/reviews/YYYY-MM-DD-maturity-review/`의 월일이고, 근거와 재현 조건은 그 폴더의 영역 문서에 있다. 복사한 프로젝트가 README대로 `docs/reviews/`를 지웠다면 이 폴더와 `PRODUCT.md`는 원본 템플릿 repo에서 찾는다. 라운드마다 `NN-MM`을 새로 매기므로 같은 `14-02`라도 라운드가 다르면 다른 결함이다. `F-N`은 그 라운드 `FOLLOW-UP.md`의 ID다. `tests/unit/changelog-review-ids.test.ts`가 라운드 없는 ID를 막는다. +- 괄호 안 ID는 리뷰 발견 ID다. `MMDD/NN-MM`으로 적는다. `MMDD`는 리뷰 폴더 `docs/reviews/YYYY-MM-DD-maturity-review/`의 월일이고, 근거와 재현 조건은 그 폴더의 영역 문서에 있다. 복사한 프로젝트가 README대로 `docs/reviews/`를 지웠다면 이 폴더와 `PRODUCT.md`는 원본 템플릿 repo에서 찾는다. 라운드마다 `NN-MM`을 새로 매기므로 같은 `14-02`라도 라운드가 다르면 다른 결함이다. `F-N`은 그 라운드 `FOLLOW-UP.md`의 ID다. 리뷰 README의 절은 `MMDD README N.N`으로 적고 다시 돌린 항목은 그 뒤에 `X2`처럼 번호를 붙인다. 영역 문서가 따로 매긴 ID는 `MMDD NN 영역 P-NN-NN`, 짝 백엔드 리뷰의 ID는 `백엔드 리뷰 MMDD/NN-MM`으로 적는다. `tests/unit/changelog-review-ids.test.ts`가 라운드 없는 ID와 이 꼴을 벗어난 참조를 막는다. - 0.2.0의 커밋 해시는 브랜치 `fix/maturity-review-2026-09-25`에서 만들었고, `main`에서도 같은 해시로 찾을 수 있다(2026-11-03에 52개 모두 확인). 그 뒤 절은 절 머리에 범위(기준 커밋과 브랜치)를 적고, 그 절의 해시는 모두 그 범위에 있다. 0.2.0의 커밋 제목은 라운드 없이 ID만 적었다(`git log --grep '03-03'`). ## 미출시 — `409d72e` → 브랜치 `fix/maturity-review-2026-11-05` @@ -266,7 +266,7 @@ - 레지스트리 도구: `check:registries`가 조립 실패의 `reason`을 적고, 읽지 못한 레지스트리를 지운 것으로 세지 않는다 (1103/14-06). FE-REG-SCHEMA 행의 `direction`·`unknownFieldPolicy`·`boundary`를 검증기·쓰임과 대조한다 (1103/07-03, 1103/16-04). 금지 조각이 든 런타임 설정 키를 `test:unit`이 이름과 함께 막는다 (1103/07-04). `check:feature-index` 예외 이유를 실제 사용처로 고쳤다 (1101/12-05) - 아키텍처 검사: zod 하위 경로(`zod/v4` 등) import도 `src/contracts/zod.ts`를 거쳐야 한다 (`64f19ac`, 1103 07 영역 P-07-06). 금지 fixture를 그 계층의 운영 ESLint 설정으로 검사하고 fixture 전용 블록을 지웠다 (1103/12-04). adapter kernel 설명을 실제 `platform` 폴더 내용에 맞췄다 (`3f72ae7`). 두 오류 어휘(`AppFailure`·`AppError`)와 `commandRecovery`를 누가 읽는지 타입 옆에 적었다 (1101/07-05, 1101/07-07) - 게이트·드릴: coverage 증거 검사(FE-GATE-005)가 istanbul summary의 `branchesTrue`를 받는다 (1103/12-09). compact smoke e2e가 빌드에 준 `VITE_BUILD_ID`를 기대해 CI 값에서 FE-GATE-008이 항상 실패하지 않는다 (1103/11-06). vitest와 dev server를 띄우는 Playwright 설정(capabilities, dev)이 CI의 `VITE_BUILD_ID`·`VITE_COMMIT_SHA`를 물려받지 않는다. 전에는 CI env에서 앱을 local-build fixture로 조립하는 테스트와 capability e2e가 `CONFIG_BUILD_MISMATCH`로 떨어져 FE-GATE-005·006·007·008·020이 항상 실패했다 (1103/11-07). 테스트가 만드는 로컬 빌드(fixture 빌드, 시각 골든 build, 브라우저 테스트의 dev server)는 `CI=true`에서도 release 빌드로 검사되지 않는다(`localBuildEnvironment`, `LOCAL_BUILD_IDENTITY`). 전에는 workflow env에서 FE-GATE-005·008·020이 실패했다 (1103/11-08). 브라우저 테스트의 strict fixture가 WebKit의 "preload했지만 몇 초 안에 쓰지 않았다" 경고 문구만 무시하고, 대신 preload된 build script가 실제로 실행됐는지를 세 엔진에서 검사한다(`preloadunused:`, `tests/support/browser/preload-use.ts`). WebKit은 load 3초 뒤 한 번 추정해서, 곧 쓰일 청크를 preload한 화면에서 FE-GATE-008이 가끔 떨어졌고 정말 안 쓴 preload는 놓쳤다. build script를 직접 fulfill하는 test는 `fulfillBuildScript`를 쓴다 (1103/11-09). browser capability의 파일 선택·다운로드 test가 붙이는 버튼을 앱 위 고정 층에 둔다. 앱이 그리는 도중 내용이 자라 클릭 사이에 버튼이 움직였고, 클릭이 버튼에 닿지 않아 firefox에서 FE-GATE-008이 가끔 30초 시간 초과로 떨어졌다 (1103/11-10). capability 제거 드릴 3개가 문서 테스트 `ENOENT`로 항상 실패하던 것을 고쳤다. 문서를 읽는 테스트 목록은 `scripts/lib/removal-fixture.ts` 한 곳이다 (1103/02-06). `test:sample-removal`이 문서를 복사해 `lint`·`verify:documentation`·`check:i18n`·`check:design-system`을 돈다 (1103/14-04). 제품 기능 제거 드릴이 CI 기준선 사유 공백으로 멈추지 않는다 (1103/16-02). `test:system` provider 묶음 30초 예산 (1103/11-03), scope wrapper EOF 테스트 (1103/10-01)와 IndexedDB 차단 업그레이드 테스트 (1103/11-05)의 부하 원인을 없앴다. `artifacts/**/*.log`를 추적하지 않는다 (1103/12-08) -- 기능 추가 뒤 검증(리뷰 조치 X2): [계약] `create:feature`와 기능 제거 드릴이 dev server의 manifest(`public/release-manifest.json`)의 contract set을 설치된 기능으로 다시 쓴다(`node scripts/write-dev-release-manifest.ts`). 기능과 함께 커밋한다. 낡으면 `tests/unit/dev-release-manifest.test.ts`가 실패한다. 전에는 `create:feature` 직후 dev server와 dev server를 쓰는 capability e2e가 `CONTRACT_SET_PACKAGE_MISSING`으로 부팅하지 못했다 (1103/16-09). dev server가 `artifacts/`·`dist/`·`.tmp/`를 감시하지 않는다. 기능 제거 드릴(`test:sample-removal -- --feature=`)이 지운 뒤 초기 JS 기록을 다시 쓴다 (1103/15-02). 초기 JS 파일 상한이 32다(템플릿 26 + 여유) (1103/15-05). Fileserver 업로드 client가 browser-file-storage 포트를 import하지 않아 그 런타임을 지워도 남는다(`FileserverByteSource`) (1103/01-01). 제품 확장 타입 검사 탐침이 예약 이름(`typecheck-probe-*`)을 쓰고 제품의 capability 선언을 덮어쓰지 않는다 (1103/09-02). 시각 골든 build와 storybook workshop spec이 CI 식별값·a11y 애드온 자동 검사와 겹치지 않는다 (1103/11-07) +- 기능 추가 뒤 검증(1103 README 14.6 X2): [계약] `create:feature`와 기능 제거 드릴이 dev server의 manifest(`public/release-manifest.json`)의 contract set을 설치된 기능으로 다시 쓴다(`node scripts/write-dev-release-manifest.ts`). 기능과 함께 커밋한다. 낡으면 `tests/unit/dev-release-manifest.test.ts`가 실패한다. 전에는 `create:feature` 직후 dev server와 dev server를 쓰는 capability e2e가 `CONTRACT_SET_PACKAGE_MISSING`으로 부팅하지 못했다 (1103/16-09). dev server가 `artifacts/`·`dist/`·`.tmp/`를 감시하지 않는다. 기능 제거 드릴(`test:sample-removal -- --feature=`)이 지운 뒤 초기 JS 기록을 다시 쓴다 (1103/15-02). 초기 JS 파일 상한이 32다(템플릿 26 + 여유) (1103/15-05). Fileserver 업로드 client가 browser-file-storage 포트를 import하지 않아 그 런타임을 지워도 남는다(`FileserverByteSource`) (1103/01-01). 제품 확장 타입 검사 탐침이 예약 이름(`typecheck-probe-*`)을 쓰고 제품의 capability 선언을 덮어쓰지 않는다 (1103/09-02). 시각 골든 build와 storybook workshop spec이 CI 식별값·a11y 애드온 자동 검사와 겹치지 않는다 (1103/11-07) - 테스트: Testing Library 대기 기한을 `tests/setup.ts` 한 곳에서 5초로 정했다 (0929/10-01). `npx vitest`나 npm을 거친 IDE 실행기로 돌려도 실패하지 않는다 (1101/15-05). cgroup 시스템 테스트가 실행 단계가 남긴 PID·argv 기록을 읽는다 (1101/11-01). exact-five CLI 테스트가 실제 출력 문구를 기대한다 (0929/11-01). guardian이 실패하면 stdin을 기다리지 않고 끝난다 (`3c175a5`). 계약 조립기의 쓰기 API 규칙 5개 (1101/07-06), 이벤트 계약 검증 (1101/10-01), Envelope 판정 경계와 처리 중 409 무재전송 (1103/10-02), `MAX_RETRY_ATTEMPTS` 전달과 signal listener 정리 (1103/10-04)를 테스트로 고정했다. 규모 측정 기준선을 다시 쟀고 측정용 기능 복사본은 외부 패키지를 고정한다 (`9333595`, 1101/07-04). 설치 기능이 0개여도 타입 검사와 커버리지가 통과한다 (`e4ace51`, 1101/15-01) - 테스트: 플랫폼 component 테스트가 스타터 화면 대신 테스트 전용 페이지(`tests/helpers/fixture-feature.tsx`)를 쓴다. 스타터 화면을 바꾸는 제품은 `tests/component/starter-*.test.tsx`를 함께 지운다. HTTP 시나리오 증거(FE-GATE-007)와 기능 API 타입 음성 fixture(FE-GATE-003)는 샘플을 지워도 남는다 (0929/10-02). 기능 테스트는 `createHttpScenarioHandler(<설치 계약>, { scenario, payload })`로 공유 MSW 시나리오를 쓰고, `tests/mocks/**`는 플랫폼 소유다 (1101/16-02, 1101/16-01). SW e2e가 제품이 켠 worker와 빌드가 만든 사전 캐시 목록을 쓴다 (0929/11-03, 0929/06-04). 접근성 e2e가 설치된 descriptor의 경로와 `responseEnvelope`로 빈 목록을 답하고 목록 화면에 경고 상자가 없음을 단언한다. 기능을 더해도 spec을 고치지 않는다 (1103/11-01, 1103/16-03) - 참조 기능: 샘플 페이지가 `referenceRouteUrl(routeId, input)`으로 링크를 만들고 route 입력 cast를 없앴다. `REFERENCE_FEATURE_ROUTE_CODECS`는 `presentation/reference-route-codecs.ts`에 있다. 목록 링크 href는 `?limit=20`이 붙은 정식 URL이다 (1101/16-04). `create:feature --context reference-context`로 만들어도 참조 라우팅 테스트가 깨지지 않는다 (`e8c4197`) diff --git a/tests/unit/changelog-review-ids.test.ts b/tests/unit/changelog-review-ids.test.ts index 11083325..d500a522 100644 --- a/tests/unit/changelog-review-ids.test.ts +++ b/tests/unit/changelog-review-ids.test.ts @@ -10,16 +10,41 @@ import { describe, expect, it } from "vitest"; * round's FOLLOW-UP list). The review folders are deletable history, so this * reads only the CHANGELOG. */ +async function parenthesizedTokens(): Promise { + const changelog = await readFile("CHANGELOG.md", "utf8"); + return [...changelog.matchAll(/\(([^()]*)\)/gu)].flatMap((match) => + (match[1] ?? "").split(",").map((token) => token.trim()), + ); +} + describe("review IDs in CHANGELOG.md (1101/14-02)", () => { it("names the review round of every finding ID", async () => { - const changelog = await readFile("CHANGELOG.md", "utf8"); - const tokens = [...changelog.matchAll(/\(([^()]*)\)/gu)].flatMap((match) => - (match[1] ?? "").split(",").map((token) => token.trim()), - ); + const tokens = await parenthesizedTokens(); const ids = tokens.filter((token) => /^(?:\d{4}\/)?(?:\d{2}-\d{2}(?:~\d{2}-\d{2})?|F-\d+)$/u.test(token), ); expect(ids.length).toBeGreaterThan(0); expect(ids.filter((id) => !/^\d{4}\//u.test(id))).toEqual([]); }); + + // The other references the CHANGELOG cites, in the shapes its header + // defines: a section of a round's README (`1101 README 14.3`, a re-run item + // after it: `1103 README 14.6 X2`), an ID an area document numbers itself + // (`1103 07 영역 P-07-06`) and the paired backend's review + // (`백엔드 리뷰 1101/02-01`). A reference without its round, such as + // "리뷰 조치 X2", named no review a reader could find. + it("cites README sections and other review references with their round", async () => { + const references = (await parenthesizedTokens()).filter((token) => + /README \d|\bX\d|P-\d{2}-\d{2}|백엔드 리뷰/u.test(token), + ); + expect(references.length).toBeGreaterThan(0); + expect( + references.filter( + (token) => + !/^(?:\d{4} README \d+(?:\.\d+)*(?: X\d+)?|\d{4} \d{2} 영역 P-\d{2}-\d{2}|백엔드 리뷰 \d{4}\/\d{2}-\d{2})$/u.test( + token, + ), + ), + ).toEqual([]); + }); }); From 1c4e57c0caac7f6c16af64a8df770d4f4befb7a5 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 23:18:31 +0900 Subject: [PATCH 09/12] =?UTF-8?q?docs(operations):=20=EB=82=A8=EC=9D=80=20?= =?UTF-8?q?FEATURE=5FOVERRIDES=20=ED=82=A4=EA=B0=80=20=EA=B2=BD=EA=B3=A0?= =?UTF-8?q?=EB=A5=BC=20=EB=82=A8=EA=B8=B4=EB=8B=A4=EA=B3=A0=20=EC=A0=81?= =?UTF-8?q?=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 ci-quality-gates.md의 기준선 표는 지운 기능의 FEATURE_OVERRIDES 키가 "조용히 무시된다"고 적는다. 코드는 그 키를 무시하지만 조용하지 않다. check:release-admission(FE-GATE-027)이 `release admission warning: FEATURE_OVERRIDES. … the override does nothing`을 내고 (scripts/check-release-admission.ts), 부팅이 진단 feature.override.unknown (warn)을 남긴다(src/bootstrap/runtime-adapters.ts). 운영자는 경고를 오류로 오해하거나, 문서대로 아무 신호도 없다고 생각한다(0929/14-05). 고른 방법 - 표의 "검사 위치" 칸을 코드대로 고쳤다: 실패하는 검사는 없고, 두 곳이 경고를 남긴다. 위험·한계 - 문서만 바꿨다. 경고 문구가 바뀌면 이 칸도 고친다(문서 검사는 문구를 대조하지 않는다). 검증 - desktop batch에서 확인: corepack pnpm verify:documentation Refs: 0929/14-05 --- docs/operations/ci-quality-gates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/operations/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index fb74d0f1..7a34e9ab 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -66,7 +66,7 @@ package script 그래프로 닿거나, 게이트가 이미 돌리는 Vitest 경 | CI 계약 크기·게이트 모양 | `config/ci/contract-baseline.json` | `update:ci-contract-baseline` (`CI_CONTRACT_BASELINE_OWNER`·`_REASON` 필수) | `scripts/contracts/ci-gates.ts` `assertCiContractBaseline` | | registry 스냅샷과 승인 | `config/contracts/registry-baseline.json`, `registry-baseline.approval.json` | `update:registry-baseline` (`REGISTRY_BASELINE_OWNER`·`_REASON` 필수). 기준선을 새로 찍지 않고 breaking 변경을 유지하려면 `config/contracts/registry-change-evidence.json`에 항목을 추가(`changeId`, 그 변경 뒤 값 `after`(삭제는 생략, 값은 JSON 그대로이고 키·원시값 배열 순서는 상관없다), `versionBump`·`migration`·`compatibilityWindow`·`rollback`·`owner`). 같은 칸을 다시 바꾸면 `after`가 달라 새 항목이 필요하다. 지금 diff의 breaking 변경과 changeId가 맞지 않는 항목이 있으면 게이트가 그 항목을 나열하며 실패한다. `update:registry-baseline`은 새 기준선이 설명하는 항목을 모두 지운다(지운 항목은 git 이력에 남는다) | `scripts/check-registries.ts`의 baseline 비교 | | 커버리지 모듈 수 하한 | `config/testing/risk-coverage.json`의 `repositoryBaseline` | 직접 수정. 지운 production 모듈 수만큼 줄인다(`scripts/test-sample-removal.ts`가 같은 계산을 한다) | `scripts/lib/risk-coverage.ts` "repository module baseline" | -| 기능 끄기 설정 | `config/runtime/.json`의 `FEATURE_OVERRIDES` | 직접 수정. 지운 기능의 키를 뺀다(`scripts/test-sample-removal.ts`가 같은 일을 한다) | 없음. 남은 키는 조용히 무시된다(리뷰 09-09) | +| 기능 끄기 설정 | `config/runtime/.json`의 `FEATURE_OVERRIDES` | 직접 수정. 지운 기능의 키를 뺀다(`scripts/test-sample-removal.ts`가 같은 일을 한다) | 실패하는 검사는 없다. 남은 키는 아무것도 끄지 않고, `check:release-admission`(FE-GATE-027)이 `release admission warning: FEATURE_OVERRIDES. … the override does nothing`을, 부팅이 진단 `feature.override.unknown`(warn)을 남긴다(리뷰 09-09) | | 의존성 목록 | `config/security/dependency-baseline.json`, `dependency-baseline.approval.json` | `update:dependency-baseline` (`DEPENDENCY_BASELINE_OWNER`·`_REASON` 필수) | `scripts/generate-supply-chain.ts` | Contract loading validates every registered command entry against the From 1ac336a72ab9020ab46e83d0880d3b80c7170a2b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 23:19:56 +0900 Subject: [PATCH 10/12] =?UTF-8?q?docs:=20=EB=A3=A8=ED=8A=B8=20SPEC.md?= =?UTF-8?q?=C2=B7tasks/=EB=A5=BC=20=EB=91=90=EB=8A=94=20=EC=9D=B4=EC=9C=A0?= =?UTF-8?q?=EB=A5=BC=20=EB=81=9D=EB=82=9C=20=EB=9D=BC=EC=9A=B4=EB=93=9C?= =?UTF-8?q?=EC=97=90=20=EB=A7=9E=EC=B6=98=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 docs/README.md 3절은 루트의 SPEC.md·tasks/를 "2026-09-25 라운드가 쓰는 중이라 docs/ 밖에 그대로 둔다"고 적는다. 그 라운드는 0.2.0(2026-09-27)으로 끝났다. 이유가 낡아서 복사한 프로젝트가 지워도 되는지, 템플릿이 왜 루트에 작업 기록을 두는지 알 수 없다(0929/14-01 잔여). 고른 방법 - 이유를 지금 사실로 고쳤다: 라운드는 끝났고, 그때 리뷰 문서가 이 경로 (`SPEC.md:18` 등)로 가리키므로 옮기지 않는다. 지워도 되는 기록이라는 것은 README "Files you can delete after copying"이 그대로 적는다. - 버린 대안: 두 기록을 docs/superpowers/ 아래로 옮기기. docs/reviews/의 지난 리뷰가 루트 경로로 가리키는데, 리뷰 이력은 고치지 않는다. 위험·한계 - 위치는 그대로라 복사 대상 루트에 작업 기록이 남는다. 지우는 것은 복사한 프로젝트의 몫이다(README 표). 0929/14-01은 일부로 남는다. 검증 - desktop batch에서 확인: corepack pnpm verify:documentation Refs: 0929/14-01 --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 7d9393f8..70eeed54 100644 --- a/docs/README.md +++ b/docs/README.md @@ -88,4 +88,4 @@ checkout이 없거나 그 커밋이 없으면 실패 대신 확인하지 못한 |---|---| | [`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/` 밖에 그대로 둔다 | +| [`../SPEC.md`](../SPEC.md), [`../tasks/`](../tasks/) | 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 그 라운드는 0.2.0(`CHANGELOG.md`)으로 끝났다. 그때 리뷰 문서(`reviews/2026-09-25-maturity-review/`)가 이 경로(`SPEC.md:18` 등)로 가리키므로 옮기지 않는다 | From 57e3586292d2f7148f18f3b484d350960f56926b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 23:20:21 +0900 Subject: [PATCH 11/12] =?UTF-8?q?docs(readme):=20=EB=AF=B8=EC=B6=9C?= =?UTF-8?q?=EC=8B=9C=20=EB=B2=94=EC=9C=84=EB=A5=BC=20=ED=95=9C=20=EB=B2=88?= =?UTF-8?q?=EC=97=90=20=EB=B0=9B=EB=8A=94=20=EB=AA=85=EB=A0=B9=EA=B3=BC=20?= =?UTF-8?q?=EA=B8=B0=EC=A4=80=EC=A0=90=20=EA=B8=B0=EB=A1=9D=EC=9D=84=20?= =?UTF-8?q?=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 README "Updating a copied project"는 미출시 절을 한 범위로 받으라고 하면서 명령은 커밋 하나의 cherry-pick과 git diff뿐이다. 두 다운스트림이 실제로 쓰는 범위 merge(memento, 이력 공유)와 3-way 이식(tech-log, 이력 없음)은 없다. 기준점 기록도 .template-origin 하나만 적고, tech-log의 template.lock.json은 CHANGELOG에만 있다(0929/14-02 잔여). 고른 방법 - 범위를 받는 두 길을 명령과 함께 적었다: 이력을 공유하면 범위 브랜치를 `git merge --no-ff`, 아니면 범위 기준점을 base로 둔 3-way 병합 `git merge-recursive -- HEAD template/`(tech-log가 2026-09-29 동기화에 쓴 명령, 그 repo의 template-sync-2026-09-29.md). - 기준점은 .template-origin이나 제품의 lock 파일(tech-log의 template.lock.json sourceRevision)에 두고, 범위를 받은 뒤 범위 끝으로 옮긴다고 적었다. - 버린 대안: 동기화 스크립트를 템플릿에 두기. 두 제품의 방식이 달라 설계가 필요하다. 위험·한계 - 명령을 이 커밋에서 실행해 보지 않았다. 두 다운스트림이 지난 동기화에 쓴 명령을 옮겨 적었다(memento: git merge --no-ff, tech-log: git merge-recursive). 충돌 처리 안내는 없다. 검증 - desktop batch에서 확인: corepack pnpm verify:documentation Refs: 0929/14-02 --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index 81d6bd69..9358df6f 100644 --- a/README.md +++ b/README.md @@ -393,6 +393,20 @@ git log --oneline ..template/main # what changed since you copied git cherry-pick -x # one fix; -x records its origin ``` +Take an unreleased range as a whole. A repository that shares the template's +history merges the range's branch. One that does not (it started from a copy +of the files) merges three-way against the range base, which leaves the files +both sides changed as conflicts; resolve them and commit: + +```bash +git merge --no-ff template/ # shared history +git merge-recursive -- HEAD template/ # no shared history +``` + +Keep the base you synced from where your project records it: `.template-origin` +(below), or your own lock file (tech-log keeps it as `sourceRevision` in +`template.lock.json`). Move it to the range end once the range is in. + When the files have moved or diverged too far for a clean pick, read the change as a diff and apply it by hand: From 1c884e1bd9437b815253f7447b898030144a48b6 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 23:33:40 +0900 Subject: [PATCH 12/12] =?UTF-8?q?docs(changelog):=201105=20PR=20B=20?= =?UTF-8?q?=EC=A1=B0=EC=B9=98=EC=99=80=20=EB=82=A8=EC=9D=80=20=ED=95=AD?= =?UTF-8?q?=EB=AA=A9=EC=9D=84=20=EC=83=88=20=EB=AF=B8=EC=B6=9C=EC=8B=9C=20?= =?UTF-8?q?=EC=A0=88=EC=97=90=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 새 미출시 절(409d72e → fix/maturity-review-2026-11-05)에는 PR A 조치 셋만 있다. PR B(fix/maturity-review-2026-11-05-b)는 그 위에 비병합 커밋 70개를 쌓았고, 그중 `!` 커밋 다섯(1105/03-01, 1105/04-02, 1103/16-01, 1103/16-05, 1103/11-01)은 복사한 프로젝트가 코드를 바꿔야 한다. 커밋 본문이 "CHANGELOG [계약] 행이 필요하다"고 적은 변경과 결정 대기·백엔드로 넘김·일부 항목도 이 절에 없다. 11-03 절의 알려진 제한 세 줄(기능 라우트 첫 진입, 참조 기능의 responseEnvelope, SW composeProduct 칸)은 PR B가 바꿨다. 고른 방법 - 절 머리의 범위 끝을 fix/maturity-review-2026-11-05-b로 바꾸고, 앞의 세 조치가 PR A(PR #5)에 있다고 한 줄로 적었다. PR A 행은 그대로 두었다. - 11-03 절과 같은 모양으로 "먼저 할 일(BREAKING)"을 두었다. 옮기는 법 10단계 (responseEnvelope, MutationOperationId, refusedBeforeWrite 플랫폼 code, poll execute, a11y.json v2, scope participant label, 레시피 복사본, SW 칸, 제품 게이트의 workflow 재생성, 기능 안 adapters/ 밖 import)와 옮긴 뒤 확인. - 보안·계약 표에 [계약] 행을 더했다: CI·게이트(13-02, 12-01 기준선, 12-04 TEST_RUN_ID·RUN_OUTPUT_ROOT·TEST_*_PORT, 12-02, 14-01·14-03, 0929/12-03 아키텍처 규칙, a11y.json, lab 예산, 기록 허용 오차, test:all, 제거 드릴 잔여), HTTP·계약, server-state, realtime, bootstrap·세션, 저장소·캐시(scope_participant 진단 키, chunkSweep deprecated, UNREADABLE·REHYDRATE, AUTH_REDIRECT_TRANSACTION 행), SW·호스팅. `!` 커밋 다섯은 **BREAKING**으로 표시했다. 나머지는 "그 밖의 수정"에 영역별로 적었다. - 이 절의 알려진 제한에 커밋 본문의 결정 대기·백엔드로 넘김·일부를 한 줄씩 적었다. 기능 라우트 첫 진입 줄은 지금 상태(lab이 EXAMPLES_UI를 500 ms로 잰다, 요청 두 묶음은 남음)로 적었다. - 11-03 절의 세 줄은 그 범위 끝의 사실로 두고 위 절에서 바뀐 것을 붙였다. - PR B의 비병합 커밋 70개가 모두 행이나 줄에 해시로 있다. 기준점 409d72e를 빼면 이 절의 해시는 모두 409d72e..이 브랜치 끝에 있다. 위험·한계 - 이 브랜치(fix/r1105-docs-v2) 커밋의 해시도 인용했다. 통합 때 이 브랜치를 다시 쌓으면(fixup 접기 등) 그 해시 11개를 새 값으로 바꿔야 한다. - 안내를 두 다운스트림 코드에 적용해 보지 않았다. 1105/12-01 기준선 행의 "제품이 기준선을 다시 기록해 두었다면 다시 기록한다"는 67082cc 본문에서 추론한 것이다. 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts Refs: 1105 PR B (fix/maturity-review-2026-11-05-b) --- CHANGELOG.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 85 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1e6fdc6d..c9aa9e46 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,9 +11,32 @@ - 괄호 안 ID는 리뷰 발견 ID다. `MMDD/NN-MM`으로 적는다. `MMDD`는 리뷰 폴더 `docs/reviews/YYYY-MM-DD-maturity-review/`의 월일이고, 근거와 재현 조건은 그 폴더의 영역 문서에 있다. 복사한 프로젝트가 README대로 `docs/reviews/`를 지웠다면 이 폴더와 `PRODUCT.md`는 원본 템플릿 repo에서 찾는다. 라운드마다 `NN-MM`을 새로 매기므로 같은 `14-02`라도 라운드가 다르면 다른 결함이다. `F-N`은 그 라운드 `FOLLOW-UP.md`의 ID다. 리뷰 README의 절은 `MMDD README N.N`으로 적고 다시 돌린 항목은 그 뒤에 `X2`처럼 번호를 붙인다. 영역 문서가 따로 매긴 ID는 `MMDD NN 영역 P-NN-NN`, 짝 백엔드 리뷰의 ID는 `백엔드 리뷰 MMDD/NN-MM`으로 적는다. `tests/unit/changelog-review-ids.test.ts`가 라운드 없는 ID와 이 꼴을 벗어난 참조를 막는다. - 0.2.0의 커밋 해시는 브랜치 `fix/maturity-review-2026-09-25`에서 만들었고, `main`에서도 같은 해시로 찾을 수 있다(2026-11-03에 52개 모두 확인). 그 뒤 절은 절 머리에 범위(기준 커밋과 브랜치)를 적고, 그 절의 해시는 모두 그 범위에 있다. 0.2.0의 커밋 제목은 라운드 없이 ID만 적었다(`git log --grep '03-03'`). -## 미출시 — `409d72e` → 브랜치 `fix/maturity-review-2026-11-05` +## 미출시 — `409d72e` → 브랜치 `fix/maturity-review-2026-11-05-b` -2026-11-05 성숙도 리뷰(`docs/reviews/2026-11-05-maturity-review/`) 조치다. 범위는 `main` `409d72e`(아래 절의 묶음을 합친 커밋)부터 이 브랜치의 끝까지다. 아래 절을 아직 받지 않은 프로젝트는 아래 절부터 받는다. +2026-11-05 성숙도 리뷰(`docs/reviews/2026-11-05-maturity-review/`) 조치다. 범위는 `main` `409d72e`(아래 절의 묶음을 합친 커밋)부터 브랜치 `fix/maturity-review-2026-11-05-b`(PR B)의 끝까지다. 앞의 세 조치(`9655958`, `629c713`, `397664e`)는 PR A(PR #5, 브랜치 `fix/maturity-review-2026-11-05`)에 있고, PR B는 그 위에 쌓였다. 기준점 `409d72e`를 빼면 이 절의 해시는 모두 이 범위에 있다. 아래 절을 아직 받지 않은 프로젝트는 아래 절부터 받는다. + +### 먼저 할 일 (BREAKING) + +아래 절의 "먼저 할 일"을 마친 뒤 순서대로 한다. 단계 끝의 괄호는 아래 표의 근거 행이다. 두 다운스트림 코드에 적용해 게이트를 돌려 보지는 않았다(알려진 제한). + +#### 옮기는 법 + +1. **HTTP descriptor마다 `responseEnvelope`를 적는다.** `InstalledHttpContract`의 필수 칸이 됐다. 감싸지 않는 백엔드(memento-web, TechLog)는 `"NONE" as const`, 짝 백엔드 Envelope는 `"ENVELOPE_V1" as const`다. 빠뜨리면 그 descriptor의 `satisfies InstalledHttpContract<...>`에서 `check:types`가 실패한다. 런타임 동작은 같다 (1103/16-01) +2. **뮤테이션 정책의 operation ID를 손으로 적지 않는다.** `BoundMutation.operationId`는 brand 타입 `MutationOperationId`다. `operationId: ""`와 `requiresIdempotencyKey`를 `...commandMutationIdentity()`로 바꾼다. 문자열로 적으면 `check:types`가 실패한다 (1103/16-05) +3. **`refusedBeforeWrite`에서 플랫폼 code를 뺀다.** 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔 code(`PLATFORM_CODES_POSSIBLY_AFTER_WRITE`: `BAD_PARAMETER`, `MAPPING_FAILED`, `DB_*` 8개, `LOCK_ACQUISITION_TIMEOUT`, Fileserver code)를 적으면 계약 조립이 거절해 부팅이 멈춘다. 그 code의 실패는 결과 불명으로 남는다 (1105/03-01) +4. **bounded poll의 `execute`는 실패를 던지지 않고 결과로 돌려준다.** 던지면(lease 자신의 abort 제외) 재시도 없이 `PROTOCOL_MISMATCH`(retryable 아님)로 lease가 끝난다. 네트워크 실패를 throw로 내던 `execute`는 retryable `PROVIDER_UNAVAILABLE` 결과로 바꾼다. 실행기에는 클로저의 descriptor 대신 `input.operation`(생성 때 검사한 descriptor)을 넘긴다 (1105/04-02, 1103/04-01) +5. **`artifacts/tests/a11y.json`을 읽는 도구는 schemaVersion 2를 읽는다.** `scope`는 실패 화면으로만 본 라우트를 빼고, 그 라우트는 새 `notChecked` 배열에 `{ routeId, reason }`으로 들어간다. 설치된 라우트 전체는 둘을 합친 것이다 (1103/11-01) +6. **제품 scope participant의 `label`은 소문자 kebab-case 48자 이하로 쓴다.** 아니면 조립이 `TypeError`로 멈춘다 (1105/02-01) +7. **레시피를 복사한 제품은 복사본을 고친다.** 쿠키 세션 모드는 `createSessionCookieRejectionHandler(context)`를 `composeProduct`의 `onCredentialRejected`에 잇는다. 잇지 않으면 서버 401이 템플릿 세션에 닿지 않는다(매뉴얼 04 4.3) (1105/09-02). OIDC PKCE owner는 sign-in transaction 키를 registry 행 `AUTH_REDIRECT_TRANSACTION`의 `physicalKey`에서 가져온다. 키 글자는 같다 (1105/05-01) +8. **Service Worker를 켠 제품은 `blockers`·`observe`를 `composeProduct`의 선택 칸 `serviceWorker`로 옮긴다.** 템플릿 파일 `src/bootstrap/create-runtime-composition.ts`는 템플릿 것으로 되돌린다 (1103/09-05) +9. **제품 merge 게이트(`config/ci/product-gates.json`의 `mergeGates`)가 있는 제품은 `corepack pnpm generate:ci-workflow`를 다시 돈다.** `release_gate`가 `product_merge_gate`도 기다리는 줄이 생긴다. 다시 돌리지 않으면 `check:ci`가 실패한다 (1105/13-02) +10. **기능 안 `adapters/` 밖에서 `src/adapters`를 import하는 파일은 `adapters/`로 옮긴다.** 아니면 `check:architecture`가 `feature-and-app-roots-do-not-reach-adapters`로 실패한다 (0929/12-03) + +#### 옮긴 뒤 확인 + +1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: `check:types`(1·2단계), 앱을 조립하는 `test:unit`·`test:component`(3·6단계), `check:ci`(9단계), `check:architecture`(10단계), `check:registries`(응답 스키마 행을 `REJECT_UNKNOWN`으로 좁힌 변경은 이제 breaking). +2. 한 checkout에서 브라우저 테스트 실행 두 개를 함께 돌리려면 실행마다 `TEST_RUN_ID`를 다르게 준다. 게이트(`ci:gate`)와 증거 검사는 기본 경로만 읽으므로 한 checkout에서 하나씩 돈다. +3. 배포가 있는 제품: 자산을 redirect로 주는 호스트는 FE-GATE-019가 FAIL이다. ### 보안·계약 변경 @@ -21,10 +44,67 @@ |---|---|---|---| | [계약] | FE-GATE-013(`test:system`) 러너는 비특권 user namespace와 network namespace를 허용해야 한다(provider 샌드박스의 `bwrap --unshare-net`). 사전 점검이 bwrap을 실제로 띄워 보고, 허용하지 않는 호스트에서는 provider 테스트를 돌리기 전에 이유·호스트 설정·고치는 방법을 적고 멈춘다. 요구는 러너 요구 목록, gate 정의의 `hostRequirements`, workflow 주석에 있다 (1105/12-01) | `scripts/check-system-test-prerequisites.ts`, `scripts/lib/provider-sandbox-namespaces.ts`, `config/ci/gates.json`, `docs/operations/ci-quality-gates.md` | `9655958` | | [계약] | release job `immutable_build`가 FE-GATE-015·027의 gate 로그·evidence와 의존성 advisory 기록을 결과와 상관없이 `immutable-gate-evidence--`로 올린다. 후보 archive와 그 upload는 그대로다 (1105/13-01) | `scripts/generate-ci-workflow.ts`, `scripts/contracts/ci-gates.ts`, `.gitea/workflows/quality-gates.yml` | `629c713` | +| [계약] | gate 모양 기준선(`canonicalGateShapeSha256`)이 FE-GATE-013의 `hostRequirements`도 본다. 요구를 지우거나 바꾸면 `check:ci`가 기준선 차이로 실패하고, 바꿀 때는 `update:ci-contract-baseline`(owner·reason 필수)으로 다시 기록한다. 제품이 `config/ci/contract-baseline.json`을 자기 값으로 다시 기록해 두었다면 받은 뒤 다시 기록한다 (1105/12-01) | `scripts/contracts/ci-gates.ts`, `config/ci/contract-baseline.json` | `67082cc` | +| [계약] | 제품 overlay에 merge 게이트가 있으면 `release_gate`가 `product_merge_gate`를 기다린다. 제품 검사가 실패하면 같은 run의 release·immutable_build·promotion·deployment가 멈춘다. 게이트가 없으면 workflow는 그대로다. `check:ci`가 그 연결이 없는 workflow를 거절한다. 위 "먼저 할 일" 9단계 (1105/13-02) | `scripts/generate-ci-workflow.ts`, `scripts/contracts/ci-gates.ts` | `92d5019` | +| [계약] | 한 checkout에서 실행 두 개가 서로를 지우지 않는다. `TEST_RUN_ID`를 주면 Playwright 결과·report·JUnit과 서빙할 빌드가 `.tmp/runs//` 아래로 간다. 빌드 단계는 `RUN_OUTPUT_ROOT`(설정이 web server에 넘긴다) 아래에 쓴다. 다섯 Playwright 설정은 빈 포트를 골라 `TEST_E2E_PORT`·`TEST_VISUAL_PORT`·`TEST_CAPABILITIES_PORT`·`TEST_STORYBOOK_PORT`·`TEST_DEV_PORT`에 적고(미리 주면 그 포트), vite는 `--strictPort`로 뜨고, dev 설정은 떠 있는 서버를 쓰지 않는다. 변수가 없으면 출력 경로는 전과 같다. 기능 인덱스 생성기는 내용이 같으면 쓰지 않고 다르면 rename으로 바꾼다. 상세는 `docs/testing/frontend-platform-testing-strategy.md` 13.6절 (1105/12-04) | `scripts/lib/run-isolation.ts`, `playwright*.config.ts`, `vite.config.ts`, `scripts/build-frontend.ts`, `scripts/generate-product-feature-index.ts` | `ddbda4d`, `f4d5761`, `0e72c0c`, `510e2bb` | +| [계약] | `verify:documentation`이 짝 백엔드 경로·링크를 `config/contracts/backend-contract-pin.json`이 고정한 커밋의 트리(옆 checkout의 git 기록)에서 찾는다. 작업 트리와 HEAD는 보지 않는다. checkout이나 그 커밋이 없으면 확인하지 못한 것으로 남긴다. repo 밖으로 나가는 링크가 pin한 저장소가 아니면(이름 오타 포함) 실패한다 (1105/12-02) | `scripts/verify-documentation-readiness.ts` | `fc95672` | +| [계약] | `verify:documentation`은 지울 수 있는 템플릿 기능(참조 기능, 예제 화면 기능. `scripts/lib/removable-template-features.ts`)의 경로와 script를 그 기능이 설치돼 있으면 검사하고, `src/features//feature-module.ts`가 없으면 요구하지 않는다. 그래서 아래 절 6단계대로 예제 기능을 지운 제품도 문서 검사와 FE-GATE-005가 통과한다. 참조 기능 경로는 다시 백틱으로 적어 검사를 받는다. 1절 문서가 그 경로를 백틱 밖에 적으면 `test:unit`이 실패한다 (1105/14-01, 1105/14-03) | `scripts/verify-documentation-readiness.ts`, `scripts/lib/removable-template-features.ts`, `scripts/test-sample-removal.ts`, `docs/` | `50b631e`, `332bfee`, `1dda18d` | +| [계약] | 아키텍처 규칙 `feature-and-app-roots-do-not-reach-adapters`가 기능의 `adapters/` 폴더와 `feature-adapter-contribution.ts`를 뺀 `src/features` 전체를 본다. 기능 안 `support/` 같은 계층 밖 폴더가 `src/adapters`에 닿으면 실패한다. 위 "먼저 할 일" 10단계 (0929/12-03) | `.dependency-cruiser.json`, `scripts/check-architecture.ts` | `a37ebba` | +| [계약] **BREAKING** | `artifacts/tests/a11y.json`이 schemaVersion 2다. 실패 화면으로만 axe를 돌린 라우트(일반 답이 없는 상세 라우트)는 `scope`에서 빠져 `notChecked`(`{ routeId, reason }`)에 들어간다. 라우트 test가 자기 상태를 `artifacts/tests/a11y-data-state/.json`에 남긴다. 위 "먼저 할 일" 5단계 (1103/11-01) | `scripts/write-a11y-report.ts`, `scripts/lib/a11y-data-state.ts`, `scripts/contracts/release-artifacts.ts`, `tests/e2e/accessibility.spec.ts` | `757d1c7` | +| [계약] | lab(FE-GATE-026)이 기능 라우트 첫 진입을 잰다. 대상은 설치된 기능의 첫 공개 내비게이션 라우트(`labFeatureRoute`, 템플릿에서는 `EXAMPLES_UI`)이고 예산은 `budgets.json`의 `lab.featureRouteInteractionMs` 500 ms다. 그런 라우트가 없으면 `measured: false`로 남기고 판정하지 않는다. run마다 대상 라우트를 직접 열어 CLS도 잰다(`metrics.targetDeepLinkCls`, 예산 `lab.cls`). lab은 스크롤바를 보이게 띄운다. `lab.json` schema에 새 칸이 필수다 (1105/15-04, 1105/15-01, 1105/15-05) | `config/performance/budgets.json`, `config/schemas/lab-performance.schema.json`, `scripts/test-performance.ts`, `scripts/lib/lab-performance.ts` | `81701ad`, `138c195`, `e02f252` | +| [계약] | 초기 JS 기록 대조(`tests/unit/feature-shape-growth.test.ts`)의 합계 허용 오차가 1%(약 2 KB)가 아니라 256 B다. 초기 JS를 수백 바이트 움직이는 변경은 기록을 다시 쓴다 (1105/15-02) | `scripts/scale/measure-feature-shape-growth.ts` | `46359a1` | +| [계약] | `test:all`이 `test:coverage`(FE-GATE-005)가 도는 Vitest 경로를 모두 돈다(`tests/features` 전체, `tests/scripts`, browser-soak 계약 테스트). `tests/unit/test-all-paths.test.ts`가 대조한다 (0929/10-05) | `package.json` | `7ead8d3` | +| [계약] | 제품 기능 제거 드릴(`test:sample-removal -- --feature=`)의 잔여 판정: `src`는 기능 ID·폴더 이름을 담은 파일, `tests`는 이름에 기능 ID가 있거나 그 기능 폴더에서 import하는 파일만이다. 템플릿 테스트가 예시 ID(`invoice-feature` 등)를 데이터로 쓰는 것은 잔여가 아니다. 참조 기능은 전처럼 넓게 찾는다 (1105/16-04) | `scripts/lib/feature-residue.ts`, `scripts/test-sample-removal.ts` | `b45d6a0` | +| [계약] **BREAKING** | `InstalledHttpContract`의 `contract.responseEnvelope`가 필수다. 참조 기능과 테스트 fixture는 `"NONE"`을 적는다. 조립은 빠진 값을 전처럼 `NONE`으로 읽는다. 위 "먼저 할 일" 1단계 (1103/16-01) | `src/contracts/external-contract-runtime.ts`, `scripts/create-feature.ts`, `src/features/reference-feature/contracts/` | `56272e8` | +| [계약] **BREAKING** | `refusedBeforeWrite`에 `PLATFORM_CODES_POSSIBLY_AFTER_WRITE`(계약 문서 6.1절의 "쓰기 뒤 가능" 플랫폼 code)를 적으면 `composeContractContributions`가 거절한다. 실행기의 fail-close도 그 목록을 무시한다. `tests/unit/backend-contract-pin.test.ts`가 6.1절 표와 목록을 양방향으로 대조한다. 위 "먼저 할 일" 3단계 (1105/03-01) | `src/contracts/external-contract-runtime.ts`, `src/adapters/http/backend-envelope.ts` | `5c0b37e` | +| [계약] | Envelope operation의 503 `RATE_LIMIT_UNAVAILABLE`·`RATE_LIMIT_INCOMPATIBLE`은 쓰기 전 거절(`NOT_APPLIED`)이다. kind는 `SERVER_FAILURE`(action retry)이고 IDEMPOTENT 쓰기는 `retryBudget` 안에서 다시 보낸다. KEYED·NEVER는 자동 재전송이 없다 (1105/03-02) | `src/adapters/http/backend-envelope.ts`, `config/contracts/backend-idempotency-answers.json` | `c6c37f3` | +| [계약] | 짝 백엔드 `http-contract.md` §2·§4 표를 pin 커밋 그대로 `config/contracts/backend-http-contract-excerpt.json`에 옮겼다. `test:unit`이 답 표와 사본을 행마다 대조한다(옮기지 않은 행은 pin의 `notCopied`). `check:backend-contract-drift`(게이트 밖)는 사본을 pin 커밋의 문서와 비교하고, pin의 `backend.scaffoldSources`(백엔드 생성기 템플릿 파일과 옮긴 프론트 위치)가 pin 뒤 바뀌었는지도 본다. 비교하지 못하면 rc=2다. pin을 올릴 때는 `--write-excerpt` (1105/07-01, 1105/16-02) | `config/contracts/backend-contract-pin.json`, `config/contracts/backend-http-contract-excerpt.json`, `scripts/check-backend-contract-drift.ts`, `scripts/lib/backend-contract-excerpt.ts` | `daf3474`, `f600e6b` | +| [계약] | Fileserver 업로드 client: 202 `REJECTED`는 실패 `VALIDATION_REJECTED`, code `FILE_REJECTED`, `NOT_APPLIED`다(전에는 `SCHEMA_MISMATCH`). 빈 파일은 보내지 않고 `FILE_EMPTY`, `NOT_STARTED`로 끝난다. 504 `TRANSFER_TIMEOUT`은 결과 불명(`MAYBE_APPLIED`, retryable 아님, 자동 재전송 없음)이다. 멱등성 code와 V3 판정 표에 있는 답은 V3 표대로 판정해 503 `IDEMPOTENCY_UNAVAILABLE`도 결과 불명이다. 실패 Envelope의 `meta.traceId`를 `AppFailure.traceId`로 싣는다 (1105/01-01, 1103/01-01, 1105/01-02, 1105/01-03) | `src/adapters/http/fileserver-upload.ts`, `docs/manual/` | `6608fef`, `471b001`, `8b92f45` | +| [계약] | FE-REG-SCHEMA `direction: "RESPONSE"` 행의 `unknownFieldPolicy`를 `REJECT_UNKNOWN`으로 좁히면 `check:registries`가 breaking(`response-reader-narrowed`)으로 본다. 넓히는 쪽과 REQUEST 행은 그대로 behavior-change다 (1105/07-02) | `scripts/lib/registry-compatibility.ts` | `3b62ccd` | +| [계약] **BREAKING** | `BoundMutation.operationId`와 `commandMutationIdentity`가 돌려주는 operationId가 brand 타입 `MutationOperationId`다. 위 "먼저 할 일" 2단계 (1103/16-05) | `src/contracts/server-state.ts` | `48c1ab7` | +| [계약] | 키 없는(`NEVER`) 결과 불명 요청과 같은 입력으로 `submit`하면 보내지 않고 `NOT_STARTED` `DUPLICATE_IN_FLIGHT`(code `UNKNOWN_EFFECT_PENDING`)를 돌려준다. `AsyncSurface`는 `unknownEffectResendable === true`일 때만 재전송 버튼을 그린다. 손으로 만든 결과 불명 상태를 넘기던 화면은 버튼이 사라진다 (0929/03-03) | `src/presentation/adapters/query/application-query.ts`, `src/presentation/components/async-surface.tsx` | `683ccfb` | +| [계약] **BREAKING** | `createBoundedPollCoordinator`의 `execute`가 던지면(abort 제외) 재시도 없이 `PROTOCOL_MISMATCH`(retryable 아님)로 lease가 끝난다. `execute` 입력에 생성 때 검사한 descriptor `input.operation`이 실린다(추가만). 위 "먼저 할 일" 4단계 (1105/04-02, 1103/04-01) | `src/adapters/realtime/` | `05330e3`, `27e3dec` | +| [계약] | scope reset이 실패하면 단계마다 진단 `cache.operation.failed`(`operation: "SCOPE_RESET"`, `reason` `PARTICIPANT_FAILED`·`CACHE_RESET_FAILED`·`GENERATION_ACTIVATION_FAILED`·`PARTICIPANTS_UNREADABLE`, participant면 `scope_participant: