문제: 코드 주석 87곳(74파일, .dependency-cruiser.json 포함)이 "Spec §N"
처럼 문서 이름 없이 절 번호만 적는다(대문자 83, 소문자 "spec §" 4).
가리키는 설계서는 README가 복사 뒤 지워도 된다고 한 docs/reviews/ 안에
있었다. 지울 수 있는 기록 검사는 경로 문자열만 찾아 이 참조를 잡지
못했다. 현재 계약 문서도 지울 수 있는 파일로 링크한다:
docs/reviews/adapters/INVENTORY.md 145행이 옆의 adapter 리뷰로,
docs/operations/adapter-remediation-ledger.md가 adapter 리뷰와
docs/superpowers/plans의 계획으로.
고른 방법:
- 주석의 "Spec §"/"spec §"를 "scale-architecture.md §"로 바꾼다(앞
커밋이 옮긴 docs/architecture/scale-architecture.md). 설명 문장과 절
번호는 그대로다. 절 번호가 없는 "Spec §"는 없었다.
- tests/unit/deletable-history-documents.test.ts에 "spec" + 선택 공백 +
"§"(대소문자 무시)를 거부하는 검사를 더하고, 검사 대상에
.dependency-cruiser.json을 넣는다.
- README "Files you can delete after copying"에서 INVENTORY.md 한 파일
대신 docs/reviews/adapters/ 폴더를 남기게 하고 이유(INVENTORY 행과
ledger가 그 리뷰로 링크한다)를 적는다. docs/README.md §3도 같게 고친다.
INVENTORY의 행 구조는 바꾸지 않는다.
- 남긴 adapter 리뷰와 ledger가 docs/superpowers/plans로 거는 링크 5곳은
링크를 풀고 "작업 이력 계획, 복사본은 지울 수 있다"로 적는다.
버린 대안: INVENTORY 145칸의 링크를 그룹 이름으로 바꾸기. 템플릿에서도
상세 리뷰로 가는 길이 없어지고 수정이 145곳이다. 계획 3개도 지우기
목록에서 빼기. 지울 수 있는 폴더 안에 예외가 흩어지고, 계획이 다시
다른 이력을 가리키면 남길 목록이 계속 커진다.
위험·한계: 검사는 "HTML spec §4"처럼 다른 명세를 "spec §"로 부르는
주석도 거부한다. 그때는 "HTML Standard §4"처럼 이름을 쓴다.
src/contracts/storage-keys.ts:79의 "release-coherence plan Task 6"처럼
이름 없는 계획 참조는 이 검사가 잡지 않는다. 복사한 프로젝트가 이미
docs/reviews/adapters/를 지웠다면 링크는 계속 끊겨 있다. CHANGELOG.md의
이력 언급 4곳(:15 두 경로, :75 PRODUCT.md, :93)은 고치지 않았다.
check:remediation-ledger는 이 변경 전후 같은 4줄로 실패한다(이미 있던
실패, 게이트 밖). tests/unit/telemetry.test.ts의 describe 이름 하나가
바뀐다.
검증:
- RED: 치환 전 새 검사가 87줄을 들어 실패(1 failed | 1 passed).
- GREEN: 같은 테스트 2 passed. 변이 "// Spec §4. budgets live here"를
src/platform/errors/app-error.ts에 넣으면 그 한 줄로 실패, 되돌림.
- 치환 diff: 바뀐 87줄 쌍이 토큰 외에 같음(스크립트 대조, 불일치 0).
- 삭제 실험(작업 트리 복사본에서 README 목록대로 지움): 끊긴 링크
148→0, 끊긴 경로 언급 10→4(남은 4는 CHANGELOG.md), 이름 없는 설계
참조 87→0, scale-architecture.md §N 87곳 중 없는 절 0. 같은 복사본에서
verify-documentation-readiness PASS_SCOPED, 지울 수 있는 기록 테스트
2 passed.
- node scripts/verify-documentation-readiness.ts: PASS_SCOPED
- node scripts/check-adapter-inventory.ts: PASS
- node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts
tests/unit/documentation-readiness.test.ts tests/unit/telemetry.test.ts:
50 passed. tests/architecture: 39 passed.
- npx tsc --noEmit (app·node·test): 모두 통과. 바꾼 TS 74파일 eslint 통과.
.dependency-cruiser.json JSON 파싱 통과.
- 미실행: check:architecture(pnpm 필요).
문제: 라우터는 모든 context gateway를 `AppShell` 하나 아래에 붙이고 플랫폼
`/`를 index로 둔다. 기능이 `APP_HOME`을 선언하면 `composeUniqueRecord`가
throw한다. 그래서 제품 홈이 기능 화면이거나 화면이 `AppShell`이 아닌 자기
셸을 쓰면 제품이 템플릿 라우터와 조립 카탈로그를 고쳐야 한다. memento는
카탈로그 브리지(`APP_HOME` 허용 목록)와 라우터 브리지(`ownsShell`)를 넣고
동기화마다 병합한다. tech-log는 라우터를 PUBLIC/STUDIO 그룹 라우터로 통째로
바꿔 생성기 설치 경로(context gateway)를 쓰지 못한다.
고른 방법: 리뷰 4.3의 (B). 선언 두 개를 연다.
- 홈 대체: 플랫폼이 기능이 대신할 수 있는 라우트 id를 선언한다
(`FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS = ["APP_HOME"]`,
src/contracts/routes.ts). 그 id를 선언한 기능의 정의가 플랫폼 정의를
대신한다. 둘이 선언하면 카탈로그를 읽을 때 두 기능 id를 담아 throw한다
(`withoutTakenOverPlatformRoutes`). 다른 플랫폼 id는 지금처럼 중복 오류다.
라우터는 대체된 라우트를 소유 context와 함께 그 경로에 붙인다.
- context 레이아웃: `BoundedContextRouteModule.loadLayout`(선택). 생성기는
`src/contexts/<context>/context-layout.tsx`가 있으면 그 `CONTEXT_LAYOUT`을
지연 import로 싣는다. 라우터는 그 context를 `AppShell` 형제인 `/` 레이아웃
라우트 아래, 기능의 등록 경로마다 붙인다. 그래서 모르는 URL은 여전히
`AppShell`의 NOT_FOUND로 간다. 선언이 없으면 지금처럼 `AppShell` 아래 루트에
붙는다. 레이아웃 청크 실패는 라우트 청크와 같은 reload-once 복구를 받는다.
- 09-06 불변식을 레이아웃으로 넓힌다. 레이아웃 라우트는 모두 `/`의
형제라서 루트는 레이아웃과 상관없이 그 아래 URL을 가진다. 그래서 기존
루트 검사가 모든 레이아웃에 걸친다. 한 레이아웃 아래 루트 여럿(같은
컴포넌트를 싣는 context들)은 허용한다. 대체된 플랫폼 라우트는 라우터가
경로에 직접 붙이므로 루트 검사에서 뺀다(09-06 재검토 조건).
- tests/unit/product-features.test.ts의 "플랫폼 라우트는 소유자가 없다"
검사가 대체 가능한 id는 건너뛴다. memento가 고쳤던 템플릿 테스트다.
- `ContextRouteModule`에 `featureIds`가 생겨서, `TEMPLATE_APP_MODULE`을
손으로 mock하며 필수 필드 `features`를 빼먹은 두 테스트
(context-route-gateway, context-boundary-diagnostics)에 `features: []`를
넣었다.
버린 대안:
- (A) 현 상태: 제품마다 브리지를 넣고 동기화마다 병합한다.
- (C) `AppShell` 통째 교체: 레이아웃 그룹이 둘인 tech-log를 담지 못한다.
- 같은 레이아웃을 쓰는 context를 로더 함수로 묶어 레이아웃 라우트 하나에
모으기: 만들었다가 지웠다. React 19는 같은 컴포넌트로 풀린 lazy 타입을 같은
타입으로 맞춰 레이아웃 인스턴스를 그대로 둔다. 묶지 않은 변이로 테스트가
그대로 통과해서 쓸모없는 코드였다.
- `CONTEXT_LAYOUT_ID` 리터럴로 다른 context의 레이아웃을 가리키기: 같은
컴포넌트를 내보내는 파일 두 개로 같은 결과가 나와 선언을 하나 덜 둔다.
- 레이아웃 라우트를 `AppShell`보다 앞에 두기(memento 브리지 순서): 경로가
같으면 기능이 플랫폼 라우트를 조용히 가린다. `AppShell`을 앞에 두어
지금처럼 플랫폼이 이긴다.
위험·한계:
- 레이아웃이 skip link와 `<main id="main-content">` 하나를 그리는 것은
계약(타입 주석, starter-experience.md)과 테스트 fixture로만 지킨다. 실행 중
검사는 없다. 레이아웃 로딩·실패 화면에는 `<main>`이 없다(`AppShell`의
errorElement와 같다).
- 레이아웃 렌더 결함(청크 실패가 아닌 것)은 라우트 errorElement로 가고
진단을 남기지 않는다. `AppShell` 렌더 결함과 같다.
- 홈을 대신한 기능을 실행 중에 끄면 `/`는 비활성 기능 화면이 된다. 빌드에서
빼면(`VITE_PRODUCT_FEATURES`) 플랫폼 홈이 돌아온다.
- tech-log의 PUBLIC 셸 안 NOT_FOUND는 표현하지 않는다. 모르는 URL은
`AppShell`의 NOT_FOUND다. STUDIO의 `/studio/*` 라우트는 STUDIO 레이아웃
아래에서 동작한다. tech-log는 기능 하나를 레이아웃 그룹별 기능 둘(context
둘)로 나눠야 한다.
- 플랫폼 라우트와 기능 라우트의 같은 경로는 여전히 검사하지 않는다(7139c7c
한계). 루트 `*` context에서 `APP_HOME`이 아닌 id로 `/`를 선언하면 플랫폼
홈에 가려진다.
- 초기 JS gzip +349 B(204,586 -> 204,935 B). 예산 204,800 B를 135 B
넘는다(이전 여유 214 B). boot 청크 +228(라우터·앱 모듈),
installed-feature-contracts 청크 +121. 같은 worktree에서 HEAD 파일로
`vite build`를 한 번 더 해서 청크별로 비교했다. 예산은 고치지 않았다.
검증:
- RED: tests/component/context-layouts.test.tsx는 파일 적재에서
"Duplicate route registry key: APP_HOME"으로 실패.
tests/architecture/context-route-roots.test.ts 15건 중 3건 실패(APP_HOME
루트 예외 "not under the route root", 대체 함수가 없어 2건).
tests/scripts/generate-product-feature-index.test.ts 새 1건이 HEAD 생성기로
"expected ... to contain 'loadLayout: async () => (await import…'"로 실패.
- GREEN: 세 파일 37건 통과(생성기 15, 루트 16, context-layouts 6).
- 변이: 라우터가 `loadLayout`을 무시하면 context-layouts 6건 중 5건 실패.
topics 레이아웃을 다른 컴포넌트로 바꾸면 "keeps one layout instance" 실패.
- 회귀: tests/{architecture,unit,features,platform,component,contract,
runtime-schema,integration,scripts,scale}(pnpm을 띄우는 4개 제외)
300 files, 3,451건 통과. check-registries, check-adapter-inventory,
verify-documentation-readiness(PASS_SCOPED) 통과.
- tsc app·test·node 통과. 바꾼 파일 eslint 통과. 생성기 --check 통과.
- check:architecture는 pnpm이 필요해 돌리지 않았다.
Refs: docs/reviews/2026-11-01-maturity-review/09-app-core.md 09-03, 4.3
문제: context gateway의 `ContextErrorBoundary`·`FeatureErrorBoundary`는
`onError`를 받지 않아 잡은 실패를 진단에 남기지 않고, 화면 지원 참조는
buildId뿐이다. 라우트 모듈이 청크 누락이 아닌 이유로 실패할 때(평가 중
throw, 15-01 뒤로는 기능 실행부 적재 실패)도 같은 화면만 그리고 기록이
없다. 안쪽 경계(`RenderErrorBoundary`) 밖에서 난 실패, 예를 들어 핸들의
route id가 레지스트리에 없거나 핸들에 라우트 codec이 없을 때는 사용자
신고로도 사건을 찾을 수 없다. 0929/08-05와 같은 결함이다.
고른 방법:
- `ScopedErrorBoundary`가 잡을 때 incident id를 만들어 `onError` 보고에
넣고, 함수형 fallback에 같은 id를 넘긴다. 둘 다 추가 변경이다(기존
ReactNode fallback과 `{scope, ownerId}`를 읽는 쪽은 그대로 동작).
- incident id 생성기를 `src/platform/errors/incident-id.ts`로 옮겨 두
경계 계열이 같은 함수를 쓴다(platform은 presentation을 import할 수 없다).
- gateway가 두 경계에 `reportRenderFailure` 호출과
`<buildId>:<incidentId>` 지원 참조를 넘긴다. context 경계는
`component_boundary`를 "route"로 보고한다. 진단·텔레메트리 계약에
context 값이 없고, 같은 gateway의 청크 복구 보고도 "route"를 쓴다.
- 비청크 적재 실패는 context 경계 안에서 다시 throw해 같은 보고 경로를
탄다. route id는 URL의 등록 라우트, 없으면 context id다.
버린 대안:
- 세 곳을 presentation `RouteBoundary`로 바꾸기(0929/08-05 제안): 경계
두 계열 통합(리팩토링 R4) 성격이고 context/feature 소유 범위 표시
(`data-boundary`, testid)가 바뀐다.
- gateway가 URL마다 incident id를 하나 만들어 두 경계에 나눠 주기:
두 경계가 같은 id를 공유해 사건 구분이 흐려진다.
- `component_boundary`에 "context" 추가: 진단·텔레메트리 계약과
레지스트리 기준선을 바꾸는 일이라 이번 범위 밖이다.
위험·한계:
- `APP_SHELL`의 `errorElement`(0929/08-05가 함께 적은 곳)는 그대로
buildId만 보이고 보고하지 않는다. React Router 오류 요소라 다른 방식
(useRouteError + 마운트 시 보고)이 필요해 남겼다.
- 실패한 context 안에서 URL을 바꾸면 경계가 리셋되고 다시 throw해 방문마다
한 번 보고한다.
- 화면 변화: context·feature 경계 실패 화면과 비청크 적재 실패 화면의
지원 참조가 `build:incident` 형식이 된다. 시각 골든에는 없는 화면이다.
- 초기 JS +58 B gzip(202,748 → 202,806 B, 여유 1,994 B).
검증:
- RED: tests/component/context-boundary-diagnostics.test.tsx 3건(context
경계: 미등록 핸들 id, feature 경계: codec 없는 핸들, 비청크 적재 실패)이
모두 `Unable to find an element with the text: /^지원 참조:
build-a:[0-9a-f]{8}$/`로 실패. 화면은 "지원 참조: build-a"였다.
- GREEN: 3건 통과. failure-boundary.test.tsx에 함수형 fallback이 보고한
incident id를 받는지 1건 추가, `onError` 보고 기대값에 incidentId 추가.
- 회귀: tests/{architecture,platform,component,features,scripts,contract}
95 files / 592 tests, tests/unit(pnpm을 띄우는 5개 제외) 164 files /
1,929 tests 통과. tsc app·test 통과. 바꾼 파일 eslint 통과.
check-architecture(shim), check-adapter-inventory, check-diagnostics,
check-registries 통과.
Follow-up to 215cc54. The chunk store passed to the shared reload-once
guard had a clear() that no path calls (chunk recovery has no coherent
boot to clear on; its marker only expires), which dropped
decide-chunk-recovery.ts to 75% function coverage against its 95% risk
threshold. RecoveryMarkerStore.clear is now optional and the chunk store
omits it; boot recovery still provides and uses it.
Verified: test:coverage risk gate PASS (363/363 modules, 72
thresholds; it failed on this module before); all gates PASS.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The buffer evicted lower-severity events one by one and only then found
the incoming event still did not fit, so both were lost (maxBytes 300,
info 50 + error 240, incoming warning 100: info evicted, warning
dropped). It now plans the evictions first (severity no higher than the
incoming one, lowest first, oldest first within a severity) and evicts
only if the plan frees enough room. The header comment now matches the
code: an event of the same severity is evicted, not only a lower one.
Verified: tests/platform/telemetry/telemetry-buffer.test.ts — the
review scenario RED before (info evicted), green after; same-severity
oldest-first eviction pinned. All gates PASS.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Chunk recovery kept its own guard: marker keyed by the release pair, no
TTL, trusted write().ok. Round 1 fixed the boot guard (key-independent
marker within a TTL, read-back check) but the chunk copy still reloaded
on every failure when replicas alternated A->B, B->A.
platform/release gains createReloadOnceGuard (the round-1 boot rule,
now with a refusal reason); createReleaseMismatchRecovery wraps it with
unchanged boot semantics (marker within TTL blocks regardless of key,
markCoherentBoot clears), and decideChunkRecovery uses it over its own
CHUNK_RELOAD_GUARD key, keeping its reason vocabulary. Application ->
platform is allowed by .dependency-cruiser.json; platform may not import
application, so the guard lives in platform.
Behavior change (chunk only): a second reload within the TTL is refused
even for a different release pair, and a marker that does not read back
is guard-write-failed. tests/component/context-route-gateway.test.tsx
used a preferences stub that dropped writes; it now persists them.
Verified: tests/unit/chunk-recovery.test.ts characterization (read/write
failure, same pair, invariants) green before the change; alternating
pair test RED before, green after. Boot tests unchanged and green;
FE-RB-002 drill PASS; test:integration PASS; all gates PASS.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
createExecutionContext forwarded an owner signal's abort and removed
that listener only when the interaction itself aborted. An interaction
that finished normally under a long-lived owner signal left its listener
and AbortController on the owner. ExecutionContext gains complete():
idempotent, detaches from the owner without aborting the interaction.
No caller passes an owner signal today, so this closes a latent leak.
Verified: new test in tests/platform/execution/execution-context.test.ts
(RED before: complete is not a function); all gates pass except the
known tests/unit/removal-fixture.test.ts (artifacts/ absent).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The application port (best-effort-telemetry) and the feature port
(feature-telemetry pipeline) each posted to TELEMETRY_ENDPOINT on their
own: 20+20 sends per minute, cookies on the application side, no
pagehide flush or dispose abort on the feature side, and no deadline on
any fetch, so a hung collector held activeFlush forever (6.3-10).
New src/adapters/telemetry/telemetry-collector.ts is the one transport:
shared send-rate window (createTelemetrySendRate, now in the platform
pipeline and injectable via `sendRate`), credentials "omit", cache
"no-store", a per-request deadline through the kernel
createAbortableOperation, and one pagehide fan-out. runtime-adapters
builds one collector and passes it to both ports. Body projections are
unchanged and pinned by characterization tests first.
Verified: new tests in tests/unit/telemetry.test.ts (5 RED before
wiring: credentials/cache, hung collector timeout, shared rate,
feature pagehide flush, feature dispose abort); all gates pass except
the known tests/unit/removal-fixture.test.ts (artifacts/ absent);
check:adapter-inventory 137/137; FE-RB-004 drill PASS.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The value check was anchored with ^, so "request failed: Authorization:
Bearer abc" passed through, as did ?access_token=... in a URL and email
addresses. The key deny-list also missed pwd/pass/auth/otp/pin.
Changes in src/platform/telemetry/redact-telemetry.ts:
- Bearer/Basic credentials and JWTs are masked wherever they occur; only
the match is replaced with [redacted], the rest of the message stays.
A JWT cut short still matches.
- URL query/fragment parameters (?, &, #) are masked when the name is a
secret key (isSecretTelemetryKey) or one of the URL-only names code,
key, sig. Non-secret parameters (limit, cursor, state) are kept.
- Email addresses are masked, including one cut in half by truncation.
- Keys: pwd, pass, auth, otp, pin match as whole key tokens (camelCase,
snake, kebab, PINCode split), so spinner/author/compass/isPinned are
kept; passcode and passphrase are added as fragments.
- Strings are truncated before the patterns run, so the scan is bounded
by maxStringLength. No regex lookbehind (Vite's default target includes
Safari 16.0).
Public exports and signatures are unchanged.
Pinned first (passed before and after): "keeps legitimate telemetry values
and innocent keys untouched" (enum codes, ULID/UUID/hex ids, route ids,
numbers, booleans, BASIC_PLAN, react@19.1.0, a URL without secrets,
code=... in prose, keys spinner/author/code/key).
RED before fix:
- "redacts the short secret key %s as a whole key token" (11 cases, key
kept)
- "redacts credentials in the middle of a string" (values unchanged)
- "masks secret URL query and fragment parameters" (tokens kept)
- "masks email addresses" (email kept)
- "does not leak a secret cut in half by truncation" (partial secrets kept)
Gates: check:architecture, check:types:app, check:types:test, lint,
test:component, check:release-coherence, test:platform pass. test:unit
passes except tests/unit/removal-fixture.test.ts, which needs generated
release evidence under artifacts/ that a fresh worktree does not have
(unrelated to this change).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
With the default queueMicrotask scheduler the first event of a burst was
sent at once with occurrences=1, and every duplicate inside the 60s dedup
window only bumped counters.deduplicated, so 1000 identical errors reached
the collector as occurrences=1. An event dropped from the buffer also left
its fingerprint in the dedup table, suppressing that event for 60s.
Per D-6 the pipeline now holds duplicate counts per fingerprint. Held
counts are folded into a buffered item of the same fingerprint or ride as
summary items in the next batch; they get a batch of their own only on an
explicit flush() or when the dedup window closes (one window timer), so a
duplicate never triggers a send by itself. The held table is bounded by
maxFingerprints. A rejected or evicted event (new buffer onEvict hook) and
a sampled-out event forget their fingerprint (new
TelemetryDeduplicator.forget), so the next occurrence is admitted again
and a sampled-out event is never reported through a summary. Existing
signatures are unchanged; onEvict and forget are additive.
Test changes:
- tests/features/reference-feature/reference-telemetry.test.ts expected
exactly one send for a 500-failure storm, which encoded the lost count;
it now expects 2 sends whose occurrences sum to 500.
- telemetry-pipeline.test.ts:93 (auto flush off, 25 in one item) is kept
as is and still passes.
RED before fix:
- "delivers every duplicate as occurrences with the default microtask
scheduler" (sum was 1, expected 1000)
- "reports held duplicates when the dedup window closes without another
flush" (no window timer armed)
- "does not let a rejected or evicted event suppress its fingerprint"
(re-emitted event was deduplicated, not buffered)
- "never reports a sampled-out event through a duplicate summary"
(sampledOut 1, expected 3)
Gates: check:architecture, check:types:app, check:types:test, lint,
test:component, check:release-coherence, test:platform pass; also
tests/scale/telemetry, tests/scale/session, tests/features/reference-feature
pass. test:unit passes except tests/unit/removal-fixture.test.ts, which
needs generated release evidence under artifacts/ that a fresh worktree
does not have (unrelated to this change).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The reload-once marker only blocked a repeat of the same mismatch key. The
key is buildId:code:releaseId, so a load balancer alternating R10/R11
replicas produced a new key on every boot and each one reloaded again
(A->B->A->... looped). decide() now returns show-failure whenever a marker
younger than the TTL exists, whatever its key. markCoherentBoot() still
clears the marker and an expired marker still allows recovery.
The platform test "keeps a single bounded marker and scopes it to the
mismatch key" encoded the bug (R10->R11 then R11->R12 both reload-once);
it is rewritten to check only the bounded marker, and the key-independent
rule gets its own tests.
RED before fix:
- "allows one automatic reload per session within the TTL whatever the key"
(A->B returned reload-once)
- "cannot loop when a load balancer alternates the mismatch key"
(20 of 20 alternating boots reloaded)
- mixed-replica "cannot reload-loop when replicas alternate between two
different mismatches" (runBootSession threw "reload loop")
Gates: check:architecture, check:types:app, check:types:test, lint,
test:component, check:release-coherence, test:platform pass. test:unit
passes except tests/unit/removal-fixture.test.ts, which needs generated
release evidence under artifacts/ that a fresh worktree does not have
(unrelated to this change).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>