codetrap 0.1.2 → 0.1.4

package/src/db/queries.ts

@@ -12,32 +12,37 @@ import {
 } from "../domain/trap";
 import { prepareFTSQuery } from "../lib/fts-query";
 import { normalizeQuery } from "../lib/search-normalizer";
-import { normalizeEvidenceForExport } from "../lib/trap-archive";
-import { encodeEvidenceRelatedFiles, encodeTrapTags } from "../lib/trap-json-fields";
+import {
+  encodeTrapInsertFields,
+  mergeTrapUpdateForSearchText,
+  normalizeEvidenceForExport,
+  normalizeTrapForExport,
+} from "../lib/trap-codec";
+import { encodeEvidenceRelatedFiles, encodeTrapPathGlobs, encodeTrapTags } from "../lib/trap-json-fields";
 import { buildTrapSearchText, passageFieldsChanged, searchTextFieldsChanged } from "../lib/trap-search-document";
 
 export type TrapStatusFilter = TrapStatus | "all";
+export type TrapRecordInsert = Omit<Trap, "id">;
 
 export function insertTrap(db: Database, input: TrapInput): number {
-  const tags = encodeTrapTags(input.tags);
-  const searchText = buildTrapSearchText({ ...input, tags });
+  const fields = encodeTrapInsertFields(input);
   const stmt = db.prepare(`
     INSERT INTO traps (
       title, category, tags, scope, context, mistake, fix, search_text,
       before_code, after_code, severity, state_key, status, supersedes_id,
-      valid_from, valid_until, project_path
+      valid_from, valid_until, project_path, path_globs, module, owner
     )
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), ?, ?)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), ?, ?, ?, ?, ?)
   `);
   const result = stmt.run(
     input.title,
     input.category,
-    tags,
+    fields.tags,
     input.scope,
     input.context,
     input.mistake,
     input.fix,
-    searchText,
+    fields.search_text,
     input.before_code ?? null,
     input.after_code ?? null,
     input.severity ?? DEFAULT_SEVERITY,
@@ -45,7 +50,10 @@ export function insertTrap(db: Database, input: TrapInput): number {
     DEFAULT_TRAP_STATUS,
     null,
     null,
-    input.project_path ?? null
+    input.project_path ?? null,
+    fields.path_globs,
+    normalizeOptionalText(input.module),
+    normalizeOptionalText(input.owner)
   );
   return Number(result.lastInsertRowid);
 }
@@ -53,7 +61,7 @@ export function insertTrap(db: Database, input: TrapInput): number {
 export function searchTraps(
   db: Database,
   query: string,
-  opts: { category?: string; scope?: string; limit?: number; status?: TrapStatusFilter } = {}
+  opts: { category?: string; scope?: string; limit?: number; status?: TrapStatusFilter; module?: string; owner?: string } = {}
 ): TrapSearchResult[] {
   const prepared = prepareFTSQuery(normalizeQuery(query));
   if (!prepared) return [];
@@ -86,7 +94,7 @@ export function getTrap(db: Database, id: number): Trap | null {
 
 export function listTraps(
   db: Database,
-  opts: { category?: string; scope?: string; limit?: number; offset?: number; status?: TrapStatusFilter } = {}
+  opts: { category?: string; scope?: string; limit?: number; offset?: number; status?: TrapStatusFilter; module?: string; owner?: string } = {}
 ): Trap[] {
   const conditions: string[] = [];
   const params: SQLQueryBindings[] = [];
@@ -108,24 +116,24 @@ export function updateTrap(db: Database, id: number, input: TrapUpdate): boolean
   const current = searchTextFieldsChanged(input) || passageFieldsChanged(input) ? getTrap(db, id) : null;
 
   for (const key of TRAP_UPDATE_FIELDS) {
-    if (key === "tags") continue;
+    if (key === "tags" || key === "path_globs") continue;
     const value = input[key];
     if (value !== undefined) {
       updates.push(`${key} = ?`);
-      params.push(value ?? null);
+      params.push(key === "module" || key === "owner" ? normalizeOptionalText(value) : value ?? null);
     }
   }
   if (input.tags !== undefined) {
     updates.push("tags = ?");
     params.push(encodeTrapTags(input.tags));
   }
+  if (input.path_globs !== undefined) {
+    updates.push("path_globs = ?");
+    params.push(encodeTrapPathGlobs(input.path_globs));
+  }
 
   if (current && searchTextFieldsChanged(input)) {
-    const merged = {
-      ...current,
-      ...input,
-      tags: input.tags !== undefined ? encodeTrapTags(input.tags) : current.tags,
-    };
+    const merged = mergeTrapUpdateForSearchText(current, input);
     updates.push("search_text = ?");
     params.push(buildTrapSearchText(merged));
   }
@@ -172,6 +180,10 @@ export function listTrapEvidence(db: Database, trapId: number): TrapEvidence[] {
 }
 
 export function archiveTrap(db: Database, id: number): boolean {
+  return markTrapArchived(db, id);
+}
+
+export function markTrapArchived(db: Database, id: number): boolean {
   const result = db
     .prepare(
       `
@@ -200,33 +212,43 @@ export function supersedeTrap(
 
   const key = stateKey ?? oldTrap.state_key ?? newTrap.state_key ?? `trap:${id}`;
   const tx = db.transaction(() => {
-    db.prepare(
-      `
-      UPDATE traps
-      SET status = 'superseded',
-          state_key = ?,
-          valid_until = COALESCE(valid_until, datetime('now')),
-          updated_at = datetime('now')
-      WHERE id = ?
-    `
-    ).run(key, id);
-    db.prepare(
-      `
-      UPDATE traps
-      SET status = 'active',
-          state_key = ?,
-          supersedes_id = ?,
-          valid_from = COALESCE(valid_from, datetime('now')),
-          valid_until = NULL,
-          updated_at = datetime('now')
-      WHERE id = ?
-    `
-    ).run(key, id, supersededById);
+    markTrapSuperseded(db, id, key);
+    markTrapSuperseding(db, supersededById, id, key);
   });
   tx();
   return true;
 }
 
+export function markTrapSuperseded(db: Database, id: number, stateKey: string): boolean {
+  const result = db.prepare(supersedeTrapSql).run(stateKey, id);
+  return result.changes > 0;
+}
+
+export function markTrapSuperseding(db: Database, id: number, supersedesId: number, stateKey: string): boolean {
+  const result = db.prepare(supersedingTrapSql).run(stateKey, supersedesId, id);
+  return result.changes > 0;
+}
+
+const supersedeTrapSql = `
+  UPDATE traps
+  SET status = 'superseded',
+      state_key = ?,
+      valid_until = COALESCE(valid_until, datetime('now')),
+      updated_at = datetime('now')
+  WHERE id = ?
+`;
+
+const supersedingTrapSql = `
+  UPDATE traps
+  SET status = 'active',
+      state_key = ?,
+      supersedes_id = ?,
+      valid_from = COALESCE(valid_from, datetime('now')),
+      valid_until = NULL,
+      updated_at = datetime('now')
+  WHERE id = ?
+`;
+
 export function incrementHitCount(db: Database, id: number): void {
   db.prepare("UPDATE traps SET hit_count = hit_count + 1, updated_at = datetime('now') WHERE id = ?").run(id);
 }
@@ -237,18 +259,22 @@ export function getTopTraps(db: Database, scope: string, limit = 20): Trap[] {
     .all(scope, limit) as Trap[];
 }
 
-export function getStats(db: Database): {
+export function getStats(db: Database, opts: { scope?: string; status?: TrapStatusFilter } = {}): {
   total: number;
   byCategory: Record<string, number>;
   bySeverity: Record<string, number>;
 } {
-  const total = (db.query("SELECT COUNT(*) as c FROM traps").get() as { c: number }).c;
+  const conditions: string[] = [];
+  const params: SQLQueryBindings[] = [];
+  addTrapFilters(conditions, params, opts);
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const total = (db.query(`SELECT COUNT(*) as c FROM traps ${where}`).get(...params) as { c: number }).c;
   const byCategory = db
-    .query("SELECT category, COUNT(*) as c FROM traps GROUP BY category")
-    .all() as { category: string; c: number }[];
+    .query(`SELECT category, COUNT(*) as c FROM traps ${where} GROUP BY category`)
+    .all(...params) as { category: string; c: number }[];
   const bySeverity = db
-    .query("SELECT severity, COUNT(*) as c FROM traps GROUP BY severity")
-    .all() as { severity: string; c: number }[];
+    .query(`SELECT severity, COUNT(*) as c FROM traps ${where} GROUP BY severity`)
+    .all(...params) as { severity: string; c: number }[];
 
   return {
     total,
@@ -260,11 +286,79 @@ export function getStats(db: Database): {
 export function exportTraps(db: Database): TrapExportRecord[] {
   const traps = db.query("SELECT * FROM traps").all() as Trap[];
   return traps.map((trap) => ({
-    ...trap,
+    ...normalizeTrapForExport(trap),
+    evidence: listTrapEvidence(db, trap.id).map(normalizeEvidenceForExport),
+  }));
+}
+
+export function exportProjectTrapsByPath(db: Database, projectPath: string): TrapExportRecord[] {
+  const traps = db
+    .query("SELECT * FROM traps WHERE scope = 'project' AND project_path = ? ORDER BY id")
+    .all(projectPath) as Trap[];
+  return traps.map((trap) => ({
+    ...normalizeTrapForExport(trap),
     evidence: listTrapEvidence(db, trap.id).map(normalizeEvidenceForExport),
   }));
 }
 
+export function insertTrapRecord(db: Database, record: TrapRecordInsert): number {
+  const stmt = db.prepare(`
+    INSERT INTO traps (
+      title, category, tags, scope, context, mistake, fix, search_text,
+      before_code, after_code, severity, state_key, status, supersedes_id,
+      valid_from, valid_until, project_path, path_globs, module, owner,
+      hit_count, created_at, updated_at
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  const result = stmt.run(
+    record.title,
+    record.category,
+    record.tags,
+    record.scope,
+    record.context,
+    record.mistake,
+    record.fix,
+    record.search_text,
+    record.before_code,
+    record.after_code,
+    record.severity,
+    record.state_key,
+    record.status,
+    record.supersedes_id,
+    record.valid_from,
+    record.valid_until,
+    record.project_path,
+    record.path_globs,
+    normalizeOptionalText(record.module),
+    normalizeOptionalText(record.owner),
+    record.hit_count,
+    record.created_at,
+    record.updated_at
+  );
+  return Number(result.lastInsertRowid);
+}
+
+export function updateTrapSupersedesId(db: Database, id: number, supersedesId: number): boolean {
+  const result = db.prepare("UPDATE traps SET supersedes_id = ? WHERE id = ?").run(supersedesId, id);
+  return result.changes > 0;
+}
+
+export function deleteTrapsByIds(db: Database, ids: number[]): number {
+  if (ids.length === 0) return 0;
+  let deleted = 0;
+  const stmt = db.prepare("DELETE FROM traps WHERE id = ?");
+  const tx = db.transaction(() => {
+    for (const id of ids) {
+      if (!getTrap(db, id)) continue;
+      stmt.run(id);
+      deleted++;
+    }
+  });
+  tx();
+  return deleted;
+}
+
 export function countTraps(db: Database, opts: { scope?: string; category?: string; status?: TrapStatusFilter } = {}): number {
   const conditions: string[] = [];
   const params: SQLQueryBindings[] = [];
@@ -274,10 +368,17 @@ export function countTraps(db: Database, opts: { scope?: string; category?: stri
   return row.c;
 }
 
+export function countProjectTrapsByPath(db: Database, projectPath: string): number {
+  const row = db
+    .query("SELECT COUNT(*) as c FROM traps WHERE scope = 'project' AND project_path = ?")
+    .get(projectPath) as { c: number };
+  return row.c;
+}
+
 function addTrapFilters(
   conditions: string[],
   params: SQLQueryBindings[],
-  opts: { category?: string; scope?: string; status?: TrapStatusFilter },
+  opts: { category?: string; scope?: string; status?: TrapStatusFilter; module?: string; owner?: string },
   alias?: string
 ): void {
   const prefix = alias ? `${alias}.` : "";
@@ -293,4 +394,20 @@ function addTrapFilters(
     conditions.push(`${prefix}status = ?`);
     params.push(opts.status ?? DEFAULT_TRAP_STATUS);
   }
+  const module = normalizeOptionalText(opts.module);
+  if (module) {
+    conditions.push(`(${prefix}module IS NULL OR ${prefix}module = '' OR ${prefix}module = ?)`);
+    params.push(module);
+  }
+  const owner = normalizeOptionalText(opts.owner);
+  if (owner) {
+    conditions.push(`(${prefix}owner IS NULL OR ${prefix}owner = '' OR ${prefix}owner = ?)`);
+    params.push(owner);
+  }
+}
+
+function normalizeOptionalText(value: unknown): string | null {
+  if (typeof value !== "string") return value == null ? null : String(value);
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
 }

package/src/db/repository.ts

@@ -8,7 +8,6 @@ import type {
   TrapSearchResult,
   TrapUpdate,
 } from "../domain/trap";
-import * as embeddingQueries from "./embedding-queries";
 import { SearchService, type SearchOptions } from "../lib/search-service";
 import {
   type EmbeddingConfig,
@@ -19,17 +18,25 @@ import { runEmbeddingJob } from "../lib/embedding-job";
 import { passageFieldsChanged } from "../lib/trap-search-document";
 import * as queries from "./queries";
 import type { TrapStatus } from "../lib/constants";
+import { TrapSearchPolicy } from "../lib/search-policy";
+import { DatabaseEmbeddingIndex } from "../lib/embedding-index";
+import { archiveTrapLifecycle, supersedeTrapLifecycle } from "../lib/trap-lifecycle";
 
 export type TrapStats = ReturnType<typeof queries.getStats>;
+export type EmbeddingStateCounts = ReturnType<DatabaseEmbeddingIndex["stateCounts"]>;
+export type TrapRecordInsert = queries.TrapRecordInsert;
 
 export class TrapRepository {
   private readonly searchService: SearchService;
+  private readonly searchPolicy = new TrapSearchPolicy();
+  private readonly embeddingIndex: DatabaseEmbeddingIndex;
 
   constructor(
     private readonly db: Database,
     private readonly embedder?: EmbeddingProvider
   ) {
     this.searchService = new SearchService(db, embedder);
+    this.embeddingIndex = new DatabaseEmbeddingIndex(db);
   }
 
   add(input: TrapInput): number {
@@ -54,14 +61,25 @@ export class TrapRepository {
     };
   }
 
-  list(opts: { category?: string; scope?: string; limit?: number; offset?: number; status?: TrapStatus | "all" } = {}): Trap[] {
-    return queries.listTraps(this.db, opts);
+  list(opts: { category?: string; scope?: string; limit?: number; offset?: number; status?: TrapStatus | "all"; path?: string; module?: string; owner?: string } = {}): Trap[] {
+    const limit = opts.limit ?? 50;
+    const queryLimit = opts.path ? Math.max(limit * 5, 250) : limit;
+    return queries
+      .listTraps(this.db, { ...opts, limit: queryLimit })
+      .filter((trap) => this.searchPolicy.matchesTrap(trap, opts))
+      .slice(0, limit);
+  }
+
+  listMisScoped(expectedScope: string): Trap[] {
+    return queries
+      .listTraps(this.db, { status: "all", limit: 100000 })
+      .filter((trap) => trap.scope !== expectedScope);
   }
 
   update(id: number, input: TrapUpdate): boolean {
     const success = queries.updateTrap(this.db, id, input);
     if (success && passageFieldsChanged(input)) {
-      embeddingQueries.deleteEmbedding(this.db, id);
+      this.embeddingIndex.delete(id);
     }
     return success;
   }
@@ -76,11 +94,11 @@ export class TrapRepository {
   }
 
   archive(id: number): boolean {
-    return queries.archiveTrap(this.db, id);
+    return archiveTrapLifecycle(this.lifecycleAdapter(), id);
   }
 
   supersede(id: number, supersededById: number, stateKey?: string): boolean {
-    return queries.supersedeTrap(this.db, id, supersededById, stateKey);
+    return supersedeTrapLifecycle(this.lifecycleAdapter(), id, supersededById, stateKey);
   }
 
   hit(id: number): void {
@@ -91,31 +109,59 @@ export class TrapRepository {
     return queries.getTopTraps(this.db, scope, limit);
   }
 
-  stats(): TrapStats {
-    return queries.getStats(this.db);
+  stats(opts: { scope?: string; status?: TrapStatus | "all" } = {}): TrapStats {
+    return queries.getStats(this.db, opts);
+  }
+
+  embeddingStats(config: EmbeddingConfig | null, opts: { scope?: string; status?: TrapStatus | "all" } = {}): EmbeddingStateCounts {
+    return this.embeddingIndex.stateCounts(config, opts);
   }
 
   exportAll(): TrapExportRecord[] {
     return queries.exportTraps(this.db);
   }
 
+  exportProjectTrapsByPath(projectPath: string): TrapExportRecord[] {
+    return queries.exportProjectTrapsByPath(this.db, projectPath);
+  }
+
+  insertTrapRecord(record: TrapRecordInsert): number {
+    return queries.insertTrapRecord(this.db, record);
+  }
+
+  updateTrapSupersedesId(id: number, supersedesId: number): boolean {
+    return queries.updateTrapSupersedesId(this.db, id, supersedesId);
+  }
+
+  deleteTrapsByIds(ids: number[]): number {
+    return queries.deleteTrapsByIds(this.db, ids);
+  }
+
+  countProjectTrapsByPath(projectPath: string): number {
+    return queries.countProjectTrapsByPath(this.db, projectPath);
+  }
+
+  transaction<T>(callback: () => T): T {
+    return this.db.transaction(callback)();
+  }
+
   getEmbedding(trapId: number): StoredEmbedding | null {
-    return embeddingQueries.getEmbedding(this.db, trapId);
+    return this.embeddingIndex.get(trapId);
   }
 
   upsertEmbedding(record: StoredEmbedding): void {
-    embeddingQueries.upsertEmbedding(this.db, record);
+    this.embeddingIndex.save(record);
   }
 
   deleteEmbedding(trapId: number): void {
-    embeddingQueries.deleteEmbedding(this.db, trapId);
+    this.embeddingIndex.delete(trapId);
   }
 
   getTrapsNeedingEmbeddings(
     config: EmbeddingConfig,
     opts: { scope?: string; category?: string; status?: TrapStatus | "all"; force?: boolean; limit?: number } = {}
   ): Trap[] {
-    return embeddingQueries.getTrapsNeedingEmbeddings(this.db, config, opts);
+    return this.embeddingIndex.trapsNeedingEmbeddings(config, opts);
   }
 
   async ensureEmbeddings(opts: { scope?: string; category?: string; limit?: number; force?: boolean; batchSize?: number } = {}): Promise<{
@@ -129,13 +175,24 @@ export class TrapRepository {
 
     return runEmbeddingJob(
       {
-        countEmbeddable: (countOpts) => embeddingQueries.countEmbeddableTraps(this.db, countOpts),
+        countEmbeddable: (countOpts) => this.embeddingIndex.countEmbeddable(countOpts),
         trapsNeedingEmbeddings: (config, jobOpts) =>
-          embeddingQueries.getTrapsNeedingEmbeddings(this.db, config, jobOpts),
-        saveEmbedding: (record) => embeddingQueries.upsertEmbedding(this.db, record),
+          this.embeddingIndex.trapsNeedingEmbeddings(config, jobOpts),
+        saveEmbedding: (record) => this.embeddingIndex.save(record),
       },
       this.embedder,
       opts
     );
   }
+
+  private lifecycleAdapter() {
+    return {
+      get: (id: number) => queries.getTrap(this.db, id),
+      transaction: <T>(callback: () => T) => this.transaction(callback),
+      markArchived: (id: number) => queries.markTrapArchived(this.db, id),
+      markSuperseded: (id: number, stateKey: string) => queries.markTrapSuperseded(this.db, id, stateKey),
+      markSuperseding: (id: number, supersedesId: number, stateKey: string) =>
+        queries.markTrapSuperseding(this.db, id, supersedesId, stateKey),
+    };
+  }
 }

package/src/db/schema.ts

@@ -140,6 +140,41 @@ function applyMigrations(db: Database, from: number): void {
 
     db.prepare("UPDATE schema_version SET version = ?").run(4);
   }
+
+  if (from < 5) {
+    if (!columnExists(db, "traps", "path_globs")) {
+      db.exec("ALTER TABLE traps ADD COLUMN path_globs TEXT NOT NULL DEFAULT '[]'");
+    }
+    if (!columnExists(db, "traps", "module")) {
+      db.exec("ALTER TABLE traps ADD COLUMN module TEXT");
+    }
+    if (!columnExists(db, "traps", "owner")) {
+      db.exec("ALTER TABLE traps ADD COLUMN owner TEXT");
+    }
+
+    const rows = db
+      .query("SELECT id, title, context, mistake, fix, tags, before_code, after_code, path_globs, module, owner FROM traps")
+      .all() as {
+      id: number;
+      title: string;
+      context: string;
+      mistake: string;
+      fix: string;
+      tags: string;
+      before_code: string | null;
+      after_code: string | null;
+      path_globs: string;
+      module: string | null;
+      owner: string | null;
+    }[];
+
+    const update = db.prepare("UPDATE traps SET search_text = ? WHERE id = ?");
+    for (const row of rows) {
+      update.run(buildTrapSearchText(row), row.id);
+    }
+
+    db.prepare("UPDATE schema_version SET version = ?").run(5);
+  }
 }
 
 function columnExists(db: Database, table: string, column: string): boolean {

package/src/domain/trap.ts

@@ -30,6 +30,9 @@ export interface Trap {
   valid_from: string;
   valid_until: string | null;
   project_path: string | null;
+  path_globs: string;
+  module: string | null;
+  owner: string | null;
   hit_count: number;
   created_at: string;
   updated_at: string;
@@ -47,6 +50,9 @@ export interface TrapInput {
   after_code?: string;
   severity?: string;
   project_path?: string | null;
+  path_globs?: string[];
+  module?: string | null;
+  owner?: string | null;
 }
 
 export interface TrapSearchResult {
@@ -54,7 +60,19 @@ export interface TrapSearchResult {
   rank: number;
   sources?: ("fts" | "semantic")[];
   score?: number;
-  diagnostics?: { code: string; message: string }[];
+  diagnostics?: TrapSearchDiagnostic[];
+  ranking_signals?: RankingSignal[];
+}
+
+export interface TrapSearchDiagnostic {
+  code: string;
+  message: string;
+}
+
+export interface RankingSignal {
+  code: string;
+  weight: number;
+  detail?: string;
 }
 
 export interface TrapActionCard {
@@ -67,13 +85,8 @@ export interface TrapActionCard {
   severity: string;
   score: number | null;
   sources: ("fts" | "semantic")[];
-  next_action: {
-    details_tool: "get_trap";
-    details_args: {
-      id: number;
-      scope: Scope;
-    };
-  };
+  diagnostics?: TrapSearchDiagnostic[];
+  ranking_signals?: RankingSignal[];
 }
 
 export type TrapUpdate = Partial<Omit<TrapInput, "scope" | "project_path">>;
@@ -101,7 +114,8 @@ export interface TrapExportEvidence extends Omit<TrapEvidence, "related_files">
   related_files: string[];
 }
 
-export interface TrapExportRecord extends Trap {
+export interface TrapExportRecord extends Omit<Trap, "path_globs"> {
+  path_globs: string[];
   evidence: TrapExportEvidence[];
 }
 
@@ -110,11 +124,12 @@ export type TrapImportEvidence = Partial<Omit<TrapEvidence, "related_files">> &
   related_files?: string[] | string | null;
 };
 
-export type TrapImportRecord = Omit<TrapInput, "tags" | "before_code" | "after_code" | "project_path"> & {
+export type TrapImportRecord = Omit<TrapInput, "tags" | "before_code" | "after_code" | "project_path" | "path_globs"> & {
   tags?: string[] | string | null;
   before_code?: string | null;
   after_code?: string | null;
   project_path?: string | null;
+  path_globs?: string[] | string | null;
   evidence?: TrapImportEvidence[];
 };
 
@@ -168,6 +183,9 @@ export const TRAP_UPDATE_FIELDS = [
   "before_code",
   "after_code",
   "severity",
+  "path_globs",
+  "module",
+  "owner",
 ] as const;
 
 export const TRAP_INPUT_SCHEMA_PROPERTIES = {
@@ -185,6 +203,13 @@ export const TRAP_INPUT_SCHEMA_PROPERTIES = {
   before_code: { type: "string", description: "Example of wrong code (optional)" },
   after_code: { type: "string", description: "Example of correct code (optional)" },
   severity: { type: "string", enum: [...SEVERITIES] as string[], description: "How severe is this pitfall?" },
+  path_globs: {
+    type: "array",
+    items: { type: "string" },
+    description: "Optional file globs where this trap applies, for example src/db/**",
+  },
+  module: { type: "string", description: "Optional module or subsystem where this trap applies" },
+  owner: { type: "string", description: "Optional team or owner for this trap" },
 } satisfies Record<keyof Omit<TrapInput, "project_path">, JsonSchemaProperty>;
 
 export function trapInputSchema() {
@@ -270,6 +295,9 @@ export function buildTrapInput(args: Record<string, any>): TrapInput {
     before_code: args.before_code,
     after_code: args.after_code,
     severity: args.severity ?? DEFAULT_SEVERITY,
+    path_globs: Array.isArray(args.path_globs) ? args.path_globs.map(String) : args.path_globs,
+    module: args.module,
+    owner: args.owner,
   };
 }
 

package/src/index.ts

@@ -46,6 +46,9 @@ function showHelp(): void {
   console.log("  export                Export traps as JSON");
   console.log("  import <file.json>    Import traps from JSON");
   console.log("  stats                 Show statistics");
+  console.log("  doctor                Diagnose scope, database, and embedding health");
+  console.log("  repair-scope          Move mis-scoped project traps into the current project");
+  console.log("  migrate-project       Move project traps between initialized projects");
   console.log("  serve                 Start MCP server (for Claude Code)");
   console.log("");
   console.log("Flags:");
@@ -53,6 +56,15 @@ function showHelp(): void {
   console.log("  --category <name>       Filter by category");
   console.log("  --mode fts|semantic|hybrid  Search mode");
   console.log("  --status active|superseded|archived|all  Lifecycle filter");
+  console.log("  --path <file>           Filter/boost traps scoped to a file path");
+  console.log("  --module <name>         Filter/boost traps scoped to a module");
+  console.log("  --owner <name>          Filter/boost traps scoped to an owner/team");
+  console.log("  --no-rerank             Disable query-aware search reranking");
+  console.log("  --ranking-signals       Include search ranking diagnostics in JSON cards");
   console.log("  --batch-size <n>        Embedding generation batch size");
-  console.log("  --json '{}'             JSON input for add/edit");
+  console.log("  --json                  JSON output for search/show/list/stats/doctor; JSON input for add/edit");
+  console.log("  --output-json           JSON output for add/edit when --json is used as input");
+  console.log("  --from-project-path <path>  Source project path for scope repair/migration");
+  console.log("  --to-project-path <path>    Destination project path for scope repair/migration");
+  console.log("  --dry-run|--apply       Preview or apply scope repair/migration");
 }