@wooojin/forgen 0.5.9 → 0.6.1

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.
Files changed (66) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/CHANGELOG.md +63 -0
  3. package/README.ja.md +12 -0
  4. package/README.ko.md +12 -0
  5. package/README.md +12 -0
  6. package/README.zh.md +12 -0
  7. package/dist/checks/_shared/model-profile.d.ts +1 -1
  8. package/dist/checks/_shared/model-profile.js +9 -5
  9. package/dist/cli.js +32 -3
  10. package/dist/core/auto-compound-runner.js +20 -43
  11. package/dist/core/block-cli.d.ts +1 -0
  12. package/dist/core/block-cli.js +41 -0
  13. package/dist/core/explain-cli.js +29 -1
  14. package/dist/core/inspect-cli.js +9 -8
  15. package/dist/core/rate-limit-forecast.d.ts +113 -0
  16. package/dist/core/rate-limit-forecast.js +236 -0
  17. package/dist/core/state-gc.js +3 -0
  18. package/dist/core/stats-cli.d.ts +15 -0
  19. package/dist/core/stats-cli.js +50 -16
  20. package/dist/core/status-cli.d.ts +18 -1
  21. package/dist/core/status-cli.js +51 -2
  22. package/dist/core/statusline-cli.d.ts +58 -13
  23. package/dist/core/statusline-cli.js +164 -201
  24. package/dist/core/v1-bootstrap.js +7 -1
  25. package/dist/engine/block-judge-cli.d.ts +2 -0
  26. package/dist/engine/block-judge-cli.js +11 -0
  27. package/dist/engine/block-judge.d.ts +68 -0
  28. package/dist/engine/block-judge.js +248 -0
  29. package/dist/engine/correction-cluster-runner.d.ts +67 -0
  30. package/dist/engine/correction-cluster-runner.js +242 -5
  31. package/dist/engine/correction-clustering.d.ts +15 -0
  32. package/dist/engine/correction-clustering.js +24 -0
  33. package/dist/engine/lifecycle/lifecycle-cli.js +7 -4
  34. package/dist/engine/lifecycle/signals.d.ts +59 -2
  35. package/dist/engine/lifecycle/signals.js +193 -4
  36. package/dist/engine/lifecycle/trigger-t3-bypass.d.ts +5 -3
  37. package/dist/engine/lifecycle/trigger-t3-bypass.js +6 -4
  38. package/dist/engine/lifecycle/types.d.ts +29 -1
  39. package/dist/engine/mined-rule-merge-cli.d.ts +11 -0
  40. package/dist/engine/mined-rule-merge-cli.js +67 -0
  41. package/dist/engine/rule-relevance.d.ts +72 -0
  42. package/dist/engine/rule-relevance.js +183 -0
  43. package/dist/engine/rule-toggle-cli.d.ts +5 -0
  44. package/dist/engine/rule-toggle-cli.js +30 -0
  45. package/dist/fgx.js +1 -1
  46. package/dist/forge/evidence-processor.js +2 -0
  47. package/dist/hooks/post-tool-use.js +9 -14
  48. package/dist/hooks/pre-tool-use.js +71 -8
  49. package/dist/hooks/shared/command-parser.d.ts +11 -0
  50. package/dist/hooks/shared/command-parser.js +120 -0
  51. package/dist/hooks/solution-injector.js +13 -0
  52. package/dist/hooks/stop-guard.d.ts +18 -0
  53. package/dist/hooks/stop-guard.js +55 -10
  54. package/dist/mcp/tools.js +7 -1
  55. package/dist/renderer/inspect-renderer.js +23 -6
  56. package/dist/renderer/rule-renderer.js +4 -2
  57. package/dist/store/evidence-store.js +37 -2
  58. package/dist/store/profile-score.d.ts +55 -0
  59. package/dist/store/profile-score.js +100 -0
  60. package/dist/store/profile-store.d.ts +22 -5
  61. package/dist/store/profile-store.js +42 -6
  62. package/dist/store/rule-origin.d.ts +39 -0
  63. package/dist/store/rule-origin.js +84 -0
  64. package/dist/store/types.d.ts +24 -0
  65. package/package.json +1 -1
  66. package/plugin.json +1 -1
@@ -7,7 +7,7 @@
7
7
  import * as path from 'node:path';
8
8
  import { loadAllRules, saveRule } from '../../store/rule-store.js';
9
9
  import { STATE_DIR } from '../../core/paths.js';
10
- import { collectSignals, readJsonlSafe } from './signals.js';
10
+ import { collectSignals, readJsonlSafe, isConfirmedBypass, isSyntheticSession } from './signals.js';
11
11
  import { detect as detectT2 } from './trigger-t2-violation.js';
12
12
  import { detect as detectT3 } from './trigger-t3-bypass.js';
13
13
  import { detect as detectT4 } from './trigger-t4-decay.js';
@@ -24,11 +24,14 @@ export async function handleLifecycleScan(args) {
24
24
  return;
25
25
  }
26
26
  const violations = readJsonlSafe(path.join(STATE_DIR, 'enforcement', 'violations.jsonl'));
27
- const bypass = readJsonlSafe(path.join(STATE_DIR, 'enforcement', 'bypass.jsonl'));
27
+ // ADR-017 D1: bypass.jsonl(자연어 휴리스틱, 전량 오탐)은 더 이상 읽지 않는다. T3 입력은
28
+ // violations 의 kind:'bypass_confirmed'(사용자 명시 우회) 뿐이며 collectSignals 가 거기서 뽑는다.
29
+ const bypassConfirmed = violations.filter(isConfirmedBypass).length;
30
+ const syntheticExcluded = violations.filter((v) => isSyntheticSession(v.session_id)).length;
28
31
  const drift = readDriftEntries();
