@pella-labs/pinakes 0.3.14 → 0.4.0

package/README.md

@@ -145,13 +145,14 @@ knowledge_query({
 All data is stored under `~/.pinakes/` (override with `PINAKES_ROOT`). Project data lives at `~/.pinakes/projects/<mangled-path>/`.
 
 ```bash
-npx @pella-labs/pinakes serve   [--wiki-path <dir>]   # Start the stdio MCP server
-npx @pella-labs/pinakes rebuild [--wiki-path <dir>]   # Full rebuild from markdown
-npx @pella-labs/pinakes status                        # Health check + row counts
-npx @pella-labs/pinakes audit   [--n 20]              # Tail the audit log
-npx @pella-labs/pinakes purge   --scope <s> --confirm # Delete a scope's DB
-npx @pella-labs/pinakes export  --scope <s> [--out f] # Dump nodes + edges as JSON
-npx @pella-labs/pinakes import  --scope <s> --in f    # Restore from dump
+npx @pella-labs/pinakes serve      [--wiki-path <dir>]   # Start the stdio MCP server
+npx @pella-labs/pinakes rebuild    [--wiki-path <dir>]   # Full rebuild from markdown
+npx @pella-labs/pinakes status                           # Health check + row counts
+npx @pella-labs/pinakes audit      [--n 20]              # Tail the audit log
+npx @pella-labs/pinakes audit-wiki                       # Wiki audit (contradictions, gaps)
+npx @pella-labs/pinakes purge      --scope <s> --confirm # Delete a scope's DB
+npx @pella-labs/pinakes export     --scope <s> [--out f] # Dump nodes + edges as JSON
+npx @pella-labs/pinakes import     --scope <s> --in f    # Restore from dump
 ```
 
 ## Embedder configuration
@@ -192,6 +193,14 @@ Changing the embedder requires a full rebuild (`pinakes rebuild`) since the vect
 - **Deterministic IDs**: `sha1(scope + ':' + source_uri + ':' + section_path)` means re-indexing is idempotent
 - **Centralized storage**: all data under `~/.pinakes/`, project paths mirrored as `~/.pinakes/projects/<mangled-path>/`
 
+## Wiki auditing
+
+Two paths for auditing your knowledge base:
+
+**Claude Code users** — run `/audit-wiki` for a deep agent-powered audit. This runs the pipeline first, then has Claude read through wiki files to find cross-file contradictions, broken references, terminology inconsistencies, and stale info that the pipeline can't catch.
+
+**All users** — run `npx @pella-labs/pinakes audit-wiki` (or `pnpm run pinakes -- audit-wiki` from source) for the deterministic pipeline audit. Produces `_audit-report.md` in the wiki directory with contradictions, documentation gaps, and health metrics. Requires an LLM provider (Ollama, API key, or `claude` CLI).
+
 ## Development
 
 ```bash

package/dist/cli/audit-wiki.d.ts

@@ -1,14 +1,58 @@
+import type { Database as BetterSqliteDatabase } from 'better-sqlite3';
+import { type GapRow } from '../gaps/detector.js';
+import { type LlmProvider } from '../llm/provider.js';
 import { type ContradictionResult } from './contradiction.js';
+import { createProgressReporter } from './progress.js';
 export interface WikiAuditOptions {
     projectRoot?: string;
     dbPath?: string;
     scope?: 'project' | 'personal';
+    quiet?: boolean;
+    generateStubs?: boolean;
 }
 export interface WikiAuditResult {
     contradictions: ContradictionResult;
     gaps_found: number;
-    stub_pages_created: string[];
+    topology_gaps: number;
+    stubs_generated: number;
     audit_report_path: string;
 }
 export declare function auditWikiCommand(opts: WikiAuditOptions): Promise<WikiAuditResult>;
+export declare function llmFilterGaps(gaps: GapRow[], llmProvider: LlmProvider, progress?: {
+    tick: (label: string, detail?: string) => void;
+}): Promise<GapRow[]>;
+export declare function parseLlmFilterResponse(response: string): string[];
+export interface TopologyGap {
+    topic: string;
+    in_degree: number;
+    source: 'graph-topology';
+}
+export declare function findTopologyGaps(reader: BetterSqliteDatabase, scope: string): TopologyGap[];
+export interface GapContext {
+    topic: string;
+    mentions: Array<{
+        source_uri: string;
+        excerpt: string;
+    }>;
+}
+export declare function gatherGapContexts(reader: BetterSqliteDatabase, scope: string, gaps: GapRow[]): GapContext[];
+export declare function generateSynthesisStubs(gaps: GapRow[], contexts: GapContext[], wikiRoot: string, llmProvider: LlmProvider, progress?: ReturnType<typeof createProgressReporter>): Promise<number>;
+export interface HealthMetrics {
+    file_count: number;
+    chunk_count: number;
+    node_count: number;
+    edge_count: number;
+}
+export declare function getHealthMetrics(reader: BetterSqliteDatabase, scope: string): HealthMetrics;
+/**
+ * Filter out noise from the gap detector (D42 Tier 1 tightening).
+ *
+ * Rejects topics that are:
+ * - Too short
+ * - URLs, file paths, qualified names
+ * - Code fragments (snake_case, camelCase, SCREAMING_SNAKE)
+ * - Common stopwords (English + technical)
+ * - Single-word generic terms that aren't proper nouns/acronyms
+ */
+export declare function isRealGap(topic: string): boolean;
 //# sourceMappingURL=audit-wiki.d.ts.map

package/dist/cli/audit-wiki.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit-wiki.d.ts","sourceRoot":"","sources":["../../src/cli/audit-wiki.ts"],"names":[],"mappings":"AAaA,OAAO,EAAqB,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAgBjF,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,mBAAmB,CAAC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CA4EvF"}
+{"version":3,"file":"audit-wiki.d.ts","sourceRoot":"","sources":["../../src/cli/audit-wiki.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAGvE,OAAO,EAAa,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAQzE,OAAO,EAAqB,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAgBvD,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,mBAAmB,CAAC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAkGvF;AAkBD,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,WAAW,EAAE,WAAW,EACxB,QAAQ,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAC5D,OAAO,CAAC,MAAM,EAAE,CAAC,CAgCnB;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAYjE;AAMD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,MAAM,GACZ,WAAW,EAAE,CA0Bf;AAMD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1D;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EAAE,GACb,UAAU,EAAE,CA4Bd;AAeD,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,EAAE,EACd,QAAQ,EAAE,UAAU,EAAE,EACtB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,WAAW,EACxB,QAAQ,CAAC,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,GACnD,OAAO,CAAC,MAAM,CAAC,CAoDjB;AAmBD,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,MAAM,GACZ,aAAa,CAoBf;AA6GD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAgChD"}

package/dist/cli/audit-wiki.js

@@ -1,10 +1,11 @@
-import { writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { closeDb, openDb } from '../db/client.js';
 import { queryGaps } from '../gaps/detector.js';
 import { createLlmProvider } from '../llm/provider.js';
 import { resolveAbs, projectWikiPath as defaultProjectWikiPath, projectDbPath as defaultProjectDbPath, personalWikiPath as defaultPersonalWikiPath, personalDbPath as defaultPersonalDbPath, } from '../paths.js';
 import { contradictionScan } from './contradiction.js';
+import { createProgressReporter } from './progress.js';
 /**
  * `pinakes audit-wiki` — LLM-powered wiki audit command.
  *
@@ -16,7 +17,7 @@ import { contradictionScan } from './contradiction.js';
  * error message if no provider is available.
  */
 const GAP_MENTION_THRESHOLD = 10;
-const MIN_TOPIC_LENGTH = 4; // filter out "or", "no", "id", etc.
+const MIN_TOPIC_LENGTH = 5; // filter out short tokens (D42 tightened from 4)
 export async function auditWikiCommand(opts) {
     const scope = opts.scope ?? 'project';
     const projectRoot = resolveAbs(opts.projectRoot ?? process.cwd());
@@ -31,13 +32,13 @@ export async function auditWikiCommand(opts) {
     const bundle = openDb(dbPath);
     try {
         const llmProvider = createLlmProvider();
+        const progress = createProgressReporter({ quiet: opts.quiet });
         // eslint-disable-next-line no-console
         console.log(`Running wiki audit (LLM provider: ${llmProvider.name})...`);
         // 1. Contradiction scan (requires LLM provider)
         let contradictions;
         if (llmProvider.available()) {
-            // eslint-disable-next-line no-console
-            console.log('  Scanning for contradictions...');
+            progress.startPhase('Phase 1/3: Scanning for contradictions', 1);
             contradictions = await contradictionScan({
                 bundle,
                 scope,
@@ -45,41 +46,51 @@ export async function auditWikiCommand(opts) {
                 wikiRoot: wikiPath,
             });
             if (contradictions.rate_limited) {
-                // eslint-disable-next-line no-console
-                console.log('  Contradiction scan rate-limited (last scan < 1h ago)');
+                progress.endPhase('Rate-limited (last scan < 1h ago)');
             }
             else {
-                // eslint-disable-next-line no-console
-                console.log(`  Scanned ${contradictions.scanned_pairs} pairs, found ${contradictions.contradictions.length} contradictions`);
+                progress.endPhase(`Scanned ${contradictions.scanned_pairs} pairs, found ${contradictions.contradictions.length} contradictions`);
             }
         }
         else {
-            // eslint-disable-next-line no-console
-            console.log('  Skipping contradiction scan (no LLM provider available)');
-            contradictions = { scanned_pairs: 0, contradictions: [], rate_limited: false };
+            progress.startPhase('Phase 1/3: Contradiction scan', 0);
+            progress.endPhase('Skipped (no LLM provider available)');
+            contradictions = { scanned_pairs: 0, topics_scanned: 0, claims_extracted: 0, contradictions: [], rate_limited: false };
         }
-        // 2. Gap detection — filter out noise (short tokens, common words, code fragments)
-        // eslint-disable-next-line no-console
-        console.log('  Checking for documentation gaps...');
+        // 2. Gap detection — syntactic filter + LLM filter + graph topology (D42)
         const allGaps = queryGaps(bundle.writer, scope);
-        const gaps = allGaps.filter((g) => isRealGap(g.topic));
-        const significantGaps = gaps.filter((g) => g.mentions_count >= GAP_MENTION_THRESHOLD);
-        // eslint-disable-next-line no-console
-        console.log(`  Found ${gaps.length} gaps (${significantGaps.length} significant)`);
-        // 3. Stub page generation is deferred to the Pharos integration (Tier 2).
-        // The claude subprocess provider is too unreliable for batch generation,
-        // and the gap detector still produces too many false positives for
-        // automated page creation. The audit report lists gaps for manual review.
-        const stubPages = [];
-        // 4. Generate audit report
+        const syntacticGaps = allGaps.filter((g) => isRealGap(g.topic));
+        const significantGaps = syntacticGaps.filter((g) => g.mentions_count >= GAP_MENTION_THRESHOLD);
+        progress.startPhase('Phase 2/3: Filtering documentation gaps', allGaps.length);
+        // LLM batch filter (Tier 2)
+        let filteredGaps;
+        if (llmProvider.available() && significantGaps.length > 0) {
+            filteredGaps = await llmFilterGaps(significantGaps, llmProvider, progress);
+        }
+        else {
+            filteredGaps = significantGaps;
+        }
+        // Add graph topology gaps (high in-degree, no dedicated page)
+        const topoGaps = findTopologyGaps(bundle.writer, scope);
+        progress.endPhase(`${allGaps.length} raw → ${syntacticGaps.length} syntactic → ${filteredGaps.length} LLM-filtered, ${topoGaps.length} topology gaps`);
+        // 3. Gather context for each confirmed gap
+        const gapContexts = gatherGapContexts(bundle.writer, scope, filteredGaps);
+        // 4. Opt-in synthesis stubs (D43 — --generate-stubs flag)
+        let stubsGenerated = 0;
+        if (opts.generateStubs && filteredGaps.length > 0 && llmProvider.available()) {
+            stubsGenerated = await generateSynthesisStubs(filteredGaps, gapContexts, wikiPath, llmProvider, progress);
+        }
+        // 5. Generate audit report (D46 restructured: contradictions, gaps, health)
+        const healthMetrics = getHealthMetrics(bundle.writer, scope);
         const reportPath = join(wikiPath, '_audit-report.md');
-        writeAuditReport(reportPath, contradictions, gaps, significantGaps, stubPages);
+        writeAuditReport(reportPath, contradictions, filteredGaps, topoGaps, gapContexts, healthMetrics, stubsGenerated);
         // eslint-disable-next-line no-console
         console.log(`\nAudit report written to: ${reportPath}`);
         return {
             contradictions,
-            gaps_found: gaps.length,
-            stub_pages_created: stubPages,
+            gaps_found: filteredGaps.length,
+            topology_gaps: topoGaps.length,
+            stubs_generated: stubsGenerated,
             audit_report_path: reportPath,
         };
     }
@@ -88,58 +99,273 @@ export async function auditWikiCommand(opts) {
     }
 }
 // ---------------------------------------------------------------------------
-// Internals
+// LLM gap filtering (D42 Tier 2)
+// ---------------------------------------------------------------------------
+const GAP_FILTER_SYSTEM = `You are a documentation quality analyst. Given a list of terms extracted from a technical wiki, identify which represent real documentation topics that would benefit from a dedicated wiki page.
+
+Return ONLY a JSON array of the real topics: ["topic1", "topic2", ...]
+
+Filter out:
+- Common words and generic technical terms
+- Code syntax, variable names, file extensions
+- Terms too specific or too vague to be standalone pages
+- Terms that are part of larger concepts already documented`;
+const LLM_FILTER_BATCH_SIZE = 50;
+export async function llmFilterGaps(gaps, llmProvider, progress) {
+    const result = [];
+    for (let i = 0; i < gaps.length; i += LLM_FILTER_BATCH_SIZE) {
+        const batch = gaps.slice(i, i + LLM_FILTER_BATCH_SIZE);
+        const topics = batch.map((g) => g.topic);
+        try {
+            const response = await llmProvider.complete({
+                system: GAP_FILTER_SYSTEM,
+                prompt: `Filter these ${topics.length} terms:\n${JSON.stringify(topics)}`,
+                maxTokens: 1000,
+            });
+            const kept = parseLlmFilterResponse(response);
+            const keptSet = new Set(kept.map((t) => t.toLowerCase()));
+            for (const gap of batch) {
+                if (keptSet.has(gap.topic.toLowerCase())) {
+                    result.push(gap);
+                }
+            }
+            progress?.tick(`batch ${Math.floor(i / LLM_FILTER_BATCH_SIZE) + 1}`, `${kept.length}/${batch.length} kept`);
+        }
+        catch {
+            // LLM filter failed — keep all gaps in this batch (graceful degradation)
+            result.push(...batch);
+            progress?.tick(`batch ${Math.floor(i / LLM_FILTER_BATCH_SIZE) + 1}`, 'LLM filter failed, keeping all');
+        }
+    }
+    return result;
+}
+export function parseLlmFilterResponse(response) {
+    try {
+        const fenceMatch = response.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+        const jsonStr = fenceMatch ? fenceMatch[1] : response;
+        const arrMatch = jsonStr.match(/\[[\s\S]*\]/);
+        if (!arrMatch)
+            return [];
+        const parsed = JSON.parse(arrMatch[0]);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((t) => typeof t === 'string');
+    }
+    catch {
+        return [];
+    }
+}
+export function findTopologyGaps(reader, scope) {
+    // Find nodes referenced by wikilink edges that don't have their own page
+    // We look for edge targets (dst_id) that appear frequently but
+    // whose corresponding node titles don't exist as dedicated pages
+    try {
+        const rows = reader
+            .prepare(`SELECT n.title, COUNT(*) as cnt
+         FROM pinakes_edges e
+         JOIN pinakes_nodes n ON e.dst_id = n.id
+         WHERE n.scope = ? AND e.edge_kind = ?
+         GROUP BY n.title
+         HAVING cnt >= 3
+         ORDER BY cnt DESC
+         LIMIT 20`)
+            .all(scope, 'wikilink');
+        return rows.map((r) => ({
+            topic: r.title ?? 'untitled',
+            in_degree: r.cnt,
+            source: 'graph-topology',
+        }));
+    }
+    catch {
+        return []; // Table might not have edges yet
+    }
+}
+export function gatherGapContexts(reader, scope, gaps) {
+    const contexts = [];
+    for (const gap of gaps.slice(0, 20)) {
+        try {
+            const mentions = reader
+                .prepare(`SELECT n.source_uri, c.text
+           FROM pinakes_chunks c
+           JOIN pinakes_nodes n ON c.node_id = n.id
+           WHERE n.scope = ? AND c.text LIKE '%' || ? || '%' COLLATE NOCASE
+           LIMIT 5`)
+                .all(scope, gap.topic);
+            contexts.push({
+                topic: gap.topic,
+                mentions: mentions.map((m) => ({
+                    source_uri: m.source_uri,
+                    excerpt: truncate(m.text, 200),
+                })),
+            });
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    return contexts;
+}
+// ---------------------------------------------------------------------------
+// Synthesis stubs (D43 — opt-in via --generate-stubs)
 // ---------------------------------------------------------------------------
-// Stub page generation deferred to Pharos Tier 2 integration.
-function writeAuditReport(reportPath, contradictions, allGaps, significantGaps, stubPages) {
+const SYNTHESIS_SYSTEM = `You are a technical documentation writer. Based on the following excerpts from a knowledge wiki, write a concise wiki page about the given topic.
+
+Rules:
+- Include ONLY facts present in the excerpts
+- Mark any inferences with "(inferred)"
+- Format as markdown with a title (H1), summary paragraph, and relevant details
+- Keep it under 500 words
+- Output only the markdown content`;
+export async function generateSynthesisStubs(gaps, contexts, wikiRoot, llmProvider, progress) {
+    const draftsDir = resolve(wikiRoot, '_audit-drafts');
+    mkdirSync(draftsDir, { recursive: true });
+    // Ensure _audit-drafts is gitignored
+    ensureGitignored(wikiRoot, '_audit-drafts/');
+    const MAX_STUBS = 20;
+    const toGenerate = gaps.slice(0, MAX_STUBS);
+    progress?.startPhase('Phase 3/3: Generating synthesis drafts', toGenerate.length);
+    let generated = 0;
+    for (const gap of toGenerate) {
+        const ctx = contexts.find((c) => c.topic === gap.topic);
+        if (!ctx || ctx.mentions.length === 0) {
+            progress?.tick(gap.topic, 'skipped (no context)');
+            continue;
+        }
+        const slug = gap.topic
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/(^-|-$)/g, '');
+        if (!slug) {
+            progress?.tick(gap.topic, 'skipped (invalid slug)');
+            continue;
+        }
+        const filePath = join(draftsDir, `${slug}.md`);
+        try {
+            const excerpts = ctx.mentions
+                .map((m) => `From ${m.source_uri}:\n${m.excerpt}`)
+                .join('\n\n');
+            const content = await llmProvider.complete({
+                system: SYNTHESIS_SYSTEM,
+                prompt: `Write a wiki page about "${gap.topic}" based on these excerpts:\n\n${excerpts}`,
+                maxTokens: 1000,
+            });
+            writeFileSync(filePath, content, 'utf-8');
+            generated++;
+            progress?.tick(gap.topic, 'draft created');
+        }
+        catch (err) {
+            progress?.tick(gap.topic, `failed: ${err instanceof Error ? err.message.slice(0, 60) : err}`);
+        }
+    }
+    progress?.endPhase(`${generated} drafts written to _audit-drafts/`);
+    return generated;
+}
+function ensureGitignored(wikiRoot, entry) {
+    // Look for .gitignore in the .pinakes parent directory
+    const pinakesDir = resolve(wikiRoot, '..');
+    const gitignorePath = join(pinakesDir, '.gitignore');
+    if (!existsSync(gitignorePath))
+        return;
+    const content = readFileSync(gitignorePath, 'utf-8');
+    if (content.includes(entry))
+        return;
+    appendFileSync(gitignorePath, `\n${entry}\n`, 'utf-8');
+}
+export function getHealthMetrics(reader, scope) {
+    const fileCount = reader.prepare(`SELECT COUNT(DISTINCT source_uri) as c FROM pinakes_nodes WHERE scope = ?`).get(scope)?.c ?? 0;
+    const chunkCount = reader.prepare(`SELECT COUNT(*) as c FROM pinakes_chunks ch
+     JOIN pinakes_nodes n ON ch.node_id = n.id WHERE n.scope = ?`).get(scope)?.c ?? 0;
+    const nodeCount = reader.prepare(`SELECT COUNT(*) as c FROM pinakes_nodes WHERE scope = ?`).get(scope)?.c ?? 0;
+    const edgeCount = reader.prepare(`SELECT COUNT(*) as c FROM pinakes_edges e
+     JOIN pinakes_nodes n ON e.src_id = n.id WHERE n.scope = ?`).get(scope)?.c ?? 0;
+    return { file_count: fileCount, chunk_count: chunkCount, node_count: nodeCount, edge_count: edgeCount };
+}
+// ---------------------------------------------------------------------------
+// Audit report (D46 restructured)
+// ---------------------------------------------------------------------------
+function writeAuditReport(reportPath, contradictions, filteredGaps, topoGaps, gapContexts, health, stubsGenerated = 0) {
     const lines = [
         '# Wiki Audit Report',
         '',
         `*Generated: ${new Date().toISOString()}*`,
         '',
-        '## Summary',
-        '',
     ];
+    // Section 1: Contradictions
+    lines.push('## Contradictions');
+    lines.push('');
     if (contradictions.rate_limited) {
-        lines.push('- **Contradictions**: scan rate-limited (last scan < 1h ago)');
+        lines.push('*Scan rate-limited (last scan < 1h ago)*');
     }
-    else {
-        lines.push(`- **Contradictions**: ${contradictions.contradictions.length} found (${contradictions.scanned_pairs} pairs scanned)`);
+    else if (contradictions.contradictions.length === 0) {
+        lines.push(`*No contradictions found (${contradictions.topics_scanned} topics, ${contradictions.claims_extracted} claims scanned)*`);
     }
-    lines.push(`- **Documentation gaps**: ${allGaps.length} total, ${significantGaps.length} significant (${GAP_MENTION_THRESHOLD}+ mentions)`);
-    lines.push(`- **Stub pages generated**: ${stubPages.length}`);
-    lines.push('');
-    if (contradictions.contradictions.length > 0) {
-        lines.push('## Contradictions');
+    else {
+        lines.push(`**${contradictions.contradictions.length} contradictions found** (${contradictions.topics_scanned} topics scanned)`);
         lines.push('');
         for (const c of contradictions.contradictions) {
-            lines.push(`### ${c.chunkA.source_uri} vs ${c.chunkB.source_uri}`);
+            lines.push(`### ${c.topic}`);
             lines.push('');
-            lines.push(`- **Confidence**: ${c.confidence}`);
-            lines.push(`- **Explanation**: ${c.explanation}`);
-            lines.push(`- Chunk A: *"${truncate(c.chunkA.text, 150)}"*`);
-            lines.push(`- Chunk B: *"${truncate(c.chunkB.text, 150)}"*`);
+            lines.push(`- **${c.claimA.source_uri}**: "${truncate(c.claimA.claim, 150)}"`);
+            lines.push(`- **${c.claimB.source_uri}**: "${truncate(c.claimB.claim, 150)}"`);
+            lines.push(`- **Why**: ${c.explanation} *(${c.confidence} confidence)*`);
             lines.push('');
         }
     }
