문제: 코드 주석 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 필요).
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>
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>