29
32
  const signals = new Map();
30
33
  for (const r of rules)
31
- signals.set(r.rule_id, collectSignals(r, { violations, bypass, now }));
34
+ signals.set(r.rule_id, collectSignals(r, { violations, now }));
32
35
  const events = [
33
36
  ...detectT2({ rules, signals, ts: now }),
34
37
  ...detectT3({ rules, signals, ts: now }),
@@ -38,7 +41,7 @@ export async function handleLifecycleScan(args) {
38
41
  const demotionCandidates = scanDriftForDemotion({ rules, drift, now });
39
42
  const promotionCandidates = scanSignalsForPromotion({ rules, signals, ts: now });
40
43
  console.log(`\n Lifecycle Scan — ${rules.length} rule(s) (${apply ? 'APPLY' : 'dry-run'})\n`);
41
- console.log(` Signals: violations.jsonl=${violations.length} bypass.jsonl=${bypass.length} drift.jsonl=${drift.length}\n`);
44
+ console.log(` Signals: violations.jsonl=${violations.length} (synthetic-session excluded ${syntheticExcluded}) bypass_confirmed=${bypassConfirmed} drift.jsonl=${drift.length}\n`);
42
45
  if (events.length === 0 && demotionCandidates.length === 0 && promotionCandidates.length === 0) {
43
46
  console.log(' No lifecycle events. System stable.\n');
44
47
  return;
@@ -9,7 +9,13 @@
9
9
  * 모든 IO 는 이 파일에 한정. 트리거들은 pure — collectSignals() 결과를 받아 detect().
10
10
  */
11
11
  import type { Rule } from '../../store/types.js';
12
- import type { RuleSignals, ViolationEntry, BypassEntry } from './types.js';
12
+ /**
13
+ * 영수증·로그용 추가 마스킹 (critic D1 SEV-2): secret-filter 의 공개 키 패턴만으로는 `DB_PASS=…`, mysql -p<값>,
14
+ * sshpass -p, Basic/X-API-Key 헤더, URL userinfo, 무접두 JWT, PEM 본문이 평문으로 남아 Haiku 로 egress 된다.
15
+ * 과잉 마스킹은 영수증 가독성만 깎지만 누락은 유출이므로 넓게 잡는다.
16
+ */
17
+ export declare function redactForReceipt(text: string): string;
18
+ import type { RuleSignals, ViolationEntry, BypassEntry, VerdictEntry, CheckEntry } from './types.js';
13
19
  /**
14
20
  * Best-effort size-based rotation. When `p` exceeds 10MB, renames to
15
21
  * `<p>.<timestamp>` so the next write starts fresh. Missing file or rename
@@ -19,7 +25,58 @@ import type { RuleSignals, ViolationEntry, BypassEntry } from './types.js';
19
25
  */
20
26
  export declare function rotateIfBig(p: string): void;
21
27
  export declare function readJsonlSafe<T>(p: string): T[];
22
- export declare function recordViolation(entry: Omit<ViolationEntry, 'at'>): void;
28
+ /**
29
+ * ADR-017 §2 원칙 2: 훅이 session_id 없이 호출되면 'default'/'unknown' 폴백이 기록된다.
30
+ * 실세션(Claude·Codex 모두 session_id 전달)에서는 나오지 않으며, 실측상 전부 테스트가
31
+ * dist 훅을 spawn 한 흔적이었다(7d 차단 108건 중 78건). 모든 집계에서 제외한다.
32
+ */
33
+ export declare const SYNTHETIC_SESSION_IDS: ReadonlySet<string>;
34
+ export declare function isSyntheticSession(sessionId: unknown): boolean;
35
+ /** 사용자 관점의 "차단": block/deny (+legacy undefined). correction/bypass_confirmed 는 아님. */
36
+ export declare function isBlockKind(kind: unknown): boolean;
37
+ /** 실세션에서 일어난 실제 차단만. stats/explain/lifecycle 이 공유하는 단일 기준. */
38
+ export declare function isRealBlock(e: {
39
+ kind?: unknown;
40
+ session_id?: unknown;
41
+ }): boolean;
42
+ export declare function isConfirmedBypass(e: {
43
+ kind?: unknown;
44
+ session_id?: unknown;
45
+ }): boolean;
46
+ export declare const RECEIPT_TTL_MS: number;
47
+ export declare const MATCHED_MAX = 160;
48
+ export interface RecordViolationOptions {
49
+ /** 영수증 전문(명령/응답/파일 본문). secret-filter 로 마스킹 후 receipts/<id>.txt 에 24h 보관. */
50
+ receipt_text?: string;
51
+ }
52
+ /**
53
+ * 위반/차단 기록. ADR-017 D1: violation_id 를 발급해 반환하고, receipt_text 가 있으면 secret
54
+ * 마스킹 후 전문을 24h TTL 영수증으로 남긴다(로그엔 hash 만). 실패해도 예외 없이 '' 반환.
55
+ */
56
+ export declare function recordViolation(entry: Omit<ViolationEntry, 'at'>, opts?: RecordViolationOptions): string;
57
+ export declare function readReceipt(violationId: string): string | null;
58
+ /** 판정 기록(append-only). 같은 violation_id 에 여러 줄이면 마지막이 유효하되 user > auto. */
59
+ export declare function setVerdict(entry: Omit<VerdictEntry, 'at'>): void;
60
+ export declare function readVerdicts(): VerdictEntry[];
61
+ /** violation_id → 유효 판정 (user 가 있으면 user, 없으면 마지막 auto). */
62
+ export declare function effectiveVerdicts(verdicts?: VerdictEntry[]): Map<string, VerdictEntry>;
63
+ export interface RulePrecision {
64
+ rule_id: string;
65
+ correct: number;
66
+ false_positive: number;
67
+ unjudged: number;
68
+ /** correct/(correct+false_positive); 판정 0건이면 null. */
69
+ precision: number | null;
70
+ }
71
+ /** 룰별 precision (실 차단만, 최근 N일). unsure 는 미판정으로 센다. */
72
+ export declare function precisionByRule(violations: ViolationEntry[], verdicts: VerdictEntry[], days: number, now?: number): Map<string, RulePrecision>;
73
+ /** D2: Stop 평가 결과 기록(통과 포함). violations.jsonl 과 분리. 7일 TTL 은 state-gc 가 담당. */
74
+ export declare const CHECKS_TTL_MS: number;
75
+ export declare function recordCheck(entry: Omit<CheckEntry, 'at'>): void;
76
+ export declare function pruneChecks(now?: number): void;
77
+ export declare function readChecks(): CheckEntry[];
78
+ /** 정규식 매칭 프래그먼트 추출 — 영수증 `matched` 필드용. */
79
+ export declare function matchedFragment(re: RegExp, text: string): string;
23
80
  export declare function recordBypass(entry: Omit<BypassEntry, 'at'>): void;
24
81
  export interface SignalInputs {
25
82
  violations?: ViolationEntry[];
@@ -10,6 +10,25 @@
10
10
  */
11
11
  import * as fs from 'node:fs';
12
12
  import * as path from 'node:path';
13
+ import * as crypto from 'node:crypto';
14
+ import { redactSecrets } from '../../hooks/secret-filter.js'; // ESM main guard 있음 — import 부작용 없음
15
+ /**
16
+ * 영수증·로그용 추가 마스킹 (critic D1 SEV-2): secret-filter 의 공개 키 패턴만으로는 `DB_PASS=…`, mysql -p<값>,
17
+ * sshpass -p, Basic/X-API-Key 헤더, URL userinfo, 무접두 JWT, PEM 본문이 평문으로 남아 Haiku 로 egress 된다.
18
+ * 과잉 마스킹은 영수증 가독성만 깎지만 누락은 유출이므로 넓게 잡는다.
19
+ */
20
+ export function redactForReceipt(text) {
21
+ // PEM 은 secret-filter 보다 먼저 — secret-filter 가 BEGIN 헤더 줄만 치환하면 본문(base64)이 평문으로 남는다.
22
+ let t = text.replace(/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, '[REDACTED:PEM]');
23
+ t = redactSecrets(t).redacted;
24
+ t = t.replace(/\[REDACTED:[^\]]*\][\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, '[REDACTED:PEM]');
25
+ t = t.replace(/\b(eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,})/g, '[REDACTED:JWT]');
26
+ t = t.replace(/(\b[A-Za-z_][A-Za-z0-9_]*(?:pass(?:word|wd)?|pwd|secret|token|api[_-]?key|auth|credential)[A-Za-z0-9_]*\s*[=:]\s*)(["']?)[^\s"'&;]+\2/gi, '$1$2[REDACTED]$2');
27
+ t = t.replace(/((?:mysql|mariadb|mysqldump|sshpass|psql)\b[^\n;|&]*?\s-p)(?!assword)\s*(\S+)/gi, '$1[REDACTED]');
28
+ t = t.replace(/((?:Authorization|X-API-Key|X-Auth-Token|Proxy-Authorization)\s*:\s*)(?:Basic|Bearer|Token)?\s*\S+/gi, '$1[REDACTED]');
29
+ t = t.replace(/(:\/\/[^\s/:@]+:)[^\s/@]+(@)/g, '$1[REDACTED]$2');
30
+ return t;
31
+ }
13
32
  import { STATE_DIR as FORGEN_STATE_DIR } from '../../core/paths.js';
14
33
  const ENFORCEMENT_DIR = path.join(FORGEN_STATE_DIR, 'enforcement');
15
34
  const VIOLATIONS_PATH = path.join(ENFORCEMENT_DIR, 'violations.jsonl');
@@ -57,18 +76,181 @@ export function readJsonlSafe(p) {
57
76
  return [];
58
77
  }
59
78
  }
60
- export function recordViolation(entry) {
79
+ /**
80
+ * ADR-017 §2 원칙 2: 훅이 session_id 없이 호출되면 'default'/'unknown' 폴백이 기록된다.
81
+ * 실세션(Claude·Codex 모두 session_id 전달)에서는 나오지 않으며, 실측상 전부 테스트가
82
+ * dist 훅을 spawn 한 흔적이었다(7d 차단 108건 중 78건). 모든 집계에서 제외한다.
83
+ */
84
+ export const SYNTHETIC_SESSION_IDS = new Set(['default', 'unknown', '']);
85
+ export function isSyntheticSession(sessionId) {
86
+ return typeof sessionId !== 'string' || SYNTHETIC_SESSION_IDS.has(sessionId);
87
+ }
88
+ /** 사용자 관점의 "차단": block/deny (+legacy undefined). correction/bypass_confirmed 는 아님. */
89
+ export function isBlockKind(kind) {
90
+ return kind === 'block' || kind === 'deny' || kind === undefined;
91
+ }
92
+ /** 실세션에서 일어난 실제 차단만. stats/explain/lifecycle 이 공유하는 단일 기준. */
93
+ export function isRealBlock(e) {
94
+ return isBlockKind(e.kind) && !isSyntheticSession(e.session_id);
95
+ }
96
+ export function isConfirmedBypass(e) {
97
+ return e.kind === 'bypass_confirmed' && !isSyntheticSession(e.session_id);
98
+ }
99
+ const RECEIPTS_DIR = path.join(ENFORCEMENT_DIR, 'receipts');
100
+ const VERDICTS_PATH = path.join(ENFORCEMENT_DIR, 'verdicts.jsonl');
101
+ const CHECKS_PATH = path.join(ENFORCEMENT_DIR, 'checks.jsonl');
102
+ export const RECEIPT_TTL_MS = 24 * 3600 * 1000;
103
+ export const MATCHED_MAX = 160;
104
+ function sha16(text) {
105
+ return crypto.createHash('sha256').update(text).digest('hex').slice(0, 16);
106
+ }
107
+ /** receipts/ 의 TTL 지난 파일 정리 — 기록 시마다 best-effort(최대 200개 확인). */
108
+ function pruneReceipts(now) {
109
+ try {
110
+ if (!fs.existsSync(RECEIPTS_DIR))
111
+ return;
112
+ const names = fs.readdirSync(RECEIPTS_DIR).slice(0, 200);
113
+ for (const n of names) {
114
+ const p = path.join(RECEIPTS_DIR, n);
115
+ try {
116
+ if (now - fs.statSync(p).mtimeMs > RECEIPT_TTL_MS)
117
+ fs.unlinkSync(p);
118
+ }
119
+ catch { /* skip */ }
120
+ }
121
+ }
122
+ catch { /* skip */ }
123
+ }
124
+ /**
125
+ * 위반/차단 기록. ADR-017 D1: violation_id 를 발급해 반환하고, receipt_text 가 있으면 secret
126
+ * 마스킹 후 전문을 24h TTL 영수증으로 남긴다(로그엔 hash 만). 실패해도 예외 없이 '' 반환.
127
+ */
128
+ export function recordViolation(entry, opts = {}) {
61
129
  try {
62
130
  fs.mkdirSync(ENFORCEMENT_DIR, { recursive: true });
63
131
  rotateIfBig(VIOLATIONS_PATH);
64
- const full = { at: new Date().toISOString(), ...entry };
132
+ const violation_id = entry.violation_id ?? crypto.randomUUID();
133
+ const full = { at: new Date().toISOString(), violation_id, ...entry };
134
+ // 로그에 남는 프래그먼트/미리보기도 secret 마스킹 — 영수증만 가리고 로그에 키가 남으면 의미 없다.
135
+ if (typeof full.matched === 'string')
136
+ full.matched = redactForReceipt(full.matched);
137
+ if (typeof full.message_preview === 'string')
138
+ full.message_preview = redactForReceipt(full.message_preview);
139
+ if (typeof full.matched === 'string' && full.matched.length > MATCHED_MAX)
140
+ full.matched = `${full.matched.slice(0, MATCHED_MAX - 1)}…`;
141
+ if (opts.receipt_text) {
142
+ full.target_hash = sha16(opts.receipt_text);
143
+ try {
144
+ fs.mkdirSync(RECEIPTS_DIR, { recursive: true, mode: 0o700 });
145
+ fs.writeFileSync(path.join(RECEIPTS_DIR, `${violation_id}.txt`), redactForReceipt(opts.receipt_text), { mode: 0o600 });
146
+ pruneReceipts(Date.now());
147
+ }
148
+ catch { /* 영수증 실패는 기록 자체를 막지 않는다 */ }
149
+ }
65
150
  fs.appendFileSync(VIOLATIONS_PATH, `${JSON.stringify(full)}\n`);
151
+ return violation_id;
66
152
  }
67
153
  catch (e) {
68
154
  // best-effort, 실패 시 debug 로그 (silent swallow 방지)
69
155
  if (process.env.FORGEN_DEBUG_SIGNALS === '1') {
70
156
  console.error(`[forgen:signals] recordViolation failed: ${e.message}`);
71
157
  }
158
+ return '';
159
+ }
160
+ }
161
+ export function readReceipt(violationId) {
162
+ if (!/^[A-Za-z0-9-]+$/.test(violationId))
163
+ return null;
164
+ try {
165
+ return fs.readFileSync(path.join(RECEIPTS_DIR, `${violationId}.txt`), 'utf-8');
166
+ }
167
+ catch {
168
+ return null;
169
+ }
170
+ }
171
+ /** 판정 기록(append-only). 같은 violation_id 에 여러 줄이면 마지막이 유효하되 user > auto. */
172
+ export function setVerdict(entry) {
173
+ try {
174
+ fs.mkdirSync(ENFORCEMENT_DIR, { recursive: true });
175
+ rotateIfBig(VERDICTS_PATH);
176
+ fs.appendFileSync(VERDICTS_PATH, `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`);
177
+ }
178
+ catch { /* best-effort */ }
179
+ }
180
+ export function readVerdicts() {
181
+ return readJsonlSafe(VERDICTS_PATH);
182
+ }
183
+ /** violation_id → 유효 판정 (user 가 있으면 user, 없으면 마지막 auto). */
184
+ export function effectiveVerdicts(verdicts = readVerdicts()) {
185
+ const m = new Map();
186
+ for (const v of verdicts) {
187
+ const cur = m.get(v.violation_id);
188
+ if (cur?.by !== 'user' || v.by === 'user')
189
+ m.set(v.violation_id, v);
190
+ }
191
+ return m;
192
+ }
193
+ /** 룰별 precision (실 차단만, 최근 N일). unsure 는 미판정으로 센다. */
194
+ export function precisionByRule(violations, verdicts, days, now = Date.now()) {
195
+ const cutoff = now - days * 24 * 3600 * 1000;
196
+ const eff = effectiveVerdicts(verdicts);
197
+ const out = new Map();
198
+ for (const v of violations) {
199
+ if (!isRealBlock(v))
200
+ continue;
201
+ const t = Date.parse(v.at);
202
+ if (!Number.isFinite(t) || t < cutoff)
203
+ continue;
204
+ const r = out.get(v.rule_id) ?? { rule_id: v.rule_id, correct: 0, false_positive: 0, unjudged: 0, precision: null };
205
+ const verdict = v.violation_id ? eff.get(v.violation_id)?.verdict : undefined;
206
+ if (verdict === 'correct')
207
+ r.correct++;
208
+ else if (verdict === 'false_positive')
209
+ r.false_positive++;
210
+ else
211
+ r.unjudged++;
212
+ out.set(v.rule_id, r);
213
+ }
214
+ for (const r of out.values()) {
215
+ const judged = r.correct + r.false_positive;
216
+ r.precision = judged > 0 ? r.correct / judged : null;
217
+ }
218
+ return out;
219
+ }
220
+ /** D2: Stop 평가 결과 기록(통과 포함). violations.jsonl 과 분리. 7일 TTL 은 state-gc 가 담당. */
221
+ export const CHECKS_TTL_MS = 7 * 24 * 3600 * 1000;
222
+ export function recordCheck(entry) {
223
+ try {
224
+ fs.mkdirSync(ENFORCEMENT_DIR, { recursive: true });
225
+ rotateIfBig(CHECKS_PATH);
226
+ fs.appendFileSync(CHECKS_PATH, `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`);
227
+ // 7일 TTL — 통과 기록은 턴마다 쌓이므로 1/50 확률로 압축(rotateIfBig 10MB 에 닿지 않게).
228
+ if (Math.random() < 0.02)
229
+ pruneChecks();
230
+ }
231
+ catch { /* best-effort */ }
232
+ }
233
+ export function pruneChecks(now = Date.now()) {
234
+ try {
235
+ const keep = readJsonlSafe(CHECKS_PATH).filter((c) => now - Date.parse(c.at) < CHECKS_TTL_MS);
236
+ fs.writeFileSync(CHECKS_PATH, keep.map((c) => JSON.stringify(c)).join('\n') + (keep.length ? '\n' : ''));
237
+ }
238
+ catch { /* best-effort */ }
239
+ }
240
+ export function readChecks() {
241
+ return readJsonlSafe(CHECKS_PATH);
242
+ }
243
+ /** 정규식 매칭 프래그먼트 추출 — 영수증 `matched` 필드용. */
244
+ export function matchedFragment(re, text) {
245
+ try {
246
+ const m = re.exec(text);
247
+ if (!m)
248
+ return '';
249
+ const start = Math.max(0, m.index - 30);
250
+ return text.slice(start, m.index + m[0].length + 30).replace(/\s+/g, ' ').trim();
251
+ }
252
+ catch {
253
+ return '';
72
254
  }
73
255
  }
74
256
  export function recordBypass(entry) {
@@ -86,8 +268,15 @@ export function recordBypass(entry) {
86
268
  }
87
269
  export function collectSignals(rule, inputs = {}) {
88
270
  const now = inputs.now ?? Date.now();
89
- const violations = inputs.violations ?? readJsonlSafe(VIOLATIONS_PATH);
90
- const bypass = inputs.bypass ?? readJsonlSafe(BYPASS_PATH);
271
+ const allViolations = inputs.violations ?? readJsonlSafe(VIOLATIONS_PATH);
272
+ // ADR-017 D1/D2: T2 는 실제 차단만 센다 — 이전엔 kind 필터가 없어 메타가드 advise(correction)
273
+ // 와 테스트 유래(default 세션) 기록이 위반으로 집계돼 flag 를 조기 발화시켰다.
274
+ const violations = allViolations.filter(isRealBlock);
275
+ // T3 입력은 bypass.jsonl(자연어 휴리스틱 — 실측 100% 오탐, ADR-017 §1.1)이 아니라
276
+ // 사용자 명시 우회(kind:'bypass_confirmed')다. `inputs.bypass` 는 하위 호환으로 남기되 읽지 않는다.
277
+ const bypass = allViolations
278
+ .filter(isConfirmedBypass)
279
+ .map((v) => ({ at: v.at, rule_id: v.rule_id, session_id: v.session_id, tool: v.source, pattern_preview: v.message_preview ?? '' }));
91
280
  // exact match only — M fix: startsWith 으로 prefix 교차 오염되던 부분 제거.
92
281
  const matchesRule = (ruleId) => ruleId === rule.rule_id;
93
282
  const vCutoff30 = now - VIOLATION_WINDOW_DAYS * 24 * 3600 * 1000;
@@ -1,10 +1,12 @@
1
1
  /**
2
2
  * T3 — 사용자 반복 우회 (user_bypass).
3
3
  *
4
- * 트리거 조건 (ADR-002):
5
- * 7d 내 bypass_count ≥ 5 → suppress (일시 비활성 + 7일 후 자동 재활성)
4
+ * 트리거 조건 (ADR-002, R6-P1 로 suppress→flag 약화):
5
+ * 7d 내 bypass_7d ≥ 5 → flag (사용자 주의 환기)
6
6
  *
7
- * bypass 기록은 post-tool-use 측 확장이 bypass.jsonl 에 append (별도 wiring).
7
+ * 입력 (ADR-017 D1, 2026-10-06): bypass_7d 는 violations.jsonl 의 kind:'bypass_confirmed'
8
+ * (FORGEN_USER_CONFIRMED=1 명시 우회) 만 센다. 과거 bypass.jsonl 자연어 휴리스틱(전량 오탐)은 폐기.
9
+ * 의미: "사용자가 같은 룰을 7일에 5번 명시적으로 우회했다 → 룰이 틀렸을 가능성, 검토 요청".
8
10
  */
9
11
  import type { Rule } from '../../store/types.js';
10
12
  import type { LifecycleEvent, RuleSignals } from './types.js';
@@ -1,10 +1,12 @@
1
1
  /**
2
2
  * T3 — 사용자 반복 우회 (user_bypass).
3
3
  *
4
- * 트리거 조건 (ADR-002):
5
- * 7d 내 bypass_count ≥ 5 → suppress (일시 비활성 + 7일 후 자동 재활성)
4
+ * 트리거 조건 (ADR-002, R6-P1 로 suppress→flag 약화):
5
+ * 7d 내 bypass_7d ≥ 5 → flag (사용자 주의 환기)
6
6
  *
7
- * bypass 기록은 post-tool-use 측 확장이 bypass.jsonl 에 append (별도 wiring).
7
+ * 입력 (ADR-017 D1, 2026-10-06): bypass_7d 는 violations.jsonl 의 kind:'bypass_confirmed'
8
+ * (FORGEN_USER_CONFIRMED=1 명시 우회) 만 센다. 과거 bypass.jsonl 자연어 휴리스틱(전량 오탐)은 폐기.
9
+ * 의미: "사용자가 같은 룰을 7일에 5번 명시적으로 우회했다 → 룰이 틀렸을 가능성, 검토 요청".
8
10
  */
9
11
  export function detect(input) {
10
12
  const threshold = input.threshold_count ?? 5;
@@ -27,7 +29,7 @@ export function detect(input) {
27
29
  kind: 't3_user_bypass',
28
30
  rule_id: rule.rule_id,
29
31
  evidence: {
30
- source: 'bypass-log',
32
+ source: 'violations:bypass_confirmed',
31
33
  refs: [],
32
34
  metrics: { bypass_7d: s.bypass_7d },
33
35
  },
@@ -40,8 +40,36 @@ export interface ViolationEntry {
40
40
  rule_id: string;
41
41
  session_id: string;
42
42
  source: 'stop-guard' | 'subagent-stop-guard' | 'pre-tool-guard' | 'post-tool-guard' | 'evidence-store' | 'manual';
43
- kind: 'block' | 'deny' | 'correction';
43
+ /**
44
+ * block/deny = 실제 차단. correction = 메타가드 advise(기록만). bypass_confirmed = 사용자가
45
+ * FORGEN_USER_CONFIRMED=1 로 명시 우회(ADR-017 D1 — T3 의 유일한 입력).
46
+ */
47
+ kind: 'block' | 'deny' | 'correction' | 'bypass_confirmed';
44
48
  message_preview?: string;
49
+ /** 영수증 식별자. `forgen block <id> --ok|--fp` 와 verdicts.jsonl 조인 키. */
50
+ violation_id?: string;
51
+ /** 어느 패턴/프래그먼트가 매칭됐는가 (최대 160자). */
52
+ matched?: string;
53
+ target_kind?: 'command' | 'response' | 'file';
54
+ /** 전문 sha256 앞 16자 — 전문은 receipts/<id>.txt 에 24h TTL 로만 보관. */
55
+ target_hash?: string;
56
+ }
57
+ export type Verdict = 'correct' | 'false_positive' | 'unsure';
58
+ export interface VerdictEntry {
59
+ at: string;
60
+ violation_id: string;
61
+ rule_id: string;
62
+ verdict: Verdict;
63
+ /** 사람 > 모델. user 판정은 auto 를 덮어쓴다. */
64
+ by: 'auto' | 'user';
65
+ reason?: string;
66
+ }
67
+ /** D2: Stop 에서 실제 평가된 룰의 결과 (통과/위반). violations.jsonl 과 분리 — T2·explain 오염 방지. */
68
+ export interface CheckEntry {
69
+ at: string;
70
+ session_id: string;
71
+ rule_id: string;
72
+ result: 'pass' | 'violation';
45
73
  }
46
74
  export interface BypassEntry {
47
75
  at: string;
@@ -0,0 +1,11 @@
1
+ /**
2
+ * CLI handler for `forgen rule merge-mined [--apply]` (ADR-017 D3).
3
+ *
4
+ * 채굴(behavior_inference, `auto:`) 룰을 채굴끼리만 병합하고, explicit 룰과 같은 개념인
5
+ * 채굴 룰은 explicit 에 *링크*만 건다(흡수 금지 — ADR-013 불변식). 기본은 dry-run:
6
+ * "채굴 N → M (병합 K, explicit 링크 L)" 과 각 클러스터의 멤버·대표 policy 를 출력한다.
7
+ * `--apply` 로 적용. 되돌리기는 `forgen rule unmerge <id>`.
8
+ */
9
+ import { type MinedMergePlan } from './correction-cluster-runner.js';
10
+ export declare function renderMinedMergePlan(plan: MinedMergePlan): string;
11
+ export declare function handleMergeMined(args: string[]): Promise<void>;
@@ -0,0 +1,67 @@
1
+ /**
2
+ * CLI handler for `forgen rule merge-mined [--apply]` (ADR-017 D3).
3
+ *
4
+ * 채굴(behavior_inference, `auto:`) 룰을 채굴끼리만 병합하고, explicit 룰과 같은 개념인
5
+ * 채굴 룰은 explicit 에 *링크*만 건다(흡수 금지 — ADR-013 불변식). 기본은 dry-run:
6
+ * "채굴 N → M (병합 K, explicit 링크 L)" 과 각 클러스터의 멤버·대표 policy 를 출력한다.
7
+ * `--apply` 로 적용. 되돌리기는 `forgen rule unmerge <id>`.
8
+ */
9
+ import { runMinedRuleMerge } from './correction-cluster-runner.js';
10
+ const POLICY_PREVIEW = 70;
11
+ function preview(policy) {
12
+ const one = policy.replace(/\s+/g, ' ').trim();
13
+ return one.length > POLICY_PREVIEW ? `${one.slice(0, POLICY_PREVIEW)}…` : one;
14
+ }
15
+ function short(id) {
16
+ return id.slice(0, 8);
17
+ }
18
+ export function renderMinedMergePlan(plan) {
19
+ const mergedCount = plan.clusters.reduce((n, c) => n + c.memberIds.length, 0);
20
+ const lines = [];
21
+ lines.push(`채굴 ${plan.totalMined} → ${plan.projectedMined} (병합 ${mergedCount}, explicit 링크 ${plan.explicitLinks.length})`);
22
+ if (plan.explicitLinks.length > 0) {
23
+ lines.push('');
24
+ lines.push(`[explicit 링크 ${plan.explicitLinks.length}] — 채굴 룰은 숨김, explicit 은 "채굴 관측 N회" 만 증가`);
25
+ for (const l of plan.explicitLinks) {
26
+ lines.push(` ${short(l.minedRuleId)} (유사도 ${l.similarity.toFixed(2)}, 관측 ${l.observations}) → ${short(l.explicitRuleId)}`);
27
+ lines.push(` 채굴: ${preview(l.minedPolicy)}`);
28
+ lines.push(` explicit: ${preview(l.explicitPolicy)}`);
29
+ }
30
+ }
31
+ plan.clusters.forEach((c, i) => {
32
+ lines.push('');
33
+ const absorb = c.absorberId ? ` (기존 통합 룰 ${short(c.absorberId)} 에 흡수)` : '';
34
+ lines.push(`[클러스터 ${i + 1}] ${c.category} · 멤버 ${c.memberIds.length} · created_at ${c.oldestCreatedAt.slice(0, 10)} 기준${absorb}`);
35
+ lines.push(` 대표: ${preview(c.representativePolicy)}`);
36
+ c.memberIds.forEach((id, j) => {
37
+ lines.push(` - ${short(id)} ${preview(c.memberPolicies[j] ?? '')}`);
38
+ });
39
+ });
40
+ if (plan.explicitLinks.length === 0 && plan.clusters.length === 0) {
41
+ lines.push('');
42
+ lines.push('병합/링크 대상 없음.');
43
+ }
44
+ return lines.join('\n');
45
+ }
46
+ export async function handleMergeMined(args) {
47
+ const apply = args.includes('--apply');
48
+ const unknown = args.filter((a) => a !== '--apply');
49
+ if (unknown.length > 0) {
50
+ console.error(`Usage: forgen rule merge-mined [--apply] (unknown: ${unknown.join(' ')})`);
51
+ process.exit(2);
52
+ }
53
+ const { plan, applied } = await runMinedRuleMerge({ apply });
54
+ console.log(renderMinedMergePlan(plan));
55
+ if (!applied) {
56
+ if (plan.explicitLinks.length > 0 || plan.clusters.length > 0) {
57
+ console.log('');
58
+ console.log('(dry-run) 적용하려면: forgen rule merge-mined --apply');
59
+ }
60
+ return;
61
+ }
62
+ console.log('');
63
+ console.log(`✓ 적용 — explicit 링크 ${applied.linked}, 신규 통합 룰 ${applied.mergedRuleIds.length}, superseded 원본 ${applied.supersededIds.length}`);
64
+ for (const id of applied.mergedRuleIds)
65
+ console.log(` 통합 룰: ${id}`);
66
+ console.log(' 되돌리기: forgen rule unmerge <통합 룰 id | explicit 룰 id>');
67
+ }
@@ -0,0 +1,72 @@
1
+ /**
2
+ * Rule relevance — "이번 턴에 어떤 룰이 관련 있는가" (ADR-017 D2, 턴 단위 룰 관련도)
3
+ *
4
+ * UserPromptSubmit 에서 프롬프트를 활성 룰의 `trigger`/`policy` 용어와 매칭해
5
+ * `state/turn-rules-<session>.json` 에 기록한다. statusline 이 이 파일을 읽어 "관련 룰 N" 을 보여주고
6
+ * `forgen status --turn` 이 각 룰의 원 교정(날짜·종류·사용자 발화)을 함께 보여준다.
7
+ *
8
+ * 정직성 원칙:
9
+ * - "관련" 이지 "적용" 이 아니다. 모델이 룰을 따랐는지는 여기서 알 수 없다(ADR-017 §5 — 인용 태그는 보류).
10
+ * - 프롬프트 원문은 저장하지 않는다. sha256 앞 16자만 남긴다(어느 프롬프트의 결과인지 대조용).
11
+ * - 프롬프트 주입에는 아무것도 보태지 않는다 — 토큰 비용 0.
12
+ *
13
+ * 매칭 (solution-matcher 와 같은 term 매칭 재사용):
14
+ * - 룰 용어: `extractTags`(solution-format) 를 trigger + policy 의 8단어 창마다 돌려 합친다. extractTags 는
15
+ * 빈도순 8개 cap 이 있어 긴 policy 를 통째로 넣으면 핵심 명사가 잘린다 — 8단어 창이면 cap 이 안 걸린다.
16
+ * - 프롬프트 매칭: `classifyMatch`(term-matcher) 를 **전체 룰 용어 합집합에 대해 한 번** 호출한다 —
17
+ * 프롬프트 NFC 정규화·한글 stem Set 계산이 룰 수와 무관하게 1회. 영문은 단어 경계, 한글은 조사 제거 후 비교.
18
+ * - 공통어 제외: term-matcher NEGATIVE_TERM_BLOCKLIST(코드/파일/테스트 …) + scoring-algorithms COMMON_TAGS
19
+ * (수정/추가/함수 …) + 룰 문장에 흔한 메타어(RULE_COMMON_TERMS: 사용자/작업/먼저/금지 …).
20
+ *
21
+ * 임계 (보수적 — 거짓 양성이 신뢰를 깎는다):
22
+ * 용어마다 가중치: 식별자급 1.0, 일반 0.5. 합 ≥ 1.0 이면 관련.
23
+ * 즉 **일반 용어 2개 이상, 또는 식별자급 용어 1개**.
24
+ * 식별자급 = 영문/숫자 6자 이상(`statusline`, `codex-cli`) 또는 한글 3음절 이상(`한국어`, `에이전트`, `리서치`).
25
+ * 한글은 음절당 정보량이 라틴 문자의 약 2배라 3음절을 영문 6자에 대응시켰다 — 2음절어(설계·검증·병렬)는
26
+ * 단독으로는 잡지 않는다. ("한국어로 답해" 가 '사용자 응답 언어' 룰을 잡아야 한다는 ADR-017 §검증 기준.)
27
+ *
28
+ * 비용: 룰 100개 × 프롬프트 1개 5ms 이내(테스트로 고정). 프롬프트는 앞 32KB 만 본다.
29
+ */
30
+ import type { Rule } from '../store/types.js';
31
+ export interface RuleRelevance {
32
+ rule_id: string;
33
+ /** 매칭 용어 가중치 합(식별자급 1.0 · 일반 0.5). 임계 RELEVANCE_THRESHOLD 이상만 반환. */
34
+ score: number;
35
+ matchedTerms: string[];
36
+ }
37
+ export interface TurnRulesFile {
38
+ at: string;
39
+ session_id: string;
40
+ /** sha256(prompt) 앞 16자 — 원문 저장 금지. */
41
+ prompt_hash: string;
42
+ rules: RuleRelevance[];
43
+ }
44
+ export declare const RELEVANCE_THRESHOLD = 1;
45
+ export declare const PROMPT_HASH_LENGTH = 16;
46
+ /**
47
+ * 룰 문장에 흔히 등장하지만 "이 턴과 관련" 의 근거가 못 되는 메타어.
48
+ * NEGATIVE_TERM_BLOCKLIST(코드/파일/테스트/에러) · COMMON_TAGS(수정/추가/함수) 와 합쳐 제외한다.
49
+ */
50
+ export declare const RULE_COMMON_TERMS: Set<string>;
51
+ /** 영문/숫자 6자 이상 또는 한글 3음절 이상 — 단독으로도 관련 근거가 되는 용어. */
52
+ export declare function isSpecificTerm(term: string): boolean;
53
+ /**
54
+ * 룰 한 개의 매칭 용어. trigger + policy 를 8단어 창으로 extractTags 해 합친다(손실 없음).
55
+ * 반환은 중복 제거·필터(길이/블록리스트/공통어) 완료 상태.
56
+ */
57
+ export declare function ruleTerms(rule: Pick<Rule, 'trigger' | 'policy'>): string[];
58
+ /**
59
+ * 프롬프트와 관련된 룰. 순수 함수 — IO 없음. 임계 이상만, score 내림차순(동점은 rule_id 순).
60
+ */
61
+ export declare function relevantRules(prompt: string, rules: readonly Rule[]): RuleRelevance[];
62
+ export declare function promptHash(prompt: string): string;
63
+ export declare function turnRulesPath(sessionId: string): string;
64
+ /** 덮어쓰기(세션당 최신 턴 하나). 디렉터리 0700 · 파일 0600 — 다른 세션 캐시와 같은 정책. */
65
+ export declare function writeTurnRules(sessionId: string, prompt: string, rules: RuleRelevance[]): TurnRulesFile;
66
+ /** 부재·손상이면 null (fail-open). */
67
+ export declare function readTurnRules(sessionId: string): TurnRulesFile | null;
68
+ /**
69
+ * `forgen status --turn` 의 세션 결정: 지정 세션의 파일이 있으면 그것, 없으면 가장 최근 turn-rules 파일.
70
+ * 반환은 원래 session_id 가 아니라 파일명에서 복원한 sanitized id — 읽기에는 충분하다.
71
+ */
72
+ export declare function resolveTurnRulesSession(preferred?: string): string | null;