-    if (significantGaps.length > 0) {
-        lines.push('## Documentation Gaps');
-        lines.push('');
-        lines.push('| Topic | Mentions | Status |');
-        lines.push('|---|---|---|');
-        for (const g of significantGaps) {
-            const status = g.resolved_at ? 'Resolved' : 'Open';
-            lines.push(`| ${g.topic} | ${g.mentions_count} | ${status} |`);
+    lines.push('');
+    // Section 2: Documentation Gaps
+    lines.push('## Documentation Gaps');
+    lines.push('');
+    if (filteredGaps.length === 0 && topoGaps.length === 0) {
+        lines.push('*No significant gaps found*');
+    }
+    else {
+        if (filteredGaps.length > 0) {
+            lines.push(`### By mention frequency (${filteredGaps.length} topics)`);
+            lines.push('');
+            lines.push('| Topic | Mentions | Context |');
+            lines.push('|---|---|---|');
+            for (const g of filteredGaps) {
+                const ctx = gapContexts.find((c) => c.topic === g.topic);
+                const ctxSummary = ctx?.mentions.length
+                    ? `Referenced in ${ctx.mentions.map((m) => m.source_uri).join(', ')}`
+                    : '';
+                lines.push(`| ${g.topic} | ${g.mentions_count} | ${ctxSummary} |`);
+            }
+            lines.push('');
         }
+        if (topoGaps.length > 0) {
+            lines.push(`### By link topology (${topoGaps.length} topics)`);
+            lines.push('');
+            lines.push('| Topic | In-degree |');
+            lines.push('|---|---|');
+            for (const g of topoGaps) {
+                lines.push(`| ${g.topic} | ${g.in_degree} |`);
+            }
+            lines.push('');
+        }
+    }
+    lines.push('');
+    // Section 3: Health Metrics
+    lines.push('## Health Metrics');
+    lines.push('');
+    lines.push(`| Metric | Value |`);
+    lines.push(`|---|---|`);
+    lines.push(`| Files | ${health.file_count} |`);
+    lines.push(`| Nodes | ${health.node_count} |`);
+    lines.push(`| Chunks | ${health.chunk_count} |`);
+    lines.push(`| Edges | ${health.edge_count} |`);
+    lines.push('');
+    // Generated drafts section
+    if (stubsGenerated > 0) {
+        lines.push('## Generated Drafts');
+        lines.push('');
+        lines.push(`${stubsGenerated} synthesis drafts written to \`_audit-drafts/\`. Review before promoting to wiki.`);
         lines.push('');
     }
-    if (stubPages.length > 0) {
-        lines.push('## Generated Stub Pages');
+    else {
+        lines.push('---');
         lines.push('');
-        for (const p of stubPages) {
-            const name = p.split('/').pop() ?? p;
-            lines.push(`- [[${name.replace('.md', '')}]]`);
-        }
+        lines.push('*Run with `--generate-stubs` to auto-generate draft pages for gaps.*');
         lines.push('');
     }
     writeFileSync(reportPath, lines.join('\n'), 'utf-8');
@@ -150,12 +376,16 @@ function truncate(s, maxLen) {
     return s.slice(0, maxLen) + '...';
 }
 /**
- * Filter out noise from the gap detector. Rejects topics that are:
- * - Too short (common tokens like "or", "no", "id")
- * - Pure code fragments (paths, URLs, variable names with underscores)
- * - Common stopwords
+ * Filter out noise from the gap detector (D42 Tier 1 tightening).
+ *
+ * Rejects topics that are:
+ * - Too short
+ * - URLs, file paths, qualified names
+ * - Code fragments (snake_case, camelCase, SCREAMING_SNAKE)
+ * - Common stopwords (English + technical)
+ * - Single-word generic terms that aren't proper nouns/acronyms
  */
-function isRealGap(topic) {
+export function isRealGap(topic) {
     if (topic.length < MIN_TOPIC_LENGTH)
         return false;
     // Skip URLs, file paths, code fragments
@@ -163,24 +393,62 @@ function isRealGap(topic) {
         return false;
     if (topic.includes('://'))
         return false;
-    // Skip things that look like code (snake_case with no spaces, camelCase identifiers)
-    if (/^[a-z_]+$/.test(topic) && topic.includes('_') && !topic.includes(' '))
+    // Qualified names (e.g., "fs.readFileSync", "path.join")
+    if (topic.includes('.') && !topic.includes(' '))
         return false;
-    // Skip common stopwords that aren't real topics
-    const stopwords = new Set([
-        'the', 'and', 'for', 'with', 'that', 'this', 'from', 'are', 'was', 'will',
-        'can', 'not', 'but', 'all', 'has', 'have', 'had', 'been', 'would', 'could',
-        'should', 'may', 'might', 'must', 'shall', 'into', 'than', 'then', 'when',
-        'where', 'which', 'while', 'about', 'after', 'before', 'between', 'under',
-        'over', 'only', 'also', 'just', 'like', 'more', 'most', 'some', 'such',
-        'each', 'every', 'both', 'either', 'neither', 'other', 'another',
-        'true', 'false', 'null', 'none', 'yes', 'done',
-    ]);
-    if (stopwords.has(topic.toLowerCase()))
+    // Skip code-like patterns
+    // snake_case: all lowercase with underscores
+    if (/^[a-z_]+$/.test(topic) && topic.includes('_'))
         return false;
-    // Skip single-word topics that are too generic
-    if (!topic.includes(' ') && topic.length < 6)
+    // camelCase: starts lowercase then has uppercase
+    if (/^[a-z]+[A-Z]/.test(topic) && !topic.includes(' '))
         return false;
+    // SCREAMING_SNAKE_CASE
+    if (/^[A-Z][A-Z0-9_]+$/.test(topic))
+        return false;
+    const lower = topic.toLowerCase();
+    // Skip common English stopwords
+    if (STOPWORDS.has(lower))
+        return false;
+    // Skip common technical terms that aren't real topics
+    if (TECH_STOPWORDS.has(lower))
+        return false;
+    // Single-word topics: only keep proper nouns/acronyms (starts with uppercase
+    // or is all-caps like "OAuth2", "Docker", "PostgreSQL")
+    if (!topic.includes(' ')) {
+        const looksProper = /^[A-Z]/.test(topic);
+        if (!looksProper)
+            return false;
+    }
     return true;
 }
+const STOPWORDS = new Set([
+    'the', 'and', 'for', 'with', 'that', 'this', 'from', 'are', 'was', 'will',
+    'can', 'not', 'but', 'all', 'has', 'have', 'had', 'been', 'would', 'could',
+    'should', 'may', 'might', 'must', 'shall', 'into', 'than', 'then', 'when',
+    'where', 'which', 'while', 'about', 'after', 'before', 'between', 'under',
+    'over', 'only', 'also', 'just', 'like', 'more', 'most', 'some', 'such',
+    'each', 'every', 'both', 'either', 'neither', 'other', 'another',
+    'true', 'false', 'null', 'none', 'yes', 'done', 'note', 'using',
+    'first', 'still', 'instead', 'enable', 'default', 'since', 'based',
+    'here', 'there', 'these', 'those', 'above', 'below', 'through',
+]);
+const TECH_STOPWORDS = new Set([
+    'example', 'section', 'configuration', 'implementation', 'method',
+    'function', 'parameter', 'argument', 'option', 'value', 'result',
+    'output', 'input', 'error', 'warning', 'status', 'type', 'string',
+    'number', 'boolean', 'object', 'array', 'list', 'file', 'path',
+    'name', 'version', 'update', 'change', 'create', 'delete', 'read',
+    'write', 'server', 'client', 'request', 'response', 'source', 'model',
+    'command', 'description', 'detail', 'content', 'window', 'provider',
+    'module', 'package', 'import', 'export', 'return', 'class', 'interface',
+    'property', 'field', 'table', 'column', 'index', 'query', 'schema',
+    'handler', 'callback', 'promise', 'async', 'await', 'event', 'action',
+    'state', 'props', 'component', 'render', 'route', 'endpoint', 'context',
+    'scope', 'token', 'session', 'header', 'body', 'payload', 'message',
+    'process', 'service', 'manager', 'factory', 'builder', 'helper',
+    'utility', 'config', 'setting', 'feature', 'support', 'format',
+    'connection', 'database', 'storage', 'cache', 'buffer', 'stream',
+    'directory', 'folder', 'entry', 'record', 'document', 'resource',
+]);
 //# sourceMappingURL=audit-wiki.js.map