@wooojin/forgen 0.6.5 → 0.6.6

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 (49) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/CHANGELOG.md +26 -0
  3. package/README.ja.md +1 -1
  4. package/README.ko.md +1 -1
  5. package/README.md +1 -1
  6. package/README.zh.md +1 -1
  7. package/dist/cli.js +2 -2
  8. package/dist/core/block-cli.js +2 -4
  9. package/dist/core/dashboard.js +1 -1
  10. package/dist/core/explain-cli.js +3 -28
  11. package/dist/core/rate-limit-forecast.js +7 -1
  12. package/dist/core/state-gc.d.ts +14 -0
  13. package/dist/core/state-gc.js +47 -4
  14. package/dist/core/stats-cli.js +5 -5
  15. package/dist/core/statusline-cli.d.ts +24 -2
  16. package/dist/core/statusline-cli.js +125 -23
  17. package/dist/core/statusline-install.d.ts +8 -1
  18. package/dist/core/statusline-install.js +34 -3
  19. package/dist/engine/block-judge.js +4 -5
  20. package/dist/engine/context-signals.d.ts +20 -0
  21. package/dist/engine/context-signals.js +102 -0
  22. package/dist/engine/correction-cluster-runner.d.ts +3 -3
  23. package/dist/engine/correction-cluster-runner.js +48 -12
  24. package/dist/engine/correction-clustering.d.ts +27 -0
  25. package/dist/engine/correction-clustering.js +79 -3
  26. package/dist/engine/ko-colloquial.d.ts +13 -0
  27. package/dist/engine/ko-colloquial.js +45 -0
  28. package/dist/engine/lifecycle/lifecycle-cli.js +25 -5
  29. package/dist/engine/lifecycle/meta-reclassifier.d.ts +1 -0
  30. package/dist/engine/lifecycle/meta-reclassifier.js +3 -21
  31. package/dist/engine/lifecycle/rotated-logs.d.ts +18 -0
  32. package/dist/engine/lifecycle/rotated-logs.js +67 -0
  33. package/dist/engine/lifecycle/signals.d.ts +27 -1
  34. package/dist/engine/lifecycle/signals.js +55 -32
  35. package/dist/engine/lifecycle/types.d.ts +5 -0
  36. package/dist/engine/match-eval-log.d.ts +2 -0
  37. package/dist/engine/match-eval-log.js +1 -0
  38. package/dist/engine/ranking-pipeline.d.ts +9 -1
  39. package/dist/engine/ranking-pipeline.js +24 -2
  40. package/dist/engine/solution-format.d.ts +2 -0
  41. package/dist/engine/solution-format.js +6 -2
  42. package/dist/engine/solution-matcher.d.ts +5 -1
  43. package/dist/engine/solution-matcher.js +4 -2
  44. package/dist/hooks/solution-injector.js +7 -2
  45. package/dist/store/rule-store.d.ts +10 -0
  46. package/dist/store/rule-store.js +26 -2
  47. package/package.json +1 -1
  48. package/plugin.json +1 -1
  49. package/scripts/postinstall.js +6 -2
@@ -1,5 +1,5 @@
1
1
  /**
2
- * forgen statusline install [--force] — ~/.claude/settings.json 의 statusLine 을 forgen 으로 (ADR-017 후속, 2026-10-07)
2
+ * forgen statusline install [--force|--chain] — ~/.claude/settings.json 의 statusLine 을 forgen 으로 (ADR-017 후속, 2026-10-07)
3
3
  *
4
4
  * 왜 따로 있나: 오너 실측 — 다른 머신에서 statusLine 이 claude-hud 로 잡혀 있어 forgen statusline 이 한 번도 실행되지 않았고,
5
5
  * `forgen install claude` 는 사용자 커스텀 statusLine 을 건드리지 않게 돼 있어 손으로 settings.json 을 고쳐야 했다.
@@ -8,6 +8,7 @@
8
8
  * 정책:
9
9
  * - statusLine 이 없거나 forgen 소유(`forgen …` / `…/dist/cli.js statusline`)면 → 현재 패키지의 절대 경로로 갱신.
10
10
  * - 커스텀(claude-hud 등)이면 → 기본은 건드리지 않고 안내만. `--force` 면 `statusLine_backup` 에 보관 후 교체.
11
+ * - `--chain`: 커스텀을 `forgen statusline --after '<원본>'` 으로 감싸 원본 출력 뒤에 forgen 데이터 줄만 덧붙인다(원본은 statusLine_backup).
11
12
  * - 켜져 있는 세션도 settings.json 의 statusLine.command 변경은 즉시 반영된다(Claude Code 가 감시).
12
13
  */
13
14
  import * as fs from 'node:fs';
@@ -24,6 +25,18 @@ export function isForgenStatusline(command) {
24
25
  return true; // 없음 = forgen 이 가져가도 됨
25
26
  return /^forgen(\s|$)/.test(command.trim()) || /[\\/]dist[\\/]cli\.js"?\s+statusline(\s|$)/.test(command);
26
27
  }
