@wooojin/forgen 0.1.0

package/dist/engine/match-eval-log.js

@@ -0,0 +1,270 @@
+/**
+ * Match eval log — JSONL ranking-decision writer (T3 of the Round 3 plan).
+ *
+ * Why this module exists:
+ *   The bootstrap evaluator (`evaluateSolutionMatcher`) measures matcher
+ *   quality against a labeled fixture, but production traffic is open-ended.
+ *   T2 hoisted query normalization out of the per-solution loop, which is
+ *   fast, but it also hid the "what did we actually rank, and why?" signal
+ *   from offline review. This module appends a single JSONL line per matcher
+ *   call capturing the normalized query, the top candidates with their
+ *   matched terms, and which ones the caller ultimately surfaced.
+ *
+ *   The target consumer is offline analysis: a reviewer can tail or grep
+ *   the file to spot systematic recall misses or spurious matches without
+ *   instrumenting production.
+ *
+ * Privacy posture (T3 security review fix):
+ *   The raw user prompt is NEVER written to disk. Instead, we store a
+ *   short SHA-256 prefix (`rawQueryHash`) plus character length
+ *   (`rawQueryLen`). This keeps dedup and "was the prompt substantial"
+ *   signals available for offline analysis while eliminating the PII /
+ *   API-key / credential leakage risk of persisting raw prompts in
+ *   `~/.forgen/state/match-eval-log.jsonl`. The `normalizedQuery` array
+ *   already carries the matching-signal payload and is safe to persist
+ *   because it only contains short tag tokens (never the full prompt).
+ *
+ * Operational principles:
+ *   1. **Off the critical path.** Never throw; never block. A failed write
+ *      is silently swallowed — the hook must continue to return its
+ *      solutions even if the log is misconfigured, read-only, or full.
+ *   2. **Bounded record size.** Candidates are capped at 5 (the matcher's
+ *      own top-5 cap). `normalizedQuery` is capped at 64 terms. Each
+ *      candidate's `matchedTerms` is capped at 16. Worst-case record ≈
+ *      2KB, which stays under Linux PIPE_BUF=4096 for safe concurrent
+ *      appends on local filesystems.
+ *   3. **Symlink defense.** `fs.openSync` with `O_NOFOLLOW` refuses to
+ *      follow a symlink at the log path. Without this guard, an attacker
+ *      with write access to `~/.forgen/state/` could redirect appends to
+ *      `~/.ssh/authorized_keys`, `~/.bashrc`, or other sensitive files.
+ *   4. **File-lock for concurrency.** Uses `withFileLockSync` to serialize
+ *      concurrent writers. macOS PIPE_BUF=512 is smaller than the worst-
+ *      case record size so POSIX atomic append alone isn't enough.
+ *   5. **Opt-out via env, fail-closed on invalid config.**
+ *      `FORGEN_MATCH_EVAL_LOG=off|disabled|0|false|no` disables entirely.
+ *      `FORGEN_MATCH_EVAL_LOG_SAMPLE=<float 0..1>` samples. An invalid
+ *      sample value (NaN, out of range, whitespace) falls back to 0
+ *      (skip) rather than 1 (log everything) — fail-closed for privacy.
+ *   6. **File size cap.** `readMatchEvalLog` refuses to parse files
+ *      larger than 50 MB to prevent OOM in the offline analyzer. Callers
+ *      are responsible for rotating the log externally.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { constants as fsc } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { MATCH_EVAL_LOG_PATH } from '../core/paths.js';
+import { createLogger } from '../core/logger.js';
+import { withFileLockSync } from '../hooks/shared/file-lock.js';
+const log = createLogger('match-eval-log');
+/** Environment variable controlling log enable/disable. */
+export const MATCH_EVAL_LOG_ENV = 'FORGEN_MATCH_EVAL_LOG';
+/** Environment variable controlling sample rate (0.0 – 1.0). */
+export const MATCH_EVAL_LOG_SAMPLE_ENV = `${MATCH_EVAL_LOG_ENV}_SAMPLE`;
+/** Max candidates to log per record (mirrors matcher top-5). */
+const MAX_CANDIDATES_LOGGED = 5;
+/** Max normalized-query terms to log — defends against large synonym families. */
+const MAX_NORMALIZED_QUERY_LOGGED = 64;
+/** Max matched-terms per candidate — prevents pathological spam. */
+const MAX_MATCHED_TERMS_PER_CANDIDATE = 16;
+/** Read-side DoS guard: refuse to load if the JSONL file is larger than this. */
+const MAX_LOG_FILE_SIZE_BYTES = 50 * 1024 * 1024; // 50 MB
+/**
+ * Check whether logging is disabled via environment variable.
+ * Accepts `off`, `disabled`, `0`, `false`, `no` (case-insensitive).
+ */
+function isDisabled() {
+    const raw = process.env[MATCH_EVAL_LOG_ENV];
+    if (raw === undefined)
+        return false;
+    const v = raw.trim().toLowerCase();
+    return v === 'off' || v === 'disabled' || v === '0' || v === 'false' || v === 'no';
+}
+/**
+ * Read the sample rate from environment. Defaults to 1.0 (log everything).
+ * Invalid values (non-numeric, out of range, whitespace-only) fall back to
+ * 0 — fail-closed for privacy. Rationale: if an operator mistypes
+ * `SAMPLE=01` (intended 0.1) and we default to 1.0, they get 10× more
+ * records than they expected. Fail-closed is safer.
+ */
+function getSampleRate() {
+    const raw = process.env[MATCH_EVAL_LOG_SAMPLE_ENV];
+    if (raw === undefined)
+        return 1.0;
+    const trimmed = raw.trim();
+    if (trimmed === '')
+        return 0;
+    const n = Number.parseFloat(trimmed);
+    if (!Number.isFinite(n) || n < 0 || n > 1)
+        return 0;
+    return n;
+}
+/** Compute a privacy-safe hash + length pair from the raw prompt. */
+function hashRawQuery(rawQuery) {
+    const hash = createHash('sha256').update(rawQuery).digest('hex').slice(0, 16);
+    // Use [...rawQuery].length to get code-point count rather than UTF-16
+    // unit count — a more honest "characters" metric for mixed-script text.
+    const len = [...rawQuery].length;
+    return { hash, len };
+}
+/**
+ * Append a single ranking decision to the match-eval-log JSONL file.
+ *
+ * Fail-open: any error is caught and debug-logged. Callers can invoke
+ * this without guarding — the logger will never bubble an exception into
+ * the hook critical path.
+ */
+export function logMatchDecision(input) {
+    try {
+        if (isDisabled())
+            return;
+        const sampleRate = getSampleRate();
+        if (sampleRate <= 0)
+            return;
+        if (sampleRate < 1 && Math.random() >= sampleRate)
+            return;
+        // Derive privacy-safe hash from rawQuery; never persist the prompt.
+        const { hash, len } = hashRawQuery(input.rawQuery);
+        // Bound record size before serialization.
+        const record = {
+            source: input.source,
+            rawQueryHash: hash,
+            rawQueryLen: len,
+            normalizedQuery: input.normalizedQuery.slice(0, MAX_NORMALIZED_QUERY_LOGGED),
+            candidates: input.candidates.slice(0, MAX_CANDIDATES_LOGGED).map(c => ({
+                name: c.name,
+                relevance: c.relevance,
+                matchedTerms: c.matchedTerms.slice(0, MAX_MATCHED_TERMS_PER_CANDIDATE),
+            })),
+            rankedTopN: input.rankedTopN.slice(0, MAX_CANDIDATES_LOGGED),
+            ts: new Date().toISOString(),
+        };
+        // Serialize FIRST so any toJSON throw is caught before we touch disk.
+        const line = `${JSON.stringify(record)}\n`;
+        // Ensure STATE_DIR exists (idempotent). mode 0o700 matches other
+        // sensitive state under ~/.forgen/state/.
+        const dir = path.dirname(MATCH_EVAL_LOG_PATH);
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        // Use a file lock — POSIX atomic append only guarantees atomicity
+        // under PIPE_BUF (512 on macOS). Records can approach 2KB worst-case
+        // so concurrent writers could interleave without this lock. The lock
+        // is taken on the log file itself, and cleaned up by withFileLockSync.
+        withFileLockSync(MATCH_EVAL_LOG_PATH, () => {
+            // O_NOFOLLOW: refuse to follow a symlink at the target path. This
+            // blocks a local-attacker symlink swap attack where the log file
+            // is replaced with a link to e.g. ~/.ssh/authorized_keys.
+            // O_APPEND: POSIX atomic append within the lock (defense in depth).
+            // O_CREAT with 0o600: create with owner-only mode if absent.
+            const fd = fs.openSync(MATCH_EVAL_LOG_PATH, fsc.O_WRONLY | fsc.O_CREAT | fsc.O_APPEND | fsc.O_NOFOLLOW, 0o600);
+            try {
+                // Enforce mode on pre-existing files (0o600 in openSync only
+                // applies on creation; an existing file with different permissions
+                // keeps them unless we fchmod).
+                try {
+                    fs.fchmodSync(fd, 0o600);
+                }
+                catch { /* best-effort: fchmod may fail on non-owned files */ }
+                fs.writeSync(fd, line);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        });
+    }
+    catch (e) {
+        // Fail-open: never rethrow. Debug-log so the failure is discoverable
+        // via the standard logger if it turns out to be persistent.
+        log.debug(`logMatchDecision failed (swallowed): ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+/**
+ * Read all records from the match-eval-log file. Intended for tests and
+ * offline analysis tools; NOT for hot-path use.
+ *
+ * Malformed lines (non-JSON, missing required fields, wrong shape) are
+ * silently skipped — preserves the debug value of the rest of the file
+ * if one entry gets corrupted by a partial write or tool error.
+ *
+ * DoS guard: refuses to read files larger than `MAX_LOG_FILE_SIZE_BYTES`
+ * to prevent OOM when a long-running log grows unbounded. Returns [] in
+ * that case and debug-logs the skip.
+ */
+export function readMatchEvalLog() {
+    try {
+        if (!fs.existsSync(MATCH_EVAL_LOG_PATH))
+            return [];
+        // Symlink check on read too — don't exfiltrate arbitrary files if the
+        // path has been swapped.
+        const lst = fs.lstatSync(MATCH_EVAL_LOG_PATH);
+        if (lst.isSymbolicLink()) {
+            log.debug('readMatchEvalLog: refusing to read a symlinked log path');
+            return [];
+        }
+        if (lst.size > MAX_LOG_FILE_SIZE_BYTES) {
+            log.debug(`readMatchEvalLog: file exceeds ${MAX_LOG_FILE_SIZE_BYTES} bytes, skipping`);
+            return [];
+        }
+        const content = fs.readFileSync(MATCH_EVAL_LOG_PATH, 'utf-8');
+        const out = [];
+        for (const line of content.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (isValidRecord(parsed)) {
+                    out.push(parsed);
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Runtime shape check for a parsed record. Strict validation of every
+ * field including per-candidate shape — a downstream consumer that calls
+ * `rec.candidates[0].matchedTerms.slice(0, 3)` must not crash on a
+ * malformed entry.
+ */
+function isValidRecord(v) {
+    if (v == null || typeof v !== 'object')
+        return false;
+    const r = v;
+    if (r.source !== 'hook' && r.source !== 'mcp')
+        return false;
+    if (typeof r.rawQueryHash !== 'string')
+        return false;
+    if (typeof r.rawQueryLen !== 'number')
+        return false;
+    if (!Array.isArray(r.normalizedQuery))
+        return false;
+    if (!r.normalizedQuery.every(t => typeof t === 'string'))
+        return false;
+    if (!Array.isArray(r.candidates))
+        return false;
+    for (const c of r.candidates) {
+        if (c == null || typeof c !== 'object')
+            return false;
+        const cc = c;
+        if (typeof cc.name !== 'string')
+            return false;
+        if (typeof cc.relevance !== 'number')
+            return false;
+        if (!Array.isArray(cc.matchedTerms))
+            return false;
+        if (!cc.matchedTerms.every(t => typeof t === 'string'))
+            return false;
+    }
+    if (!Array.isArray(r.rankedTopN))
+        return false;
+    if (!r.rankedTopN.every(t => typeof t === 'string'))
+        return false;
+    if (typeof r.ts !== 'string')
+        return false;
+    return true;
+}

package/dist/engine/phrase-blocklist.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Phrase blocklist — non-dev-context 2-word English compounds.
+ *
+ * Why this module exists (R4-T2 of the Round 4 plan):
+ *   The fixture v2 negative bucket exposed 5 false positive triggers
+ *   ("performance review meeting notes", "system architecture overview
+ *   document", "database backup recovery procedure", "validation of
+ *   insurance claims", "solar system planets astronomy"). All five share
+ *   the same structural problem: a single common dev-adjacent word
+ *   ("performance", "system", "database", "validation", "system") is
+ *   simultaneously a legitimate dev tag AND a legitimate English noun.
+ *   Tag-based matching cannot distinguish "user typed dev term in dev
+ *   context" from "user typed the same word in a non-dev context"
+ *   without external semantic signal.
+ *
+ *   T4 BM25 was prototyped as a fix (frequency-based down-weighting) and
+ *   skipped — see `docs/plans/2026-04-08-t4-bm25-skip-adr.md` for the
+ *   full rationale. The structural reason BM25 didn't help: with N=15
+ *   solutions, common dev-adjacent words still cluster in the high-IDF
+ *   range, so even after IDF the bare-tag match wins.
+ *
+ *   R4-T2's approach is the inverse: instead of trying to make the
+ *   matcher smarter, surface the non-dev *context* directly. A 2-word
+ *   English compound like "performance review" or "system architecture"
+ *   is a strong signal that the surrounding query is NOT a dev question.
+ *   When such a compound appears in the query, the function below masks
+ *   its constituent tokens from the prompt tag list, removing the false
+ *   evidence the matcher would otherwise rank on. Other dev tokens in
+ *   the same query are preserved, so a dev query that happens to include
+ *   one of these compounds (e.g., "performance review of caching
+ *   strategy") still surfaces the legitimate cache match.
+ *
+ * Curation rules (for entries in PHRASE_BLOCKLIST):
+ *   1. **2 words minimum**, lowercase ASCII, single space separator.
+ *      Single words are too prone to false negatives — "performance"
+ *      alone is a real dev concept; "performance review" is not.
+ *   2. **NEVER block legitimate dev compounds.** "code review", "function
+ *      call", "error message", "database query", "system design", "type
+ *      check", "unit test", "build pipeline" — all of these are first-
+ *      class dev terms and MUST stay matchable.
+ *   3. **Prefer concrete English compounds with a known false-positive
+ *      footprint.** Each entry should trace back to either (a) one of
+ *      the 5 known fixture v2 trigger queries, or (b) a manual review
+ *      of top-50 corpus tags for English homographs.
+ *   4. **Plurals as separate entries.** "performance review" and
+ *      "performance reviews" are both common; we list both rather than
+ *      apply automatic stemming, since stemming would risk over-blocking
+ *      ("review" → "reviews" → "reviewed" cascade).
+ *   5. **No regex / wildcards.** Literal phrase matching keeps the
+ *      blocklist auditable and avoids ReDoS surface.
+ *
+ * Roll-out posture:
+ *   Start with ~15 entries (5 known fixture triggers + 10 homograph
+ *   candidates), measure on the bootstrap eval, expand only if metrics
+ *   indicate real-world false positives that aren't covered. The ADR
+ *   targeted ~50 phrases as an upper bound — exceeding that without
+ *   measured evidence is a sign that the blocklist is becoming a leaky
+ *   abstraction for a deeper matcher problem.
+ */
+/**
+ * Lowercase ASCII 2-word phrases that signal a non-dev context.
+ *
+ * Audit owner: matcher maintainer. Adding/removing entries MUST be
+ * accompanied by a fixture eval re-run and (if the move shifts metrics)
+ * a `ROUND3_BASELINE` update in the same PR.
+ */
+export declare const PHRASE_BLOCKLIST: readonly string[];
+/**
+ * Find every blocked phrase that appears in the query as a whole-word match.
+ *
+ * Whole-word means the phrase is bounded by start-of-string, end-of-string,
+ * any whitespace, or any punctuation/non-ASCII-letter character on both
+ * sides. Substring matching alone would over-block ("performance reviewer"
+ * must NOT match "performance review"); whitespace-only boundary checks
+ * would under-detect natural-language punctuation ("performance review.").
+ *
+ * Iterates ALL occurrences of each phrase, not just the first — so a query
+ * like "performance reviewer and performance review meeting" still detects
+ * the second occurrence as a valid match even though the first overlaps a
+ * longer word.
+ *
+ * Returns the list of matched phrases in input order; the same phrase is
+ * never reported twice even if it appears multiple times. Empty array
+ * when no blocked phrase is present.
+ */
+export declare function findBlockedPhrases(rawQuery: string): string[];
+/**
+ * Mask the tokens of any blocked phrase from a prompt tag list.
+ *
+ * Given the raw query (used for phrase detection) and the already-extracted
+ * prompt tags, this function:
+ *   1. Finds every blocked phrase in the raw query.
+ *   2. Computes the union of all phrase-constituent tokens (after running
+ *      them through `extractTags` so the masking matches the same
+ *      lowercase / Korean-aware token shape the matcher already uses).
+ *   3. Returns a new prompt tag list with the masked tokens removed.
+ *
+ * If no blocked phrase is found, the input array is returned unchanged
+ * (referentially — for the hot path's allocation cost). Otherwise a new
+ * filtered array is returned.
+ *
+ * Example: query "performance review meeting notes"
+ *   - Blocked phrases found: ["performance review", "meeting notes"]
+ *   - Masked tokens: {performance, review, meeting, notes}
+ *   - extractTags("performance review meeting notes") =
+ *     [performance, review, meeting, notes]
+ *   - Result: [] (every prompt tag was masked)
+ *
+ * Example: query "performance review of caching strategy"
+ *   - Blocked phrases found: ["performance review"]
+ *   - Masked tokens: {performance, review}
+ *   - extractTags result: [performance, review, caching, strategy]
+ *   - Filtered result: [caching, strategy]  ← legitimate dev tags survive
+ *
+ * Korean queries: blocked phrases are ASCII-only, so a Korean query never
+ * triggers masking. Mixed queries (Korean + English) only mask the
+ * English-side tokens that participate in a blocked phrase.
+ */
+export declare function maskBlockedTokens(rawQuery: string, promptTags: readonly string[]): string[];

package/dist/engine/phrase-blocklist.js

@@ -0,0 +1,208 @@
+/**
+ * Phrase blocklist — non-dev-context 2-word English compounds.
+ *
+ * Why this module exists (R4-T2 of the Round 4 plan):
+ *   The fixture v2 negative bucket exposed 5 false positive triggers
+ *   ("performance review meeting notes", "system architecture overview
+ *   document", "database backup recovery procedure", "validation of
+ *   insurance claims", "solar system planets astronomy"). All five share
+ *   the same structural problem: a single common dev-adjacent word
+ *   ("performance", "system", "database", "validation", "system") is
+ *   simultaneously a legitimate dev tag AND a legitimate English noun.
+ *   Tag-based matching cannot distinguish "user typed dev term in dev
+ *   context" from "user typed the same word in a non-dev context"
+ *   without external semantic signal.
+ *
+ *   T4 BM25 was prototyped as a fix (frequency-based down-weighting) and
+ *   skipped — see `docs/plans/2026-04-08-t4-bm25-skip-adr.md` for the
+ *   full rationale. The structural reason BM25 didn't help: with N=15
+ *   solutions, common dev-adjacent words still cluster in the high-IDF
+ *   range, so even after IDF the bare-tag match wins.
+ *
+ *   R4-T2's approach is the inverse: instead of trying to make the
+ *   matcher smarter, surface the non-dev *context* directly. A 2-word
+ *   English compound like "performance review" or "system architecture"
+ *   is a strong signal that the surrounding query is NOT a dev question.
+ *   When such a compound appears in the query, the function below masks
+ *   its constituent tokens from the prompt tag list, removing the false
+ *   evidence the matcher would otherwise rank on. Other dev tokens in
+ *   the same query are preserved, so a dev query that happens to include
+ *   one of these compounds (e.g., "performance review of caching
+ *   strategy") still surfaces the legitimate cache match.
+ *
+ * Curation rules (for entries in PHRASE_BLOCKLIST):
+ *   1. **2 words minimum**, lowercase ASCII, single space separator.
+ *      Single words are too prone to false negatives — "performance"
+ *      alone is a real dev concept; "performance review" is not.
+ *   2. **NEVER block legitimate dev compounds.** "code review", "function
+ *      call", "error message", "database query", "system design", "type
+ *      check", "unit test", "build pipeline" — all of these are first-
+ *      class dev terms and MUST stay matchable.
+ *   3. **Prefer concrete English compounds with a known false-positive
+ *      footprint.** Each entry should trace back to either (a) one of
+ *      the 5 known fixture v2 trigger queries, or (b) a manual review
+ *      of top-50 corpus tags for English homographs.
+ *   4. **Plurals as separate entries.** "performance review" and
+ *      "performance reviews" are both common; we list both rather than
+ *      apply automatic stemming, since stemming would risk over-blocking
+ *      ("review" → "reviews" → "reviewed" cascade).
+ *   5. **No regex / wildcards.** Literal phrase matching keeps the
+ *      blocklist auditable and avoids ReDoS surface.
+ *
+ * Roll-out posture:
+ *   Start with ~15 entries (5 known fixture triggers + 10 homograph
+ *   candidates), measure on the bootstrap eval, expand only if metrics
+ *   indicate real-world false positives that aren't covered. The ADR
+ *   targeted ~50 phrases as an upper bound — exceeding that without
+ *   measured evidence is a sign that the blocklist is becoming a leaky
+ *   abstraction for a deeper matcher problem.
+ */
+import { extractTags } from './solution-format.js';
+/**
+ * Lowercase ASCII 2-word phrases that signal a non-dev context.
+ *
+ * Audit owner: matcher maintainer. Adding/removing entries MUST be
+ * accompanied by a fixture eval re-run and (if the move shifts metrics)
+ * a `ROUND3_BASELINE` update in the same PR.
+ */
+export const PHRASE_BLOCKLIST = [
+    // ── 5 known fixture v2 triggers ──
+    'performance review',
+    'system architecture',
+    'database backup',
+    'insurance claim',
+    'solar system',
+    // ── Plural forms of the above (separate entries per curation rule 4) ──
+    'performance reviews',
+    'system architectures',
+    'database backups',
+    'insurance claims',
+    // ── Common non-dev English compounds with dev-tag homographs ──
+    // "validation ... insurance" path: insurance domain compounds
+    'insurance policy',
+    'insurance policies',
+    // "system architecture overview document" path: document/overview compounds
+    'overview document',
+    'document overview',
+    // "performance review meeting notes" path: meeting/notes compounds
+    'meeting notes',
+    'meeting minutes',
+    // NOTE on intentionally-omitted entries:
+    //   - 'recovery procedure' / 'backup recovery' were considered (and
+    //     redundantly covered the `database backup recovery procedure`
+    //     trigger), but rejected per code review: they would silently mask
+    //     dev SRE queries like 'disaster recovery procedure' or 'rollback
+    //     recovery procedure'. The `database backup` entry alone catches
+    //     the v2 trigger, so the redundancy was pure downside.
+    //   - 'function room' / 'room booking' were also considered as
+    //     hypothetical homographs but rejected per curation rule #3 (no
+    //     fixture-traceable false-positive footprint, so adding them
+    //     would turn the blocklist into a leaky abstraction).
+];
+/**
+ * Test whether a single character is an "alphanumeric word character" for
+ * the purpose of word-boundary detection. Anything that's NOT [a-z0-9] is
+ * treated as a boundary — that includes whitespace, punctuation
+ * (`. , ; : ! ? ( ) [ ] { } " ' /`), Korean/CJK characters, and the
+ * absence of a character (start/end of string, signaled by `undefined`).
+ *
+ * Why not just whitespace: real user prompts contain natural-language
+ * punctuation ("performance review.", "(performance review)",
+ * "performance review, then revert"). Whitespace-only boundaries miss
+ * these cases and the trigger phrases survive into the matcher.
+ */
+function isWordChar(ch) {
+    if (ch === undefined)
+        return false;
+    const code = ch.charCodeAt(0);
+    // ASCII '0'-'9' (48-57), 'a'-'z' (97-122). Lowercase only because
+    // callers always pass `lower` strings.
+    return (code >= 48 && code <= 57) || (code >= 97 && code <= 122);
+}
+/**
+ * Find every blocked phrase that appears in the query as a whole-word match.
+ *
+ * Whole-word means the phrase is bounded by start-of-string, end-of-string,
+ * any whitespace, or any punctuation/non-ASCII-letter character on both
+ * sides. Substring matching alone would over-block ("performance reviewer"
+ * must NOT match "performance review"); whitespace-only boundary checks
+ * would under-detect natural-language punctuation ("performance review.").
+ *
+ * Iterates ALL occurrences of each phrase, not just the first — so a query
+ * like "performance reviewer and performance review meeting" still detects
+ * the second occurrence as a valid match even though the first overlaps a
+ * longer word.
+ *
+ * Returns the list of matched phrases in input order; the same phrase is
+ * never reported twice even if it appears multiple times. Empty array
+ * when no blocked phrase is present.
+ */
+export function findBlockedPhrases(rawQuery) {
+    const lower = rawQuery.toLowerCase();
+    const found = [];
+    for (const phrase of PHRASE_BLOCKLIST) {
+        let from = 0;
+        while (true) {
+            const idx = lower.indexOf(phrase, from);
+            if (idx === -1)
+                break;
+            const beforeOk = idx === 0 || !isWordChar(lower[idx - 1]);
+            const afterOk = !isWordChar(lower[idx + phrase.length]);
+            if (beforeOk && afterOk) {
+                if (!found.includes(phrase))
+                    found.push(phrase);
+                break; // dedup policy: one hit per phrase is enough
+            }
+            from = idx + 1;
+        }
+    }
+    return found;
+}
+/**
+ * Mask the tokens of any blocked phrase from a prompt tag list.
+ *
+ * Given the raw query (used for phrase detection) and the already-extracted
+ * prompt tags, this function:
+ *   1. Finds every blocked phrase in the raw query.
+ *   2. Computes the union of all phrase-constituent tokens (after running
+ *      them through `extractTags` so the masking matches the same
+ *      lowercase / Korean-aware token shape the matcher already uses).
+ *   3. Returns a new prompt tag list with the masked tokens removed.
+ *
+ * If no blocked phrase is found, the input array is returned unchanged
+ * (referentially — for the hot path's allocation cost). Otherwise a new
+ * filtered array is returned.
+ *
+ * Example: query "performance review meeting notes"
+ *   - Blocked phrases found: ["performance review", "meeting notes"]
+ *   - Masked tokens: {performance, review, meeting, notes}
+ *   - extractTags("performance review meeting notes") =
+ *     [performance, review, meeting, notes]
+ *   - Result: [] (every prompt tag was masked)
+ *
+ * Example: query "performance review of caching strategy"
+ *   - Blocked phrases found: ["performance review"]
+ *   - Masked tokens: {performance, review}
+ *   - extractTags result: [performance, review, caching, strategy]
+ *   - Filtered result: [caching, strategy]  ← legitimate dev tags survive
+ *
+ * Korean queries: blocked phrases are ASCII-only, so a Korean query never
+ * triggers masking. Mixed queries (Korean + English) only mask the
+ * English-side tokens that participate in a blocked phrase.
+ */
+export function maskBlockedTokens(rawQuery, promptTags) {
+    const blockedPhrases = findBlockedPhrases(rawQuery);
+    if (blockedPhrases.length === 0)
+        return [...promptTags];
+    // Tokenize blocked phrases through the SAME pipeline that produced
+    // promptTags so the mask shape matches. extractTags lowercases, splits
+    // on non-word characters, and applies stopword/length filters.
+    const masked = new Set();
+    for (const phrase of blockedPhrases) {
+        for (const token of extractTags(phrase))
+            masked.add(token);
+    }
+    if (masked.size === 0)
+        return [...promptTags];
+    return promptTags.filter(t => !masked.has(t));
+}

package/dist/engine/skill-promoter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Forgen — Skill Promoter
+ *
+ * verified/mature 솔루션을 .forgen/me/skills/ 스킬로 승격.
+ * 솔루션(선언적 지식) → 스킬(절차적 지식) 변환.
+ */
+export interface PromoteResult {
+    success: boolean;
+    skillPath?: string;
+    reason?: string;
+}
+/** 솔루션을 스킬로 승격 */
+export declare function promoteSolution(solutionName: string, triggers?: string[]): PromoteResult;
+/** 스킬 목록 조회 */
+export declare function listSkills(): Array<{
+    name: string;
+    status: string;
+    promotedFrom?: string;
+    triggers: string[];
+}>;