@wooojin/forgen 0.5.9 → 0.6.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +76 -0
- package/README.ja.md +12 -0
- package/README.ko.md +12 -0
- package/README.md +12 -0
- package/README.zh.md +12 -0
- package/dist/checks/_shared/model-profile.d.ts +1 -1
- package/dist/checks/_shared/model-profile.js +9 -5
- package/dist/cli.js +32 -3
- package/dist/core/auto-compound-runner.js +20 -43
- package/dist/core/block-cli.d.ts +1 -0
- package/dist/core/block-cli.js +41 -0
- package/dist/core/explain-cli.js +29 -1
- package/dist/core/inspect-cli.js +9 -8
- package/dist/core/rate-limit-forecast.d.ts +113 -0
- package/dist/core/rate-limit-forecast.js +236 -0
- package/dist/core/state-gc.js +3 -0
- package/dist/core/stats-cli.d.ts +15 -0
- package/dist/core/stats-cli.js +50 -16
- package/dist/core/status-cli.d.ts +18 -1
- package/dist/core/status-cli.js +51 -2
- package/dist/core/statusline-cli.d.ts +66 -13
- package/dist/core/statusline-cli.js +182 -203
- package/dist/core/v1-bootstrap.js +7 -1
- package/dist/engine/block-judge-cli.d.ts +2 -0
- package/dist/engine/block-judge-cli.js +11 -0
- package/dist/engine/block-judge.d.ts +68 -0
- package/dist/engine/block-judge.js +248 -0
- package/dist/engine/correction-cluster-runner.d.ts +67 -0
- package/dist/engine/correction-cluster-runner.js +242 -5
- package/dist/engine/correction-clustering.d.ts +15 -0
- package/dist/engine/correction-clustering.js +24 -0
- package/dist/engine/lifecycle/lifecycle-cli.js +7 -4
- package/dist/engine/lifecycle/signals.d.ts +59 -2
- package/dist/engine/lifecycle/signals.js +193 -4
- package/dist/engine/lifecycle/trigger-t3-bypass.d.ts +5 -3
- package/dist/engine/lifecycle/trigger-t3-bypass.js +6 -4
- package/dist/engine/lifecycle/types.d.ts +29 -1
- package/dist/engine/mined-rule-merge-cli.d.ts +11 -0
- package/dist/engine/mined-rule-merge-cli.js +67 -0
- package/dist/engine/rule-relevance.d.ts +72 -0
- package/dist/engine/rule-relevance.js +183 -0
- package/dist/engine/rule-toggle-cli.d.ts +5 -0
- package/dist/engine/rule-toggle-cli.js +30 -0
- package/dist/fgx.js +1 -1
- package/dist/forge/evidence-processor.js +2 -0
- package/dist/hooks/post-tool-use.js +9 -14
- package/dist/hooks/pre-tool-use.js +71 -8
- package/dist/hooks/shared/command-parser.d.ts +11 -0
- package/dist/hooks/shared/command-parser.js +120 -0
- package/dist/hooks/solution-injector.js +13 -0
- package/dist/hooks/stop-guard.d.ts +18 -0
- package/dist/hooks/stop-guard.js +55 -10
- package/dist/mcp/tools.js +7 -1
- package/dist/renderer/inspect-renderer.js +23 -6
- package/dist/renderer/rule-renderer.js +4 -2
- package/dist/store/evidence-store.js +37 -2
- package/dist/store/profile-score.d.ts +55 -0
- package/dist/store/profile-score.js +100 -0
- package/dist/store/profile-store.d.ts +22 -5
- package/dist/store/profile-store.js +42 -6
- package/dist/store/rule-origin.d.ts +39 -0
- package/dist/store/rule-origin.js +84 -0
- package/dist/store/types.d.ts +24 -0
- package/package.json +1 -1
- package/plugin.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,82 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [0.6.2] — 2026-10-07 — statusline 이 실제로는 페이로드를 한 번도 받지 못하고 있었다 (socketpair stdin)
|
|
11
|
+
|
|
12
|
+
### Fixed
|
|
13
|
+
- **`forgen statusline` 이 Claude Code 가 주는 stdin JSON 을 0.5.9 부터 단 한 번도 읽지 못했다.** Claude Code(Node)는
|
|
14
|
+
statusline 을 `stdio:'pipe'` 로 띄우고 Linux 에서 그 stdin 은 UNIX **socketpair** 인데, 구현이 `fs.readFileSync('/dev/stdin')`
|
|
15
|
+
으로 읽어 소켓에서 ENXIO 로 실패 → 페이로드가 항상 `{}` → 모델명 'Claude', 세션 없음(`statusline-cache-nosession`),
|
|
16
|
+
컨텍스트·한도·소진 예측·관련 룰·세션 모델 캐시 전부 공백. 셸 파이프(`echo … | forgen statusline`)로만 검증해 v0.6.0/0.6.1
|
|
17
|
+
까지 못 잡았고, 배포 후 15시간 실사용 관측(한도 샘플 1건·세션 캐시 nosession 만 갱신)으로 드러났다. 훅과 같은 이벤트
|
|
18
|
+
기반 리더(`read-stdin.ts`, idle/timeout)로 교체. Node `spawn` 으로 socketpair 경로를 그대로 재현하는 회귀 테스트 추가
|
|
19
|
+
(지연 도착·EOF 없음·빈 페이로드 포함).
|
|
20
|
+
- 부수: 세션별 모델 캐시(`current-model-<session>.json`)가 이제야 실제로 기록되므로, 측정된 모델(Opus 4.8 등)에서
|
|
21
|
+
완료 가드가 advise 모드로 동작하는 ADR-010 W4-3 경로도 이번에 처음 live 가 된다.
|
|
22
|
+
|
|
23
|
+
## [0.6.1] — 2026-10-06 — 핫픽스: 임시 경로 예외가 CI(루트 디렉터리 부재)에서 전부 false 이던 것 · self-gate 테스트 픽스처
|
|
24
|
+
|
|
25
|
+
### Fixed
|
|
26
|
+
- **`isTempOnlyRm` 의 symlink 검사가 임시 루트(`/tmp/claude-*`)가 아직 없는 환경에서 false 를 내던 것.** 가장 깊은 실존
|
|
27
|
+
조상이 `/tmp` 가 되면 그 realpath 만 보고 루트 밖으로 판정했다 — 로컬엔 디렉터리가 있어 통과했고 v0.6.0 의 Release
|
|
28
|
+
워크플로우(`npm test`)에서 6건 실패로 **npm 발행이 되지 않았다**(registry 는 0.5.9 유지). 실존 조상의 realpath 에
|
|
29
|
+
나머지 경로를 붙여 비교하도록 수정, 루트 부재 케이스 테스트 추가.
|
|
30
|
+
- `tests/block-receipts.test.ts` 의 마스킹 검증 픽스처(PEM 헤더·JWT 모양 문자열)가 self-gate(secrets-leak) 정적 스캔에
|
|
31
|
+
걸려 v0.6.0 의 `forgen-self-gate` CI 가 실패했다(코드 결함 아님, 테스트 소스의 리터럴). 런타임에 조립하도록 바꿔
|
|
32
|
+
스캔을 통과시킨다. 동작 변경 없음.
|
|
33
|
+
|
|
34
|
+
## [0.6.0] — 2026-10-06 — 신뢰 영수증: 차단·룰·프로필·statusline 이 "왜/언제/얼마나" 를 보여준다 (ADR-017)
|
|
35
|
+
|
|
36
|
+
오너 피드백 "교정·차단은 좋은데 체감이 안 된다" 에서 출발. 실측으로 드러난 문제 — 7d 차단 108건 중 78건이 테스트 유래,
|
|
37
|
+
Bypass 179건은 전량 휴리스틱 오탐, Recall 773건 중 351건이 테스트 픽스처, 4축 프로필 score 는 갱신 코드 자체가 없었음,
|
|
38
|
+
채굴 룰 30개는 같은 교정의 문장 변형, statusline 은 Claude Code 가 주는 컨텍스트/한도 필드를 하나도 안 읽음 — 을 고쳤다.
|
|
39
|
+
Fable critic 8라운드(ADR·프로필·D0·집계·statusline×2·D1·pre-landing) 반영. vitest 3356 passed (smoke-report). 결정 문서: docs/adr/ADR-017.
|
|
40
|
+
|
|
41
|
+
### Fixed
|
|
42
|
+
- **4축 프로필 score 가 v0.1.0 부터 0.5 리터럴 고정이던 결함.** 산출 로직이 애초에 없었다. facet 카탈로그 양 끝 팩 centroid
|
|
43
|
+
선분에 facet 벡터를 투영한 위치와 confidence 를 섞는 공식(`c×t + (1−c)×0.5`)을 구현하고, confidence bump·auto-compound
|
|
44
|
+
facet 갱신 저장을 한 경로(`saveProfileRecomputed`, atomic)로 통합. SessionStart 에서 미계산 프로필 1회 재계산(변경 없어도
|
|
45
|
+
스탬프). `inspect` 의 "N corrections" 라벨은 explicit 교정만(450→247).
|
|
46
|
+
- **status 숫자의 정직성.** session_id 없이 기록된(`default`/`unknown` — 실측 전부 테스트가 dist 훅을 spawn 한 흔적) 차단을
|
|
47
|
+
모든 집계에서 제외하고 `Excluded N` 으로 가시화. T2 는 실제 차단(block/deny)만 집계(메타가드 advise 87건이 위반으로 세어지던
|
|
48
|
+
것). Top rules 는 rule_id 로 집계(source 로 집계돼 룰별 precision 과 조인 불가하던 것). Recall hits 는 hook 경로 후보≥1 만,
|
|
49
|
+
시도·mcp 분리.
|
|
50
|
+
- **테스트가 실 `~/.forgen` 을 오염시키던 것.** hook-pipeline(실 HOME spawn)·solution-reader/plugin-coexistence/harness-e2e
|
|
51
|
+
(in-process)·fgx-routing(실 claude 바이너리 실행) 격리. 전체 suite 실행 시 실 로그 증가 0 확인.
|
|
52
|
+
- 하드 룰 "확인 없는 rm -rf 금지" 가 Claude 의 **자기 임시 작업 폴더**(`/tmp/claude-*/scratchpad`) 정리까지 막던 것(7d 실 차단
|
|
53
|
+
14건 중 13건). 같은 명령 안의 변수 대입을 한 단계 치환해 대상이 전부 임시 경로일 때만 통과(보수적 — 하나라도 비임시·미해석이면 차단).
|
|
54
|
+
|
|
55
|
+
### Added
|
|
56
|
+
- **차단 메시지에 룰의 출처.** explicit 교정 룰이 막을 때 `[forgen] 이 룰의 출처 — 2026-09-30 교정 기록 (avoid-this)` 를 붙인다.
|
|
57
|
+
정직성: 저장된 summary 는 모델이 쓴 문장이라 policy 와 같으면 인용하지 않고 날짜·종류만; 새 `correction-record` 인자
|
|
58
|
+
`user_quote`(사용자 발화 원문, `<private>` 필터) 가 있을 때만 "당신의 말" 로 인용. 룰 렌더에 ` (교정 YYYY-MM-DD)` 꼬리표.
|
|
59
|
+
- **차단 영수증 + 자동 판정 + precision.** 차단마다 `violation_id`·매칭 프래그먼트·전문 hash 를 남기고 전문은 secret 마스킹 후
|
|
60
|
+
24h 영수증으로 보관. `forgen status --blocks` 가 영수증·판정·전후 문맥을 보여주고, `forgen block <id> --ok|--fp` 로 사람이
|
|
61
|
+
판정(자동 판정을 덮어씀). 차단 직후 detached Haiku 심판(auto-compound 와 같은 consent·캡 세션 10/일 30·불확실은 unsure).
|
|
62
|
+
룰별 precision 을 status 에 표시하고 7d 판정 ≥5 & precision <0.5 면 `advise`(차단 대신 기록) 로 강등 — 하드 룰·builtin 제외,
|
|
63
|
+
복귀 `forgen rule enforce <id>`.
|
|
64
|
+
- **statusline 2줄 재설계.** 1줄: 모델·경로(브랜치)·`ctx 42%/1M`·`5h 63% → 15:40 소진 (리셋 16:20)`·`7d 21%`·`$1.23`
|
|
65
|
+
(Claude Code 공식 stdin 필드). 2줄: `관련 룰 N · 이 세션 차단 N · 7d 차단 N · surfaced N`. 소진 예측은 창 안 양끝점 기울기,
|
|
66
|
+
근거 부족(샘플<3, 폭<15분/2h, 증가<1%p, 리셋 경과)이면 숨김, 현재 페이로드에 있는 창만 표시. 2줄만 세션별 15초 캐시.
|
|
67
|
+
운영자 지표·CLAUDE.md/MCP/hook 카운트(MCP 는 틀린 값이었음)는 삭제. ADR-010 §2b(usage 철수) 부분 supersede.
|
|
68
|
+
- **턴 단위 관련 룰.** 프롬프트를 룰 용어와 보수적으로 매칭(일반 용어 2개 또는 식별자급 1개)해 `관련 룰 N` 표시,
|
|
69
|
+
`forgen status --turn` 이 각 룰의 원 교정을 보여준다. 프롬프트 원문은 저장하지 않고 주입도 0바이트.
|
|
70
|
+
- **채굴 룰 병합.** `forgen rule merge-mined [--apply]` — 채굴(auto:) 룰끼리만 병합(strength default 고정), explicit 동개념은
|
|
71
|
+
흡수하지 않고 링크(`mined_observations`) — ADR-013 불변식 유지. 승격 시 사전 중복 검사. 실측 채굴 30 → 7(활성 45 → 22).
|
|
72
|
+
- Stop 에서 실제 평가돼 통과한 룰을 `checks.jsonl`(7d TTL)에 기록 — 위반 로그와 분리.
|
|
73
|
+
|
|
74
|
+
### Changed
|
|
75
|
+
- 자연어 휴리스틱 bypass 기록(`bypass.jsonl`) 중단 — 실측 1,114건 전량 오탐(룰 policy 의 단어가 도구 출력에 등장), 실 우회 0건.
|
|
76
|
+
T3 입력은 `FORGEN_USER_CONFIRMED=1` 명시 우회(kind `bypass_confirmed`)만. 기존 파일은 보존(읽지 않음). flagged 룰을 `--rules` 에 표기.
|
|
77
|
+
- `status --blocks` 는 실세션 실제 차단만, lifecycle-scan 은 `bypass_confirmed=N` 표시.
|
|
78
|
+
|
|
79
|
+
### 알려진 한계 (정직 표기)
|
|
80
|
+
- 자동 판정은 compound consent(`forgen compound consent on`)가 켜져 있을 때만 돈다. 꺼져 있으면 미판정으로 남고 precision 강등도 없다.
|
|
81
|
+
- 합성 세션 필터는 값 기반(`default`/`unknown`/빈 값) — eval/probe 하네스가 임의 id 를 쓰면 걸러지지 않는다(격리 FORGEN_HOME 전제).
|
|
82
|
+
- 채굴 병합은 category 경계를 유지해 ADR 예상(≤5)보다 많은 7개로 수렴. τ=0.3 에서 오탐 링크 1건 가능 — dry-run 기본.
|
|
83
|
+
- 관련 룰 매칭은 한글 활용형("검증해"≠"검증")을 못 잡는다 — 보수적 방향.
|
|
84
|
+
- 소진 예측의 실세션 관측은 이번 릴리스로 statusline 이 글로벌 패키지에 실린 뒤부터.
|
|
85
|
+
|
|
10
86
|
## [0.5.9] — 2026-10-02 — 남겨 둔 한계 정리: 사용자 스킬 보존 · AGENTS.md 전체 정리 · OpenCode uninstall · claude-mem 13.28
|
|
11
87
|
|
|
12
88
|
### Fixed
|
package/README.ja.md
CHANGED
|
@@ -535,6 +535,18 @@ forgen rule activate <id> # suppressed ルールを再アクティブ化
|
|
|
535
535
|
forgen rule scan [--apply] # ライフサイクルトリガー実行 (昇格/降格/引退)
|
|
536
536
|
forgen rule health-scan # drift → Mech 降格候補をスキャン
|
|
537
537
|
forgen rule classify # 既存ルールに enforce_via を自動提案
|
|
538
|
+
forgen rule merge-mined [--apply] # マイニング(auto:)ルール同士を統合、同概念の explicit ルールにはリンクのみ (既定 dry-run)
|
|
539
|
+
forgen rule unmerge <id> # 統合/リンクされたルールの原本を復元
|
|
540
|
+
forgen rule enforce|advise <id> # 自動降格されたルールのブロック復帰 / 記録のみモード (hard ルールは拒否)
|
|
541
|
+
```
|
|
542
|
+
|
|
543
|
+
### 信頼レシート (v0.6.0)
|
|
544
|
+
|
|
545
|
+
```bash
|
|
546
|
+
forgen status --blocks [N] # 最近の実ブロック + レシート: 一致フラグメント、24h 前後文脈、判定(auto/user)
|
|
547
|
+
forgen block <id> --ok | --fp # ブロックを判定 (自動 Haiku 判定を上書き) — ルール別 precision に反映
|
|
548
|
+
forgen status --turn # 今ターンに関連するルールと、各ルールが生まれた修正(日付・種類・あなたの発言)
|
|
549
|
+
forgen statusline # 2行: モデル · パス(ブランチ) · ctx % · 5h/7d 上限 + 枯渇予測 · $ / 関連ルール · ブロック · surfaced
|
|
538
550
|
```
|
|
539
551
|
|
|
540
552
|
### 知識管理
|
package/README.ko.md
CHANGED
|
@@ -520,6 +520,18 @@ forgen rule activate <id> # suppressed 규칙 재활성화
|
|
|
520
520
|
forgen rule scan [--apply] # 수명주기 트리거 실행 (승격/강등/은퇴)
|
|
521
521
|
forgen rule health-scan # drift → Mech 강등 후보 스캔
|
|
522
522
|
forgen rule classify # 레거시 규칙에 enforce_via 자동 제안
|
|
523
|
+
forgen rule merge-mined [--apply] # 채굴(auto:) 규칙끼리 병합, 같은 개념의 explicit 규칙엔 링크만 (기본 dry-run)
|
|
524
|
+
forgen rule unmerge <id> # 병합/링크된 규칙의 원본 복원
|
|
525
|
+
forgen rule enforce|advise <id> # 자동 강등된 규칙의 차단 복귀 / 기록만 모드 (hard 규칙은 거부)
|
|
526
|
+
```
|
|
527
|
+
|
|
528
|
+
### 신뢰 영수증 (v0.6.0)
|
|
529
|
+
|
|
530
|
+
```bash
|
|
531
|
+
forgen status --blocks [N] # 최근 실제 차단 + 영수증: 매칭 프래그먼트, 24h 전후 문맥, 판정(auto/user)
|
|
532
|
+
forgen block <id> --ok | --fp # 차단 판정 (자동 Haiku 판정을 덮어씀) — 규칙별 precision 에 반영
|
|
533
|
+
forgen status --turn # 이번 턴 관련 규칙과 각 규칙이 생긴 교정(날짜·종류·당신의 말)
|
|
534
|
+
forgen statusline # 2줄: 모델 · 경로(브랜치) · ctx % · 5h/7d 한도 + 소진 예측 · $ / 관련 규칙 · 차단 · surfaced
|
|
523
535
|
```
|
|
524
536
|
|
|
525
537
|
### 지식 관리
|
package/README.md
CHANGED
|
@@ -717,6 +717,18 @@ forgen rule activate <id> # Re-activate a suppressed rule
|
|
|
717
717
|
forgen rule scan [--apply] # Run lifecycle triggers (promote/demote/retire)
|
|
718
718
|
forgen rule health-scan # Scan drift → Mech downgrade candidates
|
|
719
719
|
forgen rule classify # Propose enforce_via for legacy rules
|
|
720
|
+
forgen rule merge-mined [--apply] # Merge mined (auto:) rules among themselves; link same-concept ones to explicit rules (dry-run by default)
|
|
721
|
+
forgen rule unmerge <id> # Restore originals of a merged/linked rule
|
|
722
|
+
forgen rule enforce|advise <id> # Restore blocking for an auto-demoted rule / record-only mode (hard rules refused)
|
|
723
|
+
```
|
|
724
|
+
|
|
725
|
+
### Trust receipts (v0.6.0)
|
|
726
|
+
|
|
727
|
+
```bash
|
|
728
|
+
forgen status --blocks [N] # Recent real blocks with receipt: matched fragment, 24h context, verdict (auto/user)
|
|
729
|
+
forgen block <id> --ok | --fp # Judge a block (overrides the automatic Haiku verdict); feeds per-rule precision
|
|
730
|
+
forgen status --turn # Rules relevant to the current turn, each with the correction (date/kind/your words) it came from
|
|
731
|
+
forgen statusline # 2 lines: model · path(branch) · ctx % · 5h/7d limits + exhaustion forecast · $ / related rules · blocks · surfaced
|
|
720
732
|
```
|
|
721
733
|
|
|
722
734
|
### Knowledge management
|
package/README.zh.md
CHANGED
|
@@ -504,6 +504,18 @@ forgen rule activate <id> # 重新激活 suppressed 规则
|
|
|
504
504
|
forgen rule scan [--apply] # 运行生命周期触发器 (晋升/降级/退役)
|
|
505
505
|
forgen rule health-scan # 扫描 drift → Mech 降级候选
|
|
506
506
|
forgen rule classify # 为旧规则自动提议 enforce_via
|
|
507
|
+
forgen rule merge-mined [--apply] # 挖掘(auto:)规则之间合并,与同概念 explicit 规则仅建立链接 (默认 dry-run)
|
|
508
|
+
forgen rule unmerge <id> # 恢复已合并/链接规则的原件
|
|
509
|
+
forgen rule enforce|advise <id> # 恢复自动降级规则的拦截 / 仅记录模式 (hard 规则拒绝)
|
|
510
|
+
```
|
|
511
|
+
|
|
512
|
+
### 信任回执 (v0.6.0)
|
|
513
|
+
|
|
514
|
+
```bash
|
|
515
|
+
forgen status --blocks [N] # 最近真实拦截 + 回执: 匹配片段、24h 上下文、判定(auto/user)
|
|
516
|
+
forgen block <id> --ok | --fp # 判定一次拦截 (覆盖自动 Haiku 判定) — 计入规则级 precision
|
|
517
|
+
forgen status --turn # 本轮相关规则,以及每条规则来源的纠正(日期·类型·你的原话)
|
|
518
|
+
forgen statusline # 2 行: 模型 · 路径(分支) · ctx % · 5h/7d 配额 + 耗尽预测 · $ / 相关规则 · 拦截 · surfaced
|
|
507
519
|
```
|
|
508
520
|
|
|
509
521
|
### 知识管理
|
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
*/
|
|
20
20
|
export type CompletionGuardMode = 'block' | 'advise';
|
|
21
21
|
export declare function guardModeForModel(modelId: string | null | undefined): CompletionGuardMode;
|
|
22
|
-
/** statusline 이 세션별 모델을 기록 (fail-open) */
|
|
22
|
+
/** statusline 이 세션별 모델을 기록 (fail-open). `home` 은 테스트용 명시 경로. */
|
|
23
23
|
export declare function cacheSessionModel(sessionId: string, modelId: string, home?: string): void;
|
|
24
24
|
/** 가드가 세션별 모델 조회. 우선순위: FORGEN_MODEL env > statusline 캐시 > null */
|
|
25
25
|
export declare function readSessionModel(sessionId: string, home?: string): string | null;
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
* → 현행 동작(block) 유지. FORGEN_MODEL env 가 있으면 최우선.
|
|
19
19
|
*/
|
|
20
20
|
import * as fs from 'node:fs';
|
|
21
|
-
import
|
|
21
|
+
import { STATE_DIR } from '../../core/paths.js';
|
|
22
22
|
import * as path from 'node:path';
|
|
23
23
|
/**
|
|
24
24
|
* 측정 기반 기본 테이블. 버전 경계 안전 매칭 (리뷰 SEV-2: 단순 prefix 는
|
|
@@ -36,10 +36,14 @@ export function guardModeForModel(modelId) {
|
|
|
36
36
|
}
|
|
37
37
|
function cachePath(sessionId, home) {
|
|
38
38
|
// sessionId 는 호출측에서 sanitize 된 값이어야 함 (경로 주입 방지)
|
|
39
|
-
|
|
39
|
+
// ADR-017 (critic): home 미지정이면 paths.ts STATE_DIR — FORGEN_HOME 격리를 존중한다. 이전엔
|
|
40
|
+
// os.homedir() 고정이라 격리 실행(테스트·에이전트)이 실 ~/.forgen/state 에 current-model-*.json 을 흘렸다.
|
|
41
|
+
if (home)
|
|
42
|
+
return path.join(home, '.forgen', 'state', `current-model-${sessionId}.json`);
|
|
43
|
+
return path.join(STATE_DIR, `current-model-${sessionId}.json`);
|
|
40
44
|
}
|
|
41
|
-
/** statusline 이 세션별 모델을 기록 (fail-open) */
|
|
42
|
-
export function cacheSessionModel(sessionId, modelId, home
|
|
45
|
+
/** statusline 이 세션별 모델을 기록 (fail-open). `home` 은 테스트용 명시 경로. */
|
|
46
|
+
export function cacheSessionModel(sessionId, modelId, home) {
|
|
43
47
|
try {
|
|
44
48
|
const p = cachePath(sessionId, home);
|
|
45
49
|
fs.mkdirSync(path.dirname(p), { recursive: true });
|
|
@@ -48,7 +52,7 @@ export function cacheSessionModel(sessionId, modelId, home = os.homedir()) {
|
|
|
48
52
|
catch { /* fail-open */ }
|
|
49
53
|
}
|
|
50
54
|
/** 가드가 세션별 모델 조회. 우선순위: FORGEN_MODEL env > statusline 캐시 > null */
|
|
51
|
-
export function readSessionModel(sessionId, home
|
|
55
|
+
export function readSessionModel(sessionId, home) {
|
|
52
56
|
const envModel = process.env.FORGEN_MODEL;
|
|
53
57
|
if (envModel && envModel.trim().length > 0)
|
|
54
58
|
return envModel.trim();
|
package/dist/cli.js
CHANGED
|
@@ -94,9 +94,17 @@ const commands = [
|
|
|
94
94
|
}
|
|
95
95
|
},
|
|
96
96
|
},
|
|
97
|
+
{
|
|
98
|
+
name: 'block',
|
|
99
|
+
description: 'Judge a block receipt: forgen block <id|prefix> --ok | --fp [--reason "..."] (ADR-017 D1)',
|
|
100
|
+
handler: async (args) => {
|
|
101
|
+
const { handleBlock } = await import('./core/block-cli.js');
|
|
102
|
+
await handleBlock(args);
|
|
103
|
+
},
|
|
104
|
+
},
|
|
97
105
|
{
|
|
98
106
|
name: 'status',
|
|
99
|
-
description: 'Unified status: forgen status [--compound|--profile|--rules|--blocks [N]|--overview|--live]',
|
|
107
|
+
description: 'Unified status: forgen status [--compound|--profile|--rules|--blocks [N]|--overview|--live|--turn]',
|
|
100
108
|
handler: async (args) => {
|
|
101
109
|
const { handleStatus } = await import('./core/status-cli.js');
|
|
102
110
|
await handleStatus(args);
|
|
@@ -288,7 +296,8 @@ const commands = [
|
|
|
288
296
|
},
|
|
289
297
|
{
|
|
290
298
|
name: 'rule',
|
|
291
|
-
|
|
299
|
+
aliases: ['rules'],
|
|
300
|
+
description: 'Rule management (list|suppress|activate|scan|health-scan|classify|merge-mined|unmerge)',
|
|
292
301
|
handler: async (args) => {
|
|
293
302
|
await handleRuleNamespace(args);
|
|
294
303
|
},
|
|
@@ -373,6 +382,11 @@ async function handleRuleNamespace(args) {
|
|
|
373
382
|
forgen rule classify [--apply] [--force]
|
|
374
383
|
Propose enforce_via for legacy rules
|
|
375
384
|
forgen rule unmerge-cluster <id> Undo a W3-2 correction-cluster merge (restore originals)
|
|
385
|
+
forgen rule merge-mined [--apply] ADR-017 D3: merge mined (auto:) rules among themselves,
|
|
386
|
+
link same-concept ones to explicit rules (dry-run by default)
|
|
387
|
+
forgen rule unmerge <id> Restore originals of a merged/linked rule (alias of unmerge-cluster)
|
|
388
|
+
forgen rule enforce <id-or-prefix> ADR-017 D1: restore blocking for a rule auto-demoted to advise
|
|
389
|
+
forgen rule advise <id-or-prefix> Record-only mode (no block); hard rules refused
|
|
376
390
|
`);
|
|
377
391
|
return;
|
|
378
392
|
}
|
|
@@ -407,11 +421,25 @@ async function handleRuleNamespace(args) {
|
|
|
407
421
|
await handleClassifyEnforce(rest);
|
|
408
422
|
return;
|
|
409
423
|
}
|
|
424
|
+
case 'enforce':
|
|
425
|
+
case 'advise': {
|
|
426
|
+
const { handleEnforceMode } = await import('./engine/rule-toggle-cli.js');
|
|
427
|
+
await handleEnforceMode(rest, sub === 'advise' ? 'advise' : 'block');
|
|
428
|
+
return;
|
|
429
|
+
}
|
|
430
|
+
case 'merge-mined': {
|
|
431
|
+
// ADR-017 D3: 채굴 룰 병합(채굴끼리) + explicit 동개념 링크. 기본 dry-run.
|
|
432
|
+
const { handleMergeMined } = await import('./engine/mined-rule-merge-cli.js');
|
|
433
|
+
await handleMergeMined(rest);
|
|
434
|
+
return;
|
|
435
|
+
}
|
|
436
|
+
case 'unmerge':
|
|
410
437
|
case 'unmerge-cluster': {
|
|
411
438
|
// W3-2: 교정 클러스터 통합 취소 — 원본 룰 복원 + 재통합 억제.
|
|
439
|
+
// ADR-017 D3: 채굴 통합 룰 / explicit 링크 타깃에도 동일 경로(링크 타깃은 removed 안 됨).
|
|
412
440
|
const mergedId = rest[0];
|
|
413
441
|
if (!mergedId) {
|
|
414
|
-
console.error(
|
|
442
|
+
console.error(`[forgen] usage: forgen rule ${sub} <merged-rule-id>`);
|
|
415
443
|
process.exit(1);
|
|
416
444
|
}
|
|
417
445
|
const { unmergeCluster } = await import('./engine/correction-cluster-runner.js');
|
|
@@ -590,6 +618,7 @@ function printHelp() {
|
|
|
590
618
|
--blocks [N] recent block(s): rule/reason/fix
|
|
591
619
|
--overview rich dashboard (hooks·history·curve)
|
|
592
620
|
--live real-time hook event stream
|
|
621
|
+
--turn this turn's relevant rules + their origin corrections
|
|
593
622
|
forgen workflows install|list Install forgen dynamic-workflow templates to .claude/workflows/
|
|
594
623
|
forgen changelog Auto-summarize commits since last release tag
|
|
595
624
|
forgen compound Manage accumulated knowledge
|
|
@@ -648,55 +648,32 @@ ${sanitizedSummary.slice(0, 4000)}
|
|
|
648
648
|
if (minedCorrections > 0) {
|
|
649
649
|
process.stderr.write(`[forgen-auto-compound] mined ${minedCorrections} correction(s) (advisory-only, capped, age-retired)\n`);
|
|
650
650
|
}
|
|
651
|
-
// facet delta 적용
|
|
651
|
+
// facet delta 적용 — ADR-017: raw JSON write 금지. profile-store 경유로 score 재계산.
|
|
652
652
|
if (parsed.profile_delta) {
|
|
653
|
-
const
|
|
653
|
+
const { loadProfile, saveProfileRecomputed } = await import('../store/profile-store.js');
|
|
654
|
+
const profile = loadProfile();
|
|
655
|
+
// (critic) 동적 import 가 상단 정적 loadProfile 을 가리지만 동일 모듈 — 의도적으로 지역 바인딩 사용.
|
|
654
656
|
const clamp = (v) => Math.max(0.0, Math.min(1.0, v));
|
|
655
657
|
let changed = false;
|
|
656
|
-
if (
|
|
657
|
-
const
|
|
658
|
-
const
|
|
659
|
-
|
|
660
|
-
if (
|
|
661
|
-
|
|
662
|
-
|
|
658
|
+
if (profile) {
|
|
659
|
+
const axes = ['quality_safety', 'autonomy', 'judgment_philosophy', 'communication_style'];
|
|
660
|
+
for (const axis of axes) {
|
|
661
|
+
const d = parsed.profile_delta[axis];
|
|
662
|
+
if (!d)
|
|
663
|
+
continue;
|
|
664
|
+
const f = profile.axes[axis].facets;
|
|
665
|
+
for (const [k, v] of Object.entries(d)) {
|
|
666
|
+
if (typeof v === 'number' && Math.abs(v) > 0.001 && Object.hasOwn(f, k)) { // hasOwn: 프로토타입 키 차단 (critic)
|
|
667
|
+
f[k] = clamp(f[k] + v);
|
|
668
|
+
changed = true;
|
|
669
|
+
}
|
|
663
670
|
}
|
|
664
671
|
}
|
|
665
672
|
}
|
|
666
|
-
if (
|
|
667
|
-
const
|
|
668
|
-
const
|
|
669
|
-
|
|
670
|
-
if (typeof v === 'number' && Math.abs(v) > 0.001 && k in f) {
|
|
671
|
-
f[k] = clamp(f[k] + v);
|
|
672
|
-
changed = true;
|
|
673
|
-
}
|
|
674
|
-
}
|
|
675
|
-
}
|
|
676
|
-
if (parsed.profile_delta.judgment_philosophy) {
|
|
677
|
-
const d = parsed.profile_delta.judgment_philosophy;
|
|
678
|
-
const f = profile.axes.judgment_philosophy.facets;
|
|
679
|
-
for (const [k, v] of Object.entries(d)) {
|
|
680
|
-
if (typeof v === 'number' && Math.abs(v) > 0.001 && k in f) {
|
|
681
|
-
f[k] = clamp(f[k] + v);
|
|
682
|
-
changed = true;
|
|
683
|
-
}
|
|
684
|
-
}
|
|
685
|
-
}
|
|
686
|
-
if (parsed.profile_delta.communication_style) {
|
|
687
|
-
const d = parsed.profile_delta.communication_style;
|
|
688
|
-
const f = profile.axes.communication_style.facets;
|
|
689
|
-
for (const [k, v] of Object.entries(d)) {
|
|
690
|
-
if (typeof v === 'number' && Math.abs(v) > 0.001 && k in f) {
|
|
691
|
-
f[k] = clamp(f[k] + v);
|
|
692
|
-
changed = true;
|
|
693
|
-
}
|
|
694
|
-
}
|
|
695
|
-
}
|
|
696
|
-
if (changed) {
|
|
697
|
-
profile.metadata.updated_at = new Date().toISOString();
|
|
698
|
-
fs.writeFileSync(V1_PROFILE, JSON.stringify(profile, null, 2));
|
|
699
|
-
process.stderr.write('[forgen-auto-compound] profile facets updated from session learning\n');
|
|
673
|
+
if (profile && changed) {
|
|
674
|
+
const r = saveProfileRecomputed(profile);
|
|
675
|
+
const moved = Object.entries(r.deltas).filter(([, d]) => Math.abs(d.after - d.before) > 1e-9).map(([k, d]) => `${k} ${d.before.toFixed(2)}→${d.after.toFixed(2)}`);
|
|
676
|
+
process.stderr.write(`[forgen-auto-compound] profile facets updated from session learning${moved.length ? ` (score: ${moved.join(', ')})` : ''}\n`);
|
|
700
677
|
}
|
|
701
678
|
}
|
|
702
679
|
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function handleBlock(args: string[]): Promise<void>;
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* forgen block <id|prefix> --ok | --fp [--reason "..."] (ADR-017 D1)
|
|
3
|
+
* 사용자 판정 — 자동(Haiku) 판정을 덮어쓴다. id 는 violation_id 전체 또는 앞 8자 이상 prefix.
|
|
4
|
+
*/
|
|
5
|
+
import * as path from 'node:path';
|
|
6
|
+
import { STATE_DIR } from './paths.js';
|
|
7
|
+
import { readJsonlSafe, setVerdict, readReceipt, effectiveVerdicts } from '../engine/lifecycle/signals.js';
|
|
8
|
+
export async function handleBlock(args) {
|
|
9
|
+
const id = args.find((a) => !a.startsWith('--'));
|
|
10
|
+
const ok = args.includes('--ok');
|
|
11
|
+
const fp = args.includes('--fp');
|
|
12
|
+
const reasonIdx = args.indexOf('--reason');
|
|
13
|
+
const reason = reasonIdx >= 0 ? args[reasonIdx + 1] : undefined;
|
|
14
|
+
if (!id || (!ok && !fp) || (ok && fp)) {
|
|
15
|
+
console.log('usage: forgen block <violation_id|prefix> --ok | --fp [--reason "..."]');
|
|
16
|
+
console.log(' --ok 이 차단은 맞다(정탐) --fp 이 차단은 틀렸다(오탐). 자동 판정을 덮어씁니다.');
|
|
17
|
+
return;
|
|
18
|
+
}
|
|
19
|
+
if (!/^[A-Za-z0-9-]{8,}$/.test(id)) {
|
|
20
|
+
console.log(`invalid id: ${id}`);
|
|
21
|
+
return;
|
|
22
|
+
}
|
|
23
|
+
const all = readJsonlSafe(path.join(STATE_DIR, 'enforcement', 'violations.jsonl'));
|
|
24
|
+
const matches = all.filter((v) => typeof v.violation_id === 'string' && v.violation_id.startsWith(id));
|
|
25
|
+
if (matches.length === 0) {
|
|
26
|
+
console.log(`no block with id ${id}. See: forgen status --blocks 5`);
|
|
27
|
+
return;
|
|
28
|
+
}
|
|
29
|
+
const ids = new Set(matches.map((v) => v.violation_id));
|
|
30
|
+
if (ids.size > 1) {
|
|
31
|
+
console.log(`ambiguous prefix ${id} → ${[...ids].join(', ')}`);
|
|
32
|
+
return;
|
|
33
|
+
}
|
|
34
|
+
const v = matches[matches.length - 1];
|
|
35
|
+
const prev = effectiveVerdicts().get(v.violation_id);
|
|
36
|
+
setVerdict({ violation_id: v.violation_id, rule_id: v.rule_id, verdict: ok ? 'correct' : 'false_positive', by: 'user', reason });
|
|
37
|
+
console.log(`✓ [forgen] ${v.violation_id} (${v.rule_id}) → ${ok ? 'correct (정탐)' : 'false_positive (오탐)'} by user${prev ? ` (이전: ${prev.verdict} by ${prev.by})` : ''}`);
|
|
38
|
+
const receipt = readReceipt(v.violation_id);
|
|
39
|
+
if (receipt)
|
|
40
|
+
console.log(` receipt: ${receipt.split('\n')[0].slice(0, 100)}${receipt.length > 100 ? '…' : ''}`);
|
|
41
|
+
}
|
package/dist/core/explain-cli.js
CHANGED
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
import * as fs from 'node:fs';
|
|
7
7
|
import * as path from 'node:path';
|
|
8
8
|
import { STATE_DIR } from './paths.js';
|
|
9
|
+
import { isRealBlock, effectiveVerdicts, readReceipt } from '../engine/lifecycle/signals.js';
|
|
9
10
|
const isTTY = process.stdout.isTTY;
|
|
10
11
|
const C = {
|
|
11
12
|
reset: isTTY ? '\x1b[0m' : '',
|
|
@@ -57,7 +58,9 @@ function formatTime(iso) {
|
|
|
57
58
|
}
|
|
58
59
|
}
|
|
59
60
|
export async function handleExplain(args) {
|
|
60
|
-
|
|
61
|
+
// ADR-017 D1: `--blocks` 는 실세션의 실제 차단만 보여준다(테스트 유래 'default' 세션·
|
|
62
|
+
// advise(correction)·명시 우회 제외). 원시 로그는 `forgen inspect`.
|
|
63
|
+
const violations = readViolations().filter((v) => isRealBlock(v));
|
|
61
64
|
if (violations.length === 0) {
|
|
62
65
|
console.log(`\n ${C.green}No blocks recorded.${C.reset} forgen hasn't blocked Claude yet.\n`);
|
|
63
66
|
return;
|
|
@@ -65,6 +68,7 @@ export async function handleExplain(args) {
|
|
|
65
68
|
const count = Math.min(Number(args[0]) || 1, 5);
|
|
66
69
|
const targets = violations.slice(-count);
|
|
67
70
|
const acks = readAcknowledgments();
|
|
71
|
+
const verdicts = effectiveVerdicts();
|
|
68
72
|
for (const v of targets) {
|
|
69
73
|
const ruleId = v.rule_id ?? v.rule ?? v.guard ?? 'unknown';
|
|
70
74
|
const source = v.source ?? 'unknown';
|
|
@@ -91,6 +95,30 @@ export async function handleExplain(args) {
|
|
|
91
95
|
console.log(` ${C.dim}${line}${C.reset}`);
|
|
92
96
|
}
|
|
93
97
|
console.log(` ${C.cyan}Resolved:${C.reset} ${wasAcked ? `${C.green}Yes — Claude retracted and resubmitted with evidence${C.reset}` : `${C.yellow}No acknowledgment found${C.reset}`}`);
|
|
98
|
+
// ADR-017 D1 영수증: id · 매칭 프래그먼트 · 판정 · 전문 발췌(24h 내)
|
|
99
|
+
const vid = typeof v.violation_id === 'string' ? v.violation_id : '';
|
|
100
|
+
if (vid) {
|
|
101
|
+
const verdict = verdicts.get(vid);
|
|
102
|
+
const vLabel = !verdict ? `${C.yellow}unjudged${C.reset}`
|
|
103
|
+
: verdict.verdict === 'correct' ? `${C.green}correct (정탐)${C.reset} by ${verdict.by}`
|
|
104
|
+
: verdict.verdict === 'false_positive' ? `${C.red}false_positive (오탐)${C.reset} by ${verdict.by}`
|
|
105
|
+
: `${C.yellow}unsure${C.reset} by ${verdict.by}`;
|
|
106
|
+
console.log(` ${C.cyan}Receipt:${C.reset} ${vid.slice(0, 8)} verdict: ${vLabel}${verdict?.reason ? ` — ${C.dim}${verdict.reason.slice(0, 100)}${C.reset}` : ''}`);
|
|
107
|
+
if (typeof v.matched === 'string' && v.matched)
|
|
108
|
+
console.log(` ${C.cyan}Matched:${C.reset} ${C.dim}${v.matched.slice(0, 140)}${C.reset}`);
|
|
109
|
+
const receipt = readReceipt(vid);
|
|
110
|
+
if (receipt) {
|
|
111
|
+
console.log(` ${C.cyan}Context:${C.reset}`);
|
|
112
|
+
const m = typeof v.matched === 'string' ? v.matched.replace(/…$/, '').slice(0, 40) : '';
|
|
113
|
+
const lines = receipt.split('\n');
|
|
114
|
+
let at = m ? lines.findIndex((l) => l.includes(m)) : -1;
|
|
115
|
+
if (at < 0)
|
|
116
|
+
at = 0;
|
|
117
|
+
for (const line of lines.slice(Math.max(0, at - 1), at + 2))
|
|
118
|
+
console.log(` ${C.dim}${line.slice(0, 160)}${C.reset}`);
|
|
119
|
+
}
|
|
120
|
+
console.log(` ${C.dim}Judge: forgen block ${vid.slice(0, 8)} --ok | --fp${C.reset}`);
|
|
121
|
+
}
|
|
94
122
|
console.log('');
|
|
95
123
|
console.log(` ${C.dim}To suppress this rule: forgen suppress-rule ${ruleId}${C.reset}`);
|
|
96
124
|
console.log(` ${C.dim}To bypass one turn: set FORGEN_USER_CONFIRMED=1${C.reset}`);
|
package/dist/core/inspect-cli.js
CHANGED
|
@@ -11,7 +11,7 @@ import { loadAllRules, loadActiveRules } from '../store/rule-store.js';
|
|
|
11
11
|
import { loadRecentEvidence, loadAllEvidence } from '../store/evidence-store.js';
|
|
12
12
|
import { loadRecentSessions } from '../store/session-state-store.js';
|
|
13
13
|
import * as inspect from '../renderer/inspect-renderer.js';
|
|
14
|
-
import {
|
|
14
|
+
import { ME_SOLUTIONS, STATE_DIR } from './paths.js';
|
|
15
15
|
import { safeReadJSON } from '../hooks/shared/atomic-write.js';
|
|
16
16
|
export async function handleInspect(args) {
|
|
17
17
|
const sub = args[0];
|
|
@@ -28,14 +28,15 @@ export async function handleInspect(args) {
|
|
|
28
28
|
me: activeRules.filter(r => r.scope === 'me').length,
|
|
29
29
|
session: activeRules.filter(r => r.scope === 'session').length,
|
|
30
30
|
};
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
31
|
+
// ADR-017 §1.5b: "corrections" 라벨은 explicit_correction 만 센다. 이전엔 전체 evidence
|
|
32
|
+
// (behavior_observation·session_summary 포함) 파일 수를 corrections 로 표시해 450 vs 247 오기.
|
|
33
|
+
const allEvidence = loadAllEvidence();
|
|
34
|
+
const evidenceCount = allEvidence.filter(e => e.type === 'explicit_correction').length;
|
|
35
|
+
const otherEvidenceCount = allEvidence.length - evidenceCount;
|
|
36
36
|
const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
|
|
37
37
|
const recentEvidence = loadRecentEvidence(100);
|
|
38
|
-
|
|
38
|
+
// 7일 집계는 전체 집합 기준 (loadRecentEvidence(100) 캡에 걸리면 과소집계 — critic). stats-cli 와 동일 기준.
|
|
39
|
+
const recentCount = allEvidence.filter(e => e.type === 'explicit_correction' && e.timestamp >= sevenDaysAgo).length;
|
|
39
40
|
const solutionCount = (() => {
|
|
40
41
|
if (!fs.existsSync(ME_SOLUTIONS))
|
|
41
42
|
return 0;
|
|
@@ -53,7 +54,7 @@ export async function handleInspect(args) {
|
|
|
53
54
|
})();
|
|
54
55
|
console.log('── Learning Loop Status ──');
|
|
55
56
|
console.log(`Rules: ${activeRules.length} active (${rulesByScope.me} me, ${rulesByScope.session} session)`);
|
|
56
|
-
console.log(`Evidence: ${evidenceCount} corrections (last 7 days: ${recentCount})`);
|
|
57
|
+
console.log(`Evidence: ${evidenceCount} corrections (last 7 days: ${recentCount}; +${otherEvidenceCount} observations/summaries)`);
|
|
57
58
|
console.log(`Compound: ${solutionCount} solutions`);
|
|
58
59
|
console.log(`Last extraction: ${lastExtractionLabel}`);
|
|
59
60
|
console.log('');
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Rate-limit forecast — "지금 추세면 언제 다 쓰나" (ADR-017 D5)
|
|
3
|
+
*
|
|
4
|
+
* Claude Code statusline stdin 의 `rate_limits.{five_hour,seven_day}.{used_percentage,resets_at}` 를
|
|
5
|
+
* 호출마다 샘플로 쌓고, 최근 창의 기울기(EMA 평활)로 100% 도달 시각을 추정한다.
|
|
6
|
+
*
|
|
7
|
+
* 정직성 원칙 (ADR-017 §2-5): 근거가 부족하면 예측을 **숨긴다**. 틀린 예측 하나가 맞는 예측
|
|
8
|
+
* 열 개를 무효화한다. 숨김 조건 — 창 내 샘플 < MIN_SAMPLES, 창 내 시간 폭 < 창별 MIN_SPAN,
|
|
9
|
+
* 창 내 총 증가 < MIN_RISE_PCT, 기울기 ≤ 0, used_percentage null/비수치, resets_at 경과.
|
|
10
|
+
*
|
|
11
|
+
* 추정기 (critic SEV-1 반영): 사용률은 API 응답 시점에 **계단**으로 뛰고 호출 간격은 수 초~수십 분으로
|
|
12
|
+
* 불균일하다. 연속 쌍 기울기의 등가중 EMA 는 "정체 n개 + 짧은 dt 의 점프 1개" 에서 수십 배 과대했다
|
|
13
|
+
* (실측 27배). 창 안 **양끝점 기울기** (used_last − used_first)/(t_last − t_first) 로 교체 — dt 가중이
|
|
14
|
+
* 본질이고 점프 순서에 무관하다.
|
|
15
|
+
*
|
|
16
|
+
* 표시 게이트: 현재 페이로드에 그 창이 **수치로 존재할 때만** 출력한다. 파일 샘플은 기울기 전용.
|
|
17
|
+
* (리셋 순간 CC 는 창을 drop 하고 스크립트를 재실행하므로, 파일만 보면 리셋 전 최고치를 보여주게 된다.)
|
|
18
|
+
*
|
|
19
|
+
* 창 리셋 조건 (공식 문서 2026-10-06 확인: 창은 resets_at 을 가지며 지나면 객체가 사라졌다
|
|
20
|
+
* 재등장하고 초기엔 used_percentage 가 null 일 수 있다): resets_at 변화 · 사용률 하락 ·
|
|
21
|
+
* null 샘플 → 이전 샘플 폐기(해당 창만).
|
|
22
|
+
*
|
|
23
|
+
* 순수 함수 + 얇은 IO. 샘플 파일은 한 줄 단일 append, 읽기는 파싱 실패 라인 무시
|
|
24
|
+
* (Claude Code 가 statusline 스크립트를 중간에 취소하면 잘린 줄이 생길 수 있다).
|
|
25
|
+
*/
|
|
26
|
+
export type WindowKey = 'five_hour' | 'seven_day';
|
|
27
|
+
export interface RateWindow {
|
|
28
|
+
used_percentage?: number | null;
|
|
29
|
+
resets_at?: number | null;
|
|
30
|
+
}
|
|
31
|
+
export interface RateLimitsPayload {
|
|
32
|
+
five_hour?: RateWindow | null;
|
|
33
|
+
seven_day?: RateWindow | null;
|
|
34
|
+
}
|
|
35
|
+
export interface Sample {
|
|
36
|
+
/** epoch ms */
|
|
37
|
+
t: number;
|
|
38
|
+
used: number;
|
|
39
|
+
/** epoch seconds; 창 식별자 */
|
|
40
|
+
resets_at: number | null;
|
|
41
|
+
}
|
|
42
|
+
export declare const SAMPLES_PATH: string;
|
|
43
|
+
export declare const SAMPLE_TTL_MS: number;
|
|
44
|
+
export declare const MIN_SAMPLES = 3;
|
|
45
|
+
/** 창 안 샘플 시간 폭 최소치 — 짧은 폭의 점프 하나가 추세로 둔갑하지 않게. */
|
|
46
|
+
export declare const MIN_SPAN_MS: Record<WindowKey, number>;
|
|
47
|
+
/** 창 안 총 증가가 이보다 작으면(0.1% 양자화 잡음 수준) 예측 숨김. */
|
|
48
|
+
export declare const MIN_RISE_PCT = 1;
|
|
49
|
+
/** 기울기 추정에 쓰는 창 폭. */
|
|
50
|
+
export declare const LOOKBACK_MS: Record<WindowKey, number>;
|
|
51
|
+
/** compactSamples 가드: 이 크기 미만이거나 최근에 쓰인 파일은 재작성하지 않는다(동시 append 유실 방지). */
|
|
52
|
+
export declare const COMPACT_MIN_BYTES: number;
|
|
53
|
+
export declare const COMPACT_QUIET_MS: number;
|
|
54
|
+
export interface Forecast {
|
|
55
|
+
window: WindowKey;
|
|
56
|
+
used: number;
|
|
57
|
+
resetsAt: number | null;
|
|
58
|
+
/** 100% 도달 예상 시각(epoch ms). 근거 부족·기울기 ≤0 이면 null. */
|
|
59
|
+
exhaustAt: number | null;
|
|
60
|
+
/** exhaustAt 이 resets_at 보다 앞이면 true. */
|
|
61
|
+
exhaustsBeforeReset: boolean;
|
|
62
|
+
/** 리셋 시점 예상 사용률(기울기 외삽, 100 상한). 예측 불가면 null. */
|
|
63
|
+
projectedAtReset: number | null;
|
|
64
|
+
/** %/시간. */
|
|
65
|
+
ratePerHour: number | null;
|
|
66
|
+
sampleCount: number;
|
|
67
|
+
}
|
|
68
|
+
interface SampleLine extends Sample {
|
|
69
|
+
w: WindowKey;
|
|
70
|
+
}
|
|
71
|
+
/** payload → 이번 호출 샘플(창별). null/비수치 사용률은 샘플로 만들지 않는다. */
|
|
72
|
+
export declare function samplesFromPayload(rl: RateLimitsPayload | undefined | null, nowMs: number): SampleLine[];
|
|
73
|
+
export declare function appendSamples(lines: SampleLine[], p?: string): void;
|
|
74
|
+
export declare function readSamples(p?: string, nowMs?: number): SampleLine[];
|
|
75
|
+
/**
|
|
76
|
+
* TTL 넘은 줄 제거. read→truncate 재작성은 다른 세션의 동시 append 를 유실시키므로(critic 실측 33%)
|
|
77
|
+
* **크기 ≥ COMPACT_MIN_BYTES 이고 마지막 수정이 COMPACT_QUIET_MS 이전**일 때만 수행한다.
|
|
78
|
+
* 반환: 실제로 압축했는지.
|
|
79
|
+
*/
|
|
80
|
+
export declare function compactSamples(p?: string, nowMs?: number, force?: boolean): boolean;
|
|
81
|
+
/**
|
|
82
|
+
* 같은 창의 샘플 시계열에서 "현재 창"에 속하는 꼬리만 남긴다.
|
|
83
|
+
* 창 경계: resets_at 변화, 사용률 하락. (둘 다 "이전 창의 샘플" 이므로 버린다.)
|
|
84
|
+
*/
|
|
85
|
+
export declare function currentWindowTail(samples: Sample[]): Sample[];
|
|
86
|
+
/**
|
|
87
|
+
* 양끝점 기울기(%/ms) — lookback 창 안 첫/마지막 샘플. 시간 가중이 본질이라 점프 순서·간격에 무관.
|
|
88
|
+
* 숨김: 샘플 < MIN_SAMPLES, 시간 폭 < MIN_SPAN_MS[w], 총 증가 < MIN_RISE_PCT.
|
|
89
|
+
*/
|
|
90
|
+
export declare function estimateRate(tail: Sample[], nowMs: number, lookbackMs: number, w?: WindowKey): {
|
|
91
|
+
rate: number;
|
|
92
|
+
n: number;
|
|
93
|
+
} | null;
|
|
94
|
+
/**
|
|
95
|
+
* @param current 현재 페이로드의 이 창 샘플. **없으면 null 을 돌려 세그먼트를 생략한다** — 파일의
|
|
96
|
+
* 옛 샘플을 현재값처럼 보여주지 않는다(critic SEV-1). resets_at 이 이미 지났어도 숨긴다.
|
|
97
|
+
*/
|
|
98
|
+
export declare function forecastWindow(w: WindowKey, samples: Sample[], nowMs: number, current?: Sample | null): Forecast | null;
|
|
99
|
+
/**
|
|
100
|
+
* 모든 창 예측. `current` 가 주어지면 **그 안에 수치로 존재하는 창만** 출력한다(표시 게이트).
|
|
101
|
+
* 주어지지 않으면(오프라인 분석) 파일 샘플의 마지막을 현재로 간주.
|
|
102
|
+
*/
|
|
103
|
+
export declare function forecastAll(all: SampleLine[], nowMs: number, current?: SampleLine[]): Partial<Record<WindowKey, Forecast>>;
|
|
104
|
+
/** HH:MM (로컬). 하루 넘어가면 "D+1 HH:MM". */
|
|
105
|
+
export declare function fmtClock(epochMs: number, nowMs: number): string;
|
|
106
|
+
/**
|
|
107
|
+
* 한 창의 표시 문자열(색 없음 — 호출자가 입힘).
|
|
108
|
+
* "5h 63% → 15:40 소진 (리셋 16:20)" 리셋 전 소진 예상
|
|
109
|
+
* "5h 63% → 리셋 16:20 여유 (예상 81%)" 리셋까지 안 닿음
|
|
110
|
+
* "5h 63% (리셋 16:20)" 예측 근거 부족 — 사용률만
|
|
111
|
+
*/
|
|
112
|
+
export declare function fmtForecast(f: Forecast, nowMs: number): string;
|
|
113
|
+
export {};
|