28
+ /** POSIX 단일 인용 — 내부 `'` 는 `'\''` 로. `$(…)`·`"`·`\` 도 리터럴로 보존된다. */
29
+ export function shQuote(s) {
30
+ return `'${s.replace(/'/g, `'\\''`)}'`;
31
+ }
32
+ /** 원본 statusLine 명령을 `--after` 로 감싼 forgen 체인 명령. */
33
+ export function forgenChainCommand(original) {
34
+ return `${forgenStatuslineCommand()} --after ${shQuote(original)}`;
35
+ }
36
+ const CHAIN_RE = /\sstatusline\s+--after\s/;
37
+ export function isChainedStatusline(command) {
38
+ return typeof command === 'string' && /[\\/]cli\.js"?\s+statusline\s+--after\s/.test(command);
39
+ }
27
40
  export function installStatusline(opts = {}) {
28
41
  const settingsPath = opts.settingsPath ?? path.join(CLAUDE_DIR, 'settings.json');
29
42
  const command = forgenStatuslineCommand();
@@ -37,12 +50,27 @@ export function installStatusline(opts = {}) {
37
50
  }
38
51
  const existing = settings.statusLine;
39
52
  const previous = existing?.command;
53
+ if (isChainedStatusline(previous) && !(opts.force && !opts.chain)) {
54
+ // 이미 체인 — chain 요청이면 no-op, 일반 install 이면 체인을 풀지 않고 forgen 경로만 갱신(--after 보존).
55
+ const prev = previous;
56
+ const next = `${command}${prev.slice(prev.search(CHAIN_RE) + ' statusline'.length)}`;
57
+ if (opts.chain || prev === next)
58
+ return { status: 'unchanged', command: prev, previous, message: '이미 체인 모드입니다(forgen statusline --after …). 변경 없음.' };
59
+ settings.statusLine = { type: 'command', command: next };
60
+ return writeSettings(settingsPath, settings, next, previous, false);
61
+ }
40
62
  if (previous === command)
41
63
  return { status: 'unchanged', command, previous, message: '이미 forgen statusline(절대 경로)입니다.' };
64
+ if (!isForgenStatusline(previous) && opts.chain) {
65
+ const chained = forgenChainCommand(previous);
66
+ settings.statusLine_backup = previous;
67
+ settings.statusLine = { type: 'command', command: chained };
68
+ return writeSettings(settingsPath, settings, chained, previous, true);
69
+ }
42
70
  if (!isForgenStatusline(previous) && !opts.force) {
43
71
  return {
44
72
  status: 'skipped_custom', command, previous,
45
- message: `statusLine 이 다른 명령으로 설정돼 있어 건드리지 않았습니다: ${String(previous).slice(0, 80)}\n forgen 으로 바꾸려면: forgen statusline install --force (기존 값은 settings.json 의 statusLine_backup 에 보관)`,
73
+ message: `statusLine 이 다른 명령으로 설정돼 있어 건드리지 않았습니다: ${String(previous).slice(0, 80)}\n forgen 으로 바꾸려면: forgen statusline install --force (기존 값은 settings.json 의 statusLine_backup 에 보관)\n 기존 것을 유지한 채 forgen 줄만 뒤에 덧붙이려면: forgen statusline install --chain`,
46
74
  };
47
75
  }
48
76
  let backedUp = false;
@@ -51,6 +79,9 @@ export function installStatusline(opts = {}) {
51
79
  backedUp = true;
52
80
  }
53
81
  settings.statusLine = { type: 'command', command };
82
+ return writeSettings(settingsPath, settings, command, previous, backedUp);
83
+ }
84
+ function writeSettings(settingsPath, settings, command, previous, backedUp) {
54
85
  try {
55
86
  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
56
87
  if (fs.existsSync(settingsPath))
@@ -69,7 +100,7 @@ export function installStatusline(opts = {}) {
69
100
  }
70
101
  export async function handleStatuslineInstall(args) {
71
102
  const force = args.includes('--force');
72
- const r = installStatusline({ force });
103
+ const r = installStatusline({ force, chain: args.includes('--chain') });
73
104
  const icon = r.status === 'error' ? '✗' : r.status === 'skipped_custom' ? 'ℹ' : '✓';
74
105
  console.log(`${icon} [forgen] ${r.message}`);
75
106
  if (r.status === 'error')
@@ -18,7 +18,7 @@ import * as path from 'node:path';
18
18
  import { spawn } from 'node:child_process';
19
19
  import { fileURLToPath } from 'node:url';
20
20
  import { STATE_DIR } from '../core/paths.js';
21
- import { readJsonlSafe, readReceipt, readVerdicts, setVerdict, precisionByRule, } from './lifecycle/signals.js';
21
+ import { readJsonlSafe, readViolationsWindow, ROTATED_KEEP_DAYS, readReceipt, readVerdicts, setVerdict, precisionByRule, } from './lifecycle/signals.js';
22
22
  import { loadRule, saveRule, loadActiveRules } from '../store/rule-store.js';
23
23
  import { originLine } from '../store/rule-origin.js';
24
24
  import { isHaikuCompoundEnabled } from '../core/compound-consent.js';
@@ -27,7 +27,6 @@ export const JUDGE_CAP_PER_SESSION = 10;
27
27
  export const JUDGE_CAP_PER_DAY = 30;
28
28
  export const DEMOTE_MIN_JUDGED = 5;
29
29
  export const DEMOTE_PRECISION_BELOW = 0.5;
30
- const VIOLATIONS_PATH = path.join(STATE_DIR, 'enforcement', 'violations.jsonl');
31
30
  /** critic D1 SEV-1: 캡은 완료된 판정만 세면 연속 차단에서 폭주한다 → 부모가 spawn 전에 동기적으로 in-flight 마커를 쓴다. */
32
31
  const INFLIGHT_DIR = path.join(STATE_DIR, 'enforcement', 'judge-inflight');
33
32
  export const INFLIGHT_STALE_MS = 5 * 60 * 1000;
@@ -126,13 +125,13 @@ export function withinJudgeCaps(sessionId, now = Date.now(), verdicts = readVerd
126
125
  const today = auto.filter((v) => Date.parse(v.at) >= dayCutoff).length + inflightNew.length;
127
126
  if (today >= JUDGE_CAP_PER_DAY)
128
127
  return false;
129
- const vio = violations ?? readJsonlSafe(VIOLATIONS_PATH);
128
+ const vio = violations ?? readViolationsWindow(1, now);
130
129
  const sessionIds = new Set(vio.filter((v) => v.session_id === sessionId && v.violation_id).map((v) => v.violation_id));
131
130
  const thisSession = auto.filter((v) => sessionIds.has(v.violation_id)).length + inflightNew.filter((id) => sessionIds.has(id)).length;
132
131
  return thisSession < JUDGE_CAP_PER_SESSION;
133
132
  }
134
133
  export function findViolation(violationId) {
135
- const all = readJsonlSafe(VIOLATIONS_PATH);
134
+ const all = readViolationsWindow(ROTATED_KEEP_DAYS);
136
135
  for (let i = all.length - 1; i >= 0; i--)
137
136
  if (all[i].violation_id === violationId)
138
137
  return all[i];
@@ -197,7 +196,7 @@ export function maybeDemote(ruleId, now = Date.now()) {
197
196
  const rule = loadRule(ruleId);
198
197
  if (!rule || rule.strength === 'hard' || rule.enforce_mode === 'advise')
199
198
  return false;
200
- const violations = readJsonlSafe(VIOLATIONS_PATH);
199
+ const violations = readViolationsWindow(7, now);
201
200
  const p = precisionByRule(violations, readVerdicts(), 7, now).get(ruleId);
202
201
  if (!p || p.precision === null)
203
202
  return false;
@@ -0,0 +1,20 @@
1
+ /**
2
+ * 쿼리 측 맥락 신호 — 프롬프트 밖에서 얻는 보조 토큰 (ADR-017 §1.5a).
3
+ *
4
+ * 회화체 프롬프트는 주제어가 거의 없어("이거 왜 안 돼?") 솔루션 태그와 안 겹친다. 그래서 (a) 현재 프로젝트명
5
+ * (b) 이 세션에서 최근 편집한 파일 경로의 의미 토큰을 보조 신호로 쓴다.
6
+ *
7
+ * 불변식 (오주입 방지가 우선):
8
+ * - 맥락 토큰은 프롬프트 토큰과 분리해 다룬다(ranking-pipeline 에서 태그당 0.1·상한 0.2 의 순위 가산(게이트 불변), 프롬프트 매칭 ≥1 필수).
9
+ * - 도구 이름은 쓰지 않는다(Edit/Bash 등 공통어라 오염).
10
+ * - 경로의 범용 이름(src, dist, index, test …)과 확장자는 버린다.
11
+ * - 전부 fail-open: 상태 파일이 없거나 깨져도 빈 배열.
12
+ */
13
+ /** cwd → 프로젝트 이름. 워크트리(.claude/worktrees/x)면 그 앞의 리포 디렉터리를 쓴다. */
14
+ export declare function projectNameFromCwd(cwd: string): string;
15
+ /** 순수 함수: cwd + 최근 파일 경로(최신순) → 맥락 토큰(중복 제거, 상한 적용). */
16
+ export declare function contextTokensFromPaths(cwd: string, recentFiles: readonly string[]): string[];
17
+ /** 세션의 modified-files 상태에서 최근 편집 파일(최신순). 없으면 []. */
18
+ export declare function recentModifiedFiles(sessionId: string | undefined): string[];
19
+ /** 훅 진입점: 맥락 토큰 산출. fail-open. */
20
+ export declare function buildContextTokens(cwd: string, sessionId: string | undefined): string[];
@@ -0,0 +1,102 @@
1
+ /**
2
+ * 쿼리 측 맥락 신호 — 프롬프트 밖에서 얻는 보조 토큰 (ADR-017 §1.5a).
3
+ *
4
+ * 회화체 프롬프트는 주제어가 거의 없어("이거 왜 안 돼?") 솔루션 태그와 안 겹친다. 그래서 (a) 현재 프로젝트명
5
+ * (b) 이 세션에서 최근 편집한 파일 경로의 의미 토큰을 보조 신호로 쓴다.
6
+ *
7
+ * 불변식 (오주입 방지가 우선):
8
+ * - 맥락 토큰은 프롬프트 토큰과 분리해 다룬다(ranking-pipeline 에서 태그당 0.1·상한 0.2 의 순위 가산(게이트 불변), 프롬프트 매칭 ≥1 필수).
9
+ * - 도구 이름은 쓰지 않는다(Edit/Bash 등 공통어라 오염).
10
+ * - 경로의 범용 이름(src, dist, index, test …)과 확장자는 버린다.
11
+ * - 전부 fail-open: 상태 파일이 없거나 깨져도 빈 배열.
12
+ */
13
+ import * as fs from 'node:fs';
14
+ import * as path from 'node:path';
15
+ import { STATE_DIR } from '../core/paths.js';
16
+ import { sanitizeId } from '../hooks/shared/sanitize-id.js';
17
+ import { EN_STOPWORDS } from './solution-format.js';
18
+ const MAX_RECENT_FILES = 8;
19
+ const MAX_CONTEXT_TOKENS = 24;
20
+ const MIN_TOKEN_LEN = 3;
21
+ /** 경로 구성요소 중 의미 없는 범용 이름 */
22
+ const GENERIC_PATH_TOKENS = new Set([
23
+ 'src', 'dist', 'lib', 'bin', 'build', 'out', 'index', 'main', 'app', 'test', 'tests', 'spec', 'specs',
24
+ 'util', 'utils', 'common', 'shared', 'types', 'type', 'core', 'node_modules', 'home', 'ubuntu', 'users',
25
+ 'workspace', 'tmp', 'var', 'usr', 'opt', 'claude', 'worktrees', 'agent', 'readme', 'package', 'json',
26
+ 'config', 'default', 'base', 'helper', 'helpers', 'file', 'files', 'data', 'state', 'docs', 'doc',
27
+ ]);
28
+ /** 'a-b_c.ts', 'FooBar' → ['a','b','c'], ['foo','bar'] 로 쪼갠다. 한글은 그대로 둔다. */
29
+ function splitWords(segment) {
30
+ return segment
31
+ .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
32
+ .toLowerCase()
33
+ .split(/[^a-z0-9가-힣]+/)
34
+ .filter(Boolean);
35
+ }
36
+ function usable(tok) {
37
+ const isKo = /[가-힣]/.test(tok);
38
+ if (tok.length < (isKo ? 2 : MIN_TOKEN_LEN))
39
+ return false;
40
+ if (/^\d+$/.test(tok))
41
+ return false;
42
+ return !GENERIC_PATH_TOKENS.has(tok) && !EN_STOPWORDS.has(tok);
43
+ }
44
+ /** 한 경로 구성요소 → 토큰. 하이픈 복합어(solution-injector)는 복합형도 함께 남긴다. */
45
+ function segmentTokens(segment) {
46
+ const out = splitWords(segment).filter(usable);
47
+ const hyphen = segment.toLowerCase().replace(/_/g, '-');
48
+ if (/^[a-z0-9]+(-[a-z0-9]+)+$/.test(hyphen) && !GENERIC_PATH_TOKENS.has(hyphen))
49
+ out.push(hyphen);
50
+ return out;
51
+ }
52
+ /** cwd → 프로젝트 이름. 워크트리(.claude/worktrees/x)면 그 앞의 리포 디렉터리를 쓴다. */
53
+ export function projectNameFromCwd(cwd) {
54
+ const idx = cwd.indexOf(`${path.sep}.claude${path.sep}worktrees${path.sep}`);
55
+ const root = idx > 0 ? cwd.slice(0, idx) : cwd;
56
+ return path.basename(root);
57
+ }
58
+ /** 순수 함수: cwd + 최근 파일 경로(최신순) → 맥락 토큰(중복 제거, 상한 적용). */
59
+ export function contextTokensFromPaths(cwd, recentFiles) {
60
+ const seen = new Set();
61
+ const add = (toks) => { for (const t of toks)
62
+ seen.add(t); };
63
+ add(segmentTokens(projectNameFromCwd(cwd)));
64
+ for (const file of recentFiles.slice(0, MAX_RECENT_FILES)) {
65
+ const inCwd = path.isAbsolute(file) && file.startsWith(cwd + path.sep);
66
+ const rel = inCwd ? path.relative(cwd, file) : file;
67
+ const segs = rel.split(/[\\/]/).filter(Boolean);
68
+ // cwd 밖 절대경로는 홈/시스템 경로가 섞이므로 파일명 + 바로 위 디렉터리만 쓴다.
69
+ const used = !inCwd && path.isAbsolute(file) ? segs.slice(-2) : segs;
70
+ used.forEach((seg, i) => {
71
+ const isFile = i === used.length - 1;
72
+ add(segmentTokens(isFile ? seg.replace(/\.[A-Za-z0-9]+$/, '') : seg));
73
+ });
74
+ }
75
+ return [...seen].slice(0, MAX_CONTEXT_TOKENS);
76
+ }
77
+ /** 세션의 modified-files 상태에서 최근 편집 파일(최신순). 없으면 []. */
78
+ export function recentModifiedFiles(sessionId) {
79
+ if (!sessionId)
80
+ return [];
81
+ try {
82
+ const p = path.join(STATE_DIR, `modified-files-${sanitizeId(sessionId)}.json`);
83
+ if (!fs.existsSync(p))
84
+ return [];
85
+ const data = JSON.parse(fs.readFileSync(p, 'utf-8'));
86
+ return Object.entries(data.files ?? {})
87
+ .sort((a, b) => (b[1]?.lastModified ?? '').localeCompare(a[1]?.lastModified ?? ''))
88
+ .map(([f]) => f);
89
+ }
90
+ catch {
91
+ return [];
92
+ }
93
+ }
94
+ /** 훅 진입점: 맥락 토큰 산출. fail-open. */
95
+ export function buildContextTokens(cwd, sessionId) {
96
+ try {
97
+ return contextTokensFromPaths(cwd, recentModifiedFiles(sessionId));
98
+ }
99
+ catch {
100
+ return [];
101
+ }
102
+ }
@@ -51,7 +51,7 @@ export interface MinedExplicitLink {
51
51
  observations: number;
52
52
  }
53
53
  export interface MinedClusterPlan {
54
- category: string;
54
+ category: Rule['category'];
55
55
  /** 통합 대상 원본(기존 통합 룰이 있으면 그 룰은 absorberId 로 분리되고 여기엔 신규만). */
56
56
  memberIds: string[];
57
57
  memberPolicies: string[];
@@ -76,9 +76,9 @@ export interface MinedMergeApplyResult {
76
76
  }
77
77
  /**
78
78
  * 병합 계획(읽기 전용). 순서: (1) explicit 동개념 링크 → (2) 남은 채굴 룰끼리 클러스터.
79
- * explicit 매칭은 1:1 최고점(category 무시), 채굴끼리는 기존 clusterCorrectionRules
79
+ * explicit 매칭은 1:1 최고점(category 무시). 채굴끼리는 2단: 1차 clusterCorrectionRules
80
80
  * (category 경계 유지 — 전이 연결이 category 를 넘으면 무관한 개념까지 한 덩어리가 된다는
81
- * 실측에 근거).
81
+ * 실측에 근거) → 2차 mergeAcrossCategories(더 높은 임계 + 대표 policy 직접 유사도만 사용).
82
82
  */
83
83
  export declare function planMinedRuleMerge(): MinedMergePlan;
84
84
  /**
@@ -19,7 +19,7 @@ import { STATE_DIR } from '../core/paths.js';
19
19
  import { atomicWriteJSON, safeReadJSON } from '../hooks/shared/atomic-write.js';
20
20
  import { withFileLock } from '../hooks/shared/file-lock.js';
21
21
  import { createRule, loadAllRules, loadRule, saveRule } from '../store/rule-store.js';
22
- import { clusterCorrectionRules, clusterKey, findMostSimilarRule, isSuppressedCluster, } from './correction-clustering.js';
22
+ import { clusterCorrectionRules, clusterKey, findMostSimilarRule, isSuppressedCluster, mergeAcrossCategories, } from './correction-clustering.js';
23
23
  const log = createLogger('correction-cluster');
24
24
  const SUPPRESSION_PATH = path.join(STATE_DIR, 'cluster-suppression.json');
25
25
  /** 동시 세션종료 클러스터링 직렬화용 락 대상 경로(SEV-3 #4). */
@@ -239,11 +239,30 @@ function isMinedRule(r) {
239
239
  function minedObservationCount(r) {
240
240
  return Math.max(1, r.evidence_refs?.length ?? 0);
241
241
  }
242
+ /** 멤버 다수결 category — 동수면 관측(evidence) 합이 큰 쪽, 그래도 같으면 먼저 나온 쪽. */
243
+ function majorityCategory(members) {
244
+ const tally = new Map();
245
+ for (const m of members) {
246
+ const t = tally.get(m.category) ?? { count: 0, obs: 0 };
247
+ t.count++;
248
+ t.obs += minedObservationCount(m);
249
+ tally.set(m.category, t);
250
+ }
251
+ let best = members[0].category;
252
+ let bt = tally.get(best);
253
+ for (const [cat, t] of tally) {
254
+ if (t.count > bt.count || (t.count === bt.count && t.obs > bt.obs)) {
255
+ best = cat;
256
+ bt = t;
257
+ }
258
+ }
259
+ return best;
260
+ }
242
261
  /**
243
262
  * 병합 계획(읽기 전용). 순서: (1) explicit 동개념 링크 → (2) 남은 채굴 룰끼리 클러스터.
244
- * explicit 매칭은 1:1 최고점(category 무시), 채굴끼리는 기존 clusterCorrectionRules
263
+ * explicit 매칭은 1:1 최고점(category 무시). 채굴끼리는 2단: 1차 clusterCorrectionRules
245
264
  * (category 경계 유지 — 전이 연결이 category 를 넘으면 무관한 개념까지 한 덩어리가 된다는
246
- * 실측에 근거).
265
+ * 실측에 근거) → 2차 mergeAcrossCategories(더 높은 임계 + 대표 policy 직접 유사도만 사용).
247
266
  */
248
267
  export function planMinedRuleMerge() {
249
268
  const all = loadAllRules();
@@ -273,22 +292,38 @@ export function planMinedRuleMerge() {
273
292
  linkedIds.add(m.rule_id);
274
293
  }
275
294
  const remaining = mined.filter((r) => !linkedIds.has(r.rule_id));
295
+ const byId = new Map(remaining.map((r) => [r.rule_id, r]));
296
+ // 1차: category 내 클러스터. 2차: 1차 결과 + 잔여 단독 룰을 category 무관하게 대표 유사도로 병합.
297
+ const primary = clusterCorrectionRules(remaining.map(toClusterable), suppressed);
298
+ const inPrimary = new Set(primary.flatMap((c) => c.members.map((m) => m.rule_id)));
299
+ const units = primary.map((c) => c.members.map((m) => byId.get(m.rule_id)).filter((r) => Boolean(r)));
300
+ for (const r of remaining) {
301
+ if (inPrimary.has(r.rule_id) || r.strength === 'hard' || (r.policy?.length ?? 0) < 10)
302
+ continue;
303
+ units.push([r]);
304
+ }
305
+ const groups = mergeAcrossCategories(units, suppressed);
276
306
  const clusters = [];
277
- for (const cluster of clusterCorrectionRules(remaining.map(toClusterable), suppressed)) {
278
- const memberRules = cluster.members
279
- .map((m) => remaining.find((r) => r.rule_id === m.rule_id))
280
- .filter((r) => Boolean(r));
307
+ for (const memberRules of groups) {
281
308
  if (memberRules.length < 2)
282
309
  continue;
283
- const absorber = memberRules.find(isClusterMergedRule);
284
- const fresh = absorber ? memberRules.filter((r) => r.rule_id !== absorber.rule_id) : memberRules;
310
+ // 기존 통합 룰이 여럿이면 관측이 가장 많은 것이 흡수자, 나머지는 신규 멤버로 흡수된다
311
+ // (2단 트리: 원본→옛 통합 룰→흡수자. unmerge 시 옛 통합 룰이 그대로 복원된다).
312
+ const absorber = memberRules
313
+ .filter(isClusterMergedRule)
314
+ .sort((a, b) => minedObservationCount(b) - minedObservationCount(a))[0];
315
+ const fresh = absorber
316
+ ? memberRules.filter((r) => r.rule_id !== absorber.rule_id)
317
+ : memberRules;
285
318
  if (fresh.length === 0)
286
319
  continue;
287
320
  clusters.push({
288
- category: memberRules[0].category,
321
+ category: majorityCategory(memberRules),
289
322
  memberIds: fresh.map((r) => r.rule_id),
290
323
  memberPolicies: fresh.map((r) => r.policy),
291
- representativePolicy: cluster.representativePolicy,
324
+ representativePolicy: memberRules
325
+ .map((r) => r.policy)
326
+ .reduce((a, b) => (b.length > a.length ? b : a)),
292
327
  oldestCreatedAt: memberRules
293
328
  .map((r) => r.created_at)
294
329
  .reduce((a, b) => (Date.parse(b) < Date.parse(a) ? b : a)),
@@ -358,6 +393,7 @@ async function applyMinedRuleMergePlan(plan) {
358
393
  absorber.status = 'active';
359
394
  absorber.clustered_into = undefined;
360
395
  absorber.policy = cluster.representativePolicy;
396
+ absorber.category = cluster.category;
361
397
  absorber.strength = 'default';
362
398
  absorber.evidence_refs = evidenceRefs;
363
399
  absorber.created_at = oldestCreatedAt;
@@ -367,7 +403,7 @@ async function applyMinedRuleMergePlan(plan) {
367
403
  }
368
404
  else {
369
405
  const merged = createRule({
370
- category: fresh[0].category,
406
+ category: cluster.category,
371
407
  scope: 'me',
372
408
  trigger: fresh[0].trigger,
373
409
  policy: cluster.representativePolicy,
@@ -20,6 +20,18 @@
20
20
  import type { RuleStrength } from '../store/types.js';
21
21
  /** τ — 클러스터 편입 유사도 임계. 정준 게이트(RELEVANCE_MATCH_GATE=0.3)를 코드로 상속. */
22
22
  export declare const CLUSTER_SIMILARITY_TAU = 0.3;
23
+ /**
24
+ * explicit 링크 임계. 상투어 제거(stripPolicyBoilerplate) 후 실측 분포(2026-10-07, 프로덕션 복사본):
25
+ * 진짜 동개념 0.34, 오탐이던 쌍은 0.34→0.00 으로 소멸. 오탐 방어는 임계 상향이 아니라 어휘
26
+ * 정리가 맡으므로 정준 게이트(0.3)를 유지한다(0.4 로 올리면 진짜 링크까지 잃는다).
27
+ */
28
+ export declare const EXPLICIT_LINK_TAU = 0.3;
29
+ /**
30
+ * category 간 2차 병합 임계(대표 policy 직접 유사도). 실측 분포: 무관 쌍 최대 0.27,
31
+ * 동개념 쌍 0.41(웹검색 선조사)·0.70~0.82(Fable 조기 투입). 노이즈 상한 0.27 과 최저 진짜
32
+ * 쌍 0.41 사이 — 0.4 는 노이즈 대비 마진 0.13 을 두고 진짜 쌍을 모두 잡는다.
33
+ */
34
+ export declare const CROSS_CATEGORY_TAU = 0.4;
23
35
  /** 클러스터링 입력: 룰의 최소 표현(순수 로직이 파일/스토어에 의존하지 않도록). */
24
36
  export interface ClusterableRule {
25
37
  rule_id: string;
@@ -41,6 +53,8 @@ export interface CorrectionCluster {
41
53
  /** 통합 룰의 evidence_refs(멤버 union). */
42
54
  evidenceRefs: string[];
43
55
  }
56
+ /** 정책 텍스트에서 상투어 어절을 제거한다(유사도 계산 전용 — 저장 텍스트는 불변). */
57
+ export declare function stripPolicyBoilerplate(text: string): string;
44
58
  /**
45
59
  * 두 정책 텍스트의 대칭 유사도. calculateRelevance 는 비대칭(prompt→solution)이라
46
60
  * 양방향 평균으로 대칭화한다. confidence 인자는 1(순수 태그 매치만 보고 싶음).
@@ -66,6 +80,19 @@ export declare function strengthForConfidence(confidence: number): RuleStrength;
66
80
  * @param suppressed 억제 조합 키 집합(unmerge 된 조합 재통합 방지) — 정렬된 rule_id join
67
81
  */
68
82
  export declare function clusterCorrectionRules(rules: ClusterableRule[], suppressed?: ReadonlySet<string>): CorrectionCluster[];
83
+ /**
84
+ * category 간 2차 병합: 1차 결과 단위(unit = 룰 묶음)들을 *대표 policy 직접 유사도* ≥ tau 로
85
+ * 병합한다. union-find 가 아니라 최고 유사도 쌍부터 탐욕 병합하되, 병합 뒤 새 대표와
86
+ * 구성 단위들의 대표가 모두 tau 이상이어야 한다(star complete-linkage) — 전이 연결로
87
+ * 무관한 덩어리가 한 덩어리가 되는 것을 막는다(실측: 무시 시 10+19 두 덩어리).
88
+ *
89
+ * @param units 1차 클러스터(크기≥2) + 잔여 단독 룰(크기 1). 입력은 변경하지 않는다.
90
+ * @param suppressed 억제 조합 — 병합 결과 멤버 집합이 억제 대상이면 그 병합은 건너뛴다.
91
+ */
92
+ export declare function mergeAcrossCategories<T extends {
93
+ rule_id: string;
94
+ policy: string;
95
+ }>(units: ReadonlyArray<readonly T[]>, suppressed?: ReadonlySet<string>, tau?: number): T[][];
69
96
  /**
70
97
  * ADR-017 D3 — 단일 정책 텍스트에 가장 유사한 룰 1개(유사도 ≥ τ)를 찾는다.
71
98
  * 채굴 룰 생성 시 사전 중복 검사와 explicit 링크 판정에 쓰인다.
@@ -23,17 +23,54 @@ import { calculateRelevance } from './relevance-scorer.js';
23
23
  import { extractTags } from './solution-format.js';
24
24
  /** τ — 클러스터 편입 유사도 임계. 정준 게이트(RELEVANCE_MATCH_GATE=0.3)를 코드로 상속. */
25
25
  export const CLUSTER_SIMILARITY_TAU = RELEVANCE_MATCH_GATE;
26
+ /**
27
+ * explicit 링크 임계. 상투어 제거(stripPolicyBoilerplate) 후 실측 분포(2026-10-07, 프로덕션 복사본):
28
+ * 진짜 동개념 0.34, 오탐이던 쌍은 0.34→0.00 으로 소멸. 오탐 방어는 임계 상향이 아니라 어휘
29
+ * 정리가 맡으므로 정준 게이트(0.3)를 유지한다(0.4 로 올리면 진짜 링크까지 잃는다).
30
+ */
31
+ export const EXPLICIT_LINK_TAU = CLUSTER_SIMILARITY_TAU;
32
+ /**
33
+ * category 간 2차 병합 임계(대표 policy 직접 유사도). 실측 분포: 무관 쌍 최대 0.27,
34
+ * 동개념 쌍 0.41(웹검색 선조사)·0.70~0.82(Fable 조기 투입). 노이즈 상한 0.27 과 최저 진짜
35
+ * 쌍 0.41 사이 — 0.4 는 노이즈 대비 마진 0.13 을 두고 진짜 쌍을 모두 잡는다.
36
+ */
37
+ export const CROSS_CATEGORY_TAU = 0.4;
26
38
  /** 강도 승급 컷오프 — statusConfidence('verified')=0.75 를 코드로 상속(리터럴 복제 아님). */
27
39
  const STRONG_CONFIDENCE_CUTOFF = statusConfidence('verified');
28
40
  /** 클러스터 대상이 되는 최소 정책 텍스트 길이(너무 짧으면 tag 신호 부족). */
29
41
  const MIN_POLICY_LEN = 10;
42
+ /**
43
+ * 정책 상투어(어간) — 거의 모든 교정 정책에 나오는 어휘라 "같은 개념" 신호가 아니다.
44
+ * 실측: "사용자가 명시적으로 …" 중복만으로 서로 다른 정책이 유사도 0.34 를 받아 explicit
45
+ * 오탐 링크가 생겼다. 개념 어휘(웹 검색·Fable·설계 등)는 건드리지 않는다.
46
+ * 어절 prefix 매칭(조사/어미 변형 흡수): '사용자가'·'명시적으로'·'반드시' 등.
47
+ */
48
+ const POLICY_BOILERPLATE_STEMS = [
49
+ '사용자',
50
+ '오너',
51
+ '명시적',
52
+ '항상',
53
+ '반드시',
54
+ '절대',
55
+ '무조건',
56
+ '앞으로',
57
+ '이전에',
58
+ '지시',
59
+ ];
60
+ /** 정책 텍스트에서 상투어 어절을 제거한다(유사도 계산 전용 — 저장 텍스트는 불변). */
61
+ export function stripPolicyBoilerplate(text) {
62
+ return text
63
+ .split(/\s+/)
64
+ .filter((w) => !POLICY_BOILERPLATE_STEMS.some((s) => w.replace(/^[^가-힣a-zA-Z0-9]+/, '').startsWith(s)))
65
+ .join(' ');
66
+ }
30
67
  /**
31
68
  * 두 정책 텍스트의 대칭 유사도. calculateRelevance 는 비대칭(prompt→solution)이라
32
69
  * 양방향 평균으로 대칭화한다. confidence 인자는 1(순수 태그 매치만 보고 싶음).
33
70
  */
34
71
  export function policySimilarity(a, b) {
35
- const tagsA = extractTags(a);
36
- const tagsB = extractTags(b);
72
+ const tagsA = extractTags(stripPolicyBoilerplate(a));
73
+ const tagsB = extractTags(stripPolicyBoilerplate(b));
37
74
  if (tagsA.length === 0 || tagsB.length === 0)
38
75
  return 0;
39
76
  const ab = calculateRelevance(tagsA, tagsB, 1);
@@ -134,6 +171,45 @@ export function clusterCorrectionRules(rules, suppressed = new Set()) {
134
171
  }
135
172
  return clusters;
136
173
  }
174
+ /**
175
+ * category 간 2차 병합: 1차 결과 단위(unit = 룰 묶음)들을 *대표 policy 직접 유사도* ≥ tau 로
176
+ * 병합한다. union-find 가 아니라 최고 유사도 쌍부터 탐욕 병합하되, 병합 뒤 새 대표와
177
+ * 구성 단위들의 대표가 모두 tau 이상이어야 한다(star complete-linkage) — 전이 연결로
178
+ * 무관한 덩어리가 한 덩어리가 되는 것을 막는다(실측: 무시 시 10+19 두 덩어리).
179
+ *
180
+ * @param units 1차 클러스터(크기≥2) + 잔여 단독 룰(크기 1). 입력은 변경하지 않는다.
181
+ * @param suppressed 억제 조합 — 병합 결과 멤버 집합이 억제 대상이면 그 병합은 건너뛴다.
182
+ */
183
+ export function mergeAcrossCategories(units, suppressed = new Set(), tau = CROSS_CATEGORY_TAU) {
184
+ const repOf = (members) => members.map((m) => m.policy).reduce((a, b) => (b.length > a.length ? b : a));
185
+ let work = units
186
+ .filter((u) => u.length > 0)
187
+ .map((u) => ({ members: [...u], rep: repOf(u), constituentReps: [repOf(u)] }));
188
+ for (;;) {
189
+ let best = null;
190
+ for (let i = 0; i < work.length; i++) {
191
+ for (let j = i + 1; j < work.length; j++) {
192
+ const sim = policySimilarity(work[i].rep, work[j].rep);
193
+ if (sim < tau || (best && sim <= best.sim))
194
+ continue;
195
+ const members = [...work[i].members, ...work[j].members];
196
+ if (isSuppressedCluster(members, suppressed))
197
+ continue;
198
+ const rep = repOf(members);
199
+ const constituentReps = [...work[i].constituentReps, ...work[j].constituentReps];
200
+ if (constituentReps.some((c) => c !== rep && policySimilarity(c, rep) < tau))
201
+ continue;
202
+ best = { i, j, sim, merged: { members, rep, constituentReps } };
203
+ }
204
+ }
205
+ if (!best)
206
+ break;
207
+ const { i, j, merged } = best;
208
+ work = work.filter((_, k) => k !== i && k !== j);
209
+ work.push(merged);
210
+ }
211
+ return work.filter((u) => u.members.length >= 2).map((u) => u.members);
212
+ }
137
213
  /**
138
214
  * ADR-017 D3 — 단일 정책 텍스트에 가장 유사한 룰 1개(유사도 ≥ τ)를 찾는다.
139
215
  * 채굴 룰 생성 시 사전 중복 검사와 explicit 링크 판정에 쓰인다.
@@ -143,7 +219,7 @@ export function clusterCorrectionRules(rules, suppressed = new Set()) {
143
219
  * union-find 와 달리 전이적으로 번지지 않으므로 category 경계를 넘어도 안전하다
144
220
  * (반면 clusterCorrectionRules 는 전이 연결 때문에 category 경계를 유지한다).
145
221
  */
146
- export function findMostSimilarRule(policy, candidates, tau = CLUSTER_SIMILARITY_TAU) {
222
+ export function findMostSimilarRule(policy, candidates, tau = EXPLICIT_LINK_TAU) {
147
223
  if ((policy?.length ?? 0) < MIN_POLICY_LEN)
148
224
  return null;
149
225
  let best = null;
@@ -0,0 +1,13 @@
1
+ /**
2
+ * 한국어 회화체 잔여물 처리 — extractTags 의 한국어 분기 전처리.
3
+ *
4
+ * 문제: "이거 같아 왜냐면 시켜보자" 같은 회화체 프롬프트에서 extractTags 가 8칸을 어미/지시어/접속어로
5
+ * 채워 실제 주제어가 밀려난다(ADR-017 §1.5a 실측). KO_STOPWORDS 는 문서체 명사 위주라 이를 못 거른다.
6
+ *
7
+ * 처리 (결과는 `string | null`):
8
+ * - 순수 구어(지시어·접속어·종결 어미·"같아" 류) → null (드롭)
9
+ * - 명사+구어 어미 ("검증해줘", "가능한", "배포하는지") → 어간만 남김 ("검증", "가능", "배포")
10
+ * - 그 외 → 원문 그대로
11
+ * 어간이 2자 미만이면 어미 제거를 하지 않는다("이해"→"이" 방지).
12
+ */
13
+ export declare function normalizeColloquialKo(word: string): string | null;
@@ -0,0 +1,45 @@
1
+ /**
2
+ * 한국어 회화체 잔여물 처리 — extractTags 의 한국어 분기 전처리.
3
+ *
4
+ * 문제: "이거 같아 왜냐면 시켜보자" 같은 회화체 프롬프트에서 extractTags 가 8칸을 어미/지시어/접속어로
5
+ * 채워 실제 주제어가 밀려난다(ADR-017 §1.5a 실측). KO_STOPWORDS 는 문서체 명사 위주라 이를 못 거른다.
6
+ *
7
+ * 처리 (결과는 `string | null`):
8
+ * - 순수 구어(지시어·접속어·종결 어미·"같아" 류) → null (드롭)
9
+ * - 명사+구어 어미 ("검증해줘", "가능한", "배포하는지") → 어간만 남김 ("검증", "가능", "배포")
10
+ * - 그 외 → 원문 그대로
11
+ * 어간이 2자 미만이면 어미 제거를 하지 않는다("이해"→"이" 방지).
12
+ */
13
+ /** 순수 구어 — 단독으로 나오면 태그로 가치가 없다. */
14
+ const COLLOQUIAL_DROP = new Set([
15
+ // 종결·연결 어미 단독
16
+ '같아', '같은데', '같네', '같다', '같애', '같아서', '같은', '거야', '거예요', '건데', '인데', '는데', '은데',
17
+ '하는데', '했는데', '한데', '해줘', '해봐', '해라', '해요', '보자', '볼까', '할까', '할래', '줄래',
18
+ '시켜보자', '시켜봐', '시켜줘', '시켜', '알려줘', '말해줘', '맞아', '맞지', '아니야', '아니고', '아닌데',
19
+ '했는지', '하는지', '할지', '해야', '해야할', '해야하는', '위한', '대한', '통한', '관한', '진행해', '진행해줘',
20
+ // 접속·지시·대명사
21
+ '왜냐면', '왜냐하면', '그래서', '그러면', '그럼', '그런데', '근데', '그리고', '하지만', '그러나', '그래도',
22
+ '이거', '저거', '그거', '이게', '그게', '저게', '이건', '그건', '이걸', '그걸', '여기', '거기', '저기',
23
+ '지금', '이제', '우리', '어떤', '어떻게', '어디', '뭔가', '뭐든', '전부', '일단', '아무', '그냥', '좀더',
24
+ '혹시', '아직', '다시', '계속', '바로', '먼저', '나중', '그다음',
25
+ ]);
26
+ /**
27
+ * 어간 + 구어 어미. 긴 어미가 먼저 매칭되도록 정렬한다.
28
+ * 어간 그룹은 한글 2자 이상(lazy) — 1자 어간("이해"→"이")은 거부.
29
+ */
30
+ const COLLOQUIAL_ENDINGS = [
31
+ '해주세요', '해줄래', '해줘', '해봐', '해보자', '시켜보자', '시켜줘', '시켜봐',
32
+ '하는지', '했는지', '할지', '하는데', '했는데', '한데', '인데', '는데', '은데',
33
+ '하자', '해야', '해도', '하면', '해서', '했던', '하는',
34
+ // 1글자 어미('할/한/해')는 제거하지 않는다 — 권한·역할·제한·피해 같은 명사를 자른다(critic v0.6.6: 접근권한→접근권).
35
+ ].sort((a, b) => b.length - a.length);
36
+ const COLLOQUIAL_ENDING_RE = new RegExp(`^([가-힣]{2,}?)(${COLLOQUIAL_ENDINGS.join('|')})$`);
37
+ export function normalizeColloquialKo(word) {
38
+ if (COLLOQUIAL_DROP.has(word))
39
+ return null;
40
+ const m = word.match(COLLOQUIAL_ENDING_RE);
41
+ if (!m)
42
+ return word;
43
+ const stem = m[1];
44
+ return COLLOQUIAL_DROP.has(stem) ? null : stem;
45
+ }